Re: [O] Visibility cycling of plain lists?
Hi James, James Harkins jamshar...@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
Re: [O] Visibility cycling of plain lists?
Hi James, James Harkins jamshar...@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: [O] Visibility cycling of plain lists?
On Dec 31, 2012 5:36 PM, Bastien b...@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
Re: [O] Visibility cycling of plain lists?
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. 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: [O] Visibility cycling of plain lists?
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.
[O] Visibility cycling of plain lists?
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 jamshar...@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: [O] Visibility cycling of plain lists?
On Mon, Dec 31, 2012 at 11:53 AM, James Harkins jamshar...@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
