From mboxrd@z Thu Jan 1 00:00:00 1970 From: Alain.Cochard@unistra.fr Subject: Re: Confused about the explanation for 'org-cycle' Date: Thu, 28 Sep 2017 23:04:57 +0200 Message-ID: <22989.25593.198323.807112@frac.u-strasbg.fr> References: <22975.53875.671661.416361@frac.u-strasbg.fr> <874lrzl1gr.fsf@fastmail.fm> <87lgl963jf.fsf@nicolasgoaziou.fr> <22986.5564.583945.909910@frac.u-strasbg.fr> <877ewl4u8s.fsf@nicolasgoaziou.fr> <22986.19586.309718.302611@frac.u-strasbg.fr> <87h8vmopww.fsf@nicolasgoaziou.fr> Reply-To: alain.cochard@unistra.fr Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:59602) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dxfzb-0001AY-HX for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 17:05:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dxfzY-0004Pn-1J for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 17:05:11 -0400 Received: from mailhost.u-strasbg.fr ([130.79.222.213]:43711) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dxfzX-0004Nk-Ne for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 17:05:07 -0400 In-Reply-To: <87h8vmopww.fsf@nicolasgoaziou.fr> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Nicolas Goaziou Cc: emacs-orgmode@gnu.org, 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, >=20 > This is exactly where the manual fails. What is the point of an > exhaustive, yet not understandable, manual=3F 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. >=20 > 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. --=20 EOST (=C9cole et Observatoire des Sciences de la Terre)=20 IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr 5 rue Ren=E9 Descartes [bureau 106] | Phone: +33 (0)3 68 85 50 44=20 F-67084 Strasbourg Cedex, France | Fax: +33 (0)3 68 85 01 25 =20=