On Mon, Dec 31, 2012 at 10:19 PM, Bastien <b...@altern.org> wrote: > Hi James, > > James Harkins <jamshar...@gmail.com> 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.