From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: Confused about the explanation for 'org-cycle' Date: Thu, 28 Sep 2017 16:31:43 +0200 Message-ID: <87h8vmopww.fsf@nicolasgoaziou.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> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:52752) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dxZqz-0005Ly-65 for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 10:31:54 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dxZqt-0001ST-F1 for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 10:31:53 -0400 Received: from relay2-d.mail.gandi.net ([2001:4b98:c:538::194]:44368) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dxZqt-0001Rl-9N for emacs-orgmode@gnu.org; Thu, 28 Sep 2017 10:31:47 -0400 In-Reply-To: <22986.19586.309718.302611@frac.u-strasbg.fr> (Alain Cochard's message of "Tue, 26 Sep 2017 14:48:02 +0200") 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: Alain.Cochard@unistra.fr Cc: emacs-orgmode@gnu.org 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 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