Visibility cycling of plain lists?

Visibility cycling of plain lists?

[James Harkins]

Is there a way to show the content of a node containing a plain list,
so that the plain list items are collapsed? Or, is there a function
that will automatically collapse all the items in the plain list?

For instance, if I have a tree like this:

* Top level I
** Subheading A
*** Further subheading 1
** Subheading B
* Top-level II

When I first visit the file, I see:

* Top level I...
* Top-level II

... and if I expand the first heading, I see:

* Top level I
** Subheading A...
** Subheading B
* Top-level II

But, if the tree has this structure instead:

* TODO Top level I [0/2]
  - [ ] List item A
    Comments on list item A
  - [ ] List item B
    Comments on list item B
* Top-level II

... expanding the first node expands the entire contents, including
the comments -- I see *everything*. It's more useful to me to see the
list items collapsed (comments hidden), and then I can use tab
visibility cycling to see the comments that I want to see.

I'm aware that I could use regular subheadings for these list items.
The problem is that they would all have to be TODOs (because I want
the parent node's progress cookie to update), but I don't need to
track them individually in my agenda views. The top-level here is a
homework assignment, and each list item is work received from one
student. In the agenda, I need to know only that I haven't graded
everything for that assignment yet, but I don't need to see a separate
TODO entry for every student. Lists with checkboxes are perfect for
this.

Also, if I used "real" TODOs, org-mobile-push would assign an org-id
to every one of them, grossly bloating my ~/.emacs.d/.org-id-locations
(and bloating the org file with hundreds of :PROPERTIES: drawers that
I don't really need). So it's really much more efficient for me to use
list items, except that I haven't found a way to use visibility
cycling on them that is as intelligent as it is for outline headings.

Thanks,
hjh


-- 
James Harkins /// dewdrop world
jamshark70@dewdrop-world.net
http://www.dewdrop-world.net

"Come said the Muse,
Sing me a song no poet has yet chanted,
Sing me the universal."  -- Whitman

blog: http://www.dewdrop-world.net/words
audio clips: http://www.dewdrop-world.net/audio
more audio: http://soundcloud.com/dewdrop_world/tracks

Re: Visibility cycling of plain lists?

[James Harkins]

On Mon, Dec 31, 2012 at 11:53 AM, James Harkins <jamshark70@gmail.com> wrote:
> Is there a way to show the content of a node containing a plain list,
> so that the plain list items are collapsed? Or, is there a function
> that will automatically collapse all the items in the plain list?

Oops, just answered my own question:

http://orgmode.org/manual/Plain-lists.html#Plain-lists

"For more details, see the variable org-cycle-include-plain-lists. If
this variable is set to integrate, plain list items will be treated
like low-level headlines."

This confused me, however, because there is no "integrate" option in
org 7.9. There is an option "As children of outline headings."

Also, org-cycle-include-plain-lists's docstring is wrong: "When t,
make TAB cycle visibility on plain list items."

So... never mind the original question (but there are a couple of
documentation issues).

hjh

Re: Visibility cycling of plain lists?

[Bastien]

Hi James,

James Harkins <jamshark70@gmail.com> writes:

> http://orgmode.org/manual/Plain-lists.html#Plain-lists
>
> "For more details, see the variable org-cycle-include-plain-lists. If
> this variable is set to integrate, plain list items will be treated
> like low-level headlines."
>
> This confused me, however, because there is no "integrate" option in
> org 7.9. There is an option "As children of outline headings."

You are confusing the value of the option (which can indeed be
'integrate as a symbol) and the description of this choice in the 
customize interface.  

I reread the docstring of this option and I think it's fine.

> Also, org-cycle-include-plain-lists's docstring is wrong: "When t,
> make TAB cycle visibility on plain list items."

Mhh... what is wrong here?

> So... never mind the original question (but there are a couple of
> documentation issues).

Please report them as bugs in separate threads so that we can handle
them.

Thanks!

-- 
 Bastien

Re: Visibility cycling of plain lists?

[James Harkins]

[-- Attachment #1: Type: text/plain, Size: 1016 bytes --]

On Dec 31, 2012 5:36 PM, "Bastien" <bzg@altern.org> wrote:
> > This confused me, however, because there is no "integrate" option in
> > org 7.9. There is an option "As children of outline headings."
>
> You are confusing the value of the option (which can indeed be
> 'integrate as a symbol) and the description of this choice in the
> customize interface.

My point exactly- neither the manual nor the docstring do anything to
dispel that confusion.

> > Also, org-cycle-include-plain-lists's docstring is wrong: "When t,
> > make TAB cycle visibility on plain list items."
>
> Mhh... what is wrong here?

There are (at least) 3 options (I have no idea if there are any more), but
only t is described.

I suppose t is the default behavior (tab collapses plain list items, but
they're all open by default). But I'm guessing based on observation. This
goes unstated.

'integrate is a valid option, but the docstring doesn't say so. It also
doesn't say anything about the behavior of nil.

I can file bugs later.

hjh

[-- Attachment #2: Type: text/html, Size: 1333 bytes --]

Re: Visibility cycling of plain lists?

[Bastien]

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.

When customizing, you can either set it to "Never", which is obvious.

Or to `t', which is explained.

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.

> There are (at least) 3 options (I have no idea if there are any
> more), but only t is described.

No -- t and 'integrate are described.

> I suppose t is the default behavior

It is -- and C-h v org-cycle-include-plain-lists RET tells you this.

> (tab collapses plain list items,
> but they're all open by default). But I'm guessing based on
> observation. This goes unstated.
>
> 'integrate is a valid option, but the docstring doesn't say so. 

Well, it does say so.

> It also doesn't say anything about the behavior of nil.
>
> I can file bugs later.

Please make sure this is a real bug and not a misunderstanding on
your side.  Also please provide a patch, that's often the best way
to understand where misunderstandings lie.  Thanks!

-- 
 Bastien

Re: Visibility cycling of plain lists?

[James Harkins]

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.

Re: Visibility cycling of plain lists?

[Bastien]

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