Next:Drawers, Previous:Sparse Trees, Up:Document Structure [Contents][Index]
Within an entry of the outline tree, hand-formatted lists can provideadditional structure. They also provide a way to create lists ofcheckboxes (seeCheckboxes). Org supports editing such lists, andevery exporter (seeExporting) can parse and format them.
Org knows ordered lists, unordered lists, and description lists.
Items belonging to the same list must have the same indentation on thefirst line. In particular, if an ordered list reaches number ‘10.’,then the 2-digit numbers must be written left-aligned with the othernumbers in the list. An item ends before the next line that is lessor equally indented than its bullet/number.
A list ends whenever every item has ended, which means before any lineless or equally indented than items at top level. It also ends beforetwo blank lines. In that case, all items are closed. Here is anexample:
* Lord of the RingsMy favorite scenes are (in this order)1. The attack of the Rohirrim2. Eowyn's fight with the witch king + this was already my favorite scene in the book + I really like Miranda Otto.3. Peter Jackson being shot by Legolas - on DVD only He makes a really funny face when it happens.8. [@8] <favorite scenes 4 to 8 are skipped for brevity>But in the end, no individual scenes matter but the film as a whole.Important actors in this film are:- Elijah Wood :: He plays Frodo- Sean Astin :: He plays Sam, Frodo's friend. I still remember him very well from his role as Mikey Walsh in /The Goonies/.
Org supports these lists by tuning filling and wrapping commands todeal with them correctly, and by exporting them properly (seeExporting). Since indentation is what governs the structure of theselists, many structural constructs like ‘#+BEGIN_’ blocks can beindented to signal that they belong to a particular item.
If you find that using a different bullet for a sub-list—than thatused for the current list-level—improves readability, customize thevariableorg-list-demote-modify-bullet. To get a greater differenceof indentation between items and theirs sub-items, customizeorg-list-indent-offset.
The following commands act on items when point is in the first line ofan item—the line with the bullet or number. Some of them imply theapplication of automatic rules to keep list structure intact. If someof these actions get in your way, configureorg-list-automatic-rulesto disable them individually.
org-cycle) ¶Items can be folded just like headline levels. Normally this worksonly if point is on a plain list item. For more details, see thevariableorg-cycle-include-plain-lists. If this variable is settointegrate, plain list items are treated like low-levelheadlines. The level of an item is then given by the indentation ofthe bullet/number. Items are always subordinate to real headlines,however; the hierarchies remain completely separated. In a new itemwith no text yet, the firstTAB demotes the item tobecome a child of the previous one. SubsequentTABs movethe item to meaningful levels in the list and eventually get it backto its initial position.
org-insert-item) ¶Insert new item at current level. With a prefix argument, force anew heading (seeStructure Editing). If this command is usedin the middle of an item, that item issplit in two, and thesecond part becomes the new item13. Ifthis command is executedbefore item’s body, the new item iscreatedbefore the current one.
Insert a new item with a checkbox (seeCheckboxes).
Jump to the previous/next item in the current list, but only iforg-support-shift-select is off14.If not, you can still use paragraph jumping commands likeC-UP andC-DOWN to quite similar effect.
Move the item including subitems up/down15, i.e., swapwith previous/next item of same indentation. If the list isordered, renumbering is automatic.
Decrease/increase the indentation of an item, leaving childrenalone.
Decrease/increase the indentation of the item, including subitems.Initially, the item tree is selected based on current indentation.When these commands are executed several times in direct succession,the initially selected region is used, even if the new indentationwould imply a different hierarchy. To use the new hierarchy, breakthe command chain by moving point.
As a special case, using this command on the very first item ofa list moves the whole list. This behavior can be disabled byconfiguringorg-list-automatic-rules. The global indentation ofa list has no influence on the textafter the list.
If there is a checkbox (seeCheckboxes) in the item line, togglethe state of the checkbox. In any case, verify bullets andindentation consistency in the whole list.
Cycle the entire list level through the different itemize/enumeratebullets (‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’) or a subset of them, dependingonorg-plain-list-ordered-item-terminator, the type of list, andits indentation. With a numeric prefix argument N, select the Nthbullet from this list. If there is an active region when callingthis, all lines are converted to list items. With a prefixargument, the selected text is changed into a single item. If thefirst line already was a list item, any item marker is removed fromthe list. Finally, even without an active region, a normal line isconverted into a list item.
Turn a plain list item into a headline—so that it becomesa subheading at its location. SeeStructure Editing, fora detailed explanation.
Turn the whole plain list into a subtree of the current heading.Checkboxes (seeCheckboxes) become ‘TODO’, respectively ‘DONE’,keywords when unchecked, respectively checked.
This command also cycles bullet styles when point is in on thebullet or anywhere in an item line, details depending onorg-support-shift-select.
Sort the plain list. Prompt for the sorting method: numerically,alphabetically, by time, or by custom function.
When using ‘*’ as a bullet, lines must be indented so that theyare not interpreted as headlines. Also, when you are hiding leadingstars to get a clean outline view, plain list items starting witha star may be hard to distinguish from true headlines. In short: eventhough ‘*’ is supported, it may be better to not use it for plain listitems.
You can filter out any of them byconfiguringorg-plain-list-ordered-item-terminator.
You can also get ‘a.’, ‘A.’, ‘a)’ and ‘A)’ by configuringorg-list-allow-alphabetical. To minimize confusion with normaltext, those are limited to one character only. Beyond that limit,bullets automatically become numbers.
If there’s a checkbox in the item, the cookie must be putbefore the checkbox. If you have activated alphabetical lists, youcan also use counters like ‘[@b]’.
If you do not want the item tobe split, customize the variableorg-M-RET-may-split-line.
If you want to cycle arounditems that way, you may customizeorg-list-use-circular-motion.
Seeorg-list-use-circular-motion for a cyclic behavior.
Next:Drawers, Previous:Sparse Trees, Up:Document Structure [Contents][Index]