Hello, alain.coch...@unistra.fr writes:
> 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. Fixed. Thank you. > More generally, I cannot remember the number of times when I read the > manual, do not understand it, This is exactly where the manual fails. What is the point of an exhaustive, yet not understandable, manual? > In other words, the manual is often too concise/elegant Alas, it is not. See above. > 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. Completeness is not possible. For example, we do not document every variable in the manual. Besides, when reading a pile of special rules for special cases, the reader may lose focus and miss the whole concept. BTW, a "docstring" is the documentation you get when using, e.g., `C-h v' or `C-h f'. Regards, -- Nicolas Goaziou
