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