65
Chapter 2: Document structure
13
Unordered list items start with ‘-’, ‘+’, or ‘*’
10
as bullets.
Ordered list items start with a numeral followed by either a period or a right paren-
thesis
11
,such as ‘1.’ or ‘1)’
12
. 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
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 anordered 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.
Alist 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
14
. 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 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 to deal with them
correctly
15
,and by exporting them properly (seeChapter12[Exporting],page140). 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.
10
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.
11
You can filter out any of them by configuring org-plain-list-ordered-item-terminator.
12
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.
13
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].
14
See also org-list-empty-line-terminates-plain-lists.
15
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)
59
Chapter 2: Document structure
14
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 their 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 TABs 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
(seeSection2.5[Structure editing], page 9). 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
16
. 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 (seeSection5.6[Checkboxes],page56).
S-up
S-down
Jump to the previous/next item in the current list
17
,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
18
(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,
16
If you do not want the item to be split, customize the variable org-M-RET-may-split-line.
17
If you want to cycle around items that way, you may customize org-list-use-circular-motion.
18
See org-list-use-circular-motion for a cyclic behavior.
48
Chapter 2: Document structure
15
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 (seeSection5.6[Checkboxes],page56) 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, dependingonorg-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). SeeSection2.5[Structureediting],page9, for a detailed explanation.
C-c C-*
Turn the whole plain list into a subtree of the current heading. Checkboxes (see
Section 5.6 [Checkboxes], page 56)willbecomeTODO(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: numeri-
cally, alphabetically, by time, by checked status for check lists, or by a custom
function.
2.8 Drawers
Sometimes you want to keep information associated with an entry, but you normally don’t
want to see it. For this, Org mode has drawers. They can contain anything but a headline
and another drawer. Drawers look like this:
** This is a headline
Still outside the drawer
:DRAWERNAME:
This is inside the drawer.
:END:
After the drawer.
You can interactively insert drawers at point by calling org-insert-drawer, which is
bound to C-c C-x d. With an active region, this command will put the region inside the
drawer. With a prefix argument, this command calls org-insert-property-drawer and
52
Chapter 2: Document structure
16
add a property drawer right below the current headline. Completion over drawer keywords
is also possible using M-TAB.
Visibility cycling (seeSection2.3[Visibility cycling],page6) on the headline will hide
and show the entry, but keep the drawer collapsed to a single line. In order to look inside
the drawer, you need to move the cursor to the drawer line and press TAB there. Org mode
uses the PROPERTIES drawer for storing properties (seeChapter7[Propertiesandcolumns],
page 64),andyoucanalsoarrangeforstatechangenotes(see Section5.3.2 [Tracking TODO
state changes], page 52)andclocktimes(see Section 8.4 [Clocking work time], page 80)to
be stored in a drawer LOGBOOK. If you want to store a quick note in the LOGBOOK drawer,
in a similar way to state changes, use
C-c C-z
Add a time-stamped note to the LOGBOOK drawer.
You can select the name of the drawers which should be exported with org-export-
with-drawers. In that case, drawer contents will appear in export output. Property
drawers are not affected by this variable: configure org-export-with-properties instead.
2.9 Blocks
Org mode uses begin...end blocks for various purposes from including source code examples
(seeSection11.3[Literalexamples],page132) to capturing time logging information (see
Section 8.4 [Clocking work time], page 80). These e blocks canbefoldedandunfoldedby
pressing TAB in the begin line. You can also get all blocks folded at startup by configuring
the option org-hide-block-startup or on a per-file basis by using
#+STARTUP: hideblocks
#+STARTUP: nohideblocks
2.10 Footnotes
Org mode supports the creation of footnotes. In contrast to the footnote.el package, Org
mode’s footnotes are designedfor work on alarger document,not only for one-off documents
like emails.
Afootnote is startedby a footnote marker in square brackets in column 0, no indentation
allowed. It ends at the next footnote definition, headline, or after two consecutive empty
lines. The footnote reference is simply the marker in square brackets, inside text. For
example:
The Org homepage[fn:1] now looks a lot better than it used to.
...
[fn:1] The link is: http://orgmode.org
Org mode extends the number-based syntax to named footnotes and optional inline def-
inition. Using plain numbers as markers (as footnote.el does) is supported for backward
compatibility, but not encouraged because of possible conflicts with LAT
E
Xsnippets (see
Section 11.7 [Embedded L
A
T
E
X], page 136). Herearethevalidreferences:
[1]
Aplain numeric footnote marker. Compatible with footnote.el, but not rec-
ommended because something like ‘[1]’ could easily be part of a code snippet.
[fn:name]
Anamedfootnote reference, where name is a uniquelabelword, or, for simplicity
of automatic creation, a number.
62
Chapter 2: Document structure
17
[fn:: This is the inline definition of this footnote]
AL
A
T
E
X-like anonymous footnote where the definition is given directly at the
reference point.
[fn:name: a definition]
Aninline definition of a footnote, whichalso specifies a name for the note. Since
Org allows multiple references to the same note, you can then use [fn:name]
to create additional references.
Footnote labels can be created automatically, or you can create names yourself. This
is handled by the variable org-footnote-auto-label and its corresponding #+STARTUP
keywords. See the docstring of that variable for details.
The following command handles footnotes:
C-c C-x f The footnote action command.
When the cursor is on a footnote reference, jump to the definition. When it is
at a definition, jump to the (first) reference.
Otherwise, create a new footnote. Depending on the option org-footnote-
define-inline
19
, the definition will be placed right into the text as part
of the reference, or separately into the location determined by the option
org-footnote-section.
When this command is called with a prefix argument, a menu of additional
options is offered:
s
Sort the footnote definitions by reference sequence. During editing,
Org makes no effort to sort footnote definitions into a particular
sequence. If you want them sorted, use this command, which will
also move entries according to org-footnote-section. Automatic
sorting after each insertion/deletion can be configured using the
option org-footnote-auto-adjust.
r
Renumber the simple fn:N footnotes. Automatic renumbering
after each insertion/deletion can be configured using the option
org-footnote-auto-adjust.
S
Short for first r, then s action.
n
Normalize the footnotes by collecting all definitions (including
inline definitions) into a special section, and then numbering them
in sequence. The references will then also be numbers. This is
meant to be the final step before finishing a document (e.g., sending
off an email).
d
Delete the footnote at point, and all definitions of and references
to it.
Depending on the variable org-footnote-auto-adjust
20
, renumbering and
sorting footnotes can be automatic after each insertion or deletion.
C-c C-c
If the cursor is on a footnote reference, jump to the definition. If it is a the
definition, jump back to the reference. When called at a footnote location with
aprefix argument, offer the same menu as C-c C-x f.
19
The corresponding in-buffer setting is: #+STARTUP: fninline or #+STARTUP: nofninline
20
the corresponding in-buffer options are fnadjust and nofnadjust.
39
Chapter 2: Document structure
18
C-c C-o or mouse-1/2
Footnote labels are also links to the corresponding definition/reference, and you
can use the usual commands to follow these links.
C-c '
C-c '
Edit the footnote definitioncorrespondingto the reference at point ina seperate
window. This may be useful if editing footnotes in a narrowed buffer. The
window can be closed by pressing C-c '.
2.11 The Orgstruct minor mode
If you like the intuitive way the Org mode structure editing and list formatting works,
you might want to use these commands in other modes like Text mode or Mail mode as
well. The minor mode orgstruct-mode makes this possible. Toggle the mode with M-x
orgstruct-mode RET, or turn it on by default, for example in Message mode, with one of:
(add-hook 'message-mode-hook 'turn-on-orgstruct)
(add-hook 'message-mode-hook 'turn-on-orgstruct++)
When this mode is active and the cursor is on a line that looks to Org like a headline
or the first line of a list item, most structure editing commands will work, even if the same
keys normally have different functionality in the major mode you are using. If the cursor is
not in one of those special lines, Orgstruct mode lurks silently in the shadows.
When you use orgstruct++-mode, Org will also export indentation and autofill settings
into that mode, and detect item context after the first line of an item.
You can also use Org structure editing to fold and unfold headlines in any file, provided
you defined orgstruct-heading-prefix-regexp: the regular expression must match the
local prefix to use before Org’s headlines. For example, if you set this variable to ";;
" in Emacs Lisp files, you will be able to fold and unfold headlines in Emacs Lisp com-
mented lines. Some commands like org-demote are disabled when the prefix is set, but
folding/unfolding will work correctly.
2.12 Org syntax
Areference document providing a formal description of Org’s syntax is available asadraft
on Worg,writtenandmaintainedbyNicolasGoaziou.ItdefinesOrg’scoreinternalconcepts
such as headlines, sections, affiliated keywords, (greater) elements and objects.
Each part of an Org file falls into one of the categories above.
To explore the abstract structure of an Org buffer, run this in a buffer:
M-: (org-element-parse-buffer) RET
It will output a list containing the buffer’s content represented as an abstract structure.
The export engine relies on the information stored in this list. Most interactive commands
(e.g., for structure editing) also rely on the syntactic meaning of the surrounding context.
48
Chapter 3: Tables
19
3 Tables
Org comes witha fast and intuitive table editor. Spreadsheet-like calculations are supported
using the Emacs calc package (seeGnuEmacsCalculatorManual).
3.1 The built-in table editor
Org makes it easy to format tables in plain ASCII. Any line with ‘|’ as the first non-
whitespace character is considered part of a table. ‘|’ is also the column separator
1
. A
table might look like this:
| Name | Phone | Age |
|-------+-------+-----|
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
Atable is re-aligned automatically each time you press TAB or RET or C-c C-c inside the
table. TAB also moves to the next field (RET to the next row) and creates new table rows
at the end of the table or before horizontal lines. The indentation of the table is set by the
first line. Any line starting with ‘|-’ is considered as a horizontal separator line and will be
expanded on the next re-align to span the whole table width. So, to create the above table,
you would only type
|Name|Phone|Age|
|-
and then press TAB to align the table and start filling in fields. Even faster would be to
type |Name|Phone|Age followed by C-c RET.
When typing text into a field, Org treats DEL, Backspace, and all character keys in a
special way, so that inserting and deleting avoids shifting other fields. Also, when typing
immediately after the cursor was moved into a new field with TAB, S-TAB or RET, the field
is automatically made blank. If this behavior is too unpredictable for you, configure the
options org-enable-table-editor and org-table-auto-blank-field.
Creation and conversion
C-c |
org-table-create-or-convert-from-region
Convert the active region to a table. If every line contains at least one TAB
character, the function assumes that the material is tab separated. If every line
contains a comma, comma-separatedvalues (CSV) are assumed. If not,lines are
split at whitespace into fields. You can use a prefix argument to force a specific
separator: C-u forces CSV, C-u C-u forces TAB, C-u C-u C-u will prompt for a
regular expression to match the separator, and a numeric argument N indicates
that at least N consecutive spaces, or alternatively a TAB will be the separator.
If there is no active region, this command creates an empty Org table. But it
is easier just to start typing, like |Name|Phone|Age RET |- TAB.
Re-aligning and field motion
C-c C-c
org-table-align
Re-align the table and don’t move to another field.
1
To insert a vertical bar into a table field, use \vert or, inside a word abc\vert{}def.
Documents you may be interested
Documents you may be interested
