Re: Visibility cycling of plain lists?

[Bastien <bzg@altern.org>]

Hi James,

James Harkins <jamshark70@gmail.com> writes:

> ~~
> 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.
> ~~

If find the above a bit clumsy and repetitive, I just updated the
docstring like this:

  When this is the symbol `integrate', then integrate plain list
  items when cycling, as if they were children of outline headings.

> 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.)

I agree -- but what's difficult is that documentation problems are
often mixed problems, about content *and* UI.  And content can not 
always alleviate the guesswork induced by unfamiliar UI.

-- 
 Bastien