-
\input texinfo
@c %**start of header
@setfilename ../../info/org
@settitle The Org Manual
-
-@set VERSION 7.8.07
-@set DATE March 2012
+@set VERSION 8.2.5c
@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}
@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
+@documentencoding UTF-8
@c %**end of header
@finalout
@copying
This manual is for Org version @value{VERSION}.
-Copyright @copyright{} 2004-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2004--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+modify this GNU manual.''
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs editing modes
@direntry
-* Org Mode: (org). Outline-based notes management and organizer
+* Org Mode: (org). Outline-based notes management and organizer.
@end direntry
@titlepage
@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
@contents
@ifnottex
+@c FIXME These hand-written next,prev,up node pointers make editing a lot
+@c harder. There should be no need for them, makeinfo can do it
+@c automatically for any document with a normal structure.
@node Top, Introduction, (dir), (dir)
@top Org Mode Manual
* 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
* Hacking:: How to hack your way around
* MobileOrg:: Viewing and capture on a mobile device
* History and Acknowledgments:: How Org came into being
+* GNU Free Documentation License:: The license for this documentation.
* Main Index:: An index of Org's concepts and features
* Key Index:: Key bindings and where they are described
* Command and Function Index:: Command names and some internal functions
Introduction
* Summary:: Brief summary of what Org does
-* Installation:: How to install a downloaded version of Org
+* Installation:: Installing Org
* Activation:: How to activate Org for certain buffers
* Feedback:: Bug reports, ideas, patches etc.
-* Conventions:: Type-setting conventions in the manual
+* Conventions:: Typesetting conventions in the manual
Document structure
* 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
* Capture:: Capturing new stuff
* 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
+* Protocols:: External (e.g., Browser) access to Emacs and Org
+* Refile and copy:: Moving/copying a tree from one place to another
* Archiving:: What to do with finished projects
Capture
* Template elements:: What is needed for a complete template entry
* Template expansion:: Filling in information about time and context
+* Templates in contexts:: Only show a template in a specific context
Archiving
* 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
* Special symbols:: Greek letters and other symbols
* Subscripts and superscripts:: Simple syntax for raising/lowering text
-* @LaTeX{} fragments:: Complex formulas made easy
+* @LaTeX{} fragments:: Complex formulas made easy
* Previewing @LaTeX{} fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
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
+* Org export:: Exporting to Org
+* 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 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
* results:: Specify the type of results and how they will
be collected and handled
* file:: Specify a path for file output
+* file-desc:: Specify a description for file results
* dir:: Specify the default (possibly remote)
directory for code block execution
* exports:: Export code and/or results
* 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
Hacking
-* Hooks:: Who to reach into Org's internals
+* 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
@menu
* Summary:: Brief summary of what Org does
-* Installation:: How to install a downloaded version of Org
+* Installation:: Installing Org
* Activation:: How to activate Org for certain buffers
* Feedback:: Bug reports, ideas, patches etc.
-* Conventions:: Type-setting conventions in the manual
+* Conventions:: Typesetting conventions in the manual
@end menu
@node Summary, Installation, Introduction, Introduction
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
-
@cindex FAQ
There is a website for Org which provides links to the newest
version of Org, as well as additional information, frequently asked
-questions (FAQ), links to tutorials, etc@. This page is located at
+questions (FAQ), links to tutorials, etc. This page is located at
@uref{http://orgmode.org}.
@cindex print edition
@cindex installation
@cindex XEmacs
-@b{Important:} @i{If you are using a version of Org that is part of the Emacs
-distribution or an XEmacs package, please skip this section and go directly
-to @ref{Activation}. To see what version of Org (if any) is part of your
-Emacs distribution, type @kbd{M-x load-library RET org} and then @kbd{M-x
-org-version}.}
+Org is part of recent distributions of GNU Emacs, so you normally don't need
+to install it. If, for one reason or another, you want to install Org on top
+of this pre-packaged version, there are three ways to do it:
-If you have downloaded Org from the Web, either as a distribution @file{.zip}
-or @file{.tar} file, or as a Git archive, you must take the following steps
-to install it: go into the unpacked Org distribution directory and edit the
-top section of the file @file{Makefile}. You must set the name of the Emacs
-binary (likely either @file{emacs} or @file{xemacs}), and the paths to the
-directories where local Lisp and Info files are kept. If you don't have
-access to the system-wide directories, you can simply run Org directly from
-the distribution directory by adding the @file{lisp} subdirectory to the
-Emacs load path. To do this, add the following line to @file{.emacs}:
+@itemize @bullet
+@item By using Emacs package system.
+@item By downloading Org as an archive.
+@item By using Org's git repository.
+@end itemize
-@example
-(setq load-path (cons "~/path/to/orgdir/lisp" load-path))
-@end example
+We @b{strongly recommend} to stick to a single installation method.
-@noindent
-If you plan to use code from the @file{contrib} subdirectory, do a similar
-step for this directory:
+@subsubheading Using Emacs packaging system
-@example
-(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))
-@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}.
+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}.
-@noindent Now byte-compile the Lisp files with the shell command:
+@subsubheading Downloading Org as an archive
-@example
-make
-@end example
+You can download Org latest release from @uref{http://orgmode.org/, Org's
+website}. In this case, make sure you set the load-path correctly in your
+@file{.emacs}:
-@noindent If you are running Org from the distribution directory, this is
-all. If you want to install Org into the system directories, use (as
-administrator)
+@lisp
+(add-to-list 'load-path "~/path/to/orgdir/lisp")
+@end lisp
-@example
-make install
-@end example
+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:
-Installing Info files is system dependent, because of differences in the
-@file{install-info} program. The following should correctly install the Info
-files on most systems, please send a bug report if not@footnote{The output
-from install-info (if any) is also system dependent. In particular Debian
-and its derivatives use two different versions of install-info and you may
-see the message:
+@lisp
+(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
+@end lisp
-@example
-This is not dpkg install-info anymore, but GNU install-info
-See the man page for ginstall-info for command line arguments
-@end example
+Optionally, you can compile the files and/or install them in your system.
+Run @code{make help} to list compilation and installation options.
-@noindent which can be safely ignored.}.
+@subsubheading Using Org's git repository
+
+You can clone Org's repository and install Org like this:
@example
-make install-info
+$ cd ~/src/
+$ git clone git://orgmode.org/org-mode.git
+$ make autoloads
@end example
-Then add the following line to @file{.emacs}. It is needed so that
-Emacs can autoload functions that are located in files not immediately loaded
-when Org mode starts.
-@lisp
-(require 'org-install)
-@end lisp
+Note that in this case, @code{make autoloads} is mandatory: it defines Org's
+version in @file{org-version.el} and Org's autoloads in
+@file{org-loaddefs.el}.
-Do not forget to activate Org as described in the following section.
-@page
+Remember to add the correct load-path as described in the method above.
+
+You can also compile with @code{make}, generate the documentation with
+@code{make doc}, create a local configuration with @code{make config} and
+install Org with @code{make install}. Please run @code{make help} to get
+the list of compilation/installation options.
+
+For more detailed explanations on Org's build system, please check the Org
+Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
+Worg}.
@node Activation, Feedback, Installation, Introduction
@section Activation
@cindex activation
@cindex autoload
+@cindex ELPA
@cindex global key bindings
@cindex key bindings, global
+@findex org-agenda
+@findex org-capture
+@findex org-store-link
+@findex org-iswitchb
+
+Since Emacs 22.2, files with the @file{.org} extension use Org mode by
+default. If you are using an earlier version of Emacs, add this line to your
+@file{.emacs} file:
-To make sure files with extension @file{.org} use Org mode, add the following
-line to your @file{.emacs} file.
@lisp
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
@end lisp
-@noindent Org mode buffers need font-lock to be turned on - this is the
-default in Emacs@footnote{If you don't use font-lock globally, turn it on in
-Org buffer with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
+
+Org mode buffers need font-lock to be turned on: this is the default in
+Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
+with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
+
+There are compatibility issues between Org mode and some other Elisp
+packages, please take the time to check the list (@pxref{Conflicts}).
The four Org commands @command{org-store-link}, @command{org-capture},
@command{org-agenda}, and @command{org-iswitchb} should be accessible through
-global keys (i.e.@: anywhere in Emacs, not just in Org buffers). Here are
+global keys (i.e., anywhere in Emacs, not just in Org buffers). Here are
suggested bindings for these keys, please modify the keys to your own
liking.
@lisp
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
@end example
However if you are using Org mode as distributed with Emacs, a minimal setup
-is not necessary. In that case it is sufficient to start Emacs as @code{emacs
--Q}. The @code{minimal-org.el} setup file can have contents as shown below.
+is not necessary. In that case it is sufficient to start Emacs as
+@code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
+shown below.
-@example
+@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"))
-
-;; activate org
-(require 'org-install)
-@end example
+(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
+@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
@node Conventions, , Feedback, Introduction
@section Typesetting conventions used in this manual
-Org uses three types of keywords: TODO keywords, tags, and property
+@subsubheading TODO keywords, tags, properties, etc.
+
+Org mainly uses three types of keywords: TODO keywords, tags and property
names. In this manual we use the following conventions:
@table @code
special meaning are written with all capitals.
@end table
-The manual lists both the keys and the corresponding commands for accessing
-functionality. Org mode often uses the same key for different functions,
-depending on context. The command that is bound to such keys has a generic
-name, like @code{org-metaright}. In the manual we will, wherever possible,
-give the function that is internally called by the generic command. For
-example, in the chapter on document structure, @kbd{M-@key{right}} will be
-listed to call @code{org-do-demote}, while in the chapter on tables, it will
-be listed to call org-table-move-column-right.
-
-If you prefer, you can compile the manual without the command names by
-unsetting the flag @code{cmdnames} in @file{org.texi}.
+Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
+and @i{environment keywords} (like @code{#+BEGIN_HTML} to start a @code{HTML}
+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}.}.
+
+@subsubheading Keybindings and commands
+@kindex C-c a
+@findex org-agenda
+@kindex C-c c
+@findex org-capture
+
+The manual suggests two global keybindings: @kbd{C-c a} for @code{org-agenda}
+and @kbd{C-c c} for @code{org-capture}. These are only suggestions, but the
+rest of the manual assumes that you are using these keybindings.
+
+Also, the manual lists both the keys and the corresponding commands for
+accessing a functionality. Org mode often uses the same key for different
+functions, depending on context. The command that is bound to such keys has
+a generic name, like @code{org-metaright}. In the manual we will, wherever
+possible, give the function that is internally called by the generic command.
+For example, in the chapter on document structure, @kbd{M-@key{right}} will
+be listed to call @code{org-do-demote}, while in the chapter on tables, it
+will be listed to call @code{org-table-move-column-right}. If you prefer,
+you can compile the manual without the command names by unsetting the flag
+@code{cmdnames} in @file{org.texi}.
@node Document Structure, Tables, Introduction, Top
@chapter Document structure
* 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
start with one or more stars, on the left margin@footnote{See the variables
@code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
@code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
-@kbd{C-e}, and @kbd{C-k} in headlines.}. For example:
+@kbd{C-e}, and @kbd{C-k} in headlines.} @footnote{Clocking only works with
+headings indented less then 30 stars.}. For example:
@example
* Top level headline
@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.
CONTENTS view up to headlines of level N will be shown. Note that inside
tables, @kbd{S-@key{TAB}} jumps to the previous field.
+@cindex set startup visibility, command
+@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
+Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
@cindex show all, command
@orgcmd{C-u C-u C-u @key{TAB},show-all}
Show all, including drawers.
+@cindex revealing context
@orgcmd{C-c C-r,org-reveal}
Reveal context around point, showing the current entry, the following heading
and the hierarchy above. Useful for working near a location that has been
(@pxref{Agenda commands}). With a prefix argument show, on each
level, all sibling headings. With a double prefix argument, also show the
entire subtree of the parent.
+@cindex show branches, command
@orgcmd{C-c C-k,show-branches}
Expose all the headings of the subtree, CONTENT view for just one subtree.
+@cindex show children, command
+@orgcmd{C-c @key{TAB},show-children}
+Expose all direct children of the subtree. With a numeric prefix argument N,
+expose all children down to level N@.
@orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
Show the current subtree in an indirect buffer@footnote{The indirect
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{content}, 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
#+STARTUP: showeverything
@end example
+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 @code{nil}.
+
@cindex property, VISIBILITY
@noindent
Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
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
+Switch back to the startup visibility of the buffer, i.e., whatever is
requested by startup options and @samp{VISIBILITY} properties in individual
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
level).
@orgcmd{M-S-@key{down},org-move-subtree-down}
Move subtree down (swap with next subtree of same level).
+@orgcmd{M-h,org-mark-element}
+Mark the element at point. Hitting repeatedly will mark subsequent elements
+of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
+hitting @key{M-h} immediately again will mark the next one.
+@orgcmd{C-c @@,org-mark-subtree}
+Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
+of the same level than the marked subtree.
@orgcmd{C-c C-x C-w,org-cut-subtree}
-Kill subtree, i.e.@: remove it from buffer but save in kill ring.
+Kill subtree, i.e., remove it from buffer but save in kill ring.
With a numeric prefix argument N, kill N sequential subtrees.
@orgcmd{C-c C-x M-w,org-copy-subtree}
Copy subtree to kill ring. With a numeric prefix argument N, copy the N
@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}.
-@orgcmd{C-c ^,org-sort-entries-or-items}
+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
sorted. The command prompts for the sorting method, which can be
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 to start with a different value (e.g., 20), start the text of the item
with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
must be put @emph{before} the checkbox. If you have activated alphabetical
lists, you can also use counters like @code{[@@b]}.}. Those constructs can
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
consistency in the whole list.
@kindex C-c -
@vindex org-plain-list-ordered-item-terminator
-@vindex org-list-automatic-rules
@item C-c -
Cycle the entire list level through the different itemize/enumerate bullets
(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
-and its position@footnote{See @code{bullet} rule in
-@code{org-list-automatic-rules} for more information.}. With a numeric
-prefix argument N, select the Nth bullet from this list. If there is an
-active region when calling this, selected text will be changed into an item.
-With a prefix argument, all lines will be converted to list items. If the
-first line already was a list item, any item marker will be removed from the
-list. Finally, even without an active region, a normal line will be
-converted into a list item.
+and its indentation. With a numeric prefix argument N, select the Nth bullet
+from this list. If there is an active region when calling this, selected
+text will be changed into an item. With a prefix argument, all lines will be
+converted to list items. If the first line already was a list item, any item
+marker will be removed from the list. Finally, even without an active
+region, a normal line will be converted into a list item.
@kindex C-c *
@item C-c *
Turn a plain list item into a headline (so that it becomes a subheading at
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
@cindex visibility cycling, drawers
@vindex org-drawers
+@cindex org-insert-drawer
+@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 drawers on a per-file basis
-with a line like @code{#+DRAWERS: HIDDEN PROPERTIES 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
After the drawer.
@end example
+You can interactively insert drawers at point by calling
+@code{org-insert-drawer}, which is bound to @key{C-c C-x d}. With an active
+region, this command will put the region inside the drawer. With a prefix
+argument, this command calls @code{org-insert-property-drawer} and add a
+property drawer right below the current headline. Completion over drawer
+keywords is also possible using @key{M-TAB}.
+
Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
show the entry, but keep the drawer collapsed to a single line. In order to
look inside the drawer, you need to move the cursor to the drawer line and
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{meant to be the final step before finishing a document (e.g., sending}
+ @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
@section The built-in table editor
@cindex table editor, built-in
-Org makes it easy to format tables in plain ASCII. Any line with @samp{|} as
+Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} as
the first non-whitespace character is considered part of a table. @samp{|}
is also the column separator@footnote{To insert a vertical bar into a table
field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
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
If you would like to overrule the automatic alignment of number-rich columns
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
+@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}
@end example
Column specifications can be absolute like @code{$1},
-@code{$2},...@code{$@var{N}}, or relative to the current column (i.e.@: the
+@code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
column of the field which is being computed) like @code{$+1} or @code{$-2}.
@code{$<} and @code{$>} are immutable references to the first and last
column, respectively, and you can use @code{$>>>} to indicate the third
However, this syntax is deprecated, it should not be used for new documents.
Use @code{@@>$} instead.} row in the table, respectively. You may also
specify the row relative to one of the hlines: @code{@@I} refers to the first
-hline, @code{@@II} to the second, etc@. @code{@@-I} refers to the first such
+hline, @code{@@II} to the second, etc. @code{@@-I} refers to the first such
line above the current line, @code{@@+I} to the first such line below the
current line. You can also write @code{@@III+2} which is the second data line
after the third hline in the table.
@code{@@0} and @code{$0} refer to the current row and column, respectively,
-i.e. to the row/column for the field being computed. Also, if you omit
+i.e., to the row/column for the field being computed. Also, if you omit
either the column or the row part of the reference, the current row/column is
implied.
$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{3 numbers from the column to the left, 2 up to current row}
+@@-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
@cindex Lisp forms, as table formulas
-It is also possible to write a formula in Emacs Lisp; this can be useful for
-string manipulation and control structures, if Calc's functionality is not
-enough. If a formula starts with a single-quote followed by an opening
-parenthesis, then it is evaluated as a Lisp form. The evaluation should
-return either a string or a number. Just as with @file{calc} formulas, you
-can specify modes and a printf format after a semicolon. With Emacs Lisp
-forms, you need to be conscious about the way field references are
-interpolated into the form. By default, a reference will be interpolated as
-a Lisp string (in double-quotes) containing the field. If you provide the
-@samp{N} mode switch, all referenced elements will be numbers (non-number
-fields will be zero) and interpolated as Lisp numbers, without quotes. If
-you provide the @samp{L} flag, all fields will be interpolated literally,
-without quotes. I.e., if you want a reference to be interpreted as a string
-by the Lisp form, enclose the reference operator itself in double-quotes,
-like @code{"$3"}. Ranges are inserted as space-separated fields, so you can
-embed them in list or vector syntax. 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
+It is also possible to write a formula in Emacs Lisp. This can be useful
+for string manipulation and control structures, if Calc's functionality is
+not enough.
+
+If a formula starts with a single-quote followed by an opening parenthesis,
+then it is evaluated as a Lisp form. The evaluation should return either a
+string or a number. Just as with @file{calc} formulas, you can specify modes
+and a printf format after a semicolon.
+
+With Emacs Lisp forms, you need to be conscious about the way field
+references are interpolated into the form. By default, a reference will be
+interpolated as a Lisp string (in double-quotes) containing the field. If
+you provide the @samp{N} mode switch, all referenced elements will be numbers
+(non-number fields will be zero) and interpolated as Lisp numbers, without
+quotes. If you provide the @samp{L} flag, all fields will be interpolated
+literally, without quotes. I.e., if you want a reference to be interpreted
+as a string by the Lisp form, enclose the reference operator itself in
+double-quotes, like @code{"$3"}. Ranges are inserted as space-separated
+fields, so you can embed them in list or vector syntax.
+
+Here are a few examples---note how the @samp{N} mode is used when we do
+computations in Lisp:
+
+@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
+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 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).
happening, in particular in range references, anchor ranges at the table
borders (using @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines
using the @code{@@I} notation. Automatic adaptation of field references does
-of cause not happen if you edit the table structure with normal editing
+of course not happen if you edit the table structure with normal editing
commands---then you must fix the equations yourself.
Instead of typing an equation into the field, you may also use the following
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
Install a new formula for the current column and replace current field with
the result of the formula. The command prompts for a formula, with default
taken from the @samp{#+TBLFM} line, applies it to the current field and
-stores it. With a numeric prefix argument(e.g.@: @kbd{C-5 C-c =}) the command
+stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
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.
| # | Peter | 10 | 8 | 23 | 41 | 8.2 |
| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
|---+---------+--------+--------+--------+-------+------|
-| | Average | | | | 29.7 | |
+| | Average | | | | 25.0 | |
| ^ | | | | | at | |
| $ | max=50 | | | | | |
|---+---------+--------+--------+--------+-------+------|
@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
Selects this line for global recalculation with @kbd{C-u C-c *}, but
not for automatic recalculation. Use this when automatic
recalculation slows down editing too much.
-@item
+@item @w{ }
Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
All lines that should be recalculated should be marked with @samp{#}
or @samp{*}.
Org-Plot can produce 2D and 3D graphs of information stored in org tables
using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
-@uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To see
-this in action, ensure that you have both Gnuplot and Gnuplot mode installed
-on your system, then call @code{org-plot/gnuplot} on the following table.
+@uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
+that you have both Gnuplot and Gnuplot mode installed on your system, then
+call @code{org-plot/gnuplot} on the following table.
@example
@group
@item with
Specify a @code{with} option to be inserted for every col being plotted
-(e.g.@: @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
+(e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
Defaults to @code{lines}.
@item file
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}
-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]]
For Org files, if there is a @samp{<<target>>} at the cursor, the link points
to the target. Otherwise it points to the current headline, which will also
be the description@footnote{If the headline contains a timestamp, it will be
-removed from the link and result in a wrong link -- you should avoid putting
+removed from the link and result in a wrong link---you should avoid putting
timestamp in the headline.}.
-@vindex org-link-to-org-use-id
+@vindex org-id-link-to-org-use-id
@cindex property, CUSTOM_ID
@cindex property, ID
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-link-to-org-use-id}), a globally unique @code{ID} property will be
-created and/or used to construct a link. 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.
+@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
+@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
@cindex @code{inlineimages}, STARTUP keyword
@cindex @code{noinlineimages}, STARTUP keyword
Toggle the inline display of linked images. Normally this will only inline
-images that have no description part in the link, i.e.@: images that will also
+images that have no description part in the link, i.e., images that will also
be inlined during export. When called with a prefix argument, also display
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
@smalllisp
@group
(setq org-link-abbrev-alist
- '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
- ("google" . "http://www.google.com/search?q=")
- ("gmap" . "http://maps.google.com/maps?q=%s")
- ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
- ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
+ '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
+ ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
+ ("google" . "http://www.google.com/search?q=")
+ ("gmap" . "http://maps.google.com/maps?q=%s")
+ ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
+ ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
@end group
@end smalllisp
If the replacement text contains the string @samp{%s}, it will be
-replaced with the tag. Otherwise the tag will be appended to the string
-in order to create the link. You may also specify a function that will
-be called with the tag as the only argument to create the link.
+replaced with the tag. Using @samp{%h} instead of @samp{%s} will
+url-encode the tag (see the example above, where we need to encode
+the URL parameter.) Using @samp{%(my-function)} will pass the tag
+to a custom function, and replace it by the resulting string.
+
+If the replacement text don't contain any specifier, it will simply
+be appended to the string in order to create the link.
+
+Instead of a string, you may also specify a function that will be
+called with the tag as the only argument to create the link.
With the above setting, you could link to a specific bug with
@code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
@noindent
In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
complete link abbreviations. You may also define a function
-@code{org-PREFIX-complete-link} that implements special (e.g.@: completion)
+@code{org-PREFIX-complete-link} that implements special (e.g., completion)
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.
@table @kbd
@orgcmd{C-c C-t,org-todo}
@cindex cycling, of TODO states
+@vindex org-use-fast-todo-selection
+
Rotate the TODO state of the current item among
@example
'--------------------------------'
@end example
-The same rotation can also be done ``remotely'' from the timeline and
-agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
+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
+@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}
-Select a specific keyword using completion or (if it has been set up)
-the fast selection interface. For the latter, you need to assign keys
-to TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, for
-more information.
+When TODO keywords have no selection keys, select a specific keyword using
+completion; otherwise force cycling through TODO states with no prompt. When
+@code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
+selection interface.
@kindex S-@key{right}
@kindex S-@key{left}
extensions}). See also @ref{Conflicts}, for a discussion of the interaction
with @code{shift-selection-mode}. See also the variable
@code{org-treat-S-cursor-todo-selection-as-state-change}.
-@orgcmd{C-c / t,org-show-todo-key}
+@orgcmd{C-c / t,org-show-todo-tree}
@cindex sparse tree, for TODO
@vindex org-todo-keywords
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-todo-keywords
By default, marked TODO entries have one of only two states: TODO and
-DONE. Org mode allows you to classify TODO items in more complex ways
+DONE@. Org mode allows you to classify TODO items in more complex ways
with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
special setup, the TODO keyword system can work differently in different
files.
state.
@cindex completion, of TODO keywords
With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
-to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may
+to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
also use a numeric prefix argument to quickly select a specific state. For
-example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
+example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
define many keywords, you can use in-buffer completion
(@pxref{Completion}) or even a special one-key selection scheme
In this case, different keywords do not indicate a sequence, but rather
different types. So the normal work flow would be to assign a task to a
-person, and later to mark it DONE. Org mode supports this style by adapting
+person, and later to mark it DONE@. Org mode supports this style by adapting
the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
@kbd{t} command in the timeline and agenda buffers.}. When used several
times in succession, it will still cycle through all names, in order to first
select the right type for a task. But when you return to the item after some
time and execute @kbd{C-c C-t} again, it will switch from any name directly
-to DONE. Use prefix arguments or completion to quickly select a specific
+to DONE@. Use prefix arguments or completion to quickly select a specific
name. You can also review the items of a specific TODO type in a sparse tree
by using a numeric prefix to @kbd{C-c / t}. For example, to see all things
Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items
@subsection Fast access to TODO states
If you would like to quickly change an entry to an arbitrary TODO state
-instead of cycling through the states, you can set up keys for
-single-letter access to the states. This is done by adding the section
-key after each keyword, in parentheses. For example:
+instead of cycling through the states, you can set up keys for single-letter
+access to the states. This is done by adding the selection character after
+each keyword, in parentheses@footnote{All characters are allowed except
+@code{@@^!}, which have a special meaning here.}. For example:
@lisp
(setq org-todo-keywords
@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.
@cindex property, ORDERED
The structure of Org files (hierarchy and lists) makes it easy to define TODO
dependencies. Usually, a parent TODO task should not be marked DONE until
-all subtasks (defined as children tasks) are marked as DONE. And sometimes
+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
-from changing state to DONE while they have children that are not DONE.
+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
+will be blocked until all earlier siblings are marked DONE@. Here is an
example:
@example
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.
Org mode can automatically record a timestamp and possibly a note when
you mark a TODO item as DONE, or even each time you change the state of
-a TODO item. This system is highly configurable, settings can be on a
+a TODO item. This system is highly configurable; settings can be on a
per-keyword basis and can be localized to a file or even a subtree. For
information on how to clock working time for a task, see @ref{Clocking
work time}.
(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}. You can
-also overrule the setting of this variable for a subtree by setting a
+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
@code{LOG_INTO_DRAWER} property.
Since it is normally too much to record a note for every state, Org mode
However, it will never prompt for two notes---if you have configured
both, the state change recording note will take precedence and cancel
the @samp{Closing Note}.}, and that a note is recorded when switching to
-WAIT or CANCELED. The setting for WAIT is even more special: the
+WAIT or CANCELED@. The setting for WAIT is even more special: the
@samp{!} after the slash means that in addition to the note taken when
entering the state, a timestamp should be recorded when @i{leaving} the
WAIT state, if and only if the @i{target} state does not configure
@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
syntax @samp{.+2d/3d}, which says that you want to do the task at least every
three days, but at most every two days.
@item
-You must also have state logging for the @code{DONE} state enabled, in order
-for historical data to be represented in the consistency graph. If it is not
-enabled it is not an error, but the consistency graphs will be largely
-meaningless.
+You must also have state logging for the @code{DONE} state enabled
+(@pxref{Tracking TODO state changes}), in order for historical data to be
+represented in the consistency graph. If it is not enabled it is not an
+error, but the consistency graphs will be largely meaningless.
@end enumerate
To give you an idea of what the above rules look like in action, here's an
@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.
accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
it with the string @samp{[ ]}. This feature is similar to TODO items
(@pxref{TODO Items}), but is more lightweight. Checkboxes are not included
-into the global TODO list, so they are often great to split a task into a
+in the global TODO list, so they are often great to split a task into a
number of simple steps. Or you can use them in a shopping list. To toggle a
checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
@file{org-mouse.el}).
@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}
@orgcmd{C-c C-c,org-toggle-checkbox}
Toggle checkbox status or (with prefix arg) checkbox presence at point.
With a single prefix argument, add an empty checkbox or remove the current
-one@footnote{`C-u C-c C-c' on the @emph{first} item of a list with no checkbox
+one@footnote{@kbd{C-u C-c C-c} on the @emph{first} item of a list with no checkbox
will add checkboxes to the rest of the list.}. With a double prefix argument, set it to @samp{[-]}, which is
considered to be an intermediate state.
@orgcmd{C-c C-x C-b,org-toggle-checkbox}
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
@noindent
@vindex org-use-tag-inheritance
@vindex org-tags-exclude-from-inheritance
-To limit tag inheritance to specific tags, or to turn it off entirely, use
-the variables @code{org-use-tag-inheritance} and
-@code{org-tags-exclude-from-inheritance}.
+To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
+To turn it off entirely, use @code{org-use-tag-inheritance}.
@vindex org-tags-match-list-sublevels
When a headline matches during a tags search while tag inheritance is turned
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).
-
-@node Setting tags, Tag searches, Tag inheritance, Tags
+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,
+either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
+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 @code{nil}
+can really speed up agenda generation.
+
+@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 M-x org-insert-property-drawer
-@findex org-insert-property-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
information like deadlines.
property names are special and (except for @code{:CATEGORY:}) should not be
used as keys in the properties drawer:
+@cindex property, special, ID
@cindex property, special, TODO
@cindex property, special, TAGS
@cindex property, special, ALLTAGS
@cindex property, special, TIMESTAMP
@cindex property, special, TIMESTAMP_IA
@cindex property, special, CLOCKSUM
+@cindex property, special, CLOCKSUM_T
@cindex property, special, BLOCKED
@c guessing that ITEM is needed in this area; also, should this list be sorted?
@cindex property, special, ITEM
@cindex property, special, FILE
@example
+ID @r{A globally unique ID used for synchronization during}
+ @r{iCalendar or MobileOrg export.}
TODO @r{The TODO keyword of the entry.}
TAGS @r{The tags defined directly in the headline.}
ALLTAGS @r{All tags, including inherited ones.}
TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}}
@r{must be run first to compute the values in the current buffer.}
+CLOCKSUM_T @r{The sum of CLOCK intervals in the subtree for today.}
+ @r{@code{org-clock-sum-today} must be run first to compute the}
+ @r{values in the current buffer.}
BLOCKED @r{"t" if task is currently blocked by children or siblings}
-ITEM @r{The content of the entry.}
+ITEM @r{The headline of the entry.}
FILE @r{The filename the entry is located in.}
@end example
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}
+@orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
Create a sparse tree with all matching entries. With a
@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
@orgcmd{C-c a m,org-tags-view}
@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}.
The @code{est+} summary type requires further explanation. It is used for
combining estimates, expressed as low-high ranges. For example, instead
of estimating a particular task will take 5 days, you might estimate it as
-5-6 days if you're fairly confident you know how much work is required, or
-1-10 days if you don't really know what needs to be done. Both ranges
+5--6 days if you're fairly confident you know how much work is required, or
+1--10 days if you don't really know what needs to be done. Both ranges
average at 5.5 days, but the first represents a more predictable delivery.
When combining a set of such estimates, simply adding the lows and highs
estimated at 0.5 to 2 days of work. Straight addition produces an estimate
of 5 to 20 days, representing what to expect if everything goes either
extremely well or extremely poorly. In contrast, @code{est+} estimates the
-full job more realistically, at 10-15 days.
+full job more realistically, at 10--15 days.
Here is an example for a complete columns definition, along with allowed
values.
@example
:COLUMNS: %25ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line---it is wrapped here only because of formatting constraints.}
- %10Time_Estimate@{:@} %CLOCKSUM
+ %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T
:Owner_ALL: Tammy Mark Karl Lisa Don
:Status_ALL: "In progress" "Not started yet" "Finished" ""
:Approved_ALL: "[ ]" "[X]"
@noindent
The first column, @samp{%25ITEM}, means the first 25 characters of the
-item itself, i.e.@: of the headline. You probably always should start the
+item itself, i.e., of the headline. You probably always should start the
column definition with the @samp{ITEM} specifier. The other specifiers
create columns @samp{Owner} with a list of names as allowed values, for
@samp{Status} with four different possible values, and for a checkbox
be created for the @samp{Time_Estimate} column by adding time duration
expressions like HH:MM, and for the @samp{Approved} column, by providing
an @samp{[X]} status if all children have been checked. The
-@samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals
-in the subtree.
+@samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns are special, they lists the
+sums of CLOCK intervals in the subtree, either for all clocks or just for
+today.
@node Using column view, Capturing column view, Defining columns, Column view
@subsection Using column view
@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
plain timestamp will be shown exactly on that date.
@example
-* Meet Peter at the movies <2006-11-01 Wed 19:15>
-* Discussion on climate change <2006-11-02 Thu 20:00-22:00>
+* Meet Peter at the movies
+ <2006-11-01 Wed 19:15>
+* Discussion on climate change
+ <2006-11-02 Thu 20:00-22:00>
@end example
@item Timestamp with repeater interval
following will show up in the agenda every Wednesday:
@example
-* Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
+* Pick up Sam at school
+ <2007-05-16 Wed 12:30 +1w>
@end example
@item Diary-style sexp entries
@example
* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
- <%%(org-float t 4 2)>
+ <%%(diary-float t 4 2)>
@end example
@item Time/Date range
@emph{not} trigger an entry to show up in the agenda.
@example
-* Gillian comes late for the fifth time [2006-11-01 Wed]
+* Gillian comes late for the fifth time
+ [2006-11-01 Wed]
@end example
@end table
@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
You can specify a time range by giving start and end times or by giving a
start time and a duration (in HH:MM format). Use one or two dash(es) as the
separator in the former case and use '+' as the separator in the latter
-case, e.g.@:
+case, e.g.:
@example
11am-1:15pm @result{} 11:00-13:15
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
@code{org-deadline-warning-days} before the due date, and continuing
-until the entry is marked DONE. An example:
+until the entry is marked DONE@. An example:
@example
*** TODO write article about the Earth for the Guide
- The editor in charge is [[bbdb:Ford Prefect]]
DEADLINE: <2004-02-29 Sun>
+ The editor in charge is [[bbdb:Ford Prefect]]
@end example
You can specify a different lead time for warnings for a specific
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
@vindex org-agenda-skip-scheduled-if-done
The headline will be listed under the given date@footnote{It will still
-be listed on that date after it has been marked DONE. If you don't like
+be listed on that date after it has been marked DONE@. If you don't like
this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
addition, a reminder that the scheduled date has passed will be present
-in the compilation for @emph{today}, until the entry is marked DONE, i.e.@:
+in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
the task will automatically be forwarded until completed.
@example
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}.
assumption that the timestamp represents the @i{nearest instance} of
the repeater. However, the use of diary sexp entries like
@c
-@code{<%%(org-float t 42)>}
+@code{<%%(diary-float t 42)>}
@c
in scheduling and deadline timestamps is limited. Org mode does not
know enough about the internals of each sexp function to issue early and
@end table
Note that @code{org-schedule} and @code{org-deadline} supports
-setting the date by indicating a relative time: e.g. +1d will set
+setting the date by indicating a relative time: e.g., +1d will set
the date to the next day after today, and --1w will set the date
to the previous week before any current timestamp.
@noindent
the @code{+1m} is a repeater; the intended interpretation is that the task
has a deadline on <2005-10-01> and repeats itself every (one) month starting
-from that time. If you need both a repeater and a special warning period in
-a deadline entry, the repeater should come first and the warning period last:
-@code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
+from that time. You can use yearly, monthly, weekly, daily and hourly repeat
+cookies by using the @code{y/w/m/d/h} letters. If you need both a repeater
+and a special warning period in a deadline entry, the repeater should come
+first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
@vindex org-todo-repeat-to-state
Deadlines and scheduled items produce entries in the agenda when they are
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
@cindex time clocking
Org mode allows you to clock the time you spend on specific tasks in a
-project. When you start working on an item, you can start the clock.
-When you stop working on that task, or when you mark the task done, the
-clock is stopped and the corresponding time interval is recorded. It
-also computes the total time spent on each subtree of a project. And it
-remembers a history or tasks recently clocked, to that you can jump quickly
-between a number of tasks absorbing your time.
+project. When you start working on an item, you can start the clock. When
+you stop working on that task, or when you mark the task done, the clock is
+stopped and the corresponding time interval is recorded. It also computes
+the total time spent on each subtree@footnote{Clocking only works if all
+headings are indented with less than 30 stars. This is a hardcoded
+limitation of `lmax' in `org-clock-sum'.} of a project. And it remembers a
+history or tasks recently clocked, to that you can jump quickly between a
+number of tasks absorbing your time.
To save the clock history across Emacs sessions, use
@lisp
@table @kbd
@orgcmd{C-c C-x C-i,org-clock-in}
@vindex org-clock-into-drawer
+@vindex org-clock-continuously
@cindex property, LOG_INTO_DRAWER
Start the clock on the current item (clock-in). This inserts the CLOCK
keyword together with a timestamp. If this is not the first clocking of
@code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
When called with a @kbd{C-u} prefix argument,
select the task from a list of recently clocked tasks. With two @kbd{C-u
-C-u} prefixes, clock into the task at point and mark it as the default task.
-The default task will always be available when selecting a clocking task,
-with letter @kbd{d}.@*
+C-u} prefixes, clock into the task at point and mark it as the default task;
+the default task will then always be available with letter @kbd{d} when
+selecting a clocking task. With three @kbd{C-u C-u C-u} prefixes, force
+continuous clocking by starting the clock when the last clock stopped.@*
@cindex property: CLOCK_MODELINE_TOTAL
@cindex property: LAST_REPEAT
@vindex org-clock-modeline-total
possibility to record an additional note together with the clock-out
timestamp@footnote{The corresponding in-buffer setting is:
@code{#+STARTUP: lognoteclock-out}}.
+@orgcmd{C-c C-x C-x,org-clock-in-last}
+@vindex org-clock-continuously
+Reclock the last clocked task. With one @kbd{C-u} prefix argument,
+select the task from the clock history. With two @kbd{C-u} prefixes,
+force continuous clocking by starting the clock when the last clock
+stopped.
@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
Update the effort estimate for the current clock task.
@kindex C-c C-y
is only necessary if you edit the timestamps directly. If you change
them with @kbd{S-@key{cursor}} keys, the update is automatic.
@orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
-On @code{CLOCK} log lines, increase/decrease both timestamps at the same
-time so that duration keeps the same.
+On @code{CLOCK} log lines, increase/decrease both timestamps so that the
+clock duration keeps the same.
+@orgcmd{S-M-@key{up/down},org-timestamp-up/down}
+On @code{CLOCK} log lines, increase/decrease the timestamp at point and
+the one of the previous (or the next clock) timestamp by the same duration.
+For example, if you hit @kbd{S-M-@key{up}} to increase a clocked-out timestamp
+by five minutes, then the clocked-in timestamp of the next clock will be
+increased by five minutes.
@orgcmd{C-c C-t,org-todo}
Changing the TODO state of an item to DONE automatically stops the clock
if it is running in this same item.
-@orgcmd{C-c C-x C-x,org-clock-cancel}
+@orgcmd{C-c C-x C-q,org-clock-cancel}
Cancel the current clock. This is useful if a clock was started by
mistake, or if you ended up working on something else.
@orgcmd{C-c C-x C-j,org-clock-goto}
the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
worked on or closed during a day.
+@strong{Important:} note that both @code{org-clock-out} and
+@code{org-clock-in-last} can have a global keybinding and will not
+modify the window disposition.
+
@node The clock table, Resolving idle time, Clocking commands, Clocking work time
@subsection The clock table
@cindex clocktable, dynamic block
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 %
@end example
@node Resolving idle time, , The clock table, Clocking work time
-@subsection Resolving idle time
+@subsection Resolving idle time and continuous clocking
+
+@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
-UTILITIES 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
to a recovery event rather than a set amount of idle time.
You can also check all the files visited by your Org agenda for dangling
-clocks at any time using @kbd{M-x org-resolve-clocks}.
+clocks at any time using @kbd{M-x org-resolve-clocks RET} (or @kbd{C-c C-x C-z}).
+
+@subsubheading Continuous clocking
+@cindex continuous clocking
+@vindex org-clock-continuously
+
+You may want to start clocking from the time when you clocked out the
+previous task. To enable this systematically, set @code{org-clock-continuously}
+to @code{t}. Each time you clock in, Org retrieves the clock-out time of the
+last clocked entry for this session, and start the new clock from there.
+
+If you only want this from time to time, use three universal prefix arguments
+with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}.
@node Effort estimates, Relative timer, Clocking work time, Dates and Times
@section Effort estimates
* Capture:: Capturing new stuff
* 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
+* Protocols:: External (e.g., Browser) access to Emacs and Org
+* 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
@table @kbd
@orgcmd{C-c c,org-capture}
Call the command @code{org-capture}. Note that this keybinding is global and
-not active by default - you need to install it. If you have templates
+not active by default: you need to install it. If you have templates
@cindex date tree
defined @pxref{Capture templates}, it will offer these templates for
selection or use a new Org outline node as the default template. It will
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
Visit the last stored capture item in its buffer.
@end table
+@vindex org-capture-bookmark
+@cindex org-capture-last-stored
+You can also jump to the bookmark @code{org-capture-last-stored}, which will
+automatically be created unless you set @code{org-capture-bookmark} to
+@code{nil}.
+
+To insert the capture at point in an Org buffer, call @code{org-capture} with
+a @code{C-0} prefix argument.
+
@node Capture templates, , Using capture, Capture
@subsection Capture templates
@cindex templates, for Capture
@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
@menu
* Template elements:: What is needed for a complete template entry
* Template expansion:: Filling in information about time and context
+* Templates in contexts:: Only show a template in a specific context
@end menu
@node Template elements, Template expansion, Capture templates, Capture templates
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
@end table
@end table
-@node Template expansion, , Template elements, Capture templates
+@node Template expansion, Templates in contexts, Template elements, Capture templates
@subsubsection Template expansion
In the template itself, special @kbd{%}-escapes@footnote{If you need one of
-these sequences literally, escape the @kbd{%} with a backslash.} allow
+these sequences literally, escape the @kbd{%} with a backslash.} allow
dynamic insertion of content. The templates are expanded in the order given here:
@smallexample
-%[@var{file}] @r{insert the contents of the file given by @var{file}.}
-%(@var{sexp}) @r{evaluate Elisp @var{sexp} and replace with the result.}
-%<...> @r{the result of format-time-string on the ... format specification.}
-%t @r{timestamp, date only.}
-%T @r{timestamp with date and time.}
-%u, %U @r{like the above, but inactive timestamps.}
-%a @r{annotation, normally the link created with @code{org-store-link}.}
-%i @r{initial content, the region when capture is called while the}
+%[@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{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.}
+%u, %U @r{Like the above, but inactive timestamps.}
+%i @r{Initial content, the region when capture is called while the}
@r{region is active.}
@r{The entire text will be indented like @code{%i} itself.}
-%A @r{like @code{%a}, but prompt for the description part.}
+%a @r{Annotation, normally the link created with @code{org-store-link}.}
+%A @r{Like @code{%a}, but prompt for the description part.}
+%l @r{Like %a, but only insert the literal link.}
%c @r{Current kill ring head.}
%x @r{Content of the X clipboard.}
-%k @r{title of the currently clocked task.}
-%K @r{link to the currently clocked task.}
-%n @r{user name (taken from @code{user-full-name}).}
-%f @r{file visited by current buffer when org-capture was called.}
-%F @r{full path of the file or directory visited by current buffer.}
-%:keyword @r{specific information for certain link types, see below.}
-%^g @r{prompt for tags, with completion on tags in target file.}
-%^G @r{prompt for tags, with completion all tags in all agenda files.}
-%^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
+%k @r{Title of the currently clocked task.}
+%K @r{Link to the currently clocked task.}
+%n @r{User name (taken from @code{user-full-name}).}
+%f @r{File visited by current buffer when org-capture was called.}
+%F @r{Full path of the file or directory visited by current buffer.}
+%:keyword @r{Specific information for certain link types, see below.}
+%^g @r{Prompt for tags, with completion on tags in target file.}
+%^G @r{Prompt for tags, with completion all tags in all agenda files.}
+%^t @r{Like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
@r{You may define a prompt like @code{%^@{Birthday@}t}.}
%^C @r{Interactive selection of which kill or clip to use.}
%^L @r{Like @code{%^C}, but insert as link.}
@r{You may specify a default value and a completion table with}
@r{%^@{prompt|default|completion2|completion3...@}.}
@r{The arrow keys access a prompt-specific history.}
+%\n @r{Insert the text entered at the nth %^@{@var{prompt}@}, where @code{n} is}
+ @r{a number, starting from 1.}
+%? @r{After completing the template, position cursor here.}
@end smallexample
@noindent
@vindex org-from-is-user-regexp
@smallexample
-Link type | Available keywords
-------------------------+----------------------------------------------
-bbdb | %:name %:company
-irc | %:server %:port %:nick
-vm, wl, mh, mew, rmail | %:type %:subject %:message-id
- | %:from %:fromname %:fromaddress
- | %:to %:toname %:toaddress
- | %:date @r{(message date header field)}
- | %:date-timestamp @r{(date as active timestamp)}
- | %:date-timestamp-inactive @r{(date as inactive timestamp)}
- | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}}
-gnus | %:group, @r{for messages also all email fields}
-w3, w3m | %:url
-info | %:file %:node
-calendar | %:date
+Link type | Available keywords
+---------------------------------+----------------------------------------------
+bbdb | %:name %:company
+irc | %:server %:port %:nick
+vm, vm-imap, wl, mh, mew, rmail | %:type %:subject %:message-id
+ | %:from %:fromname %:fromaddress
+ | %:to %:toname %:toaddress
+ | %:date @r{(message date header field)}
+ | %:date-timestamp @r{(date as active timestamp)}
+ | %:date-timestamp-inactive @r{(date as inactive timestamp)}
+ | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}}
+gnus | %:group, @r{for messages also all email fields}
+w3, w3m | %:url
+info | %:file %:node
+calendar | %:date
@end smallexample
@noindent
%? @r{After completing the template, position cursor here.}
@end smallexample
+@node Templates in contexts, , Template expansion, Capture templates
+@subsubsection Templates in contexts
+
+@vindex org-capture-templates-contexts
+To control whether a capture template should be accessible from a specific
+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:
+
+@smalllisp
+(setq org-capture-templates-contexts
+ '(("p" (in-mode . "message-mode"))))
+@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:
+
+@smalllisp
+(setq org-capture-templates-contexts
+ '(("p" "q" (in-mode . "message-mode"))))
+@end smalllisp
+
+See the docstring of the variable for more information.
@node Attachments, RSS Feeds, Capture, Capture - Refile - Archive
@section Attachments
@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
@cindex archive locations
The default archive location is a file in the same directory as the
current file, with the name derived by appending @file{_archive} to the
-current file name. For information and examples on how to change this,
+current file name. You can also choose what heading to file archived
+items under, with the possibility to add them to a datetree in a file.
+For information and examples on how to specify the file and the heading,
see the documentation string of the variable
-@code{org-archive-location}. There is also an in-buffer option for
-setting this variable, for example@footnote{For backward compatibility,
-the following also works: If there are several such lines in a file,
-each specifies the archive location for the text below it. The first
-such line also applies to any text before its definition. However,
-using this method is @emph{strongly} deprecated as it is incompatible
-with the outline structure of the document. The correct method for
-setting multiple archive locations in a buffer is using properties.}:
+@code{org-archive-location}.
+
+There is also an in-buffer option for setting this variable, for
+example@footnote{For backward compatibility, the following also works:
+If there are several such lines in a file, each specifies the archive
+location for the text below it. The first such line also applies to any
+text before its definition. However, using this method is
+@emph{strongly} deprecated as it is incompatible with the outline
+structure of the document. The correct method for setting multiple
+archive locations in a buffer is using properties.}:
@cindex #+ARCHIVE
@example
@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}).
backward compatibility, you can also press @kbd{0} to restrict to the
current region/subtree.}. After pressing @kbd{< <}, you still need to press the
character selecting the command.
+
+@item *
+@vindex org-agenda-sticky
+Toggle sticky agenda views. By default, Org maintains only a single agenda
+buffer and rebuilds it each time you change the view, to make sure everything
+is always up to date. If you switch between views often and the build time
+bothers you, you can turn on sticky agenda buffers (make this the default by
+customizing the variable @code{org-agenda-sticky}). With sticky agendas, the
+dispatcher only switches to the selected view, you need to update it by hand
+with @kbd{r} or @kbd{g}. You can toggle sticky agenda view any time with
+@code{org-toggle-sticky-agenda}.
@end table
You can also define custom commands that will be accessible through the
@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.
@cindex appointment
@cindex reminders
-Org can interact with Emacs appointments notification facility. To add all
-the appointments of your agenda files, use the command
-@code{org-agenda-to-appt}. This command also lets you filter through the
-list of your appointments and add only those belonging to a specific category
-or matching a regular expression. See the docstring for details.
+Org can interact with Emacs appointments notification facility. To add the
+appointments of your agenda files, use the command @code{org-agenda-to-appt}.
+This command lets you filter through the list of your appointments and add
+only those belonging to a specific category or matching a regular expression.
+It also reads a @code{APPT_WARNTIME} property which will then override the
+value of @code{appt-message-warning-time} for this appointment. See the
+docstring for details.
@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
@subsection The global TODO list
@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.
+entry and the ``property'' @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
assumed to be date/time specifications in the standard Org way, and the
comparison will be done accordingly. Special values that will be recognized
are @code{"<now>"} for now (including time), and @code{"<today>"}, and
-@code{"<tomorrow>"} for these days at 0:00 hours, i.e.@: without a time
+@code{"<tomorrow>"} for these days at 0:00 hours, i.e., without a time
specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
respectively, can be used.
connected with @samp{|}) with a @samp{/} and then specify a Boolean
expression just for TODO keywords. The syntax is then similar to that for
tags, but should be applied with care: for example, a positive selection on
-several TODO keywords cannot meaningfully be combined with boolean AND.
+several TODO keywords cannot meaningfully be combined with boolean AND@.
However, @emph{negative selection} combined with AND can be meaningful. To
make sure that only lines are checked that actually have any TODO keyword
(resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the 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{up} and @kbd{C-p}).
-@orgcmd{p,org-agenda-previous-line}
-Previous line (same as @key{down} and @kbd{C-n}).
-@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.
+@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.}
+
+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.
+
+@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
+categories: 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.
Delete other windows.
@c
@orgcmdkskc{v d,d,org-agenda-day-view}
-@xorgcmdkskc{v w,w,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-month-year}
+@xorgcmd{v y,org-agenda-year-view}
@xorgcmd{v SPC,org-agenda-reset-view}
@vindex org-agenda-span
Switch to day/week/month/year view. When switching to day or week view, this
month view, a year may be encoded in the prefix argument as well. For
example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
specification has only one or two digits, it will be mapped to the interval
-1938-2037. @kbd{v @key{SPC}} will reset to what is set in
+1938--2037. @kbd{v @key{SPC}} will reset to what is set in
@code{org-agenda-span}.
@c
@orgcmd{f,org-agenda-later}
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
-when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show
+when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
contributions from entries that are hidden by agenda filtering@footnote{Only
tags filtering will be respected here, effort filtering is ignored.}. See
also the variable @code{org-clock-report-include-clocking-task}.
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
-@item 0-9
+@item 0--9
Digit argument.
@c
@cindex undoing remote-editing events
@orgcmd{C-c C-d,org-agenda-deadline}
Set a deadline for this item. With prefix arg remove the deadline.
@c
-@orgcmd{k,org-agenda-action}
-Agenda actions, to set dates for selected items to the cursor date.
-This command also works in the calendar! The command prompts for an
-additional key:
-@example
-m @r{Mark the entry at point for action. You can also make entries}
- @r{in Org files with @kbd{C-c C-x C-k}.}
-d @r{Set the deadline of the marked entry to the date at point.}
-s @r{Schedule the marked entry at the date at point.}
-r @r{Call @code{org-capture} with the cursor date as default date.}
-@end example
-@noindent
-Press @kbd{r} afterward to refresh the agenda and see the effect of the
-command.
-@c
@orgcmd{S-@key{right},org-agenda-do-date-later}
Change the timestamp associated with the current line by one day into the
future. If the date is in the past, the first call to this command will move
@c
@orgcmd{J,org-agenda-clock-goto}
Jump to the running clock in another window.
+@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 @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-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}
will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
-these special timestamps.
-@example
-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.}
-$ @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}.}
-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.}
-d @r{Set deadline to a specific date.}
-f @r{Apply a function 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
+these special timestamps. By default, marks are removed after the bulk. If
+you want them to persist, set @code{org-agenda-bulk-persistent-marks} to
+@code{t} or hit @kbd{p} at the prompt.
+
+@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.
@tsubheading{Exporting to a file}
-@orgcmd{C-x C-w,org-write-agenda}
+@orgcmd{C-x C-w,org-agenda-write}
@cindex exporting agenda views
@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}
buffer).
@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
+@cindex todo-tree
+@cindex occur-tree
+@cindex tags-tree
+
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:
+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 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
Peter, or Kim) as additional tag to match.
@end table
+Note that the @code{*-tree} agenda views need to be called from an
+Org buffer as they operate on the current buffer only.
+
@node Block agenda, Setting Options, Storing searches, Custom agenda views
@subsection Block agenda
@cindex block agenda
value is a string, you need to add the double-quotes around the value
yourself.
+@vindex org-agenda-custom-commands-contexts
+To control whether an agenda command should be accessible from a specific
+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:
+
+@lisp
+(setq org-agenda-custom-commands-contexts
+ '(("o" (in-mode . "message-mode"))))
+@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:
+
+@lisp
+(setq org-agenda-custom-commands-contexts
+ '(("o" "r" (in-mode . "message-mode"))))
+@end lisp
+
+See the docstring of the variable for more information.
@node Exporting Agenda Views, Agenda column view, Custom agenda views, Agenda Views
@section Exporting Agenda Views
you want to do this only occasionally, use the command
@table @kbd
-@orgcmd{C-x C-w,org-write-agenda}
+@orgcmd{C-x C-w,org-agenda-write}
@cindex exporting agenda views
@cindex agenda views, exporting
@vindex org-agenda-exporter-settings
applications for column view in the agenda. If you want information about
clocked time in the displayed period use clock table mode (press @kbd{R} in
the agenda).
+
+@item
+@cindex property, special, CLOCKSUM_T
+When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
+always today's clocked time for this item. So even in the weekly agenda,
+the clocksum listed in column view only originates from today. This lets
+you compare the time you spent on a task for today, with the time already
+spent (via @code{CLOCKSUM}) and with the planned total effort for it.
@end enumerate
@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 default 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.
+@example
+#+OPTIONS: toc:nil (no default TOC)
+...
+#+TOC: headlines 2 (insert TOC here, with two headline levels)
+@end example
-@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}.
-
-@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 exporting, not
@cindex #+BEGIN_COMMENT
-Lines starting with @samp{#} in column zero are treated as comments and will
-never be exported. If you want an indented line to be treated as a comment,
-start it with @samp{#+ }. Also entire subtrees starting with the word
-@samp{COMMENT} will never be exported. Finally, regions surrounded by
-@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported.
+Lines starting with zero or more whitespace characters followed by one
+@samp{#} and a whitespace are treated as comments and will never be exported.
+Also entire subtrees starting with the word @samp{COMMENT} will never be
+exported. Finally, regions surrounded by @samp{#+BEGIN_COMMENT}
+... @samp{#+END_COMMENT} will not be exported.
@table @kbd
@kindex C-c ;
@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: tbl: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. To use listings, turn
-on the variable @code{org-export-latex-listings} and ensure that the listings
-package is included by the @LaTeX{} header (e.g.@: by configuring
-@code{org-export-latex-packages-alist}). See the listings documentation for
-configuration options, including obtaining colored output. For minted it is
-necessary to install the program @url{http://pygments.org, pygments}, in
-addition to setting @code{org-export-latex-minted}, ensuring that the minted
-package is included by the @LaTeX{} header, and ensuring that the
-@code{-shell-escape} option is passed to @file{pdflatex} (see
-@code{org-latex-to-pdf-process}). See the documentation of the variables
-@code{org-export-latex-listings} and @code{org-export-latex-minted} for
-further 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. See @pxref{Working With Source Code} for more
-information on evaluating code blocks.}, see @ref{Easy Templates} for
-shortcuts to easily insert code blocks.
+@url{http://code.google.com/p/minted, minted,} package. Refer to
+@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.
+See @pxref{Working With Source Code} for more information on evaluating code
+blocks.}, see @ref{Easy Templates} for shortcuts to easily insert code
+blocks.
@cindex #+BEGIN_SRC
@example
numbered. If you use a @code{+n} switch, the numbering from the previous
numbered snippet will be continued in the current one. In literal examples,
Org will interpret strings like @samp{(ref:name)} as labels, and use them as
-targets for special hyperlinks like @code{[[(name)]]} (i.e.@: the reference name
+targets for special hyperlinks like @code{[[(name)]]} (i.e., the reference name
enclosed in single parenthesis). In HTML, hovering the mouse over such a
link will remote-highlight the corresponding code line, which is kind of
cool.
@item C-c '
Edit the source code example at point in its native mode. This works by
switching to a temporary buffer with the source code. You need to exit by
-pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*}
-or @samp{#} will get a comma prepended, to keep them from being interpreted
-by Org as outline nodes or special comments. These commas will be stripped
-for editing with @kbd{C-c '}, and also for export.}. The edited version will
-then replace the old version in the Org buffer. Fixed-width regions
-(where each line starts with a colon followed by a space) will be edited
-using @code{artist-mode}@footnote{You may select a different-mode with the
-variable @code{org-edit-fixed-width-region-mode}.} to allow creating ASCII
-drawings easily. Using this command in an empty line will create a new
-fixed-width region.
+pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*},
+@samp{,*}, @samp{#+} and @samp{,#+} will get a comma prepended, to keep them
+from being interpreted by Org as outline nodes or special syntax. These
+commas will be stripped for editing with @kbd{C-c '}, and also for export.}.
+The edited version will then replace the old version in the Org buffer.
+Fixed-width regions (where each line starts with a colon followed by a space)
+will be edited using @code{artist-mode}@footnote{You may select
+a different-mode with the variable @code{org-edit-fixed-width-region-mode}.}
+to allow creating ASCII drawings easily. Using this command in an empty line
+will create a new fixed-width region.
@kindex C-c l
@item C-c l
Calling @code{org-store-link} while editing a source code example in a
@example
#+INCLUDE: "~/.emacs" src emacs-lisp
@end example
+
@noindent
-The optional second and third parameter are the markup (e.g.@: @samp{quote},
+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 behavior 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
* Subscripts and superscripts:: Simple syntax for raising/lowering text
-* @LaTeX{} fragments:: Complex formulas made easy
+* @LaTeX{} fragments:: Complex formulas made easy
* Previewing @LaTeX{} fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
@end menu
@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, available at
-@url{http://sourceforge.net/projects/dvipng/}. 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}.
+
+For example, @samp{#+BEGIN_ABSTRACT} and @samp{#+BEGIN_VIDEO} are special
+blocks. The first one is useful when exporting to @LaTeX{}, the second one
+when exporting to HTML5.
+
+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 opening and
+closing block lines were not there. For example, when exporting a
+@samp{#+BEGIN_TEST} block, HTML back-end wraps its contents within a
+@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
+* Org export:: Exporting to Org
+* 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 behavior 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 org (Org 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). When headlines are selectively exported with @code{:export:}
+anywhere in a file, text before the first headline is ignored.
+
+@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}
-@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 overridden 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
@cindex UTF-8 export
ASCII export produces a simple and very readable version of an Org mode
-file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file
+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
-Export as 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}
+@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.
+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
-@kbd{C-1 C-c C-e a}
+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
-@noindent
-creates only top level headlines and does 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, 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
+@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 presentation:
+@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
+
+Here is a simple example Org document that is intended for Beamer export.
+
+@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
-Export as HTML file. For an Org file @file{myfile.org},
+@orgcmd{C-c C-e h h,org-html-export-to-html}
+Export as an 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}
-Export as HTML file and immediately open it with a browser.
-@orgcmd{C-c C-e H,org-export-as-html-to-buffer}
+without warning.
+@kbd{C-c C-e h o}
+Export as an HTML file and immediately open it with a browser.
+@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 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 syntax
+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
+#+BEGIN_ASIDE
+Lorem ipsum
+#+END_ASIDE
+@end example
+
+Will export to:
+
+@example
+<aside>
+ <p>Lorem ipsum</p>
+</aside>
+@end example
+
+While this:
@example
-@kbd{C-2 C-c C-e b}
+#+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
-@noindent
-creates two levels of headings and does the rest as items.
+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.,
+@code{#+BEGIN_LEDERHOSEN} will still export to @samp{<div class="lederhosen">}.
+Headlines cannot appear within special blocks. To wrap a headline and its
+contents in e.g., @samp{<section>} or @samp{<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 formatting
-string in @code{org-export-html-preamble-format}.
-
-Setting @code{org-export-html-preamble} to a string will override the default
-formatting 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 formatting 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 links, in HTML export
@cindex internal links, in HTML export
@cindex external links, in HTML export
-Internal links (@pxref{Internal links}) will continue to work in HTML. This
+Internal links (@pxref{Internal links}) will continue to work in HTML@. This
includes automatic links created by radio targets (@pxref{Radio
targets}). Links to external files will still work if the target file is on
the same @i{relative} path as the published Org file. Links to other
@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{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
path: @r{The path to the script. The default is to grab the script from}
@r{@url{http://orgmode.org/org-info.js}, but you might want to have}
@r{a local copy and use a path like @samp{../scripts/org-info.js}.}
-view: @r{Initial view when website is first shown. Possible values are:}
+view: @r{Initial view when the website is first shown. Possible values are:}
info @r{Info-like interface with one section per page.}
overview @r{Folding interface, initially showing only top-level.}
content @r{Folding interface, starting with all headlines visible.}
@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 @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 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
+@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-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, LATEX_CLASS
-@cindex property, LATEX_CLASS_OPTIONS
-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. 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.
+@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.
-@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, Header and sectioning, @LaTeX{} and PDF export
-@subsection Quoting @LaTeX{} code
+@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.
-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:
+An example is shown below.
-@cindex #+LaTeX
-@cindex #+BEGIN_LaTeX
@example
-#+LaTeX: Literal @LaTeX{} code for export
+#+LATEX_CLASS: article
+#+LATEX_CLASS_OPTIONS: [a4paper]
+#+LATEX_HEADER: \usepackage@{xyz@}
+
+* Headline 1
+ some text
@end example
-@noindent or
-@cindex #+BEGIN_LaTeX
+@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. Furthermore, you can add special code that
+should only be present in @LaTeX{} export with the following constructs:
+@cindex #+LATEX
+@cindex #+BEGIN_LATEX
@example
-#+BEGIN_LaTeX
+Code within @@@@latex:some code@@@@ a paragraph.
+
+#+LATEX: Literal @LaTeX{} code for export
+
+#+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
+
+@LaTeX{} understands attributes specified in an @code{ATTR_LATEX} line. They
+affect tables, images, plain lists, special blocks and source blocks.
-@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} and PDF export
-@subsection Tables in @LaTeX{} export
+@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}}. For example the
-@code{#+ATTR_LaTeX:} line below is exported as the @code{figure} environment
-below it.
-
-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 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.
+If you need a specific command for the caption, use @code{:caption}
+attribute. It will override standard @code{#+CAPTION} value, if any.
-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{multicolumn}: if you wish to include a source block which spans multiple
+columns in a page.
+@item
+@code{nil}: if you need to avoid any floating environment, 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 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 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 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
+@cindex abstract, in @LaTeX{} export
+@cindex proof, 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
+#+BEGIN_ABSTRACT
+We demonstrate how to solve the Syracuse problem.
+#+END_ABSTRACT
+
+#+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@{abstract@}
+We demonstrate how to solve the Syracuse problem.
+\end@{abstract@}
+
+\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}.
-
-@node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export
-@subsection Tables in DocBook export
-@cindex tables, in DocBook export
+@subsubheading Horizontal rules
+@cindex horizontal rules, in @LaTeX{} export
-Tables in Org files are exported as HTML tables, which have been supported since
-DocBook V4.3.
+Width and thickness of a given horizontal rule can be controlled with,
+respectively, @code{:width} and @code{:thickness} attributes:
-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 flavor,
+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, Org 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
-Orgmode@footnote{Versions 7.8 or later} supports export to OpenDocument Text
-(ODT) format using the @file{org-odt.el} module. Documents created
-by this exporter use the @cite{OpenDocument-v1.2
+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}
-Export as OpenDocument Text file and open the resulting file.
+@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}. If you
-would like to use a converter of your own choosing or tweak the default
-settings of the default @file{LibreOffice} and @samp{unoconv} converters
-@xref{Configuring a document converter}.
+@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
LibreOffice. The latter method is suitable for expert and non-expert
users alike, and is described here.
-@subsubsection Applying custom styles - the easy way
+@subsubsection Applying custom styles: the easy way
@enumerate
@item
@item
Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
-to locate the target styles - these typically have the @samp{Org} prefix -
-and modify those to your taste. Save the modified file either as an
+to locate the target styles---these typically have the @samp{Org} prefix---and
+modify those to your taste. Save the modified file either as an
OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file.
@item
@cindex #+ODT_STYLES_FILE
-@vindex org-export-odt-styles-file
-Customize the variable @code{org-export-odt-styles-file} and point it to the
+@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 that have column or row spans - is not supported. Such tables are
+tables is supported. However, export of complex @file{table.el} tables---tables
+that have column or row spans---is not supported. Such tables are
stripped from the exported document.
By default, a table is exported with top and bottom frames and with rules
@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.
@cindex #+ATTR_ODT
You can control the manner in which an image is anchored by setting the
@code{:anchor} property of it's @code{#+ATTR_ODT} line. You can specify one
-of the the following three values for the @code{:anchor} property -
+of the the following three values for the @code{:anchor} property:
@samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}.
To create an image that is anchored to a page, do the following:
the @LaTeX{}-to-MathML converter.
@table @kbd
+@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
-Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file.
-
-@item M-x org-export-as-odf-and-open
-Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file and
-open the formula file with the system-registered application.
+@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
For various reasons, you may find embedding @LaTeX{} math snippets in an
ODT document less than reliable. In that case, you can embed a
-math equation by linking to its MathML(@file{.mml}) source or its
+math equation by linking to its MathML (@file{.mml}) source or its
OpenDocument formula (@file{.odf}) file as shown below:
@example
@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export
@subsection Labels and captions in ODT export
-You can label and caption various category of objects - an inline image, a
-table, a @LaTeX{} fragment or a Math formula - using @code{#+LABEL} and
+You can label and caption various category of objects---an inline image, a
+table, a @LaTeX{} fragment or a Math formula---using @code{#+LABEL} and
@code{#+CAPTION} lines. @xref{Images and tables}. ODT exporter enumerates
each labeled or captioned object of a given category separately. As a
result, each such object is assigned a sequence number based on order of it's
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
Export of literal examples (@pxref{Literal examples}) with full fontification
is supported. Internally, the exporter relies on @file{htmlfontify.el} to
generate all style definitions needed for a fancy listing.@footnote{Your
-@file{htmlfontify.el} library must atleast be at Emacs 24.1 levels for
+@file{htmlfontify.el} library must at least be at Emacs 24.1 levels for
fontification to be turned on.} The auto-generated styles have @samp{OrgSrc}
as prefix and inherit their color from the faces used by Emacs
@code{font-lock} library for the source language.
-@vindex org-export-odt-fontify-srcblocks
-If you prefer to use your own custom styles for fontification, you can do so
-by customizing the variable
-@code{org-export-odt-create-custom-styles-for-srcblocks}.
+@vindex org-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
@item
It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
-elements that control how various entities - tables, images, equations etc -
-are numbered.
+elements that control how various entities---tables, images, equations,
+etc.---are numbered.
@end enumerate
@end itemize
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.
@enumerate
@item Embedding ODT tags as part of regular text
-You can include simple OpenDocument tags by prefixing them with
-@samp{@@}. For example, to highlight a region of text do the following:
+You can inline OpenDocument syntax by enclosing it within
+@samp{@@@@odt:...@@@@} markup. For example, to highlight a region of text do
+the following:
@example
-@@<text:span text:style-name="Highlight">This is a
-highlighted text@@</text:span>. But this is a
-regular text.
+@@@@odt:<text:span text:style-name="Highlight">This is a highlighted
+text</text:span>@@@@. But this is a regular text.
@end example
@strong{Hint:} To see the above example in action, edit your
-@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
+@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
custom @samp{Highlight} style as shown below.
@example
@end example
@strong{Hint:} To see the above example in action, edit your
-@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
+@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
custom @samp{PageBreak} style as shown below.
@example
<style:style style:name="PageBreak" style:family="paragraph"
- style:parent-style-name="Text_20_body">
+ style: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
-
-@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.
-@subsubheading Custom table styles - the nitty-gritty
+@subsubheading Custom table styles: the nitty-gritty
To use this feature proceed as follows:
@enumerate
@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
general help with validation (and schema-sensitive editing) of XML files:
@inforef{Introduction,,nxml-mode}.
-@vindex org-export-odt-schema-dir
+@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-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.
+@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.
@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 TaskJuggler file.
-
-@orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open}
-Export as 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}}.
-
-For more information and examples see the Org-taskjuggler tutorial at
-@uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.html}.
+@node Org export
+@section Org export
+@cindex Org export
-@node Freemind export, XOXO export, TaskJuggler export, Exporting
-@section Freemind export
-@cindex Freemind export
-@cindex mind map
+@code{org} export back-end creates a normalized version of the Org document
+in current buffer. In particular, it evaluates Babel code (@pxref{Evaluating
+code blocks}) and removes other back-ends specific contents.
-The Freemind exporter was written by Lennart Borgman.
+@subheading Org export commands
@table @kbd
-@orgcmd{C-c C-e m,org-export-as-freemind}
-Export as Freemind mind map. For an Org file @file{myfile.org}, the Freemind
-file will be @file{myfile.mm}.
-@end table
-
-@node XOXO export, iCalendar export, Freemind export, Exporting
-@section XOXO export
-@cindex XOXO export
-
-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.
-
-@table @kbd
-@orgcmd{C-c C-e x,org-export-as-xoxo}
-Export as 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.
+@orgcmd{C-c C-e O o,org-org-export-to-org}
+Export as an Org document. For an Org file, @file{myfile.org}, the resulting
+file will be @file{myfile.org.org}. The file will be overwritten without
+warning.
+@orgcmd{C-c C-e O O,org-org-export-as-org}
+Export to a temporary buffer. Do not create a file.
+@item C-c C-e O v
+Export to an Org file, then open it.
@end table
-@node iCalendar export, , XOXO export, Exporting
+@node iCalendar export, Other built-in back-ends, Org export, Exporting
@section iCalendar export
@cindex iCalendar export
in the standard iCalendar format. If you also want to have TODO entries
included in the export, configure the variable
@code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT,
-and TODO items as VTODO. It will also create events from deadlines that are
+and TODO items as VTODO@. It will also create events from deadlines that are
in non-TODO items. Deadlines and scheduling dates in TODO items will be used
to set the start and due dates for the TODO entry@footnote{See the variables
@code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}.
@code{org-icalendar-alarm-time} for a way to assign alarms to entries with a
time.
-@vindex org-icalendar-store-UID
-@cindex property, ID
-The iCalendar standard requires each entry to have a globally unique
-identifier (UID). Org creates these identifiers during export. If you set
-the variable @code{org-icalendar-store-UID}, the UID will be stored in the
-@code{:ID:} property of the entry and re-used next time you report this
-entry. Since a single entry can give rise to multiple iCalendar entries (as
-a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
-prefixes to the UID, depending on what triggered the inclusion of the entry.
-In this way the UID remains unique, but a synchronization program can still
-figure out from which entry all the different instances originate.
+@vindex org-icalendar-store-UID
+@cindex property, ID
+The iCalendar standard requires each entry to have a globally unique
+identifier (UID). Org creates these identifiers during export. If you set
+the variable @code{org-icalendar-store-UID}, the UID will be stored in the
+@code{:ID:} property of the entry and re-used next time you report this
+entry. Since a single entry can give rise to multiple iCalendar entries (as
+a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
+prefixes to the UID, depending on what triggered the inclusion of the entry.
+In this way the UID remains unique, but a synchronization program can still
+figure out from which entry all the different instances originate.
+
+@table @kbd
+@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 c a, org-icalendar-export-agenda-files}
+@vindex org-agenda-files
+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 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-icalendar-combined-agenda-file}.
+@end table
+
+@vindex org-use-property-inheritance
+@vindex org-icalendar-include-body
+@cindex property, SUMMARY
+@cindex property, DESCRIPTION
+@cindex property, LOCATION
+The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
+property can be inherited from higher in the hierarchy if you configure
+@code{org-use-property-inheritance} accordingly.} properties if the selected
+entries have them. If not, the summary will be derived from the headline,
+and the description from the body (limited to
+@code{org-icalendar-include-body} characters).
+
+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 aforementioned 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.
+@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 particularly useful for converting tables and lists in foreign
+buffers. E.g., in an 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)))
-@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
-directory, using a file extension @file{.ics}.
-@orgcmd{C-c C-e I, org-export-icalendar-all-agenda-files}
-@vindex org-agenda-files
-Like @kbd{C-c C-e i}, 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
-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}.
-@end table
+(add-to-list 'org-export-filter-plain-text-functions
+ 'my-latex-filter-nobreaks)
+@end group
+@end lisp
-@vindex org-use-property-inheritance
-@vindex org-icalendar-include-body
-@cindex property, SUMMARY
-@cindex property, DESCRIPTION
-@cindex property, LOCATION
-The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
-property can be inherited from higher in the hierarchy if you configure
-@code{org-use-property-inheritance} accordingly.} properties if the selected
-entries have them. If not, the summary will be derived from the headline,
-and the description from the body (limited to
-@code{org-icalendar-include-body} characters).
+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}).
-How this calendar is best read and updated, depends on the application
-you are using. The FAQ covers this issue.
+@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 behavior 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
@lisp
("project-name" :property value :property value ...)
- @r{i.e.@: a well-formed property list with alternating keys and values}
+ @r{i.e., a well-formed property list with alternating keys and values}
@r{or}
("project-name" :components ("project-name" "project-name" ...))
@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-container-element
+@vindex org-html-html5-fancy
+@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-link-use-abs-url
+@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-table-row-tags
+@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-container} @tab @code{org-html-container-element}
+@item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy}
+@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-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
+@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-table-row-tags} @tab @code{org-html-table-row-tags}
+@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
The file will be created when first publishing a project with the
-@code{:makeindex} set. The file only contains a statement @code{#+include:
+@code{:makeindex} set. The file only contains a statement @code{#+INCLUDE:
"theindex.inc"}. You can then build around this include statement by adding
a title, style information, etc.
that you can afford more easily to republish entire projects. If you set
@code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
benefit of re-including any changed external files such as source example
-files you might include with @code{#+INCLUDE}. The timestamp mechanism in
+files you might include with @code{#+INCLUDE:}. The timestamp mechanism in
Org is not smart enough to detect if included files have been modified.
@node Sample configuration, Triggering publication, Uploading files, Publishing
: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
@cindex source code, working with
Source code can be included in Org mode documents using a @samp{src} block,
-e.g.@:
+e.g.:
@example
#+BEGIN_SRC emacs-lisp
@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
It is possible to export the @emph{code} of code blocks, the @emph{results}
of code block evaluation, @emph{both} the code and the results of code block
evaluation, or @emph{none}. For most languages, the default exports code.
-However, for some languages (e.g.@: @code{ditaa}) the default exports the
+However, for some languages (e.g., @code{ditaa}) the default exports the
results of code block evaluation. For information on exporting code block
bodies, see @ref{Literal examples}.
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
@code{org-babel-results-keyword}.
By default, the evaluation facility is only enabled for Lisp code blocks
-specified as @code{emacs-lisp}. However, source code blocks in many languages
+specified as @code{emacs-lisp}. However, source code blocks in many languages
can be evaluated within Org mode (see @ref{Languages} for a list of supported
languages and @ref{Structure of code blocks} for information on the syntax
used to define a code block).
@kindex C-c C-c
There are a number of ways to evaluate code blocks. The simplest is to press
@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.
@cindex #+CALL
-It is also possible to evaluate named code blocks from anywhere in an
-Org mode buffer or an Org mode table. Live code blocks located in the current
+It is also possible to evaluate named code blocks from anywhere in an Org
+mode buffer or an Org mode table. Live code blocks located in the current
Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel})
can be executed. Named code blocks can be executed with a separate
@code{#+CALL:} line or inline within a block of text.
Language-specific documentation is available for some languages. If
available, it can be found at
-@uref{http://orgmode.org/worg/org-contrib/babel/languages}.
+@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)))
+ (cons '(:noweb . "yes")
+ (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.
-
-@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
+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: 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 behavior 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
-:END:
+ :PROPERTIES:
+ :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
@cindex #+HEADERS:
Multi-line header arguments on an un-named code block:
+
@example
#+HEADERS: :var data1=1
#+BEGIN_SRC emacs-lisp :var data2=2
(message "data1:%S, data2:%S" data1 data2)
#+END_SRC
- #+results:
+ #+RESULTS:
: data1:1, data2:2
@end example
Multi-line header arguments on a named code block:
+
@example
#+NAME: named-block
#+HEADER: :var data=2
(message "data:%S" data)
#+END_SRC
- #+results: named-block
+ #+RESULTS: named-block
: data:2
@end example
The following will apply the @code{:exports results} header argument to the
evaluation of the @code{#+CALL:} line.
+
@example
#+CALL: factorial(n=5) :exports results
@end example
The following will apply the @code{:session special} header argument to the
evaluation of the @code{factorial} code block.
+
@example
#+CALL: factorial[:session special](n=5)
@end example
* results:: Specify the type of results and how they will
be collected and handled
* file:: Specify a path for file output
+* file-desc:: Specify a description for file results
* dir:: Specify the default (possibly remote)
directory for code block execution
* exports:: Export code and/or results
* 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 |
(length table)
#+END_SRC
-#+results: table-length
+#+RESULTS: table-length
: 4
@end example
(print x)
#+END_SRC
-#+results:
+#+RESULTS:
| simple | list |
@end example
(* 2 length)
#+END_SRC
-#+results:
+#+RESULTS:
: 8
@end example
(* 2 input)
#+END_SRC
-#+results: double
+#+RESULTS: double
: 16
#+NAME: squared
(* input input)
#+END_SRC
-#+results: squared
+#+RESULTS: squared
: 4
@end example
(concatenate 'string x " for you.")
#+END_SRC
-#+results: read-literal-example
+#+RESULTS: read-literal-example
: A literal example
: on two lines for you.
@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
data
#+END_SRC
-#+results:
+#+RESULTS:
: a
@end example
data
#+END_SRC
-#+results:
+#+RESULTS:
| 2 | b |
| 3 | c |
| 4 | d |
data
#+END_SRC
-#+results:
+#+RESULTS:
| 1 | 2 | 3 | 4 |
@end example
data
#+END_SRC
-#+results:
+#+RESULTS:
| 11 | 14 | 17 |
@end example
$data
#+END_SRC
-#+results:
+#+RESULTS:
: (a b c)
@end example
@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}.
-@item @code{raw}, @code{org}
+@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
such by Org mode. E.g., @code{:results value raw}.
+@item @code{org}
+The results are will be enclosed in a @code{BEGIN_SRC org} block.
+They are not comma-escaped by default but they will be if you hit @kbd{TAB}
+in the block and/or if you export the file. E.g., @code{:results value org}.
@item @code{html}
-Results are assumed to be HTML and will be enclosed in a @code{begin_html}
+Results are assumed to be HTML and will be enclosed in a @code{BEGIN_HTML}
block. E.g., @code{:results value html}.
@item @code{latex}
-Results assumed to be @LaTeX{} and are enclosed in a @code{begin_latex} block.
+Results assumed to be @LaTeX{} and are enclosed in a @code{BEGIN_LaTeX} block.
E.g., @code{:results value latex}.
@item @code{code}
Result are assumed to be parsable code and are enclosed in a code block.
The result is converted to pretty-printed code and is enclosed in a code
block. This option currently supports Emacs Lisp, Python, and Ruby. E.g.,
@code{:results value pp}.
-@item @code{wrap}
+@item @code{drawer}
The result is wrapped in a RESULTS drawer. This can be useful for
inserting @code{raw} or @code{org} syntax results in such a way that their
extent is known and they can be automatically removed or replaced.
inserted as with @code{replace}.
@end itemize
-@node file, dir, results, Specific header arguments
+@node file, file-desc, results, Specific header arguments
@subsubsection @code{:file}
The header argument @code{:file} is used to specify an external file in which
a file, or a list of two strings in which case the first element of the list
should be the path to a file and the second a description for the link.
-@node dir, exports, file, Specific header arguments
+@node file-desc, dir, file, Specific header arguments
+@subsubsection @code{:file-desc}
+
+The value of the @code{:file-desc} header argument is used to provide a
+description for file code block results which are inserted as Org mode links
+(see @ref{Link format}). If the @code{:file-desc} header argument is given
+with no value the link path will be placed in both the ``link'' and the
+``description'' portion of the Org mode link.
+
+@node dir, exports, file-desc, Specific header arguments
@subsubsection @code{:dir} and remote execution
While the @code{:file} header argument can be used to specify the path to the
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}.
When using @code{:dir}, you should supply a relative path for file output
-(e.g.@: @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
+(e.g., @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
case that path will be interpreted relative to the default directory.
In other words, if you want your plot to go into a folder called @file{Work}
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}
@node noweb, noweb-ref, session, Specific header arguments
@subsubsection @code{:noweb}
-The @code{:noweb} header argument controls expansion of ``noweb'' style (see
-@ref{Noweb reference syntax}) references in a code block. This header
-argument can have one of three values: @code{yes}, @code{no}, or @code{tangle}.
+The @code{:noweb} header argument controls expansion of ``noweb'' syntax
+references (see @ref{Noweb reference syntax}) when the code block is
+evaluated, tangled, or exported. The @code{:noweb} header argument can have
+one of the five values: @code{no}, @code{yes}, @code{tangle}, or
+@code{no-export} @code{strip-export}.
@itemize @bullet
-@item @code{yes}
-All ``noweb'' syntax references in the body of the code block will be
-expanded before the block is evaluated, tangled or exported.
@item @code{no}
-The default. No ``noweb'' syntax specific action is taken when the code
-block is evaluated, tangled or exported.
+The default. ``Noweb'' syntax references in the body of the code block will
+not be expanded before the code block is evaluated, tangled or exported.
+@item @code{yes}
+``Noweb'' syntax references in the body of the code block will be
+expanded before the code block is evaluated, tangled or exported.
@item @code{tangle}
-All ``noweb'' syntax references in the body of the code block will be
-expanded before the block is tangled, however ``noweb'' references will not
-be expanded when the block is evaluated or exported.
+``Noweb'' syntax references in the body of the code block will be expanded
+before the code block is tangled. However, ``noweb'' syntax references will
+not be expanded when the code block is evaluated or exported.
+@item @code{no-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 expanded when the code block is exported.
+@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 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.
@end itemize
@subsubheading Noweb prefix lines
-- <<example>>
@end example
-
expands to:
@example
unchanged code blocks. Note that the @code{:cache} header argument will not
attempt to cache results when the @code{:session} header argument is used,
because the results of the code block execution may be stored in the session
-outside of the Org-mode buffer. The @code{:cache} header argument can have
+outside of the Org mode buffer. The @code{:cache} header argument can have
one of two values: @code{yes} or @code{no}.
@itemize @bullet
@item @code{yes}
Every time the code block is run a SHA1 hash of the code and arguments
passed to the block will be generated. This hash is packed into the
-@code{#+results:} line and will be checked on subsequent
+@code{#+RESULTS:} line and will be checked on subsequent
executions of the code block. If the code block has not
changed since the last time it was evaluated, it will not be re-evaluated.
@end itemize
runif(1)
#+END_SRC
- #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
+ #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
0.4659510825295
#+NAME: caller
x
#+END_SRC
- #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
+ #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
0.254227238707244
@end example
default value yields the following results.
@example
-#+TBLNAME: many-cols
+#+NAME: many-cols
| a | b | c |
|---+---+---|
| d | e | f |
return tab
#+END_SRC
-#+results: echo-table
+#+RESULTS: echo-table
| a | b | c |
| d | e | f |
| g | h | i |
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 |
return tab
#+END_SRC
-#+results: echo-table
+#+RESULTS: echo-table
| 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 |
return [[val + '*' for val in row] for row in tab]
#+END_SRC
-#+results: echo-table-again
+#+RESULTS: echo-table-again
| a |
|----|
| b* |
@item @code{yes}
Column names are removed and reapplied as with @code{nil} even if the table
-does not ``look like'' it has column names (i.e.@: the second row is not an
+does not ``look like'' it has column names (i.e., the second row is not an
hline)
@end itemize
@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 |
return [[val + 10 for val in row] for row in tab]
#+END_SRC
-#+results: echo-table-once-again
+#+RESULTS: echo-table-once-again
| one | 11 | 12 | 13 | 14 | 15 |
| two | 16 | 17 | 18 | 19 | 20 |
@end example
@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
-(e.g.@: @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
+(e.g., @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
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, , 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, 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
+to @code{#+BEGIN_} and @code{#+END_}, which will then be used to wrap the
+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
print "bye"
#+END_SRC
-#+results:
+#+RESULTS:
: hello
: bye
@end example
In non-session mode, the `2' is not printed and does not appear.
+
@example
#+BEGIN_SRC python :results output :session
print "hello"
print "bye"
#+END_SRC
-#+results:
+#+RESULTS:
: hello
: 2
: bye
syntactically valid in languages that you use, then please consider setting
the default value.
-Note: if noweb tangling is slow in large Org-mode files consider setting the
-@code{*org-babel-use-quick-and-dirty-noweb-expansion*} variable to true.
+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 @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.
#
DIR=`pwd`
FILES=""
-ORGINSTALL="~/src/org/lisp/org-install.el"
# wrap each argument in the code required to call tangle on it
for i in $@@; do
FILES="$FILES \"$i\""
done
-emacs -Q --batch -l $ORGINSTALL \
+emacs -Q --batch \
--eval "(progn
(add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
-(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\"))
+(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\" t))
(require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
(mapc (lambda (file)
(find-file (expand-file-name file \"$DIR\"))
* 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
will insert example settings for this keyword.
@item
In the line after @samp{#+STARTUP: }, complete startup keywords,
-i.e.@: valid keys for this line.
+i.e., valid keys for this line.
@item
Elsewhere, complete dictionary words using Ispell.
@end itemize
The following template selectors are currently supported.
@multitable @columnfractions 0.1 0.9
-@item @kbd{s} @tab @code{#+begin_src ... #+end_src}
-@item @kbd{e} @tab @code{#+begin_example ... #+end_example}
-@item @kbd{q} @tab @code{#+begin_quote ... #+end_quote}
-@item @kbd{v} @tab @code{#+begin_verse ... #+end_verse}
-@item @kbd{c} @tab @code{#+begin_center ... #+end_center}
-@item @kbd{l} @tab @code{#+begin_latex ... #+end_latex}
-@item @kbd{L} @tab @code{#+latex:}
-@item @kbd{h} @tab @code{#+begin_html ... #+end_html}
-@item @kbd{H} @tab @code{#+html:}
-@item @kbd{a} @tab @code{#+begin_ascii ... #+end_ascii}
-@item @kbd{A} @tab @code{#+ascii:}
-@item @kbd{i} @tab @code{#+index:} line
-@item @kbd{I} @tab @code{#+include:} line
+@item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC}
+@item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
+@item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE}
+@item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE}
+@item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER}
+@item @kbd{l} @tab @code{#+BEGIN_LaTeX ... #+END_LaTeX}
+@item @kbd{L} @tab @code{#+LaTeX:}
+@item @kbd{h} @tab @code{#+BEGIN_HTML ... #+END_HTML}
+@item @kbd{H} @tab @code{#+HTML:}
+@item @kbd{a} @tab @code{#+BEGIN_ASCII ... #+END_ASCII}
+@item @kbd{A} @tab @code{#+ASCII:}
+@item @kbd{i} @tab @code{#+INDEX:} line
+@item @kbd{I} @tab @code{#+INCLUDE:} line
@end multitable
For example, on an empty line, typing "<e" and then pressing TAB, will expand
@vindex org-speed-commands-user
Single keys can be made to execute commands when the cursor is at the
-beginning of a headline, i.e.@: before the first star. Configure the variable
+beginning of a headline, i.e., before the first star. Configure the variable
@code{org-use-speed-commands} to activate this feature. There is a
pre-defined list of commands, and you can add more such commands using the
variable @code{org-speed-commands-user}. Speed keys do not only speed up
@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
@cindex options, for customization
@cindex variables, for customization
-There are more than 180 variables that can be used to customize
+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}).
top-level entries.
@item #+DRAWERS: NAME1 .....
@vindex org-drawers
-Set the file-local set of drawers. The corresponding global variable is
-@code{org-drawers}.
+Set the file-local set of additional drawers. The corresponding global
+variable is @code{org-drawers}.
@item #+LINK: linkword replace
@vindex org-link-abbrev-alist
These lines (several are allowed) specify link abbreviations.
@vindex org-lowest-priority
@vindex org-default-priority
This line sets the limits and the default for the priorities. All three
-must be either letters A-Z or numbers 0-9. The highest priority must
+must be either letters A--Z or numbers 0--9. The highest priority must
have a lower ASCII number than the lowest priority.
@item #+PROPERTY: Property_Name Value
This line sets a default inheritance value for entries in the current
@item #+SETUPFILE: file
This line defines a file that holds more in-buffer setup. Normally this is
entirely ignored. Only when the buffer is parsed for option-setting lines
-(i.e.@: when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
+(i.e., when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
settings line, or when exporting), then the contents of this file are parsed
as if they had been included in the buffer. In particular, the file can be
any other Org mode file with internal setup. You can visit the file the
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
stars but the last one are made invisible using the @code{org-hide}
face@footnote{Turning on @code{org-indent-mode} sets
@code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
-@code{nil}.} - see below under @samp{2.} for more information on how this
+@code{nil}.}; see below under @samp{2.} for more information on how this
works. You can turn on @code{org-indent-mode} for all files by customizing
the variable @code{org-startup-indented}, or you can turn it on for
individual files using
Things become cleaner still if you skip all the even levels and use only odd
levels 1, 3, 5..., effectively adding two stars to go from one outline level
to the next@footnote{When you need to specify a level for a property search
-or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}. In this
+or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}. In this
way we get the outline view shown at the beginning of this section. In order
to make the structure editing and export commands handle this convention
correctly, configure the variable @code{org-odd-levels-only}, or set this on
@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
constants in the variable @code{org-table-formula-constants}, install
the @file{constants} package which defines a large number of constants
and units, and lets you use unit prefixes like @samp{M} for
-@samp{Mega}, etc@. You will need version 2.0 of this package, available
+@samp{Mega}, etc. You will need version 2.0 of this package, available
at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for
the function @code{constants-get}, which has to be autoloaded in your
setup. See the installation instructions in the file
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}
+
+Org mode tries to do the right thing when filling paragraphs, list items and
+other elements. Many users reported they had problems using both
+@file{filladapt.el} and Org mode, so a safe thing to do is to disable it like
+this:
+
+@lisp
+(add-hook 'org-mode-hook 'turn-off-filladapt-mode)
+@end lisp
+
@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
(defun yas/org-very-safe-expand ()
- (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
+ (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
@end lisp
Then, tell Org mode what to do with the new function:
@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.
Org.
@menu
-* Hooks:: Who to reach into Org's internals
+* 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
buffer with @kbd{C-c C-l}.
When it makes sense for your new link type, you may also define a function
-@code{org-PREFIX-complete-link} that implements special (e.g.@: completion)
+@code{org-PREFIX-complete-link} that implements special (e.g., completion)
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 */
Please note that the translator function sees the table @emph{after} the
removal of these columns, the function never knows that there have been
additional columns.
+
+@item :no-escape t
+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 inserted between the two marker lines.
Now let's assume you want to make the table header by hand, because you
-want to control how columns are aligned, etc@. In this case we make sure
+want to control how columns are aligned, etc. In this case we make sure
that the table translator skips the first 2 lines of the source
-table, and tell the command to work as a @i{splice}, i.e.@: to not produce
+table, and tell the command to work as a @i{splice}, i.e., to not produce
header and footer commands of the target table:
@example
@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
As you can see, the properties passed into the function (variable
@var{PARAMS}) are combined with the ones newly defined in the function
-(variable @var{PARAMS2}). The ones passed into the function (i.e.@: the
+(variable @var{PARAMS2}). The ones passed into the function (i.e., the
ones set by the @samp{ORGTBL SEND} line) take precedence. So if you
would like to use the @LaTeX{} translator, but wanted the line endings to
be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
\end@{comment@}
@end example
-Pressing `C-c C-c' on @code{a new house} and will insert the converted
+Pressing @kbd{C-c C-c} on @code{a new house} and will insert the converted
@LaTeX{} list between the two marker lines.
@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
@lisp
(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)))))
+ (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
+ (insert "Last block update at: "
+ (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
marked all tree headings that define a project with the TODO keyword
-PROJECT. In this case you would run a TODO search for the keyword
+PROJECT@. In this case you would run a TODO search for the keyword
PROJECT, but skip the match unless there is a WAITING tag anywhere in
the subtree belonging to the project line.
Skip current entry if the TODO keyword marks a DONE state.
@item (org-agenda-skip-entry-if 'timestamp)
Skip current entry if it has any timestamp, may also be deadline or scheduled.
-@item (org-agenda-skip-entry 'regexp "regular expression")
+@anchor{x-agenda-skip-entry-regexp}
+@item (org-agenda-skip-entry-if 'regexp "regular expression")
Skip current entry if the regular expression matches in the entry.
-@item (org-agenda-skip-entry 'notregexp "regular expression")
+@item (org-agenda-skip-entry-if 'notregexp "regular expression")
Skip current entry unless the regular expression matches.
@item (org-agenda-skip-subtree-if 'regexp "regular expression")
Same as above, but check and skip the entire subtree.
(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 slowness caused
+by accessing 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
directly to a printer, or it can be read by a program that does further
processing of the data. The first of these commands is the function
@code{org-batch-agenda}, that produces an agenda view and sends it as
-ASCII text to STDOUT. The command takes a single string as parameter.
+ASCII text to STDOUT@. The command takes a single string as parameter.
If the string has length 1, it is used as a key to one of the commands
you have configured in @code{org-agenda-custom-commands}, basically any
key you can use after @kbd{C-c a}. For example, to directly print the
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-insert-property-drawer
-Insert a property drawer at point.
+Insert a property drawer for the current entry. Also
@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
@lisp
(org-map-entries
- '(org-todo "UPCOMING")
- "+TOMORROW" 'file 'archive 'comment)
+ '(org-todo "UPCOMING")
+ "+TOMORROW" 'file 'archive 'comment)
@end lisp
The following example counts the number of entries with TODO keyword
@cindex iPhone
@cindex MobileOrg
-@uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the
-@i{iPhone/iPod Touch} series of devices, developed by Richard Moreland.
-@i{MobileOrg} offers offline viewing and capture support for an Org mode
-system rooted on a ``real'' computer. It does also allow you to record
-changes to existing entries. Android users should check out
+@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{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.
+by Matt Jones. The two implementations are not identical but offer similar
+features.
This appendix describes the support Org has for creating agenda views in a
format that can be displayed by @i{MobileOrg}, and for integrating notes
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
all agenda files (as listed in @code{org-agenda-files}), but additional files
can be included by customizing @code{org-mobile-files}. File names will be
staged with paths relative to @code{org-directory}, so all files should be
-inside this directory. The push operation also creates a special Org file
-@file{agendas.org} with all custom agenda view defined by the
-user@footnote{While creating the agendas, Org mode will force ID properties
-on all referenced entries, so that these entries can be uniquely identified
-if @i{MobileOrg} flags them for further action. If you do not want to get
-these properties in so many entries, you can set the variable
-@code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then
-rely on outline paths, in the hope that these will be unique enough.}.
+inside this directory@footnote{Symbolic links in @code{org-directory} need to
+have the same name than their targets.}.
+
+The push operation also creates a special Org file @file{agendas.org} with
+all custom agenda view defined by the user@footnote{While creating the
+agendas, Org mode will force ID properties on all referenced entries, so that
+these entries can be uniquely identified if @i{MobileOrg} flags them for
+further action. If you do not want to get these properties in so many
+entries, you can set the variable @code{org-mobile-force-id-on-agenda-items}
+to @code{nil}. Org mode will then rely on outline paths, in the hope that
+these will be unique enough.}.
+
Finally, Org writes the file @file{index.org}, containing links to all other
files. @i{MobileOrg} first reads this file from the server, and then
downloads all agendas and Org files listed in it. To speed up the download,
-MobileOrg will only read files whose checksums@footnote{stored automatically
-in the file @file{checksums.dat}} have changed.
+MobileOrg will only read files whose checksums@footnote{Checksums are stored
+automatically in the file @file{checksums.dat}} have changed.
@node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg
@section Pulling from MobileOrg
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, Main Index, MobileOrg, Top
+@node History and Acknowledgments, GNU Free Documentation License, MobileOrg, Top
@appendix History and acknowledgments
@cindex acknowledgments
@cindex history
@cindex thanks
+@section From Carsten
+
Org was born in 2003, out of frustration over the user interface of the Emacs
Outline mode. I was trying to organize my notes and projects, and using
Emacs seemed to be the natural way to go. However, having to remember eleven
integrated into the core by now), including the @LaTeX{} exporter and the plain
list parser. His support during the early days, when he basically acted as
co-maintainer, was central to the success of this project. Bastien also
-invented Worg, helped establishing the Web presence of Org, and sponsors
+invented Worg, helped establishing the Web presence of Org, and sponsored
hosting costs for the orgmode.org website.
@item Eric Schulte and Dan Davison
Eric and Dan are jointly responsible for the Org-babel system, which turns
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
-@noindent OK, now to the full list of contributions! Again, please let me
-know what I am missing here!
+@noindent See below for the full list of contributions! Again, please
+let me know what I am missing here!
+
+@section From Bastien
+
+I (Bastien) have been maintaining Org since January 2011. This appendix
+would not be complete without adding a few more acknowledgements and thanks
+to Carsten's ones above.
+
+I am first grateful to Carsten for his trust while handing me over the
+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
+knowledgeable than I am on many parts of the code. Here is a list of the
+persons I could rely on, they should really be considered co-maintainers,
+either of the code or the community:
+
+@table @i
+@item Eric Schulte
+Eric is maintaining the Babel parts of Org. His reactivity here kept me away
+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{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
+into a flexible and conceptually clean process. He patiently coped with the
+many hiccups that such a change can create for users.
+
+@item Nick Dokos
+The Org mode mailing list would not be such a nice place without Nick, who
+patiently helped users so many times. It is impossible to overestimate such
+a great help, and the list would not be so active without him.
+@end table
+
+I received support from so many users that it is clearly impossible to be
+fair when shortlisting a few of them, but Org's history would not be
+complete if the ones above were not mentioned in this manual.
+
+@section List of contributions
@itemize @bullet
@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 sponsored 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.
@item
@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
and contributed various ideas and code snippets.
-@item
@end itemize
-@node Main Index, Key Index, History and Acknowledgments, Top
+@node GNU Free Documentation License, Main Index, History and Acknowledgments, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@node Main Index, Key Index, GNU Free Documentation License, Top
@unnumbered Concept index
@printindex cp