Re: Confused about the explanation for 'org-cycle'

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Alain.Cochard@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