From mboxrd@z Thu Jan 1 00:00:00 1970 From: James Harkins Subject: Re: Visibility cycling of plain lists? Date: Tue, 1 Jan 2013 10:13:05 +0800 Message-ID: References: <87k3ryo95z.fsf@bzg.ath.cx> <87sj6ml2x5.fsf@bzg.ath.cx> Reply-To: jamshark70@dewdrop-world.net Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Return-path: Received: from eggs.gnu.org ([208.118.235.92]:46266) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TprLs-0002bG-8X for Emacs-orgmode@gnu.org; Mon, 31 Dec 2012 21:13:14 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TprLo-0002gs-C2 for Emacs-orgmode@gnu.org; Mon, 31 Dec 2012 21:13:12 -0500 Received: from mail-oa0-f44.google.com ([209.85.219.44]:45882) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TprLo-0002go-7E for Emacs-orgmode@gnu.org; Mon, 31 Dec 2012 21:13:08 -0500 Received: by mail-oa0-f44.google.com with SMTP id n5so12178683oag.17 for ; Mon, 31 Dec 2012 18:13:05 -0800 (PST) In-Reply-To: <87sj6ml2x5.fsf@bzg.ath.cx> 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-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Emacs-orgmode@gnu.org On Mon, Dec 31, 2012 at 10:19 PM, Bastien wrote: > Hi James, > > James Harkins writes: > >> My point exactly- neither the manual nor the docstring do anything to >> dispel that confusion. > > If you do C-h v org-cycle-include-plain-lists RET you read that > a value of t allows visibility cycling and that a value of 'integrate > temporarily interprets list items as outline headlines. You're right; I had forgotten to expand the docstring, so I saw only the first line. The options are explained in subsequent paragraphs. The only issue left, then, is the disconnect between the value menu descriptions and the actual values. Here, I guess it would make sense to follow the Emacs convention for documenting customize-interface value menus, if there is such a convention. If not, this patch might help, adding text like this after the paragraph description: ~~ Value menu options: Never --> nil With cursor in plain list (recommended) --> t (the default) As children of outline headings --> integrate ~~ (I'm assuming the convention is not "don't document.") In the org manual, it would probably be enough to add a parenthetical note: ~~ If this variable is set to 'integrate' ("As children of outline headings" in the customize interface), plain list items will be treated like low-level headlines. ~~ > When customizing, you can either set it to "Never", which is obvious. > > Or to `t', which is explained. I differ here -- in the menu, you don't set it to "t." > Or to the other value, which is the symbol 'integrate. This third > value is mentioned in the docstring, and it is pretty obvious that > it corresponds to "As children of outline headings", as there are > no other choices. Ah, I see. It's *obvious*. (I guess org-mode's target audience is smarter than I am.) I do see your point that the options are described, and I apologize for overlooking them earlier. But, if one is using the customize interface, then there remains a (small) bit of guesswork to connect the documentation to what is presented in the interface, and I think generally documentation should be there to eliminate guesswork (or at least reduce the need for it). (That's not a specific complaint to org -- on the SuperCollider mailing list, I'm constantly harping on method documentation that doesn't explain the expected types of the input and output, for the same reason -- if I have to write a short bit of test code to figure out what the method is supposed to do, then the documentation isn't complete.) hjh PS And *again* I'm bitten by the fact that I just can't get used to mailing lists where replies are sent to individual authors as well as the list address... sorry about that.