org: Plain lists
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 (
Checkboxes). Org supports editing such lists, and
every exporter (Exporting) can parse and format them.
Org knows ordered lists, unordered lists, and description lists.
• _Unordered_ list items start with ‘-’, ‘+’, or ‘*’(1) as bullets.
• _Ordered_ list items start with a numeral followed by either a
period or a right parenthesis(2), such as ‘1.’ or ‘1)’(3). If you
want a list to start with a different value (e.g., 20), start the
text of the item with ‘[@20]’(4). 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 distinguish 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. An item ends before the next line that is less or
equally indented than its bullet/number.
A list ends whenever every item has ended, which means before any
line less or equally indented than items at top level. It also ends
before two blank lines(5). In that case, all items are closed. 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
- on DVD only
He makes a really funny face when it happens.
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(6), and by exporting them properly (
Exporting). Since indentation is what governs the structure of these
lists, many structural constructs like ‘#+BEGIN_...’ blocks can be
indented to signal that they belong to a particular item.
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 ‘org-list-demote-modify-bullet’. To get a greater difference
of indentation between items and theirs sub-items, customize
‘org-list-indent-offset’.
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
‘org-list-automatic-rules’ to disable them individually.
‘<TAB>’ (‘org-cycle’)
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.
In a new item with no text yet, the first <TAB> demotes the item to
become a child of the previous one. Subsequent <TAB>s move the
item to meaningful levels in the list and eventually get it back to
its initial position.
‘M-<RET>’ (‘org-insert-heading’)
Insert new item at current level. With a prefix argument, force a
new heading (Structure editing). If this command is used
in the middle of an item, that item is _split_ in two, and the
second part becomes the new item(7). If this command is executed
_before item’s body_, the new item is created _before_ the current
one.
‘M-S-<RET>’
Insert a new item with a checkbox (Checkboxes).
‘S-up’
‘S-down’
Jump to the previous/next item in the current list(8), but only if
‘org-support-shift-select’ is off. If not, you can still use
paragraph jumping commands like ‘C-<up>’ and ‘C-<down>’ to quite
similar effect.
‘M-up’
‘M-down’
Move the item including subitems up/down(9) (swap with
previous/next item of same indentation). If the list is ordered,
renumbering is automatic.
‘M-left’
‘M-right’
Decrease/increase the indentation of an item, leaving children
alone.
‘M-S-<left>’
‘M-S-<right>’
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 (Checkboxes) in the item line,
toggle the state of the checkbox. In any case, verify bullets and
indentation consistency in the whole list.
‘C-c -’
Cycle the entire list level through the different itemize/enumerate
bullets (‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’) or a subset of them, depending
on ‘org-plain-list-ordered-item-terminator’, the type of list, and
its indentation. With a numeric prefix argument N, select the Nth
bullet from this list. If there is an active region when calling
this, selected text will be changed into an item. With a prefix
argument, all lines will be converted to list items. If the first
line already was a list item, any item marker 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). Structure editing, for a
detailed explanation.
‘C-c C-*’
Turn the whole plain list into a subtree of the current heading.
Checkboxes (Checkboxes) will become TODO (resp. DONE)
keywords when unchecked (resp. checked).
‘S-left/right’
This command also cycles bullet styles when the cursor in on the
bullet or anywhere in an item line, details depending on
‘org-support-shift-select’.
‘C-c ^’
Sort the plain list. You will be prompted for the sorting method:
numerically, alphabetically, by time, by checked status for check
lists, or by a custom function.
---------- Footnotes ----------
(1) When using ‘*’ as a bullet, lines must be indented or they will
be seen as top-level headlines. Also, when you are hiding leading stars
to get a clean outline view, plain list items starting with a star may
be hard to distinguish from true headlines. In short: even though ‘*’
is supported, it may be better to not use it for plain list items.
(2) You can filter out any of them by configuring
‘org-plain-list-ordered-item-terminator’.
(3) You can also get ‘a.’, ‘A.’, ‘a)’ and ‘A)’ by configuring
‘org-list-allow-alphabetical’. To minimize confusion with normal text,
those are limited to one character only. Beyond that limit, bullets
will automatically fallback to numbers.
(4) If there’s a checkbox in the item, the cookie must be put
_before_ the checkbox. If you have activated alphabetical lists, you
can also use counters like ‘[@b]’.
(5) See also ‘org-list-empty-line-terminates-plain-lists’.
(6) Org only changes the filling settings for Emacs. For XEmacs, you
should use Kyle E. Jones’ ‘filladapt.el’. To turn this on, put into
‘.emacs’: ‘(require 'filladapt)’
(7) If you do not want the item to be split, customize the variable
‘org-M-RET-may-split-line’.
(8) If you want to cycle around items that way, you may customize
‘org-list-use-circular-motion’.
(9) See ‘org-list-use-circular-motion’ for a cyclic behavior.
Info Catalog
org: Sparse trees
org: Document Structure
org: Drawers