Re: [O] Confused about the explanation for 'org-cycle'

[Alain . Cochard]

Nicolas Goaziou writes on Tue 26 Sep 2017 12:41:
 > Hello,
 > 
 > address@hidden writes:
 > 
 > > But now, compared to the previous version:
 > >
 > >    When the cursor is at the beginning of the buffer and the
 > >    first line is not a headline, then <TAB> actually runs global
 > >    cycling
 > >
 > > it is not clear to me why the mention "and the first line is not
 > > a headline" has been suppressed.
 > 
 > I traded completeness for clarity. 
 > 
 > The reasoning is that the description about a pathological case --
 > here, the first line of the buffer being a heading -- belongs to
 > variable's docstring, not to the manual.
 > 
 > We can add a footnote about that case, but even a footnote impedes
 > clarity.
 > 
 > Of course, if you have a clear wording that includes that
 > pathological case, I'll happily use it.

OK, I understand your point, although I probably cannot fully
appreciate it because I do not know what a "docstring" is.

As for the wording, I have nothing ecstatic to propose, but -- as a
beginner and trying to think like one who is reading the manual for
the first time while experimenting -- I would have been happy with
something like:

   You can run global cycling using <TAB> only if point is at the very
   beginning of the buffer (not being a headline) and
   `org-cycle-global-at-bob' is set to a non-`nil' value.


More generally, I cannot remember the number of times when I read the
manual, do not understand it, am essentially sure that it is wrongly
phrased but (just in case) spend a (too) long time searching the Web
before complaining to the list, to finally realize that "Ah OK, the
manual is fully correct."

In other words, the manual is often too concise/elegant for the
(admittedly not very smart) beginner that I am, and I would favor
completeness -- with footnotes, dumb examples to get started, more
cross-references, even repetitions -- over clarity.

But maybe that's just me...

Regards,
a.



-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | address@hidden
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25