-
\input texinfo
@c %**start of header
@setfilename ../../info/org
@settitle The Org Manual
-
-@set VERSION 7.8.03
-@set DATE January 2012
+@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
(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
@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
* 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
* Special symbols:: Greek letters and other symbols
* Subscripts and superscripts:: Simple syntax for raising/lowering text
-* @LaTeX{} fragments:: Complex formulas made easy
+* @LaTeX{} fragments:: Complex formulas made easy
* Previewing @LaTeX{} fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
OpenDocument Text export
-* Pre-requisites for @acronym{ODT} export:: What packages @acronym{ODT} exporter relies on
-* @acronym{ODT} export commands:: How to invoke @acronym{ODT} 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 @acronym{ODT} export:: How links will be interpreted and formatted
-* Tables in @acronym{ODT} export:: How Tables are exported
-* Images in @acronym{ODT} export:: How to insert images
-* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted
-* Literal examples in @acronym{ODT} export:: How source and example blocks are formatted
-* Advanced topics in @acronym{ODT} export:: Read this if you are a power user
+* Links in ODT export:: How links will be interpreted and formatted
+* Tables in ODT export:: How Tables are exported
+* Images in ODT export:: How to insert images
+* Math formatting in ODT export:: How @LaTeX{} fragments are formatted
+* Labels and captions in ODT export:: How captions are rendered
+* Literal examples in ODT export:: How source and example blocks are formatted
+* Advanced topics in ODT export:: Read this if you are a power user
-Math formatting in @acronym{ODT} export
+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 @acronym{ODT} export
+Advanced topics in ODT export
-* Exporting and converting to other formats:: How to produce @samp{pdf} and other formats
+* 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 @acronym{ODT} export:: How to define and use Table templates
+* Customizing tables in ODT export:: How to define and use Table templates
* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
Publishing
* 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
* 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
-@noindent Now byte-compile the Lisp files with the shell command:
+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
+
+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
@end example
However if you are using Org mode as distributed with Emacs, a minimal setup
-is not necessary. In that case it is sufficient to start Emacs as @code{emacs
--Q}. The @code{minimal-org.el} setup file can have contents as shown below.
+is not necessary. In that case it is sufficient to start Emacs as
+@code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
+shown below.
@example
;;; Minimal setup to load latest `org-mode'
;; add latest org-mode to load path
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
-(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp"))
-
-;; activate org
-(require 'org-install)
+(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
@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
(@pxref{Agenda commands}). With a prefix argument show, on each
level, all sibling headings. With a double prefix argument, also show the
entire subtree of the parent.
+@cindex show branches, command
@orgcmd{C-c C-k,show-branches}
Expose all the headings of the subtree, CONTENT view for just one subtree.
+@cindex show children, command
+@orgcmd{C-c @key{TAB},show-children}
+Expose all direct children of the subtree. With a numeric prefix argument N,
+expose all children down to level N@.
@orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
Show the current subtree in an indirect buffer@footnote{The indirect
buffer
@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}
@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
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
@cindex visibility cycling, drawers
@vindex org-drawers
+@cindex org-insert-drawer
+@kindex C-c C-x d
Sometimes you want to keep information associated with an entry, but you
normally don't want to see it. For this, Org mode has @emph{drawers}.
Drawers need to be configured with the variable
-@code{org-drawers}@footnote{You can define drawers on a per-file basis
-with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers
+@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
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
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}
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:
@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
| # | 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
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}
@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.
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.
state.
@cindex completion, of TODO keywords
With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
-to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may
+to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
also use a numeric prefix argument to quickly select a specific state. For
-example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
+example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
define many keywords, you can use in-buffer completion
(@pxref{Completion}) or even a special one-key selection scheme
In this case, different keywords do not indicate a sequence, but rather
different types. So the normal work flow would be to assign a task to a
-person, and later to mark it DONE. Org mode supports this style by adapting
+person, and later to mark it DONE@. Org mode supports this style by adapting
the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
@kbd{t} command in the timeline and agenda buffers.}. When used several
times in succession, it will still cycle through all names, in order to first
select the right type for a task. But when you return to the item after some
time and execute @kbd{C-c C-t} again, it will switch from any name directly
-to DONE. Use prefix arguments or completion to quickly select a specific
+to DONE@. Use prefix arguments or completion to quickly select a specific
name. You can also review the items of a specific TODO type in a sparse tree
by using a numeric prefix to @kbd{C-c / t}. For example, to see all things
Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items
@subsection Fast access to TODO states
If you would like to quickly change an entry to an arbitrary TODO state
-instead of cycling through the states, you can set up keys for
-single-letter access to the states. This is done by adding the section
-key after each keyword, in parentheses. For example:
+instead of cycling through the states, you can set up keys for single-letter
+access to the states. This is done by adding the selection character after
+each keyword, in parentheses@footnote{All characters are allowed except
+@code{@@^!}, which have a special meaning here.}. For example:
@lisp
(setq org-todo-keywords
@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
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
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
@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.
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
@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
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
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
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
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 table
Note that @code{org-schedule} and @code{org-deadline} supports
-setting the date by indicating a relative time: e.g. +1d will set
+setting the date by indicating a relative time: e.g., +1d will set
the date to the next day after today, and --1w will set the date
to the previous week before any current timestamp.
@noindent
the @code{+1m} is a repeater; the intended interpretation is that the task
has a deadline on <2005-10-01> and repeats itself every (one) month starting
-from that time. If you need both a repeater and a special warning period in
-a deadline entry, the repeater should come first and the warning period last:
-@code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
+from that time. You can use yearly, monthly, weekly, daily and hourly repeat
+cookies by using the @code{y/w/m/d/h} letters. If you need both a repeater
+and a special warning period in a deadline entry, the repeater should come
+first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
@vindex org-todo-repeat-to-state
Deadlines and scheduled items produce entries in the agenda when they are
@cindex time clocking
Org mode allows you to clock the time you spend on specific tasks in a
-project. When you start working on an item, you can start the clock.
-When you stop working on that task, or when you mark the task done, the
-clock is stopped and the corresponding time interval is recorded. It
-also computes the total time spent on each subtree of a project. And it
-remembers a history or tasks recently clocked, to that you can jump quickly
-between a number of tasks absorbing your time.
+project. When you start working on an item, you can start the clock. When
+you stop working on that task, or when you mark the task done, the clock is
+stopped and the corresponding time interval is recorded. It also computes
+the total time spent on each subtree@footnote{Clocking only works if all
+headings are indented with less than 30 stars. This is a hardcoded
+limitation of `lmax' in `org-clock-sum'.} of a project. And it remembers a
+history or tasks recently clocked, to that you can jump quickly between a
+number of tasks absorbing your time.
To save the clock history across Emacs sessions, use
@lisp
@table @kbd
@orgcmd{C-c C-x C-i,org-clock-in}
@vindex org-clock-into-drawer
+@vindex org-clock-continuously
@cindex property, LOG_INTO_DRAWER
Start the clock on the current item (clock-in). This inserts the CLOCK
keyword together with a timestamp. If this is not the first clocking of
@code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
When called with a @kbd{C-u} prefix argument,
select the task from a list of recently clocked tasks. With two @kbd{C-u
-C-u} prefixes, clock into the task at point and mark it as the default task.
-The default task will always be available when selecting a clocking task,
-with letter @kbd{d}.@*
+C-u} prefixes, clock into the task at point and mark it as the default task;
+the default task will then always be available with letter @kbd{d} when
+selecting a clocking task. With three @kbd{C-u C-u C-u} prefixes, force
+continuous clocking by starting the clock when the last clock stopped.@*
@cindex property: CLOCK_MODELINE_TOTAL
@cindex property: LAST_REPEAT
@vindex org-clock-modeline-total
possibility to record an additional note together with the clock-out
timestamp@footnote{The corresponding in-buffer setting is:
@code{#+STARTUP: lognoteclock-out}}.
+@orgcmd{C-c C-x C-x,org-clock-in-last}
+@vindex org-clock-continuously
+Reclock the last clocked task. With one @kbd{C-u} prefix argument,
+select the task from the clock history. With two @kbd{C-u} prefixes,
+force continuous clocking by starting the clock when the last clock
+stopped.
@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
Update the effort estimate for the current clock task.
@kindex C-c C-y
is only necessary if you edit the timestamps directly. If you change
them with @kbd{S-@key{cursor}} keys, the update is automatic.
@orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
-On @code{CLOCK} log lines, increase/decrease both timestamps at the same
-time so that duration keeps the same.
+On @code{CLOCK} log lines, increase/decrease both timestamps so that the
+clock duration keeps the same.
+@orgcmd{S-M-@key{up/down},org-timestamp-up/down}
+On @code{CLOCK} log lines, increase/decrease the timestamp at point and
+the one of the previous (or the next clock) timestamp by the same duration.
+For example, if you hit @kbd{S-M-@key{up}} to increase a clocked-out timestamp
+by five minutes, then the clocked-in timestamp of the next clock will be
+increased by five minutes.
@orgcmd{C-c C-t,org-todo}
Changing the TODO state of an item to DONE automatically stops the clock
if it is running in this same item.
-@orgcmd{C-c C-x C-x,org-clock-cancel}
+@orgcmd{C-c C-x C-q,org-clock-cancel}
Cancel the current clock. This is useful if a clock was started by
mistake, or if you ended up working on something else.
@orgcmd{C-c C-x C-j,org-clock-goto}
the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
worked on or closed during a day.
+@strong{Important:} note that both @code{org-clock-out} and
+@code{org-clock-in-last} can have a global keybinding and will not
+modify the window disposition.
+
@node The clock table, Resolving idle time, Clocking commands, Clocking work time
@subsection The clock table
@cindex clocktable, dynamic block
@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
By customizing the variable @code{org-clock-idle-time} to some integer, such
as 10 or 15, Emacs can alert you when you get back to your computer after
being idle for that many minutes@footnote{On computers using Mac OS X,
-idleness is based on actual user idleness, not just Emacs's idle time. For
+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
* 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
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
@end table
@end table
-@node Template expansion, , Template elements, Capture templates
+@node Template expansion, Templates in contexts, Template elements, Capture templates
@subsubsection Template expansion
In the template itself, special @kbd{%}-escapes@footnote{If you need one of
-these sequences literally, escape the @kbd{%} with a backslash.} allow
+these sequences literally, escape the @kbd{%} with a backslash.} allow
dynamic insertion of content. The templates are expanded in the order given here:
@smallexample
-%[@var{file}] @r{insert the contents of the file given by @var{file}.}
-%(@var{sexp}) @r{evaluate Elisp @var{sexp} and replace with the result.}
-%<...> @r{the result of format-time-string on the ... format specification.}
-%t @r{timestamp, date only.}
-%T @r{timestamp with date and time.}
-%u, %U @r{like the above, but inactive timestamps.}
-%a @r{annotation, normally the link created with @code{org-store-link}.}
-%i @r{initial content, the region when capture is called while the}
+%[@var{file}] @r{Insert the contents of the file given by @var{file}.}
+%(@var{sexp}) @r{Evaluate Elisp @var{sexp} and replace with the result.}
+ @r{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
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
@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.
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
@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.
Delete other windows.
@c
@orgcmdkskc{v d,d,org-agenda-day-view}
-@xorgcmdkskc{v w,w,org-agenda-day-view}
+@xorgcmdkskc{v w,w,org-agenda-week-view}
@xorgcmd{v 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
covered by the current agenda view. The initial setting for this mode in new
agenda buffers can be set with the variable
@code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
-when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show
+when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
contributions from entries that are hidden by agenda filtering@footnote{Only
tags filtering will be respected here, effort filtering is ignored.}. See
also the variable @code{org-clock-report-include-clocking-task}.
@orgcmd{C-c C-d,org-agenda-deadline}
Set a deadline for this item. With prefix arg remove the deadline.
@c
-@orgcmd{k,org-agenda-action}
-Agenda actions, to set dates for selected items to the cursor date.
-This command also works in the calendar! The command prompts for an
-additional key:
-@example
-m @r{Mark the entry at point for action. You can also make entries}
- @r{in Org files with @kbd{C-c C-x C-k}.}
-d @r{Set the deadline of the marked entry to the date at point.}
-s @r{Schedule the marked entry at the date at point.}
-r @r{Call @code{org-capture} with the cursor date as default date.}
-@end example
-@noindent
-Press @kbd{r} afterward to refresh the agenda and see the effect of the
-command.
-@c
@orgcmd{S-@key{right},org-agenda-do-date-later}
Change the timestamp associated with the current line by one day into the
future. If the date is in the past, the first call to this command will move
@c
@orgcmd{J,org-agenda-clock-goto}
Jump to the running clock in another window.
+@c
+@orgcmd{k,org-agenda-capture}
+Like @code{org-capture}, but use the date at point as the default date for
+the capture template. See @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 ()}
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
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
you want to do this only occasionally, use the command
@table @kbd
-@orgcmd{C-x C-w,org-write-agenda}
+@orgcmd{C-x C-w,org-agenda-write}
@cindex exporting agenda views
@cindex agenda views, exporting
@vindex org-agenda-exporter-settings
applications for column view in the agenda. If you want information about
clocked time in the displayed period use clock table mode (press @kbd{R} in
the agenda).
+
+@item
+@cindex property, special, CLOCKSUM_T
+When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
+always today's clocked time for this item. So even in the weekly agenda,
+the clocksum listed in column view only originates from today. This lets
+you compare the time you spent on a task for today, with the time already
+spent (via @code{CLOCKSUM}) and with the planned total effort for it.
@end enumerate
@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 ;
@example
#+CAPTION: This is the caption for the next table (or link)
-#+LABEL: tbl:basic-data
+#+LABEL: tab:basic-data
| ... | ...|
|-----|----|
@end example
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
achieved using either the listings or the
-@url{http://code.google.com/p/minted, minted,} package. To use listings, turn
-on the variable @code{org-export-latex-listings} and ensure that the listings
-package is included by the @LaTeX{} header (e.g.@: by configuring
-@code{org-export-latex-packages-alist}). See the listings documentation for
-configuration options, including obtaining colored output. For minted it is
-necessary to install the program @url{http://pygments.org, pygments}, in
-addition to setting @code{org-export-latex-minted}, ensuring that the minted
-package is included by the @LaTeX{} header, and ensuring that the
-@code{-shell-escape} option is passed to @file{pdflatex} (see
-@code{org-latex-to-pdf-process}). See the documentation of the variables
-@code{org-export-latex-listings} and @code{org-export-latex-minted} for
-further details.}. This is done with the @samp{src} block, where you also
-need to specify the name of the major mode that should be used to fontify the
-example@footnote{Code in @samp{src} blocks may also be evaluated either
-interactively or on export. See @pxref{Working With Source Code} for more
-information on evaluating code blocks.}, see @ref{Easy Templates} for
-shortcuts to easily insert code blocks.
+@url{http://code.google.com/p/minted, minted,} package. Refer to
+@code{org-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.
@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
@menu
* Special symbols:: Greek letters and other symbols
* Subscripts and superscripts:: Simple syntax for raising/lowering text
-* @LaTeX{} fragments:: Complex formulas made easy
+* @LaTeX{} fragments:: Complex formulas made easy
* Previewing @LaTeX{} fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
@end menu
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
broad range of other applications. @LaTeX{} export lets you use Org mode and
its structured editing functions to easily create @LaTeX{} files. DocBook
export makes it possible to convert Org files to many other formats using
-DocBook tools. OpenDocument Text(@acronym{ODT}) export allows seamless
+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
+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
@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
#+AUTHOR: the author (default taken from @code{user-full-name})
#+DATE: a date, an Org timestamp@footnote{@code{org-export-date-timestamp-format} defines how this timestamp will be exported.}, or a format string for @code{format-time-string}
#+EMAIL: his/her email address (default from @code{user-mail-address})
-#+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag
-#+KEYWORDS: the page keywords, e.g.@: for the XHTML meta tag
-#+LANGUAGE: language for HTML, e.g.@: @samp{en} (@code{org-export-default-language})
+#+DESCRIPTION: the page description, e.g., for the XHTML meta tag
+#+KEYWORDS: the page keywords, e.g., for the XHTML meta tag
+#+LANGUAGE: language for HTML, e.g., @samp{en} (@code{org-export-default-language})
#+TEXT: Some descriptive text to be inserted at the beginning.
#+TEXT: Several lines may be given.
#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
-#+BIND: lisp-var lisp-val, e.g.@:: @code{org-export-latex-low-levels itemize}
+#+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
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 UTF-8 export
ASCII export produces a simple and very readable version of an Org mode
-file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file
+file, containing only plain ASCII@. Latin-1 and UTF-8 export augment the file
with special characters and symbols available in these encodings.
@cindex region, active
@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
@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.
@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
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}.
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.}
@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
@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
@subsection Quoting @LaTeX{} code
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
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.
@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 org-odt.el
@cindex org-modules
-Orgmode@footnote{Versions 7.8 or later} supports export to OpenDocument Text
-(@acronym{ODT}) format using the @file{org-odt.el} module. Documents created
+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
-* Pre-requisites for @acronym{ODT} export:: What packages @acronym{ODT} exporter relies on
-* @acronym{ODT} export commands:: How to invoke @acronym{ODT} 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 @acronym{ODT} export:: How links will be interpreted and formatted
-* Tables in @acronym{ODT} export:: How Tables are exported
-* Images in @acronym{ODT} export:: How to insert images
-* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted
-* Literal examples in @acronym{ODT} export:: How source and example blocks are formatted
-* Advanced topics in @acronym{ODT} export:: Read this if you are a power user
+* 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 Pre-requisites for @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export, OpenDocument Text export
-@subsection Pre-requisites for @acronym{ODT} export
+@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export
+@subsection Pre-requisites for ODT export
@cindex zip
-The @acronym{ODT} exporter relies on the @file{zip} program to create the final
+The ODT exporter relies on the @file{zip} program to create the final
output. Check the availability of this program before proceeding further.
-@node @acronym{ODT} export commands, Applying custom styles, Pre-requisites for @acronym{ODT} export, OpenDocument Text export
-@subsection @acronym{ODT} export commands
+@node ODT export commands, Extending ODT export, Pre-requisites for ODT export, OpenDocument Text export
+@subsection ODT export commands
-@subsubheading Exporting to @acronym{ODT}
+@subsubheading Exporting to ODT
@anchor{x-export-to-odt}
@cindex region, active
@cindex property EXPORT_FILE_NAME
Export as OpenDocument Text file.
+
@vindex org-export-odt-preferred-output-format
If @code{org-export-odt-preferred-output-format} is specified, automatically
-convert the exported file to that format.
-@xref{x-export-to-other-formats,,Automatically exporting to other formats}.
+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 @acronym{ODT} file will be
+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
export.
@orgcmd{C-c C-e O,org-export-as-odt-and-open}
-Export as OpenDocument Text 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}.
+converted file instead. @xref{x-export-to-other-formats, , Automatically
+exporting to other formats}.
@end table
-@subsubheading Automatically exporting to other formats
+@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 @acronym{ODT} format, only to
-immediately save the exported document to a different format like @samp{pdf}.
-In such cases, you will find it convenient to configure a converter
-(@pxref{Exporting and converting to other formats}) and specify your
+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 also export to
-the preferred format.
+(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a
+format that is of immediate interest to you.
+
+@subsubsection Converting between document formats
+@anchor{x-convert-to-other-formats}
+
+There are many document converters in the wild which support conversion to
+and from various file formats, including, but not limited to the
+ODT format. LibreOffice converter, mentioned above, is one such
+converter. Once a converter is configured, you can interact with it using
+the following command.
+
+@vindex org-export-odt-convert
+@table @kbd
+
+@item M-x org-export-odt-convert
+Convert an existing document from one format to another. With a prefix
+argument, also open the newly produced file.
+@end table
-@node Applying custom styles, Links in @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export
+@node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export
@subsection Applying custom styles
@cindex styles, custom
@cindex template, custom
-The @acronym{ODT} exporter ships with a set of OpenDocument styles
+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
@enumerate
@item
Create a sample @file{example.org} file with the below settings and export it
-to @acronym{ODT} format.
+to ODT format.
@example
#+OPTIONS: H:10 num:t
recommended that you only work with templates that are directly derived from
the factory settings.
-@node Links in @acronym{ODT} export, Tables in @acronym{ODT} export, Applying custom styles, OpenDocument Text export
-@subsection Links in @acronym{ODT} 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
-The @acronym{ODT} exporter creates cross-references (aka bookmarks) for
-internal links. 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.
+
+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.
-@node Tables in @acronym{ODT} export, Images in @acronym{ODT} export, Links in @acronym{ODT} export, OpenDocument Text export
-@subsection Tables in @acronym{ODT} export
+A @samp{\ref@{label@}}-style reference to an image, table etc. is replaced
+with a cross-reference and sequence number of the labeled entity.
+@xref{Labels and captions in ODT export}.
+
+@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export
+@subsection Tables in ODT export
@cindex tables, in DocBook export
Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el}
tables that have column or row spans - is not supported. Such tables are
stripped from the exported document.
-By default, a table is exported with top and bottom frames and with
-rules separating row and column groups (@pxref{Column groups}). 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}
+By default, a table is exported with top and bottom frames and with rules
+separating row and column groups (@pxref{Column groups}). Furthermore, all
+tables are typeset to occupy the same width. If the table specifies
+alignment and relative width for its columns (@pxref{Column width and
+alignment}) then these are honored on export.@footnote{The column widths are
+interpreted as weighted ratios with the default weight being 1}
@cindex #+ATTR_ODT
-If you are not satisfied with the default formatting of tables, you can
-create custom table styles and associate them with a table using
-the @code{#+ATTR_ODT} line. @xref{Customizing tables in @acronym{ODT} export}.
+You can control the width of the table by specifying @code{:rel-width}
+property using an @code{#+ATTR_ODT} line.
-@node Images in @acronym{ODT} export, Math formatting in @acronym{ODT} export, Tables in @acronym{ODT} export, OpenDocument Text export
-@subsection Images in @acronym{ODT} export
-@cindex images, embedding in @acronym{ODT}
-@cindex embedding images in @acronym{ODT}
+For example, consider the following table which makes use of all the rules
+mentioned above.
+
+@example
+#+ATTR_ODT: :rel-width 50
+| Area/Month | Jan | Feb | Mar | Sum |
+|---------------+-------+-------+-------+-------|
+| / | < | | | < |
+| <l13> | <r5> | <r5> | <r5> | <r6> |
+| North America | 1 | 21 | 926 | 948 |
+| Middle East | 6 | 75 | 844 | 925 |
+| Asia Pacific | 9 | 27 | 790 | 826 |
+|---------------+-------+-------+-------+-------|
+| Sum | 16 | 123 | 2560 | 2699 |
+@end example
+
+On export, the table will occupy 50% of text area. The columns will be sized
+(roughly) in the ratio of 13:5:5:5:6. The first column will be left-aligned
+and rest of the columns will be right-aligned. There will be vertical rules
+after separating the header and last columns from other columns. There will
+be horizontal rules separating the header and last rows from other rows.
+
+If you are not satisfied with the above formatting options, you can create
+custom table styles and associate them with a table using the
+@code{#+ATTR_ODT} line. @xref{Customizing tables in ODT export}.
+
+@node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export
+@subsection Images in ODT export
+@cindex images, embedding in ODT
+@cindex embedding images in ODT
@subsubheading Embedding images
You can embed images within the exported document by providing a link to the
@subsubheading Sizing and scaling of embedded images
+@cindex #+ATTR_ODT
You can control the size and scale of the embedded images using the
@code{#+ATTR_ODT} attribute.
+@cindex identify, ImageMagick
@vindex org-export-odt-pixels-per-inch
-Note that 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 needs to compute the size of the image. This is done by retrieving
-the image size in pixels and converting the pixel units to centimeters using
+The exporter specifies the desired size of the image in the final document in
+units of centimeters. In order to scale the embedded images, the exporter
+queries for pixel dimensions of the images using one of a) ImageMagick's
+@file{identify} program or b) Emacs `create-image' and `image-size'
+APIs.@footnote{Use of @file{ImageMagick} is only desirable. However, if you
+routinely produce documents that have large images or you export your Org
+files that has images using a Emacs batch script, then the use of
+@file{ImageMagick} is mandatory.} The pixel dimensions are subsequently
+converted in to units of centimeters using
@code{org-export-odt-pixels-per-inch}. The default value of this variable is
set to @code{display-pixels-per-inch}. You can tweak this variable to
achieve the best results.
The examples below illustrate the various possibilities.
@table @asis
-
@item Explicitly size the image
To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
@end example
@end table
-@node Math formatting in @acronym{ODT} export, Literal examples in @acronym{ODT} export, Images in @acronym{ODT} export, OpenDocument Text export
-@subsection Math formatting in @acronym{ODT} export
+@subsubheading Anchoring of images
-The @acronym{ODT} exporter has special support for handling math.
+@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 @acronym{ODT} export, Math formatting in @acronym{ODT} export
+@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
@table @kbd
@item M-x org-export-as-odf
-Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file.
+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 OpenDocument formula (@file{.odf}) file and
-open the formula file with the system-registered application.
+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
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 @acronym{ODT} export
+@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
-@acronym{ODT} document less than reliable. In that case, you can embed a
-math equation by linking to its MathML(@file{.mml}) source or its
+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.odf]]
@end example
-@node Literal examples in @acronym{ODT} export, Advanced topics in @acronym{ODT} export, Math formatting in @acronym{ODT} export, OpenDocument Text export
-@subsection Literal examples in @acronym{ODT} export
+@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
-Export of literal examples (@pxref{Literal examples}) with full fontification
-is supported. This feature is enabled by default and is activated
-automatically if an enhanced version of @file{htmlfontify.el} is available in
-the @code{load-path}.@footnote{The @file{htmlfontify.el} that ships with
-standard Emacs <= 24.1 has no support for @acronym{ODT} fontification. A
-copy of the proposed version is available as an attachment to
-@url{http://debbugs.gnu.org/cgi/bugreport.cgi?msg=5;filename=htmlfontify.el;att=9;bug=9914,
-Emacs Bug #9914}.}
+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.
-@vindex org-export-odt-fontify-srcblocks
+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.
-The character styles used for fontification of the literal blocks are
-auto-generated by the exporter in conjunction with @file{htmlfontify.el}
-library and need not be included in the default @file{styles.xml} file.
-These auto-generated styles have the @samp{OrgSrc} prefix and inherit their color
-based on the face used by Emacs @code{font-lock} library.
+@example
+#+CAPTION: Bell curve
+#+LABEL: fig:SED-HR4049
+[[./img/a.png]]
+@end example
-@vindex org-export-odt-create-custom-styles-for-srcblocks
-If you prefer to use your own custom styles for fontification and disable
-their auto-generation altogether, you can do so by customizing the variable
-@code{org-export-odt-create-custom-styles-for-srcblocks}.
+It could be rendered as shown below in the exported document.
-You can turn off fontification support for literal examples by customizing
-the variable @code{org-export-odt-fontify-srcblocks}.
+@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.
-@node Advanced topics in @acronym{ODT} export, , Literal examples in @acronym{ODT} export, OpenDocument Text export
-@subsection Advanced topics in @acronym{ODT} export
+@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}.
-If you rely heavily on @acronym{ODT} export, you may want to exploit the full
+@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
-* Exporting and converting to other formats:: How to produce @samp{pdf} and other formats
+* 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 @acronym{ODT} export:: How to define and use Table templates
+* Customizing tables in ODT export:: How to define and use Table templates
* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
@end menu
-@node Exporting and converting to other formats, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export, Advanced topics in @acronym{ODT} export
-@subsubsection Exporting and converting to other formats
+@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
-
-The @acronym{ODT} exporter adds support for exporting Org outlines to formats
-that are not supported natively by Org. It also adds support to convert
-document from one format to another. To use these features, you need to
-configure a command-line converter. Once a command-line converter is
-configured you can use it to extend the list of formats to which Org can
-export. @xref{x-export-to-other-formats,,Automatically exporting to other
-formats}. You can also use it to perform one-off document conversion as
-detailed below.
-
-@vindex org-export-odt-convert
-@table @kbd
-
-@item M-x org-export-odt-convert
-Convert an existing document from one format to another as determined by the
-variable @code{org-export-odt-convert-capabilities}
-(@pxref{x-odt-converter-capabilities,,Configure converter
-capabilities}). @strong{Please note} that you can use this command to even
-convert documents that are produced outside of Org and in other formats than
-@acronym{ODT} format.
-@end table
-
-@subsubheading Pre-configured converters
-
+@cindex doc, docx, rtf
@cindex converter
-The @acronym{ODT} exporter supports two converters out of the box:
-
-@enumerate
-
-@cindex @file{unoconv}
-@item @file{unoconv}
-
-This converter is available as an installable package in your favorite
-distribution.
-@cindex @file{BasicODConverter}
-@item @file{BasicODConverter}
-
-@vindex org-odt-data-dir
-This converter is distributed as a LibreOffice extension and can be found in
-your Org distribution. See the subdirectory pointed to by the variable
-@code{org-odt-data-dir}.
-
-@end enumerate
-
-@subsubheading Installing a new converter
-If you prefer to use a converter other than the two mentioned above, then you
-may have to do additional configuration. You can proceed as follows:
+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
converter can be invoked via command-line to effect the conversion.
@item Configure its capabilities
-@vindex org-export-odt-convert-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
variable @code{org-export-odt-convert-process}.
@end enumerate
-@node Working with OpenDocument style files, Creating one-off styles, Exporting and converting to other formats, Advanced topics in @acronym{ODT} export
+@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 @acronym{ODT} exporter and the
+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 @acronym{ODT} exporter relies on two files for generating its output.
+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:
@anchor{x-overriding-factory-styles}
@subsubheading Overriding factory styles
-The following two variables control the location from which the @acronym{ODT}
+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.
in the final output.
@end itemize
-@node Creating one-off styles, Customizing tables in @acronym{ODT} export, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export
+@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
@end example
@strong{Hint:} To see the above example in action, edit your
-@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
+@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
custom @samp{Highlight} style as shown below.
@example
@end example
@strong{Hint:} To see the above example in action, edit your
-@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
+@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
custom @samp{PageBreak} style as shown below.
@example
@end enumerate
-@node Customizing tables in @acronym{ODT} export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in @acronym{ODT} export
-@subsubsection Customizing tables in @acronym{ODT} export
+@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 @acronym{ODT} export}.
+formatting of tables @pxref{Tables in ODT export}.
This feature closely mimics the way table templates are defined in the
OpenDocument-v1.2
@end lisp
@example
-#+ATTR_ODT: TableWithHeaderRowAndColumn
+#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
| Name | Phone | Age |
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
@end itemize
For example, the entry below defines two different table styles
-@samp{TableWithHeaderRowsAndColumns} and @samp{TableWithHeaderColumns} based
-on the same template @samp{Custom}. The styles achieve their intended effect
-by selectively activating the individual cell styles in that template.
+@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
the @code{ATTR_ODT} line as shown below.
@example
-#+ATTR_ODT: TableWithHeaderRowAndColumn
+#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
| Name | Phone | Age |
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
@end example
@end enumerate
-@node Validating OpenDocument XML, , Customizing tables in @acronym{ODT} export, Advanced topics in @acronym{ODT} export
+@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
-@acronym{ODT} exporter cannot be opened by your favorite application. One of
+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.
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
-@acronym{ODT} exporter will take care of updating the
+ODT exporter will take care of updating the
@code{rng-schema-locating-files} for you.
@c end opendocument
@table @kbd
@orgcmd{C-c C-e j,org-export-as-taskjuggler}
-Export as TaskJuggler file.
+Export as a TaskJuggler file.
@orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open}
-Export as TaskJuggler file and then open the file with TaskJugglerUI.
+Export as a TaskJuggler file and then open the file with TaskJugglerUI.
@end table
@subsection Tasks
@subsection Export of properties
-The exporter also takes TODO state information into consideration, i.e.@: if a
+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
@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
@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.
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.
@end multitable
The file will be created when first publishing a project with the
-@code{:makeindex} set. The file only contains a statement @code{#+include:
+@code{:makeindex} set. The file only contains a statement @code{#+INCLUDE:
"theindex.inc"}. You can then build around this include statement by adding
a title, style information, etc.
that you can afford more easily to republish entire projects. If you set
@code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
benefit of re-including any changed external files such as source example
-files you might include with @code{#+INCLUDE}. The timestamp mechanism in
+files you might include with @code{#+INCLUDE:}. The timestamp mechanism in
Org is not smart enough to detect if included files have been modified.
@node Sample configuration, Triggering publication, Uploading files, Publishing
@cindex source code, working with
Source code can be included in Org mode documents using a @samp{src} block,
-e.g.@:
+e.g.:
@example
#+BEGIN_SRC emacs-lisp
It is possible to export the @emph{code} of code blocks, the @emph{results}
of code block evaluation, @emph{both} the code and the results of code block
evaluation, or @emph{none}. For most languages, the default exports code.
-However, for some languages (e.g.@: @code{ditaa}) the default exports the
+However, for some languages (e.g., @code{ditaa}) the default exports the
results of code block evaluation. For information on exporting code block
bodies, see @ref{Literal examples}.
@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 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. 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).
+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
its results into the Org mode buffer.
@cindex #+CALL
-It is also possible to evaluate named code blocks from anywhere in an
-Org mode buffer or an Org mode table. Live code blocks located in the current
+It is also possible to evaluate named code blocks from anywhere in an Org
+mode buffer or an Org mode table. Live code blocks located in the current
Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel})
can be executed. Named code blocks can be executed with a separate
@code{#+CALL:} line or inline within a block of text.
Language-specific documentation is available for some languages. If
available, it can be found at
-@uref{http://orgmode.org/worg/org-contrib/babel/languages}.
+@uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
The @code{org-babel-load-languages} controls which languages are enabled for
evaluation (by default only @code{emacs-lisp} is enabled). This variable can
@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
@example
* outline header
-:PROPERTIES:
-:cache: yes
-:END:
+ :PROPERTIES:
+ :cache: yes
+ :END:
@end example
@kindex C-c C-x p
@cindex #+HEADERS:
Multi-line header arguments on an un-named code block:
+
@example
#+HEADERS: :var data1=1
#+BEGIN_SRC emacs-lisp :var data2=2
(message "data1:%S, data2:%S" data1 data2)
#+END_SRC
- #+results:
+ #+RESULTS:
: data1:1, data2:2
@end example
Multi-line header arguments on a named code block:
+
@example
#+NAME: named-block
#+HEADER: :var data=2
(message "data:%S" data)
#+END_SRC
- #+results: named-block
+ #+RESULTS: named-block
: data:2
@end example
The following will apply the @code{:exports results} header argument to the
evaluation of the @code{#+CALL:} line.
+
@example
#+CALL: factorial(n=5) :exports results
@end example
The following will apply the @code{:session special} header argument to the
evaluation of the @code{factorial} code block.
+
@example
#+CALL: factorial[:session special](n=5)
@end example
* results:: Specify the type of results and how they will
be collected and handled
* file:: Specify a path for file output
+* file-desc:: Specify a description for file results
* dir:: Specify the default (possibly remote)
directory for code block execution
* exports:: Export code and/or results
* 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
case, variables require a default value when they are declared.
The values passed to arguments can either be literal values, references, or
-Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). References
+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
@item table
an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line
+
@example
#+TBLNAME: example-table
| 1 |
(length table)
#+END_SRC
-#+results: table-length
+#+RESULTS: table-length
: 4
@end example
(print x)
#+END_SRC
-#+results:
+#+RESULTS:
| simple | list |
@end example
(* 2 length)
#+END_SRC
-#+results:
+#+RESULTS:
: 8
@end example
(* 2 input)
#+END_SRC
-#+results: double
+#+RESULTS: double
: 16
#+NAME: squared
(* input input)
#+END_SRC
-#+results: squared
+#+RESULTS: squared
: 4
@end example
(concatenate 'string x " for you.")
#+END_SRC
-#+results: read-literal-example
+#+RESULTS: read-literal-example
: A literal example
: on two lines for you.
data
#+END_SRC
-#+results:
+#+RESULTS:
: a
@end example
data
#+END_SRC
-#+results:
+#+RESULTS:
| 2 | b |
| 3 | c |
| 4 | d |
data
#+END_SRC
-#+results:
+#+RESULTS:
| 1 | 2 | 3 | 4 |
@end example
data
#+END_SRC
-#+results:
+#+RESULTS:
| 11 | 14 | 17 |
@end example
$data
#+END_SRC
-#+results:
+#+RESULTS:
: (a b c)
@end example
@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}
+@item @code{raw}
The results are interpreted as raw Org mode code and are inserted directly
into the buffer. If the results look like a table they will be aligned as
such by Org mode. E.g., @code{:results value raw}.
+@item @code{org}
+The results are will be enclosed in a @code{BEGIN_SRC org} block.
+They are not comma-escaped by default but they will be if you hit @kbd{TAB}
+in the block and/or if you export the file. E.g., @code{:results value org}.
@item @code{html}
-Results are assumed to be HTML and will be enclosed in a @code{begin_html}
+Results are assumed to be HTML and will be enclosed in a @code{BEGIN_HTML}
block. E.g., @code{:results value html}.
@item @code{latex}
-Results assumed to be @LaTeX{} and are enclosed in a @code{begin_latex} block.
+Results assumed to be @LaTeX{} and are enclosed in a @code{BEGIN_LaTeX} block.
E.g., @code{:results value latex}.
@item @code{code}
Result are assumed to be parsable code and are enclosed in a code block.
The result is converted to pretty-printed code and is enclosed in a code
block. This option currently supports Emacs Lisp, Python, and Ruby. E.g.,
@code{:results value pp}.
-@item @code{wrap}
-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
inserted as with @code{replace}.
@end itemize
-@node file, dir, results, Specific header arguments
+@node file, file-desc, results, Specific header arguments
@subsubsection @code{:file}
The header argument @code{:file} is used to specify an external file in which
a file, or a list of two strings in which case the first element of the list
should be the path to a file and the second a description for the link.
-@node dir, exports, file, Specific header arguments
+@node file-desc, dir, file, Specific header arguments
+@subsubsection @code{:file-desc}
+
+The value of the @code{:file-desc} header argument is used to provide a
+description for file code block results which are inserted as Org mode links
+(see @ref{Link format}). If the @code{:file-desc} header argument is given
+with no value the link path will be placed in both the ``link'' and the
+``description'' portion of the Org mode link.
+
+@node dir, exports, file-desc, Specific header arguments
@subsubsection @code{:dir} and remote execution
While the @code{:file} header argument can be used to specify the path to the
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}
@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
#+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
runif(1)
#+END_SRC
- #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
+ #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
0.4659510825295
#+NAME: caller
x
#+END_SRC
- #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
+ #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
0.254227238707244
@end example
return tab
#+END_SRC
-#+results: echo-table
+#+RESULTS: echo-table
| a | b | c |
| d | e | f |
| g | h | i |
return tab
#+END_SRC
-#+results: echo-table
+#+RESULTS: echo-table
| a | b | c |
|---+---+---|
| d | e | f |
return [[val + '*' for val in row] for row in tab]
#+END_SRC
-#+results: echo-table-again
+#+RESULTS: echo-table-again
| a |
|----|
| b* |
@item @code{yes}
Column names are removed and reapplied as with @code{nil} even if the table
-does not ``look like'' it has column names (i.e.@: the second row is not an
+does not ``look like'' it has column names (i.e., the second row is not an
hline)
@end itemize
return [[val + 10 for val in row] for row in tab]
#+END_SRC
-#+results: echo-table-once-again
+#+RESULTS: echo-table-once-again
| one | 11 | 12 | 13 | 14 | 15 |
| two | 16 | 17 | 18 | 19 | 20 |
@end example
@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. The @code{:eval} header argument can be useful for
of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation
security}.
+@node wrap, , eval, Specific header arguments
+@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
print "bye"
#+END_SRC
-#+results:
+#+RESULTS:
: hello
: bye
@end example
In non-session mode, the `2' is not printed and does not appear.
+
@example
#+BEGIN_SRC python :results output :session
print "hello"
print "bye"
#+END_SRC
-#+results:
+#+RESULTS:
: hello
: 2
: bye
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
@code{<<arg>>} is a syntactically valid construct. If @code{<<arg>>} is not
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
+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
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\"))
will insert example settings for this keyword.
@item
In the line after @samp{#+STARTUP: }, complete startup keywords,
-i.e.@: valid keys for this line.
+i.e., valid keys for this line.
@item
Elsewhere, complete dictionary words using Ispell.
@end itemize
The following template selectors are currently supported.
@multitable @columnfractions 0.1 0.9
-@item @kbd{s} @tab @code{#+begin_src ... #+end_src}
-@item @kbd{e} @tab @code{#+begin_example ... #+end_example}
-@item @kbd{q} @tab @code{#+begin_quote ... #+end_quote}
-@item @kbd{v} @tab @code{#+begin_verse ... #+end_verse}
-@item @kbd{c} @tab @code{#+begin_center ... #+end_center}
-@item @kbd{l} @tab @code{#+begin_latex ... #+end_latex}
-@item @kbd{L} @tab @code{#+latex:}
-@item @kbd{h} @tab @code{#+begin_html ... #+end_html}
-@item @kbd{H} @tab @code{#+html:}
-@item @kbd{a} @tab @code{#+begin_ascii ... #+end_ascii}
-@item @kbd{A} @tab @code{#+ascii:}
-@item @kbd{i} @tab @code{#+index:} line
-@item @kbd{I} @tab @code{#+include:} line
+@item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC}
+@item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
+@item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE}
+@item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE}
+@item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER}
+@item @kbd{l} @tab @code{#+BEGIN_LaTeX ... #+END_LaTeX}
+@item @kbd{L} @tab @code{#+LaTeX:}
+@item @kbd{h} @tab @code{#+BEGIN_HTML ... #+END_HTML}
+@item @kbd{H} @tab @code{#+HTML:}
+@item @kbd{a} @tab @code{#+BEGIN_ASCII ... #+END_ASCII}
+@item @kbd{A} @tab @code{#+ASCII:}
+@item @kbd{i} @tab @code{#+INDEX:} line
+@item @kbd{I} @tab @code{#+INCLUDE:} line
@end multitable
For example, on an empty line, typing "<e" and then pressing TAB, will expand
@vindex org-speed-commands-user
Single keys can be made to execute commands when the cursor is at the
-beginning of a headline, i.e.@: before the first star. Configure the variable
+beginning of a headline, i.e., before the first star. Configure the variable
@code{org-use-speed-commands} to activate this feature. There is a
pre-defined list of commands, and you can add more such commands using the
variable @code{org-speed-commands-user}. Speed keys do not only speed up
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
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
@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}.
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
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
@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
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
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
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
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
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
`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
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
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{David O'Toole} wrote @file{org-publish.el} and drafted the manual
chapter about publishing.
@item
-@i{Jambunathan K} contributed the @acronym{ODT} exporter.
+@i{Jambunathan K} contributed the ODT exporter.
@item
@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
enabled source code highlighting in Gnus.
@item
@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
and contributed various ideas and code snippets.
-@item
@end itemize
-@node Main Index, Key Index, History and Acknowledgments, Top
+@node GNU Free Documentation License, Main Index, History and Acknowledgments, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@node Main Index, Key Index, GNU Free Documentation License, Top
@unnumbered Concept index
@printindex cp
HCoop / bpt / emacs.git / blobdiff