@setfilename ../../info/org
@settitle The Org Manual
-@set VERSION 7.7
-@set DATE July 2011
+@set VERSION 7.8.11
+@set DATE May 2012
@c Use proper quote and backtick for code sections in PDF output
@c Cf. Texinfo manual 14.2
@c orgkey{key} A key item
@c orgcmd{key,cmd} Key with command name
-@c xorgcmd{key,command} Key with command name as @itemx
+@c xorgcmd{key,cmd} Key with command name as @itemx
@c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
@c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
@c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
@copying
This manual is for Org version @value{VERSION}.
-Copyright @copyright{} 2004-2011 Free Software Foundation, Inc.
+Copyright @copyright{} 2004-2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs editing modes
@direntry
* Org Mode: (org). Outline-based notes management and organizer
@end direntry
@subtitle Release @value{VERSION}
@author by Carsten Dominik
-with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, and Thomas Dye
+with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K.
@c The following two commands start the copyright page.
@page
* Column formulas:: Formulas valid for an entire column
* Editing and debugging formulas:: Fixing formulas
* Updating the table:: Recomputing all dependent fields
-* Advanced features:: Field names, parameters and automatic recalc
+* Advanced features:: Field and column names, parameters and automatic recalc
Hyperlinks
Properties and columns
* Property syntax:: How properties are spelled out
-* Special properties:: Access to other Org-mode features
+* Special properties:: Access to other Org mode features
* Property searches:: Matching property values
* Property inheritance:: Passing values down the tree
* Column view:: Tabular viewing and editing
Creating timestamps
-* The date/time prompt:: How Org-mode helps you entering date and time
+* The date/time prompt:: How Org mode helps you entering date and time
* Custom time format:: Making dates look different
Deadlines and scheduling
* Include files:: Include additional files into a document
* Index entries:: Making an index
* Macro replacement:: Use macros to create complex output
-* Embedded LaTeX:: LaTeX can be freely used inside Org documents
+* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
Structural markup elements
* Special symbols:: Greek letters and other symbols
* Subscripts and superscripts:: Simple syntax for raising/lowering text
-* LaTeX fragments:: Complex formulas made easy
-* Previewing LaTeX fragments:: What will this snippet look like?
+* @LaTeX{} fragments:: Complex formulas made easy
+* Previewing @LaTeX{} fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
Exporting
* The export dispatcher:: How to access exporter commands
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* HTML export:: Exporting to HTML
-* LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF
+* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
* DocBook export:: Exporting to DocBook
-* OpenDocumentText export:: Exporting to OpenDocumentText
+* OpenDocument Text export:: Exporting to OpenDocument Text
* TaskJuggler export:: Exporting to TaskJuggler
* Freemind export:: Exporting to Freemind mind maps
* XOXO export:: Exporting to XOXO
* HTML Export commands:: How to invoke HTML export
* HTML preamble and postamble:: How to insert a preamble and a postamble
-* Quoting HTML tags:: Using direct HTML in Org-mode
+* Quoting HTML tags:: Using direct HTML in Org mode
* Links in HTML export:: How links will be interpreted and formatted
* Tables in HTML export:: How to modify the formatting of tables
* Images in HTML export:: How to insert figures into HTML output
@LaTeX{} and PDF export
-* LaTeX/PDF export commands:: Which key invokes which commands
+* @LaTeX{}/PDF export commands::
* Header and sectioning:: Setting up the export file structure
-* Quoting LaTeX code:: Incorporating literal @LaTeX{} code
-* Tables in LaTeX export:: Options for exporting tables to @LaTeX{}
-* Images in LaTeX export:: How to insert figures into @LaTeX{} output
+* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code
+* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{}
+* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output
* Beamer class export:: Turning the file into a presentation
DocBook export
* Images in DocBook export:: How to insert figures into DocBook output
* Special characters:: How to handle special characters
-OpenDocument export
+OpenDocument Text export
-* OpenDocumentText export commands:: How to invoke OpenDocumentText export
-* Applying Custom Styles:: How to apply custom styles to the output
-* Converting to Other formats:: How to convert to formats like doc, docx etc
-* Links in OpenDocumentText export:: How links will be interpreted and formatted
-* Tables in OpenDocumentText export:: How Tables are handled
-* Images in OpenDocumentText export:: How to insert figures
-* Additional Documentation:: How to handle special characters
+* Pre-requisites for ODT export:: What packages ODT exporter relies on
+* ODT export commands:: How to invoke ODT export
+* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files
+* Applying custom styles:: How to apply custom styles to the output
+* Links in ODT export:: How links will be interpreted and formatted
+* Tables in ODT export:: How Tables are exported
+* Images in ODT export:: How to insert images
+* Math formatting in ODT export:: How @LaTeX{} fragments are formatted
+* Labels and captions in ODT export:: How captions are rendered
+* Literal examples in ODT export:: How source and example blocks are formatted
+* Advanced topics in ODT export:: Read this if you are a power user
+
+Math formatting in ODT export
+
+* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments
+* Working with MathML or OpenDocument formula files:: How to embed equations in native format
+
+Advanced topics in ODT export
+
+* Configuring a document converter:: How to register a document converter
+* Working with OpenDocument style files:: Explore the internals
+* Creating one-off styles:: How to produce custom highlighting etc
+* Customizing tables in ODT export:: How to define and use Table templates
+* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
Publishing
* Editing source code:: Language major-mode editing
* Exporting code blocks:: Export contents and/or results
* Extracting source code:: Create pure source code files
-* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer
+* Evaluating code blocks:: Place results of evaluation in the Org mode buffer
* Library of Babel:: Use and contribute to a library of useful code blocks
* Languages:: List of supported code block languages
* Header arguments:: Configure code block functionality
* Results of evaluation:: How evaluation results are handled
-* Noweb reference syntax:: Literate programming in Org-mode
+* Noweb reference syntax:: Literate programming in Org mode
* Key bindings and useful functions:: Work quickly with code blocks
* Batch execution:: Call functions from the command line
* System-wide header arguments:: Set global default values
* Language-specific header arguments:: Set default values by language
* Buffer-wide header arguments:: Set default values for a specific buffer
-* Header arguments in Org-mode properties:: Set default values for a buffer or heading
+* Header arguments in Org mode properties:: Set default values for a buffer or heading
* Code block specific header arguments:: The most common way to set values
* Header arguments in function calls:: The most specific level
* session:: Preserve the state of code evaluation
* noweb:: Toggle expansion of noweb references
* noweb-ref:: Specify block's noweb reference resolution target
+* noweb-sep:: String used to separate noweb references
* cache:: Avoid re-evaluating unchanged code blocks
* sep:: Delimiter for writing tabular results outside Org
* hlines:: Handle horizontal lines in tables
Tables and lists in arbitrary syntax
* Radio tables:: Sending and receiving radio tables
-* A LaTeX example:: Step by step, almost a tutorial
+* A @LaTeX{} example:: Step by step, almost a tutorial
* Translator functions:: Copy and modify
* Radio lists:: Doing the same for lists
Then add the following line to @file{.emacs}. It is needed so that
Emacs can autoload functions that are located in files not immediately loaded
-when Org-mode starts.
+when Org mode starts.
@lisp
(require 'org-install)
@end lisp
(global-set-key "\C-cb" 'org-iswitchb)
@end lisp
-@cindex Org-mode, turning on
+@cindex Org mode, turning on
With this setup, all files with extension @samp{.org} will be put
-into Org-mode. As an alternative, make the first line of a file look
+into Org mode. As an alternative, make the first line of a file look
like this:
@example
@end example
@vindex org-insert-mode-line-in-empty-file
-@noindent which will select Org-mode for this buffer no matter what
+@noindent which will select Org mode for this buffer no matter what
the file's name is. See also the variable
@code{org-insert-mode-line-in-empty-file}.
that you only need to add your description. If you re not sending the Email
from within Emacs, please copy and paste the content into your Email program.
+Sometimes you might face a problem due to an error in your Emacs or Org mode
+setup. Before reporting a bug, it is very helpful to start Emacs with minimal
+customizations and reproduce the problem. Doing so often helps you determine
+if the problem is with your customization or with Org mode itself. You can
+start a typical minimal session with a command like the example below.
+
+@example
+$ emacs -Q -l /path/to/minimal-org.el
+@end example
+
+However if you are using Org mode as distributed with Emacs, a minimal setup
+is not necessary. In that case it is sufficient to start Emacs as @code{emacs
+-Q}. The @code{minimal-org.el} setup file can have contents as shown below.
+
+@example
+;;; Minimal setup to load latest `org-mode'
+
+;; activate debugging
+(setq debug-on-error t
+ debug-on-signal nil
+ debug-on-quit nil)
+
+;; add latest org-mode to load path
+(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
+(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp"))
+
+;; activate org
+(require 'org-install)
+@end example
+
If an error occurs, a backtrace can be very useful (see below on how to
create one). Often a small example file helps, along with clear information
about:
@enumerate
@item
-Reload uncompiled versions of all Org-mode Lisp files. The backtrace
+Reload uncompiled versions of all Org mode Lisp files. The backtrace
contains much more information if it is produced with uncompiled code.
To do this, use
@example
and the hierarchy above. Useful for working near a location that has been
exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
(@pxref{Agenda commands}). With a prefix argument show, on each
-level, all sibling headings. With double prefix arg, also show the entire
-subtree of the parent.
+level, all sibling headings. With a double prefix argument, also show the
+entire subtree of the parent.
@orgcmd{C-c C-k,show-branches}
Expose all the headings of the subtree, CONTENT view for just one subtree.
@orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
(in the sequence the keywords have been defined in the setup) or by the value
of a property. Reverse sorting is possible as well. You can also supply
your own function to extract the sorting key. With a @kbd{C-u} prefix,
-sorting will be case-sensitive. With two @kbd{C-u C-u} prefixes, duplicate
-entries will also be removed.
+sorting will be case-sensitive.
@orgcmd{C-x n s,org-narrow-to-subtree}
Narrow buffer to current subtree.
@orgcmd{C-x n b,org-narrow-to-block}
@vindex org-show-following-heading
@vindex org-show-siblings
@vindex org-show-entry-below
-An important feature of Org-mode is the ability to construct @emph{sparse
+An important feature of Org mode is the ability to construct @emph{sparse
trees} for selected information in an outline tree, so that the entire
document is folded as much as possible, but the selected information is made
visible along with the headline structure above it@footnote{See also the
control on how much context is shown around each match.}. Just try it out
and you will see immediately how it works.
-Org-mode contains several commands creating such trees, all these
+Org mode contains several commands creating such trees, all these
commands can be accessed through a dispatcher:
@table @asis
list. An item ends before the next line that is less or equally indented
than its bullet/number.
-@vindex org-list-ending-method
-@vindex org-list-end-regexp
@vindex org-empty-line-terminates-plain-lists
-Two methods@footnote{To disable either of them, configure
-@code{org-list-ending-method}.} are provided to terminate lists. 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
+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@footnote{See also @code{org-empty-line-terminates-plain-lists}.}. In
-that case, all items are closed. For finer control, you can end lists with
-any pattern set in @code{org-list-end-regexp}. Here is an example:
+that case, all items are closed. Here is an example:
@example
@group
@table @asis
@orgcmd{@key{TAB},org-cycle}
+@cindex cycling, in plain lists
@vindex org-cycle-include-plain-lists
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
@code{org-cycle-include-plain-lists}. If this variable is set to
@code{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.
+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 @key{TAB} demotes the item to become a child of the previous
+one. Subsequent @key{TAB}s move the item to meaningful levels in the list
+and eventually get it back to its initial position.
@orgcmd{M-@key{RET},org-insert-heading}
@vindex org-M-RET-may-split-line
@vindex org-list-automatic-rules
variable @code{org-M-RET-may-split-line}.}. If this command is executed
@emph{before item's body}, the new item is created @emph{before} the current
one.
+@end table
+
+@table @kbd
@kindex M-S-@key{RET}
-@item M-S-@key{RET}
+@item M-S-RET
Insert a new item with a checkbox (@pxref{Checkboxes}).
-@orgcmd{@key{TAB},org-cycle}
-In a new item with no text yet, the first @key{TAB} demotes the item to
-become a child of the previous one. Subsequent @key{TAB}s move the item to
-meaningful levels in the list and eventually get it back to its initial
-position.
@kindex S-@key{down}
-@item S-@key{up}
-@itemx S-@key{down}
+@item S-up
+@itemx S-down
@cindex shift-selection-mode
@vindex org-support-shift-select
@vindex org-list-use-circular-motion
similar effect.
@kindex M-@key{up}
@kindex M-@key{down}
-@item M-@key{up}
-@itemx M-@key{down}
+@item M-up
+@itemx M-down
Move the item including subitems up/down@footnote{See
@code{org-liste-use-circular-motion} for a cyclic behavior.} (swap with
previous/next item of same indentation). If the list is ordered, renumbering
is automatic.
@kindex M-@key{left}
@kindex M-@key{right}
-@item M-@key{left}
-@itemx M-@key{right}
+@item M-left
+@itemx M-right
Decrease/increase the indentation of an item, leaving children alone.
@kindex M-S-@key{left}
@kindex M-S-@key{right}
-@item M-S-@key{left}
-@itemx M-S-@key{right}
+@item M-S-left
+@itemx 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
(resp. checked).
@kindex S-@key{left}
@kindex S-@key{right}
-@item S-@key{left}/@key{right}
+@item S-left/right
@vindex org-support-shift-select
This command also cycles bullet styles when the cursor in on the bullet or
anywhere in an item line, details depending on
@vindex org-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 @emph{drawers}.
+normally don't want to see it. For this, Org mode has @emph{drawers}.
Drawers need to be configured with the variable
@code{org-drawers}@footnote{You can define drawers on a per-file basis
with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers
Visibility cycling (@pxref{Visibility cycling}) 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 @key{TAB} there. Org-mode uses the @code{PROPERTIES} drawer for
+press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
storing properties (@pxref{Properties and Columns}), and you can also arrange
for state change notes (@pxref{Tracking TODO state changes}) and clock times
(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
@vindex org-hide-block-startup
@cindex blocks, folding
-Org-mode uses begin...end blocks for various purposes from including source
+Org mode uses begin...end blocks for various purposes from including source
code examples (@pxref{Literal examples}) to capturing time logging
information (@pxref{Clocking work time}). These blocks can be folded and
unfolded by pressing TAB in the begin line. You can also get all blocks
@section Footnotes
@cindex footnotes
-Org-mode supports the creation of footnotes. In contrast to the
-@file{footnote.el} package, Org-mode's footnotes are designed for work on a
+Org mode supports the creation of footnotes. In contrast to the
+@file{footnote.el} package, Org mode's footnotes are designed for work on a
larger document, not only for one-off documents like emails. The basic
syntax is similar to the one used by @file{footnote.el}, i.e.@: a footnote is
defined in a paragraph that is started by a footnote marker in square
[fn:1] The link is: http://orgmode.org
@end example
-Org-mode extends the number-based syntax to @emph{named} footnotes and
+Org mode extends the number-based syntax to @emph{named} footnotes and
optional inline definition. Using plain numbers as markers (as
@file{footnote.el} does) is supported for backward compatibility, but not
encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded
-LaTeX}). Here are the valid references:
+@LaTeX{}}). Here are the valid references:
@table @code
@item [1]
@cindex Orgstruct mode
@cindex minor mode for structure editing
-If you like the intuitive way the Org-mode structure editing and list
+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 @code{orgstruct-mode} makes
this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or
Org comes with a fast and intuitive table editor. Spreadsheet-like
calculations are supported using the Emacs @file{calc} package
-@ifinfo
-(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}).
-@end ifinfo
-@ifnotinfo
-(see the Emacs Calculator manual for more information about the Emacs
-calculator).
-@end ifnotinfo
+(@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
@menu
* Built-in table editor:: Simple tables
order to specify column groups, you can use a special row where the
first field contains only @samp{/}. The further fields can either
contain @samp{<} to indicate that this column should start a group,
-@samp{>} to indicate the end of a column, or @samp{<>} to make a column
+@samp{>} to indicate the end of a column, or @samp{<>} (no space between @samp{<}
+and @samp{>}) to make a column
a group of its own. Boundaries between column groups will upon export be
marked with vertical lines. Here is an example:
* Column formulas:: Formulas valid for an entire column
* Editing and debugging formulas:: Fixing formulas
* Updating the table:: Recomputing all dependent fields
-* Advanced features:: Field names, parameters and automatic recalc
+* Advanced features:: Field and column names, parameters and automatic recalc
@end menu
@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
non-standard convention that @samp{/} has lower precedence than
@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before
evaluation by @code{calc-eval} (@pxref{Calling Calc from
-Your Programs,calc-eval,Calling Calc from Your Lisp Programs,Calc,GNU
+Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc, GNU
Emacs Calc Manual}),
-@c FIXME: The link to the Calc manual in HTML does not work.
variable substitution takes place according to the rules described above.
@cindex vectors, in table calculations
The range vectors can be directly fed into the Calc vector functions
Input duration values must be of the form @code{[HH:MM[:SS]}, where seconds
are optional. With the @code{T} flag, computed durations will be displayed
-as @code{[HH:MM:SS} (see the first formula above). With the @code{t} flag,
+as @code{HH:MM:SS} (see the first formula above). With the @code{t} flag,
computed durations will be displayed according to the value of the variable
@code{org-table-duration-custom-format}, which defaults to @code{'hours} and
will display the result as a fraction of hours (see the second formula in the
@node Advanced features, , Updating the table, The spreadsheet
@subsection Advanced features
-If you want the recalculation of fields to happen automatically, or if
-you want to be able to assign @i{names} to fields and columns, you need
-to reserve the first column of the table for special marking characters.
+If you want the recalculation of fields to happen automatically, or if you
+want to be able to assign @i{names}@footnote{Such names must start by an
+alphabetic character and use only alphanumeric/underscore characters.} to
+fields and columns, you need to reserve the first column of the table for
+special marking characters.
@table @kbd
@orgcmd{C-#,org-table-rotate-recalc-marks}
flat mapping rather than a @code{3d} slope.
@item timefmt
-Specify format of Org-mode timestamps as they will be parsed by Gnuplot.
+Specify format of Org mode timestamps as they will be parsed by Gnuplot.
Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
@item script
./papers/last.pdf @r{same as above}
file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine}
/myself@@some.where:papers/last.pdf @r{same as above}
-file:sometextfile::NNN @r{file with line number to jump to}
+file:sometextfile::NNN @r{file, jump to line number}
file:projects.org @r{another Org file}
-file:projects.org::some words @r{text search in Org file}
+file:projects.org::some words @r{text search in Org file}@footnote{
+The actual behavior of the search will depend on the value of
+the variable @code{org-link-search-must-match-exact-headline}. If its value
+is nil, then a fuzzy text search will be done. If it is t, then only the
+exact headline will be matched. If the value is @code{'query-to-create},
+then an exact headline will be searched; if it is not found, then the user
+will be queried to create it.}
file:projects.org::*task title @r{heading search in Org file}
-docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN}
+file+sys:/path/to/file @r{open via OS, like double-click}
+file+emacs:/path/to/file @r{force opening by Emacs}
+docview:papers/last.pdf::NNN @r{open in doc-view mode at page}
id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
news:comp.emacs @r{Usenet link}
mailto:adent@@galaxy.net @r{Mail link}
gnus:group#id @r{Gnus article link}
bbdb:R.*Stallman @r{BBDB link (with regexp)}
irc:/irc.com/#emacs/bob @r{IRC link}
-info:org#External%20links @r{Info node link (with encoded space)}
+info:org#External links @r{Info node link}
shell:ls *.org @r{A shell command}
elisp:org-agenda @r{Interactive Elisp command}
elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
buffer (see below). What kind of link will be created depends on the current
buffer:
-@b{Org-mode buffers}@*
+@b{Org mode buffers}@*
For Org files, if there is a @samp{<<target>>} at the cursor, the link points
to the target. Otherwise it points to the current headline, which will also
be the description@footnote{If the headline contains a timestamp, it will be
@cindex following links
@orgcmd{C-c C-o,org-open-at-point}
@vindex org-file-apps
+@vindex org-link-frame-setup
Open link at point. This will launch a web browser for URLs (using
@command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
the corresponding links, and execute the command in a shell link. When the
visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
opening in Emacs, use a @kbd{C-u C-u} prefix.@*
If the cursor is on a headline, but not on a link, offer all links in the
-headline and entry text.
+headline and entry text. If you want to setup the frame configuration for
+following links, customize @code{org-link-frame-setup}.
+
@orgkey @key{RET}
@vindex org-return-follows-link
When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
@item /regexp/
Do a regular expression search for @code{regexp}. This uses the Emacs
command @code{occur} to list all matches in a separate window. If the
-target file is in Org-mode, @code{org-occur} is used to create a
+target file is in Org mode, @code{org-occur} is used to create a
sparse tree with the matches.
@c If the target file is a directory,
@c @code{grep} will be used to search all files in the directory.
@chapter TODO items
@cindex TODO items
-Org-mode does not maintain TODO lists as separate documents@footnote{Of
+Org mode does not maintain TODO lists as separate documents@footnote{Of
course, you can make a document that contains only long lists of TODO items,
but this is not required.}. Instead, TODO items are an integral part of the
notes file, because TODO items usually come up while taking notes! With Org
item emerged is always present.
Of course, this technique for managing TODO items scatters them
-throughout your notes file. Org-mode compensates for this by providing
+throughout your notes file. Org mode compensates for this by providing
methods to give you an overview of all the things that you have to do.
@menu
@vindex org-todo-keywords
By default, marked TODO entries have one of only two states: TODO and
-DONE. Org-mode allows you to classify TODO items in more complex ways
+DONE. Org mode allows you to classify TODO items in more complex ways
with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
special setup, the TODO keyword system can work differently in different
files.
You can use TODO keywords to indicate different @emph{sequential} states
in the process of working on an item, for example@footnote{Changing
-this variable only becomes effective after restarting Org-mode in a
+this variable only becomes effective after restarting Org mode in a
buffer.}:
@lisp
In this case, different keywords do not indicate a sequence, but rather
different types. So the normal work flow would be to assign a task to a
-person, and later to mark it DONE. Org-mode supports this style by adapting
+person, and later to mark it DONE. Org mode supports this style by adapting
the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
@kbd{t} command in the timeline and agenda buffers.}. When used several
times in succession, it will still cycle through all names, in order to first
(sequence "|" "CANCELED")))
@end lisp
-The keywords should all be different, this helps Org-mode to keep track
+The keywords should all be different, this helps Org mode to keep track
of which subsequence should be used for a given entry. In this setup,
@kbd{C-c C-t} only operates within a subsequence, so it switches from
@code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
if no bar is there) must always mean that the item is DONE (although you
may use a different word). After changing one of these lines, use
@kbd{C-c C-c} with the cursor still in the line to make the changes
-known to Org-mode@footnote{Org-mode parses these lines only when
-Org-mode is activated after visiting a file. @kbd{C-c C-c} with the
-cursor in a line starting with @samp{#+} is simply restarting Org-mode
+known to Org mode@footnote{Org mode parses these lines only when
+Org mode is activated after visiting a file. @kbd{C-c C-c} with the
+cursor in a line starting with @samp{#+} is simply restarting Org mode
for the current buffer.}.
@node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions
@vindex org-todo @r{(face)}
@vindex org-done @r{(face)}
@vindex org-todo-keyword-faces
-Org-mode highlights TODO keywords with special faces: @code{org-todo}
+Org mode highlights TODO keywords with special faces: @code{org-todo}
for keywords indicating that an item still has to be acted upon, and
@code{org-done} for keywords indicating that an item is finished. If
you are using more than 2 different states, you might want to use
@cindex progress logging
@cindex logging, of progress
-Org-mode can automatically record a timestamp and possibly a note when
+Org mode can automatically record a timestamp and possibly a note when
you mark a TODO item as DONE, or even each time you change the state of
a TODO item. This system is highly configurable, settings can be on a
per-keyword basis and can be localized to a file or even a subtree. For
also overrule the setting of this variable for a subtree by setting a
@code{LOG_INTO_DRAWER} property.
-Since it is normally too much to record a note for every state, Org-mode
+Since it is normally too much to record a note for every state, Org mode
expects configuration on a per-keyword basis for this. This is achieved by
-adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note)
-in parentheses after each keyword. For example, with the setting
+adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
+with timestamp) in parentheses after each keyword. For example, with the
+setting
@lisp
(setq org-todo-keywords
'((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
@end lisp
+To record a timestamp without a note for TODO keywords configured with
+@samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
+
@noindent
@vindex org-log-done
you not only define global TODO keywords and fast access keys, but also
request that a time is recorded when the entry is set to
-DONE@footnote{It is possible that Org-mode will record two timestamps
+DONE@footnote{It is possible that Org mode will record two timestamps
when you are using both @code{org-log-done} and state change logging.
However, it will never prompt for two notes---if you have configured
both, the state change recording note will take precedence and cancel
@section Priorities
@cindex priorities
-If you use Org-mode extensively, you may end up with enough TODO items that
+If you use Org mode extensively, you may end up with enough TODO items that
it starts to make sense to prioritize them. Prioritizing can be done by
placing a @emph{priority cookie} into the headline of a TODO item, like this
@noindent
@vindex org-priority-faces
-By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and
+By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
@samp{C}. @samp{A} is the highest priority. An entry without a cookie is
treated just like priority @samp{B}. Priorities make a difference only for
sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
-have no inherent meaning to Org-mode. The cookies can be highlighted with
+have no inherent meaning to Org mode. The cookies can be highlighted with
special faces by customizing the variable @code{org-priority-faces}.
Priorities can be attached to any outline node; they do not need to be TODO
@table @kbd
@orgcmd{C-c C-c,org-toggle-checkbox}
-Toggle checkbox status or (with prefix arg) checkbox presence at point. With
-double prefix argument, set it to @samp{[-]}, which is considered to be an
-intermediate state.
+Toggle checkbox status or (with prefix arg) checkbox presence at point.
+With a single prefix argument, add an empty checkbox or remove the current
+one@footnote{`C-u C-c C-c' on the @emph{first} item of a list with no checkbox
+will add checkboxes to the rest of the list.}. With a double prefix argument, set it to @samp{[-]}, which is
+considered to be an intermediate state.
@orgcmd{C-c C-x C-b,org-toggle-checkbox}
Toggle checkbox status or (with prefix arg) checkbox presence at point. With
double prefix argument, set it to @samp{[-]}, which is considered to be an
@cindex sparse tree, tag based
An excellent way to implement labels and contexts for cross-correlating
-information is to assign @i{tags} to headlines. Org-mode has extensive
+information is to assign @i{tags} to headlines. Org mode has extensive
support for tags.
@vindex org-tag-faces
@orgcmd{C-c C-q,org-set-tags-command}
@cindex completion, of tags
@vindex org-tags-column
-Enter new tags for the current headline. Org-mode will either offer
+Enter new tags for the current headline. Org mode will either offer
completion or a special single-key interface for setting tags, see
below. After pressing @key{RET}, the tags will be inserted and aligned
to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
#+STARTUP: noptag
@end example
-By default Org-mode uses the standard minibuffer completion facilities for
+By default Org mode uses the standard minibuffer completion facilities for
entering tags. However, it also implements another, quicker, tag selection
method called @emph{fast tag selection}. This allows you to select and
deselect tags with just a single key press. For this to work well you should
@chapter Properties and columns
@cindex properties
-Properties are a set of key-value pairs associated with an entry. There
-are two main applications for properties in Org-mode. First, properties
-are like tags, but with a value. Second, you can use properties to
-implement (very basic) database capabilities in an Org buffer. For
-an example of the first application, imagine maintaining a file where
+A property is a key-value pair associated with an entry. Properties can be
+set so they are associated with a single entry, with every entry in a tree,
+or with every entry in an Org mode file.
+
+There are two main applications for properties in Org mode. First,
+properties are like tags, but with a value. Imagine maintaining a file where
you document bugs and plan releases for a piece of software. Instead of
-using tags like @code{:release_1:}, @code{:release_2:}, one can use a
+using tags like @code{:release_1:}, @code{:release_2:}, you can use a
property, say @code{:Release:}, that in different subtrees has different
-values, such as @code{1.0} or @code{2.0}. For an example of the second
-application of properties, imagine keeping track of your music CDs,
-where properties could be things such as the album, artist, date of
-release, number of tracks, and so on.
+values, such as @code{1.0} or @code{2.0}. Second, you can use properties to
+implement (very basic) database capabilities in an Org buffer. Imagine
+keeping track of your music CDs, where properties could be things such as the
+album, artist, date of release, number of tracks, and so on.
Properties can be conveniently edited and viewed in column view
(@pxref{Column view}).
@menu
* Property syntax:: How properties are spelled out
-* Special properties:: Access to other Org-mode features
+* Special properties:: Access to other Org mode features
* Property searches:: Matching property values
* Property inheritance:: Passing values down the tree
* Column view:: Tabular viewing and editing
@cindex property syntax
@cindex drawer, for properties
-Properties are key-value pairs. They need to be inserted into a special
+Properties are key-value pairs. When they are associated with a single entry
+or with a tree they need to be inserted into a special
drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property
is specified on a single line, with the key (surrounded by colons)
first, and the value after it. Here is an example:
:END:
@end example
+Depending on the value of @code{org-use-property-inheritance}, a property set
+this way will either be associated with a single entry, or the sub-tree
+defined by the entry, see @ref{Property inheritance}.
+
You may define the allowed values for a particular property @samp{:Xyz:}
by setting a property @samp{:Xyz_ALL:}. This special property is
@emph{inherited}, so if you set it in a level 1 entry, it will apply to
#+PROPERTY: NDisks_ALL 1 2 3 4
@end example
+If you want to add to the value of an existing property, append a @code{+} to
+the property name. The following results in the property @code{var} having
+the value ``foo=1 bar=2''.
+@cindex property, +
+@example
+#+PROPERTY: var foo=1
+#+PROPERTY: var+ bar=2
+@end example
+
+It is also possible to add to the values of inherited properties. The
+following results in the @code{genres} property having the value ``Classic
+Baroque'' under the @code{Goldberg Variations} subtree.
+@cindex property, +
+@example
+* CD collection
+** Classic
+ :PROPERTIES:
+ :GENRES: Classic
+ :END:
+*** Goldberg Variations
+ :PROPERTIES:
+ :Title: Goldberg Variations
+ :Composer: J.S. Bach
+ :Artist: Glen Gould
+ :Publisher: Deutsche Grammophon
+ :NDisks: 1
+ :GENRES+: Baroque
+ :END:
+@end example
+Note that a property can only have one entry per Drawer.
+
@vindex org-global-properties
Property values set with the global variable
@code{org-global-properties} can be inherited by all entries in all
@section Special properties
@cindex properties, special
-Special properties provide an alternative access method to Org-mode features,
+Special properties provide an alternative access method to Org mode features,
like the TODO state or the priority of an entry, discussed in the previous
chapters. This interface exists so that you can include these states in a
column view (@pxref{Column view}), or to use them in queries. The following
@cindex inheritance, of properties
@vindex org-use-property-inheritance
-The outline structure of Org-mode documents lends itself to an
+The outline structure of Org mode documents lends itself to an
inheritance model of properties: if the parent in a tree has a certain
-property, the children can inherit this property. Org-mode does not
+property, the children can inherit this property. Org mode does not
turn this on by default, because it can slow down property searches
significantly and is often not needed. However, if you find inheritance
useful, you can turn it on by setting the variable
interpreted as an explicit undefine of the property, so that inheritance
search will stop at this value and return @code{nil}.
-Org-mode has a few properties for which inheritance is hard-coded, at
+Org mode has a few properties for which inheritance is hard-coded, at
least for the special applications for which they are used:
@cindex property, COLUMNS
A great way to view and edit properties in an outline tree is
@emph{column view}. In column view, each outline node is turned into a
table row. Columns in this table provide access to properties of the
-entries. Org-mode implements columns by overlaying a tabular structure
+entries. Org mode implements columns by overlaying a tabular structure
over the headline of each item. While the headlines have been turned
into a table row, you can still change the visibility of the outline
tree. For example, you get a compact table by switching to CONTENTS
To assist project planning, TODO items can be labeled with a date and/or
a time. The specially formatted string carrying the date and time
-information is called a @emph{timestamp} in Org-mode. This may be a
+information is called a @emph{timestamp} in Org mode. This may be a
little confusing because timestamp is often used as indicating when
-something was created or last changed. However, in Org-mode this term
+something was created or last changed. However, in Org mode this term
is used in a much wider sense.
@menu
@cindex scheduling
A timestamp is a specification of a date (possibly with a time or a range of
-times) in a special format, either @samp{<2003-09-16 Tue>} or
-@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue
-12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 date/time
-format. To use an alternative format, see @ref{Custom time format}.}. A
-timestamp can appear anywhere in the headline or body of an Org tree entry.
-Its presence causes entries to be shown on specific dates in the agenda
-(@pxref{Weekly/daily agenda}). We distinguish:
+times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this
+simplest form, the day name is optional when you type the date yourself.
+However, any dates inserted or modified by Org will add that day name, for
+reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16
+Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601
+date/time format. To use an alternative format, see @ref{Custom time
+format}.}. A timestamp can appear anywhere in the headline or body of an Org
+tree entry. Its presence causes entries to be shown on specific dates in the
+agenda (@pxref{Weekly/daily agenda}). We distinguish:
@table @var
@item Plain timestamp; Event; Appointment
@cindex timestamp
+@cindex appointment
A simple timestamp just assigns a date/time to an item. This is just
like writing down an appointment or event in a paper agenda. In the
timeline and agenda displays, the headline of an entry associated with a
@end example
@item Diary-style sexp entries
-For more complex date specifications, Org-mode supports using the special
+For more complex date specifications, Org mode supports using the special
sexp diary entries implemented in the Emacs calendar/diary
package@footnote{When working with the standard diary sexp functions, you
need to be very careful with the order of the arguments. That order depend
versions, @code{european-calendar-style}). For example, to specify a date
December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or
@code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
-the settings. This has been the source of much confusion. Org-mode users
+the settings. This has been the source of much confusion. Org mode users
can resort to special versions of these functions like @code{org-date} or
@code{org-anniversary}. These work just like the corresponding @code{diary-}
functions, but with stable ISO order of arguments (year, month, day) wherever
-applicable, independent of the value of @code{calendar-date-style}.}. For example
+applicable, independent of the value of @code{calendar-date-style}.}. For
+example with optional time
@example
-* The nerd meeting on every 2nd Thursday of the month
+* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
<%%(org-float t 4 2)>
@end example
@cindex creating timestamps
@cindex timestamps, creating
-For Org-mode to recognize timestamps, they need to be in the specific
+For Org mode to recognize timestamps, they need to be in the specific
format. All commands listed below produce timestamps in the correct
format.
contains date and time. The default time can be rounded to multiples of 5
minutes, see the option @code{org-time-stamp-rounding-minutes}.
@c
+@orgkey{C-c C-c}
+Normalize timestamp, insert/fix day name if missing or wrong.
+@c
@orgcmd{C-c <,org-date-from-calendar}
Insert a timestamp corresponding to the cursor date in the Calendar.
@c
@menu
-* The date/time prompt:: How Org-mode helps you entering date and time
+* The date/time prompt:: How Org mode helps you entering date and time
* Custom time format:: Making dates look different
@end menu
@cindex time, reading in minibuffer
@vindex org-read-date-prefer-future
-When Org-mode prompts for a date/time, the default is shown in default
+When Org mode prompts for a date/time, the default is shown in default
date/time format, and the prompt therefore seems to ask for a specific
format. But it will in fact accept any string containing some date and/or
time information, and it is really smart about interpreting your input. You
can, for example, use @kbd{C-y} to paste a (possibly multi-line) string
-copied from an email message. Org-mode will find whatever information is in
+copied from an email message. Org mode will find whatever information is in
there and derive anything you have not specified from the @emph{default date
and time}. The default is usually the current date and time, but when
modifying an existing timestamp, or when entering the second stamp of a
range, it is taken from the stamp in the buffer. When filling in
-information, Org-mode assumes that most of the time you will want to enter a
+information, Org mode assumes that most of the time you will want to enter a
date in the future: if you omit the month/year and the given day/month is
@i{before} today, it will assume that you mean a future date@footnote{See the
variable @code{org-read-date-prefer-future}. You may set that variable to
time prompt will show this with @samp{(=>F).}
For example, let's assume that today is @b{June 13, 2006}. Here is how
-various inputs will be interpreted, the items filled in by Org-mode are
+various inputs will be interpreted, the items filled in by Org mode are
in @b{bold}.
@example
@vindex org-display-custom-times
@vindex org-time-stamp-custom-formats
-Org-mode uses the standard ISO notation for dates and times as it is
+Org mode uses the standard ISO notation for dates and times as it is
defined in ISO 8601. If you cannot get used to this and require another
representation of date and time to keep you happy, you can get it by
customizing the variables @code{org-display-custom-times} and
@end table
@noindent
-Org-mode needs the default format for scanning, so the custom date/time
+Org mode needs the default format for scanning, so the custom date/time
format does not @emph{replace} the default format---instead it is put
@emph{over} the default format using text properties. This has the
following consequences:
@example
*** TODO write article about the Earth for the Guide
- The editor in charge is [[bbdb:Ford Prefect]]
DEADLINE: <2004-02-29 Sun>
+ The editor in charge is [[bbdb:Ford Prefect]]
@end example
You can specify a different lead time for warnings for a specific
@end example
@noindent
-@b{Important:} Scheduling an item in Org-mode should @i{not} be
+@b{Important:} Scheduling an item in Org mode should @i{not} be
understood in the same way that we understand @i{scheduling a meeting}.
Setting a date for a meeting is just a simple appointment, you should
mark this entry with a simple plain timestamp, to get this item shown
on the date where it applies. This is a frequent misunderstanding by
-Org users. In Org-mode, @i{scheduling} means setting a date when you
+Org users. In Org mode, @i{scheduling} means setting a date when you
want to start working on an action item.
@end table
You may use timestamps with repeaters in scheduling and deadline
-entries. Org-mode will issue early and late warnings based on the
+entries. Org mode will issue early and late warnings based on the
assumption that the timestamp represents the @i{nearest instance} of
the repeater. However, the use of diary sexp entries like
@c
@code{<%%(org-float t 42)>}
@c
-in scheduling and deadline timestamps is limited. Org-mode does not
+in scheduling and deadline timestamps is limited. Org mode does not
know enough about the internals of each sexp function to issue early and
late warnings. However, it will show the item on each day where the
sexp entry matches.
@cindex tasks, repeated
@cindex repeated tasks
-Some tasks need to be repeated again and again. Org-mode helps to
+Some tasks need to be repeated again and again. Org mode helps to
organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
or plain timestamp. In the following example
@example
once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO
keyword DONE, it will no longer produce entries in the agenda. The problem
with this is, however, that then also the @emph{next} instance of the
-repeated entry will not be active. Org-mode deals with this in the following
+repeated entry will not be active. Org mode deals with this in the following
way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
shift the base date of the repeating timestamp by the repeater interval, and
immediately set the entry state back to TODO@footnote{In fact, the target
forgot to call your father for 3 weeks, it does not make sense to call
him 3 times in a single day to make up for it. Finally, there are tasks
like changing batteries which should always repeat a certain time
-@i{after} the last time you did it. For these tasks, Org-mode has
+@i{after} the last time you did it. For these tasks, Org mode has
special repeaters @samp{++} and @samp{.+}. For example:
@example
@cindex clocking time
@cindex time clocking
-Org-mode allows you to clock the time you spend on specific tasks in a
+Org mode allows you to clock the time you spend on specific tasks in a
project. When you start working on an item, you can start the clock.
When you stop working on that task, or when you mark the task done, the
clock is stopped and the corresponding time interval is recorded. It
@table @kbd
@orgcmd{C-c C-x C-r,org-clock-report}
Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
-report as an Org-mode table into the current file. When the cursor is
+report as an Org mode table into the current file. When the cursor is
at an existing clock table, just update it. When called with a prefix
argument, jump to the first clock report in the current document and
-update it.
+update it. The clock table always includes also trees with
+@code{:ARCHIVE:} tag.
@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
Update dynamic block at point. The cursor needs to be in the
@code{#+BEGIN} line of the dynamic block.
@kindex C-c C-x ;
@kindex ;
-Calling @code{org-timer-set-timer} from an Org-mode buffer runs a countdown
+Calling @code{org-timer-set-timer} from an Org mode buffer runs a countdown
timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everywhere else.
@code{org-timer-set-timer} prompts the user for a duration and displays a
Org's method for capturing new items is heavily inspired by John Wiegley
excellent remember package. Up to version 6.36 Org used a special setup
-for @file{remember.el}. @file{org-remember.el} is still part of Org-mode for
+for @file{remember.el}. @file{org-remember.el} is still part of Org mode for
backward compatibility with existing setups. You can find the documentation
for org-remember at @url{http://orgmode.org/org-remember.pdf}.
@node Template elements, Template expansion, Capture templates, Capture templates
@subsubsection Template elements
-Now let's look at the elements of a template definition. Each entry in
+Now lets look at the elements of a template definition. Each entry in
@code{org-capture-templates} is a list with the following items:
@table @var
The type of entry, a symbol. Valid values are:
@table @code
@item entry
-An Org-mode node, with a headline. Will be filed as the child of the target
-entry or as a top-level entry. The target file should be an Org-mode file.
+An Org mode node, with a headline. Will be filed as the child of the target
+entry or as a top-level entry. The target file should be an Org mode file.
@item item
A plain list item, placed in the first plain list at the target
location. Again the target file should be an Org file.
@item target
@vindex org-default-notes-file
-Specification of where the captured item should be placed. In Org-mode
+Specification of where the captured item should be placed. In Org mode
files, targets usually define a node. Entries will become children of this
node. Other types will be added to the table or list in the body of this
node. Most target specifications contain a file name. If that file name is
In the template itself, special @kbd{%}-escapes@footnote{If you need one of
these sequences literally, escape the @kbd{%} with a backslash.} allow
-dynamic insertion of content. The templates are expanded in the order given here:
+dynamic insertion of content. The templates are expanded in the order given here:
@smallexample
%[@var{file}] @r{insert the contents of the file given by @var{file}.}
Jump to the location where @code{org-refile} last moved a tree to.
@item C-2 C-c C-w
Refile as the child of the item currently being clocked.
-@item C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w
-
@orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear}
-
Clear the target cache. Caching of refile targets can be turned on by
setting @code{org-refile-use-cache}. To make the command see new possible
targets, you have to clear the cache with this command.
@orgcmd{C-c ],org-remove-file}
Remove current file from the list of agenda files.
@kindex C-,
+@cindex cycling, of agenda files
@orgcmd{C-',org-cycle-agenda-files}
@itemx C-,
Cycle through agenda file list, visiting one file after the other.
Org. It can be very useful to combine output from Org with
the diary.
-In order to include entries from the Emacs diary into Org-mode's
+In order to include entries from the Emacs diary into Org mode's
agenda, you only need to customize the variable
@lisp
@noindent After that, everything will happen automatically. All diary
entries including holidays, anniversaries, etc., will be included in the
-agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
+agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and
@key{RET} can be used from the agenda buffer to jump to the diary
file in order to edit existing diary entries. The @kbd{i} command to
insert new entries for the current date works in the agenda buffer, as
If you are using the diary only for sexp entries and holidays, it is
faster to not use the above setting, but instead to copy or even move
-the entries into an Org file. Org-mode evaluates diary-style sexp
+the entries into an Org file. Org mode evaluates diary-style sexp
entries, and does it faster because there is no overhead for first
creating the diary display. Note that the sexp entries must start at
the left margin, no whitespace is allowed before them. For example,
#+CATEGORY: Holiday
%%(org-calendar-holiday) ; special function for holiday names
#+CATEGORY: Ann
-%%(org-anniversary 1956 5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is allways according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old
+%%(org-anniversary 1956 5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is always according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old
%%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
@end example
very likely prefer to store anniversaries in BBDB rather than in a
separate Org or diary file. Org supports this and will show BBDB
anniversaries as part of the agenda. All you need to do is to add the
-following to one your your agenda files:
+following to one of your agenda files:
@example
* Anniversaries
1973-06-22
06-22
1955-08-02 wedding
-2008-04-14 %s released version 6.01 of org-mode, %d years ago
+2008-04-14 %s released version 6.01 of org mode, %d years ago
@end example
After a change to BBDB, or for the first agenda display during an Emacs
@subsubheading Appointment reminders
@cindex @file{appt.el}
@cindex appointment reminders
+@cindex appointment
+@cindex reminders
Org can interact with Emacs appointments notification facility. To add all
the appointments of your agenda files, use the command
price by accessing one property, testing additional properties is cheap
again.
-You can configure Org-mode to use property inheritance during a search, but
+You can configure Org mode to use property inheritance during a search, but
beware that this can slow down searches considerably. See @ref{Property
inheritance}, for details.
@cindex timeline, single file
@cindex time-sorted view
-The timeline summarizes all time-stamped items from a single Org-mode
+The timeline summarizes all time-stamped items from a single Org mode
file in a @emph{time-sorted view}. The main purpose of this command is
to give an overview over events in a project.
@cindex text search
@cindex searching, for text
-This agenda view is a general text search facility for Org-mode entries.
+This agenda view is a general text search facility for Org mode entries.
It is particularly useful to find notes.
@table @kbd
work, one of the ``duties'' you have is a regular review to make sure
that all projects move along. A @emph{stuck} project is a project that
has no defined next actions, so it will never show up in the TODO lists
-Org-mode produces. During the review, you need to identify such
+Org mode produces. During the review, you need to identify such
projects and define next actions for them.
@table @kbd
level-2 headlines, and that a project is not stuck if it has at least
one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
-Let's assume that you, in your own way of using Org-mode, identify
+Let's assume that you, in your own way of using Org mode, identify
projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
indicate a project that should not be considered yet. Let's further
assume that the TODO keyword DONE marks finished projects, and that NEXT
@vindex org-agenda-prefix-format
@vindex org-agenda-tags-column
-Before displaying items in an agenda view, Org-mode visually prepares the
+Before displaying items in an agenda view, Org mode visually prepares the
items and sorts them. Each item occupies a single line. The line starts
with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
of the item and other important information. You can customize in which
@subsection Time-of-day specifications
@cindex time-of-day specification
-Org-mode checks each agenda item for a time-of-day specification. The
+Org mode checks each agenda item for a time-of-day specification. The
time can be part of the timestamp that triggered inclusion into the
agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
ranges can be specified with two timestamps, like
integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
specifications in diary entries are recognized as well.
-For agenda display, Org-mode extracts the time and displays it in a
+For agenda display, Org mode extracts the time and displays it in a
standard 24 hour format as part of the prefix. The example times in
the previous paragraphs would end up in the agenda like this:
@tsubheading{Motion}
@cindex motion commands in agenda
@orgcmd{n,org-agenda-next-line}
-Next line (same as @key{up} and @kbd{C-p}).
+Next line (same as @key{down} and @kbd{C-n}).
@orgcmd{p,org-agenda-previous-line}
-Previous line (same as @key{down} and @kbd{C-n}).
+Previous line (same as @key{up} and @kbd{C-p}).
@tsubheading{View/Go to Org file}
@orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
Display the original location of the item in another window.
@item o
Delete other windows.
@c
-@orgcmdkskc{v d,d,org-aganda-day-view}
-@xorgcmdkskc{v w,w,org-aganda-day-view}
+@orgcmdkskc{v d,d,org-agenda-day-view}
+@xorgcmdkskc{v w,w,org-agenda-week-view}
@xorgcmd{v m,org-agenda-month-view}
-@xorgcmd{v y,org-agenda-month-year}
+@xorgcmd{v y,org-agenda-year-view}
@xorgcmd{v SPC,org-agenda-reset-view}
@vindex org-agenda-span
Switch to day/week/month/year view. When switching to day or week view, this
@c
@orgcmdkskc{v R,R,org-agenda-clockreport-mode}
@vindex org-agenda-start-with-clockreport-mode
+@vindex org-clock-report-include-clocking-task
Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will
always show a table with the clocked times for the timespan and file scope
covered by the current agenda view. The initial setting for this mode in new
@code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show
contributions from entries that are hidden by agenda filtering@footnote{Only
-tags filtering will be respected here, effort filtering is ignored.}.
+tags filtering will be respected here, effort filtering is ignored.}. See
+also the variable @code{org-clock-report-include-clocking-task}.
@c
@orgkey{v c}
@vindex org-agenda-clock-consistency-checks
file or subtree (@pxref{Agenda files}).
@tsubheading{Secondary filtering and query editing}
-@cindex filtering, by tag and effort, in agenda
+@cindex filtering, by tag category and effort, in agenda
@cindex tag filtering, in agenda
+@cindex category filtering, in agenda
@cindex effort filtering, in agenda
@cindex query editing, in agenda
+@orgcmd{<,org-agenda-filter-by-category}
+@vindex org-agenda-category-filter-preset
+
+Filter the current agenda view with respect to the category of the item at
+point. Pressing @code{<} another time will remove this filter. You can add
+a filter preset through the option @code{org-agenda-category-filter-preset}
+(see below.)
+
@orgcmd{/,org-agenda-filter-by-tag}
-@vindex org-agenda-filter-preset
+@vindex org-agenda-tag-filter-preset
Filter the current agenda view with respect to a tag and/or effort estimates.
The difference between this and a custom agenda command is that filtering is
very fast, so that you can switch quickly between different filters without
having to recreate the agenda.@footnote{Custom commands can preset a filter by
-binding the variable @code{org-agenda-filter-preset} as an option. This
+binding the variable @code{org-agenda-tag-filter-preset} as an option. This
filter will then be applied to the view and persist as a basic filter through
refreshes and more secondary filtering. The filter is a global property of
the entire agenda view---in a block agenda, you should only set this in the
@kindex ,
@item ,
Set the priority for the current item (@command{org-agenda-priority}).
-Org-mode prompts for the priority character. If you reply with @key{SPC},
+Org mode prompts for the priority character. If you reply with @key{SPC},
the priority cookie is removed from the entry.
@c
@orgcmd{P,org-agenda-show-priority}
@c
@orgcmd{S-@key{right},org-agenda-do-date-later}
Change the timestamp associated with the current line by one day into the
-future. With a numeric prefix argument, change it by that many days. For
-example, @kbd{3 6 5 S-@key{right}} will change it by a year. With a
-@kbd{C-u} prefix, change the time by one hour. If you immediately repeat the
-command, it will continue to change hours even without the prefix arg. With
-a double @kbd{C-u C-u} prefix, do the same for changing minutes. The stamp
-is changed in the original Org file, but the change is not directly reflected
-in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
+future. If the date is in the past, the first call to this command will move
+it to today.@*
+With a numeric prefix argument, change it by that many days. For example,
+@kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix,
+change the time by one hour. If you immediately repeat the command, it will
+continue to change hours even without the prefix arg. With a double @kbd{C-u
+C-u} prefix, do the same for changing minutes.@*
+The stamp is changed in the original Org file, but the change is not directly
+reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
@c
@orgcmd{S-@key{left},org-agenda-do-date-earlier}
Change the timestamp associated with the current line by one day
Open the Emacs calendar and move to the date at the agenda cursor.
@c
@orgcmd{c,org-calendar-goto-agenda}
-When in the calendar, compute and show the Org-mode agenda for the
+When in the calendar, compute and show the Org mode agenda for the
date at the cursor.
@c
@cindex diary entries, creating from agenda
command in the calendar. The diary file will pop up in another window, where
you can add the entry.
-If you configure @code{org-agenda-diary-file} to point to an Org-mode file,
-Org will create entries (in org-mode syntax) in that file instead. Most
+If you configure @code{org-agenda-diary-file} to point to an Org mode file,
+Org will create entries (in Org mode syntax) in that file instead. Most
entries will be stored in a date-based outline tree that will later make it
easy to archive appointments from previous months/years. The tree will be
built under an entry with a @code{DATE_TREE} property, or else with years as
@vindex org-agenda-exporter-settings
Write the agenda view to a file. Depending on the extension of the selected
file name, the view will be exported as HTML (extension @file{.html} or
-@file{.htm}), PostScript (extension @file{.ps}), PDF (extension @file{.pdf}),
+@file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}),
and plain text (any other extension). When called with a @kbd{C-u} prefix
argument, immediately open the newly created file. Use the variable
@code{org-agenda-exporter-settings} to set options for @file{ps-print} and
@cindex options, for custom agenda views
@vindex org-agenda-custom-commands
-Org-mode contains a number of variables regulating agenda construction
+Org mode contains a number of variables regulating agenda construction
and display. The global variables define the behavior for all agenda
commands, including the custom commands. However, if you want to change
some settings just for a single custom view, you can do so. Setting
@cindex agenda views, exporting
If you are away from your computer, it can be very useful to have a printed
-version of some agenda views to carry around. Org-mode can export custom
+version of some agenda views to carry around. Org mode can export custom
agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's
-@file{htmlize.el}.}, PostScript, PDF@footnote{To create PDF output, the
+@file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the
ghostscript @file{ps2pdf} utility must be installed on the system. Selecting
-a PDF file will also create the PostScript file.}, and iCalendar files. If
+a PDF file will also create the postscript file.}, and iCalendar files. If
you want to do this only occasionally, use the command
@table @kbd
@vindex org-agenda-exporter-settings
Write the agenda view to a file. Depending on the extension of the selected
file name, the view will be exported as HTML (extension @file{.html} or
-@file{.htm}), PostScript (extension @file{.ps}), iCalendar (extension
+@file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
@file{.ics}), or plain text (any other extension). Use the variable
@code{org-agenda-exporter-settings} to set options for @file{ps-print} and
for @file{htmlize} to be used during export, for example
@end lisp
The extension of the file name determines the type of export. If it is
-@file{.html}, Org-mode will use the @file{htmlize.el} package to convert
+@file{.html}, Org mode will use the @file{htmlize.el} package to convert
the buffer to HTML and save it to this file name. If the extension is
@file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
-PostScript output. If the extension is @file{.ics}, iCalendar export is
+Postscript output. If the extension is @file{.ics}, iCalendar export is
run export over all files that were used to construct the agenda, and
limit the export to entries listed in the agenda. Any other
extension produces a plain ASCII file.
@end lisp
@noindent
-This command sets two options for the PostScript exporter, to make it
+This command sets two options for the Postscript exporter, to make it
print in two columns in landscape format---the resulting page can be cut
in two and then used in a paper agenda. The remaining settings modify
the agenda prefix to omit category and scheduling information, and
@noindent
From the command line you may also use
@example
-emacs -f org-batch-store-agenda-views -kill
+emacs -eval (org-batch-store-agenda-views) -kill
@end example
@noindent
or, if you need to modify some parameters@footnote{Quoting depends on the
system you use, please check the FAQ for examples.}
@example
emacs -eval '(org-batch-store-agenda-views \
- org-agenda-span month \
+ org-agenda-span (quote month) \
org-agenda-start-day "2007-11-01" \
org-agenda-include-diary nil \
org-agenda-files (quote ("~/org/project.org")))' \
@node Markup, Exporting, Agenda Views, Top
@chapter Markup for rich export
-When exporting Org-mode documents, the exporter tries to reflect the
+When exporting Org mode documents, the exporter tries to reflect the
structure of the document as accurately as possible in the backend. Since
export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting,
-Org-mode has rules on how to prepare text for rich export. This section
-summarizes the markup rules used in an Org-mode buffer.
+Org mode has rules on how to prepare text for rich export. This section
+summarizes the markup rules used in an Org mode buffer.
@menu
* Structural markup elements:: The basic structure as seen by the exporter
* Include files:: Include additional files into a document
* Index entries:: Making an index
* Macro replacement:: Use macros to create complex output
-* Embedded LaTeX:: LaTeX can be freely used inside Org documents
+* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
@end menu
@node Structural markup elements, Images and tables, Markup, Markup
@cindex text before first headline, markup rules
@cindex #+TEXT
-Org-mode normally exports the text before the first headline, and even uses
+Org mode normally exports the text before the first headline, and even uses
the first line as the document title. The text will be fully marked up. If
you need to include literal HTML, @LaTeX{}, or DocBook code, use the special
constructs described below in the sections for the individual exporters.
When quoting a passage from another document, it is customary to format this
as a paragraph that is indented on both the left and the right margin. You
-can include quotations in Org-mode documents like this:
+can include quotations in Org mode documents like this:
@cindex #+BEGIN_QUOTE
@example
@cindex strike-through text, markup rules
You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text
-in the code and verbatim string is not processed for Org-mode specific
+in the code and verbatim string is not processed for Org mode specific
syntax; it is exported verbatim.
@node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements
@cindex tables, markup rules
@cindex #+CAPTION
@cindex #+LABEL
-Both the native Org-mode tables (@pxref{Tables}) and tables formatted with
-the @file{table.el} package will be exported properly. For Org-mode tables,
+Both the native Org mode tables (@pxref{Tables}) and tables formatted with
+the @file{table.el} package will be exported properly. For Org mode tables,
the lines before the first horizontal separator line will become table header
lines. You can use the following lines somewhere before the table to assign
a caption and a label for cross references, and in the text you can refer to
that can be marked up by font-lock in Emacs, you can ask for the example to
look like the fontified Emacs buffer@footnote{This works automatically for
the HTML backend (it requires version 1.34 of the @file{htmlize.el} package,
-which is distributed with Org). Fontified code chunks in LaTeX can be
+which is distributed with Org). Fontified code chunks in @LaTeX{} can be
achieved using either the listings or the
@url{http://code.google.com/p/minted, minted,} package. To use listings, turn
on the variable @code{org-export-latex-listings} and ensure that the listings
-package is included by the LaTeX header (e.g.@: by configuring
+package is included by the @LaTeX{} header (e.g.@: by configuring
@code{org-export-latex-packages-alist}). See the listings documentation for
configuration options, including obtaining colored output. For minted it is
necessary to install the program @url{http://pygments.org, pygments}, in
addition to setting @code{org-export-latex-minted}, ensuring that the minted
-package is included by the LaTeX header, and ensuring that the
+package is included by the @LaTeX{} header, and ensuring that the
@code{-shell-escape} option is passed to @file{pdflatex} (see
@code{org-latex-to-pdf-process}). See the documentation of the variables
@code{org-export-latex-listings} and @code{org-export-latex-minted} for
need to specify the name of the major mode that should be used to fontify the
example@footnote{Code in @samp{src} blocks may also be evaluated either
interactively or on export. See @pxref{Working With Source Code} for more
-information on evaluating code blocks.}:
+information on evaluating code blocks.}, see @ref{Easy Templates} for
+shortcuts to easily insert code blocks.
@cindex #+BEGIN_SRC
@example
You can also add a @code{-r} switch which @i{removes} the labels from the
source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
labels in the source code while using line numbers for the links, which might
-be useful to explain those in an org-mode example code.}. With the @code{-n}
+be useful to explain those in an Org mode example code.}. With the @code{-n}
switch, links to these references will be labeled by the line numbers from
the code listing, otherwise links will use the labels with no parentheses.
Here is an example:
The optional second and third parameter are the markup (e.g.@: @samp{quote},
@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
language for formatting the contents. The markup is optional; if it is not
-given, the text will be assumed to be in Org-mode format and will be
+given, the text will be assumed to be in Org mode format and will be
processed normally. The include line will also allow additional keyword
parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the
first line and for each following line, @code{:minlevel} in order to get
-org-mode content demoted to a specified level, as well as any options
+Org mode content demoted to a specified level, as well as any options
accepted by the selected markup. For example, to include a file as an item,
use
-@node Macro replacement, Embedded LaTeX, Index entries, Markup
+@node Macro replacement, Embedded @LaTeX{}, Index entries, Markup
@section Macro replacement
@cindex macro replacement, during export
@cindex #+MACRO
construct complex HTML code.
-@node Embedded LaTeX, , Macro replacement, Markup
+@node Embedded @LaTeX{}, , Macro replacement, Markup
@section Embedded @LaTeX{}
@cindex @TeX{} interpretation
@cindex @LaTeX{} interpretation
occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on
Donald E. Knuth's @TeX{} system. Many of the features described here as
``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
-distinction.} is widely used to typeset scientific documents. Org-mode
+distinction.} is widely used to typeset scientific documents. Org mode
supports embedding @LaTeX{} code into its files, because many academics are
used to writing and reading @LaTeX{} source code, and because it can be
readily processed to produce pretty output for a number of export backends.
@menu
* Special symbols:: Greek letters and other symbols
* Subscripts and superscripts:: Simple syntax for raising/lowering text
-* LaTeX fragments:: Complex formulas made easy
-* Previewing LaTeX fragments:: What will this snippet look like?
+* @LaTeX{} fragments:: Complex formulas made easy
+* Previewing @LaTeX{} fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
@end menu
-@node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX
+@node Special symbols, Subscripts and superscripts, Embedded @LaTeX{}, Embedded @LaTeX{}
@subsection Special symbols
@cindex math symbols
@cindex special symbols
indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion
for these macros is available, just type @samp{\} and maybe a few letters,
and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{}
-code, Org-mode allows these macros to be present without surrounding math
+code, Org mode allows these macros to be present without surrounding math
delimiters, for example:
@example
for display purposes only.
@end table
-@node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX
+@node Subscripts and superscripts, @LaTeX{} fragments, Special symbols, Embedded @LaTeX{}
@subsection Subscripts and superscripts
@cindex subscript
@cindex superscript
format sub- and superscripts in a WYSIWYM way.
@end table
-@node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX
+@node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Subscripts and superscripts, Embedded @LaTeX{}
@subsection @LaTeX{} fragments
@cindex @LaTeX{} fragments
@vindex org-format-latex-header
Going beyond symbols and sub- and superscripts, a full formula language is
-needed. Org-mode can contain @LaTeX{} math fragments, and it supports ways
+needed. Org mode can contain @LaTeX{} math fragments, and it supports ways
to process these for several export backends. When exporting to @LaTeX{},
the code is obviously left as it is. When exporting to HTML, Org invokes the
@uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in
ones you do not wish to have interpreted by the @LaTeX{} converter.
@vindex org-export-with-LaTeX-fragments
-LaTeX processing can be configured with the variable
+@LaTeX{} processing can be configured with the variable
@code{org-export-with-LaTeX-fragments}. The default setting is @code{t}
which means @file{MathJax} for HTML, and no processing for DocBook, ASCII and
-LaTeX backends. You can also set this variable on a per-file basis using one
+@LaTeX{} backends. You can also set this variable on a per-file basis using one
of these lines:
@example
#+OPTIONS: LaTeX:verbatim @r{Verbatim export, for jsMath or so}
@end example
-@node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
-@subsection Previewing LaTeX fragments
-@cindex LaTeX fragments, preview
+@node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{}
+@subsection Previewing @LaTeX{} fragments
+@cindex @LaTeX{} fragments, preview
If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to
produce preview images of the typeset expressions:
export, @code{:html-scale}) property can be used to adjust the size of the
preview images.
-@node CDLaTeX mode, , Previewing LaTeX fragments, Embedded LaTeX
-@subsection Using CDLa@TeX{} to enter math
-@cindex CDLa@TeX{}
+@node CDLaTeX mode, , Previewing @LaTeX{} fragments, Embedded @LaTeX{}
+@subsection Using CD@LaTeX{} to enter math
+@cindex CD@LaTeX{}
-CDLa@TeX{} mode is a minor mode that is normally used in combination with a
+CD@LaTeX{} mode is a minor mode that is normally used in combination with a
major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
-environments and math templates. Inside Org-mode, you can make use of
-some of the features of CDLa@TeX{} mode. You need to install
+environments and math templates. Inside Org mode, you can make use of
+some of the features of CD@LaTeX{} mode. You need to install
@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
-Don't use CDLa@TeX{} mode itself under Org-mode, but use the light
-version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it
+Don't use CD@LaTeX{} mode itself under Org mode, but use the light
+version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it
on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
Org files with
@end lisp
When this mode is enabled, the following features are present (for more
-details see the documentation of CDLa@TeX{} mode):
+details see the documentation of CD@LaTeX{} mode):
@itemize @bullet
@kindex C-c @{
@item
@item
@kindex @key{TAB}
The @key{TAB} key will do template expansion if the cursor is inside a
-@LaTeX{} fragment@footnote{Org-mode has a method to test if the cursor is
+@LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
inside such a fragment, see the documentation of the function
@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
@chapter Exporting
@cindex exporting
-Org-mode documents can be exported into a variety of other formats. For
+Org mode documents can be exported into a variety of other formats. For
printing and sharing of notes, ASCII export produces a readable and simple
version of an Org file. HTML export allows you to publish a notes file on
the web, while the XOXO format provides a solid base for exchange with a
-broad range of other applications. @LaTeX{} export lets you use Org-mode and
+broad range of other applications. @LaTeX{} export lets you use Org mode and
its structured editing functions to easily create @LaTeX{} files. DocBook
export makes it possible to convert Org files to many other formats using
-DocBook tools. OpenDocumentText export allows seamless collaboration across
-organizational boundaries. For project management you can create gantt and
-resource charts by using TaskJuggler export. To incorporate entries with
-associated times like deadlines or appointments into a desktop calendar
-program like iCal, Org-mode can also produce extracts in the iCalendar
-format. Currently Org-mode only supports export, not import of these
-different formats.
+DocBook tools. OpenDocument Text (ODT) export allows seamless
+collaboration across organizational boundaries. For project management you
+can create gantt and resource charts by using TaskJuggler export. To
+incorporate entries with associated times like deadlines or appointments into
+a desktop calendar program like iCal, Org mode can also produce extracts in
+the iCalendar format. Currently, Org mode only supports export, not import of
+these different formats.
Org supports export of selected regions when @code{transient-mark-mode} is
enabled (default in Emacs 23).
* The export dispatcher:: How to access exporter commands
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* HTML export:: Exporting to HTML
-* LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF
+* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
* DocBook export:: Exporting to DocBook
-* OpenDocumentText export:: Exporting to OpenDocumentText
+* OpenDocument Text export:: Exporting to OpenDocument Text
* TaskJuggler export:: Exporting to TaskJuggler
* Freemind export:: Exporting to Freemind mind maps
* XOXO export:: Exporting to XOXO
@cindex org-export-with-tasks
You may use tags to select the parts of a document that should be exported,
or to exclude parts from export. This behavior is governed by two variables:
-@code{org-export-select-tags} and @code{org-export-exclude-tags}.
+@code{org-export-select-tags} and @code{org-export-exclude-tags},
+respectively defaulting to @code{'(:export:)} and @code{'(:noexport:)}.
@enumerate
@item
@vindex user-full-name
@vindex user-mail-address
@vindex org-export-default-language
+@vindex org-export-date-timestamp-format
@example
#+TITLE: the title to be shown (default is the buffer name)
#+AUTHOR: the author (default taken from @code{user-full-name})
-#+DATE: a date, fixed, or a format string for @code{format-time-string}
+#+DATE: a date, an Org timestamp@footnote{@code{org-export-date-timestamp-format} defines how this timestamp will be exported.}, or a format string for @code{format-time-string}
#+EMAIL: his/her email address (default from @code{user-mail-address})
#+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag
#+KEYWORDS: the page keywords, e.g.@: for the XHTML meta tag
#+TEXT: Some descriptive text to be inserted at the beginning.
#+TEXT: Several lines may be given.
#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
-#+BIND: lisp-var lisp-val, e.g.@:: org-export-latex-low-levels itemize
+#+BIND: lisp-var lisp-val, e.g.@:: @code{org-export-latex-low-levels itemize}
@r{You need to confirm using these, or configure @code{org-export-allow-BIND}}
#+LINK_UP: the ``up'' link of an exported page
#+LINK_HOME: the ``home'' link of an exported page
-#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@}
+#+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@}
#+EXPORT_SELECT_TAGS: Tags that select a tree for export
#+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export
#+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file
@end example
@noindent
-The OPTIONS line is a compact@footnote{If you want to configure many options
-this way, you can use several OPTIONS lines.} form to specify export
+The @code{#+OPTIONS} line is a compact@footnote{If you want to configure many options
+this way, you can use several @code{#+OPTIONS} lines.} form to specify export
settings. Here you can:
@cindex headline levels
@cindex section-numbers
@cindex Latin-1 export
@cindex UTF-8 export
-ASCII export produces a simple and very readable version of an Org-mode
+ASCII export produces a simple and very readable version of an Org mode
file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file
with special characters and symbols available in these encodings.
the text and the link in a note before the next heading. See the variable
@code{org-export-ascii-links-to-notes} for details and other options.
-@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting
+@node HTML export, @LaTeX{} and PDF export, ASCII/Latin-1/UTF-8 export, Exporting
@section HTML export
@cindex HTML export
-Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
+Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive
HTML formatting, in ways similar to John Gruber's @emph{markdown}
language, but with additional support for tables.
@menu
* HTML Export commands:: How to invoke HTML export
* HTML preamble and postamble:: How to insert a preamble and a postamble
-* Quoting HTML tags:: Using direct HTML in Org-mode
+* Quoting HTML tags:: Using direct HTML in Org mode
* Links in HTML export:: How links will be interpreted and formatted
* Tables in HTML export:: How to modify the formatting of tables
* Images in HTML export:: How to insert figures into HTML output
@item C-c C-e v h/b/H/R
Export only the visible part of the document.
@item M-x org-export-region-as-html
-Convert the region to HTML under the assumption that it was Org-mode
+Convert the region to HTML under the assumption that it was Org mode
syntax before. This is a global command that can be invoked in any
buffer.
@item M-x org-replace-region-by-HTML
-Replace the active region (assumed to be in Org-mode syntax) by HTML
+Replace the active region (assumed to be in Org mode syntax) by HTML
code.
@end table
@cindex #+ATTR_HTML
@example
-#+ATTR_HTML: title="The Org-mode homepage" style="color:red;"
+#+ATTR_HTML: title="The Org mode homepage" style="color:red;"
[[http://orgmode.org]]
@end example
@cindex tables, in HTML
@vindex org-export-html-table-tag
-Org-mode tables are exported to HTML using the table tag defined in
+Org mode tables are exported to HTML using the table tag defined in
@code{org-export-html-table-tag}. The default setting makes tables without
cell borders and frame. If you would like to change this for individual
tables, place something like the following before the table:
@cindex #+ATTR_HTML
@example
#+CAPTION: This is a table with lines around and between cells
-#+ATTR_HTML: border="2" rules="all" frame="all"
+#+ATTR_HTML: border="2" rules="all" frame="border"
@end example
@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export
@cindex MathJax
@cindex dvipng
-@LaTeX{} math snippets (@pxref{LaTeX fragments}) can be displayed in two
+@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
different ways on HTML pages. The default is to use the
@uref{http://www.mathjax.org, MathJax system} which should work out of the
box with Org mode installation because @code{http://orgmode.org} serves
-@file{MathJax} for Org-mode users for small applications and for testing
+@file{MathJax} for Org mode users for small applications and for testing
purposes. @b{If you plan to use this regularly or on pages with significant
page views, you should install@footnote{Installation instructions can be
found on the MathJax website, see
@example
p.author @r{author information, including email}
p.date @r{publishing date}
-p.creator @r{creator info, about org-mode version}
+p.creator @r{creator info, about org mode version}
.title @r{document title}
.todo @r{TODO keywords, all not-done states}
.done @r{the DONE keywords, all states that count as done}
@code{org-infojs-options}. If you always want to apply the script to your
pages, configure the variable @code{org-export-html-use-infojs}.
-@node LaTeX and PDF export, DocBook export, HTML export, Exporting
+@node @LaTeX{} and PDF export, DocBook export, HTML export, Exporting
@section @LaTeX{} and PDF export
@cindex @LaTeX{} export
@cindex PDF export
@cindex Guerry, Bastien
-Org-mode contains a @LaTeX{} exporter written by Bastien Guerry. With
-further processing@footnote{The default LaTeX output is designed for
-processing with pdftex or latex. It includes packages that are not
-compatible with xetex and possibly luatex. See the variables
+Org mode contains a @LaTeX{} exporter written by Bastien Guerry. With
+further processing@footnote{The default @LaTeX{} output is designed for
+processing with @code{pdftex} or @LaTeX{}. It includes packages that are not
+compatible with @code{xetex} and possibly @code{luatex}. See the variables
@code{org-export-latex-default-packages-alist} and
@code{org-export-latex-packages-alist}.}, this backend is also used to
produce PDF output. Since the @LaTeX{} output uses @file{hyperref} to
sections.
@menu
-* LaTeX/PDF export commands:: Which key invokes which commands
+* @LaTeX{}/PDF export commands::
* Header and sectioning:: Setting up the export file structure
-* Quoting LaTeX code:: Incorporating literal @LaTeX{} code
-* Tables in LaTeX export:: Options for exporting tables to @LaTeX{}
-* Images in LaTeX export:: How to insert figures into @LaTeX{} output
+* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code
+* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{}
+* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output
* Beamer class export:: Turning the file into a presentation
@end menu
-@node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export
+@node @LaTeX{}/PDF export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export
@subsection @LaTeX{} export commands
@cindex region, active
@item C-c C-e v l/L
Export only the visible part of the document.
@item M-x org-export-region-as-latex
-Convert the region to @LaTeX{} under the assumption that it was Org-mode
+Convert the region to @LaTeX{} under the assumption that it was Org mode
syntax before. This is a global command that can be invoked in any
buffer.
@item M-x org-replace-region-by-latex
-Replace the active region (assumed to be in Org-mode syntax) by @LaTeX{}
+Replace the active region (assumed to be in Org mode syntax) by @LaTeX{}
code.
@orgcmd{C-c C-e p,org-export-as-pdf}
Export as @LaTeX{} and then process to PDF.
@noindent
creates two levels of headings and does the rest as items.
-@node Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export
+@node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{}/PDF export commands, @LaTeX{} and PDF export
@subsection Header and sectioning structure
@cindex @LaTeX{} class
@cindex @LaTeX{} sectioning structure
@cindex @LaTeX{} header
-@cindex header, for LaTeX files
-@cindex sectioning structure, for LaTeX export
+@cindex header, for @LaTeX{} files
+@cindex sectioning structure, for @LaTeX{} export
By default, the @LaTeX{} output uses the class @code{article}.
header. See the docstring of @code{org-export-latex-classes} for more
information.
-@node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export
+@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, Header and sectioning, @LaTeX{} and PDF export
@subsection Quoting @LaTeX{} code
-Embedded @LaTeX{} as described in @ref{Embedded LaTeX}, will be correctly
+Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly
inserted into the @LaTeX{} file. This includes simple macros like
@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore,
you can add special code that should only be present in @LaTeX{} export with
@cindex #+LaTeX
@cindex #+BEGIN_LaTeX
@example
-#+LaTeX: Literal LaTeX code for export
+#+LaTeX: Literal @LaTeX{} code for export
@end example
@noindent or
@end example
-@node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export
+@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} and PDF export
@subsection Tables in @LaTeX{} export
@cindex tables, in @LaTeX{} export
| ..... | ..... |
@end example
-@node Images in LaTeX export, Beamer class export, Tables in LaTeX export, LaTeX and PDF export
+@node Images in @LaTeX{} export, Beamer class export, Tables in @LaTeX{} export, @LaTeX{} and PDF export
@subsection Images in @LaTeX{} export
@cindex images, inline in @LaTeX{}
@cindex inlining images in @LaTeX{}
If you need references to a label created in this way, write
@samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}.
-@node Beamer class export, , Images in LaTeX export, LaTeX and PDF export
+@node Beamer class export, , Images in @LaTeX{} export, @LaTeX{} and PDF export
@subsection Beamer class export
-The LaTeX class @file{beamer} allows production of high quality presentations
-using LaTeX and pdf processing. Org-mode has special support for turning an
-Org-mode file or tree into a @file{beamer} presentation.
+The @LaTeX{} class @file{beamer} allows production of high quality presentations
+using @LaTeX{} and pdf processing. Org mode has special support for turning an
+Org mode file or tree into a @file{beamer} presentation.
-When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS:
+When the @LaTeX{} class for the current buffer (as set with @code{#+LaTeX_CLASS:
beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is
@code{beamer}, a special export mode will turn the file or tree into a beamer
presentation. Any tree with not-too-deep level nesting should in principle be
For more information, see the documentation on Worg.
-@node DocBook export, OpenDocumentText export, LaTeX and PDF export, Exporting
+@node DocBook export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting
@section DocBook export
@cindex DocBook export
@cindex PDF export
@cindex #+LABEL
@cindex #+ATTR_DOCBOOK
@example
-#+CAPTION: The logo of Org-mode
+#+CAPTION: The logo of Org mode
#+LABEL: unicorn-svg
#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
[[./img/org-mode-unicorn.svg]]
@c begin opendocument
-@node OpenDocumentText export, TaskJuggler export, DocBook export, Exporting
-@section OpenDocumentText export
-@cindex OpenDocumentText export
+@node OpenDocument Text export, TaskJuggler export, DocBook export, Exporting
+@section OpenDocument Text export
@cindex K, Jambunathan
-
-Org-mode 7.6 supports export to OpenDocumentText format using
-@file{org-odt.el} module contributed by Jambunathan K. This module can be
-enabled in one of the following ways based on your mode of installation.
-
-@enumerate
-@item
-If you have downloaded the Org from the Web, either as a distribution
-@file{.zip} or @file{.tar} file, or as a Git archive, enable the @code{odt}
-option in variable @code{org-modules}.
-@item
-If you are using Org that comes bundled with Emacs, then you can install the
-OpenDocumentText exporter using the package manager. To do this, customize
-the variable @code{package-archives} to include
-@uref{http://orgmode.org/pkg/releases/} as one of the package archives.
-@end enumerate
+@cindex ODT
+@cindex OpenDocument
+@cindex export, OpenDocument
+@cindex LibreOffice
+@cindex org-odt.el
+@cindex org-modules
+
+Orgmode@footnote{Versions 7.8 or later} supports export to OpenDocument Text
+(ODT) format using the @file{org-odt.el} module. Documents created
+by this exporter use the @cite{OpenDocument-v1.2
+specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
+Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
+are compatible with LibreOffice 3.4.
@menu
-* OpenDocumentText export commands::How to invoke OpenDocumentText export
-* Applying Custom Styles:: How to apply custom styles to the output
-* Converting to Other formats:: How to convert to formats like doc, docx etc
-* Links in OpenDocumentText export:: How links will be interpreted and formatted
-* Tables in OpenDocumentText export:: Tables are exported as HTML tables
-* Images in OpenDocumentText export:: How to insert figures into DocBook output
-* Additional Documentation:: Where to find more information
+* Pre-requisites for ODT export:: What packages ODT exporter relies on
+* ODT export commands:: How to invoke ODT export
+* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files
+* Applying custom styles:: How to apply custom styles to the output
+* Links in ODT export:: How links will be interpreted and formatted
+* Tables in ODT export:: How Tables are exported
+* Images in ODT export:: How to insert images
+* Math formatting in ODT export:: How @LaTeX{} fragments are formatted
+* Labels and captions in ODT export:: How captions are rendered
+* Literal examples in ODT export:: How source and example blocks are formatted
+* Advanced topics in ODT export:: Read this if you are a power user
@end menu
-@node OpenDocumentText export commands, Applying Custom Styles, OpenDocumentText export, OpenDocumentText export
-@subsection OpenDocumentText export commands
+@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export
+@subsection Pre-requisites for ODT export
+@cindex zip
+The ODT exporter relies on the @file{zip} program to create the final
+output. Check the availability of this program before proceeding further.
+
+@node ODT export commands, Extending ODT export, Pre-requisites for ODT export, OpenDocument Text export
+@subsection ODT export commands
+
+@subsubheading Exporting to ODT
+@anchor{x-export-to-odt}
@cindex region, active
@cindex active region
@table @kbd
@orgcmd{C-c C-e o,org-export-as-odt}
@cindex property EXPORT_FILE_NAME
-Export as OpenDocumentText file. For an Org file, @file{myfile.org}, the
-OpenDocumentText file will be @file{myfile.odt}. The file will be
-overwritten without warning. If there is an active region@footnote{This
-requires @code{transient-mark-mode} to be turned on}, only the region will be
-exported. If the selected region is a single tree@footnote{To select the
-current subtree, use @kbd{C-c @@}.}, the tree head will become the document
-title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
-property, that name will be used for the export.
+
+Export as OpenDocument Text file.
+
+@vindex org-export-odt-preferred-output-format
+If @code{org-export-odt-preferred-output-format} is specified, automatically
+convert the exported file to that format. @xref{x-export-to-other-formats, ,
+Automatically exporting to other formats}.
+
+For an Org file @file{myfile.org}, the ODT file will be
+@file{myfile.odt}. The file will be overwritten without warning. If there
+is an active region,@footnote{This requires @code{transient-mark-mode} to be
+turned on} only the region will be exported. If the selected region is a
+single tree,@footnote{To select the current subtree, use @kbd{C-c @@}} the
+tree head will become the document title. If the tree head entry has, or
+inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the
+export.
+
@orgcmd{C-c C-e O,org-export-as-odt-and-open}
-Export as OpenDocumentText file and open the resulting file.
+Export as OpenDocument Text file and open the resulting file.
+
+@vindex org-export-odt-preferred-output-format
+If @code{org-export-odt-preferred-output-format} is specified, open the
+converted file instead. @xref{x-export-to-other-formats, , Automatically
+exporting to other formats}.
@end table
-@node Applying Custom Styles, Converting to Other formats, OpenDocumentText export commands, OpenDocumentText export
-@subsection Applying Custom Styles
+@node Extending ODT export, Applying custom styles, ODT export commands, OpenDocument Text export
+@subsection Extending ODT export
+
+The ODT exporter can interface with a variety of document
+converters and supports popular converters out of the box. As a result, you
+can use it to export to formats like @samp{doc} or convert a document from
+one format (say @samp{csv}) to another format (say @samp{ods} or @samp{xls}).
+
+@cindex @file{unoconv}
+@cindex LibreOffice
+If you have a working installation of LibreOffice, a document converter is
+pre-configured for you and you can use it right away. If you would like to
+use @file{unoconv} as your preferred converter, customize the variable
+@code{org-export-odt-convert-process} to point to @code{unoconv}. You can
+also use your own favorite converter or tweak the default settings of the
+@file{LibreOffice} and @samp{unoconv} converters. @xref{Configuring a
+document converter}.
+
+@subsubsection Automatically exporting to other formats
+@anchor{x-export-to-other-formats}
+
+@vindex org-export-odt-preferred-output-format
+Very often, you will find yourself exporting to ODT format, only to
+immediately save the exported document to other formats like @samp{doc},
+@samp{docx}, @samp{rtf}, @samp{pdf} etc. In such cases, you can specify your
+preferred output format by customizing the variable
+@code{org-export-odt-preferred-output-format}. This way, the export commands
+(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a
+format that is of immediate interest to you.
+
+@subsubsection Converting between document formats
+@anchor{x-convert-to-other-formats}
+
+There are many document converters in the wild which support conversion to
+and from various file formats, including, but not limited to the
+ODT format. LibreOffice converter, mentioned above, is one such
+converter. Once a converter is configured, you can interact with it using
+the following command.
+
+@vindex org-export-odt-convert
+@table @kbd
+
+@item M-x org-export-odt-convert
+Convert an existing document from one format to another. With a prefix
+argument, also open the newly produced file.
+@end table
+
+@node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export
+@subsection Applying custom styles
@cindex styles, custom
@cindex template, custom
-@vindex org-export-odt-styles-file
+The ODT exporter ships with a set of OpenDocument styles
+(@pxref{Working with OpenDocument style files}) that ensure a well-formatted
+output. These factory styles, however, may not cater to your specific
+tastes. To customize the output, you can either modify the above styles
+files directly, or generate the required styles using an application like
+LibreOffice. The latter method is suitable for expert and non-expert
+users alike, and is described here.
-OpenDocumentExporter ships with a custom @file{styles.xml} for formatting of
-the exported file. To customize the output to suit your needs you can use
-one of the following methods:
+@subsubsection Applying custom styles - the easy way
@enumerate
@item
-Customize the variable @code{org-export-odt-styles-file} to point to either a
-@file{styles.xml} file, a OpenDocument Text Template file @code{.ott} or a
-combination of Text or Template Document together with a set of member files.
-Use the first two options if the styles.xml has no references to additional
-set of files and use the last option if the @file{styles.xml} references
-additional files like header and footer images.
+Create a sample @file{example.org} file with the below settings and export it
+to ODT format.
+
+@example
+#+OPTIONS: H:10 num:t
+@end example
+
@item
-Use an external tool like unoconv to apply custom templates.
+Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
+to locate the target styles - these typically have the @samp{Org} prefix -
+and modify those to your taste. Save the modified file either as an
+OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file.
+
+@item
+@cindex #+ODT_STYLES_FILE
+@vindex org-export-odt-styles-file
+Customize the variable @code{org-export-odt-styles-file} and point it to the
+newly created file. For additional configuration options
+@pxref{x-overriding-factory-styles,,Overriding factory styles}.
+
+If you would like to choose a style on a per-file basis, you can use the
+@code{#+ODT_STYLES_FILE} option. A typical setting will look like
+
+@example
+#+ODT_STYLES_FILE: "/path/to/example.ott"
+@end example
+
+or
+
+@example
+#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
+@end example
+
@end enumerate
-For best results, it is necessary that the style names used by
-OpenDocumentText exporter match that used in the @file{styles.xml}.
+@subsubsection Using third-party styles and templates
-@node Converting to Other formats, Links in OpenDocumentText export, Applying Custom Styles, OpenDocumentText export
-@subsection Converting to Other formats
+You can use third-party styles and templates for customizing your output.
+This will produce the desired output only if the template provides all
+style names that the @samp{ODT} exporter relies on. Unless this condition is
+met, the output is going to be less than satisfactory. So it is highly
+recommended that you only work with templates that are directly derived from
+the factory settings.
-@cindex convert
-@cindex doc, docx
+@node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export
+@subsection Links in ODT export
+@cindex tables, in DocBook export
-@vindex org-export-odt-styles-file
+ODT exporter creates native cross-references for internal links. It creates
+Internet-style links for all other links.
+
+A link with no description and destined to a regular (un-itemized) outline
+heading is replaced with a cross-reference and section number of the heading.
-Often times there is a need to convert OpenDocumentText files to other
-formats like doc, docx or pdf. You can accomplish this by one of the
-following methods:
+A @samp{\ref@{label@}}-style reference to an image, table etc. is replaced
+with a cross-reference and sequence number of the labeled entity.
+@xref{Labels and captions in ODT export}.
+
+@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export
+@subsection Tables in ODT export
+@cindex tables, in DocBook export
+
+Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el}
+tables is supported. However, export of complex @file{table.el} tables -
+tables that have column or row spans - is not supported. Such tables are
+stripped from the exported document.
+
+By default, a table is exported with top and bottom frames and with rules
+separating row and column groups (@pxref{Column groups}). Furthermore, all
+tables are typeset to occupy the same width. If the table specifies
+alignment and relative width for its columns (@pxref{Column width and
+alignment}) then these are honored on export.@footnote{The column widths are
+interpreted as weighted ratios with the default weight being 1}
+
+@cindex #+ATTR_ODT
+You can control the width of the table by specifying @code{:rel-width}
+property using an @code{#+ATTR_ODT} line.
+
+For example, consider the following table which makes use of all the rules
+mentioned above.
+
+@example
+#+ATTR_ODT: :rel-width 50
+| Area/Month | Jan | Feb | Mar | Sum |
+|---------------+-------+-------+-------+-------|
+| / | < | | | < |
+| <l13> | <r5> | <r5> | <r5> | <r6> |
+| North America | 1 | 21 | 926 | 948 |
+| Middle East | 6 | 75 | 844 | 925 |
+| Asia Pacific | 9 | 27 | 790 | 826 |
+|---------------+-------+-------+-------+-------|
+| Sum | 16 | 123 | 2560 | 2699 |
+@end example
+
+On export, the table will occupy 50% of text area. The columns will be sized
+(roughly) in the ratio of 13:5:5:5:6. The first column will be left-aligned
+and rest of the columns will be right-aligned. There will be vertical rules
+after separating the header and last columns from other columns. There will
+be horizontal rules separating the header and last rows from other rows.
+
+If you are not satisfied with the above formatting options, you can create
+custom table styles and associate them with a table using the
+@code{#+ATTR_ODT} line. @xref{Customizing tables in ODT export}.
+
+@node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export
+@subsection Images in ODT export
+@cindex images, embedding in ODT
+@cindex embedding images in ODT
+
+@subsubheading Embedding images
+You can embed images within the exported document by providing a link to the
+desired image file with no link description. For example, to embed
+@samp{img.png} do either of the following:
+
+@example
+[[file:img.png]]
+@end example
+
+@example
+[[./img.png]]
+@end example
+
+@subsubheading Embedding clickable images
+You can create clickable images by providing a link whose description is a
+link to an image file. For example, to embed a image
+@file{org-mode-unicorn.png} which when clicked jumps to
+@uref{http://Orgmode.org} website, do the following
+
+@example
+[[http://orgmode.org][./org-mode-unicorn.png]]
+@end example
+
+@subsubheading Sizing and scaling of embedded images
+
+@cindex #+ATTR_ODT
+You can control the size and scale of the embedded images using the
+@code{#+ATTR_ODT} attribute.
+
+@cindex identify, ImageMagick
+@vindex org-export-odt-pixels-per-inch
+The exporter specifies the desired size of the image in the final document in
+units of centimeters. In order to scale the embedded images, the exporter
+queries for pixel dimensions of the images using one of a) ImageMagick's
+@file{identify} program or b) Emacs `create-image' and `image-size'
+APIs.@footnote{Use of @file{ImageMagick} is only desirable. However, if you
+routinely produce documents that have large images or you export your Org
+files that has images using a Emacs batch script, then the use of
+@file{ImageMagick} is mandatory.} The pixel dimensions are subsequently
+converted in to units of centimeters using
+@code{org-export-odt-pixels-per-inch}. The default value of this variable is
+set to @code{display-pixels-per-inch}. You can tweak this variable to
+achieve the best results.
+
+The examples below illustrate the various possibilities.
+
+@table @asis
+@item Explicitly size the image
+To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
+
+@example
+#+ATTR_ODT: :width 10 :height 10
+[[./img.png]]
+@end example
+
+@item Scale the image
+To embed @file{img.png} at half its size, do the following:
+
+@example
+#+ATTR_ODT: :scale 0.5
+[[./img.png]]
+@end example
+
+@item Scale the image to a specific width
+To embed @file{img.png} with a width of 10 cm while retaining the original
+height:width ratio, do the following:
+
+@example
+#+ATTR_ODT: :width 10
+[[./img.png]]
+@end example
+
+@item Scale the image to a specific height
+To embed @file{img.png} with a height of 10 cm while retaining the original
+height:width ratio, do the following
+
+@example
+#+ATTR_ODT: :height 10
+[[./img.png]]
+@end example
+@end table
+
+@subsubheading Anchoring of images
+
+@cindex #+ATTR_ODT
+You can control the manner in which an image is anchored by setting the
+@code{:anchor} property of it's @code{#+ATTR_ODT} line. You can specify one
+of the the following three values for the @code{:anchor} property -
+@samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}.
+
+To create an image that is anchored to a page, do the following:
+@example
+#+ATTR_ODT: :anchor "page"
+[[./img.png]]
+@end example
+
+@node Math formatting in ODT export, Labels and captions in ODT export, Images in ODT export, OpenDocument Text export
+@subsection Math formatting in ODT export
+
+The ODT exporter has special support for handling math.
+
+@menu
+* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments
+* Working with MathML or OpenDocument formula files:: How to embed equations in native format
+@end menu
+
+@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in ODT export, Math formatting in ODT export
+@subsubsection Working with @LaTeX{} math snippets
+
+@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT
+document in one of the following ways:
+
+@cindex MathML
+@enumerate
+@item MathML
+
+This option is activated on a per-file basis with
+
+@example
+#+OPTIONS: LaTeX:t
+@end example
+
+With this option, @LaTeX{} fragments are first converted into MathML
+fragments using an external @LaTeX{}-to-MathML converter program. The
+resulting MathML fragments are then embedded as an OpenDocument Formula in
+the exported document.
+
+@vindex org-latex-to-mathml-convert-command
+@vindex org-latex-to-mathml-jar-file
+
+You can specify the @LaTeX{}-to-MathML converter by customizing the variables
+@code{org-latex-to-mathml-convert-command} and
+@code{org-latex-to-mathml-jar-file}.
+
+If you prefer to use @file{MathToWeb}@footnote{See
+@uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your
+converter, you can configure the above variables as shown below.
+
+@lisp
+(setq org-latex-to-mathml-convert-command
+ "java -jar %j -unicode -force -df %o %I"
+ org-latex-to-mathml-jar-file
+ "/path/to/mathtoweb.jar")
+@end lisp
+
+You can use the following commands to quickly verify the reliability of
+the @LaTeX{}-to-MathML converter.
@table @kbd
-@item M-x org-lparse
-Export the outline first to one of the native formats (like OpenDocumentText)
-and immediately post-process it to other formats using an external converter.
-@item M-x org-lparse-convert
-Export an existing document to other formats using an external converter.
+@item M-x org-export-as-odf
+Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file.
+
+@item M-x org-export-as-odf-and-open
+Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file and
+open the formula file with the system-registered application.
@end table
-You can choose the converter used for conversion by customizing the variable
-@code{org-lparse-convert-process}.
+@cindex dvipng
+@item PNG images
-@node Links in OpenDocumentText export, Tables in OpenDocumentText export, Converting to Other formats, OpenDocumentText export
-@subsection Links in OpenDocumentText export
-@cindex tables, in DocBook export
+This option is activated on a per-file basis with
-OpenDocumentExporter creates cross-references (aka bookmarks) for links that
-are destined locally. It creates internet style links for all other links.
+@example
+#+OPTIONS: LaTeX:dvipng
+@end example
-@node Tables in OpenDocumentText export, Images in OpenDocumentText export, Links in OpenDocumentText export, OpenDocumentText export
-@subsection Tables in OpenDocumentText export
-@cindex tables, in DocBook export
+With this option, @LaTeX{} fragments are processed into PNG images and the
+resulting images are embedded in the exported document. This method requires
+that the @file{dvipng} program be available on your system.
+@end enumerate
-Export of @file{table.el} tables with row or column spanning is not
-supported. Such tables are stripped from the exported document.
+@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in ODT export
+@subsubsection Working with MathML or OpenDocument formula files
-@node Images in OpenDocumentText export, Additional Documentation, Tables in OpenDocumentText export, OpenDocumentText export
-@subsection Images in OpenDocumentText export
-@cindex images, embedding in OpenDocumentText
-@cindex embedding images in OpenDocumentText
+For various reasons, you may find embedding @LaTeX{} math snippets in an
+ODT document less than reliable. In that case, you can embed a
+math equation by linking to its MathML (@file{.mml}) source or its
+OpenDocument formula (@file{.odf}) file as shown below:
-OpenDocumentText exporter can embed images within the exported document. To
-embed images, provide a link to the desired image file with no link
-description. For example, the following links @samp{[[file:img.jpg]]} or
-@samp{[[./img.jpg]]}, will result in embedding of @samp{img.jpg} in the
-exported file.
+@example
+[[./equation.mml]]
+@end example
+
+or
+
+@example
+[[./equation.odf]]
+@end example
-The exporter can also embed scaled and explicitly sized images within the
-exported document. The markup of the scale and size specifications has not
-been standardized yet and is hence conveniently skipped in this document.
+@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export
+@subsection Labels and captions in ODT export
+
+You can label and caption various category of objects - an inline image, a
+table, a @LaTeX{} fragment or a Math formula - using @code{#+LABEL} and
+@code{#+CAPTION} lines. @xref{Images and tables}. ODT exporter enumerates
+each labeled or captioned object of a given category separately. As a
+result, each such object is assigned a sequence number based on order of it's
+appearance in the Org file.
+
+In the exported document, a user-provided caption is augmented with the
+category and sequence number. Consider the following inline image in an Org
+file.
+
+@example
+#+CAPTION: Bell curve
+#+LABEL: fig:SED-HR4049
+[[./img/a.png]]
+@end example
+
+It could be rendered as shown below in the exported document.
+
+@example
+Figure 2: Bell curve
+@end example
+
+@vindex org-export-odt-category-strings
+You can modify the category component of the caption by customizing the
+variable @code{org-export-odt-category-strings}. For example, to tag all
+embedded images with the string @samp{Illustration} (instead of the default
+@samp{Figure}) use the following setting.
+
+@lisp
+(setq org-export-odt-category-strings
+ '(("en" "Table" "Illustration" "Equation" "Equation")))
+@end lisp
+
+With this, previous image will be captioned as below in the exported
+document.
+
+@example
+Illustration 2: Bell curve
+@end example
+
+@node Literal examples in ODT export, Advanced topics in ODT export, Labels and captions in ODT export, OpenDocument Text export
+@subsection Literal examples in ODT export
+
+Export of literal examples (@pxref{Literal examples}) with full fontification
+is supported. Internally, the exporter relies on @file{htmlfontify.el} to
+generate all style definitions needed for a fancy listing.@footnote{Your
+@file{htmlfontify.el} library must at least be at Emacs 24.1 levels for
+fontification to be turned on.} The auto-generated styles have @samp{OrgSrc}
+as prefix and inherit their color from the faces used by Emacs
+@code{font-lock} library for the source language.
+
+@vindex org-export-odt-fontify-srcblocks
+If you prefer to use your own custom styles for fontification, you can do so
+by customizing the variable
+@code{org-export-odt-create-custom-styles-for-srcblocks}.
+
+@vindex org-export-odt-create-custom-styles-for-srcblocks
+You can turn off fontification of literal examples by customizing the
+variable @code{org-export-odt-fontify-srcblocks}.
+
+@node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export
+@subsection Advanced topics in ODT export
+
+If you rely heavily on ODT export, you may want to exploit the full
+set of features that the exporter offers. This section describes features
+that would be of interest to power users.
+
+@menu
+* Configuring a document converter:: How to register a document converter
+* Working with OpenDocument style files:: Explore the internals
+* Creating one-off styles:: How to produce custom highlighting etc
+* Customizing tables in ODT export:: How to define and use Table templates
+* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
+@end menu
+
+@node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export
+@subsubsection Configuring a document converter
+@cindex convert
+@cindex doc, docx, rtf
+@cindex converter
+
+The ODT exporter can work with popular converters with little or no
+extra configuration from your side. @xref{Extending ODT export}.
+If you are using a converter that is not supported by default or if you would
+like to tweak the default converter settings, proceed as below.
+
+@enumerate
+@item Register the converter
+
+@vindex org-export-odt-convert-processes
+Name your converter and add it to the list of known converters by customizing
+the variable @code{org-export-odt-convert-processes}. Also specify how the
+converter can be invoked via command-line to effect the conversion.
+
+@item Configure its capabilities
+
+@vindex org-export-odt-convert-capabilities
+@anchor{x-odt-converter-capabilities}
+Specify the set of formats the converter can handle by customizing the
+variable @code{org-export-odt-convert-capabilities}. Use the default value
+for this variable as a guide for configuring your converter. As suggested by
+the default setting, you can specify the full set of formats supported by the
+converter and not limit yourself to specifying formats that are related to
+just the OpenDocument Text format.
+
+@item Choose the converter
+
+@vindex org-export-odt-convert-process
+Select the newly added converter as the preferred one by customizing the
+variable @code{org-export-odt-convert-process}.
+@end enumerate
+
+@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export
+@subsubsection Working with OpenDocument style files
+@cindex styles, custom
+@cindex template, custom
-The exporter can also make an image the clickable part of a link. To create
-clickable images, provide a link whose description is a link to an image
-file. For example, the following link
-@samp{[[http://orgmode.org][./img.jpg]]}, will result in a clickable image
-that links to @uref{http://Orgmode.org} website.
+This section explores the internals of the ODT exporter and the
+means by which it produces styled documents. Read this section if you are
+interested in exploring the automatic and custom OpenDocument styles used by
+the exporter.
-@node Additional Documentation, , Images in OpenDocumentText export, OpenDocumentText export
-@subsection Additional documentation
+@anchor{x-factory-styles}
+@subsubheading Factory styles
-The OpenDocumentText exporter is still in development. For up to date
-information, please follow Org mailing list @email{emacs-orgmode@@gnu.org}
-closely.
+The ODT exporter relies on two files for generating its output.
+These files are bundled with the distribution under the directory pointed to
+by the variable @code{org-odt-styles-dir}. The two files are:
+
+@itemize
+@anchor{x-orgodtstyles-xml}
+@item
+@file{OrgOdtStyles.xml}
+
+This file contributes to the @file{styles.xml} file of the final @samp{ODT}
+document. This file gets modified for the following purposes:
+@enumerate
+
+@item
+To control outline numbering based on user settings.
+
+@item
+To add styles generated by @file{htmlfontify.el} for fontification of code
+blocks.
+@end enumerate
+
+@anchor{x-orgodtcontenttemplate-xml}
+@item
+@file{OrgOdtContentTemplate.xml}
+
+This file contributes to the @file{content.xml} file of the final @samp{ODT}
+document. The contents of the Org outline are inserted between the
+@samp{<office:text>}@dots{}@samp{</office:text>} elements of this file.
+
+Apart from serving as a template file for the final @file{content.xml}, the
+file serves the following purposes:
+@enumerate
+
+@item
+It contains automatic styles for formatting of tables which are referenced by
+the exporter.
+
+@item
+It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
+elements that control how various entities - tables, images, equations etc -
+are numbered.
+@end enumerate
+@end itemize
+
+@anchor{x-overriding-factory-styles}
+@subsubheading Overriding factory styles
+The following two variables control the location from which the ODT
+exporter picks up the custom styles and content template files. You can
+customize these variables to override the factory styles used by the
+exporter.
+
+@itemize
+@anchor{x-org-export-odt-styles-file}
+@item
+@code{org-export-odt-styles-file}
+
+Use this variable to specify the @file{styles.xml} that will be used in the
+final output. You can specify one of the following values:
+
+@enumerate
+@item A @file{styles.xml} file
+
+Use this file instead of the default @file{styles.xml}
+
+@item A @file{.odt} or @file{.ott} file
+
+Use the @file{styles.xml} contained in the specified OpenDocument Text or
+Template file
+
+@item A @file{.odt} or @file{.ott} file and a subset of files contained within them
+
+Use the @file{styles.xml} contained in the specified OpenDocument Text or
+Template file. Additionally extract the specified member files and embed
+those within the final @samp{ODT} document.
+
+Use this option if the @file{styles.xml} file references additional files
+like header and footer images.
+
+@item @code{nil}
+
+Use the default @file{styles.xml}
+@end enumerate
+
+@anchor{x-org-export-odt-content-template-file}
+@item
+@code{org-export-odt-content-template-file}
+
+Use this variable to specify the blank @file{content.xml} that will be used
+in the final output.
+@end itemize
+
+@node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export
+@subsubsection Creating one-off styles
+
+There are times when you would want one-off formatting in the exported
+document. You can achieve this by embedding raw OpenDocument XML in the Org
+file. The use of this feature is better illustrated with couple of examples.
+
+@enumerate
+@item Embedding ODT tags as part of regular text
+
+You can include simple OpenDocument tags by prefixing them with
+@samp{@@}. For example, to highlight a region of text do the following:
+
+@example
+@@<text:span text:style-name="Highlight">This is a
+highlighted text@@</text:span>. But this is a
+regular text.
+@end example
+
+@strong{Hint:} To see the above example in action, edit your
+@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
+custom @samp{Highlight} style as shown below.
+
+@example
+<style:style style:name="Highlight" style:family="text">
+ <style:text-properties fo:background-color="#ff0000"/>
+</style:style>
+@end example
+
+@item Embedding a one-line OpenDocument XML
+
+You can add a simple OpenDocument one-liner using the @code{#+ODT:}
+directive. For example, to force a page break do the following:
+
+@example
+#+ODT: <text:p text:style-name="PageBreak"/>
+@end example
+
+@strong{Hint:} To see the above example in action, edit your
+@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
+custom @samp{PageBreak} style as shown below.
+
+@example
+<style:style style:name="PageBreak" style:family="paragraph"
+ style:parent-style-name="Text_20_body">
+ <style:paragraph-properties fo:break-before="page"/>
+</style:style>
+@end example
+
+@item Embedding a block of OpenDocument XML
+
+You can add a large block of OpenDocument XML using the
+@code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct.
+
+For example, to create a one-off paragraph that uses bold text, do the
+following:
+
+@example
+#+BEGIN_ODT
+<text:p text:style-name="Text_20_body_20_bold">
+This paragraph is specially formatted and uses bold text.
+</text:p>
+#+END_ODT
+@end example
+
+@end enumerate
+
+@node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export
+@subsubsection Customizing tables in ODT export
+@cindex tables, in ODT export
+
+@cindex #+ATTR_ODT
+You can override the default formatting of the table by specifying a custom
+table style with the @code{#+ATTR_ODT} line. For a discussion on default
+formatting of tables @pxref{Tables in ODT export}.
+
+This feature closely mimics the way table templates are defined in the
+OpenDocument-v1.2
+specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
+OpenDocument-v1.2 Specification}}
+
+
+
+@subsubheading Custom table styles - an illustration
+
+To have a quick preview of this feature, install the below setting and export
+the table that follows.
+
+@lisp
+(setq org-export-odt-table-styles
+ (append org-export-odt-table-styles
+ '(("TableWithHeaderRowAndColumn" "Custom"
+ ((use-first-row-styles . t)
+ (use-first-column-styles . t)))
+ ("TableWithFirstRowandLastRow" "Custom"
+ ((use-first-row-styles . t)
+ (use-last-row-styles . t))))))
+@end lisp
+
+@example
+#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
+| Name | Phone | Age |
+| Peter | 1234 | 17 |
+| Anna | 4321 | 25 |
+@end example
+
+In the above example, you used a template named @samp{Custom} and installed
+two table styles with the names @samp{TableWithHeaderRowAndColumn} and
+@samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument
+styles needed for producing the above template have been pre-defined for you.
+These styles are available under the section marked @samp{Custom Table
+Template} in @file{OrgOdtContentTemplate.xml}
+(@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need
+additional templates you have to define these styles yourselves.
+
+@subsubheading Custom table styles - the nitty-gritty
+To use this feature proceed as follows:
+
+@enumerate
+@item
+Create a table template@footnote{See the @code{<table:table-template>}
+element of the OpenDocument-v1.2 specification}
+
+A table template is nothing but a set of @samp{table-cell} and
+@samp{paragraph} styles for each of the following table cell categories:
+
+@itemize @minus
+@item Body
+@item First column
+@item Last column
+@item First row
+@item Last row
+@item Even row
+@item Odd row
+@item Even column
+@item Odd Column
+@end itemize
+
+The names for the above styles must be chosen based on the name of the table
+template using a well-defined convention.
+
+The naming convention is better illustrated with an example. For a table
+template with the name @samp{Custom}, the needed style names are listed in
+the following table.
+
+@multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
+@headitem Table cell type
+@tab @code{table-cell} style
+@tab @code{paragraph} style
+@item
+@tab
+@tab
+@item Body
+@tab @samp{CustomTableCell}
+@tab @samp{CustomTableParagraph}
+@item First column
+@tab @samp{CustomFirstColumnTableCell}
+@tab @samp{CustomFirstColumnTableParagraph}
+@item Last column
+@tab @samp{CustomLastColumnTableCell}
+@tab @samp{CustomLastColumnTableParagraph}
+@item First row
+@tab @samp{CustomFirstRowTableCell}
+@tab @samp{CustomFirstRowTableParagraph}
+@item Last row
+@tab @samp{CustomLastRowTableCell}
+@tab @samp{CustomLastRowTableParagraph}
+@item Even row
+@tab @samp{CustomEvenRowTableCell}
+@tab @samp{CustomEvenRowTableParagraph}
+@item Odd row
+@tab @samp{CustomOddRowTableCell}
+@tab @samp{CustomOddRowTableParagraph}
+@item Even column
+@tab @samp{CustomEvenColumnTableCell}
+@tab @samp{CustomEvenColumnTableParagraph}
+@item Odd column
+@tab @samp{CustomOddColumnTableCell}
+@tab @samp{CustomOddColumnTableParagraph}
+@end multitable
+
+To create a table template with the name @samp{Custom}, define the above
+styles in the
+@code{<office:automatic-styles>}...@code{</office:automatic-styles>} element
+of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory
+styles}).
+
+@item
+Define a table style@footnote{See the attributes @code{table:template-name},
+@code{table:use-first-row-styles}, @code{table:use-last-row-styles},
+@code{table:use-first-column-styles}, @code{table:use-last-column-styles},
+@code{table:use-banding-rows-styles}, and
+@code{table:use-banding-column-styles} of the @code{<table:table>} element in
+the OpenDocument-v1.2 specification}
+
+@vindex org-export-odt-table-styles
+To define a table style, create an entry for the style in the variable
+@code{org-export-odt-table-styles} and specify the following:
+
+@itemize @minus
+@item the name of the table template created in step (1)
+@item the set of cell styles in that template that are to be activated
+@end itemize
+
+For example, the entry below defines two different table styles
+@samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
+based on the same template @samp{Custom}. The styles achieve their intended
+effect by selectively activating the individual cell styles in that template.
+
+@lisp
+(setq org-export-odt-table-styles
+ (append org-export-odt-table-styles
+ '(("TableWithHeaderRowAndColumn" "Custom"
+ ((use-first-row-styles . t)
+ (use-first-column-styles . t)))
+ ("TableWithFirstRowandLastRow" "Custom"
+ ((use-first-row-styles . t)
+ (use-last-row-styles . t))))))
+@end lisp
+
+@item
+Associate a table with the table style
+
+To do this, specify the table style created in step (2) as part of
+the @code{ATTR_ODT} line as shown below.
+
+@example
+#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
+| Name | Phone | Age |
+| Peter | 1234 | 17 |
+| Anna | 4321 | 25 |
+@end example
+@end enumerate
+
+@node Validating OpenDocument XML, , Customizing tables in ODT export, Advanced topics in ODT export
+@subsubsection Validating OpenDocument XML
+
+Occasionally, you will discover that the document created by the
+ODT exporter cannot be opened by your favorite application. One of
+the common reasons for this is that the @file{.odt} file is corrupt. In such
+cases, you may want to validate the document against the OpenDocument RELAX
+NG Compact Syntax (RNC) schema.
+
+For de-compressing the @file{.odt} file@footnote{@file{.odt} files are
+nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For
+general help with validation (and schema-sensitive editing) of XML files:
+@inforef{Introduction,,nxml-mode}.
+
+@vindex org-export-odt-schema-dir
+If you have ready access to OpenDocument @file{.rnc} files and the needed
+schema-locating rules in a single folder, you can customize the variable
+@code{org-export-odt-schema-dir} to point to that directory. The
+ODT exporter will take care of updating the
+@code{rng-schema-locating-files} for you.
@c end opendocument
-@node TaskJuggler export, Freemind export, OpenDocumentText export, Exporting
+@node TaskJuggler export, Freemind export, OpenDocument Text export, Exporting
@section TaskJuggler export
@cindex TaskJuggler export
@cindex Project management
you have provided.
The TaskJuggler exporter is a bit different from other exporters, such as the
-HTML and LaTeX exporters for example, in that it does not export all the
+@code{HTML} and @LaTeX{} exporters for example, in that it does not export all the
nodes of a document or strictly follow the order of the nodes in the
document.
@subsection Tasks
@vindex org-export-taskjuggler-project-tag
-Create your tasks as you usually do with Org-mode. Assign efforts to each
+Create your tasks as you usually do with Org mode. Assign efforts to each
task using properties (it is easiest to do this in the column view). You
should end up with something similar to the example by Peter Jones in
@url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}.
@section XOXO export
@cindex XOXO export
-Org-mode contains an exporter that produces XOXO-style output.
+Org mode contains an exporter that produces XOXO-style output.
Currently, this exporter only handles the general outline structure and
-does not interpret any additional Org-mode features.
+does not interpret any additional Org mode features.
@table @kbd
@orgcmd{C-c C-e x,org-export-as-xoxo}
@vindex org-icalendar-use-scheduled
@vindex org-icalendar-categories
@vindex org-icalendar-alarm-time
-Some people use Org-mode for keeping track of projects, but still prefer a
+Some people use Org mode for keeping track of projects, but still prefer a
standard calendar application for anniversaries and appointments. In this
case it can be useful to show deadlines and other time-stamped items in Org
-files in the calendar application. Org-mode can export calendar information
+files in the calendar application. Org mode can export calendar information
in the standard iCalendar format. If you also want to have TODO entries
included in the export, configure the variable
@code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT,
@tab Should sorting be case-sensitive? Default @code{nil}.
@item @code{:sitemap-file-entry-format}
-@tab With this option one can tell how a sitemap's entry is formated in the
+@tab With this option one can tell how a sitemap's entry is formatted in the
sitemap. This is a format string with some escape sequences: @code{%t} stands
for the title of the file, @code{%a} stands for the author of the file and
@code{%d} stands for the date of the file. The date is retrieved with the
-@code{org-publish-find-date} function and formated with
+@code{org-publish-find-date} function and formatted with
@code{org-publish-sitemap-date-format}. Default @code{%t}.
@item @code{:sitemap-date-format}
@tab Format string for the @code{format-time-string} function that tells how
-a sitemap entry's date is to be formated. This property bypasses
+a sitemap entry's date is to be formatted. This property bypasses
@code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
@item @code{:sitemap-sans-extension}
@subsection Generating an index
@cindex index, in a publishing project
-Org-mode can generate an index across the files of a publishing project.
+Org mode can generate an index across the files of a publishing project.
@multitable @columnfractions 0.25 0.75
@item @code{:makeindex}
For those people already utilizing third party sync tools such as
@command{rsync} or @command{unison}, it might be preferable not to use the built in
-@i{remote} publishing facilities of Org-mode which rely heavily on
+@i{remote} publishing facilities of Org mode which rely heavily on
Tramp. Tramp, while very useful and powerful, tends not to be
so efficient for multiple file transfer and has been known to cause problems
under heavy usage.
@cindex Davison, Dan
@cindex source code, working with
-Source code can be included in Org-mode documents using a @samp{src} block,
+Source code can be included in Org mode documents using a @samp{src} block,
e.g.@:
@example
#+END_SRC
@end example
-Org-mode provides a number of features for working with live source code,
+Org mode provides a number of features for working with live source code,
including editing of code blocks in their native major-mode, evaluation of
code blocks, converting code blocks into source files (known as @dfn{tangling}
in literate programming), and exporting code blocks and their
results in several formats. This functionality was contributed by Eric
Schulte and Dan Davison, and was originally named Org-babel.
-The following sections describe Org-mode's code block handling facilities.
+The following sections describe Org mode's code block handling facilities.
@menu
* Structure of code blocks:: Code block syntax described
* Editing source code:: Language major-mode editing
* Exporting code blocks:: Export contents and/or results
* Extracting source code:: Create pure source code files
-* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer
+* Evaluating code blocks:: Place results of evaluation in the Org mode buffer
* Library of Babel:: Use and contribute to a library of useful code blocks
* Languages:: List of supported code block languages
* Header arguments:: Configure code block functionality
* Results of evaluation:: How evaluation results are handled
-* Noweb reference syntax:: Literate programming in Org-mode
+* Noweb reference syntax:: Literate programming in Org mode
* Key bindings and useful functions:: Work quickly with code blocks
* Batch execution:: Call functions from the command line
@end menu
@section Structure of code blocks
@cindex code block, structure
@cindex source code, block structure
+@cindex #+NAME
+@cindex #+BEGIN_SRC
-The structure of code blocks is as follows:
+Live code blocks can be specified with a @samp{src} block or
+inline.@footnote{Note that @samp{src} blocks may be inserted using Org mode's
+@ref{Easy Templates} system} The structure of a @samp{src} block is
@example
-#+srcname: <name>
-#+begin_src <language> <switches> <header arguments>
+#+NAME: <name>
+#+BEGIN_SRC <language> <switches> <header arguments>
<body>
-#+end_src
+#+END_SRC
@end example
-Switches and header arguments are optional. Code can also be embedded in text
-inline using
+The @code{#+NAME:} line is optional, and can be used to name the code
+block. Live code blocks require that a language be specified on the
+@code{#+BEGIN_SRC} line. Switches and header arguments are optional.
+@cindex source code, inline
+
+Live code blocks can also be specified inline using
@example
src_<language>@{<body>@}
@end example
@table @code
-@item <name>
-This name is associated with the code block. This is similar to the
-@samp{#+tblname} lines that can be used to name tables in Org-mode files.
-Referencing the name of a code block makes it possible to evaluate the
-block from other places in the file, other files, or from Org-mode table
-formulas (see @ref{The spreadsheet}). Names are assumed to be unique by
-evaluation functions and the behavior of multiple blocks of the same name is
+@item <#+NAME: name>
+This line associates a name with the code block. This is similar to the
+@code{#+TBLNAME: NAME} lines that can be used to name tables in Org mode
+files. Referencing the name of a code block makes it possible to evaluate
+the block from other places in the file, from other files, or from Org mode
+table formulas (see @ref{The spreadsheet}). Names are assumed to be unique
+and the behavior of Org mode when two or more blocks share the same name is
undefined.
+@cindex #+NAME
@item <language>
-The language of the code in the block.
+The language of the code in the block (see @ref{Languages}).
+@cindex source code, language
@item <switches>
-Optional switches controlling exportation of the code block (see switches discussion in
+Optional switches control code block export (see the discussion of switches in
@ref{Literal examples})
+@cindex source code, switches
@item <header arguments>
Optional header arguments control many aspects of evaluation, export and
-tangling of code blocks. See the @ref{Header arguments}.
+tangling of code blocks (see @ref{Header arguments}).
Header arguments can also be set on a per-buffer or per-subtree
basis using properties.
+@item source code, header arguments
@item <body>
-The source code.
+Source code in the specified language.
@end table
@comment node-name, next, previous, up
@cindex code block, exporting
@cindex source code, exporting
-It is possible to export the @emph{contents} of code blocks, the
-@emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For
-most languages, the default exports the contents of code blocks. However, for
-some languages (e.g.@: @code{ditaa}) the default exports the results of code
-block evaluation. For information on exporting code block bodies, see
-@ref{Literal examples}.
+It is possible to export the @emph{code} of code blocks, the @emph{results}
+of code block evaluation, @emph{both} the code and the results of code block
+evaluation, or @emph{none}. For most languages, the default exports code.
+However, for some languages (e.g.@: @code{ditaa}) the default exports the
+results of code block evaluation. For information on exporting code block
+bodies, see @ref{Literal examples}.
The @code{:exports} header argument can be used to specify export
behavior:
described in @ref{Literal examples}.
@item :exports results
The code block will be evaluated and the results will be placed in the
-Org-mode buffer for export, either updating previous results of the code
+Org mode buffer for export, either updating previous results of the code
block located anywhere in the buffer or, if no previous results exist,
placing the results immediately after the code block. The body of the code
block will not be exported.
It is possible to inhibit the evaluation of code blocks during export.
Setting the @code{org-export-babel-evaluate} variable to @code{nil} will
ensure that no code blocks are evaluated as part of the export process. This
-can be useful in situations where potentially untrusted Org-mode files are
-exported in an automated fashion, for example when Org-mode is used as the
+can be useful in situations where potentially untrusted Org mode files are
+exported in an automated fashion, for example when Org mode is used as the
markup language for a wiki.
@comment node-name, next, previous, up
@section Evaluating code blocks
@cindex code block, evaluating
@cindex source code, evaluating
+@cindex #+RESULTS
Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
-potential for that code to do harm. Org-mode provides a number of safeguards
-to ensure that it only evaluates code with explicit confirmation from the
-user. For information on these safeguards (and on how to disable them) see
-@ref{Code evaluation security}.} and the results placed in the Org-mode
-buffer. By default, evaluation is only turned on for @code{emacs-lisp} code
-blocks, however support exists for evaluating blocks in many languages. See
-@ref{Languages} for a list of supported languages. See @ref{Structure of
-code blocks} for information on the syntax used to define a code block.
+potential for that code to do harm. Org mode provides safeguards to ensure
+that code is only evaluated after explicit confirmation from the user. For
+information on these safeguards (and on how to disable them) see @ref{Code
+evaluation security}.} and the results of evaluation optionally placed in the
+Org mode buffer. The results of evaluation are placed following a line that
+begins by default with @code{#+RESULTS} and optionally a cache identifier
+and/or the name of the evaluated code block. The default value of
+@code{#+RESULTS} can be changed with the customizable variable
+@code{org-babel-results-keyword}.
+
+By default, the evaluation facility is only enabled for Lisp code blocks
+specified as @code{emacs-lisp}. However, source code blocks in many languages
+can be evaluated within Org mode (see @ref{Languages} for a list of supported
+languages and @ref{Structure of code blocks} for information on the syntax
+used to define a code block).
@kindex C-c C-c
There are a number of ways to evaluate code blocks. The simplest is to press
@code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code
evaluation from the @kbd{C-c C-c} key binding.}. This will call the
@code{org-babel-execute-src-block} function to evaluate the block and insert
-its results into the Org-mode buffer.
+its results into the Org mode buffer.
+@cindex #+CALL
It is also possible to evaluate named code blocks from anywhere in an
-Org-mode buffer or an Org-mode table. @code{#+call} (or synonymously
-@code{#+function} or @code{#+lob}) lines can be used to remotely execute code
-blocks located in the current Org-mode buffer or in the ``Library of Babel''
-(see @ref{Library of Babel}). These lines use the following syntax to place
-a call on a line by itself.
+Org mode buffer or an Org mode table. Live code blocks located in the current
+Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel})
+can be executed. Named code blocks can be executed with a separate
+@code{#+CALL:} line or inline within a block of text.
+
+The syntax of the @code{#+CALL:} line is
@example
-#+
call: <name>(<arguments>)
-#+call: <name>[<header args>](<arguments>) <header args>
+#+
CALL: <name>(<arguments>)
+#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
@end example
-The following syntax can be used to place these calls within a block of
-prose.
+The syntax for inline evaluation of named code blocks is
@example
-...prose... call_<name>(<arguments>) ...prose...
-...prose... call_<name>[<header args>](<arguments>)[<header args>] ...prose...
+... call_<name>(<arguments>) ...
+... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
@end example
@table @code
@item <name>
-The name of the code block to be evaluated.
+The name of the code block to be evaluated (see @ref{Structure of code blocks}).
@item <arguments>
Arguments specified in this section will be passed to the code block. These
-arguments should relate to @code{:var} header arguments in the called code
-block expressed using standard function call syntax. For example if the
-original code block named @code{double} has the header argument @code{:var
-n=2}, then the call line passing the number four to that block would be
-written as @code{#+call: double(n=2)}.
-@item <header args>
-Header arguments can be placed either inside the call to the code block or at
-the end of the line as shown below.
-
-@example
-#+call: code_bloc_name[XXXX](arguments) YYYY
-@end example
-
-Header arguments located in these two locations are treated differently.
-
-@table @code
-@item XXXX
-Those placed in the @code{XXXX} location are passed through and applied to
-the code block being called. These header arguments affect how the code
-block is evaluated, for example @code{[:results output]} will collect the
-results from @code{STDOUT} of the called code block.
-@item YYYY
-Those placed in the @code{YYYY} location are applied to the call line and do
-not affect the code block being called. These header arguments affect how
-the results are incorporated into the Org-mode buffer when the call line is
-evaluated, and how the call line is exported. For example @code{:results
-org} at the end of the call line will insert the results of the call line
-inside of an Org-mode block.
-@end table
-
-For more examples of passing header arguments to @code{#+call:} lines see
+arguments use standard function call syntax, rather than
+header argument syntax. For example, a @code{#+CALL:} line that passes the
+number four to a code block named @code{double}, which declares the header
+argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}.
+@item <inside header arguments>
+Inside header arguments are passed through and applied to the named code
+block. These arguments use header argument syntax rather than standard
+function call syntax. Inside header arguments affect how the code block is
+evaluated. For example, @code{[:results output]} will collect the results of
+everything printed to @code{STDOUT} during execution of the code block.
+@item <end header arguments>
+End header arguments are applied to the calling instance and do not affect
+evaluation of the named code block. They affect how the results are
+incorporated into the Org mode buffer and how the call line is exported. For
+example, @code{:results html} will insert the results of the call line
+evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block.
+
+For more examples of passing header arguments to @code{#+CALL:} lines see
@ref{Header arguments in function calls}.
@end table
@cindex source code, library
@cindex code block, library
-The ``Library of Babel'' is a library of code blocks
-that can be called from any Org-mode file. The library is housed in an
-Org-mode file located in the @samp{contrib} directory of Org-mode.
-Org-mode users can deposit functions they believe to be generally
-useful in the library.
+The ``Library of Babel'' consists of code blocks that can be called from any
+Org mode file. Code blocks defined in the ``Library of Babel'' can be called
+remotely as if they were in the current Org mode buffer (see @ref{Evaluating
+code blocks} for information on the syntax of remote code block evaluation).
+
+
+The central repository of code blocks in the ``Library of Babel'' is housed
+in an Org mode file located in the @samp{contrib} directory of Org mode.
+
+Users can add code blocks they believe to be generally useful to their
+``Library of Babel.'' The code blocks can be stored in any Org mode file and
+then loaded into the library with @code{org-babel-lob-ingest}.
-Code blocks defined in the ``Library of Babel'' can be called remotely as if
-they were in the current Org-mode buffer (see @ref{Evaluating code blocks}
-for information on the syntax of remote code block evaluation).
@kindex C-c C-v i
-Code blocks located in any Org-mode file can be loaded into the ``Library of
+Code blocks located in any Org mode file can be loaded into the ``Library of
Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v
i}.
@item Ledger @tab ledger @tab Lisp @tab lisp
@item Lilypond @tab lilypond @tab MATLAB @tab matlab
@item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
-@item Octave @tab octave @tab Org-mode @tab org
+@item Octave @tab octave @tab Org mode @tab org
@item Oz @tab oz @tab Perl @tab perl
@item Plantuml @tab plantuml @tab Python @tab python
@item R @tab R @tab Ruby @tab ruby
* System-wide header arguments:: Set global default values
* Language-specific header arguments:: Set default values by language
* Buffer-wide header arguments:: Set default values for a specific buffer
-* Header arguments in Org-mode properties:: Set default values for a buffer or heading
+* Header arguments in Org mode properties:: Set default values for a buffer or heading
* Code block specific header arguments:: The most common way to set values
* Header arguments in function calls:: The most specific level
@end menu
language-specific documentation available online at
@uref{http://orgmode.org/worg/org-contrib/babel}.
-@node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments
+@node Buffer-wide header arguments, Header arguments in Org mode properties, Language-specific header arguments, Using header arguments
@subsubheading Buffer-wide header arguments
-Buffer-wide header arguments may be specified through the use of a special
-line placed anywhere in an Org-mode file. The line consists of the
-@code{#+BABEL:} keyword followed by a series of header arguments which may be
-specified using the standard header argument syntax.
+Buffer-wide header arguments may be specified as properties through the use
+of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see
+@ref{Property syntax}).
For example the following would set @code{session} to @code{*R*}, and
@code{results} to @code{silent} for every code block in the buffer, ensuring
inserted into the buffer.
@example
-#+BABEL: :session *R* :results silent
+#+PROPERTY: session *R*
+#+PROPERTY: results silent
@end example
-@node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments
-@subsubheading Header arguments in Org-mode properties
+@node Header arguments in Org mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments
+@subsubheading Header arguments in Org mode properties
-Header arguments are also read from Org-mode properties (see @ref{Property
+Header arguments are also read from Org mode properties (see @ref{Property
syntax}), which can be set on a buffer-wide or per-heading basis. An example
of setting a header argument for all code blocks in a buffer is
@example
-#+property: tangle yes
+#+PROPERTY: tangle yes
@end example
+@vindex org-use-property-inheritance
When properties are used to set default header arguments, they are looked up
-with inheritance, so the value of the @code{:cache} header argument will default
-to @code{yes} in all code blocks in the subtree rooted at the following
-heading:
+with inheritance, regardless of the value of
+@code{org-use-property-inheritance}. In the following example the value of
+the @code{:cache} header argument will default to @code{yes} in all code
+blocks in the subtree rooted at the following heading:
@example
* outline header
Properties defined in this way override the properties set in
@code{org-babel-default-header-args}. It is convenient to use the
@code{org-set-property} function bound to @kbd{C-c C-x p} to set properties
-in Org-mode documents.
+in Org mode documents.
-@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org-mode properties, Using header arguments
+@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org mode properties, Using header arguments
@subsubheading Code block specific header arguments
The most common way to assign values to header arguments is at the
code block level. This can be done by listing a sequence of header
-arguments and their values as part of the @code{#+begin_src} line.
+arguments and their values as part of the @code{#+BEGIN_SRC} line.
Properties set in this way override both the values of
@code{org-babel-default-header-args} and header arguments specified as
properties. In the following example, the @code{:results} header argument
is set to @code{silent}, meaning the results of execution will not be
inserted in the buffer, and the @code{:exports} header argument is set to
@code{code}, meaning only the body of the code block will be
-preserved on export to HTML or LaTeX.
+preserved on export to HTML or @LaTeX{}.
@example
-#+source: factorial
-#+begin_src haskell :results silent :exports code :var n=0
+#+NAME: factorial
+#+BEGIN_SRC haskell :results silent :exports code :var n=0
fac 0 = 1
fac n = n * fac (n-1)
-#+end_src
+#+END_SRC
@end example
-Similarly, it is possible to set header arguments for inline code blocks:
+Similarly, it is possible to set header arguments for inline code blocks
@example
src_haskell[:exports both]@{fac 5@}
@end example
-Code block header arguments can span multiple lines using =#+header:= or
-=#+headers:= lines preceding a code block or nested in between the name and
-body of a named code block.
+Code block header arguments can span multiple lines using @code{#+HEADER:} or
+@code{#+HEADERS:} lines preceding a code block or nested between the
+@code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block.
+@cindex #+HEADER:
+@cindex #+HEADERS:
Multi-line header arguments on an un-named code block:
@example
- #+headers: :var data1=1
- #+begin_src emacs-lisp :var data2=2
+ #+HEADERS: :var data1=1
+ #+BEGIN_SRC emacs-lisp :var data2=2
(message "data1:%S, data2:%S" data1 data2)
- #+end_src
+ #+END_SRC
#+results:
: data1:1, data2:2
Multi-line header arguments on a named code block:
@example
- #+source: named-block
- #+header: :var data=2
- #+begin_src emacs-lisp
+ #+NAME: named-block
+ #+HEADER: :var data=2
+ #+BEGIN_SRC emacs-lisp
(message "data:%S" data)
- #+end_src
+ #+END_SRC
#+results: named-block
: data:2
@subsubheading Header arguments in function calls
At the most specific level, header arguments for ``Library of Babel'' or
-function call lines can be set as shown in the two examples below. For more
-information on the structure of @code{#+call:} lines see @ref{Evaluating code
+@code{#+CALL:} lines can be set as shown in the two examples below. For more
+information on the structure of @code{#+CALL:} lines see @ref{Evaluating code
blocks}.
The following will apply the @code{:exports results} header argument to the
-evaluation of the @code{#+call:} line.
+evaluation of the @code{#+CALL:} line.
@example
-#+call: factorial(n=5) :exports results
+#+CALL: factorial(n=5) :exports results
@end example
The following will apply the @code{:session special} header argument to the
evaluation of the @code{factorial} code block.
@example
-#+call: factorial[:session special](n=5)
+#+CALL: factorial[:session special](n=5)
@end example
@node Specific header arguments, , Using header arguments, Header arguments
@subsection Specific header arguments
-The following header arguments are defined:
+Header arguments consist of an initial colon followed by the name of the
+argument in lowercase letters. The following header arguments are defined:
@menu
* var:: Pass arguments to code blocks
* session:: Preserve the state of code evaluation
* noweb:: Toggle expansion of noweb references
* noweb-ref:: Specify block's noweb reference resolution target
+* noweb-sep:: String used to separate noweb references
* cache:: Avoid re-evaluating unchanged code blocks
* sep:: Delimiter for writing tabular results outside Org
* hlines:: Handle horizontal lines in tables
The @code{:var} header argument is used to pass arguments to code blocks.
The specifics of how arguments are included in a code block vary by language;
these are addressed in the language-specific documentation. However, the
-syntax used to specify arguments is the same across all languages. The
-values passed to arguments can be literal values, values from org-mode tables
-and literal example blocks, the results of other code blocks, or Emacs Lisp
-code---see the ``Emacs Lisp evaluation of variables'' heading below.
+syntax used to specify arguments is the same across all languages. In every
+case, variables require a default value when they are declared.
-These values can be indexed in a manner similar to arrays---see the
-``indexable variable values'' heading below.
+The values passed to arguments can either be literal values, references, or
+Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). References
+include anything in the Org mode file that takes a @code{#+NAME:},
+@code{#+TBLNAME:}, or @code{#+RESULTS:} line. This includes tables, lists,
+@code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other
+code blocks.
+
+Argument values can be indexed in a manner similar to arrays (see @ref{var,
+Indexable variable values}).
The following syntax is used to pass arguments to code blocks using the
@code{:var} header argument.
:var name=assign
@end example
-where @code{assign} can take one of the following forms
+The argument, @code{assign}, can either be a literal value, such as a string
+@samp{"string"} or a number @samp{9}, or a reference to a table, a list, a
+literal example, another code block (with or without arguments), or the
+results of evaluating another code block.
-@itemize @bullet
-@item literal value
-either a string @code{"string"} or a number @code{9}.
-@item reference
-a table name:
+Here are examples of passing values by reference:
+@table @dfn
+
+@item table
+an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line
@example
-#+tblname: example-table
+#+TBLNAME: example-table
| 1 |
| 2 |
| 3 |
| 4 |
-#+source: table-length
-#+begin_src emacs-lisp :var table=example-table
+#+NAME: table-length
+#+BEGIN_SRC emacs-lisp :var table=example-table
(length table)
-#+end_src
+#+END_SRC
#+results: table-length
: 4
@end example
-a code block name, as assigned by @code{#+srcname:}, followed by
-parentheses:
+@item list
+a simple list named with a @code{#+NAME:} line (note that nesting is not
+carried through to the source code block)
+
+@example
+#+NAME: example-list
+ - simple
+ - not
+ - nested
+ - list
+
+#+BEGIN_SRC emacs-lisp :var x=example-list
+ (print x)
+#+END_SRC
+
+#+results:
+| simple | list |
+@end example
+
+@item code block without arguments
+a code block name (from the example above), as assigned by @code{#+NAME:},
+optionally followed by parentheses
@example
-#+begin_src emacs-lisp :var length=table-length()
+#+BEGIN_SRC emacs-lisp :var length=table-length()
(* 2 length)
-#+end_src
+#+END_SRC
#+results:
: 8
@end example
-In addition, an argument can be passed to the code block referenced
-by @code{:var}. The argument is passed within the parentheses following the
-code block name:
+@item code block with arguments
+a code block name, as assigned by @code{#+NAME:}, followed by parentheses and
+optional arguments passed within the parentheses following the
+code block name using standard function call syntax
@example
-#+source: double
-#+begin_src emacs-lisp :var input=8
+#+NAME: double
+#+BEGIN_SRC emacs-lisp :var input=8
(* 2 input)
-#+end_src
+#+END_SRC
#+results: double
: 16
-#+source: squared
-#+begin_src emacs-lisp :var input=double(input=1)
+#+NAME: squared
+#+BEGIN_SRC emacs-lisp :var input=double(input=1)
(* input input)
-#+end_src
+#+END_SRC
#+results: squared
: 4
@end example
-@end itemize
+
+@item literal example
+a literal example block named with a @code{#+NAME:} line
+
+@example
+#+NAME: literal-example
+#+BEGIN_EXAMPLE
+A literal example
+on two lines
+#+END_EXAMPLE
+
+#+NAME: read-literal-example
+#+BEGIN_SRC emacs-lisp :var x=literal-example
+ (concatenate 'string x " for you.")
+#+END_SRC
+
+#+results: read-literal-example
+: A literal example
+: on two lines for you.
+
+@end example
+
+@end table
@subsubheading Alternate argument syntax
It is also possible to specify arguments in a potentially more natural way
-using the @code{#+source:} line of a code block. As in the following
-example arguments can be packed inside of parenthesis, separated by commas,
+using the @code{#+NAME:} line of a code block. As in the following
+example, arguments can be packed inside of parentheses, separated by commas,
following the source name.
@example
-#+source: double(input=0, x=2)
-#+begin_src emacs-lisp
+#+NAME: double(input=0, x=2)
+#+BEGIN_SRC emacs-lisp
(* 2 (+ input x))
-#+end_src
+#+END_SRC
@end example
@subsubheading Indexable variable values
@code{example-table} to the variable @code{data}:
@example
-#+results: example-table
+#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |
-#+begin_src emacs-lisp :var data=example-table[0,-1]
+#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
data
-#+end_src
+#+END_SRC
#+results:
: a
to @code{data}.
@example
-#+results: example-table
+#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |
| 5 | 3 |
-#+begin_src emacs-lisp :var data=example-table[1:3]
+#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
data
-#+end_src
+#+END_SRC
#+results:
| 2 | b |
column is referenced.
@example
-#+results: example-table
+#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |
-#+begin_src emacs-lisp :var data=example-table[,0]
+#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
data
-#+end_src
+#+END_SRC
#+results:
| 1 | 2 | 3 | 4 |
another by commas, as shown in the following example.
@example
-#+source: 3D
-#+begin_src emacs-lisp
+#+NAME: 3D
+#+BEGIN_SRC emacs-lisp
'(((1 2 3) (4 5 6) (7 8 9))
((10 11 12) (13 14 15) (16 17 18))
((19 20 21) (22 23 24) (25 26 27)))
-#+end_src
+#+END_SRC
-#+begin_src emacs-lisp :var data=3D[1,,1]
+#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
data
-#+end_src
+#+END_SRC
#+results:
| 11 | 14 | 17 |
@subsubheading Emacs Lisp evaluation of variables
Emacs lisp code can be used to initialize variable values. When a variable
-value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be evaluated as
-Emacs Lisp and the result of the evaluation will be assigned as the variable
-value. The following example demonstrates use of this evaluation to reliably
-pass the file-name of the org-mode buffer to a code block---note that
-evaluation of header arguments is guaranteed to take place in the original
-org-mode file, while there is no such guarantee for evaluation of the code
-block body.
+value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be
+evaluated as Emacs Lisp and the result of the evaluation will be assigned as
+the variable value. The following example demonstrates use of this
+evaluation to reliably pass the file-name of the Org mode buffer to a code
+block---note that evaluation of header arguments is guaranteed to take place
+in the original Org mode file, while there is no such guarantee for
+evaluation of the code block body.
@example
-#+begin_src sh :var filename=(buffer-file-name) :exports both
+#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
wc -w $filename
-#+end_src
+#+END_SRC
@end example
Note that values read from tables and lists will not be evaluated as
Emacs Lisp, as shown in the following example.
@example
-#+results: table
+#+NAME: table
| (a b c) |
-#+headers: :var data=table[0,0]
-#+begin_src perl
+#+HEADERS: :var data=table[0,0]
+#+BEGIN_SRC perl
$data
-#+end_src
+#+END_SRC
#+results:
: (a b c)
@item
@b{type} header arguments specify what type of result the code block will
return---which has implications for how they will be inserted into the
-Org-mode buffer
+Org mode buffer
@item
@b{handling} header arguments specify how the results of evaluating the code
block should be handled.
@itemize @bullet
@item @code{table}, @code{vector}
-The results should be interpreted as an Org-mode table. If a single value is
+The results should be interpreted as an Org mode table. If a single value is
returned, it will be converted into a table with one row and one column.
E.g., @code{:results value table}.
@item @code{list}
-The results should be interpreted as an Org-mode list. If a single scalar
+The results should be interpreted as an Org mode list. If a single scalar
value is returned it will be converted into a list with only one element.
@item @code{scalar}, @code{verbatim}
The results should be interpreted literally---they will not be
-converted into a table. The results will be inserted into the Org-mode
+converted into a table. The results will be inserted into the Org mode
buffer as quoted text. E.g., @code{:results value verbatim}.
@item @code{file}
The results will be interpreted as the path to a file, and will be inserted
-into the Org-mode buffer as a file link. E.g., @code{:results value file}.
+into the Org mode buffer as a file link. E.g., @code{:results value file}.
@item @code{raw}, @code{org}
-The results are interpreted as raw Org-mode code and are inserted directly
+The results are interpreted as raw Org mode code and are inserted directly
into the buffer. If the results look like a table they will be aligned as
-such by Org-mode. E.g., @code{:results value raw}.
+such by Org mode. E.g., @code{:results value raw}.
@item @code{html}
Results are assumed to be HTML and will be enclosed in a @code{begin_html}
block. E.g., @code{:results value html}.
@item @code{latex}
-Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block.
+Results assumed to be @LaTeX{} and are enclosed in a @code{begin_latex} block.
E.g., @code{:results value latex}.
@item @code{code}
-Result are assumed to be parseable code and are enclosed in a code block.
+Result are assumed to be parsable code and are enclosed in a code block.
E.g., @code{:results value code}.
@item @code{pp}
The result is converted to pretty-printed code and is enclosed in a code
block. This option currently supports Emacs Lisp, Python, and Ruby. E.g.,
@code{:results value pp}.
@item @code{wrap}
-The result is wrapped in a @code{begin_result} block. This can be useful for
+The result is wrapped in a RESULTS drawer. This can be useful for
inserting @code{raw} or @code{org} syntax results in such a way that their
-extend is known and they can be automatically removed or replaced.
+extent is known and they can be automatically removed or replaced.
@end itemize
@subsubheading Handling
@itemize @bullet
@item @code{silent}
The results will be echoed in the minibuffer but will not be inserted into
-the Org-mode buffer. E.g., @code{:results output silent}.
+the Org mode buffer. E.g., @code{:results output silent}.
@item @code{replace}
The default value. Any existing results will be removed, and the new results
-will be inserted into the Org-mode buffer in their place. E.g.,
+will be inserted into the Org mode buffer in their place. E.g.,
@code{:results output replace}.
@item @code{append}
If there are pre-existing results of the code block then the new results will
@subsubsection @code{:file}
The header argument @code{:file} is used to specify an external file in which
-to save code block results. After code block evaluation an Org-mode style
+to save code block results. After code block evaluation an Org mode style
@code{[[file:]]} link (see @ref{Link format}) to the file will be inserted
-into the Org-mode buffer. Some languages including R, gnuplot, dot, and
+into the Org mode buffer. Some languages including R, gnuplot, dot, and
ditaa provide special handling of the @code{:file} header argument
automatically wrapping the code block body in the boilerplate code required
to save output to the specified file. This is often useful for saving
in your home directory, you could use
@example
-#+begin_src R :file myplot.png :dir ~/Work
+#+BEGIN_SRC R :file myplot.png :dir ~/Work
matplot(matrix(rnorm(100), 10), type="l")
-#+end_src
+#+END_SRC
@end example
@subsubheading Remote execution
which case the code will be evaluated on the remote machine. An example is
@example
-#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu:
+#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu:
plot(1:10, main=system("hostname", intern=TRUE))
-#+end_src
+#+END_SRC
@end example
-Text results will be returned to the local Org-mode buffer as usual, and file
+Text results will be returned to the local Org mode buffer as usual, and file
output will be created on the remote machine with relative paths interpreted
-relative to the remote directory. An Org-mode link to the remote file will be
+relative to the remote directory. An Org mode link to the remote file will be
created.
So, in the above example a plot will be created on the remote machine,
@code{:dir} should typically not be used to create files during export with
@code{:exports results} or @code{:exports both}. The reason is that, in order
to retain portability of exported material between machines, during export
-links inserted into the buffer will *not* be expanded against @code{default
+links inserted into the buffer will @emph{not} be expanded against @code{default
directory}. Therefore, if @code{default-directory} is altered using
@code{:dir}, it is probable that the file will be created in a location to
which the link does not point.
@subsubsection @code{:exports}
The @code{:exports} header argument specifies what should be included in HTML
-or LaTeX exports of the Org-mode file.
+or @LaTeX{} exports of the Org mode file.
@itemize @bullet
@item @code{code}
@itemize @bullet
@item @code{tangle}
The code block is exported to a source code file named after the full path
-(including the directory) and file name (w/o extension) of the Org-mode file.
+(including the directory) and file name (w/o extension) of the Org mode file.
E.g., @code{:tangle yes}.
@item @code{no}
The default. The code block is not exported to a source code file.
E.g., @code{:tangle no}.
@item other
Any other string passed to the @code{:tangle} header argument is interpreted
-as a path (directory and file name relative to the directory of the Org-mode
+as a path (directory and file name relative to the directory of the Org mode
file) to which the block will be exported. E.g., @code{:tangle path}.
@end itemize
@item @code{yes}
A synonym for ``link'' to maintain backwards compatibility.
@item @code{org}
-Include text from the org-mode file as a comment.
+Include text from the Org mode file as a comment.
The text is picked from the leading context of the tangled code and is
limited by the nearest headline or source block as the case may be.
All ``noweb'' syntax references in the body of the code block will be
expanded before the block is evaluated, tangled or exported.
@item @code{no}
-The default. No ``noweb'' syntax specific action is taken on evaluating
-code blocks, However, noweb references will still be expanded during
-tangling.
+The default. No ``noweb'' syntax specific action is taken when the code
+block is evaluated, tangled or exported.
@item @code{tangle}
All ``noweb'' syntax references in the body of the code block will be
expanded before the block is tangled, however ``noweb'' references will not
be affected by this change, so it is still possible to use inline noweb
references.
-@node noweb-ref, cache, noweb, Specific header arguments
+@node noweb-ref, noweb-sep, noweb, Specific header arguments
@subsubsection @code{:noweb-ref}
When expanding ``noweb'' style references the bodies of all code block with
@emph{either} a block name matching the reference name @emph{or} a
By setting this header argument at the sub-tree or file level, simple code
block concatenation may be achieved. For example, when tangling the
-following Org-mode file, the bodies of code blocks will be concatenated into
-the resulting pure code file.
+following Org mode file, the bodies of code blocks will be concatenated into
+the resulting pure code file@footnote{(The example needs property inheritance
+to be turned on for the @code{noweb-ref} property, see @ref{Property
+inheritance}).}.
@example
- #+begin_src sh :tangle yes :noweb yes :shebang #!/bin/sh
+ #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
<<fullest-disk>>
- #+end_src
+ #+END_SRC
* the mount point of the fullest disk
:PROPERTIES:
:noweb-ref: fullest-disk
:END:
** query all mounted disks
- #+begin_src sh
+ #+BEGIN_SRC sh
df \
- #+end_src
+ #+END_SRC
** strip the header row
- #+begin_src sh
+ #+BEGIN_SRC sh
|sed '1d' \
- #+end_src
+ #+END_SRC
** sort by the percent full
- #+begin_src sh
+ #+BEGIN_SRC sh
|awk '@{print $5 " " $6@}'|sort -n |tail -1 \
- #+end_src
+ #+END_SRC
** extract the mount point
- #+begin_src sh
+ #+BEGIN_SRC sh
|awk '@{print $2@}'
- #+end_src
+ #+END_SRC
@end example
-@node cache, sep, noweb-ref, Specific header arguments
+The @code{:noweb-sep} (see @ref{noweb-sep}) header argument holds the string
+used to separate accumulate noweb references like those above. By default a
+newline is used.
+
+@node noweb-sep, cache, noweb-ref, Specific header arguments
+@subsubsection @code{:noweb-sep}
+
+The @code{:noweb-sep} header argument holds the string used to separate
+accumulate noweb references (see @ref{noweb-ref}). By default a newline is
+used.
+
+@node cache, sep, noweb-sep, Specific header arguments
@subsubsection @code{:cache}
The @code{:cache} header argument controls the use of in-buffer caching of
the results of evaluating code blocks. It can be used to avoid re-evaluating
-unchanged code blocks. This header argument can have one of two
-values: @code{yes} or @code{no}.
+unchanged code blocks. Note that the @code{:cache} header argument will not
+attempt to cache results when the @code{:session} header argument is used,
+because the results of the code block execution may be stored in the session
+outside of the Org-mode buffer. The @code{:cache} header argument can have
+one of two values: @code{yes} or @code{no}.
@itemize @bullet
@item @code{no}
changed since it was last run.
@example
- #+srcname: random
- #+begin_src R :cache yes
+ #+NAME: random
+ #+BEGIN_SRC R :cache yes
runif(1)
- #+end_src
+ #+END_SRC
#+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
0.4659510825295
- #+srcname: caller
- #+begin_src emacs-lisp :var x=random :cache yes
+ #+NAME: caller
+ #+BEGIN_SRC emacs-lisp :var x=random :cache yes
x
- #+end_src
+ #+END_SRC
#+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
0.254227238707244
@subsubsection @code{:sep}
The @code{:sep} header argument can be used to control the delimiter used
-when writing tabular results out to files external to Org-mode. This is used
+when writing tabular results out to files external to Org mode. This is used
either when opening tabular results of a code block by calling the
@code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block,
or when writing code block results to an external file (see @ref{file})
default value yields the following results.
@example
-#+tblname: many-cols
+#+TBLNAME: many-cols
| a | b | c |
|---+---+---|
| d | e | f |
|---+---+---|
| g | h | i |
-#+source: echo-table
-#+begin_src python :var tab=many-cols
+#+NAME: echo-table
+#+BEGIN_SRC python :var tab=many-cols
return tab
-#+end_src
+#+END_SRC
#+results: echo-table
| a | b | c |
Leaves hlines in the table. Setting @code{:hlines yes} has this effect.
@example
-#+tblname: many-cols
+#+TBLNAME: many-cols
| a | b | c |
|---+---+---|
| d | e | f |
|---+---+---|
| g | h | i |
-#+source: echo-table
-#+begin_src python :var tab=many-cols :hlines yes
+#+NAME: echo-table
+#+BEGIN_SRC python :var tab=many-cols :hlines yes
return tab
-#+end_src
+#+END_SRC
#+results: echo-table
| a | b | c |
The @code{:colnames} header argument accepts the values @code{yes},
@code{no}, or @code{nil} for unassigned. The default value is @code{nil}.
+Note that the behavior of the @code{:colnames} header argument may differ
+across languages. For example Emacs Lisp code blocks ignore the
+@code{:colnames} header argument entirely given the ease with which tables
+with column names may be handled directly in Emacs Lisp.
@itemize @bullet
@item @code{nil}
processing, then reapplied to the results.
@example
-#+tblname: less-cols
+#+TBLNAME: less-cols
| a |
|---|
| b |
| c |
-#+srcname: echo-table-again
-#+begin_src python :var tab=less-cols
+#+NAME: echo-table-again
+#+BEGIN_SRC python :var tab=less-cols
return [[val + '*' for val in row] for row in tab]
-#+end_src
+#+END_SRC
#+results: echo-table-again
| a |
and is then reapplied to the results.
@example
-#+tblname: with-rownames
+#+TBLNAME: with-rownames
| one | 1 | 2 | 3 | 4 | 5 |
| two | 6 | 7 | 8 | 9 | 10 |
-#+srcname: echo-table-once-again
-#+begin_src python :var tab=with-rownames :rownames yes
+#+NAME: echo-table-once-again
+#+BEGIN_SRC python :var tab=with-rownames :rownames yes
return [[val + 10 for val in row] for row in tab]
-#+end_src
+#+END_SRC
#+results: echo-table-once-again
| one | 11 | 12 | 13 | 14 | 15 |
@node eval, , shebang, Specific header arguments
@subsubsection @code{:eval}
The @code{:eval} header argument can be used to limit the evaluation of
-specific code blocks. @code{:eval} accepts two arguments ``never'' and
-``query''. @code{:eval never} will ensure that a code block is never
-evaluated, this can be useful for protecting against the evaluation of
-dangerous code blocks. @code{:eval query} will require a query for every
-execution of a code block regardless of the value of the
-@code{org-confirm-babel-evaluate} variable.
+specific code blocks. The @code{:eval} header argument can be useful for
+protecting against the evaluation of dangerous code blocks or to ensure that
+evaluation will require a query regardless of the value of the
+@code{org-confirm-babel-evaluate} variable. The possible values of
+@code{:eval} and their effects are shown below.
+
+@table @code
+@item never or no
+The code block will not be evaluated under any circumstances.
+@item query
+Evaluation of the code block will require a query.
+@item never-export or no-export
+The code block will not be evaluated during export but may still be called
+interactively.
+@item query-export
+Evaluation of the code block during export will require a query.
+@end table
If this header argument is not set then evaluation is determined by the value
of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation
@end multitable
Note: With @code{:results value}, the result in both @code{:session} and
-non-session is returned to Org-mode as a table (a one- or two-dimensional
+non-session is returned to Org mode as a table (a one- or two-dimensional
vector of strings or numbers) when appropriate.
@subsection Non-session
process. For example, compare the following two blocks:
@example
-#+begin_src python :results output
+#+BEGIN_SRC python :results output
print "hello"
2
print "bye"
-#+end_src
+#+END_SRC
-#+resname:
+#+results:
: hello
: bye
@end example
In non-session mode, the `2' is not printed and does not appear.
@example
-#+begin_src python :results output :session
+#+BEGIN_SRC python :results output :session
print "hello"
2
print "bye"
-#+end_src
+#+END_SRC
-#+resname:
+#+results:
: hello
: 2
: bye
references are expanded depends upon the value of the @code{:noweb} header
argument. If @code{:noweb yes}, then a Noweb reference is expanded before
evaluation. If @code{:noweb no}, the default, then the reference is not
-expanded before evaluation.
+expanded before evaluation. See the @ref{noweb-ref} header argument for
+a more flexible way to resolve noweb references.
+
+It is possible to include the @emph{results} of a code block rather than the
+body. This is done by appending parenthesis to the code block name which may
+optionally contain arguments to the code block as shown below.
+
+@example
+<<code-block-name(optional arguments)>>
+@end example
Note: the default value, @code{:noweb no}, was chosen to ensure that
correct code is not broken in a language, such as Ruby, where
syntactically valid in languages that you use, then please consider setting
the default value.
+Note: if noweb tangling is slow in large Org-mode files consider setting the
+@code{*org-babel-use-quick-and-dirty-noweb-expansion*} variable to true.
+This will result in faster noweb reference resolution at the expense of not
+correctly resolving inherited values of the @code{:noweb-ref} header
+argument.
+
@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code
@section Key bindings and useful functions
@cindex code block, key bindings
-Many common Org-mode key sequences are re-bound depending on
+Many common Org mode key sequences are re-bound depending on
the context.
Within a code block, the following key bindings
@item @kbd{M-@key{down}} @tab @code{org-babel-pop-to-session}
@end multitable
-In an Org-mode buffer, the following key bindings are active:
+In an Org mode buffer, the following key bindings are active:
@multitable @columnfractions 0.45 0.55
-@kindex C-c C-v a
-@kindex C-c C-v C-a
-@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
+@kindex C-c C-v p
+@kindex C-c C-v C-p
+@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block}
+@kindex C-c C-v n
+@kindex C-c C-v C-n
+@item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block}
+@kindex C-c C-v e
+@kindex C-c C-v C-e
+@item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe}
+@kindex C-c C-v o
+@kindex C-c C-v C-o
+@item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result}
+@kindex C-c C-v v
+@kindex C-c C-v C-v
+@item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block}
+@kindex C-c C-v u
+@kindex C-c C-v C-u
+@item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head}
+@kindex C-c C-v g
+@kindex C-c C-v C-g
+@item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block}
+@kindex C-c C-v r
+@kindex C-c C-v C-r
+@item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result}
@kindex C-c C-v b
@kindex C-c C-v C-b
@item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
-@kindex C-c C-v f
-@kindex C-c C-v C-f
-@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
-@kindex C-c C-v g
-@item @kbd{C-c C-v g} @tab @code{org-babel-goto-named-source-block}
-@kindex C-c C-v h
-@item @kbd{C-c C-v h} @tab @code{org-babel-describe-bindings}
-@kindex C-c C-v l
-@kindex C-c C-v C-l
-@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
-@kindex C-c C-v p
-@kindex C-c C-v C-p
-@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
@kindex C-c C-v s
@kindex C-c C-v C-s
@item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
+@kindex C-c C-v d
+@kindex C-c C-v C-d
+@item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block}
@kindex C-c C-v t
@kindex C-c C-v C-t
@item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
+@kindex C-c C-v f
+@kindex C-c C-v C-f
+@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
+@kindex C-c C-v c
+@kindex C-c C-v C-c
+@item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block}
+@kindex C-c C-v j
+@kindex C-c C-v C-j
+@item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg}
+@kindex C-c C-v l
+@kindex C-c C-v C-l
+@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session}
+@kindex C-c C-v i
+@kindex C-c C-v C-i
+@item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest}
+@kindex C-c C-v I
+@kindex C-c C-v C-I
+@item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info}
@kindex C-c C-v z
@kindex C-c C-v C-z
-@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
+@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session-with-code}
+@kindex C-c C-v a
+@kindex C-c C-v C-a
+@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
+@kindex C-c C-v h
+@kindex C-c C-v C-h
+@item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings}
+@kindex C-c C-v x
+@kindex C-c C-v C-x
+@item @kbd{C-c C-v x} @ @ @r{or} @ @ @kbd{C-c C-v C-x} @tab @code{org-babel-do-key-sequence-in-edit-buffer}
@end multitable
@c When possible these keybindings were extended to work when the control key is
@cindex tag completion
@cindex link abbreviations, completion of
-Emacs would not be Emacs without completion, and Org-mode uses it whenever it
+Emacs would not be Emacs without completion, and Org mode uses it whenever it
makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for
some of the completion prompts, you can specify your preference by setting at
most one of the variables @code{org-completion-use-iswitchb}
After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
@item
After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
-@samp{OPTIONS} which set file-specific options for Org-mode. When the
+@samp{OPTIONS} which set file-specific options for Org mode. When the
option keyword is already complete, pressing @kbd{M-@key{TAB}} again
will insert example settings for this keyword.
@item
@cindex template insertion
@cindex insertion, of templates
-Org-mode supports insertion of empty structural elements (like
+Org mode supports insertion of empty structural elements (like
@code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key
strokes. This is achieved through a native template expansion mechanism.
Note that Emacs has several other template mechanisms which could be used in
@cindex in-buffer settings
@cindex special keywords
-Org-mode uses special lines in the buffer to define settings on a
+Org mode uses special lines in the buffer to define settings on a
per-file basis. These lines start with a @samp{#+} followed by a
keyword, a colon, and then individual words defining a setting. Several
setting words can be in the same line, but you can also have multiple
@item #+SETUPFILE: file
This line defines a file that holds more in-buffer setup. Normally this is
entirely ignored. Only when the buffer is parsed for option-setting lines
-(i.e.@: when starting Org-mode for a file, when pressing @kbd{C-c C-c} in a
+(i.e.@: when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
settings line, or when exporting), then the contents of this file are parsed
as if they had been included in the buffer. In particular, the file can be
-any other Org-mode file with internal setup. You can visit the file the
+any other Org mode file with internal setup. You can visit the file the
cursor is in the line with @kbd{C-c '}.
@item #+STARTUP:
@cindex #+STARTUP:
-This line sets options to be used at startup of Org-mode, when an
+This line sets options to be used at startup of Org mode, when an
Org file is being visited.
The first set of options deals with the initial visibility of the outline
@cindex @code{indent}, STARTUP keyword
@cindex @code{noindent}, STARTUP keyword
Dynamic virtual indentation is controlled by the variable
-@code{org-startup-indented}@footnote{Emacs 23 and Org-mode 6.29 are required}
+@code{org-startup-indented}@footnote{Emacs 23 and Org mode 6.29 are required}
@example
indent @r{start with @code{org-indent-mode} turned on}
noindent @r{start with @code{org-indent-mode} turned off}
@item
If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
block is updated.
+@item
+If the cursor is at a timestamp, fix the day name in the timestamp.
@end itemize
@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
been installed properly. As of Emacs 22, Calc is part of the Emacs
distribution. Another possibility for interaction between the two
packages is using Calc for embedded calculations. @xref{Embedded Mode,
-, Embedded Mode, Calc, GNU Emacs Calc Manual}.
+, Embedded Mode, calc, GNU Emacs Calc Manual}.
@item @file{constants.el} by Carsten Dominik
@cindex @file{constants.el}
@cindex Dominik, Carsten
@item @file{cdlatex.el} by Carsten Dominik
@cindex @file{cdlatex.el}
@cindex Dominik, Carsten
-Org-mode can make use of the CDLa@TeX{} package to efficiently enter
+Org mode can make use of the CD@LaTeX{} package to efficiently enter
@LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}.
@item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
@cindex @file{imenu.el}
-Imenu allows menu access to an index of items in a file. Org-mode
+Imenu allows menu access to an index of items in a file. Org mode
supports Imenu---all you need to do to get the index is the following:
@lisp
(add-hook 'org-mode-hook
@cindex @file{speedbar.el}
@cindex Ludlam, Eric M.
Speedbar is a package that creates a special frame displaying files and
-index items in files. Org-mode supports Speedbar and allows you to
+index items in files. Org mode supports Speedbar and allows you to
drill into Org files directly from the Speedbar. It also allows you to
restrict the scope of agenda commands to a file or a subtree by using
the command @kbd{<} in the Speedbar frame.
Complex ASCII tables with automatic line wrapping, column- and row-spanning,
and alignment can be created using the Emacs table package by Takaaki Ota
(@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22).
-Org-mode will recognize these tables and export them properly. Because of
-interference with other Org-mode functionality, you unfortunately cannot edit
+Org mode will recognize these tables and export them properly. Because of
+interference with other Org mode functionality, you unfortunately cannot edit
these tables directly in the buffer. Instead, you need to use the command
@kbd{C-c '} to edit them, similar to source code snippets.
@c
@orgcmd{C-c ~,org-table-create-with-table.el}
Insert a @file{table.el} table. If there is already a table at point, this
-command converts it between the @file{table.el} format and the Org-mode
+command converts it between the @file{table.el} format and the Org mode
format. See the documentation string of the command
@code{org-convert-table} for the restrictions under which this is
possible.
@item @file{footnote.el} by Steven L. Baur
@cindex @file{footnote.el}
@cindex Baur, Steven L.
-Org-mode recognizes numerical footnotes as provided by this package.
-However, Org-mode also has its own footnote support (@pxref{Footnotes}),
+Org mode recognizes numerical footnotes as provided by this package.
+However, Org mode also has its own footnote support (@pxref{Footnotes}),
which makes using @file{footnote.el} unnecessary.
@end table
@node Conflicts, , Cooperation, Interaction
-@subsection Packages that lead to conflicts with Org-mode
+@subsection Packages that lead to conflicts with Org mode
@table @asis
timestamps, TODO keywords, priorities, and item bullet types if the cursor is
at such a location. By default, @kbd{S-@key{cursor}} commands outside
special contexts don't do anything, but you can customize the variable
-@code{org-support-shift-select}. Org-mode then tries to accommodate shift
+@code{org-support-shift-select}. Org mode then tries to accommodate shift
selection by (i) using it outside of the special contexts where special
commands apply, and by (ii) extending an existing active region even if the
cursor moves across a special context.
@code{shift-selection-mode}, see previous paragraph. If you are using Emacs
23, you probably don't want to use another package for this purpose. However,
if you prefer to leave these keys to a different package while working in
-Org-mode, configure the variable @code{org-replace-disputed-keys}. When set,
+Org mode, configure the variable @code{org-replace-disputed-keys}. When set,
Org will move the following key bindings in Org files, and in the agenda
buffer (but not during date selection).
(add-hook 'org-mode-hook
(lambda ()
(org-set-local 'yas/trigger-key [tab])
- (define-key yas/keymap [tab] 'yas/next-field-group)))
+ (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
@end lisp
The latest version of yasnippet doesn't play well with Org mode. If the
@cindex @file{windmove.el}
This package also uses the @kbd{S-<cursor>} keys, so everything written
in the paragraph above about CUA mode also applies here. If you want make
-the windmove function active in locations where Org-mode does not have
+the windmove function active in locations where Org mode does not have
special functionality on @kbd{S-@key{cursor}}, add this to your
configuration:
@cindex @file{viper.el}
@kindex C-c /
Viper uses @kbd{C-c /} and therefore makes this key not access the
-corresponding Org-mode command @code{org-sparse-tree}. You need to find
+corresponding Org mode command @code{org-sparse-tree}. You need to find
another key for this command, or override the key in
@code{viper-vi-global-user-map} with
A large number of add-on packages have been written by various authors.
These packages are not part of Emacs, but they are distributed as contributed
-packages with the separate release available at the Org-mode home page at
+packages with the separate release available at the Org mode home page at
@uref{http://orgmode.org}. The list of contributed packages, along with
documentation about each package, is maintained by the Worg project at
@uref{http://orgmode.org/worg/org-contrib/}.
@vindex org-ctrl-c-ctrl-c-hook
Org has several commands that act differently depending on context. The most
-important example it the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
+important example is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property.
Add-ons can tap into this functionality by providing a function that detects
special context for that add-on and executes functionality appropriate for
the context. Here is an example from Dan Davison's @file{org-R.el} which
allows you to evaluate commands based on the @file{R} programming language
-@footnote{@file{org-R.el} has been replaced by the org-mode functionality
+@footnote{@file{org-R.el} has been replaced by the Org mode functionality
described in @ref{Working With Source Code} and is now obsolete.}. For this
package, special contexts are lines that start with @code{#+R:} or
@code{#+RR:}.
@menu
* Radio tables:: Sending and receiving radio tables
-* A LaTeX example:: Step by step, almost a tutorial
+* A @LaTeX{} example:: Step by step, almost a tutorial
* Translator functions:: Copy and modify
* Radio lists:: Doing the same for lists
@end menu
-@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax
+@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax
@subsection Radio tables
@cindex radio tables
key.
@end itemize
-@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax
+@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax
@subsection A @LaTeX{} example of radio tables
@cindex @LaTeX{}, and Orgtbl mode
supplied instead of strings.
@end table
-@node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax
+@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax
@subsection Translator functions
@cindex HTML, and Orgtbl mode
@cindex translator function
@example
emacs -batch -l ~/.emacs \
-eval '(org-batch-agenda "a" \
- org-agenda-span month \
+ org-agenda-span (quote month) \
org-agenda-include-diary nil \
org-agenda-files (quote ("~/org/project.org")))' \
| lpr
@uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the
@i{iPhone/iPod Touch} series of devices, developed by Richard Moreland.
-@i{MobileOrg} offers offline viewing and capture support for an Org-mode
+@i{MobileOrg} offers offline viewing and capture support for an Org mode
system rooted on a ``real'' computer. It does also allow you to record
changes to existing entries. Android users should check out
@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
MobileOrg needs to interact with Emacs through a directory on a server. If you
are using a public server, you should consider to encrypt the files that are
-uploaded to the server. This can be done with Org-mode 7.02 and with
+uploaded to the server. This can be done with Org mode 7.02 and with
@i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl}
installation on your system. To turn on encryption, set a password in
@i{MobileOrg} and, on the Emacs side, configure the variable
(setq org-mobile-directory "~/Dropbox/MobileOrg")
@end lisp
-Org-mode has commands to put files for @i{MobileOrg} into that directory,
+Org mode has commands to put files for @i{MobileOrg} into that directory,
and to read captured notes from there.
@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
staged with paths relative to @code{org-directory}, so all files should be
inside this directory. The push operation also creates a special Org file
@file{agendas.org} with all custom agenda view defined by the
-user@footnote{While creating the agendas, Org-mode will force ID properties
+user@footnote{While creating the agendas, Org mode will force ID properties
on all referenced entries, so that these entries can be uniquely identified
if @i{MobileOrg} flags them for further action. If you do not want to get
these properties in so many entries, you can set the variable
@table @i
@item Bastien Guerry
Bastien has written a large number of extensions to Org (most of them
-integrated into the core by now), including the LaTeX exporter and the plain
+integrated into the core by now), including the @LaTeX{} exporter and the plain
list parser. His support during the early days, when he basically acted as
co-maintainer, was central to the success of this project. Bastien also
invented Worg, helped establishing the Web presence of Org, and sponsors
@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
@item
@i{Christophe Bataillon} created the great unicorn logo that we use on the
-Org-mode website.
+Org mode website.
@item
@i{Alex Bochannek} provided a patch for rounding timestamps.
@item
@i{Jan Böcker} wrote @file{org-docview.el}.
@item
-@i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files.
+@i{Brad Bozarth} showed how to pull RSS feed data into Org mode files.
@item
@i{Tom Breton} wrote @file{org-choose.el}.
@item
extension system, added support for mairix, and proposed the mapping API.
@item
@i{Ulf Stegemann} created the table to translate special symbols to HTML,
-LaTeX, UTF-8, Latin-1 and ASCII.
+@LaTeX{}, UTF-8, Latin-1 and ASCII.
@item
@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
with links transformation to Org syntax.
@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
chapter about publishing.
@item
-@i{Jambunathan K} contributed the OpenDocumentText exporter.
+@i{Jambunathan K} contributed the ODT exporter.
@item
-@i{Sebastien Vauban} reported many issues with LaTeX and BEAMER export and
-enabled source code highlighling in Gnus.
+@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
+enabled source code highlighting in Gnus.
@item
@i{Stefan Vollmar} organized a video-recorded talk at the
Max-Planck-Institute for Neurology. He also inspired the creation of a