@c %**start of header
@setfilename ../../info/org
@settitle The Org Manual
-@set VERSION 7.9.3f (GNU Emacs 24.3)
+
+@include org-version.inc
@c Use proper quote and backtick for code sections in PDF output
@c Cf. Texinfo manual 14.2
@set txicodequotebacktick
@c Version and Contact Info
-@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
+@set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page}
@set AUTHOR Carsten Dominik
@set MAINTAINER Carsten Dominik
@set MAINTAINEREMAIL @email{carsten at orgmode dot org}
@subtitle Release @value{VERSION}
@author by Carsten Dominik
-with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K.
+with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan
+Davison, Eric Schulte, Thomas Dye, Jambunathan K and Nicolas Goaziou.
@c The following two commands start the copyright page.
@page
* Capture - Refile - Archive:: The ins and outs for projects
* Agenda Views:: Collecting information into views
* Markup:: Prepare text for rich export
-* Exporting:: Sharing and publishing of notes
+* Exporting:: Sharing and publishing notes
* Publishing:: Create a web site of linked Org files
* Working With Source Code:: Export, evaluate, and tangle code blocks
* Miscellaneous:: All the rest which did not fit elsewhere
* Blocks:: Folding blocks
* Footnotes:: How footnotes are defined in Org's syntax
* Orgstruct mode:: Structure editing outside Org
+* Org syntax:: Formal description of Org's syntax
+
+Visibility cycling
+
+* Global and local cycling:: Cycling through various visibility states
+* Initial visibility:: Setting the initial visibility state
+* Catching invisible edits:: Preventing mistakes when editing invisible parts
+
+Global and local cycling
+
+* Initial visibility:: Setting the initial visibility state
+* Catching invisible edits:: Preventing mistakes when editing invisible parts
Tables
* Durations and time values:: How to compute durations and time values
* Field and range formulas:: Formula for specific (ranges of) fields
* Column formulas:: Formulas valid for an entire column
+* Lookup functions:: Lookup functions for searching tables
* Editing and debugging formulas:: Fixing formulas
* Updating the table:: Recomputing all dependent fields
* Advanced features:: Field and column names, parameters and automatic recalc
* Tag inheritance:: Tags use the tree structure of the outline
* Setting tags:: How to assign tags to a headline
+* Tag groups:: Use one tag to search for several tags
* Tag searches:: Searching for combinations of tags
Properties and columns
* Attachments:: Add files to tasks
* RSS Feeds:: Getting input from RSS feeds
* Protocols:: External (e.g., Browser) access to Emacs and Org
-* Refiling notes:: Moving a tree from one place to another
+* Refile and copy:: Moving/copying a tree from one place to another
* Archiving:: What to do with finished projects
Capture
* Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time
-* Sorting of agenda items:: The order of things
+* Sorting agenda items:: The order of things
+* Filtering/limiting agenda items:: Dynamically narrow the agenda
Custom agenda views
Markup for rich export
* Structural markup elements:: The basic structure as seen by the exporter
-* Images and tables:: Tables and Images will be included
+* Images and tables:: Images, tables and caption mechanism
* Literal examples:: Source code examples with special formatting
* Include files:: Include additional files into a document
* Index entries:: Making an index
-* Macro replacement:: Use macros to create complex output
+* Macro replacement:: Use macros to create templates
* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
+* Special blocks:: Containers targeted at export back-ends
Structural markup elements
* Document title:: Where the title is taken from
* Headings and sections:: The document structure as seen by the exporter
* Table of contents:: The if and where of the table of contents
-* Initial text:: Text before the first heading?
* Lists:: Lists
* Paragraphs:: Paragraphs
* Footnote markup:: Footnotes
Exporting
-* Selective export:: Using tags to select and exclude trees
-* Export options:: Per-file export settings
-* The export dispatcher:: How to access exporter commands
+* The Export Dispatcher:: The main exporter interface
+* Export back-ends:: Built-in export formats
+* Export settings:: Generic export settings
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
+* Beamer export:: Exporting as a Beamer presentation
* HTML export:: Exporting to HTML
* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
-* DocBook export:: Exporting to DocBook
+* Markdown export:: Exporting to Markdown
* OpenDocument Text export:: Exporting to OpenDocument Text
-* TaskJuggler export:: Exporting to TaskJuggler
-* Freemind export:: Exporting to Freemind mind maps
-* XOXO export:: Exporting to XOXO
-* iCalendar export:: Exporting in iCalendar format
+* iCalendar export:: Exporting to iCalendar
+* Other built-in back-ends:: Exporting to @code{Texinfo}, a man page, or Org
+* Export in foreign buffers:: Author tables in lists in Org syntax
+* Advanced configuration:: Fine-tuning the export output
HTML export
* HTML Export commands:: How to invoke HTML export
+* HTML doctypes:: Org can export to various (X)HTML flavors
* HTML preamble and postamble:: How to insert a preamble and a postamble
* Quoting HTML tags:: Using direct HTML in Org mode
* Links in HTML export:: How links will be interpreted and formatted
@LaTeX{} and PDF export
-* @LaTeX{}/PDF export commands::
+* @LaTeX{} export commands:: How to export to LaTeX and PDF
* 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
-* Beamer class export:: Turning the file into a presentation
-
-DocBook export
-
-* DocBook export commands:: How to invoke DocBook export
-* Quoting DocBook code:: Incorporating DocBook code in Org files
-* Recursive sections:: Recursive sections in DocBook
-* Tables in DocBook export:: Tables are exported as HTML tables
-* Images in DocBook export:: How to insert figures into DocBook output
-* Special characters:: How to handle special characters
+* @LaTeX{} specific attributes:: Controlling @LaTeX{} output
OpenDocument Text export
* 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
+* Language-specific header arguments in Org mode properties:: Set langugage-specific 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
* colnames:: Handle column names in tables
* rownames:: Handle row names in tables
* shebang:: Make tangled files executable
+* tangle-mode:: Set permission of tangled files
* eval:: Limit evaluation of specific code blocks
* wrap:: Mark source block evaluation results
+* post:: Post processing of code block results
+* prologue:: Text to prepend to code block body
+* epilogue:: Text to append to code block body
Miscellaneous
* Clean view:: Getting rid of leading stars in the outline
* TTY keys:: Using Org on a tty
* Interaction:: Other Emacs packages
-* org-crypt.el:: Encrypting Org files
+* org-crypt:: Encrypting Org files
Interaction with other packages
* Hooks:: How to reach into Org's internals
* Add-on packages:: Available extensions
* Adding hyperlink types:: New custom link types
+* Adding export back-ends:: How to write new export back-ends
* Context-sensitive commands:: How to add functionality to such commands
* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
-* Extracting agenda information:: Postprocessing of agenda information
+* Speeding up your agendas:: Tips on how to speed up your agendas
+* Extracting agenda information:: Post-processing of agenda information
* Using the property API:: Writing programs that use entry properties
* Using the mapping API:: Mapping over all or selected entries
* Radio tables:: Sending and receiving radio tables
* A @LaTeX{} example:: Step by step, almost a tutorial
* Translator functions:: Copy and modify
-* Radio lists:: Doing the same for lists
+* Radio lists:: Sending and receiving lists
MobileOrg
agenda that utilizes and smoothly integrates much of the Emacs calendar
and diary. Plain text URL-like links connect to websites, emails,
Usenet messages, BBDB entries, and any files related to the projects.
-For printing and sharing of notes, an Org file can be exported as a
+For printing and sharing notes, an Org file can be exported as a
structured ASCII file, as HTML, or (TODO and agenda items only) as an
iCalendar file. It can also serve as a publishing tool for a set of
linked web pages.
@pindex GTD, Getting Things Done
@r{@bullet{} an environment in which to implement David Allen's GTD system}
@r{@bullet{} a simple hypertext system, with HTML and @LaTeX{} export}
-@r{@bullet{} a publishing tool to create a set of interlinked webpages}
+@r{@bullet{} a publishing tool to create a set of interlinked web pages}
@r{@bullet{} an environment for literate programming}
@end example
Recent Emacs distributions include a packaging system which lets you install
Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
-To make sure your Org configuration is well taken into account, initialize
-the package system with @code{(package-initialize)} before setting any Org
-option. If you want to use Org's package repository, check out the
-@uref{http://orgmode.org/elpa.html, Org ELPA page}.
+You need to do this in a session where no @code{.org} file has been visited.
+Then, to make sure your Org configuration is taken into account, initialize
+the package system with @code{(package-initialize)} in your @file{.emacs}
+before setting any Org option. If you want to use Org's package repository,
+check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
@subsubheading Downloading Org as an archive
website}. In this case, make sure you set the load-path correctly in your
@file{.emacs}:
-@example
+@lisp
(add-to-list 'load-path "~/path/to/orgdir/lisp")
-@end example
+@end lisp
The downloaded archive contains contributed libraries that are not included
in Emacs. If you want to use them, add the @file{contrib} directory to your
load-path:
-@example
+@lisp
(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
-@end example
+@end lisp
Optionally, you can compile the files and/or install them in your system.
Run @code{make help} to list compilation and installation options.
quite possible that the bug has been fixed already. If the bug persists,
prepare a report and provide as much information as possible, including the
version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
-(@kbd{M-x org-version @key{RET}}), as well as the Org related setup in
+(@kbd{M-x org-version RET}), as well as the Org related setup in
@file{.emacs}. The easiest way to do this is to use the command
@example
-@kbd{M-x org-submit-bug-report}
+@kbd{M-x org-submit-bug-report RET}
@end example
@noindent which will put all this information into an Emacs mail buffer so
that you only need to add your description. If you re not sending the Email
@code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
shown below.
-@example
+@lisp
;;; Minimal setup to load latest `org-mode'
;; activate debugging
;; 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" t))
-@end example
+@end lisp
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
contains much more information if it is produced with uncompiled code.
To do this, use
@example
-C-u M-x org-reload RET
+@kbd{C-u M-x org-reload RET}
@end example
@noindent
or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
environment). They are written in uppercase in the manual to enhance its
readability, but you can use lowercase in your Org files@footnote{Easy
templates insert lowercase keywords and Babel dynamically inserts
-@code{#+results}.}
+@code{#+results}.}.
@subsubheading Keybindings and commands
@kindex C-c a
* Blocks:: Folding blocks
* Footnotes:: How footnotes are defined in Org's syntax
* Orgstruct mode:: Structure editing outside Org
+* Org syntax:: Formal description of Org's syntax
@end menu
@node Outlines, Headlines, Document Structure, Document Structure
@cindex show hidden text
@cindex hide text
+@menu
+* Global and local cycling:: Cycling through various visibility states
+* Initial visibility:: Setting the initial visibility state
+* Catching invisible edits:: Preventing mistakes when editing invisible parts
+@end menu
+
+@node Global and local cycling, Initial visibility, Visibility cycling, Visibility cycling
+@subsection Global and local cycling
+
Outlines make it possible to hide parts of the text in the buffer.
Org uses just two commands, bound to @key{TAB} and
@kbd{S-@key{TAB}} to change the visibility in the buffer.
Copy the @i{visible} text in the region into the kill ring.
@end table
+@menu
+* Initial visibility:: Setting the initial visibility state
+* Catching invisible edits:: Preventing mistakes when editing invisible parts
+@end menu
+
+@node Initial visibility, Catching invisible edits, Global and local cycling, Visibility cycling
+@subsection Initial visibility
+
+@cindex visibility, initialize
@vindex org-startup-folded
@vindex org-agenda-inhibit-startup
@cindex @code{overview}, STARTUP keyword
@cindex @code{showall}, STARTUP keyword
@cindex @code{showeverything}, STARTUP keyword
-When Emacs first visits an Org file, the global state is set to
-OVERVIEW, i.e., only the top level headlines are visible. This can be
-configured through the variable @code{org-startup-folded}, or on a
-per-file basis by adding one of the following lines anywhere in the
-buffer:
+When Emacs first visits an Org file, the global state is set to OVERVIEW,
+i.e., only the top level headlines are visible@footnote{When
+@code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default
+visibility state when first opening a file for the agenda (@pxref{Speeding up
+your agendas}).} This can be configured through the variable
+@code{org-startup-folded}, or on a per-file basis by adding one of the
+following lines anywhere in the buffer:
@example
#+STARTUP: overview
The startup visibility options are ignored when the file is open for the
first time during the agenda generation: if you want the agenda to honor
-the startup visibility, set @code{org-agenda-inhibit-startup} to nil.
+the startup visibility, set @code{org-agenda-inhibit-startup} to @code{nil}.
@cindex property, VISIBILITY
@noindent
and Columns}) will get their visibility adapted accordingly. Allowed values
for this property are @code{folded}, @code{children}, @code{content}, and
@code{all}.
+
@table @asis
@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
Switch back to the startup visibility of the buffer, i.e., whatever is
entries.
@end table
+@node Catching invisible edits, , Initial visibility, Visibility cycling
+@subsection Catching invisible edits
+
+@vindex org-catch-invisible-edits
+@cindex edits, catching invisible
+Sometimes you may inadvertently edit an invisible part of the buffer and be
+confused on what has been edited and how to undo the mistake. Setting
+@code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the
+docstring of this option on how Org should catch invisible edits and process
+them.
+
@node Motion, Structure editing, Visibility cycling, Document Structure
@section Motion
@cindex motion, between headlines
@end example
@vindex org-goto-interface
@noindent
-See also the variable @code{org-goto-interface}.
+See also the option @code{org-goto-interface}.
@end table
@node Structure editing, Sparse trees, Motion, Document Structure
@table @asis
@orgcmd{M-@key{RET},org-insert-heading}
@vindex org-M-RET-may-split-line
-Insert new heading with same level as current. If the cursor is in a plain
-list item, a new item is created (@pxref{Plain lists}). To force creation of
-a new headline, use a prefix argument. When this command is used in the
-middle of a line, the line is split and the rest of the line becomes the new
-headline@footnote{If you do not want the line to be split, customize the
-variable @code{org-M-RET-may-split-line}.}. If the command is used at the
-beginning of a headline, the new headline is created before the current line.
-If at the beginning of any other line, the content of that line is made the
-new heading. If the command is used at the end of a folded subtree (i.e.,
-behind the ellipses at the end of a headline), then a headline like the
-current one will be inserted after the end of the subtree.
+Insert a new heading/item with the same level than the one at point.
+If the cursor is in a plain list item, a new item is created
+(@pxref{Plain lists}). To prevent this behavior in lists, call the
+command with a prefix argument. When this command is used in the
+middle of a line, the line is split and the rest of the line becomes
+the new item or headline@footnote{If you do not want the line to be
+split, customize the variable @code{org-M-RET-may-split-line}.}. If
+the command is used at the @emph{beginning} of a headline, the new
+headline is created before the current line. If the command is used
+at the @emph{end} of a folded subtree (i.e., behind the ellipses at
+the end of a headline), then a headline will be
+inserted after the end of the subtree. Calling this command with
+@kbd{C-u C-u} will unconditionally respect the headline's content and
+create a new item at the end of the parent subtree.
@orgcmd{C-@key{RET},org-insert-heading-respect-content}
Just like @kbd{M-@key{RET}}, except when adding a new heading below the
current heading, the new heading is placed after the body instead of before
@orgcmd{C-y,org-yank}
@vindex org-yank-adjusted-subtrees
@vindex org-yank-folded-subtrees
-Depending on the variables @code{org-yank-adjusted-subtrees} and
+Depending on the options @code{org-yank-adjusted-subtrees} and
@code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
paste subtrees folded and in a clever way, using the same command as @kbd{C-c
C-x C-y}. With the default settings, no level adjustment will take place,
more details, see the docstring of the command
@code{org-clone-subtree-with-time-shift}.
@orgcmd{C-c C-w,org-refile}
-Refile entry or region to a different location. @xref{Refiling notes}.
+Refile entry or region to a different location. @xref{Refile and copy}.
@orgcmd{C-c ^,org-sort}
Sort same-level entries. When there is an active region, all entries in the
region will be sorted. Otherwise the children of the current headline are
Jump to the previous sparse tree match in this buffer.
@end table
-
@noindent
@vindex org-agenda-custom-commands
For frequently used sparse trees of specific search strings, you can
-use the variable @code{org-agenda-custom-commands} to define fast
+use the option @code{org-agenda-custom-commands} to define fast
keyboard access to specific sparse trees. These commands will then be
accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
For example:
The other sparse tree commands select headings based on TODO keywords,
tags, or properties and will be discussed later in this manual.
-@kindex C-c C-e v
+@kindex C-c C-e C-v
@cindex printing sparse trees
@cindex visible text, printing
To print a sparse tree, you can use the Emacs command
@code{ps-print-buffer-with-faces} which does not print invisible parts
of the document @footnote{This does not work under XEmacs, because
XEmacs uses selective display for outlining, not text properties.}.
-Or you can use the command @kbd{C-c C-e v} to export only the visible
-part of the document and print the resulting file.
+Or you can use @kbd{C-c C-e C-v} to export only the visible part of
+the document and print the resulting file.
@node Plain lists, Drawers, Sparse trees, Document Structure
@section Plain lists
bullets.
@item
@vindex org-plain-list-ordered-item-terminator
-@vindex org-alphabetical-lists
+@vindex org-list-allow-alphabetical
@emph{Ordered} list items start with a numeral followed by either a period or
a right parenthesis@footnote{You can filter out any of them by configuring
@code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
@samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
-@samp{A)} by configuring @code{org-alphabetical-lists}. To minimize
+@samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize
confusion with normal text, those are limited to one character only. Beyond
that limit, bullets will automatically fallback to numbers.}. If you want a
list to start with a different value (e.g., 20), start the text of the item
list. An item ends before the next line that is less or equally indented
than its bullet/number.
-@vindex org-empty-line-terminates-plain-lists
+@vindex org-list-empty-line-terminates-plain-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
-lines@footnote{See also @code{org-empty-line-terminates-plain-lists}.}. In
-that case, all items are closed. Here is an example:
+lines@footnote{See also @code{org-list-empty-line-terminates-plain-lists}.}.
+In that case, all items are closed. Here is an example:
@example
@group
@table @kbd
@kindex M-S-@key{RET}
-@item M-S-RET
+@item M-S-@key{RET}
Insert a new item with a checkbox (@pxref{Checkboxes}).
@kindex S-@key{down}
@item S-up
@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
+@code{org-list-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}
Decrease/increase the indentation of an item, leaving children alone.
@kindex M-S-@key{left}
@kindex M-S-@key{right}
-@item M-S-left
-@itemx M-S-right
+@item M-S-@key{left}
+@itemx M-S-@key{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
anywhere in an item line, details depending on
@code{org-support-shift-select}.
@kindex C-c ^
+@cindex sorting, of plain list
@item C-c ^
Sort the plain list. You will be prompted for the sorting method:
-numerically, alphabetically, by time, or by custom function.
+numerically, alphabetically, by time, by checked status for check lists,
+or by a custom function.
@end table
@node Drawers, Blocks, Plain lists, Document Structure
@kindex C-c C-x d
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}.
-Drawers need to be configured with the variable
-@code{org-drawers}@footnote{You can define additional drawers on a
-per-file basis with a line like @code{#+DRAWERS: HIDDEN STATE}}. Drawers
-look like this:
+Drawers need to be configured with the option @code{org-drawers}@footnote{You
+can define additional drawers on a per-file basis with a line like
+@code{#+DRAWERS: HIDDEN STATE}}. Drawers look like this:
@example
** This is a headline
Add a time-stamped note to the LOGBOOK drawer.
@end table
+@vindex org-export-with-drawers
+You can select the name of the drawers which should be exported with
+@code{org-export-with-drawers}. In that case, drawer contents will appear in
+export output. Property drawers are not affected by this variable and are
+never exported.
+
@node Blocks, Footnotes, Drawers, Document Structure
@section Blocks
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
-folded at startup by configuring the variable @code{org-hide-block-startup}
+folded at startup by configuring the option @code{org-hide-block-startup}
or on a per-file basis by using
@cindex @code{hideblocks}, STARTUP keyword
@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
-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
-brackets in column 0, no indentation allowed. If you need a paragraph break
-inside a footnote, use the @LaTeX{} idiom @samp{\par}. The footnote reference
-is simply the marker in square brackets, inside text. For example:
+@file{footnote.el} package, Org mode's footnotes are designed for work on
+a larger document, not only for one-off documents like emails.
+
+A footnote is started by a footnote marker in square brackets in column 0, no
+indentation allowed. It ends at the next footnote definition, headline, or
+after two consecutive empty lines. The footnote reference is simply the
+marker in square brackets, inside text. For example:
@example
The Org homepage[fn:1] now looks a lot better than it used to.
@vindex org-footnote-define-inline
@vindex org-footnote-section
@vindex org-footnote-auto-adjust
-Otherwise, create a new footnote. Depending on the variable
+Otherwise, create a new footnote. Depending on the option
@code{org-footnote-define-inline}@footnote{The corresponding in-buffer
setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
definition will be placed right into the text as part of the reference, or
-separately into the location determined by the variable
+separately into the location determined by the option
@code{org-footnote-section}.
When this command is called with a prefix argument, a menu of additional
@r{sequence. If you want them sorted, use this command, which will}
@r{also move entries according to @code{org-footnote-section}. Automatic}
@r{sorting after each insertion/deletion can be configured using the}
- @r{variable @code{org-footnote-auto-adjust}.}
+ @r{option @code{org-footnote-auto-adjust}.}
r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
- @r{after each insertion/deletion can be configured using the variable}
+ @r{after each insertion/deletion can be configured using the option}
@r{@code{org-footnote-auto-adjust}.}
S @r{Short for first @code{r}, then @code{s} action.}
n @r{Normalize the footnotes by collecting all definitions (including}
@r{inline definitions) into a special section, and then numbering them}
@r{in sequence. The references will then also be numbers. This is}
@r{meant to be the final step before finishing a document (e.g., sending}
- @r{off an email). The exporters do this automatically, and so could}
- @r{something like @code{message-send-hook}.}
+ @r{off an email).}
d @r{Delete the footnote at point, and all definitions of and references}
@r{to it.}
@end example
you can use the usual commands to follow these links.
@end table
-@node Orgstruct mode, , Footnotes, Document Structure
+@node Orgstruct mode, Org syntax, Footnotes, Document Structure
@section The Orgstruct minor mode
@cindex Orgstruct mode
@cindex minor mode for structure editing
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
+this possible. Toggle the mode with @kbd{M-x orgstruct-mode RET}, or
turn it on by default, for example in Message mode, with one of:
@lisp
headline or the first line of a list item, most structure editing commands
will work, even if the same keys normally have different functionality in the
major mode you are using. If the cursor is not in one of those special
-lines, Orgstruct mode lurks silently in the shadows. When you use
-@code{orgstruct++-mode}, Org will also export indentation and autofill
-settings into that mode, and detect item context after the first line of an
-item.
+lines, Orgstruct mode lurks silently in the shadows.
+
+When you use @code{orgstruct++-mode}, Org will also export indentation and
+autofill settings into that mode, and detect item context after the first
+line of an item.
+
+@vindex orgstruct-heading-prefix-regexp
+You can also use Org structure editing to fold and unfold headlines in
+@emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}:
+the regular expression must match the local prefix to use before Org's
+headlines. For example, if you set this variable to @code{";; "} in Emacs
+Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
+commented lines. Some commands like @code{org-demote} are disabled when the
+prefix is set, but folding/unfolding will work correctly.
+
+@node Org syntax, , Orgstruct mode, Document Structure
+@section Org syntax
+@cindex Org syntax
+
+A reference document providing a formal description of Org's syntax is
+available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on
+Worg}, written and maintained by Nicolas Goaziou. It defines Org's core
+internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
+keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org
+file falls into one of the categories above.
+
+To explore the abstract structure of an Org buffer, run this in a buffer:
+
+@lisp
+M-: (org-element-parse-buffer) RET
+@end lisp
+
+It will output a list containing the buffer's content represented as an
+abstract structure. The export engine relies on the information stored in
+this list. Most interactive commands (e.g., for structure editing) also
+rely on the syntactic meaning of the surrounding context.
@node Tables, Hyperlinks, Document Structure, Top
@chapter Tables
typing @emph{immediately after the cursor was moved into a new field
with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
field is automatically made blank. If this behavior is too
-unpredictable for you, configure the variables
+unpredictable for you, configure the options
@code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
@table @kbd
@tsubheading{Re-aligning and field motion}
@orgcmd{C-c C-c,org-table-align}
-Re-align the table without moving the cursor.
+Re-align the table and don't move to another field.
@c
@orgcmd{<TAB>,org-table-next-field}
Re-align the table, move to the next field. Creates a new row if
@vindex org-table-copy-increment
When current field is empty, copy from first non-empty field above. When not
empty, copy current field down to next row and move cursor along with it.
-Depending on the variable @code{org-table-copy-increment}, integer field
+Depending on the option @code{org-table-copy-increment}, integer field
values will be incremented during copy. Integers that are too large will not
be incremented. Also, a @code{0} prefix argument temporarily disables the
increment. This key is also used by shift-selection and related modes
field. The follow mode exits automatically when the cursor leaves the table,
or when you repeat this command with @kbd{C-u C-u C-c `}.
@c
-@item M-x org-table-import
+@item M-x org-table-import RET
Import a file as a table. The table should be TAB or whitespace
separated. Use, for example, to import a spreadsheet table or data
from a database, because these programs generally can write
buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
@kbd{C-c |} command (see above under @i{Creation and conversion}).
@c
-@item M-x org-table-export
+@item M-x org-table-export RET
@findex org-table-export
@vindex org-table-export-default-format
Export the table, by default as a TAB-separated file. Use for data
exchange with, for example, spreadsheet or database programs. The format
-used to export the file can be configured in the variable
+used to export the file can be configured in the option
@code{org-table-export-default-format}. You may also use properties
@code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
name and the format for table export in a subtree. Org supports quite
to the right and of string-rich column to the left, you can use @samp{<r>},
@samp{<c>}@footnote{Centering does not work inside Emacs, but it does have an
effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may
-also combine alignment and field width like this: @samp{<l10>}.
+also combine alignment and field width like this: @samp{<r10>}.
Lines which only contain these formatting cookies will be removed
automatically when exporting the document.
If you like the intuitive way the Org table editor works, you
might also want to use it in other modes like Text mode or Mail mode.
The minor mode Orgtbl mode makes this possible. You can always toggle
-the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
+the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for
example in Message mode, use
@lisp
* Durations and time values:: How to compute durations and time values
* Field and range formulas:: Formula for specific (ranges of) fields
* Column formulas:: Formulas valid for an entire column
+* Lookup functions:: Lookup functions for searching tables
* Editing and debugging formulas:: Fixing formulas
* Updating the table:: Recomputing all dependent fields
* Advanced features:: Field and column names, parameters and automatic recalc
@vindex org-table-use-standard-references
However, Org prefers@footnote{Org will understand references typed by the
user as @samp{B4}, but it will not use this syntax when offering a formula
-for editing. You can customize this behavior using the variable
-@code{org-table-use-standard-references}.} to use another, more general
+for editing. You can customize this behavior using the option
+@code{org-table-use-standard-references}.} to use another, more general
representation that looks like this:
@example
@@@var{row}$@var{column}
$P..$Q @r{range, using column names (see under Advanced)}
$<<<..$>> @r{start in third column, continue to the one but last}
@@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
-@@-1$-2..@@-1 @r{in the first row up, 3 fields from 2 columns on the left}
+@@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left}
@@I..II @r{between first and second hline, short for @code{@@I..@@II}}
@end example
@noindent Range references return a vector of values that can be fed
-into Calc vector functions. Empty fields in ranges are normally
-suppressed, so that the vector contains only the non-empty fields (but
-see the @samp{E} mode switch below). If there are no non-empty fields,
-@samp{[0]} is returned to avoid syntax errors in formulas.
+into Calc vector functions. Empty fields in ranges are normally suppressed,
+so that the vector contains only the non-empty fields. For other options
+with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
+for Calc}.
@subsubheading Field coordinates in formulas
@cindex field coordinates
@vindex org-table-formula-constants
@samp{$name} is interpreted as the name of a column, parameter or
-constant. Constants are defined globally through the variable
+constant. Constants are defined globally through the option
@code{org-table-formula-constants}, and locally (for the file) through a
line like
@cindex references, to a different table
@cindex name, of column or field
@cindex constants, in calculations
-@cindex #+TBLNAME
+@cindex #+NAME, for table
You may also reference constants, fields and ranges from a different table,
either in the current file or even in a different file. The syntax is
@noindent
where NAME can be the name of a table in the current file as set by a
-@code{#+TBLNAME: NAME} line before the table. It can also be the ID of an
+@code{#+NAME: Name} line before the table. It can also be the ID of an
entry, even in a different file, and the reference then refers to the first
table in that entry. REF is an absolute field or range reference as
described above for example @code{@@3$3} or @code{$somename}, valid in the
@cindex formula syntax, Calc
@cindex syntax, of formulas
-A formula can be any algebraic expression understood by the Emacs
-@file{Calc} package. @b{Note that @file{calc} has the
-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
-Emacs Calc Manual}),
-variable substitution takes place according to the rules described above.
+A formula can be any algebraic expression understood by the Emacs @file{Calc}
+package. Note that @file{calc} has the 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 Emacs Calc Manual}), 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
like @samp{vmean} and @samp{vsum}.
execution. By default, Org uses the standard Calc modes (precision
12, angular units degrees, fraction and symbolic modes off). The display
format, however, has been changed to @code{(float 8)} to keep tables
-compact. The default settings can be configured using the variable
+compact. The default settings can be configured using the option
@code{org-calc-default-modes}.
-@example
-p20 @r{set the internal Calc calculation precision to 20 digits}
-n3 s3 e2 f4 @r{Normal, scientific, engineering, or fixed}
- @r{format of the result of Calc passed back to Org.}
- @r{Calc formatting is unlimited in precision as}
- @r{long as the Calc calculation precision is greater.}
-D R @r{angle modes: degrees, radians}
-F S @r{fraction and symbolic modes}
-N @r{interpret all fields as numbers, use 0 for non-numbers}
-E @r{keep empty fields in ranges}
-L @r{literal}
-@end example
+@noindent List of modes:
+
+@table @asis
+@item @code{p20}
+Set the internal Calc calculation precision to 20 digits.
+@item @code{n3}, @code{s3}, @code{e2}, @code{f4}
+Normal, scientific, engineering or fixed format of the result of Calc passed
+back to Org. Calc formatting is unlimited in precision as long as the Calc
+calculation precision is greater.
+@item @code{D}, @code{R}
+Degree and radian angle modes of Calc.
+@item @code{F}, @code{S}
+Fraction and symbolic modes of Calc.
+@item @code{T}, @code{t}
+Duration computations in Calc or Lisp, @pxref{Durations and time values}.
+@item @code{E}
+If and how to consider empty fields. Without @samp{E} empty fields in range
+references are suppressed so that the Calc vector or Lisp list contains only
+the non-empty fields. With @samp{E} the empty fields are kept. For empty
+fields in ranges or empty field references the value @samp{nan} (not a
+number) is used in Calc formulas and the empty string is used for Lisp
+formulas. Add @samp{N} to use 0 instead for both formula types. For the
+value of a field the mode @samp{N} has higher precedence than @samp{E}.
+@item @code{N}
+Interpret all fields as numbers, use 0 for non-numbers. See the next section
+to see how this is essential for computations with Lisp formulas. In Calc
+formulas it is used only occasionally because there number strings are
+already interpreted as numbers without @samp{N}.
+@item @code{L}
+Literal, for Lisp formulas only. See the next section.
+@end table
@noindent
-Unless you use large integer numbers or high-precision-calculation
-and -display for floating point numbers you may alternatively provide a
-@code{printf} format specifier to reformat the Calc result after it has been
+Unless you use large integer numbers or high-precision-calculation and
+-display for floating point numbers you may alternatively provide a
+@samp{printf} format specifier to reformat the Calc result after it has been
passed back to Org instead of letting Calc already do the
-formatting@footnote{The @code{printf} reformatting is limited in precision
-because the value passed to it is converted into an @code{integer} or
-@code{double}. The @code{integer} is limited in size by truncating the
-signed value to 32 bits. The @code{double} is limited in precision to 64
-bits overall which leaves approximately 16 significant decimal digits.}.
-A few examples:
+formatting@footnote{The @samp{printf} reformatting is limited in precision
+because the value passed to it is converted into an @samp{integer} or
+@samp{double}. The @samp{integer} is limited in size by truncating the
+signed value to 32 bits. The @samp{double} is limited in precision to 64
+bits overall which leaves approximately 16 significant decimal digits.}. A
+few examples:
@example
$1+$2 @r{Sum of first and second field}
$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
-vmean($2..$7) @r{Compute column range mean, using vector function}
-vmean($2..$7);EN @r{Same, but treat empty fields as 0}
taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
@end example
-Calc also contains a complete set of logical operations. For example
+Calc also contains a complete set of logical operations, (@pxref{Logical
+Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example
-@example
-if($1<20,teen,string("")) @r{"teen" if age $1 less than 20, else empty}
-@end example
+@table @code
+@item if($1 < 20, teen, string(""))
+"teen" if age $1 is less than 20, else the Org table result field is set to
+empty with the empty string.
+@item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E
+Sum of the first two columns. When at least one of the input fields is empty
+the Org table result field is set to empty.
+@item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
+Mean value of a range unless there is any empty field. Every field in the
+range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
+in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from
+@samp{vmean} and the Org table result field is set to empty. Use this when
+the sample set is expected to never have missing values.
+@item if("$1..$7" == "[]", string(""), vmean($1..$7))
+Mean value of a range with empty fields skipped. Every field in the range
+that is empty is skipped. When all fields in the range are empty the mean
+value is not defined and the Org table result field is set to empty. Use
+this when the sample set can have a variable size.
+@item vmean($1..$7); EN
+To complete the example before: Mean value of a range with empty fields
+counting as samples with value 0. Use this only when incomplete sample sets
+should be padded with 0 to the full size.
+@end table
-Note that you can also use two org-specific flags @code{T} and @code{t} for
-durations computations @ref{Durations and time values}.
+You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
+and use them in formula syntax for Calc.
@node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet
@subsection Emacs Lisp forms as formulas
Here are a few examples---note how the @samp{N} mode is used when we do
computations in Lisp:
-@example
-@r{Swap the first two characters of the content of column 1}
- '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
-@r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}}
- '(+ $1 $2);N
-@r{Compute the sum of columns 1--4, like Calc's @code{vsum($1..$4)}}
- '(apply '+ '($1..$4));N
-@end example
+@table @code
+@item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
+Swap the first two characters of the content of column 1.
+@item '(+ $1 $2);N
+Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
+@item '(apply '+ '($1..$4));N
+Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
+@end table
@node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet
@subsection Durations and time values
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,
-computed durations will be displayed according to the value of the variable
+computed durations will be displayed according to the value of the option
@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
example above).
Named field, see @ref{Advanced features}.
@end table
-@node Column formulas, Editing and debugging formulas, Field and range formulas, The spreadsheet
+@node Column formulas, Lookup functions, Field and range formulas, The spreadsheet
@subsection Column formulas
@cindex column formula
@cindex formula, for table column
When you assign a formula to a simple column reference like @code{$3=}, the
same formula will be used in all fields of that column, with the following
very convenient exceptions: (i) If the table contains horizontal separator
-hlines, everything before the first such line is considered part of the table
-@emph{header} and will not be modified by column formulas. (ii) Fields that
-already get a value from a field/range formula will be left alone by column
-formulas. These conditions make column formulas very easy to use.
+hlines with rows above and below, everything before the first such hline is
+considered part of the table @emph{header} and will not be modified by column
+formulas. Therefore a header is mandatory when you use column formulas and
+want to add hlines to group rows, like for example to separate a total row at
+the bottom from the summand rows above. (ii) Fields that already get a value
+from a field/range formula will be left alone by column formulas. These
+conditions make column formulas very easy to use.
To assign a formula to a column, type it directly into any field in the
column, preceded by an equal sign, like @samp{=$1+$2}. When you press
will apply it to that many consecutive fields in the current column.
@end table
-@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet
+@node Lookup functions, Editing and debugging formulas, Column formulas, The spreadsheet
+@subsection Lookup functions
+@cindex lookup functions in tables
+@cindex table lookup functions
+
+Org has three predefined Emacs Lisp functions for lookups in tables.
+@table @code
+@item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
+@findex org-lookup-first
+Searches for the first element @code{S} in list @code{S-LIST} for which
+@lisp
+(PREDICATE VAL S)
+@end lisp
+is @code{t}; returns the value from the corresponding position in list
+@code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the
+parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
+order as the corresponding parameters are in the call to
+@code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If
+@code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
+is returned.
+@item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
+@findex org-lookup-last
+Similar to @code{org-lookup-first} above, but searches for the @i{last}
+element for which @code{PREDICATE} is @code{t}.
+@item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
+@findex org-lookup-all
+Similar to @code{org-lookup-first}, but searches for @i{all} elements for
+which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
+values. This function can not be used by itself in a formula, because it
+returns a list of values. However, powerful lookups can be built when this
+function is combined with other Emacs Lisp functions.
+@end table
+
+If the ranges used in these functions contain empty fields, the @code{E} mode
+for the formula should usually be specified: otherwise empty fields will not be
+included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
+in an incorrect mapping from an element of @code{S-LIST} to the corresponding
+element of @code{R-LIST}.
+
+These three functions can be used to implement associative arrays, count
+matching cells, rank results, group data etc. For practical examples
+see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
+tutorial on Worg}.
+
+@node Editing and debugging formulas, Updating the table, Lookup functions, The spreadsheet
@subsection Editing and debugging formulas
@cindex formula editing
@cindex editing, of table formulas
@vindex org-table-use-standard-references
-You can edit individual formulas in the minibuffer or directly in the
-field. Org can also prepare a special buffer with all active
-formulas of a table. When offering a formula for editing, Org
-converts references to the standard format (like @code{B3} or @code{D&})
-if possible. If you prefer to only work with the internal format (like
-@code{@@3$2} or @code{$4}), configure the variable
-@code{org-table-use-standard-references}.
+You can edit individual formulas in the minibuffer or directly in the field.
+Org can also prepare a special buffer with all active formulas of a table.
+When offering a formula for editing, Org converts references to the standard
+format (like @code{B3} or @code{D&}) if possible. If you prefer to only work
+with the internal format (like @code{@@3$2} or @code{$4}), configure the
+option @code{org-table-use-standard-references}.
@table @kbd
@orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
While inside the special buffer, Org will automatically highlight
any field or range reference at the cursor position. You may edit,
remove and add formulas, and use the following commands:
+
@table @kbd
@orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
Exit the formula editor and store the modified formulas. With @kbd{C-u}
equations with @kbd{C-c C-c} in that line or with the normal
recalculation commands in the table.
+@anchor{Using multiple #+TBLFM lines}
+@subsubheading Using multiple #+TBLFM lines
+@cindex #+TBLFM line, multiple
+@cindex #+TBLFM
+@cindex #+TBLFM, switching
+@kindex C-c C-c
+
+You may apply the formula temporarily. This is useful when you
+switch the formula. Place multiple @samp{#+TBLFM} lines right
+after the table, and then press @kbd{C-c C-c} on the formula to
+apply. Here is an example:
+
+@example
+| x | y |
+|---+---|
+| 1 | |
+| 2 | |
+#+TBLFM: $2=$1*1
+#+TBLFM: $2=$1*2
+@end example
+
+@noindent
+Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
+
+@example
+| x | y |
+|---+---|
+| 1 | 2 |
+| 2 | 4 |
+#+TBLFM: $2=$1*1
+#+TBLFM: $2=$1*2
+@end example
+
+@noindent
+Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
+will get the following result of applying only the first @samp{#+TBLFM} line.
+
+@example
+| x | y |
+|---+---|
+| 1 | 1 |
+| 2 | 2 |
+#+TBLFM: $2=$1*1
+#+TBLFM: $2=$1*2
+@end example
+
@subsubheading Debugging formulas
@cindex formula debugging
@cindex debugging, of table formulas
Iterate the table by recomputing it until no further changes occur.
This may be necessary if some computed fields use the value of other
fields that are computed @i{later} in the calculation sequence.
-@item M-x org-table-recalculate-buffer-tables
+@item M-x org-table-recalculate-buffer-tables RET
@findex org-table-recalculate-buffer-tables
Recompute all tables in the current buffer.
-@item M-x org-table-iterate-buffer-tables
+@item M-x org-table-iterate-buffer-tables RET
@findex org-table-iterate-buffer-tables
Iterate all tables in the current buffer, in order to converge table-to-table
dependencies.
@cindex marking characters, tables
The marking characters have the following meaning:
+
@table @samp
@item !
The fields in this line define names for the columns, so that you may
If the link does not look like a URL, it is considered to be internal in the
current file. The most important case is a link like
@samp{[[#my-custom-id]]} which will link to the entry with the
-@code{CUSTOM_ID} property @samp{my-custom-id}. Such custom IDs are very good
-for HTML export (@pxref{HTML export}) where they produce pretty section
-links. You are responsible yourself to make sure these custom IDs are unique
-in a file.
+@code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
+to make sure these custom IDs are unique in a file.
Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
lead to a text search in the current file.
The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
or with a mouse click (@pxref{Handling links}). Links to custom IDs will
point to the corresponding headline. The preferred match for a text link is
-a @i{dedicated target}: the same string in double angular brackets. Targets
-may be located anywhere; sometimes it is convenient to put them into a
-comment line. For example
+a @i{dedicated target}: the same string in double angular brackets, like
+@samp{<<My Target>>}.
+
+@cindex #+NAME
+If no dedicated target exists, the link will then try to match the exact name
+of an element within the buffer. Naming is done with the @code{#+NAME}
+keyword, which has to be put the line before the element it refers to, as in
+the following example
@example
-# <<My Target>>
+#+NAME: My Target
+| a | table |
+|----+------------|
+| of | four cells |
@end example
-@noindent In HTML export (@pxref{HTML export}), such targets will become
-named anchors for direct access through @samp{http} links@footnote{Note that
-text before the first headline is usually not exported, so the first such
-target should be after the first headline, or in the line directly before the
-first headline.}.
-
-If no dedicated target exists, Org will search for a headline that is exactly
+If none of the above succeeds, Org will search for a headline that is exactly
the link text but may also include a TODO keyword and tags@footnote{To insert
-a link targeting a headline, in-buffer completion can be used. Just type a
-star followed by a few optional letters into the buffer and press
+a link targeting a headline, in-buffer completion can be used. Just type
+a star followed by a few optional letters into the buffer and press
@kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
-completions.}. In non-Org files, the search will look for the words in the
-link text. In the above example the search would be for @samp{my target}.
+completions.}.
+
+During export, internal links will be used to mark objects and assign them
+a number. Marked objects will then be referenced by links pointing to them.
+In particular, links without a description will appear as the number assigned
+to the marked object@footnote{When targeting a @code{#+NAME} keyword,
+@code{#+CAPTION} keyword is mandatory in order to get proper numbering
+(@pxref{Images and tables}).}. In the following excerpt from an Org buffer
+
+@example
+- one item
+- <<target>>another item
+Here we refer to item [[target]].
+@end example
+
+@noindent
+The last sentence will appear as @samp{Here we refer to item 2} when
+exported.
+
+In non-Org files, the search will look for the words in the link text. In
+the above example the search would be for @samp{my target}.
Following a link pushes a mark onto Org's own mark ring. You can
return to the previous position with @kbd{C-c &}. Using this command
@section External links
@cindex links, external
@cindex external links
-@cindex links, external
@cindex Gnus links
@cindex BBDB links
@cindex IRC links
@cindex URL links
@cindex file links
-@cindex VM links
@cindex RMAIL links
-@cindex WANDERLUST links
@cindex MH-E links
@cindex USENET links
@cindex SHELL links
@cindex Info links
@cindex Elisp links
-Org supports links to files, websites, Usenet and email messages,
-BBDB database entries and links to both IRC conversations and their
-logs. External links are URL-like locators. They start with a short
-identifying string followed by a colon. There can be no space after
-the colon. The following list shows examples for each link type.
+Org supports links to files, websites, Usenet and email messages, BBDB
+database entries and links to both IRC conversations and their logs.
+External links are URL-like locators. They start with a short identifying
+string followed by a colon. There can be no space after the colon. The
+following list shows examples for each link type.
@example
http://www.astro.uva.nl/~dominik @r{on the web}
file:projects.org @r{another 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
+the option @code{org-link-search-must-match-exact-headline}. If its value
+is @code{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.}
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}
-vm:folder @r{VM folder link}
-vm:folder#id @r{VM message link}
-vm://myself@@some.where.org/folder#id @r{VM on remote machine}
-vm-imap:account:folder @r{VM IMAP folder link}
-vm-imap:account:folder#id @r{VM IMAP message link}
-wl:folder @r{WANDERLUST folder link}
-wl:folder#id @r{WANDERLUST message link}
mhe:folder @r{MH-E folder link}
mhe:folder#id @r{MH-E message link}
rmail:folder @r{RMAIL folder link}
elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
@end example
+@cindex VM links
+@cindex WANDERLUST links
+On top of these built-in link types, some are available through the
+@code{contrib/} directory (@pxref{Installation}). For example, these links
+to VM or Wanderlust messages are available when you load the corresponding
+libraries from the @code{contrib/} directory:
+
+@example
+vm:folder @r{VM folder link}
+vm:folder#id @r{VM message link}
+vm://myself@@some.where.org/folder#id @r{VM on remote machine}
+vm-imap:account:folder @r{VM IMAP folder link}
+vm-imap:account:folder#id @r{VM IMAP message link}
+wl:folder @r{WANDERLUST folder link}
+wl:folder#id @r{WANDERLUST message link}
+@end example
+
For customizing Org to add new link types @ref{Adding hyperlink types}.
-A link should be enclosed in double brackets and may contain a
-descriptive text to be displayed instead of the URL (@pxref{Link
-format}), for example:
+A link should be enclosed in double brackets and may contain a descriptive
+text to be displayed instead of the URL (@pxref{Link format}), for example:
@example
[[http://www.gnu.org/software/emacs/][GNU Emacs]]
If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
will be stored. In addition or alternatively (depending on the value of
@code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
-be created and/or used to construct a link@footnote{The library @code{org-id}
-must first be loaded, either through @code{org-customize} by enabling
-@code{id} in @code{org-modules} , or by adding @code{(require 'org-id)} in
-your @file{.emacs}.}. So using this command in Org
-buffers will potentially create two links: a human-readable from the custom
-ID, and one that is globally unique and works even if the entry is moved from
-file to file. Later, when inserting the link, you need to decide which one
-to use.
+be created and/or used to construct a link@footnote{The library
+@file{org-id.el} must first be loaded, either through @code{org-customize} by
+enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
+'org-id)} in your @file{.emacs}.}. So using this command in Org buffers will
+potentially create two links: a human-readable from the custom ID, and one
+that is globally unique and works even if the entry is moved from file to
+file. Later, when inserting the link, you need to decide which one to use.
@b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
Pretty much all Emacs mail clients are supported. The link will point to the
@b{Chat: IRC}@*
@vindex org-irc-link-to-logs
-For IRC links, if you set the variable @code{org-irc-link-to-logs} to
-@code{t}, a @samp{file:/} style link to the relevant point in the logs for
-the current conversation is created. Otherwise an @samp{irc:/} style link to
-the user/channel/server under the point will be stored.
+For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
+a @samp{file:/} style link to the relevant point in the logs for the current
+conversation is created. Otherwise an @samp{irc:/} style link to the
+user/channel/server under the point will be stored.
@b{Other files}@*
For any other files, the link will point to the file, with a search string
@vindex org-display-internal-link-with-indirect-buffer
Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
internal links to be displayed in another window@footnote{See the
-variable @code{org-display-internal-link-with-indirect-buffer}}.
+option @code{org-display-internal-link-with-indirect-buffer}}.
@c
@orgcmd{C-c C-x C-v,org-toggle-inline-images}
@cindex inlining images
images that do have a link description. You can ask for inline images to be
displayed at startup by configuring the variable
@code{org-startup-with-inline-images}@footnote{with corresponding
-@code{#+STARTUP} keywords @code{inlineimages} and @code{inlineimages}}.
+@code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
@orgcmd{C-c %,org-mark-ring-push}
@cindex mark ring
Push the current position onto the mark ring, to be able to return
If TODO keywords have fast access keys (see @ref{Fast access to TODO
states}), you will be prompted for a TODO keyword through the fast selection
interface; this is the default behavior when
-@var{org-use-fast-todo-selection} is @code{non-nil}.
+@code{org-use-fast-todo-selection} is non-@code{nil}.
The same rotation can also be done ``remotely'' from the timeline and agenda
buffers with the @kbd{t} command key (@pxref{Agenda commands}).
@orgkey{C-u C-c C-t}
When TODO keywords have no selection keys, select a specific keyword using
completion; otherwise force cycling through TODO states with no prompt. When
-@var{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
+@code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
selection interface.
@kindex S-@key{right}
View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
entire buffer, but shows all TODO items (with not-DONE state) and the
headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
-/ T}), search for a specific TODO@. You will be prompted for the keyword, and
-you can also give a list of keywords like @code{KWD1|KWD2|...} to list
+/ T}), search for a specific TODO@. You will be prompted for the keyword,
+and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
entries that match any one of these keywords. With a numeric prefix argument
-N, show the tree for the Nth keyword in the variable
-@code{org-todo-keywords}. With two prefix arguments, find all TODO states,
-both un-done and done.
+N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
+With two prefix arguments, find all TODO states, both un-done and done.
@orgcmd{C-c a t,org-todo-list}
Show the global TODO list. Collects the TODO items (with not-DONE states)
from all agenda files (@pxref{Agenda Views}) into a single buffer. The new
@vindex org-fast-tag-selection-include-todo
If you then press @kbd{C-c C-t} followed by the selection key, the entry
will be switched to this state. @kbd{SPC} can be used to remove any TODO
-keyword from an entry.@footnote{Check also the variable
+keyword from an entry.@footnote{Check also the option
@code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
state through the tags interface (@pxref{Setting tags}), in case you like to
mingle the two concepts. Note that this means you need to come up with
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
-special faces for some of them. This can be done using the variable
+special faces for some of them. This can be done using the option
@code{org-todo-keyword-faces}. For example:
@lisp
While using a list with face properties as shown for CANCELED @emph{should}
work, this does not always seem to be the case. If necessary, define a
-special face and use that. A string is interpreted as a color. The variable
+special face and use that. A string is interpreted as a color. The option
@code{org-faces-easy-properties} determines if that color is interpreted as a
foreground or a background color.
all subtasks (defined as children tasks) are marked as DONE@. And sometimes
there is a logical sequence to a number of (sub)tasks, so that one task
cannot be acted upon before all siblings above it are done. If you customize
-the variable @code{org-enforce-todo-dependencies}, Org will block entries
+the option @code{org-enforce-todo-dependencies}, Org will block entries
from changing state to DONE while they have children that are not DONE@.
Furthermore, if an entry has a property @code{ORDERED}, each of its children
will be blocked until all earlier siblings are marked DONE@. Here is an
Toggle the @code{ORDERED} property of the current entry. A property is used
for this behavior because this should be local to the current entry, not
inherited like a tag. However, if you would like to @i{track} the value of
-this property with a tag for better visibility, customize the variable
+this property with a tag for better visibility, customize the option
@code{org-track-ordered-property-with-tag}.
@orgkey{C-u C-u C-u C-c C-t}
Change TODO state, circumventing any state blocking.
@end table
@vindex org-agenda-dim-blocked-tasks
-If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries
+If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
that cannot be closed because of such dependencies will be shown in a dimmed
font or even made invisible in agenda views (@pxref{Agenda Views}).
@cindex checkboxes and TODO dependencies
@vindex org-enforce-todo-dependencies
You can also block changes of TODO states by looking at checkboxes
-(@pxref{Checkboxes}). If you set the variable
+(@pxref{Checkboxes}). If you set the option
@code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
checkboxes will be blocked from switching to DONE.
(setq org-log-done 'time)
@end lisp
+@vindex org-closed-keep-when-no-todo
@noindent
-Then each time you turn an entry from a TODO (not-done) state into any
-of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted
-just after the headline. If you turn the entry back into a TODO item
-through further state cycling, that line will be removed again. If you
-want to record a note along with the timestamp, use@footnote{The
-corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}}
+Then each time you turn an entry from a TODO (not-done) state into any of the
+DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
+the headline. If you turn the entry back into a TODO item through further
+state cycling, that line will be removed again. If you turn the entry back
+to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
+will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
+non-@code{nil}. If you want to record a note along with the timestamp,
+use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
+lognotedone}.}
@lisp
(setq org-log-done 'note)
might want to keep track of when a state change occurred and maybe take a
note about this change. You can either record just a timestamp, or a
time-stamped note for a change. These records will be inserted after the
-headline as an itemized list, newest first@footnote{See the variable
+headline as an itemized list, newest first@footnote{See the option
@code{org-log-states-order-reversed}}. When taking a lot of notes, you might
want to get the notes out of the way into a drawer (@pxref{Drawers}).
-Customize the variable @code{org-log-into-drawer} to get this behavior---the
-recommended drawer for this is called @code{LOGBOOK}@footnote{Note that the
+Customize @code{org-log-into-drawer} to get this behavior---the recommended
+drawer for this is called @code{LOGBOOK}@footnote{Note that the
@code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
show an entry---use @key{C-u SPC} to keep it folded here}. You can also
overrule the setting of this variable for a subtree by setting a
@cindex property, LOGGING
In order to define logging settings that are local to a subtree or a
single item, define a LOGGING property in this entry. Any non-empty
-LOGGING property resets all logging settings to nil. You may then turn
+LOGGING property resets all logging settings to @code{nil}. You may then turn
on logging for this specific tree using STARTUP keywords like
@code{lognotedone} or @code{logrepeat}, as well as adding state specific
settings like @code{TODO(!)}. For example
@enumerate
@item
-You have enabled the @code{habits} module by customizing the variable
-@code{org-modules}.
+You have enabled the @code{habits} module by customizing @code{org-modules}.
@item
The habit is a TODO item, with a TODO keyword representing an open state.
@item
@item org-habit-following-days
The number of days after today that will appear in consistency graphs.
@item org-habit-show-habits-only-for-today
-If non-nil, only show habits in today's agenda view. This is set to true by
+If non-@code{nil}, only show habits in today's agenda view. This is set to true by
default.
@end table
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
-special faces by customizing the variable @code{org-priority-faces}.
+special faces by customizing @code{org-priority-faces}.
Priorities can be attached to any outline node; they do not need to be TODO
items.
@vindex org-highest-priority
@vindex org-lowest-priority
@vindex org-default-priority
-You can change the range of allowed priorities by setting the variables
+You can change the range of allowed priorities by setting the options
@code{org-highest-priority}, @code{org-lowest-priority}, and
@code{org-default-priority}. For an individual buffer, you may set
these values (highest, lowest, default) like this (please make sure that
@vindex org-hierarchical-todo-statistics
If you would like to have the statistics cookie count any TODO entries in the
-subtree (not just direct children), configure the variable
+subtree (not just direct children), configure
@code{org-hierarchical-todo-statistics}. To do this for a single subtree,
include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
property.
@cindex statistics, for checkboxes
@cindex checkbox statistics
@cindex property, COOKIE_DATA
-@vindex org-hierarchical-checkbox-statistics
+@vindex org-checkbox-hierarchical-statistics
The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
indicating how many checkboxes present in this entry have been checked off,
and the total number of checkboxes present. This can give you an idea on how
many checkboxes remain, even without opening a folded entry. The cookies can
be placed into a headline or into (the first line of) a plain list item.
Each cookie covers checkboxes of direct children structurally below the
-headline/item on which the cookie appears@footnote{Set the variable
-@code{org-hierarchical-checkbox-statistics} if you want such cookies to
+headline/item on which the cookie appears@footnote{Set the option
+@code{org-checkbox-hierarchical-statistics} if you want such cookies to
count all checkboxes below the cookie, not just those belonging to direct
children.}. You have to insert the cookie yourself by typing either
@samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
be checked off in sequence. A property is used for this behavior because
this should be local to the current entry, not inherited like a tag.
However, if you would like to @i{track} the value of this property with a tag
-for better visibility, customize the variable
-@code{org-track-ordered-property-with-tag}.
+for better visibility, customize @code{org-track-ordered-property-with-tag}.
@orgcmd{C-c #,org-update-statistics-cookies}
Update the statistics cookie in the current outline entry. When called with
a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
@samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
Tags will by default be in bold face with the same color as the headline.
-You may specify special faces for specific tags using the variable
+You may specify special faces for specific tags using the option
@code{org-tag-faces}, in much the same way as you can for TODO keywords
(@pxref{Faces for TODO keywords}).
@menu
* Tag inheritance:: Tags use the tree structure of the outline
* Setting tags:: How to assign tags to a headline
+* Tag groups:: Use one tag to search for several tags
* Tag searches:: Searching for combinations of tags
@end menu
as well@footnote{This is only true if the search does not involve more
complex tests including properties (@pxref{Property searches}).}. The list
of matches may then become very long. If you only want to see the first tags
-match in a subtree, configure the variable
-@code{org-tags-match-list-sublevels} (not recommended).
+match in a subtree, configure @code{org-tags-match-list-sublevels} (not
+recommended).
@vindex org-agenda-use-tag-inheritance
Tag inheritance is relevant when the agenda search tries to match a tag,
types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
have your tags correctly set in the agenda, so that tag filtering works fine,
with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
-this: the default value includes all agenda types, but setting this to nil
+this: the default value includes all agenda types, but setting this to @code{nil}
can really speed up agenda generation.
-@node Setting tags, Tag searches, Tag inheritance, Tags
+@node Setting tags, Tag groups, Tag inheritance, Tags
@section Setting tags
@cindex setting tags
@cindex tags, setting
tags in the current buffer will be aligned to that column, just to make
things look nice. TAGS are automatically realigned after promotion,
demotion, and TODO state changes (@pxref{TODO basics}).
+
@orgcmd{C-c C-c,org-set-tags-command}
When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
@end table
these lines to activate any changes.
@noindent
-To set these mutually exclusive groups in the variable @code{org-tags-alist},
+To set these mutually exclusive groups in the variable @code{org-tag-alist},
you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
of the braces. Similarly, you can use @code{:newline} to indicate a line
break. The previous example would be set globally by the following
@vindex org-fast-tag-selection-single-key
If you find that most of the time you need only a single key press to
-modify your list of tags, set the variable
-@code{org-fast-tag-selection-single-key}. Then you no longer have to
-press @key{RET} to exit fast tag selection---it will immediately exit
-after the first change. If you then occasionally need more keys, press
-@kbd{C-c} to turn off auto-exit for the current tag selection process
-(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c
-C-c}). If you set the variable to the value @code{expert}, the special
-window is not even shown for single-key tag selection, it comes up only
-when you press an extra @kbd{C-c}.
-
-@node Tag searches, , Setting tags, Tags
+modify your list of tags, set @code{org-fast-tag-selection-single-key}.
+Then you no longer have to press @key{RET} to exit fast tag selection---it
+will immediately exit after the first change. If you then occasionally
+need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
+selection process (in effect: start selection with @kbd{C-c C-c C-c}
+instead of @kbd{C-c C-c}). If you set the variable to the value
+@code{expert}, the special window is not even shown for single-key tag
+selection, it comes up only when you press an extra @kbd{C-c}.
+
+@node Tag groups, Tag searches, Setting tags, Tags
+@section Tag groups
+
+@cindex group tags
+@cindex tags, groups
+In a set of mutually exclusive tags, the first tag can be defined as a
+@emph{group tag}. When you search for a group tag, it will return matches
+for all members in the group. In an agenda view, filtering by a group tag
+will display headlines tagged with at least one of the members of the
+group. This makes tag searches and filters even more flexible.
+
+You can set group tags by inserting a colon between the group tag and other
+tags---beware that all whitespaces are mandatory so that Org can parse this
+line correctly:
+
+@example
+#+TAGS: @{ @@read : @@read_book @@read_ebook @}
+@end example
+
+In this example, @samp{@@read} is a @emph{group tag} for a set of three
+tags: @samp{@@read}, @samp{@@read_book} and @samp{@@read_ebook}.
+
+You can also use the @code{:grouptags} keyword directly when setting
+@code{org-tag-alist}:
+
+@lisp
+(setq org-tag-alist '((:startgroup . nil)
+ ("@@read" . nil)
+ (:grouptags . nil)
+ ("@@read_book" . nil)
+ ("@@read_ebook" . nil)
+ (:endgroup . nil)))
+@end lisp
+
+You cannot nest group tags or use a group tag as a tag in another group.
+
+@kindex C-c C-x q
+@vindex org-group-tags
+If you want to ignore group tags temporarily, toggle group tags support
+with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you
+want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
+
+@node Tag searches, , Tag groups, Tags
@section Tag searches
@cindex tag searches
@cindex searching for tags
@table @kbd
@orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
-Create a sparse tree with all headlines matching a tags search. With a
-@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
-@orgcmd{C-c a m,org-tags-view}
-Create a global list of tag matches from all agenda files.
+Create a sparse tree with all headlines matching a tags/property/TODO search.
+With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
@xref{Matching tags and properties}.
+@orgcmd{C-c a m,org-tags-view}
+Create a global list of tag matches from all agenda files. @xref{Matching
+tags and properties}.
@orgcmd{C-c a M,org-tags-view}
@vindex org-tags-match-list-sublevels
Create a global list of tag matches from all agenda files, but check
-only TODO items and force checking subitems (see variable
+only TODO items and force checking subitems (see the option
@code{org-tags-match-list-sublevels}).
@end table
#+PROPERTY: NDisks_ALL 1 2 3 4
@end example
+Contrary to properties set from a special drawer, you have to refresh the
+buffer with @kbd{C-c C-c} to activate this changes.
+
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''.
@orgcmd{C-c C-x p,org-set-property}
Set a property. This prompts for a property name and a value. If
necessary, the property drawer is created as well.
-@item C-u M-x org-insert-drawer
+@item C-u M-x org-insert-drawer RET
@cindex org-insert-drawer
Insert a property drawer into the current entry. The drawer will be
inserted early in the entry, but after the lines with planning
To create sparse trees and special lists with selection based on properties,
the same commands are used as for tag searches (@pxref{Tag searches}).
+
@table @kbd
@orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
Create a sparse tree with all matching entries. With a
@orgcmd{C-c a M,org-tags-view}
@vindex org-tags-match-list-sublevels
Create a global list of tag matches from all agenda files, but check
-only TODO items and force checking of subitems (see variable
+only TODO items and force checking of subitems (see the option
@code{org-tags-match-list-sublevels}).
@end table
@code{org-use-property-inheritance}. It may be set to @code{t} to make
all properties inherited from the parent, to a list of properties
that should be inherited, or to a regular expression that matches
-inherited properties. If a property has the value @samp{nil}, this is
+inherited properties. If a property has the value @code{nil}, this is
interpreted as an explicit undefine of the property, so that inheritance
search will stop at this value and return @code{nil}.
@r{run column view at the top of this file}
"@var{ID}" @r{call column view in the tree that has an @code{:ID:}}
@r{property with the value @i{label}. You can use}
- @r{@kbd{M-x org-id-copy} to create a globally unique ID for}
+ @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for}
@r{the current entry and copy it to the kill-ring.}
@end example
@item :hlines
@vindex org-read-date-prefer-future
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
+format. But it will in fact accept date/time information in a variety of
+formats. Generally, the information should start at the beginning of the
+string. 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
14 @result{} @b{2006}-@b{06}-14
12 @result{} @b{2006}-@b{07}-12
2/5 @result{} @b{2007}-02-05
-Fri @result{} nearest Friday (default date or later)
+Fri @result{} nearest Friday after the default date
sep 15 @result{} @b{2006}-09-15
feb 15 @result{} @b{2007}-02-15
sep 12 9 @result{} 2009-09-12
2012-w04-5 @result{} Same as above
@end example
-Furthermore you can specify a relative date by giving, as the
-@emph{first} thing in the input: a plus/minus sign, a number and a
-letter ([dwmy]) to indicate change in days, weeks, months, or years. With a
-single plus or minus, the date is always relative to today. With a
-double plus or minus, it is relative to the default date. If instead of
-a single letter, you use the abbreviation of day name, the date will be
-the Nth such day, e.g.:
+Furthermore you can specify a relative date by giving, as the @emph{first}
+thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to
+indicate change in hours, days, weeks, months, or years. With a single plus
+or minus, the date is always relative to today. With a double plus or minus,
+it is relative to the default date. If instead of a single letter, you use
+the abbreviation of day name, the date will be the Nth such day, e.g.:
@example
+0 @result{} today
+4 @result{} same as above
+2w @result{} two weeks from today
++5 @result{} five days from default date
-+2tue @result{} second Tuesday from now.
++2tue @result{} second Tuesday from now
+-wed @result{} last Wednesday
@end example
@vindex parse-time-months
will grow on you, and you will start getting annoyed by pretty much any other
way of entering a date/time out there. To help you understand what is going
on, the current interpretation of your input will be displayed live in the
-minibuffer@footnote{If you find this distracting, turn the display of with
+minibuffer@footnote{If you find this distracting, turn the display off with
@code{org-read-date-display-live}.}.
@node Custom time format, , The date/time prompt, Creating timestamps
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
+customizing the options @code{org-display-custom-times} and
@code{org-time-stamp-custom-formats}.
@table @kbd
to be finished on that date.
@vindex org-deadline-warning-days
+@vindex org-agenda-skip-deadline-prewarning-if-scheduled
On the deadline date, the task will be listed in the agenda. In
addition, the agenda for @emph{today} will carry a warning about the
approaching or missed deadline, starting
You can specify a different lead time for warnings for a specific
deadlines using the following syntax. Here is an example with a warning
-period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}.
+period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. This warning is
+deactivated if the task get scheduled and you set
+@code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
@item SCHEDULED
@cindex SCHEDULED keyword
SCHEDULED: <2004-12-25 Sat>
@end example
+@vindex org-scheduled-delay-days
+@vindex org-agenda-skip-scheduled-delay-if-deadline
+If you want to @emph{delay} the display of this task in the agenda, use
+@code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the
+25th but will appear two days later. In case the task contains a repeater,
+the delay is considered to affect all occurrences; if you want the delay to
+only affect the first scheduled occurrence of the task, use @code{--2d}
+instead. See @code{org-scheduled-delay-days} and
+@code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to
+control this globally or per agenda.
+
@noindent
@b{Important:} Scheduling an item in Org mode should @i{not} be
understood in the same way that we understand @i{scheduling a meeting}.
today.
@end example
-You may have both scheduling and deadline information for a specific
-task---just make sure that the repeater intervals on both are the same.
+@vindex org-agenda-skip-scheduled-if-deadline-is-shown
+You may have both scheduling and deadline information for a specific task.
+If the repeater is set for the scheduling information only, you probably want
+the repeater to be ignored after the deadline. If so, set the variable
+@code{org-agenda-skip-scheduled-if-deadline-is-shown} to
+@code{repeated-after-deadline}. If you want both scheduling and deadline
+information to repeat after the same interval, set the same repeater for both
+timestamps.
An alternative to using a repeater is to create a number of copies of a task
subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was
thisyear, lastyear, thisyear-@var{N} @r{a relative year}
@r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
:tstart @r{A time string specifying when to start considering times.}
+ @r{Relative times like @code{"<-2w>"} can also be used. See}
+ @r{@ref{Matching tags and properties} for relative time syntax.}
:tend @r{A time string specifying when to stop considering times.}
+ @r{Relative times like @code{"<now>"} can also be used. See}
+ @r{@ref{Matching tags and properties} for relative time syntax.}
+:wstart @r{The starting day of the week. The default is 1 for monday.}
+:mstart @r{The starting day of the month. The default 1 is for the first}
+ @r{day of the month.}
:step @r{@code{week} or @code{day}, to split the table into chunks.}
@r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
:stepskip0 @r{Do not show steps that have zero time.}
:tend "<2006-08-10 Thu 12:00>"
#+END: clocktable
@end example
+A range starting a week ago and ending right now could be written as
+@example
+#+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
+#+END: clocktable
+@end example
A summary of the current subtree with % times would be
@example
#+BEGIN: clocktable :scope subtree :link t :formula %
@subsubheading Resolving idle time
@cindex resolve idle time
+@vindex org-clock-x11idle-program-name
@cindex idle, resolve, dangling
If you clock in on a work item, and then walk away from your
being idle for that many minutes@footnote{On computers using Mac OS X,
idleness is based on actual user idleness, not just Emacs' idle time. For
X11, you can install a utility program @file{x11idle.c}, available in the
-@code{contrib/scripts} directory of the Org git distribution, to get the same
-general treatment of idleness. On other systems, idle time refers to Emacs
-idle time only.}, and ask what you want to do with the idle time. There will
-be a question waiting for you when you get back, indicating how much idle
-time has passed (constantly updated with the current amount), as well as a
-set of choices to correct the discrepancy:
+@code{contrib/scripts} directory of the Org git distribution, or install the
+@file{xprintidle} package and set it to the variable
+@code{org-clock-x11idle-program-name} if you are running Debian, to get the
+same general treatment of idleness. On other systems, idle time refers to
+Emacs idle time only.}, and ask what you want to do with the idle time.
+There will be a question waiting for you when you get back, indicating how
+much idle time has passed (constantly updated with the current amount), as
+well as a set of choices to correct the discrepancy:
@table @kbd
@item k
* Attachments:: Add files to tasks
* RSS Feeds:: Getting input from RSS feeds
* Protocols:: External (e.g., Browser) access to Emacs and Org
-* Refiling notes:: Moving a tree from one place to another
+* Refile and copy:: Moving/copying a tree from one place to another
* Archiving:: What to do with finished projects
@end menu
@section Capture
@cindex capture
-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
-backward compatibility with existing setups. You can find the documentation
-for org-remember at @url{http://orgmode.org/org-remember.pdf}.
+Capture lets you quickly store notes with little interruption of your work
+flow. Org's method for capturing new items is heavily inspired by John
+Wiegley excellent @file{remember.el} package. Up to version 6.36, Org
+used a special setup for @file{remember.el}, then replaced it with
+@file{org-remember.el}. As of version 8.0, @file{org-remember.el} has
+been completely replaced by @file{org-capture.el}.
-The new capturing setup described here is preferred and should be used by new
-users. To convert your @code{org-remember-templates}, run the command
+If your configuration depends on @file{org-remember.el}, you need to update
+it and use the setup described below. To convert your
+@code{org-remember-templates}, run the command
@example
-@kbd{M-x org-capture-import-remember-templates @key{RET}}
+@kbd{M-x org-capture-import-remember-templates RET}
@end example
@noindent and then customize the new variable with @kbd{M-x
customize-variable org-capture-templates}, check the result, and save the
-customization. You can then use both remember and capture until
-you are familiar with the new mechanism.
-
-Capture lets you quickly store notes with little interruption of your work
-flow. The basic process of capturing is very similar to remember, but Org
-does enhance it with templates and more.
+customization.
@menu
* Setting up capture:: Where notes will be stored
suggestion.} for capturing new material.
@vindex org-default-notes-file
-@example
+@smalllisp
+@group
(setq org-default-notes-file (concat org-directory "/notes.org"))
(define-key global-map "\C-cc" 'org-capture)
-@end example
+@end group
+@end smalllisp
@node Using capture, Capture templates, Setting up capture, Capture
@subsection Using capture
with a prefix arg, finalize and then jump to the captured item.
@orgcmd{C-c C-w,org-capture-refile}
-Finalize the capture process by refiling (@pxref{Refiling notes}) the note to
+Finalize the capture process by refiling (@pxref{Refile and copy}) the note to
a different place. Please realize that this is a normal refiling command
that will be executed---so the cursor position at the moment you run this
command is important. If you have inserted a tree with a parent and
@file{journal.org} should capture journal entries. A possible configuration
would look like:
-@example
+@smalllisp
+@group
(setq org-capture-templates
'(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
"* TODO %?\n %i\n %a")
("j" "Journal" entry (file+datetree "~/org/journal.org")
"* %?\nEntered on %U\n %i\n %a")))
-@end example
+@end group
+@end smalllisp
@noindent If you then press @kbd{C-c c t}, Org will prepare the template
for you like this:
During expansion of the template, @code{%a} has been replaced by a link to
the location from where you called the capture command. This can be
extremely useful for deriving tasks from emails, for example. You fill in
-the task definition, press @code{C-c C-c} and Org returns you to the same
+the task definition, press @kbd{C-c C-c} and Org returns you to the same
place where you started the capture process.
To define special keys to capture to a particular template without going
several keys, keys using the same prefix key must be sequential
in the list and preceded by a 2-element entry explaining the
prefix key, for example
-@example
+@smalllisp
("b" "Templates for marking stuff to buy")
-@end example
+@end smalllisp
@noindent If you do not define a template for the @kbd{C} key, this key will
be used to open the customize buffer for this complex variable.
@item type
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
also be given as a variable, function, or Emacs Lisp form.
Valid values are:
+
@table @code
@item (file "path/to/file")
Text will be placed at the beginning or end of that file.
Use a regular expression to position the cursor.
@item (file+datetree "path/to/file")
-Will create a heading in a date tree for today's date.
+Will create a heading in a date tree for today's date@footnote{Datetree
+headlines for years accept tags, so if you use both @code{* 2013 :noexport:}
+and @code{* 2013} in your file, the capture will refile the note to the first
+one matched.}.
@item (file+datetree+prompt "path/to/file")
Will create a heading in a date tree, but will prompt for the date.
@item properties
The rest of the entry is a property list of additional options.
Recognized properties are:
+
@table @code
@item :prepend
Normally new captured information will be appended at
@smallexample
%[@var{file}] @r{Insert the contents of the file given by @var{file}.}
%(@var{sexp}) @r{Evaluate Elisp @var{sexp} and replace with the result.}
- @r{The sexp must return a string.}
+ @r{For convenience, %:keyword (see below) placeholders}
+ @r{within the expression will be expanded prior to this.}
+ @r{The sexp must return a string.}
%<...> @r{The result of format-time-string on the ... format specification.}
%t @r{Timestamp, date only.}
%T @r{Timestamp, with date and time.}
@vindex org-capture-templates-contexts
To control whether a capture template should be accessible from a specific
-context, you can customize @var{org-capture-templates-contexts}. Let's say
+context, you can customize @code{org-capture-templates-contexts}. Let's say
for example that you have a capture template @code{"p"} for storing Gnus
emails containing patches. Then you would configure this option like this:
-@example
+@smalllisp
(setq org-capture-templates-contexts
'(("p" (in-mode . "message-mode"))))
-@end example
+@end smalllisp
You can also tell that the command key @code{"p"} should refer to another
template. In that case, add this command key like this:
-@example
+@smalllisp
(setq org-capture-templates-contexts
'(("p" "q" (in-mode . "message-mode"))))
-@end example
+@end smalllisp
See the docstring of the variable for more information.
@noindent The following commands deal with attachments:
@table @kbd
-
@orgcmd{C-c C-a,org-attach}
The dispatcher for commands related to the attachment system. After these
keys, a list of commands is displayed and you must press an additional key
@code{org-feed-alist}. The docstring of this variable has detailed
information. Here is just an example:
-@example
+@smalllisp
+@group
(setq org-feed-alist
'(("Slashdot"
"http://rss.slashdot.org/Slashdot/slashdot"
"~/txt/org/feeds.org" "Slashdot Entries")))
-@end example
+@end group
+@end smalllisp
@noindent
will configure that new items from the feed provided by
For more information, including how to read atom feeds, see
@file{org-feed.el} and the docstring of @code{org-feed-alist}.
-@node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive
+@node Protocols, Refile and copy, RSS Feeds, Capture - Refile - Archive
@section Protocols for external access
@cindex protocols, for external access
@cindex emacsserver
@uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed
documentation and setup instructions.
-@node Refiling notes, Archiving, Protocols, Capture - Refile - Archive
-@section Refiling notes
+@node Refile and copy, Archiving, Protocols, Capture - Refile - Archive
+@section Refile and copy
@cindex refiling notes
+@cindex copying notes
-When reviewing the captured data, you may want to refile some of the entries
-into a different list, for example into a project. Cutting, finding the
-right location, and then pasting the note is cumbersome. To simplify this
-process, you can use the following special command:
+When reviewing the captured data, you may want to refile or to copy some of
+the entries into a different list, for example into a project. Cutting,
+finding the right location, and then pasting the note is cumbersome. To
+simplify this process, you can use the following special command:
@table @kbd
+@orgcmd{C-c M-w,org-copy}
+@findex org-copy
+Copying works like refiling, except that the original note is not deleted.
@orgcmd{C-c C-w,org-refile}
+@findex org-refile
@vindex org-reverse-note-order
@vindex org-refile-targets
@vindex org-refile-use-outline-path
@vindex org-refile-allow-creating-parent-nodes
@vindex org-log-refile
@vindex org-refile-use-cache
+@vindex org-refile-keep
Refile the entry or region at point. This command offers possible locations
for refiling the entry and lets you select one with completion. The item (or
all items in the region) is filed below the target heading as a subitem.
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-3 C-c C-w
+Refile and keep the entry in place. Also see @code{org-refile-keep} to make
+this the default behavior, and beware that this may result in duplicated
+@code{ID} properties.
@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.
@end table
-@node Archiving, , Refiling notes, Capture - Refile - Archive
+@node Archiving, , Refile and copy, Capture - Refile - Archive
@section Archiving
@cindex archiving
@itemx C-,
Cycle through agenda file list, visiting one file after the other.
@kindex M-x org-iswitchb
-@item M-x org-iswitchb
+@item M-x org-iswitchb RET
Command to use an @code{iswitchb}-like interface to switch to and between Org
buffers.
@end table
@noindent
When working with @file{speedbar.el}, you can use the following commands in
the Speedbar frame:
+
@table @kbd
@orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
Permanently restrict the agenda to the item---either an Org file or a subtree
is accessed and list keyboard access to commands accordingly. After
pressing @kbd{C-c a}, an additional letter is required to execute a
command. The dispatcher offers the following default commands:
+
@table @kbd
@item a
Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
@vindex org-agenda-span
@vindex org-agenda-ndays
+@vindex org-agenda-start-day
+@vindex org-agenda-start-on-weekday
The default number of days displayed in the agenda is set by the variable
@code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This
variable can be set to any number of days you want to see by default in the
-agenda, or to a span name, such a @code{day}, @code{week}, @code{month} or
-@code{year}.
+agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or
+@code{year}. For weekly agendas, the default is to start on the previous
+monday (see @code{org-agenda-start-on-weekday}). You can also set the start
+date using a date shift: @code{(setq org-agenda-start-day "+10d")} will
+start the agenda ten days from today in the future.
Remote editing from the agenda buffer means, for example, that you can
change the dates of deadlines and appointments from the agenda buffer.
@subsubheading Match syntax
@cindex Boolean logic, for tag/property searches
-A search string can use Boolean operators @samp{&} for AND and @samp{|} for
-OR@. @samp{&} binds more strongly than @samp{|}. Parentheses are currently
-not implemented. Each element in the search is either a tag, a regular
-expression matching tags, or an expression like @code{PROPERTY OPERATOR
-VALUE} with a comparison operator, accessing a property value. Each element
-may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic
-sugar for positive selection. The AND operator @samp{&} is optional when
-@samp{+} or @samp{-} is present. Here are some examples, using only tags.
+A search string can use Boolean operators @samp{&} for @code{AND} and
+@samp{|} for @code{OR}@. @samp{&} binds more strongly than @samp{|}.
+Parentheses are not implemented. Each element in the search is either a
+tag, a regular expression matching tags, or an expression like
+@code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a
+property value. Each element may be preceded by @samp{-}, to select
+against it, and @samp{+} is syntactic sugar for positive selection. The
+@code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is
+present. Here are some examples, using only tags.
@table @samp
+@item work
+Select headlines tagged @samp{:work:}.
+@item work&boss
+Select headlines tagged @samp{:work:} and @samp{:boss:}.
@item +work-boss
Select headlines tagged @samp{:work:}, but discard those also tagged
@samp{:boss:}.
@samp{work+@{^boss.*@}} matches headlines that contain the tag
@samp{:work:} and any tag @i{starting} with @samp{boss}.
+@cindex group tags, as regular expressions
+Group tags (@pxref{Tag groups}) are expanded as regular expressions. E.g.,
+if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then
+searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}}
+and searching for @samp{-work} will search for all headlines but those with
+one of the tag in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
+
@cindex TODO keyword matching, with tags search
@cindex level, require for tags/property match
@cindex category, require for tags/property match
time as matching tags. The properties may be real properties, or special
properties that represent other metadata (@pxref{Special properties}). For
example, the ``property'' @code{TODO} represents the TODO keyword of the
-entry. Or, the ``property'' @code{LEVEL} represents the level of an entry.
-So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines
-that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword
-DONE@. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
-count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
-The ITEM special property cannot currently be used in tags/property
+entry and the ``propety'' @code{PRIORITY} represents the PRIORITY keyword of
+the entry. The ITEM special property cannot currently be used in tags/property
searches@footnote{But @pxref{x-agenda-skip-entry-regexp,
,skipping entries based on regexp}.}.
+Except the @pxref{Special properties}, one other ``property'' can also be
+used. @code{LEVEL} represents the level of an entry. So a search
+@samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines that have
+the tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE@.
+In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not count
+the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
+
Here are more examples:
+
@table @samp
@item work+TODO="WAITING"
Select @samp{:work:}-tagged TODO lines with the specific TODO
@menu
* Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time
-* Sorting of agenda items:: The order of things
+* Sorting agenda items:: The order of things
+* Filtering/limiting agenda items:: Dynamically narrow the agenda
@end menu
@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
You can set up icons for category by customizing the
@code{org-agenda-category-icon-alist} variable.
-@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
+@node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting
@subsection Time-of-day specifications
@cindex time-of-day specification
@code{org-agenda-use-time-grid}, and can be configured with
@code{org-agenda-time-grid}.
-@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting
-@subsection Sorting of agenda items
+@node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting
+@subsection Sorting agenda items
@cindex sorting, of agenda items
@cindex priorities, of agenda items
Before being inserted into a view, the items are sorted. How this is
@code{org-agenda-sorting-strategy}, and may also include criteria based on
the estimated effort of an entry (@pxref{Effort estimates}).
-@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
-@section Commands in the agenda buffer
-@cindex commands, in agenda buffer
+@node Filtering/limiting agenda items, , Sorting agenda items, Presentation and sorting
+@subsection Filtering/limiting agenda items
-Entries in the agenda buffer are linked back to the Org file or diary
-file where they originate. You are not allowed to edit the agenda
-buffer itself, but commands are provided to show and jump to the
-original entry location, and to edit the Org files ``remotely'' from
-the agenda buffer. In this way, all information is stored only once,
-removing the risk that your agenda and note files may diverge.
+Agenda built-in or customized commands are statically defined. Agenda
+filters and limits provide two ways of dynamically narrowing down the list of
+agenda entries: @emph{fitlers} and @emph{limits}. Filters only act on the
+display of the items, while limits take effect before the list of agenda
+entries is built. Filter are more often used interactively, while limits are
+mostly useful when defined as local variables within custom agenda commands.
-Some commands can be executed with mouse clicks on agenda lines. For
-the other commands, the cursor needs to be in the desired line.
+@subsubheading Filtering in the agenda
+@cindex filtering, by tag, category, top headline and effort, in agenda
+@cindex tag filtering, in agenda
+@cindex category filtering, in agenda
+@cindex top headline filtering, in agenda
+@cindex effort filtering, in agenda
+@cindex query editing, in agenda
@table @kbd
-@tsubheading{Motion}
-@cindex motion commands in agenda
-@orgcmd{n,org-agenda-next-line}
-Next line (same as @key{down} and @kbd{C-n}).
-@orgcmd{p,org-agenda-previous-line}
-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.
-With prefix arg, make sure that the entire entry is made visible in the
-outline, not only the heading.
-@c
-@orgcmd{L,org-agenda-recenter}
-Display original location and recenter that window.
-@c
-@orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
-Go to the original location of the item in another window.
-@c
-@orgcmd{@key{RET},org-agenda-switch-to}
-Go to the original location of the item and delete other windows.
-@c
-@orgcmd{F,org-agenda-follow-mode}
-@vindex org-agenda-start-with-follow-mode
-Toggle Follow mode. In Follow mode, as you move the cursor through
-the agenda buffer, the other window always shows the corresponding
-location in the Org file. The initial setting for this mode in new
-agenda buffers can be set with the variable
-@code{org-agenda-start-with-follow-mode}.
-@c
-@orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
-Display the entire subtree of the current item in an indirect buffer. With a
-numeric prefix argument N, go up to level N and then take that tree. If N is
-negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
-previously used indirect buffer.
+@orgcmd{/,org-agenda-filter-by-tag}
+@vindex org-agenda-tag-filter-preset
+Filter the 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-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
+global options section, not in the section of an individual block.}
-@orgcmd{C-c C-o,org-agenda-open-link}
-Follow a link in the entry. This will offer a selection of any links in the
-text belonging to the referenced Org node. If there is only one link, it
-will be followed without a selection prompt.
+You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
+all. Pressing @key{TAB} at that prompt will offer use completion to select a
+tag (including any tags that do not have a selection character). The command
+then hides all entries that do not contain or inherit this tag. When called
+with prefix arg, remove the entries that @emph{do} have the tag. A second
+@kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
+If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
+will be narrowed by requiring or forbidding the selected additional tag.
+Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
+immediately use the @kbd{\} command.
-@tsubheading{Change display}
-@cindex display changing, in agenda
-@kindex A
-@item A
-Interactively select another agenda view and append it to the current view.
+@vindex org-sort-agenda-noeffort-is-high
+In order to filter for effort estimates, you should set up allowed
+efforts globally, for example
+@lisp
+(setq org-global-properties
+ '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
+@end lisp
+You can then filter for an effort by first typing an operator, one of
+@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
+estimate in your array of allowed values, where @kbd{0} means the 10th value.
+The filter will then restrict to entries with effort smaller-or-equal, equal,
+or larger-or-equal than the selected value. If the digits 0--9 are not used
+as fast access keys to tags, you can also simply press the index digit
+directly without an operator. In this case, @kbd{<} will be assumed. For
+application of the operator, entries without a defined effort will be treated
+according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter
+for tasks without effort definition, press @kbd{?} as the operator.
+
+Org also supports automatic, context-aware tag filtering. If the variable
+@code{org-agenda-auto-exclude-function} is set to a user-defined function,
+that function can decide which tags should be excluded from the agenda
+automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
+as a sub-option key and runs the auto exclusion logic. For example, let's
+say you use a @code{Net} tag to identify tasks which need network access, an
+@code{Errand} tag for errands in town, and a @code{Call} tag for making phone
+calls. You could auto-exclude these tags based on the availability of the
+Internet, and outside of business hours, with something like this:
+
+@smalllisp
+@group
+(defun org-my-auto-exclude-function (tag)
+ (and (cond
+ ((string= tag "Net")
+ (/= 0 (call-process "/sbin/ping" nil nil nil
+ "-c1" "-q" "-t1" "mail.gnu.org")))
+ ((or (string= tag "Errand") (string= tag "Call"))
+ (let ((hour (nth 2 (decode-time))))
+ (or (< hour 8) (> hour 21)))))
+ (concat "-" tag)))
+
+(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
+@end group
+@end smalllisp
+
+@orgcmd{\\,org-agenda-filter-by-tag-refine}
+Narrow the current agenda filter by an additional condition. When called with
+prefix arg, remove the entries that @emph{do} have the tag, or that do match
+the effort criterion. You can achieve the same effect by pressing @kbd{+} or
+@kbd{-} as the first key after the @kbd{/} command.
+
+@c
+@kindex [
+@kindex ]
+@kindex @{
+@kindex @}
+@item [ ] @{ @}
+@table @i
+@item @r{in} search view
+add new search words (@kbd{[} and @kbd{]}) or new regular expressions
+(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
+add a positive search term prefixed by @samp{+}, indicating that this search
+term @i{must} occur/match in the entry. The closing bracket/brace will add a
+negative search term which @i{must not} occur/match in the entry for it to be
+selected.
+@end table
+
+@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-top-headline}
+Filter the current agenda view and only display the siblings and the parent
+headline of the one at point.
+
+@orgcmd{=,org-agenda-filter-by-regexp}
+@vindex org-agenda-regexp-filter-preset
+
+Filter the agenda view by a regular expression: only show agenda entries
+matching the regular expression the user entered. When called with a prefix
+argument, it will filter @emph{out} entries matching the regexp. With two
+universal prefix arguments, it will remove all the regexp filters, which can
+be accumulated. You can add a filter preset through the option
+@code{org-agenda-category-filter-preset} (see below.)
+
+@orgcmd{|,org-agenda-filter-remove-all}
+Remove all filters in the current agenda view.
+@end table
+
+@subsubheading Setting limits for the agenda
+@cindex limits, in agenda
+@vindex org-agenda-max-entries
+@vindex org-agenda-max-effort
+@vindex org-agenda-max-todos
+@vindex org-agenda-max-tags
+
+Here is a list of options that you can set, either globally, or locally in
+your custom agenda views@pxref{Custom agenda views}.
+
+@table @var
+@item org-agenda-max-entries
+Limit the number of entries.
+@item org-agenda-max-effort
+Limit the duration of accumulated efforts (as minutes).
+@item org-agenda-max-todos
+Limit the number of entries with TODO keywords.
+@item org-agenda-max-tags
+Limit the number of tagged entries.
+@end table
+
+When set to a positive integer, each option will exclude entries from other
+catogories: for example, @code{(setq org-agenda-max-effort 100)} will limit
+the agenda to 100 minutes of effort and exclude any entry that as no effort
+property. If you want to include entries with no effort property, use a
+negative value for @code{org-agenda-max-effort}.
+
+One useful setup is to use @code{org-agenda-max-entries} locally in a custom
+command. For example, this custom command will display the next five entries
+with a @code{NEXT} TODO keyword.
+
+@smalllisp
+(setq org-agenda-custom-commands
+ '(("n" todo "NEXT"
+ ((org-agenda-max-entries 5)))))
+@end smalllisp
+
+Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
+will again the next five entries again, including the first entry that was
+excluded so far.
+
+You can also dynamically set temporary limits@footnote{Those temporary limits
+are lost when rebuilding the agenda.}:
+
+@table @kbd
+@orgcmd{~,org-agenda-limit-interactively}
+This prompts for the type of limit to apply and its value.
+@end table
+
+@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
+@section Commands in the agenda buffer
+@cindex commands, in agenda buffer
+
+Entries in the agenda buffer are linked back to the Org file or diary
+file where they originate. You are not allowed to edit the agenda
+buffer itself, but commands are provided to show and jump to the
+original entry location, and to edit the Org files ``remotely'' from
+the agenda buffer. In this way, all information is stored only once,
+removing the risk that your agenda and note files may diverge.
+
+Some commands can be executed with mouse clicks on agenda lines. For
+the other commands, the cursor needs to be in the desired line.
+
+@table @kbd
+@tsubheading{Motion}
+@cindex motion commands in agenda
+@orgcmd{n,org-agenda-next-line}
+Next line (same as @key{down} and @kbd{C-n}).
+@orgcmd{p,org-agenda-previous-line}
+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.
+With prefix arg, make sure that the entire entry is made visible in the
+outline, not only the heading.
+@c
+@orgcmd{L,org-agenda-recenter}
+Display original location and recenter that window.
+@c
+@orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
+Go to the original location of the item in another window.
+@c
+@orgcmd{@key{RET},org-agenda-switch-to}
+Go to the original location of the item and delete other windows.
+@c
+@orgcmd{F,org-agenda-follow-mode}
+@vindex org-agenda-start-with-follow-mode
+Toggle Follow mode. In Follow mode, as you move the cursor through
+the agenda buffer, the other window always shows the corresponding
+location in the Org file. The initial setting for this mode in new
+agenda buffers can be set with the variable
+@code{org-agenda-start-with-follow-mode}.
+@c
+@orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
+Display the entire subtree of the current item in an indirect buffer. With a
+numeric prefix argument N, go up to level N and then take that tree. If N is
+negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
+previously used indirect buffer.
+
+@orgcmd{C-c C-o,org-agenda-open-link}
+Follow a link in the entry. This will offer a selection of any links in the
+text belonging to the referenced Org node. If there is only one link, it
+will be followed without a selection prompt.
+
+@tsubheading{Change display}
+@cindex display changing, in agenda
+@kindex A
+@item A
+Interactively select another agenda view and append it to the current view.
@c
@kindex o
@item o
@c
@orgcmdkskc{v d,d,org-agenda-day-view}
@xorgcmdkskc{v w,w,org-agenda-week-view}
+@xorgcmd{v t,org-agenda-fortnight-view}
@xorgcmd{v m,org-agenda-month-view}
@xorgcmd{v y,org-agenda-year-view}
@xorgcmd{v SPC,org-agenda-reset-view}
types that should be included in log mode using the variable
@code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show
all possible logbook entries, including state changes. When called with two
-prefix args @kbd{C-u C-u}, show only logging information, nothing else.
+prefix arguments @kbd{C-u C-u}, show only logging information, nothing else.
@kbd{v L} is equivalent to @kbd{C-u v l}.
@c
@orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
@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
+always show a table with the clocked times for the time span and file scope
covered by the current agenda view. The initial setting for this mode in new
agenda buffers can be set with the variable
@code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
file or subtree (@pxref{Agenda files}).
@tsubheading{Secondary filtering and query editing}
-@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.)
+For a detailed description of these commands, see @pxref{Filtering/limiting
+agenda items}.
@orgcmd{/,org-agenda-filter-by-tag}
@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-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
-global options section, not in the section of an individual block.}
+Filter the agenda view with respect to a tag and/or effort estimates.
-You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
-all. Pressing @key{TAB} at that prompt will offer use completion to select a
-tag (including any tags that do not have a selection character). The command
-then hides all entries that do not contain or inherit this tag. When called
-with prefix arg, remove the entries that @emph{do} have the tag. A second
-@kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
-If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
-will be narrowed by requiring or forbidding the selected additional tag.
-Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
-immediately use the @kbd{\} command.
+@orgcmd{\\,org-agenda-filter-by-tag-refine}
+Narrow the current agenda filter by an additional condition.
-@vindex org-sort-agenda-noeffort-is-high
-In order to filter for effort estimates, you should set up allowed
-efforts globally, for example
-@lisp
-(setq org-global-properties
- '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
-@end lisp
-You can then filter for an effort by first typing an operator, one of
-@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
-estimate in your array of allowed values, where @kbd{0} means the 10th value.
-The filter will then restrict to entries with effort smaller-or-equal, equal,
-or larger-or-equal than the selected value. If the digits 0--9 are not used
-as fast access keys to tags, you can also simply press the index digit
-directly without an operator. In this case, @kbd{<} will be assumed. For
-application of the operator, entries without a defined effort will be treated
-according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter
-for tasks without effort definition, press @kbd{?} as the operator.
+@orgcmd{<,org-agenda-filter-by-category}
+@vindex org-agenda-category-filter-preset
-Org also supports automatic, context-aware tag filtering. If the variable
-@code{org-agenda-auto-exclude-function} is set to a user-defined function,
-that function can decide which tags should be excluded from the agenda
-automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
-as a sub-option key and runs the auto exclusion logic. For example, let's
-say you use a @code{Net} tag to identify tasks which need network access, an
-@code{Errand} tag for errands in town, and a @code{Call} tag for making phone
-calls. You could auto-exclude these tags based on the availability of the
-Internet, and outside of business hours, with something like this:
+Filter the current agenda view with respect to the category of the item at
+point. Pressing @code{<} another time will remove this filter.
-@lisp
-@group
-(defun org-my-auto-exclude-function (tag)
- (and (cond
- ((string= tag "Net")
- (/= 0 (call-process "/sbin/ping" nil nil nil
- "-c1" "-q" "-t1" "mail.gnu.org")))
- ((or (string= tag "Errand") (string= tag "Call"))
- (let ((hour (nth 2 (decode-time))))
- (or (< hour 8) (> hour 21)))))
- (concat "-" tag)))
+@orgcmd{^,org-agenda-filter-by-top-headline}
+Filter the current agenda view and only display the siblings and the parent
+headline of the one at point.
-(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
-@end group
-@end lisp
+@orgcmd{=,org-agenda-filter-by-regexp}
+@vindex org-agenda-regexp-filter-preset
-@orgcmd{\\,org-agenda-filter-by-tag-refine}
-Narrow the current agenda filter by an additional condition. When called with
-prefix arg, remove the entries that @emph{do} have the tag, or that do match
-the effort criterion. You can achieve the same effect by pressing @kbd{+} or
-@kbd{-} as the first key after the @kbd{/} command.
+Filter the agenda view by a regular expression: only show agenda entries
+matching the regular expression the user entered. When called with a prefix
+argument, it will filter @emph{out} entries matching the regexp. With two
+universal prefix arguments, it will remove all the regexp filters, which can
+be accumulated. You can add a filter preset through the option
+@code{org-agenda-category-filter-preset} (see below.)
-@c
-@kindex [
-@kindex ]
-@kindex @{
-@kindex @}
-@item [ ] @{ @}
-@table @i
-@item @r{in} search view
-add new search words (@kbd{[} and @kbd{]}) or new regular expressions
-(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
-add a positive search term prefixed by @samp{+}, indicating that this search
-term @i{must} occur/match in the entry. The closing bracket/brace will add a
-negative search term which @i{must not} occur/match in the entry for it to be
-selected.
-@end table
+@orgcmd{|,org-agenda-filter-remove-all}
+Remove all filters in the current agenda view.
@tsubheading{Remote editing}
@cindex remote editing, from agenda
@c
@orgcmd{k,org-agenda-capture}
Like @code{org-capture}, but use the date at point as the default date for
-the capture template. See @var{org-capture-use-agenda-date} to make this
+the capture template. See @code{org-capture-use-agenda-date} to make this
the default behavior of @code{org-capture}.
@cindex capturing, from agenda
@vindex org-capture-use-agenda-date
+@tsubheading{Dragging agenda lines forward/backward}
+@cindex dragging, agenda lines
+
+@orgcmd{M-<up>,org-agenda-drag-line-backward}
+Drag the line at point backward one line@footnote{Moving agenda lines does
+not persist after an agenda refresh and does not modify the contributing
+@file{.org} files}. With a numeric prefix argument, drag backward by that
+many lines.
+
+@orgcmd{M-<down>,org-agenda-drag-line-forward}
+Drag the line at point forward one line. With a numeric prefix argument,
+drag forward by that many lines.
+
@tsubheading{Bulk remote editing selected entries}
@cindex remote editing, bulk, from agenda
-@vindex org-agenda-bulk-persistent-marks
@vindex org-agenda-bulk-custom-functions
@orgcmd{m,org-agenda-bulk-mark}
-Mark the entry at point for bulk action. With prefix arg, mark that many
-successive entries.
+Mark the entry at point for bulk action. With numeric prefix argument, mark
+that many successive entries.
@c
-@orgcmd{%,org-agenda-bulk-mark-regexp}
-Mark entries matching a regular expression for bulk action.
+@orgcmd{*,org-agenda-bulk-mark-all}
+Mark all visible agenda entries for bulk action.
@c
@orgcmd{u,org-agenda-bulk-unmark}
-Unmark entry for bulk action.
+Unmark entry at point for bulk action.
@c
@orgcmd{U,org-agenda-bulk-remove-all-marks}
Unmark all marked entries for bulk action.
@c
+@orgcmd{M-m,org-agenda-bulk-toggle}
+Toggle mark of the entry at point for bulk action.
+@c
+@orgcmd{M-*,org-agenda-bulk-toggle-all}
+Toggle marks of all visible entries for bulk action.
+@c
+@orgcmd{%,org-agenda-bulk-mark-regexp}
+Mark entries matching a regular expression for bulk action.
+@c
@orgcmd{B,org-agenda-bulk-action}
Bulk action: act on all marked entries in the agenda. This will prompt for
another key to select the action to be applied. The prefix arg to @kbd{B}
you want them to persist, set @code{org-agenda-bulk-persistent-marks} to
@code{t} or hit @kbd{p} at the prompt.
-@example
-* @r{Toggle persistent marks.}
-$ @r{Archive all selected entries.}
-A @r{Archive entries by moving them to their respective archive siblings.}
-t @r{Change TODO state. This prompts for a single TODO keyword and}
- @r{changes the state of all selected entries, bypassing blocking and}
- @r{suppressing logging notes (but not timestamps).}
-+ @r{Add a tag to all selected entries.}
-- @r{Remove a tag from all selected entries.}
-s @r{Schedule all items to a new date. To shift existing schedule dates}
- @r{by a fixed number of days, use something starting with double plus}
- @r{at the prompt, for example @samp{++8d} or @samp{++2w}.}
-d @r{Set deadline to a specific date.}
-r @r{Prompt for a single refile target and move all entries. The entries}
- @r{will no longer be in the agenda; refresh (@kbd{g}) to bring them back.}
-S @r{Reschedule randomly into the coming N days. N will be prompted for.}
- @r{With prefix arg (@kbd{C-u B S}), scatter only across weekdays.}
-f @r{Apply a function@footnote{You can also create persistent custom functions through@code{org-agenda-bulk-custom-functions}.} to marked entries.}
- @r{For example, the function below sets the CATEGORY property of the}
- @r{entries to web.}
- @r{(defun set-category ()}
- @r{ (interactive "P")}
- @r{ (let* ((marker (or (org-get-at-bol 'org-hd-marker)}
- @r{ (org-agenda-error)))}
- @r{ (buffer (marker-buffer marker)))}
- @r{ (with-current-buffer buffer}
- @r{ (save-excursion}
- @r{ (save-restriction}
- @r{ (widen)}
- @r{ (goto-char marker)}
- @r{ (org-back-to-heading t)}
- @r{ (org-set-property "CATEGORY" "web"))))))}
-@end example
+@table @kbd
+@item *
+Toggle persistent marks.
+@item $
+Archive all selected entries.
+@item A
+Archive entries by moving them to their respective archive siblings.
+@item t
+Change TODO state. This prompts for a single TODO keyword and changes the
+state of all selected entries, bypassing blocking and suppressing logging
+notes (but not timestamps).
+@item +
+Add a tag to all selected entries.
+@item -
+Remove a tag from all selected entries.
+@item s
+Schedule all items to a new date. To shift existing schedule dates by a
+fixed number of days, use something starting with double plus at the prompt,
+for example @samp{++8d} or @samp{++2w}.
+@item d
+Set deadline to a specific date.
+@item r
+Prompt for a single refile target and move all entries. The entries will no
+longer be in the agenda; refresh (@kbd{g}) to bring them back.
+@item S
+Reschedule randomly into the coming N days. N will be prompted for. With
+prefix arg (@kbd{C-u B S}), scatter only across weekdays.
+@item f
+Apply a function@footnote{You can also create persistent custom functions
+through @code{org-agenda-bulk-custom-functions}.} to marked entries. For
+example, the function below sets the CATEGORY property of the entries to web.
+@lisp
+@group
+(defun set-category ()
+ (interactive "P")
+ (let* ((marker (or (org-get-at-bol 'org-hd-marker)
+ (org-agenda-error)))
+ (buffer (marker-buffer marker)))
+ (with-current-buffer buffer
+ (save-excursion
+ (save-restriction
+ (widen)
+ (goto-char marker)
+ (org-back-to-heading t)
+ (org-set-property "CATEGORY" "web"))))))
+@end group
+@end lisp
+@end table
@tsubheading{Calendar commands}
@cindex calendar commands, from agenda
@orgcmd{H,org-agenda-holidays}
Show holidays for three months around the cursor date.
-@item M-x org-export-icalendar-combine-agenda-files
+@item M-x org-icalendar-combine-agenda-files RET
Export a single iCalendar file containing entries from all agenda files.
This is a globally available command, and also available in the agenda menu.
@cindex agenda views, exporting
@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}),
-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
-for @file{htmlize} to be used during export.
+file name, the view will be exported as HTML (@file{.html} or @file{.htm}),
+Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text
+(any other extension). When exporting to Org, only the body of original
+headlines are exported, not subtrees or inherited tags. 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 for @file{htmlize} to be used during export.
@tsubheading{Quit and Exit}
@orgcmd{q,org-agenda-quit}
@kindex C-c a C
@vindex org-agenda-custom-commands
@cindex agenda views, main example
+@cindex agenda, as an agenda views
+@cindex agenda*, as an agenda views
@cindex tags, as an agenda view
@cindex todo, as an agenda view
@cindex tags-todo
Custom commands are configured in the variable
@code{org-agenda-custom-commands}. You can customize this variable, for
example by pressing @kbd{C-c a C}. You can also directly set it with Emacs
-Lisp in @file{.emacs}. The following example contains all valid search
-types:
+Lisp in @file{.emacs}. The following example contains all valid agenda
+views:
@lisp
@group
(setq org-agenda-custom-commands
- '(("w" todo "WAITING")
+ '(("x" agenda)
+ ("y" agenda*)
+ ("w" todo "WAITING")
("W" todo-tree "WAITING")
("u" tags "+boss-urgent")
("v" tags-todo "+boss-urgent")
therefore define:
@table @kbd
+@item C-c a x
+as a global search for agenda entries planned@footnote{@emph{Planned} means
+here that these entries have some planning information attached to them, like
+a time-stamp, a scheduled or a deadline string. See
+@code{org-agenda-entry-types} on how to set what planning information will be
+taken into account.} this week/day.
+@item C-c a y
+as a global search for agenda entries planned this week/day, but only those
+with an hour specification like @code{[h]h:mm}---think of them as appointments.
@item C-c a w
as a global search for TODO entries with @samp{WAITING} as the TODO
keyword
@vindex org-agenda-custom-commands-contexts
To control whether an agenda command should be accessible from a specific
-context, you can customize @var{org-agenda-custom-commands-contexts}. Let's
+context, you can customize @code{org-agenda-custom-commands-contexts}. Let's
say for example that you have an agenda commands @code{"o"} displaying a view
that you only need when reading emails. Then you would configure this option
like this:
-@example
+@lisp
(setq org-agenda-custom-commands-contexts
'(("o" (in-mode . "message-mode"))))
-@end example
+@end lisp
You can also tell that the command key @code{"o"} should refer to another
command key @code{"r"}. In that case, add this command key like this:
-@example
+@lisp
(setq org-agenda-custom-commands-contexts
'(("o" "r" (in-mode . "message-mode"))))
-@end example
+@end lisp
See the docstring of the variable for more information.
@chapter Markup for rich export
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.
+structure of the document as accurately as possible in the back-end. Since
+export targets like HTML, @LaTeX{} 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.
@menu
* Structural markup elements:: The basic structure as seen by the exporter
-* Images and tables:: Tables and Images will be included
+* Images and tables:: Images, tables and caption mechanism
* Literal examples:: Source code examples with special formatting
* Include files:: Include additional files into a document
* Index entries:: Making an index
-* Macro replacement:: Use macros to create complex output
+* Macro replacement:: Use macros to create templates
* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
+* Special blocks:: Containers targeted at export back-ends
@end menu
@node Structural markup elements, Images and tables, Markup, Markup
* Document title:: Where the title is taken from
* Headings and sections:: The document structure as seen by the exporter
* Table of contents:: The if and where of the table of contents
-* Initial text:: Text before the first heading?
* Lists:: Lists
* Paragraphs:: Paragraphs
* Footnote markup:: Footnotes
@end example
@noindent
-If this line does not exist, the title is derived from the first non-empty,
-non-comment line in the buffer. If no such line exists, or if you have
-turned off exporting of the text before the first headline (see below), the
-title will be the file name without extension.
+If this line does not exist, the title will be the name of the file
+associated to buffer, without extension, or the buffer name.
@cindex property, EXPORT_TITLE
-If you are exporting only a subtree by marking is as the region, the heading
-of the subtree will become the title of the document. If the subtree has a
-property @code{EXPORT_TITLE}, that will take precedence.
+If you are exporting only a subtree, its heading will become the title of the
+document. If the subtree has a property @code{EXPORT_TITLE}, that will take
+precedence.
@node Headings and sections, Table of contents, Document title, Structural markup elements
@subheading Headings and sections
#+OPTIONS: H:4
@end example
-@node Table of contents, Initial text, Headings and sections, Structural markup elements
+@node Table of contents, Lists, Headings and sections, Structural markup elements
@subheading Table of contents
@cindex table of contents, markup rules
+@cindex #+TOC
@vindex org-export-with-toc
The table of contents is normally inserted directly before the first headline
-of the file. If you would like to get it to a different location, insert the
-string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired
-location. The depth of the table of contents is by default the same as the
-number of headline levels, but you can choose a smaller number, or turn off
-the table of contents entirely, by configuring the variable
-@code{org-export-with-toc}, or on a per-file basis with a line like
+of the file. The depth of the table is by default the same as the number of
+headline levels, but you can choose a smaller number, or turn off the table
+of contents entirely, by configuring the variable @code{org-export-with-toc},
+or on a per-file basis with a line like
@example
#+OPTIONS: toc:2 (only to two levels in TOC)
-#+OPTIONS: toc:nil (no TOC at all)
+#+OPTIONS: toc:nil (no default TOC at all)
@end example
-@node Initial text, Lists, Table of contents, Structural markup elements
-@subheading Text before the first headline
-@cindex text before first headline, markup rules
-@cindex #+TEXT
+If you would like to move the table of contents to a different location, you
+should turn off the detault table using @code{org-export-with-toc} or
+@code{#+OPTIONS} and insert @code{#+TOC: headlines N} at the desired
+location(s).
-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.
-
-@vindex org-export-skip-text-before-1st-heading
-Some people like to use the space before the first headline for setup and
-internal links and therefore would like to control the exported text before
-the first headline in a different way. You can do so by setting the variable
-@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file
-basis, you can get the same effect with @samp{#+OPTIONS: skip:t}.
+@example
+#+OPTIONS: toc:nil (no default TOC)
+...
+#+TOC: headlines 2 (insert TOC here, with two headline levels)
+@end example
-@noindent
-If you still want to have some text before the first headline, use the
-@code{#+TEXT} construct:
+Multiple @code{#+TOC: headline} lines are allowed. The same @code{TOC}
+keyword can also generate a list of all tables (resp.@: all listings) with a
+caption in the buffer.
@example
-#+OPTIONS: skip:t
-#+TEXT: This text will go before the *first* headline.
-#+TEXT: [TABLE-OF-CONTENTS]
-#+TEXT: This goes between the table of contents and the *first* headline
+#+TOC: listings (build a list of listings)
+#+TOC: tables (build a list of tables)
@end example
-@node Lists, Paragraphs, Initial text, Structural markup elements
+@cindex property, ALT_TITLE
+The headline's title usually determines its corresponding entry in a table of
+contents. However, it is possible to specify an alternative title by
+setting @code{ALT_TITLE} property accordingly. It will then be used when
+building the table.
+
+@node Lists, Paragraphs, Table of contents, Structural markup elements
@subheading Lists
@cindex lists, markup rules
-Plain lists as described in @ref{Plain lists}, are translated to the backend's
-syntax for such lists. Most backends support unordered, ordered, and
+Plain lists as described in @ref{Plain lists}, are translated to the back-end's
+syntax for such lists. Most back-ends support unordered, ordered, and
description lists.
@node Paragraphs, Footnote markup, Lists, Structural markup elements
@cindex @file{footnote.el}
Footnotes defined in the way described in @ref{Footnotes}, will be exported
-by all backends. Org allows multiple references to the same note, and
+by all back-ends. Org allows multiple references to the same note, and
multiple footnotes side by side.
@node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements
@cindex verbatim text, markup rules
@cindex code text, markup rules
@cindex strike-through text, markup rules
+@vindex org-fontify-emphasized-text
+@vindex org-emphasis-regexp-components
+@vindex org-emphasis-alist
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
-syntax; it is exported verbatim.
+syntax, it is exported verbatim.
+
+To turn off fontification for marked up text, you can set
+@code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of
+available markup syntax, you can customize @code{org-emphasis-alist}. To fine
+tune what characters are allowed before and after the markup characters, you
+can tweak @code{org-emphasis-regexp-components}. Beware that changing one of
+the above variables will no take effect until you reload Org, for which you
+may need to restart Emacs.
@node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements
@subheading Horizontal rules
@cindex horizontal rules, markup rules
A line consisting of only dashes, and at least 5 of them, will be exported as
-a horizontal line (@samp{<hr/>} in HTML and @code{\hrule} in @LaTeX{}).
+a horizontal line.
@node Comment lines, , Horizontal rules, Structural markup elements
@subheading Comment lines
@cindex tables, markup rules
@cindex #+CAPTION
-@cindex #+LABEL
+@cindex #+NAME
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
-the object with @code{\ref@{tab:basic-data@}}:
+the object with @code{[[tab:basic-data]]} (@pxref{Internal links}):
@example
#+CAPTION: This is the caption for the next table (or link)
-#+LABEL: tab:basic-data
+#+NAME: tab:basic-data
| ... | ...|
|-----|----|
@end example
Optionally, the caption can take the form:
@example
-#+CAPTION: [Caption for list of figures]@{Caption for table (or link).@}
+#+CAPTION[Caption for list of tables]: Caption for table.
@end example
@cindex inlined images, markup rules
-Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include
-images into the exported document. Org does this, if a link to an image
-files does not have a description part, for example @code{[[./img/a.jpg]]}.
-If you wish to define a caption for the image and maybe a label for internal
-cross references, make sure that the link is on a line by itself and precede
-it with @code{#+CAPTION} and @code{#+LABEL} as follows:
+Some back-ends allow you to directly include images into the exported
+document. Org does this, if a link to an image files does not have
+a description part, for example @code{[[./img/a.jpg]]}. If you wish to
+define a caption for the image and maybe a label for internal cross
+references, make sure that the link is on a line by itself and precede it
+with @code{#+CAPTION} and @code{#+NAME} as follows:
@example
#+CAPTION: This is the caption for the next figure link (or table)
-#+LABEL: fig:SED-HR4049
+#+NAME: fig:SED-HR4049
[[./img/a.jpg]]
@end example
-You may also define additional attributes for the figure. As this is
-backend-specific, see the sections about the individual backends for more
-information.
+@noindent
+Such images can be displayed within the buffer. @xref{Handling links,the
+discussion of image links}.
-@xref{Handling links,the discussion of image links}.
+Even though images and tables are prominent examples of captioned structures,
+the same caption mechanism can apply to many others (e.g., @LaTeX{}
+equations, source code blocks). Depending on the export back-end, those may
+or may not be handled.
@node Literal examples, Include files, Images and tables, Markup
@section Literal examples
If the example is source code from a programming language, or any other text
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,
+the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package,
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. Refer to
-@code{org-export-latex-listings} documentation for details.}. This is done
+@code{org-latex-listings} documentation for details.}. This is done
with the @samp{src} block, where you also 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.
@example
#+INCLUDE: "~/.emacs" src emacs-lisp
@end example
+
@noindent
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
-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
-accepted by the selected markup. For example, to include a file as an item,
-use
+processed normally.
+
+Contents of the included file will belong to the same structure (headline,
+item) containing the @code{INCLUDE} keyword. In particular, headlines within
+the file will become children of the current section. That behaviour can be
+changed by providing an additional keyword parameter, @code{:minlevel}. In
+that case, all headlines in the included file will be shifted so the one with
+the lowest level reaches that specified level. For example, to make a file
+become a sibling of the current top-level headline, use
@example
-#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " "
+#+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
@end example
You can also include a portion of a file by specifying a lines range using
#+MACRO: name replacement text $1, $2 are arguments
@end example
-@noindent which can be referenced anywhere in the document (even in
-code examples) with @code{@{@{@{name(arg1,arg2)@}@}@}}. In addition to
-defined macros, @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc.,
-will reference information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and
-similar lines. Also, @code{@{@{@{date(@var{FORMAT})@}@}@}} and
+@noindent which can be referenced in
+paragraphs, verse blocks, table cells and some keywords with
+@code{@{@{@{name(arg1,arg2)@}@}@}}@footnote{Since commas separate arguments,
+commas within arguments have to be escaped with a backslash character.
+Conversely, backslash characters before a comma, and only them, need to be
+escaped with another backslash character.}. In addition to defined macros,
+@code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc., will reference
+information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and similar lines.
+Also, @code{@{@{@{time(@var{FORMAT})@}@}@}} and
@code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time
and to the modification time of the file being exported, respectively.
@var{FORMAT} should be a format string understood by
@code{format-time-string}.
-Macro expansion takes place during export, and some people use it to
-construct complex HTML code.
+Macro expansion takes place during export.
-@node Embedded @LaTeX{}, , Macro replacement, Markup
+@node Embedded @LaTeX{}, Special blocks, Macro replacement, Markup
@section Embedded @LaTeX{}
@cindex @TeX{} interpretation
@cindex @LaTeX{} interpretation
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.
+readily processed to produce pretty output for a number of export back-ends.
@menu
* Special symbols:: Greek letters and other symbols
@cindex HTML entities
@cindex @LaTeX{} entities
-You can use @LaTeX{} macros to insert special symbols like @samp{\alpha} to
-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,
+You can use @LaTeX{}-like syntax to insert special symbols like @samp{\alpha}
+to indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion
+for these symbols 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 symbols to be present without surrounding math
delimiters, for example:
@example
@vindex org-entities
During export, these symbols will be transformed into the native format of
-the exporter backend. Strings like @code{\alpha} will be exported as
+the exporter back-end. Strings like @code{\alpha} will be exported as
@code{α} in the HTML output, and as @code{$\alpha$} in the @LaTeX{}
output. Similarly, @code{\nbsp} will become @code{ } in HTML and
@code{~} in @LaTeX{}. If you need such a symbol inside a word, terminate it
@samp{...} are all converted into special commands creating hyphens of
different lengths or a compact set of dots.
-If you would like to see entities displayed as UTF8 characters, use the
+If you would like to see entities displayed as UTF-8 characters, use the
following command@footnote{You can turn this on by default by setting the
variable @code{org-pretty-entities}, or on a per-file base with the
@code{#+STARTUP} option @code{entitiespretty}.}:
@table @kbd
+@cindex @code{entitiespretty}, STARTUP keyword
@kindex C-c C-x \
@item C-c C-x \
Toggle display of entities as UTF-8 characters. This does not change the
@cindex subscript
@cindex superscript
-Just like in @LaTeX{}, @samp{^} and @samp{_} are used to indicate super-
-and subscripts. Again, these can be used without embedding them in
-math-mode delimiters. To increase the readability of ASCII text, it is
-not necessary (but OK) to surround multi-character sub- and superscripts
-with curly braces. For example
+Just like in @LaTeX{}, @samp{^} and @samp{_} are used to indicate super- and
+subscripts. Again, these can be used without embedding them in math-mode
+delimiters. To increase the readability of ASCII text, it is not necessary
+(but OK) to surround multi-character sub- and superscripts with curly braces.
+For example
@example
The mass of the sun is M_sun = 1.989 x 10^30 kg. The radius of
the sun is R_@{sun@} = 6.96 x 10^8 m.
@end example
-@vindex org-export-with-sub-superscripts
-To avoid interpretation as raised or lowered text, you can quote @samp{^} and
-@samp{_} with a backslash: @samp{\^} and @samp{\_}. If you write a text
-where the underscore is often used in a different context, Org's convention
-to always interpret these as subscripts can get in your way. Configure the
-variable @code{org-export-with-sub-superscripts} to globally change this
-convention, or use, on a per-file basis:
-
-@example
-#+OPTIONS: ^:@{@}
-@end example
-
-@noindent With this setting, @samp{a_b} will not be interpreted as a
-subscript, but @samp{a_@{b@}} will.
+@vindex org-use-sub-superscripts
+If you write a text where the underscore is often used in a different
+context, Org's convention to always interpret these as subscripts can get in
+your way. Configure the variable @code{org-use-sub-superscripts} to change
+this convention. For example, when setting this variable to @code{@{@}},
+@samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will.
@table @kbd
@kindex C-c C-x \
@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
-to process these for several export backends. When exporting to @LaTeX{},
+to process these for several export back-ends. 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
HTML export}) to process and display the math@footnote{If you plan to use
this regularly or on pages with significant page views, you should install
-@file{MathJax} on your own
-server in order to limit the load of our server.}. Finally, it can also
-process the mathematical expressions into images@footnote{For this to work
-you need to be on a system with a working @LaTeX{} installation. You also
-need the @file{dvipng} program or the @file{convert}, respectively available
-at @url{http://sourceforge.net/projects/dvipng/} and from the
-@file{imagemagick} suite. The @LaTeX{} header that will be used when
-processing a fragment can be configured with the variable
-@code{org-format-latex-header}.} that can be displayed in a browser or in
-DocBook documents.
+@file{MathJax} on your own server in order to limit the load of our server.}.
+Finally, it can also process the mathematical expressions into
+images@footnote{For this to work you need to be on a system with a working
+@LaTeX{} installation. You also need the @file{dvipng} program or the
+@file{convert}, respectively available at
+@url{http://sourceforge.net/projects/dvipng/} and from the @file{imagemagick}
+suite. The @LaTeX{} header that will be used when processing a fragment can
+be configured with the variable @code{org-format-latex-header}.} that can be
+displayed in a browser.
@LaTeX{} fragments don't need any special marking at all. The following
snippets will be identified as @LaTeX{} source code:
@itemize @bullet
@item
Environments of any kind@footnote{When @file{MathJax} is used, only the
-environment recognized by @file{MathJax} will be processed. When
-@file{dvipng} is used to create images, any @LaTeX{} environments will be
-handled.}. The only requirement is that the @code{\begin} statement appears
-on a new line, preceded by only whitespace.
+environments recognized by @file{MathJax} will be processed. When
+@file{dvipng} program or @file{imagemagick} suite is used to create images,
+any @LaTeX{} environment will be handled.}. The only requirement is that the
+@code{\begin} and @code{\end} statements appear on a new line, at the
+beginning of the line or after whitespaces only.
@item
Text within the usual @LaTeX{} math delimiters. To avoid conflicts with
currency specifications, single @samp{$} characters are only recognized as
@noindent For example:
@example
-\begin@{equation@} % arbitrary environments,
-x=\sqrt@{b@} % even tables, figures
-\end@{equation@} % etc
+\begin@{equation@}
+x=\sqrt@{b@}
+\end@{equation@}
If $a^2=b$ and \( b=2 \), then the solution must be
either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
@end example
-@noindent
-@vindex org-format-latex-options
-If you need any of the delimiter ASCII sequences for other purposes, you
-can configure the option @code{org-format-latex-options} to deselect the
-ones you do not wish to have interpreted by the @LaTeX{} converter.
+@c FIXME
+@c @noindent
+@c @vindex org-format-latex-options
+@c If you need any of the delimiter ASCII sequences for other purposes, you
+@c can configure the option @code{org-format-latex-options} to deselect the
+@c ones you do not wish to have interpreted by the @LaTeX{} converter.
-@vindex org-export-with-LaTeX-fragments
+@vindex org-export-with-latex
@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
-of these lines:
+@code{org-export-with-latex}. The default setting is @code{t} which means
+@file{MathJax} for HTML, and no processing for ASCII and @LaTeX{} back-ends.
+You can also set this variable on a per-file basis using one of these
+lines:
@example
-#+OPTIONS: LaTeX:t @r{Do the right thing automatically (MathJax)}
-#+OPTIONS: LaTeX:dvipng @r{Force using dvipng images}
-#+OPTIONS: LaTeX:nil @r{Do not process @LaTeX{} fragments at all}
-#+OPTIONS: LaTeX:verbatim @r{Verbatim export, for jsMath or so}
+#+OPTIONS: tex:t @r{Do the right thing automatically (MathJax)}
+#+OPTIONS: tex:nil @r{Do not process @LaTeX{} fragments at all}
+#+OPTIONS: tex: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
-If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to
-produce preview images of the typeset expressions:
+@vindex org-latex-create-formula-image-program
+If you have @file{dvipng} or @file{imagemagick} installed@footnote{Choose the
+converter by setting the variable
+@code{org-latex-create-formula-image-program} accordingly.}, @LaTeX{}
+fragments can be processed to produce preview images of the typeset
+expressions:
@table @kbd
@kindex C-c C-x C-l
export, @code{:html-scale}) property can be used to adjust the size of the
preview images.
+@vindex org-startup-with-latex-preview
+You can turn on the previewing of all @LaTeX{} fragments in a file with
+
+@example
+#+STARTUP: latexpreview
+@end example
+
+To disable it, simply use
+
+@example
+#+STARTUP: nolatexpreview
+@end example
+
@node CDLaTeX mode, , Previewing @LaTeX{} fragments, Embedded @LaTeX{}
@subsection Using CD@LaTeX{} to enter math
@cindex CD@LaTeX{}
AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
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
+on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all
Org files with
@lisp
environment abbreviations at the beginning of a line. For example, if
you write @samp{equ} at the beginning of a line and press @key{TAB},
this abbreviation will be expanded to an @code{equation} environment.
-To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
+To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}.
@item
@kindex _
@kindex ^
is normal.
@end itemize
+@node Special blocks, , Embedded @LaTeX{}, Markup
+@section Special blocks
+@cindex Special blocks
+
+Org syntax includes pre-defined blocks (@pxref{Paragraphs} and @ref{Literal
+examples}). It is also possible to create blocks containing raw code
+targeted at a specific back-ends (e.g., @samp{#+BEGIN_LATEX}).
+
+Any other block is a @emph{special block}. Each export back-end decides if
+they should be exported, and how. When the block is ignored, its contents
+are still exported, as if the block were not there. For example, when
+exporting a @samp{#+BEGIN_TEST} block, HTML back-end wraps its contents
+within @samp{<div name="test">} tag. Refer to back-end specific
+documentation for more information.
+
@node Exporting, Publishing, Markup, Top
@chapter Exporting
@cindex exporting
-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
-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. 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 Org mode export facilities can be used to export Org documents or parts
+of Org documents to a variety of other formats. In addition, these
+facilities can be used with @code{orgtbl-mode} and/or @code{orgstruct-mode}
+in foreign buffers so you can author tables and lists in Org syntax and
+convert them in place to the target language.
+
+ASCII export produces a readable and simple version of an Org file for
+printing and sharing notes. HTML export allows you to easily publish notes
+on the web, or to build full-fledged websites. @LaTeX{} export lets you use
+Org mode and its structured editing functions to create arbitrarily complex
+@LaTeX{} files for any kind of document. OpenDocument Text (ODT) export
+allows seamless collaboration across organizational boundaries. Markdown
+export lets you seamlessly collaborate with other developers. Finally, iCal
+export can extract entries with deadlines or appointments to produce a file
+in the iCalendar format.
@menu
-* Selective export:: Using tags to select and exclude trees
-* Export options:: Per-file export settings
-* The export dispatcher:: How to access exporter commands
+* The Export Dispatcher:: The main exporter interface
+* Export back-ends:: Built-in export formats
+* Export settings:: Generic export settings
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
+* Beamer export:: Exporting as a Beamer presentation
* HTML export:: Exporting to HTML
* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
-* DocBook export:: Exporting to DocBook
+* Markdown export:: Exporting to Markdown
* OpenDocument Text export:: Exporting to OpenDocument Text
-* TaskJuggler export:: Exporting to TaskJuggler
-* Freemind export:: Exporting to Freemind mind maps
-* XOXO export:: Exporting to XOXO
-* iCalendar export:: Exporting in iCalendar format
+* iCalendar export:: Exporting to iCalendar
+* Other built-in back-ends:: Exporting to @code{Texinfo}, a man page, or Org
+* Export in foreign buffers:: Author tables in lists in Org syntax
+* Advanced configuration:: Fine-tuning the export output
@end menu
-@node Selective export, Export options, Exporting, Exporting
-@section Selective export
-@cindex export, selective by tags or TODO keyword
+@node The Export Dispatcher, Export back-ends, Exporting, Exporting
+@section The Export Dispatcher
+@vindex org-export-dispatch-use-expert-ui
+@cindex Export, dispatcher
+
+The main entry point for export related tasks is the dispatcher, a
+hierarchical menu from which it is possible to select an export format and
+toggle export options@footnote{It is also possible to use a less intrusive
+interface by setting @code{org-export-dispatch-use-expert-ui} to a
+non-@code{nil} value. In that case, only a prompt is visible from the
+minibuffer. From there one can still switch back to regular menu by pressing
+@key{?}.} from which it is possible to select an export format and to toggle
+export options.
+
+@c @quotation
+@table @asis
+@orgcmd{C-c C-e,org-export-dispatch}
-@vindex org-export-select-tags
-@vindex org-export-exclude-tags
-@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},
-respectively defaulting to @code{'(:export:)} and @code{'(:noexport:)}.
+Dispatch for export and publishing commands. When called with a @kbd{C-u}
+prefix argument, repeat the last export command on the current buffer while
+preserving toggled options. If the current buffer hasn't changed and subtree
+export was activated, the command will affect that same subtree.
+@end table
+@c @end quotation
-@enumerate
-@item
-Org first checks if any of the @emph{select} tags is present in the
-buffer. If yes, all trees that do not carry one of these tags will be
-excluded. If a selected tree is a subtree, the heading hierarchy above it
-will also be selected for export, but not the text below those headings.
+Normally the entire buffer is exported, but if there is an active region
+only that part of the buffer will be exported.
-@item
-If none of the select tags is found, the whole buffer will be selected for
-export.
+Several export options (@pxref{Export settings}) can be toggled from the
+export dispatcher with the following key combinations:
-@item
-Finally, all subtrees that are marked by any of the @emph{exclude} tags will
-be removed from the export buffer.
-@end enumerate
+@table @kbd
+@item C-a
+@vindex org-export-async-init-file
+Toggle asynchronous export. Asynchronous export uses an external Emacs
+process that is configured with a specified initialization file.
-The variable @code{org-export-with-tasks} can be configured to select which
-kind of tasks should be included for export. See the docstring of the
-variable for more information.
+While exporting asynchronously, the output is not displayed. It is stored in
+a list called ``the export stack'', and can be viewed from there. The stack
+can be reached by calling the dispatcher with a double @kbd{C-u} prefix
+argument, or with @kbd{&} key from the dispatcher.
-@node Export options, The export dispatcher, Selective export, Exporting
-@section Export options
-@cindex options, for export
+@vindex org-export-in-background
+To make this behaviour the default, customize the variable
+@code{org-export-in-background}.
-@cindex completion, of option keywords
-The exporter recognizes special lines in the buffer which provide
-additional information. These lines may be put anywhere in the file.
-The whole set of lines can be inserted into the buffer with @kbd{C-c
-C-e t}. For individual lines, a good way to make sure the keyword is
-correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
-(@pxref{Completion}). For a summary of other in-buffer settings not
-specifically related to export, see @ref{In-buffer settings}.
-In particular, note that you can place commonly-used (export) options in
-a separate file which can be included using @code{#+SETUPFILE}.
+@item C-b
+Toggle body-only export. Its effect depends on the back-end used.
+Typically, if the back-end has a header section (like @code{<head>...</head>}
+in the HTML back-end), a body-only export will not include this header.
+
+@item C-s
+@vindex org-export-initial-scope
+Toggle subtree export. The top heading becomes the document title.
+
+You can change the default state of this option by setting
+@code{org-export-initial-scope}.
+
+@item C-v
+Toggle visible-only export. Only export the text that is currently
+visible, i.e. not hidden by outline visibility in the buffer.
-@table @kbd
-@orgcmd{C-c C-e t,org-insert-export-options-template}
-Insert template with export options, see example below.
@end table
-@cindex #+TITLE
-@cindex #+AUTHOR
-@cindex #+DATE
-@cindex #+EMAIL
-@cindex #+DESCRIPTION
-@cindex #+KEYWORDS
-@cindex #+LANGUAGE
-@cindex #+TEXT
-@cindex #+OPTIONS
-@cindex #+BIND
-@cindex #+LINK_UP
-@cindex #+LINK_HOME
-@cindex #+EXPORT_SELECT_TAGS
-@cindex #+EXPORT_EXCLUDE_TAGS
-@cindex #+XSLT
-@cindex #+LaTeX_HEADER
+@vindex org-export-copy-to-kill-ring
+With the exception of asynchronous export, a successful export process writes
+its output to the kill-ring. You can configure this behavior by altering the
+option @code{org-export-copy-to-kill-ring}.
+
+@node Export back-ends, Export settings, The Export Dispatcher, Exporting
+@section Export back-ends
+@cindex Export, back-ends
+
+An export back-end is a library that translates Org syntax into a foreign
+format. An export format is not available until the proper back-end has been
+loaded.
+
+@vindex org-export-backends
+By default, the following four back-ends are loaded: @code{ascii},
+@code{html}, @code{icalendar} and @code{latex}. It is possible to add more
+(or remove some) by customizing @code{org-export-backends}.
+
+Built-in back-ends include:
+
+@itemize
+@item ascii (ASCII format)
+@item beamer (@LaTeX{} Beamer format)
+@item html (HTML format)
+@item icalendar (iCalendar format)
+@item latex (@LaTeX{} format)
+@item man (Man page format)
+@item md (Markdown format)
+@item odt (OpenDocument Text format)
+@item texinfo (Texinfo format)
+@end itemize
+
+Other back-ends might be found in the @code{contrib/} directory
+(@pxref{Installation}).
+
+@node Export settings, ASCII/Latin-1/UTF-8 export, Export back-ends, Exporting
+@section Export settings
+@cindex Export, settings
+
+Export options can be set: globally with variables; for an individual file by
+making variables buffer-local with in-buffer settings (@pxref{In-buffer
+settings}), by setting individual keywords, or by specifying them in a
+compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
+properties (@pxref{Properties and Columns}). Options set at a specific level
+override options set at a more general level.
+
+@cindex #+SETUPFILE
+In-buffer settings may appear anywhere in the file, either directly or
+indirectly through a file included using @samp{#+SETUPFILE: filename} syntax.
+Option keyword sets tailored to a particular back-end can be inserted from
+the export dispatcher (@pxref{The Export Dispatcher}) using the @code{Insert
+template} command by pressing @key{#}. To insert keywords individually,
+a good way to make sure the keyword is correct is to type @code{#+} and then
+to use @kbd{M-<TAB>} for completion.
+
+The export keywords available for every back-end, and their equivalent global
+variables, include:
+
+@table @samp
+@item AUTHOR
@vindex user-full-name
+The document author (@code{user-full-name}).
+
+@item CREATOR
+@vindex org-export-creator-string
+Entity responsible for output generation (@code{org-export-creator-string}).
+
+@item DATE
+@vindex org-export-date-timestamp-format
+A date or a time-stamp@footnote{The variable
+@code{org-export-date-timestamp-format} defines how this time-stamp will be
+exported.}.
+
+@item DESCRIPTION
+The document description. Back-ends handle it as they see fit (e.g., for the
+XHTML meta tag), if at all. You can use several such keywords for long
+descriptions.
+
+@item EMAIL
@vindex user-mail-address
+The email address (@code{user-mail-address}).
+
+@item KEYWORDS
+The keywords defining the contents of the document. Back-ends handle it as
+they see fit (e.g., for the XHTML meta tag), if at all. You can use several
+such keywords if the list is long.
+
+@item LANGUAGE
@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, 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
-#+LANGUAGE: language for HTML, e.g., @samp{en} (@code{org-export-default-language})
-#+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., @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@}
-#+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
+The language used for translating some strings
+(@code{org-export-default-language}). E.g., @samp{#+LANGUAGE: fr} will tell
+Org to translate @emph{File} (english) into @emph{Fichier} (french) in the
+clocktable.
-@noindent
-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 table of contents
-@cindex line-break preservation
-@cindex quoted HTML tags
-@cindex fixed-width sections
-@cindex tables
-@cindex @TeX{}-like syntax for sub- and superscripts
-@cindex footnotes
-@cindex special strings
-@cindex emphasized text
-@cindex @TeX{} macros
-@cindex @LaTeX{} fragments
-@cindex author info, in export
-@cindex time info, in export
-@vindex org-export-plist-vars
-@vindex org-export-author-info
-@vindex org-export-creator-info
-@vindex org-export-email-info
+@item SELECT_TAGS
+@vindex org-export-select-tags
+The tags that select a tree for export (@code{org-export-select-tags}). The
+default value is @code{:export:}. Within a subtree tagged with
+@code{:export:}, you can still exclude entries with @code{:noexport:} (see
+below).
+
+@item EXCLUDE_TAGS
+The tags that exclude a tree from export (@code{org-export-exclude-tags}).
+The default value is @code{:noexport:}. Entries with the @code{:noexport:}
+tag will be unconditionally excluded from the export, even if they have an
+@code{:export:} tag.
+
+@item TITLE
+The title to be shown (otherwise derived from buffer's name). You can use
+several such keywords for long titles.
+@end table
+
+The @code{#+OPTIONS} keyword is a compact@footnote{If you want to configure
+many options this way, you can use several @code{#+OPTIONS} lines.} form that
+recognizes the following arguments:
+
+@table @code
+@item ':
+@vindex org-export-with-smart-quotes
+Toggle smart quotes (@code{org-export-with-smart-quotes}).
+
+@item *:
+Toggle emphasized text (@code{org-export-with-emphasize}).
+
+@item -:
+@vindex org-export-with-special-strings
+Toggle conversion of special strings
+(@code{org-export-with-special-strings}).
+
+@item ::
+@vindex org-export-with-fixed-width
+Toggle fixed-width sections
+(@code{org-export-with-fixed-width}).
+
+@item <:
+@vindex org-export-with-timestamps
+Toggle inclusion of any time/date active/inactive stamps
+(@code{org-export-with-timestamps}).
+
+@item :
+@vindex org-export-preserve-breaks
+Toggle line-break-preservation (@code{org-export-preserve-breaks}).
+
+@item ^:
+@vindex org-export-with-sub-superscripts
+Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}",
+@samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
+it is (@code{org-export-with-sub-superscripts}).
+
+@item arch:
+@vindex org-export-with-archived-trees
+Configure export of archived trees. Can be set to @code{headline} to only
+process the headline, skipping its contents
+(@code{org-export-with-archived-trees}).
+
+@item author:
+@vindex org-export-with-author
+Toggle inclusion of author name into exported file
+(@code{org-export-with-author}).
+
+@item c:
+@vindex org-export-with-clocks
+Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
+
+@item creator:
+@vindex org-export-with-creator
+Configure inclusion of creator info into exported file. It may be set to
+@code{comment} (@code{org-export-with-creator}).
+
+@item d:
+@vindex org-export-with-drawers
+Toggle inclusion of drawers, or list drawers to include
+(@code{org-export-with-drawers}).
+
+@item e:
+@vindex org-export-with-entities
+Toggle inclusion of entities (@code{org-export-with-entities}).
+
+@item email:
+@vindex org-export-with-email
+Toggle inclusion of the author's e-mail into exported file
+(@code{org-export-with-email}).
+
+@item f:
+@vindex org-export-with-footnotes
+Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
+
+@item H:
+@vindex org-export-headline-levels
+Set the number of headline levels for export
+(@code{org-export-headline-levels}). Below that level, headlines are treated
+differently. In most back-ends, they become list items.
+
+@item inline:
+@vindex org-export-with-inlinetasks
+Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
+
+@item num:
+@vindex org-export-with-section-numbers
+Toggle section-numbers (@code{org-export-with-section-numbers}). It can also
+be set to a number @samp{n}, so only headlines at that level or above will be
+numbered.
+
+@item p:
+@vindex org-export-with-planning
+Toggle export of planning information (@code{org-export-with-planning}).
+``Planning information'' is the line containing the @code{SCHEDULED:}, the
+@code{DEADLINE:} or the @code{CLOSED:} cookies or a combination of them.
+
+@item pri:
+@vindex org-export-with-priority
+Toggle inclusion of priority cookies (@code{org-export-with-priority}).
+
+@item stat:
+@vindex org-export-with-statistics-cookies
+Toggle inclusion of statistics cookies
+(@code{org-export-with-statistics-cookies}).
+
+@item tags:
+@vindex org-export-with-tags
+Toggle inclusion of tags, may also be @code{not-in-toc}
+(@code{org-export-with-tags}).
+
+@item tasks:
+@vindex org-export-with-tasks
+Toggle inclusion of tasks (TODO items), can be @code{nil} to remove all
+tasks, @code{todo} to remove DONE tasks, or a list of keywords to keep
+(@code{org-export-with-tasks}).
+
+@item tex:
+@vindex org-export-with-latex
+Configure export of @LaTeX{} fragments and environments. It may be set to
+@code{verbatim} (@code{org-export-with-latex}).
+
+@item timestamp:
@vindex org-export-time-stamp-file
-@example
-H: @r{set the number of headline levels for export}
-num: @r{turn on/off section-numbers}
-toc: @r{turn on/off table of contents, or set level limit (integer)}
-\n: @r{turn on/off line-break-preservation (DOES NOT WORK)}
-@@: @r{turn on/off quoted HTML tags}
-:: @r{turn on/off fixed-width sections}
-|: @r{turn on/off tables}
-^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If}
- @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but}
- @r{the simple @code{a_b} will be left as it is.}
--: @r{turn on/off conversion of special strings.}
-f: @r{turn on/off footnotes like this[1].}
-todo: @r{turn on/off inclusion of TODO keywords into exported text}
-tasks: @r{turn on/off inclusion of tasks (TODO items), can be nil to remove}
- @r{all tasks, @code{todo} to remove DONE tasks, or list of kwds to keep}
-pri: @r{turn on/off priority cookies}
-tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}}
-<: @r{turn on/off inclusion of any time/date stamps like DEADLINES}
-*: @r{turn on/off emphasized text (bold, italic, underlined)}
-TeX: @r{turn on/off simple @TeX{} macros in plain text}
-LaTeX: @r{configure export of @LaTeX{} fragments. Default @code{auto}}
-skip: @r{turn on/off skipping the text before the first heading}
-author: @r{turn on/off inclusion of author name/email into exported file}
-email: @r{turn on/off inclusion of author email into exported file}
-creator: @r{turn on/off inclusion of creator info into exported file}
-timestamp: @r{turn on/off inclusion creation time into exported file}
-d: @r{turn on/off inclusion of drawers, or list drawers to include}
-@end example
-@noindent
-These options take effect in both the HTML and @LaTeX{} export, except for
-@code{TeX} and @code{LaTeX} options, which are respectively @code{t} and
-@code{nil} for the @LaTeX{} export.
-
-The default values for these and many other options are given by a set of
-variables. For a list of such variables, the corresponding OPTIONS keys and
-also the publishing keys (@pxref{Project alist}), see the constant
-@code{org-export-plist-vars}.
-
-When exporting only a single subtree by selecting it with @kbd{C-c @@} before
-calling an export command, the subtree can overrule some of the file's export
-settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE},
-@code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and
-@code{EXPORT_OPTIONS}.
-
-@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting
-@section The export dispatcher
-@cindex dispatcher, for export commands
-
-All export commands can be reached using the export dispatcher, which is a
-prefix key that prompts for an additional key specifying the command.
-Normally the entire file is exported, but if there is an active region that
-contains one outline tree, the first heading is used as document title and
-the subtrees are exported.
+Toggle inclusion of the creation time into exported file
+(@code{org-export-time-stamp-file}).
-@table @kbd
-@orgcmd{C-c C-e,org-export}
-@vindex org-export-run-in-background
-Dispatcher for export and publishing commands. Displays a help-window
-listing the additional key(s) needed to launch an export or publishing
-command. The prefix arg is passed through to the exporter. A double prefix
-@kbd{C-u C-u} causes most commands to be executed in the background, in a
-separate Emacs process@footnote{To make this behavior the default, customize
-the variable @code{org-export-run-in-background}.}.
-@orgcmd{C-c C-e v,org-export-visible}
-Like @kbd{C-c C-e}, but only export the text that is currently visible
-(i.e., not hidden by outline visibility).
-@orgcmd{C-u C-u C-c C-e,org-export}
-@vindex org-export-run-in-background
-Call the exporter, but reverse the setting of
-@code{org-export-run-in-background}, i.e., request background processing if
-not set, or force processing in the current Emacs process if set.
+@item toc:
+@vindex org-export-with-toc
+Toggle inclusion of the table of contents, or set the level limit
+(@code{org-export-with-toc}).
+
+@item todo:
+@vindex org-export-with-todo-keywords
+Toggle inclusion of TODO keywords into exported text
+(@code{org-export-with-todo-keywords}).
+
+@item |:
+@vindex org-export-with-tables
+Toggle inclusion of tables (@code{org-export-with-tables}).
@end table
-@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting
+@cindex property, EXPORT_FILE_NAME
+When exporting only a subtree, each of the previous keywords@footnote{With
+the exception of @samp{SETUPFILE}.} can be overriden locally by special node
+properties. These begin with @samp{EXPORT_}, followed by the name of the
+keyword they supplant. For example, @samp{DATE} and @samp{OPTIONS} keywords
+become, respectively, @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS}
+properties. Subtree export also supports the self-explicit
+@samp{EXPORT_FILE_NAME} property@footnote{There is no buffer-wide equivalent
+for this property. The file name in this case is derived from the file
+associated to the buffer, if possible, or asked to the user otherwise.}.
+
+@cindex #+BIND
+@vindex org-export-allow-bind-keywords
+If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables
+can become buffer-local during export by using the BIND keyword. Its syntax
+is @samp{#+BIND: variable value}. This is particularly useful for in-buffer
+settings that cannot be changed using specific keywords.
+
+@node ASCII/Latin-1/UTF-8 export, Beamer export, Export settings, Exporting
@section ASCII/Latin-1/UTF-8 export
@cindex ASCII export
@cindex Latin-1 export
file, containing only plain ASCII@. Latin-1 and UTF-8 export augment the file
with special characters and symbols available in these encodings.
-@cindex region, active
-@cindex active region
-@cindex transient-mark-mode
+@vindex org-ascii-links-to-notes
+Links are exported in a footnote-like style, with the descriptive part in the
+text and the link in a note before the next heading. See the variable
+@code{org-ascii-links-to-notes} for details and other options.
+
+@subheading ASCII export commands
+
@table @kbd
-@orgcmd{C-c C-e a,org-export-as-ascii}
-@cindex property, EXPORT_FILE_NAME
+@orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii}
Export as an ASCII file. For an Org file, @file{myfile.org}, the ASCII file
-will be @file{myfile.txt}. The file will be overwritten without
-warning. If there is an active region@footnote{This requires
-@code{transient-mark-mode} 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 A,org-export-as-ascii-to-buffer}
+will be @file{myfile.txt}. The file will be overwritten without warning.
+When the original file is @file{myfile.txt}, the resulting file becomes
+@file{myfile.txt.txt} in order to prevent data loss.
+@orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii}
Export to a temporary buffer. Do not create a file.
-@orgcmd{C-c C-e n,org-export-as-latin1}
-@xorgcmd{C-c C-e N,org-export-as-latin1-to-buffer}
-Like the above commands, but use Latin-1 encoding.
-@orgcmd{C-c C-e u,org-export-as-utf8}
-@xorgcmd{C-c C-e U,org-export-as-utf8-to-buffer}
-Like the above commands, but use UTF-8 encoding.
-@item C-c C-e v a/n/u
-Export only the visible part of the document.
@end table
-@cindex headline levels, for exporting
-In the exported version, the first 3 outline levels will become
-headlines, defining a general document structure. Additional levels
-will be exported as itemized lists. If you want that transition to occur
-at a different level, specify it with a prefix argument. For example,
+@subheading Header and sectioning structure
+
+In the exported version, the first three outline levels become headlines,
+defining a general document structure. Additional levels are exported as
+lists. The transition can also occur at a different level (@pxref{Export
+settings}).
+
+@subheading Quoting ASCII text
+
+You can insert text that will only appear when using @code{ASCII} back-end
+with the following constructs:
+
+@cindex #+ASCII
+@cindex #+BEGIN_ASCII
+@example
+Text @@@@ascii:and additional text@@@@ within a paragraph.
+
+#+ASCII: Some text
+
+#+BEGIN_ASCII
+All lines in this block will appear only when using this back-end.
+#+END_ASCII
+@end example
+
+@subheading ASCII specific attributes
+@cindex #+ATTR_ASCII
+@cindex horizontal rules, in ASCII export
+
+@code{ASCII} back-end only understands one attribute, @code{:width}, which
+specifies the length, in characters, of a given horizontal rule. It must be
+specified using an @code{ATTR_ASCII} line, directly preceding the rule.
+
+@example
+#+ATTR_ASCII: :width 10
+-----
+@end example
+
+@node Beamer export, HTML export, ASCII/Latin-1/UTF-8 export, Exporting
+@section Beamer export
+@cindex Beamer export
+
+The @LaTeX{} class @emph{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 Beamer presentation.
+
+@subheading Beamer export commands
+
+@table @kbd
+@orgcmd{C-c C-e l b,org-beamer-export-to-latex}
+Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{}
+file will be @file{myfile.tex}. The file will be overwritten without
+warning.
+@orgcmd{C-c C-e l B,org-beamer-export-as-latex}
+Export to a temporary buffer. Do not create a file.
+@orgcmd{C-c C-e l P,org-beamer-export-to-pdf}
+Export as @LaTeX{} and then process to PDF.
+@item C-c C-e l O
+Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
+@end table
+
+@subheading Sectioning, Frames and Blocks
+
+Any tree with not-too-deep level nesting should in principle be exportable as
+a Beamer presentation. Headlines fall into three categories: sectioning
+elements, frames and blocks.
+
+@itemize @minus
+@item
+@vindex org-beamer-frame-level
+Headlines become frames when their level is equal to
+@code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line
+(@pxref{Export settings}).
+
+@cindex property, BEAMER_ENV
+Though, if a headline in the current tree has a @code{BEAMER_ENV} property
+set to either to @code{frame} or @code{fullframe}, its level overrides the
+variable. A @code{fullframe} is a frame with an empty (ignored) title.
+
+@item
+@vindex org-beamer-environments-default
+@vindex org-beamer-environments-extra
+All frame's children become @code{block} environments. Special block types
+can be enforced by setting headline's @code{BEAMER_ENV} property@footnote{If
+this property is set, the entry will also get a @code{:B_environment:} tag to
+make this visible. This tag has no semantic meaning, it is only a visual
+aid.} to an appropriate value (see @code{org-beamer-environments-default} for
+supported values and @code{org-beamer-environments-extra} for adding more).
+
+@item
+@cindex property, BEAMER_REF
+As a special case, if the @code{BEAMER_ENV} property is set to either
+@code{appendix}, @code{note}, @code{noteNH} or @code{againframe}, the
+headline will become, respectively, an appendix, a note (within frame or
+between frame, depending on its level), a note with its title ignored or an
+@code{\againframe} command. In the latter case, a @code{BEAMER_REF} property
+is mandatory in order to refer to the frame being resumed, and contents are
+ignored.
+
+Also, a headline with an @code{ignoreheading} environment will have its
+contents only inserted in the output. This special value is useful to have
+data between frames, or to properly close a @code{column} environment.
+@end itemize
+
+@cindex property, BEAMER_ACT
+@cindex property, BEAMER_OPT
+Headlines also support @code{BEAMER_ACT} and @code{BEAMER_OPT} properties.
+The former is translated as an overlay/action specification, or a default
+overlay specification when enclosed within square brackets. The latter
+specifies options@footnote{The @code{fragile} option is added automatically
+if it contains code that requires a verbatim environment, though.} for the
+current frame or block. The export back-end will automatically wrap
+properties within angular or square brackets when appropriate.
+
+@cindex property, BEAMER_COL
+Moreover, headlines handle the @code{BEAMER_COL} property. Its value should
+be a decimal number representing the width of the column as a fraction of the
+total text width. If the headline has no specific environment, its title
+will be ignored and its contents will fill the column created. Otherwise,
+the block will fill the whole column and the title will be preserved. Two
+contiguous headlines with a non-@code{nil} @code{BEAMER_COL} value share the same
+@code{columns} @LaTeX{} environment. It will end before the next headline
+without such a property. This environment is generated automatically.
+Although, it can also be explicitly created, with a special @code{columns}
+value for @code{BEAMER_ENV} property (if it needs to be set up with some
+specific options, for example).
+
+@subheading Beamer specific syntax
+
+Beamer back-end is an extension of @LaTeX{} back-end. As such, all @LaTeX{}
+specific syntax (e.g., @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}) is
+recognized. See @ref{@LaTeX{} and PDF export} for more information.
+
+@cindex #+BEAMER_THEME
+@cindex #+BEAMER_COLOR_THEME
+@cindex #+BEAMER_FONT_THEME
+@cindex #+BEAMER_INNER_THEME
+@cindex #+BEAMER_OUTER_THEME
+Beamer export introduces a number of keywords to insert code in the
+document's header. Four control appearance of the presentantion:
+@code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
+@code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
+@code{#+BEAMER_OUTER_THEME}. All of them accept optional arguments
+within square brackets. The last one, @code{#+BEAMER_HEADER}, is more
+generic and allows you to append any line of code in the header.
+
+@example
+#+BEAMER_THEME: Rochester [height=20pt]
+#+BEAMER_COLOR_THEME: spruce
+@end example
+
+Table of contents generated from @code{toc:t} @code{OPTION} keyword are
+wrapped within a @code{frame} environment. Those generated from a @code{TOC}
+keyword (@pxref{Table of contents}) are not. In that case, it is also
+possible to specify options, enclosed within square brackets.
+
+@example
+#+TOC: headlines [currentsection]
+@end example
+
+Beamer specific code can be inserted with the following constructs:
+
+@cindex #+BEAMER
+@cindex #+BEGIN_BEAMER
+@example
+#+BEAMER: \pause
+
+#+BEGIN_BEAMER
+All lines in this block will appear only when using this back-end.
+#+END_BEAMER
+
+Text @@@@beamer:some code@@@@ within a paragraph.
+@end example
+
+In particular, this last example can be used to add overlay specifications to
+objects whose type is among @code{bold}, @code{item}, @code{link},
+@code{radio-target} and @code{target}, when the value is enclosed within
+angular brackets and put at the beginning the object.
+
+@example
+A *@@@@beamer:<2->@@@@useful* feature
+@end example
+
+@cindex #+ATTR_BEAMER
+Eventually, every plain list has support for @code{:environment},
+@code{:overlay} and @code{:options} attributes through
+@code{ATTR_BEAMER} affiliated keyword. The first one allows the use
+of a different environment, the second sets overlay specifications and
+the last one inserts optional arguments in current list environment.
+
+@example
+#+ATTR_BEAMER: :overlay +-
+- item 1
+- item 2
+@end example
+
+@subheading Editing support
+
+You can turn on a special minor mode @code{org-beamer-mode} for faster
+editing with:
+
+@example
+#+STARTUP: beamer
+@end example
+
+@table @kbd
+@orgcmd{C-c C-b,org-beamer-select-environment}
+In @code{org-beamer-mode}, this key offers fast selection of a Beamer
+environment or the @code{BEAMER_COL} property.
+@end table
+
+Also, a template for useful in-buffer settings or properties can be inserted
+into the buffer with @kbd{M-x org-beamer-insert-options-template}. Among
+other things, this will install a column view format which is very handy for
+editing special properties used by Beamer.
+
+@subheading An example
-@example
-@kbd{C-1 C-c C-e a}
-@end example
+Here is a simple example Org document that is intended for Beamer export.
-@noindent
-creates only top level headlines and exports the rest as items. When
-headlines are converted to items, the indentation of the text following
-the headline is changed to fit nicely under the item. This is done with
-the assumption that the first body line indicates the base indentation of
-the body text. Any indentation larger than this is adjusted to preserve
-the layout relative to the first line. Should there be lines with less
-indentation than the first one, these are left alone.
-
-@vindex org-export-ascii-links-to-notes
-Links will be exported in a footnote-like style, with the descriptive part in
-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
+@smallexample
+#+TITLE: Example Presentation
+#+AUTHOR: Carsten Dominik
+#+OPTIONS: H:2
+#+LATEX_CLASS: beamer
+#+LATEX_CLASS_OPTIONS: [presentation]
+#+BEAMER_THEME: Madrid
+#+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt)
+
+* This is the first structural section
+
+** Frame 1
+*** Thanks to Eric Fraga :B_block:BMCOL:
+ :PROPERTIES:
+ :BEAMER_COL: 0.48
+ :BEAMER_ENV: block
+ :END:
+ for the first viable Beamer setup in Org
+*** Thanks to everyone else :B_block:BMCOL:
+ :PROPERTIES:
+ :BEAMER_COL: 0.48
+ :BEAMER_ACT: <2->
+ :BEAMER_ENV: block
+ :END:
+ for contributing to the discussion
+**** This will be formatted as a beamer note :B_note:
+ :PROPERTIES:
+ :BEAMER_env: note
+ :END:
+** Frame 2 (where we will not use columns)
+*** Request
+ Please test this stuff!
+@end smallexample
+
+@node HTML export, @LaTeX{} and PDF export, Beamer export, Exporting
@section HTML export
@cindex HTML export
@menu
* HTML Export commands:: How to invoke HTML export
+* HTML doctypes:: Org can export to various (X)HTML flavors
* HTML preamble and postamble:: How to insert a preamble and a postamble
* Quoting HTML tags:: Using direct HTML in Org mode
* Links in HTML export:: How links will be interpreted and formatted
* JavaScript support:: Info and Folding in a web browser
@end menu
-@node HTML Export commands, HTML preamble and postamble, HTML export, HTML export
+@node HTML Export commands, HTML doctypes, HTML export, HTML export
@subsection HTML export commands
-@cindex region, active
-@cindex active region
-@cindex transient-mark-mode
@table @kbd
-@orgcmd{C-c C-e h,org-export-as-html}
-@cindex property, EXPORT_FILE_NAME
+@orgcmd{C-c C-e h h,org-html-export-to-html}
Export as a HTML file. For an Org file @file{myfile.org},
the HTML file will be @file{myfile.html}. The file will be overwritten
-without warning. If there is an active region@footnote{This requires
-@code{transient-mark-mode} 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 b,org-export-as-html-and-open}
+without warning.
+@kbd{C-c C-e h o}
Export as a HTML file and immediately open it with a browser.
-@orgcmd{C-c C-e H,org-export-as-html-to-buffer}
+@orgcmd{C-c C-e h H,org-html-export-as-html}
Export to a temporary buffer. Do not create a file.
-@orgcmd{C-c C-e R,org-export-region-as-html}
-Export the active region to a temporary buffer. With a prefix argument, do
-not produce the file header and footer, but just the plain HTML section for
-the region. This is good for cut-and-paste operations.
-@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 in 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
-code.
@end table
-@cindex headline levels, for exporting
-In the exported version, the first 3 outline levels will become headlines,
-defining a general document structure. Additional levels will be exported as
-itemized lists. If you want that transition to occur at a different level,
-specify it with a numeric prefix argument. For example,
+@c FIXME Exporting sublevels
+@c @cindex headline levels, for exporting
+@c In the exported version, the first 3 outline levels will become headlines,
+@c defining a general document structure. Additional levels will be exported as
+@c itemized lists. If you want that transition to occur at a different level,
+@c specify it with a numeric prefix argument. For example,
+
+@c @example
+@c @kbd{C-2 C-c C-e b}
+@c @end example
+
+@c @noindent
+@c creates two levels of headings and does the rest as items.
+
+@node HTML doctypes, HTML preamble and postamble, HTML Export commands, HTML export
+@subsection HTML doctypes
+@vindex org-html-doctype
+@vindex org-html-doctype-alist
+
+Org can export to various (X)HTML flavors.
+
+Setting the variable @code{org-html-doctype} allows you to export to different
+(X)HTML variants. The exported HTML will be adjusted according to the sytax
+requirements of that variant. You can either set this variable to a doctype
+string directly, in which case the exporter will try to adjust the syntax
+automatically, or you can use a ready-made doctype. The ready-made options
+are:
+
+@itemize
+@item
+``html4-strict''
+@item
+``html4-transitional''
+@item
+``html4-frameset''
+@item
+``xhtml-strict''
+@item
+``xhtml-transitional''
+@item
+``xhtml-frameset''
+@item
+``xhtml-11''
+@item
+``html5''
+@item
+``xhtml5''
+@end itemize
+
+See the variable @code{org-html-doctype-alist} for details. The default is
+``xhtml-strict''.
+
+@subsubheading Fancy HTML5 export
+@vindex org-html-html5-fancy
+@vindex org-html-html5-elements
+
+HTML5 introduces several new element types. By default, Org will not make
+use of these element types, but you can set @code{org-html-html5-fancy} to
+@code{t} (or set @code{html5-fancy} item in an @code{OPTIONS} line), to
+enable a few new block-level elements. These are created using arbitrary
+#+BEGIN and #+END blocks. For instance:
@example
-@kbd{C-2 C-c C-e b}
+#+BEGIN_ASIDE
+Lorem ipsum
+#+END_ASIDE
@end example
-@noindent
-creates two levels of headings and does the rest as items.
+Will export to:
+
+@example
+<aside>
+ <p>Lorem ipsum</p>
+</aside>
+@end example
+
+While this:
+
+@example
+#+ATTR_HTML: :controls controls :width 350
+#+BEGIN_VIDEO
+#+HTML: <source src="movie.mp4" type="video/mp4">
+#+HTML: <source src="movie.ogg" type="video/ogg">
+Your browser does not support the video tag.
+#+END_VIDEO
+@end example
+
+Becomes:
+
+@example
+<video controls="controls" width="350">
+ <source src="movie.mp4" type="video/mp4">
+ <source src="movie.ogg" type="video/ogg">
+ <p>Your browser does not support the video tag.</p>
+</video>
+@end example
+
+Special blocks that do not correspond to HTML5 elements (see
+@code{org-html-html5-elements}) will revert to the usual behavior,
+i.e. #+BEGIN_LEDERHOSEN will still export to <div class=''lederhosen''>.
+Headlines cannot appear within special blocks. To wrap a headline and its
+contents in e.g. <section> or <article> tags, set the @code{HTML_CONTAINER}
+property on the headline itself.
-@node HTML preamble and postamble, Quoting HTML tags, HTML Export commands, HTML export
+@node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export
@subsection HTML preamble and postamble
-@vindex org-export-html-preamble
-@vindex org-export-html-postamble
-@vindex org-export-html-preamble-format
-@vindex org-export-html-postamble-format
-@vindex org-export-html-validation-link
-@vindex org-export-author-info
-@vindex org-export-email-info
-@vindex org-export-creator-info
+@vindex org-html-preamble
+@vindex org-html-postamble
+@vindex org-html-preamble-format
+@vindex org-html-postamble-format
+@vindex org-html-validation-link
+@vindex org-export-creator-string
@vindex org-export-time-stamp-file
The HTML exporter lets you define a preamble and a postamble.
-The default value for @code{org-export-html-preamble} is @code{t}, which
-means that the preamble is inserted depending on the relevant format string
-in @code{org-export-html-preamble-format}.
-
-Setting @code{org-export-html-preamble} to a string will override the default
-format string. Setting it to a function, will insert the output of the
-function, which must be a string; such a function takes no argument but you
-can check against the value of @code{opt-plist}, which contains the list of
-publishing properties for the current file. Setting to @code{nil} will not
-insert any preamble.
-
-The default value for @code{org-export-html-postamble} is @code{'auto}, which
-means that the HTML exporter will look for the value of
-@code{org-export-author-info}, @code{org-export-email-info},
-@code{org-export-creator-info} and @code{org-export-time-stamp-file},
-@code{org-export-html-validation-link} and build the postamble from these
-values. Setting @code{org-export-html-postamble} to @code{t} will insert the
-postamble from the relevant format string found in
-@code{org-export-html-postamble-format}. Setting it to @code{nil} will not
-insert any postamble.
+The default value for @code{org-html-preamble} is @code{t}, which means
+that the preamble is inserted depending on the relevant format string in
+@code{org-html-preamble-format}.
+
+Setting @code{org-html-preamble} to a string will override the default format
+string. If you set it to a function, it will insert the output of the
+function, which must be a string. Setting to @code{nil} will not insert any
+preamble.
+
+The default value for @code{org-html-postamble} is @code{'auto}, which means
+that the HTML exporter will look for information about the author, the email,
+the creator and the date, and build the postamble from these values. Setting
+@code{org-html-postamble} to @code{t} will insert the postamble from the
+relevant format string found in @code{org-html-postamble-format}. Setting it
+to @code{nil} will not insert any postamble.
@node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export
@subsection Quoting HTML tags
Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
-@samp{>} in HTML export. If you want to include simple HTML tags
-which should be interpreted as such, mark them with @samp{@@} as in
-@samp{@@<b>bold text@@</b>}. Note that this really works only for
-simple tags. For more extensive HTML that should be copied verbatim to
-the exported file use either
+@samp{>} in HTML export. If you want to include raw HTML code, which
+should only appear in HTML export, mark it with @samp{@@@@html:} as in
+@samp{@@@@html:<b>@@@@bold text@@@@html:</b>@@@@}. For more extensive HTML
+that should be copied verbatim to the exported file use either
@cindex #+HTML
@cindex #+BEGIN_HTML
@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
@node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export
@subsection Tables
@cindex tables, in HTML
-@vindex org-export-html-table-tag
+@vindex org-html-table-default-attributes
-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:
+Org mode tables are exported to HTML using the table attributes defined in
+@code{org-html-table-default-attributes}. 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 #+CAPTION
@cindex #+ATTR_HTML
@example
#+CAPTION: This is a table with lines around and between cells
-#+ATTR_HTML: border="2" rules="all" frame="border"
+#+ATTR_HTML: :border 2 :rules all :frame border
@end example
+@vindex org-html-table-row-tags
+You can also modify the default tags used for each row by setting
+@code{org-html-table-row-tags}. See the docstring for an example on
+how to use this option.
+
@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export
@subsection Images in HTML export
@cindex images, inline in HTML
@cindex inlining images in HTML
-@vindex org-export-html-inline-images
+@vindex org-html-inline-images
HTML export can inline images given as links in the Org file, and
it can make an image the clickable part of a link. By
default@footnote{But see the variable
-@code{org-export-html-inline-images}.}, images are inlined if a link does
+@code{org-html-inline-images}.}, images are inlined if a link does
not have a description. So @samp{[[file:myimg.jpg]]} will be inlined,
while @samp{[[file:myimg.jpg][the image]]} will just produce a link
@samp{the image} that points to the image. If the description part
@cindex #+ATTR_HTML
@example
#+CAPTION: A black cat stalking a spider
-#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"
+#+ATTR_HTML: :alt cat/spider image :title Action! :align right
[[./img/a.jpg]]
@end example
@subsection Math formatting in HTML export
@cindex MathJax
@cindex dvipng
+@cindex imagemagick
@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
+box with Org mode installation because @uref{http://orgmode.org} serves
@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
@uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on
your own server in order to limit the load of our server.} To configure
-@file{MathJax}, use the variable @code{org-export-html-mathjax-options} or
+@file{MathJax}, use the variable @code{org-html-mathjax-options} or
insert something like the following into the buffer:
@example
-#+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
+#+HTML_MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
@end example
@noindent See the docstring of the variable
-@code{org-export-html-mathjax-options} for the meaning of the parameters in
+@code{org-html-mathjax-options} for the meaning of the parameters in
this line.
If you prefer, you can also request that @LaTeX{} fragments are processed
into small images that will be inserted into the browser page. Before the
availability of MathJax, this was the default method for Org files. This
-method requires that the @file{dvipng} program is available on your system.
-You can still get this processing with
+method requires that the @file{dvipng} program or @file{imagemagick} suite is
+available on your system. You can still get this processing with
+
+@example
+#+OPTIONS: tex:dvipng
+@end example
+
+or:
@example
-#+OPTIONS: LaTeX:dvipng
+#+OPTIONS: tex:imagemagick
@end example
@node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export
@cindex text areas, in HTML
An alternative way to publish literal code examples in HTML is to use text
areas, where the example can even be edited before pasting it into an
-application. It is triggered by a @code{-t} switch at an @code{example} or
-@code{src} block. Using this switch disables any options for syntax and
-label highlighting, and line numbering, which may be present. You may also
-use @code{-h} and @code{-w} switches to specify the height and width of the
-text area, which default to the number of lines in the example, and 80,
-respectively. For example
+application. It is triggered by @code{:textarea} attribute at an
+@code{example} or @code{src} block.
+
+You may also use @code{:height} and @code{:width} attributes to specify the
+height and width of the text area, which default to the number of lines in
+the example, and 80, respectively. For example
@example
-#+BEGIN_EXAMPLE -t -w 40
+#+ATTR_HTML: :textarea t :width 40
+#+BEGIN_EXAMPLE
(defun org-xor (a b)
"Exclusive or."
(if a (not b) b))
@cindex CSS, for HTML export
@cindex HTML export, CSS
-@vindex org-export-html-todo-kwd-class-prefix
-@vindex org-export-html-tag-class-prefix
-You can also give style information for the exported file. The HTML exporter
-assigns the following special CSS classes@footnote{If the classes on TODO
-keywords and tags lead to conflicts, use the variables
-@code{org-export-html-todo-kwd-class-prefix} and
-@code{org-export-html-tag-class-prefix} to make them unique.} to appropriate
-parts of the document---your style specifications may change these, in
-addition to any of the standard classes like for headlines, tables, etc.
+@vindex org-html-todo-kwd-class-prefix
+@vindex org-html-tag-class-prefix
+You can modify the CSS style definitions for the exported file. The HTML
+exporter assigns the following special CSS classes@footnote{If the classes on
+TODO keywords and tags lead to conflicts, use the variables
+@code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to
+make them unique.} to appropriate parts of the document---your style
+specifications may change these, in addition to any of the standard classes
+like for headlines, tables, etc.
@example
p.author @r{author information, including email}
p.date @r{publishing date}
div.outline-N @r{div for outline level N (headline plus text))}
div.outline-text-N @r{extra div for text at outline level N}
.section-number-N @r{section number in headlines, different for each level}
+.figure-number @r{label like "Figure 1:"}
+.table-number @r{label like "Table 1:"}
+.listing-number @r{label like "Listing 1:"}
div.figure @r{how to format an inlined image}
pre.src @r{formatted source code}
pre.example @r{normal example}
.footnum @r{footnote number in footnote definition (always <sup>)}
@end example
-@vindex org-export-html-style-default
-@vindex org-export-html-style-include-default
-@vindex org-export-html-style
-@vindex org-export-html-extra
-@vindex org-export-html-style-default
+@vindex org-html-style-default
+@vindex org-html-head-include-default-style
+@vindex org-html-head
+@vindex org-html-head-extra
+@cindex #+HTML_INCLUDE_STYLE
Each exported file contains a compact default style that defines these
classes in a basic way@footnote{This style is defined in the constant
-@code{org-export-html-style-default}, which you should not modify. To turn
+@code{org-html-style-default}, which you should not modify. To turn
inclusion of these defaults off, customize
-@code{org-export-html-style-include-default}}. You may overwrite these
-settings, or add to them by using the variables @code{org-export-html-style}
-(for Org-wide settings) and @code{org-export-html-style-extra} (for more
-fine-grained settings, like file-local settings). To set the latter variable
-individually for each file, you can use
+@code{org-html-head-include-default-style} or set @code{html-style} to
+@code{nil} in an @code{OPTIONS} line.}. You may overwrite these settings, or
+add to them by using the variables @code{org-html-head} and
+@code{org-html-head-extra}. You can override the global values of these
+variables for each file by using these keywords:
-@cindex #+STYLE
+@cindex #+HTML_HEAD
+@cindex #+HTML_HEAD_EXTRA
@example
-#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
+#+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
@end example
@noindent
view type is a @emph{folding} view much like Org provides inside Emacs. The
script is available at @url{http://orgmode.org/org-info.js} and you can find
the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}.
-We host the script at our site, but if you use it a lot, you might
-not want to be dependent on @url{http://orgmode.org} and prefer to install a local
+We host the script at our site, but if you use it a lot, you might not want
+to be dependent on @url{http://orgmode.org} and prefer to install a local
copy on your own web server.
-To use the script, you need to make sure that the @file{org-jsinfo.el} module
-gets loaded. It should be loaded by default, but you can try @kbd{M-x
-customize-variable @key{RET} org-modules @key{RET}} to convince yourself that
-this is indeed the case. All it then takes to make use of the program is
-adding a single line to the Org file:
+All it then takes to use this program is adding a single line to the Org
+file:
@cindex #+INFOJS_OPT
@example
@r{default), only one such button will be present.}
@end example
@noindent
-@vindex org-infojs-options
-@vindex org-export-html-use-infojs
+@vindex org-html-infojs-options
+@vindex org-html-use-infojs
You can choose default values for these options by customizing the variable
-@code{org-infojs-options}. If you always want to apply the script to your
-pages, configure the variable @code{org-export-html-use-infojs}.
+@code{org-html-infojs-options}. If you always want to apply the script to your
+pages, configure the variable @code{org-html-use-infojs}.
-@node @LaTeX{} and PDF export, DocBook export, HTML export, Exporting
+@node @LaTeX{} and PDF export, Markdown 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 @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
-implement links and cross references, the PDF output file will be fully
-linked. Beware of the fact that your @code{org} file has to be properly
-structured in order to be correctly exported: respect the hierarchy of
-sections.
+
+@LaTeX{} export can produce an arbitrarily complex LaTeX document of any
+standard or custom document class. 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}. The @LaTeX{} exporter can be configured to support
+alternative TeX engines, see the options
+@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.},
+which the @LaTeX{} exporter is able to control, this back-end is able to
+produce PDF output. Because the @LaTeX{} exporter can be configured to use
+the @code{hyperref} package, the default setup produces fully-linked PDF
+output.
+
+As in @LaTeX{}, blank lines are meaningful for this back-end: a paragraph
+will not be started if two contiguous syntactical elements are not separated
+by an empty line.
+
+This back-end also offers enhanced support for footnotes. Thus, it handles
+nested footnotes, footnotes in tables and footnotes in a list item's
+description.
@menu
-* @LaTeX{}/PDF export commands::
+* @LaTeX{} export commands:: How to export to LaTeX and PDF
* 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
-* Beamer class export:: Turning the file into a presentation
+* @LaTeX{} specific attributes:: Controlling @LaTeX{} output
@end menu
-@node @LaTeX{}/PDF export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export
+@node @LaTeX{} export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export
@subsection @LaTeX{} export commands
-@cindex region, active
-@cindex active region
-@cindex transient-mark-mode
@table @kbd
-@orgcmd{C-c C-e l,org-export-as-latex}
-@cindex property EXPORT_FILE_NAME
-Export as a @LaTeX{} file. For an Org file
-@file{myfile.org}, the @LaTeX{} file will be @file{myfile.tex}. The file will
-be overwritten without warning. If there is an active region@footnote{This
-requires @code{transient-mark-mode} 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 L,org-export-as-latex-to-buffer}
+@orgcmd{C-c C-e l l,org-latex-export-to-latex}
+Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{}
+file will be @file{myfile.tex}. The file will be overwritten without
+warning.
+@orgcmd{C-c C-e l L,org-latex-export-as-latex}
Export to a temporary buffer. Do not create a file.
-@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 in 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{}
-code.
-@orgcmd{C-c C-e p,org-export-as-pdf}
+@orgcmd{C-c C-e l p,org-latex-export-to-pdf}
Export as @LaTeX{} and then process to PDF.
-@orgcmd{C-c C-e d,org-export-as-pdf-and-open}
+@item C-c C-e l o
Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
@end table
-@cindex headline levels, for exporting
-@vindex org-latex-low-levels
-In the exported version, the first 3 outline levels will become
-headlines, defining a general document structure. Additional levels
-will be exported as description lists. The exporter can ignore them or
-convert them to a custom string depending on
-@code{org-latex-low-levels}.
-
-If you want that transition to occur at a different level, specify it
-with a numeric prefix argument. For example,
-
-@example
-@kbd{C-2 C-c C-e l}
-@end example
-
-@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{} export commands, @LaTeX{} and PDF export
@subsection Header and sectioning structure
@cindex @LaTeX{} class
@cindex @LaTeX{} sectioning structure
@cindex header, for @LaTeX{} files
@cindex sectioning structure, for @LaTeX{} export
+By default, the first three outline levels become headlines, defining a
+general document structure. Additional levels are exported as @code{itemize}
+or @code{enumerate} lists. The transition can also occur at a different
+level (@pxref{Export settings}).
+
By default, the @LaTeX{} output uses the class @code{article}.
-@vindex org-export-latex-default-class
-@vindex org-export-latex-classes
-@vindex org-export-latex-default-packages-alist
-@vindex org-export-latex-packages-alist
-@cindex #+LaTeX_HEADER
-@cindex #+LaTeX_CLASS
-@cindex #+LaTeX_CLASS_OPTIONS
-@cindex property, LaTeX_CLASS
-@cindex property, LaTeX_CLASS_OPTIONS
+@vindex org-latex-default-class
+@vindex org-latex-classes
+@vindex org-latex-default-packages-alist
+@vindex org-latex-packages-alist
You can change this globally by setting a different value for
-@code{org-export-latex-default-class} or locally by adding an option like
-@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:}
-property that applies when exporting a region containing only this (sub)tree.
-The class must be listed in @code{org-export-latex-classes}. This variable
-defines a header template for each class@footnote{Into which the values of
-@code{org-export-latex-default-packages-alist} and
-@code{org-export-latex-packages-alist} are spliced.}, and allows you to
-define the sectioning structure for each class. You can also define your own
-classes there. @code{#+LaTeX_CLASS_OPTIONS} or a @code{:LaTeX_CLASS_OPTIONS:}
-property can specify the options for the @code{\documentclass} macro. The
-options to documentclass have to be provided, as expected by @LaTeX{}, within
-square brackets. You can also use @code{#+LaTeX_HEADER: \usepackage@{xyz@}}
-to add lines to the header. See the docstring of
-@code{org-export-latex-classes} for more information. An example is shown
-below.
-
-@example
-#+LaTeX_CLASS: article
-#+LaTeX_CLASS_OPTIONS: [a4paper]
-#+LaTeX_HEADER: \usepackage@{xyz@}
+@code{org-latex-default-class} or locally by adding an option like
+@code{#+LATEX_CLASS: myclass} in your file, or with
+a @code{EXPORT_LATEX_CLASS} property that applies when exporting a region
+containing only this (sub)tree. The class must be listed in
+@code{org-latex-classes}. This variable defines a header template for each
+class@footnote{Into which the values of
+@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}
+are spliced.}, and allows you to define the sectioning structure for each
+class. You can also define your own classes there.
+
+@cindex #+LATEX_CLASS
+@cindex #+LATEX_CLASS_OPTIONS
+@cindex property, EXPORT_LATEX_CLASS
+@cindex property, EXPORT_LATEX_CLASS_OPTIONS
+The @code{LATEX_CLASS_OPTIONS} keyword or @code{EXPORT_LATEX_CLASS_OPTIONS}
+property can specify the options for the @code{\documentclass} macro. These
+options have to be provided, as expected by @LaTeX{}, within square brackets.
+
+@cindex #+LATEX_HEADER
+@cindex #+LATEX_HEADER_EXTRA
+You can also use the @code{LATEX_HEADER} and
+@code{LATEX_HEADER_EXTRA}@footnote{Unlike @code{LATEX_HEADER}, contents
+from @code{LATEX_HEADER_EXTRA} keywords will not be loaded when previewing
+@LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).} keywords in order
+to add lines to the header. See the docstring of @code{org-latex-classes} for
+more information.
+
+An example is shown below.
+
+@example
+#+LATEX_CLASS: article
+#+LATEX_CLASS_OPTIONS: [a4paper]
+#+LATEX_HEADER: \usepackage@{xyz@}
* Headline 1
some text
@end example
-@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, Header and sectioning, @LaTeX{} and PDF export
+@node Quoting @LaTeX{} code, @LaTeX{} specific attributes, Header and sectioning, @LaTeX{} and PDF export
@subsection Quoting @LaTeX{} code
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
-the following constructs:
+inserted into the @LaTeX{} file. Furthermore, you can add special code that
+should only be present in @LaTeX{} export with the following constructs:
-@cindex #+LaTeX
-@cindex #+BEGIN_LaTeX
+@cindex #+LATEX
+@cindex #+BEGIN_LATEX
@example
-#+LaTeX: Literal @LaTeX{} code for export
-@end example
+Code within @@@@latex:some code@@@@ a paragraph.
-@noindent or
-@cindex #+BEGIN_LaTeX
+#+LATEX: Literal @LaTeX{} code for export
-@example
-#+BEGIN_LaTeX
+#+BEGIN_LATEX
All lines between these markers are exported literally
-#+END_LaTeX
+#+END_LATEX
@end example
+@node @LaTeX{} specific attributes, , Quoting @LaTeX{} code, @LaTeX{} and PDF export
+@subsection @LaTeX{} specific attributes
+@cindex #+ATTR_LATEX
-@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} and PDF export
-@subsection Tables in @LaTeX{} export
+@LaTeX{} understands attributes specified in an @code{ATTR_LATEX} line. They
+affect tables, images, plain lists, special blocks and source blocks.
+
+@subsubheading Tables in @LaTeX{} export
@cindex tables, in @LaTeX{} export
-For @LaTeX{} export of a table, you can specify a label, a caption and
-placement options (@pxref{Images and tables}). You can also use the
-@code{ATTR_LaTeX} line to request a @code{longtable} environment for the
-table, so that it may span several pages, or to change the default table
-environment from @code{table} to @code{table*} or to change the default inner
-tabular environment to @code{tabularx} or @code{tabulary}. Finally, you can
-set the alignment string, and (with @code{tabularx} or @code{tabulary}) the
-width:
+For @LaTeX{} export of a table, you can specify a label and a caption
+(@pxref{Images and tables}). You can also use attributes to control table
+layout and contents. Valid @LaTeX{} attributes include:
+
+@table @code
+@item :mode
+@vindex org-latex-default-table-mode
+Nature of table's contents. It can be set to @code{table}, @code{math},
+@code{inline-math} or @code{verbatim}. In particular, when in @code{math} or
+@code{inline-math} mode, every cell is exported as-is, horizontal rules are
+ignored and the table will be wrapped in a math environment. Also,
+contiguous tables sharing the same math mode will be wrapped within the same
+environment. Default mode is determined in
+@code{org-latex-default-table-mode}.
+@item :environment
+@vindex org-latex-default-table-environment
+Environment used for the table. It can be set to any @LaTeX{} table
+environment, like @code{tabularx}@footnote{Requires adding the
+@code{tabularx} package to @code{org-latex-packages-alist}.},
+@code{longtable}, @code{array}, @code{tabu}@footnote{Requires adding the
+@code{tabu} package to @code{org-latex-packages-alist}.},
+@code{bmatrix}@enddots{} It defaults to
+@code{org-latex-default-table-environment} value.
+@item :caption
+@code{#+CAPTION} keyword is the simplest way to set a caption for a table
+(@pxref{Images and tables}). If you need more advanced commands for that
+task, you can use @code{:caption} attribute instead. Its value should be raw
+@LaTeX{} code. It has precedence over @code{#+CAPTION}.
+@item :float
+@itemx :placement
+Float environment for the table. Possible values are @code{sidewaystable},
+@code{multicolumn}, @code{t} and @code{nil}. When unspecified, a table with
+a caption will have a @code{table} environment. Moreover, @code{:placement}
+attribute can specify the positioning of the float.
+@item :align
+@itemx :font
+@itemx :width
+Set, respectively, the alignment string of the table, its font size and its
+width. They only apply on regular tables.
+@item :spread
+Boolean specific to the @code{tabu} and @code{longtabu} environments, and
+only takes effect when used in conjunction with the @code{:width} attribute.
+When @code{:spread} is non-@code{nil}, the table will be spread or shrunk by the
+value of @code{:width}.
+@item :booktabs
+@itemx :center
+@itemx :rmlines
+@vindex org-latex-tables-booktabs
+@vindex org-latex-tables-centered
+They toggle, respectively, @code{booktabs} usage (assuming the package is
+properly loaded), table centering and removal of every horizontal rule but
+the first one (in a "table.el" table only). In particular,
+@code{org-latex-tables-booktabs} (respectively @code{org-latex-tables-centered})
+activates the first (respectively second) attribute globally.
+@item :math-prefix
+@itemx :math-suffix
+@itemx :math-arguments
+A string that will be inserted, respectively, before the table within the
+math environment, after the table within the math environment, and between
+the macro name and the contents of the table. The @code{:math-arguments}
+attribute is used for matrix macros that require more than one argument
+(e.g., @code{qbordermatrix}).
+@end table
+
+Thus, attributes can be used in a wide array of situations, like writing
+a table that will span over multiple pages, or a matrix product:
-@cindex #+CAPTION
-@cindex #+LABEL
-@cindex #+ATTR_LaTeX
@example
-#+CAPTION: A long table
-#+LABEL: tbl:long
-#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l
+#+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l
| ..... | ..... |
| ..... | ..... |
+
+#+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
+| a | b |
+| c | d |
+#+ATTR_LATEX: :mode math :environment bmatrix
+| 1 | 2 |
+| 3 | 4 |
@end example
-or to specify a multicolumn table with @code{tabulary}
+In the example below, @LaTeX{} command
+@code{\bicaption@{HeadingA@}@{HeadingB@}} will set the caption.
-@cindex #+CAPTION
-@cindex #+LABEL
-@cindex #+ATTR_LaTeX
@example
-#+CAPTION: A wide table with tabulary
-#+LABEL: tbl:wide
-#+ATTR_LaTeX: table* tabulary width=\textwidth
+#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
| ..... | ..... |
| ..... | ..... |
@end example
-@node Images in @LaTeX{} export, Beamer class export, Tables in @LaTeX{} export, @LaTeX{} and PDF export
-@subsection Images in @LaTeX{} export
+
+@subsubheading Images in @LaTeX{} export
@cindex images, inline in @LaTeX{}
@cindex inlining images in @LaTeX{}
Images that are linked to without a description part in the link, like
@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF
output file resulting from @LaTeX{} processing. Org will use an
-@code{\includegraphics} macro to insert the image. If you have specified a
-caption and/or a label as described in @ref{Images and tables}, the figure
-will be wrapped into a @code{figure} environment and thus become a floating
-element. You can use an @code{#+ATTR_LaTeX:} line to specify various other
-options. You can ask org to export an image as a float without specifying
-a label or a caption by using the keyword @code{float} in this line. Various
-optional arguments to the @code{\includegraphics} macro can also be specified
-in this fashion. To modify the placement option of the floating environment,
-add something like @samp{placement=[h!]} to the attributes. It is to be noted
-this option can be used with tables as well@footnote{One can also take
-advantage of this option to pass other, unrelated options into the figure or
-table environment. For an example see the section ``Exporting org files'' in
-@url{http://orgmode.org/worg/org-hacks.html}}.
-
-If you would like to let text flow around the image, add the word @samp{wrap}
-to the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left
-half of the page. To fine-tune, the @code{placement} field will be the set
-of additional arguments needed by the @code{wrapfigure} environment. Note
-that if you change the size of the image, you need to use compatible settings
-for @code{\includegraphics} and @code{wrapfigure}.
+@code{\includegraphics} macro to insert the image@footnote{In the case of
+TikZ (@url{http://sourceforge.net/projects/pgf/}) images, it will become an
+@code{\input} macro wrapped within a @code{tikzpicture} environment.}.
+
+You can specify specify image width or height with, respectively,
+@code{:width} and @code{:height} attributes. It is also possible to add any
+other option with the @code{:options} attribute, as shown in the following
+example:
-@cindex #+CAPTION
-@cindex #+LABEL
-@cindex #+ATTR_LaTeX
@example
-#+CAPTION: The black-body emission of the disk around HR 4049
-#+LABEL: fig:SED-HR4049
-#+ATTR_LaTeX: width=5cm,angle=90
+#+ATTR_LATEX: :width 5cm :options angle=90
[[./img/sed-hr4049.pdf]]
-
-#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@}
-[[./img/hst.png]]
@end example
-If you wish to include an image which spans multiple columns in a page, you
-can use the keyword @code{multicolumn} in the @code{#+ATTR_LaTeX} line. This
-will export the image wrapped in a @code{figure*} environment.
+If you need a specific command for the caption, use @code{:caption}
+attribute. It will override standard @code{#+CAPTION} value, if any.
-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
-@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.
-
-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
-exportable as a beamer presentation. By default, the top-level entries (or
-the first level below the selected subtree heading) will be turned into
-frames, and the outline structure below this level will become itemize lists.
-You can also configure the variable @code{org-beamer-frame-level} to a
-different level---then the hierarchy above frames will produce the sectioning
-structure of the presentation.
-
-A template for useful in-buffer settings or properties can be inserted into
-the buffer with @kbd{M-x org-insert-beamer-options-template}. Among other
-things, this will install a column view format which is very handy for
-editing special properties used by beamer.
-
-You can influence the structure of the presentation using the following
-properties:
+@example
+#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
+[[./img/sed-hr4049.pdf]]
+@end example
-@table @code
-@item BEAMER_env
-The environment that should be used to format this entry. Valid environments
-are defined in the constant @code{org-beamer-environments-default}, and you
-can define more in @code{org-beamer-environments-extra}. If this property is
-set, the entry will also get a @code{:B_environment:} tag to make this
-visible. This tag has no semantic meaning, it is only a visual aid.
-@item BEAMER_envargs
-The beamer-special arguments that should be used for the environment, like
-@code{[t]} or @code{[<+->]} of @code{<2-3>}. If the @code{BEAMER_col}
-property is also set, something like @code{C[t]} can be added here as well to
-set an options argument for the implied @code{columns} environment.
-@code{c[t]} or @code{c<2->} will set an options for the implied @code{column}
+If you have specified a caption as described in @ref{Images and tables}, the
+picture will be wrapped into a @code{figure} environment and thus become
+a floating element. You can also ask Org to export an image as a float
+without specifying caption by setting the @code{:float} attribute. You may
+also set it to:
+@itemize @minus
+@item
+@code{t}: if you want to use the standard @samp{figure} environment. It is
+used by default if you provide a caption to the image.
+@item
+@code{multicolumn}: if you wish to include an image which spans multiple
+columns in a page. This will export the image wrapped in a @code{figure*}
environment.
-@item BEAMER_col
-The width of a column that should start with this entry. If this property is
-set, the entry will also get a @code{:BMCOL:} property to make this visible.
-Also this tag is only a visual aid. When this is a plain number, it will be
-interpreted as a fraction of @code{\textwidth}. Otherwise it will be assumed
-that you have specified the units, like @samp{3cm}. The first such property
-in a frame will start a @code{columns} environment to surround the columns.
-This environment is closed when an entry has a @code{BEAMER_col} property
-with value 0 or 1, or automatically at the end of the frame.
-@item BEAMER_extra
-Additional commands that should be inserted after the environment has been
-opened. For example, when creating a frame, this can be used to specify
-transitions.
-@end table
-
-Frames will automatically receive a @code{fragile} option if they contain
-source code that uses the verbatim environment. Special @file{beamer}
-specific code can be inserted using @code{#+BEAMER:} and
-@code{#+BEGIN_BEAMER...#+END_BEAMER} constructs, similar to other export
-backends, but with the difference that @code{#+LaTeX:} stuff will be included
-in the presentation as well.
-
-Outline nodes with @code{BEAMER_env} property value @samp{note} or
-@samp{noteNH} will be formatted as beamer notes, i,e, they will be wrapped
-into @code{\note@{...@}}. The former will include the heading as part of the
-note text, the latter will ignore the heading of that node. To simplify note
-generation, it is actually enough to mark the note with a @emph{tag} (either
-@code{:B_note:} or @code{:B_noteNH:}) instead of creating the
-@code{BEAMER_env} property.
-
-You can turn on a special minor mode @code{org-beamer-mode} for editing
-support with
+@item
+@code{wrap}: if you would like to let text flow around the image. It will
+make the figure occupy the left half of the page.
+@item
+@code{nil}: if you need to avoid any floating environment, even when
+a caption is provided.
+@end itemize
+@noindent
+To modify the placement option of any floating environment, set the
+@code{placement} attribute.
@example
-#+STARTUP: beamer
+#+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@}
+[[./img/hst.png]]
@end example
-@table @kbd
-@orgcmd{C-c C-b,org-beamer-select-environment}
-In @code{org-beamer-mode}, this key offers fast selection of a beamer
-environment or the @code{BEAMER_col} property.
-@end table
-
-Column view provides a great way to set the environment of a node and other
-important parameters. Make sure you are using a COLUMN format that is geared
-toward this special purpose. The command @kbd{M-x
-org-insert-beamer-options-template} defines such a format.
-
-Here is a simple example Org document that is intended for beamer export.
-
-@smallexample
-#+LaTeX_CLASS: beamer
-#+TITLE: Example Presentation
-#+AUTHOR: Carsten Dominik
-#+LaTeX_CLASS_OPTIONS: [presentation]
-#+BEAMER_FRAME_LEVEL: 2
-#+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@}
-#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex)
-
-* This is the first structural section
-
-** Frame 1 \\ with a subtitle
-*** Thanks to Eric Fraga :BMCOL:B_block:
- :PROPERTIES:
- :BEAMER_env: block
- :BEAMER_envargs: C[t]
- :BEAMER_col: 0.5
- :END:
- for the first viable beamer setup in Org
-*** Thanks to everyone else :BMCOL:B_block:
- :PROPERTIES:
- :BEAMER_col: 0.5
- :BEAMER_env: block
- :BEAMER_envargs: <2->
- :END:
- for contributing to the discussion
-**** This will be formatted as a beamer note :B_note:
-** Frame 2 \\ where we will not use columns
-*** Request :B_block:
- Please test this stuff!
- :PROPERTIES:
- :BEAMER_env: block
- :END:
-@end smallexample
-
-For more information, see the documentation on Worg.
+If the @code{:comment-include} attribute is set to a non-@code{nil} value,
+the @LaTeX{} @code{\includegraphics} macro will be commented out.
-@node DocBook export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting
-@section DocBook export
-@cindex DocBook export
-@cindex PDF export
-@cindex Cui, Baoqiu
+@subsubheading Plain lists in @LaTeX{} export
+@cindex plain lists, in @LaTeX{} export
-Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is
-exported to DocBook format, it can be further processed to produce other
-formats, including PDF, HTML, man pages, etc., using many available DocBook
-tools and stylesheets.
+Plain lists accept two optional attributes: @code{:environment} and
+@code{:options}. The first one allows the use of a non-standard
+environment (e.g., @samp{inparaenum}). The second one specifies
+optional arguments for that environment (square brackets may be
+omitted).
-Currently DocBook exporter only supports DocBook V5.0.
+@example
+#+ATTR_LATEX: :environment compactitem :options $\circ$
+- you need ``paralist'' package to reproduce this example.
+@end example
-@menu
-* DocBook export commands:: How to invoke DocBook export
-* Quoting DocBook code:: Incorporating DocBook code in Org files
-* Recursive sections:: Recursive sections in DocBook
-* Tables in DocBook export:: Tables are exported as HTML tables
-* Images in DocBook export:: How to insert figures into DocBook output
-* Special characters:: How to handle special characters
-@end menu
+@subsubheading Source blocks in @LaTeX{} export
+@cindex source blocks, in @LaTeX{} export
-@node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export
-@subsection DocBook export commands
+In addition to syntax defined in @ref{Literal examples}, names and captions
+(@pxref{Images and tables}), source blocks also accept a @code{:float}
+attribute. You may set it to:
+@itemize @minus
+@item
+@code{t}: if you want to make the source block a float. It is the default
+value when a caption is provided.
+@item
+@code{mulicolumn}: if you wish to include a source block which spans multiple
+colums in a page.
+@item
+@code{nil}: if you need to avoid any floating evironment, even when a caption
+is provided. It is useful for source code that may not fit in a single page.
+@end itemize
-@cindex region, active
-@cindex active region
-@cindex transient-mark-mode
-@table @kbd
-@orgcmd{C-c C-e D,org-export-as-docbook}
-@cindex property EXPORT_FILE_NAME
-Export as a DocBook file. For an Org file, @file{myfile.org}, the DocBook XML
-file will be @file{myfile.xml}. 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 V,org-export-as-docbook-pdf-and-open}
-Export as a DocBook file, process to PDF, then open the resulting PDF file.
-
-@vindex org-export-docbook-xslt-proc-command
-@vindex org-export-docbook-xsl-fo-proc-command
-Note that, in order to produce PDF output based on an exported DocBook file,
-you need to have XSLT processor and XSL-FO processor software installed on your
-system. Check variables @code{org-export-docbook-xslt-proc-command} and
-@code{org-export-docbook-xsl-fo-proc-command}.
-
-@vindex org-export-docbook-xslt-stylesheet
-The stylesheet argument @code{%s} in variable
-@code{org-export-docbook-xslt-proc-command} is replaced by the value of
-variable @code{org-export-docbook-xslt-stylesheet}, which needs to be set by
-the user. You can also overrule this global setting on a per-file basis by
-adding an in-buffer setting @code{#+XSLT:} to the Org file.
-
-@orgkey{C-c C-e v D}
-Export only the visible part of the document.
-@end table
+@example
+#+ATTR_LATEX: :float nil
+#+BEGIN_SRC emacs-lisp
+Code that may not fit in a single page.
+#+END_SRC
+@end example
-@node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export
-@subsection Quoting DocBook code
+@subsubheading Special blocks in @LaTeX{} export
+@cindex special blocks, in @LaTeX{} export
-You can quote DocBook code in Org files and copy it verbatim into exported
-DocBook file with the following constructs:
+In @LaTeX{} back-end, special blocks become environments of the same name.
+Value of @code{:options} attribute will be appended as-is to that
+environment's opening string. For example:
-@cindex #+DOCBOOK
-@cindex #+BEGIN_DOCBOOK
@example
-#+DOCBOOK: Literal DocBook code for export
+#+ATTR_LATEX: :options [Proof of important theorem]
+#+BEGIN_PROOF
+...
+Therefore, any even number greater than 2 is the sum of two primes.
+#+END_PROOF
@end example
-@noindent or
-@cindex #+BEGIN_DOCBOOK
+@noindent
+becomes
@example
-#+BEGIN_DOCBOOK
-All lines between these markers are exported by DocBook exporter
-literally.
-#+END_DOCBOOK
+\begin@{proof@}[Proof of important theorem]
+...
+Therefore, any even number greater than 2 is the sum of two primes.
+\end@{proof@}
@end example
-For example, you can use the following lines to include a DocBook warning
-admonition. As to what this warning says, you should pay attention to the
-document context when quoting DocBook code in Org files. You may make
-exported DocBook XML files invalid by not quoting DocBook code correctly.
+If you need to insert a specific caption command, use @code{:caption}
+attribute. It will override standard @code{#+CAPTION} value, if any. For
+example:
@example
-#+BEGIN_DOCBOOK
-<warning>
- <para>You should know what you are doing when quoting DocBook XML code
- in your Org file. Invalid DocBook XML may be generated by
- DocBook exporter if you are not careful!</para>
-</warning>
-#+END_DOCBOOK
+#+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
+#+BEGIN_PROOF
+...
+#+END_PROOF
@end example
-@node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export
-@subsection Recursive sections
-@cindex DocBook recursive sections
-
-DocBook exporter exports Org files as articles using the @code{article}
-element in DocBook. Recursive sections, i.e., @code{section} elements, are
-used in exported articles. Top level headlines in Org files are exported as
-top level sections, and lower level headlines are exported as nested
-sections. The entire structure of Org files will be exported completely, no
-matter how many nested levels of headlines there are.
-
-Using recursive sections makes it easy to port and reuse exported DocBook
-code in other DocBook document types like @code{book} or @code{set}.
+@subsubheading Horizontal rules
+@cindex horizontal rules, in @LaTeX{} export
-@node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export
-@subsection Tables in DocBook export
-@cindex tables, in DocBook export
+Width and thickness of a given horizontal rule can be controlled with,
+respectively, @code{:width} and @code{:thickness} attributes:
-Tables in Org files are exported as HTML tables, which have been supported since
-DocBook V4.3.
-
-If a table does not have a caption, an informal table is generated using the
-@code{informaltable} element; otherwise, a formal table will be generated
-using the @code{table} element.
-
-@node Images in DocBook export, Special characters, Tables in DocBook export, DocBook export
-@subsection Images in DocBook export
-@cindex images, inline in DocBook
-@cindex inlining images in DocBook
-
-Images that are linked to without a description part in the link, like
-@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBook
-using @code{mediaobject} elements. Each @code{mediaobject} element contains
-an @code{imageobject} that wraps an @code{imagedata} element. If you have
-specified a caption for an image as described in @ref{Images and tables}, a
-@code{caption} element will be added in @code{mediaobject}. If a label is
-also specified, it will be exported as an @code{xml:id} attribute of the
-@code{mediaobject} element.
-
-@vindex org-export-docbook-default-image-attributes
-Image attributes supported by the @code{imagedata} element, like @code{align}
-or @code{width}, can be specified in two ways: you can either customize
-variable @code{org-export-docbook-default-image-attributes} or use the
-@code{#+ATTR_DOCBOOK:} line. Attributes specified in variable
-@code{org-export-docbook-default-image-attributes} are applied to all inline
-images in the Org file to be exported (unless they are overridden by image
-attributes specified in @code{#+ATTR_DOCBOOK:} lines).
-
-The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image
-attributes or override default image attributes for individual images. If
-the same attribute appears in both the @code{#+ATTR_DOCBOOK:} line and
-variable @code{org-export-docbook-default-image-attributes}, the former
-takes precedence. Here is an example about how image attributes can be
-set:
-
-@cindex #+CAPTION
-@cindex #+LABEL
-@cindex #+ATTR_DOCBOOK
@example
-#+CAPTION: The logo of Org mode
-#+LABEL: unicorn-svg
-#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
-[[./img/org-mode-unicorn.svg]]
+#+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
+-----
@end example
-@vindex org-export-docbook-inline-image-extensions
-By default, DocBook exporter recognizes the following image file types:
-@file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}. You can
-customize variable @code{org-export-docbook-inline-image-extensions} to add
-more types to this list as long as DocBook supports them.
+@node Markdown export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting
+@section Markdown export
+@cindex Markdown export
-@node Special characters, , Images in DocBook export, DocBook export
-@subsection Special characters in DocBook export
-@cindex Special characters in DocBook export
+@code{md} export back-end generates Markdown syntax@footnote{Vanilla flavour,
+as defined at @url{http://daringfireball.net/projects/markdown/}.} for an Org
+mode buffer.
-@vindex org-export-docbook-doctype
-@vindex org-entities
-Special characters that are written in @TeX{}-like syntax, such as @code{\alpha},
-@code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter. These
-characters are rewritten to XML entities, like @code{α},
-@code{Γ}, and @code{Ζ}, based on the list saved in variable
-@code{org-entities}. As long as the generated DocBook file includes the
-corresponding entities, these special characters are recognized.
+It is built over HTML back-end: any construct not supported by Markdown
+syntax (e.g., tables) will be controlled and translated by @code{html}
+back-end (@pxref{HTML export}).
-You can customize variable @code{org-export-docbook-doctype} to include the
-entities you need. For example, you can set variable
-@code{org-export-docbook-doctype} to the following value to recognize all
-special characters included in XHTML entities:
+@subheading Markdown export commands
-@example
-"<!DOCTYPE article [
-<!ENTITY % xhtml1-symbol PUBLIC
-\"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
-\"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
->
-%xhtml1-symbol;
-]>
-"
-@end example
+@table @kbd
+@orgcmd{C-c C-e m m,org-md-export-to-markdown}
+Export as a text file written in Markdown syntax. For an Org file,
+@file{myfile.org}, the resulting file will be @file{myfile.md}. The file
+will be overwritten without warning.
+@orgcmd{C-c C-e m M,org-md-export-as-markdown}
+Export to a temporary buffer. Do not create a file.
+@item C-c C-e m o
+Export as a text file with Markdown syntax, then open it.
+@end table
+
+@subheading Header and sectioning structure
+
+@vindex org-md-headline-style
+Markdown export can generate both @code{atx} and @code{setext} types for
+headlines, according to @code{org-md-headline-style}. The former introduces
+a hard limit of two levels, whereas the latter pushes it to six. Headlines
+below that limit are exported as lists. You can also set a soft limit before
+that one (@pxref{Export settings}).
@c begin opendocument
-@node OpenDocument Text export, TaskJuggler export, DocBook export, Exporting
+@node OpenDocument Text export, iCalendar export, Markdown export, Exporting
@section OpenDocument Text export
-@cindex K, Jambunathan
@cindex ODT
@cindex OpenDocument
@cindex export, OpenDocument
@cindex LibreOffice
-@cindex org-odt.el
-@cindex org-modules
-Org Mode@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
+Org mode@footnote{Versions 7.8 or later} supports export to OpenDocument Text
+(ODT) format. 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.
@cindex active region
@cindex transient-mark-mode
@table @kbd
-@orgcmd{C-c C-e o,org-export-as-odt}
+@orgcmd{C-c C-e o o,org-odt-export-to-odt}
@cindex property EXPORT_FILE_NAME
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, ,
+@vindex org-odt-preferred-output-format
+If @code{org-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
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}
+@kbd{C-c C-e o O}
Export as an 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}.
+@vindex org-odt-preferred-output-format
+If @code{org-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 Extending ODT export, Applying custom styles, ODT export commands, OpenDocument Text export
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
+@code{org-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
+@vindex org-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
+@code{org-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.
converter. Once a converter is configured, you can interact with it using
the following command.
-@vindex org-export-odt-convert
+@vindex org-odt-convert
@table @kbd
-@item M-x org-export-odt-convert
+@item M-x org-odt-convert RET
Convert an existing document from one format to another. With a prefix
argument, also open the newly produced file.
@end table
@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
+@vindex org-odt-styles-file
+Customize the variable @code{org-odt-styles-file} and point it to the
newly created file. For additional configuration options
@pxref{x-overriding-factory-styles,,Overriding factory styles}.
@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
+@cindex links, in ODT export
ODT exporter creates native cross-references for internal links. It creates
Internet-style links for all other links.
@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
+@cindex tables, in ODT 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
@code{#+ATTR_ODT} attribute.
@cindex identify, ImageMagick
-@vindex org-export-odt-pixels-per-inch
+@vindex org-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
+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
+@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
+@code{org-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 @LaTeX{}-to-MathML converter.
@table @kbd
-
-@item M-x org-export-as-odf
+@item M-x org-odt-export-as-odf RET
Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file.
-@item M-x org-export-as-odf-and-open
+@item M-x org-odt-export-as-odf-and-open RET
Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file
and open the formula file with the system-registered application.
@end table
@cindex dvipng
+@cindex imagemagick
@item PNG images
This option is activated on a per-file basis with
@example
-#+OPTIONS: LaTeX:dvipng
+#+OPTIONS: tex:dvipng
+@end example
+
+or:
+
+@example
+#+OPTIONS: tex:imagemagick
@end example
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.
+that the @file{dvipng} program or @file{imagemagick} suite be available on
+your system.
@end enumerate
@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in ODT export
Figure 2: Bell curve
@end example
-@vindex org-export-odt-category-strings
+@vindex org-odt-category-map-alist
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.
+option @code{org-odt-category-map-alist}. 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")))
+(setq org-odt-category-map-alist
+ (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
@end lisp
With this, previous image will be captioned as below in the exported
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-odt-fontify-srcblocks
+If you prefer to use your own custom styles for fontification, you can do
+so by customizing the option
+@code{org-odt-create-custom-styles-for-srcblocks}.
-@vindex org-export-odt-create-custom-styles-for-srcblocks
+@vindex org-odt-create-custom-styles-for-srcblocks
You can turn off fontification of literal examples by customizing the
-variable @code{org-export-odt-fontify-srcblocks}.
+option @code{org-odt-fontify-srcblocks}.
@node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export
@subsection Advanced topics in ODT export
@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.
+@vindex org-odt-convert-processes
+Name your converter and add it to the list of known converters by
+customizing the option @code{org-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
+@vindex org-odt-convert-capabilities
+@anchor{x-odt-converter-capabilities} Specify the set of formats the
+converter can handle by customizing the variable
+@code{org-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
+@vindex org-odt-convert-process
Select the newly added converter as the preferred one by customizing the
-variable @code{org-export-odt-convert-process}.
+option @code{org-odt-convert-process}.
@end enumerate
@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export
exporter.
@itemize
-@anchor{x-org-export-odt-styles-file}
+@anchor{x-org-odt-styles-file}
@item
-@code{org-export-odt-styles-file}
+@code{org-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:
Use the default @file{styles.xml}
@end enumerate
-@anchor{x-org-export-odt-content-template-file}
+@anchor{x-org-odt-content-template-file}
@item
-@code{org-export-odt-content-template-file}
+@code{org-odt-content-template-file}
Use this variable to specify the blank @file{content.xml} that will be used
in the final output.
@example
<style:style style:name="PageBreak" style:family="paragraph"
- style:parent-style-name="Text_20_body">
+ style:parent-style-name="Text_20_body">
<style:paragraph-properties fo:break-before="page"/>
</style:style>
@end example
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.
+@vindex org-odt-table-styles
+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))))))
+(setq org-odt-table-styles
+ (append org-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
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}
+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.
@code{table:use-banding-column-styles} of the @code{<table:table>} element in
the OpenDocument-v1.2 specification}
-@vindex org-export-odt-table-styles
+@vindex org-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:
+@code{org-odt-table-styles} and specify the following:
@itemize @minus
@item the name of the table template created in step (1)
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))))))
+(setq org-odt-table-styles
+ (append org-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, OpenDocument Text export, Exporting
-@section TaskJuggler export
-@cindex TaskJuggler export
-@cindex Project management
-
-@uref{http://www.taskjuggler.org/, TaskJuggler} is a project management tool.
-It provides an optimizing scheduler that computes your project time lines and
-resource assignments based on the project outline and the constraints that
-you have provided.
-
-The TaskJuggler exporter is a bit different from other exporters, such as 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.
-
-Instead the TaskJuggler exporter looks for a tree that defines the tasks and
-a optionally tree that defines the resources for this project. It then
-creates a TaskJuggler file based on these trees and the attributes defined in
-all the nodes.
-
-@subsection TaskJuggler export commands
-
-@table @kbd
-@orgcmd{C-c C-e j,org-export-as-taskjuggler}
-Export as a TaskJuggler file.
-
-@orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open}
-Export as a TaskJuggler file and then open the file with TaskJugglerUI.
-@end table
-
-@subsection Tasks
-
-@vindex org-export-taskjuggler-project-tag
-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}.
-Now mark the top node of your tasks with a tag named
-@code{:taskjuggler_project:} (or whatever you customized
-@code{org-export-taskjuggler-project-tag} to). You are now ready to export
-the project plan with @kbd{C-c C-e J} which will export the project plan and
-open a gantt chart in TaskJugglerUI.
-
-@subsection Resources
-
-@vindex org-export-taskjuggler-resource-tag
-Next you can define resources and assign those to work on specific tasks. You
-can group your resources hierarchically. Tag the top node of the resources
-with @code{:taskjuggler_resource:} (or whatever you customized
-@code{org-export-taskjuggler-resource-tag} to). You can optionally assign an
-identifier (named @samp{resource_id}) to the resources (using the standard
-Org properties commands, @pxref{Property syntax}) or you can let the exporter
-generate identifiers automatically (the exporter picks the first word of the
-headline as the identifier as long as it is unique---see the documentation of
-@code{org-taskjuggler-get-unique-id}). Using that identifier you can then
-allocate resources to tasks. This is again done with the @samp{allocate}
-property on the tasks. Do this in column view or when on the task type
-@kbd{C-c C-x p allocate @key{RET} <resource_id> @key{RET}}.
-
-Once the allocations are done you can again export to TaskJuggler and check
-in the Resource Allocation Graph which person is working on what task at what
-time.
-
-@subsection Export of properties
-
-The exporter also takes TODO state information into consideration, i.e., if a
-task is marked as done it will have the corresponding attribute in
-TaskJuggler (@samp{complete 100}). Also it will export any property on a task
-resource or resource node which is known to TaskJuggler, such as
-@samp{limits}, @samp{vacation}, @samp{shift}, @samp{booking},
-@samp{efficiency}, @samp{journalentry}, @samp{rate} for resources or
-@samp{account}, @samp{start}, @samp{note}, @samp{duration}, @samp{end},
-@samp{journalentry}, @samp{milestone}, @samp{reference}, @samp{responsible},
-@samp{scheduling}, etc.@: for tasks.
-
-@subsection Dependencies
-
-The exporter will handle dependencies that are defined in the tasks either
-with the @samp{ORDERED} attribute (@pxref{TODO dependencies}), with the
-@samp{BLOCKER} attribute (see @file{org-depend.el}) or alternatively with a
-@samp{depends} attribute. Both the @samp{BLOCKER} and the @samp{depends}
-attribute can be either @samp{previous-sibling} or a reference to an
-identifier (named @samp{task_id}) which is defined for another task in the
-project. @samp{BLOCKER} and the @samp{depends} attribute can define multiple
-dependencies separated by either space or comma. You can also specify
-optional attributes on the dependency by simply appending it. The following
-examples should illustrate this:
-
-@example
-* Preparation
- :PROPERTIES:
- :task_id: preparation
- :ORDERED: t
- :END:
-* Training material
- :PROPERTIES:
- :task_id: training_material
- :ORDERED: t
- :END:
-** Markup Guidelines
- :PROPERTIES:
- :Effort: 2d
- :END:
-** Workflow Guidelines
- :PROPERTIES:
- :Effort: 2d
- :END:
-* Presentation
- :PROPERTIES:
- :Effort: 2d
- :BLOCKER: training_material @{ gapduration 1d @} preparation
- :END:
-@end example
-
-@subsection Reports
-
-@vindex org-export-taskjuggler-default-reports
-TaskJuggler can produce many kinds of reports (e.g., gantt chart, resource
-allocation, etc). The user defines what kind of reports should be generated
-for a project in the TaskJuggler file. The exporter will automatically insert
-some default reports in the file. These defaults are defined in
-@code{org-export-taskjuggler-default-reports}. They can be modified using
-customize along with a number of other options. For a more complete list, see
-@kbd{M-x customize-group @key{RET} org-export-taskjuggler @key{RET}}.
+@item
+Associate a table with the table style
-For more information and examples see the Org-taskjuggler tutorial at
-@uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.html}.
+To do this, specify the table style created in step (2) as part of
+the @code{ATTR_ODT} line as shown below.
-@node Freemind export, XOXO export, TaskJuggler export, Exporting
-@section Freemind export
-@cindex Freemind export
-@cindex mind map
+@example
+#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
+| Name | Phone | Age |
+| Peter | 1234 | 17 |
+| Anna | 4321 | 25 |
+@end example
+@end enumerate
-The Freemind exporter was written by Lennart Borgman.
+@node Validating OpenDocument XML, , Customizing tables in ODT export, Advanced topics in ODT export
+@subsubsection Validating OpenDocument XML
-@table @kbd
-@orgcmd{C-c C-e m,org-export-as-freemind}
-Export as a Freemind mind map. For an Org file @file{myfile.org}, the Freemind
-file will be @file{myfile.mm}.
-@end table
+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.
-@node XOXO export, iCalendar export, Freemind export, Exporting
-@section XOXO export
-@cindex XOXO export
+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}.
-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.
+@vindex org-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-odt-schema-dir} to point to that directory. The ODT exporter
+will take care of updating the @code{rng-schema-locating-files} for you.
-@table @kbd
-@orgcmd{C-c C-e x,org-export-as-xoxo}
-Export as an XOXO file. For an Org file @file{myfile.org}, the XOXO file will be
-@file{myfile.html}.
-@orgkey{C-c C-e v x}
-Export only the visible part of the document.
-@end table
+@c end opendocument
-@node iCalendar export, , XOXO export, Exporting
+@node iCalendar export, Other built-in back-ends, OpenDocument Text export, Exporting
@section iCalendar export
@cindex iCalendar export
figure out from which entry all the different instances originate.
@table @kbd
-@orgcmd{C-c C-e i,org-export-icalendar-this-file}
-Create iCalendar entries for the current file and store them in the same
+@orgcmd{C-c C-e c f,org-icalendar-export-to-ics}
+Create iCalendar entries for the current buffer and store them in the same
directory, using a file extension @file{.ics}.
-@orgcmd{C-c C-e I, org-export-icalendar-all-agenda-files}
+@orgcmd{C-c C-e c a, org-icalendar-export-agenda-files}
@vindex org-agenda-files
-Like @kbd{C-c C-e i}, but do this for all files in
+Like @kbd{C-c C-e c f}, but do this for all files in
@code{org-agenda-files}. For each of these files, a separate iCalendar
file will be written.
-@orgcmd{C-c C-e c,org-export-icalendar-combine-agenda-files}
-@vindex org-combined-agenda-icalendar-file
+@orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files}
+@vindex org-icalendar-combined-agenda-file
Create a single large iCalendar file from all files in
@code{org-agenda-files} and write it to the file given by
-@code{org-combined-agenda-icalendar-file}.
+@code{org-icalendar-combined-agenda-file}.
@end table
@vindex org-use-property-inheritance
How this calendar is best read and updated, depends on the application
you are using. The FAQ covers this issue.
+@node Other built-in back-ends, Export in foreign buffers, iCalendar export, Exporting
+@section Other built-in back-ends
+@cindex export back-ends, built-in
+@vindex org-export-backends
+
+On top of the aforemetioned back-ends, Org comes with other built-in ones:
+
+@itemize
+@item @file{ox-man.el}: export to a man page.
+@item @file{ox-texinfo.el}: export to @code{Texinfo} format.
+@item @file{ox-org.el}: export to an Org document.
+@end itemize
+
+To activate these export back-end, customize @code{org-export-backends} or
+load them directly with e.g., @code{(require 'ox-texinfo)}. This will add
+new keys in the export dispatcher (@pxref{The Export Dispatcher}).
+
+See the comment section of these files for more information on how to use
+them.
+
+@node Export in foreign buffers, Advanced configuration, Other built-in back-ends, Exporting
+@section Export in foreign buffers
+
+Most built-in back-ends come with a command to convert the selected region
+into a selected format and replace this region by the exported output. Here
+is a list of such conversion commands:
+
+@table @code
+@item org-html-convert-region-to-html
+Convert the selected region into HTML.
+@item org-latex-convert-region-to-latex
+Convert the selected region into @LaTeX{}.
+@item org-texinfo-convert-region-to-texinfo
+Convert the selected region into @code{Texinfo}.
+@item org-md-convert-region-to-md
+Convert the selected region into @code{MarkDown}.
+@end table
+
+This is particularily useful for converting tables and lists in foreign
+buffers. E.g., in a HTML buffer, you can turn on @code{orgstruct-mode}, then
+use Org commands for editing a list, and finally select and convert the list
+with @code{M-x org-html-convert-region-to-html RET}.
+
+@node Advanced configuration, , Export in foreign buffers, Exporting
+@section Advanced configuration
+
+@subheading Hooks
+
+@vindex org-export-before-processing-hook
+@vindex org-export-before-parsing-hook
+Two hooks are run during the first steps of the export process. The first
+one, @code{org-export-before-processing-hook} is called before expanding
+macros, Babel code and include keywords in the buffer. The second one,
+@code{org-export-before-parsing-hook}, as its name suggests, happens just
+before parsing the buffer. Their main use is for heavy duties, that is
+duties involving structural modifications of the document. For example, one
+may want to remove every headline in the buffer during export. The following
+code can achieve this:
+
+@lisp
+@group
+(defun my-headline-removal (backend)
+ "Remove all headlines in the current buffer.
+BACKEND is the export back-end being used, as a symbol."
+ (org-map-entries
+ (lambda () (delete-region (point) (progn (forward-line) (point))))))
+
+(add-hook 'org-export-before-parsing-hook 'my-headline-removal)
+@end group
+@end lisp
+
+Note that functions used in these hooks require a mandatory argument,
+a symbol representing the back-end used.
+
+@subheading Filters
+
+@cindex Filters, exporting
+Filters are lists of functions applied on a specific part of the output from
+a given back-end. More explicitly, each time a back-end transforms an Org
+object or element into another language, all functions within a given filter
+type are called in turn on the string produced. The string returned by the
+last function will be the one used in the final output.
+
+There are filters sets for each type of element or object, for plain text,
+for the parse tree, for the export options and for the final output. They
+are all named after the same scheme: @code{org-export-filter-TYPE-functions},
+where @code{TYPE} is the type targeted by the filter. Valid types are:
+
+@multitable @columnfractions .33 .33 .33
+@item bold
+@tab babel-call
+@tab center-block
+@item clock
+@tab code
+@tab comment
+@item comment-block
+@tab diary-sexp
+@tab drawer
+@item dynamic-block
+@tab entity
+@tab example-block
+@item export-block
+@tab export-snippet
+@tab final-output
+@item fixed-width
+@tab footnote-definition
+@tab footnote-reference
+@item headline
+@tab horizontal-rule
+@tab inline-babel-call
+@item inline-src-block
+@tab inlinetask
+@tab italic
+@item item
+@tab keyword
+@tab latex-environment
+@item latex-fragment
+@tab line-break
+@tab link
+@item node-property
+@tab options
+@tab paragraph
+@item parse-tree
+@tab plain-list
+@tab plain-text
+@item planning
+@tab property-drawer
+@tab quote-block
+@item quote-section
+@tab radio-target
+@tab section
+@item special-block
+@tab src-block
+@tab statistics-cookie
+@item strike-through
+@tab subscript
+@tab superscript
+@item table
+@tab table-cell
+@tab table-row
+@item target
+@tab timestamp
+@tab underline
+@item verbatim
+@tab verse-block
+@tab
+@end multitable
+
+For example, the following snippet allows me to use non-breaking spaces in
+the Org buffer and get them translated into @LaTeX{} without using the
+@code{\nbsp} macro (where @code{_} stands for the non-breaking space):
+
+@lisp
+@group
+(defun my-latex-filter-nobreaks (text backend info)
+ "Ensure \"Â \" are properly handled in LaTeX export."
+ (when (org-export-derived-backend-p backend 'latex)
+ (replace-regexp-in-string "Â " "~" text)))
+
+(add-to-list 'org-export-filter-plain-text-functions
+ 'my-latex-filter-nobreaks)
+@end group
+@end lisp
+
+Three arguments must be provided to a filter: the code being changed, the
+back-end used, and some information about the export process. You can safely
+ignore the third argument for most purposes. Note the use of
+@code{org-export-derived-backend-p}, which ensures that the filter will only
+be applied when using @code{latex} back-end or any other back-end derived
+from it (e.g., @code{beamer}).
+
+@subheading Extending an existing back-end
+
+This is obviously the most powerful customization, since the changes happen
+at the parser level. Indeed, some export back-ends are built as extensions
+of other ones (e.g. Markdown back-end an extension of HTML back-end).
+
+Extending a back-end means that if an element type is not transcoded by the
+new back-end, it will be handled by the original one. Hence you can extend
+specific parts of a back-end without too much work.
+
+As an example, imagine we want the @code{ascii} back-end to display the
+language used in a source block, when it is available, but only when some
+attribute is non-@code{nil}, like the following:
+
+@example
+#+ATTR_ASCII: :language t
+@end example
+
+Because that back-end is lacking in that area, we are going to create a new
+back-end, @code{my-ascii} that will do the job.
+
+@lisp
+@group
+(defun my-ascii-src-block (src-block contents info)
+ "Transcode a SRC-BLOCK element from Org to ASCII.
+CONTENTS is nil. INFO is a plist used as a communication
+channel."
+ (if (not (org-export-read-attribute :attr_ascii src-block :language))
+ (org-export-with-backend 'ascii src-block contents info)
+ (concat
+ (format ",--[ %s ]--\n%s`----"
+ (org-element-property :language src-block)
+ (replace-regexp-in-string
+ "^" "| "
+ (org-element-normalize-string
+ (org-export-format-code-default src-block info)))))))
+
+(org-export-define-derived-backend 'my-ascii 'ascii
+ :translate-alist '((src-block . my-ascii-src-block)))
+@end group
+@end lisp
+
+The @code{my-ascii-src-block} function looks at the attribute above the
+element. If it isn’t true, it gives hand to the @code{ascii} back-end.
+Otherwise, it creates a box around the code, leaving room for the language.
+A new back-end is then created. It only changes its behaviour when
+translating @code{src-block} type element. Now, all it takes to use the new
+back-end is calling the following from an Org buffer:
+
+@smalllisp
+(org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
+@end smalllisp
+
+It is obviously possible to write an interactive function for this, install
+it in the export dispatcher menu, and so on.
+
@node Publishing, Working With Source Code, Exporting, Top
@chapter Publishing
@cindex publishing
@tab Directory containing publishing source files
@item @code{:publishing-directory}
@tab Directory where output files will be published. You can directly
-publish to a webserver using a file name syntax appropriate for
+publish to a web server using a file name syntax appropriate for
the Emacs @file{tramp} package. Or you can publish to a local directory and
use external tools to upload your website (@pxref{Uploading files}).
@item @code{:preparation-function}
and @code{:exclude}.
@item @code{:recursive}
-@tab Non-nil means, check base-directory recursively for files to publish.
+@tab non-@code{nil} means, check base-directory recursively for files to publish.
@end multitable
@node Publishing action, Publishing options, Selecting files, Configuration
Publishing means that a file is copied to the destination directory and
possibly transformed in the process. The default transformation is to export
Org files as HTML files, and this is done by the function
-@code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML
+@code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML
export}). But you also can publish your content as PDF files using
-@code{org-publish-org-to-pdf}, or as @code{ascii}, @code{latin1} or
-@code{utf8} encoded files using the corresponding functions. If you want to
-publish the Org file itself, but with @i{archived}, @i{commented}, and
-@i{tag-excluded} trees removed, use @code{org-publish-org-to-org} and set the
-parameters @code{:plain-source} and/or @code{:htmlized-source}. This will
-produce @file{file.org} and @file{file.org.html} in the publishing
-directory@footnote{@file{file-source.org} and @file{file-source.org.html} if
-source and publishing directories are equal. Note that with this kind of
-setup, you need to add @code{:exclude "-source\\.org"} to the project
-definition in @code{org-publish-project-alist} to prevent the published
-source files from being considered as new org files the next time the project
-is published.}. Other files like images only need to be copied to the
-publishing destination; for this you may use @code{org-publish-attachment}.
-For non-Org files, you always need to specify the publishing function:
+@code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc.,
+using the corresponding functions.
+
+If you want to publish the Org file as an @code{.org} file but with the
+@i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the
+function @code{org-org-publish-to-org}. This will produce @file{file.org}
+and put it in the publishing directory. If you want a htmlized version of
+this file, set the parameter @code{:htmlized-source} to @code{t}, it will
+produce @file{file.org.html} in the publishing directory@footnote{If the
+publishing directory is the same than the source directory, @file{file.org}
+will be exported as @file{file.org.org}, so probably don't want to do this.}.
+
+Other files like images only need to be copied to the publishing destination.
+For this you can use @code{org-publish-attachment}. For non-org files, you
+always need to specify the publishing function:
@multitable @columnfractions 0.3 0.7
@item @code{:publishing-function}
@tab Function executing the publication of a file. This may also be a
list of functions, which will all be called in turn.
-@item @code{:plain-source}
-@tab Non-nil means, publish plain source.
@item @code{:htmlized-source}
-@tab Non-nil means, publish htmlized source.
+@tab non-@code{nil} means, publish htmlized source.
@end multitable
The function must accept three arguments: a property list containing at least
-a @code{:publishing-directory} property, the name of the file to be
-published, and the path to the publishing directory of the output file. It
-should take the specified file, make the necessary transformation (if any)
-and place the result into the destination folder.
+a @code{:publishing-directory} property, the name of the file to be published
+and the path to the publishing directory of the output file. It should take
+the specified file, make the necessary transformation (if any) and place the
+result into the destination folder.
@node Publishing options, Publishing links, Publishing action, Configuration
-@subsection Options for the HTML/@LaTeX{} exporters
+@subsection Options for the exporters
@cindex options, for publishing
-The property list can be used to set many export options for the HTML
-and @LaTeX{} exporters. In most cases, these properties correspond to user
-variables in Org. The table below lists these properties along
-with the variable they belong to. See the documentation string for the
-respective variable for details.
+The property list can be used to set many export options for the exporters.
+In most cases, these properties correspond to user variables in Org. The
+first table below lists these properties along with the variable they belong
+to. The second table list HTML specific properties. See the documentation
+string of these options for details.
-@vindex org-export-html-link-up
-@vindex org-export-html-link-home
-@vindex org-export-default-language
@vindex org-display-custom-times
+@vindex org-export-default-language
+@vindex org-export-exclude-tags
@vindex org-export-headline-levels
-@vindex org-export-with-section-numbers
-@vindex org-export-section-number-format
-@vindex org-export-with-toc
@vindex org-export-preserve-breaks
+@vindex org-export-publishing-directory
+@vindex org-export-select-tags
@vindex org-export-with-archived-trees
+@vindex org-export-with-author
+@vindex org-export-with-creator
+@vindex org-export-with-drawers
+@vindex org-export-with-email
@vindex org-export-with-emphasize
-@vindex org-export-with-sub-superscripts
-@vindex org-export-with-special-strings
+@vindex org-export-with-fixed-width
@vindex org-export-with-footnotes
-@vindex org-export-with-drawers
+@vindex org-export-with-latex
+@vindex org-export-with-planning
+@vindex org-export-with-priority
+@vindex org-export-with-section-numbers
+@vindex org-export-with-special-strings
+@vindex org-export-with-sub-superscripts
+@vindex org-export-with-tables
@vindex org-export-with-tags
-@vindex org-export-with-todo-keywords
@vindex org-export-with-tasks
-@vindex org-export-with-done-tasks
-@vindex org-export-with-priority
-@vindex org-export-with-TeX-macros
-@vindex org-export-with-LaTeX-fragments
-@vindex org-export-skip-text-before-1st-heading
-@vindex org-export-with-fixed-width
@vindex org-export-with-timestamps
-@vindex org-export-author-info
-@vindex org-export-email-info
-@vindex org-export-creator-info
-@vindex org-export-time-stamp-file
-@vindex org-export-with-tables
-@vindex org-export-highlight-first-table-line
-@vindex org-export-html-style-include-default
-@vindex org-export-html-style-include-scripts
-@vindex org-export-html-style
-@vindex org-export-html-style-extra
-@vindex org-export-html-link-org-files-as-html
-@vindex org-export-html-inline-images
-@vindex org-export-html-extension
-@vindex org-export-html-table-tag
-@vindex org-export-html-expand
-@vindex org-export-html-with-timestamp
-@vindex org-export-publishing-directory
-@vindex org-export-html-preamble
-@vindex org-export-html-postamble
-@vindex user-full-name
+@vindex org-export-with-toc
+@vindex org-export-with-todo-keywords
@vindex user-mail-address
-@vindex org-export-select-tags
-@vindex org-export-exclude-tags
@multitable @columnfractions 0.32 0.68
-@item @code{:link-up} @tab @code{org-export-html-link-up}
-@item @code{:link-home} @tab @code{org-export-html-link-home}
-@item @code{:language} @tab @code{org-export-default-language}
-@item @code{:customtime} @tab @code{org-display-custom-times}
+@item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
+@item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
@item @code{:headline-levels} @tab @code{org-export-headline-levels}
-@item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
-@item @code{:section-number-format} @tab @code{org-export-section-number-format}
-@item @code{:table-of-contents} @tab @code{org-export-with-toc}
+@item @code{:language} @tab @code{org-export-default-language}
@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
-@item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
-@item @code{:emphasize} @tab @code{org-export-with-emphasize}
-@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}
-@item @code{:special-strings} @tab @code{org-export-with-special-strings}
-@item @code{:footnotes} @tab @code{org-export-with-footnotes}
-@item @code{:drawers} @tab @code{org-export-with-drawers}
-@item @code{:tags} @tab @code{org-export-with-tags}
-@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords}
-@item @code{:tasks} @tab @code{org-export-with-tasks}
-@item @code{:priority} @tab @code{org-export-with-priority}
-@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
-@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
-@item @code{:latex-listings} @tab @code{org-export-latex-listings}
-@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading}
-@item @code{:fixed-width} @tab @code{org-export-with-fixed-width}
-@item @code{:timestamps} @tab @code{org-export-with-timestamps}
-@item @code{:author} @tab @code{user-full-name}
-@item @code{:email} @tab @code{user-mail-address} : @code{addr;addr;..}
-@item @code{:author-info} @tab @code{org-export-author-info}
-@item @code{:email-info} @tab @code{org-export-email-info}
-@item @code{:creator-info} @tab @code{org-export-creator-info}
-@item @code{:tables} @tab @code{org-export-with-tables}
-@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}
-@item @code{:style-include-default} @tab @code{org-export-html-style-include-default}
-@item @code{:style-include-scripts} @tab @code{org-export-html-style-include-scripts}
-@item @code{:style} @tab @code{org-export-html-style}
-@item @code{:style-extra} @tab @code{org-export-html-style-extra}
-@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}
-@item @code{:inline-images} @tab @code{org-export-html-inline-images}
-@item @code{:html-extension} @tab @code{org-export-html-extension}
-@item @code{:html-preamble} @tab @code{org-export-html-preamble}
-@item @code{:html-postamble} @tab @code{org-export-html-postamble}
-@item @code{:xml-declaration} @tab @code{org-export-html-xml-declaration}
-@item @code{:html-table-tag} @tab @code{org-export-html-table-tag}
-@item @code{:expand-quoted-html} @tab @code{org-export-html-expand}
-@item @code{:timestamp} @tab @code{org-export-html-with-timestamp}
@item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
+@item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
@item @code{:select-tags} @tab @code{org-export-select-tags}
-@item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
-@item @code{:latex-image-options} @tab @code{org-export-latex-image-default-option}
+@item @code{:with-author} @tab @code{org-export-with-author}
+@item @code{:with-creator} @tab @code{org-export-with-creator}
+@item @code{:with-drawers} @tab @code{org-export-with-drawers}
+@item @code{:with-email} @tab @code{org-export-with-email}
+@item @code{:with-emphasize} @tab @code{org-export-with-emphasize}
+@item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width}
+@item @code{:with-footnotes} @tab @code{org-export-with-footnotes}
+@item @code{:with-latex} @tab @code{org-export-with-latex}
+@item @code{:with-planning} @tab @code{org-export-with-planning}
+@item @code{:with-priority} @tab @code{org-export-with-priority}
+@item @code{:with-special-strings} @tab @code{org-export-with-special-strings}
+@item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts}
+@item @code{:with-tables} @tab @code{org-export-with-tables}
+@item @code{:with-tags} @tab @code{org-export-with-tags}
+@item @code{:with-tasks} @tab @code{org-export-with-tasks}
+@item @code{:with-timestamps} @tab @code{org-export-with-timestamps}
+@item @code{:with-toc} @tab @code{org-export-with-toc}
+@item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords}
@end multitable
-Most of the @code{org-export-with-*} variables have the same effect in
-both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and
-@code{:LaTeX-fragments} options, respectively @code{nil} and @code{t} in the
-@LaTeX{} export. See @code{org-export-plist-vars} to check this list of
-options.
-
+@vindex org-html-doctype
+@vindex org-html-xml-declaration
+@vindex org-html-link-up
+@vindex org-html-link-home
+@vindex org-html-link-org-files-as-html
+@vindex org-html-head
+@vindex org-html-head-extra
+@vindex org-html-inline-images
+@vindex org-html-extension
+@vindex org-html-preamble
+@vindex org-html-postamble
+@vindex org-html-table-default-attributes
+@vindex org-html-head-include-default-style
+@vindex org-html-head-include-scripts
+@multitable @columnfractions 0.32 0.68
+@item @code{:html-doctype} @tab @code{org-html-doctype}
+@item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration}
+@item @code{:html-link-up} @tab @code{org-html-link-up}
+@item @code{:html-link-home} @tab @code{org-html-link-home}
+@item @code{:html-link-org-as-html} @tab @code{org-html-link-org-files-as-html}
+@item @code{:html-head} @tab @code{org-html-head}
+@item @code{:html-head-extra} @tab @code{org-html-head-extra}
+@item @code{:html-inline-images} @tab @code{org-html-inline-images}
+@item @code{:html-extension} @tab @code{org-html-extension}
+@item @code{:html-preamble} @tab @code{org-html-preamble}
+@item @code{:html-postamble} @tab @code{org-html-postamble}
+@item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
+@item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
+@item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
+@end multitable
+Most of the @code{org-export-with-*} variables have the same effect in each
+exporter.
@vindex org-publish-project-alist
-When a property is given a value in @code{org-publish-project-alist},
-its setting overrides the value of the corresponding user variable (if
-any) during publishing. Options set within a file (@pxref{Export
-options}), however, override everything.
+When a property is given a value in @code{org-publish-project-alist}, its
+setting overrides the value of the corresponding user variable (if any)
+during publishing. Options set within a file (@pxref{Export settings}),
+however, override everything.
@node Publishing links, Sitemap, Publishing options, Configuration
@subsection Links between published files
@cindex links, publishing
-To create a link from one Org file to another, you would use
-something like @samp{[[file:foo.org][The foo]]} or simply
-@samp{file:foo.org.} (@pxref{Hyperlinks}). When published, this link
-becomes a link to @file{foo.html}. In this way, you can interlink the
-pages of your "org web" project and the links will work as expected when
-you publish them to HTML@. If you also publish the Org source file and want
-to link to that, use an @code{http:} link instead of a @code{file:} link,
-because @code{file:} links are converted to link to the corresponding
-@file{html} file.
+To create a link from one Org file to another, you would use something like
+@samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org.}
+(@pxref{Hyperlinks}). When published, this link becomes a link to
+@file{foo.html}. You can thus interlink the pages of your "org web" project
+and the links will work as expected when you publish them to HTML@. If you
+also publish the Org source file and want to link to it, use an @code{http:}
+link instead of a @code{file:} link, because @code{file:} links are converted
+to link to the corresponding @file{html} file.
You may also link to related files, such as images. Provided you are careful
with relative file names, and provided you have also configured Org to upload
the related files, these links will work too. See @ref{Complex example}, for
an example of this usage.
-Sometimes an Org file to be published may contain links that are
-only valid in your production environment, but not in the publishing
-location. In this case, use the property
-
-@multitable @columnfractions 0.4 0.6
-@item @code{:link-validation-function}
-@tab Function to validate links
-@end multitable
-
-@noindent
-to define a function for checking link validity. This function must
-accept two arguments, the file name and a directory relative to which
-the file name is interpreted in the production environment. If this
-function returns @code{nil}, then the HTML generator will only insert a
-description into the HTML file, but no link. One option for this
-function is @code{org-publish-validate-link} which checks if the given
-file is part of any project in @code{org-publish-project-alist}.
-
@node Sitemap, Generating an index, Publishing links, Configuration
@subsection Generating a sitemap
@cindex sitemap, of published pages
@multitable @columnfractions 0.35 0.65
@item @code{:auto-sitemap}
-@tab When non-nil, publish a sitemap during @code{org-publish-current-project}
+@tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project}
or @code{org-publish-all}.
@item @code{:sitemap-filename}
@code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
@item @code{:sitemap-sans-extension}
-@tab When non-nil, remove filenames' extensions from the generated sitemap.
+@tab When non-@code{nil}, remove filenames' extensions from the generated sitemap.
Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}).
Defaults to @code{nil}.
@multitable @columnfractions 0.25 0.75
@item @code{:makeindex}
-@tab When non-nil, generate in index in the file @file{theindex.org} and
+@tab When non-@code{nil}, generate in index in the file @file{theindex.org} and
publish it as @file{theindex.html}.
@end multitable
:base-directory "~/org/"
:publishing-directory "~/public_html"
:section-numbers nil
- :table-of-contents nil
- :style "<link rel=\"stylesheet\"
- href=\"../other/mystyle.css\"
- type=\"text/css\"/>")))
+ :with-toc nil
+ :html-head "<link rel=\"stylesheet\"
+ href=\"../other/mystyle.css\"
+ type=\"text/css\"/>")))
@end lisp
@node Complex example, , Simple example, Sample configuration
:base-directory "~/org/"
:base-extension "org"
:publishing-directory "/ssh:user@@host:~/html/notebook/"
- :publishing-function org-publish-org-to-html
+ :publishing-function org-html-publish-to-html
:exclude "PrivatePage.org" ;; regexp
:headline-levels 3
:section-numbers nil
- :table-of-contents nil
- :style "<link rel=\"stylesheet\"
+ :with-toc nil
+ :html-head "<link rel=\"stylesheet\"
href=\"../other/mystyle.css\" type=\"text/css\"/>"
:html-preamble t)
Once properly configured, Org can publish with the following commands:
@table @kbd
-@orgcmd{C-c C-e X,org-publish}
+@orgcmd{C-c C-e P x,org-publish}
Prompt for a specific project and publish all files that belong to it.
-@orgcmd{C-c C-e P,org-publish-current-project}
+@orgcmd{C-c C-e P p,org-publish-current-project}
Publish the project containing the current file.
-@orgcmd{C-c C-e F,org-publish-current-file}
+@orgcmd{C-c C-e P f,org-publish-current-file}
Publish only the current file.
-@orgcmd{C-c C-e E,org-publish-all}
+@orgcmd{C-c C-e P a,org-publish-all}
Publish every project.
@end table
@table @code
@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
+@code{#+NAME: 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
@cindex code block, editing
@cindex source code, editing
+@vindex org-edit-src-auto-save-idle-delay
+@vindex org-edit-src-turn-on-auto-save
@kindex C-c '
-Use @kbd{C-c '} to edit the current code block. This brings up
-a language major-mode edit buffer containing the body of the code
-block. Saving this buffer will write the new contents back to the Org
-buffer. Use @kbd{C-c '} again to exit.
+Use @kbd{C-c '} to edit the current code block. This brings up a language
+major-mode edit buffer containing the body of the code block. Manually
+saving this buffer with @key{C-x C-s} will write the contents back to the Org
+buffer. You can also set @code{org-edit-src-auto-save-idle-delay} to save the
+base buffer after some idle delay, or @code{org-edit-src-turn-on-auto-save}
+to auto-save this buffer into a separate file using @code{auto-save-mode}.
+Use @kbd{C-c '} again to exit.
The @code{org-src-mode} minor mode will be active in the edit buffer. The
following variables can be used to configure the behavior of the edit
Python, in which whitespace indentation in the output is critical.
@item org-src-ask-before-returning-to-edit-buffer
By default, Org will ask before returning to an open edit buffer. Set this
-variable to nil to switch without asking.
+variable to @code{nil} to switch without asking.
@end table
To turn on native code fontification in the @emph{Org} buffer, configure the
behavior:
@subsubheading Header arguments:
+
@table @code
@item :exports code
The default in most languages. The body of the code block is exported, as
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
-markup language for a wiki.
+markup language for a wiki. It is also possible to set this variable to
+@code{‘inline-only}. In that case, only inline code blocks will be
+evaluated, in order to insert their results. Non-inline code blocks are
+assumed to have their results already inserted in the buffer by manual
+evaluation. This setting is useful to avoid expensive recalculations during
+export, not to provide security.
@comment node-name, next, previous, up
@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
``noweb'' style references (see @ref{Noweb reference syntax}).
@subsubheading Header arguments
+
@table @code
@item :tangle no
The default. The code block is not included in the tangled output.
@kindex C-c C-v t
@subsubheading Functions
+
@table @code
@item org-babel-tangle
Tangle the current file. Bound to @kbd{C-c C-v t}.
+
+With prefix argument only tangle the current code block.
@item org-babel-tangle-file
Choose a file to tangle. Bound to @kbd{C-c C-v f}.
@end table
@subsubheading Hooks
+
@table @code
@item org-babel-post-tangle-hook
This hook is run from within code files tangled by @code{org-babel-tangle}.
of tangled code files.
@end table
+@subsubheading Jumping between code and Org
+
+When tangling code from an Org-mode buffer to a source code file, you'll
+frequently find yourself viewing the file of tangled source code (e.g., many
+debuggers point to lines of the source code file). It is useful to be able
+to navigate from the tangled source to the Org-mode buffer from which the
+code originated.
+
+The @code{org-babel-tangle-jump-to-org} function provides this jumping from
+code to Org-mode functionality. Two header arguments are required for
+jumping to work, first the @code{padline} (@ref{padline}) option must be set
+to true (the default setting), second the @code{comments} (@ref{comments})
+header argument must be set to @code{links}, which will insert comments into
+the source code buffer which point back to the original Org-mode file.
+
@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code
@section Evaluating code blocks
@cindex code block, evaluating
@kindex C-c C-c
There are a number of ways to evaluate code blocks. The simplest is to press
@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The
-@code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code
+option @code{org-babel-no-eval-on-ctrl-c-ctrl-c} 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.
available, it can be found at
@uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
-The @code{org-babel-load-languages} controls which languages are enabled for
-evaluation (by default only @code{emacs-lisp} is enabled). This variable can
-be set using the customization interface or by adding code like the following
-to your emacs configuration.
+The option @code{org-babel-load-languages} controls which languages are
+enabled for evaluation (by default only @code{emacs-lisp} is enabled). This
+variable can be set using the customization interface or by adding code like
+the following to your emacs configuration.
@quotation
The following disables @code{emacs-lisp} evaluation and enables evaluation of
@node Using header arguments, Specific header arguments, Header arguments, Header arguments
@subsection Using header arguments
-The values of header arguments can be set in six different ways, each more
-specific (and having higher priority) than the last.
+The values of header arguments can be set in several way. When the header
+arguments in each layer have been determined, they are combined in order from
+the first, least specific (having the lowest priority) up to the last, most
+specific (having the highest priority). A header argument with a higher
+priority replaces the same header argument specified at lower priority.
@menu
* 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
+* Language-specific header arguments in Org mode properties:: Set language-specific 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
@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments
@subsubheading System-wide header arguments
@vindex org-babel-default-header-args
-System-wide values of header arguments can be specified by customizing the
+System-wide values of header arguments can be specified by adapting the
@code{org-babel-default-header-args} variable:
@example
:noweb => "no"
@end example
-@c @example
-@c org-babel-default-header-args is a variable defined in `org-babel.el'.
-@c Its value is
-@c ((:session . "none")
-@c (:results . "replace")
-@c (:exports . "code")
-@c (:cache . "no")
-@c (:noweb . "no"))
-
-
-@c Documentation:
-@c Default arguments to use when evaluating a code block.
-@c @end example
-
For example, the following example could be used to set the default value of
@code{:noweb} header arguments to @code{yes}. This would have the effect of
expanding @code{:noweb} references by default when evaluating source code
@lisp
(setq org-babel-default-header-args
(cons '(:noweb . "yes")
- (assq-delete-all :noweb org-babel-default-header-args)))
+ (assq-delete-all :noweb org-babel-default-header-args)))
@end lisp
-@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments
+@node Language-specific header arguments, Header arguments in Org mode properties, System-wide header arguments, Using header arguments
@subsubheading Language-specific header arguments
-Each language can define its own set of default header arguments. See the
-language-specific documentation available online at
+Each language can define its own set of default header arguments in variable
+@code{org-babel-default-header-args:<lang>}, where @code{<lang>} is the name
+of the language. See the 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
-@subsubheading Buffer-wide header arguments
+@node Header arguments in Org mode properties, Language-specific header arguments in Org mode properties, Language-specific header arguments, Using header arguments
+@subsubheading Header arguments in Org mode properties
+
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
-that all execution took place in the same session, and no results would be
-inserted into the buffer.
+For example the following would set @code{session} to @code{*R*} (only for R
+code blocks), and @code{results} to @code{silent} for every code block in the
+buffer, ensuring that all execution took place in the same session, and no
+results would be inserted into the buffer.
@example
-#+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
-
-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: header-args:R :session *R*
+#+PROPERTY: header-args :results silent
@end example
+Header arguments read from Org mode properties can also be set on a
+per-subtree basis using property drawers (see @ref{Property syntax}).
@vindex org-use-property-inheritance
-When properties are used to set default header arguments, they are looked up
-with inheritance, regardless of the value of
-@code{org-use-property-inheritance}. In the following example the value of
+When properties are used to set default header arguments, they are always
+looked up with inheritance, regardless of the value of
+@code{org-use-property-inheritance}. Properties are evaluated as seen by the
+outermost call or source block.@footnote{The deprecated syntax for default
+header argument properties, using the name of the header argument as a
+property name directly, evaluates the property as seen by the corresponding
+source block definition. This behaviour has been kept for backwards
+compatibility.}
+
+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:
- :cache: yes
+ :header-args: :cache yes
:END:
@end example
@kindex C-c C-x p
@vindex org-babel-default-header-args
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.
+@code{org-babel-default-header-args} and are applied for all activated
+languages. 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.
+
+@node Language-specific header arguments in Org mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments
+@subsubheading Language-specific header arguments in Org mode properties
+
+Language-specific header arguments are also read from properties
+@code{header-args:<lang>} where @code{<lang>} is the name of the language
+targeted. As an example
+
+@example
+* Heading
+ :PROPERTIES:
+ :header-args:clojure: :session *clojure-1*
+ :header-args:R: :session *R*
+ :END:
+** Subheading
+ :PROPERTIES:
+ :header-args:clojure: :session *clojure-2*
+ :END:
+@end example
+
+would independently set a default session header argument for R and clojure
+for calls and source blocks under subtree ``Heading'' and change to a
+different clojure setting for evaluations under subtree ``Subheading'', while
+the R session is inherited from ``Heading'' and therefore unchanged.
-@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, Language-specific 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
* colnames:: Handle column names in tables
* rownames:: Handle row names in tables
* shebang:: Make tangled files executable
+* tangle-mode:: Set permission of tangled files
* eval:: Limit evaluation of specific code blocks
* wrap:: Mark source block evaluation results
+* post:: Post processing of code block results
+* prologue:: Text to prepend to code block body
+* epilogue:: Text to append to code block body
@end menu
Additional header arguments are defined on a language-specific basis, see
case, variables require a default value when they are declared.
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.
+Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}).
+References include anything in the Org mode file that takes a @code{#+NAME:}
+or @code{#+RESULTS:} line: tables, lists, @code{#+BEGIN_EXAMPLE} blocks,
+other code blocks and the results of other code blocks.
+
+Note: When a reference is made to another code block, the referenced block
+will be evaluated unless it has current cached results (see @ref{cache}).
Argument values can be indexed in a manner similar to arrays (see @ref{var,
Indexable variable values}).
@table @dfn
@item table
-an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line
+an Org mode table named with either a @code{#+NAME:} line
@example
-#+TBLNAME: example-table
+#+NAME: example-table
| 1 |
| 2 |
| 3 |
@end table
-@subsubheading Alternate argument syntax
-It is also possible to specify arguments in a potentially more natural way
-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
-#+NAME: double(input=0, x=2)
-#+BEGIN_SRC emacs-lisp
-(* 2 (+ input x))
-#+END_SRC
-@end example
-
@subsubheading Indexable variable values
It is possible to reference portions of variable values by ``indexing'' into
the variables. Indexes are 0 based with negative values counting back from
@node results, file, var, Specific header arguments
@subsubsection @code{:results}
-There are three classes of @code{:results} header argument. Only one option
+There are four classes of @code{:results} header argument. Only one option
per class may be supplied per code block.
@itemize @bullet
from the code block
@item
@b{type} header arguments specify what type of result the code block will
+return---which has implications for how they will be processed before
+insertion into the Org mode buffer
+@item
+@b{format} 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
@item
@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}.
+@end itemize
+
+@subsubheading Format
+
+The following options are mutually exclusive and specify what type of results
+the code block will return. By default, results are inserted according to the
+type as specified above.
+
+@itemize @bullet
@item @code{raw}
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
output file, @code{:dir} specifies the default directory during code block
execution. If it is absent, then the directory associated with the current
buffer is used. In other words, supplying @code{:dir path} temporarily has
-the same effect as changing the current directory with @kbd{M-x cd path}, and
+the same effect as changing the current directory with @kbd{M-x cd path RET}, and
then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets
the value of the Emacs variable @code{default-directory}.
A synonym for ``link'' to maintain backwards compatibility.
@item @code{org}
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.
@item @code{both}
@item @code{strip-export}
``Noweb'' syntax references in the body of the code block will be expanded
before the block is evaluated or tangled. However, ``noweb'' syntax
-references will not be removed when the code block is exported.
+references will be removed when the code block is exported.
@item @code{eval}
``Noweb'' syntax references in the body of the code block will only be
expanded before the block is evaluated.
default value yields the following results.
@example
-#+TBLNAME: many-cols
+#+NAME: many-cols
| a | b | c |
|---+---+---|
| d | e | f |
Leaves hlines in the table. Setting @code{:hlines yes} has this effect.
@example
-#+TBLNAME: many-cols
+#+NAME: many-cols
| a | b | c |
|---+---+---|
| d | e | f |
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.
+across languages.
@itemize @bullet
@item @code{nil}
processing, then reapplied to the results.
@example
-#+TBLNAME: less-cols
+#+NAME: less-cols
| a |
|---|
| b |
@node rownames, shebang, colnames, Specific header arguments
@subsubsection @code{:rownames}
-The @code{:rownames} header argument can take on the values @code{yes}
-or @code{no}, with a default value of @code{no}.
+The @code{:rownames} header argument can take on the values @code{yes} or
+@code{no}, with a default value of @code{no}. Note that Emacs Lisp code
+blocks ignore the @code{:rownames} header argument entirely given the ease
+with which tables with row names may be handled directly in Emacs Lisp.
@itemize @bullet
@item @code{no}
and is then reapplied to the results.
@example
-#+TBLNAME: with-rownames
+#+NAME: with-rownames
| one | 1 | 2 | 3 | 4 | 5 |
| two | 6 | 7 | 8 | 9 | 10 |
@end itemize
-@node shebang, eval, rownames, Specific header arguments
+@node shebang, tangle-mode, rownames, Specific header arguments
@subsubsection @code{:shebang}
Setting the @code{:shebang} header argument to a string value
first line of any tangled file holding the code block, and the file
permissions of the tangled file are set to make it executable.
-@node eval, wrap, shebang, Specific header arguments
+
+@node tangle-mode, eval, shebang, Specific header arguments
+@subsubsection @code{:tangle-mode}
+
+The @code{tangle-mode} header argument controls the permission set on tangled
+files. The value of this header argument will be passed to
+@code{set-file-modes}. For example, to set a tangled file as read only use
+@code{:tangle-mode (identity #o444)}, or to set a tangled file as executable
+use @code{:tangle-mode (identity #o755)}. Blocks with @code{shebang}
+(@ref{shebang}) header arguments will automatically be made executable unless
+the @code{tangle-mode} header argument is also used. The behavior is
+undefined if multiple code blocks with different values for the
+@code{tangle-mode} header argument are tangled to the same file.
+
+@node eval, wrap, tangle-mode, Specific header arguments
@subsubsection @code{:eval}
The @code{:eval} header argument can be used to limit the evaluation of
specific code blocks. The @code{:eval} header argument can be useful for
of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation
security}.
-@node wrap, , eval, Specific header arguments
+@node wrap, post, eval, Specific header arguments
@subsubsection @code{:wrap}
The @code{:wrap} header argument is used to mark the results of source block
evaluation. The header argument can be passed a string that will be appended
results. If not string is specified then the results will be wrapped in a
@code{#+BEGIN/END_RESULTS} block.
+@node post, prologue, wrap, Specific header arguments
+@subsubsection @code{:post}
+The @code{:post} header argument is used to post-process the results of a
+code block execution. When a post argument is given, the results of the code
+block will temporarily be bound to the @code{*this*} variable. This variable
+may then be included in header argument forms such as those used in @ref{var}
+header argument specifications allowing passing of results to other code
+blocks, or direct execution via Emacs Lisp.
+
+The following example illustrates the usage of the @code{:post} header
+argument.
+
+@example
+#+name: attr_wrap
+#+begin_src sh :var data="" :var width="\\textwidth" :results output
+ echo "#+ATTR_LATEX :width $width"
+ echo "$data"
+#+end_src
+
+#+header: :file /tmp/it.png
+#+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer
+ digraph@{
+ a -> b;
+ b -> c;
+ c -> a;
+ @}
+#+end_src
+
+#+RESULTS:
+:RESULTS:
+#+ATTR_LATEX :width 5cm
+[[file:/tmp/it.png]]
+:END:
+@end example
+
+@node prologue, epilogue, post, Specific header arguments
+@subsubsection @code{:prologue}
+The value of the @code{prologue} header argument will be prepended to the
+code block body before execution. For example, @code{:prologue "reset"} may
+be used to reset a gnuplot session before execution of a particular code
+block, or the following configuration may be used to do this for all gnuplot
+code blocks. Also see @ref{epilogue}.
+
+@lisp
+(add-to-list 'org-babel-default-header-args:gnuplot
+ '((:prologue . "reset")))
+@end lisp
+
+@node epilogue, , prologue, Specific header arguments
+@subsubsection @code{:epilogue}
+The value of the @code{epilogue} header argument will be appended to the code
+block body before execution. Also see @ref{prologue}.
+
@node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code
@section Results of evaluation
@cindex code block, results of evaluation
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.
+@code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}.
This will result in faster noweb reference resolution at the expense of not
correctly resolving inherited values of the @code{:noweb-ref} header
argument.
* Clean view:: Getting rid of leading stars in the outline
* TTY keys:: Using Org on a tty
* Interaction:: Other Emacs packages
-* org-crypt.el:: Encrypting Org files
+* org-crypt:: Encrypting Org files
@end menu
@defopt org-confirm-babel-evaluate
When t (the default), the user is asked before every code block evaluation.
-When nil, the user is not asked. When set to a function, it is called with
+When @code{nil}, the user is not asked. When set to a function, it is called with
two arguments (language and body of the code block) and should return t to
-ask and nil not to ask.
+ask and @code{nil} not to ask.
@end defopt
For example, here is how to execute "ditaa" code (which is considered safe)
without asking:
-@example
+@lisp
(defun my-org-confirm-babel-evaluate (lang body)
(not (string= lang "ditaa"))) ; don't ask for ditaa
(setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
-@end example
+@end lisp
@item Following @code{shell} and @code{elisp} links
Org has two link types that can directly evaluate code (@pxref{External
There are more than 500 variables that can be used to customize
Org. For the sake of compactness of the manual, I am not
describing the variables here. A structured overview of customization
-variables is available with @kbd{M-x org-customize}. Or select
+variables is available with @kbd{M-x org-customize RET}. Or select
@code{Browse Org Group} from the @code{Org->Customization} menu. Many
settings can also be activated on a per-file basis, by putting special
lines into the buffer (@pxref{In-buffer settings}).
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:
+@cindex #+STARTUP
This line sets options to be used at startup of Org mode, when an
Org file is being visited.
noinlineimages @r{don't show inline images on startup}
@end example
+@vindex org-startup-with-latex-preview
+When visiting a file, @LaTeX{} fragments can be converted to images
+automatically. The variable @code{org-startup-with-latex-preview} which
+controls this behavior, is set to @code{nil} by default to avoid delays on
+startup.
+@cindex @code{latexpreview}, STARTUP keyword
+@cindex @code{nolatexpreview}, STARTUP keyword
+@example
+latexpreview @r{preview @LaTeX{} fragments}
+nolatexpreview @r{don't preview @LaTeX{} fragments}
+@end example
+
@vindex org-log-done
@vindex org-log-note-clock-out
@vindex org-log-repeat
@cindex @code{logrefile}, STARTUP keyword
@cindex @code{lognoterefile}, STARTUP keyword
@cindex @code{nologrefile}, STARTUP keyword
-@example
-logdone @r{record a timestamp when an item is marked DONE}
-lognotedone @r{record timestamp and a note when DONE}
-nologdone @r{don't record when items are marked DONE}
-logrepeat @r{record a time when reinstating a repeating item}
-lognoterepeat @r{record a note when reinstating a repeating item}
-nologrepeat @r{do not record when reinstating repeating item}
-lognoteclock-out @r{record a note when clocking out}
-nolognoteclock-out @r{don't record a note when clocking out}
-logreschedule @r{record a timestamp when scheduling time changes}
-lognotereschedule @r{record a note when scheduling time changes}
-nologreschedule @r{do not record when a scheduling date changes}
-logredeadline @r{record a timestamp when deadline changes}
-lognoteredeadline @r{record a note when deadline changes}
-nologredeadline @r{do not record when a deadline date changes}
-logrefile @r{record a timestamp when refiling}
-lognoterefile @r{record a note when refiling}
-nologrefile @r{do not record when refiling}
+@cindex @code{logdrawer}, STARTUP keyword
+@cindex @code{nologdrawer}, STARTUP keyword
+@cindex @code{logstatesreversed}, STARTUP keyword
+@cindex @code{nologstatesreversed}, STARTUP keyword
+@example
+logdone @r{record a timestamp when an item is marked DONE}
+lognotedone @r{record timestamp and a note when DONE}
+nologdone @r{don't record when items are marked DONE}
+logrepeat @r{record a time when reinstating a repeating item}
+lognoterepeat @r{record a note when reinstating a repeating item}
+nologrepeat @r{do not record when reinstating repeating item}
+lognoteclock-out @r{record a note when clocking out}
+nolognoteclock-out @r{don't record a note when clocking out}
+logreschedule @r{record a timestamp when scheduling time changes}
+lognotereschedule @r{record a note when scheduling time changes}
+nologreschedule @r{do not record when a scheduling date changes}
+logredeadline @r{record a timestamp when deadline changes}
+lognoteredeadline @r{record a note when deadline changes}
+nologredeadline @r{do not record when a deadline date changes}
+logrefile @r{record a timestamp when refiling}
+lognoterefile @r{record a note when refiling}
+nologrefile @r{do not record when refiling}
+logdrawer @r{store log into drawer}
+nologdrawer @r{store log outside of drawer}
+logstatesreversed @r{reverse the order of states notes}
+nologstatesreversed @r{do not reverse the order of states notes}
@end example
+
@vindex org-hide-leading-stars
@vindex org-odd-levels-only
Here are the options for hiding leading stars in outline headings, and for
odd @r{allow only odd outline levels (1,3,...)}
oddeven @r{allow all outline levels}
@end example
+
@vindex org-put-time-stamp-overlays
@vindex org-time-stamp-overlay-formats
To turn on custom format overlays over timestamps (variables
@example
customtime @r{overlay custom time format}
@end example
+
@vindex constants-unit-system
The following options influence the table spreadsheet (variable
@code{constants-unit-system}).
constcgs @r{@file{constants.el} should use the c-g-s unit system}
constSI @r{@file{constants.el} should use the SI unit system}
@end example
+
@vindex org-footnote-define-inline
@vindex org-footnote-auto-label
@vindex org-footnote-auto-adjust
fnadjust @r{automatically renumber and sort footnotes}
nofnadjust @r{do not renumber and sort automatically}
@end example
+
@cindex org-hide-block-startup
To hide blocks on startup, use these keywords. The corresponding variable is
@code{org-hide-block-startup}.
hideblocks @r{Hide all begin/end blocks on startup}
nohideblocks @r{Do not hide blocks on startup}
@end example
+
@cindex org-pretty-entities
The display of entities as UTF-8 characters is governed by the variable
@code{org-pretty-entities} and the keywords
entitiespretty @r{Show entities as UTF-8 characters where possible}
entitiesplain @r{Leave entities plain}
@end example
+
@item #+TAGS: TAG1(c1) TAG2(c2)
@vindex org-tag-alist
These lines (several such lines are allowed) specify the valid tags in
this file, and (potentially) the corresponding @emph{fast tag selection}
keys. The corresponding variable is @code{org-tag-alist}.
+@cindex #+TBLFM
@item #+TBLFM:
This line contains the formulas for the table directly above the line.
-@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,
-@itemx #+OPTIONS:, #+BIND:, #+XSLT:,
+
+Table can have multiple lines containing @samp{#+TBLFM:}. Note
+that only the first line of @samp{#+TBLFM:} will be applied when
+you recalculate the table. For more details see @ref{Using
+multiple #+TBLFM lines} in @ref{Editing and debugging formulas}.
+
+@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
+@itemx #+OPTIONS:, #+BIND:,
@itemx #+DESCRIPTION:, #+KEYWORDS:,
-@itemx #+LaTeX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,
-@itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:
+@itemx #+LaTeX_HEADER:, #+LaTeX_HEADER_EXTRA:,
+@itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
+@itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
These lines provide settings for exporting files. For more details see
-@ref{Export options}.
+@ref{Export settings}.
@item #+TODO: #+SEQ_TODO: #+TYP_TODO:
@vindex org-todo-keywords
These lines set the TODO keywords and their interpretation in the
drawer, offer property commands.
@item
If the cursor is at a footnote reference, go to the corresponding
-definition, and vice versa.
+definition, and @emph{vice versa}.
@item
If the cursor is on a statistics cookie, update it.
@item
@end multitable
-@node Interaction, org-crypt.el, TTY keys, Miscellaneous
+@node Interaction, org-crypt, TTY keys, Miscellaneous
@section Interaction with other packages
@cindex packages, interaction with other
Org lives in the world of GNU Emacs and interacts in various ways
to have other replacement keys, look at the variable
@code{org-disputed-keys}.
+@item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org}
+@cindex @file{ecomplete.el}
+
+Ecomplete provides ``electric'' address completion in address header
+lines in message buffers. Sadly Orgtbl mode cuts ecompletes power
+supply: No completion happens when Orgtbl mode is enabled in message
+buffers while entering text in address header lines. If one wants to
+use ecomplete one should @emph{not} follow the advice to automagically
+turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but
+instead---after filling in the message headers---turn on Orgtbl mode
+manually when needed in the messages body.
+
@item @file{filladapt.el} by Kyle Jones
@cindex @file{filladapt.el}
@item @file{yasnippet.el}
@cindex @file{yasnippet.el}
-The way Org mode binds the TAB key (binding to @code{[tab]} instead of
+The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of
@code{"\t"}) overrules YASnippet's access to this key. The following code
fixed this problem:
@lisp
(add-hook 'org-mode-hook
(lambda ()
- (make-variable-buffer-local 'yas/trigger-key)
- (setq yas/trigger-key [tab])
- (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
- (define-key yas/keymap [tab] 'yas/next-field)))
+ (make-variable-buffer-local 'yas/trigger-key)
+ (setq yas/trigger-key [tab])
+ (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
+ (define-key yas/keymap [tab] 'yas/next-field)))
@end lisp
@item @file{windmove.el} by Hovav Shacham
(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
@end lisp
+
+
@end table
-@node org-crypt.el, , Interaction, Miscellaneous
+@node org-crypt, , Interaction, Miscellaneous
@section org-crypt.el
@cindex @file{org-crypt.el}
@cindex @code{org-decrypt-entry}
To use org-crypt it is suggested that you have the following in your
@file{.emacs}:
-@example
+@lisp
(require 'org-crypt)
(org-crypt-use-before-save-magic)
(setq org-tags-exclude-from-inheritance (quote ("crypt")))
;; To turn it off only locally, you can insert this:
;;
;; # -*- buffer-auto-save-file-name: nil; -*-
-@end example
+@end lisp
Excluding the crypt tag from inheritance prevents already encrypted text
being encrypted again.
* Hooks:: How to reach into Org's internals
* Add-on packages:: Available extensions
* Adding hyperlink types:: New custom link types
+* Adding export back-ends:: How to write new export back-ends
* Context-sensitive commands:: How to add functionality to such commands
* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
-* Extracting agenda information:: Postprocessing of agenda information
+* Speeding up your agendas:: Tips on how to speed up your agendas
+* Extracting agenda information:: Post-processing of agenda information
* Using the property API:: Writing programs that use entry properties
* Using the mapping API:: Mapping over all or selected entries
@end menu
@cindex add-on packages
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
-@uref{http://orgmode.org}. The list of contributed packages, along with
-documentation about each package, is maintained by the Worg project at
+packages with the separate release available at @uref{http://orgmode.org}.
+See the @file{contrib/README} file in the source code directory for a list of
+contributed files. You may also find some more information on the Worg page:
@uref{http://orgmode.org/worg/org-contrib/}.
-
-
-@node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking
+@node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking
@section Adding hyperlink types
@cindex hyperlinks, adding new types
support for inserting such a link with @kbd{C-c C-l}. Such a function should
not accept any arguments, and return the full link with prefix.
-@node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking
+@node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking
+@section Adding export back-ends
+@cindex Export, writing back-ends
+
+Org 8.0 comes with a completely rewritten export engine which makes it easy
+to write new export back-ends, either from scratch, or from deriving them
+from existing ones.
+
+Your two entry points are respectively @code{org-export-define-backend} and
+@code{org-export-define-derived-backend}. To grok these functions, you
+should first have a look at @file{ox-latex.el} (for how to define a new
+back-end from scratch) and @file{ox-beamer.el} (for how to derive a new
+back-end from an existing one.
+
+When creating a new back-end from scratch, the basic idea is to set the name
+of the back-end (as a symbol) and an an alist of elements and export
+functions. On top of this, you will need to set additional keywords like
+@code{:menu-entry} (to display the back-end in the export dispatcher),
+@code{:export-block} (to specify what blocks should not be exported by this
+back-end), and @code{:options-alist} (to let the user set export options that
+are specific to this back-end.)
+
+Deriving a new back-end is similar, except that you need to set
+@code{:translate-alist} to an alist of export functions that should be used
+instead of the parent back-end functions.
+
+For a complete reference documentation, see
+@url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
+Reference on Worg}.
+
+@node Context-sensitive commands, Tables in arbitrary syntax, Adding export back-ends, Hacking
@section Context-sensitive commands
@cindex context-sensitive commands, hooks
@cindex add-ons, context-sensitive commands
* Radio tables:: Sending and receiving radio tables
* A @LaTeX{} example:: Step by step, almost a tutorial
* Translator functions:: Copy and modify
-* Radio lists:: Doing the same for lists
+* Radio lists:: Sending and receiving lists
@end menu
@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax
@cindex radio tables
To define the location of the target table, you first need to create two
-lines that are comments in the current mode, but contain magic words for
-Orgtbl mode to find. Orgtbl mode will insert the translated table
-between these lines, replacing whatever was there before. For example:
+lines that are comments in the current mode, but contain magic words
+@code{BEGIN/END RECEIVE ORGTBL} for Orgtbl mode to find. Orgtbl mode will
+insert the translated table between these lines, replacing whatever was there
+before. For example in C mode where comments are between @code{/* ... */}:
@example
/* BEGIN RECEIVE ORGTBL table_name */
additional columns.
@item :no-escape t
-When non-nil, do not escape special characters @code{&%#_^} when exporting
-the table. The default value is nil.
+When non-@code{nil}, do not escape special characters @code{&%#_^} when exporting
+the table. The default value is @code{nil}.
@end table
@noindent
@item
You can just comment the table line-by-line whenever you want to process
the file, and uncomment it whenever you need to edit the table. This
-only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment}
+only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment RET}
makes this comment-toggling very easy, in particular if you bind it to a
key.
@end itemize
activated by placing @code{\usepackage@{comment@}} into the document
header. Orgtbl mode can insert a radio table skeleton@footnote{By
default this works only for @LaTeX{}, HTML, and Texinfo. Configure the
-variable @code{orgtbl-radio-tables} to install templates for other
-modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will
+variable @code{orgtbl-radio-table-templates} to install templates for other
+modes.} with the command @kbd{M-x orgtbl-insert-radio-table RET}. You will
be prompted for a table name, let's say we use @samp{salesfigures}. You
will then get the following template:
@table @code
@item :splice nil/t
When set to t, return only table body lines, don't wrap them into a
-tabular environment. Default is nil.
+tabular environment. Default is @code{nil}.
@item :fmt fmt
A format to be used to wrap each field, it should contain @code{%s} for the
(defun org-dblock-write:block-update-time (params)
(let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
(insert "Last block update at: "
- (format-time-string fmt (current-time)))))
+ (format-time-string fmt (current-time)))))
@end lisp
If you want to make sure that all dynamic blocks are always up-to-date,
You can narrow the current buffer to the current dynamic block (like any
other block) with @code{org-narrow-to-block}.
-@node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking
+@node Special agenda views, Speeding up your agendas, Dynamic blocks, Hacking
@section Special agenda views
@cindex agenda views, user-defined
@vindex org-agenda-skip-function
@vindex org-agenda-skip-function-global
Org provides a special hook that can be used to narrow down the selection
-made by these agenda views: @code{agenda}, @code{todo}, @code{alltodo},
-@code{tags}, @code{tags-todo}, @code{tags-tree}. You may specify a function
-that is used at each match to verify if the match should indeed be part of
-the agenda view, and if not, how much should be skipped. You can specify a
-global condition that will be applied to all agenda views, this condition
-would be stored in the variable @code{org-agenda-skip-function-global}. More
-commonly, such a definition is applied only to specific custom searches,
-using @code{org-agenda-skip-function}.
+made by these agenda views: @code{agenda}, @code{agenda*}@footnote{The
+@code{agenda*} view is the same than @code{agenda} except that it only
+considers @emph{appointments}, i.e., scheduled and deadline items that have a
+time specification @code{[h]h:mm} in their time-stamps.}, @code{todo},
+@code{alltodo}, @code{tags}, @code{tags-todo}, @code{tags-tree}. You may
+specify a function that is used at each match to verify if the match should
+indeed be part of the agenda view, and if not, how much should be skipped.
+You can specify a global condition that will be applied to all agenda views,
+this condition would be stored in the variable
+@code{org-agenda-skip-function-global}. More commonly, such a definition is
+applied only to specific custom searches, using
+@code{org-agenda-skip-function}.
Let's say you want to produce a list of projects that contain a WAITING
tag anywhere in the project tree. Let's further assume that you have
(org-agenda-overriding-header "Projects waiting for something: "))))
@end lisp
-@node Extracting agenda information, Using the property API, Special agenda views, Hacking
+@node Speeding up your agendas, Extracting agenda information, Special agenda views, Hacking
+@section Speeding up your agendas
+@cindex agenda views, optimization
+
+When your Org files grow in both number and size, agenda commands may start
+to become slow. Below are some tips on how to speed up the agenda commands.
+
+@enumerate
+@item
+Reduce the number of Org agenda files: this will reduce the slowliness caused
+by accessing to a hard drive.
+@item
+Reduce the number of DONE and archived headlines: this way the agenda does
+not need to skip them.
+@item
+@vindex org-agenda-dim-blocked-tasks
+Inhibit the dimming of blocked tasks:
+@lisp
+(setq org-agenda-dim-blocked-tasks nil)
+@end lisp
+@item
+@vindex org-startup-folded
+@vindex org-agenda-inhibit-startup
+Inhibit agenda files startup options:
+@lisp
+(setq org-agenda-inhibit-startup nil)
+@end lisp
+@item
+@vindex org-agenda-show-inherited-tags
+@vindex org-agenda-use-tag-inheritance
+Disable tag inheritance in agenda:
+@lisp
+(setq org-agenda-use-tag-inheritance nil)
+@end lisp
+@end enumerate
+
+You can set these options for specific agenda views only. See the docstrings
+of these variables for details on why they affect the agenda generation, and
+this @uref{http://orgmode.org/worg/agenda-optimization.html, dedicated Worg
+page} for further explanations.
+
+@node Extracting agenda information, Using the property API, Speeding up your agendas, Hacking
@section Extracting agenda information
@cindex agenda, pipe
@cindex Scripts, for agenda processing
scheduled, and clocking, and any additional properties defined in the
entry. The return value is an alist. Keys may occur multiple times
if the property key was used several times.@*
-POM may also be nil, in which case the current entry is used.
-If WHICH is nil or `all', get all properties. If WHICH is
+POM may also be @code{nil}, in which case the current entry is used.
+If WHICH is @code{nil} or `all', get all properties. If WHICH is
`special' or `standard', only get that subclass.
@end defun
@vindex org-use-property-inheritance
@findex org-insert-property-drawer
@defun org-entry-get pom property &optional inherit
-Get value of PROPERTY for entry at point-or-marker POM@. By default,
-this only looks at properties defined locally in the entry. If INHERIT
-is non-nil and the entry does not have the property, then also check
-higher levels of the hierarchy. If INHERIT is the symbol
+Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By default,
+this only looks at properties defined locally in the entry. If @code{INHERIT}
+is non-@code{nil} and the entry does not have the property, then also check
+higher levels of the hierarchy. If @code{INHERIT} is the symbol
@code{selective}, use inheritance if and only if the setting of
-@code{org-use-property-inheritance} selects PROPERTY for inheritance.
+@code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance.
@end defun
@defun org-entry-delete pom property
-Delete the property PROPERTY from entry at point-or-marker POM.
+Delete the property @code{PROPERTY} from entry at point-or-marker POM.
@end defun
@defun org-entry-put pom property value
-Set PROPERTY to VALUE for entry at point-or-marker POM.
+Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM.
@end defun
@defun org-buffer-property-keys &optional include-specials
@end defun
@defun org-entry-put-multivalued-property pom property &rest values
-Set PROPERTY at point-or-marker POM to VALUES@. VALUES should be a list of
-strings. They will be concatenated, with spaces as separators.
+Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@.
+@code{VALUES} should be a list of strings. They will be concatenated, with
+spaces as separators.
@end defun
@defun org-entry-get-multivalued-property pom property
-Treat the value of the property PROPERTY as a whitespace-separated list of
-values and return the values as a list of strings.
+Treat the value of the property @code{PROPERTY} as a whitespace-separated
+list of values and return the values as a list of strings.
@end defun
@defun org-entry-add-to-multivalued-property pom property value
-Treat the value of the property PROPERTY as a whitespace-separated list of
-values and make sure that VALUE is in this list.
+Treat the value of the property @code{PROPERTY} as a whitespace-separated
+list of values and make sure that @code{VALUE} is in this list.
@end defun
@defun org-entry-remove-from-multivalued-property pom property value
-Treat the value of the property PROPERTY as a whitespace-separated list of
-values and make sure that VALUE is @emph{not} in this list.
+Treat the value of the property @code{PROPERTY} as a whitespace-separated
+list of values and make sure that @code{VALUE} is @emph{not} in this list.
@end defun
@defun org-entry-member-in-multivalued-property pom property value
-Treat the value of the property PROPERTY as a whitespace-separated list of
-values and check if VALUE is in this list.
+Treat the value of the property @code{PROPERTY} as a whitespace-separated
+list of values and check if @code{VALUE} is in this list.
@end defun
@defopt org-property-allowed-value-functions
is:
@defun org-map-entries func &optional match scope &rest skip
-Call FUNC at each headline selected by MATCH in SCOPE.
+Call @code{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
-FUNC is a function or a Lisp form. The function will be called without
-arguments, with the cursor positioned at the beginning of the headline.
-The return values of all calls to the function will be collected and
-returned as a list.
+@code{FUNC} is a function or a Lisp form. The function will be called
+without arguments, with the cursor positioned at the beginning of the
+headline. The return values of all calls to the function will be collected
+and returned as a list.
-The call to FUNC will be wrapped into a save-excursion form, so FUNC
-does not need to preserve point. After evaluation, the cursor will be
-moved to the end of the line (presumably of the headline of the
-processed entry) and search continues from there. Under some
-circumstances, this may not produce the wanted results. For example,
-if you have removed (e.g., archived) the current (sub)tree it could
-mean that the next entry will be skipped entirely. In such cases, you
-can specify the position from where search should continue by making
-FUNC set the variable `org-map-continue-from' to the desired buffer
-position.
+The call to @code{FUNC} will be wrapped into a save-excursion form, so
+@code{FUNC} does not need to preserve point. After evaluation, the cursor
+will be moved to the end of the line (presumably of the headline of the
+processed entry) and search continues from there. Under some circumstances,
+this may not produce the wanted results. For example, if you have removed
+(e.g., archived) the current (sub)tree it could mean that the next entry will
+be skipped entirely. In such cases, you can specify the position from where
+search should continue by making @code{FUNC} set the variable
+@code{org-map-continue-from} to the desired buffer position.
-MATCH is a tags/property/todo match as it is used in the agenda match view.
-Only headlines that are matched by this query will be considered during
-the iteration. When MATCH is nil or t, all headlines will be
-visited by the iteration.
+@code{MATCH} is a tags/property/todo match as it is used in the agenda match
+view. Only headlines that are matched by this query will be considered
+during the iteration. When @code{MATCH} is @code{nil} or @code{t}, all
+headlines will be visited by the iteration.
-SCOPE determines the scope of this command. It can be any of:
+@code{SCOPE} determines the scope of this command. It can be any of:
@example
nil @r{the current buffer, respecting the restriction if any}
@defun org-todo &optional arg
Change the TODO state of the entry. See the docstring of the functions for
-the many possible values for the argument ARG.
+the many possible values for the argument @code{ARG}.
@end defun
@defun org-priority &optional action
Change the priority of the entry. See the docstring of this function for the
-possible values for ACTION.
+possible values for @code{ACTION}.
@end defun
@defun org-toggle-tag tag &optional onoff
-Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on}
-or @code{off} will not toggle tag, but ensure that it is either on or off.
+Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to
+either @code{on} or @code{off} will not toggle tag, but ensure that it is
+either on or off.
@end defun
@defun org-promote
@i{MobileOrg} is the name of the mobile companion app for Org mode, currently
available for iOS and for Android. @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.
-The @uref{http://mobileorg.ncogni.to/, iOS implementation} for the
-@i{iPhone/iPod Touch/iPad} series of devices, was developed by Richard
-Moreland. Android users should check out
+does also allow you to record changes to existing entries. The
+@uref{https://github.com/MobileOrg/, iOS implementation} for the
+@i{iPhone/iPod Touch/iPad} series of devices, was started by Richard Moreland
+and is now in the hands Sean Escriva. Android users should check out
@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
by Matt Jones. The two implementations are not identical but offer similar
features.
captured and changes made by @i{MobileOrg} into the main system.
For changing tags and TODO states in MobileOrg, you should have set up the
-customization variables @code{org-todo-keywords} and @code{org-tags-alist} to
+customization variables @code{org-todo-keywords} and @code{org-tag-alist} to
cover all important tags and TODO keywords, even if individual files use only
part of these. MobileOrg will also offer you states and tags set up with
in-buffer settings, but it will understand the logistics of TODO state
If a note has been stored while flagging an entry in @i{MobileOrg}, that note
will be displayed in the echo area when the cursor is on the corresponding
agenda line.
+
@table @kbd
@kindex ?
@item ?
@kindex C-c a ?
If you are not able to process all flagged entries directly, you can always
return to this agenda view@footnote{Note, however, that there is a subtle
-difference. The view created automatically by @kbd{M-x org-mobile-pull
-@key{RET}} is guaranteed to search all files that have been addressed by the
-last pull. This might include a file that is not currently in your list of
-agenda files. If you later use @kbd{C-c a ?} to regenerate the view, only
-the current agenda files will be searched.} using @kbd{C-c a ?}.
+difference. The view created automatically by @kbd{M-x org-mobile-pull RET}
+is guaranteed to search all files that have been addressed by the last pull.
+This might include a file that is not currently in your list of agenda files.
+If you later use @kbd{C-c a ?} to regenerate the view, only the current
+agenda files will be searched.} using @kbd{C-c a ?}.
@node History and Acknowledgments, GNU Free Documentation License, MobileOrg, Top
@appendix History and acknowledgments
Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
of an ignorant amateur. Sebastian has pushed this part of Org onto a much
higher level. He also wrote @file{org-info.js}, a Java script for displaying
-webpages derived from Org using an Info-like or a folding interface with
+web pages derived from Org using an Info-like or a folding interface with
single-key navigation.
@end table
to Carsten's ones above.
I am first grateful to Carsten for his trust while handing me over the
-maintainership of Org. His support as been great since day one of this new
-adventure, and it helped a lot.
+maintainership of Org. His unremitting support is what really helped me
+getting more confident over time, with both the community and the code.
When I took over maintainership, I knew I would have to make Org more
collaborative than ever, as I would have to rely on people that are more
from worrying about possible bugs here and let me focus on other parts.
@item Nicolas Goaziou
-Nicolas is maintaining the consistency of the deepest parts of Org. His work
-on @file{org-element.el} and @file{org-export.el} has been outstanding, and
-opened the doors for many new ideas and features.
-
-@item Jambunathan K
-Jambunathan contributed the ODT exporter, definitely a killer feature of
-Org mode. He also contributed the new HTML exporter, which is another core
-feature of Org. Here too, I knew I could rely on him to fix bugs in these
-areas and to patiently explain the users what was the problems and solutions.
+Nicolas is maintaining the consistency of the deepest parts of Org. His
+work on @file{org-element.el} and @file{ox.el} has been outstanding, and
+opened the doors for many new ideas and features. He rewrote many of the
+old exporters to use the new export engine, and helped with documenting
+this major change. More importantly (if that's possible), he has been more
+than reliable during all the work done for Org 8.0, and always very
+reactive on the mailing list.
@item Achim Gratz
Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
@item
@i{Russel Adams} came up with the idea for drawers.
@item
+@i{Suvayu Ali} has steadily helped on the mailing list, providing useful
+feedback on many features and several patches.
+@item
+@i{Luis Anaya} wrote @file{ox-man.el}.
+@item
@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
@item
+@i{Michael Brand} helped by reporting many bugs and testing many features.
+He also implemented the distinction between empty fields and 0-value fields
+in Org's spreadsheets.
+@item
@i{Christophe Bataillon} created the great unicorn logo that we use on the
Org mode website.
@item
@item
@i{Sacha Chua} suggested copying some linking code from Planner.
@item
-@i{Baoqiu Cui} contributed the DocBook exporter.
+@i{Toby S. Cubitt} contributed to the code for clock formats.
+@item
+@i{Baoqiu Cui} contributed the DocBook exporter. It has been deleted from
+Org 8.0: you can now export to Texinfo and export the @file{.texi} file to
+DocBook using @code{makeinfo}.
@item
@i{Eddward DeVilla} proposed and tested checkbox statistics. He also
came up with the idea of properties, and that there should be an API for
inspired some of the early development, including HTML export. He also
asked for a way to narrow wide table columns.
@item
+@i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
+several years now. He also sponsered the hosting costs until Rackspace
+started to host us for free.
+@item
@i{Thomas S. Dye} contributed documentation on Worg and helped integrating
the Org-Babel documentation into the manual.
@item
@i{Christian Egli} converted the documentation into Texinfo format, inspired
the agenda, patched CSS formatting into the HTML exporter, and wrote
-@file{org-taskjuggler.el}.
+@file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as
+@file{ox-taskjuggler.el} for Org 8.0.
@item
@i{David Emery} provided a patch for custom CSS support in exported
HTML agendas.
@item
+@i{Sean Escriva} took over MobileOrg development on the iPhone platform.
+@item
@i{Nic Ferrier} contributed mailcap and XOXO support.
@item
@i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
@item
@i{Niels Giesen} had the idea to automatically archive DONE trees.
@item
-@i{Nicolas Goaziou} rewrote much of the plain list code.
+@i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote
+@file{org-element.el} and @file{org-export.el}, which was a huge step forward
+in implementing a clean framework for Org exporters.
@item
@i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
@item
@item
@i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
@item
+@i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}.
+@item
@i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also
provided frequent feedback and some patches.
@item
@item
@i{Jason F. McBrayer} suggested agenda export to CSV format.
@item
-@i{Max Mikhanosha} came up with the idea of refiling.
+@i{Max Mikhanosha} came up with the idea of refiling and sticky agendas.
@item
@i{Dmitri Minaev} sent a patch to set priority limits on a per-file
basis.
@i{Pete Phillips} helped during the development of the TAGS feature, and
provided frequent feedback.
@item
+@i{Francesco Pizzolante} provided patches that helped speeding up the agenda
+generation.
+@item
@i{Martin Pohlack} provided the code snippet to bundle character insertion
into bundles of 20 for undo.
@item
+@i{Rackspace.com} is hosting our website for free. Thank you Rackspace!
+@item
@i{T.V. Raman} reported bugs and suggested improvements.
@item
@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
@i{Christian Schlauer} proposed angular brackets around links, among
other things.
@item
+@i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can
+enjoy folding in non-org buffers by using Org headlines in comments.
+@item
@i{Paul Sexton} wrote @file{org-ctags.el}.
@item
Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
chapter about publishing.
@item
-@i{Jambunathan K} contributed the ODT exporter.
+@i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter.
@item
@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
enabled source code highlighting in Gnus.