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: Tue, 26 Sep 2017 14:48:02 +0200 Message-ID: <22986.19586.309718.302611@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> 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]:60221) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dwpHg-0005uo-Mg for emacs-orgmode@gnu.org; Tue, 26 Sep 2017 08:48:23 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dwpHX-0006Hq-FE for emacs-orgmode@gnu.org; Tue, 26 Sep 2017 08:48:17 -0400 Received: from mailhost.u-strasbg.fr ([130.79.222.212]:50778) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dwpHX-0006HS-4z for emacs-orgmode@gnu.org; Tue, 26 Sep 2017 08:48:11 -0400 In-Reply-To: <877ewl4u8s.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 Nicolas Goaziou writes on Tue 26 Sep 2017 12:41: > Hello, >=20 > Alain.Cochard@unistra.fr writes: >=20 > > But now, compared to the previous version: > > > > When the cursor is at the beginning of the buffer and the > > first line is not a headline, then actually runs global > > cycling > > > > it is not clear to me why the mention "and the first line is not > > a headline" has been suppressed. >=20 > I traded completeness for clarity.=20 >=20 > The reasoning is that the description about a pathological case -- > here, the first line of the buffer being a heading -- belongs to > variable's docstring, not to the manual. >=20 > We can add a footnote about that case, but even a footnote impedes > clarity. >=20 > Of course, if you have a clear wording that includes that > pathological case, I'll happily use it. OK, I understand your point, although I probably cannot fully appreciate it because I do not know what a "docstring" is. 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. More generally, I cannot remember the number of times when I read the manual, do not understand it, am essentially sure that it is wrongly phrased but (just in case) spend a (too) long time searching the Web before complaining to the list, to finally realize that "Ah OK, the manual is fully correct." In other words, the manual is often too concise/elegant 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. But maybe that's just me... 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=