Nicolas Goaziou writes on Tue 26 Sep 2017 12:41: > Hello, > > alain.coch...@unistra.fr 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) | alain.coch...@unistra.fr 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