|The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
RRP £9.95 ($14.95)
Sales of this book support the Org project! Get a printed copy>>>
2.7 Plain lists
Within an entry of the outline tree, hand-formatted lists can provide additional structure. They also provide a way to create lists of checkboxes (see section 5.6 Checkboxes). Org supports editing such lists, and every exporter (see section 12 Exporting) can parse and format them.
Org knows ordered lists, unordered lists, and description lists.
- Unordered list items start with ‘-’, ‘+’, or ‘*’(11) as bullets.
Ordered list items start with a numeral followed by either a period or
a right parenthesis,(12) such as ‘1.’ or
‘1)’. If you want a list to start with a different value (e.g. 20), start
the text of the item with
[@20].(13) Those constructs can be used in any item of the list in order to enforce a particular numbering.
- Description list items are unordered list items, and contain the separator ‘ :: ’ to separate the description term from the description.
Items belonging to the same list must have the same indentation on the first line. In particular, if an ordered list reaches number ‘10.’, then the 2--digit numbers must be written left-aligned with the other numbers in the list.
Two methods(14) are provided to terminate lists. A list ends
before the next line that is indented like the bullet/number or less, or it
ends before two blank lines.(15) In both cases, all levels of
the list are closed.(16) For finer control, you can end lists
with any pattern set in
org-list-end-regexp. Here is an example:
** Lord of the Rings My favorite scenes are (in this order) 1. The attack of the Rohirrim 2. 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 He makes a really funny face when it happens. - on DVD only 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 Austin :: 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 to deal with
them correctly,(17) and by exporting them
properly (see section 12 Exporting). Since indentation is what governs the
structure of these lists, many structural constructs like
blocks can be indented to signal that they should be considered as a list
If you find that using a different bullet for a sub-list (than that used for
the current list-level) improves readability, customize the variable
The following commands act on items when the cursor is in the first line of
an item (the line with the bullet or number). Some of them imply the
application of automatic rules to keep list structure intact. If some of
these actions get in your way, configure
to disable them individually.
- TAB (
Items can be folded just like headline levels. Normally this works only if
the cursor is on a plain list item. 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. The level of an item is then given by the indentation of the bullet/number. Items are always subordinate to real headlines, however; the hierarchies remain completely separated.
- M-RET (
- Insert new item at current level. With a prefix argument, force a new heading (see section 2.5 Structure editing). If this command is used in the middle of a line, the line is split and the rest of the line becomes the new item.(18) If this command is executed before an item's body, the new item is created before the current item. If the command is executed in the white space before the text that is part of an item but does not contain the bullet, a bullet is added to the current line. As a new item cannot be inserted in a structural construct (like an example or source code block) within a list, Org will instead insert it right before the structure, or return an error.
- Insert a new item with a checkbox (see section 5.6 Checkboxes).
- TAB (
- In a new item with no text yet, the first TAB demotes the item to become a child of the previous one. Subsequent TABs move the item to meaningful levels in the list and eventually get it back to its initial position.
Jump to the previous/next item in the current list, but only if
org-support-shift-selectis off. If not, you can still use paragraph jumping commands like C-up and C-down to quite similar effect.
- Move the item including subitems up/down (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic.
- Decrease/increase the indentation of an item, leaving children alone.
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 indentation would imply a different
hierarchy. To use the new hierarchy, break the command chain with a cursor
motion or so.
As a special case, using this command on the very first item of a list will
move the whole list. This behavior can be disabled by configuring
org-list-automatic-rules. The global indentation of a list has no influence on the text after the list.
- C-c C-c
- If there is a checkbox (see section 5.6 Checkboxes) in the item line, toggle the state of the checkbox. Also, makes sure that all the items on this list level use the same bullet and that the numbering of list items (if applicable) is correct.
- C-c -
Cycle the entire list level through the different itemize/enumerate bullets
(‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’) or a subset of them,
org-plain-list-ordered-item-terminator, the type of list, and its position.(19) With a numeric prefix argument N, select the Nth bullet from this list. If there is an active region when calling this, all lines will be converted to list items. If the first line already was a list item, any item markers will be removed from the list. Finally, even without an active region, a normal line will be converted into a list item.
- C-c *
- Turn a plain list item into a headline (so that it becomes a subheading at its location). See section 2.5 Structure editing, for a detailed explanation.
This command also cycles bullet styles when the cursor in on the bullet or
anywhere in an item line, details depending on
- C-c ^
- Sort the plain list. You will be prompted for the sorting method: numerically, alphabetically, by time, or by custom function.
|ISBN 9781906966089||The Org Mode 7 Reference Manual||See the print edition|