Re: Visibility cycling of plain lists?

[James Harkins <jamshark70@gmail.com>]

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