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