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

[Alain.Cochard@unistra.fr]

Thanks for your answer.

Nicolas Goaziou writes on Thu 28 Sep 2017 16:31:

 > > 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?

It looks like I did not make myself clear (or I don't understand your
sentence above): the "number of times" to which I was referring are
when the manual is /not exhaustive enough/ (to me, that is).

 > > 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.

I guess the degree of expected completeness varies between
individuals...  This being said, I contend that it is often possible
to add a lot of completeness mostly without altering clarity, using an
appropriate organization (like more in-depth sections or examples
sections).  (In fact, it seems to me that this is what is already
often done.)

Precisely, regarding variable documentation, I remember that you
already made your point in an earlier email, advocating the use of
customize-group; while I certainly do not argue about its usefulness
for some purposes, for me it is often much less convenient than
exhaustive variable documentation would be.

I have a fresh example in mind to illustrate my point: this afternoon,
I was looking for org-blank-before-new-entry.  I vaguely remembered it
existed and was searching the manual (from Info) with the regexps
'blank' and 'list'.  Had the variable been mentioned, I would have
found it within seconds; by contrast I can't imagine how much time I
would need using customize-group...  And, in this case, I don't see
how having a separate section (e.g., an appendix, much like the
Variable section), with all variables documented, would remove the
least bit of clarity.

Also, I am aware that there exist at the Worg site many tutorials
which give more in-depth documentation on specific topics.  Those
tutorials are great in general.  Nevertheless, I often observe that,
by contrast with the manual which is meant to be up-to-date, they are
obsolete in some respect, which makes them difficult for me to use in
order to get started.


 > BTW, a "docstring" is the documentation you get when using, e.g.,
 > `C-h v' or `C-h f'.

Thank you.  In retrospect, I realize I should have looked it up
myself...


Regards,
a.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@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