From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: "Why is emacs so square?" Date: Wed, 22 Apr 2020 17:25:31 +0300 Message-ID: <83v9lregx0.fsf@gnu.org> References: <863691n4xl.wl-me@enzu.ru> <86blno9yle.wl-me@enzu.ru> <87d0845msg.fsf@yahoo.com> <87h7xgjasw.fsf@yahoo.com> <875zdwjais.fsf@yahoo.com> <6a198677-41b6-4dbd-39d0-2b01550d53cf@yandex.ru> <32f6a2ce-e30f-059f-dcd4-233d666a10a1@yandex.ru> <87r1whiape.fsf@fastmail.fm> <87blnjopd0.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="93491"; mail-complaints-to="usenet@ciao.gmane.io" Cc: joostkremers@fastmail.fm, rms@gnu.org, emacs-devel@gnu.org To: Nicolas Goaziou Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Apr 22 16:26:50 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jRGKv-000OEm-Nr for ged-emacs-devel@m.gmane-mx.org; Wed, 22 Apr 2020 16:26:49 +0200 Original-Received: from localhost ([::1]:51764 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jRGKu-0003f5-SV for ged-emacs-devel@m.gmane-mx.org; Wed, 22 Apr 2020 10:26:48 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58246) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jRGK9-0002gt-H9 for emacs-devel@gnu.org; Wed, 22 Apr 2020 10:26:02 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:59338) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jRGK9-0005o5-32; Wed, 22 Apr 2020 10:26:01 -0400 Original-Received: from [176.228.60.248] (port=2995 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jRGJx-0002YK-EX; Wed, 22 Apr 2020 10:25:52 -0400 In-Reply-To: <87blnjopd0.fsf@nicolasgoaziou.fr> (message from Nicolas Goaziou on Wed, 22 Apr 2020 11:12:59 +0200) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:247513 Archived-At: > From: Nicolas Goaziou > Date: Wed, 22 Apr 2020 11:12:59 +0200 > Cc: Joost Kremers , emacs-devel@gnu.org > > > When you tell me that Emacs has important facilities -- doing jobs > > very different from outline editing -- that I don't know about because > > they have been integrated as "part of Org mode", my conclusion is that > > we should have integrated them differently. Those other facilities > > should not be treated as "part of Org mode". They should be separate > > facilities, each one documented separately, and usable by itself. > > > > I would like to see those facilities separated from Org mode and made > > into separate first-class subsystems. Then they can be documented in > > the Emacs manual. > > There may be a misconception about what Org really is. It is unfortunate > if its documentation lets one think the mode is about outline editing. > > Org is both a lightweight markup language, and a major mode to edit > it. Versatile, it is useful for keeping notes, maintaining TODO lists, > and project planning. Powerful, it may be used as a complete authoring > system, with support for literate programming and reproducible > research. > > Outline editing is but the design choice that was made for the major > mode to edit documents with Org syntax. To put it differently, the > common factor between the "other facilities" you mention, whatever they > are, is not the outliner part, but the markup language behind it. IMNSHO, the Org manual "needs work"™. Its current form shows the long history of the package, more than it shows what it is nowadays. I mean, consider this opening phrases in Introduction: Org is a mode for keeping notes, maintaining TODO lists, and project planning with a fast and effective plain-text markup language. It also is an authoring system with unique support for literate programming and reproducible research. Org is implemented on top of Outline mode, which makes it possible to keep the content of large files well structured. Visibility cycling and structure editing help to work with the tree. Tables are easily created with a built-in table editor. Plain text URL-like links connect to websites, emails, Usenet messages, BBDB entries, and any files related to the projects. Org develops organizational tasks around notes files that contain lists or information about projects as plain text. Project planning and task management make use of metadata which is part of an outline node. Based on this data, specific entries can be extracted in queries and create dynamic _agenda views_ that also integrate the Emacs calendar and diary. Org can be used to implement many different project planning schemes, such as David Allen’s GTD system. Etc., etc. I invite you to put yourself in the shows of a newcomer to Org, and try to imagine how such a newcomer will be able to realize that Org can be used as a word-processor... So please don't be surprised that Richard thinks about this what he thinks. Now, suppose someone tells me that Org includes word-processing capabilities, and I'm excited about that and want to learn how to do that. Here's the menu I'm presented with in the Top node: * Introduction:: Getting started. * Document Structure:: A tree works like your brain. * Tables:: Pure magic for quick formatting. * Hyperlinks:: Notes in context. * TODO Items:: Every tree branch can be a TODO item. * Tags:: Tagging headlines and matching sets of tags. * Properties and Columns:: Storing information about an entry. * Dates and Times:: Making items useful for planning. * Refiling and Archiving:: Moving and copying information with ease. * Capture and Attachments:: Dealing with external data. * Agenda Views:: Collecting information into views. * Markup for Rich Contents:: Compose beautiful documents. * Exporting:: Sharing and publishing notes. * Publishing:: Create a web site of linked Org files. * Working with Source Code:: Export, evaluate, and tangle code blocks. * Miscellaneous:: All the rest which did not fit elsewhere. * Hacking:: How to hack your way around. * History and Acknowledgments:: How Org came into being. * GNU Free Documentation License:: The license for this documentation. * Main Index:: An index of Org’s concepts and features. * Key Index:: Key bindings and where they are described. * Command and Function Index:: Command names and some internal functions. * Variable Index:: Variables mentioned in the manual. Hmm... which one of the chapters should I read? I tried "Publishing" first, but quickly realized that's not it. Next, I tried "Exporting" ("Sharing and publishing notes.", right?) -- another false hit. Finally, I thought maybe it's in "Markup for Rich Contents". This time I think I found what I was looking for, but look at that chapter's menu: * Paragraphs:: The basic unit of text. * Emphasis and Monospace:: Bold, italic, etc. * Subscripts and Superscripts:: Simple syntax for raising/lowering text. * Special Symbols:: Greek letters and other symbols. * Embedded LaTeX:: LaTeX can be freely used inside Org documents. * Literal Examples:: Source code examples with special formatting. * Images:: Display an image. * Captions:: Describe tables, images... * Horizontal Rules:: Make a line. * Creating Footnotes:: Edit and read footnotes. This sounds like a more-or-less random collection of related tidbits, not an explanation of how to use Org as a word-processor. And as soon as I go to the first section, "Paragraphs", I'm almost immediately lost: Paragraphs are separated by at least one empty line. If you need to enforce a line break within a paragraph, use ‘\\’ at the end of a line. To preserve the line breaks, indentation and blank lines in a region, but otherwise use normal formatting, you can use this construct, which can also be used to format poetry. #+BEGIN_VERSE Great clouds overhead Tiny black birds rise and fall Snow covers Emacs ---AlexSchroeder #+END_VERSE What are those "#+BEGIN_VERSE" and "#+END_VERSE" markers? Do I type them verbatim in the text of a document? There's no answer. (Of course, yours truly is somewhat familiar with Org, so _I_ know the answer. But a newbie won't.) This is not what a chapter about using a word processor should look like. It should begin with an introduction to word-processing with Org, an overview of what's possible and what isn't; it should go on to explaining how to start a document, how to write a heading and a sub-heading, how to insert references, links, footnotes, and other objects; it should then explain how to produce a TOC and an index, and finally point me to another chapter that explains how to export my document in a variety of formats. A good example of how such documentation should be structured is at the beginning of the Texinfo manual, which also describes a system for writing documents. Look at the first dozen of chapters there for inspiration. > As a consequence, it probably makes little sense to separate such > "facilities"---the term would need to be properly defined in the current > context, tho---, because each of them implies full support for the whole > Org syntax. Maybe you took the "separate" part to mean that the _code_ should be separated or subdivided. I'm not sure Richard meant that, but even if he did, what I would like to see is a "separation" on the documentation level. Let a user who only wants to write documents with Org be able to learn that without reading 50% of the Org manual, in order to understand "the whole Org syntax". Allow a user who is only interested in GTD to be able to do just that by learning the necessary Org commands and procedures, and little else. Etc. etc. -- try to "separate" what Org is capable of into several large classes of jobs, and make sure each of these classes is documented clearly and logically, as if it were a separate manual (and maybe it really should be a separate manual, I don't know). I hope I explained at least what is my view of how Org should evolve (in addition to the routine development that adds new features) -- it should try to present a less monolith-like appearance towards new users, and allow them to master just a part of its capabilities, the part that they are interested in. HTH and TIA