[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Nicolas Goaziou
Subject: Re: [O] Confused about the explanation for 'org-cycle'
Date: Thu, 28 Sep 2017 16:31:43 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.2 (gnu/linux)


address@hidden 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'.


Nicolas Goaziou

reply via email to

[Prev in Thread] Current Thread [Next in Thread]