From mboxrd@z Thu Jan  1 00:00:00 1970
From: Matt Lundin <mdl@imapmail.org>
Subject: Re: Confused about the explanation for 'org-cycle'
Date: Tue, 19 Sep 2017 00:08:36 -0500
Message-ID: <874lrzl1gr.fsf@fastmail.fm>
References: <22975.53875.671661.416361@frac.u-strasbg.fr>
Mime-Version: 1.0
Content-Type: text/plain
Return-path: <emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([2001:4830:134:3::10]:36245)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <mdl@imapmail.org>) id 1duAm4-0007yV-Nc
	for emacs-orgmode@gnu.org; Tue, 19 Sep 2017 01:08:45 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <mdl@imapmail.org>) id 1duAlz-0002Tj-Mj
	for emacs-orgmode@gnu.org; Tue, 19 Sep 2017 01:08:44 -0400
Received: from out1-smtp.messagingengine.com ([66.111.4.25]:39287)
	by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)
	(Exim 4.71) (envelope-from <mdl@imapmail.org>) id 1duAlz-0002TF-EB
	for emacs-orgmode@gnu.org; Tue, 19 Sep 2017 01:08:39 -0400
In-Reply-To: <22975.53875.671661.416361@frac.u-strasbg.fr> (Alain Cochard's
	message of "Mon, 18 Sep 2017 16:04:35 +0200")
List-Id: "General discussions about Org-mode." <emacs-orgmode.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/emacs-orgmode/>
List-Post: <mailto:emacs-orgmode@gnu.org>
List-Help: <mailto:emacs-orgmode-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=subscribe>
Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
Sender: "Emacs-orgmode"
	<emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org>
To: Alain.Cochard@unistra.fr
Cc: emacs-orgmode@gnu.org

I agree that this is confusing. I examined the org repository history,
and it seems that both the documentation and the variable go all the way
back to 2007. I believe the default value of the variable was changed to
nil, but the documentation was not updated accordingly.  

Matt

Alain.Cochard@unistra.fr writes:

> Hello.
>
> In section "2.3.1 Global and local cycling" of the manual I read:
>
>
>      `<TAB>'     (`org-cycle')
>           _Subtree cycling_: Rotate current subtree among the states
>
>                ,-> FOLDED -> CHILDREN -> SUBTREE --.
>                '-----------------------------------'
>
>           The cursor must be on a headline for this to work(1).  When the
>           cursor is at the beginning of the buffer and the first line is not
>           a headline, then <TAB> actually runs global cycling (see
>           below)(2).
>
> with the footnote being
>
>      (2) see the option `org-cycle-global-at-bob'.
>
>
> If I use Org Mode without any customization, then, when using <TAB>
> "When the cursor is at the beginning of the buffer and the first line
> is not a headline", absolutely nothing is done.
>
> Sure, this is consistent with the help page of variable
> org-cycle-global-at-bob which says that "When this option is nil,
> don't do anything special at the beginning of the buffer", together
> with the fact that, without any customization, org-cycle-global-at-bob
> is 'nil'.
>
> But I find this very confusing, at least for the beginner, who is
> unlikely to enquire right away about the possible values of
> org-cycle-global-at-bob.
>
> Or perhaps I am missing something at the English level?
>
> Regards,
> alain