Re: "Why is emacs so square?"

[Eli Zaretskii]

> From: Nicolas Goaziou <address@hidden>
> Date: Wed, 22 Apr 2020 11:12:59 +0200
> Cc: Joost Kremers <address@hidden>, address@hidden
> 
> > 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