Re: Specialized Emacs Features ?

[Jean-Christophe Helary]

> On Jun 3, 2017, at 8:55, Clément Pit-Claudel <address@hidden> wrote:
> 
> On 2017-06-02 19:46, Jean-Christophe Helary wrote:
>> I agree, and I'm not suggesting that we impose a learning method to the 
>> reader. The manual is fully linked and referenced and as such is already 
>> fully "spiralable".
> 
> That's not how I understood "in a spiral": I understood it as meaning that 
> the current manual can be read front to back, and that it proceeds roughly in 
> breadth-first order.  Gathering related topic causes you to learn a lot about 
> a particular topic before you learn anything about the next one.

I understand that. And we can discuss theory of learning and reading books for 
ever, which is not what I am trying to do.

The reality of the manual is that nobody reads it front to back. People start 
with a few online tutorials, start using Emacs, eventually go through the 
Tutorial and then search for information on topics either on the web or in the 
manuals installed on their machines. And even when they know that the manual is 
here, they don't really try to read it front to back in the end because there 
is no logical structure in it: why would we consider "moving around words, 
paragraphs and pages" as "advanced" when it is pretty much the core of the 
Tutorial ?

The "Advanced Features" section maybe made sense when the printed manual was 
really a thing (3 decades ago?),  but then people started to abuse it and it is 
now a place where things that are now considered "basic" are mixed with things 
that are commonly used and things that are truly advanced...

It reminds me of the documentation for the "trim" argument in split-string. The 
argument was added in 2013 and instead of putting its documentation at the 
*end* of the documentation paragraph since it was the last argument of the 
function, it was put *after* the long list or examples. I moved it where it 
belonged the other day, but there are plenty of things like this in the manual 
and in the reference that make it hard to read and in the end hard to 
understand.

Jean-Christophe