@c %**start of header
@setfilename ../../info/org
@settitle The Org Manual
+@set VERSION 8.2.5c
-@set VERSION 6.33x
-@set DATE November 2009
+@c Use proper quote and backtick for code sections in PDF output
+@c Cf. Texinfo manual 14.2
+@set txicodequoteundirected
+@set txicodequotebacktick
@c Version and Contact Info
-@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
+@set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page}
@set AUTHOR Carsten Dominik
@set MAINTAINER Carsten Dominik
@set MAINTAINEREMAIL @email{carsten at orgmode dot org}
@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
+@documentencoding UTF-8
@c %**end of header
@finalout
-@c Macro definitions
+
+@c -----------------------------------------------------------------------------
+
+@c Macro definitions for commands and keys
+@c =======================================
+
+@c The behavior of the key/command macros will depend on the flag cmdnames
+@c When set, commands names are shown. When clear, they are not shown.
+
+@set cmdnames
+
+@c Below we define the following macros for Org key tables:
+
+@c orgkey{key} A key item
+@c orgcmd{key,cmd} Key with command name
+@c xorgcmd{key,cmd} Key with command name as @itemx
+@c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
+@c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
+@c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
+@c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but
+@c different functions, so format as @itemx
+@c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short"
+@c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx
+@c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands
+
+@c a key but no command
+@c Inserts: @item key
+@macro orgkey{key}
+@kindex \key\
+@item @kbd{\key\}
+@end macro
+
+@macro xorgkey{key}
+@kindex \key\
+@itemx @kbd{\key\}
+@end macro
+
+@c one key with a command
+@c Inserts: @item KEY COMMAND
+@macro orgcmd{key,command}
+@ifset cmdnames
+@kindex \key\
+@findex \command\
@iftex
-@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
+@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
+@end iftex
+@ifnottex
+@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@kindex \key\
+@item @kbd{\key\}
+@end ifclear
+@end macro
+
+@c One key with one command, formatted using @itemx
+@c Inserts: @itemx KEY COMMAND
+@macro xorgcmd{key,command}
+@ifset cmdnames
+@kindex \key\
+@findex \command\
+@iftex
+@itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
+@end iftex
+@ifnottex
+@itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@kindex \key\
+@itemx @kbd{\key\}
+@end ifclear
+@end macro
+
+@c one key with a command, bit do not index the key
+@c Inserts: @item KEY COMMAND
+@macro orgcmdnki{key,command}
+@ifset cmdnames
+@findex \command\
+@iftex
+@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
+@end iftex
+@ifnottex
+@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@item @kbd{\key\}
+@end ifclear
+@end macro
+
+@c one key with a command, and special text to replace key in item
+@c Inserts: @item TEXT COMMAND
+@macro orgcmdtkc{text,key,command}
+@ifset cmdnames
+@kindex \key\
+@findex \command\
+@iftex
+@item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
+@end iftex
+@ifnottex
+@item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@kindex \key\
+@item @kbd{\text\}
+@end ifclear
+@end macro
+
+@c two keys with one command
+@c Inserts: @item KEY1 or KEY2 COMMAND
+@macro orgcmdkkc{key1,key2,command}
+@ifset cmdnames
+@kindex \key1\
+@kindex \key2\
+@findex \command\
+@iftex
+@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
+@end iftex
+@ifnottex
+@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@kindex \key1\
+@kindex \key2\
+@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
+@end ifclear
+@end macro
+
+@c Two keys with one command name, but different functions, so format as
+@c @itemx
+@c Inserts: @item KEY1
+@c @itemx KEY2 COMMAND
+@macro orgcmdkxkc{key1,key2,command}
+@ifset cmdnames
+@kindex \key1\
+@kindex \key2\
+@findex \command\
+@iftex
+@item @kbd{\key1\}
+@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
-@macro Ie {}
-I.e.,
+@ifnottex
+@item @kbd{\key1\}
+@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@kindex \key1\
+@kindex \key2\
+@item @kbd{\key1\}
+@itemx @kbd{\key2\}
+@end ifclear
@end macro
-@macro ie {}
-i.e.,
+
+@c Same as previous, but use "or short"
+@c Inserts: @item KEY1 or short KEY2 COMMAND
+@macro orgcmdkskc{key1,key2,command}
+@ifset cmdnames
+@kindex \key1\
+@kindex \key2\
+@findex \command\
+@iftex
+@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
+@end iftex
+@ifnottex
+@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@kindex \key1\
+@kindex \key2\
+@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
+@end ifclear
@end macro
-@macro Eg {}
-E.g.,
+
+@c Same as previous, but use @itemx
+@c Inserts: @itemx KEY1 or short KEY2 COMMAND
+@macro xorgcmdkskc{key1,key2,command}
+@ifset cmdnames
+@kindex \key1\
+@kindex \key2\
+@findex \command\
+@iftex
+@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
+@end iftex
+@ifnottex
+@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@kindex \key1\
+@kindex \key2\
+@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
+@end ifclear
@end macro
-@macro eg {}
-e.g.,
+
+@c two keys with two commands
+@c Inserts: @item KEY1 COMMAND1
+@c @itemx KEY2 COMMAND2
+@macro orgcmdkkcc{key1,key2,command1,command2}
+@ifset cmdnames
+@kindex \key1\
+@kindex \key2\
+@findex \command1\
+@findex \command2\
+@iftex
+@item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
+@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
+@end iftex
+@ifnottex
+@item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
+@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
+@end ifnottex
+@end ifset
+@ifclear cmdnames
+@kindex \key1\
+@kindex \key2\
+@item @kbd{\key1\}
+@itemx @kbd{\key2\}
+@end ifclear
@end macro
+@c -----------------------------------------------------------------------------
+
+@iftex
+@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
+@end iftex
@c Subheadings inside a table.
@macro tsubheading{text}
@copying
This manual is for Org version @value{VERSION}.
-Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
-Free Software Foundation, Inc.
+Copyright @copyright{} 2004--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+modify this GNU manual.''
@end quotation
@end copying
@subtitle Release @value{VERSION}
@author by Carsten Dominik
+with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan
+Davison, Eric Schulte, Thomas Dye, Jambunathan K and Nicolas Goaziou.
@c The following two commands start the copyright page.
@page
@contents
@ifnottex
+@c FIXME These hand-written next,prev,up node pointers make editing a lot
+@c harder. There should be no need for them, makeinfo can do it
+@c automatically for any document with a normal structure.
@node Top, Introduction, (dir), (dir)
@top Org Mode Manual
* Capture - Refile - Archive:: The ins and outs for projects
* Agenda Views:: Collecting information into views
* Markup:: Prepare text for rich export
-* Exporting:: Sharing and publishing of notes
+* Exporting:: Sharing and publishing notes
* Publishing:: Create a web site of linked Org files
+* Working With Source Code:: Export, evaluate, and tangle code blocks
* Miscellaneous:: All the rest which did not fit elsewhere
* Hacking:: How to hack your way around
* MobileOrg:: Viewing and capture on a mobile device
* History and Acknowledgments:: How Org came into being
+* GNU Free Documentation License:: The license for this documentation.
* Main Index:: An index of Org's concepts and features
* Key Index:: Key bindings and where they are described
+* Command and Function Index:: Command names and some internal functions
* Variable Index:: Variables mentioned in the manual
@detailmenu
Introduction
* Summary:: Brief summary of what Org does
-* Installation:: How to install a downloaded version of Org
+* Installation:: Installing Org
* Activation:: How to activate Org for certain buffers
* Feedback:: Bug reports, ideas, patches etc.
-* Conventions:: Type-setting conventions in the manual
+* Conventions:: Typesetting conventions in the manual
-Document Structure
+Document structure
* Outlines:: Org is based on Outline mode
* Headlines:: How to typeset Org tree headlines
* Blocks:: Folding blocks
* Footnotes:: How footnotes are defined in Org's syntax
* Orgstruct mode:: Structure editing outside Org
+* Org syntax:: Formal description of Org's syntax
+
+Visibility cycling
+
+* Global and local cycling:: Cycling through various visibility states
+* Initial visibility:: Setting the initial visibility state
+* Catching invisible edits:: Preventing mistakes when editing invisible parts
+
+Global and local cycling
+
+* Initial visibility:: Setting the initial visibility state
+* Catching invisible edits:: Preventing mistakes when editing invisible parts
Tables
* References:: How to refer to another field or range
* Formula syntax for Calc:: Using Calc to compute stuff
* Formula syntax for Lisp:: Writing formulas in Emacs Lisp
-* Field formulas:: Formulas valid for a single field
+* Durations and time values:: How to compute durations and time values
+* Field and range formulas:: Formula for specific (ranges of) fields
* Column formulas:: Formulas valid for an entire column
+* Lookup functions:: Lookup functions for searching tables
* Editing and debugging formulas:: Fixing formulas
* Updating the table:: Recomputing all dependent fields
-* Advanced features:: Field names, parameters and automatic recalc
+* Advanced features:: Field and column names, parameters and automatic recalc
Hyperlinks
* Radio targets:: Make targets trigger links in plain text
-TODO Items
+TODO items
* TODO basics:: Marking and displaying TODO entries
* TODO extensions:: Workflow and assignments
* Tag inheritance:: Tags use the tree structure of the outline
* Setting tags:: How to assign tags to a headline
+* Tag groups:: Use one tag to search for several tags
* Tag searches:: Searching for combinations of tags
-Properties and Columns
+Properties and columns
* Property syntax:: How properties are spelled out
* Special properties:: Access to other Org mode features
* Scope of column definitions:: Where defined, where valid?
* Column attributes:: Appearance and content of a column
-Dates and Times
+Dates and times
* Timestamps:: Assigning a time to a tree entry
* Creating timestamps:: Commands which insert timestamps
* Deadlines and scheduling:: Planning your work
* Clocking work time:: Tracking how long you spend on a task
-* Resolving idle time:: Resolving time if you've been idle
* Effort estimates:: Planning work effort in advance
* Relative timer:: Notes with a running timer
+* Countdown timer:: Starting a countdown timer for a task
Creating timestamps
* Inserting deadline/schedule:: Planning items
* Repeated tasks:: Items that show up again and again
+Clocking work time
+
+* Clocking commands:: Starting and stopping a clock
+* The clock table:: Detailed reports
+* Resolving idle time:: Resolving time when you've been idle
+
Capture - Refile - Archive
-* Remember:: Capture new tasks/ideas with little interruption
-* Attachments:: Add files to tasks.
+* Capture:: Capturing new stuff
+* Attachments:: Add files to tasks
* RSS Feeds:: Getting input from RSS feeds
-* Protocols:: External (e.g. Browser) access to Emacs and Org
-* Refiling notes:: Moving a tree from one place to another
+* Protocols:: External (e.g., Browser) access to Emacs and Org
+* Refile and copy:: Moving/copying a tree from one place to another
* Archiving:: What to do with finished projects
-Remember
+Capture
+
+* Setting up capture:: Where notes will be stored
+* Using capture:: Commands to invoke and terminate capture
+* Capture templates:: Define the outline of different note types
+
+Capture templates
-* Setting up Remember for Org:: Some code for .emacs to get things going
-* Remember templates:: Define the outline of different note types
-* Storing notes:: Directly get the note to where it belongs
+* 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
* Moving subtrees:: Moving a tree to an archive file
-* Internal archiving:: Switch off a tree but keep i in the file
+* Internal archiving:: Switch off a tree but keep it in the file
-Agenda Views
+Agenda views
* Agenda files:: Files being searched for agenda information
* Agenda dispatcher:: Keyboard access to agenda views
* Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time
-* Sorting of agenda items:: The order of things
+* Sorting agenda items:: The order of things
+* Filtering/limiting agenda items:: Dynamically narrow the agenda
Custom agenda views
Markup for rich export
* Structural markup elements:: The basic structure as seen by the exporter
-* Images and tables:: Tables and Images will be included
+* Images and tables:: Images, tables and caption mechanism
* Literal examples:: Source code examples with special formatting
* Include files:: Include additional files into a document
-* Macro replacement:: Use macros to create complex output
-* Embedded LaTeX:: LaTeX can be freely used inside Org documents
+* Index entries:: Making an index
+* Macro replacement:: Use macros to create templates
+* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
+* Special blocks:: Containers targeted at export back-ends
Structural markup elements
* Document title:: Where the title is taken from
* Headings and sections:: The document structure as seen by the exporter
* Table of contents:: The if and where of the table of contents
-* Initial text:: Text before the first heading?
* Lists:: Lists
* Paragraphs:: Paragraphs
* Footnote markup:: Footnotes
* Horizontal rules:: Make a line
* Comment lines:: What will *not* be exported
-Embedded La@TeX{}
+Embedded @LaTeX{}
* Special symbols:: Greek letters and other symbols
* Subscripts and superscripts:: Simple syntax for raising/lowering text
-* LaTeX fragments:: Complex formulas made easy
-* Previewing LaTeX fragments:: What will this snippet look like?
+* @LaTeX{} fragments:: Complex formulas made easy
+* Previewing @LaTeX{} fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
Exporting
-* Selective export:: Using tags to select and exclude trees
-* Export options:: Per-file export settings
-* The export dispatcher:: How to access exporter commands
-* ASCII export:: Exporting to plain ASCII
+* The Export Dispatcher:: The main exporter interface
+* Export back-ends:: Built-in export formats
+* Export settings:: Generic export settings
+* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
+* Beamer export:: Exporting as a Beamer presentation
* HTML export:: Exporting to HTML
-* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF
-* DocBook export:: Exporting to DocBook
-* Freemind export:: Exporting to Freemind mind maps
-* XOXO export:: Exporting to XOXO
-* iCalendar export:: Exporting in iCalendar format
+* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
+* Markdown export:: Exporting to Markdown
+* OpenDocument Text export:: Exporting to OpenDocument Text
+* Org export:: Exporting to Org
+* iCalendar export:: Exporting to iCalendar
+* Other built-in back-ends:: Exporting to @code{Texinfo}, a man page, or Org
+* Export in foreign buffers:: Author tables in lists in Org syntax
+* Advanced configuration:: Fine-tuning the export output
HTML export
* HTML Export commands:: How to invoke HTML export
+* HTML doctypes:: Org can export to various (X)HTML flavors
+* HTML preamble and postamble:: How to insert a preamble and a postamble
* Quoting HTML tags:: Using direct HTML in Org mode
* Links in HTML export:: How links will be interpreted and formatted
* Tables in HTML export:: How to modify the formatting of tables
* Images in HTML export:: How to insert figures into HTML output
+* Math formatting in HTML export:: Beautiful math also on the web
* Text areas in HTML export:: An alternative way to show an example
* CSS support:: Changing the appearance of the output
-* Javascript support:: Info and Folding in a web browser
+* JavaScript support:: Info and Folding in a web browser
-La@TeX{} and PDF export
+@LaTeX{} and PDF export
-* LaTeX/PDF export commands:: Which key invokes which commands
-* Quoting LaTeX code:: Incorporating literal La@TeX{} code
-* Sectioning structure:: Changing sectioning in La@TeX{} output
-* Tables in LaTeX export:: Options for exporting tables to La@TeX{}
-* Images in LaTeX export:: How to insert figures into La@TeX{} output
+* @LaTeX{} export commands:: How to export to LaTeX and PDF
+* Header and sectioning:: Setting up the export file structure
+* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code
+* @LaTeX{} specific attributes:: Controlling @LaTeX{} output
-DocBook export
+OpenDocument Text export
-* DocBook export commands:: How to invoke DocBook export
-* Quoting DocBook code:: Incorporating DocBook code in Org files
-* Recursive sections:: Recursive sections in DocBook
-* Tables in DocBook export:: Tables are exported as HTML tables
-* Images in DocBook export:: How to insert figures into DocBook output
-* Special characters:: How to handle special characters
+* Pre-requisites for ODT export:: What packages ODT exporter relies on
+* ODT export commands:: How to invoke ODT export
+* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files
+* Applying custom styles:: How to apply custom styles to the output
+* Links in ODT export:: How links will be interpreted and formatted
+* Tables in ODT export:: How Tables are exported
+* Images in ODT export:: How to insert images
+* Math formatting in ODT export:: How @LaTeX{} fragments are formatted
+* Labels and captions in ODT export:: How captions are rendered
+* Literal examples in ODT export:: How source and example blocks are formatted
+* Advanced topics in ODT export:: Read this if you are a power user
+
+Math formatting in ODT export
+
+* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments
+* Working with MathML or OpenDocument formula files:: How to embed equations in native format
+
+Advanced topics in ODT export
+
+* Configuring a document converter:: How to register a document converter
+* Working with OpenDocument style files:: Explore the internals
+* Creating one-off styles:: How to produce custom highlighting etc
+* Customizing tables in ODT export:: How to define and use Table templates
+* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
Publishing
* Sources and destinations:: From here to there
* Selecting files:: What files are part of the project?
* Publishing action:: Setting the function doing the publishing
-* Publishing options:: Tweaking HTML export
+* Publishing options:: Tweaking HTML/@LaTeX{} export
* Publishing links:: Which links keep working after publishing?
-* Project page index:: Publishing a list of project files
+* Sitemap:: Generating a list of all pages
+* Generating an index:: An index that reaches across pages
Sample configuration
* Simple example:: One-component publishing
* Complex example:: A multi-component publishing example
+Working with source code
+
+* Structure of code blocks:: Code block syntax described
+* Editing source code:: Language major-mode editing
+* Exporting code blocks:: Export contents and/or results
+* Extracting source code:: Create pure source code files
+* Evaluating code blocks:: Place results of evaluation in the Org mode buffer
+* Library of Babel:: Use and contribute to a library of useful code blocks
+* Languages:: List of supported code block languages
+* Header arguments:: Configure code block functionality
+* Results of evaluation:: How evaluation results are handled
+* Noweb reference syntax:: Literate programming in Org mode
+* Key bindings and useful functions:: Work quickly with code blocks
+* Batch execution:: Call functions from the command line
+
+Header arguments
+
+* Using header arguments:: Different ways to set header arguments
+* Specific header arguments:: List of header arguments
+
+Using header arguments
+
+* System-wide header arguments:: Set global default values
+* Language-specific header arguments:: Set default values by language
+* Header arguments in Org mode properties:: Set default values for a buffer or heading
+* Language-specific header arguments in Org mode properties:: Set language-specific default values for a buffer or heading
+* Code block specific header arguments:: The most common way to set values
+* Header arguments in function calls:: The most specific level
+
+Specific header arguments
+
+* var:: Pass arguments to code blocks
+* results:: Specify the type of results and how they will
+ be collected and handled
+* file:: Specify a path for file output
+* file-desc:: Specify a description for file results
+* dir:: Specify the default (possibly remote)
+ directory for code block execution
+* exports:: Export code and/or results
+* tangle:: Toggle tangling and specify file name
+* mkdirp:: Toggle creation of parent directories of target
+ files during tangling
+* comments:: Toggle insertion of comments in tangled
+ code files
+* padline:: Control insertion of padding lines in tangled
+ code files
+* no-expand:: Turn off variable assignment and noweb
+ expansion during tangling
+* 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
+* colnames:: Handle column names in tables
+* rownames:: Handle row names in tables
+* shebang:: Make tangled files executable
+* tangle-mode:: Set permission of tangled files
+* eval:: Limit evaluation of specific code blocks
+* wrap:: Mark source block evaluation results
+* post:: Post processing of code block results
+* prologue:: Text to prepend to code block body
+* epilogue:: Text to append to code block body
+
Miscellaneous
* Completion:: M-TAB knows what you need
-* Speed keys:: Electic commands at the beginning of a headline
+* Easy Templates:: Quick insertion of structural elements
+* Speed keys:: Electric commands at the beginning of a headline
+* Code evaluation security:: Org mode files evaluate inline code
* Customization:: Adapting Org to your taste
* In-buffer settings:: Overview of the #+KEYWORDS
* The very busy C-c C-c key:: When in doubt, press C-c C-c
* Clean view:: Getting rid of leading stars in the outline
* TTY keys:: Using Org on a tty
* Interaction:: Other Emacs packages
+* org-crypt:: Encrypting Org files
Interaction with other packages
Hacking
-* Hooks:: Who to reach into Org's internals
+* Hooks:: How to reach into Org's internals
* Add-on packages:: Available extensions
* Adding hyperlink types:: New custom link types
+* Adding export back-ends:: How to write new export back-ends
* Context-sensitive commands:: How to add functionality to such commands
-* Tables in arbitrary syntax:: Orgtbl for La@TeX{} and other programs
+* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
-* Extracting agenda information:: Postprocessing of agenda information
+* Speeding up your agendas:: Tips on how to speed up your agendas
+* Extracting agenda information:: Post-processing of agenda information
* Using the property API:: Writing programs that use entry properties
* Using the mapping API:: Mapping over all or selected entries
Tables and lists in arbitrary syntax
* Radio tables:: Sending and receiving radio tables
-* A LaTeX example:: Step by step, almost a tutorial
+* A @LaTeX{} example:: Step by step, almost a tutorial
* Translator functions:: Copy and modify
-* Radio lists:: Doing the same for lists
+* Radio lists:: Sending and receiving lists
MobileOrg
@menu
* Summary:: Brief summary of what Org does
-* Installation:: How to install a downloaded version of Org
+* Installation:: Installing Org
* Activation:: How to activate Org for certain buffers
* Feedback:: Bug reports, ideas, patches etc.
-* Conventions:: Type-setting conventions in the manual
+* Conventions:: Typesetting conventions in the manual
@end menu
@node Summary, Installation, Introduction, Introduction
agenda that utilizes and smoothly integrates much of the Emacs calendar
and diary. Plain text URL-like links connect to websites, emails,
Usenet messages, BBDB entries, and any files related to the projects.
-For printing and sharing of notes, an Org file can be exported as a
+For printing and sharing notes, an Org file can be exported as a
structured ASCII file, as HTML, or (TODO and agenda items only) as an
iCalendar file. It can also serve as a publishing tool for a set of
linked web pages.
-An important design aspect that distinguishes Org from, for example,
-Planner/Muse is that it encourages you to store every piece of information
-only once. In Planner, you have project pages, day pages and possibly
-other files, duplicating some information such as tasks. In Org,
-you only have notes files. In your notes you mark entries as tasks, and
-label them with tags and timestamps. All necessary lists, like a
-schedule for the day, the agenda for a meeting, tasks lists selected by
-tags, etc., are created dynamically when you need them.
+As a project planning environment, Org works by adding metadata to outline
+nodes. Based on this data, specific entries can be extracted in queries and
+create dynamic @i{agenda views}.
+
+Org mode contains the Org Babel environment which allows you to work with
+embedded source code blocks in a file, to facilitate code evaluation,
+documentation, and literate programming techniques.
+
+Org's automatic, context-sensitive table editor with spreadsheet
+capabilities can be integrated into any major mode by activating the
+minor Orgtbl mode. Using a translation step, it can be used to maintain
+tables in arbitrary file types, for example in @LaTeX{}. The structure
+editing and list creation capabilities can be used outside Org with
+the minor Orgstruct mode.
Org keeps simple things simple. When first fired up, it should
feel like a straightforward, easy to use outliner. Complexity is not
imposed, but a large amount of functionality is available when you need
-it. Org is a toolbox and can be used in different ways, for
-example as:
+it. Org is a toolbox and can be used in different ways and for different
+ends, for example:
@example
@r{@bullet{} an outline extension with visibility cycling and structure editing}
@r{@bullet{} an ASCII system and table editor for taking structured notes}
-@r{@bullet{} an ASCII table editor with spreadsheet-like capabilities}
@r{@bullet{} a TODO list editor}
@r{@bullet{} a full agenda and planner with deadlines and work scheduling}
@pindex GTD, Getting Things Done
-@r{@bullet{} an environment to implement David Allen's GTD system}
-@r{@bullet{} a basic database application}
-@r{@bullet{} a simple hypertext system, with HTML and La@TeX{} export}
-@r{@bullet{} a publishing tool to create a set of interlinked webpages}
+@r{@bullet{} an environment in which to implement David Allen's GTD system}
+@r{@bullet{} a simple hypertext system, with HTML and @LaTeX{} export}
+@r{@bullet{} a publishing tool to create a set of interlinked web pages}
+@r{@bullet{} an environment for literate programming}
@end example
-Org's automatic, context-sensitive table editor with spreadsheet
-capabilities can be integrated into any major mode by activating the
-minor Orgtbl mode. Using a translation step, it can be used to maintain
-tables in arbitrary file types, for example in La@TeX{}. The structure
-editing and list creation capabilities can be used outside Org with
-the minor Orgstruct mode.
-
@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
+The version 7.3 of this manual is available as a
+@uref{http://www.network-theory.co.uk/org/manual/, paperback book from Network
+Theory Ltd.}
+
@page
@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}.}
+Org is part of recent distributions of GNU Emacs, so you normally don't need
+to install it. If, for one reason or another, you want to install Org on top
+of this pre-packaged version, there are three ways to do it:
-If you have downloaded Org from the Web, either as a distribution @file{.zip}
-or @file{.tar} file, or as a Git archive, you must take the following steps
-to install it: go into the unpacked Org distribution directory and edit the
-top section of the file @file{Makefile}. You must set the name of the Emacs
-binary (likely either @file{emacs} or @file{xemacs}), and the paths to the
-directories where local Lisp and Info files are kept. If you don't have
-access to the system-wide directories, you can simply run Org directly from
-the distribution directory by adding the @file{lisp} subdirectory to the
-Emacs load path. To do this, add the following line to @file{.emacs}:
+@itemize @bullet
+@item By using Emacs package system.
+@item By downloading Org as an archive.
+@item By using Org's git repository.
+@end itemize
-@example
-(setq load-path (cons "~/path/to/orgdir/lisp" load-path))
-@end example
+We @b{strongly recommend} to stick to a single installation method.
-@noindent
-If you plan to use code from the @file{contrib} subdirectory, do a similar
-step for this directory:
+@subsubheading Using Emacs packaging system
-@example
-(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))
-@end example
+Recent Emacs distributions include a packaging system which lets you install
+Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
+You need to do this in a session where no @code{.org} file has been visited.
+Then, to make sure your Org configuration is taken into account, initialize
+the package system with @code{(package-initialize)} in your @file{.emacs}
+before setting any Org option. If you want to use Org's package repository,
+check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
-@sp 2
-@cartouche
-XEmacs users now need to install the file @file{noutline.el} from
-the @file{xemacs} sub-directory of the Org distribution. Use the
-command:
+@subsubheading Downloading Org as an archive
-@example
- make install-noutline
-@end example
-@end cartouche
-@sp 2
+You can download Org latest release from @uref{http://orgmode.org/, Org's
+website}. In this case, make sure you set the load-path correctly in your
+@file{.emacs}:
-@noindent Now byte-compile the Lisp files with the shell command:
+@lisp
+(add-to-list 'load-path "~/path/to/orgdir/lisp")
+@end lisp
-@example
-make
-@end example
+The downloaded archive contains contributed libraries that are not included
+in Emacs. If you want to use them, add the @file{contrib} directory to your
+load-path:
-@noindent If you are running Org from the distribution directory, this is
-all. If you want to install Org into the system directories, use (as
-administrator)
+@lisp
+(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
+@end lisp
-@example
-make install
-@end example
+Optionally, you can compile the files and/or install them in your system.
+Run @code{make help} to list compilation and installation options.
-Installing Info files is system dependent, because of differences in the
-@file{install-info} program. In Debian it copies the info files into the
-correct directory and modifies the info directory file. In many other
-systems, the files need to be copied to the correct directory separately, and
-@file{install-info} then only modifies the directory file. Check your system
-documentation to find out which of the following commands you need:
+@subsubheading Using Org's git repository
+
+You can clone Org's repository and install Org like this:
@example
-make install-info
-make install-info-debian
+$ cd ~/src/
+$ git clone git://orgmode.org/org-mode.git
+$ make autoloads
@end example
-Then add the following line to @file{.emacs}. It is needed so that
-Emacs can autoload functions that are located in files not immediately loaded
-when Org-mode starts.
-@lisp
-(require 'org-install)
-@end lisp
+Note that in this case, @code{make autoloads} is mandatory: it defines Org's
+version in @file{org-version.el} and Org's autoloads in
+@file{org-loaddefs.el}.
-Do not forget to activate Org as described in the following section.
-@page
+Remember to add the correct load-path as described in the method above.
+
+You can also compile with @code{make}, generate the documentation with
+@code{make doc}, create a local configuration with @code{make config} and
+install Org with @code{make install}. Please run @code{make help} to get
+the list of compilation/installation options.
+
+For more detailed explanations on Org's build system, please check the Org
+Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
+Worg}.
@node Activation, Feedback, Installation, Introduction
@section Activation
@cindex activation
@cindex autoload
+@cindex ELPA
@cindex global key bindings
@cindex key bindings, global
+@findex org-agenda
+@findex org-capture
+@findex org-store-link
+@findex org-iswitchb
-@iftex
-@b{Important:} @i{If you use copy-and-paste to copy Lisp code from the
-PDF documentation as viewed by some PDF viewers to your @file{.emacs} file, the
-single-quote character comes out incorrectly and the code will not work.
-You need to fix the single-quotes by hand, or copy from Info
-documentation.}
-@end iftex
-
-Add the following lines to your @file{.emacs} file. The last three lines
-define @emph{global} keys for the commands @command{org-store-link},
-@command{org-agenda}, and @command{org-iswitchb}---please choose suitable
-keys yourself.
+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:
@lisp
-;; The following lines are always needed. Choose your own keys.
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
-(global-set-key "\C-cl" 'org-store-link)
-(global-set-key "\C-ca" 'org-agenda)
-(global-set-key "\C-cb" 'org-iswitchb)
@end lisp
-Furthermore, you must activate @code{font-lock-mode} in Org
-buffers, because significant functionality depends on font-locking being
-active. You can do this with either one of the following two lines
-(XEmacs users must use the second option):
+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
+suggested bindings for these keys, please modify the keys to your own
+liking.
@lisp
-(global-font-lock-mode 1) ; for all buffers
-(add-hook 'org-mode-hook 'turn-on-font-lock) ; Org buffers only
+(global-set-key "\C-cl" 'org-store-link)
+(global-set-key "\C-cc" 'org-capture)
+(global-set-key "\C-ca" 'org-agenda)
+(global-set-key "\C-cb" 'org-iswitchb)
@end lisp
@cindex Org mode, turning on
If you find problems with Org, or if you have questions, remarks, or ideas
about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
If you are not a member of the mailing list, your mail will be passed to the
-list after a moderator has approved it.
-
-For bug reports, please provide as much information as possible, including
-the version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
-(@kbd{M-x org-version @key{RET}}), as well as the Org related setup in
+list after a moderator has approved it@footnote{Please consider subscribing
+to the mailing list, in order to minimize the work the mailing list
+moderators have to do.}.
+
+For bug reports, please first try to reproduce the bug with the latest
+version of Org available---if you are running an outdated version, it is
+quite possible that the bug has been fixed already. If the bug persists,
+prepare a report and provide as much information as possible, including the
+version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
+(@kbd{M-x org-version RET}), as well as the Org related setup in
@file{.emacs}. The easiest way to do this is to use the command
@example
-@kbd{M-x org-submit-bug-report}
+@kbd{M-x org-submit-bug-report RET}
@end example
@noindent which will put all this information into an Emacs mail buffer so
that you only need to add your description. If you re not sending the Email
from within Emacs, please copy and paste the content into your Email program.
+Sometimes you might face a problem due to an error in your Emacs or Org mode
+setup. Before reporting a bug, it is very helpful to start Emacs with minimal
+customizations and reproduce the problem. Doing so often helps you determine
+if the problem is with your customization or with Org mode itself. You can
+start a typical minimal session with a command like the example below.
+
+@example
+$ emacs -Q -l /path/to/minimal-org.el
+@end example
+
+However if you are using Org mode as distributed with Emacs, a minimal setup
+is not necessary. In that case it is sufficient to start Emacs as
+@code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
+shown below.
+
+@lisp
+;;; Minimal setup to load latest `org-mode'
+
+;; activate debugging
+(setq debug-on-error t
+ debug-on-signal nil
+ debug-on-quit nil)
+
+;; add latest org-mode to load path
+(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
+(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
+@end lisp
+
If an error occurs, a backtrace can be very useful (see below on how to
create one). Often a small example file helps, along with clear information
about:
@item What did you expect to happen?
@item What happened instead?
@end enumerate
-@noindent Thank you for helping to improve this mode.
+@noindent Thank you for helping to improve this program.
@subsubheading How to create a useful backtrace
@enumerate
@item
-Reload uncompiled versions of all Org-mode Lisp files. The backtrace
+Reload uncompiled versions of all Org mode Lisp files. The backtrace
contains much more information if it is produced with uncompiled code.
To do this, use
@example
-C-u M-x org-reload RET
+@kbd{C-u M-x org-reload RET}
@end example
@noindent
or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
@node Conventions, , Feedback, Introduction
@section Typesetting conventions used in this manual
-Org uses three types of keywords: TODO keywords, tags, and property
+@subsubheading TODO keywords, tags, properties, etc.
+
+Org mainly uses three types of keywords: TODO keywords, tags and property
names. In this manual we use the following conventions:
@table @code
special meaning are written with all capitals.
@end table
+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
+@chapter Document structure
@cindex document structure
@cindex structure of document
* Blocks:: Folding blocks
* Footnotes:: How footnotes are defined in Org's syntax
* Orgstruct mode:: Structure editing outside Org
+* Org syntax:: Formal description of Org's syntax
@end menu
@node Outlines, Headlines, Document Structure, Document Structure
@cindex headlines
@cindex outline tree
@vindex org-special-ctrl-a/e
+@vindex org-special-ctrl-k
+@vindex org-ctrl-k-protect-subtree
-Headlines define the structure of an outline tree. The headlines in
-Org start with one or more stars, on the left margin@footnote{See
-the variable @code{org-special-ctrl-a/e} to configure special behavior
-of @kbd{C-a} and @kbd{C-e} in headlines.}. For example:
+Headlines define the structure of an outline tree. The headlines in Org
+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.} @footnote{Clocking only works with
+headings indented less then 30 stars.}. For example:
@example
* Top level headline
@cindex show hidden text
@cindex hide text
+@menu
+* Global and local cycling:: Cycling through various visibility states
+* Initial visibility:: Setting the initial visibility state
+* Catching invisible edits:: Preventing mistakes when editing invisible parts
+@end menu
+
+@node Global and local cycling, Initial visibility, Visibility cycling, Visibility cycling
+@subsection Global and local cycling
+
Outlines make it possible to hide parts of the text in the buffer.
Org uses just two commands, bound to @key{TAB} and
@kbd{S-@key{TAB}} to change the visibility in the buffer.
@cindex folded, subtree visibility state
@cindex children, subtree visibility state
@cindex subtree, subtree visibility state
-@table @kbd
-@kindex @key{TAB}
-@item @key{TAB}
+@table @asis
+@orgcmd{@key{TAB},org-cycle}
@emph{Subtree cycling}: Rotate current subtree among the states
@example
@cindex overview, global visibility state
@cindex contents, global visibility state
@cindex show all, global visibility state
-@kindex S-@key{TAB}
-@item S-@key{TAB}
+@orgcmd{S-@key{TAB},org-global-cycle}
@itemx C-u @key{TAB}
@emph{Global cycling}: Rotate the entire buffer among the states
CONTENTS view up to headlines of level N will be shown. Note that inside
tables, @kbd{S-@key{TAB}} jumps to the previous field.
+@cindex set startup visibility, command
+@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
+Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
@cindex show all, command
-@kindex C-u C-u C-u @key{TAB}
-@item C-u C-u C-u @key{TAB}
+@orgcmd{C-u C-u C-u @key{TAB},show-all}
Show all, including drawers.
-@kindex C-c C-r
-@item C-c C-r
+@cindex revealing context
+@orgcmd{C-c C-r,org-reveal}
Reveal context around point, showing the current entry, the following heading
and the hierarchy above. Useful for working near a location that has been
exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
(@pxref{Agenda commands}). With a prefix argument show, on each
-level, all sibling headings.
-@kindex C-c C-x b
-@item C-c C-x b
+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
@ifinfo
prefix argument N, go up to level N and then take that tree. If N is
negative then go up that many levels. With a @kbd{C-u} prefix, do not remove
the previously used indirect buffer.
+@orgcmd{C-c C-x v,org-copy-visible}
+Copy the @i{visible} text in the region into the kill ring.
@end table
+@menu
+* Initial visibility:: Setting the initial visibility state
+* Catching invisible edits:: Preventing mistakes when editing invisible parts
+@end menu
+
+@node Initial visibility, Catching invisible edits, Global and local cycling, Visibility cycling
+@subsection Initial visibility
+
+@cindex visibility, initialize
@vindex org-startup-folded
+@vindex org-agenda-inhibit-startup
@cindex @code{overview}, STARTUP keyword
@cindex @code{content}, STARTUP keyword
@cindex @code{showall}, STARTUP keyword
@cindex @code{showeverything}, STARTUP keyword
-When Emacs first visits an Org file, the global state is set to
-OVERVIEW, i.e. only the top level headlines are visible. This can be
-configured through the variable @code{org-startup-folded}, or on a
-per-file basis by adding one of the following lines anywhere in the
-buffer:
+When Emacs first visits an Org file, the global state is set to OVERVIEW,
+i.e., only the top level headlines are visible@footnote{When
+@code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default
+visibility state when first opening a file for the agenda (@pxref{Speeding up
+your agendas}).} This can be configured through the variable
+@code{org-startup-folded}, or on a per-file basis by adding one of the
+following lines anywhere in the buffer:
@example
#+STARTUP: overview
#+STARTUP: showeverything
@end example
+The startup visibility options are ignored when the file is open for the
+first time during the agenda generation: if you want the agenda to honor
+the startup visibility, set @code{org-agenda-inhibit-startup} to @code{nil}.
+
@cindex property, VISIBILITY
@noindent
Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
and Columns}) will get their visibility adapted accordingly. Allowed values
for this property are @code{folded}, @code{children}, @code{content}, and
@code{all}.
-@table @kbd
-@kindex C-u C-u @key{TAB}
-@item C-u C-u @key{TAB}
-Switch back to the startup visibility of the buffer, i.e. whatever is
+
+@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
requested by startup options and @samp{VISIBILITY} properties in individual
entries.
@end table
+@node Catching invisible edits, , Initial visibility, Visibility cycling
+@subsection Catching invisible edits
+
+@vindex org-catch-invisible-edits
+@cindex edits, catching invisible
+Sometimes you may inadvertently edit an invisible part of the buffer and be
+confused on what has been edited and how to undo the mistake. Setting
+@code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the
+docstring of this option on how Org should catch invisible edits and process
+them.
+
@node Motion, Structure editing, Visibility cycling, Document Structure
@section Motion
@cindex motion, between headlines
@cindex headline navigation
The following commands jump to other headlines in the buffer.
-@table @kbd
-@kindex C-c C-n
-@item C-c C-n
+@table @asis
+@orgcmd{C-c C-n,outline-next-visible-heading}
Next heading.
-@kindex C-c C-p
-@item C-c C-p
+@orgcmd{C-c C-p,outline-previous-visible-heading}
Previous heading.
-@kindex C-c C-f
-@item C-c C-f
+@orgcmd{C-c C-f,org-forward-same-level}
Next heading same level.
-@kindex C-c C-b
-@item C-c C-b
+@orgcmd{C-c C-b,org-backward-same-level}
Previous heading same level.
-@kindex C-c C-u
-@item C-c C-u
+@orgcmd{C-c C-u,outline-up-heading}
Backward to higher level heading.
-@kindex C-c C-j
-@item C-c C-j
+@orgcmd{C-c C-j,org-goto}
Jump to a different place without changing the current outline
visibility. Shows the document structure in a temporary buffer, where
you can use the following keys to find your destination:
@end example
@vindex org-goto-interface
@noindent
-See also the variable @code{org-goto-interface}.
+See also the option @code{org-goto-interface}.
@end table
@node Structure editing, Sparse trees, Motion, Document Structure
@cindex sorting, of subtrees
@cindex subtrees, cut and paste
-@table @kbd
-@kindex M-@key{RET}
-@item M-@key{RET}
+@table @asis
+@orgcmd{M-@key{RET},org-insert-heading}
@vindex org-M-RET-may-split-line
-Insert new heading with same level as current. If the cursor is in a
-plain list item, a new item is created (@pxref{Plain lists}). To force
-creation of a new headline, use a prefix argument, or first press @key{RET}
-to get to the beginning of the next line. When this command is used in
-the middle of a line, the line is split and the rest of the line becomes
-the new headline@footnote{If you do not want the line to be split,
-customize the variable @code{org-M-RET-may-split-line}.}. If the
-command is used at the beginning of a headline, the new headline is
-created before the current line. If at the beginning of any other line,
-the content of that line is made the new heading. If the command is
-used at the end of a folded subtree (i.e. behind the ellipses at the end
-of a headline), then a headline like the current one will be inserted
-after the end of the subtree.
-@kindex C-@key{RET}
-@item C-@key{RET}
+Insert a new heading/item with the same level than the one at point.
+If the cursor is in a plain list item, a new item is created
+(@pxref{Plain lists}). To prevent this behavior in lists, call the
+command with a prefix argument. When this command is used in the
+middle of a line, the line is split and the rest of the line becomes
+the new item or headline@footnote{If you do not want the line to be
+split, customize the variable @code{org-M-RET-may-split-line}.}. If
+the command is used at the @emph{beginning} of a headline, the new
+headline is created before the current line. If the command is used
+at the @emph{end} of a folded subtree (i.e., behind the ellipses at
+the end of a headline), then a headline will be
+inserted after the end of the subtree. Calling this command with
+@kbd{C-u C-u} will unconditionally respect the headline's content and
+create a new item at the end of the parent subtree.
+@orgcmd{C-@key{RET},org-insert-heading-respect-content}
Just like @kbd{M-@key{RET}}, except when adding a new heading below the
current heading, the new heading is placed after the body instead of before
it. This command works from anywhere in the entry.
-@kindex M-S-@key{RET}
-@item M-S-@key{RET}
+@orgcmd{M-S-@key{RET},org-insert-todo-heading}
@vindex org-treat-insert-todo-heading-as-state-change
Insert new TODO entry with same level as current heading. See also the
variable @code{org-treat-insert-todo-heading-as-state-change}.
-@kindex C-S-@key{RET}
-@item C-S-@key{RET}
+@orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
Insert new TODO entry with same level as current heading. Like
@kbd{C-@key{RET}}, the new headline will be inserted after the current
subtree.
-@kindex @key{TAB}
-@item @key{TAB} @r{in new, empty entry}
+@orgcmd{@key{TAB},org-cycle}
In a new entry with no text yet, the first @key{TAB} demotes the entry to
become a child of the previous one. The next @key{TAB} makes it a parent,
and so on, all the way to top level. Yet another @key{TAB}, and you are back
to the initial level.
-@kindex M-@key{left}
-@item M-@key{left}
+@orgcmd{M-@key{left},org-do-promote}
Promote current heading by one level.
-@kindex M-@key{right}
-@item M-@key{right}
+@orgcmd{M-@key{right},org-do-demote}
Demote current heading by one level.
-@kindex M-S-@key{left}
-@item M-S-@key{left}
+@orgcmd{M-S-@key{left},org-promote-subtree}
Promote the current subtree by one level.
-@kindex M-S-@key{right}
-@item M-S-@key{right}
+@orgcmd{M-S-@key{right},org-demote-subtree}
Demote the current subtree by one level.
-@kindex M-S-@key{up}
-@item M-S-@key{up}
+@orgcmd{M-S-@key{up},org-move-subtree-up}
Move subtree up (swap with previous subtree of same
level).
-@kindex M-S-@key{down}
-@item M-S-@key{down}
+@orgcmd{M-S-@key{down},org-move-subtree-down}
Move subtree down (swap with next subtree of same level).
-@kindex C-c C-x C-w
-@item C-c C-x C-w
-Kill subtree, i.e. remove it from buffer but save in kill ring.
+@orgcmd{M-h,org-mark-element}
+Mark the element at point. Hitting repeatedly will mark subsequent elements
+of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
+hitting @key{M-h} immediately again will mark the next one.
+@orgcmd{C-c @@,org-mark-subtree}
+Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
+of the same level than the marked subtree.
+@orgcmd{C-c C-x C-w,org-cut-subtree}
+Kill subtree, i.e., remove it from buffer but save in kill ring.
With a numeric prefix argument N, kill N sequential subtrees.
-@kindex C-c C-x M-w
-@item C-c C-x M-w
+@orgcmd{C-c C-x M-w,org-copy-subtree}
Copy subtree to kill ring. With a numeric prefix argument N, copy the N
sequential subtrees.
-@kindex C-c C-x C-y
-@item C-c C-x C-y
+@orgcmd{C-c C-x C-y,org-paste-subtree}
Yank subtree from kill ring. This does modify the level of the subtree to
make sure the tree fits in nicely at the yank position. The yank level can
also be specified with a numeric prefix argument, or by yanking after a
headline marker like @samp{****}.
-@kindex C-y
-@item C-y
+@orgcmd{C-y,org-yank}
@vindex org-yank-adjusted-subtrees
@vindex org-yank-folded-subtrees
-Depending on the variables @code{org-yank-adjusted-subtrees} and
+Depending on the options @code{org-yank-adjusted-subtrees} and
@code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
paste subtrees folded and in a clever way, using the same command as @kbd{C-c
C-x C-y}. With the default settings, no level adjustment will take place,
force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a
yank, it will yank previous kill items plainly, without adjustment and
folding.
-@kindex C-c C-x c
-@item C-c C-x c
+@orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
Clone a subtree by making a number of sibling copies of it. You will be
prompted for the number of copies to make, and you can also specify if any
timestamps in the entry should be shifted. This can be useful, for example,
to create a number of tasks related to a series of lectures to prepare. For
more details, see the docstring of the command
@code{org-clone-subtree-with-time-shift}.
-@kindex C-c C-w
-@item C-c C-w
-Refile entry or region to a different location. @xref{Refiling notes}.
-@kindex C-c ^
-@item C-c ^
+@orgcmd{C-c C-w,org-refile}
+Refile entry or region to a different location. @xref{Refile and copy}.
+@orgcmd{C-c ^,org-sort}
Sort same-level entries. When there is an active region, all entries in the
region will be sorted. Otherwise the children of the current headline are
sorted. The command prompts for the sorting method, which can be
(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.
-@kindex C-x n s
-@item C-x n s
+sorting will be case-sensitive.
+@orgcmd{C-x n s,org-narrow-to-subtree}
Narrow buffer to current subtree.
-@kindex C-x n w
-@item C-x n w
+@orgcmd{C-x n b,org-narrow-to-block}
+Narrow buffer to current block.
+@orgcmd{C-x n w,widen}
Widen buffer to remove narrowing.
-@kindex C-c *
-@item C-c *
+@orgcmd{C-c *,org-toggle-heading}
Turn a normal line or plain list item into a headline (so that it becomes a
subheading at its location). Also turn a headline into a normal line by
removing the stars. If there is an active region, turn all lines in the
Org mode contains several commands creating such trees, all these
commands can be accessed through a dispatcher:
-@table @kbd
-@kindex C-c /
-@item C-c /
+@table @asis
+@orgcmd{C-c /,org-sparse-tree}
This prompts for an extra key to select a sparse-tree creating command.
-@kindex C-c / r
-@item C-c / r
+@orgcmd{C-c / r,org-occur}
@vindex org-remove-highlights-with-change
-Occur. Prompts for a regexp and shows a sparse tree with all matches. If
+Prompts for a regexp and shows a sparse tree with all matches. If
the match is in a headline, the headline is made visible. If the match is in
the body of an entry, headline and body are made visible. In order to
provide minimal context, also the full hierarchy of headlines above the match
@code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
When called with a @kbd{C-u} prefix argument, previous highlights are kept,
so several calls to this command can be stacked.
+@orgcmdkkc{M-g n,M-g M-n,next-error}
+Jump to the next sparse tree match in this buffer.
+@orgcmdkkc{M-g p,M-g M-p,previous-error}
+Jump to the previous sparse tree match in this buffer.
@end table
@noindent
@vindex org-agenda-custom-commands
For frequently used sparse trees of specific search strings, you can
-use the variable @code{org-agenda-custom-commands} to define fast
+use the option @code{org-agenda-custom-commands} to define fast
keyboard access to specific sparse trees. These commands will then be
accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
For example:
The other sparse tree commands select headings based on TODO keywords,
tags, or properties and will be discussed later in this manual.
-@kindex C-c C-e v
+@kindex C-c C-e C-v
@cindex printing sparse trees
@cindex visible text, printing
To print a sparse tree, you can use the Emacs command
@code{ps-print-buffer-with-faces} which does not print invisible parts
of the document @footnote{This does not work under XEmacs, because
XEmacs uses selective display for outlining, not text properties.}.
-Or you can use the command @kbd{C-c C-e v} to export only the visible
-part of the document and print the resulting file.
+Or you can use @kbd{C-c C-e C-v} to export only the visible part of
+the document and print the resulting file.
@node Plain lists, Drawers, Sparse trees, Document Structure
@section Plain lists
@cindex ordered lists
Within an entry of the outline tree, hand-formatted lists can provide
-additional structure. They also provide a way to create lists of
-checkboxes (@pxref{Checkboxes}). Org supports editing such lists,
-and the HTML exporter (@pxref{Exporting}) parses and formats them.
+additional structure. They also provide a way to create lists of checkboxes
+(@pxref{Checkboxes}). Org supports editing such lists, and every exporter
+(@pxref{Exporting}) can parse and format them.
Org knows ordered lists, unordered lists, and description lists.
@itemize @bullet
@emph{Unordered} list items start with @samp{-}, @samp{+}, or
@samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
they will be seen as top-level headlines. Also, when you are hiding leading
-stars to get a clean outline view, plain list items starting with a star are
-visually indistinguishable from true headlines. In short: even though
-@samp{*} is supported, it may be better to not use it for plain list items.}
-as bullets.
+stars to get a clean outline view, plain list items starting with a star may
+be hard to distinguish from true headlines. In short: even though @samp{*}
+is supported, it may be better to not use it for plain list items.} as
+bullets.
@item
+@vindex org-plain-list-ordered-item-terminator
+@vindex org-list-allow-alphabetical
@emph{Ordered} list items start with a numeral followed by either a period or
-a right parenthesis, such as @samp{1.} or @samp{1)}.
+a right parenthesis@footnote{You can filter out any of them by configuring
+@code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
+@samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
+@samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize
+confusion with normal text, those are limited to one character only. Beyond
+that limit, bullets will automatically fallback to numbers.}. If you want a
+list to start with a different value (e.g., 20), start the text of the item
+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
+be used in any item of the list in order to enforce a particular numbering.
@item
@emph{Description} list items are unordered list items, and contain the
-separator @samp{ :: } to separate the description @emph{term} from the
+separator @samp{ :: } to distinguish the description @emph{term} from the
description.
@end itemize
-@vindex org-empty-line-terminates-plain-lists
Items belonging to the same list must have the same indentation on the first
line. In particular, if an ordered list reaches number @samp{10.}, then the
2--digit numbers must be written left-aligned with the other numbers in the
-list. Indentation also determines the end of a list item. It ends before
-the next line that is indented like the bullet/number, or less. Empty lines
-are part of the previous item, so you can have several paragraphs in one
-item. If you would like an empty line to terminate all currently open plain
-lists, configure the variable @code{org-empty-line-terminates-plain-lists}.
-Here is an example:
+list. An item ends before the next line that is less or equally indented
+than its bullet/number.
+
+@vindex org-list-empty-line-terminates-plain-lists
+A list ends whenever every item has ended, which means before any line less
+or equally indented than items at top level. It also ends before two blank
+lines@footnote{See also @code{org-list-empty-line-terminates-plain-lists}.}.
+In that case, all items are closed. Here is an example:
@example
@group
+ this was already my favorite scene in the book
+ I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
- - on DVD only
+ - on DVD only
He makes a really funny face when it happens.
But in the end, no individual scenes matter but the film as a whole.
Important actors in this film are:
put into @file{.emacs}: @code{(require 'filladapt)}}, and by exporting them
properly (@pxref{Exporting}). Since indentation is what governs the
structure of these lists, many structural constructs like @code{#+BEGIN_...}
-blocks can be indented to signal that they should be part of a list item.
-
-The following commands act on items when the cursor is in the first line
-of an item (the line with the bullet or number).
+blocks can be indented to signal that they belong to a particular item.
+
+@vindex org-list-demote-modify-bullet
+@vindex org-list-indent-offset
+If you find that using a different bullet for a sub-list (than that used for
+the current list-level) improves readability, customize the variable
+@code{org-list-demote-modify-bullet}. To get a greater difference of
+indentation between items and theirs sub-items, customize
+@code{org-list-indent-offset}.
+
+@vindex org-list-automatic-rules
+The following commands act on items when the cursor is in the first line of
+an item (the line with the bullet or number). Some of them imply the
+application of automatic rules to keep list structure intact. If some of
+these actions get in your way, configure @code{org-list-automatic-rules}
+to disable them individually.
-@table @kbd
-@kindex @key{TAB}
-@item @key{TAB}
+@table @asis
+@orgcmd{@key{TAB},org-cycle}
+@cindex cycling, in plain lists
@vindex org-cycle-include-plain-lists
Items can be folded just like headline levels. Normally this works only if
the cursor is on a plain list item. For more details, see the variable
-@code{org-cycle-include-plain-lists}. to @code{integrate}, plain list items
-will be treated like low-level. The level of an item is then given by the
-indentation of the bullet/number. Items are always subordinate to real
-headlines, however; the hierarchies remain completely separated.
-
-If @code{org-cycle-include-plain-lists} has not been set, @key{TAB}
-fixes the indentation of the current line in a heuristic way.
-@kindex M-@key{RET}
-@item M-@key{RET}
+@code{org-cycle-include-plain-lists}. If this variable is set to
+@code{integrate}, plain list items will be treated like low-level
+headlines. The level of an item is then given by the indentation of the
+bullet/number. Items are always subordinate to real headlines, however; the
+hierarchies remain completely separated. In a new item with no text yet, the
+first @key{TAB} demotes the item to become a child of the previous
+one. Subsequent @key{TAB}s move the item to meaningful levels in the list
+and eventually get it back to its initial position.
+@orgcmd{M-@key{RET},org-insert-heading}
@vindex org-M-RET-may-split-line
+@vindex org-list-automatic-rules
Insert new item at current level. With a prefix argument, force a new
heading (@pxref{Structure editing}). If this command is used in the middle
-of a line, the line is @emph{split} and the rest of the line becomes the new
-item@footnote{If you do not want the line to be split, customize the variable
-@code{org-M-RET-may-split-line}.}. If this command is executed in the
-@emph{whitespace before a bullet or number}, the new item is created
-@emph{before} the current item. If the command is executed in the white
-space before the text that is part of an item but does not contain the
-bullet, a bullet is added to the current line.
+of an item, that item is @emph{split} in two, and the second part becomes the
+new item@footnote{If you do not want the item to be split, customize the
+variable @code{org-M-RET-may-split-line}.}. If this command is executed
+@emph{before item's body}, the new item is created @emph{before} the current
+one.
+@end table
+
+@table @kbd
@kindex M-S-@key{RET}
@item M-S-@key{RET}
Insert a new item with a checkbox (@pxref{Checkboxes}).
-@kindex @key{TAB}
-@item @key{TAB} @r{in new, empty item}
-In a new item with no text yet, the first @key{TAB} demotes the item to
-become a child of the previous one. The next @key{TAB} makes it a parent,
-and so on, all the way to the left margin. Yet another @key{TAB}, and you
-are back to the initial level.
-@kindex S-@key{up}
@kindex S-@key{down}
-@item S-@key{up}
-@itemx S-@key{down}
+@item S-up
+@itemx S-down
@cindex shift-selection-mode
@vindex org-support-shift-select
-Jump to the previous/next item in the current list, but only if
+@vindex org-list-use-circular-motion
+Jump to the previous/next item in the current list@footnote{If you want to
+cycle around items that way, you may customize
+@code{org-list-use-circular-motion}.}, but only if
@code{org-support-shift-select} is off. If not, you can still use paragraph
jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
similar effect.
-@kindex M-S-@key{up}
-@kindex M-S-@key{down}
-@item M-S-@key{up}
-@itemx M-S-@key{down}
-Move the item including subitems up/down (swap with previous/next item
-of same indentation). If the list is ordered, renumbering is
-automatic.
+@kindex M-@key{up}
+@kindex M-@key{down}
+@item M-up
+@itemx M-down
+Move the item including subitems up/down@footnote{See
+@code{org-list-use-circular-motion} for a cyclic behavior.} (swap with
+previous/next item of same indentation). If the list is ordered, renumbering
+is automatic.
+@kindex M-@key{left}
+@kindex M-@key{right}
+@item M-left
+@itemx M-right
+Decrease/increase the indentation of an item, leaving children alone.
@kindex M-S-@key{left}
@kindex M-S-@key{right}
@item M-S-@key{left}
@itemx M-S-@key{right}
Decrease/increase the indentation of the item, including subitems.
-Initially, the item tree is selected based on current indentation.
-When these commands are executed several times in direct succession,
-the initially selected region is used, even if the new indentation
-would imply a different hierarchy. To use the new hierarchy, break
-the command chain with a cursor motion or so.
+Initially, the item tree is selected based on current indentation. When
+these commands are executed several times in direct succession, the initially
+selected region is used, even if the new indentation would imply a different
+hierarchy. To use the new hierarchy, break the command chain with a cursor
+motion or so.
+
+As a special case, using this command on the very first item of a list will
+move the whole list. This behavior can be disabled by configuring
+@code{org-list-automatic-rules}. The global indentation of a list has no
+influence on the text @emph{after} the list.
@kindex C-c C-c
@item C-c C-c
If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
-state of the checkbox. If not, this command makes sure that all the
-items on this list level use the same bullet. Furthermore, if this is
-an ordered list, make sure the numbering is OK.
+state of the checkbox. In any case, verify bullets and indentation
+consistency in the whole list.
@kindex C-c -
+@vindex org-plain-list-ordered-item-terminator
@item C-c -
Cycle the entire list level through the different itemize/enumerate bullets
-(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). With a numeric prefix
-argument N, select the Nth bullet from this list. If there is an active
-region when calling this, all lines will be converted to list items. If the
-first line already was a list item, any item markers will be removed from the
-list. Finally, even without an active region, a normal line will be
-converted into a list item.
+(@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 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
-its location). @xref{Structure editing}, for a detailed explanation.
+its location). @xref{Structure editing}, for a detailed explanation.
+@kindex C-c C-*
+@item C-c C-*
+Turn the whole plain list into a subtree of the current heading. Checkboxes
+(@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
+(resp. checked).
@kindex S-@key{left}
@kindex S-@key{right}
-@item S-@key{left}/@key{right}
+@item S-left/right
@vindex org-support-shift-select
This command also cycles bullet styles when the cursor in on the bullet or
anywhere in an item line, details depending on
@code{org-support-shift-select}.
@kindex C-c ^
+@cindex sorting, of plain list
@item C-c ^
Sort the plain list. You will be prompted for the sorting method:
-numerically, alphabetically, by time, or by custom function.
+numerically, alphabetically, by time, by checked status for check lists,
+or by a custom function.
@end table
@node Drawers, Blocks, Plain lists, Document Structure
@cindex visibility cycling, drawers
@vindex org-drawers
+@cindex org-insert-drawer
+@kindex C-c C-x d
Sometimes you want to keep information associated with an entry, but you
normally don't want to see it. For this, Org mode has @emph{drawers}.
-Drawers need to be configured with the variable
-@code{org-drawers}@footnote{You can define drawers on a per-file basis
-with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers
-look like this:
+Drawers need to be configured with the option @code{org-drawers}@footnote{You
+can define additional drawers on a per-file basis with a line like
+@code{#+DRAWERS: HIDDEN STATE}}. Drawers look like this:
@example
** This is a headline
Still outside the drawer
:DRAWERNAME:
- This is inside the drawer.
+ This is inside the drawer.
:END:
After the drawer.
@end example
+You can interactively insert drawers at point by calling
+@code{org-insert-drawer}, which is bound to @key{C-c C-x d}. With an active
+region, this command will put the region inside the drawer. With a prefix
+argument, this command calls @code{org-insert-property-drawer} and add a
+property drawer right below the current headline. Completion over drawer
+keywords is also possible using @key{M-TAB}.
+
Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
show the entry, but keep the drawer collapsed to a single line. In order to
look inside the drawer, you need to move the cursor to the drawer line and
press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
storing properties (@pxref{Properties and Columns}), and you can also arrange
for state change notes (@pxref{Tracking TODO state changes}) and clock times
-(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}.
+(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
+want to store a quick note in the LOGBOOK drawer, in a similar way to state changes, use
+
+@table @kbd
+@kindex C-c C-z
+@item C-c C-z
+Add a time-stamped note to the LOGBOOK drawer.
+@end table
+
+@vindex org-export-with-drawers
+You can select the name of the drawers which should be exported with
+@code{org-export-with-drawers}. In that case, drawer contents will appear in
+export output. Property drawers are not affected by this variable and are
+never exported.
@node Blocks, Footnotes, Drawers, Document Structure
@section Blocks
@vindex org-hide-block-startup
@cindex blocks, folding
-Org-mode uses begin...end blocks for various purposes from including source
+Org mode uses begin...end blocks for various purposes from including source
code examples (@pxref{Literal examples}) to capturing time logging
information (@pxref{Clocking work time}). These blocks can be folded and
unfolded by pressing TAB in the begin line. You can also get all blocks
-folded at startup by configuring the variable @code{org-hide-block-startup}
+folded at startup by configuring the option @code{org-hide-block-startup}
or on a per-file basis by using
@cindex @code{hideblocks}, STARTUP keyword
@cindex footnotes
Org mode supports the creation of footnotes. In contrast to the
-@file{footnote.el} package, Org mode's footnotes are designed for work on a
-larger document, not only for one-off documents like emails. The basic
-syntax is similar to the one used by @file{footnote.el}, i.e. a footnote is
-defined in a paragraph that is started by a footnote marker in square
-brackets in column 0, no indentation allowed. If you need a paragraph break
-inside a footnote, use the La@TeX{} idiom @samp{\par}. The footnote reference
-is simply the marker in square brackets, inside text. For example:
+@file{footnote.el} package, Org mode's footnotes are designed for work on
+a larger document, not only for one-off documents like emails.
+
+A footnote is started by a footnote marker in square brackets in column 0, no
+indentation allowed. It ends at the next footnote definition, headline, or
+after two consecutive empty lines. The footnote reference is simply the
+marker in square brackets, inside text. For example:
@example
The Org homepage[fn:1] now looks a lot better than it used to.
Org mode extends the number-based syntax to @emph{named} footnotes and
optional inline definition. Using plain numbers as markers (as
@file{footnote.el} does) is supported for backward compatibility, but not
-encouraged because of possible conflicts with La@TeX{} snippets (@pxref{Embedded
-LaTeX}). Here are the valid references:
+encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded
+@LaTeX{}}). Here are the valid references:
@table @code
@item [1]
A named footnote reference, where @code{name} is a unique label word, or, for
simplicity of automatic creation, a number.
@item [fn:: This is the inline definition of this footnote]
-A La@TeX{}-like anonymous footnote where the definition is given directly at the
+A @LaTeX{}-like anonymous footnote where the definition is given directly at the
reference point.
@item [fn:name: a definition]
An inline definition of a footnote, which also specifies a name for the note.
@vindex org-footnote-auto-label
Footnote labels can be created automatically, or you can create names yourself.
This is handled by the variable @code{org-footnote-auto-label} and its
-corresponding @code{#+STARTUP} keywords, see the docstring of that variable
+corresponding @code{#+STARTUP} keywords. See the docstring of that variable
for details.
@noindent The following command handles footnotes:
@vindex org-footnote-define-inline
@vindex org-footnote-section
@vindex org-footnote-auto-adjust
-Otherwise, create a new footnote. Depending on the variable
+Otherwise, create a new footnote. Depending on the option
@code{org-footnote-define-inline}@footnote{The corresponding in-buffer
setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
definition will be placed right into the text as part of the reference, or
-separately into the location determined by the variable
+separately into the location determined by the option
@code{org-footnote-section}.
When this command is called with a prefix argument, a menu of additional
@r{sequence. If you want them sorted, use this command, which will}
@r{also move entries according to @code{org-footnote-section}. Automatic}
@r{sorting after each insertion/deletion can be configured using the}
- @r{variable @code{org-footnote-auto-adjust}.}
+ @r{option @code{org-footnote-auto-adjust}.}
r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
- @r{after each insertion/deletion can be configured using the variable}
+ @r{after each insertion/deletion can be configured using the option}
@r{@code{org-footnote-auto-adjust}.}
S @r{Short for first @code{r}, then @code{s} action.}
n @r{Normalize the footnotes by collecting all definitions (including}
@r{inline definitions) into a special section, and then numbering them}
@r{in sequence. The references will then also be numbers. This is}
- @r{meant to be the final step before finishing a document (e.g. sending}
- @r{off an email). The exporters do this automatically, and so could}
- @r{something like @code{message-send-hook}.}
+ @r{meant to be the final step before finishing a document (e.g., sending}
+ @r{off an email).}
d @r{Delete the footnote at point, and all definitions of and references}
@r{to it.}
@end example
you can use the usual commands to follow these links.
@end table
-@node Orgstruct mode, , Footnotes, Document Structure
+@node Orgstruct mode, Org syntax, Footnotes, Document Structure
@section The Orgstruct minor mode
@cindex Orgstruct mode
@cindex minor mode for structure editing
If you like the intuitive way the Org mode structure editing and list
formatting works, you might want to use these commands in other modes like
Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes
-this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or
-turn it on by default, for example in Mail mode, with one of:
+this possible. Toggle the mode with @kbd{M-x orgstruct-mode RET}, or
+turn it on by default, for example in Message mode, with one of:
@lisp
-(add-hook 'mail-mode-hook 'turn-on-orgstruct)
-(add-hook 'mail-mode-hook 'turn-on-orgstruct++)
+(add-hook 'message-mode-hook 'turn-on-orgstruct)
+(add-hook 'message-mode-hook 'turn-on-orgstruct++)
@end lisp
When this mode is active and the cursor is on a line that looks to Org like a
headline or the first line of a list item, most structure editing commands
will work, even if the same keys normally have different functionality in the
major mode you are using. If the cursor is not in one of those special
-lines, Orgstruct mode lurks silently in the shadow. When you use
-@code{orgstruct++-mode}, Org will also export indentation and autofill
-settings into that mode, and detect item context after the first line of an
-item.
+lines, Orgstruct mode lurks silently in the shadows.
+
+When you use @code{orgstruct++-mode}, Org will also export indentation and
+autofill settings into that mode, and detect item context after the first
+line of an item.
+
+@vindex orgstruct-heading-prefix-regexp
+You can also use Org structure editing to fold and unfold headlines in
+@emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}:
+the regular expression must match the local prefix to use before Org's
+headlines. For example, if you set this variable to @code{";; "} in Emacs
+Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
+commented lines. Some commands like @code{org-demote} are disabled when the
+prefix is set, but folding/unfolding will work correctly.
+
+@node Org syntax, , Orgstruct mode, Document Structure
+@section Org syntax
+@cindex Org syntax
+
+A reference document providing a formal description of Org's syntax is
+available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on
+Worg}, written and maintained by Nicolas Goaziou. It defines Org's core
+internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
+keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org
+file falls into one of the categories above.
+
+To explore the abstract structure of an Org buffer, run this in a buffer:
+
+@lisp
+M-: (org-element-parse-buffer) RET
+@end lisp
+
+It will output a list containing the buffer's content represented as an
+abstract structure. The export engine relies on the information stored in
+this list. Most interactive commands (e.g., for structure editing) also
+rely on the syntactic meaning of the surrounding context.
@node Tables, Hyperlinks, Document Structure, Top
@chapter Tables
@cindex editing tables
Org comes with a fast and intuitive table editor. Spreadsheet-like
-calculations are supported in connection with 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
+calculations are supported using the Emacs @file{calc} package
+(@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 the first non-whitespace character is considered part of a
-table. @samp{|} is also the column separator. A table might look like
-this:
+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
+might look like this:
@example
| Name | Phone | Age |
typing @emph{immediately after the cursor was moved into a new field
with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
field is automatically made blank. If this behavior is too
-unpredictable for you, configure the variables
+unpredictable for you, configure the options
@code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
@table @kbd
@tsubheading{Creation and conversion}
-@kindex C-c |
-@item C-c |
-Convert the active region to table. If every line contains at least one
+@orgcmd{C-c |,org-table-create-or-convert-from-region}
+Convert the active region to table. If every line contains at least one
TAB character, the function assumes that the material is tab separated.
If every line contains a comma, comma-separated values (CSV) are assumed.
If not, lines are split at whitespace into fields. You can use a prefix
consecutive spaces, or alternatively a TAB will be the separator.
@*
If there is no active region, this command creates an empty Org
-table. But it's easier just to start typing, like
+table. But it is easier just to start typing, like
@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
@tsubheading{Re-aligning and field motion}
-@kindex C-c C-c
-@item C-c C-c
-Re-align the table without moving the cursor.
+@orgcmd{C-c C-c,org-table-align}
+Re-align the table and don't move to another field.
@c
-@kindex @key{TAB}
-@item @key{TAB}
+@orgcmd{<TAB>,org-table-next-field}
Re-align the table, move to the next field. Creates a new row if
necessary.
@c
-@kindex S-@key{TAB}
-@item S-@key{TAB}
+@orgcmd{S-@key{TAB},org-table-previous-field}
Re-align, move to previous field.
@c
-@kindex @key{RET}
-@item @key{RET}
+@orgcmd{@key{RET},org-table-next-row}
Re-align the table and move down to next row. Creates a new row if
necessary. At the beginning or end of a line, @key{RET} still does
NEWLINE, so it can be used to split a table.
@c
-@kindex M-a
-@item M-a
+@orgcmd{M-a,org-table-beginning-of-field}
Move to beginning of the current table field, or on to the previous field.
-@kindex M-e
-@item M-e
+@orgcmd{M-e,org-table-end-of-field}
Move to end of the current table field, or on to the next field.
@tsubheading{Column and row editing}
-@kindex M-@key{left}
-@kindex M-@key{right}
-@item M-@key{left}
-@itemx M-@key{right}
+@orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
Move the current column left/right.
@c
-@kindex M-S-@key{left}
-@item M-S-@key{left}
+@orgcmd{M-S-@key{left},org-table-delete-column}
Kill the current column.
@c
-@kindex M-S-@key{right}
-@item M-S-@key{right}
+@orgcmd{M-S-@key{right},org-table-insert-column}
Insert a new column to the left of the cursor position.
@c
-@kindex M-@key{up}
-@kindex M-@key{down}
-@item M-@key{up}
-@itemx M-@key{down}
+@orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
Move the current row up/down.
@c
-@kindex M-S-@key{up}
-@item M-S-@key{up}
+@orgcmd{M-S-@key{up},org-table-kill-row}
Kill the current row or horizontal line.
@c
-@kindex M-S-@key{down}
-@item M-S-@key{down}
+@orgcmd{M-S-@key{down},org-table-insert-row}
Insert a new row above the current row. With a prefix argument, the line is
created below the current one.
@c
-@kindex C-c -
-@item C-c -
+@orgcmd{C-c -,org-table-insert-hline}
Insert a horizontal line below current row. With a prefix argument, the line
is created above the current line.
@c
-@kindex C-c @key{RET}
-@item C-c @key{RET}
+@orgcmd{C-c @key{RET},org-table-hline-and-move}
Insert a horizontal line below current row, and move the cursor into the row
below that line.
@c
-@kindex C-c ^
-@item C-c ^
+@orgcmd{C-c ^,org-table-sort-lines}
Sort the table lines in the region. The position of point indicates the
column to be used for sorting, and the range of lines is the range
between the nearest horizontal separator lines, or the entire table. If
argument, alphabetic sorting will be case-sensitive.
@tsubheading{Regions}
-@kindex C-c C-x M-w
-@item C-c C-x M-w
+@orgcmd{C-c C-x M-w,org-table-copy-region}
Copy a rectangular region from a table to a special clipboard. Point and
mark determine edge fields of the rectangle. If there is no active region,
copy just the current field. The process ignores horizontal separator lines.
@c
-@kindex C-c C-x C-w
-@item C-c C-x C-w
+@orgcmd{C-c C-x C-w,org-table-cut-region}
Copy a rectangular region from a table to a special clipboard, and
blank all fields in the rectangle. So this is the ``cut'' operation.
@c
-@kindex C-c C-x C-y
-@item C-c C-x C-y
+@orgcmd{C-c C-x C-y,org-table-paste-rectangle}
Paste a rectangular region into a table.
The upper left corner ends up in the current field. All involved fields
will be overwritten. If the rectangle does not fit into the present table,
the table is enlarged as needed. The process ignores horizontal separator
lines.
@c
-@kindex M-@key{RET}
-@itemx M-@kbd{RET}
-Wrap several fields in a column like a paragraph. If there is an active
-region, and both point and mark are in the same column, the text in the
-column is wrapped to minimum width for the given number of lines. A numeric
-prefix argument may be used to change the number of desired lines. If there
-is no region, the current field is split at the cursor position and the text
-fragment to the right of the cursor is prepended to the field one line
-down. If there is no region, but you specify a prefix argument, the current
-field is made blank, and the content is appended to the field above.
+@orgcmd{M-@key{RET},org-table-wrap-region}
+Split the current field at the cursor position and move the rest to the line
+below. If there is an active region, and both point and mark are in the same
+column, the text in the column is wrapped to minimum width for the given
+number of lines. A numeric prefix argument may be used to change the number
+of desired lines. If there is no region, but you specify a prefix argument,
+the current field is made blank, and the content is appended to the field
+above.
@tsubheading{Calculations}
@cindex formula, in tables
@cindex region, active
@cindex active region
@cindex transient mark mode
-@kindex C-c +
-@item C-c +
+@orgcmd{C-c +,org-table-sum}
Sum the numbers in the current column, or in the rectangle defined by
the active region. The result is shown in the echo area and can
be inserted with @kbd{C-y}.
@c
-@kindex S-@key{RET}
-@item S-@key{RET}
+@orgcmd{S-@key{RET},org-table-copy-down}
@vindex org-table-copy-increment
When current field is empty, copy from first non-empty field above. When not
empty, copy current field down to next row and move cursor along with it.
-Depending on the variable @code{org-table-copy-increment}, integer field
+Depending on the option @code{org-table-copy-increment}, integer field
values will be incremented during copy. Integers that are too large will not
be incremented. Also, a @code{0} prefix argument temporarily disables the
increment. This key is also used by shift-selection and related modes
(@pxref{Conflicts}).
@tsubheading{Miscellaneous}
-@kindex C-c `
-@item C-c `
+@orgcmd{C-c `,org-table-edit-field}
Edit the current field in a separate window. This is useful for fields that
are not fully visible (@pxref{Column width and alignment}). When called with
a @kbd{C-u} prefix, just make the full field visible, so that it can be
-edited in place.
+edited in place. When called with two @kbd{C-u} prefixes, make the editor
+window follow the cursor through the table and always show the current
+field. The follow mode exits automatically when the cursor leaves the table,
+or when you repeat this command with @kbd{C-u C-u C-c `}.
@c
-@item M-x org-table-import
+@item M-x org-table-import RET
Import a file as a table. The table should be TAB or whitespace
separated. Use, for example, to import a spreadsheet table or data
from a database, because these programs generally can write
the buffer and then converting the region to a table. Any prefix
argument is passed on to the converter, which uses it to determine the
separator.
-@item C-c |
+@orgcmd{C-c |,org-table-create-or-convert-from-region}
Tables can also be imported by pasting tabular text into the Org
buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
@kbd{C-c |} command (see above under @i{Creation and conversion}).
@c
-@item M-x org-table-export
+@item M-x org-table-export RET
+@findex org-table-export
@vindex org-table-export-default-format
Export the table, by default as a TAB-separated file. Use for data
exchange with, for example, spreadsheet or database programs. The format
-used to export the file can be configured in the variable
+used to export the file can be configured in the option
@code{org-table-export-default-format}. You may also use properties
@code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
name and the format for table export in a subtree. Org supports quite
also the alignment of a column is determined automatically from the fraction
of number-like versus non-number fields in the column.
-Sometimes a single field or a few fields need to carry more text,
-leading to inconveniently wide columns. To limit@footnote{This feature
-does not work on XEmacs.} the width of a column, one field anywhere in
-the column may contain just the string @samp{<N>} where @samp{N} is an
-integer specifying the width of the column in characters. The next
-re-align will then set the width of this column to no more than this
-value.
+Sometimes a single field or a few fields need to carry more text, leading to
+inconveniently wide columns. Or maybe you want to make a table with several
+columns having a fixed width, regardless of content. To set@footnote{This
+feature does not work on XEmacs.} the width of a column, one field anywhere
+in the column may contain just the string @samp{<N>} where @samp{N} is an
+integer specifying the width of the column in characters. The next re-align
+will then set the width of this column to this value.
@example
@group
@noindent
Fields that are wider become clipped and end in the string @samp{=>}.
-Note that the full text is still in the buffer, it is only invisible.
+Note that the full text is still in the buffer but is hidden.
To see the full text, hold the mouse over the field---a tool-tip window
will show the full content. To edit such a field, use the command
@kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will
@end example
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 and use @samp{<r>} or
-@samp{<l>} in a similar fashion. You may also combine alignment and field
-width like this: @samp{<l10>}.
+to the right and of string-rich column to the left, you can use @samp{<r>},
+@samp{<c>}@footnote{Centering does not work inside Emacs, but it does have an
+effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may
+also combine alignment and field width like this: @samp{<r10>}.
+
+Lines which only contain these formatting cookies will be removed
+automatically when exporting the document.
@node Column groups, Orgtbl mode, Column width and alignment, Tables
@section Column groups
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:
@example
-| | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
-|---+----+-----+-----+-----+---------+------------|
-| / | <> | < | | > | < | > |
-| # | 1 | 1 | 1 | 1 | 1 | 1 |
-| # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
-| # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
-|---+----+-----+-----+-----+---------+------------|
-#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2)))
+| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
+|---+-----+-----+-----+---------+------------|
+| / | < | | > | < | > |
+| 1 | 1 | 1 | 1 | 1 | 1 |
+| 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
+| 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
+|---+-----+-----+-----+---------+------------|
+#+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
@end example
It is also sufficient to just insert the column group starters after
-every vertical line you'd like to have:
+every vertical line you would like to have:
@example
| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
If you like the intuitive way the Org table editor works, you
might also want to use it in other modes like Text mode or Mail mode.
The minor mode Orgtbl mode makes this possible. You can always toggle
-the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
-example in mail mode, use
+the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for
+example in Message mode, use
@lisp
-(add-hook 'mail-mode-hook 'turn-on-orgtbl)
+(add-hook 'message-mode-hook 'turn-on-orgtbl)
@end lisp
Furthermore, with some special setup, it is possible to maintain tables
in arbitrary syntax with Orgtbl mode. For example, it is possible to
-construct La@TeX{} tables with the underlying ease and power of
+construct @LaTeX{} tables with the underlying ease and power of
Orgtbl mode, including spreadsheet capabilities. For details, see
@ref{Tables in arbitrary syntax}.
The table editor makes use of the Emacs @file{calc} package to implement
spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
-derive fields from other fields. While fully featured, Org's
-implementation is not identical to other spreadsheets. For example,
-Org knows the concept of a @emph{column formula} that will be
-applied to all non-header fields in a column without having to copy the
-formula to each relevant field.
+derive fields from other fields. While fully featured, Org's implementation
+is not identical to other spreadsheets. For example, Org knows the concept
+of a @emph{column formula} that will be applied to all non-header fields in a
+column without having to copy the formula to each relevant field. There is
+also a formula debugger, and a formula editor with features for highlighting
+fields in the table corresponding to the references at the point in the
+formula, moving these references by arrow keys
@menu
* References:: How to refer to another field or range
* Formula syntax for Calc:: Using Calc to compute stuff
* Formula syntax for Lisp:: Writing formulas in Emacs Lisp
-* Field formulas:: Formulas valid for a single field
+* Durations and time values:: How to compute durations and time values
+* Field and range formulas:: Formula for specific (ranges of) fields
* Column formulas:: Formulas valid for an entire column
+* Lookup functions:: Lookup functions for searching tables
* Editing and debugging formulas:: Fixing formulas
* Updating the table:: Recomputing all dependent fields
-* Advanced features:: Field names, parameters and automatic recalc
+* Advanced features:: Field and column names, parameters and automatic recalc
@end menu
@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
Formulas can reference the value of another field in two ways. Like in
any other spreadsheet, you may reference fields with a letter/number
combination like @code{B3}, meaning the 2nd field in the 3rd row.
-@c Such references are always fixed to that field, they don't change
-@c when you copy and paste a formula to a different field. So
-@c Org's @code{B3} behaves like @code{$B$3} in other spreadsheets.
-
-@noindent
-Org also uses another, more general operator that looks like this:
+@vindex org-table-use-standard-references
+However, Org prefers@footnote{Org will understand references typed by the
+user as @samp{B4}, but it will not use this syntax when offering a formula
+for editing. You can customize this behavior using the option
+@code{org-table-use-standard-references}.} to use another, more general
+representation that looks like this:
@example
@@@var{row}$@var{column}
@end example
-@noindent
-Column references can be absolute like @samp{1}, @samp{2},...@samp{@var{N}},
-or relative to the current column like @samp{+1} or @samp{-2}.
-
-The row specification only counts data lines and ignores horizontal
-separator lines (hlines). You can use absolute row numbers
-@samp{1}...@samp{@var{N}}, and row numbers relative to the current row like
-@samp{+3} or @samp{-1}. Or specify the row relative to one of the
-hlines: @samp{I} refers to the first hline@footnote{Note that only
-hlines are counted that @emph{separate} table lines. If the table
-starts with a hline above the header, it does not count.}, @samp{II} to
-the second, etc@. @samp{-I} refers to the first such line above the
-current line, @samp{+I} to the first such line below the current line.
-You can also write @samp{III+2} which is the second data line after the
-third hline in the table.
-
-@samp{0} refers to the current row and column. Also, if you omit
-either the column or the row part of the reference, the current
-row/column is implied.
+Column specifications can be absolute like @code{$1},
+@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
+column from the right.
+
+The row specification only counts data lines and ignores horizontal separator
+lines (hlines). Like with columns, you can use absolute row numbers
+@code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
+current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are
+immutable references the first and last@footnote{For backward compatibility
+you can also use special names like @code{$LR5} and @code{$LR12} to refer in
+a stable way to the 5th and 12th field in the last row of the table.
+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
+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
+either the column or the row part of the reference, the current row/column is
+implied.
Org's references with @emph{unsigned} numbers are fixed references
in the sense that if you use the same reference in the formula for two
references because the same reference operator can reference different
fields depending on the field being calculated by the formula.
-As a special case, references like @samp{$LR5} and @samp{$LR12} can be used
-to refer in a stable way to the 5th and 12th field in the last row of the
-table.
-
Here are a few examples:
@example
-@@2$3 @r{2nd row, 3rd column}
-C2 @r{same as previous}
-$5 @r{column 5 in the current row}
-E& @r{same as previous}
+@@2$3 @r{2nd row, 3rd column (same as @code{C2})}
+$5 @r{column 5 in the current row (same as @code{E&})}
@@2 @r{current column, row 2}
@@-1$-3 @r{the field one row up, three columns to the left}
@@-I$2 @r{field just under hline above current row, column 2}
+@@>$5 @r{field in the last row, in column 5}
@end example
@subsubheading Range references
@samp{@@} in order to be interpreted correctly). Examples:
@example
-$1..$3 @r{First three fields in the current row.}
-$P..$Q @r{Range, using column names (see under Advanced)}
-@@2$1..@@4$3 @r{6 fields between these two fields.}
-A2..C4 @r{Same as above.}
-@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row}
+$1..$3 @r{first three fields in the current row}
+$P..$Q @r{range, using column names (see under Advanced)}
+$<<<..$>> @r{start in third column, continue to the one but last}
+@@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
+@@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left}
+@@I..II @r{between first and second hline, short for @code{@@I..@@II}}
@end example
@noindent Range references return a vector of values that can be fed
-into Calc vector functions. Empty fields in ranges are normally
-suppressed, so that the vector contains only the non-empty fields (but
-see the @samp{E} mode switch below). If there are no non-empty fields,
-@samp{[0]} is returned to avoid syntax errors in formulas.
+into Calc vector functions. Empty fields in ranges are normally suppressed,
+so that the vector contains only the non-empty fields. For other options
+with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
+for Calc}.
+
+@subsubheading Field coordinates in formulas
+@cindex field coordinates
+@cindex coordinates, of field
+@cindex row, of field coordinates
+@cindex column, of field coordinates
+
+For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to
+get the row or column number of the field where the formula result goes.
+The traditional Lisp formula equivalents are @code{org-table-current-dline}
+and @code{org-table-current-column}. Examples:
+
+@example
+if(@@# % 2, $#, string("")) @r{column number on odd lines only}
+$3 = remote(FOO, @@@@#$2) @r{copy column 2 from table FOO into}
+ @r{column 3 of the current table}
+@end example
+
+@noindent For the second example, table FOO must have at least as many rows
+as the current table. Note that this is inefficient@footnote{The computation time scales as
+O(N^2) because table FOO is parsed for each field to be copied.} for large
+number of rows.
@subsubheading Named references
@cindex named references
@vindex org-table-formula-constants
@samp{$name} is interpreted as the name of a column, parameter or
-constant. Constants are defined globally through the variable
+constant. Constants are defined globally through the option
@code{org-table-formula-constants}, and locally (for the file) through a
line like
@cindex references, to a different table
@cindex name, of column or field
@cindex constants, in calculations
-@cindex #+TBLNAME
+@cindex #+NAME, for table
You may also reference constants, fields and ranges from a different table,
either in the current file or even in a different file. The syntax is
@noindent
where NAME can be the name of a table in the current file as set by a
-@code{#+TBLNAME: NAME} line before the table. It can also be the ID of an
+@code{#+NAME: Name} line before the table. It can also be the ID of an
entry, even in a different file, and the reference then refers to the first
table in that entry. REF is an absolute field or range reference as
described above for example @code{@@3$3} or @code{$somename}, valid in the
@cindex formula syntax, Calc
@cindex syntax, of formulas
-A formula can be any algebraic expression understood by the Emacs
-@file{Calc} package. @b{Note that @file{calc} has the
-non-standard convention that @samp{/} has lower precedence than
-@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before
-evaluation by @code{calc-eval} (@pxref{Calling Calc from
-Your Programs,calc-eval,Calling Calc from Your Lisp Programs,Calc,GNU
-Emacs Calc Manual}),
-@c FIXME: The link to the Calc manual in HTML does not work.
-variable substitution takes place according to the rules described above.
+A formula can be any algebraic expression understood by the Emacs @file{Calc}
+package. Note that @file{calc} has the non-standard convention that @samp{/}
+has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
+@samp{a/(b*c)}. Before evaluation by @code{calc-eval} (@pxref{Calling Calc
+from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc,
+GNU Emacs Calc Manual}), variable substitution takes place according to the
+rules described above.
@cindex vectors, in table calculations
The range vectors can be directly fed into the Calc vector functions
like @samp{vmean} and @samp{vsum}.
execution. By default, Org uses the standard Calc modes (precision
12, angular units degrees, fraction and symbolic modes off). The display
format, however, has been changed to @code{(float 8)} to keep tables
-compact. The default settings can be configured using the variable
+compact. The default settings can be configured using the option
@code{org-calc-default-modes}.
-@example
-p20 @r{switch the internal precision to 20 digits}
-n3 s3 e2 f4 @r{normal, scientific, engineering, or fixed display format}
-D R @r{angle modes: degrees, radians}
-F S @r{fraction and symbolic modes}
-N @r{interpret all fields as numbers, use 0 for non-numbers}
-T @r{force text interpretation}
-E @r{keep empty fields in ranges}
-L @r{literal}
-@end example
+@noindent List of modes:
+
+@table @asis
+@item @code{p20}
+Set the internal Calc calculation precision to 20 digits.
+@item @code{n3}, @code{s3}, @code{e2}, @code{f4}
+Normal, scientific, engineering or fixed format of the result of Calc passed
+back to Org. Calc formatting is unlimited in precision as long as the Calc
+calculation precision is greater.
+@item @code{D}, @code{R}
+Degree and radian angle modes of Calc.
+@item @code{F}, @code{S}
+Fraction and symbolic modes of Calc.
+@item @code{T}, @code{t}
+Duration computations in Calc or Lisp, @pxref{Durations and time values}.
+@item @code{E}
+If and how to consider empty fields. Without @samp{E} empty fields in range
+references are suppressed so that the Calc vector or Lisp list contains only
+the non-empty fields. With @samp{E} the empty fields are kept. For empty
+fields in ranges or empty field references the value @samp{nan} (not a
+number) is used in Calc formulas and the empty string is used for Lisp
+formulas. Add @samp{N} to use 0 instead for both formula types. For the
+value of a field the mode @samp{N} has higher precedence than @samp{E}.
+@item @code{N}
+Interpret all fields as numbers, use 0 for non-numbers. See the next section
+to see how this is essential for computations with Lisp formulas. In Calc
+formulas it is used only occasionally because there number strings are
+already interpreted as numbers without @samp{N}.
+@item @code{L}
+Literal, for Lisp formulas only. See the next section.
+@end table
@noindent
-In addition, you may provide a @code{printf} format specifier to
-reformat the final result. A few examples:
+Unless you use large integer numbers or high-precision-calculation and
+-display for floating point numbers you may alternatively provide a
+@samp{printf} format specifier to reformat the Calc result after it has been
+passed back to Org instead of letting Calc already do the
+formatting@footnote{The @samp{printf} reformatting is limited in precision
+because the value passed to it is converted into an @samp{integer} or
+@samp{double}. The @samp{integer} is limited in size by truncating the
+signed value to 32 bits. The @samp{double} is limited in precision to 64
+bits overall which leaves approximately 16 significant decimal digits.}. A
+few examples:
@example
$1+$2 @r{Sum of first and second field}
$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
-vmean($2..$7) @r{Compute column range mean, using vector function}
-vmean($2..$7);EN @r{Same, but treat empty fields as 0}
-taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}
+taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
@end example
-Calc also contains a complete set of logical operations. For example
+Calc also contains a complete set of logical operations, (@pxref{Logical
+Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example
-@example
-if($1<20,teen,string("")) @r{``teen'' if age $1 less than 20, else empty}
-@end example
+@table @code
+@item if($1 < 20, teen, string(""))
+"teen" if age $1 is less than 20, else the Org table result field is set to
+empty with the empty string.
+@item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E
+Sum of the first two columns. When at least one of the input fields is empty
+the Org table result field is set to empty.
+@item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
+Mean value of a range unless there is any empty field. Every field in the
+range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
+in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from
+@samp{vmean} and the Org table result field is set to empty. Use this when
+the sample set is expected to never have missing values.
+@item if("$1..$7" == "[]", string(""), vmean($1..$7))
+Mean value of a range with empty fields skipped. Every field in the range
+that is empty is skipped. When all fields in the range are empty the mean
+value is not defined and the Org table result field is set to empty. Use
+this when the sample set can have a variable size.
+@item vmean($1..$7); EN
+To complete the example before: Mean value of a range with empty fields
+counting as samples with value 0. Use this only when incomplete sample sets
+should be padded with 0 to the full size.
+@end table
-@node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet
+You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
+and use them in formula syntax for Calc.
+
+@node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet
@subsection Emacs Lisp forms as formulas
@cindex Lisp forms, as table formulas
-It is also possible to write a formula in Emacs Lisp; this can be useful
-for string manipulation and control structures, if Calc's
-functionality is not enough. If a formula starts with a single-quote
-followed by an opening parenthesis, then it is evaluated as a Lisp form.
-The evaluation should return either a string or a number. Just as with
-@file{calc} formulas, you can specify modes and a printf format after a
-semicolon. With Emacs Lisp forms, you need to be conscious about the way
-field references are interpolated into the form. By default, a
-reference will be interpolated as a Lisp string (in double-quotes)
-containing the field. If you provide the @samp{N} mode switch, all
-referenced elements will be numbers (non-number fields will be zero) and
-interpolated as Lisp numbers, without quotes. If you provide the
-@samp{L} flag, all fields will be interpolated literally, without quotes.
-I.e., if you want a reference to be interpreted as a string by the Lisp
-form, enclose the reference operator itself in double-quotes, like
-@code{"$3"}. Ranges are inserted as space-separated fields, so you can
-embed them in list or vector syntax. A few examples, note how the
-@samp{N} mode is used when we do computations in Lisp.
-
-@example
-@r{Swap the first two characters of the content of column 1}
- '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
-@r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}}
- '(+ $1 $2);N
-@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}}
- '(apply '+ '($1..$4));N
-@end example
-
-@node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet
-@subsection Field formulas
-@cindex field formula
-@cindex formula, for individual table field
+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:
-To assign a formula to a particular field, type it directly into the
-field, preceded by @samp{:=}, for example @samp{:=$1+$2}. When you
-press @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in
-the field, the formula will be stored as the formula for this field,
-evaluated, and the current field replaced with the result.
+@table @code
+@item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
+Swap the first two characters of the content of column 1.
+@item '(+ $1 $2);N
+Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
+@item '(apply '+ '($1..$4));N
+Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
+@end table
-@cindex #+TBLFM
-Formulas are stored in a special line starting with @samp{#+TBLFM:}
-directly below the table. If you typed the equation in the 4th field of
-the 3rd data line in the table, the formula will look like
-@samp{@@3$4=$1+$2}. When inserting/deleting/swapping column and rows
-with the appropriate commands, @i{absolute references} (but not relative
-ones) in stored formulas are modified in order to still reference the
-same field. Of course this is not true if you edit the table structure
-with normal editing commands---then you must fix the equations yourself.
-The left-hand side of a formula may also be a named field (@pxref{Advanced
-features}), or a last-row reference like @samp{$LR3}.
+@node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet
+@subsection Durations and time values
+@cindex Duration, computing
+@cindex Time, computing
+@vindex org-table-duration-custom-format
-Instead of typing an equation into the field, you may also use the
-following command
+If you want to compute time values use the @code{T} flag, either in Calc
+formulas or Elisp formulas:
-@table @kbd
-@kindex C-u C-c =
-@item C-u C-c =
-Install a new formula for the current field. The command prompts for a
-formula with default taken from the @samp{#+TBLFM:} line, applies
+@example
+@group
+ | Task 1 | Task 2 | Total |
+ |---------+----------+----------|
+ | 2:12 | 1:47 | 03:59:00 |
+ | 3:02:20 | -2:07:00 | 0.92 |
+ #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;t
+@end group
+@end example
+
+Input duration values must be of the form @code{[HH:MM[:SS]}, where seconds
+are optional. With the @code{T} flag, computed durations will be displayed
+as @code{HH:MM:SS} (see the first formula above). With the @code{t} flag,
+computed durations will be displayed according to the value of the option
+@code{org-table-duration-custom-format}, which defaults to @code{'hours} and
+will display the result as a fraction of hours (see the second formula in the
+example above).
+
+Negative duration values can be manipulated as well, and integers will be
+considered as seconds in addition and subtraction.
+
+@node Field and range formulas, Column formulas, Durations and time values, The spreadsheet
+@subsection Field and range formulas
+@cindex field formula
+@cindex range formula
+@cindex formula, for individual table field
+@cindex formula, for range of fields
+
+To assign a formula to a particular field, type it directly into the field,
+preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
+@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
+the formula will be stored as the formula for this field, evaluated, and the
+current field will be replaced with the result.
+
+@cindex #+TBLFM
+Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
+below the table. If you type the equation in the 4th field of the 3rd data
+line in the table, the formula will look like @samp{@@3$4=$1+$2}. When
+inserting/deleting/swapping column and rows with the appropriate commands,
+@i{absolute references} (but not relative ones) in stored formulas are
+modified in order to still reference the same field. To avoid this from
+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 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
+command
+
+@table @kbd
+@orgcmd{C-u C-c =,org-table-eval-formula}
+Install a new formula for the current field. The command prompts for a
+formula with default taken from the @samp{#+TBLFM:} line, applies
it to the current field, and stores it.
@end table
-@node Column formulas, Editing and debugging formulas, Field formulas, The spreadsheet
+The left-hand side of a formula can also be a special expression in order to
+assign the formula to a number of different fields. There is no keyboard
+shortcut to enter such range formulas. To add them, use the formula editor
+(@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
+directly.
+
+@table @code
+@item $2=
+Column formula, valid for the entire column. This is so common that Org
+treats these formulas in a special way, see @ref{Column formulas}.
+@item @@3=
+Row formula, applies to all fields in the specified row. @code{@@>=} means
+the last row.
+@item @@1$2..@@4$3=
+Range formula, applies to all fields in the given rectangular range. This
+can also be used to assign a formula to some but not all fields in a row.
+@item $name=
+Named field, see @ref{Advanced features}.
+@end table
+
+@node Column formulas, Lookup functions, Field and range formulas, The spreadsheet
@subsection Column formulas
@cindex column formula
@cindex formula, for table column
-Often in a table, the same formula should be used for all fields in a
-particular column. Instead of having to copy the formula to all fields
-in that column, Org allows you to assign a single formula to an entire
-column. If the table contains horizontal separator hlines, everything
-before the first such line is considered part of the table @emph{header}
-and will not be modified by column formulas.
+When you assign a formula to a simple column reference like @code{$3=}, the
+same formula will be used in all fields of that column, with the following
+very convenient exceptions: (i) If the table contains horizontal separator
+hlines with rows above and below, everything before the first such hline is
+considered part of the table @emph{header} and will not be modified by column
+formulas. Therefore a header is mandatory when you use column formulas and
+want to add hlines to group rows, like for example to separate a total row at
+the bottom from the summand rows above. (ii) Fields that already get a value
+from a field/range formula will be left alone by column formulas. These
+conditions make column formulas very easy to use.
To assign a formula to a column, type it directly into any field in the
column, preceded by an equal sign, like @samp{=$1+$2}. When you press
and the current field replaced with the result. If the field contains only
@samp{=}, the previously stored formula for this column is used. For each
column, Org will only remember the most recently used formula. In the
-@samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The left-hand
-side of a column formula cannot currently be the name of column, it
-must be the numeric column reference.
+@samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
+left-hand side of a column formula can not be the name of column, it must be
+the numeric column reference or @code{$>}.
Instead of typing an equation into the field, you may also use the
following command:
@table @kbd
-@kindex C-c =
-@item C-c =
+@orgcmd{C-c =,org-table-eval-formula}
Install a new formula for the current column and replace current field with
the result of the formula. The command prompts for a formula, with default
taken from the @samp{#+TBLFM} line, applies it to the current field and
-stores it. With a numeric prefix argument(e.g. @kbd{C-5 C-c =}) the command
+stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
will apply it to that many consecutive fields in the current column.
@end table
-@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet
+@node Lookup functions, Editing and debugging formulas, Column formulas, The spreadsheet
+@subsection Lookup functions
+@cindex lookup functions in tables
+@cindex table lookup functions
+
+Org has three predefined Emacs Lisp functions for lookups in tables.
+@table @code
+@item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
+@findex org-lookup-first
+Searches for the first element @code{S} in list @code{S-LIST} for which
+@lisp
+(PREDICATE VAL S)
+@end lisp
+is @code{t}; returns the value from the corresponding position in list
+@code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the
+parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
+order as the corresponding parameters are in the call to
+@code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If
+@code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
+is returned.
+@item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
+@findex org-lookup-last
+Similar to @code{org-lookup-first} above, but searches for the @i{last}
+element for which @code{PREDICATE} is @code{t}.
+@item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
+@findex org-lookup-all
+Similar to @code{org-lookup-first}, but searches for @i{all} elements for
+which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
+values. This function can not be used by itself in a formula, because it
+returns a list of values. However, powerful lookups can be built when this
+function is combined with other Emacs Lisp functions.
+@end table
+
+If the ranges used in these functions contain empty fields, the @code{E} mode
+for the formula should usually be specified: otherwise empty fields will not be
+included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
+in an incorrect mapping from an element of @code{S-LIST} to the corresponding
+element of @code{R-LIST}.
+
+These three functions can be used to implement associative arrays, count
+matching cells, rank results, group data etc. For practical examples
+see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
+tutorial on Worg}.
+
+@node Editing and debugging formulas, Updating the table, Lookup functions, The spreadsheet
@subsection Editing and debugging formulas
@cindex formula editing
@cindex editing, of table formulas
@vindex org-table-use-standard-references
-You can edit individual formulas in the minibuffer or directly in the
-field. Org can also prepare a special buffer with all active
-formulas of a table. When offering a formula for editing, Org
-converts references to the standard format (like @code{B3} or @code{D&})
-if possible. If you prefer to only work with the internal format (like
-@code{@@3$2} or @code{$4}), configure the variable
-@code{org-table-use-standard-references}.
+You can edit individual formulas in the minibuffer or directly in the field.
+Org can also prepare a special buffer with all active formulas of a table.
+When offering a formula for editing, Org converts references to the standard
+format (like @code{B3} or @code{D&}) if possible. If you prefer to only work
+with the internal format (like @code{@@3$2} or @code{$4}), configure the
+option @code{org-table-use-standard-references}.
@table @kbd
-@kindex C-c =
-@kindex C-u C-c =
-@item C-c =
-@itemx C-u C-c =
+@orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
Edit the formula associated with the current column/field in the
-minibuffer. See @ref{Column formulas}, and @ref{Field formulas}.
-@kindex C-u C-u C-c =
-@item C-u C-u C-c =
+minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
+@orgcmd{C-u C-u C-c =,org-table-eval-formula}
Re-insert the active formula (either a
field formula, or a column formula) into the current field, so that you
can edit it directly in the field. The advantage over editing in the
minibuffer is that you can use the command @kbd{C-c ?}.
-@kindex C-c ?
-@item C-c ?
+@orgcmd{C-c ?,org-table-field-info}
While editing a formula in a table field, highlight the field(s)
referenced by the reference at the cursor position in the formula.
@kindex C-c @}
+@findex org-table-toggle-coordinate-overlays
@item C-c @}
-Toggle the display of row and column numbers for a table, using
-overlays. These are updated each time the table is aligned; you can
-force it with @kbd{C-c C-c}.
+Toggle the display of row and column numbers for a table, using overlays
+(@command{org-table-toggle-coordinate-overlays}). These are updated each
+time the table is aligned; you can force it with @kbd{C-c C-c}.
@kindex C-c @{
+@findex org-table-toggle-formula-debugger
@item C-c @{
-Toggle the formula debugger on and off. See below.
-@kindex C-c '
-@item C-c '
+Toggle the formula debugger on and off
+(@command{org-table-toggle-formula-debugger}). See below.
+@orgcmd{C-c ',org-table-edit-formulas}
Edit all formulas for the current table in a special buffer, where the
formulas will be displayed one per line. If the current field has an
active formula, the cursor in the formula editor will mark it.
While inside the special buffer, Org will automatically highlight
any field or range reference at the cursor position. You may edit,
remove and add formulas, and use the following commands:
+
@table @kbd
-@kindex C-c C-c
-@kindex C-x C-s
-@item C-c C-c
-@itemx C-x C-s
+@orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
Exit the formula editor and store the modified formulas. With @kbd{C-u}
prefix, also apply the new formulas to the entire table.
-@kindex C-c C-q
-@item C-c C-q
+@orgcmd{C-c C-q,org-table-fedit-abort}
Exit the formula editor without installing changes.
-@kindex C-c C-r
-@item C-c C-r
+@orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
Toggle all references in the formula editor between standard (like
@code{B3}) and internal (like @code{@@3$2}).
-@kindex @key{TAB}
-@item @key{TAB}
+@orgcmd{@key{TAB},org-table-fedit-lisp-indent}
Pretty-print or indent Lisp formula at point. When in a line containing
a Lisp formula, format the formula according to Emacs Lisp rules.
Another @key{TAB} collapses the formula back again. In the open
formula, @key{TAB} re-indents just like in Emacs Lisp mode.
-@kindex M-@key{TAB}
-@item M-@key{TAB}
+@orgcmd{M-@key{TAB},lisp-complete-symbol}
Complete Lisp symbols, just like in Emacs Lisp mode.
@kindex S-@key{up}
@kindex S-@key{down}
@kindex S-@key{left}
@kindex S-@key{right}
+@findex org-table-fedit-ref-up
+@findex org-table-fedit-ref-down
+@findex org-table-fedit-ref-left
+@findex org-table-fedit-ref-right
@item S-@key{up}/@key{down}/@key{left}/@key{right}
Shift the reference at point. For example, if the reference is
@code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
This also works for relative references and for hline references.
-@kindex M-S-@key{up}
-@kindex M-S-@key{down}
-@item M-S-@key{up}/@key{down}
+@orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
Move the test line for column formulas in the Org buffer up and
down.
-@kindex M-@key{up}
-@kindex M-@key{down}
-@item M-@key{up}/@key{down}
+@orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
Scroll the window displaying the table.
@kindex C-c @}
+@findex org-table-toggle-coordinate-overlays
@item C-c @}
Turn the coordinate grid in the table on and off.
@end table
equations with @kbd{C-c C-c} in that line or with the normal
recalculation commands in the table.
+@anchor{Using multiple #+TBLFM lines}
+@subsubheading Using multiple #+TBLFM lines
+@cindex #+TBLFM line, multiple
+@cindex #+TBLFM
+@cindex #+TBLFM, switching
+@kindex C-c C-c
+
+You may apply the formula temporarily. This is useful when you
+switch the formula. Place multiple @samp{#+TBLFM} lines right
+after the table, and then press @kbd{C-c C-c} on the formula to
+apply. Here is an example:
+
+@example
+| x | y |
+|---+---|
+| 1 | |
+| 2 | |
+#+TBLFM: $2=$1*1
+#+TBLFM: $2=$1*2
+@end example
+
+@noindent
+Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
+
+@example
+| x | y |
+|---+---|
+| 1 | 2 |
+| 2 | 4 |
+#+TBLFM: $2=$1*1
+#+TBLFM: $2=$1*2
+@end example
+
+@noindent
+Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
+will get the following result of applying only the first @samp{#+TBLFM} line.
+
+@example
+| x | y |
+|---+---|
+| 1 | 1 |
+| 2 | 2 |
+#+TBLFM: $2=$1*1
+#+TBLFM: $2=$1*2
+@end example
+
@subsubheading Debugging formulas
@cindex formula debugging
@cindex debugging, of table formulas
following commands:
@table @kbd
-@kindex C-c *
-@item C-c *
+@orgcmd{C-c *,org-table-recalculate}
Recalculate the current row by first applying the stored column formulas
-from left to right, and all field formulas in the current row.
+from left to right, and all field/range formulas in the current row.
@c
@kindex C-u C-c *
@item C-u C-c *
Recompute the entire table, line by line. Any lines before the first
hline are left alone, assuming that these are part of the table header.
@c
-@kindex C-u C-u C-c *
-@kindex C-u C-u C-c C-c
-@item C-u C-u C-c *
-@itemx C-u C-u C-c C-c
+@orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
Iterate the table by recomputing it until no further changes occur.
This may be necessary if some computed fields use the value of other
fields that are computed @i{later} in the calculation sequence.
+@item M-x org-table-recalculate-buffer-tables RET
+@findex org-table-recalculate-buffer-tables
+Recompute all tables in the current buffer.
+@item M-x org-table-iterate-buffer-tables RET
+@findex org-table-iterate-buffer-tables
+Iterate all tables in the current buffer, in order to converge table-to-table
+dependencies.
@end table
@node Advanced features, , Updating the table, The spreadsheet
@subsection Advanced features
-If you want the recalculation of fields to happen automatically, or if
-you want to be able to assign @i{names} to fields and columns, you need
-to reserve the first column of the table for special marking characters.
+If you want the recalculation of fields to happen automatically, or if you
+want to be able to assign @i{names}@footnote{Such names must start by an
+alphabetic character and use only alphanumeric/underscore characters.} to
+fields and columns, you need to reserve the first column of the table for
+special marking characters.
+
@table @kbd
-@kindex C-#
-@item C-#
+@orgcmd{C-#,org-table-rotate-recalc-marks}
Rotate the calculation mark in first column through the states @samp{ },
@samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
change all marks in the region.
| # | Peter | 10 | 8 | 23 | 41 | 8.2 |
| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
|---+---------+--------+--------+--------+-------+------|
-| | Average | | | | 29.7 | |
+| | Average | | | | 25.0 | |
| ^ | | | | | at | |
| $ | max=50 | | | | | |
|---+---------+--------+--------+--------+-------+------|
@cindex marking characters, tables
The marking characters have the following meaning:
+
@table @samp
@item !
The fields in this line define names for the columns, so that you may
Selects this line for global recalculation with @kbd{C-u C-c *}, but
not for automatic recalculation. Use this when automatic
recalculation slows down editing too much.
-@item
+@item @w{ }
Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
All lines that should be recalculated should be marked with @samp{#}
or @samp{*}.
@node Org-Plot, , The spreadsheet, Tables
@section Org-Plot
@cindex graph, in tables
-@cindex plot tables using gnuplot
+@cindex plot tables using Gnuplot
@cindex #+PLOT
Org-Plot can produce 2D and 3D graphs of information stored in org tables
using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
-@uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To see
-this in action, ensure that you have both Gnuplot and Gnuplot mode installed
-on your system, then call @code{org-plot/gnuplot} on the following table.
+@uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
+that you have both Gnuplot and Gnuplot mode installed on your system, then
+call @code{org-plot/gnuplot} on the following table.
@example
@group
be exercised through the @code{#+PLOT:} lines preceding a table. See below
for a complete list of Org-plot options. For more information and examples
see the Org-plot tutorial at
-@uref{http://orgmode.org/worg/org-tutorials/org-plot.php}.
+@uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
@subsubheading Plot Options
@item with
Specify a @code{with} option to be inserted for every col being plotted
-(e.g. @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
+(e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
Defaults to @code{lines}.
@item file
If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
@item labels
-List of labels to be used for the deps (defaults to the column headers if
-they exist).
+List of labels to be used for the @code{deps} (defaults to the column headers
+if they exist).
@item line
Specify an entire line to be inserted in the Gnuplot script.
flat mapping rather than a @code{3d} slope.
@item timefmt
-Specify format of Org-mode timestamps as they will be parsed by Gnuplot.
+Specify format of Org mode timestamps as they will be parsed by Gnuplot.
Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
@item script
If the link does not look like a URL, it is considered to be internal in the
current file. The most important case is a link like
@samp{[[#my-custom-id]]} which will link to the entry with the
-@code{CUSTOM_ID} property @samp{my-custom-id}. Such custom IDs are very good
-for HTML export (@pxref{HTML export}) where they produce pretty section
-links. You are responsible yourself to make sure these custom IDs are unique
-in a file.
+@code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
+to make sure these custom IDs are unique in a file.
Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
lead to a text search in the current file.
The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
or with a mouse click (@pxref{Handling links}). Links to custom IDs will
point to the corresponding headline. The preferred match for a text link is
-a @i{dedicated target}: the same string in double angular brackets. Targets
-may be located anywhere; sometimes it is convenient to put them into a
-comment line. For example
+a @i{dedicated target}: the same string in double angular brackets, like
+@samp{<<My Target>>}.
+
+@cindex #+NAME
+If no dedicated target exists, the link will then try to match the exact name
+of an element within the buffer. Naming is done with the @code{#+NAME}
+keyword, which has to be put the line before the element it refers to, as in
+the following example
@example
-# <<My Target>>
+#+NAME: My Target
+| a | table |
+|----+------------|
+| of | four cells |
@end example
-@noindent In HTML export (@pxref{HTML export}), such targets will become
-named anchors for direct access through @samp{http} links@footnote{Note that
-text before the first headline is usually not exported, so the first such
-target should be after the first headline, or in the line directly before the
-first headline.}.
+If none of the above succeeds, Org will search for a headline that is exactly
+the link text but may also include a TODO keyword and tags@footnote{To insert
+a link targeting a headline, in-buffer completion can be used. Just type
+a star followed by a few optional letters into the buffer and press
+@kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
+completions.}.
-If no dedicated target exists, Org will search for the words in the link. In
-the above example the search would be for @samp{my target}. Links starting
-with a star like @samp{*My Target} restrict the search to
-headlines@footnote{To insert a link targeting a headline, in-buffer
-completion can be used. Just type a star followed by a few optional letters
-into the buffer and press @kbd{M-@key{TAB}}. All headlines in the current
-buffer will be offered as completions. @xref{Handling links}, for more
-commands creating links.}. When searching, Org mode will first try an
-exact match, but then move on to more and more lenient searches. For
-example, the link @samp{[[*My Targets]]} will find any of the following:
+During export, internal links will be used to mark objects and assign them
+a number. Marked objects will then be referenced by links pointing to them.
+In particular, links without a description will appear as the number assigned
+to the marked object@footnote{When targeting a @code{#+NAME} keyword,
+@code{#+CAPTION} keyword is mandatory in order to get proper numbering
+(@pxref{Images and tables}).}. In the following excerpt from an Org buffer
@example
-** My targets
-** TODO my targets are bright
-** my 20 targets are
+- one item
+- <<target>>another item
+Here we refer to item [[target]].
@end example
+@noindent
+The last sentence will appear as @samp{Here we refer to item 2} when
+exported.
+
+In non-Org files, the search will look for the words in the link text. In
+the above example the search would be for @samp{my target}.
Following a link pushes a mark onto Org's own mark ring. You can
return to the previous position with @kbd{C-c &}. Using this command
@section External links
@cindex links, external
@cindex external links
-@cindex links, external
@cindex Gnus links
@cindex BBDB links
@cindex IRC links
@cindex URL links
@cindex file links
-@cindex VM links
@cindex RMAIL links
-@cindex WANDERLUST links
@cindex MH-E links
@cindex USENET links
@cindex SHELL links
@cindex Info links
@cindex Elisp links
-Org supports links to files, websites, Usenet and email messages,
-BBDB database entries and links to both IRC conversations and their
-logs. External links are URL-like locators. They start with a short
-identifying string followed by a colon. There can be no space after
-the colon. The following list shows examples for each link type.
+Org supports links to files, websites, Usenet and email messages, BBDB
+database entries and links to both IRC conversations and their logs.
+External links are URL-like locators. They start with a short identifying
+string followed by a colon. There can be no space after the colon. The
+following list shows examples for each link type.
@example
http://www.astro.uva.nl/~dominik @r{on the web}
+doi:10.1000/182 @r{DOI for an electronic resource}
file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
/home/dominik/images/jupiter.jpg @r{same as above}
file:papers/last.pdf @r{file, relative path}
./papers/last.pdf @r{same as above}
-file:sometextfile::NNN @r{file with line number to jump to}
+file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine}
+/myself@@some.where:papers/last.pdf @r{same as above}
+file:sometextfile::NNN @r{file, jump to line number}
file:projects.org @r{another Org file}
-file:projects.org::some words @r{text search in Org file}
+file:projects.org::some words @r{text search in Org file}@footnote{
+The actual behavior of the search will depend on the value of
+the option @code{org-link-search-must-match-exact-headline}. If its value
+is @code{nil}, then a fuzzy text search will be done. If it is t, then only the
+exact headline will be matched. If the value is @code{'query-to-create},
+then an exact headline will be searched; if it is not found, then the user
+will be queried to create it.}
file:projects.org::*task title @r{heading search in Org file}
+file+sys:/path/to/file @r{open via OS, like double-click}
+file+emacs:/path/to/file @r{force opening by Emacs}
+docview:papers/last.pdf::NNN @r{open in doc-view mode at page}
id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
news:comp.emacs @r{Usenet link}
mailto:adent@@galaxy.net @r{Mail link}
-vm:folder @r{VM folder link}
-vm:folder#id @r{VM message link}
-vm://myself@@some.where.org/folder#id @r{VM on remote machine}
-wl:folder @r{WANDERLUST folder link}
-wl:folder#id @r{WANDERLUST message link}
mhe:folder @r{MH-E folder link}
mhe:folder#id @r{MH-E message link}
rmail:folder @r{RMAIL folder link}
gnus:group#id @r{Gnus article link}
bbdb:R.*Stallman @r{BBDB link (with regexp)}
irc:/irc.com/#emacs/bob @r{IRC link}
+info:org#External links @r{Info node link}
shell:ls *.org @r{A shell command}
elisp:org-agenda @r{Interactive Elisp command}
elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
@end example
-A link should be enclosed in double brackets and may contain a
-descriptive text to be displayed instead of the URL (@pxref{Link
-format}), for example:
+@cindex VM links
+@cindex WANDERLUST links
+On top of these built-in link types, some are available through the
+@code{contrib/} directory (@pxref{Installation}). For example, these links
+to VM or Wanderlust messages are available when you load the corresponding
+libraries from the @code{contrib/} directory:
+
+@example
+vm:folder @r{VM folder link}
+vm:folder#id @r{VM message link}
+vm://myself@@some.where.org/folder#id @r{VM on remote machine}
+vm-imap:account:folder @r{VM IMAP folder link}
+vm-imap:account:folder#id @r{VM IMAP message link}
+wl:folder @r{WANDERLUST folder link}
+wl:folder#id @r{WANDERLUST message link}
+@end example
+
+For customizing Org to add new link types @ref{Adding hyperlink types}.
+
+A link should be enclosed in double brackets and may contain a descriptive
+text to be displayed instead of the URL (@pxref{Link format}), for example:
@example
[[http://www.gnu.org/software/emacs/][GNU Emacs]]
insert it into an Org file, and to follow the link.
@table @kbd
-@kindex C-c l
+@orgcmd{C-c l,org-store-link}
@cindex storing links
-@item C-c l
Store a link to the current location. This is a @emph{global} command (you
must create the key binding yourself) which can be used in any buffer to
create a link. The link will be stored for later insertion into an Org
buffer (see below). What kind of link will be created depends on the current
buffer:
-@b{Org-mode buffers}@*
+@b{Org mode buffers}@*
For Org files, if there is a @samp{<<target>>} at the cursor, the link points
to the target. Otherwise it points to the current headline, which will also
-be the description.
+be the description@footnote{If the headline contains a timestamp, it will be
+removed from the link and result in a wrong link---you should avoid putting
+timestamp in the headline.}.
-@vindex org-link-to-org-use-id
+@vindex org-id-link-to-org-use-id
@cindex property, CUSTOM_ID
@cindex property, ID
If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
will be stored. In addition or alternatively (depending on the value of
-@code{org-link-to-org-use-id}), a globally unique @code{ID} property will be
-created and/or used to construct a link. So using this command in Org
-buffers will potentially create two links: a human-readable from the custom
-ID, and one that is globally unique and works even if the entry is moved from
-file to file. Later, when inserting the link, you need to decide which one
-to use.
+@code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
+be created and/or used to construct a link@footnote{The library
+@file{org-id.el} must first be loaded, either through @code{org-customize} by
+enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
+'org-id)} in your @file{.emacs}.}. So using this command in Org buffers will
+potentially create two links: a human-readable from the custom ID, and one
+that is globally unique and works even if the entry is moved from file to
+file. Later, when inserting the link, you need to decide which one to use.
@b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
Pretty much all Emacs mail clients are supported. The link will point to the
@b{Chat: IRC}@*
@vindex org-irc-link-to-logs
-For IRC links, if you set the variable @code{org-irc-link-to-logs} to
-@code{t}, a @samp{file:/} style link to the relevant point in the logs for
-the current conversation is created. Otherwise an @samp{irc:/} style link to
-the user/channel/server under the point will be stored.
+For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
+a @samp{file:/} style link to the relevant point in the logs for the current
+conversation is created. Otherwise an @samp{irc:/} style link to the
+user/channel/server under the point will be stored.
@b{Other files}@*
For any other files, the link will point to the file, with a search string
entry referenced by the current line.
@c
-@kindex C-c C-l
+@orgcmd{C-c C-l,org-insert-link}
@cindex link completion
@cindex completion, of links
@cindex inserting links
-@item C-c C-l
@vindex org-keep-stored-link-after-insertion
Insert a link@footnote{ Note that you don't have to use this command to
insert a link. Links in Org are plain text, and you can type or paste them
example, if you type @kbd{file @key{RET}}, file name completion (alternative
access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb
@key{RET}} you can complete contact names.
-@kindex C-u C-c C-l
+@orgkey C-u C-c C-l
@cindex file name completion
@cindex completion, of file names
-@item C-u C-c C-l
When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
a file will be inserted and you may use file name completion to select
the name of the file. The path to the file is inserted relative to the
is used, if possible with @samp{~/} for your home directory. You can
force an absolute path with two @kbd{C-u} prefixes.
@c
-@item C-c C-l @r{(with cursor on existing link)}
+@item C-c C-l @ @r{(with cursor on existing link)}
When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
link and description parts of the link.
@c
@cindex following links
-@kindex C-c C-o
-@kindex RET
-@item C-c C-o @r{or} @key{RET}
+@orgcmd{C-c C-o,org-open-at-point}
@vindex org-file-apps
+@vindex org-link-frame-setup
Open link at point. This will launch a web browser for URLs (using
@command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
the corresponding links, and execute the command in a shell link. When the
visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
opening in Emacs, use a @kbd{C-u C-u} prefix.@*
If the cursor is on a headline, but not on a link, offer all links in the
-headline and entry text.
+headline and entry text. If you want to setup the frame configuration for
+following links, customize @code{org-link-frame-setup}.
+
+@orgkey @key{RET}
+@vindex org-return-follows-link
+When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
+the link at point.
@c
@kindex mouse-2
@kindex mouse-1
@item mouse-2
@itemx mouse-1
On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
-would. Under Emacs 22, @kbd{mouse-1} will also follow a link.
+would. Under Emacs 22 and later, @kbd{mouse-1} will also follow a link.
@c
@kindex mouse-3
@item mouse-3
@vindex org-display-internal-link-with-indirect-buffer
Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
internal links to be displayed in another window@footnote{See the
-variable @code{org-display-internal-link-with-indirect-buffer}}.
+option @code{org-display-internal-link-with-indirect-buffer}}.
@c
+@orgcmd{C-c C-x C-v,org-toggle-inline-images}
+@cindex inlining images
+@cindex images, inlining
+@vindex org-startup-with-inline-images
+@cindex @code{inlineimages}, STARTUP keyword
+@cindex @code{noinlineimages}, STARTUP keyword
+Toggle the inline display of linked images. Normally this will only inline
+images that have no description part in the link, i.e., images that will also
+be inlined during export. When called with a prefix argument, also display
+images that do have a link description. You can ask for inline images to be
+displayed at startup by configuring the variable
+@code{org-startup-with-inline-images}@footnote{with corresponding
+@code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
+@orgcmd{C-c %,org-mark-ring-push}
@cindex mark ring
-@kindex C-c %
-@item C-c %
Push the current position onto the mark ring, to be able to return
-easily. Commands following an internal link do this automatically.
+easily. Commands following an internal link do this automatically.
@c
+@orgcmd{C-c &,org-mark-ring-goto}
@cindex links, returning to
-@kindex C-c &
-@item C-c &
Jump back to a recorded position. A position is recorded by the
commands following internal links, and by @kbd{C-c %}. Using this
command several times in direct succession moves through a ring of
previously recorded positions.
@c
-@kindex C-c C-x C-n
-@kindex C-c C-x C-p
+@orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
@cindex links, finding next/previous
-@item C-c C-x C-n
-@itemx C-c C-x C-p
Move forward/backward to the next link in the buffer. At the limit of
the buffer, the search fails once, and then wraps around. The key
-bindings for this are really too long, you might want to bind this also
+bindings for this are really too long; you might want to bind this also
to @kbd{C-n} and @kbd{C-p}
@lisp
(add-hook 'org-load-hook
(lambda ()
- (define-key 'org-mode-map "\C-n" 'org-next-link)
- (define-key 'org-mode-map "\C-p" 'org-previous-link)))
+ (define-key org-mode-map "\C-n" 'org-next-link)
+ (define-key org-mode-map "\C-p" 'org-previous-link)))
@end lisp
@end table
@noindent
@vindex org-link-abbrev-alist
-where the tag is optional. The @i{linkword} must be a word; letter, numbers,
-@samp{-}, and @samp{_} are allowed here. Abbreviations are resolved
+where the tag is optional.
+The @i{linkword} must be a word, starting with a letter, followed by
+letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved
according to the information in the variable @code{org-link-abbrev-alist}
that relates the linkwords to replacement text. Here is an example:
-@lisp
+@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=")
- ("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 lisp
+@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
-@code{[[google:OrgMode]]} and find out what the Org author is
-doing besides Emacs hacking with @code{[[ads:Dominik,C]]}.
+@code{[[google:OrgMode]]}, show the map location of the Free Software
+Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
+@code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
+what the Org author is doing besides Emacs hacking with
+@code{[[ads:Dominik,C]]}.
If you need special abbreviations just for a single Org buffer, you
can define them in the file 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.
File links can contain additional information to make Emacs jump to a
particular location in the file when following a link. This can be a
line number or a search option after a double@footnote{For backward
-compatibility, line numbers can also follow a single colon.} colon. For
+compatibility, line numbers can also follow a single colon.} colon. For
example, when the command @kbd{C-c l} creates a link (@pxref{Handling
links}) to a file, it encodes the words in the current line as a search
string that can be used to find this line back later when following the
[[file:~/code/main.c::255]]
[[file:~/xx.org::My Target]]
[[file:~/xx.org::*My Target]]
+[[file:~/xx.org::#my-custom-id]]
[[file:~/xx.org::/regexp/]]
@end example
the linked file.
@item *My Target
In an Org file, restrict search to headlines.
+@item #my-custom-id
+Link to a heading with a @code{CUSTOM_ID} property
@item /regexp/
Do a regular expression search for @code{regexp}. This uses the Emacs
command @code{occur} to list all matches in a separate window. If the
an implementation example. See the file @file{org-bibtex.el}.
@node TODO Items, Tags, Hyperlinks, Top
-@chapter TODO Items
+@chapter TODO items
@cindex TODO items
Org mode does not maintain TODO lists as separate documents@footnote{Of
The most important commands to work with TODO entries are:
@table @kbd
-@kindex C-c C-t
+@orgcmd{C-c C-t,org-todo}
@cindex cycling, of TODO states
-@item C-c C-t
+@vindex org-use-fast-todo-selection
+
Rotate the TODO state of the current item among
@example
'--------------------------------'
@end example
-The same rotation can also be done ``remotely'' from the timeline and
-agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
+If TODO keywords have fast access keys (see @ref{Fast access to TODO
+states}), you will be prompted for a TODO keyword through the fast selection
+interface; this is the default behavior when
+@code{org-use-fast-todo-selection} is non-@code{nil}.
-@kindex C-u C-c C-t
-@item C-u C-c C-t
-Select a specific keyword using completion or (if it has been set up)
-the fast selection interface. For the latter, you need to assign keys
-to TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, for
-more information.
+The same rotation can also be done ``remotely'' from the timeline and agenda
+buffers with the @kbd{t} command key (@pxref{Agenda commands}).
+
+@orgkey{C-u C-c C-t}
+When TODO keywords have no selection keys, select a specific keyword using
+completion; otherwise force cycling through TODO states with no prompt. When
+@code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
+selection interface.
@kindex S-@key{right}
@kindex S-@key{left}
+@item S-@key{right} @ @r{/} @ S-@key{left}
@vindex org-treat-S-cursor-todo-selection-as-state-change
-@item S-@key{right}
-@itemx S-@key{left}
Select the following/preceding TODO state, similar to cycling. Useful
mostly if more than two TODO states are possible (@pxref{TODO
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}.
-@kindex C-c C-v
-@kindex C-c / t
+@orgcmd{C-c / t,org-show-todo-tree}
@cindex sparse tree, for TODO
-@item C-c C-v
-@itemx C-c / t
@vindex org-todo-keywords
View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
-entire buffer, but shows all TODO items and the headings hierarchy above
-them. With a prefix argument, 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 numeric prefix argument N, show the tree for the Nth keyword in the
-variable @code{org-todo-keywords}. With two prefix arguments, find all TODO
-and DONE entries.
-@kindex C-c a t
-@item C-c a t
-Show the global TODO list. Collects the TODO items from all agenda
-files (@pxref{Agenda Views}) into a single buffer. The new buffer will
-be in @code{agenda-mode}, which provides commands to examine and
-manipulate the TODO entries from the new buffer (@pxref{Agenda
-commands}). @xref{Global TODO list}, for more information.
-@kindex S-M-@key{RET}
-@item S-M-@key{RET}
+entire buffer, but shows all TODO items (with not-DONE state) and the
+headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
+/ T}), search for a specific TODO@. You will be prompted for the keyword,
+and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
+entries that match any one of these keywords. With a numeric prefix argument
+N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
+With two prefix arguments, find all TODO states, both un-done and done.
+@orgcmd{C-c a t,org-todo-list}
+Show the global TODO list. Collects the TODO items (with not-DONE states)
+from all agenda files (@pxref{Agenda Views}) into a single buffer. The new
+buffer will be in @code{agenda-mode}, which provides commands to examine and
+manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
+@xref{Global TODO list}, for more information.
+@orgcmd{S-M-@key{RET},org-insert-todo-heading}
Insert a new TODO entry below the current one.
@end table
@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 C-v}. For example, to see all things
-Lucy has to do, you would use @kbd{C-3 C-c C-v}. To collect Lucy's items
+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
from all agenda files into a single buffer, you would use the numeric prefix
-argument as well when creating the global TODO list: @kbd{C-3 C-c t}.
+argument as well when creating the global TODO list: @kbd{C-3 C-c a t}.
@node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions
@subsection Multiple keyword sets in one file
@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
@end lisp
@vindex org-fast-tag-selection-include-todo
-If you then press @code{C-c C-t} followed by the selection key, the entry
-will be switched to this state. @key{SPC} can be used to remove any TODO
-keyword from an entry.@footnote{Check also the variable
+If you then press @kbd{C-c C-t} followed by the selection key, the entry
+will be switched to this state. @kbd{SPC} can be used to remove any TODO
+keyword from an entry.@footnote{Check also the option
@code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
state through the tags interface (@pxref{Setting tags}), in case you like to
mingle the two concepts. Note that this means you need to come up with
for keywords indicating that an item still has to be acted upon, and
@code{org-done} for keywords indicating that an item is finished. If
you are using more than 2 different states, you might want to use
-special faces for some of them. This can be done using the variable
+special faces for some of them. This can be done using the option
@code{org-todo-keyword-faces}. For example:
@lisp
@group
(setq org-todo-keyword-faces
- '(("TODO" . org-warning)
- ("DEFERRED" . shadow)
- ("CANCELED" . (:foreground "blue" :weight bold))))
+ '(("TODO" . org-warning) ("STARTED" . "yellow")
+ ("CANCELED" . (:foreground "blue" :weight bold))))
@end group
@end lisp
-While using a list with face properties as shown for CANCELED
-@emph{should} work, this does not aways seem to be the case. If
-necessary, define a special face and use that.
+While using a list with face properties as shown for CANCELED @emph{should}
+work, this does not always seem to be the case. If necessary, define a
+special face and use that. A string is interpreted as a color. The option
+@code{org-faces-easy-properties} determines if that color is interpreted as a
+foreground or a background color.
@node TODO dependencies, , Faces for TODO keywords, TODO extensions
@subsection TODO dependencies
@cindex property, ORDERED
The structure of Org files (hierarchy and lists) makes it easy to define TODO
dependencies. Usually, a parent TODO task should not be marked DONE until
-all subtasks (defined as children tasks) are marked as DONE. And sometimes
+all subtasks (defined as children tasks) are marked as DONE@. And sometimes
there is a logical sequence to a number of (sub)tasks, so that one task
cannot be acted upon before all siblings above it are done. If you customize
-the variable @code{org-enforce-todo-dependencies}, Org will block entries
-from changing state to DONE while they have children that are not DONE.
+the option @code{org-enforce-todo-dependencies}, Org will block entries
+from changing state to DONE while they have children that are not DONE@.
Furthermore, if an entry has a property @code{ORDERED}, each of its children
-will be blocked until all earlier siblings are marked DONE. Here is an
+will be blocked until all earlier siblings are marked DONE@. Here is an
example:
@example
* Parent
:PROPERTIES:
- :ORDERED: t
+ :ORDERED: t
:END:
** TODO a
** TODO b, needs to wait for (a)
@end example
@table @kbd
-@kindex C-c C-x o
-@item C-c C-x o
+@orgcmd{C-c C-x o,org-toggle-ordered-property}
@vindex org-track-ordered-property-with-tag
@cindex property, ORDERED
Toggle the @code{ORDERED} property of the current entry. A property is used
for this behavior because this should be local to the current entry, not
inherited like a tag. However, if you would like to @i{track} the value of
-this property with a tag for better visibility, customize the variable
+this property with a tag for better visibility, customize the option
@code{org-track-ordered-property-with-tag}.
-@kindex C-u C-u C-u C-c C-t
-@item C-u C-u C-u C-c C-t
+@orgkey{C-u C-u C-u C-c C-t}
Change TODO state, circumventing any state blocking.
@end table
@vindex org-agenda-dim-blocked-tasks
-If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries
+If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
that cannot be closed because of such dependencies will be shown in a dimmed
font or even made invisible in agenda views (@pxref{Agenda Views}).
@cindex checkboxes and TODO dependencies
@vindex org-enforce-todo-dependencies
You can also block changes of TODO states by looking at checkboxes
-(@pxref{Checkboxes}). If you set the variable
+(@pxref{Checkboxes}). If you set the option
@code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
checkboxes will be blocked from switching to DONE.
Org mode can automatically record a timestamp and possibly a note when
you mark a TODO item as DONE, or even each time you change the state of
-a TODO item. This system is highly configurable, settings can be on a
+a TODO item. This system is highly configurable; settings can be on a
per-keyword basis and can be localized to a file or even a subtree. For
information on how to clock working time for a task, see @ref{Clocking
work time}.
The most basic logging is to keep track of @emph{when} a certain TODO
item was finished. This is achieved with@footnote{The corresponding
-in-buffer setting is: @code{#+STARTUP: logdone}}.
+in-buffer setting is: @code{#+STARTUP: logdone}}
@lisp
(setq org-log-done 'time)
@end lisp
+@vindex org-closed-keep-when-no-todo
@noindent
-Then each time you turn an entry from a TODO (not-done) state into any
-of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted
-just after the headline. If you turn the entry back into a TODO item
-through further state cycling, that line will be removed again. If you
-want to record a note along with the timestamp, use@footnote{The
-corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}}
+Then each time you turn an entry from a TODO (not-done) state into any of the
+DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
+the headline. If you turn the entry back into a TODO item through further
+state cycling, that line will be removed again. If you turn the entry back
+to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
+will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
+non-@code{nil}. If you want to record a note along with the timestamp,
+use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
+lognotedone}.}
@lisp
(setq org-log-done 'note)
might want to keep track of when a state change occurred and maybe take a
note about this change. You can either record just a timestamp, or a
time-stamped note for a change. These records will be inserted after the
-headline as an itemized list, newest first@footnote{See the variable
+headline as an itemized list, newest first@footnote{See the option
@code{org-log-states-order-reversed}}. When taking a lot of notes, you might
want to get the notes out of the way into a drawer (@pxref{Drawers}).
-Customize the variable @code{org-log-into-drawer} to get this
-behavior---the recommended drawer for this is called @code{LOGBOOK}. You can
-also overrule the setting of this variable for a subtree by setting a
+Customize @code{org-log-into-drawer} to get this behavior---the recommended
+drawer for this is called @code{LOGBOOK}@footnote{Note that the
+@code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
+show an entry---use @key{C-u SPC} to keep it folded here}. You can also
+overrule the setting of this variable for a subtree by setting a
@code{LOG_INTO_DRAWER} property.
Since it is normally too much to record a note for every state, Org mode
expects configuration on a per-keyword basis for this. This is achieved by
-adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note)
-in parentheses after each keyword. For example, with the setting
+adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
+with timestamp) in parentheses after each keyword. For example, with the
+setting
@lisp
(setq org-todo-keywords
'((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
@end lisp
+To record a timestamp without a note for TODO keywords configured with
+@samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
+
@noindent
@vindex org-log-done
you not only define global TODO keywords and fast access keys, but also
However, it will never prompt for two notes---if you have configured
both, the state change recording note will take precedence and cancel
the @samp{Closing Note}.}, and that a note is recorded when switching to
-WAIT or CANCELED. The setting for WAIT is even more special: the
+WAIT or CANCELED@. The setting for WAIT is even more special: the
@samp{!} after the slash means that in addition to the note taken when
entering the state, a timestamp should be recorded when @i{leaving} the
WAIT state, if and only if the @i{target} state does not configure
@cindex property, LOGGING
In order to define logging settings that are local to a subtree or a
single item, define a LOGGING property in this entry. Any non-empty
-LOGGING property resets all logging settings to nil. You may then turn
+LOGGING property resets all logging settings to @code{nil}. You may then turn
on logging for this specific tree using STARTUP keywords like
@code{lognotedone} or @code{logrepeat}, as well as adding state specific
settings like @code{TODO(!)}. For example
@enumerate
@item
-You have enabled the @code{habits} module by customizing the variable
-@code{org-modules}.
+You have enabled the @code{habits} module by customizing @code{org-modules}.
@item
-The habit is a TODO, with a TODO keyword representing an open state.
+The habit is a TODO item, with a TODO keyword representing an open state.
@item
The property @code{STYLE} is set to the value @code{habit}.
@item
-The TODO has a scheduled date, with a @code{.+} style repeat interval.
+The TODO has a scheduled date, usually with a @code{.+} style repeat
+interval. A @code{++} style may be appropriate for habits with time
+constraints, e.g., must be done on weekends, or a @code{+} style for an
+unusual habit that can have a backlog, e.g., weekly reports.
@item
The TODO may also have minimum and maximum ranges specified by using the
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's not
-enabled it's 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
If the task was overdue on that day.
@end table
-In addition to coloring each day, the day is also marked with an asterix if
+In addition to coloring each day, the day is also marked with an asterisk if
the task was actually done that day, and an exclamation mark to show where
the current day falls in the graph.
@table @code
@item org-habit-graph-column
The buffer column at which the consistency graph should be drawn. This will
-overwrite any text in that column, so it's a good idea to keep your habits'
+overwrite any text in that column, so it is a good idea to keep your habits'
titles brief and to the point.
@item org-habit-preceding-days
The amount of history, in days before today, to appear in consistency graphs.
@item org-habit-following-days
The number of days after today that will appear in consistency graphs.
@item org-habit-show-habits-only-for-today
-If non-nil, only show habits in today's agenda view. This is set to true by
+If non-@code{nil}, only show habits in today's agenda view. This is set to true by
default.
@end table
@section Priorities
@cindex priorities
-If you use Org mode extensively, you may end up enough TODO items that
+If you use Org mode extensively, you may end up with enough TODO items that
it starts to make sense to prioritize them. Prioritizing can be done by
-placing a @emph{priority cookie} into the headline of a TODO item, like
-this
+placing a @emph{priority cookie} into the headline of a TODO item, like this
@example
*** TODO [#A] Write letter to Sam Fortune
@end example
@noindent
+@vindex org-priority-faces
By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
-@samp{C}. @samp{A} is the highest priority. An entry without a cookie
-is treated as priority @samp{B}. Priorities make a difference only in
-the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they have
-no inherent meaning to Org mode.
+@samp{C}. @samp{A} is the highest priority. An entry without a cookie is
+treated just like priority @samp{B}. Priorities make a difference only for
+sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
+have no inherent meaning to Org mode. The cookies can be highlighted with
+special faces by customizing @code{org-priority-faces}.
-Priorities can be attached to any outline tree entries; they do not need
-to be TODO items.
+Priorities can be attached to any outline node; they do not need to be TODO
+items.
@table @kbd
-@kindex @kbd{C-c ,}
@item @kbd{C-c ,}
-Set the priority of the current headline. The command prompts for a
-priority character @samp{A}, @samp{B} or @samp{C}. When you press
-@key{SPC} instead, the priority cookie is removed from the headline.
-The priorities can also be changed ``remotely'' from the timeline and
-agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
+@kindex @kbd{C-c ,}
+@findex org-priority
+Set the priority of the current headline (@command{org-priority}). The
+command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
+When you press @key{SPC} instead, the priority cookie is removed from the
+headline. The priorities can also be changed ``remotely'' from the timeline
+and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
@c
-@kindex S-@key{up}
-@kindex S-@key{down}
-@item S-@key{up}
-@itemx S-@key{down}
+@orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
@vindex org-priority-start-cycle-with-default
Increase/decrease priority of current headline@footnote{See also the option
@code{org-priority-start-cycle-with-default}.}. Note that these keys are
@vindex org-highest-priority
@vindex org-lowest-priority
@vindex org-default-priority
-You can change the range of allowed priorities by setting the variables
+You can change the range of allowed priorities by setting the options
@code{org-highest-priority}, @code{org-lowest-priority}, and
@code{org-default-priority}. For an individual buffer, you may set
these values (highest, lowest, default) like this (please make sure that
global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
the overview over the fraction of subtasks that are already completed, insert
either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
-be updates each time the todo status of a child changes, or when pressing
+be updated each time the TODO status of a child changes, or when pressing
@kbd{C-c C-c} on the cookie. For example:
@example
@vindex org-hierarchical-todo-statistics
If you would like to have the statistics cookie count any TODO entries in the
-subtree (not just direct children), configure the variable
+subtree (not just direct children), configure
@code{org-hierarchical-todo-statistics}. To do this for a single subtree,
include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
property.
@section Checkboxes
@cindex checkboxes
-Every item in a plain list (@pxref{Plain lists}) can be made into a
-checkbox by starting it with the string @samp{[ ]}. This feature is
-similar to TODO items (@pxref{TODO Items}), but is more lightweight.
-Checkboxes are not included into the global TODO list, so they are often
-great to split a task into a number of simple steps. Or you can use
-them in a shopping list. To toggle a checkbox, use @kbd{C-c C-c}, or
-use the mouse (thanks to Piotr Zielinski's @file{org-mouse.el}).
+@vindex org-list-automatic-rules
+Every item in a plain list@footnote{With the exception of description
+lists. But you can allow it by modifying @code{org-list-automatic-rules}
+accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
+it with the string @samp{[ ]}. This feature is similar to TODO items
+(@pxref{TODO Items}), but is more lightweight. Checkboxes are not included
+in the global TODO list, so they are often great to split a task into a
+number of simple steps. Or you can use them in a shopping list. To toggle a
+checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
+@file{org-mouse.el}).
Here is an example of a checkbox list.
@cindex statistics, for checkboxes
@cindex checkbox statistics
@cindex property, COOKIE_DATA
-@vindex org-hierarchical-checkbox-statistics
+@vindex org-checkbox-hierarchical-statistics
The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
indicating how many checkboxes present in this entry have been checked off,
and the total number of checkboxes present. This can give you an idea on how
many checkboxes remain, even without opening a folded entry. The cookies can
be placed into a headline or into (the first line of) a plain list item.
Each cookie covers checkboxes of direct children structurally below the
-headline/item on which the cookie appears@footnote{Set the variable
-@code{org-hierarchical-checkbox-statistics} if you want such cookies to
-represent the all checkboxes below the cookie, not just the direct
+headline/item on which the cookie appears@footnote{Set the option
+@code{org-checkbox-hierarchical-statistics} if you want such cookies to
+count all checkboxes below the cookie, not just those belonging to direct
children.}. You have to insert the cookie yourself by typing either
@samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
result, as in the examples above. With @samp{[%]} you get information about
@noindent The following commands work with checkboxes:
@table @kbd
-@kindex C-c C-c
-@item C-c C-c
-Toggle checkbox status or (with prefix arg) checkbox presence at point. With
-double prefix argument, set it to @samp{[-]}, which is considered to be an
-intermediate state.
-@kindex C-c C-x C-b
-@item C-c C-x C-b
+@orgcmd{C-c C-c,org-toggle-checkbox}
+Toggle checkbox status or (with prefix arg) checkbox presence at point.
+With a single prefix argument, add an empty checkbox or remove the current
+one@footnote{@kbd{C-u C-c C-c} on the @emph{first} item of a list with no checkbox
+will add checkboxes to the rest of the list.}. With a double prefix argument, set it to @samp{[-]}, which is
+considered to be an intermediate state.
+@orgcmd{C-c C-x C-b,org-toggle-checkbox}
Toggle checkbox status or (with prefix arg) checkbox presence at point. With
double prefix argument, set it to @samp{[-]}, which is considered to be an
intermediate state.
@item
If there is no active region, just toggle the checkbox at point.
@end itemize
-@kindex M-S-@key{RET}
-@item M-S-@key{RET}
-Insert a new item with a checkbox.
-This works only if the cursor is already in a plain list item
-(@pxref{Plain lists}).
-@kindex C-c C-x o
-@item C-c C-x o
+@orgcmd{M-S-@key{RET},org-insert-todo-heading}
+Insert a new item with a checkbox. This works only if the cursor is already
+in a plain list item (@pxref{Plain lists}).
+@orgcmd{C-c C-x o,org-toggle-ordered-property}
@vindex org-track-ordered-property-with-tag
@cindex property, ORDERED
Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
be checked off in sequence. A property is used for this behavior because
this should be local to the current entry, not inherited like a tag.
However, if you would like to @i{track} the value of this property with a tag
-for better visibility, customize the variable
-@code{org-track-ordered-property-with-tag}.
-@kindex C-c #
-@item C-c #
+for better visibility, customize @code{org-track-ordered-property-with-tag}.
+@orgcmd{C-c #,org-update-statistics-cookies}
Update the statistics cookie in the current outline entry. When called with
a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when
changing TODO states. If you delete boxes/entries or add/change them by
-hand, use this command to get things back into sync. Or simply toggle any
-entry twice (checkboxes with @kbd{C-c C-c}).
+hand, use this command to get things back into sync.
@end table
@node Tags, Properties and Columns, TODO Items, Top
@samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
Tags will by default be in bold face with the same color as the headline.
-You may specify special faces for specific tags using the variable
+You may specify special faces for specific tags using the option
@code{org-tag-faces}, in much the same way as you can for TODO keywords
(@pxref{Faces for TODO keywords}).
@menu
* Tag inheritance:: Tags use the tree structure of the outline
* Setting tags:: How to assign tags to a headline
+* Tag groups:: Use one tag to search for several tags
* Tag searches:: Searching for combinations of tags
@end menu
@noindent
@vindex org-use-tag-inheritance
@vindex org-tags-exclude-from-inheritance
-To limit tag inheritance to specific tags, or to turn it off entirely, use
-the variables @code{org-use-tag-inheritance} and
-@code{org-tags-exclude-from-inheritance}.
+To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
+To turn it off entirely, use @code{org-use-tag-inheritance}.
@vindex org-tags-match-list-sublevels
When a headline matches during a tags search while tag inheritance is turned
as well@footnote{This is only true if the search does not involve more
complex tests including properties (@pxref{Property searches}).}. The list
of matches may then become very long. If you only want to see the first tags
-match in a subtree, configure the variable
-@code{org-tags-match-list-sublevels} (not recommended).
-
-@node Setting tags, Tag searches, Tag inheritance, Tags
+match in a subtree, configure @code{org-tags-match-list-sublevels} (not
+recommended).
+
+@vindex org-agenda-use-tag-inheritance
+Tag inheritance is relevant when the agenda search tries to match a tag,
+either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
+types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
+have your tags correctly set in the agenda, so that tag filtering works fine,
+with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
+this: the default value includes all agenda types, but setting this to @code{nil}
+can really speed up agenda generation.
+
+@node Setting tags, Tag groups, Tag inheritance, Tags
@section Setting tags
@cindex setting tags
@cindex tags, setting
also a special command for inserting tags:
@table @kbd
-@kindex C-c C-q
-@item C-c C-q
+@orgcmd{C-c C-q,org-set-tags-command}
@cindex completion, of tags
@vindex org-tags-column
Enter new tags for the current headline. Org mode will either offer
tags in the current buffer will be aligned to that column, just to make
things look nice. TAGS are automatically realigned after promotion,
demotion, and TODO state changes (@pxref{TODO basics}).
-@kindex C-c C-c
-@item C-c C-c
+
+@orgcmd{C-c C-c,org-set-tags-command}
When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
@end table
@vindex org-tag-alist
-Org will support tag insertion based on a @emph{list of tags}. By
+Org supports tag insertion based on a @emph{list of tags}. By
default this list is constructed dynamically, containing all tags
currently used in the buffer. You may also globally specify a hard list
of tags with the variable @code{org-tag-alist}. Finally you can set
these lines to activate any changes.
@noindent
-To set these mutually exclusive groups in the variable @code{org-tags-alist},
+To set these mutually exclusive groups in the variable @code{org-tag-alist},
you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
of the braces. Similarly, you can use @code{:newline} to indicate a line
break. The previous example would be set globally by the following
@item @key{TAB}
Enter a tag in the minibuffer, even if the tag is not in the predefined
list. You will be able to complete on all tags present in the buffer.
+You can also add several tags: just separate them with a comma.
+
@kindex @key{SPC}
@item @key{SPC}
Clear all tags for this line.
@vindex org-fast-tag-selection-single-key
If you find that most of the time you need only a single key press to
-modify your list of tags, set the variable
-@code{org-fast-tag-selection-single-key}. Then you no longer have to
-press @key{RET} to exit fast tag selection---it will immediately exit
-after the first change. If you then occasionally need more keys, press
-@kbd{C-c} to turn off auto-exit for the current tag selection process
-(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c
-C-c}). If you set the variable to the value @code{expert}, the special
-window is not even shown for single-key tag selection, it comes up only
-when you press an extra @kbd{C-c}.
-
-@node Tag searches, , Setting tags, Tags
+modify your list of tags, set @code{org-fast-tag-selection-single-key}.
+Then you no longer have to press @key{RET} to exit fast tag selection---it
+will immediately exit after the first change. If you then occasionally
+need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
+selection process (in effect: start selection with @kbd{C-c C-c C-c}
+instead of @kbd{C-c C-c}). If you set the variable to the value
+@code{expert}, the special window is not even shown for single-key tag
+selection, it comes up only when you press an extra @kbd{C-c}.
+
+@node Tag groups, Tag searches, Setting tags, Tags
+@section Tag groups
+
+@cindex group tags
+@cindex tags, groups
+In a set of mutually exclusive tags, the first tag can be defined as a
+@emph{group tag}. When you search for a group tag, it will return matches
+for all members in the group. In an agenda view, filtering by a group tag
+will display headlines tagged with at least one of the members of the
+group. This makes tag searches and filters even more flexible.
+
+You can set group tags by inserting a colon between the group tag and other
+tags---beware that all whitespaces are mandatory so that Org can parse this
+line correctly:
+
+@example
+#+TAGS: @{ @@read : @@read_book @@read_ebook @}
+@end example
+
+In this example, @samp{@@read} is a @emph{group tag} for a set of three
+tags: @samp{@@read}, @samp{@@read_book} and @samp{@@read_ebook}.
+
+You can also use the @code{:grouptags} keyword directly when setting
+@code{org-tag-alist}:
+
+@lisp
+(setq org-tag-alist '((:startgroup . nil)
+ ("@@read" . nil)
+ (:grouptags . nil)
+ ("@@read_book" . nil)
+ ("@@read_ebook" . nil)
+ (:endgroup . nil)))
+@end lisp
+
+You cannot nest group tags or use a group tag as a tag in another group.
+
+@kindex C-c C-x q
+@vindex org-group-tags
+If you want to ignore group tags temporarily, toggle group tags support
+with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you
+want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
+
+@node Tag searches, , Tag groups, Tags
@section Tag searches
@cindex tag searches
@cindex searching for tags
information into special lists.
@table @kbd
-@kindex C-c \
-@kindex C-c / m
-@item C-c \
-@itemx C-c / m
-Create a sparse tree with all headlines matching a tags search. With a
-@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
-@kindex C-c a m
-@item C-c a m
-Create a global list of tag matches from all agenda files.
+@orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
+Create a sparse tree with all headlines matching a tags/property/TODO search.
+With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
@xref{Matching tags and properties}.
-@kindex C-c a M
-@item C-c a M
+@orgcmd{C-c a m,org-tags-view}
+Create a global list of tag matches from all agenda files. @xref{Matching
+tags and properties}.
+@orgcmd{C-c a M,org-tags-view}
@vindex org-tags-match-list-sublevels
Create a global list of tag matches from all agenda files, but check
-only TODO items and force checking subitems (see variable
+only TODO items and force checking subitems (see the option
@code{org-tags-match-list-sublevels}).
@end table
@node Properties and Columns, Dates and Times, Tags, Top
-@chapter Properties and Columns
+@chapter Properties and columns
@cindex properties
-Properties are a set of key-value pairs associated with an entry. There
-are two main applications for properties in Org mode. First, properties
-are like tags, but with a value. Second, you can use properties to
-implement (very basic) database capabilities in an Org buffer. For
-an example of the first application, imagine maintaining a file where
+A property is a key-value pair associated with an entry. Properties can be
+set so they are associated with a single entry, with every entry in a tree,
+or with every entry in an Org mode file.
+
+There are two main applications for properties in Org mode. First,
+properties are like tags, but with a value. Imagine maintaining a file where
you document bugs and plan releases for a piece of software. Instead of
-using tags like @code{:release_1:}, @code{:release_2:}, one can use a
+using tags like @code{:release_1:}, @code{:release_2:}, you can use a
property, say @code{:Release:}, that in different subtrees has different
-values, such as @code{1.0} or @code{2.0}. For an example of the second
-application of properties, imagine keeping track of your music CDs,
-where properties could be things such as the album, artist, date of
-release, number of tracks, and so on.
+values, such as @code{1.0} or @code{2.0}. Second, you can use properties to
+implement (very basic) database capabilities in an Org buffer. Imagine
+keeping track of your music CDs, where properties could be things such as the
+album, artist, date of release, number of tracks, and so on.
Properties can be conveniently edited and viewed in column view
(@pxref{Column view}).
@cindex property syntax
@cindex drawer, for properties
-Properties are key-value pairs. They need to be inserted into a special
+Properties are key-value pairs. When they are associated with a single entry
+or with a tree they need to be inserted into a special
drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property
is specified on a single line, with the key (surrounded by colons)
first, and the value after it. Here is an example:
:END:
@end example
+Depending on the value of @code{org-use-property-inheritance}, a property set
+this way will either be associated with a single entry, or the sub-tree
+defined by the entry, see @ref{Property inheritance}.
+
You may define the allowed values for a particular property @samp{:Xyz:}
by setting a property @samp{:Xyz_ALL:}. This special property is
@emph{inherited}, so if you set it in a level 1 entry, it will apply to
#+PROPERTY: NDisks_ALL 1 2 3 4
@end example
+Contrary to properties set from a special drawer, you have to refresh the
+buffer with @kbd{C-c C-c} to activate this changes.
+
+If you want to add to the value of an existing property, append a @code{+} to
+the property name. The following results in the property @code{var} having
+the value ``foo=1 bar=2''.
+@cindex property, +
+@example
+#+PROPERTY: var foo=1
+#+PROPERTY: var+ bar=2
+@end example
+
+It is also possible to add to the values of inherited properties. The
+following results in the @code{genres} property having the value ``Classic
+Baroque'' under the @code{Goldberg Variations} subtree.
+@cindex property, +
+@example
+* CD collection
+** Classic
+ :PROPERTIES:
+ :GENRES: Classic
+ :END:
+*** Goldberg Variations
+ :PROPERTIES:
+ :Title: Goldberg Variations
+ :Composer: J.S. Bach
+ :Artist: Glen Gould
+ :Publisher: Deutsche Grammophon
+ :NDisks: 1
+ :GENRES+: Baroque
+ :END:
+@end example
+Note that a property can only have one entry per Drawer.
+
@vindex org-global-properties
Property values set with the global variable
@code{org-global-properties} can be inherited by all entries in all
The following commands help to work with properties:
@table @kbd
-@kindex M-@key{TAB}
-@item M-@key{TAB}
+@orgcmd{M-@key{TAB},pcomplete}
After an initial colon in a line, complete property keys. All keys used
in the current file will be offered as possible completions.
-@kindex C-c C-x p
-@item C-c C-x p
+@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
+@item C-u M-x org-insert-drawer RET
+@cindex org-insert-drawer
Insert a property drawer into the current entry. The drawer will be
inserted early in the entry, but after the lines with planning
information like deadlines.
-@kindex C-c C-c
-@item C-c C-c
+@orgcmd{C-c C-c,org-property-action}
With the cursor in a property drawer, this executes property commands.
-@item C-c C-c s
+@orgcmd{C-c C-c s,org-set-property}
Set a property in the current entry. Both the property and the value
can be inserted using completion.
-@kindex S-@key{right}
-@kindex S-@key{left}
-@item S-@key{left}/@key{right}
+@orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
Switch property at point to the next/previous allowed value.
-@item C-c C-c d
+@orgcmd{C-c C-c d,org-delete-property}
Remove a property from the current entry.
-@item C-c C-c D
+@orgcmd{C-c C-c D,org-delete-property-globally}
Globally remove a property, from all entries in the current file.
-@item C-c C-c c
+@orgcmd{C-c C-c c,org-compute-property-at-point}
Compute the property at point, using the operator and scope from the
nearest column format definition.
@end table
@section Special properties
@cindex properties, special
-Special properties provide an alternative access method to Org mode
-features, like the TODO state or the priority of an entry, discussed in the
-previous chapters. This interface exists so that you can include
-these states in a column view (@pxref{Column view}), or to use them in
-queries. The following property names are special and should not be
+Special properties provide an alternative access method to Org mode features,
+like the TODO state or the priority of an entry, discussed in the previous
+chapters. This interface exists so that you can include these states in a
+column view (@pxref{Column view}), or to use them in queries. The following
+property names are special and (except for @code{:CATEGORY:}) should not be
used as keys in the properties drawer:
+@cindex property, special, ID
@cindex property, special, TODO
@cindex property, special, TAGS
@cindex property, special, ALLTAGS
@cindex property, special, TIMESTAMP
@cindex property, special, TIMESTAMP_IA
@cindex property, special, CLOCKSUM
+@cindex property, special, CLOCKSUM_T
+@cindex property, special, BLOCKED
@c guessing that ITEM is needed in this area; also, should this list be sorted?
@cindex property, special, ITEM
+@cindex property, special, FILE
@example
+ID @r{A globally unique ID used for synchronization during}
+ @r{iCalendar or MobileOrg export.}
TODO @r{The TODO keyword of the entry.}
TAGS @r{The tags defined directly in the headline.}
ALLTAGS @r{All tags, including inherited ones.}
TIMESTAMP @r{The first keyword-less timestamp in the entry.}
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.}
-ITEM @r{The content of the entry.}
+ @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 headline of the entry.}
+FILE @r{The filename the entry is located in.}
@end example
@node Property searches, Property inheritance, Special properties, Properties and Columns
To create sparse trees and special lists with selection based on properties,
the same commands are used as for tag searches (@pxref{Tag searches}).
+
@table @kbd
-@kindex C-c \
-@kindex C-c / m
-@item C-c \
-@itemx C-c / m
+@orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
Create a sparse tree with all matching entries. With a
@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
-@kindex C-c a m
-@item C-c a m
+@orgcmd{C-c a m,org-tags-view}
Create a global list of tag/property matches from all agenda files.
@xref{Matching tags and properties}.
-@kindex C-c a M
-@item C-c a M
+@orgcmd{C-c a M,org-tags-view}
@vindex org-tags-match-list-sublevels
Create a global list of tag matches from all agenda files, but check
-only TODO items and force checking of subitems (see variable
+only TODO items and force checking of subitems (see the option
@code{org-tags-match-list-sublevels}).
@end table
single property:
@table @kbd
-@kindex C-c / p
-@item C-c / p
+@orgkey{C-c / p}
Create a sparse tree based on the value of a property. This first
prompts for the name of a property, and then for a value. A sparse tree
is created with all entries that define this property with the given
-value. If you enclose the value into curly braces, it is interpreted as
+value. If you enclose the value in curly braces, it is interpreted as
a regular expression and matched against the property values.
@end table
@cindex inheritance, of properties
@vindex org-use-property-inheritance
-The outline structure of Org-mode documents lends itself for an
+The outline structure of Org mode documents lends itself to an
inheritance model of properties: if the parent in a tree has a certain
property, the children can inherit this property. Org mode does not
turn this on by default, because it can slow down property searches
@code{org-use-property-inheritance}. It may be set to @code{t} to make
all properties inherited from the parent, to a list of properties
that should be inherited, or to a regular expression that matches
-inherited properties.
+inherited properties. If a property has the value @code{nil}, this is
+interpreted as an explicit undefine of the property, so that inheritance
+search will stop at this value and return @code{nil}.
Org mode has a few properties for which inheritance is hard-coded, at
least for the special applications for which they are used:
@var{property} @r{The property that should be edited in this column.}
@r{Special properties representing meta data are allowed here}
@r{as well (@pxref{Special properties})}
-(title) @r{The header text for the column. If omitted, the}
- @r{property name is used.}
+@var{title} @r{The header text for the column. If omitted, the property}
+ @r{name is used.}
@{@var{summary-type}@} @r{The summary type. If specified, the column values for}
@r{parent nodes are computed from the children.}
@r{Supported summary types are:}
@{+@} @r{Sum numbers in this column.}
@{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
@{$@} @r{Currency, short for @samp{+;%.2f}.}
- @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.}
+ @{:@} @r{Sum times, HH:MM, plain numbers are hours.}
@{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
@{X/@} @r{Checkbox status, @samp{[n/m]}.}
@{X%@} @r{Checkbox status, @samp{[n%]}.}
@{:min@} @r{Smallest time value in column.}
@{:max@} @r{Largest time value.}
@{:mean@} @r{Arithmetic mean of time values.}
- @{@@min@} @r{Minimum age (in days/hours/mins/seconds).}
- @{@@max@} @r{Maximum age (in days/hours/mins/seconds).}
- @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
+ @{@@min@} @r{Minimum age (in days/hours/mins/seconds).}
+ @{@@max@} @r{Maximum age (in days/hours/mins/seconds).}
+ @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
+ @{est+@} @r{Add low-high estimates.}
@end example
@noindent
Be aware that you can only have one summary type for any property you
-include. Subsequent columns referencing the same property will all display the
+include. Subsequent columns referencing the same property will all display the
same summary information.
+The @code{est+} summary type requires further explanation. It is used for
+combining estimates, expressed as low-high ranges. For example, instead
+of estimating a particular task will take 5 days, you might estimate it as
+5--6 days if you're fairly confident you know how much work is required, or
+1--10 days if you don't really know what needs to be done. Both ranges
+average at 5.5 days, but the first represents a more predictable delivery.
+
+When combining a set of such estimates, simply adding the lows and highs
+produces an unrealistically wide result. Instead, @code{est+} adds the
+statistical mean and variance of the sub-tasks, generating a final estimate
+from the sum. For example, suppose you had ten tasks, each of which was
+estimated at 0.5 to 2 days of work. Straight addition produces an estimate
+of 5 to 20 days, representing what to expect if everything goes either
+extremely well or extremely poorly. In contrast, @code{est+} estimates the
+full job more realistically, at 10--15 days.
+
Here is an example for a complete columns definition, along with allowed
values.
@example
:COLUMNS: %25ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line---it is wrapped here only because of formatting constraints.}
- %10Time_Estimate@{:@} %CLOCKSUM
+ %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T
:Owner_ALL: Tammy Mark Karl Lisa Don
:Status_ALL: "In progress" "Not started yet" "Finished" ""
:Approved_ALL: "[ ]" "[X]"
@noindent
The first column, @samp{%25ITEM}, means the first 25 characters of the
-item itself, i.e. of the headline. You probably always should start the
+item itself, i.e., of the headline. You probably always should start the
column definition with the @samp{ITEM} specifier. The other specifiers
create columns @samp{Owner} with a list of names as allowed values, for
@samp{Status} with four different possible values, and for a checkbox
be created for the @samp{Time_Estimate} column by adding time duration
expressions like HH:MM, and for the @samp{Approved} column, by providing
an @samp{[X]} status if all children have been checked. The
-@samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals
-in the subtree.
+@samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns are special, they lists the
+sums of CLOCK intervals in the subtree, either for all clocks or just for
+today.
@node Using column view, Capturing column view, Defining columns, Column view
@subsection Using column view
@table @kbd
@tsubheading{Turning column view on and off}
-@kindex C-c C-x C-c
-@item C-c C-x C-c
+@orgcmd{C-c C-x C-c,org-columns}
@vindex org-columns-default-format
Turn on column view. If the cursor is before the first headline in the file,
column view is turned on for the entire file, using the @code{#+COLUMNS}
property. If no such property is found, the format is taken from the
@code{#+COLUMNS} line or from the variable @code{org-columns-default-format},
and column view is established for the current entry and its subtree.
-@kindex r
-@item r
+@orgcmd{r,org-columns-redo}
Recreate the column view, to include recent changes made in the buffer.
-@kindex g
-@item g
+@orgcmd{g,org-columns-redo}
Same as @kbd{r}.
-@kindex q
-@item q
+@orgcmd{q,org-columns-quit}
Exit column view.
@tsubheading{Editing values}
@item @key{left} @key{right} @key{up} @key{down}
Switch to the next/previous allowed value of the field. For this, you
have to have specified allowed values for a property.
@item 1..9,0
-Directly select the nth allowed value, @kbd{0} selects the 10th value.
-@kindex n
-@kindex p
-@itemx n / p
+Directly select the Nth allowed value, @kbd{0} selects the 10th value.
+@orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
Same as @kbd{S-@key{left}/@key{right}}
-@kindex e
-@item e
+@orgcmd{e,org-columns-edit-value}
Edit the property at point. For the special properties, this will
invoke the same interface that you normally use to change that
property. For example, when editing a TAGS property, the tag completion
or fast selection interface will pop up.
-@kindex C-c C-c
-@item C-c C-c
+@orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
When there is a checkbox at point, toggle it.
-@kindex v
-@item v
+@orgcmd{v,org-columns-show-value}
View the full value of this property. This is useful if the width of
the column is smaller than that of the value.
-@kindex a
-@item a
+@orgcmd{a,org-columns-edit-allowed}
Edit the list of allowed values for this property. If the list is found
in the hierarchy, the modified values is stored there. If no list is
found, the new value is stored in the first entry that is part of the
current column view.
@tsubheading{Modifying the table structure}
-@kindex <
-@kindex >
-@item < / >
+@orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
Make the column narrower/wider by one character.
-@kindex S-M-@key{right}
-@item S-M-@key{right}
+@orgcmd{S-M-@key{right},org-columns-new}
Insert a new column, to the left of the current column.
-@kindex S-M-@key{left}
-@item S-M-@key{left}
+@orgcmd{S-M-@key{left},org-columns-delete}
Delete the current column.
@end table
@r{run column view at the top of this file}
"@var{ID}" @r{call column view in the tree that has an @code{:ID:}}
@r{property with the value @i{label}. You can use}
- @r{@kbd{M-x org-id-copy} to create a globally unique ID for}
+ @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for}
@r{the current entry and copy it to the kill-ring.}
@end example
@item :hlines
The following commands insert or update the dynamic block:
@table @kbd
-@kindex C-c C-x i
-@item C-c C-x i
+@orgcmd{C-c C-x i,org-insert-columns-dblock}
Insert a dynamic block capturing a column view. You will be prompted
for the scope or ID of the view.
-@kindex C-c C-c
-@item C-c C-c
-@kindex C-c C-x C-u
-@itemx C-c C-x C-u
+@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
Update dynamic block at point. The cursor needs to be in the
@code{#+BEGIN} line of the dynamic block.
-@kindex C-u C-c C-x C-u
-@item C-u C-c C-x C-u
+@orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
-you have several clock table blocks in a buffer.
+you have several clock table blocks, column-capturing blocks or other dynamic
+blocks in a buffer.
@end table
You can add formulas to the column view table and you may add plotting
property API}.
@node Dates and Times, Capture - Refile - Archive, Properties and Columns, Top
-@chapter Dates and Times
+@chapter Dates and times
@cindex dates
@cindex times
@cindex timestamp
* Creating timestamps:: Commands which insert timestamps
* Deadlines and scheduling:: Planning your work
* Clocking work time:: Tracking how long you spend on a task
-* Resolving idle time:: Resolving time if you've been idle
* Effort estimates:: Planning work effort in advance
* Relative timer:: Notes with a running timer
+* Countdown timer:: Starting a countdown timer for a task
@end menu
@cindex scheduling
A timestamp is a specification of a date (possibly with a time or a range of
-times) in a special format, either @samp{<2003-09-16 Tue>} or
-@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue
-12:00-12:30>}@footnote{This is inspired by the standard ISO 6801 date/time
-format. To use an alternative format, see @ref{Custom time format}.}. A
-timestamp can appear anywhere in the headline or body of an Org tree entry.
-Its presence causes entries to be shown on specific dates in the agenda
-(@pxref{Weekly/daily agenda}). We distinguish:
+times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this
+simplest form, the day name is optional when you type the date yourself.
+However, any dates inserted or modified by Org will add that day name, for
+reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16
+Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601
+date/time format. To use an alternative format, see @ref{Custom time
+format}.}. A timestamp can appear anywhere in the headline or body of an Org
+tree entry. Its presence causes entries to be shown on specific dates in the
+agenda (@pxref{Weekly/daily agenda}). We distinguish:
@table @var
@item Plain timestamp; Event; Appointment
@cindex timestamp
+@cindex appointment
A simple timestamp just assigns a date/time to an item. This is just
like writing down an appointment or event in a paper agenda. In the
timeline and agenda displays, the headline of an entry associated with a
plain timestamp will be shown exactly on that date.
@example
-* Meet Peter at the movies <2006-11-01 Wed 19:15>
-* Discussion on climate change <2006-11-02 Thu 20:00-22:00>
+* Meet Peter at the movies
+ <2006-11-01 Wed 19:15>
+* Discussion on climate change
+ <2006-11-02 Thu 20:00-22:00>
@end example
@item Timestamp with repeater interval
following will show up in the agenda every Wednesday:
@example
-* Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
+* Pick up Sam at school
+ <2007-05-16 Wed 12:30 +1w>
@end example
@item Diary-style sexp entries
-For more complex date specifications, Org mode supports using the
-special sexp diary entries implemented in the Emacs calendar/diary
-package. For example
+For more complex date specifications, Org mode supports using the special
+sexp diary entries implemented in the Emacs calendar/diary
+package@footnote{When working with the standard diary sexp functions, you
+need to be very careful with the order of the arguments. That order depend
+evilly on the variable @code{calendar-date-style} (or, for older Emacs
+versions, @code{european-calendar-style}). For example, to specify a date
+December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or
+@code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
+the settings. This has been the source of much confusion. Org mode users
+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 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
<%%(diary-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
format.
@table @kbd
-@kindex C-c .
-@item C-c .
+@orgcmd{C-c .,org-time-stamp}
Prompt for a date and insert a corresponding timestamp. When the cursor is
at an existing timestamp in the buffer, the command is used to modify this
timestamp instead of inserting a new one. When this command is used twice in
succession, a time range is inserted.
@c
-@kindex C-c !
-@item C-c !
+@orgcmd{C-c !,org-time-stamp-inactive}
Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
an agenda entry.
@c
contains date and time. The default time can be rounded to multiples of 5
minutes, see the option @code{org-time-stamp-rounding-minutes}.
@c
-@kindex C-c <
-@item C-c <
+@orgkey{C-c C-c}
+Normalize timestamp, insert/fix day name if missing or wrong.
+@c
+@orgcmd{C-c <,org-date-from-calendar}
Insert a timestamp corresponding to the cursor date in the Calendar.
@c
-@kindex C-c >
-@item C-c >
+@orgcmd{C-c >,org-goto-calendar}
Access the Emacs calendar for the current date. If there is a
timestamp in the current line, go to the corresponding date
instead.
@c
-@kindex C-c C-o
-@item C-c C-o
+@orgcmd{C-c C-o,org-open-at-point}
Access the agenda for the date given by the timestamp or -range at
point (@pxref{Weekly/daily agenda}).
@c
-@kindex S-@key{left}
-@kindex S-@key{right}
-@item S-@key{left}
-@itemx S-@key{right}
+@orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
Change date at cursor by one day. These key bindings conflict with
shift-selection and related modes (@pxref{Conflicts}).
@c
-@kindex S-@key{up}
-@kindex S-@key{down}
-@item S-@key{up}
-@itemx S-@key{down}
+@orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
Change the item under the cursor in a timestamp. The cursor can be on a
year, month, day, hour or minute. When the timestamp contains a time range
like @samp{15:30-16:30}, modifying the first time will also shift the second,
shifting the time block with constant length. To change the length, modify
the second time. Note that if the cursor is in a headline and not at a
timestamp, these same keys modify the priority of an item.
-(@pxref{Priorities}). The key bindings also conflict with shift-selection and
+(@pxref{Priorities}). The key bindings also conflict with shift-selection and
related modes (@pxref{Conflicts}).
@c
-@kindex C-c C-y
+@orgcmd{C-c C-y,org-evaluate-time-range}
@cindex evaluate time range
-@item C-c C-y
Evaluate a time range by computing the difference between start and end.
With a prefix argument, insert result after the time range (in a table: into
the following column).
@vindex org-read-date-prefer-future
When Org mode prompts for a date/time, the default is shown in default
date/time format, and the prompt therefore seems to ask for a specific
-format. But it will in fact accept any string containing some date and/or
-time information, and it is really smart about interpreting your input. You
-can, for example, use @kbd{C-y} to paste a (possibly multi-line) string
-copied from an email message. Org mode will find whatever information is in
+format. But it will in fact accept date/time information in a variety of
+formats. Generally, the information should start at the beginning of the
+string. Org mode will find whatever information is in
there and derive anything you have not specified from the @emph{default date
and time}. The default is usually the current date and time, but when
modifying an existing timestamp, or when entering the second stamp of a
in @b{bold}.
@example
-3-2-5 --> 2003-02-05
-14 --> @b{2006}-@b{06}-14
-12 --> @b{2006}-@b{07}-12
-Fri --> nearest Friday (defaultdate or later)
-sep 15 --> @b{2006}-09-15
-feb 15 --> @b{2007}-02-15
-sep 12 9 --> 2009-09-12
-12:45 --> @b{2006}-@b{06}-@b{13} 12:45
-22 sept 0:34 --> @b{2006}-09-22 0:34
-w4 --> ISO week for of the current year @b{2006}
-2012 w4 fri --> Friday of ISO week 4 in 2012
-2012-w04-5 --> Same as above
+3-2-5 @result{} 2003-02-05
+2/5/3 @result{} 2003-02-05
+14 @result{} @b{2006}-@b{06}-14
+12 @result{} @b{2006}-@b{07}-12
+2/5 @result{} @b{2007}-02-05
+Fri @result{} nearest Friday after the default date
+sep 15 @result{} @b{2006}-09-15
+feb 15 @result{} @b{2007}-02-15
+sep 12 9 @result{} 2009-09-12
+12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45
+22 sept 0:34 @result{} @b{2006}-09-22 0:34
+w4 @result{} ISO week for of the current year @b{2006}
+2012 w4 fri @result{} Friday of ISO week 4 in 2012
+2012-w04-5 @result{} Same as above
@end example
-Furthermore you can specify a relative date by giving, as the
-@emph{first} thing in the input: a plus/minus sign, a number and a
-letter ([dwmy]) to indicate change in days, weeks, months, or years. With a
-single plus or minus, the date is always relative to today. With a
-double plus or minus, it is relative to the default date. If instead of
-a single letter, you use the abbreviation of day name, the date will be
-the nth such day. E.g.
+Furthermore you can specify a relative date by giving, as the @emph{first}
+thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to
+indicate change in hours, days, weeks, months, or years. With a single plus
+or minus, the date is always relative to today. With a double plus or minus,
+it is relative to the default date. If instead of a single letter, you use
+the abbreviation of day name, the date will be the Nth such day, e.g.:
@example
-+0 --> today
-. --> today
-+4d --> four days from today
-+4 --> same as above
-+2w --> two weeks from today
-++5 --> five days from default date
-+2tue --> second Tuesday from now.
++0 @result{} today
+. @result{} today
++4d @result{} four days from today
++4 @result{} same as above
++2w @result{} two weeks from today
+++5 @result{} five days from default date
++2tue @result{} second Tuesday from now
+-wed @result{} last Wednesday
@end example
@vindex parse-time-months
you want to use unabbreviated names and/or other languages, configure
the variables @code{parse-time-months} and @code{parse-time-weekdays}.
+@vindex org-read-date-force-compatible-dates
+Not all dates can be represented in a given Emacs implementation. By default
+Org mode forces dates into the compatibility range 1970--2037 which works on
+all Emacs implementations. If you want to use dates outside of this range,
+read the docstring of the variable
+@code{org-read-date-force-compatible-dates}.
+
+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.:
+
+@example
+11am-1:15pm @result{} 11:00-13:15
+11am--1:15pm @result{} same as above
+11am+2:15 @result{} same as above
+@end example
+
@cindex calendar, for selecting date
@vindex org-popup-calendar-for-date-prompt
Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
@kindex <
@kindex >
+@kindex M-v
+@kindex C-v
@kindex mouse-1
@kindex S-@key{right}
@kindex S-@key{left}
@kindex M-S-@key{left}
@kindex @key{RET}
@example
-> / < @r{Scroll calendar forward/backward by one month.}
+@key{RET} @r{Choose date at cursor in calendar.}
mouse-1 @r{Select date by clicking on it.}
S-@key{right}/@key{left} @r{One day forward/backward.}
S-@key{down}/@key{up} @r{One week forward/backward.}
M-S-@key{right}/@key{left} @r{One month forward/backward.}
-@key{RET} @r{Choose date in calendar.}
+> / < @r{Scroll calendar forward/backward by one month.}
+M-v / C-v @r{Scroll calendar forward/backward by 3 months.}
@end example
@vindex org-read-date-display-live
will grow on you, and you will start getting annoyed by pretty much any other
way of entering a date/time out there. To help you understand what is going
on, the current interpretation of your input will be displayed live in the
-minibuffer@footnote{If you find this distracting, turn the display of with
+minibuffer@footnote{If you find this distracting, turn the display off with
@code{org-read-date-display-live}.}.
@node Custom time format, , The date/time prompt, Creating timestamps
Org mode uses the standard ISO notation for dates and times as it is
defined in ISO 8601. If you cannot get used to this and require another
representation of date and time to keep you happy, you can get it by
-customizing the variables @code{org-display-custom-times} and
+customizing the options @code{org-display-custom-times} and
@code{org-time-stamp-custom-formats}.
@table @kbd
-@kindex C-c C-x C-t
-@item C-c C-x C-t
+@orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
Toggle the display of custom formats for dates and times.
@end table
time will be changed by one minute.
@item
If the timestamp contains a range of clock times or a repeater, these
-will not be overlayed, but remain in the buffer as they were.
+will not be overlaid, but remain in the buffer as they were.
@item
When you delete a timestamp character-by-character, it will only
disappear from the buffer after @emph{all} (invisible) characters
to be finished on that date.
@vindex org-deadline-warning-days
+@vindex org-agenda-skip-deadline-prewarning-if-scheduled
On the deadline date, the task will be listed in the agenda. In
addition, the agenda for @emph{today} will carry a warning about the
approaching or missed deadline, starting
@code{org-deadline-warning-days} before the due date, and continuing
-until the entry is marked DONE. An example:
+until the entry is marked DONE@. An example:
@example
*** TODO write article about the Earth for the Guide
- The editor in charge is [[bbdb:Ford Prefect]]
DEADLINE: <2004-02-29 Sun>
+ The editor in charge is [[bbdb:Ford Prefect]]
@end example
You can specify a different lead time for warnings for a specific
deadlines using the following syntax. Here is an example with a warning
-period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}.
+period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. This warning is
+deactivated if the task get scheduled and you set
+@code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
@item SCHEDULED
@cindex SCHEDULED keyword
@vindex org-agenda-skip-scheduled-if-done
The headline will be listed under the given date@footnote{It will still
-be listed on that date after it has been marked DONE. If you don't like
+be listed on that date after it has been marked DONE@. If you don't like
this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
addition, a reminder that the scheduled date has passed will be present
-in the compilation for @emph{today}, until the entry is marked DONE.
-I.e. the task will automatically be forwarded until completed.
+in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
+the task will automatically be forwarded until completed.
@example
*** TODO Call Trillian for a date on New Years Eve.
SCHEDULED: <2004-12-25 Sat>
@end example
+@vindex org-scheduled-delay-days
+@vindex org-agenda-skip-scheduled-delay-if-deadline
+If you want to @emph{delay} the display of this task in the agenda, use
+@code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the
+25th but will appear two days later. In case the task contains a repeater,
+the delay is considered to affect all occurrences; if you want the delay to
+only affect the first scheduled occurrence of the task, use @code{--2d}
+instead. See @code{org-scheduled-delay-days} and
+@code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to
+control this globally or per agenda.
+
@noindent
@b{Important:} Scheduling an item in Org mode should @i{not} be
understood in the same way that we understand @i{scheduling a meeting}.
@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling
@subsection Inserting deadlines or schedules
-The following commands allow you to quickly insert a deadline or to schedule
+The following commands allow you to quickly insert@footnote{The @samp{SCHEDULED} and
+@samp{DEADLINE} dates are inserted on the line right below the headline. Don't put
+any text between this line and the headline.} a deadline or to schedule
an item:
@table @kbd
@c
-@kindex C-c C-d
-@item C-c C-d
+@orgcmd{C-c C-d,org-deadline}
Insert @samp{DEADLINE} keyword along with a stamp. The insertion will happen
-in the line directly following the headline. When called with a prefix arg,
-an existing deadline will be removed from the entry. Depending on the
-variable @code{org-log-redeadline}@footnote{with corresponding
+in the line directly following the headline. Any CLOSED timestamp will be
+removed. When called with a prefix arg, an existing deadline will be removed
+from the entry. Depending on the variable @code{org-log-redeadline}@footnote{with corresponding
@code{#+STARTUP} keywords @code{logredeadline}, @code{lognoteredeadline},
and @code{nologredeadline}}, a note will be taken when changing an existing
deadline.
-@c FIXME Any CLOSED timestamp will be removed.????????
-@c
-@kindex C-c C-s
-@item C-c C-s
+
+@orgcmd{C-c C-s,org-schedule}
Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will
happen in the line directly following the headline. Any CLOSED timestamp
will be removed. When called with a prefix argument, remove the scheduling
date from the entry. Depending on the variable
@code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
-keywords @code{logredeadline}, @code{lognoteredeadline}, and
-@code{nologredeadline}}, a note will be taken when changing an existing
+keywords @code{logreschedule}, @code{lognotereschedule}, and
+@code{nologreschedule}}, a note will be taken when changing an existing
scheduling time.
@c
-@kindex C-c C-x C-k
+@orgcmd{C-c C-x C-k,org-mark-entry-for-agenda-action}
@kindex k a
@kindex k s
-@item C-c C-x C-k
Mark the current entry for agenda action. After you have marked the entry
like this, you can open the agenda or the calendar to find an appropriate
date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to
schedule the marked item.
@c
-@kindex C-c / d
+@orgcmd{C-c / d,org-check-deadlines}
@cindex sparse tree, for deadlines
-@item C-c / d
@vindex org-deadline-warning-days
Create a sparse tree with all deadlines that are either past-due, or
which will become due within @code{org-deadline-warning-days}.
prefix, check that many days. For example, @kbd{C-1 C-c / d} shows
all deadlines due tomorrow.
@c
-@kindex C-c / b
-@item C-c / b
+@orgcmd{C-c / b,org-check-before-date}
Sparse tree for deadlines and scheduled items before a given date.
@c
-@kindex C-c / a
-@item C-c / a
+@orgcmd{C-c / a,org-check-after-date}
Sparse tree for deadlines and scheduled items after a given date.
@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
+the date to the next day after today, and --1w will set the date
+to the previous week before any current timestamp.
+
@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling
@subsection Repeated tasks
@cindex tasks, repeated
@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>}.
-
-Deadlines and scheduled items produce entries in the agenda when they
-are over-due, so it is important to be able to mark such an entry as
-completed once you have done so. When you mark a DEADLINE or a SCHEDULE
-with the TODO keyword DONE, it will no longer produce entries in the
-agenda. The problem with this is, however, that then also the
-@emph{next} instance of the repeated entry will not be active. Org mode
-deals with this in the following way: When you try to mark such an entry
-DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating
-timestamp by the repeater interval, and immediately set the entry state
-back to TODO. In the example above, setting the state to DONE would
-actually switch the date like this:
+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
+over-due, so it is important to be able to mark such an entry as completed
+once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO
+keyword DONE, it will no longer produce entries in the agenda. The problem
+with this is, however, that then also the @emph{next} instance of the
+repeated entry will not be active. Org mode deals with this in the following
+way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
+shift the base date of the repeating timestamp by the repeater interval, and
+immediately set the entry state back to TODO@footnote{In fact, the target
+state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
+the variable @code{org-todo-repeat-to-state}. If neither of these is
+specified, the target state defaults to the first state of the TODO state
+sequence.}. In the example above, setting the state to DONE would actually
+switch the date like this:
@example
** TODO Pay the rent
month. So if you have not paid the rent for three months, marking this
entry DONE will still keep it as an overdue deadline. Depending on the
task, this may not be the best way to handle it. For example, if you
-forgot to call you father for 3 weeks, it does not make sense to call
+forgot to call your father for 3 weeks, it does not make sense to call
him 3 times in a single day to make up for it. Finally, there are tasks
like changing batteries which should always repeat a certain time
@i{after} the last time you did it. For these tasks, Org mode has
-special repeaters markers with @samp{++} and @samp{.+}. For example:
+special repeaters @samp{++} and @samp{.+}. For example:
@example
** TODO Call Father
today.
@end example
-You may have both scheduling and deadline information for a specific
-task---just make sure that the repeater intervals on both are the same.
+@vindex org-agenda-skip-scheduled-if-deadline-is-shown
+You may have both scheduling and deadline information for a specific task.
+If the repeater is set for the scheduling information only, you probably want
+the repeater to be ignored after the deadline. If so, set the variable
+@code{org-agenda-skip-scheduled-if-deadline-is-shown} to
+@code{repeated-after-deadline}. If you want both scheduling and deadline
+information to repeat after the same interval, set the same repeater for both
+timestamps.
An alternative to using a repeater is to create a number of copies of a task
subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was
created for this purpose, it is described in @ref{Structure editing}.
-@node Clocking work time, Resolving idle time, Deadlines and scheduling, Dates and Times
+@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times
@section Clocking work time
+@cindex clocking time
+@cindex time clocking
Org mode allows you to clock the time you spend on specific tasks in a
-project. When you start working on an item, you can start the clock.
-When you stop working on that task, or when you mark the task done, the
-clock is stopped and the corresponding time interval is recorded. It
-also computes the total time spent on each subtree of a project. And it
-remembers a history or tasks recently clocked, to that you can jump quickly
-between a number of tasks absorbing your time.
+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
will be found (@pxref{Resolving idle time}) and you will be prompted about
what to do with it.
+@menu
+* Clocking commands:: Starting and stopping a clock
+* The clock table:: Detailed reports
+* Resolving idle time:: Resolving time when you've been idle
+@end menu
+
+@node Clocking commands, The clock table, Clocking work time, Clocking work time
+@subsection Clocking commands
+
@table @kbd
-@kindex C-c C-x C-i
-@item C-c C-x C-i
+@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
this item, the multiple CLOCK lines will be wrapped into a
@code{:LOGBOOK:} drawer (see also the variable
-@code{org-clock-into-drawer}). When called with a @kbd{C-u} prefix argument,
+@code{org-clock-into-drawer}). You can also overrule
+the setting of this variable for a subtree by setting a
+@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
@code{auto} which is the default@footnote{See also the variable
@code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
mode line entry will pop up a menu with clocking options.
-@kindex C-c C-x C-o
-@item C-c C-x C-o
+@c
+@orgcmd{C-c C-x C-o,org-clock-out}
@vindex org-log-note-clock-out
Stop the clock (clock-out). This inserts another timestamp at the same
location where the clock was last started. It also directly computes
possibility to record an additional note together with the clock-out
timestamp@footnote{The corresponding in-buffer setting is:
@code{#+STARTUP: lognoteclock-out}}.
-@kindex C-c C-x C-e
-@item C-c C-x C-e
+@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
@kindex C-c C-c
-@item C-c C-y @ @ @r{or}@ @ C-c C-c
+@orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
Recompute the time interval after changing one of the timestamps. This
is only necessary if you edit the timestamps directly. If you change
them with @kbd{S-@key{cursor}} keys, the update is automatic.
-@kindex C-c C-t
-@item C-c C-t
+@orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
+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.
-@kindex C-c C-x C-x
-@item C-c C-x C-x
+@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.
-@kindex C-c C-x C-j
-@item C-c C-x C-j
-Jump to the entry that contains the currently running clock. With a
-@kbd{C-u} prefix arg, select the target task from a list of recently clocked
-tasks.
-@kindex C-c C-x C-d
-@item C-c C-x C-d
+@orgcmd{C-c C-x C-j,org-clock-goto}
+Jump to the headline of the currently clocked in task. With a @kbd{C-u}
+prefix arg, select the target task from a list of recently clocked tasks.
+@orgcmd{C-c C-x C-d,org-clock-display}
@vindex org-remove-highlights-with-change
-Display time summaries for each subtree in the current buffer. This
-puts overlays at the end of each headline, showing the total time
-recorded under that heading, including the time of any subheadings. You
-can use visibility cycling to study the tree, but the overlays disappear
-when you change the buffer (see variable
-@code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}.
-@kindex C-c C-x C-r
-@item C-c C-x C-r
+Display time summaries for each subtree in the current buffer. This puts
+overlays at the end of each headline, showing the total time recorded under
+that heading, including the time of any subheadings. You can use visibility
+cycling to study the tree, but the overlays disappear when you change the
+buffer (see variable @code{org-remove-highlights-with-change}) or press
+@kbd{C-c C-c}.
+@end table
+
+The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
+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
+@cindex report, of clocked time
+
+Org mode can produce quite complex reports based on the time clocking
+information. Such a report is called a @emph{clock table}, because it is
+formatted as one or several Org tables.
+
+@table @kbd
+@orgcmd{C-c C-x C-r,org-clock-report}
Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
-report as an Org-mode table into the current file. When the cursor is
+report as an Org mode table into the current file. When the cursor is
at an existing clock table, just update it. When called with a prefix
argument, jump to the first clock report in the current document and
-update it.
+update it. The clock table always includes also trees with
+@code{:ARCHIVE:} tag.
+@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
+Update dynamic block at point. The cursor needs to be in the
+@code{#+BEGIN} line of the dynamic block.
+@orgkey{C-u C-c C-x C-u}
+Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
+you have several clock table blocks in a buffer.
+@orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
+Shift the current @code{:block} interval and update the table. The cursor
+needs to be in the @code{#+BEGIN: clocktable} line for this command. If
+@code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
+@end table
+
+
+Here is an example of the frame for a clock table as it is inserted into the
+buffer with the @kbd{C-c C-x C-r} command:
+
@cindex #+BEGIN, clocktable
@example
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
#+END: clocktable
@end example
@noindent
-If such a block already exists at point, its content is replaced by the
-new table. The @samp{BEGIN} line can specify options:
+@vindex org-clocktable-defaults
+The @samp{BEGIN} line and specify a number of options to define the scope,
+structure, and formatting of the report. Defaults for all these options can
+be configured in the variable @code{org-clocktable-defaults}.
+
+@noindent First there are options that determine which clock entries are to
+be selected:
@example
:maxlevel @r{Maximum level depth to which times are listed in the table.}
-:emphasize @r{When @code{t}, emphasize level one and level two items.}
+ @r{Clocks at deeper levels will be summed into the upper level.}
:scope @r{The scope to consider. This can be any of the following:}
nil @r{the current buffer or narrowed region}
file @r{the full current buffer}
2007-12-31 @r{New year eve 2007}
2007-12 @r{December 2007}
2007-W50 @r{ISO-week 50 in 2007}
+ 2007-Q2 @r{2nd quarter in 2007}
2007 @r{the year 2007}
today, yesterday, today-@var{N} @r{a relative day}
thisweek, lastweek, thisweek-@var{N} @r{a relative week}
thisyear, lastyear, thisyear-@var{N} @r{a relative year}
@r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
:tstart @r{A time string specifying when to start considering times.}
+ @r{Relative times like @code{"<-2w>"} can also be used. See}
+ @r{@ref{Matching tags and properties} for relative time syntax.}
:tend @r{A time string specifying when to stop considering times.}
+ @r{Relative times like @code{"<now>"} can also be used. See}
+ @r{@ref{Matching tags and properties} for relative time syntax.}
+:wstart @r{The starting day of the week. The default is 1 for monday.}
+:mstart @r{The starting day of the month. The default 1 is for the first}
+ @r{day of the month.}
:step @r{@code{week} or @code{day}, to split the table into chunks.}
@r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
+:stepskip0 @r{Do not show steps that have zero time.}
+:fileskip0 @r{Do not show table sections from files which did not contribute.}
+:tags @r{A tags match to select entries that should contribute. See}
+ @r{@ref{Matching tags and properties} for the match syntax.}
+@end example
+
+Then there are options which determine the formatting of the table. There
+options are interpreted by the function @code{org-clocktable-write-default},
+but you can specify your own function using the @code{:formatter} parameter.
+@example
+:emphasize @r{When @code{t}, emphasize level one and level two items.}
+:lang @r{Language@footnote{Language terms can be set through the variable @code{org-clock-clocktable-language-setup}.} to use for descriptive cells like "Task".}
:link @r{Link the item headlines in the table to their origins.}
+:narrow @r{An integer to limit the width of the headline column in}
+ @r{the org table. If you write it like @samp{50!}, then the}
+ @r{headline will also be shortened in export.}
+:indent @r{Indent each headline field according to its level.}
+:tcolumns @r{Number of columns to be used for times. If this is smaller}
+ @r{than @code{:maxlevel}, lower levels will be lumped into one column.}
+:level @r{Should a level number column be included?}
+:compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}}
+ @r{All are overwritten except if there is an explicit @code{:narrow}}
+:timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,}
+ @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
+:properties @r{List of properties that should be shown in the table. Each}
+ @r{property will get its own column.}
+:inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.}
:formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
@r{As a special case, @samp{:formula %} adds a column with % time.}
- @r{If you do not specify a formula here, any existing formula.}
+ @r{If you do not specify a formula here, any existing formula}
@r{below the clock table will survive updates and be evaluated.}
-:timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,}
- @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
+:formatter @r{A function to format clock data and insert it into the buffer.}
@end example
To get a clock summary of the current level 1 tree, for the current
day, you could write
:tend "<2006-08-10 Thu 12:00>"
#+END: clocktable
@end example
+A range starting a week ago and ending right now could be written as
+@example
+#+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
+#+END: clocktable
+@end example
A summary of the current subtree with % times would be
@example
#+BEGIN: clocktable :scope subtree :link t :formula %
#+END: clocktable
@end example
-@kindex C-c C-c
-@item C-c C-c
-@kindex C-c C-x C-u
-@itemx C-c C-x C-u
-Update dynamic block at point. The cursor needs to be in the
-@code{#+BEGIN} line of the dynamic block.
-@kindex C-u C-c C-x C-u
-@item C-u C-c C-x C-u
-Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
-you have several clock table blocks in a buffer.
-@kindex S-@key{left}
-@kindex S-@key{right}
-@item S-@key{left}
-@itemx S-@key{right}
-Shift the current @code{:block} interval and update the table. The cursor
-needs to be in the @code{#+BEGIN: clocktable} line for this command. If
-@code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
-@end table
+A horizontally compact representation of everything clocked during last week
+would be
+@example
+#+BEGIN: clocktable :scope agenda :block lastweek :compact t
+#+END: clocktable
+@end example
-The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
-the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
-worked on or closed during a day.
+@node Resolving idle time, , The clock table, Clocking work time
+@subsection Resolving idle time and continuous clocking
-@node Resolving idle time, Effort estimates, Clocking work time, Dates and Times
-@section Resolving idle time
+@subsubheading Resolving idle time
@cindex resolve idle time
+@vindex org-clock-x11idle-program-name
@cindex idle, resolve, dangling
If you clock in on a work item, and then walk away from your
being idle for that many minutes@footnote{On computers using Mac OS X,
idleness is based on actual user idleness, not just Emacs' idle time. For
X11, you can install a utility program @file{x11idle.c}, available in the
-UTILITIES directory of the Org git distribution, to get the same general
-treatment of idleness. On other systems, idle time refers to Emacs idle time
-only.}, and ask what you want to do with the idle time. There will be a
-question waiting for you when you get back, indicating how much idle time has
-passed (constantly updated with the current amount), as well as a set of
-choices to correct the discrepancy:
+@code{contrib/scripts} directory of the Org git distribution, or install the
+@file{xprintidle} package and set it to the variable
+@code{org-clock-x11idle-program-name} if you are running Debian, to get the
+same general treatment of idleness. On other systems, idle time refers to
+Emacs idle time only.}, and ask what you want to do with the idle time.
+There will be a question waiting for you when you get back, indicating how
+much idle time has passed (constantly updated with the current amount), as
+well as a set of choices to correct the discrepancy:
@table @kbd
@item k
leave you clocked out, no matter which option you choose.
@item C
To cancel the clock altogether, use @kbd{C}. Note that if instead of
-cancelling you subtract the away time, and the resulting clock amount is less
-than a minute, the clock will still be cancelled rather than clutter up the
+canceling you subtract the away time, and the resulting clock amount is less
+than a minute, the clock will still be canceled rather than clutter up the
log with an empty entry.
@end table
dangling clock which was never clocked out from your last session. Using
that clock's starting time as the beginning of the unaccounted-for period,
Org will ask how you want to resolve that time. The logic and behavior is
-identical to dealing with away time due to idleness, it's just happening due
+identical to dealing with away time due to idleness; it is just happening due
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}).
-@node Effort estimates, Relative timer, Resolving idle time, Dates and Times
+@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
@cindex effort estimates
for an entry with the following commands:
@table @kbd
-@kindex C-c C-x e
-@item C-c C-x e
+@orgcmd{C-c C-x e,org-set-effort}
Set the effort estimate for the current entry. With a numeric prefix
-argument, set it to the NTH allowed value (see below). This command is also
+argument, set it to the Nth allowed value (see below). This command is also
accessible from the agenda with the @kbd{e} key.
-@kindex C-c C-x C-e
-@item C-c C-x C-e
+@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
Modify the effort estimate of the item currently being clocked.
@end table
buffer you can use
@example
-#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 8:00
+#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM
@end example
these estimates defined consistently, two or three key presses will narrow
down the list to stuff that fits into an available time slot.
-@node Relative timer, , Effort estimates, Dates and Times
+@node Relative timer, Countdown timer, Effort estimates, Dates and Times
@section Taking notes with a relative timer
@cindex relative timer
such a relative timer and make it easy to create timed notes.
@table @kbd
-@kindex C-c C-x .
-@item C-c C-x .
+@orgcmd{C-c C-x .,org-timer}
Insert a relative time into the buffer. The first time you use this, the
timer will be started. When called with a prefix argument, the timer is
restarted.
-@kindex C-c C-x -
-@item C-c C-x -
+@orgcmd{C-c C-x -,org-timer-item}
Insert a description list item with the current relative time. With a prefix
argument, first reset the timer to 0.
-@kindex M-@key{RET}
-@item M-@key{RET}
+@orgcmd{M-@key{RET},org-insert-heading}
Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert
new timer items.
+@c for key sequences with a comma, command name macros fail :(
@kindex C-c C-x ,
@item C-c C-x ,
-Pause the timer, or continue it if it is already paused.
+Pause the timer, or continue it if it is already paused
+(@command{org-timer-pause-or-continue}).
@c removed the sentence because it is redundant to the following item
@kindex C-u C-c C-x ,
@item C-u C-c C-x ,
Stop the timer. After this, you can only start a new timer, not continue the
old one. This command also removes the timer from the mode line.
-@kindex C-c C-x 0
-@item C-c C-x 0
+@orgcmd{C-c C-x 0,org-timer-start}
Reset the timer without inserting anything into the buffer. By default, the
timer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer to
specific starting offset. The user is prompted for the offset, with a
default taken from a timer string at point, if any, So this can be used to
restart taking notes after a break in the process. When called with a double
-prefix argument @kbd{C-c C-u}, change all timer strings in the active region
+prefix argument @kbd{C-u C-u}, change all timer strings in the active region
by a certain amount. This can be used to fix timer strings if the timer was
not started at exactly the right moment.
@end table
+@node Countdown timer, , Relative timer, Dates and Times
+@section Countdown timer
+@cindex Countdown timer
+@kindex C-c C-x ;
+@kindex ;
+
+Calling @code{org-timer-set-timer} from an Org mode buffer runs a countdown
+timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everywhere else.
+
+@code{org-timer-set-timer} prompts the user for a duration and displays a
+countdown timer in the modeline. @code{org-timer-default-timer} sets the
+default countdown value. Giving a prefix numeric argument overrides this
+default value.
+
@node Capture - Refile - Archive, Agenda Views, Dates and Times, Top
@chapter Capture - Refile - Archive
@cindex capture
An important part of any organization system is the ability to quickly
capture new ideas and tasks, and to associate reference material with them.
-Org uses the @file{remember.el} package to create tasks, and stores files
+Org does this using a process called @i{capture}. It also can store files
related to a task (@i{attachments}) in a special directory. Once in the
system, tasks and projects need to be moved around. Moving completed project
trees to an archive file keeps the system compact and fast.
@menu
-* Remember:: Capture new tasks/ideas with little interruption
-* Attachments:: Add files to tasks.
+* Capture:: Capturing new stuff
+* Attachments:: Add files to tasks
* RSS Feeds:: Getting input from RSS feeds
-* Protocols:: External (e.g. Browser) access to Emacs and Org
-* Refiling notes:: Moving a tree from one place to another
+* Protocols:: External (e.g., Browser) access to Emacs and Org
+* Refile and copy:: Moving/copying a tree from one place to another
* Archiving:: What to do with finished projects
@end menu
-@node Remember, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
-@section Remember
-@cindex @file{remember.el}
+@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
+@section Capture
+@cindex capture
-The Remember package by John Wiegley lets you store quick notes with little
-interruption of your work flow. It is an excellent way to add new notes and
-tasks to Org files. The @code{remember.el} package is part of Emacs 23, not
-Emacs 22. See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for
-more information.
+Capture lets you quickly store notes with little interruption of your work
+flow. Org's method for capturing new items is heavily inspired by John
+Wiegley excellent @file{remember.el} package. Up to version 6.36, Org
+used a special setup for @file{remember.el}, then replaced it with
+@file{org-remember.el}. As of version 8.0, @file{org-remember.el} has
+been completely replaced by @file{org-capture.el}.
-Org significantly expands the possibilities of Remember: you may define
-templates for different note types, and associate target files and headlines
-with specific templates. It also allows you to select the location where a
-note should be stored interactively, on the fly.
+If your configuration depends on @file{org-remember.el}, you need to update
+it and use the setup described below. To convert your
+@code{org-remember-templates}, run the command
+@example
+@kbd{M-x org-capture-import-remember-templates RET}
+@end example
+@noindent and then customize the new variable with @kbd{M-x
+customize-variable org-capture-templates}, check the result, and save the
+customization.
@menu
-* Setting up Remember for Org:: Some code for .emacs to get things going
-* Remember templates:: Define the outline of different note types
-* Storing notes:: Directly get the note to where it belongs
+* Setting up capture:: Where notes will be stored
+* Using capture:: Commands to invoke and terminate capture
+* Capture templates:: Define the outline of different note types
@end menu
-@node Setting up Remember for Org, Remember templates, Remember, Remember
-@subsection Setting up Remember for Org
+@node Setting up capture, Using capture, Capture, Capture
+@subsection Setting up capture
-The following customization will tell Remember to use Org files as
-target, and to create annotations compatible with Org links.
+The following customization sets a default target file for notes, and defines
+a global key@footnote{Please select your own key, @kbd{C-c c} is only a
+suggestion.} for capturing new material.
-@example
-(org-remember-insinuate)
-(setq org-directory "~/path/to/my/orgfiles/")
+@vindex org-default-notes-file
+@smalllisp
+@group
(setq org-default-notes-file (concat org-directory "/notes.org"))
-(define-key global-map "\C-cr" 'org-remember)
-@end example
+(define-key global-map "\C-cc" 'org-capture)
+@end group
+@end smalllisp
-@noindent
-The last line binds the command @code{org-remember} to a global
-key@footnote{Please select your own key, @kbd{C-c r} is only a
-suggestion.}. @code{org-remember} basically just calls Remember,
-but it makes a few things easier: if there is an active region, it will
-automatically copy the region into the Remember buffer. It also allows
-to jump to the buffer and location where Remember notes are being
-stored: just call @code{org-remember} with a prefix argument. If you
-use two prefix arguments, Org jumps to the location where the last
-remember note was stored.
-
-The Remember buffer will actually use @code{org-mode} as its major mode, so
-that all editing features of Org mode are available. In addition to this, a
-minor mode @code{org-remember-mode} is turned on, for the single purpose that
-you can use its keymap @code{org-remember-mode-map} to overwrite some of
-Org mode's key bindings.
-
-You can also call @code{org-remember} in a special way from the agenda,
-using the @kbd{k r} key combination. With this access, any timestamps
-inserted by the selected Remember template (see below) will default to
-the cursor date in the agenda, rather than to the current date.
-
-@node Remember templates, Storing notes, Setting up Remember for Org, Remember
-@subsection Remember templates
-@cindex templates, for Remember
-
-In combination with Org, you can use templates to generate
-different types of Remember notes. For example, if you would like
-to use one template to create general TODO entries, another one for
-journal entries, and a third one for collecting random ideas, you could
-use:
-
-@example
-(setq org-remember-templates
- '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks")
- ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
- ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
-@end example
-
-@vindex org-remember-default-headline
-@vindex org-directory
-@noindent In these entries, the first string is just a name, and the
-character specifies how to select the template. It is useful if the
-character is also the first letter of the name. The next string specifies
-the template. Two more (optional) strings give the file in which, and the
-headline under which, the new note should be stored. The file (if not
-present or @code{nil}) defaults to @code{org-default-notes-file}, the heading
-to @code{org-remember-default-headline}. If the file name is not an absolute
-path, it will be interpreted relative to @code{org-directory}.
-
-The heading can also be the symbols @code{top} or @code{bottom} to send notes
-as level 1 entries to the beginning or end of the file, respectively. It may
-also be the symbol @code{date-tree}. Then, a tree with year on level 1,
-month on level 2 and day on level three will be build in the file, and the
-entry will be filed into the tree under the current date@footnote{If the file
-contains an entry with a @code{DATE_TREE} property, the entire date tree will
-be build under that entry.}
-
-An optional sixth element specifies the contexts in which the user can select
-the template. This element can be a list of major modes or a function.
-@code{org-remember} will first check whether the function returns @code{t} or
-if we are in any of the listed major modes, and exclude templates for which
-this condition is not fulfilled. Templates that do not specify this element
-at all, or that use @code{nil} or @code{t} as a value will always be
-selectable.
-
-So for example:
-
-@example
-(setq org-remember-templates
- '(("Bug" ?b "* BUG %?\n %i\n %a" "~/org/BUGS.org" "Bugs" (emacs-lisp-mode))
- ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org" "X" my-check)
- ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
-@end example
+@node Using capture, Capture templates, Setting up capture, Capture
+@subsection Using capture
-@noindent
-The first template will only be available when invoking @code{org-remember}
-from an buffer in @code{emacs-lisp-mode}. The second template will only be
-available when the function @code{my-check} returns @code{t}. The third
-template will be proposed in any context.
+@table @kbd
+@orgcmd{C-c c,org-capture}
+Call the command @code{org-capture}. Note that this keybinding is global and
+not active by default: you need to install it. If you have templates
+@cindex date tree
+defined @pxref{Capture templates}, it will offer these templates for
+selection or use a new Org outline node as the default template. It will
+insert the template into the target file and switch to an indirect buffer
+narrowed to this new node. You may then insert the information you want.
+
+@orgcmd{C-c C-c,org-capture-finalize}
+Once you have finished entering information into the capture buffer, @kbd{C-c
+C-c} will return you to the window configuration before the capture process,
+so that you can resume your work without further distraction. When called
+with a prefix arg, finalize and then jump to the captured item.
+
+@orgcmd{C-c C-w,org-capture-refile}
+Finalize the capture process by refiling (@pxref{Refile and copy}) the note to
+a different place. Please realize that this is a normal refiling command
+that will be executed---so the cursor position at the moment you run this
+command is important. If you have inserted a tree with a parent and
+children, first move the cursor back to the parent. Any prefix argument
+given to this command will be passed on to the @code{org-refile} command.
+
+@orgcmd{C-c C-k,org-capture-kill}
+Abort the capture process and return to the previous state.
+
+@end table
+
+You can also call @code{org-capture} in a special way from the agenda, using
+the @kbd{k c} key combination. With this access, any timestamps inserted by
+the selected capture template will default to the cursor date in the agenda,
+rather than to the current date.
+
+To find the locations of the last stored capture, use @code{org-capture} with
+prefix commands:
+
+@table @kbd
+@orgkey{C-u C-c c}
+Visit the target location of a capture template. You get to select the
+template in the usual way.
+@orgkey{C-u C-u C-c c}
+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
+
+You can use templates for different types of capture items, and
+for different target locations. The easiest way to create such templates is
+through the customize interface.
+
+@table @kbd
+@orgkey{C-c c C}
+Customize the variable @code{org-capture-templates}.
+@end table
+
+Before we give the formal description of template definitions, let's look at
+an example. Say you would like to use one template to create general TODO
+entries, and you want to put these entries under the heading @samp{Tasks} in
+your file @file{~/org/gtd.org}. Also, a date tree in the file
+@file{journal.org} should capture journal entries. A possible configuration
+would look like:
+
+@smalllisp
+@group
+(setq org-capture-templates
+ '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
+ "* TODO %?\n %i\n %a")
+ ("j" "Journal" entry (file+datetree "~/org/journal.org")
+ "* %?\nEntered on %U\n %i\n %a")))
+@end group
+@end smalllisp
-When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember
-something, Org will prompt for a key to select the template (if you have
-more than one template) and then prepare the buffer like
+@noindent If you then press @kbd{C-c c t}, Org will prepare the template
+for you like this:
@example
* TODO
- [[file:@var{link to where you called remember}]]
+ [[file:@var{link to where you initiated capture}]]
@end example
@noindent
-During expansion of the template, special @kbd{%}-escapes@footnote{If you
-need one of these sequences literally, escape the @kbd{%} with a backslash.}
-allow dynamic insertion of content:
-@example
-%^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
- @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.}
-%a @r{annotation, normally the link created with @code{org-store-link}}
-%A @r{like @code{%a}, but prompt for the description part}
-%i @r{initial content, the region when remember is called with C-u.}
+During expansion of the template, @code{%a} has been replaced by a link to
+the location from where you called the capture command. This can be
+extremely useful for deriving tasks from emails, for example. You fill in
+the task definition, press @kbd{C-c C-c} and Org returns you to the same
+place where you started the capture process.
+
+To define special keys to capture to a particular template without going
+through the interactive template selection, you can create your key binding
+like this:
+
+@lisp
+(define-key global-map "\C-cx"
+ (lambda () (interactive) (org-capture nil "x")))
+@end lisp
+
+@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
+@subsubsection Template elements
+
+Now lets look at the elements of a template definition. Each entry in
+@code{org-capture-templates} is a list with the following items:
+
+@table @var
+@item keys
+The keys that will select the template, as a string, characters
+only, for example @code{"a"} for a template to be selected with a
+single key, or @code{"bt"} for selection with two keys. When using
+several keys, keys using the same prefix key must be sequential
+in the list and preceded by a 2-element entry explaining the
+prefix key, for example
+@smalllisp
+ ("b" "Templates for marking stuff to buy")
+@end smalllisp
+@noindent If you do not define a template for the @kbd{C} key, this key will
+be used to open the customize buffer for this complex variable.
+
+@item description
+A short string describing the template, which will be shown during
+selection.
+
+@item type
+The type of entry, a symbol. Valid values are:
+
+@table @code
+@item entry
+An Org mode node, with a headline. Will be filed as the child of the target
+entry or as a top-level entry. The target file should be an Org mode file.
+@item item
+A plain list item, placed in the first plain list at the target
+location. Again the target file should be an Org file.
+@item checkitem
+A checkbox item. This only differs from the plain list item by the
+default template.
+@item table-line
+a new line in the first table at the target location. Where exactly the
+line will be inserted depends on the properties @code{:prepend} and
+@code{:table-line-pos} (see below).
+@item plain
+Text to be inserted as it is.
+@end table
+
+@item target
+@vindex org-default-notes-file
+Specification of where the captured item should be placed. In Org mode
+files, targets usually define a node. Entries will become children of this
+node. Other types will be added to the table or list in the body of this
+node. Most target specifications contain a file name. If that file name is
+the empty string, it defaults to @code{org-default-notes-file}. A file can
+also be given as a variable, function, or Emacs Lisp form.
+
+Valid values are:
+
+@table @code
+@item (file "path/to/file")
+Text will be placed at the beginning or end of that file.
+
+@item (id "id of existing org entry")
+Filing as child of this entry, or in the body of the entry.
+
+@item (file+headline "path/to/file" "node headline")
+Fast configuration if the target heading is unique in the file.
+
+@item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
+For non-unique headings, the full path is safer.
+
+@item (file+regexp "path/to/file" "regexp to find location")
+Use a regular expression to position the cursor.
+
+@item (file+datetree "path/to/file")
+Will create a heading in a date tree for today's date@footnote{Datetree
+headlines for years accept tags, so if you use both @code{* 2013 :noexport:}
+and @code{* 2013} in your file, the capture will refile the note to the first
+one matched.}.
+
+@item (file+datetree+prompt "path/to/file")
+Will create a heading in a date tree, but will prompt for the date.
+
+@item (file+function "path/to/file" function-finding-location)
+A function to find the right location in the file.
+
+@item (clock)
+File to the entry that is currently being clocked.
+
+@item (function function-finding-location)
+Most general way, write your own function to find both
+file and location.
+@end table
+
+@item template
+The template for creating the capture item. If you leave this empty, an
+appropriate default template will be used. Otherwise this is a string with
+escape codes, which will be replaced depending on time and context of the
+capture call. The string with escapes may be loaded from a template file,
+using the special syntax @code{(file "path/to/template")}. See below for
+more details.
+
+@item properties
+The rest of the entry is a property list of additional options.
+Recognized properties are:
+
+@table @code
+@item :prepend
+Normally new captured information will be appended at
+the target location (last child, last table line, last list item...).
+Setting this property will change that.
+
+@item :immediate-finish
+When set, do not offer to edit the information, just
+file it away immediately. This makes sense if the template only needs
+information that can be added automatically.
+
+@item :empty-lines
+Set this to the number of lines to insert
+before and after the new item. Default 0, only common other value is 1.
+
+@item :clock-in
+Start the clock in this item.
+
+@item :clock-keep
+Keep the clock running when filing the captured entry.
+
+@item :clock-resume
+If starting the capture interrupted a clock, restart that clock when finished
+with the capture. Note that @code{:clock-keep} has precedence over
+@code{:clock-resume}. When setting both to @code{t}, the current clock will
+run and the previous one will not be resumed.
+
+@item :unnarrowed
+Do not narrow the target buffer, simply show the full buffer. Default is to
+narrow it so that you only see the new material.
+
+@item :table-line-pos
+Specification of the location in the table where the new line should be
+inserted. It should be a string like @code{"II-3"} meaning that the new
+line should become the third line before the second horizontal separator
+line.
+
+@item :kill-buffer
+If the target file was not yet visited when capture was invoked, kill the
+buffer again after capture is completed.
+@end table
+@end table
+
+@node Template expansion, Templates in contexts, Template elements, Capture templates
+@subsubsection Template expansion
+
+In the template itself, special @kbd{%}-escapes@footnote{If you need one of
+these sequences literally, escape the @kbd{%} with a backslash.} allow
+dynamic insertion of content. The templates are expanded in the order given here:
+
+@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{For convenience, %:keyword (see below) placeholders}
+ @r{within the expression will be expanded prior to this.}
+ @r{The sexp must return a string.}
+%<...> @r{The result of format-time-string on the ... format specification.}
+%t @r{Timestamp, date only.}
+%T @r{Timestamp, with date and time.}
+%u, %U @r{Like the above, but inactive timestamps.}
+%i @r{Initial content, the region when capture is called while the}
+ @r{region is active.}
@r{The entire text will be indented like @code{%i} itself.}
-%t @r{timestamp, date only}
-%T @r{timestamp with date and time}
-%u, %U @r{like the above, but inactive timestamps}
-%^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}}
-%n @r{user name (taken from @code{user-full-name})}
+%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}.}
+ @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.}
-%^g @r{prompt for tags, with completion on tags in target file.}
-%k @r{title of currently clocked task}
-%K @r{link to currently clocked task}
-%^G @r{prompt for tags, with completion all tags in all agenda files.}
-%^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}}
-%:keyword @r{specific information for certain link types, see below}
-%[@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{immediately store note after completing the template}
- @r{(skipping the @kbd{C-c C-c} that normally triggers storing)}
-%& @r{jump to target location immediately after storing note}
-@end example
+%^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}.}
+%^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
+ @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
For specific link types, the following keywords will be
defined@footnote{If you define your own link types (@pxref{Adding
hyperlink types}), any property you store with
-@code{org-store-link-props} can be accessed in remember templates in a
+@code{org-store-link-props} can be accessed in capture templates in a
similar way.}:
@vindex org-from-is-user-regexp
-@example
-Link type | Available keywords
--------------------+----------------------------------------------
-bbdb | %:name %:company
-bbdb | %::server %:port %:nick
-vm, wl, mh, rmail | %:type %:subject %:message-id
- | %:from %:fromname %:fromaddress
- | %:to %:toname %:toaddress
- | %: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 example
+@smallexample
+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
To place the cursor after template expansion use:
-@example
+@smallexample
%? @r{After completing the template, position cursor here.}
-@end example
+@end smallexample
-@noindent
-If you change your mind about which template to use, call
-@code{org-remember} in the remember buffer. You may then select a new
-template that will be filled with the previous context information.
-
-@node Storing notes, , Remember templates, Remember
-@subsection Storing notes
-
-@vindex org-remember-clock-out-on-exit
-When you are finished preparing a note with Remember, you have to press
-@kbd{C-c C-c} to file the note away. If you have started the clock in the
-Remember buffer, you will first be asked if you want to clock out
-now@footnote{To avoid this query, configure the variable
-@code{org-remember-clock-out-on-exit}.}. If you answer @kbd{n}, the clock
-will continue to run after the note was filed away.
-
-The handler will then store the note in the file and under the headline
-specified in the template, or it will use the default file and headline.
-The window configuration will be restored, sending you back to the working
-context before the call to Remember. To re-use the location found
-during the last call to Remember, exit the Remember buffer with
-@kbd{C-0 C-c C-c}, i.e. specify a zero prefix argument to @kbd{C-c C-c}.
-Another special case is @kbd{C-2 C-c C-c} which files the note as a child of
-the currently clocked item.
-
-@vindex org-remember-store-without-prompt
-If you want to store the note directly to a different place, use
-@kbd{C-1 C-c C-c} instead to exit Remember@footnote{Configure the
-variable @code{org-remember-store-without-prompt} to make this behavior
-the default.}. The handler will then first prompt for a target file---if
-you press @key{RET}, the value specified for the template is used.
-Then the command offers the headings tree of the selected file, with the
-cursor position at the default headline (if you specified one in the
-template). You can either immediately press @key{RET} to get the note
-placed there. Or you can use the following keys to find a different
-location:
-@example
-@key{TAB} @r{Cycle visibility.}
-@key{down} / @key{up} @r{Next/previous visible headline.}
-n / p @r{Next/previous visible headline.}
-f / b @r{Next/previous headline same level.}
-u @r{One level up.}
-@c 0-9 @r{Digit argument.}
-@end example
-@noindent
-Pressing @key{RET} or @key{left} or @key{right}
-then leads to the following result.
+@node Templates in contexts, , Template expansion, Capture templates
+@subsubsection Templates in contexts
-@vindex org-reverse-note-order
-@multitable @columnfractions 0.2 0.15 0.65
-@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
-@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor, first or last
-@item @tab @tab depending on @code{org-reverse-note-order}.
-@item @tab @key{left}/@key{right} @tab as same level, before/after current heading
-@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file or level 1 at beginning
-@item @tab @tab depending on @code{org-reverse-note-order}.
-@item not on headline @tab @key{RET}
- @tab at cursor position, level taken from context.
-@end multitable
+@vindex org-capture-templates-contexts
+To control whether a capture template should be accessible from a specific
+context, you can customize @code{org-capture-templates-contexts}. Let's say
+for example that you have a capture template @code{"p"} for storing Gnus
+emails containing patches. Then you would configure this option like this:
+
+@smalllisp
+(setq org-capture-templates-contexts
+ '(("p" (in-mode . "message-mode"))))
+@end smalllisp
-Before inserting the text into a tree, the function ensures that the text has
-a headline, i.e. a first line that starts with a @samp{*}. If not, a
-headline is constructed from the current date. If you have indented the text
-of the note below the headline, the indentation will be adapted if inserting
-the note into the tree requires demotion from level 1.
+You can also tell that the command key @code{"p"} should refer to another
+template. In that case, add this command key like this:
+@smalllisp
+(setq org-capture-templates-contexts
+ '(("p" "q" (in-mode . "message-mode"))))
+@end smalllisp
-@node Attachments, RSS Feeds, Remember, Capture - Refile - Archive
+See the docstring of the variable for more information.
+
+@node Attachments, RSS Feeds, Capture, Capture - Refile - Archive
@section Attachments
@cindex attachments
@vindex org-attach-directory
It is often useful to associate reference material with an outline node/task.
Small chunks of plain text can simply be stored in the subtree of a project.
-Hyperlinks (@pxref{Hyperlinks}) can be used to establish associations with
+Hyperlinks (@pxref{Hyperlinks}) can establish associations with
files that live elsewhere on your computer or in the cloud, like emails or
source code files belonging to a project. Another method is @i{attachments},
which are files located in a directory belonging to an outline node. Org
directory from a parent, so that an entire subtree uses the same attached
directory.
-@noindent The following commands deal with attachments.
+@noindent The following commands deal with attachments:
@table @kbd
-
-@kindex C-c C-a
-@item C-c C-a
+@orgcmd{C-c C-a,org-attach}
The dispatcher for commands related to the attachment system. After these
-keys, a list of commands is displayed and you need to press an additional key
+keys, a list of commands is displayed and you must press an additional key
to select a command:
@table @kbd
-@kindex C-c C-a a
-@item a
+@orgcmdtkc{a,C-c C-a a,org-attach-attach}
@vindex org-attach-method
Select a file and move it into the task's attachment directory. The file
will be copied, moved, or linked, depending on @code{org-attach-method}.
Attach a file using the copy/move/link method.
Note that hard links are not supported on all systems.
-@kindex C-c C-a n
-@item n
+@orgcmdtkc{n,C-c C-a n,org-attach-new}
Create a new attachment as an Emacs buffer.
-@kindex C-c C-a z
-@item z
+@orgcmdtkc{z,C-c C-a z,org-attach-sync}
Synchronize the current task with its attachment directory, in case you added
attachments yourself.
-@kindex C-c C-a o
-@item o
+@orgcmdtkc{o,C-c C-a o,org-attach-open}
@vindex org-file-apps
-Open current task's attachment. If there are more than one, prompt for a
+Open current task's attachment. If there is more than one, prompt for a
file name first. Opening will follow the rules set by @code{org-file-apps}.
For more details, see the information on following hyperlinks
(@pxref{Handling links}).
-@kindex C-c C-a O
-@item O
+@orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
Also open the attachment, but force opening the file in Emacs.
-@kindex C-c C-a f
-@item f
+@orgcmdtkc{f,C-c C-a f,org-attach-reveal}
Open the current task's attachment directory.
-@kindex C-c C-a F
-@item F
+@orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
Also open the directory, but force using @command{dired} in Emacs.
-@kindex C-c C-a d
-@item d
+@orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
Select and delete a single attachment.
-@kindex C-c C-a D
-@item D
+@orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
Delete all of a task's attachments. A safer way is to open the directory in
@command{dired} and delete from there.
-@kindex C-c C-a s
-@item C-c C-a s
+@orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
@cindex property, ATTACH_DIR
Set a specific directory as the entry's attachment directory. This works by
putting the directory path into the @code{ATTACH_DIR} property.
-@kindex C-c C-a i
-@item C-c C-a i
+@orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
@cindex property, ATTACH_DIR_INHERIT
Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
same directory for attachments as the parent does.
@node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive
@section RSS feeds
@cindex RSS feeds
+@cindex Atom feeds
-Org has the capability to add and change entries based on information found in
-RSS feeds. You could use this to make a task out of each new podcast in a
+Org can add and change entries based on information found in RSS feeds and
+Atom feeds. You could use this to make a task out of each new podcast in a
podcast feed. Or you could use a phone-based note-creating service on the
-web to import tasks into Org. To access feeds, you need to configure the
-variable @code{org-feed-alist}. The docstring of this variable has detailed
+web to import tasks into Org. To access feeds, configure the variable
+@code{org-feed-alist}. The docstring of this variable has detailed
information. Here is just an example:
-@example
+@smalllisp
+@group
(setq org-feed-alist
- '(("ReQall" "http://www.reqall.com/user/feeds/rss/a1b2c3....."
- "~/org/feeds.org" "ReQall Entries")
-@end example
+ '(("Slashdot"
+ "http://rss.slashdot.org/Slashdot/slashdot"
+ "~/txt/org/feeds.org" "Slashdot Entries")))
+@end group
+@end smalllisp
+
@noindent
-will configure that new items from the feed provided by @file{reqall.com}
-will result in new entries in the file @file{~/org/feeds.org} under the
-heading @samp{ReQall Entries}, whenever the following command is used:
+will configure that new items from the feed provided by
+@code{rss.slashdot.org} will result in new entries in the file
+@file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
+the following command is used:
@table @kbd
-@kindex C-c C-x g
+@orgcmd{C-c C-x g,org-feed-update-all}
@item C-c C-x g
Collect items from the feeds configured in @code{org-feed-alist} and act upon
them.
-@kindex C-c C-x G
-@item C-c C-x G
+@orgcmd{C-c C-x G,org-feed-goto-inbox}
Prompt for a feed name and go to the inbox configured for this feed.
@end table
#+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS
@end example
-For more information, see @file{org-feed.el} and the docstring of
-@code{org-feed-alist}.
+For more information, including how to read atom feeds, see
+@file{org-feed.el} and the docstring of @code{org-feed-alist}.
-@node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive
+@node Protocols, Refile and copy, RSS Feeds, Capture - Refile - Archive
@section Protocols for external access
@cindex protocols, for external access
@cindex emacsserver
You can set up Org for handling protocol calls from outside applications that
are passed to Emacs through the @file{emacsserver}. For example, you can
configure bookmarks in your web browser to send a link to the current page to
-Org and create a note from it using Remember (@pxref{Remember}). Or you
+Org and create a note from it using capture (@pxref{Capture}). Or you
could create a bookmark that will tell Emacs to open the local source file of
a remote website you are looking at with the browser. See
@uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed
documentation and setup instructions.
-@node Refiling notes, Archiving, Protocols, Capture - Refile - Archive
-@section Refiling notes
+@node Refile and copy, Archiving, Protocols, Capture - Refile - Archive
+@section Refile and copy
@cindex refiling notes
+@cindex copying notes
-When reviewing the captured data, you may want to refile some of the entries
-into a different list, for example into a project. Cutting, finding the
-right location, and then pasting the note is cumbersome. To simplify this
-process, you can use the following special command:
+When reviewing the captured data, you may want to refile or to copy some of
+the entries into a different list, for example into a project. Cutting,
+finding the right location, and then pasting the note is cumbersome. To
+simplify this process, you can use the following special command:
@table @kbd
-@kindex C-c C-w
-@item C-c C-w
+@orgcmd{C-c M-w,org-copy}
+@findex org-copy
+Copying works like refiling, except that the original note is not deleted.
+@orgcmd{C-c C-w,org-refile}
+@findex org-refile
@vindex org-reverse-note-order
@vindex org-refile-targets
@vindex org-refile-use-outline-path
@vindex org-outline-path-complete-in-steps
@vindex org-refile-allow-creating-parent-nodes
+@vindex org-log-refile
+@vindex org-refile-use-cache
+@vindex org-refile-keep
Refile the entry or region at point. This command offers possible locations
for refiling the entry and lets you select one with completion. The item (or
all items in the region) is filed below the target heading as a subitem.
@code{org-outline-path-complete-in-steps}. If you would like to be able to
create new nodes as new parents for refiling on the fly, check the
variable @code{org-refile-allow-creating-parent-nodes}.
-@kindex C-u C-c C-w
-@item C-u C-c C-w
+When the variable @code{org-log-refile}@footnote{with corresponding
+@code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
+and @code{nologrefile}} is set, a timestamp or a note will be
+recorded when an entry has been refiled.
+@orgkey{C-u C-c C-w}
Use the refile interface to jump to a heading.
-@kindex C-u C-u C-c C-w
-@item C-u C-u C-c C-w
+@orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
Jump to the location where @code{org-refile} last moved a tree to.
@item C-2 C-c C-w
Refile as the child of the item currently being clocked.
+@item C-3 C-c C-w
+Refile and keep the entry in place. Also see @code{org-refile-keep} to make
+this the default behavior, and beware that this may result in duplicated
+@code{ID} properties.
+@orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear}
+Clear the target cache. Caching of refile targets can be turned on by
+setting @code{org-refile-use-cache}. To make the command see new possible
+targets, you have to clear the cache with this command.
@end table
-@node Archiving, , Refiling notes, Capture - Refile - Archive
+@node Archiving, , Refile and copy, Capture - Refile - Archive
@section Archiving
@cindex archiving
searches like the construction of agenda views fast.
@table @kbd
-@kindex C-c C-x C-a
-@item C-c C-x C-a
+@orgcmd{C-c C-x C-a,org-archive-subtree-default}
@vindex org-archive-default-command
Archive the current entry using the command specified in the variable
@code{org-archive-default-command}.
@menu
* Moving subtrees:: Moving a tree to an archive file
-* Internal archiving:: Switch off a tree but keep i in the file
+* Internal archiving:: Switch off a tree but keep it in the file
@end menu
@node Moving subtrees, Internal archiving, Archiving, Archiving
the archive file.
@table @kbd
-@kindex C-c $
-@kindex C-c C-x C-s
-@item C-c C-x C-s@ @r{or short} @ C-c $
+@orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
@vindex org-archive-location
Archive the subtree starting at the cursor position to the location
given by @code{org-archive-location}.
-@kindex C-u C-c C-x C-s
-@item C-u C-c C-x C-s
+@orgkey{C-u C-c C-x C-s}
Check if any direct children of the current headline could be moved to
the archive. To do this, each subtree is checked for open TODO entries.
If none are found, the command offers to move it to the archive
@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
is. Configure the details using the variable
@code{org-export-with-archived-trees}.
@item
-@vindex org-columns-skip-arrchived-trees
+@vindex org-columns-skip-archived-trees
Archived trees are excluded from column view unless the variable
-@code{org-columns-skip-arrchived-trees} is configured to @code{nil}.
+@code{org-columns-skip-archived-trees} is configured to @code{nil}.
@end itemize
-The following commands help managing the ARCHIVE tag:
+The following commands help manage the ARCHIVE tag:
@table @kbd
-@kindex C-c C-x a
-@item C-c C-x a
+@orgcmd{C-c C-x a,org-toggle-archive-tag}
Toggle the ARCHIVE tag for the current headline. When the tag is set,
the headline changes to a shadowed face, and the subtree below it is
hidden.
-@kindex C-u C-c C-x a
-@item C-u C-c C-x a
+@orgkey{C-u C-c C-x a}
Check if any direct children of the current headline should be archived.
To do this, each subtree is checked for open TODO entries. If none are
found, the command offers to set the ARCHIVE tag for the child. If the
cursor is @emph{not} on a headline when this command is invoked, the
level 1 trees will be checked.
-@kindex C-@kbd{TAB}
-@item C-@kbd{TAB}
+@orgcmd{C-@kbd{TAB},org-force-cycle-archived}
Cycle a tree even if it is tagged with ARCHIVE.
-@kindex C-c C-x A
-@item C-c C-x A
+@orgcmd{C-c C-x A,org-archive-to-archive-sibling}
Move the current entry to the @emph{Archive Sibling}. This is a sibling of
the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The
entry becomes a child of that sibling and in this way retains a lot of its
@node Agenda Views, Markup, Capture - Refile - Archive, Top
-@chapter Agenda Views
+@chapter Agenda views
@cindex agenda views
Due to the way Org works, TODO items, time-stamped items, and
files}, the files listed in the variable
@code{org-agenda-files}@footnote{If the value of that variable is not a
list, but a single file name, then the list of agenda files will be
-maintained in that external file.}. If a directory is part of this list,
+maintained in that external file.}. If a directory is part of this list,
all files with the extension @file{.org} in this directory will be part
of the list.
@cindex files, adding to agenda list
@table @kbd
-@kindex C-c [
-@item C-c [
+@orgcmd{C-c [,org-agenda-file-to-front}
Add current file to the list of agenda files. The file is added to
the front of the list. If it was already in the list, it is moved to
the front. With a prefix argument, file is added/moved to the end.
-@kindex C-c ]
-@item C-c ]
+@orgcmd{C-c ],org-remove-file}
Remove current file from the list of agenda files.
@kindex C-,
-@kindex C-'
-@item C-,
-@itemx C-'
+@cindex cycling, of agenda files
+@orgcmd{C-',org-cycle-agenda-files}
+@itemx C-,
Cycle through agenda file list, visiting one file after the other.
@kindex M-x org-iswitchb
-@item M-x org-iswitchb
+@item M-x org-iswitchb RET
Command to use an @code{iswitchb}-like interface to switch to and between Org
buffers.
@end table
extended period, use the following commands:
@table @kbd
-@kindex C-c C-x <
-@item C-c C-x <
+@orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
Permanently restrict the agenda to the current subtree. When with a
prefix argument, or with the cursor before the first headline in a file,
the agenda scope is set to the entire file. This restriction remains in
effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
or @kbd{>} in the agenda dispatcher. If there is a window displaying an
agenda view, the new restriction takes effect immediately.
-@kindex C-c C-x >
-@item C-c C-x >
+@orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
Remove the permanent restriction created by @kbd{C-c C-x <}.
@end table
@noindent
When working with @file{speedbar.el}, you can use the following commands in
the Speedbar frame:
+
@table @kbd
-@kindex <
-@item < @r{in the speedbar frame}
+@orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
Permanently restrict the agenda to the item---either an Org file or a subtree
in such a file---at the cursor in the Speedbar frame.
If there is a window displaying an agenda view, the new restriction takes
effect immediately.
-@kindex >
-@item > @r{in the speedbar frame}
+@orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
Lift the restriction.
@end table
@cindex agenda dispatcher
@cindex dispatching agenda commands
The views are created through a dispatcher, which should be bound to a
-global key---for example @kbd{C-c a} (@pxref{Installation}). In the
+global key---for example @kbd{C-c a} (@pxref{Activation}). In the
following we will assume that @kbd{C-c a} is indeed how the dispatcher
is accessed and list keyboard access to commands accordingly. After
pressing @kbd{C-c a}, an additional letter is required to execute a
command. The dispatcher offers the following default commands:
+
@table @kbd
@item a
Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
backward compatibility, you can also press @kbd{0} to restrict to the
current region/subtree.}. After pressing @kbd{< <}, you still need to press the
character selecting the command.
+
+@item *
+@vindex org-agenda-sticky
+Toggle sticky agenda views. By default, Org maintains only a single agenda
+buffer and rebuilds it each time you change the view, to make sure everything
+is always up to date. If you switch between views often and the build time
+bothers you, you can turn on sticky agenda buffers (make this the default by
+customizing the variable @code{org-agenda-sticky}). With sticky agendas, the
+dispatcher only switches to the selected view, you need to update it by hand
+with @kbd{r} or @kbd{g}. You can toggle sticky agenda view any time with
+@code{org-toggle-sticky-agenda}.
@end table
You can also define custom commands that will be accessible through the
@table @kbd
@cindex org-agenda, command
-@kindex C-c a a
-@item C-c a a
-@vindex org-agenda-ndays
+@orgcmd{C-c a a,org-agenda-list}
Compile an agenda for the current week from a list of Org files. The agenda
shows the entries for each day. With a numeric prefix@footnote{For backward
compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
listed before the agenda. This feature is deprecated, use the dedicated TODO
list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1
-C-c a a}) you may set the number of days to be displayed (see also the
-variable @code{org-agenda-ndays})
+C-c a a}) you may set the number of days to be displayed.
@end table
+@vindex org-agenda-span
+@vindex org-agenda-ndays
+@vindex org-agenda-start-day
+@vindex org-agenda-start-on-weekday
+The default number of days displayed in the agenda is set by the variable
+@code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This
+variable can be set to any number of days you want to see by default in the
+agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or
+@code{year}. For weekly agendas, the default is to start on the previous
+monday (see @code{org-agenda-start-on-weekday}). You can also set the start
+date using a date shift: @code{(setq org-agenda-start-day "+10d")} will
+start the agenda ten days from today in the future.
+
Remote editing from the agenda buffer means, for example, that you can
change the dates of deadlines and appointments from the agenda buffer.
The commands available in the Agenda buffer are listed in @ref{Agenda
If you are using the diary only for sexp entries and holidays, it is
faster to not use the above setting, but instead to copy or even move
-the entries into an Org file. Org mode evaluates diary-style sexp
+the entries into an Org file. Org mode evaluates diary-style sexp
entries, and does it faster because there is no overhead for first
creating the diary display. Note that the sexp entries must start at
the left margin, no whitespace is allowed before them. For example,
#+CATEGORY: Holiday
%%(org-calendar-holiday) ; special function for holiday names
#+CATEGORY: Ann
-%%(diary-anniversary 14 5 1956) Arthur Dent is %d years old
-%%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old
+%%(org-anniversary 1956 5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is always according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old
+%%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
@end example
@subsubheading Anniversaries from BBDB
very likely prefer to store anniversaries in BBDB rather than in a
separate Org or diary file. Org supports this and will show BBDB
anniversaries as part of the agenda. All you need to do is to add the
-following to one your your agenda files:
+following to one of your agenda files:
@example
* Anniversaries
:PROPERTIES:
:CATEGORY: Anniv
- :END
+ :END:
%%(org-bbdb-anniversaries)
@end example
You can then go ahead and define anniversaries for a BBDB record. Basically,
you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
-record and then add the date in the format @code{YYYY-MM-DD}, followed by a
-space and the class of the anniversary (@samp{birthday} or @samp{wedding}, or
-a format string). If you omit the class, it will default to @samp{birthday}.
-Here are a few examples, the header for the file @file{org-bbdb.el} contains
-more detailed information.
+record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
+followed by a space and the class of the anniversary (@samp{birthday} or
+@samp{wedding}, or a format string). If you omit the class, it will default to
+@samp{birthday}. Here are a few examples, the header for the file
+@file{org-bbdb.el} contains more detailed information.
@example
1973-06-22
+06-22
1955-08-02 wedding
-2008-04-14 %s released version 6.01 of org-mode, %d years ago
+2008-04-14 %s released version 6.01 of org mode, %d years ago
@end example
After a change to BBDB, or for the first agenda display during an Emacs
@subsubheading Appointment reminders
@cindex @file{appt.el}
@cindex appointment reminders
+@cindex appointment
+@cindex reminders
-Org can interact with Emacs appointments notification facility. To add all
-the appointments of your agenda files, use the command
-@code{org-agenda-to-appt}. This command also lets you filter through the
-list of your appointments and add only those belonging to a specific category
-or matching a regular expression. See the docstring for details.
+Org can interact with Emacs appointments notification facility. To add the
+appointments of your agenda files, use the command @code{org-agenda-to-appt}.
+This command lets you filter through the list of your appointments and add
+only those belonging to a specific category or matching a regular expression.
+It also reads a @code{APPT_WARNTIME} property which will then override the
+value of @code{appt-message-warning-time} for this appointment. See the
+docstring for details.
@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
@subsection The global TODO list
collected into a single place.
@table @kbd
-@kindex C-c a t
-@item C-c a t
-Show the global TODO list. This collects the TODO items from all
-agenda files (@pxref{Agenda Views}) into a single buffer. The buffer is in
-@code{agenda-mode}, so there are commands to examine and manipulate
-the TODO entries directly from that buffer (@pxref{Agenda commands}).
-@kindex C-c a T
-@item C-c a T
+@orgcmd{C-c a t,org-todo-list}
+Show the global TODO list. This collects the TODO items from all agenda
+files (@pxref{Agenda Views}) into a single buffer. By default, this lists
+items with a state the is not a DONE state. The buffer is in
+@code{agenda-mode}, so there are commands to examine and manipulate the TODO
+entries directly from that buffer (@pxref{Agenda commands}).
+@orgcmd{C-c a T,org-todo-list}
@cindex TODO keyword matching
@vindex org-todo-keywords
-Like the above, but allows selection of a specific TODO keyword. You
-can also do this by specifying a prefix argument to @kbd{C-c a t}. With
-a @kbd{C-u} prefix you are prompted for a keyword, and you may also
-specify several keywords by separating them with @samp{|} as the boolean OR
-operator. With a numeric prefix, the nth keyword in
-@code{org-todo-keywords} is selected.
+Like the above, but allows selection of a specific TODO keyword. You can
+also do this by specifying a prefix argument to @kbd{C-c a t}. You are
+prompted for a keyword, and you may also specify several keywords by
+separating them with @samp{|} as the boolean OR operator. With a numeric
+prefix, the Nth keyword in @code{org-todo-keywords} is selected.
@kindex r
The @kbd{r} key in the agenda buffer regenerates it, and you can give
a prefix argument to this command to change the selected TODO keyword,
@item
@vindex org-agenda-todo-ignore-scheduled
@vindex org-agenda-todo-ignore-deadlines
+@vindex org-agenda-todo-ignore-timestamp
@vindex org-agenda-todo-ignore-with-date
Some people view a TODO item that has been @emph{scheduled} for execution or
have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
Configure the variables @code{org-agenda-todo-ignore-scheduled},
-@code{org-agenda-todo-ignore-deadlines}, and/or
-@code{org-agenda-todo-ignore-with-date} to exclude such items from the
-global TODO list.
+@code{org-agenda-todo-ignore-deadlines},
+@code{org-agenda-todo-ignore-timestamp} and/or
+@code{org-agenda-todo-ignore-with-date} to exclude such items from the global
+TODO list.
@item
@vindex org-agenda-todo-list-sublevels
TODO items may have sublevels to break up the task into subtasks. In
m}.
@table @kbd
-@kindex C-c a m
-@item C-c a m
+@orgcmd{C-c a m,org-tags-view}
Produce a list of all headlines that match a given set of tags. The
command prompts for a selection criterion, which is a boolean logic
expression with tags, like @samp{+work+urgent-withboss} or
@samp{work|home} (@pxref{Tags}). If you often need a specific search,
define a custom command for it (@pxref{Agenda dispatcher}).
-@kindex C-c a M
-@item C-c a M
+@orgcmd{C-c a M,org-tags-view}
@vindex org-tags-match-list-sublevels
@vindex org-agenda-tags-todo-honor-ignore-options
-Like @kbd{C-c a m}, but only select headlines that are also TODO items and
-force checking subitems (see variable @code{org-tags-match-list-sublevels}).
-To exclude scheduled/deadline items, see the variable
-@code{org-agenda-tags-todo-honor-ignore-options}. Matching specific TODO
-keywords together with a tags match is also possible, see @ref{Tag searches}.
+Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
+not-DONE state and force checking subitems (see variable
+@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,
+see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching
+specific TODO keywords together with a tags match is also possible, see
+@ref{Tag searches}.
@end table
The commands available in the tags list are described in @ref{Agenda
@subsubheading Match syntax
@cindex Boolean logic, for tag/property searches
-A search string can use Boolean operators @samp{&} for AND and @samp{|} for
-OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently
-not implemented. Each element in the search is either a tag, a regular
-expression matching tags, or an expression like @code{PROPERTY OPERATOR
-VALUE} with a comparison operator, accessing a property value. Each element
-may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic
-sugar for positive selection. The AND operator @samp{&} is optional when
-@samp{+} or @samp{-} is present. Here are some examples, using only tags.
+A search string can use Boolean operators @samp{&} for @code{AND} and
+@samp{|} for @code{OR}@. @samp{&} binds more strongly than @samp{|}.
+Parentheses are not implemented. Each element in the search is either a
+tag, a regular expression matching tags, or an expression like
+@code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a
+property value. Each element may be preceded by @samp{-}, to select
+against it, and @samp{+} is syntactic sugar for positive selection. The
+@code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is
+present. Here are some examples, using only tags.
@table @samp
+@item work
+Select headlines tagged @samp{:work:}.
+@item work&boss
+Select headlines tagged @samp{:work:} and @samp{:boss:}.
@item +work-boss
Select headlines tagged @samp{:work:}, but discard those also tagged
@samp{:boss:}.
@samp{work+@{^boss.*@}} matches headlines that contain the tag
@samp{:work:} and any tag @i{starting} with @samp{boss}.
+@cindex group tags, as regular expressions
+Group tags (@pxref{Tag groups}) are expanded as regular expressions. E.g.,
+if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then
+searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}}
+and searching for @samp{-work} will search for all headlines but those with
+one of the tag in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
+
@cindex TODO keyword matching, with tags search
@cindex level, require for tags/property match
@cindex category, require for tags/property match
time as matching tags. The properties may be real properties, or special
properties that represent other metadata (@pxref{Special properties}). For
example, the ``property'' @code{TODO} represents the TODO keyword of the
-entry. Or, the ``property'' @code{LEVEL} represents the level of an entry.
-So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines
-that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword
-DONE. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
-count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
+entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
+the entry. The ITEM special property cannot currently be used in tags/property
+searches@footnote{But @pxref{x-agenda-skip-entry-regexp,
+,skipping entries based on regexp}.}.
+
+Except the @pxref{Special properties}, one other ``property'' can also be
+used. @code{LEVEL} represents the level of an entry. So a search
+@samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines that have
+the tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE@.
+In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not count
+the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
Here are more examples:
+
@table @samp
@item work+TODO="WAITING"
Select @samp{:work:}-tagged TODO lines with the specific TODO
assumed to be date/time specifications in the standard Org way, and the
comparison will be done accordingly. Special values that will be recognized
are @code{"<now>"} for now (including time), and @code{"<today>"}, and
-@code{"<tomorrow>"} for these days at 0:00 hours, i.e. without a time
+@code{"<tomorrow>"} for these days at 0:00 hours, i.e., without a time
specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
respectively, can be used.
tags/property part of the search string (which may include several terms
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. 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 part after the slash with @samp{!}. Examples:
+tags, but should be applied with care: for example, a positive selection on
+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
+part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will
+not match TODO keywords in a DONE state. Examples:
@table @samp
@item work/WAITING
to give an overview over events in a project.
@table @kbd
-@kindex C-c a L
-@item C-c a L
+@orgcmd{C-c a L,org-timeline}
Show a time-sorted view of the Org file, with all time-stamped items.
When called with a @kbd{C-u} prefix, all unfinished TODO entries
(scheduled or not) are also listed under the current date.
It is particularly useful to find notes.
@table @kbd
-@kindex C-c a s
-@item C-c a s
+@orgcmd{C-c a s,org-search-view}
This is a special search that lets you select entries by matching a substring
or specific words using a boolean logic.
@end table
will search for note entries that contain the keywords @code{computer}
and @code{wifi}, but not the keyword @code{ethernet}, and which are also
not matched by the regular expression @code{8\.11[bg]}, meaning to
-exclude both 8.11b and 8.11g.
+exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on
+word search, other @samp{+} characters are optional. For more details, see
+the docstring of the command @code{org-search-view}.
@vindex org-agenda-text-search-extra-files
Note that in addition to the agenda files, this command will also search
@node Stuck projects, , Search view, Built-in agenda views
@subsection Stuck projects
+@pindex GTD, Getting Things Done
If you are following a system like David Allen's GTD to organize your
work, one of the ``duties'' you have is a regular review to make sure
projects and define next actions for them.
@table @kbd
-@kindex C-c a #
-@item C-c a #
+@orgcmd{C-c a #,org-agenda-list-stuck-projects}
List projects that are stuck.
@kindex C-c a !
@item C-c a !
@cindex presentation, of agenda items
@vindex org-agenda-prefix-format
-Before displaying items in an agenda view, Org mode visually prepares
-the items and sorts them. Each item occupies a single line. The line
-starts with a @emph{prefix} that contains the @emph{category}
-(@pxref{Categories}) of the item and other important information. You can
-customize the prefix using the option @code{org-agenda-prefix-format}.
-The prefix is followed by a cleaned-up version of the outline headline
+@vindex org-agenda-tags-column
+Before displaying items in an agenda view, Org mode visually prepares the
+items and sorts them. Each item occupies a single line. The line starts
+with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
+of the item and other important information. You can customize in which
+column tags will be displayed through @code{org-agenda-tags-column}. You can
+also customize the prefix using the option @code{org-agenda-prefix-format}.
+This prefix is followed by a cleaned-up version of the outline headline
associated with the item.
@menu
* Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time
-* Sorting of agenda items:: The order of things
+* Sorting agenda items:: The order of things
+* Filtering/limiting agenda items:: Dynamically narrow the agenda
@end menu
@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
@subsection Categories
@cindex category
+@cindex #+CATEGORY
The category is a broad label assigned to each agenda item. By default,
the category is simply derived from the file name, but you can also
specify it with a special line in the buffer, like this@footnote{For
The display in the agenda buffer looks best if the category is not
longer than 10 characters.
-@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
+@noindent
+You can set up icons for category by customizing the
+@code{org-agenda-category-icon-alist} variable.
+
+@node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting
@subsection Time-of-day specifications
@cindex time-of-day specification
@code{org-agenda-use-time-grid}, and can be configured with
@code{org-agenda-time-grid}.
-@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting
-@subsection Sorting of agenda items
+@node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting
+@subsection Sorting agenda items
@cindex sorting, of agenda items
@cindex priorities, of agenda items
Before being inserted into a view, the items are sorted. How this is
@code{org-agenda-sorting-strategy}, and may also include criteria based on
the estimated effort of an entry (@pxref{Effort estimates}).
+@node Filtering/limiting agenda items, , Sorting agenda items, Presentation and sorting
+@subsection Filtering/limiting agenda items
+
+Agenda built-in or customized commands are statically defined. Agenda
+filters and limits provide two ways of dynamically narrowing down the list of
+agenda entries: @emph{fitlers} and @emph{limits}. Filters only act on the
+display of the items, while limits take effect before the list of agenda
+entries is built. Filter are more often used interactively, while limits are
+mostly useful when defined as local variables within custom agenda commands.
+
+@subsubheading Filtering in the agenda
+@cindex filtering, by tag, category, top headline and effort, in agenda
+@cindex tag filtering, in agenda
+@cindex category filtering, in agenda
+@cindex top headline filtering, in agenda
+@cindex effort filtering, in agenda
+@cindex query editing, in agenda
+
+@table @kbd
+@orgcmd{/,org-agenda-filter-by-tag}
+@vindex org-agenda-tag-filter-preset
+Filter the agenda view with respect to a tag and/or effort estimates. The
+difference between this and a custom agenda command is that filtering is very
+fast, so that you can switch quickly between different filters without having
+to recreate the agenda.@footnote{Custom commands can preset a filter by
+binding the variable @code{org-agenda-tag-filter-preset} as an option. This
+filter will then be applied to the view and persist as a basic filter through
+refreshes and more secondary filtering. The filter is a global property of
+the entire agenda view---in a block agenda, you should only set this in the
+global options section, not in the section of an individual block.}
+
+You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
+all. Pressing @key{TAB} at that prompt will offer use completion to select a
+tag (including any tags that do not have a selection character). The command
+then hides all entries that do not contain or inherit this tag. When called
+with prefix arg, remove the entries that @emph{do} have the tag. A second
+@kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
+If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
+will be narrowed by requiring or forbidding the selected additional tag.
+Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
+immediately use the @kbd{\} command.
+
+@vindex org-sort-agenda-noeffort-is-high
+In order to filter for effort estimates, you should set up allowed
+efforts globally, for example
+@lisp
+(setq org-global-properties
+ '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
+@end lisp
+You can then filter for an effort by first typing an operator, one of
+@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
+estimate in your array of allowed values, where @kbd{0} means the 10th value.
+The filter will then restrict to entries with effort smaller-or-equal, equal,
+or larger-or-equal than the selected value. If the digits 0--9 are not used
+as fast access keys to tags, you can also simply press the index digit
+directly without an operator. In this case, @kbd{<} will be assumed. For
+application of the operator, entries without a defined effort will be treated
+according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter
+for tasks without effort definition, press @kbd{?} as the operator.
+
+Org also supports automatic, context-aware tag filtering. If the variable
+@code{org-agenda-auto-exclude-function} is set to a user-defined function,
+that function can decide which tags should be excluded from the agenda
+automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
+as a sub-option key and runs the auto exclusion logic. For example, let's
+say you use a @code{Net} tag to identify tasks which need network access, an
+@code{Errand} tag for errands in town, and a @code{Call} tag for making phone
+calls. You could auto-exclude these tags based on the availability of the
+Internet, and outside of business hours, with something like this:
+
+@smalllisp
+@group
+(defun org-my-auto-exclude-function (tag)
+ (and (cond
+ ((string= tag "Net")
+ (/= 0 (call-process "/sbin/ping" nil nil nil
+ "-c1" "-q" "-t1" "mail.gnu.org")))
+ ((or (string= tag "Errand") (string= tag "Call"))
+ (let ((hour (nth 2 (decode-time))))
+ (or (< hour 8) (> hour 21)))))
+ (concat "-" tag)))
+
+(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
+@end group
+@end smalllisp
+
+@orgcmd{\\,org-agenda-filter-by-tag-refine}
+Narrow the current agenda filter by an additional condition. When called with
+prefix arg, remove the entries that @emph{do} have the tag, or that do match
+the effort criterion. You can achieve the same effect by pressing @kbd{+} or
+@kbd{-} as the first key after the @kbd{/} command.
+
+@c
+@kindex [
+@kindex ]
+@kindex @{
+@kindex @}
+@item [ ] @{ @}
+@table @i
+@item @r{in} search view
+add new search words (@kbd{[} and @kbd{]}) or new regular expressions
+(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
+add a positive search term prefixed by @samp{+}, indicating that this search
+term @i{must} occur/match in the entry. The closing bracket/brace will add a
+negative search term which @i{must not} occur/match in the entry for it to be
+selected.
+@end table
+
+@orgcmd{<,org-agenda-filter-by-category}
+@vindex org-agenda-category-filter-preset
+
+Filter the current agenda view with respect to the category of the item at
+point. Pressing @code{<} another time will remove this filter. You can add
+a filter preset through the option @code{org-agenda-category-filter-preset}
+(see below.)
+
+@orgcmd{^,org-agenda-filter-by-top-headline}
+Filter the current agenda view and only display the siblings and the parent
+headline of the one at point.
+
+@orgcmd{=,org-agenda-filter-by-regexp}
+@vindex org-agenda-regexp-filter-preset
+
+Filter the agenda view by a regular expression: only show agenda entries
+matching the regular expression the user entered. When called with a prefix
+argument, it will filter @emph{out} entries matching the regexp. With two
+universal prefix arguments, it will remove all the regexp filters, which can
+be accumulated. You can add a filter preset through the option
+@code{org-agenda-category-filter-preset} (see below.)
+
+@orgcmd{|,org-agenda-filter-remove-all}
+Remove all filters in the current agenda view.
+@end table
+
+@subsubheading Setting limits for the agenda
+@cindex limits, in agenda
+@vindex org-agenda-max-entries
+@vindex org-agenda-max-effort
+@vindex org-agenda-max-todos
+@vindex org-agenda-max-tags
+
+Here is a list of options that you can set, either globally, or locally in
+your custom agenda views@pxref{Custom agenda views}.
+
+@table @var
+@item org-agenda-max-entries
+Limit the number of entries.
+@item org-agenda-max-effort
+Limit the duration of accumulated efforts (as minutes).
+@item org-agenda-max-todos
+Limit the number of entries with TODO keywords.
+@item org-agenda-max-tags
+Limit the number of tagged entries.
+@end table
+
+When set to a positive integer, each option will exclude entries from other
+categories: for example, @code{(setq org-agenda-max-effort 100)} will limit
+the agenda to 100 minutes of effort and exclude any entry that as no effort
+property. If you want to include entries with no effort property, use a
+negative value for @code{org-agenda-max-effort}.
+
+One useful setup is to use @code{org-agenda-max-entries} locally in a custom
+command. For example, this custom command will display the next five entries
+with a @code{NEXT} TODO keyword.
+
+@smalllisp
+(setq org-agenda-custom-commands
+ '(("n" todo "NEXT"
+ ((org-agenda-max-entries 5)))))
+@end smalllisp
+
+Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
+will again the next five entries again, including the first entry that was
+excluded so far.
+
+You can also dynamically set temporary limits@footnote{Those temporary limits
+are lost when rebuilding the agenda.}:
+
+@table @kbd
+@orgcmd{~,org-agenda-limit-interactively}
+This prompts for the type of limit to apply and its value.
+@end table
+
@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
@section Commands in the agenda buffer
@cindex commands, in agenda buffer
@table @kbd
@tsubheading{Motion}
@cindex motion commands in agenda
-@kindex n
-@item n
-Next line (same as @key{up} and @kbd{C-p}).
-@kindex p
-@item p
-Previous line (same as @key{down} and @kbd{C-n}).
+@orgcmd{n,org-agenda-next-line}
+Next line (same as @key{down} and @kbd{C-n}).
+@orgcmd{p,org-agenda-previous-line}
+Previous line (same as @key{up} and @kbd{C-p}).
@tsubheading{View/Go to Org file}
-@kindex mouse-3
-@kindex @key{SPC}
-@item mouse-3
-@itemx @key{SPC}
+@orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
Display the original location of the item in another window.
With prefix arg, make sure that the entire entry is made visible in the
outline, not only the heading.
@c
-@kindex L
-@item L
+@orgcmd{L,org-agenda-recenter}
Display original location and recenter that window.
@c
-@kindex mouse-2
-@kindex mouse-1
-@kindex @key{TAB}
-@item mouse-2
-@itemx mouse-1
-@itemx @key{TAB}
-Go to the original location of the item in another window. Under Emacs
-22, @kbd{mouse-1} will also works for this.
+@orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
+Go to the original location of the item in another window.
@c
-@kindex @key{RET}
-@itemx @key{RET}
+@orgcmd{@key{RET},org-agenda-switch-to}
Go to the original location of the item and delete other windows.
@c
-@kindex F
-@item F
+@orgcmd{F,org-agenda-follow-mode}
@vindex org-agenda-start-with-follow-mode
Toggle Follow mode. In Follow mode, as you move the cursor through
the agenda buffer, the other window always shows the corresponding
agenda buffers can be set with the variable
@code{org-agenda-start-with-follow-mode}.
@c
-@kindex C-c C-x b
-@item C-c C-x b
+@orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
Display the entire subtree of the current item in an indirect buffer. With a
numeric prefix argument N, go up to level N and then take that tree. If N is
negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
previously used indirect buffer.
-@kindex C-c C-o
-@item C-c C-o
+@orgcmd{C-c C-o,org-agenda-open-link}
Follow a link in the entry. This will offer a selection of any links in the
text belonging to the referenced Org node. If there is only one link, it
will be followed without a selection prompt.
@tsubheading{Change display}
@cindex display changing, in agenda
+@kindex A
+@item A
+Interactively select another agenda view and append it to the current view.
+@c
@kindex o
@item o
Delete other windows.
@c
-@kindex v d
-@kindex d
-@kindex v w
-@kindex w
-@kindex v m
-@kindex v y
-@item v d @ @r{or short} @ d
-@itemx v w @ @r{or short} @ w
-@itemx v m
-@itemx v y
-Switch to day/week/month/year view. When switching to day or week view,
-this setting becomes the default for subsequent agenda commands. Since
-month and year views are slow to create, they do not become the default.
-A numeric prefix argument may be used to jump directly to a specific day
-of the year, ISO week, month, or year, respectively. For example,
-@kbd{32 d} jumps to February 1st, @kbd{9 w} to ISO week number 9. When
-setting day, week, or month view, a year may be encoded in the prefix
-argument as well. For example, @kbd{200712 w} will jump to week 12 in
-2007. If such a year specification has only one or two digits, it will
-be mapped to the interval 1938-2037.
+@orgcmdkskc{v d,d,org-agenda-day-view}
+@xorgcmdkskc{v w,w,org-agenda-week-view}
+@xorgcmd{v t,org-agenda-fortnight-view}
+@xorgcmd{v m,org-agenda-month-view}
+@xorgcmd{v y,org-agenda-year-view}
+@xorgcmd{v SPC,org-agenda-reset-view}
+@vindex org-agenda-span
+Switch to day/week/month/year view. When switching to day or week view, this
+setting becomes the default for subsequent agenda refreshes. Since month and
+year views are slow to create, they do not become the default. A numeric
+prefix argument may be used to jump directly to a specific day of the year,
+ISO week, month, or year, respectively. For example, @kbd{32 d} jumps to
+February 1st, @kbd{9 w} to ISO week number 9. When setting day, week, or
+month view, a year may be encoded in the prefix argument as well. For
+example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
+specification has only one or two digits, it will be mapped to the interval
+1938--2037. @kbd{v @key{SPC}} will reset to what is set in
+@code{org-agenda-span}.
@c
-@kindex f
-@item f
-@vindex org-agenda-ndays
-Go forward in time to display the following @code{org-agenda-ndays} days.
+@orgcmd{f,org-agenda-later}
+Go forward in time to display the following @code{org-agenda-current-span} days.
For example, if the display covers a week, switch to the following week.
-With prefix arg, go forward that many times @code{org-agenda-ndays} days.
+With prefix arg, go forward that many times @code{org-agenda-current-span} days.
@c
-@kindex b
-@item b
+@orgcmd{b,org-agenda-earlier}
Go backward in time to display earlier dates.
@c
-@kindex .
-@item .
+@orgcmd{.,org-agenda-goto-today}
Go to today.
@c
-@kindex j
-@item j
+@orgcmd{j,org-agenda-goto-date}
Prompt for a date and go there.
@c
-@kindex D
-@item D
+@orgcmd{J,org-agenda-clock-goto}
+Go to the currently clocked-in task @i{in the agenda buffer}.
+@c
+@orgcmd{D,org-agenda-toggle-diary}
Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.
@c
-@kindex v l
-@kindex l
-@item v l @ @r{or short} @ l
+@orgcmdkskc{v l,l,org-agenda-log-mode}
+@kindex v L
@vindex org-log-done
@vindex org-agenda-log-mode-items
Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
types that should be included in log mode using the variable
@code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show
all possible logbook entries, including state changes. When called with two
-prefix args @kbd{C-u C-u}, show only logging information, nothing else.
+prefix arguments @kbd{C-u C-u}, show only logging information, nothing else.
+@kbd{v L} is equivalent to @kbd{C-u v l}.
@c
-@kindex v [
-@kindex [
-@item v [ @ @r{or short} @ [
+@orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
Include inactive timestamps into the current view. Only for weekly/daily
agenda and timeline views.
@c
-@kindex v a
-@kindex v A
-@item v a
-@itemx v A
+@orgcmd{v a,org-agenda-archives-mode}
+@xorgcmd{v A,org-agenda-archives-mode 'files}
Toggle Archives mode. In Archives mode, trees that are marked
@code{ARCHIVED} are also scanned when producing the agenda. When you use the
capital @kbd{A}, even all archive files are included. To exit archives mode,
press @kbd{v a} again.
@c
-@kindex v R
-@kindex R
-@item v R @ @r{or short} @ R
+@orgcmdkskc{v R,R,org-agenda-clockreport-mode}
@vindex org-agenda-start-with-clockreport-mode
+@vindex org-clock-report-include-clocking-task
Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will
-always show a table with the clocked times for the timespan and file scope
+always show a table with the clocked times for the time span and file scope
covered by the current agenda view. The initial setting for this mode in new
agenda buffers can be set with the variable
-@code{org-agenda-start-with-clockreport-mode}.
+@code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
+when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
+contributions from entries that are hidden by agenda filtering@footnote{Only
+tags filtering will be respected here, effort filtering is ignored.}. See
+also the variable @code{org-clock-report-include-clocking-task}.
@c
-@kindex v E
-@kindex E
-@item v E @ @r{or short} @ E
+@orgkey{v c}
+@vindex org-agenda-clock-consistency-checks
+Show overlapping clock entries, clocking gaps, and other clocking problems in
+the current agenda range. You can then visit clocking lines and fix them
+manually. See the variable @code{org-agenda-clock-consistency-checks} for
+information on how to customize the definition of what constituted a clocking
+problem. To return to normal agenda display, press @kbd{l} to exit Logbook
+mode.
+@c
+@orgcmdkskc{v E,E,org-agenda-entry-text-mode}
@vindex org-agenda-start-with-entry-text-mode
@vindex org-agenda-entry-text-maxlines
Toggle entry text mode. In entry text mode, a number of lines from the Org
@code{org-agenda-entry-text-maxlines}. Calling this command with a numeric
prefix argument will temporarily modify that number to the prefix value.
@c
-@kindex G
-@item G
+@orgcmd{G,org-agenda-toggle-time-grid}
@vindex org-agenda-use-time-grid
@vindex org-agenda-time-grid
Toggle the time grid on and off. See also the variables
@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
@c
-@kindex r
-@item r
+@orgcmd{r,org-agenda-redo}
Recreate the agenda buffer, for example to reflect the changes after
modification of the timestamps of items with @kbd{S-@key{left}} and
@kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix
argument is interpreted to create a selective list for a specific TODO
keyword.
-@kindex g
-@item g
+@orgcmd{g,org-agenda-redo}
Same as @kbd{r}.
@c
-@kindex s
-@kindex C-x C-s
-@item s
-@itemx C-x C-s
+@orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
Save all Org buffers in the current Emacs session, and also the locations of
IDs.
@c
-@kindex C-c C-x C-c
-@item C-c C-x C-c
+@orgcmd{C-c C-x C-c,org-agenda-columns}
@vindex org-columns-default-format
Invoke column view (@pxref{Column view}) in the agenda buffer. The column
view format is taken from the entry at point, or (if there is no entry at
@code{#+COLUMNS} line, or from the default variable
@code{org-columns-default-format}), will be used in the agenda.
-@kindex C-c C-x >
-@item C-c C-x >
+@orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
Remove the restriction lock on the agenda, if it is currently restricted to a
file or subtree (@pxref{Agenda files}).
@tsubheading{Secondary filtering and query editing}
-@cindex filtering, by tag and effort, in agenda
-@cindex tag filtering, in agenda
-@cindex effort filtering, in agenda
-@cindex query editing, in agenda
-@kindex /
-@item /
-@vindex org-agenda-filter-preset
-Filter the current agenda view with respect to a tag and/or effort estimates.
-The difference between this and a custom agenda command is that filtering is
-very fast, so that you can switch quickly between different filters without
-having to recreate the agenda@footnote{Custom commands can preset a filter by
-binding the variable @code{org-agenda-filter-preset} as an option. This
-filter will then be applied to the view and persist as a basic filter through
-refreshes and more secondary filtering.}
+For a detailed description of these commands, see @pxref{Filtering/limiting
+agenda items}.
-You will be prompted for a tag selection letter, SPC will mean any tag at
-all. Pressing @key{TAB} at that prompt will offer use completion to select a
-tag (including any tags that do not have a selection character). The command
-then hides all entries that do not contain or inherit this tag. When called
-with prefix arg, remove the entries that @emph{do} have the tag. A second
-@kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
-If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
-will be narrowed by requiring or forbidding the selected additional tag.
-Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
-immediately use the @kbd{\} command.
+@orgcmd{/,org-agenda-filter-by-tag}
+@vindex org-agenda-tag-filter-preset
+Filter the agenda view with respect to a tag and/or effort estimates.
-@vindex org-sort-agenda-noeffort-is-high
-In order to filter for effort estimates, you should set-up allowed
-efforts globally, for example
-@lisp
-(setq org-global-properties
- '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
-@end lisp
-You can then filter for an effort by first typing an operator, one of
-@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
-estimate in your array of allowed values, where @kbd{0} means the 10th value.
-The filter will then restrict to entries with effort smaller-or-equal, equal,
-or larger-or-equal than the selected value. If the digits 0-9 are not used
-as fast access keys to tags, you can also simply press the index digit
-directly without an operator. In this case, @kbd{<} will be assumed. For
-application of the operator, entries without a defined effort will be treated
-according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter
-for tasks without effort definition, press @kbd{?} as the operator.
+@orgcmd{\\,org-agenda-filter-by-tag-refine}
+Narrow the current agenda filter by an additional condition.
-Org also supports automatic, context-aware tag filtering. If the variable
-@code{org-agenda-auto-exclude-function} is set to a user-defined function,
-that function can decide which tags should be excluded from the agenda
-automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
-as a sub-option key and runs the auto exclusion logic. For example, let's
-say you use a @code{Net} tag to identify tasks which need network access, an
-@code{Errand} tag for errands in town, and a @code{Call} tag for making phone
-calls. You could auto-exclude these tags based on the availability of the
-Internet, and outside of business hours, with something like this:
+@orgcmd{<,org-agenda-filter-by-category}
+@vindex org-agenda-category-filter-preset
-@lisp
-@group
-(defun org-my-auto-exclude-function (tag)
- (and (cond
- ((string= tag "Net")
- (/= 0 (call-process "/sbin/ping" nil nil nil
- "-c1" "-q" "-t1" "mail.gnu.org")))
- ((or (string= tag "Errand") (string= tag "Call"))
- (let ((hour (nth 2 (decode-time))))
- (or (< hour 8) (> hour 21)))))
- (concat "-" tag)))
+Filter the current agenda view with respect to the category of the item at
+point. Pressing @code{<} another time will remove this filter.
-(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
-@end group
-@end lisp
+@orgcmd{^,org-agenda-filter-by-top-headline}
+Filter the current agenda view and only display the siblings and the parent
+headline of the one at point.
-@kindex \
-@item \
-Narrow the current agenda filter by an additional condition. When called with
-prefix arg, remove the entries that @emph{do} have the tag, or that do match
-the effort criterion. You can achieve the same effect by pressing @kbd{+} or
-@kbd{-} as the first key after the @kbd{/} command.
+@orgcmd{=,org-agenda-filter-by-regexp}
+@vindex org-agenda-regexp-filter-preset
-@kindex [
-@kindex ]
-@kindex @{
-@kindex @}
-@item [ ] @{ @}
-@table @i
-@item @r{in} search view
-add new search words (@kbd{[} and @kbd{]}) or new regular expressions
-(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
-add a positive search term prefixed by @samp{+}, indicating that this search
-term @i{must} occur/match in the entry. The closing bracket/brace will add a
-negative search term which @i{must not} occur/match in the entry for it to be
-selected.
-@end table
+Filter the agenda view by a regular expression: only show agenda entries
+matching the regular expression the user entered. When called with a prefix
+argument, it will filter @emph{out} entries matching the regexp. With two
+universal prefix arguments, it will remove all the regexp filters, which can
+be accumulated. You can add a filter preset through the option
+@code{org-agenda-category-filter-preset} (see below.)
+
+@orgcmd{|,org-agenda-filter-remove-all}
+Remove all filters in the current agenda view.
-@page
@tsubheading{Remote editing}
@cindex remote editing, from agenda
-@item 0-9
+@item 0--9
Digit argument.
@c
@cindex undoing remote-editing events
@cindex remote editing, undo
-@kindex C-_
-@item C-_
+@orgcmd{C-_,org-agenda-undo}
Undo a change due to a remote editing command. The change is undone
both in the agenda buffer and in the remote buffer.
@c
-@kindex t
-@item t
+@orgcmd{t,org-agenda-todo}
Change the TODO state of the item, both in the agenda and in the
original org file.
@c
-@kindex C-S-@key{right}
-@kindex C-S-@key{left}
-@item C-S-@key{right}@r{/}@key{left}
+@orgcmd{C-S-@key{right},org-agenda-todo-nextset}
+@orgcmd{C-S-@key{left},org-agenda-todo-previousset}
Switch to the next/previous set of TODO keywords.
@c
-@kindex C-k
-@item C-k
+@orgcmd{C-k,org-agenda-kill}
@vindex org-agenda-confirm-kill
Delete the current agenda item along with the entire subtree belonging
to it in the original Org file. If the text to be deleted remotely
is longer than one line, the kill needs to be confirmed by the user. See
variable @code{org-agenda-confirm-kill}.
@c
-@kindex C-c C-w
-@item C-c C-w
+@orgcmd{C-c C-w,org-agenda-refile}
Refile the entry at point.
@c
-@kindex C-c C-x C-a
-@kindex a
-@item C-c C-x C-a @ @r{or short} @ a
+@orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
@vindex org-archive-default-command
Archive the subtree corresponding to the entry at point using the default
archiving command set in @code{org-archive-default-command}. When using the
@code{a} key, confirmation will be required.
@c
-@kindex C-c C-x a
-@item C-c C-x a
+@orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
Toggle the ARCHIVE tag for the current headline.
@c
-@kindex C-c C-x A
-@item C-c C-x A
+@orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
Move the subtree corresponding to the current entry to its @emph{archive
sibling}.
@c
-@kindex $
-@kindex C-c C-x C-s
-@item C-c C-x C-s @ @r{or short} @ $
+@orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
Archive the subtree corresponding to the current headline. This means the
entry will be moved to the configured archive location, most likely a
different file.
@c
-@kindex T
-@item T
+@orgcmd{T,org-agenda-show-tags}
@vindex org-agenda-show-inherited-tags
Show all tags associated with the current item. This is useful if you have
turned off @code{org-agenda-show-inherited-tags}, but still want to see all
tags of a headline occasionally.
@c
-@kindex :
-@item :
+@orgcmd{:,org-agenda-set-tags}
Set tags for the current headline. If there is an active region in the
agenda, change a tag for all headings in the region.
@c
@kindex ,
@item ,
-Set the priority for the current item. Org mode prompts for the
-priority character. If you reply with @key{SPC}, the priority cookie
-is removed from the entry.
+Set the priority for the current item (@command{org-agenda-priority}).
+Org mode prompts for the priority character. If you reply with @key{SPC},
+the priority cookie is removed from the entry.
@c
-@kindex P
-@item P
+@orgcmd{P,org-agenda-show-priority}
Display weighted priority of current item.
@c
-@kindex +
-@kindex S-@key{up}
-@item +
-@itemx S-@key{up}
+@orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
Increase the priority of the current item. The priority is changed in
the original buffer, but the agenda is not resorted. Use the @kbd{r}
key for this.
@c
-@kindex -
-@kindex S-@key{down}
-@item -
-@itemx S-@key{down}
+@orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
Decrease the priority of the current item.
@c
-@kindex z
-@item z
+@orgcmdkkc{z,C-c C-z,org-agenda-add-note}
@vindex org-log-into-drawer
-Add a note to the entry. This note will be recorded, and then files to the
+Add a note to the entry. This note will be recorded, and then filed to the
same location where state change notes are put. Depending on
-@code{org-log-into-drawer}, this maybe inside a drawer.
+@code{org-log-into-drawer}, this may be inside a drawer.
@c
-@kindex C-c C-a
-@item C-c C-a
+@orgcmd{C-c C-a,org-attach}
Dispatcher for all command related to attachments.
@c
-@kindex C-c C-s
-@item C-c C-s
-Schedule this item
+@orgcmd{C-c C-s,org-agenda-schedule}
+Schedule this item. With prefix arg remove the scheduling timestamp
@c
-@kindex C-c C-d
-@item C-c C-d
-Set a deadline for this item.
+@orgcmd{C-c C-d,org-agenda-deadline}
+Set a deadline for this item. With prefix arg remove the deadline.
@c
-@kindex k
-@item k
-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-remember} 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
-@kindex S-@key{right}
-@item S-@key{right}
+@orgcmd{S-@key{right},org-agenda-do-date-later}
Change the timestamp associated with the current line by one day into the
-future. With a numeric prefix argument, change it by that many days. For
-example, @kbd{3 6 5 S-@key{right}} will change it by a year. With a
-@kbd{C-u} prefix, change the time by one hour. If you immediately repeat the
-command, it will continue to change hours even without the prefix arg. With
-a double @kbd{C-u C-u} prefix, do the same for changing minutes. The stamp
-is changed in the original Org file, but the change is not directly reflected
-in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
+future. If the date is in the past, the first call to this command will move
+it to today.@*
+With a numeric prefix argument, change it by that many days. For example,
+@kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix,
+change the time by one hour. If you immediately repeat the command, it will
+continue to change hours even without the prefix arg. With a double @kbd{C-u
+C-u} prefix, do the same for changing minutes.@*
+The stamp is changed in the original Org file, but the change is not directly
+reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
@c
-@kindex S-@key{left}
-@item S-@key{left}
+@orgcmd{S-@key{left},org-agenda-do-date-earlier}
Change the timestamp associated with the current line by one day
into the past.
@c
-@kindex >
-@item >
-Change the timestamp associated with the current line to today.
-The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}
-on my keyboard.
+@orgcmd{>,org-agenda-date-prompt}
+Change the timestamp associated with the current line. The key @kbd{>} has
+been chosen, because it is the same as @kbd{S-.} on my keyboard.
@c
-@kindex I
-@item I
+@orgcmd{I,org-agenda-clock-in}
Start the clock on the current item. If a clock is running already, it
is stopped first.
@c
-@kindex O
-@item O
+@orgcmd{O,org-agenda-clock-out}
Stop the previously started clock.
@c
-@kindex X
-@item X
+@orgcmd{X,org-agenda-clock-cancel}
Cancel the currently running clock.
-
-@kindex J
-@item J
+@c
+@orgcmd{J,org-agenda-clock-goto}
Jump to the running clock in another window.
+@c
+@orgcmd{k,org-agenda-capture}
+Like @code{org-capture}, but use the date at point as the default date for
+the capture template. See @code{org-capture-use-agenda-date} to make this
+the default behavior of @code{org-capture}.
+@cindex capturing, from agenda
+@vindex org-capture-use-agenda-date
+
+@tsubheading{Dragging agenda lines forward/backward}
+@cindex dragging, agenda lines
+
+@orgcmd{M-<up>,org-agenda-drag-line-backward}
+Drag the line at point backward one line@footnote{Moving agenda lines does
+not persist after an agenda refresh and does not modify the contributing
+@file{.org} files}. With a numeric prefix argument, drag backward by that
+many lines.
+
+@orgcmd{M-<down>,org-agenda-drag-line-forward}
+Drag the line at point forward one line. With a numeric prefix argument,
+drag forward by that many lines.
@tsubheading{Bulk remote editing selected entries}
@cindex remote editing, bulk, from agenda
+@vindex org-agenda-bulk-custom-functions
-@kindex m
-@item s
-Mark the entry at point for bulk action.
-
-@kindex u
-@item u
-Unmark entry for bulk action.
-
-@kindex U
-@item U
+@orgcmd{m,org-agenda-bulk-mark}
+Mark the entry at point for bulk action. With numeric prefix argument, mark
+that many successive entries.
+@c
+@orgcmd{*,org-agenda-bulk-mark-all}
+Mark all visible agenda entries for bulk action.
+@c
+@orgcmd{u,org-agenda-bulk-unmark}
+Unmark entry at point for bulk action.
+@c
+@orgcmd{U,org-agenda-bulk-remove-all-marks}
Unmark all marked entries for bulk action.
-
-@kindex B
-@item B
+@c
+@orgcmd{M-m,org-agenda-bulk-toggle}
+Toggle mark of the entry at point for bulk action.
+@c
+@orgcmd{M-*,org-agenda-bulk-toggle-all}
+Toggle marks of all visible entries for bulk action.
+@c
+@orgcmd{%,org-agenda-bulk-mark-regexp}
+Mark entries matching a regular expression for bulk action.
+@c
+@orgcmd{B,org-agenda-bulk-action}
Bulk action: act on all marked entries in the agenda. This will prompt for
-another key to select the action to be applied:
-@example
-r @r{Prompt for a single refile target and move all entries. The entries}
- @r{will no longer be in the agenda, refresh (@kbd{g}) to bring them back.}
-$ @r{Archive all selected entries.}
-A @r{Archive entries by moving them to their respective archive siblings.}
-t @r{Change TODO state. This prompts for a single TODO keyword and}
- @r{changes the state of all selected entries, bypassing blocking and}
- @r{suppressing logging notes (but not time stamps).}
-+ @r{Add a tag to all selected entries.}
-- @r{Remove a tag from all selected entries.}
-s @r{Schedule all items to a new date. To shift existing schedule dates}
- @r{by a fixed number of days, use something starting with double plus}
- @r{at the prompt, for example @samp{++8d} or @samp{++2w}.}
-d @r{Set deadline to a specific date.}
-@end example
+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. By default, marks are removed after the bulk. If
+you want them to persist, set @code{org-agenda-bulk-persistent-marks} to
+@code{t} or hit @kbd{p} at the prompt.
+
+@table @kbd
+@item *
+Toggle persistent marks.
+@item $
+Archive all selected entries.
+@item A
+Archive entries by moving them to their respective archive siblings.
+@item t
+Change TODO state. This prompts for a single TODO keyword and changes the
+state of all selected entries, bypassing blocking and suppressing logging
+notes (but not timestamps).
+@item +
+Add a tag to all selected entries.
+@item -
+Remove a tag from all selected entries.
+@item s
+Schedule all items to a new date. To shift existing schedule dates by a
+fixed number of days, use something starting with double plus at the prompt,
+for example @samp{++8d} or @samp{++2w}.
+@item d
+Set deadline to a specific date.
+@item r
+Prompt for a single refile target and move all entries. The entries will no
+longer be in the agenda; refresh (@kbd{g}) to bring them back.
+@item S
+Reschedule randomly into the coming N days. N will be prompted for. With
+prefix arg (@kbd{C-u B S}), scatter only across weekdays.
+@item f
+Apply a function@footnote{You can also create persistent custom functions
+through @code{org-agenda-bulk-custom-functions}.} to marked entries. For
+example, the function below sets the CATEGORY property of the entries to web.
+@lisp
+@group
+(defun set-category ()
+ (interactive "P")
+ (let* ((marker (or (org-get-at-bol 'org-hd-marker)
+ (org-agenda-error)))
+ (buffer (marker-buffer marker)))
+ (with-current-buffer buffer
+ (save-excursion
+ (save-restriction
+ (widen)
+ (goto-char marker)
+ (org-back-to-heading t)
+ (org-set-property "CATEGORY" "web"))))))
+@end group
+@end lisp
+@end table
@tsubheading{Calendar commands}
@cindex calendar commands, from agenda
-@kindex c
-@item c
+
+@orgcmd{c,org-agenda-goto-calendar}
Open the Emacs calendar and move to the date at the agenda cursor.
@c
-@item c
+@orgcmd{c,org-calendar-goto-agenda}
When in the calendar, compute and show the Org mode agenda for the
date at the cursor.
@c
@cindex diary entries, creating from agenda
-@kindex i
-@item i
+@orgcmd{i,org-agenda-diary-entry}
@vindex org-agenda-diary-file
Insert a new entry into the diary, using the date at the cursor and (for
block entries) the date at the mark. This will add to the Emacs diary
command in the calendar. The diary file will pop up in another window, where
you can add the entry.
-If you configure @code{org-agenda-diary-file} to point to an Org-mode file,
-Org will create entries (in org-mode syntax) in that file instead. Most
+If you configure @code{org-agenda-diary-file} to point to an Org mode file,
+Org will create entries (in Org mode syntax) in that file instead. Most
entries will be stored in a date-based outline tree that will later make it
easy to archive appointments from previous months/years. The tree will be
-build under an entry with a @code{DATE_TREE} property, or else with years as
-top-level entries. Emacs will prompt you for the entry text - if you specify
+built under an entry with a @code{DATE_TREE} property, or else with years as
+top-level entries. Emacs will prompt you for the entry text---if you specify
it, the entry will be created in @code{org-agenda-diary-file} without further
interaction. If you directly press @key{RET} at the prompt without typing
text, the target file will be shown in another window for you to finish the
entry there. See also the @kbd{k r} command.
@c
-@kindex M
-@item M
+@orgcmd{M,org-agenda-phases-of-moon}
Show the phases of the moon for the three months around current date.
@c
-@kindex S
-@item S
+@orgcmd{S,org-agenda-sunrise-sunset}
Show sunrise and sunset times. The geographical location must be set
with calendar variables, see the documentation for the Emacs calendar.
@c
-@kindex C
-@item C
+@orgcmd{C,org-agenda-convert-date}
Convert the date at cursor into many other cultural and historic
calendars.
@c
-@kindex H
-@item H
+@orgcmd{H,org-agenda-holidays}
Show holidays for three months around the cursor date.
-@item M-x org-export-icalendar-combine-agenda-files
+@item M-x org-icalendar-combine-agenda-files RET
Export a single iCalendar file containing entries from all agenda files.
This is a globally available command, and also available in the agenda menu.
@tsubheading{Exporting to a file}
-@kindex C-x C-w
-@item C-x C-w
+@orgcmd{C-x C-w,org-agenda-write}
@cindex exporting agenda views
@cindex agenda views, exporting
@vindex org-agenda-exporter-settings
Write the agenda view to a file. Depending on the extension of the selected
-file name, the view will be exported as HTML (extension @file{.html} or
-@file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}),
-and plain text (any other extension). When called with a @kbd{C-u} prefix
-argument, immediately open the newly created file. Use the variable
-@code{org-agenda-exporter-settings} to set options for @file{ps-print} and
-for @file{htmlize} to be used during export.
+file name, the view will be exported as HTML (@file{.html} or @file{.htm}),
+Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text
+(any other extension). When exporting to Org, only the body of original
+headlines are exported, not subtrees or inherited tags. When called with a
+@kbd{C-u} prefix argument, immediately open the newly created file. Use the
+variable @code{org-agenda-exporter-settings} to set options for
+@file{ps-print} and for @file{htmlize} to be used during export.
@tsubheading{Quit and Exit}
-@kindex q
-@item q
+@orgcmd{q,org-agenda-quit}
Quit agenda, remove the agenda buffer.
@c
-@kindex x
@cindex agenda files, removing buffers
-@item x
+@orgcmd{x,org-agenda-exit}
Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
for the compilation of the agenda. Buffers created by the user to
visit Org files will not be removed.
buffer).
@kindex C-c a C
@vindex org-agenda-custom-commands
+@cindex agenda views, main example
+@cindex agenda, as an agenda views
+@cindex agenda*, as an agenda views
+@cindex tags, as an agenda view
+@cindex todo, as an agenda view
+@cindex tags-todo
+@cindex todo-tree
+@cindex occur-tree
+@cindex tags-tree
+
Custom commands are configured in the variable
@code{org-agenda-custom-commands}. You can customize this variable, for
-example by pressing @kbd{C-c a C}. You can also directly set it with
-Emacs Lisp in @file{.emacs}. The following example contains all valid
-search types:
+example by pressing @kbd{C-c a C}. You can also directly set it with Emacs
+Lisp in @file{.emacs}. The following example contains all valid agenda
+views:
@lisp
@group
(setq org-agenda-custom-commands
- '(("w" todo "WAITING")
+ '(("x" agenda)
+ ("y" agenda*)
+ ("w" todo "WAITING")
("W" todo-tree "WAITING")
("u" tags "+boss-urgent")
("v" tags-todo "+boss-urgent")
therefore define:
@table @kbd
+@item C-c a x
+as a global search for agenda entries planned@footnote{@emph{Planned} means
+here that these entries have some planning information attached to them, like
+a time-stamp, a scheduled or a deadline string. See
+@code{org-agenda-entry-types} on how to set what planning information will be
+taken into account.} this week/day.
+@item C-c a y
+as a global search for agenda entries planned this week/day, but only those
+with an hour specification like @code{[h]h:mm}---think of them as appointments.
@item C-c a w
as a global search for TODO entries with @samp{WAITING} as the TODO
keyword
Peter, or Kim) as additional tag to match.
@end table
+Note that the @code{*-tree} agenda views need to be called from an
+Org buffer as they operate on the current buffer only.
+
@node Block agenda, Setting Options, Storing searches, Custom agenda views
@subsection Block agenda
@cindex block agenda
@code{org-agenda-custom-commands} has two separate spots for setting
options. You can add options that should be valid for just a single
command in the set, and options that should be valid for all commands in
-the set. The former are just added to the command entry, the latter
+the set. The former are just added to the command entry; the latter
must come after the list of command entries. Going back to the block
agenda example (@pxref{Block agenda}), let's change the sorting strategy
for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
value is a string, you need to add the double-quotes around the value
yourself.
+@vindex org-agenda-custom-commands-contexts
+To control whether an agenda command should be accessible from a specific
+context, you can customize @code{org-agenda-custom-commands-contexts}. Let's
+say for example that you have an agenda commands @code{"o"} displaying a view
+that you only need when reading emails. Then you would configure this option
+like this:
+
+@lisp
+(setq org-agenda-custom-commands-contexts
+ '(("o" (in-mode . "message-mode"))))
+@end lisp
+
+You can also tell that the command key @code{"o"} should refer to another
+command key @code{"r"}. In that case, add this command key like this:
+
+@lisp
+(setq org-agenda-custom-commands-contexts
+ '(("o" "r" (in-mode . "message-mode"))))
+@end lisp
+
+See the docstring of the variable for more information.
@node Exporting Agenda Views, Agenda column view, Custom agenda views, Agenda Views
@section Exporting Agenda Views
agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's
@file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the
ghostscript @file{ps2pdf} utility must be installed on the system. Selecting
-a PDF file with also create the postscript file.}, and iCalendar files. If
+a PDF file will also create the postscript file.}, and iCalendar files. If
you want to do this only occasionally, use the command
@table @kbd
-@kindex C-x C-w
-@item C-x C-w
+@orgcmd{C-x C-w,org-agenda-write}
@cindex exporting agenda views
@cindex agenda views, exporting
@vindex org-agenda-exporter-settings
files in one step:
@table @kbd
-@kindex C-c a e
-@item C-c a e
+@orgcmd{C-c a e,org-store-agenda-views}
Export all agenda views that have export file names associated with
them.
@end table
@noindent
From the command line you may also use
@example
-emacs -f org-batch-store-agenda-views -kill
+emacs -eval (org-batch-store-agenda-views) -kill
@end example
@noindent
or, if you need to modify some parameters@footnote{Quoting depends on the
system you use, please check the FAQ for examples.}
@example
emacs -eval '(org-batch-store-agenda-views \
- org-agenda-ndays 30 \
+ org-agenda-span (quote month) \
org-agenda-start-day "2007-11-01" \
org-agenda-include-diary nil \
org-agenda-files (quote ("~/org/project.org")))' \
collected by certain criteria.
@table @kbd
-@kindex C-c C-x C-c
-@item C-c C-x C-c
+@orgcmd{C-c C-x C-c,org-agenda-columns}
Turn on column view in the agenda.
@end table
Org needs to make a decision which @code{COLUMNS} format to use. Since the
entries in the agenda are collected from different files, and different files
may have different @code{COLUMNS} formats, this is a non-trivial problem.
-Org first checks if the variable @code{org-overriding-columns-format} is
+Org first checks if the variable @code{org-agenda-overriding-columns-format} is
currently set, and if so, takes the format from there. Otherwise it takes
the format associated with the first item in the agenda, or, if that item
does not have a specific format (defined in a property, or in its file), it
make sure that the computations of this property are up to date. This is
also true for the special @code{CLOCKSUM} property. Org will then sum the
values displayed in the agenda. In the daily/weekly agenda, the sums will
-cover a single day, in all other views they cover the entire block. It is
+cover a single day; in all other views they cover the entire block. It is
vital to realize that the agenda may show the same entry @emph{twice} (for
example as scheduled and as a deadline), and it may show two entries from the
same hierarchy (for example a @emph{parent} and its @emph{child}). In these
applications for column view in the agenda. If you want information about
clocked time in the displayed period use clock table mode (press @kbd{R} in
the agenda).
+
+@item
+@cindex property, special, CLOCKSUM_T
+When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
+always today's clocked time for this item. So even in the weekly agenda,
+the clocksum listed in column view only originates from today. This lets
+you compare the time you spent on a task for today, with the time already
+spent (via @code{CLOCKSUM}) and with the planned total effort for it.
@end enumerate
@node Markup, Exporting, Agenda Views, Top
@chapter Markup for rich export
-When exporting Org-mode documents, the exporter tries to reflect the
-structure of the document as accurately as possible in the backend. Since
-export targets like HTML, La@TeX{}, or DocBook allow much richer formatting,
-Org mode has rules on how to prepare text for rich export. This section
-summarizes the markup rules used in an Org-mode buffer.
+When exporting Org mode documents, the exporter tries to reflect the
+structure of the document as accurately as possible in the back-end. Since
+export targets like HTML, @LaTeX{} allow much richer formatting, Org mode has
+rules on how to prepare text for rich export. This section summarizes the
+markup rules used in an Org mode buffer.
@menu
* Structural markup elements:: The basic structure as seen by the exporter
-* Images and tables:: Tables and Images will be included
+* Images and tables:: Images, tables and caption mechanism
* Literal examples:: Source code examples with special formatting
* Include files:: Include additional files into a document
-* Macro replacement:: Use macros to create complex output
-* Embedded LaTeX:: LaTeX can be freely used inside Org documents
+* Index entries:: Making an index
+* Macro replacement:: Use macros to create templates
+* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
+* Special blocks:: Containers targeted at export back-ends
@end menu
@node Structural markup elements, Images and tables, Markup, Markup
* Document title:: Where the title is taken from
* Headings and sections:: The document structure as seen by the exporter
* Table of contents:: The if and where of the table of contents
-* Initial text:: Text before the first heading?
* Lists:: Lists
* Paragraphs:: Paragraphs
* Footnote markup:: Footnotes
@end example
@noindent
-If this line does not exist, the title is derived from the first non-empty,
-non-comment line in the buffer. If no such line exists, or if you have
-turned off exporting of the text before the first headline (see below), the
-title will be the file name without extension.
+If this line does not exist, the title will be the name of the file
+associated to buffer, without extension, or the buffer name.
@cindex property, EXPORT_TITLE
-If you are exporting only a subtree by marking is as the region, the heading
-of the subtree will become the title of the document. If the subtree has a
-property @code{EXPORT_TITLE}, that will take precedence.
+If you are exporting only a subtree, its heading will become the title of the
+document. If the subtree has a property @code{EXPORT_TITLE}, that will take
+precedence.
@node Headings and sections, Table of contents, Document title, Structural markup elements
@subheading Headings and sections
#+OPTIONS: H:4
@end example
-@node Table of contents, Initial text, Headings and sections, Structural markup elements
+@node Table of contents, Lists, Headings and sections, Structural markup elements
@subheading Table of contents
@cindex table of contents, markup rules
+@cindex #+TOC
@vindex org-export-with-toc
The table of contents is normally inserted directly before the first headline
-of the file. If you would like to get it to a different location, insert the
-string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired
-location. The depth of the table of contents is by default the same as the
-number of headline levels, but you can choose a smaller number, or turn off
-the table of contents entirely, by configuring the variable
-@code{org-export-with-toc}, or on a per-file basis with a line like
+of the file. The depth of the table is by default the same as the number of
+headline levels, but you can choose a smaller number, or turn off the table
+of contents entirely, by configuring the variable @code{org-export-with-toc},
+or on a per-file basis with a line like
@example
#+OPTIONS: toc:2 (only to two levels in TOC)
-#+OPTIONS: toc:nil (no TOC at all)
+#+OPTIONS: toc:nil (no default TOC at all)
@end example
-@node Initial text, Lists, Table of contents, Structural markup elements
-@subheading Text before the first headline
-@cindex text before first headline, markup rules
-@cindex #+TEXT
-
-Org mode normally exports the text before the first headline, and even uses
-the first line as the document title. The text will be fully marked up. If
-you need to include literal HTML, La@TeX{}, or DocBook code, use the special
-constructs described below in the sections for the individual exporters.
+If you would like to move the table of contents to a different location, you
+should turn off the default table using @code{org-export-with-toc} or
+@code{#+OPTIONS} and insert @code{#+TOC: headlines N} at the desired
+location(s).
-@vindex org-export-skip-text-before-1st-heading
-Some people like to use the space before the first headline for setup and
-internal links and therefore would like to control the exported text before
-the first headline in a different way. You can do so by setting the variable
-@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file
-basis, you can get the same effect with @samp{#+OPTIONS: skip:t}.
+@example
+#+OPTIONS: toc:nil (no default TOC)
+...
+#+TOC: headlines 2 (insert TOC here, with two headline levels)
+@end example
-@noindent
-If you still want to have some text before the first headline, use the
-@code{#+TEXT} construct:
+Multiple @code{#+TOC: headline} lines are allowed. The same @code{TOC}
+keyword can also generate a list of all tables (resp.@: all listings) with a
+caption in the buffer.
@example
-#+OPTIONS: skip:t
-#+TEXT: This text will go before the *first* headline.
-#+TEXT: [TABLE-OF-CONTENTS]
-#+TEXT: This goes between the table of contents and the first headline
+#+TOC: listings (build a list of listings)
+#+TOC: tables (build a list of tables)
@end example
-@node Lists, Paragraphs, Initial text, Structural markup elements
+@cindex property, ALT_TITLE
+The headline's title usually determines its corresponding entry in a table of
+contents. However, it is possible to specify an alternative title by
+setting @code{ALT_TITLE} property accordingly. It will then be used when
+building the table.
+
+@node Lists, Paragraphs, Table of contents, Structural markup elements
@subheading Lists
@cindex lists, markup rules
-Plain lists as described in @ref{Plain lists}, are translated to the backend's
-syntax for such lists. Most backends support unordered, ordered, and
+Plain lists as described in @ref{Plain lists}, are translated to the back-end's
+syntax for such lists. Most back-ends support unordered, ordered, and
description lists.
@node Paragraphs, Footnote markup, Lists, Structural markup elements
When quoting a passage from another document, it is customary to format this
as a paragraph that is indented on both the left and the right margin. You
-can include quotations in Org-mode documents like this:
+can include quotations in Org mode documents like this:
@cindex #+BEGIN_QUOTE
@example
@cindex footnotes, markup rules
@cindex @file{footnote.el}
-Footnotes defined in the way described in @ref{Footnotes}, will be exported by
-all backends. Org allows multiple references to the same note, and
-different backends support this to varying degrees.
+Footnotes defined in the way described in @ref{Footnotes}, will be exported
+by all back-ends. Org allows multiple references to the same note, and
+multiple footnotes side by side.
@node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements
@subheading Emphasis and monospace
@cindex verbatim text, markup rules
@cindex code text, markup rules
@cindex strike-through text, markup rules
+@vindex org-fontify-emphasized-text
+@vindex org-emphasis-regexp-components
+@vindex org-emphasis-alist
You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text
-in the code and verbatim string is not processed for Org-mode specific
+in the code and verbatim string is not processed for Org mode specific
syntax, it is exported verbatim.
+To turn off fontification for marked up text, you can set
+@code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of
+available markup syntax, you can customize @code{org-emphasis-alist}. To fine
+tune what characters are allowed before and after the markup characters, you
+can tweak @code{org-emphasis-regexp-components}. Beware that changing one of
+the above variables will no take effect until you reload Org, for which you
+may need to restart Emacs.
+
@node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements
@subheading Horizontal rules
@cindex horizontal rules, markup rules
-A line consisting of only dashes, and at least 5 of them, will be
-exported as a horizontal line (@samp{<hr/>} in HTML).
+A line consisting of only dashes, and at least 5 of them, will be exported as
+a horizontal line.
@node Comment lines, , Horizontal rules, Structural markup elements
@subheading Comment lines
@cindex exporting, not
@cindex #+BEGIN_COMMENT
-Lines starting with @samp{#} in column zero are treated as comments and will
-never be exported. If you want an indented line to be treated as a comment,
-start it with @samp{#+ }. Also entire subtrees starting with the word
-@samp{COMMENT} will never be exported. Finally, regions surrounded by
-@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported.
+Lines starting with zero or more whitespace characters followed by one
+@samp{#} and a whitespace are treated as comments and will never be exported.
+Also entire subtrees starting with the word @samp{COMMENT} will never be
+exported. Finally, regions surrounded by @samp{#+BEGIN_COMMENT}
+... @samp{#+END_COMMENT} will not be exported.
@table @kbd
@kindex C-c ;
@cindex tables, markup rules
@cindex #+CAPTION
-@cindex #+LABEL
+@cindex #+NAME
Both the native Org mode tables (@pxref{Tables}) and tables formatted with
the @file{table.el} package will be exported properly. For Org mode tables,
the lines before the first horizontal separator line will become table header
lines. You can use the following lines somewhere before the table to assign
-a caption and a label for cross references:
+a caption and a label for cross references, and in the text you can refer to
+the object with @code{[[tab:basic-data]]} (@pxref{Internal links}):
@example
#+CAPTION: This is the caption for the next table (or link)
-#+LABEL: tbl:basic-data
+#+NAME: tab:basic-data
| ... | ...|
|-----|----|
@end example
+Optionally, the caption can take the form:
+@example
+#+CAPTION[Caption for list of tables]: Caption for table.
+@end example
+
@cindex inlined images, markup rules
-Some backends (HTML, La@TeX{}, and DocBook) allow you to directly include
-images into the exported document. Org does this, if a link to an image
-files does not have a description part, for example @code{[[./img/a.jpg]]}.
-If you wish to define a caption for the image and maybe a label for internal
-cross references, you sure that the link is on a line by itself precede it
-with:
+Some back-ends allow you to directly include images into the exported
+document. Org does this, if a link to an image files does not have
+a description part, for example @code{[[./img/a.jpg]]}. If you wish to
+define a caption for the image and maybe a label for internal cross
+references, make sure that the link is on a line by itself and precede it
+with @code{#+CAPTION} and @code{#+NAME} as follows:
@example
#+CAPTION: This is the caption for the next figure link (or table)
-#+LABEL: fig:SED-HR4049
+#+NAME: fig:SED-HR4049
[[./img/a.jpg]]
@end example
-You may also define additional attributes for the figure. As this is
-backend-specific, see the sections about the individual backends for more
-information.
+@noindent
+Such images can be displayed within the buffer. @xref{Handling links,the
+discussion of image links}.
+Even though images and tables are prominent examples of captioned structures,
+the same caption mechanism can apply to many others (e.g., @LaTeX{}
+equations, source code blocks). Depending on the export back-end, those may
+or may not be handled.
@node Literal examples, Include files, Images and tables, Markup
@section Literal examples
@cindex formatting source code, markup rules
If the example is source code from a programming language, or any other text
that can be marked up by font-lock in Emacs, you can ask for the example to
-look like the fontified Emacs buffer@footnote{Currently this works for the
-HTML backend, and requires the @file{htmlize.el} package version 1.34 or
-later. It also works for LaTeX with the listings package, if you turn on the
-option @code{org-export-latex-listings} and make sure that the listings
-package is included by the LaTeX header.}. 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:
+look like the fontified Emacs buffer@footnote{This works automatically for
+the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package,
+which is distributed with Org). Fontified code chunks in @LaTeX{} can be
+achieved using either the listings or the
+@url{http://code.google.com/p/minted, minted,} package. Refer to
+@code{org-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
#+BEGIN_SRC emacs-lisp
-(defun org-xor (a b)
- "Exclusive or."
- (if a (not b) b))
+ (defun org-xor (a b)
+ "Exclusive or."
+ (if a (not b) b))
#+END_SRC
@end example
numbered. If you use a @code{+n} switch, the numbering from the previous
numbered snippet will be continued in the current one. In literal examples,
Org will interpret strings like @samp{(ref:name)} as labels, and use them as
-targets for special hyperlinks like @code{[[(name)]]} (i.e. the reference name
+targets for special hyperlinks like @code{[[(name)]]} (i.e., the reference name
enclosed in single parenthesis). In HTML, hovering the mouse over such a
link will remote-highlight the corresponding code line, which is kind of
cool.
You can also add a @code{-r} switch which @i{removes} the labels from the
source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
labels in the source code while using line numbers for the links, which might
-be useful to explain those in an org-mode example code.}. With the @code{-n}
+be useful to explain those in an Org mode example code.}. With the @code{-n}
switch, links to these references will be labeled by the line numbers from
the code listing, otherwise links will use the labels with no parentheses.
Here is an example:
@code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
-n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}.
-HTML export also allows examples to be published as text areas, @xref{Text
-areas in HTML export}.
+HTML export also allows examples to be published as text areas (@pxref{Text
+areas in HTML export}).
+
+Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
+so often, shortcuts are provided using the Easy Templates facility
+(@pxref{Easy Templates}).
@table @kbd
@kindex C-c '
@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 striped
-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
-temporary buffer created with @kbd{C-c '} will prompt for a label, make sure
+temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure
that it is unique in the current buffer, and insert it with the proper
formatting like @samp{(ref:label)} at the end of the current line. Then the
label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
@end table
-@node Include files, Macro replacement, Literal examples, Markup
+@node Include files, Index entries, Literal examples, Markup
@section Include files
@cindex include files, markup rules
@example
#+INCLUDE: "~/.emacs" src emacs-lisp
@end example
+
@noindent
-The optional second and third parameter are the markup (e.g. @samp{quote},
+The optional second and third parameter are the markup (e.g., @samp{quote},
@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
-language for formatting the contents. The markup is optional, if it is not
+language for formatting the contents. The markup is optional; if it is not
given, the text will be assumed to be in Org mode format and will be
-processed normally. The include line will also allow additional keyword
-parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the
-first line and for each following line, as well as any options accepted by
-the selected markup. For example, to include a file as an item, use
+processed normally.
+
+Contents of the included file will belong to the same structure (headline,
+item) containing the @code{INCLUDE} keyword. In particular, headlines within
+the file will become children of the current section. That behavior can be
+changed by providing an additional keyword parameter, @code{:minlevel}. In
+that case, all headlines in the included file will be shifted so the one with
+the lowest level reaches that specified level. For example, to make a file
+become a sibling of the current top-level headline, use
+
+@example
+#+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
+@end example
+
+You can also include a portion of a file by specifying a lines range using
+the @code{:lines} parameter. The line at the upper end of the range will not
+be included. The start and/or the end of the range may be omitted to use the
+obvious defaults.
@example
-#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " "
+#+INCLUDE: "~/.emacs" :lines "5-10" @r{Include lines 5 to 10, 10 excluded}
+#+INCLUDE: "~/.emacs" :lines "-10" @r{Include lines 1 to 10, 10 excluded}
+#+INCLUDE: "~/.emacs" :lines "10-" @r{Include lines from 10 to EOF}
@end example
@table @kbd
Visit the include file at point.
@end table
+@node Index entries, Macro replacement, Include files, Markup
+@section Index entries
+@cindex index entries, for publishing
+
+You can specify entries that will be used for generating an index during
+publishing. This is done by lines starting with @code{#+INDEX}. An entry
+the contains an exclamation mark will create a sub item. See @ref{Generating
+an index} for more information.
+
+@example
+* Curriculum Vitae
+#+INDEX: CV
+#+INDEX: Application!CV
+@end example
+
+
+
-@node Macro replacement, Embedded LaTeX, Include files, Markup
+@node Macro replacement, Embedded @LaTeX{}, Index entries, Markup
@section Macro replacement
@cindex macro replacement, during export
@cindex #+MACRO
#+MACRO: name replacement text $1, $2 are arguments
@end example
-@noindent which can be referenced anywhere in the document (even in
-code examples) with @code{@{@{@{name(arg1,arg2)@}@}@}}. In addition to
-defined macros, @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc.,
-will reference information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and
-similar lines. Also, @code{@{@{@{date(@var{FORMAT})@}@}@}} and
+@noindent which can be referenced in
+paragraphs, verse blocks, table cells and some keywords with
+@code{@{@{@{name(arg1,arg2)@}@}@}}@footnote{Since commas separate arguments,
+commas within arguments have to be escaped with a backslash character.
+Conversely, backslash characters before a comma, and only them, need to be
+escaped with another backslash character.}. In addition to defined macros,
+@code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc., will reference
+information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and similar lines.
+Also, @code{@{@{@{time(@var{FORMAT})@}@}@}} and
@code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time
and to the modification time of the file being exported, respectively.
@var{FORMAT} should be a format string understood by
@code{format-time-string}.
-Macro expansion takes place during export, and some people use it to
-construct complex HTML code.
+Macro expansion takes place during export.
-@node Embedded LaTeX, , Macro replacement, Markup
-@section Embedded La@TeX{}
+@node Embedded @LaTeX{}, Special blocks, Macro replacement, Markup
+@section Embedded @LaTeX{}
@cindex @TeX{} interpretation
-@cindex La@TeX{} interpretation
-
-Plain ASCII is normally sufficient for almost all note taking. One
-exception, however, are scientific notes which need to be able to contain
-mathematical symbols and the occasional formula. La@TeX{}@footnote{La@TeX{}
-is a macro system based on Donald E. Knuth's @TeX{} system. Many of the
-features described here as ``La@TeX{}'' are really from @TeX{}, but for
-simplicity I am blurring this distinction.} is widely used to typeset
-scientific documents. Org mode supports embedding La@TeX{} code into its
-files, because many academics are used to reading La@TeX{} source code, and
-because it can be readily processed into images for HTML production.
-
-It is not necessary to mark La@TeX{} macros and code in any special way.
-If you observe a few conventions, Org mode knows how to find it and what
-to do with it.
+@cindex @LaTeX{} interpretation
+
+Plain ASCII is normally sufficient for almost all note taking. Exceptions
+include scientific notes, which often require mathematical symbols and the
+occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on
+Donald E. Knuth's @TeX{} system. Many of the features described here as
+``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
+distinction.} is widely used to typeset scientific documents. Org mode
+supports embedding @LaTeX{} code into its files, because many academics are
+used to writing and reading @LaTeX{} source code, and because it can be
+readily processed to produce pretty output for a number of export back-ends.
@menu
* Special symbols:: Greek letters and other symbols
* Subscripts and superscripts:: Simple syntax for raising/lowering text
-* LaTeX fragments:: Complex formulas made easy
-* Previewing LaTeX fragments:: What will this snippet look like?
+* @LaTeX{} fragments:: Complex formulas made easy
+* Previewing @LaTeX{} fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
@end menu
-@node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX
+@node Special symbols, Subscripts and superscripts, Embedded @LaTeX{}, Embedded @LaTeX{}
@subsection Special symbols
@cindex math symbols
@cindex special symbols
@cindex @TeX{} macros
-@cindex La@TeX{} fragments, markup rules
+@cindex @LaTeX{} fragments, markup rules
@cindex HTML entities
-@cindex La@TeX{} entities
+@cindex @LaTeX{} entities
-You can use La@TeX{} macros to insert special symbols like @samp{\alpha} to
-indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion
-for these macros is available, just type @samp{\} and maybe a few letters,
-and press @kbd{M-@key{TAB}} to see possible completions. Unlike La@TeX{}
-code, Org mode allows these macros to be present without surrounding math
+You can use @LaTeX{}-like syntax to insert special symbols like @samp{\alpha}
+to indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion
+for these symbols is available, just type @samp{\} and maybe a few letters,
+and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{}
+code, Org mode allows these symbols to be present without surrounding math
delimiters, for example:
@example
Angles are written as Greek letters \alpha, \beta and \gamma.
@end example
-@vindex org-html-entities
+@vindex org-entities
During export, these symbols will be transformed into the native format of
-the exporter backend. Strings like @code{\alpha} will be exported as
-@code{α} in the HTML output, and as @code{$\alpha$} in the La@TeX{}
+the exporter back-end. Strings like @code{\alpha} will be exported as
+@code{α} in the HTML output, and as @code{$\alpha$} in the @LaTeX{}
output. Similarly, @code{\nbsp} will become @code{ } in HTML and
-@code{~} in La@TeX{}. If you need such a symbol inside a word, terminate it
+@code{~} in @LaTeX{}. If you need such a symbol inside a word, terminate it
like this: @samp{\Aacute@{@}stor}.
A large number of entities is provided, with names taken from both HTML and
-La@TeX{}, see the variable @code{org-html-entities} for the complete list.
+@LaTeX{}; see the variable @code{org-entities} for the complete list.
@samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and
@samp{...} are all converted into special commands creating hyphens of
different lengths or a compact set of dots.
-@node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX
+If you would like to see entities displayed as UTF-8 characters, use the
+following command@footnote{You can turn this on by default by setting the
+variable @code{org-pretty-entities}, or on a per-file base with the
+@code{#+STARTUP} option @code{entitiespretty}.}:
+
+@table @kbd
+@cindex @code{entitiespretty}, STARTUP keyword
+@kindex C-c C-x \
+@item C-c C-x \
+Toggle display of entities as UTF-8 characters. This does not change the
+buffer content which remains plain ASCII, but it overlays the UTF-8 character
+for display purposes only.
+@end table
+
+@node Subscripts and superscripts, @LaTeX{} fragments, Special symbols, Embedded @LaTeX{}
@subsection Subscripts and superscripts
@cindex subscript
@cindex superscript
-Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super-
-and subscripts. Again, these can be used without embedding them in
-math-mode delimiters. To increase the readability of ASCII text, it is
-not necessary (but OK) to surround multi-character sub- and superscripts
-with curly braces. For example
+Just like in @LaTeX{}, @samp{^} and @samp{_} are used to indicate super- and
+subscripts. Again, these can be used without embedding them in math-mode
+delimiters. To increase the readability of ASCII text, it is not necessary
+(but OK) to surround multi-character sub- and superscripts with curly braces.
+For example
@example
-The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
+The mass of the sun is M_sun = 1.989 x 10^30 kg. The radius of
the sun is R_@{sun@} = 6.96 x 10^8 m.
@end example
-@vindex org-export-with-sub-superscripts
-To avoid interpretation as raised or lowered text, you can quote @samp{^} and
-@samp{_} with a backslash: @samp{\^} and @samp{\_}. If you write a text
-where the underscore is often used in a different context, Org's convention
-to always interpret these as subscripts can get in your way. Configure the
-variable @code{org-export-with-sub-superscripts} to globally change this
-convention, or use, on a per-file basis:
-
-@example
-#+OPTIONS: ^:@{@}
-@end example
+@vindex org-use-sub-superscripts
+If you write a text where the underscore is often used in a different
+context, Org's convention to always interpret these as subscripts can get in
+your way. Configure the variable @code{org-use-sub-superscripts} to change
+this convention. For example, when setting this variable to @code{@{@}},
+@samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will.
+@table @kbd
+@kindex C-c C-x \
+@item C-c C-x \
+In addition to showing entities as UTF-8 characters, this command will also
+format sub- and superscripts in a WYSIWYM way.
+@end table
-@node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX
-@subsection La@TeX{} fragments
-@cindex La@TeX{} fragments
+@node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Subscripts and superscripts, Embedded @LaTeX{}
+@subsection @LaTeX{} fragments
+@cindex @LaTeX{} fragments
@vindex org-format-latex-header
-With symbols, sub- and superscripts, HTML is pretty much at its end when
-it comes to representing mathematical formulas@footnote{Yes, there is
-MathML, but that is not yet fully supported by many browsers, and there
-is no decent converter for turning La@TeX{} or ASCII representations of
-formulas into MathML. So for the time being, converting formulas into
-images seems the way to go.}. More complex expressions need a dedicated
-formula processor. To this end, Org mode can contain arbitrary La@TeX{}
-fragments. It provides commands to preview the typeset result of these
-fragments, and upon export to HTML, all fragments will be converted to
-images and inlined into the HTML document@footnote{The La@TeX{} export
-will not use images for displaying La@TeX{} fragments but include these
-fragments directly into the La@TeX{} code.}. For this to work you
-need to be on a system with a working La@TeX{} installation. You also
-need the @file{dvipng} program, available at
-@url{http://sourceforge.net/projects/dvipng/}. The La@TeX{} header that
-will be used when processing a fragment can be configured with the
-variable @code{org-format-latex-header}.
-
-La@TeX{} fragments don't need any special marking at all. The following
-snippets will be identified as La@TeX{} source code:
+Going beyond symbols and sub- and superscripts, a full formula language is
+needed. Org mode can contain @LaTeX{} math fragments, and it supports ways
+to process these for several export back-ends. When exporting to @LaTeX{},
+the code is obviously left as it is. When exporting to HTML, Org invokes the
+@uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in
+HTML export}) to process and display the math@footnote{If you plan to use
+this regularly or on pages with significant page views, you should install
+@file{MathJax} on your own server in order to limit the load of our server.}.
+Finally, it can also process the mathematical expressions into
+images@footnote{For this to work you need to be on a system with a working
+@LaTeX{} installation. You also need the @file{dvipng} program or the
+@file{convert}, respectively available at
+@url{http://sourceforge.net/projects/dvipng/} and from the @file{imagemagick}
+suite. The @LaTeX{} header that will be used when processing a fragment can
+be configured with the variable @code{org-format-latex-header}.} that can be
+displayed in a browser.
+
+@LaTeX{} fragments don't need any special marking at all. The following
+snippets will be identified as @LaTeX{} source code:
@itemize @bullet
@item
-Environments of any kind. The only requirement is that the
-@code{\begin} statement appears on a new line, preceded by only
-whitespace.
+Environments of any kind@footnote{When @file{MathJax} is used, only the
+environments recognized by @file{MathJax} will be processed. When
+@file{dvipng} program or @file{imagemagick} suite is used to create images,
+any @LaTeX{} environment will be handled.}. The only requirement is that the
+@code{\begin} and @code{\end} statements appear on a new line, at the
+beginning of the line or after whitespaces only.
@item
-Text within the usual La@TeX{} math delimiters. To avoid conflicts with
+Text within the usual @LaTeX{} math delimiters. To avoid conflicts with
currency specifications, single @samp{$} characters are only recognized as
math delimiters if the enclosed text contains at most two line breaks, is
directly attached to the @samp{$} characters with no whitespace in between,
@noindent For example:
@example
-\begin@{equation@} % arbitrary environments,
-x=\sqrt@{b@} % even tables, figures
-\end@{equation@} % etc
+\begin@{equation@}
+x=\sqrt@{b@}
+\end@{equation@}
If $a^2=b$ and \( b=2 \), then the solution must be
either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
@end example
-@noindent
-@vindex org-format-latex-options
-If you need any of the delimiter ASCII sequences for other purposes, you
-can configure the option @code{org-format-latex-options} to deselect the
-ones you do not wish to have interpreted by the La@TeX{} converter.
+@c FIXME
+@c @noindent
+@c @vindex org-format-latex-options
+@c If you need any of the delimiter ASCII sequences for other purposes, you
+@c can configure the option @code{org-format-latex-options} to deselect the
+@c ones you do not wish to have interpreted by the @LaTeX{} converter.
+
+@vindex org-export-with-latex
+@LaTeX{} processing can be configured with the variable
+@code{org-export-with-latex}. The default setting is @code{t} which means
+@file{MathJax} for HTML, and no processing for ASCII and @LaTeX{} back-ends.
+You can also set this variable on a per-file basis using one of these
+lines:
+
+@example
+#+OPTIONS: tex:t @r{Do the right thing automatically (MathJax)}
+#+OPTIONS: tex:nil @r{Do not process @LaTeX{} fragments at all}
+#+OPTIONS: tex:verbatim @r{Verbatim export, for jsMath or so}
+@end example
-@node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
-@subsection Previewing LaTeX fragments
-@cindex LaTeX fragments, preview
+@node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{}
+@subsection Previewing @LaTeX{} fragments
+@cindex @LaTeX{} fragments, preview
-La@TeX{} fragments can be processed to produce preview images of the
-typeset expressions:
+@vindex org-latex-create-formula-image-program
+If you have @file{dvipng} or @file{imagemagick} installed@footnote{Choose the
+converter by setting the variable
+@code{org-latex-create-formula-image-program} accordingly.}, @LaTeX{}
+fragments can be processed to produce preview images of the typeset
+expressions:
@table @kbd
@kindex C-c C-x C-l
@item C-c C-x C-l
-Produce a preview image of the La@TeX{} fragment at point and overlay it
+Produce a preview image of the @LaTeX{} fragment at point and overlay it
over the source code. If there is no fragment at point, process all
fragments in the current entry (between two headlines). When called
with a prefix argument, process the entire subtree. When called with
@vindex org-format-latex-options
You can customize the variable @code{org-format-latex-options} to influence
-some aspects of the preview. In particular, the @code{:scale} (and for HTML
+some aspects of the preview. In particular, the @code{:scale} (and for HTML
export, @code{:html-scale}) property can be used to adjust the size of the
preview images.
-During HTML export (@pxref{HTML export}), all La@TeX{} fragments are
-converted into images and inlined into the document if the following
-setting is active:
+@vindex org-startup-with-latex-preview
+You can turn on the previewing of all @LaTeX{} fragments in a file with
-@lisp
-(setq org-export-with-LaTeX-fragments t)
-@end lisp
+@example
+#+STARTUP: latexpreview
+@end example
+
+To disable it, simply use
+
+@example
+#+STARTUP: nolatexpreview
+@end example
-@node CDLaTeX mode, , Previewing LaTeX fragments, Embedded LaTeX
-@subsection Using CDLa@TeX{} to enter math
-@cindex CDLa@TeX{}
+@node CDLaTeX mode, , Previewing @LaTeX{} fragments, Embedded @LaTeX{}
+@subsection Using CD@LaTeX{} to enter math
+@cindex CD@LaTeX{}
-CDLa@TeX{} mode is a minor mode that is normally used in combination with a
-major La@TeX{} mode like AUC@TeX{} in order to speed-up insertion of
+CD@LaTeX{} mode is a minor mode that is normally used in combination with a
+major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
environments and math templates. Inside Org mode, you can make use of
-some of the features of CDLa@TeX{} mode. You need to install
+some of the features of CD@LaTeX{} mode. You need to install
@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
-Don't use CDLa@TeX{} mode itself under Org mode, but use the light
+Don't use CD@LaTeX{} mode itself under Org mode, but use the light
version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it
-on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
+on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all
Org files with
@lisp
@end lisp
When this mode is enabled, the following features are present (for more
-details see the documentation of CDLa@TeX{} mode):
+details see the documentation of CD@LaTeX{} mode):
@itemize @bullet
@kindex C-c @{
@item
@item
@kindex @key{TAB}
The @key{TAB} key will do template expansion if the cursor is inside a
-La@TeX{} fragment@footnote{Org mode has a method to test if the cursor is
+@LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
inside such a fragment, see the documentation of the function
@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
environment abbreviations at the beginning of a line. For example, if
you write @samp{equ} at the beginning of a line and press @key{TAB},
this abbreviation will be expanded to an @code{equation} environment.
-To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
+To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}.
@item
@kindex _
@kindex ^
@vindex cdlatex-simplify-sub-super-scripts
-Pressing @kbd{_} and @kbd{^} inside a La@TeX{} fragment will insert these
+Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
characters together with a pair of braces. If you use @key{TAB} to move
out of the braces, and if the braces surround only a single character or
macro, they are removed again (depending on the variable
@item
@kindex `
Pressing the backquote @kbd{`} followed by a character inserts math
-macros, also outside La@TeX{} fragments. If you wait more than 1.5 seconds
+macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds
after the backquote, a help window will pop up.
@item
@kindex '
Pressing the single-quote @kbd{'} followed by another character modifies
the symbol before point with an accent or a font. If you wait more than
-1.5 seconds after the backquote, a help window will pop up. Character
-modification will work only inside La@TeX{} fragments, outside the quote
+1.5 seconds after the single-quote, a help window will pop up. Character
+modification will work only inside @LaTeX{} fragments; outside the quote
is normal.
@end itemize
+@node Special blocks, , Embedded @LaTeX{}, Markup
+@section Special blocks
+@cindex Special blocks
+
+Org syntax includes pre-defined blocks (@pxref{Paragraphs} and @ref{Literal
+examples}). It is also possible to create blocks containing raw code
+targeted at a specific back-ends (e.g., @samp{#+BEGIN_LATEX}).
+
+Any other block is a @emph{special block}.
+
+For example, @samp{#+BEGIN_ABSTRACT} and @samp{#+BEGIN_VIDEO} are special
+blocks. The first one is useful when exporting to @LaTeX{}, the second one
+when exporting to HTML5.
+
+Each export back-end decides if they should be exported, and how. When the
+block is ignored, its contents are still exported, as if the opening and
+closing block lines were not there. For example, when exporting a
+@samp{#+BEGIN_TEST} block, HTML back-end wraps its contents within a
+@samp{<div name="test">} tag.
+
+Refer to back-end specific documentation for more information.
+
@node Exporting, Publishing, Markup, Top
@chapter Exporting
@cindex exporting
-Org-mode documents can be exported into a variety of other formats. For
-printing and sharing of notes, ASCII export produces a readable and simple
-version of an Org file. HTML export allows you to publish a notes file on
-the web, while the XOXO format provides a solid base for exchange with a
-broad range of other applications. La@TeX{} export lets you use Org mode and
-its structured editing functions to easily create La@TeX{} files. DocBook
-export makes it possible to convert Org files to many other formats using
-DocBook tools. To incorporate entries with associated times like deadlines
-or appointments into a desktop calendar program like iCal, Org mode can also
-produce extracts in the iCalendar format. Currently Org mode only supports
-export, not import of these different formats.
-
-Org supports export of selected regions when @code{transient-mark-mode} is
-enabled (default in Emacs 23).
+The Org mode export facilities can be used to export Org documents or parts
+of Org documents to a variety of other formats. In addition, these
+facilities can be used with @code{orgtbl-mode} and/or @code{orgstruct-mode}
+in foreign buffers so you can author tables and lists in Org syntax and
+convert them in place to the target language.
+
+ASCII export produces a readable and simple version of an Org file for
+printing and sharing notes. HTML export allows you to easily publish notes
+on the web, or to build full-fledged websites. @LaTeX{} export lets you use
+Org mode and its structured editing functions to create arbitrarily complex
+@LaTeX{} files for any kind of document. OpenDocument Text (ODT) export
+allows seamless collaboration across organizational boundaries. Markdown
+export lets you seamlessly collaborate with other developers. Finally, iCal
+export can extract entries with deadlines or appointments to produce a file
+in the iCalendar format.
@menu
-* Selective export:: Using tags to select and exclude trees
-* Export options:: Per-file export settings
-* The export dispatcher:: How to access exporter commands
-* ASCII export:: Exporting to plain ASCII
+* The Export Dispatcher:: The main exporter interface
+* Export back-ends:: Built-in export formats
+* Export settings:: Generic export settings
+* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
+* Beamer export:: Exporting as a Beamer presentation
* HTML export:: Exporting to HTML
-* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF
-* DocBook export:: Exporting to DocBook
-* Freemind export:: Exporting to Freemind mind maps
-* XOXO export:: Exporting to XOXO
-* iCalendar export:: Exporting in iCalendar format
+* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
+* Markdown export:: Exporting to Markdown
+* OpenDocument Text export:: Exporting to OpenDocument Text
+* Org export:: Exporting to Org
+* iCalendar export:: Exporting to iCalendar
+* Other built-in back-ends:: Exporting to @code{Texinfo}, a man page, or Org
+* Export in foreign buffers:: Author tables in lists in Org syntax
+* Advanced configuration:: Fine-tuning the export output
@end menu
-@node Selective export, Export options, Exporting, Exporting
-@section Selective export
-@cindex export, selective by tags
-
-@vindex org-export-select-tags
-@vindex org-export-exclude-tags
-You may use tags to select the parts of a document that should be exported,
-or to exclude parts from export. This behavior is governed by two variables:
-@code{org-export-select-tags} and @code{org-export-exclude-tags}.
+@node The Export Dispatcher, Export back-ends, Exporting, Exporting
+@section The Export Dispatcher
+@vindex org-export-dispatch-use-expert-ui
+@cindex Export, dispatcher
+
+The main entry point for export related tasks is the dispatcher, a
+hierarchical menu from which it is possible to select an export format and
+toggle export options@footnote{It is also possible to use a less intrusive
+interface by setting @code{org-export-dispatch-use-expert-ui} to a
+non-@code{nil} value. In that case, only a prompt is visible from the
+minibuffer. From there one can still switch back to regular menu by pressing
+@key{?}.} from which it is possible to select an export format and to toggle
+export options.
+
+@c @quotation
+@table @asis
+@orgcmd{C-c C-e,org-export-dispatch}
-Org first checks if any of the @emph{select} tags is present in the buffer.
-If yes, all trees that do not carry one of these tags will be excluded. If a
-selected tree is a subtree, the heading hierarchy above it will also be
-selected for export, but not the text below those headings.
+Dispatch for export and publishing commands. When called with a @kbd{C-u}
+prefix argument, repeat the last export command on the current buffer while
+preserving toggled options. If the current buffer hasn't changed and subtree
+export was activated, the command will affect that same subtree.
+@end table
+@c @end quotation
-@noindent
-If none of the select tags is found, the whole buffer will be selected for
-export.
+Normally the entire buffer is exported, but if there is an active region
+only that part of the buffer will be exported.
-@noindent
-Finally, all subtrees that are marked by any of the @emph{exclude} tags will
-be removed from the export buffer.
+Several export options (@pxref{Export settings}) can be toggled from the
+export dispatcher with the following key combinations:
-@node Export options, The export dispatcher, Selective export, Exporting
-@section Export options
-@cindex options, for export
+@table @kbd
+@item C-a
+@vindex org-export-async-init-file
+Toggle asynchronous export. Asynchronous export uses an external Emacs
+process that is configured with a specified initialization file.
-@cindex completion, of option keywords
-The exporter recognizes special lines in the buffer which provide
-additional information. These lines may be put anywhere in the file.
-The whole set of lines can be inserted into the buffer with @kbd{C-c
-C-e t}. For individual lines, a good way to make sure the keyword is
-correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
-(@pxref{Completion}). For a summary of other in-buffer settings not
-specifically related to export, see @ref{In-buffer settings}.
-In particular, note that you can place commonly-used (export) options in
-a separate file which can be included using @code{#+SETUPFILE}.
+While exporting asynchronously, the output is not displayed. It is stored in
+a list called ``the export stack'', and can be viewed from there. The stack
+can be reached by calling the dispatcher with a double @kbd{C-u} prefix
+argument, or with @kbd{&} key from the dispatcher.
-@table @kbd
-@kindex C-c C-e t
-@item C-c C-e t
-Insert template with export options, see example below.
-@end table
+@vindex org-export-in-background
+To make this behavior the default, customize the variable
+@code{org-export-in-background}.
-@cindex #+TITLE
-@cindex #+AUTHOR
-@cindex #+DATE
-@cindex #+EMAIL
-@cindex #+DESCRIPTION
-@cindex #+KEYWORDS
-@cindex #+LANGUAGE
-@cindex #+TEXT
-@cindex #+OPTIONS
-@cindex #+BIND
-@cindex #+LINK_UP
-@cindex #+LINK_HOME
-@cindex #+EXPORT_SELECT_TAGS
-@cindex #+EXPORT_EXCLUDE_TAGS
-@cindex #+LATEX_HEADER
-@vindex user-full-name
-@vindex user-mail-address
-@vindex org-export-default-language
-@example
-#+TITLE: the title to be shown (default is the buffer name)
-#+AUTHOR: the author (default taken from @code{user-full-name})
-#+DATE: a date, fixed, of a format string for @code{format-time-string}
-#+EMAIL: his/her email address (default from @code{user-mail-address})
-#+DESCRIPTION: the page description, e.g. for the XHTML meta tag
-#+KEYWORDS: the page keywords, e.g. for the XHTML meta tag
-#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language})
-#+TEXT: Some descriptive text to be inserted at the beginning.
-#+TEXT: Several lines may be given.
-#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
-#+BIND: lisp-var lisp-val, e.g.: org-export-latex-low-levels itemize
- @r{You need to confirm using these, or configure @code{org-export-allow-BIND}}
-#+LINK_UP: the ``up'' link of an exported page
-#+LINK_HOME: the ``home'' link of an exported page
-#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@}
-#+EXPORT_SELECT_TAGS: Tags that select a tree for export
-#+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export
-@end example
+@item C-b
+Toggle body-only export. Its effect depends on the back-end used.
+Typically, if the back-end has a header section (like @code{<head>...</head>}
+in the HTML back-end), a body-only export will not include this header.
-@noindent
-The OPTIONS line is a compact@footnote{If you want to configure many options
-this way, you can use several OPTIONS lines.} form to specify export settings. Here
-you can:
-@cindex headline levels
-@cindex section-numbers
-@cindex table of contents
-@cindex line-break preservation
-@cindex quoted HTML tags
-@cindex fixed-width sections
-@cindex tables
-@cindex @TeX{}-like syntax for sub- and superscripts
-@cindex footnotes
-@cindex special strings
-@cindex emphasized text
-@cindex @TeX{} macros
-@cindex La@TeX{} fragments
-@cindex author info, in export
-@cindex time info, in export
-@example
-H: @r{set the number of headline levels for export}
-num: @r{turn on/off section-numbers}
-toc: @r{turn on/off table of contents, or set level limit (integer)}
-\n: @r{turn on/off line-break-preservation}
-@@: @r{turn on/off quoted HTML tags}
-:: @r{turn on/off fixed-width sections}
-|: @r{turn on/off tables}
-^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If}
- @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but}
- @r{the simple @code{a_b} will be left as it is.}
--: @r{turn on/off conversion of special strings.}
-f: @r{turn on/off footnotes like this[1].}
-todo: @r{turn on/off inclusion of TODO keywords into exported text}
-pri: @r{turn on/off priority cookies}
-tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}}
-<: @r{turn on/off inclusion of any time/date stamps like DEADLINES}
-*: @r{turn on/off emphasized text (bold, italic, underlined)}
-TeX: @r{turn on/off simple @TeX{} macros in plain text}
-LaTeX: @r{turn on/off La@TeX{} fragments}
-skip: @r{turn on/off skipping the text before the first heading}
-author: @r{turn on/off inclusion of author name/email into exported file}
-creator: @r{turn on/off inclusion of creator info into exported file}
-timestamp: @r{turn on/off inclusion creation time into exported file}
-d: @r{turn on/off inclusion of drawers}
-@end example
-@noindent
-These options take effect in both the HTML and La@TeX{} export, except
-for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and
-@code{nil} for the La@TeX{} export.
-
-When exporting only a single subtree by selecting it with @kbd{C-c @@} before
-calling an export command, the subtree can overrule some of the file's export
-settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE},
-@code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and
-@code{EXPORT_OPTIONS}.
-
-@node The export dispatcher, ASCII export, Export options, Exporting
-@section The export dispatcher
-@cindex dispatcher, for export commands
-
-All export commands can be reached using the export dispatcher, which is a
-prefix key that prompts for an additional key specifying the command.
-Normally the entire file is exported, but if there is an active region that
-contains one outline tree, the first heading is used as document title and
-the subtrees are exported.
+@item C-s
+@vindex org-export-initial-scope
+Toggle subtree export. The top heading becomes the document title.
-@table @kbd
-@kindex C-c C-e
-@item C-c C-e
-@vindex org-export-run-in-background
-Dispatcher for export and publishing commands. Displays a help-window
-listing the additional key(s) needed to launch an export or publishing
-command. The prefix arg is passed through to the exporter. A double prefix
-@kbd{C-u C-u} causes most commands to be executed in the background, in a
-separate Emacs process@footnote{To make this behavior the default, customize
-the variable @code{org-export-run-in-background}.}.
-@kindex C-c C-e v
-@item C-c C-e v
-Like @kbd{C-c C-e}, but only export the text that is currently visible
-(i.e. not hidden by outline visibility).
-@kindex C-u C-u C-c C-e
-@item C-u C-u C-c C-e
-@vindex org-export-run-in-background
-Call an the exporter, but reverse the setting of
-@code{org-export-run-in-background}, i.e. request background processing if
-not set, or force processing in the current Emacs process if set.
-@end table
-
-@node ASCII export, HTML export, The export dispatcher, Exporting
-@section ASCII export
-@cindex ASCII export
+You can change the default state of this option by setting
+@code{org-export-initial-scope}.
-ASCII export produces a simple and very readable version of an Org-mode
-file.
+@item C-v
+Toggle visible-only export. Only export the text that is currently
+visible, i.e. not hidden by outline visibility in the buffer.
-@cindex region, active
-@cindex active region
-@cindex transient-mark-mode
-@table @kbd
-@kindex C-c C-e a
-@item C-c C-e a
-@cindex property, EXPORT_FILE_NAME
-Export as ASCII file. For an Org file, @file{myfile.org}, the ASCII file
-will be @file{myfile.txt}. The file will be overwritten without
-warning. If there is an active region@footnote{This requires
-@code{transient-mark-mode} be turned on.}, only the region will be
-exported. If the selected region is a single tree@footnote{To select the
-current subtree, use @kbd{C-c @@}.}, the tree head will
-become the document title. If the tree head entry has or inherits an
-@code{EXPORT_FILE_NAME} property, that name will be used for the
-export.
-@kindex C-c C-e A
-@item C-c C-e A
-Export to a temporary buffer, do not create a file.
-@kindex C-c C-e v a
-@item C-c C-e v a
-Export only the visible part of the document.
@end table
-@cindex headline levels, for exporting
-In the exported version, the first 3 outline levels will become
-headlines, defining a general document structure. Additional levels
-will be exported as itemized lists. If you want that transition to occur
-at a different level, specify it with a prefix argument. For example,
+@vindex org-export-copy-to-kill-ring
+With the exception of asynchronous export, a successful export process writes
+its output to the kill-ring. You can configure this behavior by altering the
+option @code{org-export-copy-to-kill-ring}.
-@example
-@kbd{C-1 C-c C-e a}
-@end example
+@node Export back-ends, Export settings, The Export Dispatcher, Exporting
+@section Export back-ends
+@cindex Export, back-ends
-@noindent
-creates only top level headlines and does the rest as items. When
-headlines are converted to items, the indentation of the text following
-the headline is changed to fit nicely under the item. This is done with
-the assumption that the first body line indicates the base indentation of
-the body text. Any indentation larger than this is adjusted to preserve
-the layout relative to the first line. Should there be lines with less
-indentation than the first, these are left alone.
-
-@vindex org-export-ascii-links-to-notes
-Links will be exported in a footnote-like style, with the descriptive part in
-the text and the link in a note before the next heading. See the variable
-@code{org-export-ascii-links-to-notes} for details and other options.
-
-@node HTML export, LaTeX and PDF export, ASCII export, Exporting
-@section HTML export
-@cindex HTML export
+An export back-end is a library that translates Org syntax into a foreign
+format. An export format is not available until the proper back-end has been
+loaded.
-Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive
-HTML formatting, in ways similar to John Gruber's @emph{markdown}
-language, but with additional support for tables.
+@vindex org-export-backends
+By default, the following four back-ends are loaded: @code{ascii},
+@code{html}, @code{icalendar} and @code{latex}. It is possible to add more
+(or remove some) by customizing @code{org-export-backends}.
+
+Built-in back-ends include:
+
+@itemize
+@item ascii (ASCII format)
+@item beamer (@LaTeX{} Beamer format)
+@item html (HTML format)
+@item icalendar (iCalendar format)
+@item latex (@LaTeX{} format)
+@item man (Man page format)
+@item md (Markdown format)
+@item odt (OpenDocument Text format)
+@item org (Org format)
+@item texinfo (Texinfo format)
+@end itemize
-@menu
-* HTML Export commands:: How to invoke HTML export
-* Quoting HTML tags:: Using direct HTML in Org mode
-* Links in HTML export:: How links will be interpreted and formatted
-* Tables in HTML export:: How to modify the formatting of tables
-* Images in HTML export:: How to insert figures into HTML output
-* Text areas in HTML export:: An alternative way to show an example
-* CSS support:: Changing the appearance of the output
-* Javascript support:: Info and Folding in a web browser
-@end menu
+Other back-ends might be found in the @code{contrib/} directory
+(@pxref{Installation}).
-@node HTML Export commands, Quoting HTML tags, HTML export, HTML export
-@subsection HTML export commands
+@node Export settings, ASCII/Latin-1/UTF-8 export, Export back-ends, Exporting
+@section Export settings
+@cindex Export, settings
-@cindex region, active
-@cindex active region
-@cindex transient-mark-mode
-@table @kbd
-@kindex C-c C-e h
-@item C-c C-e h
-@cindex property, EXPORT_FILE_NAME
-Export as HTML file @file{myfile.html}. For an Org file @file{myfile.org},
-the ASCII file will be @file{myfile.html}. The file will be overwritten
-without warning. If there is an active region@footnote{This requires
-@code{transient-mark-mode} be turned on.}, only the region will be
-exported. If the selected region is a single tree@footnote{To select the
-current subtree, use @kbd{C-c @@}.}, the tree head will become the document
-title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
-property, that name will be used for the export.
-@kindex C-c C-e b
-@item C-c C-e b
-Export as HTML file and immediately open it with a browser.
-@kindex C-c C-e H
-@item C-c C-e H
-Export to a temporary buffer, do not create a file.
-@kindex C-c C-e R
-@item C-c C-e R
-Export the active region to a temporary buffer. With a prefix argument, do
-not produce the file header and footer, but just the plain HTML section for
-the region. This is good for cut-and-paste operations.
-@kindex C-c C-e v h
-@kindex C-c C-e v b
-@kindex C-c C-e v H
-@kindex C-c C-e v R
-@item C-c C-e v h
-@item C-c C-e v b
-@item C-c C-e v H
-@item C-c C-e v R
-Export only the visible part of the document.
-@item M-x org-export-region-as-html
-Convert the region to HTML under the assumption that it was Org-mode
-syntax before. This is a global command that can be invoked in any
-buffer.
-@item M-x org-replace-region-by-HTML
-Replace the active region (assumed to be in Org-mode syntax) by HTML
-code.
-@end table
+Export options can be set: globally with variables; for an individual file by
+making variables buffer-local with in-buffer settings (@pxref{In-buffer
+settings}), by setting individual keywords, or by specifying them in a
+compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
+properties (@pxref{Properties and Columns}). Options set at a specific level
+override options set at a more general level.
-@cindex headline levels, for exporting
-In the exported version, the first 3 outline levels will become headlines,
-defining a general document structure. Additional levels will be exported as
-itemized lists. If you want that transition to occur at a different level,
-specify it with a numeric prefix argument. For example,
+@cindex #+SETUPFILE
+In-buffer settings may appear anywhere in the file, either directly or
+indirectly through a file included using @samp{#+SETUPFILE: filename} syntax.
+Option keyword sets tailored to a particular back-end can be inserted from
+the export dispatcher (@pxref{The Export Dispatcher}) using the @code{Insert
+template} command by pressing @key{#}. To insert keywords individually,
+a good way to make sure the keyword is correct is to type @code{#+} and then
+to use @kbd{M-<TAB>} for completion.
-@example
-@kbd{C-2 C-c C-e b}
-@end example
+The export keywords available for every back-end, and their equivalent global
+variables, include:
-@noindent
-creates two levels of headings and does the rest as items.
+@table @samp
+@item AUTHOR
+@vindex user-full-name
+The document author (@code{user-full-name}).
+
+@item CREATOR
+@vindex org-export-creator-string
+Entity responsible for output generation (@code{org-export-creator-string}).
+
+@item DATE
+@vindex org-export-date-timestamp-format
+A date or a time-stamp@footnote{The variable
+@code{org-export-date-timestamp-format} defines how this time-stamp will be
+exported.}.
+
+@item DESCRIPTION
+The document description. Back-ends handle it as they see fit (e.g., for the
+XHTML meta tag), if at all. You can use several such keywords for long
+descriptions.
+
+@item EMAIL
+@vindex user-mail-address
+The email address (@code{user-mail-address}).
+
+@item KEYWORDS
+The keywords defining the contents of the document. Back-ends handle it as
+they see fit (e.g., for the XHTML meta tag), if at all. You can use several
+such keywords if the list is long.
+
+@item LANGUAGE
+@vindex org-export-default-language
+The language used for translating some strings
+(@code{org-export-default-language}). E.g., @samp{#+LANGUAGE: fr} will tell
+Org to translate @emph{File} (english) into @emph{Fichier} (french) in the
+clocktable.
+
+@item SELECT_TAGS
+@vindex org-export-select-tags
+The tags that select a tree for export (@code{org-export-select-tags}). The
+default value is @code{:export:}. Within a subtree tagged with
+@code{:export:}, you can still exclude entries with @code{:noexport:} (see
+below). When headlines are selectively exported with @code{:export:}
+anywhere in a file, text before the first headline is ignored.
+
+@item EXCLUDE_TAGS
+The tags that exclude a tree from export (@code{org-export-exclude-tags}).
+The default value is @code{:noexport:}. Entries with the @code{:noexport:}
+tag will be unconditionally excluded from the export, even if they have an
+@code{:export:} tag.
+
+@item TITLE
+The title to be shown (otherwise derived from buffer's name). You can use
+several such keywords for long titles.
+@end table
+
+The @code{#+OPTIONS} keyword is a compact@footnote{If you want to configure
+many options this way, you can use several @code{#+OPTIONS} lines.} form that
+recognizes the following arguments:
+
+@table @code
+@item ':
+@vindex org-export-with-smart-quotes
+Toggle smart quotes (@code{org-export-with-smart-quotes}).
+
+@item *:
+Toggle emphasized text (@code{org-export-with-emphasize}).
+
+@item -:
+@vindex org-export-with-special-strings
+Toggle conversion of special strings
+(@code{org-export-with-special-strings}).
+
+@item ::
+@vindex org-export-with-fixed-width
+Toggle fixed-width sections
+(@code{org-export-with-fixed-width}).
+
+@item <:
+@vindex org-export-with-timestamps
+Toggle inclusion of any time/date active/inactive stamps
+(@code{org-export-with-timestamps}).
+
+@item :
+@vindex org-export-preserve-breaks
+Toggle line-break-preservation (@code{org-export-preserve-breaks}).
+
+@item ^:
+@vindex org-export-with-sub-superscripts
+Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}",
+@samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
+it is (@code{org-export-with-sub-superscripts}).
+
+@item arch:
+@vindex org-export-with-archived-trees
+Configure export of archived trees. Can be set to @code{headline} to only
+process the headline, skipping its contents
+(@code{org-export-with-archived-trees}).
+
+@item author:
+@vindex org-export-with-author
+Toggle inclusion of author name into exported file
+(@code{org-export-with-author}).
+
+@item c:
+@vindex org-export-with-clocks
+Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
+
+@item creator:
+@vindex org-export-with-creator
+Configure inclusion of creator info into exported file. It may be set to
+@code{comment} (@code{org-export-with-creator}).
+
+@item d:
+@vindex org-export-with-drawers
+Toggle inclusion of drawers, or list drawers to include
+(@code{org-export-with-drawers}).
+
+@item e:
+@vindex org-export-with-entities
+Toggle inclusion of entities (@code{org-export-with-entities}).
+
+@item email:
+@vindex org-export-with-email
+Toggle inclusion of the author's e-mail into exported file
+(@code{org-export-with-email}).
+
+@item f:
+@vindex org-export-with-footnotes
+Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
+
+@item H:
+@vindex org-export-headline-levels
+Set the number of headline levels for export
+(@code{org-export-headline-levels}). Below that level, headlines are treated
+differently. In most back-ends, they become list items.
+
+@item inline:
+@vindex org-export-with-inlinetasks
+Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
+
+@item num:
+@vindex org-export-with-section-numbers
+Toggle section-numbers (@code{org-export-with-section-numbers}). It can also
+be set to a number @samp{n}, so only headlines at that level or above will be
+numbered.
+
+@item p:
+@vindex org-export-with-planning
+Toggle export of planning information (@code{org-export-with-planning}).
+``Planning information'' is the line containing the @code{SCHEDULED:}, the
+@code{DEADLINE:} or the @code{CLOSED:} cookies or a combination of them.
+
+@item pri:
+@vindex org-export-with-priority
+Toggle inclusion of priority cookies (@code{org-export-with-priority}).
+
+@item stat:
+@vindex org-export-with-statistics-cookies
+Toggle inclusion of statistics cookies
+(@code{org-export-with-statistics-cookies}).
+
+@item tags:
+@vindex org-export-with-tags
+Toggle inclusion of tags, may also be @code{not-in-toc}
+(@code{org-export-with-tags}).
+
+@item tasks:
+@vindex org-export-with-tasks
+Toggle inclusion of tasks (TODO items), can be @code{nil} to remove all
+tasks, @code{todo} to remove DONE tasks, or a list of keywords to keep
+(@code{org-export-with-tasks}).
+
+@item tex:
+@vindex org-export-with-latex
+Configure export of @LaTeX{} fragments and environments. It may be set to
+@code{verbatim} (@code{org-export-with-latex}).
+
+@item timestamp:
+@vindex org-export-time-stamp-file
+Toggle inclusion of the creation time into exported file
+(@code{org-export-time-stamp-file}).
+
+@item toc:
+@vindex org-export-with-toc
+Toggle inclusion of the table of contents, or set the level limit
+(@code{org-export-with-toc}).
+
+@item todo:
+@vindex org-export-with-todo-keywords
+Toggle inclusion of TODO keywords into exported text
+(@code{org-export-with-todo-keywords}).
+
+@item |:
+@vindex org-export-with-tables
+Toggle inclusion of tables (@code{org-export-with-tables}).
+@end table
+
+@cindex property, EXPORT_FILE_NAME
+When exporting only a subtree, each of the previous keywords@footnote{With
+the exception of @samp{SETUPFILE}.} can be overridden locally by special node
+properties. These begin with @samp{EXPORT_}, followed by the name of the
+keyword they supplant. For example, @samp{DATE} and @samp{OPTIONS} keywords
+become, respectively, @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS}
+properties. Subtree export also supports the self-explicit
+@samp{EXPORT_FILE_NAME} property@footnote{There is no buffer-wide equivalent
+for this property. The file name in this case is derived from the file
+associated to the buffer, if possible, or asked to the user otherwise.}.
+
+@cindex #+BIND
+@vindex org-export-allow-bind-keywords
+If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables
+can become buffer-local during export by using the BIND keyword. Its syntax
+is @samp{#+BIND: variable value}. This is particularly useful for in-buffer
+settings that cannot be changed using specific keywords.
+
+@node ASCII/Latin-1/UTF-8 export, Beamer export, Export settings, Exporting
+@section ASCII/Latin-1/UTF-8 export
+@cindex ASCII export
+@cindex Latin-1 export
+@cindex UTF-8 export
+
+ASCII export produces a simple and very readable version of an Org mode
+file, containing only plain ASCII@. Latin-1 and UTF-8 export augment the file
+with special characters and symbols available in these encodings.
+
+@vindex org-ascii-links-to-notes
+Links are exported in a footnote-like style, with the descriptive part in the
+text and the link in a note before the next heading. See the variable
+@code{org-ascii-links-to-notes} for details and other options.
+
+@subheading ASCII export commands
+
+@table @kbd
+@orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii}
+Export as an ASCII file. For an Org file, @file{myfile.org}, the ASCII file
+will be @file{myfile.txt}. The file will be overwritten without warning.
+When the original file is @file{myfile.txt}, the resulting file becomes
+@file{myfile.txt.txt} in order to prevent data loss.
+@orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii}
+Export to a temporary buffer. Do not create a file.
+@end table
+
+@subheading Header and sectioning structure
+
+In the exported version, the first three outline levels become headlines,
+defining a general document structure. Additional levels are exported as
+lists. The transition can also occur at a different level (@pxref{Export
+settings}).
+
+@subheading Quoting ASCII text
+
+You can insert text that will only appear when using @code{ASCII} back-end
+with the following constructs:
+
+@cindex #+ASCII
+@cindex #+BEGIN_ASCII
+@example
+Text @@@@ascii:and additional text@@@@ within a paragraph.
+
+#+ASCII: Some text
+
+#+BEGIN_ASCII
+All lines in this block will appear only when using this back-end.
+#+END_ASCII
+@end example
+
+@subheading ASCII specific attributes
+@cindex #+ATTR_ASCII
+@cindex horizontal rules, in ASCII export
+
+@code{ASCII} back-end only understands one attribute, @code{:width}, which
+specifies the length, in characters, of a given horizontal rule. It must be
+specified using an @code{ATTR_ASCII} line, directly preceding the rule.
+
+@example
+#+ATTR_ASCII: :width 10
+-----
+@end example
+
+@node Beamer export, HTML export, ASCII/Latin-1/UTF-8 export, Exporting
+@section Beamer export
+@cindex Beamer export
+
+The @LaTeX{} class @emph{Beamer} allows production of high quality
+presentations using @LaTeX{} and pdf processing. Org mode has special
+support for turning an Org mode file or tree into a Beamer presentation.
+
+@subheading Beamer export commands
+
+@table @kbd
+@orgcmd{C-c C-e l b,org-beamer-export-to-latex}
+Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{}
+file will be @file{myfile.tex}. The file will be overwritten without
+warning.
+@orgcmd{C-c C-e l B,org-beamer-export-as-latex}
+Export to a temporary buffer. Do not create a file.
+@orgcmd{C-c C-e l P,org-beamer-export-to-pdf}
+Export as @LaTeX{} and then process to PDF.
+@item C-c C-e l O
+Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
+@end table
+
+@subheading Sectioning, Frames and Blocks
+
+Any tree with not-too-deep level nesting should in principle be exportable as
+a Beamer presentation. Headlines fall into three categories: sectioning
+elements, frames and blocks.
+
+@itemize @minus
+@item
+@vindex org-beamer-frame-level
+Headlines become frames when their level is equal to
+@code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line
+(@pxref{Export settings}).
+
+@cindex property, BEAMER_ENV
+Though, if a headline in the current tree has a @code{BEAMER_ENV} property
+set to either to @code{frame} or @code{fullframe}, its level overrides the
+variable. A @code{fullframe} is a frame with an empty (ignored) title.
+
+@item
+@vindex org-beamer-environments-default
+@vindex org-beamer-environments-extra
+All frame's children become @code{block} environments. Special block types
+can be enforced by setting headline's @code{BEAMER_ENV} property@footnote{If
+this property is set, the entry will also get a @code{:B_environment:} tag to
+make this visible. This tag has no semantic meaning, it is only a visual
+aid.} to an appropriate value (see @code{org-beamer-environments-default} for
+supported values and @code{org-beamer-environments-extra} for adding more).
+
+@item
+@cindex property, BEAMER_REF
+As a special case, if the @code{BEAMER_ENV} property is set to either
+@code{appendix}, @code{note}, @code{noteNH} or @code{againframe}, the
+headline will become, respectively, an appendix, a note (within frame or
+between frame, depending on its level), a note with its title ignored or an
+@code{\againframe} command. In the latter case, a @code{BEAMER_REF} property
+is mandatory in order to refer to the frame being resumed, and contents are
+ignored.
+
+Also, a headline with an @code{ignoreheading} environment will have its
+contents only inserted in the output. This special value is useful to have
+data between frames, or to properly close a @code{column} environment.
+@end itemize
+
+@cindex property, BEAMER_ACT
+@cindex property, BEAMER_OPT
+Headlines also support @code{BEAMER_ACT} and @code{BEAMER_OPT} properties.
+The former is translated as an overlay/action specification, or a default
+overlay specification when enclosed within square brackets. The latter
+specifies options@footnote{The @code{fragile} option is added automatically
+if it contains code that requires a verbatim environment, though.} for the
+current frame or block. The export back-end will automatically wrap
+properties within angular or square brackets when appropriate.
+
+@cindex property, BEAMER_COL
+Moreover, headlines handle the @code{BEAMER_COL} property. Its value should
+be a decimal number representing the width of the column as a fraction of the
+total text width. If the headline has no specific environment, its title
+will be ignored and its contents will fill the column created. Otherwise,
+the block will fill the whole column and the title will be preserved. Two
+contiguous headlines with a non-@code{nil} @code{BEAMER_COL} value share the same
+@code{columns} @LaTeX{} environment. It will end before the next headline
+without such a property. This environment is generated automatically.
+Although, it can also be explicitly created, with a special @code{columns}
+value for @code{BEAMER_ENV} property (if it needs to be set up with some
+specific options, for example).
+
+@subheading Beamer specific syntax
+
+Beamer back-end is an extension of @LaTeX{} back-end. As such, all @LaTeX{}
+specific syntax (e.g., @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}) is
+recognized. See @ref{@LaTeX{} and PDF export} for more information.
+
+@cindex #+BEAMER_THEME
+@cindex #+BEAMER_COLOR_THEME
+@cindex #+BEAMER_FONT_THEME
+@cindex #+BEAMER_INNER_THEME
+@cindex #+BEAMER_OUTER_THEME
+Beamer export introduces a number of keywords to insert code in the
+document's header. Four control appearance of the presentation:
+@code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
+@code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
+@code{#+BEAMER_OUTER_THEME}. All of them accept optional arguments
+within square brackets. The last one, @code{#+BEAMER_HEADER}, is more
+generic and allows you to append any line of code in the header.
+
+@example
+#+BEAMER_THEME: Rochester [height=20pt]
+#+BEAMER_COLOR_THEME: spruce
+@end example
+
+Table of contents generated from @code{toc:t} @code{OPTION} keyword are
+wrapped within a @code{frame} environment. Those generated from a @code{TOC}
+keyword (@pxref{Table of contents}) are not. In that case, it is also
+possible to specify options, enclosed within square brackets.
+
+@example
+#+TOC: headlines [currentsection]
+@end example
+
+Beamer specific code can be inserted with the following constructs:
+
+@cindex #+BEAMER
+@cindex #+BEGIN_BEAMER
+@example
+#+BEAMER: \pause
+
+#+BEGIN_BEAMER
+All lines in this block will appear only when using this back-end.
+#+END_BEAMER
+
+Text @@@@beamer:some code@@@@ within a paragraph.
+@end example
+
+In particular, this last example can be used to add overlay specifications to
+objects whose type is among @code{bold}, @code{item}, @code{link},
+@code{radio-target} and @code{target}, when the value is enclosed within
+angular brackets and put at the beginning the object.
+
+@example
+A *@@@@beamer:<2->@@@@useful* feature
+@end example
+
+@cindex #+ATTR_BEAMER
+Eventually, every plain list has support for @code{:environment},
+@code{:overlay} and @code{:options} attributes through
+@code{ATTR_BEAMER} affiliated keyword. The first one allows the use
+of a different environment, the second sets overlay specifications and
+the last one inserts optional arguments in current list environment.
+
+@example
+#+ATTR_BEAMER: :overlay +-
+- item 1
+- item 2
+@end example
+
+@subheading Editing support
+
+You can turn on a special minor mode @code{org-beamer-mode} for faster
+editing with:
+
+@example
+#+STARTUP: beamer
+@end example
+
+@table @kbd
+@orgcmd{C-c C-b,org-beamer-select-environment}
+In @code{org-beamer-mode}, this key offers fast selection of a Beamer
+environment or the @code{BEAMER_COL} property.
+@end table
+
+Also, a template for useful in-buffer settings or properties can be inserted
+into the buffer with @kbd{M-x org-beamer-insert-options-template}. Among
+other things, this will install a column view format which is very handy for
+editing special properties used by Beamer.
+
+@subheading An example
+
+Here is a simple example Org document that is intended for Beamer export.
+
+@smallexample
+#+TITLE: Example Presentation
+#+AUTHOR: Carsten Dominik
+#+OPTIONS: H:2
+#+LATEX_CLASS: beamer
+#+LATEX_CLASS_OPTIONS: [presentation]
+#+BEAMER_THEME: Madrid
+#+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt)
+
+* This is the first structural section
+
+** Frame 1
+*** Thanks to Eric Fraga :B_block:BMCOL:
+ :PROPERTIES:
+ :BEAMER_COL: 0.48
+ :BEAMER_ENV: block
+ :END:
+ for the first viable Beamer setup in Org
+*** Thanks to everyone else :B_block:BMCOL:
+ :PROPERTIES:
+ :BEAMER_COL: 0.48
+ :BEAMER_ACT: <2->
+ :BEAMER_ENV: block
+ :END:
+ for contributing to the discussion
+**** This will be formatted as a beamer note :B_note:
+ :PROPERTIES:
+ :BEAMER_env: note
+ :END:
+** Frame 2 (where we will not use columns)
+*** Request
+ Please test this stuff!
+@end smallexample
+
+@node HTML export, @LaTeX{} and PDF export, Beamer export, Exporting
+@section HTML export
+@cindex HTML export
+
+Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive
+HTML formatting, in ways similar to John Gruber's @emph{markdown}
+language, but with additional support for tables.
+
+@menu
+* HTML Export commands:: How to invoke HTML export
+* HTML doctypes:: Org can export to various (X)HTML flavors
+* HTML preamble and postamble:: How to insert a preamble and a postamble
+* Quoting HTML tags:: Using direct HTML in Org mode
+* Links in HTML export:: How links will be interpreted and formatted
+* Tables in HTML export:: How to modify the formatting of tables
+* Images in HTML export:: How to insert figures into HTML output
+* Math formatting in HTML export:: Beautiful math also on the web
+* Text areas in HTML export:: An alternative way to show an example
+* CSS support:: Changing the appearance of the output
+* JavaScript support:: Info and Folding in a web browser
+@end menu
+
+@node HTML Export commands, HTML doctypes, HTML export, HTML export
+@subsection HTML export commands
+
+@table @kbd
+@orgcmd{C-c C-e h h,org-html-export-to-html}
+Export as an HTML file. For an Org file @file{myfile.org},
+the HTML file will be @file{myfile.html}. The file will be overwritten
+without warning.
+@kbd{C-c C-e h o}
+Export as an HTML file and immediately open it with a browser.
+@orgcmd{C-c C-e h H,org-html-export-as-html}
+Export to a temporary buffer. Do not create a file.
+@end table
+
+@c FIXME Exporting sublevels
+@c @cindex headline levels, for exporting
+@c In the exported version, the first 3 outline levels will become headlines,
+@c defining a general document structure. Additional levels will be exported as
+@c itemized lists. If you want that transition to occur at a different level,
+@c specify it with a numeric prefix argument. For example,
+
+@c @example
+@c @kbd{C-2 C-c C-e b}
+@c @end example
+
+@c @noindent
+@c creates two levels of headings and does the rest as items.
+
+@node HTML doctypes, HTML preamble and postamble, HTML Export commands, HTML export
+@subsection HTML doctypes
+@vindex org-html-doctype
+@vindex org-html-doctype-alist
+
+Org can export to various (X)HTML flavors.
+
+Setting the variable @code{org-html-doctype} allows you to export to different
+(X)HTML variants. The exported HTML will be adjusted according to the syntax
+requirements of that variant. You can either set this variable to a doctype
+string directly, in which case the exporter will try to adjust the syntax
+automatically, or you can use a ready-made doctype. The ready-made options
+are:
+
+@itemize
+@item
+``html4-strict''
+@item
+``html4-transitional''
+@item
+``html4-frameset''
+@item
+``xhtml-strict''
+@item
+``xhtml-transitional''
+@item
+``xhtml-frameset''
+@item
+``xhtml-11''
+@item
+``html5''
+@item
+``xhtml5''
+@end itemize
+
+See the variable @code{org-html-doctype-alist} for details. The default is
+``xhtml-strict''.
+
+@subsubheading Fancy HTML5 export
+@vindex org-html-html5-fancy
+@vindex org-html-html5-elements
+
+HTML5 introduces several new element types. By default, Org will not make
+use of these element types, but you can set @code{org-html-html5-fancy} to
+@code{t} (or set @code{html5-fancy} item in an @code{OPTIONS} line), to
+enable a few new block-level elements. These are created using arbitrary
+#+BEGIN and #+END blocks. For instance:
+
+@example
+#+BEGIN_ASIDE
+Lorem ipsum
+#+END_ASIDE
+@end example
+
+Will export to:
+
+@example
+<aside>
+ <p>Lorem ipsum</p>
+</aside>
+@end example
+
+While this:
+
+@example
+#+ATTR_HTML: :controls controls :width 350
+#+BEGIN_VIDEO
+#+HTML: <source src="movie.mp4" type="video/mp4">
+#+HTML: <source src="movie.ogg" type="video/ogg">
+Your browser does not support the video tag.
+#+END_VIDEO
+@end example
+
+Becomes:
+
+@example
+<video controls="controls" width="350">
+ <source src="movie.mp4" type="video/mp4">
+ <source src="movie.ogg" type="video/ogg">
+ <p>Your browser does not support the video tag.</p>
+</video>
+@end example
-@node Quoting HTML tags, Links in HTML export, HTML Export commands, HTML export
+Special blocks that do not correspond to HTML5 elements (see
+@code{org-html-html5-elements}) will revert to the usual behavior, i.e.,
+@code{#+BEGIN_LEDERHOSEN} will still export to @samp{<div class="lederhosen">}.
+
+Headlines cannot appear within special blocks. To wrap a headline and its
+contents in e.g., @samp{<section>} or @samp{<article>} tags, set the
+@code{HTML_CONTAINER} property on the headline itself.
+
+@node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export
+@subsection HTML preamble and postamble
+@vindex org-html-preamble
+@vindex org-html-postamble
+@vindex org-html-preamble-format
+@vindex org-html-postamble-format
+@vindex org-html-validation-link
+@vindex org-export-creator-string
+@vindex org-export-time-stamp-file
+
+The HTML exporter lets you define a preamble and a postamble.
+
+The default value for @code{org-html-preamble} is @code{t}, which means
+that the preamble is inserted depending on the relevant format string in
+@code{org-html-preamble-format}.
+
+Setting @code{org-html-preamble} to a string will override the default format
+string. If you set it to a function, it will insert the output of the
+function, which must be a string. Setting to @code{nil} will not insert any
+preamble.
+
+The default value for @code{org-html-postamble} is @code{'auto}, which means
+that the HTML exporter will look for information about the author, the email,
+the creator and the date, and build the postamble from these values. Setting
+@code{org-html-postamble} to @code{t} will insert the postamble from the
+relevant format string found in @code{org-html-postamble-format}. Setting it
+to @code{nil} will not insert any postamble.
+
+@node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export
@subsection Quoting HTML tags
Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
-@samp{>} in HTML export. If you want to include simple HTML tags
-which should be interpreted as such, mark them with @samp{@@} as in
-@samp{@@<b>bold text@@</b>}. Note that this really works only for
-simple tags. For more extensive HTML that should be copied verbatim to
-the exported file use either
+@samp{>} in HTML export. If you want to include raw HTML code, which
+should only appear in HTML export, mark it with @samp{@@@@html:} as in
+@samp{@@@@html:<b>@@@@bold text@@@@html:</b>@@@@}. For more extensive HTML
+that should be copied verbatim to the exported file use either
@cindex #+HTML
@cindex #+BEGIN_HTML
@cindex links, in HTML export
@cindex internal links, in HTML export
@cindex external links, in HTML export
-Internal links (@pxref{Internal links}) will continue to work in HTML. This
+Internal links (@pxref{Internal links}) will continue to work in HTML@. This
includes automatic links created by radio targets (@pxref{Radio
targets}). Links to external files will still work if the target file is on
the same @i{relative} path as the published Org file. Links to other
@cindex #+ATTR_HTML
@example
-#+ATTR_HTML: title="The Org-mode homepage" style="color:red;"
+#+ATTR_HTML: :title The Org mode homepage :style color:red;
[[http://orgmode.org]]
@end example
@node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export
@subsection Tables
@cindex tables, in HTML
-@vindex org-export-html-table-tag
+@vindex org-html-table-default-attributes
-Org-mode tables are exported to HTML using the table tag defined in
-@code{org-export-html-table-tag}. The default setting makes tables without
-cell borders and frame. If you would like to change this for individual
-tables, place something like the following before the table:
+Org mode tables are exported to HTML using the table attributes defined in
+@code{org-html-table-default-attributes}. The default setting makes tables
+without cell borders and frame. If you would like to change this for
+individual tables, place something like the following before the table:
@cindex #+CAPTION
@cindex #+ATTR_HTML
@example
#+CAPTION: This is a table with lines around and between cells
-#+ATTR_HTML: border="2" rules="all" frame="all"
+#+ATTR_HTML: :border 2 :rules all :frame border
@end example
-@node Images in HTML export, Text areas in HTML export, Tables in HTML export, HTML export
+@vindex org-html-table-row-tags
+You can also modify the default tags used for each row by setting
+@code{org-html-table-row-tags}. See the docstring for an example on
+how to use this option.
+
+@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export
@subsection Images in HTML export
@cindex images, inline in HTML
@cindex inlining images in HTML
-@vindex org-export-html-inline-images
+@vindex org-html-inline-images
HTML export can inline images given as links in the Org file, and
it can make an image the clickable part of a link. By
default@footnote{But see the variable
-@code{org-export-html-inline-images}.}, images are inlined if a link does
+@code{org-html-inline-images}.}, images are inlined if a link does
not have a description. So @samp{[[file:myimg.jpg]]} will be inlined,
while @samp{[[file:myimg.jpg][the image]]} will just produce a link
@samp{the image} that points to the image. If the description part
[[file:highres.jpg][file:thumb.jpg]]
@end example
-If you need to add attributes to an inlines image, use a @code{#+ATTR_HTML}.
+If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}.
In the example below we specify the @code{alt} and @code{title} attributes to
support text viewers and accessibility, and align it to the right.
@cindex #+ATTR_HTML
@example
#+CAPTION: A black cat stalking a spider
-#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"
+#+ATTR_HTML: :alt cat/spider image :title Action! :align right
[[./img/a.jpg]]
@end example
@noindent
-and you could use @code{http} addresses just as well.
+You could use @code{http} addresses just as well.
+
+@node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export
+@subsection Math formatting in HTML export
+@cindex MathJax
+@cindex dvipng
+@cindex imagemagick
+
+@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
+different ways on HTML pages. The default is to use the
+@uref{http://www.mathjax.org, MathJax system} which should work out of the
+box with Org mode installation because @uref{http://orgmode.org} serves
+@file{MathJax} for Org mode users for small applications and for testing
+purposes. @b{If you plan to use this regularly or on pages with significant
+page views, you should install@footnote{Installation instructions can be
+found on the MathJax website, see
+@uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on
+your own server in order to limit the load of our server.} To configure
+@file{MathJax}, use the variable @code{org-html-mathjax-options} or
+insert something like the following into the buffer:
+
+@example
+#+HTML_MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
+@end example
+
+@noindent See the docstring of the variable
+@code{org-html-mathjax-options} for the meaning of the parameters in
+this line.
+
+If you prefer, you can also request that @LaTeX{} fragments are processed
+into small images that will be inserted into the browser page. Before the
+availability of MathJax, this was the default method for Org files. This
+method requires that the @file{dvipng} program or @file{imagemagick} suite is
+available on your system. You can still get this processing with
+
+@example
+#+OPTIONS: tex:dvipng
+@end example
+
+or:
+
+@example
+#+OPTIONS: tex:imagemagick
+@end example
-@node Text areas in HTML export, CSS support, Images in HTML export, HTML export
+@node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export
@subsection Text areas in HTML export
@cindex text areas, in HTML
An alternative way to publish literal code examples in HTML is to use text
areas, where the example can even be edited before pasting it into an
-application. It is triggered by a @code{-t} switch at an @code{example} or
-@code{src} block. Using this switch disables any options for syntax and
-label highlighting, and line numbering, which may be present. You may also
-use @code{-h} and @code{-w} switches to specify the height and width of the
-text area, which default to the number of lines in the example, and 80,
-respectively. For example
-
-@example
-#+BEGIN_EXAMPLE -t -w 40
-(defun org-xor (a b)
- "Exclusive or."
- (if a (not b) b))
+application. It is triggered by @code{:textarea} attribute at an
+@code{example} or @code{src} block.
+
+You may also use @code{:height} and @code{:width} attributes to specify the
+height and width of the text area, which default to the number of lines in
+the example, and 80, respectively. For example
+
+@example
+#+ATTR_HTML: :textarea t :width 40
+#+BEGIN_EXAMPLE
+ (defun org-xor (a b)
+ "Exclusive or."
+ (if a (not b) b))
#+END_EXAMPLE
@end example
-@node CSS support, Javascript support, Text areas in HTML export, HTML export
+@node CSS support, JavaScript support, Text areas in HTML export, HTML export
@subsection CSS support
@cindex CSS, for HTML export
@cindex HTML export, CSS
-@vindex org-export-html-todo-kwd-class-prefix
-@vindex org-export-html-tag-class-prefix
-You can also give style information for the exported file. The HTML exporter
-assigns the following special CSS classes@footnote{If the classes on TODO
-keywords and tags lead to conflicts, use the variables
-@code{org-export-html-todo-kwd-class-prefix} and
-@code{org-export-html-tag-class-prefix} to make them unique.} to appropriate
-parts of the document---your style specifications may change these, in
-addition to any of the standard classes like for headlines, tables, etc.
+@vindex org-html-todo-kwd-class-prefix
+@vindex org-html-tag-class-prefix
+You can modify the CSS style definitions for the exported file. The HTML
+exporter assigns the following special CSS classes@footnote{If the classes on
+TODO keywords and tags lead to conflicts, use the variables
+@code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to
+make them unique.} to appropriate parts of the document---your style
+specifications may change these, in addition to any of the standard classes
+like for headlines, tables, etc.
@example
p.author @r{author information, including email}
p.date @r{publishing date}
-p.creator @r{creator info, about org-mode version}
+p.creator @r{creator info, about org mode version}
.title @r{document title}
.todo @r{TODO keywords, all not-done states}
-.done @r{the DONE keywords, all stated the count as done}
+.done @r{the DONE keywords, all states that count as done}
.WAITING @r{each TODO keyword also uses a class named after itself}
.timestamp @r{timestamp}
.timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED}
div.outline-N @r{div for outline level N (headline plus text))}
div.outline-text-N @r{extra div for text at outline level N}
.section-number-N @r{section number in headlines, different for each level}
+.figure-number @r{label like "Figure 1:"}
+.table-number @r{label like "Table 1:"}
+.listing-number @r{label like "Listing 1:"}
div.figure @r{how to format an inlined image}
pre.src @r{formatted source code}
pre.example @r{normal example}
.footnum @r{footnote number in footnote definition (always <sup>)}
@end example
-@vindex org-export-html-style-default
-@vindex org-export-html-style-include-default
-@vindex org-export-html-style
-@vindex org-export-html-extra
-@vindex org-export-html-style-default
+@vindex org-html-style-default
+@vindex org-html-head-include-default-style
+@vindex org-html-head
+@vindex org-html-head-extra
+@cindex #+HTML_INCLUDE_STYLE
Each exported file contains a compact default style that defines these
classes in a basic way@footnote{This style is defined in the constant
-@code{org-export-html-style-default}, which you should not modify. To turn
+@code{org-html-style-default}, which you should not modify. To turn
inclusion of these defaults off, customize
-@code{org-export-html-style-include-default}}. You may overwrite these
-settings, or add to them by using the variables @code{org-export-html-style}
-(for Org-wide settings) and @code{org-export-html-style-extra} (for more
-granular settings, like file-local settings). To set the latter variable
-individually for each file, you can use
-
-@cindex #+STYLE
+@code{org-html-head-include-default-style} or set @code{html-style} to
+@code{nil} in an @code{OPTIONS} line.}. You may overwrite these settings, or
+add to them by using the variables @code{org-html-head} and
+@code{org-html-head-extra}. You can override the global values of these
+variables for each file by using these keywords:
+
+@cindex #+HTML_HEAD
+@cindex #+HTML_HEAD_EXTRA
@example
-#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
+#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
+#+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
@end example
@noindent
directly write a @code{<style>} @code{</style>} section in this way, without
referring to an external file.
+In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:}
+property to assign a class to the tree. In order to specify CSS styles for a
+particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
+property.
+
@c FIXME: More about header and footer styles
@c FIXME: Talk about links and targets.
-@node Javascript support, , CSS support, HTML export
-@subsection Javascript supported display of web pages
+@node JavaScript support, , CSS support, HTML export
+@subsection JavaScript supported display of web pages
@cindex Rose, Sebastian
Sebastian Rose has written a JavaScript program especially designed to
view type is a @emph{folding} view much like Org provides inside Emacs. The
script is available at @url{http://orgmode.org/org-info.js} and you can find
the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}.
-We host the script at our site, but if you use it a lot, you might
-not want to be dependent on @url{orgmode.org} and prefer to install a local
+We host the script at our site, but if you use it a lot, you might not want
+to be dependent on @url{http://orgmode.org} and prefer to install a local
copy on your own web server.
-To use the script, you need to make sure that the @file{org-jsinfo.el} module
-gets loaded. It should be loaded by default, but you can try @kbd{M-x
-customize-variable @key{RET} org-modules @key{RET}} to convince yourself that
-this is indeed the case. All it then takes to make use of the program is
-adding a single line to the Org file:
+All it then takes to use this program is adding a single line to the Org
+file:
@cindex #+INFOJS_OPT
@example
path: @r{The path to the script. The default is to grab the script from}
@r{@url{http://orgmode.org/org-info.js}, but you might want to have}
@r{a local copy and use a path like @samp{../scripts/org-info.js}.}
-view: @r{Initial view when website is first shown. Possible values are:}
+view: @r{Initial view when the website is first shown. Possible values are:}
info @r{Info-like interface with one section per page.}
overview @r{Folding interface, initially showing only top-level.}
content @r{Folding interface, starting with all headlines visible.}
@r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
@r{If this is smaller than in @code{org-export-headline-levels}, each}
@r{info/folding section can still contain child headlines.}
-toc: @r{Should the table of content @emph{initially} be visible?}
+toc: @r{Should the table of contents @emph{initially} be visible?}
@r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
tdepth: @r{The depth of the table of contents. The defaults are taken from}
@r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
-ftoc: @r{Does the css of the page specify a fixed position for the "toc"?}
+ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?}
@r{If yes, the toc will never be displayed as a section.}
ltoc: @r{Should there be short contents (children) in each section?}
@r{Make this @code{above} if the section should be above initial text.}
@r{default), only one such button will be present.}
@end example
@noindent
-@vindex org-infojs-options
-@vindex org-export-html-use-infojs
+@vindex org-html-infojs-options
+@vindex org-html-use-infojs
You can choose default values for these options by customizing the variable
-@code{org-infojs-options}. If you always want to apply the script to your
-pages, configure the variable @code{org-export-html-use-infojs}.
+@code{org-html-infojs-options}. If you always want to apply the script to your
+pages, configure the variable @code{org-html-use-infojs}.
-@node LaTeX and PDF export, DocBook export, HTML export, Exporting
-@section La@TeX{} and PDF export
-@cindex La@TeX{} export
+@node @LaTeX{} and PDF export, Markdown export, HTML export, Exporting
+@section @LaTeX{} and PDF export
+@cindex @LaTeX{} export
@cindex PDF export
-@cindex Guerry, Bastien
-Org mode contains a La@TeX{} exporter written by Bastien Guerry. With
-further processing, this backend is also used to produce PDF output. Since
-the La@TeX{} output uses @file{hyperref} to implement links and cross
-references, the PDF output file will be fully linked.
+@LaTeX{} export can produce an arbitrarily complex LaTeX document of any
+standard or custom document class. With further processing@footnote{The
+default @LaTeX{} output is designed for processing with @code{pdftex} or
+@LaTeX{}. It includes packages that are not compatible with @code{xetex} and
+possibly @code{luatex}. The @LaTeX{} exporter can be configured to support
+alternative TeX engines, see the options
+@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.},
+which the @LaTeX{} exporter is able to control, this back-end is able to
+produce PDF output. Because the @LaTeX{} exporter can be configured to use
+the @code{hyperref} package, the default setup produces fully-linked PDF
+output.
+
+As in @LaTeX{}, blank lines are meaningful for this back-end: a paragraph
+will not be started if two contiguous syntactical elements are not separated
+by an empty line.
+
+This back-end also offers enhanced support for footnotes. Thus, it handles
+nested footnotes, footnotes in tables and footnotes in a list item's
+description.
@menu
-* LaTeX/PDF export commands:: Which key invokes which commands
-* Quoting LaTeX code:: Incorporating literal La@TeX{} code
-* Sectioning structure:: Changing sectioning in La@TeX{} output
-* Tables in LaTeX export:: Options for exporting tables to La@TeX{}
-* Images in LaTeX export:: How to insert figures into La@TeX{} output
+* @LaTeX{} export commands:: How to export to LaTeX and PDF
+* Header and sectioning:: Setting up the export file structure
+* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code
+* @LaTeX{} specific attributes:: Controlling @LaTeX{} output
@end menu
-@node LaTeX/PDF export commands, Quoting LaTeX code, LaTeX and PDF export, LaTeX and PDF export
-@subsection La@TeX{} export commands
+@node @LaTeX{} export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export
+@subsection @LaTeX{} export commands
-@cindex region, active
-@cindex active region
-@cindex transient-mark-mode
@table @kbd
-@kindex C-c C-e l
-@item C-c C-e l
-@cindex property EXPORT_FILE_NAME
-Export as La@TeX{} file @file{myfile.tex}. For an Org file
-@file{myfile.org}, the ASCII file will be @file{myfile.tex}. The file will
-be overwritten without warning. If there is an active region@footnote{This
-requires @code{transient-mark-mode} be turned on.}, only the region will be
-exported. If the selected region is a single tree@footnote{To select the
-current subtree, use @kbd{C-c @@}.}, the tree head will become the document
-title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME}
-property, that name will be used for the export.
-@kindex C-c C-e L
-@item C-c C-e L
-Export to a temporary buffer, do not create a file.
-@kindex C-c C-e v l
-@kindex C-c C-e v L
-@item C-c C-e v l
-@item C-c C-e v L
-Export only the visible part of the document.
-@item M-x org-export-region-as-latex
-Convert the region to La@TeX{} under the assumption that it was Org mode
-syntax before. This is a global command that can be invoked in any
-buffer.
-@item M-x org-replace-region-by-latex
-Replace the active region (assumed to be in Org mode syntax) by La@TeX{}
-code.
-@kindex C-c C-e p
-@item C-c C-e p
-Export as La@TeX{} and then process to PDF.
-@kindex C-c C-e d
-@item C-c C-e d
-Export as La@TeX{} and then process to PDF, then open the resulting PDF file.
+@orgcmd{C-c C-e l l,org-latex-export-to-latex}
+Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{}
+file will be @file{myfile.tex}. The file will be overwritten without
+warning.
+@orgcmd{C-c C-e l L,org-latex-export-as-latex}
+Export to a temporary buffer. Do not create a file.
+@orgcmd{C-c C-e l p,org-latex-export-to-pdf}
+Export as @LaTeX{} and then process to PDF.
+@item C-c C-e l o
+Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
@end table
-@cindex headline levels, for exporting
-@vindex org-latex-low-levels
-In the exported version, the first 3 outline levels will become
-headlines, defining a general document structure. Additional levels
-will be exported as description lists. The exporter can ignore them or
-convert them to a custom string depending on
-@code{org-latex-low-levels}.
+@node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{} export commands, @LaTeX{} and PDF export
+@subsection Header and sectioning structure
+@cindex @LaTeX{} class
+@cindex @LaTeX{} sectioning structure
+@cindex @LaTeX{} header
+@cindex header, for @LaTeX{} files
+@cindex sectioning structure, for @LaTeX{} export
+
+By default, the first three outline levels become headlines, defining a
+general document structure. Additional levels are exported as @code{itemize}
+or @code{enumerate} lists. The transition can also occur at a different
+level (@pxref{Export settings}).
+
+By default, the @LaTeX{} output uses the class @code{article}.
+
+@vindex org-latex-default-class
+@vindex org-latex-classes
+@vindex org-latex-default-packages-alist
+@vindex org-latex-packages-alist
+You can change this globally by setting a different value for
+@code{org-latex-default-class} or locally by adding an option like
+@code{#+LATEX_CLASS: myclass} in your file, or with
+a @code{EXPORT_LATEX_CLASS} property that applies when exporting a region
+containing only this (sub)tree. The class must be listed in
+@code{org-latex-classes}. This variable defines a header template for each
+class@footnote{Into which the values of
+@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}
+are spliced.}, and allows you to define the sectioning structure for each
+class. You can also define your own classes there.
+
+@cindex #+LATEX_CLASS
+@cindex #+LATEX_CLASS_OPTIONS
+@cindex property, EXPORT_LATEX_CLASS
+@cindex property, EXPORT_LATEX_CLASS_OPTIONS
+The @code{LATEX_CLASS_OPTIONS} keyword or @code{EXPORT_LATEX_CLASS_OPTIONS}
+property can specify the options for the @code{\documentclass} macro. These
+options have to be provided, as expected by @LaTeX{}, within square brackets.
+
+@cindex #+LATEX_HEADER
+@cindex #+LATEX_HEADER_EXTRA
+You can also use the @code{LATEX_HEADER} and
+@code{LATEX_HEADER_EXTRA}@footnote{Unlike @code{LATEX_HEADER}, contents
+from @code{LATEX_HEADER_EXTRA} keywords will not be loaded when previewing
+@LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).} keywords in order
+to add lines to the header. See the docstring of @code{org-latex-classes} for
+more information.
-If you want that transition to occur at a different level, specify it
-with a numeric prefix argument. For example,
+An example is shown below.
@example
-@kbd{C-2 C-c C-e l}
-@end example
+#+LATEX_CLASS: article
+#+LATEX_CLASS_OPTIONS: [a4paper]
+#+LATEX_HEADER: \usepackage@{xyz@}
-@noindent
-creates two levels of headings and does the rest as items.
+* Headline 1
+ some text
+@end example
-@node Quoting LaTeX code, Sectioning structure, LaTeX/PDF export commands, LaTeX and PDF export
-@subsection Quoting La@TeX{} code
+@node Quoting @LaTeX{} code, @LaTeX{} specific attributes, Header and sectioning, @LaTeX{} and PDF export
+@subsection Quoting @LaTeX{} code
-Embedded La@TeX{} as described in @ref{Embedded LaTeX}, will be correctly
-inserted into the La@TeX{} file. This includes simple macros like
-@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore,
-you can add special code that should only be present in La@TeX{} export with
-the following constructs:
+Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly
+inserted into the @LaTeX{} file. Furthermore, you can add special code that
+should only be present in @LaTeX{} export with the following constructs:
-@cindex #+LaTeX
-@cindex #+BEGIN_LaTeX
+@cindex #+LATEX
+@cindex #+BEGIN_LATEX
@example
-#+LaTeX: Literal LaTeX code for export
-@end example
+Code within @@@@latex:some code@@@@ a paragraph.
-@noindent or
-@cindex #+BEGIN_LaTeX
+#+LATEX: Literal @LaTeX{} code for export
-@example
-#+BEGIN_LaTeX
+#+BEGIN_LATEX
All lines between these markers are exported literally
-#+END_LaTeX
+#+END_LATEX
@end example
-@node Sectioning structure, Tables in LaTeX export, Quoting LaTeX code, LaTeX and PDF export
-@subsection Sectioning structure
-@cindex La@TeX{} class
-@cindex La@TeX{} sectioning structure
+@node @LaTeX{} specific attributes, , Quoting @LaTeX{} code, @LaTeX{} and PDF export
+@subsection @LaTeX{} specific attributes
+@cindex #+ATTR_LATEX
-By default, the La@TeX{} output uses the class @code{article}.
+@LaTeX{} understands attributes specified in an @code{ATTR_LATEX} line. They
+affect tables, images, plain lists, special blocks and source blocks.
-@vindex org-export-latex-default-class
-@vindex org-export-latex-classes
-@cindex #+LATEX_HEADER
-@cindex #+LATEX_CLASS
-@cindex property, LATEX_CLASS
-You can change this globally by setting a different value for
-@code{org-export-latex-default-class} or locally by adding an option like
-@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:}
-property that applies when exporting a region containing only this (sub)tree.
-The class should be listed in @code{org-export-latex-classes}, where you can
-also define the sectioning structure for each class, as well as defining
-additional classes. You can also use @code{#+LATEX_HEADER:
-\usepackage@{xyz@}} to add lines to the header.
-
-@node Tables in LaTeX export, Images in LaTeX export, Sectioning structure, LaTeX and PDF export
-@subsection Tables in La@TeX{} export
-@cindex tables, in La@TeX{} export
-
-For La@TeX{} export of a table, you can specify a label and a caption
-(@pxref{Images and tables}). You can also use the @code{ATTR_LaTeX} line to
-request a longtable environment for the table, so that it may span several
-pages. Finally, you can set the alignment string:
+@subsubheading Tables in @LaTeX{} export
+@cindex tables, in @LaTeX{} export
+
+For @LaTeX{} export of a table, you can specify a label and a caption
+(@pxref{Images and tables}). You can also use attributes to control table
+layout and contents. Valid @LaTeX{} attributes include:
+
+@table @code
+@item :mode
+@vindex org-latex-default-table-mode
+Nature of table's contents. It can be set to @code{table}, @code{math},
+@code{inline-math} or @code{verbatim}. In particular, when in @code{math} or
+@code{inline-math} mode, every cell is exported as-is, horizontal rules are
+ignored and the table will be wrapped in a math environment. Also,
+contiguous tables sharing the same math mode will be wrapped within the same
+environment. Default mode is determined in
+@code{org-latex-default-table-mode}.
+@item :environment
+@vindex org-latex-default-table-environment
+Environment used for the table. It can be set to any @LaTeX{} table
+environment, like @code{tabularx}@footnote{Requires adding the
+@code{tabularx} package to @code{org-latex-packages-alist}.},
+@code{longtable}, @code{array}, @code{tabu}@footnote{Requires adding the
+@code{tabu} package to @code{org-latex-packages-alist}.},
+@code{bmatrix}@enddots{} It defaults to
+@code{org-latex-default-table-environment} value.
+@item :caption
+@code{#+CAPTION} keyword is the simplest way to set a caption for a table
+(@pxref{Images and tables}). If you need more advanced commands for that
+task, you can use @code{:caption} attribute instead. Its value should be raw
+@LaTeX{} code. It has precedence over @code{#+CAPTION}.
+@item :float
+@itemx :placement
+Float environment for the table. Possible values are @code{sidewaystable},
+@code{multicolumn}, @code{t} and @code{nil}. When unspecified, a table with
+a caption will have a @code{table} environment. Moreover, @code{:placement}
+attribute can specify the positioning of the float.
+@item :align
+@itemx :font
+@itemx :width
+Set, respectively, the alignment string of the table, its font size and its
+width. They only apply on regular tables.
+@item :spread
+Boolean specific to the @code{tabu} and @code{longtabu} environments, and
+only takes effect when used in conjunction with the @code{:width} attribute.
+When @code{:spread} is non-@code{nil}, the table will be spread or shrunk by the
+value of @code{:width}.
+@item :booktabs
+@itemx :center
+@itemx :rmlines
+@vindex org-latex-tables-booktabs
+@vindex org-latex-tables-centered
+They toggle, respectively, @code{booktabs} usage (assuming the package is
+properly loaded), table centering and removal of every horizontal rule but
+the first one (in a "table.el" table only). In particular,
+@code{org-latex-tables-booktabs} (respectively @code{org-latex-tables-centered})
+activates the first (respectively second) attribute globally.
+@item :math-prefix
+@itemx :math-suffix
+@itemx :math-arguments
+A string that will be inserted, respectively, before the table within the
+math environment, after the table within the math environment, and between
+the macro name and the contents of the table. The @code{:math-arguments}
+attribute is used for matrix macros that require more than one argument
+(e.g., @code{qbordermatrix}).
+@end table
+
+Thus, attributes can be used in a wide array of situations, like writing
+a table that will span over multiple pages, or a matrix product:
+
+@example
+#+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l
+| ..... | ..... |
+| ..... | ..... |
+
+#+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
+| a | b |
+| c | d |
+#+ATTR_LATEX: :mode math :environment bmatrix
+| 1 | 2 |
+| 3 | 4 |
+@end example
+
+In the example below, @LaTeX{} command
+@code{\bicaption@{HeadingA@}@{HeadingB@}} will set the caption.
-@cindex #+CAPTION
-@cindex #+LABEL
-@cindex #+ATTR_LaTeX
@example
-#+CAPTION: A long table
-#+LABEL: tbl:long
-#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l
+#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
| ..... | ..... |
| ..... | ..... |
@end example
-@node Images in LaTeX export, , Tables in LaTeX export, LaTeX and PDF export
-@subsection Images in La@TeX{} export
-@cindex images, inline in La@TeX{}
-@cindex inlining images in La@TeX{}
+@subsubheading Images in @LaTeX{} export
+@cindex images, inline in @LaTeX{}
+@cindex inlining images in @LaTeX{}
Images that are linked to without a description part in the link, like
@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF
-output file resulting from La@TeX{} processing. Org will use an
-@code{\includegraphics} macro to insert the image. If you have specified a
-caption and/or a label as described in @ref{Images and tables}, the figure
-will be wrapped into a @code{figure} environment and thus become a floating
-element. You can use an @code{#+ATTR_LaTeX:} line to specify the various
-options that can be used in the optional argument of the
-@code{\includegraphics} macro. To modify the placement option of the
-@code{figure} environment, add something like @samp{placement=[h!]} to the
-Attributes.
-
-If you'd like to let text flow around the image, add the word @samp{wrap} to
-the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left
-half of the page. To fine-tune, the @code{placement} field will be the
-set of additional arguments needed by the @code{wrapfigure} environment.
-Note that if you change the size of the image, you need to use compatible
-settings for @code{\includegraphics} and @code{wrapfigure}.
+output file resulting from @LaTeX{} processing. Org will use an
+@code{\includegraphics} macro to insert the image@footnote{In the case of
+TikZ (@url{http://sourceforge.net/projects/pgf/}) images, it will become an
+@code{\input} macro wrapped within a @code{tikzpicture} environment.}.
+
+You can specify specify image width or height with, respectively,
+@code{:width} and @code{:height} attributes. It is also possible to add any
+other option with the @code{:options} attribute, as shown in the following
+example:
-@cindex #+CAPTION
-@cindex #+LABEL
-@cindex #+ATTR_LaTeX
@example
-#+CAPTION: The black-body emission of the disk around HR 4049
-#+LABEL: fig:SED-HR4049
-#+ATTR_LaTeX: width=5cm,angle=90
+#+ATTR_LATEX: :width 5cm :options angle=90
[[./img/sed-hr4049.pdf]]
-
-#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@}
-[[./img/hst.png]]
@end example
-If you need references to a label created in this way, write
-@samp{\ref@{fig:SED-HR4049@}} just like in La@TeX{}.
+If you need a specific command for the caption, use @code{:caption}
+attribute. It will override standard @code{#+CAPTION} value, if any.
-@node DocBook export, Freemind export, LaTeX and PDF export, Exporting
-@section DocBook export
-@cindex DocBook export
-@cindex PDF export
-@cindex Cui, Baoqui
+@example
+#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
+[[./img/sed-hr4049.pdf]]
+@end example
+
+If you have specified a caption as described in @ref{Images and tables}, the
+picture will be wrapped into a @code{figure} environment and thus become
+a floating element. You can also ask Org to export an image as a float
+without specifying caption by setting the @code{:float} attribute. You may
+also set it to:
+@itemize @minus
+@item
+@code{t}: if you want to use the standard @samp{figure} environment. It is
+used by default if you provide a caption to the image.
+@item
+@code{multicolumn}: if you wish to include an image which spans multiple
+columns in a page. This will export the image wrapped in a @code{figure*}
+environment.
+@item
+@code{wrap}: if you would like to let text flow around the image. It will
+make the figure occupy the left half of the page.
+@item
+@code{nil}: if you need to avoid any floating environment, even when
+a caption is provided.
+@end itemize
+@noindent
+To modify the placement option of any floating environment, set the
+@code{placement} attribute.
+
+@example
+#+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@}
+[[./img/hst.png]]
+@end example
+
+If the @code{:comment-include} attribute is set to a non-@code{nil} value,
+the @LaTeX{} @code{\includegraphics} macro will be commented out.
+
+@subsubheading Plain lists in @LaTeX{} export
+@cindex plain lists, in @LaTeX{} export
+
+Plain lists accept two optional attributes: @code{:environment} and
+@code{:options}. The first one allows the use of a non-standard
+environment (e.g., @samp{inparaenum}). The second one specifies
+optional arguments for that environment (square brackets may be
+omitted).
+
+@example
+#+ATTR_LATEX: :environment compactitem :options $\circ$
+- you need ``paralist'' package to reproduce this example.
+@end example
+
+@subsubheading Source blocks in @LaTeX{} export
+@cindex source blocks, in @LaTeX{} export
+
+In addition to syntax defined in @ref{Literal examples}, names and captions
+(@pxref{Images and tables}), source blocks also accept a @code{:float}
+attribute. You may set it to:
+@itemize @minus
+@item
+@code{t}: if you want to make the source block a float. It is the default
+value when a caption is provided.
+@item
+@code{multicolumn}: if you wish to include a source block which spans multiple
+columns in a page.
+@item
+@code{nil}: if you need to avoid any floating environment, even when a caption
+is provided. It is useful for source code that may not fit in a single page.
+@end itemize
+
+@example
+#+ATTR_LATEX: :float nil
+#+BEGIN_SRC emacs-lisp
+Code that may not fit in a single page.
+#+END_SRC
+@end example
+
+@subsubheading Special blocks in @LaTeX{} export
+@cindex special blocks, in @LaTeX{} export
+@cindex abstract, in @LaTeX{} export
+@cindex proof, in @LaTeX{} export
+
+In @LaTeX{} back-end, special blocks become environments of the same name.
+Value of @code{:options} attribute will be appended as-is to that
+environment's opening string. For example:
+
+@example
+#+BEGIN_ABSTRACT
+We demonstrate how to solve the Syracuse problem.
+#+END_ABSTRACT
+
+#+ATTR_LATEX: :options [Proof of important theorem]
+#+BEGIN_PROOF
+...
+Therefore, any even number greater than 2 is the sum of two primes.
+#+END_PROOF
+@end example
+
+@noindent
+becomes
+
+@example
+\begin@{abstract@}
+We demonstrate how to solve the Syracuse problem.
+\end@{abstract@}
+
+\begin@{proof@}[Proof of important theorem]
+...
+Therefore, any even number greater than 2 is the sum of two primes.
+\end@{proof@}
+@end example
+
+If you need to insert a specific caption command, use @code{:caption}
+attribute. It will override standard @code{#+CAPTION} value, if any. For
+example:
+
+@example
+#+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
+#+BEGIN_PROOF
+...
+#+END_PROOF
+@end example
+
+@subsubheading Horizontal rules
+@cindex horizontal rules, in @LaTeX{} export
+
+Width and thickness of a given horizontal rule can be controlled with,
+respectively, @code{:width} and @code{:thickness} attributes:
+
+@example
+#+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
+-----
+@end example
+
+@node Markdown export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting
+@section Markdown export
+@cindex Markdown export
+
+@code{md} export back-end generates Markdown syntax@footnote{Vanilla flavor,
+as defined at @url{http://daringfireball.net/projects/markdown/}.} for an Org
+mode buffer.
+
+It is built over HTML back-end: any construct not supported by Markdown
+syntax (e.g., tables) will be controlled and translated by @code{html}
+back-end (@pxref{HTML export}).
+
+@subheading Markdown export commands
+
+@table @kbd
+@orgcmd{C-c C-e m m,org-md-export-to-markdown}
+Export as a text file written in Markdown syntax. For an Org file,
+@file{myfile.org}, the resulting file will be @file{myfile.md}. The file
+will be overwritten without warning.
+@orgcmd{C-c C-e m M,org-md-export-as-markdown}
+Export to a temporary buffer. Do not create a file.
+@item C-c C-e m o
+Export as a text file with Markdown syntax, then open it.
+@end table
+
+@subheading Header and sectioning structure
+
+@vindex org-md-headline-style
+Markdown export can generate both @code{atx} and @code{setext} types for
+headlines, according to @code{org-md-headline-style}. The former introduces
+a hard limit of two levels, whereas the latter pushes it to six. Headlines
+below that limit are exported as lists. You can also set a soft limit before
+that one (@pxref{Export settings}).
-Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is
-exported to DocBook format, it can be further processed to produce other
-formats, including PDF, HTML, man pages, etc., using many available DocBook
-tools and stylesheets.
+@c begin opendocument
-Currently DocBook exporter only supports DocBook V5.0.
+@node OpenDocument Text export, Org export, Markdown export, Exporting
+@section OpenDocument Text export
+@cindex ODT
+@cindex OpenDocument
+@cindex export, OpenDocument
+@cindex LibreOffice
+
+Org mode@footnote{Versions 7.8 or later} supports export to OpenDocument Text
+(ODT) format. Documents created by this exporter use the
+@cite{OpenDocument-v1.2
+specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
+Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
+are compatible with LibreOffice 3.4.
@menu
-* DocBook export commands:: How to invoke DocBook export
-* Quoting DocBook code:: Incorporating DocBook code in Org files
-* Recursive sections:: Recursive sections in DocBook
-* Tables in DocBook export:: Tables are exported as HTML tables
-* Images in DocBook export:: How to insert figures into DocBook output
-* Special characters:: How to handle special characters
+* Pre-requisites for ODT export:: What packages ODT exporter relies on
+* ODT export commands:: How to invoke ODT export
+* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files
+* Applying custom styles:: How to apply custom styles to the output
+* Links in ODT export:: How links will be interpreted and formatted
+* Tables in ODT export:: How Tables are exported
+* Images in ODT export:: How to insert images
+* Math formatting in ODT export:: How @LaTeX{} fragments are formatted
+* Labels and captions in ODT export:: How captions are rendered
+* Literal examples in ODT export:: How source and example blocks are formatted
+* Advanced topics in ODT export:: Read this if you are a power user
@end menu
-@node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export
-@subsection DocBook export commands
+@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export
+@subsection Pre-requisites for ODT export
+@cindex zip
+The ODT exporter relies on the @file{zip} program to create the final
+output. Check the availability of this program before proceeding further.
+
+@node ODT export commands, Extending ODT export, Pre-requisites for ODT export, OpenDocument Text export
+@subsection ODT export commands
+
+@subsubheading Exporting to ODT
+@anchor{x-export-to-odt}
@cindex region, active
@cindex active region
@cindex transient-mark-mode
@table @kbd
-@kindex C-c C-e D
-@item C-c C-e D
+@orgcmd{C-c C-e o o,org-odt-export-to-odt}
@cindex property EXPORT_FILE_NAME
-Export as DocBook file. For an Org file, @file{myfile.org}, the DocBook XML
-file will be @file{myfile.xml}. The file will be overwritten without
-warning. If there is an active region@footnote{This requires
-@code{transient-mark-mode} to be turned on}, only the region will be
-exported. If the selected region is a single tree@footnote{To select the
-current subtree, use @kbd{C-c @@}.}, the tree head will become the document
-title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
-property, that name will be used for the export.
-@kindex C-c C-e V
-@item C-c C-e V
-Export as DocBook file, process to PDF, then open the resulting PDF file.
-@vindex org-export-docbook-xslt-proc-command
-@vindex org-export-docbook-xsl-fo-proc-command
-Note that, in order to produce PDF output based on exported DocBook file, you
-need to have XSLT processor and XSL-FO processor software installed on your
-system. Check variables @code{org-export-docbook-xslt-proc-command} and
-@code{org-export-docbook-xsl-fo-proc-command}.
+Export as OpenDocument Text file.
+
+@vindex org-odt-preferred-output-format
+If @code{org-odt-preferred-output-format} is specified, automatically convert
+the exported file to that format. @xref{x-export-to-other-formats, ,
+Automatically exporting to other formats}.
-@kindex C-c C-e v D
-@item C-c C-e v D
-Export only the visible part of the document.
+For an Org file @file{myfile.org}, the ODT file will be
+@file{myfile.odt}. The file will be overwritten without warning. If there
+is an active region,@footnote{This requires @code{transient-mark-mode} to be
+turned on} only the region will be exported. If the selected region is a
+single tree,@footnote{To select the current subtree, use @kbd{C-c @@}} the
+tree head will become the document title. If the tree head entry has, or
+inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the
+export.
+
+@kbd{C-c C-e o O}
+Export as an OpenDocument Text file and open the resulting file.
+
+@vindex org-odt-preferred-output-format
+If @code{org-odt-preferred-output-format} is specified, open the converted
+file instead. @xref{x-export-to-other-formats, , Automatically exporting to
+other formats}.
+@end table
+
+@node Extending ODT export, Applying custom styles, ODT export commands, OpenDocument Text export
+@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-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-odt-preferred-output-format
+Very often, you will find yourself exporting to ODT format, only to
+immediately save the exported document to other formats like @samp{doc},
+@samp{docx}, @samp{rtf}, @samp{pdf} etc. In such cases, you can specify your
+preferred output format by customizing the variable
+@code{org-odt-preferred-output-format}. This way, the export commands
+(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a
+format that is of immediate interest to you.
+
+@subsubsection Converting between document formats
+@anchor{x-convert-to-other-formats}
+
+There are many document converters in the wild which support conversion to
+and from various file formats, including, but not limited to the
+ODT format. LibreOffice converter, mentioned above, is one such
+converter. Once a converter is configured, you can interact with it using
+the following command.
+
+@vindex org-odt-convert
+@table @kbd
+
+@item M-x org-odt-convert RET
+Convert an existing document from one format to another. With a prefix
+argument, also open the newly produced file.
@end table
-@node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export
-@subsection Quoting DocBook code
+@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 ODT exporter ships with a set of OpenDocument styles
+(@pxref{Working with OpenDocument style files}) that ensure a well-formatted
+output. These factory styles, however, may not cater to your specific
+tastes. To customize the output, you can either modify the above styles
+files directly, or generate the required styles using an application like
+LibreOffice. The latter method is suitable for expert and non-expert
+users alike, and is described here.
-You can quote DocBook code in Org files and copy it verbatim into exported
-DocBook file with the following constructs:
+@subsubsection Applying custom styles: the easy way
+
+@enumerate
+@item
+Create a sample @file{example.org} file with the below settings and export it
+to ODT format.
-@cindex #+DOCBOOK
-@cindex #+BEGIN_DOCBOOK
@example
-#+DOCBOOK: Literal DocBook code for export
+#+OPTIONS: H:10 num:t
@end example
-@noindent or
-@cindex #+BEGIN_DOCBOOK
+@item
+Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
+to locate the target styles---these typically have the @samp{Org} prefix---and
+modify those to your taste. Save the modified file either as an
+OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file.
+
+@item
+@cindex #+ODT_STYLES_FILE
+@vindex org-odt-styles-file
+Customize the variable @code{org-odt-styles-file} and point it to the
+newly created file. For additional configuration options
+@pxref{x-overriding-factory-styles,,Overriding factory styles}.
+
+If you would like to choose a style on a per-file basis, you can use the
+@code{#+ODT_STYLES_FILE} option. A typical setting will look like
@example
-#+BEGIN_DOCBOOK
-All lines between these markers are exported by DocBook exporter
-literally.
-#+END_DOCBOOK
+#+ODT_STYLES_FILE: "/path/to/example.ott"
@end example
-For example, you can use the following lines to include a DocBook warning
-admonition. As to what this warning says, you should pay attention to the
-document context when quoting DocBook code in Org files. You may make
-exported DocBook XML files invalid by not quoting DocBook code correctly.
+or
@example
-#+BEGIN_DOCBOOK
-<warning>
- <para>You should know what you are doing when quoting DocBook XML code
- in your Org file. Invalid DocBook XML file may be generated by
- DocBook exporter if you are not careful!</para>
-</warning>
-#+END_DOCBOOK
+#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
@end example
-@node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export
-@subsection Recursive sections
-@cindex DocBook recursive sections
+@end enumerate
-DocBook exporter exports Org files as articles using the @code{article}
-element in DocBook. Recursive sections, i.e. @code{section} elements, are
-used in exported articles. Top level headlines in Org files are exported as
-top level sections, and lower level headlines are exported as nested
-sections. The entire structure of Org files will be exported completely, no
-matter how many nested levels of headlines there are.
+@subsubsection Using third-party styles and templates
-Using recursive sections makes it easy to port and reuse exported DocBook
-code in other DocBook document types like @code{book} or @code{set}.
+You can use third-party styles and templates for customizing your output.
+This will produce the desired output only if the template provides all
+style names that the @samp{ODT} exporter relies on. Unless this condition is
+met, the output is going to be less than satisfactory. So it is highly
+recommended that you only work with templates that are directly derived from
+the factory settings.
-@node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export
-@subsection Tables in DocBook export
-@cindex tables, in DocBook export
+@node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export
+@subsection Links in ODT export
+@cindex links, in ODT export
-Tables in Org files are exported as HTML tables, which have been supported since
-DocBook V4.3.
+ODT exporter creates native cross-references for internal links. It creates
+Internet-style links for all other links.
-If a table does not have a caption, an informal table is generated using the
-@code{informaltable} element; otherwise, a formal table will be generated
-using the @code{table} element.
+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 Images in DocBook export, Special characters, Tables in DocBook export, DocBook export
-@subsection Images in DocBook export
-@cindex images, inline in DocBook
-@cindex inlining images in DocBook
+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}.
-Images that are linked to without a description part in the link, like
-@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBook
-using @code{mediaobject} elements. Each @code{mediaobject} element contains
-an @code{imageobject} that wraps an @code{imagedata} element. If you have
-specified a caption for an image as described in @ref{Images and tables}, a
-@code{caption} element will be added in @code{mediaobject}. If a label is
-also specified, it will be exported as an @code{xml:id} attribute of the
-@code{mediaobject} element.
-
-@vindex org-export-docbook-default-image-attributes
-Image attributes supported by the @code{imagedata} element, like @code{align}
-or @code{width}, can be specified in two ways: you can either customize
-variable @code{org-export-docbook-default-image-attributes} or use the
-@code{#+ATTR_DOCBOOK:} line. Attributes specified in variable
-@code{org-export-docbook-default-image-attributes} are applied to all inline
-images in the Org file to be exported (unless they are overwritten by image
-attributes specified in @code{#+ATTR_DOCBOOK:} lines).
-
-The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image
-attributes or overwrite default image attributes for individual images. If
-the same attribute appears in both the @code{#+ATTR_DOCBOOK:} line and
-variable @code{org-export-docbook-default-image-attributes}, the former
-overwrites the latter. Here is an example about how image attributes can be
-set:
+@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export
+@subsection Tables in ODT export
+@cindex tables, in ODT export
+
+Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el}
+tables is supported. However, export of complex @file{table.el} tables---tables
+that have column or row spans---is not supported. Such tables are
+stripped from the exported document.
+
+By default, a table is exported with top and bottom frames and with rules
+separating row and column groups (@pxref{Column groups}). Furthermore, all
+tables are typeset to occupy the same width. If the table specifies
+alignment and relative width for its columns (@pxref{Column width and
+alignment}) then these are honored on export.@footnote{The column widths are
+interpreted as weighted ratios with the default weight being 1}
+
+@cindex #+ATTR_ODT
+You can control the width of the table by specifying @code{:rel-width}
+property using an @code{#+ATTR_ODT} line.
+
+For example, consider the following table which makes use of all the rules
+mentioned above.
-@cindex #+CAPTION
-@cindex #+LABEL
-@cindex #+ATTR_DOCBOOK
@example
-#+CAPTION: The logo of Org mode
-#+LABEL: unicorn-svg
-#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
-[[./img/org-mode-unicorn.svg]]
+#+ATTR_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
-@vindex org-export-docbook-inline-image-extensions
-By default, DocBook exporter recognizes the following image file types:
-@file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}. You can
-customize variable @code{org-export-docbook-inline-image-extensions} to add
-more types to this list as long as DocBook supports them.
+On export, the table will occupy 50% of text area. The columns will be sized
+(roughly) in the ratio of 13:5:5:5:6. The first column will be left-aligned
+and rest of the columns will be right-aligned. There will be vertical rules
+after separating the header and last columns from other columns. There will
+be horizontal rules separating the header and last rows from other rows.
-@node Special characters, , Images in DocBook export, DocBook export
-@subsection Special characters in DocBook export
-@cindex Special characters in DocBook export
+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}.
-@vindex org-export-docbook-doctype
-@vindex org-html-entities
-Special characters that are written in @TeX{}-like syntax, such as @code{\alpha},
-@code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter. These
-characters are rewritten to XML entities, like @code{α},
-@code{Γ}, and @code{Ζ}, based on the list saved in variable
-@code{org-html-entities}. As long as the generated DocBook file includes the
-corresponding entities, these special characters are recognized.
+@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
-You can customize variable @code{org-export-docbook-doctype} to include the
-entities you need. For example, you can set variable
-@code{org-export-docbook-doctype} to the following value to recognize all
-special characters included in XHTML entities:
+@subsubheading Embedding images
+You can embed images within the exported document by providing a link to the
+desired image file with no link description. For example, to embed
+@samp{img.png} do either of the following:
@example
-"<!DOCTYPE article [
-<!ENTITY % xhtml1-symbol PUBLIC
-\"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
-\"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
->
-%xhtml1-symbol;
-]>
-"
+[[file:img.png]]
@end example
-@node Freemind export, XOXO export, DocBook export, Exporting
-@section Freemind export
-@cindex Freemind export
-@cindex mind map
+@example
+[[./img.png]]
+@end example
-The freemind exporter was written by Lennart Borgman.
+@subsubheading Embedding clickable images
+You can create clickable images by providing a link whose description is a
+link to an image file. For example, to embed a image
+@file{org-mode-unicorn.png} which when clicked jumps to
+@uref{http://Orgmode.org} website, do the following
-@table @kbd
-@kindex C-c C-e m
-@item C-c C-e m
-Export as Freemind mind map @file{myfile.mm}.
-@end table
+@example
+[[http://orgmode.org][./org-mode-unicorn.png]]
+@end example
-@node XOXO export, iCalendar export, Freemind export, Exporting
-@section XOXO export
-@cindex XOXO export
+@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-odt-pixels-per-inch
+The exporter specifies the desired size of the image in the final document in
+units of centimeters. In order to scale the embedded images, the exporter
+queries for pixel dimensions of the images using one of a) ImageMagick's
+@file{identify} program or b) Emacs `create-image' and `image-size'
+APIs@footnote{Use of @file{ImageMagick} is only desirable. However, if you
+routinely produce documents that have large images or you export your Org
+files that has images using a Emacs batch script, then the use of
+@file{ImageMagick} is mandatory.}. The pixel dimensions are subsequently
+converted in to units of centimeters using
+@code{org-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.
-Org mode contains an exporter that produces XOXO-style output.
-Currently, this exporter only handles the general outline structure and
-does not interpret any additional Org-mode features.
+@table @asis
+@item Explicitly size the image
+To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
-@table @kbd
-@kindex C-c C-e x
-@item C-c C-e x
-Export as XOXO file @file{myfile.html}.
-@kindex C-c C-e v
-@item C-c C-e v x
-Export only the visible part of the document.
-@end table
+@example
+#+ATTR_ODT: :width 10 :height 10
+[[./img.png]]
+@end example
-@node iCalendar export, , XOXO export, Exporting
-@section iCalendar export
-@cindex iCalendar export
+@item Scale the image
+To embed @file{img.png} at half its size, do the following:
-@vindex org-icalendar-include-todo
-@vindex org-icalendar-use-deadline
-@vindex org-icalendar-use-scheduled
-@vindex org-icalendar-categories
-Some people use Org mode for keeping track of projects, but still prefer a
-standard calendar application for anniversaries and appointments. In this
-case it can be useful to show deadlines and other time-stamped items in Org
-files in the calendar application. Org mode can export calendar information
-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
-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}.}.
-As categories, it will use the tags locally defined in the heading, and the
-file/tree category@footnote{To add inherited tags or the TODO state,
-configure the variable @code{org-icalendar-categories}.}.
+@example
+#+ATTR_ODT: :scale 0.5
+[[./img.png]]
+@end example
-@vindex org-icalendar-store-UID
-@cindex property, ID
-The iCalendar standard requires each entry to have a globally unique
-identifier (UID). Org creates these identifiers during export. If you set
-the variable @code{org-icalendar-store-UID}, the UID will be stored in the
-@code{:ID:} property of the entry and re-used next time you report this
-entry. Since a single entry can give rise to multiple iCalendar entries (as
-a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
-prefixes to the UID, depending on what triggered the inclusion of the entry.
-In this way the UID remains unique, but a synchronization program can still
-figure out from which entry all the different instances originate.
+@item Scale the image to a specific width
+To embed @file{img.png} with a width of 10 cm while retaining the original
+height:width ratio, do the following:
-@table @kbd
-@kindex C-c C-e i
-@item C-c C-e i
-Create iCalendar entries for the current file and store them in the same
-directory, using a file extension @file{.ics}.
-@kindex C-c C-e I
-@item C-c C-e I
-@vindex org-agenda-files
-Like @kbd{C-c C-e i}, but do this for all files in
-@code{org-agenda-files}. For each of these files, a separate iCalendar
-file will be written.
-@kindex C-c C-e c
-@item C-c C-e c
-@vindex org-combined-agenda-icalendar-file
-Create a single large iCalendar file from all files in
-@code{org-agenda-files} and write it to the file given by
-@code{org-combined-agenda-icalendar-file}.
-@end table
+@example
+#+ATTR_ODT: :width 10
+[[./img.png]]
+@end example
-@vindex org-use-property-inheritance
-@vindex org-icalendar-include-body
-@cindex property, SUMMARY
-@cindex property, DESCRIPTION
-@cindex property, LOCATION
-The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
-property can be inherited from higher in the hierarchy if you configure
-@code{org-use-property-inheritance} accordingly.} properties if the selected
-entries have them. If not, the summary will be derived from the headline,
-and the description from the body (limited to
-@code{org-icalendar-include-body} characters).
+@item Scale the image to a specific height
+To embed @file{img.png} with a height of 10 cm while retaining the original
+height:width ratio, do the following
-How this calendar is best read and updated, depends on the application
-you are using. The FAQ covers this issue.
+@example
+#+ATTR_ODT: :height 10
+[[./img.png]]
+@end example
+@end table
-@node Publishing, Miscellaneous, Exporting, Top
-@chapter Publishing
-@cindex publishing
-@cindex O'Toole, David
+@subsubheading Anchoring of images
-Org includes a publishing management system that allows you to configure
-automatic HTML conversion of @emph{projects} composed of interlinked org
-files. You can also configure Org to automatically upload your exported HTML
-pages and related attachments, such as images and source code files, to a web
-server.
+@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"}.
-You can also use Org to convert files into PDF, or even combine HTML and PDF
-conversion so that files are available in both formats on the server.
+To create an image that is anchored to a page, do the following:
+@example
+#+ATTR_ODT: :anchor "page"
+[[./img.png]]
+@end example
-Publishing has been contributed to Org by David O'Toole.
+@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
-* Configuration:: Defining projects
-* Uploading files:: How to get files up on the server
-* Sample configuration:: Example projects
-* Triggering publication:: Publication commands
+* 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 Configuration, Uploading files, Publishing, Publishing
-@section Configuration
+@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
-Publishing needs significant configuration to specify files, destination
-and many other properties of a project.
+@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT
+document in one of the following ways:
-@menu
-* Project alist:: The central configuration variable
-* Sources and destinations:: From here to there
-* Selecting files:: What files are part of the project?
-* Publishing action:: Setting the function doing the publishing
-* Publishing options:: Tweaking HTML export
-* Publishing links:: Which links keep working after publishing?
-* Project page index:: Publishing a list of project files
-@end menu
+@cindex MathML
+@enumerate
+@item MathML
-@node Project alist, Sources and destinations, Configuration, Configuration
-@subsection The variable @code{org-publish-project-alist}
-@cindex org-publish-project-alist
-@cindex projects, for publishing
+This option is activated on a per-file basis with
-@vindex org-publish-project-alist
-Publishing is configured almost entirely through setting the value of one
-variable, called @code{org-publish-project-alist}. Each element of the list
-configures one project, and may be in one of the two following forms:
+@example
+#+OPTIONS: LaTeX:t
+@end example
-@lisp
- ("project-name" :property value :property value ...)
-@r{or}
- ("project-name" :components ("project-name" "project-name" ...))
+With this option, @LaTeX{} fragments are first converted into MathML
+fragments using an external @LaTeX{}-to-MathML converter program. The
+resulting MathML fragments are then embedded as an OpenDocument Formula in
+the exported document.
-@end lisp
+@vindex org-latex-to-mathml-convert-command
+@vindex org-latex-to-mathml-jar-file
-In both cases, projects are configured by specifying property values. A
-project defines the set of files that will be published, as well as the
-publishing configuration to use when publishing those files. When a project
-takes the second form listed above, the individual members of the
-@code{:components} property are taken to be sub-projects, which group
-together files requiring different publishing options. When you publish such
-a ``meta-project'', all the components will also be published, in the
-sequence given.
+You can specify the @LaTeX{}-to-MathML converter by customizing the variables
+@code{org-latex-to-mathml-convert-command} and
+@code{org-latex-to-mathml-jar-file}.
-@node Sources and destinations, Selecting files, Project alist, Configuration
-@subsection Sources and destinations for files
-@cindex directories, for publishing
+If you prefer to use @file{MathToWeb}@footnote{See
+@uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your
+converter, you can configure the above variables as shown below.
-Most properties are optional, but some should always be set. In
-particular, Org needs to know where to look for source files,
-and where to put published files.
+@lisp
+(setq org-latex-to-mathml-convert-command
+ "java -jar %j -unicode -force -df %o %I"
+ org-latex-to-mathml-jar-file
+ "/path/to/mathtoweb.jar")
+@end lisp
-@multitable @columnfractions 0.3 0.7
-@item @code{:base-directory}
-@tab Directory containing publishing source files
-@item @code{:publishing-directory}
-@tab Directory where output files will be published. You can directly
-publish to a webserver using a file name syntax appropriate for
-the Emacs @file{tramp} package. Or you can publish to a local directory and
-use external tools to upload your website (@pxref{Uploading files}).
-@item @code{:preparation-function}
-@tab Function called before starting the publishing process, for example, to
-run @code{make} for updating files to be published.
-@item @code{:completion-function}
-@tab Function called after finishing the publishing process, for example, to
-change permissions of the resulting files.
-@end multitable
-@noindent
+You can use the following commands to quickly verify the reliability of
+the @LaTeX{}-to-MathML converter.
-@node Selecting files, Publishing action, Sources and destinations, Configuration
-@subsection Selecting files
-@cindex files, selecting for publishing
+@table @kbd
+@item M-x org-odt-export-as-odf RET
+Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file.
-By default, all files with extension @file{.org} in the base directory
-are considered part of the project. This can be modified by setting the
-properties
-@multitable @columnfractions 0.25 0.75
-@item @code{:base-extension}
-@tab Extension (without the dot!) of source files. This actually is a
-regular expression. Set this to the symbol @code{any} if you want to get all
-files in @code{:base-directory}, even without extension.
+@item M-x org-odt-export-as-odf-and-open RET
+Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file
+and open the formula file with the system-registered application.
+@end table
-@item @code{:exclude}
-@tab Regular expression to match file names that should not be
-published, even though they have been selected on the basis of their
-extension.
+@cindex dvipng
+@cindex imagemagick
+@item PNG images
-@item @code{:include}
-@tab List of files to be included regardless of @code{:base-extension}
-and @code{:exclude}.
-@end multitable
+This option is activated on a per-file basis with
-@node Publishing action, Publishing options, Selecting files, Configuration
-@subsection Publishing action
-@cindex action, for publishing
+@example
+#+OPTIONS: tex:dvipng
+@end example
-Publishing means that a file is copied to the destination directory and
-possibly transformed in the process. The default transformation is to export
-Org files as HTML files, and this is done by the function
-@code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML
-export}). But you also can publish your content as PDF files using
-@code{org-publish-org-to-pdf}. If you want to publish the Org file itself,
-but with @i{archived}, @i{commented}, and @i{tag-excluded} trees removed, use
-@code{org-publish-org-to-org} and set the parameters @code{:plain-source}
-and/or @code{:htmlized-source}. This will produce @file{file.org} and
-@file{file.org.html} in the publishing
-directory@footnote{@file{file-source.org} and @file{file-source.org.html} if
-source and publishing directories are equal. Note that with this kind of
-setup, you need to add @code{:exclude "-source\\.org"} to the project
-definition in @code{org-publish-project-alist} to avoid that the published
-source files will be considered as new org files the next time the project is
-published.}. Other files like images only
-need to be copied to the publishing destination, for this you may use
-@code{org-publish-attachment}. For non-Org files, you always need to
-specify the publishing function:
+or:
-@multitable @columnfractions 0.3 0.7
-@item @code{:publishing-function}
-@tab Function executing the publication of a file. This may also be a
-list of functions, which will all be called in turn.
-@item @code{:plain-source}
-@tab Non-nil means, publish plain source.
-@item @code{:htmlized-source}
-@tab Non-nil means, publish htmlized source.
-@end multitable
+@example
+#+OPTIONS: tex:imagemagick
+@end example
-The function must accept two arguments: a property list containing at least a
-@code{:publishing-directory} property, and the name of the file to be
-published. It should take the specified file, make the necessary
-transformation (if any) and place the result into the destination folder.
+With this option, @LaTeX{} fragments are processed into PNG images and the
+resulting images are embedded in the exported document. This method requires
+that the @file{dvipng} program or @file{imagemagick} suite be available on
+your system.
+@end enumerate
-@node Publishing options, Publishing links, Publishing action, Configuration
-@subsection Options for the HTML/La@TeX{} exporters
-@cindex options, for publishing
+@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
-The property list can be used to set many export options for the HTML
-and La@TeX{} exporters. In most cases, these properties correspond to user
-variables in Org. The table below lists these properties along
-with the variable they belong to. See the documentation string for the
-respective variable for details.
+For various reasons, you may find embedding @LaTeX{} math snippets in an
+ODT document less than reliable. In that case, you can embed a
+math equation by linking to its MathML (@file{.mml}) source or its
+OpenDocument formula (@file{.odf}) file as shown below:
-@vindex org-export-html-link-up
-@vindex org-export-html-link-home
-@vindex org-export-default-language
-@vindex org-display-custom-times
-@vindex org-export-headline-levels
-@vindex org-export-with-section-numbers
-@vindex org-export-section-number-format
-@vindex org-export-with-toc
-@vindex org-export-preserve-breaks
-@vindex org-export-with-archived-trees
-@vindex org-export-with-emphasize
-@vindex org-export-with-sub-superscripts
-@vindex org-export-with-special-strings
-@vindex org-export-with-footnotes
-@vindex org-export-with-drawers
-@vindex org-export-with-tags
-@vindex org-export-with-todo-keywords
-@vindex org-export-with-priority
-@vindex org-export-with-TeX-macros
-@vindex org-export-with-LaTeX-fragments
-@vindex org-export-skip-text-before-1st-heading
-@vindex org-export-with-fixed-width
-@vindex org-export-with-timestamps
-@vindex org-export-author-info
-@vindex org-export-creator-info
-@vindex org-export-with-tables
-@vindex org-export-highlight-first-table-line
-@vindex org-export-html-style-include-default
-@vindex org-export-html-style
-@vindex org-export-html-style-extra
-@vindex org-export-html-link-org-files-as-html
-@vindex org-export-html-inline-images
-@vindex org-export-html-extension
-@vindex org-export-html-table-tag
-@vindex org-export-html-expand
-@vindex org-export-html-with-timestamp
-@vindex org-export-publishing-directory
-@vindex org-export-html-preamble
-@vindex org-export-html-postamble
-@vindex org-export-html-auto-preamble
-@vindex org-export-html-auto-postamble
-@vindex user-full-name
-@vindex user-mail-address
-@vindex org-export-select-tags
-@vindex org-export-exclude-tags
+@example
+[[./equation.mml]]
+@end example
-@multitable @columnfractions 0.32 0.68
-@item @code{:link-up} @tab @code{org-export-html-link-up}
-@item @code{:link-home} @tab @code{org-export-html-link-home}
-@item @code{:language} @tab @code{org-export-default-language}
-@item @code{:customtime} @tab @code{org-display-custom-times}
-@item @code{:headline-levels} @tab @code{org-export-headline-levels}
-@item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
-@item @code{:section-number-format} @tab @code{org-export-section-number-format}
-@item @code{:table-of-contents} @tab @code{org-export-with-toc}
-@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
-@item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
-@item @code{:emphasize} @tab @code{org-export-with-emphasize}
-@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}
-@item @code{:special-strings} @tab @code{org-export-with-special-strings}
-@item @code{:footnotes} @tab @code{org-export-with-footnotes}
-@item @code{:drawers} @tab @code{org-export-with-drawers}
-@item @code{:tags} @tab @code{org-export-with-tags}
-@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords}
-@item @code{:priority} @tab @code{org-export-with-priority}
-@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
-@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
-@item @code{:latex-listings} @tab @code{org-export-latex-listings}
-@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading}
-@item @code{:fixed-width} @tab @code{org-export-with-fixed-width}
-@item @code{:timestamps} @tab @code{org-export-with-timestamps}
-@item @code{:author-info} @tab @code{org-export-author-info}
-@item @code{:creator-info} @tab @code{org-export-creator-info}
-@item @code{:tables} @tab @code{org-export-with-tables}
-@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}
-@item @code{:style-include-default} @tab @code{org-export-html-style-include-default}
-@item @code{:style} @tab @code{org-export-html-style}
-@item @code{:style-extra} @tab @code{org-export-html-style-extra}
-@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}
-@item @code{:inline-images} @tab @code{org-export-html-inline-images}
-@item @code{:html-extension} @tab @code{org-export-html-extension}
-@item @code{:xml-declaration} @tab @code{org-export-html-xml-declaration}
-@item @code{:html-table-tag} @tab @code{org-export-html-table-tag}
-@item @code{:expand-quoted-html} @tab @code{org-export-html-expand}
-@item @code{:timestamp} @tab @code{org-export-html-with-timestamp}
-@item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
-@item @code{:preamble} @tab @code{org-export-html-preamble}
-@item @code{:postamble} @tab @code{org-export-html-postamble}
-@item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble}
-@item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble}
-@item @code{:author} @tab @code{user-full-name}
-@item @code{:email} @tab @code{user-mail-address} : @code{addr;addr;..}
-@item @code{:select-tags} @tab @code{org-export-select-tags}
-@item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
-@item @code{:latex-image-options} @tab @code{org-export-latex-image-default-option}
-@end multitable
+or
+
+@example
+[[./equation.odf]]
+@end example
-Most of the @code{org-export-with-*} variables have the same effect in
-both HTML and La@TeX{} exporters, except for @code{:TeX-macros} and
-@code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the
-La@TeX{} 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
-@vindex org-publish-project-alist
-When a property is given a value in @code{org-publish-project-alist},
-its setting overrides the value of the corresponding user variable (if
-any) during publishing. Options set within a file (@pxref{Export
-options}), however, override everything.
+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.
-@node Publishing links, Project page index, Publishing options, Configuration
-@subsection Links between published files
-@cindex links, publishing
+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.
-To create a link from one Org file to another, you would use
-something like @samp{[[file:foo.org][The foo]]} or simply
-@samp{file:foo.org.} (@pxref{Hyperlinks}). When published, this link
-becomes a link to @file{foo.html}. In this way, you can interlink the
-pages of your "org web" project and the links will work as expected when
-you publish them to HTML. If you also publish the Org source file and want
-to link to that, use an @code{http:} link instead of a @code{file:} link,
-because @code{file:} links are converted to link to the corresponding
-@file{html} file.
-
-You may also link to related files, such as images. Provided you are careful
-with relative file names, and provided you have also configured Org to upload
-the related files, these links will work too. See @ref{Complex example}, for
-an example of this usage.
+@example
+#+CAPTION: Bell curve
+#+LABEL: fig:SED-HR4049
+[[./img/a.png]]
+@end example
-Sometimes an Org file to be published may contain links that are
-only valid in your production environment, but not in the publishing
-location. In this case, use the property
+It could be rendered as shown below in the exported document.
-@multitable @columnfractions 0.4 0.6
-@item @code{:link-validation-function}
-@tab Function to validate links
-@end multitable
+@example
+Figure 2: Bell curve
+@end example
-@noindent
-to define a function for checking link validity. This function must
-accept two arguments, the file name and a directory relative to which
-the file name is interpreted in the production environment. If this
-function returns @code{nil}, then the HTML generator will only insert a
-description into the HTML file, but no link. One option for this
-function is @code{org-publish-validate-link} which checks if the given
-file is part of any project in @code{org-publish-project-alist}.
+@vindex org-odt-category-map-alist
+You can modify the category component of the caption by customizing the
+option @code{org-odt-category-map-alist}. For example, to tag all embedded
+images with the string @samp{Illustration} (instead of the default
+@samp{Figure}) use the following setting:
+
+@lisp
+(setq org-odt-category-map-alist
+ (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
+@end lisp
-@node Project page index, , Publishing links, Configuration
-@subsection Project page index
-@cindex index, of published pages
+With this, previous image will be captioned as below in the exported
+document.
-The following properties may be used to control publishing of an
-index of files or a summary page for a given project.
+@example
+Illustration 2: Bell curve
+@end example
-@multitable @columnfractions 0.25 0.75
-@item @code{:auto-index}
-@tab When non-nil, publish an index during @code{org-publish-current-project}
-or @code{org-publish-all}.
+@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
-@item @code{:index-filename}
-@tab Filename for output of index. Defaults to @file{sitemap.org} (which
-becomes @file{sitemap.html}).
+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.
-@item @code{:index-title}
-@tab Title of index page. Defaults to name of file.
+@vindex org-odt-fontify-srcblocks
+If you prefer to use your own custom styles for fontification, you can do
+so by customizing the option
+@code{org-odt-create-custom-styles-for-srcblocks}.
-@item @code{:index-function}
-@tab Plug-in function to use for generation of index.
-Defaults to @code{org-publish-org-index}, which generates a plain list
-of links to all files in the project.
+@vindex org-odt-create-custom-styles-for-srcblocks
+You can turn off fontification of literal examples by customizing the
+option @code{org-odt-fontify-srcblocks}.
+
+@node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export
+@subsection Advanced topics in ODT export
+
+If you rely heavily on ODT export, you may want to exploit the full
+set of features that the exporter offers. This section describes features
+that would be of interest to power users.
+
+@menu
+* Configuring a document converter:: How to register a document converter
+* Working with OpenDocument style files:: Explore the internals
+* Creating one-off styles:: How to produce custom highlighting etc
+* Customizing tables in ODT export:: How to define and use Table templates
+* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
+@end menu
+
+@node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export
+@subsubsection Configuring a document converter
+@cindex convert
+@cindex doc, docx, rtf
+@cindex converter
+
+The ODT exporter can work with popular converters with little or no
+extra configuration from your side. @xref{Extending ODT export}.
+If you are using a converter that is not supported by default or if you would
+like to tweak the default converter settings, proceed as below.
+
+@enumerate
+@item Register the converter
+
+@vindex org-odt-convert-processes
+Name your converter and add it to the list of known converters by
+customizing the option @code{org-odt-convert-processes}. Also specify how
+the converter can be invoked via command-line to effect the conversion.
+
+@item Configure its capabilities
+
+@vindex org-odt-convert-capabilities
+@anchor{x-odt-converter-capabilities} Specify the set of formats the
+converter can handle by customizing the variable
+@code{org-odt-convert-capabilities}. Use the default value for this
+variable as a guide for configuring your converter. As suggested by the
+default setting, you can specify the full set of formats supported by the
+converter and not limit yourself to specifying formats that are related to
+just the OpenDocument Text format.
+
+@item Choose the converter
+
+@vindex org-odt-convert-process
+Select the newly added converter as the preferred one by customizing the
+option @code{org-odt-convert-process}.
+@end enumerate
+
+@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export
+@subsubsection Working with OpenDocument style files
+@cindex styles, custom
+@cindex template, custom
+
+This section explores the internals of the ODT exporter and the
+means by which it produces styled documents. Read this section if you are
+interested in exploring the automatic and custom OpenDocument styles used by
+the exporter.
+
+@anchor{x-factory-styles}
+@subsubheading Factory styles
+
+The ODT exporter relies on two files for generating its output.
+These files are bundled with the distribution under the directory pointed to
+by the variable @code{org-odt-styles-dir}. The two files are:
+
+@itemize
+@anchor{x-orgodtstyles-xml}
+@item
+@file{OrgOdtStyles.xml}
+
+This file contributes to the @file{styles.xml} file of the final @samp{ODT}
+document. This file gets modified for the following purposes:
+@enumerate
+
+@item
+To control outline numbering based on user settings.
+
+@item
+To add styles generated by @file{htmlfontify.el} for fontification of code
+blocks.
+@end enumerate
+
+@anchor{x-orgodtcontenttemplate-xml}
+@item
+@file{OrgOdtContentTemplate.xml}
+
+This file contributes to the @file{content.xml} file of the final @samp{ODT}
+document. The contents of the Org outline are inserted between the
+@samp{<office:text>}@dots{}@samp{</office:text>} elements of this file.
+
+Apart from serving as a template file for the final @file{content.xml}, the
+file serves the following purposes:
+@enumerate
+
+@item
+It contains automatic styles for formatting of tables which are referenced by
+the exporter.
+
+@item
+It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
+elements that control how various entities---tables, images, equations,
+etc.---are numbered.
+@end enumerate
+@end itemize
+
+@anchor{x-overriding-factory-styles}
+@subsubheading Overriding factory styles
+The following two variables control the location from which the ODT
+exporter picks up the custom styles and content template files. You can
+customize these variables to override the factory styles used by the
+exporter.
+
+@itemize
+@anchor{x-org-odt-styles-file}
+@item
+@code{org-odt-styles-file}
+
+Use this variable to specify the @file{styles.xml} that will be used in the
+final output. You can specify one of the following values:
+
+@enumerate
+@item A @file{styles.xml} file
+
+Use this file instead of the default @file{styles.xml}
+
+@item A @file{.odt} or @file{.ott} file
+
+Use the @file{styles.xml} contained in the specified OpenDocument Text or
+Template file
+
+@item A @file{.odt} or @file{.ott} file and a subset of files contained within them
+
+Use the @file{styles.xml} contained in the specified OpenDocument Text or
+Template file. Additionally extract the specified member files and embed
+those within the final @samp{ODT} document.
+
+Use this option if the @file{styles.xml} file references additional files
+like header and footer images.
+
+@item @code{nil}
+
+Use the default @file{styles.xml}
+@end enumerate
+
+@anchor{x-org-odt-content-template-file}
+@item
+@code{org-odt-content-template-file}
+
+Use this variable to specify the blank @file{content.xml} that will be used
+in the final output.
+@end itemize
+
+@node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export
+@subsubsection Creating one-off styles
+
+There are times when you would want one-off formatting in the exported
+document. You can achieve this by embedding raw OpenDocument XML in the Org
+file. The use of this feature is better illustrated with couple of examples.
+
+@enumerate
+@item Embedding ODT tags as part of regular text
+
+You can inline OpenDocument syntax by enclosing it within
+@samp{@@@@odt:...@@@@} markup. For example, to highlight a region of text do
+the following:
+
+@example
+@@@@odt:<text:span text:style-name="Highlight">This is a highlighted
+text</text:span>@@@@. But this is a regular text.
+@end example
+
+@strong{Hint:} To see the above example in action, edit your
+@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
+custom @samp{Highlight} style as shown below.
+
+@example
+<style:style style:name="Highlight" style:family="text">
+ <style:text-properties fo:background-color="#ff0000"/>
+</style:style>
+@end example
+
+@item Embedding a one-line OpenDocument XML
+
+You can add a simple OpenDocument one-liner using the @code{#+ODT:}
+directive. For example, to force a page break do the following:
+
+@example
+#+ODT: <text:p text:style-name="PageBreak"/>
+@end example
+
+@strong{Hint:} To see the above example in action, edit your
+@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
+custom @samp{PageBreak} style as shown below.
+
+@example
+<style:style style:name="PageBreak" style:family="paragraph"
+ style:parent-style-name="Text_20_body">
+ <style:paragraph-properties fo:break-before="page"/>
+</style:style>
+@end example
+
+@item Embedding a block of OpenDocument XML
+
+You can add a large block of OpenDocument XML using the
+@code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct.
+
+For example, to create a one-off paragraph that uses bold text, do the
+following:
+
+@example
+#+BEGIN_ODT
+<text:p text:style-name="Text_20_body_20_bold">
+This paragraph is specially formatted and uses bold text.
+</text:p>
+#+END_ODT
+@end example
+
+@end enumerate
+
+@node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export
+@subsubsection Customizing tables in ODT export
+@cindex tables, in ODT export
+
+@cindex #+ATTR_ODT
+You can override the default formatting of the table by specifying a custom
+table style with the @code{#+ATTR_ODT} line. For a discussion on default
+formatting of tables @pxref{Tables in ODT export}.
+
+This feature closely mimics the way table templates are defined in the
+OpenDocument-v1.2
+specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
+OpenDocument-v1.2 Specification}}
+
+@subsubheading Custom table styles: an illustration
+
+@vindex org-odt-table-styles
+To have a quick preview of this feature, install the below setting and
+export the table that follows:
+
+@lisp
+(setq org-odt-table-styles
+ (append org-odt-table-styles
+ '(("TableWithHeaderRowAndColumn" "Custom"
+ ((use-first-row-styles . t)
+ (use-first-column-styles . t)))
+ ("TableWithFirstRowandLastRow" "Custom"
+ ((use-first-row-styles . t)
+ (use-last-row-styles . t))))))
+@end lisp
+
+@example
+#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
+| Name | Phone | Age |
+| Peter | 1234 | 17 |
+| Anna | 4321 | 25 |
+@end example
+
+In the above example, you used a template named @samp{Custom} and installed
+two table styles with the names @samp{TableWithHeaderRowAndColumn} and
+@samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument
+styles needed for producing the above template have been pre-defined for
+you. These styles are available under the section marked @samp{Custom
+Table Template} in @file{OrgOdtContentTemplate.xml}
+(@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need
+additional templates you have to define these styles yourselves.
+
+@subsubheading Custom table styles: the nitty-gritty
+To use this feature proceed as follows:
+
+@enumerate
+@item
+Create a table template@footnote{See the @code{<table:table-template>}
+element of the OpenDocument-v1.2 specification}
+
+A table template is nothing but a set of @samp{table-cell} and
+@samp{paragraph} styles for each of the following table cell categories:
+
+@itemize @minus
+@item Body
+@item First column
+@item Last column
+@item First row
+@item Last row
+@item Even row
+@item Odd row
+@item Even column
+@item Odd Column
+@end itemize
+
+The names for the above styles must be chosen based on the name of the table
+template using a well-defined convention.
+
+The naming convention is better illustrated with an example. For a table
+template with the name @samp{Custom}, the needed style names are listed in
+the following table.
+
+@multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
+@headitem Table cell type
+@tab @code{table-cell} style
+@tab @code{paragraph} style
+@item
+@tab
+@tab
+@item Body
+@tab @samp{CustomTableCell}
+@tab @samp{CustomTableParagraph}
+@item First column
+@tab @samp{CustomFirstColumnTableCell}
+@tab @samp{CustomFirstColumnTableParagraph}
+@item Last column
+@tab @samp{CustomLastColumnTableCell}
+@tab @samp{CustomLastColumnTableParagraph}
+@item First row
+@tab @samp{CustomFirstRowTableCell}
+@tab @samp{CustomFirstRowTableParagraph}
+@item Last row
+@tab @samp{CustomLastRowTableCell}
+@tab @samp{CustomLastRowTableParagraph}
+@item Even row
+@tab @samp{CustomEvenRowTableCell}
+@tab @samp{CustomEvenRowTableParagraph}
+@item Odd row
+@tab @samp{CustomOddRowTableCell}
+@tab @samp{CustomOddRowTableParagraph}
+@item Even column
+@tab @samp{CustomEvenColumnTableCell}
+@tab @samp{CustomEvenColumnTableParagraph}
+@item Odd column
+@tab @samp{CustomOddColumnTableCell}
+@tab @samp{CustomOddColumnTableParagraph}
@end multitable
-@node Uploading files, Sample configuration, Configuration, Publishing
-@section Uploading files
-@cindex rsync
-@cindex unison
+To create a table template with the name @samp{Custom}, define the above
+styles in the
+@code{<office:automatic-styles>}...@code{</office:automatic-styles>} element
+of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory
+styles}).
-For those people already utilizing third party sync tools such as
-@command{rsync} or @command{unison}, it might be preferable not to use the built in
-@i{remote} publishing facilities of Org mode which rely heavily on
-Tramp. Tramp, while very useful and powerful, tends not to be
-so efficient for multiple file transfer and has been known to cause problems
-under heavy usage.
+@item
+Define a table style@footnote{See the attributes @code{table:template-name},
+@code{table:use-first-row-styles}, @code{table:use-last-row-styles},
+@code{table:use-first-column-styles}, @code{table:use-last-column-styles},
+@code{table:use-banding-rows-styles}, and
+@code{table:use-banding-column-styles} of the @code{<table:table>} element in
+the OpenDocument-v1.2 specification}
-Specialized synchronization utilities offer several advantages. In addition
-to timestamp comparison, they also do content and permissions/attribute
-checks. For this reason you might prefer to publish your web to a local
-directory (possibly even @i{in place} with your Org files) and then use
-@file{unison} or @file{rsync} to do the synchronization with the remote host.
+@vindex org-odt-table-styles
+To define a table style, create an entry for the style in the variable
+@code{org-odt-table-styles} and specify the following:
+
+@itemize @minus
+@item the name of the table template created in step (1)
+@item the set of cell styles in that template that are to be activated
+@end itemize
+
+For example, the entry below defines two different table styles
+@samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
+based on the same template @samp{Custom}. The styles achieve their intended
+effect by selectively activating the individual cell styles in that template.
+
+@lisp
+(setq org-odt-table-styles
+ (append org-odt-table-styles
+ '(("TableWithHeaderRowAndColumn" "Custom"
+ ((use-first-row-styles . t)
+ (use-first-column-styles . t)))
+ ("TableWithFirstRowandLastRow" "Custom"
+ ((use-first-row-styles . t)
+ (use-last-row-styles . t))))))
+@end lisp
+
+@item
+Associate a table with the table style
+
+To do this, specify the table style created in step (2) as part of
+the @code{ATTR_ODT} line as shown below.
+
+@example
+#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
+| Name | Phone | Age |
+| Peter | 1234 | 17 |
+| Anna | 4321 | 25 |
+@end example
+@end enumerate
+
+@node Validating OpenDocument XML, , Customizing tables in ODT export, Advanced topics in ODT export
+@subsubsection Validating OpenDocument XML
+
+Occasionally, you will discover that the document created by the
+ODT exporter cannot be opened by your favorite application. One of
+the common reasons for this is that the @file{.odt} file is corrupt. In such
+cases, you may want to validate the document against the OpenDocument RELAX
+NG Compact Syntax (RNC) schema.
+
+For de-compressing the @file{.odt} file@footnote{@file{.odt} files are
+nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For
+general help with validation (and schema-sensitive editing) of XML files:
+@inforef{Introduction,,nxml-mode}.
+
+@vindex org-odt-schema-dir
+If you have ready access to OpenDocument @file{.rnc} files and the needed
+schema-locating rules in a single folder, you can customize the variable
+@code{org-odt-schema-dir} to point to that directory. The ODT exporter
+will take care of updating the @code{rng-schema-locating-files} for you.
+
+@c end opendocument
+
+@node Org export
+@section Org export
+@cindex Org export
+
+@code{org} export back-end creates a normalized version of the Org document
+in current buffer. In particular, it evaluates Babel code (@pxref{Evaluating
+code blocks}) and removes other back-ends specific contents.
+
+@subheading Org export commands
+
+@table @kbd
+@orgcmd{C-c C-e O o,org-org-export-to-org}
+Export as an Org document. For an Org file, @file{myfile.org}, the resulting
+file will be @file{myfile.org.org}. The file will be overwritten without
+warning.
+@orgcmd{C-c C-e O O,org-org-export-as-org}
+Export to a temporary buffer. Do not create a file.
+@item C-c C-e O v
+Export to an Org file, then open it.
+@end table
+
+@node iCalendar export, Other built-in back-ends, Org export, Exporting
+@section iCalendar export
+@cindex iCalendar export
+
+@vindex org-icalendar-include-todo
+@vindex org-icalendar-use-deadline
+@vindex org-icalendar-use-scheduled
+@vindex org-icalendar-categories
+@vindex org-icalendar-alarm-time
+Some people use Org mode for keeping track of projects, but still prefer a
+standard calendar application for anniversaries and appointments. In this
+case it can be useful to show deadlines and other time-stamped items in Org
+files in the calendar application. Org mode can export calendar information
+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
+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}.}.
+As categories, it will use the tags locally defined in the heading, and the
+file/tree category@footnote{To add inherited tags or the TODO state,
+configure the variable @code{org-icalendar-categories}.}. See the variable
+@code{org-icalendar-alarm-time} for a way to assign alarms to entries with a
+time.
+
+@vindex org-icalendar-store-UID
+@cindex property, ID
+The iCalendar standard requires each entry to have a globally unique
+identifier (UID). Org creates these identifiers during export. If you set
+the variable @code{org-icalendar-store-UID}, the UID will be stored in the
+@code{:ID:} property of the entry and re-used next time you report this
+entry. Since a single entry can give rise to multiple iCalendar entries (as
+a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
+prefixes to the UID, depending on what triggered the inclusion of the entry.
+In this way the UID remains unique, but a synchronization program can still
+figure out from which entry all the different instances originate.
+
+@table @kbd
+@orgcmd{C-c C-e c f,org-icalendar-export-to-ics}
+Create iCalendar entries for the current buffer and store them in the same
+directory, using a file extension @file{.ics}.
+@orgcmd{C-c C-e c a, org-icalendar-export-agenda-files}
+@vindex org-agenda-files
+Like @kbd{C-c C-e c f}, but do this for all files in
+@code{org-agenda-files}. For each of these files, a separate iCalendar
+file will be written.
+@orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files}
+@vindex org-icalendar-combined-agenda-file
+Create a single large iCalendar file from all files in
+@code{org-agenda-files} and write it to the file given by
+@code{org-icalendar-combined-agenda-file}.
+@end table
+
+@vindex org-use-property-inheritance
+@vindex org-icalendar-include-body
+@cindex property, SUMMARY
+@cindex property, DESCRIPTION
+@cindex property, LOCATION
+The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
+property can be inherited from higher in the hierarchy if you configure
+@code{org-use-property-inheritance} accordingly.} properties if the selected
+entries have them. If not, the summary will be derived from the headline,
+and the description from the body (limited to
+@code{org-icalendar-include-body} characters).
+
+How this calendar is best read and updated, depends on the application
+you are using. The FAQ covers this issue.
+
+@node Other built-in back-ends, Export in foreign buffers, iCalendar export, Exporting
+@section Other built-in back-ends
+@cindex export back-ends, built-in
+@vindex org-export-backends
+
+On top of the aforementioned back-ends, Org comes with other built-in ones:
+
+@itemize
+@item @file{ox-man.el}: export to a man page.
+@item @file{ox-texinfo.el}: export to @code{Texinfo} format.
+@end itemize
+
+To activate these export back-end, customize @code{org-export-backends} or
+load them directly with e.g., @code{(require 'ox-texinfo)}. This will add
+new keys in the export dispatcher (@pxref{The Export Dispatcher}).
+
+See the comment section of these files for more information on how to use
+them.
+
+@node Export in foreign buffers, Advanced configuration, Other built-in back-ends, Exporting
+@section Export in foreign buffers
+
+Most built-in back-ends come with a command to convert the selected region
+into a selected format and replace this region by the exported output. Here
+is a list of such conversion commands:
+
+@table @code
+@item org-html-convert-region-to-html
+Convert the selected region into HTML.
+@item org-latex-convert-region-to-latex
+Convert the selected region into @LaTeX{}.
+@item org-texinfo-convert-region-to-texinfo
+Convert the selected region into @code{Texinfo}.
+@item org-md-convert-region-to-md
+Convert the selected region into @code{MarkDown}.
+@end table
+
+This is particularly useful for converting tables and lists in foreign
+buffers. E.g., in an HTML buffer, you can turn on @code{orgstruct-mode}, then
+use Org commands for editing a list, and finally select and convert the list
+with @code{M-x org-html-convert-region-to-html RET}.
+
+@node Advanced configuration, , Export in foreign buffers, Exporting
+@section Advanced configuration
+
+@subheading Hooks
+
+@vindex org-export-before-processing-hook
+@vindex org-export-before-parsing-hook
+Two hooks are run during the first steps of the export process. The first
+one, @code{org-export-before-processing-hook} is called before expanding
+macros, Babel code and include keywords in the buffer. The second one,
+@code{org-export-before-parsing-hook}, as its name suggests, happens just
+before parsing the buffer. Their main use is for heavy duties, that is
+duties involving structural modifications of the document. For example, one
+may want to remove every headline in the buffer during export. The following
+code can achieve this:
+
+@lisp
+@group
+(defun my-headline-removal (backend)
+ "Remove all headlines in the current buffer.
+BACKEND is the export back-end being used, as a symbol."
+ (org-map-entries
+ (lambda () (delete-region (point) (progn (forward-line) (point))))))
+
+(add-hook 'org-export-before-parsing-hook 'my-headline-removal)
+@end group
+@end lisp
+
+Note that functions used in these hooks require a mandatory argument,
+a symbol representing the back-end used.
+
+@subheading Filters
+
+@cindex Filters, exporting
+Filters are lists of functions applied on a specific part of the output from
+a given back-end. More explicitly, each time a back-end transforms an Org
+object or element into another language, all functions within a given filter
+type are called in turn on the string produced. The string returned by the
+last function will be the one used in the final output.
+
+There are filters sets for each type of element or object, for plain text,
+for the parse tree, for the export options and for the final output. They
+are all named after the same scheme: @code{org-export-filter-TYPE-functions},
+where @code{TYPE} is the type targeted by the filter. Valid types are:
+
+@multitable @columnfractions .33 .33 .33
+@item bold
+@tab babel-call
+@tab center-block
+@item clock
+@tab code
+@tab comment
+@item comment-block
+@tab diary-sexp
+@tab drawer
+@item dynamic-block
+@tab entity
+@tab example-block
+@item export-block
+@tab export-snippet
+@tab final-output
+@item fixed-width
+@tab footnote-definition
+@tab footnote-reference
+@item headline
+@tab horizontal-rule
+@tab inline-babel-call
+@item inline-src-block
+@tab inlinetask
+@tab italic
+@item item
+@tab keyword
+@tab latex-environment
+@item latex-fragment
+@tab line-break
+@tab link
+@item node-property
+@tab options
+@tab paragraph
+@item parse-tree
+@tab plain-list
+@tab plain-text
+@item planning
+@tab property-drawer
+@tab quote-block
+@item quote-section
+@tab radio-target
+@tab section
+@item special-block
+@tab src-block
+@tab statistics-cookie
+@item strike-through
+@tab subscript
+@tab superscript
+@item table
+@tab table-cell
+@tab table-row
+@item target
+@tab timestamp
+@tab underline
+@item verbatim
+@tab verse-block
+@tab
+@end multitable
+
+For example, the following snippet allows me to use non-breaking spaces in
+the Org buffer and get them translated into @LaTeX{} without using the
+@code{\nbsp} macro (where @code{_} stands for the non-breaking space):
+
+@lisp
+@group
+(defun my-latex-filter-nobreaks (text backend info)
+ "Ensure \"Â \" are properly handled in LaTeX export."
+ (when (org-export-derived-backend-p backend 'latex)
+ (replace-regexp-in-string "Â " "~" text)))
+
+(add-to-list 'org-export-filter-plain-text-functions
+ 'my-latex-filter-nobreaks)
+@end group
+@end lisp
+
+Three arguments must be provided to a filter: the code being changed, the
+back-end used, and some information about the export process. You can safely
+ignore the third argument for most purposes. Note the use of
+@code{org-export-derived-backend-p}, which ensures that the filter will only
+be applied when using @code{latex} back-end or any other back-end derived
+from it (e.g., @code{beamer}).
+
+@subheading Extending an existing back-end
+
+This is obviously the most powerful customization, since the changes happen
+at the parser level. Indeed, some export back-ends are built as extensions
+of other ones (e.g. Markdown back-end an extension of HTML back-end).
+
+Extending a back-end means that if an element type is not transcoded by the
+new back-end, it will be handled by the original one. Hence you can extend
+specific parts of a back-end without too much work.
+
+As an example, imagine we want the @code{ascii} back-end to display the
+language used in a source block, when it is available, but only when some
+attribute is non-@code{nil}, like the following:
+
+@example
+#+ATTR_ASCII: :language t
+@end example
+
+Because that back-end is lacking in that area, we are going to create a new
+back-end, @code{my-ascii} that will do the job.
+
+@lisp
+@group
+(defun my-ascii-src-block (src-block contents info)
+ "Transcode a SRC-BLOCK element from Org to ASCII.
+CONTENTS is nil. INFO is a plist used as a communication
+channel."
+ (if (not (org-export-read-attribute :attr_ascii src-block :language))
+ (org-export-with-backend 'ascii src-block contents info)
+ (concat
+ (format ",--[ %s ]--\n%s`----"
+ (org-element-property :language src-block)
+ (replace-regexp-in-string
+ "^" "| "
+ (org-element-normalize-string
+ (org-export-format-code-default src-block info)))))))
+
+(org-export-define-derived-backend 'my-ascii 'ascii
+ :translate-alist '((src-block . my-ascii-src-block)))
+@end group
+@end lisp
+
+The @code{my-ascii-src-block} function looks at the attribute above the
+element. If it isn't true, it gives hand to the @code{ascii} back-end.
+Otherwise, it creates a box around the code, leaving room for the language.
+A new back-end is then created. It only changes its behavior when
+translating @code{src-block} type element. Now, all it takes to use the new
+back-end is calling the following from an Org buffer:
+
+@smalllisp
+(org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
+@end smalllisp
+
+It is obviously possible to write an interactive function for this, install
+it in the export dispatcher menu, and so on.
+
+@node Publishing, Working With Source Code, Exporting, Top
+@chapter Publishing
+@cindex publishing
+
+Org includes a publishing management system that allows you to configure
+automatic HTML conversion of @emph{projects} composed of interlinked org
+files. You can also configure Org to automatically upload your exported HTML
+pages and related attachments, such as images and source code files, to a web
+server.
+
+You can also use Org to convert files into PDF, or even combine HTML and PDF
+conversion so that files are available in both formats on the server.
+
+Publishing has been contributed to Org by David O'Toole.
+
+@menu
+* Configuration:: Defining projects
+* Uploading files:: How to get files up on the server
+* Sample configuration:: Example projects
+* Triggering publication:: Publication commands
+@end menu
+
+@node Configuration, Uploading files, Publishing, Publishing
+@section Configuration
+
+Publishing needs significant configuration to specify files, destination
+and many other properties of a project.
+
+@menu
+* Project alist:: The central configuration variable
+* Sources and destinations:: From here to there
+* Selecting files:: What files are part of the project?
+* Publishing action:: Setting the function doing the publishing
+* Publishing options:: Tweaking HTML/@LaTeX{} export
+* Publishing links:: Which links keep working after publishing?
+* Sitemap:: Generating a list of all pages
+* Generating an index:: An index that reaches across pages
+@end menu
+
+@node Project alist, Sources and destinations, Configuration, Configuration
+@subsection The variable @code{org-publish-project-alist}
+@cindex org-publish-project-alist
+@cindex projects, for publishing
+
+@vindex org-publish-project-alist
+Publishing is configured almost entirely through setting the value of one
+variable, called @code{org-publish-project-alist}. Each element of the list
+configures one project, and may be in one of the two following forms:
+
+@lisp
+ ("project-name" :property value :property value ...)
+ @r{i.e., a well-formed property list with alternating keys and values}
+@r{or}
+ ("project-name" :components ("project-name" "project-name" ...))
+
+@end lisp
+
+In both cases, projects are configured by specifying property values. A
+project defines the set of files that will be published, as well as the
+publishing configuration to use when publishing those files. When a project
+takes the second form listed above, the individual members of the
+@code{:components} property are taken to be sub-projects, which group
+together files requiring different publishing options. When you publish such
+a ``meta-project'', all the components will also be published, in the
+sequence given.
+
+@node Sources and destinations, Selecting files, Project alist, Configuration
+@subsection Sources and destinations for files
+@cindex directories, for publishing
+
+Most properties are optional, but some should always be set. In
+particular, Org needs to know where to look for source files,
+and where to put published files.
+
+@multitable @columnfractions 0.3 0.7
+@item @code{:base-directory}
+@tab Directory containing publishing source files
+@item @code{:publishing-directory}
+@tab Directory where output files will be published. You can directly
+publish to a web server using a file name syntax appropriate for
+the Emacs @file{tramp} package. Or you can publish to a local directory and
+use external tools to upload your website (@pxref{Uploading files}).
+@item @code{:preparation-function}
+@tab Function or list of functions to be called before starting the
+publishing process, for example, to run @code{make} for updating files to be
+published. The project property list is scoped into this call as the
+variable @code{project-plist}.
+@item @code{:completion-function}
+@tab Function or list of functions called after finishing the publishing
+process, for example, to change permissions of the resulting files. The
+project property list is scoped into this call as the variable
+@code{project-plist}.
+@end multitable
+@noindent
+
+@node Selecting files, Publishing action, Sources and destinations, Configuration
+@subsection Selecting files
+@cindex files, selecting for publishing
+
+By default, all files with extension @file{.org} in the base directory
+are considered part of the project. This can be modified by setting the
+properties
+@multitable @columnfractions 0.25 0.75
+@item @code{:base-extension}
+@tab Extension (without the dot!) of source files. This actually is a
+regular expression. Set this to the symbol @code{any} if you want to get all
+files in @code{:base-directory}, even without extension.
+
+@item @code{:exclude}
+@tab Regular expression to match file names that should not be
+published, even though they have been selected on the basis of their
+extension.
+
+@item @code{:include}
+@tab List of files to be included regardless of @code{:base-extension}
+and @code{:exclude}.
+
+@item @code{:recursive}
+@tab non-@code{nil} means, check base-directory recursively for files to publish.
+@end multitable
+
+@node Publishing action, Publishing options, Selecting files, Configuration
+@subsection Publishing action
+@cindex action, for publishing
+
+Publishing means that a file is copied to the destination directory and
+possibly transformed in the process. The default transformation is to export
+Org files as HTML files, and this is done by the function
+@code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML
+export}). But you also can publish your content as PDF files using
+@code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc.,
+using the corresponding functions.
+
+If you want to publish the Org file as an @code{.org} file but with the
+@i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the
+function @code{org-org-publish-to-org}. This will produce @file{file.org}
+and put it in the publishing directory. If you want a htmlized version of
+this file, set the parameter @code{:htmlized-source} to @code{t}, it will
+produce @file{file.org.html} in the publishing directory@footnote{If the
+publishing directory is the same than the source directory, @file{file.org}
+will be exported as @file{file.org.org}, so probably don't want to do this.}.
+
+Other files like images only need to be copied to the publishing destination.
+For this you can use @code{org-publish-attachment}. For non-org files, you
+always need to specify the publishing function:
+
+@multitable @columnfractions 0.3 0.7
+@item @code{:publishing-function}
+@tab Function executing the publication of a file. This may also be a
+list of functions, which will all be called in turn.
+@item @code{:htmlized-source}
+@tab non-@code{nil} means, publish htmlized source.
+@end multitable
+
+The function must accept three arguments: a property list containing at least
+a @code{:publishing-directory} property, the name of the file to be published
+and the path to the publishing directory of the output file. It should take
+the specified file, make the necessary transformation (if any) and place the
+result into the destination folder.
+
+@node Publishing options, Publishing links, Publishing action, Configuration
+@subsection Options for the exporters
+@cindex options, for publishing
+
+The property list can be used to set many export options for the exporters.
+In most cases, these properties correspond to user variables in Org. The
+first table below lists these properties along with the variable they belong
+to. The second table list HTML specific properties. See the documentation
+string of these options for details.
+
+@vindex org-display-custom-times
+@vindex org-export-default-language
+@vindex org-export-exclude-tags
+@vindex org-export-headline-levels
+@vindex org-export-preserve-breaks
+@vindex org-export-publishing-directory
+@vindex org-export-select-tags
+@vindex org-export-with-archived-trees
+@vindex org-export-with-author
+@vindex org-export-with-creator
+@vindex org-export-with-drawers
+@vindex org-export-with-email
+@vindex org-export-with-emphasize
+@vindex org-export-with-fixed-width
+@vindex org-export-with-footnotes
+@vindex org-export-with-latex
+@vindex org-export-with-planning
+@vindex org-export-with-priority
+@vindex org-export-with-section-numbers
+@vindex org-export-with-special-strings
+@vindex org-export-with-sub-superscripts
+@vindex org-export-with-tables
+@vindex org-export-with-tags
+@vindex org-export-with-tasks
+@vindex org-export-with-timestamps
+@vindex org-export-with-toc
+@vindex org-export-with-todo-keywords
+@vindex user-mail-address
+
+@multitable @columnfractions 0.32 0.68
+@item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
+@item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
+@item @code{:headline-levels} @tab @code{org-export-headline-levels}
+@item @code{:language} @tab @code{org-export-default-language}
+@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
+@item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
+@item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
+@item @code{:select-tags} @tab @code{org-export-select-tags}
+@item @code{:with-author} @tab @code{org-export-with-author}
+@item @code{:with-creator} @tab @code{org-export-with-creator}
+@item @code{:with-drawers} @tab @code{org-export-with-drawers}
+@item @code{:with-email} @tab @code{org-export-with-email}
+@item @code{:with-emphasize} @tab @code{org-export-with-emphasize}
+@item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width}
+@item @code{:with-footnotes} @tab @code{org-export-with-footnotes}
+@item @code{:with-latex} @tab @code{org-export-with-latex}
+@item @code{:with-planning} @tab @code{org-export-with-planning}
+@item @code{:with-priority} @tab @code{org-export-with-priority}
+@item @code{:with-special-strings} @tab @code{org-export-with-special-strings}
+@item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts}
+@item @code{:with-tables} @tab @code{org-export-with-tables}
+@item @code{:with-tags} @tab @code{org-export-with-tags}
+@item @code{:with-tasks} @tab @code{org-export-with-tasks}
+@item @code{:with-timestamps} @tab @code{org-export-with-timestamps}
+@item @code{:with-toc} @tab @code{org-export-with-toc}
+@item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords}
+@end multitable
+
+@vindex org-html-doctype
+@vindex org-html-container-element
+@vindex org-html-html5-fancy
+@vindex org-html-xml-declaration
+@vindex org-html-link-up
+@vindex org-html-link-home
+@vindex org-html-link-org-files-as-html
+@vindex org-html-link-use-abs-url
+@vindex org-html-head
+@vindex org-html-head-extra
+@vindex org-html-inline-images
+@vindex org-html-extension
+@vindex org-html-preamble
+@vindex org-html-postamble
+@vindex org-html-table-default-attributes
+@vindex org-html-table-row-tags
+@vindex org-html-head-include-default-style
+@vindex org-html-head-include-scripts
+@multitable @columnfractions 0.32 0.68
+@item @code{:html-doctype} @tab @code{org-html-doctype}
+@item @code{:html-container} @tab @code{org-html-container-element}
+@item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy}
+@item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration}
+@item @code{:html-link-up} @tab @code{org-html-link-up}
+@item @code{:html-link-home} @tab @code{org-html-link-home}
+@item @code{:html-link-org-as-html} @tab @code{org-html-link-org-files-as-html}
+@item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
+@item @code{:html-head} @tab @code{org-html-head}
+@item @code{:html-head-extra} @tab @code{org-html-head-extra}
+@item @code{:html-inline-images} @tab @code{org-html-inline-images}
+@item @code{:html-extension} @tab @code{org-html-extension}
+@item @code{:html-preamble} @tab @code{org-html-preamble}
+@item @code{:html-postamble} @tab @code{org-html-postamble}
+@item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
+@item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags}
+@item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
+@item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
+@end multitable
+
+Most of the @code{org-export-with-*} variables have the same effect in each
+exporter.
+
+@vindex org-publish-project-alist
+When a property is given a value in @code{org-publish-project-alist}, its
+setting overrides the value of the corresponding user variable (if any)
+during publishing. Options set within a file (@pxref{Export settings}),
+however, override everything.
+
+@node Publishing links, Sitemap, Publishing options, Configuration
+@subsection Links between published files
+@cindex links, publishing
+
+To create a link from one Org file to another, you would use something like
+@samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org.}
+(@pxref{Hyperlinks}). When published, this link becomes a link to
+@file{foo.html}. You can thus interlink the pages of your "org web" project
+and the links will work as expected when you publish them to HTML@. If you
+also publish the Org source file and want to link to it, use an @code{http:}
+link instead of a @code{file:} link, because @code{file:} links are converted
+to link to the corresponding @file{html} file.
+
+You may also link to related files, such as images. Provided you are careful
+with relative file names, and provided you have also configured Org to upload
+the related files, these links will work too. See @ref{Complex example}, for
+an example of this usage.
+
+@node Sitemap, Generating an index, Publishing links, Configuration
+@subsection Generating a sitemap
+@cindex sitemap, of published pages
+
+The following properties may be used to control publishing of
+a map of files for a given project.
+
+@multitable @columnfractions 0.35 0.65
+@item @code{:auto-sitemap}
+@tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project}
+or @code{org-publish-all}.
+
+@item @code{:sitemap-filename}
+@tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which
+becomes @file{sitemap.html}).
+
+@item @code{:sitemap-title}
+@tab Title of sitemap page. Defaults to name of file.
+
+@item @code{:sitemap-function}
+@tab Plug-in function to use for generation of the sitemap.
+Defaults to @code{org-publish-org-sitemap}, which generates a plain list
+of links to all files in the project.
+
+@item @code{:sitemap-sort-folders}
+@tab Where folders should appear in the sitemap. Set this to @code{first}
+(default) or @code{last} to display folders first or last,
+respectively. Any other value will mix files and folders.
+
+@item @code{:sitemap-sort-files}
+@tab How the files are sorted in the site map. Set this to
+@code{alphabetically} (default), @code{chronologically} or
+@code{anti-chronologically}. @code{chronologically} sorts the files with
+older date first while @code{anti-chronologically} sorts the files with newer
+date first. @code{alphabetically} sorts the files alphabetically. The date of
+a file is retrieved with @code{org-publish-find-date}.
+
+@item @code{:sitemap-ignore-case}
+@tab Should sorting be case-sensitive? Default @code{nil}.
+
+@item @code{:sitemap-file-entry-format}
+@tab With this option one can tell how a sitemap's entry is formatted in the
+sitemap. This is a format string with some escape sequences: @code{%t} stands
+for the title of the file, @code{%a} stands for the author of the file and
+@code{%d} stands for the date of the file. The date is retrieved with the
+@code{org-publish-find-date} function and formatted with
+@code{org-publish-sitemap-date-format}. Default @code{%t}.
+
+@item @code{:sitemap-date-format}
+@tab Format string for the @code{format-time-string} function that tells how
+a sitemap entry's date is to be formatted. This property bypasses
+@code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
+
+@item @code{:sitemap-sans-extension}
+@tab When non-@code{nil}, remove filenames' extensions from the generated sitemap.
+Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}).
+Defaults to @code{nil}.
+
+@end multitable
+
+@node Generating an index, , Sitemap, Configuration
+@subsection Generating an index
+@cindex index, in a publishing project
+
+Org mode can generate an index across the files of a publishing project.
+
+@multitable @columnfractions 0.25 0.75
+@item @code{:makeindex}
+@tab When non-@code{nil}, generate in index in the file @file{theindex.org} and
+publish it as @file{theindex.html}.
+@end multitable
+
+The file will be created when first publishing a project with the
+@code{:makeindex} set. The file only contains a statement @code{#+INCLUDE:
+"theindex.inc"}. You can then build around this include statement by adding
+a title, style information, etc.
+
+@node Uploading files, Sample configuration, Configuration, Publishing
+@section Uploading files
+@cindex rsync
+@cindex unison
+
+For those people already utilizing third party sync tools such as
+@command{rsync} or @command{unison}, it might be preferable not to use the built in
+@i{remote} publishing facilities of Org mode which rely heavily on
+Tramp. Tramp, while very useful and powerful, tends not to be
+so efficient for multiple file transfer and has been known to cause problems
+under heavy usage.
+
+Specialized synchronization utilities offer several advantages. In addition
+to timestamp comparison, they also do content and permissions/attribute
+checks. For this reason you might prefer to publish your web to a local
+directory (possibly even @i{in place} with your Org files) and then use
+@file{unison} or @file{rsync} to do the synchronization with the remote host.
+
+Since Unison (for example) can be configured as to which files to transfer to
+a certain remote destination, it can greatly simplify the project publishing
+definition. Simply keep all files in the correct location, process your Org
+files with @code{org-publish} and let the synchronization tool do the rest.
+You do not need, in this scenario, to include attachments such as @file{jpg},
+@file{css} or @file{gif} files in the project definition since the 3rd party
+tool syncs them.
+
+Publishing to a local directory is also much faster than to a remote one, so
+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
+Org is not smart enough to detect if included files have been modified.
+
+@node Sample configuration, Triggering publication, Uploading files, Publishing
+@section Sample configuration
+
+Below we provide two example configurations. The first one is a simple
+project publishing only a set of Org files. The second example is
+more complex, with a multi-component project.
+
+@menu
+* Simple example:: One-component publishing
+* Complex example:: A multi-component publishing example
+@end menu
+
+@node Simple example, Complex example, Sample configuration, Sample configuration
+@subsection Example: simple publishing configuration
+
+This example publishes a set of Org files to the @file{public_html}
+directory on the local machine.
+
+@lisp
+(setq org-publish-project-alist
+ '(("org"
+ :base-directory "~/org/"
+ :publishing-directory "~/public_html"
+ :section-numbers nil
+ :with-toc nil
+ :html-head "<link rel=\"stylesheet\"
+ href=\"../other/mystyle.css\"
+ type=\"text/css\"/>")))
+@end lisp
+
+@node Complex example, , Simple example, Sample configuration
+@subsection Example: complex publishing configuration
+
+This more complicated example publishes an entire website, including
+Org files converted to HTML, image files, Emacs Lisp source code, and
+style sheets. The publishing directory is remote and private files are
+excluded.
+
+To ensure that links are preserved, care should be taken to replicate
+your directory structure on the web server, and to use relative file
+paths. For example, if your Org files are kept in @file{~/org} and your
+publishable images in @file{~/images}, you would link to an image with
+@c
+@example
+file:../images/myimage.png
+@end example
+@c
+On the web server, the relative path to the image should be the
+same. You can accomplish this by setting up an "images" folder in the
+right place on the web server, and publishing images to it.
+
+@lisp
+(setq org-publish-project-alist
+ '(("orgfiles"
+ :base-directory "~/org/"
+ :base-extension "org"
+ :publishing-directory "/ssh:user@@host:~/html/notebook/"
+ :publishing-function org-html-publish-to-html
+ :exclude "PrivatePage.org" ;; regexp
+ :headline-levels 3
+ :section-numbers nil
+ :with-toc nil
+ :html-head "<link rel=\"stylesheet\"
+ href=\"../other/mystyle.css\" type=\"text/css\"/>"
+ :html-preamble t)
+
+ ("images"
+ :base-directory "~/images/"
+ :base-extension "jpg\\|gif\\|png"
+ :publishing-directory "/ssh:user@@host:~/html/images/"
+ :publishing-function org-publish-attachment)
+
+ ("other"
+ :base-directory "~/other/"
+ :base-extension "css\\|el"
+ :publishing-directory "/ssh:user@@host:~/html/other/"
+ :publishing-function org-publish-attachment)
+ ("website" :components ("orgfiles" "images" "other"))))
+@end lisp
+
+@node Triggering publication, , Sample configuration, Publishing
+@section Triggering publication
+
+Once properly configured, Org can publish with the following commands:
+
+@table @kbd
+@orgcmd{C-c C-e P x,org-publish}
+Prompt for a specific project and publish all files that belong to it.
+@orgcmd{C-c C-e P p,org-publish-current-project}
+Publish the project containing the current file.
+@orgcmd{C-c C-e P f,org-publish-current-file}
+Publish only the current file.
+@orgcmd{C-c C-e P a,org-publish-all}
+Publish every project.
+@end table
+
+@vindex org-publish-use-timestamps-flag
+Org uses timestamps to track when a file has changed. The above functions
+normally only publish changed files. You can override this and force
+publishing of all files by giving a prefix argument to any of the commands
+above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
+This may be necessary in particular if files include other files via
+@code{#+SETUPFILE:} or @code{#+INCLUDE:}.
+
+@comment node-name, next, previous, up
+@comment Working With Source Code, Miscellaneous, Publishing, Top
+
+@node Working With Source Code, Miscellaneous, Publishing, Top
+@chapter Working with source code
+@cindex Schulte, Eric
+@cindex Davison, Dan
+@cindex source code, working with
+
+Source code can be included in Org mode documents using a @samp{src} block,
+e.g.:
+
+@example
+#+BEGIN_SRC emacs-lisp
+ (defun org-xor (a b)
+ "Exclusive or."
+ (if a (not b) b))
+#+END_SRC
+@end example
+
+Org mode provides a number of features for working with live source code,
+including editing of code blocks in their native major-mode, evaluation of
+code blocks, converting code blocks into source files (known as @dfn{tangling}
+in literate programming), and exporting code blocks and their
+results in several formats. This functionality was contributed by Eric
+Schulte and Dan Davison, and was originally named Org-babel.
+
+The following sections describe Org mode's code block handling facilities.
+
+@menu
+* Structure of code blocks:: Code block syntax described
+* Editing source code:: Language major-mode editing
+* Exporting code blocks:: Export contents and/or results
+* Extracting source code:: Create pure source code files
+* Evaluating code blocks:: Place results of evaluation in the Org mode buffer
+* Library of Babel:: Use and contribute to a library of useful code blocks
+* Languages:: List of supported code block languages
+* Header arguments:: Configure code block functionality
+* Results of evaluation:: How evaluation results are handled
+* Noweb reference syntax:: Literate programming in Org mode
+* Key bindings and useful functions:: Work quickly with code blocks
+* Batch execution:: Call functions from the command line
+@end menu
+
+@comment node-name, next, previous, up
+@comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code
+
+@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code
+@section Structure of code blocks
+@cindex code block, structure
+@cindex source code, block structure
+@cindex #+NAME
+@cindex #+BEGIN_SRC
+
+Live code blocks can be specified with a @samp{src} block or
+inline.@footnote{Note that @samp{src} blocks may be inserted using Org mode's
+@ref{Easy Templates} system} The structure of a @samp{src} block is
+
+@example
+#+NAME: <name>
+#+BEGIN_SRC <language> <switches> <header arguments>
+ <body>
+#+END_SRC
+@end example
+
+The @code{#+NAME:} line is optional, and can be used to name the code
+block. Live code blocks require that a language be specified on the
+@code{#+BEGIN_SRC} line. Switches and header arguments are optional.
+@cindex source code, inline
+
+Live code blocks can also be specified inline using
+
+@example
+src_<language>@{<body>@}
+@end example
+
+or
+
+@example
+src_<language>[<header arguments>]@{<body>@}
+@end example
+
+@table @code
+@item <#+NAME: name>
+This line associates a name with the code block. This is similar to the
+@code{#+NAME: Name} lines that can be used to name tables in Org mode
+files. Referencing the name of a code block makes it possible to evaluate
+the block from other places in the file, from other files, or from Org mode
+table formulas (see @ref{The spreadsheet}). Names are assumed to be unique
+and the behavior of Org mode when two or more blocks share the same name is
+undefined.
+@cindex #+NAME
+@item <language>
+The language of the code in the block (see @ref{Languages}).
+@cindex source code, language
+@item <switches>
+Optional switches control code block export (see the discussion of switches in
+@ref{Literal examples})
+@cindex source code, switches
+@item <header arguments>
+Optional header arguments control many aspects of evaluation, export and
+tangling of code blocks (see @ref{Header arguments}).
+Header arguments can also be set on a per-buffer or per-subtree
+basis using properties.
+@item source code, header arguments
+@item <body>
+Source code in the specified language.
+@end table
+
+@comment node-name, next, previous, up
+@comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
+
+@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
+@section Editing source code
+@cindex code block, editing
+@cindex source code, editing
+
+@vindex org-edit-src-auto-save-idle-delay
+@vindex org-edit-src-turn-on-auto-save
+@kindex C-c '
+Use @kbd{C-c '} to edit the current code block. This brings up a language
+major-mode edit buffer containing the body of the code block. Manually
+saving this buffer with @key{C-x C-s} will write the contents back to the Org
+buffer. You can also set @code{org-edit-src-auto-save-idle-delay} to save the
+base buffer after some idle delay, or @code{org-edit-src-turn-on-auto-save}
+to auto-save this buffer into a separate file using @code{auto-save-mode}.
+Use @kbd{C-c '} again to exit.
+
+The @code{org-src-mode} minor mode will be active in the edit buffer. The
+following variables can be used to configure the behavior of the edit
+buffer. See also the customization group @code{org-edit-structure} for
+further configuration options.
+
+@table @code
+@item org-src-lang-modes
+If an Emacs major-mode named @code{<lang>-mode} exists, where
+@code{<lang>} is the language named in the header line of the code block,
+then the edit buffer will be placed in that major-mode. This variable
+can be used to map arbitrary language names to existing major modes.
+@item org-src-window-setup
+Controls the way Emacs windows are rearranged when the edit buffer is created.
+@item org-src-preserve-indentation
+This variable is especially useful for tangling languages such as
+Python, in which whitespace indentation in the output is critical.
+@item org-src-ask-before-returning-to-edit-buffer
+By default, Org will ask before returning to an open edit buffer. Set this
+variable to @code{nil} to switch without asking.
+@end table
+
+To turn on native code fontification in the @emph{Org} buffer, configure the
+variable @code{org-src-fontify-natively}.
+
+@comment node-name, next, previous, up
+@comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code
+
+@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code
+@section Exporting code blocks
+@cindex code block, exporting
+@cindex source code, exporting
+
+It is possible to export the @emph{code} of code blocks, the @emph{results}
+of code block evaluation, @emph{both} the code and the results of code block
+evaluation, or @emph{none}. For most languages, the default exports code.
+However, for some languages (e.g., @code{ditaa}) the default exports the
+results of code block evaluation. For information on exporting code block
+bodies, see @ref{Literal examples}.
+
+The @code{:exports} header argument can be used to specify export
+behavior:
+
+@subsubheading Header arguments:
+
+@table @code
+@item :exports code
+The default in most languages. The body of the code block is exported, as
+described in @ref{Literal examples}.
+@item :exports results
+The code block will be evaluated and the results will be placed in the
+Org mode buffer for export, either updating previous results of the code
+block located anywhere in the buffer or, if no previous results exist,
+placing the results immediately after the code block. The body of the code
+block will not be exported.
+@item :exports both
+Both the code block and its results will be exported.
+@item :exports none
+Neither the code block nor its results will be exported.
+@end table
+
+It is possible to inhibit the evaluation of code blocks during export.
+Setting the @code{org-export-babel-evaluate} variable to @code{nil} will
+ensure that no code blocks are evaluated as part of the export process. This
+can be useful in situations where potentially untrusted Org mode files are
+exported in an automated fashion, for example when Org mode is used as the
+markup language for a wiki. It is also possible to set this variable to
+@code{'inline-only}. In that case, only inline code blocks will be
+evaluated, in order to insert their results. Non-inline code blocks are
+assumed to have their results already inserted in the buffer by manual
+evaluation. This setting is useful to avoid expensive recalculations during
+export, not to provide security.
+
+@comment node-name, next, previous, up
+@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
+@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
+@section Extracting source code
+@cindex tangling
+@cindex source code, extracting
+@cindex code block, extracting source code
+
+Creating pure source code files by extracting code from source blocks is
+referred to as ``tangling''---a term adopted from the literate programming
+community. During ``tangling'' of code blocks their bodies are expanded
+using @code{org-babel-expand-src-block} which can expand both variable and
+``noweb'' style references (see @ref{Noweb reference syntax}).
+
+@subsubheading Header arguments
+
+@table @code
+@item :tangle no
+The default. The code block is not included in the tangled output.
+@item :tangle yes
+Include the code block in the tangled output. The output file name is the
+name of the org file with the extension @samp{.org} replaced by the extension
+for the block language.
+@item :tangle filename
+Include the code block in the tangled output to file @samp{filename}.
+@end table
+
+@kindex C-c C-v t
+@subsubheading Functions
+
+@table @code
+@item org-babel-tangle
+Tangle the current file. Bound to @kbd{C-c C-v t}.
+
+With prefix argument only tangle the current code block.
+@item org-babel-tangle-file
+Choose a file to tangle. Bound to @kbd{C-c C-v f}.
+@end table
+
+@subsubheading Hooks
+
+@table @code
+@item org-babel-post-tangle-hook
+This hook is run from within code files tangled by @code{org-babel-tangle}.
+Example applications could include post-processing, compilation or evaluation
+of tangled code files.
+@end table
+
+@subsubheading Jumping between code and Org
+
+When tangling code from an Org-mode buffer to a source code file, you'll
+frequently find yourself viewing the file of tangled source code (e.g., many
+debuggers point to lines of the source code file). It is useful to be able
+to navigate from the tangled source to the Org-mode buffer from which the
+code originated.
+
+The @code{org-babel-tangle-jump-to-org} function provides this jumping from
+code to Org-mode functionality. Two header arguments are required for
+jumping to work, first the @code{padline} (@ref{padline}) option must be set
+to true (the default setting), second the @code{comments} (@ref{comments})
+header argument must be set to @code{links}, which will insert comments into
+the source code buffer which point back to the original Org-mode file.
+
+@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code
+@section Evaluating code blocks
+@cindex code block, evaluating
+@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. 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
+@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The
+option @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code
+evaluation from the @kbd{C-c C-c} key binding.}. This will call the
+@code{org-babel-execute-src-block} function to evaluate the block and insert
+its results into the Org mode buffer.
+@cindex #+CALL
+
+It is also possible to evaluate named code blocks from anywhere in an Org
+mode buffer or an Org mode table. Live code blocks located in the current
+Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel})
+can be executed. Named code blocks can be executed with a separate
+@code{#+CALL:} line or inline within a block of text.
+
+The syntax of the @code{#+CALL:} line is
+
+@example
+#+CALL: <name>(<arguments>)
+#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
+@end example
+
+The syntax for inline evaluation of named code blocks is
+
+@example
+... call_<name>(<arguments>) ...
+... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
+@end example
+
+@table @code
+@item <name>
+The name of the code block to be evaluated (see @ref{Structure of code blocks}).
+@item <arguments>
+Arguments specified in this section will be passed to the code block. These
+arguments use standard function call syntax, rather than
+header argument syntax. For example, a @code{#+CALL:} line that passes the
+number four to a code block named @code{double}, which declares the header
+argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}.
+@item <inside header arguments>
+Inside header arguments are passed through and applied to the named code
+block. These arguments use header argument syntax rather than standard
+function call syntax. Inside header arguments affect how the code block is
+evaluated. For example, @code{[:results output]} will collect the results of
+everything printed to @code{STDOUT} during execution of the code block.
+@item <end header arguments>
+End header arguments are applied to the calling instance and do not affect
+evaluation of the named code block. They affect how the results are
+incorporated into the Org mode buffer and how the call line is exported. For
+example, @code{:results html} will insert the results of the call line
+evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block.
+
+For more examples of passing header arguments to @code{#+CALL:} lines see
+@ref{Header arguments in function calls}.
+@end table
+
+@node Library of Babel, Languages, Evaluating code blocks, Working With Source Code
+@section Library of Babel
+@cindex babel, library of
+@cindex source code, library
+@cindex code block, library
+
+The ``Library of Babel'' consists of code blocks that can be called from any
+Org mode file. Code blocks defined in the ``Library of Babel'' can be called
+remotely as if they were in the current Org mode buffer (see @ref{Evaluating
+code blocks} for information on the syntax of remote code block evaluation).
+
+
+The central repository of code blocks in the ``Library of Babel'' is housed
+in an Org mode file located in the @samp{contrib} directory of Org mode.
+
+Users can add code blocks they believe to be generally useful to their
+``Library of Babel.'' The code blocks can be stored in any Org mode file and
+then loaded into the library with @code{org-babel-lob-ingest}.
+
+
+@kindex C-c C-v i
+Code blocks located in any Org mode file can be loaded into the ``Library of
+Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v
+i}.
+
+@node Languages, Header arguments, Library of Babel, Working With Source Code
+@section Languages
+@cindex babel, languages
+@cindex source code, languages
+@cindex code block, languages
+
+Code blocks in the following languages are supported.
+
+@multitable @columnfractions 0.28 0.3 0.22 0.2
+@item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
+@item Asymptote @tab asymptote @tab Awk @tab awk
+@item Emacs Calc @tab calc @tab C @tab C
+@item C++ @tab C++ @tab Clojure @tab clojure
+@item CSS @tab css @tab ditaa @tab ditaa
+@item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp
+@item gnuplot @tab gnuplot @tab Haskell @tab haskell
+@item Java @tab java @tab @tab
+@item Javascript @tab js @tab LaTeX @tab latex
+@item Ledger @tab ledger @tab Lisp @tab lisp
+@item Lilypond @tab lilypond @tab MATLAB @tab matlab
+@item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
+@item Octave @tab octave @tab Org mode @tab org
+@item Oz @tab oz @tab Perl @tab perl
+@item Plantuml @tab plantuml @tab Python @tab python
+@item R @tab R @tab Ruby @tab ruby
+@item Sass @tab sass @tab Scheme @tab scheme
+@item GNU Screen @tab screen @tab shell @tab sh
+@item SQL @tab sql @tab SQLite @tab sqlite
+@end multitable
+
+Language-specific documentation is available for some languages. If
+available, it can be found at
+@uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
+
+The option @code{org-babel-load-languages} controls which languages are
+enabled for evaluation (by default only @code{emacs-lisp} is enabled). This
+variable can be set using the customization interface or by adding code like
+the following to your emacs configuration.
+
+@quotation
+The following disables @code{emacs-lisp} evaluation and enables evaluation of
+@code{R} code blocks.
+@end quotation
+
+@lisp
+(org-babel-do-load-languages
+ 'org-babel-load-languages
+ '((emacs-lisp . nil)
+ (R . t)))
+@end lisp
+
+It is also possible to enable support for a language by loading the related
+elisp file with @code{require}.
+
+@quotation
+The following adds support for evaluating @code{clojure} code blocks.
+@end quotation
+
+@lisp
+(require 'ob-clojure)
+@end lisp
+
+@node Header arguments, Results of evaluation, Languages, Working With Source Code
+@section Header arguments
+@cindex code block, header arguments
+@cindex source code, block header arguments
+
+Code block functionality can be configured with header arguments. This
+section provides an overview of the use of header arguments, and then
+describes each header argument in detail.
+
+@menu
+* Using header arguments:: Different ways to set header arguments
+* Specific header arguments:: List of header arguments
+@end menu
+
+@node Using header arguments, Specific header arguments, Header arguments, Header arguments
+@subsection Using header arguments
+
+The values of header arguments can be set in several way. When the header
+arguments in each layer have been determined, they are combined in order from
+the first, least specific (having the lowest priority) up to the last, most
+specific (having the highest priority). A header argument with a higher
+priority replaces the same header argument specified at lower priority.
+@menu
+* System-wide header arguments:: Set global default values
+* Language-specific header arguments:: Set default values by language
+* Header arguments in Org mode properties:: Set default values for a buffer or heading
+* Language-specific header arguments in Org mode properties:: Set language-specific default values for a buffer or heading
+* Code block specific header arguments:: The most common way to set values
+* Header arguments in function calls:: The most specific level
+@end menu
+
+
+@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments
+@subsubheading System-wide header arguments
+@vindex org-babel-default-header-args
+System-wide values of header arguments can be specified by adapting the
+@code{org-babel-default-header-args} variable:
+
+@example
+:session => "none"
+:results => "replace"
+:exports => "code"
+:cache => "no"
+:noweb => "no"
+@end example
+
+For example, the following example could be used to set the default value of
+@code{:noweb} header arguments to @code{yes}. This would have the effect of
+expanding @code{:noweb} references by default when evaluating source code
+blocks.
+
+@lisp
+(setq org-babel-default-header-args
+ (cons '(:noweb . "yes")
+ (assq-delete-all :noweb org-babel-default-header-args)))
+@end lisp
+
+@node Language-specific header arguments, Header arguments in Org mode properties, System-wide header arguments, Using header arguments
+@subsubheading Language-specific header arguments
+Each language can define its own set of default header arguments in variable
+@code{org-babel-default-header-args:<lang>}, where @code{<lang>} is the name
+of the language. See the language-specific documentation available online at
+@uref{http://orgmode.org/worg/org-contrib/babel}.
+
+@node Header arguments in Org mode properties, Language-specific header arguments in Org mode properties, Language-specific header arguments, Using header arguments
+@subsubheading Header arguments in Org mode properties
+
+Buffer-wide header arguments may be specified as properties through the use
+of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see
+@ref{Property syntax}).
+
+For example the following would set @code{session} to @code{*R*} (only for R
+code blocks), and @code{results} to @code{silent} for every code block in the
+buffer, ensuring that all execution took place in the same session, and no
+results would be inserted into the buffer.
+
+@example
+#+PROPERTY: header-args:R :session *R*
+#+PROPERTY: header-args :results silent
+@end example
+
+Header arguments read from Org mode properties can also be set on a
+per-subtree basis using property drawers (see @ref{Property syntax}).
+@vindex org-use-property-inheritance
+When properties are used to set default header arguments, they are always
+looked up with inheritance, regardless of the value of
+@code{org-use-property-inheritance}. Properties are evaluated as seen by the
+outermost call or source block.@footnote{The deprecated syntax for default
+header argument properties, using the name of the header argument as a
+property name directly, evaluates the property as seen by the corresponding
+source block definition. This behavior has been kept for backwards
+compatibility.}
+
+In the following example the value of
+the @code{:cache} header argument will default to @code{yes} in all code
+blocks in the subtree rooted at the following heading:
+
+@example
+* outline header
+ :PROPERTIES:
+ :header-args: :cache yes
+ :END:
+@end example
+
+@kindex C-c C-x p
+@vindex org-babel-default-header-args
+Properties defined in this way override the properties set in
+@code{org-babel-default-header-args} and are applied for all activated
+languages. It is convenient to use the @code{org-set-property} function
+bound to @kbd{C-c C-x p} to set properties in Org mode documents.
+
+@node Language-specific header arguments in Org mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments
+@subsubheading Language-specific header arguments in Org mode properties
+
+Language-specific header arguments are also read from properties
+@code{header-args:<lang>} where @code{<lang>} is the name of the language
+targeted. As an example
+
+@example
+* Heading
+ :PROPERTIES:
+ :header-args:clojure: :session *clojure-1*
+ :header-args:R: :session *R*
+ :END:
+** Subheading
+ :PROPERTIES:
+ :header-args:clojure: :session *clojure-2*
+ :END:
+@end example
+
+would independently set a default session header argument for R and clojure
+for calls and source blocks under subtree ``Heading'' and change to a
+different clojure setting for evaluations under subtree ``Subheading'', while
+the R session is inherited from ``Heading'' and therefore unchanged.
+
+@node Code block specific header arguments, Header arguments in function calls, Language-specific header arguments in Org mode properties, Using header arguments
+@subsubheading Code block specific header arguments
+
+The most common way to assign values to header arguments is at the
+code block level. This can be done by listing a sequence of header
+arguments and their values as part of the @code{#+BEGIN_SRC} line.
+Properties set in this way override both the values of
+@code{org-babel-default-header-args} and header arguments specified as
+properties. In the following example, the @code{:results} header argument
+is set to @code{silent}, meaning the results of execution will not be
+inserted in the buffer, and the @code{:exports} header argument is set to
+@code{code}, meaning only the body of the code block will be
+preserved on export to HTML or @LaTeX{}.
+
+@example
+#+NAME: factorial
+#+BEGIN_SRC haskell :results silent :exports code :var n=0
+fac 0 = 1
+fac n = n * fac (n-1)
+#+END_SRC
+@end example
+Similarly, it is possible to set header arguments for inline code blocks
+
+@example
+src_haskell[:exports both]@{fac 5@}
+@end example
+
+Code block header arguments can span multiple lines using @code{#+HEADER:} or
+@code{#+HEADERS:} lines preceding a code block or nested between the
+@code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block.
+@cindex #+HEADER:
+@cindex #+HEADERS:
+
+Multi-line header arguments on an un-named code block:
+
+@example
+ #+HEADERS: :var data1=1
+ #+BEGIN_SRC emacs-lisp :var data2=2
+ (message "data1:%S, data2:%S" data1 data2)
+ #+END_SRC
+
+ #+RESULTS:
+ : data1:1, data2:2
+@end example
+
+Multi-line header arguments on a named code block:
+
+@example
+ #+NAME: named-block
+ #+HEADER: :var data=2
+ #+BEGIN_SRC emacs-lisp
+ (message "data:%S" data)
+ #+END_SRC
+
+ #+RESULTS: named-block
+ : data:2
+@end example
+
+@node Header arguments in function calls, , Code block specific header arguments, Using header arguments
+@comment node-name, next, previous, up
+@subsubheading Header arguments in function calls
+
+At the most specific level, header arguments for ``Library of Babel'' or
+@code{#+CALL:} lines can be set as shown in the two examples below. For more
+information on the structure of @code{#+CALL:} lines see @ref{Evaluating code
+blocks}.
+
+The following will apply the @code{:exports results} header argument to the
+evaluation of the @code{#+CALL:} line.
+
+@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
+
+@node Specific header arguments, , Using header arguments, Header arguments
+@subsection Specific header arguments
+Header arguments consist of an initial colon followed by the name of the
+argument in lowercase letters. The following header arguments are defined:
+
+@menu
+* var:: Pass arguments to code blocks
+* results:: Specify the type of results and how they will
+ be collected and handled
+* file:: Specify a path for file output
+* file-desc:: Specify a description for file results
+* dir:: Specify the default (possibly remote)
+ directory for code block execution
+* exports:: Export code and/or results
+* tangle:: Toggle tangling and specify file name
+* mkdirp:: Toggle creation of parent directories of target
+ files during tangling
+* comments:: Toggle insertion of comments in tangled
+ code files
+* padline:: Control insertion of padding lines in tangled
+ code files
+* no-expand:: Turn off variable assignment and noweb
+ expansion during tangling
+* 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
+* colnames:: Handle column names in tables
+* rownames:: Handle row names in tables
+* shebang:: Make tangled files executable
+* tangle-mode:: Set permission of tangled files
+* eval:: Limit evaluation of specific code blocks
+* wrap:: Mark source block evaluation results
+* post:: Post processing of code block results
+* prologue:: Text to prepend to code block body
+* epilogue:: Text to append to code block body
+@end menu
+
+Additional header arguments are defined on a language-specific basis, see
+@ref{Languages}.
+
+@node var, results, Specific header arguments, Specific header arguments
+@subsubsection @code{:var}
+The @code{:var} header argument is used to pass arguments to code blocks.
+The specifics of how arguments are included in a code block vary by language;
+these are addressed in the language-specific documentation. However, the
+syntax used to specify arguments is the same across all languages. In every
+case, variables require a default value when they are declared.
+
+The values passed to arguments can either be literal values, references, or
+Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}).
+References include anything in the Org mode file that takes a @code{#+NAME:}
+or @code{#+RESULTS:} line: tables, lists, @code{#+BEGIN_EXAMPLE} blocks,
+other code blocks and the results of other code blocks.
+
+Note: When a reference is made to another code block, the referenced block
+will be evaluated unless it has current cached results (see @ref{cache}).
+
+Argument values can be indexed in a manner similar to arrays (see @ref{var,
+Indexable variable values}).
+
+The following syntax is used to pass arguments to code blocks using the
+@code{:var} header argument.
+
+@example
+:var name=assign
+@end example
+
+The argument, @code{assign}, can either be a literal value, such as a string
+@samp{"string"} or a number @samp{9}, or a reference to a table, a list, a
+literal example, another code block (with or without arguments), or the
+results of evaluating another code block.
+
+Here are examples of passing values by reference:
+
+@table @dfn
+
+@item table
+an Org mode table named with either a @code{#+NAME:} line
+
+@example
+#+NAME: example-table
+| 1 |
+| 2 |
+| 3 |
+| 4 |
+
+#+NAME: table-length
+#+BEGIN_SRC emacs-lisp :var table=example-table
+(length table)
+#+END_SRC
+
+#+RESULTS: table-length
+: 4
+@end example
+
+@item list
+a simple list named with a @code{#+NAME:} line (note that nesting is not
+carried through to the source code block)
+
+@example
+#+NAME: example-list
+ - simple
+ - not
+ - nested
+ - list
+
+#+BEGIN_SRC emacs-lisp :var x=example-list
+ (print x)
+#+END_SRC
+
+#+RESULTS:
+| simple | list |
+@end example
+
+@item code block without arguments
+a code block name (from the example above), as assigned by @code{#+NAME:},
+optionally followed by parentheses
+
+@example
+#+BEGIN_SRC emacs-lisp :var length=table-length()
+(* 2 length)
+#+END_SRC
+
+#+RESULTS:
+: 8
+@end example
+
+@item code block with arguments
+a code block name, as assigned by @code{#+NAME:}, followed by parentheses and
+optional arguments passed within the parentheses following the
+code block name using standard function call syntax
+
+@example
+#+NAME: double
+#+BEGIN_SRC emacs-lisp :var input=8
+(* 2 input)
+#+END_SRC
+
+#+RESULTS: double
+: 16
+
+#+NAME: squared
+#+BEGIN_SRC emacs-lisp :var input=double(input=1)
+(* input input)
+#+END_SRC
+
+#+RESULTS: squared
+: 4
+@end example
+
+@item literal example
+a literal example block named with a @code{#+NAME:} line
+
+@example
+#+NAME: literal-example
+#+BEGIN_EXAMPLE
+A literal example
+on two lines
+#+END_EXAMPLE
+
+#+NAME: read-literal-example
+#+BEGIN_SRC emacs-lisp :var x=literal-example
+ (concatenate 'string x " for you.")
+#+END_SRC
+
+#+RESULTS: read-literal-example
+: A literal example
+: on two lines for you.
+
+@end example
+
+@end table
+
+@subsubheading Indexable variable values
+It is possible to reference portions of variable values by ``indexing'' into
+the variables. Indexes are 0 based with negative values counting back from
+the end. If an index is separated by @code{,}s then each subsequent section
+will index into the next deepest nesting or dimension of the value. Note
+that this indexing occurs @emph{before} other table related header arguments
+like @code{:hlines}, @code{:colnames} and @code{:rownames} are applied. The
+following example assigns the last cell of the first row the table
+@code{example-table} to the variable @code{data}:
+
+@example
+#+NAME: example-table
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
+
+#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
+ data
+#+END_SRC
+
+#+RESULTS:
+: a
+@end example
+
+Ranges of variable values can be referenced using two integers separated by a
+@code{:}, in which case the entire inclusive range is referenced. For
+example the following assigns the middle three rows of @code{example-table}
+to @code{data}.
+
+@example
+#+NAME: example-table
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
+| 5 | 3 |
+
+#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
+ data
+#+END_SRC
+
+#+RESULTS:
+| 2 | b |
+| 3 | c |
+| 4 | d |
+@end example
+
+Additionally, an empty index, or the single character @code{*}, are both
+interpreted to mean the entire range and as such are equivalent to
+@code{0:-1}, as shown in the following example in which the entire first
+column is referenced.
+
+@example
+#+NAME: example-table
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
+
+#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
+ data
+#+END_SRC
+
+#+RESULTS:
+| 1 | 2 | 3 | 4 |
+@end example
+
+It is possible to index into the results of code blocks as well as tables.
+Any number of dimensions can be indexed. Dimensions are separated from one
+another by commas, as shown in the following example.
+
+@example
+#+NAME: 3D
+#+BEGIN_SRC emacs-lisp
+ '(((1 2 3) (4 5 6) (7 8 9))
+ ((10 11 12) (13 14 15) (16 17 18))
+ ((19 20 21) (22 23 24) (25 26 27)))
+#+END_SRC
+
+#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
+ data
+#+END_SRC
+
+#+RESULTS:
+| 11 | 14 | 17 |
+@end example
+
+@subsubheading Emacs Lisp evaluation of variables
+
+Emacs lisp code can be used to initialize variable values. When a variable
+value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be
+evaluated as Emacs Lisp and the result of the evaluation will be assigned as
+the variable value. The following example demonstrates use of this
+evaluation to reliably pass the file-name of the Org mode buffer to a code
+block---note that evaluation of header arguments is guaranteed to take place
+in the original Org mode file, while there is no such guarantee for
+evaluation of the code block body.
+
+@example
+#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
+ wc -w $filename
+#+END_SRC
+@end example
+
+Note that values read from tables and lists will not be evaluated as
+Emacs Lisp, as shown in the following example.
+
+@example
+#+NAME: table
+| (a b c) |
+
+#+HEADERS: :var data=table[0,0]
+#+BEGIN_SRC perl
+ $data
+#+END_SRC
+
+#+RESULTS:
+: (a b c)
+@end example
+
+@node results, file, var, Specific header arguments
+@subsubsection @code{:results}
+
+There are four classes of @code{:results} header argument. Only one option
+per class may be supplied per code block.
+
+@itemize @bullet
+@item
+@b{collection} header arguments specify how the results should be collected
+from the code block
+@item
+@b{type} header arguments specify what type of result the code block will
+return---which has implications for how they will be processed before
+insertion into the Org mode buffer
+@item
+@b{format} header arguments specify what type of result the code block will
+return---which has implications for how they will be inserted into the
+Org mode buffer
+@item
+@b{handling} header arguments specify how the results of evaluating the code
+block should be handled.
+@end itemize
+
+@subsubheading Collection
+The following options are mutually exclusive, and specify how the results
+should be collected from the code block.
+
+@itemize @bullet
+@item @code{value}
+This is the default. The result is the value of the last statement in the
+code block. This header argument places the evaluation in functional
+mode. Note that in some languages, e.g., Python, use of this result type
+requires that a @code{return} statement be included in the body of the source
+code block. E.g., @code{:results value}.
+@item @code{output}
+The result is the collection of everything printed to STDOUT during the
+execution of the code block. This header argument places the
+evaluation in scripting mode. E.g., @code{:results output}.
+@end itemize
+
+@subsubheading Type
+
+The following options are mutually exclusive and specify what type of results
+the code block will return. By default, results are inserted as either a
+table or scalar depending on their value.
+
+@itemize @bullet
+@item @code{table}, @code{vector}
+The results should be interpreted as an Org mode table. If a single value is
+returned, it will be converted into a table with one row and one column.
+E.g., @code{:results value table}.
+@item @code{list}
+The results should be interpreted as an Org mode list. If a single scalar
+value is returned it will be converted into a list with only one element.
+@item @code{scalar}, @code{verbatim}
+The results should be interpreted literally---they will not be
+converted into a table. The results will be inserted into the Org mode
+buffer as quoted text. E.g., @code{:results value verbatim}.
+@item @code{file}
+The results will be interpreted as the path to a file, and will be inserted
+into the Org mode buffer as a file link. E.g., @code{:results value file}.
+@end itemize
+
+@subsubheading Format
+
+The following options are mutually exclusive and specify what type of results
+the code block will return. By default, results are inserted according to the
+type as specified above.
+
+@itemize @bullet
+@item @code{raw}
+The results are interpreted as raw Org mode code and are inserted directly
+into the buffer. If the results look like a table they will be aligned as
+such by Org mode. E.g., @code{:results value raw}.
+@item @code{org}
+The results are will be enclosed in a @code{BEGIN_SRC org} block.
+They are not comma-escaped by default but they will be if you hit @kbd{TAB}
+in the block and/or if you export the file. E.g., @code{:results value org}.
+@item @code{html}
+Results are assumed to be HTML and will be enclosed in a @code{BEGIN_HTML}
+block. E.g., @code{:results value html}.
+@item @code{latex}
+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.
+E.g., @code{:results value code}.
+@item @code{pp}
+The result is converted to pretty-printed code and is enclosed in a code
+block. This option currently supports Emacs Lisp, Python, and Ruby. E.g.,
+@code{:results value pp}.
+@item @code{drawer}
+The result is wrapped in a RESULTS drawer. This can be useful for
+inserting @code{raw} or @code{org} syntax results in such a way that their
+extent is known and they can be automatically removed or replaced.
+@end itemize
+
+@subsubheading Handling
+The following results options indicate what happens with the
+results once they are collected.
+
+@itemize @bullet
+@item @code{silent}
+The results will be echoed in the minibuffer but will not be inserted into
+the Org mode buffer. E.g., @code{:results output silent}.
+@item @code{replace}
+The default value. Any existing results will be removed, and the new results
+will be inserted into the Org mode buffer in their place. E.g.,
+@code{:results output replace}.
+@item @code{append}
+If there are pre-existing results of the code block then the new results will
+be appended to the existing results. Otherwise the new results will be
+inserted as with @code{replace}.
+@item @code{prepend}
+If there are pre-existing results of the code block then the new results will
+be prepended to the existing results. Otherwise the new results will be
+inserted as with @code{replace}.
+@end itemize
+
+@node file, file-desc, results, Specific header arguments
+@subsubsection @code{:file}
+
+The header argument @code{:file} is used to specify an external file in which
+to save code block results. After code block evaluation an Org mode style
+@code{[[file:]]} link (see @ref{Link format}) to the file will be inserted
+into the Org mode buffer. Some languages including R, gnuplot, dot, and
+ditaa provide special handling of the @code{:file} header argument
+automatically wrapping the code block body in the boilerplate code required
+to save output to the specified file. This is often useful for saving
+graphical output of a code block to the specified file.
+
+The argument to @code{:file} should be either a string specifying the path to
+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 file-desc, dir, file, Specific header arguments
+@subsubsection @code{:file-desc}
+
+The value of the @code{:file-desc} header argument is used to provide a
+description for file code block results which are inserted as Org mode links
+(see @ref{Link format}). If the @code{:file-desc} header argument is given
+with no value the link path will be placed in both the ``link'' and the
+``description'' portion of the Org mode link.
+
+@node dir, exports, file-desc, Specific header arguments
+@subsubsection @code{:dir} and remote execution
+
+While the @code{:file} header argument can be used to specify the path to the
+output file, @code{:dir} specifies the default directory during code block
+execution. If it is absent, then the directory associated with the current
+buffer is used. In other words, supplying @code{:dir path} temporarily has
+the same effect as changing the current directory with @kbd{M-x cd path RET}, and
+then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets
+the value of the Emacs variable @code{default-directory}.
+
+When using @code{:dir}, you should supply a relative path for file output
+(e.g., @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
+case that path will be interpreted relative to the default directory.
+
+In other words, if you want your plot to go into a folder called @file{Work}
+in your home directory, you could use
+
+@example
+#+BEGIN_SRC R :file myplot.png :dir ~/Work
+matplot(matrix(rnorm(100), 10), type="l")
+#+END_SRC
+@end example
+
+@subsubheading Remote execution
+A directory on a remote machine can be specified using tramp file syntax, in
+which case the code will be evaluated on the remote machine. An example is
+
+@example
+#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu:
+plot(1:10, main=system("hostname", intern=TRUE))
+#+END_SRC
+@end example
+
+Text results will be returned to the local Org mode buffer as usual, and file
+output will be created on the remote machine with relative paths interpreted
+relative to the remote directory. An Org mode link to the remote file will be
+created.
+
+So, in the above example a plot will be created on the remote machine,
+and a link of the following form will be inserted in the org buffer:
+
+@example
+[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
+@end example
+
+Most of this functionality follows immediately from the fact that @code{:dir}
+sets the value of the Emacs variable @code{default-directory}, thanks to
+tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to
+install tramp separately in order for these features to work correctly.
+
+@subsubheading Further points
+
+@itemize @bullet
+@item
+If @code{:dir} is used in conjunction with @code{:session}, although it will
+determine the starting directory for a new session as expected, no attempt is
+currently made to alter the directory associated with an existing session.
+@item
+@code{:dir} should typically not be used to create files during export with
+@code{:exports results} or @code{:exports both}. The reason is that, in order
+to retain portability of exported material between machines, during export
+links inserted into the buffer will @emph{not} be expanded against @code{default
+directory}. Therefore, if @code{default-directory} is altered using
+@code{:dir}, it is probable that the file will be created in a location to
+which the link does not point.
+@end itemize
+
+@node exports, tangle, dir, Specific header arguments
+@subsubsection @code{:exports}
+
+The @code{:exports} header argument specifies what should be included in HTML
+or @LaTeX{} exports of the Org mode file.
+
+@itemize @bullet
+@item @code{code}
+The default. The body of code is included into the exported file. E.g.,
+@code{:exports code}.
+@item @code{results}
+The result of evaluating the code is included in the exported file. E.g.,
+@code{:exports results}.
+@item @code{both}
+Both the code and results are included in the exported file. E.g.,
+@code{:exports both}.
+@item @code{none}
+Nothing is included in the exported file. E.g., @code{:exports none}.
+@end itemize
+
+@node tangle, mkdirp, exports, Specific header arguments
+@subsubsection @code{:tangle}
+
+The @code{:tangle} header argument specifies whether or not the code
+block should be included in tangled extraction of source code files.
+
+@itemize @bullet
+@item @code{tangle}
+The code block is exported to a source code file named after the full path
+(including the directory) and file name (w/o extension) of the Org mode file.
+E.g., @code{:tangle yes}.
+@item @code{no}
+The default. The code block is not exported to a source code file.
+E.g., @code{:tangle no}.
+@item other
+Any other string passed to the @code{:tangle} header argument is interpreted
+as a path (directory and file name relative to the directory of the Org mode
+file) to which the block will be exported. E.g., @code{:tangle path}.
+@end itemize
+
+@node mkdirp, comments, tangle, Specific header arguments
+@subsubsection @code{:mkdirp}
+
+The @code{:mkdirp} header argument can be used to create parent directories
+of tangled files when missing. This can be set to @code{yes} to enable
+directory creation or to @code{no} to inhibit directory creation.
+
+@node comments, padline, mkdirp, Specific header arguments
+@subsubsection @code{:comments}
+By default code blocks are tangled to source-code files without any insertion
+of comments beyond those which may already exist in the body of the code
+block. The @code{:comments} header argument can be set as follows to control
+the insertion of extra comments into the tangled code file.
+
+@itemize @bullet
+@item @code{no}
+The default. No extra comments are inserted during tangling.
+@item @code{link}
+The code block is wrapped in comments which contain pointers back to the
+original Org file from which the code was tangled.
+@item @code{yes}
+A synonym for ``link'' to maintain backwards compatibility.
+@item @code{org}
+Include text from the Org mode file as a comment.
+The text is picked from the leading context of the tangled code and is
+limited by the nearest headline or source block as the case may be.
+@item @code{both}
+Turns on both the ``link'' and ``org'' comment options.
+@item @code{noweb}
+Turns on the ``link'' comment option, and additionally wraps expanded noweb
+references in the code block body in link comments.
+@end itemize
+
+@node padline, no-expand, comments, Specific header arguments
+@subsubsection @code{:padline}
+Control in insertion of padding lines around code block bodies in tangled
+code files. The default value is @code{yes} which results in insertion of
+newlines before and after each tangled code block. The following arguments
+are accepted.
+
+@itemize @bullet
+@item @code{yes}
+Insert newlines before and after each code block body in tangled code files.
+@item @code{no}
+Do not insert any newline padding in tangled output.
+@end itemize
+
+@node no-expand, session, padline, Specific header arguments
+@subsubsection @code{:no-expand}
+
+By default, code blocks are expanded with @code{org-babel-expand-src-block}
+during tangling. This has the effect of assigning values to variables
+specified with @code{:var} (see @ref{var}), and of replacing ``noweb''
+references (see @ref{Noweb reference syntax}) with their targets. The
+@code{:no-expand} header argument can be used to turn off this behavior.
+
+@node session, noweb, no-expand, Specific header arguments
+@subsubsection @code{:session}
+
+The @code{:session} header argument starts a session for an interpreted
+language where state is preserved.
+
+By default, a session is not started.
+
+A string passed to the @code{:session} header argument will give the session
+a name. This makes it possible to run concurrent sessions for each
+interpreted language.
+
+@node noweb, noweb-ref, session, Specific header arguments
+@subsubsection @code{:noweb}
+
+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{no}
+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}
+``Noweb'' syntax references in the body of the code block will be expanded
+before the code block is tangled. However, ``noweb'' syntax references will
+not be expanded when the code block is evaluated or exported.
+@item @code{no-export}
+``Noweb'' syntax references in the body of the code block will be expanded
+before the block is evaluated or tangled. However, ``noweb'' syntax
+references will not be expanded when the code block is exported.
+@item @code{strip-export}
+``Noweb'' syntax references in the body of the code block will be expanded
+before the block is evaluated or tangled. However, ``noweb'' syntax
+references will be removed when the code block is exported.
+@item @code{eval}
+``Noweb'' syntax references in the body of the code block will only be
+expanded before the block is evaluated.
+@end itemize
+
+@subsubheading Noweb prefix lines
+Noweb insertions are now placed behind the line prefix of the
+@code{<<reference>>}.
+This behavior is illustrated in the following example. Because the
+@code{<<example>>} noweb reference appears behind the SQL comment syntax,
+each line of the expanded noweb reference will be commented.
+
+This code block:
+
+@example
+-- <<example>>
+@end example
+
+expands to:
+
+@example
+-- this is the
+-- multi-line body of example
+@end example
+
+Note that noweb replacement text that does not contain any newlines will not
+be affected by this change, so it is still possible to use inline noweb
+references.
+
+@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
+@code{:noweb-ref} header argument matching the reference name will be
+concatenated together to form the replacement text.
+
+By setting this header argument at the sub-tree or file level, simple code
+block concatenation may be achieved. For example, when tangling the
+following Org mode file, the bodies of code blocks will be concatenated into
+the resulting pure code file@footnote{(The example needs property inheritance
+to be turned on for the @code{noweb-ref} property, see @ref{Property
+inheritance}).}.
+
+@example
+ #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
+ <<fullest-disk>>
+ #+END_SRC
+ * the mount point of the fullest disk
+ :PROPERTIES:
+ :noweb-ref: fullest-disk
+ :END:
+
+ ** query all mounted disks
+ #+BEGIN_SRC sh
+ df \
+ #+END_SRC
+
+ ** strip the header row
+ #+BEGIN_SRC sh
+ |sed '1d' \
+ #+END_SRC
+
+ ** sort by the percent full
+ #+BEGIN_SRC sh
+ |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
+ #+END_SRC
+
+ ** extract the mount point
+ #+BEGIN_SRC sh
+ |awk '@{print $2@}'
+ #+END_SRC
+@end example
+
+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. 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}
+The default. No caching takes place, and the code block will be evaluated
+every time it is called.
+@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
+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
+
+Code block caches notice if the value of a variable argument
+to the code block has changed. If this is the case, the cache is
+invalidated and the code block is re-run. In the following example,
+@code{caller} will not be re-run unless the results of @code{random} have
+changed since it was last run.
+
+@example
+ #+NAME: random
+ #+BEGIN_SRC R :cache yes
+ runif(1)
+ #+END_SRC
+
+ #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
+ 0.4659510825295
+
+ #+NAME: caller
+ #+BEGIN_SRC emacs-lisp :var x=random :cache yes
+ x
+ #+END_SRC
+
+ #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
+ 0.254227238707244
+@end example
+
+@node sep, hlines, cache, Specific header arguments
+@subsubsection @code{:sep}
+
+The @code{:sep} header argument can be used to control the delimiter used
+when writing tabular results out to files external to Org mode. This is used
+either when opening tabular results of a code block by calling the
+@code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block,
+or when writing code block results to an external file (see @ref{file})
+header argument.
+
+By default, when @code{:sep} is not specified output tables are tab
+delimited.
+
+@node hlines, colnames, sep, Specific header arguments
+@subsubsection @code{:hlines}
+
+Tables are frequently represented with one or more horizontal lines, or
+hlines. The @code{:hlines} argument to a code block accepts the
+values @code{yes} or @code{no}, with a default value of @code{no}.
+
+@itemize @bullet
+@item @code{no}
+Strips horizontal lines from the input table. In most languages this is the
+desired effect because an @code{hline} symbol is interpreted as an unbound
+variable and raises an error. Setting @code{:hlines no} or relying on the
+default value yields the following results.
+
+@example
+#+NAME: many-cols
+| a | b | c |
+|---+---+---|
+| d | e | f |
+|---+---+---|
+| g | h | i |
+
+#+NAME: echo-table
+#+BEGIN_SRC python :var tab=many-cols
+ return tab
+#+END_SRC
+
+#+RESULTS: echo-table
+| a | b | c |
+| d | e | f |
+| g | h | i |
+@end example
+
+@item @code{yes}
+Leaves hlines in the table. Setting @code{:hlines yes} has this effect.
+
+@example
+#+NAME: many-cols
+| a | b | c |
+|---+---+---|
+| d | e | f |
+|---+---+---|
+| g | h | i |
+
+#+NAME: echo-table
+#+BEGIN_SRC python :var tab=many-cols :hlines yes
+ return tab
+#+END_SRC
+
+#+RESULTS: echo-table
+| a | b | c |
+|---+---+---|
+| d | e | f |
+|---+---+---|
+| g | h | i |
+@end example
+@end itemize
+
+@node colnames, rownames, hlines, Specific header arguments
+@subsubsection @code{:colnames}
+
+The @code{:colnames} header argument accepts the values @code{yes},
+@code{no}, or @code{nil} for unassigned. The default value is @code{nil}.
+Note that the behavior of the @code{:colnames} header argument may differ
+across languages.
+
+@itemize @bullet
+@item @code{nil}
+If an input table looks like it has column names
+(because its second row is an hline), then the column
+names will be removed from the table before
+processing, then reapplied to the results.
+
+@example
+#+NAME: less-cols
+| a |
+|---|
+| b |
+| c |
+
+#+NAME: echo-table-again
+#+BEGIN_SRC python :var tab=less-cols
+ return [[val + '*' for val in row] for row in tab]
+#+END_SRC
+
+#+RESULTS: echo-table-again
+| a |
+|----|
+| b* |
+| c* |
+@end example
+
+Please note that column names are not removed before the table is indexed
+using variable indexing @xref{var, Indexable variable values}.
+
+@item @code{no}
+No column name pre-processing takes place
+
+@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
+hline)
+@end itemize
+
+@node rownames, shebang, colnames, Specific header arguments
+@subsubsection @code{:rownames}
+
+The @code{:rownames} header argument can take on the values @code{yes} or
+@code{no}, with a default value of @code{no}. Note that Emacs Lisp code
+blocks ignore the @code{:rownames} header argument entirely given the ease
+with which tables with row names may be handled directly in Emacs Lisp.
+
+@itemize @bullet
+@item @code{no}
+No row name pre-processing will take place.
+
+@item @code{yes}
+The first column of the table is removed from the table before processing,
+and is then reapplied to the results.
+
+@example
+#+NAME: with-rownames
+| one | 1 | 2 | 3 | 4 | 5 |
+| two | 6 | 7 | 8 | 9 | 10 |
+
+#+NAME: echo-table-once-again
+#+BEGIN_SRC python :var tab=with-rownames :rownames yes
+ return [[val + 10 for val in row] for row in tab]
+#+END_SRC
+
+#+RESULTS: echo-table-once-again
+| one | 11 | 12 | 13 | 14 | 15 |
+| two | 16 | 17 | 18 | 19 | 20 |
+@end example
+
+Please note that row names are not removed before the table is indexed using
+variable indexing @xref{var, Indexable variable values}.
+
+@end itemize
+
+@node shebang, tangle-mode, rownames, Specific header arguments
+@subsubsection @code{:shebang}
+
+Setting the @code{:shebang} header argument to a string value
+(e.g., @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
+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 tangle-mode, eval, shebang, Specific header arguments
+@subsubsection @code{:tangle-mode}
+
+The @code{tangle-mode} header argument controls the permission set on tangled
+files. The value of this header argument will be passed to
+@code{set-file-modes}. For example, to set a tangled file as read only use
+@code{:tangle-mode (identity #o444)}, or to set a tangled file as executable
+use @code{:tangle-mode (identity #o755)}. Blocks with @code{shebang}
+(@ref{shebang}) header arguments will automatically be made executable unless
+the @code{tangle-mode} header argument is also used. The behavior is
+undefined if multiple code blocks with different values for the
+@code{tangle-mode} header argument are tangled to the same file.
+
+@node eval, wrap, tangle-mode, Specific header arguments
+@subsubsection @code{:eval}
+The @code{:eval} header argument can be used to limit the evaluation of
+specific code blocks. The @code{:eval} header argument can be useful for
+protecting against the evaluation of dangerous code blocks or to ensure that
+evaluation will require a query regardless of the value of the
+@code{org-confirm-babel-evaluate} variable. The possible values of
+@code{:eval} and their effects are shown below.
+
+@table @code
+@item never or no
+The code block will not be evaluated under any circumstances.
+@item query
+Evaluation of the code block will require a query.
+@item never-export or no-export
+The code block will not be evaluated during export but may still be called
+interactively.
+@item query-export
+Evaluation of the code block during export will require a query.
+@end table
+
+If this header argument is not set then evaluation is determined by the value
+of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation
+security}.
+
+@node wrap, post, eval, Specific header arguments
+@subsubsection @code{:wrap}
+The @code{:wrap} header argument is used to mark the results of source block
+evaluation. The header argument can be passed a string that will be appended
+to @code{#+BEGIN_} and @code{#+END_}, which will then be used to wrap the
+results. If not string is specified then the results will be wrapped in a
+@code{#+BEGIN/END_RESULTS} block.
+
+@node post, prologue, wrap, Specific header arguments
+@subsubsection @code{:post}
+The @code{:post} header argument is used to post-process the results of a
+code block execution. When a post argument is given, the results of the code
+block will temporarily be bound to the @code{*this*} variable. This variable
+may then be included in header argument forms such as those used in @ref{var}
+header argument specifications allowing passing of results to other code
+blocks, or direct execution via Emacs Lisp.
+
+The following example illustrates the usage of the @code{:post} header
+argument.
+
+@example
+#+name: attr_wrap
+#+begin_src sh :var data="" :var width="\\textwidth" :results output
+ echo "#+ATTR_LATEX :width $width"
+ echo "$data"
+#+end_src
+
+#+header: :file /tmp/it.png
+#+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer
+ digraph@{
+ a -> b;
+ b -> c;
+ c -> a;
+ @}
+#+end_src
+
+#+RESULTS:
+:RESULTS:
+#+ATTR_LATEX :width 5cm
+[[file:/tmp/it.png]]
+:END:
+@end example
+
+@node prologue, epilogue, post, Specific header arguments
+@subsubsection @code{:prologue}
+The value of the @code{prologue} header argument will be prepended to the
+code block body before execution. For example, @code{:prologue "reset"} may
+be used to reset a gnuplot session before execution of a particular code
+block, or the following configuration may be used to do this for all gnuplot
+code blocks. Also see @ref{epilogue}.
+
+@lisp
+(add-to-list 'org-babel-default-header-args:gnuplot
+ '((:prologue . "reset")))
+@end lisp
+
+@node epilogue, , prologue, Specific header arguments
+@subsubsection @code{:epilogue}
+The value of the @code{epilogue} header argument will be appended to the code
+block body before execution. Also see @ref{prologue}.
+
+@node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code
+@section Results of evaluation
+@cindex code block, results of evaluation
+@cindex source code, results of evaluation
+
+The way in which results are handled depends on whether a session is invoked,
+as well as on whether @code{:results value} or @code{:results output} is
+used. The following table shows the table possibilities. For a full listing
+of the possible results header arguments see @ref{results}.
+
+@multitable @columnfractions 0.26 0.33 0.41
+@item @tab @b{Non-session} @tab @b{Session}
+@item @code{:results value} @tab value of last expression @tab value of last expression
+@item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
+@end multitable
+
+Note: With @code{:results value}, the result in both @code{:session} and
+non-session is returned to Org mode as a table (a one- or two-dimensional
+vector of strings or numbers) when appropriate.
+
+@subsection Non-session
+@subsubsection @code{:results value}
+This is the default. Internally, the value is obtained by wrapping the code
+in a function definition in the external language, and evaluating that
+function. Therefore, code should be written as if it were the body of such a
+function. In particular, note that Python does not automatically return a
+value from a function unless a @code{return} statement is present, and so a
+@samp{return} statement will usually be required in Python.
+
+This is the only one of the four evaluation contexts in which the code is
+automatically wrapped in a function definition.
+
+@subsubsection @code{:results output}
+The code is passed to the interpreter as an external process, and the
+contents of the standard output stream are returned as text. (In certain
+languages this also contains the error output stream; this is an area for
+future work.)
+
+@subsection Session
+@subsubsection @code{:results value}
+The code is passed to an interpreter running as an interactive Emacs inferior
+process. Only languages which provide tools for interactive evaluation of
+code have session support, so some language (e.g., C and ditaa) do not
+support the @code{:session} header argument, and in other languages (e.g.,
+Python and Haskell) which have limitations on the code which may be entered
+into interactive sessions, those limitations apply to the code in code blocks
+using the @code{:session} header argument as well.
+
+Unless the @code{:results output} option is supplied (see below) the result
+returned is the result of the last evaluation performed by the
+interpreter. (This is obtained in a language-specific manner: the value of
+the variable @code{_} in Python and Ruby, and the value of @code{.Last.value}
+in R).
+
+@subsubsection @code{:results output}
+The code is passed to the interpreter running as an interactive Emacs
+inferior process. The result returned is the concatenation of the sequence of
+(text) output from the interactive interpreter. Notice that this is not
+necessarily the same as what would be sent to @code{STDOUT} if the same code
+were passed to a non-interactive interpreter running as an external
+process. For example, compare the following two blocks:
+
+@example
+#+BEGIN_SRC python :results output
+ print "hello"
+ 2
+ print "bye"
+#+END_SRC
-Since Unison (for example) can be configured as to which files to transfer to
-a certain remote destination, it can greatly simplify the project publishing
-definition. Simply keep all files in the correct location, process your Org
-files with @code{org-publish} and let the synchronization tool do the rest.
-You do not need, in this scenario, to include attachments such as @file{jpg},
-@file{css} or @file{gif} files in the project definition since the 3rd party
-tool syncs them.
+#+RESULTS:
+: hello
+: bye
+@end example
-Publishing to a local directory is also much faster than to a remote one, so
-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
-Org is not smart enough to detect if included files have been modified.
+In non-session mode, the `2' is not printed and does not appear.
-@node Sample configuration, Triggering publication, Uploading files, Publishing
-@section Sample configuration
+@example
+#+BEGIN_SRC python :results output :session
+ print "hello"
+ 2
+ print "bye"
+#+END_SRC
-Below we provide two example configurations. The first one is a simple
-project publishing only a set of Org files. The second example is
-more complex, with a multi-component project.
+#+RESULTS:
+: hello
+: 2
+: bye
+@end example
-@menu
-* Simple example:: One-component publishing
-* Complex example:: A multi-component publishing example
-@end menu
+But in @code{:session} mode, the interactive interpreter receives input `2'
+and prints out its value, `2'. (Indeed, the other print statements are
+unnecessary here).
-@node Simple example, Complex example, Sample configuration, Sample configuration
-@subsection Example: simple publishing configuration
+@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code
+@section Noweb reference syntax
+@cindex code block, noweb reference
+@cindex syntax, noweb
+@cindex source code, noweb reference
-This example publishes a set of Org files to the @file{public_html}
-directory on the local machine.
+The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate
+Programming system allows named blocks of code to be referenced by using the
+familiar Noweb syntax:
-@lisp
-(setq org-publish-project-alist
- '(("org"
- :base-directory "~/org/"
- :publishing-directory "~/public_html"
- :section-numbers nil
- :table-of-contents nil
- :style "<link rel=\"stylesheet\"
- href=\"../other/mystyle.css\"
- type=\"text/css\"/>")))
-@end lisp
+@example
+<<code-block-name>>
+@end example
-@node Complex example, , Simple example, Sample configuration
-@subsection Example: complex publishing configuration
+When a code block is tangled or evaluated, whether or not ``noweb''
+references are expanded depends upon the value of the @code{:noweb} header
+argument. If @code{:noweb yes}, then a Noweb reference is expanded before
+evaluation. If @code{:noweb no}, the default, then the reference is not
+expanded before evaluation. See the @ref{noweb-ref} header argument for
+a more flexible way to resolve noweb references.
-This more complicated example publishes an entire website, including
-Org files converted to HTML, image files, Emacs Lisp source code, and
-style sheets. The publishing directory is remote and private files are
-excluded.
+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.
-To ensure that links are preserved, care should be taken to replicate
-your directory structure on the web server, and to use relative file
-paths. For example, if your Org files are kept in @file{~/org} and your
-publishable images in @file{~/images}, you'd link to an image with
-@c
@example
-file:../images/myimage.png
+<<code-block-name(optional arguments)>>
@end example
-@c
-On the web server, the relative path to the image should be the
-same. You can accomplish this by setting up an "images" folder in the
-right place on the web server, and publishing images to it.
-@lisp
-(setq org-publish-project-alist
- '(("orgfiles"
- :base-directory "~/org/"
- :base-extension "org"
- :publishing-directory "/ssh:user@@host:~/html/notebook/"
- :publishing-function org-publish-org-to-html
- :exclude "PrivatePage.org" ;; regexp
- :headline-levels 3
- :section-numbers nil
- :table-of-contents nil
- :style "<link rel=\"stylesheet\"
- href=\"../other/mystyle.css\" type=\"text/css\"/>"
- :auto-preamble t
- :auto-postamble nil)
+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.
- ("images"
- :base-directory "~/images/"
- :base-extension "jpg\\|gif\\|png"
- :publishing-directory "/ssh:user@@host:~/html/images/"
- :publishing-function org-publish-attachment)
+Note: if noweb tangling is slow in large Org mode files consider setting the
+@code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}.
+This will result in faster noweb reference resolution at the expense of not
+correctly resolving inherited values of the @code{:noweb-ref} header
+argument.
- ("other"
- :base-directory "~/other/"
- :base-extension "css\\|el"
- :publishing-directory "/ssh:user@@host:~/html/other/"
- :publishing-function org-publish-attachment)
- ("website" :components ("orgfiles" "images" "other"))))
-@end lisp
+@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code
+@section Key bindings and useful functions
+@cindex code block, key bindings
-@node Triggering publication, , Sample configuration, Publishing
-@section Triggering publication
+Many common Org mode key sequences are re-bound depending on
+the context.
-Once properly configured, Org can publish with the following commands:
+Within a code block, the following key bindings
+are active:
-@table @kbd
-@kindex C-c C-e C
-@item C-c C-e C
-Prompt for a specific project and publish all files that belong to it.
-@kindex C-c C-e P
-@item C-c C-e P
-Publish the project containing the current file.
-@kindex C-c C-e F
-@item C-c C-e F
-Publish only the current file.
-@kindex C-c C-e E
-@item C-c C-e E
-Publish every project.
-@end table
+@multitable @columnfractions 0.25 0.75
+@kindex C-c C-c
+@item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
+@kindex C-c C-o
+@item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
+@kindex C-up
+@item @kbd{C-@key{up}} @tab @code{org-babel-load-in-session}
+@kindex M-down
+@item @kbd{M-@key{down}} @tab @code{org-babel-pop-to-session}
+@end multitable
-@vindex org-publish-use-timestamps-flag
-Org uses timestamps to track when a file has changed. The above functions
-normally only publish changed files. You can override this and force
-publishing of all files by giving a prefix argument to any of the commands
-above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
-This may be necessary in particular if files include other files via
-@code{#+SETUPFILE:} or @code{#+INCLUDE:}.
+In an Org mode buffer, the following key bindings are active:
+
+@multitable @columnfractions 0.45 0.55
+@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 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-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
+@c kept pressed, resulting in the following additional keybindings.
+
+@c @multitable @columnfractions 0.25 0.75
+@c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
+@c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
+@c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
+@c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
+@c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
+@c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
+@c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
+@c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
+@c @end multitable
+
+@node Batch execution, , Key bindings and useful functions, Working With Source Code
+@section Batch execution
+@cindex code block, batch execution
+@cindex source code, batch execution
+
+It is possible to call functions from the command line. This shell
+script calls @code{org-babel-tangle} on every one of its arguments.
+
+Be sure to adjust the paths to fit your system.
-@node Miscellaneous, Hacking, Publishing, Top
+@example
+#!/bin/sh
+# -*- mode: shell-script -*-
+#
+# tangle files with org-mode
+#
+DIR=`pwd`
+FILES=""
+
+# wrap each argument in the code required to call tangle on it
+for i in $@@; do
+ FILES="$FILES \"$i\""
+done
+
+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/\" t))
+(require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
+(mapc (lambda (file)
+ (find-file (expand-file-name file \"$DIR\"))
+ (org-babel-tangle)
+ (kill-buffer)) '($FILES)))" 2>&1 |grep tangled
+@end example
+
+@node Miscellaneous, Hacking, Working With Source Code, Top
@chapter Miscellaneous
@menu
* Completion:: M-TAB knows what you need
-* Speed keys:: Electic commands at the beginning of a headline
+* Easy Templates:: Quick insertion of structural elements
+* Speed keys:: Electric commands at the beginning of a headline
+* Code evaluation security:: Org mode files evaluate inline code
* Customization:: Adapting Org to your taste
* In-buffer settings:: Overview of the #+KEYWORDS
* The very busy C-c C-c key:: When in doubt, press C-c C-c
* Clean view:: Getting rid of leading stars in the outline
* TTY keys:: Using Org on a tty
* Interaction:: Other Emacs packages
+* org-crypt:: Encrypting Org files
@end menu
-@node Completion, Speed keys, Miscellaneous, Miscellaneous
+@node Completion, Easy Templates, Miscellaneous, Miscellaneous
@section Completion
@cindex completion, of @TeX{} symbols
@cindex completion, of TODO keywords
@cindex tag completion
@cindex link abbreviations, completion of
-Emacs would not be Emacs without completion, and Org-mode uses it whenever it
+Emacs would not be Emacs without completion, and Org mode uses it whenever it
makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for
some of the completion prompts, you can specify your preference by setting at
most one of the variables @code{org-completion-use-iswitchb}
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
@end table
-@node Speed keys, Customization, Completion, Miscellaneous
+@node Easy Templates, Speed keys, Completion, Miscellaneous
+@section Easy Templates
+@cindex template insertion
+@cindex insertion, of templates
+
+Org mode supports insertion of empty structural elements (like
+@code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key
+strokes. This is achieved through a native template expansion mechanism.
+Note that Emacs has several other template mechanisms which could be used in
+a similar way, for example @file{yasnippet}.
+
+To insert a structural element, type a @samp{<}, followed by a template
+selector and @kbd{@key{TAB}}. Completion takes effect only when the above
+keystrokes are typed on a line by itself.
+
+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
+@end multitable
+
+For example, on an empty line, typing "<e" and then pressing TAB, will expand
+into a complete EXAMPLE template.
+
+You can install additional templates by customizing the variable
+@code{org-structure-template-alist}. See the docstring of the variable for
+additional details.
+
+@node Speed keys, Code evaluation security, Easy Templates, Miscellaneous
@section Speed keys
@cindex speed keys
@vindex org-use-speed-commands
@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
navigation and other commands, but they also provide an alternative way to
-execute commands bound to keys that are not or not easily available on a tty,
+execute commands bound to keys that are not or not easily available on a TTY,
or on a small mobile device with a limited keyboard.
To see which commands are available, activate the feature and press @kbd{?}
with the cursor at the beginning of a headline.
-@node Customization, In-buffer settings, Speed keys, Miscellaneous
+@node Code evaluation security, Customization, Speed keys, Miscellaneous
+@section Code evaluation and security issues
+
+Org provides tools to work with the code snippets, including evaluating them.
+
+Running code on your machine always comes with a security risk. Badly
+written or malicious code can be executed on purpose or by accident. Org has
+default settings which will only evaluate such code if you give explicit
+permission to do so, and as a casual user of these features you should leave
+these precautions intact.
+
+For people who regularly work with such code, the confirmation prompts can
+become annoying, and you might want to turn them off. This can be done, but
+you must be aware of the risks that are involved.
+
+Code evaluation can happen under the following circumstances:
+
+@table @i
+@item Source code blocks
+Source code blocks can be evaluated during export, or when pressing @kbd{C-c
+C-c} in the block. The most important thing to realize here is that Org mode
+files which contain code snippets are, in a certain sense, like executable
+files. So you should accept them and load them into Emacs only from trusted
+sources---just like you would do with a program you install on your computer.
+
+Make sure you know what you are doing before customizing the variables
+which take off the default security brakes.
+
+@defopt org-confirm-babel-evaluate
+When t (the default), the user is asked before every code block evaluation.
+When @code{nil}, the user is not asked. When set to a function, it is called with
+two arguments (language and body of the code block) and should return t to
+ask and @code{nil} not to ask.
+@end defopt
+
+For example, here is how to execute "ditaa" code (which is considered safe)
+without asking:
+
+@lisp
+(defun my-org-confirm-babel-evaluate (lang body)
+ (not (string= lang "ditaa"))) ; don't ask for ditaa
+(setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
+@end lisp
+
+@item Following @code{shell} and @code{elisp} links
+Org has two link types that can directly evaluate code (@pxref{External
+links}). These links can be problematic because the code to be evaluated is
+not visible.
+
+@defopt org-confirm-shell-link-function
+Function to queries user about shell link execution.
+@end defopt
+@defopt org-confirm-elisp-link-function
+Functions to query user for Emacs Lisp link execution.
+@end defopt
+
+@item Formulas in tables
+Formulas in tables (@pxref{The spreadsheet}) are code that is evaluated
+either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter.
+@end table
+
+@node Customization, In-buffer settings, Code evaluation security, Miscellaneous
@section Customization
@cindex customization
@cindex options, for customization
@cindex variables, for customization
-There are more than 180 variables that can be used to customize
+There are more than 500 variables that can be used to customize
Org. For the sake of compactness of the manual, I am not
describing the variables here. A structured overview of customization
-variables is available with @kbd{M-x org-customize}. Or select
+variables is available with @kbd{M-x org-customize RET}. Or select
@code{Browse Org Group} from the @code{Org->Customization} menu. Many
settings can also be activated on a per-file basis, by putting special
lines into the buffer (@pxref{In-buffer settings}).
@vindex org-table-formula-constants
@vindex org-table-formula
Set file-local values for constants to be used in table formulas. This
-line set the local variable @code{org-table-formula-constants-local}.
+line sets the local variable @code{org-table-formula-constants-local}.
The global version of this variable is
@code{org-table-formula-constants}.
@item #+FILETAGS: :tag1:tag2:tag3:
top-level entries.
@item #+DRAWERS: NAME1 .....
@vindex org-drawers
-Set the file-local set of drawers. The corresponding global variable is
-@code{org-drawers}.
+Set the file-local set of additional drawers. The corresponding global
+variable is @code{org-drawers}.
@item #+LINK: linkword replace
@vindex org-link-abbrev-alist
These lines (several are allowed) specify link abbreviations.
@vindex org-lowest-priority
@vindex org-default-priority
This line sets the limits and the default for the priorities. All three
-must be either letters A-Z or numbers 0-9. The highest priority must
-have a lower ASCII number that the lowest priority.
+must be either letters A--Z or numbers 0--9. The highest priority must
+have a lower ASCII number than the lowest priority.
@item #+PROPERTY: Property_Name Value
This line sets a default inheritance value for entries in the current
buffer, most useful for specifying the allowed values of a property.
@item #+SETUPFILE: file
This line defines a file that holds more in-buffer setup. Normally this is
entirely ignored. Only when the buffer is parsed for option-setting lines
-(i.e. when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
+(i.e., when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
settings line, or when exporting), then the contents of this file are parsed
as if they had been included in the buffer. In particular, the file can be
any other Org mode file with internal setup. You can visit the file the
cursor is in the line with @kbd{C-c '}.
@item #+STARTUP:
-@cindex #+STARTUP:
+@cindex #+STARTUP
This line sets options to be used at startup of Org mode, when an
Org file is being visited.
@cindex @code{indent}, STARTUP keyword
@cindex @code{noindent}, STARTUP keyword
Dynamic virtual indentation is controlled by the variable
-@code{org-startup-indented}@footnote{Emacs 23 and Org-mode 6.29 are required}
+@code{org-startup-indented}@footnote{Emacs 23 and Org mode 6.29 are required}
@example
indent @r{start with @code{org-indent-mode} turned on}
noindent @r{start with @code{org-indent-mode} turned off}
align @r{align all tables}
noalign @r{don't align tables on startup}
@end example
+
+@vindex org-startup-with-inline-images
+When visiting a file, inline images can be automatically displayed. The
+corresponding variable is @code{org-startup-with-inline-images}, with a
+default value @code{nil} to avoid delays when visiting a file.
+@cindex @code{inlineimages}, STARTUP keyword
+@cindex @code{noinlineimages}, STARTUP keyword
+@example
+inlineimages @r{show inline images}
+noinlineimages @r{don't show inline images on startup}
+@end example
+
+@vindex org-startup-with-latex-preview
+When visiting a file, @LaTeX{} fragments can be converted to images
+automatically. The variable @code{org-startup-with-latex-preview} which
+controls this behavior, is set to @code{nil} by default to avoid delays on
+startup.
+@cindex @code{latexpreview}, STARTUP keyword
+@cindex @code{nolatexpreview}, STARTUP keyword
+@example
+latexpreview @r{preview @LaTeX{} fragments}
+nolatexpreview @r{don't preview @LaTeX{} fragments}
+@end example
+
@vindex org-log-done
@vindex org-log-note-clock-out
@vindex org-log-repeat
@cindex @code{logredeadline}, STARTUP keyword
@cindex @code{lognoteredeadline}, STARTUP keyword
@cindex @code{nologredeadline}, STARTUP keyword
+@cindex @code{logrefile}, STARTUP keyword
+@cindex @code{lognoterefile}, STARTUP keyword
+@cindex @code{nologrefile}, STARTUP keyword
+@cindex @code{logdrawer}, STARTUP keyword
+@cindex @code{nologdrawer}, STARTUP keyword
+@cindex @code{logstatesreversed}, STARTUP keyword
+@cindex @code{nologstatesreversed}, STARTUP keyword
@example
-logdone @r{record a timestamp when an item is marked DONE}
-lognotedone @r{record timestamp and a note when DONE}
-nologdone @r{don't record when items are marked DONE}
-logrepeat @r{record a time when reinstating a repeating item}
-lognoterepeat @r{record a note when reinstating a repeating item}
-nologrepeat @r{do not record when reinstating repeating item}
-lognoteclock-out @r{record a note when clocking out}
-nolognoteclock-out @r{don't record a note when clocking out}
-logreschedule @r{record a timestamp when scheduling time changes}
-lognotereschedule @r{record a note when scheduling time changes}
-nologreschedule @r{do not record when a scheduling date changes}
-logredeadline @r{record a timestamp when deadline changes}
-lognoteredeadline @r{record a note when deadline changes}
-nologredeadline @r{do not record when a deadline date changes}
+logdone @r{record a timestamp when an item is marked DONE}
+lognotedone @r{record timestamp and a note when DONE}
+nologdone @r{don't record when items are marked DONE}
+logrepeat @r{record a time when reinstating a repeating item}
+lognoterepeat @r{record a note when reinstating a repeating item}
+nologrepeat @r{do not record when reinstating repeating item}
+lognoteclock-out @r{record a note when clocking out}
+nolognoteclock-out @r{don't record a note when clocking out}
+logreschedule @r{record a timestamp when scheduling time changes}
+lognotereschedule @r{record a note when scheduling time changes}
+nologreschedule @r{do not record when a scheduling date changes}
+logredeadline @r{record a timestamp when deadline changes}
+lognoteredeadline @r{record a note when deadline changes}
+nologredeadline @r{do not record when a deadline date changes}
+logrefile @r{record a timestamp when refiling}
+lognoterefile @r{record a note when refiling}
+nologrefile @r{do not record when refiling}
+logdrawer @r{store log into drawer}
+nologdrawer @r{store log outside of drawer}
+logstatesreversed @r{reverse the order of states notes}
+nologstatesreversed @r{do not reverse the order of states notes}
@end example
+
@vindex org-hide-leading-stars
@vindex org-odd-levels-only
Here are the options for hiding leading stars in outline headings, and for
odd @r{allow only odd outline levels (1,3,...)}
oddeven @r{allow all outline levels}
@end example
+
@vindex org-put-time-stamp-overlays
@vindex org-time-stamp-overlay-formats
To turn on custom format overlays over timestamps (variables
@example
customtime @r{overlay custom time format}
@end example
+
@vindex constants-unit-system
The following options influence the table spreadsheet (variable
@code{constants-unit-system}).
constcgs @r{@file{constants.el} should use the c-g-s unit system}
constSI @r{@file{constants.el} should use the SI unit system}
@end example
+
@vindex org-footnote-define-inline
@vindex org-footnote-auto-label
@vindex org-footnote-auto-adjust
fnnoinline @r{define footnotes in separate section}
fnlocal @r{define footnotes near first reference, but not inline}
fnprompt @r{prompt for footnote labels}
-fnauto @r{create [fn:1]-like labels automatically (default)}
+fnauto @r{create @code{[fn:1]}-like labels automatically (default)}
fnconfirm @r{offer automatic label for editing or confirmation}
-fnplain @r{create [1]-like labels automatically}
+fnplain @r{create @code{[1]}-like labels automatically}
fnadjust @r{automatically renumber and sort footnotes}
nofnadjust @r{do not renumber and sort automatically}
@end example
+
@cindex org-hide-block-startup
-To hide blocks on startup, use these keywords. The corresponding variable is
+To hide blocks on startup, use these keywords. The corresponding variable is
@code{org-hide-block-startup}.
@cindex @code{hideblocks}, STARTUP keyword
@cindex @code{nohideblocks}, STARTUP keyword
hideblocks @r{Hide all begin/end blocks on startup}
nohideblocks @r{Do not hide blocks on startup}
@end example
+
+@cindex org-pretty-entities
+The display of entities as UTF-8 characters is governed by the variable
+@code{org-pretty-entities} and the keywords
+@cindex @code{entitiespretty}, STARTUP keyword
+@cindex @code{entitiesplain}, STARTUP keyword
+@example
+entitiespretty @r{Show entities as UTF-8 characters where possible}
+entitiesplain @r{Leave entities plain}
+@end example
+
@item #+TAGS: TAG1(c1) TAG2(c2)
@vindex org-tag-alist
These lines (several such lines are allowed) specify the valid tags in
this file, and (potentially) the corresponding @emph{fast tag selection}
keys. The corresponding variable is @code{org-tag-alist}.
+@cindex #+TBLFM
@item #+TBLFM:
This line contains the formulas for the table directly above the line.
-@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,
-@itemx #+OPTIONS:, #+BIND:
-@itemx #+DESCRIPTION:, #+KEYWORDS:
-@itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,
-@itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:
+
+Table can have multiple lines containing @samp{#+TBLFM:}. Note
+that only the first line of @samp{#+TBLFM:} will be applied when
+you recalculate the table. For more details see @ref{Using
+multiple #+TBLFM lines} in @ref{Editing and debugging formulas}.
+
+@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
+@itemx #+OPTIONS:, #+BIND:,
+@itemx #+DESCRIPTION:, #+KEYWORDS:,
+@itemx #+LaTeX_HEADER:, #+LaTeX_HEADER_EXTRA:,
+@itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
+@itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
These lines provide settings for exporting files. For more details see
-@ref{Export options}.
+@ref{Export settings}.
@item #+TODO: #+SEQ_TODO: #+TYP_TODO:
@vindex org-todo-keywords
These lines set the TODO keywords and their interpretation in the
If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
the entire table.
@item
-If the cursor is inside a table created by the @file{table.el} package,
-activate that table.
-@item
-If the current buffer is a Remember buffer, close the note and file it.
+If the current buffer is a capture buffer, close the note and file it.
With a prefix argument, file it, without further interaction, to the
default location.
@item
drawer, offer property commands.
@item
If the cursor is at a footnote reference, go to the corresponding
-definition, and vice versa.
+definition, and @emph{vice versa}.
@item
If the cursor is on a statistics cookie, update it.
@item
@item
If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
block is updated.
+@item
+If the cursor is at a timestamp, fix the day name in the timestamp.
@end itemize
@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
@end example
@noindent
-If you are using at least Emacs 23.1.50.3 and version 6.29 of Org, this kind
-of view can be achieved dynamically at display time using
-@code{org-indent-mode}. In this minor mode, all lines are prefixed for
-display with the necessary amount of space. Also headlines are prefixed with
-additional stars, so that the amount of indentation shifts by
-two@footnote{See the variable @code{org-indent-indentation-per-level}.}
-spaces per level. All headline stars but the last one are made invisible
-using the @code{org-hide} face@footnote{Turning on @code{org-indent-mode}
-sets @code{org-hide-leading-stars} to @code{t} and
-@code{org-adapt-indentation} to @code{nil}.} - see below under @samp{2.} for
-more information on how this works. You can turn on @code{org-indent-mode}
-for all files by customizing the variable @code{org-startup-indented}, or you
-can turn it on for individual files using
+
+If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash
+with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can
+be achieved dynamically at display time using @code{org-indent-mode}. In
+this minor mode, all lines are prefixed for display with the necessary amount
+of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix}
+property, such that @code{visual-line-mode} (or purely setting
+@code{word-wrap}) wraps long lines (including headlines) correctly indented.
+}. Also headlines are prefixed with additional stars, so that the amount of
+indentation shifts by two@footnote{See the variable
+@code{org-indent-indentation-per-level}.} spaces per level. All headline
+stars but the last one are made invisible using the @code{org-hide}
+face@footnote{Turning on @code{org-indent-mode} sets
+@code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
+@code{nil}.}; see below under @samp{2.} for more information on how this
+works. You can turn on @code{org-indent-mode} for all files by customizing
+the variable @code{org-startup-indented}, or you can turn it on for
+individual files using
@example
#+STARTUP: indent
@end example
-If you want a similar effect in earlier version of Emacs and/or Org, or if
+If you want a similar effect in an earlier version of Emacs and/or Org, or if
you want the indentation to be hard space characters so that the plain text
file looks as similar as possible to the Emacs display, Org supports you in
the following way:
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
tty you would rather use @kbd{C-c .} to re-insert the timestamp.
@multitable @columnfractions 0.15 0.2 0.1 0.2
-@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
-@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab
-@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
-@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab
+@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
+@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab
+@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
+@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab
@item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
-@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab
-@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
-@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab
+@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab
+@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
+@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab
@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
-@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab
+@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab
@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab
@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab
@end multitable
-@node Interaction, , TTY keys, Miscellaneous
+@node Interaction, org-crypt, TTY keys, Miscellaneous
@section Interaction with other packages
@cindex packages, interaction with other
Org lives in the world of GNU Emacs and interacts in various ways
@code{calc-eval} which will have been autoloaded during setup if Calc has
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}.
+packages is using Calc for embedded calculations. @xref{Embedded Mode,
+, 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
-at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for
+@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
@file{constants.el}.
@item @file{cdlatex.el} by Carsten Dominik
@cindex @file{cdlatex.el}
@cindex Dominik, Carsten
-Org mode can make use of the CDLa@TeX{} package to efficiently enter
-La@TeX{} fragments into Org files. See @ref{CDLaTeX mode}.
+Org mode can make use of the CD@LaTeX{} package to efficiently enter
+@LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}.
@item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
@cindex @file{imenu.el}
Imenu allows menu access to an index of items in a file. Org mode
@item @file{remember.el} by John Wiegley
@cindex @file{remember.el}
@cindex Wiegley, John
-Org cooperates with remember, see @ref{Remember}.
-@file{Remember.el} is not part of Emacs, find it on the web.
+Org used to use this package for capture, but no longer does.
@item @file{speedbar.el} by Eric M. Ludlam
@cindex @file{speedbar.el}
@cindex Ludlam, Eric M.
@cindex @file{table.el}
@cindex Ota, Takaaki
-Complex ASCII tables with automatic line wrapping, column- and
-row-spanning, and alignment can be created using the Emacs table
-package by Takaaki Ota (@uref{http://sourceforge.net/projects/table},
-and also part of Emacs 22).
-When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org mode
-will call @command{table-recognize-table} and move the cursor into the
-table. Inside a table, the keymap of Org mode is inactive. In order
-to execute Org mode-related commands, leave the table.
+Complex ASCII tables with automatic line wrapping, column- and row-spanning,
+and alignment can be created using the Emacs table package by Takaaki Ota
+(@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22).
+Org mode will recognize these tables and export them properly. Because of
+interference with other Org mode functionality, you unfortunately cannot edit
+these tables directly in the buffer. Instead, you need to use the command
+@kbd{C-c '} to edit them, similar to source code snippets.
@table @kbd
-@kindex C-c C-c
-@item C-c C-c
-Recognize @file{table.el} table. Works when the cursor is in a
-table.el table.
+@orgcmd{C-c ',org-edit-special}
+Edit a @file{table.el} table. Works when the cursor is in a table.el table.
@c
-@kindex C-c ~
-@item C-c ~
+@orgcmd{C-c ~,org-table-create-with-table.el}
Insert a @file{table.el} table. If there is already a table at point, this
-command converts it between the @file{table.el} format and the Org-mode
+command converts it between the @file{table.el} format and the Org mode
format. See the documentation string of the command
@code{org-convert-table} for the restrictions under which this is
possible.
@end table
-@file{table.el} is part of Emacs 22.
+@file{table.el} is part of Emacs since Emacs 22.
@item @file{footnote.el} by Steven L. Baur
@cindex @file{footnote.el}
@cindex Baur, Steven L.
buffer (but not during date selection).
@example
-S-UP -> M-p S-DOWN -> M-n
-S-LEFT -> M-- S-RIGHT -> M-+
-C-S-LEFT -> M-S-- C-S-RIGHT -> M-S-+
+S-UP @result{} M-p S-DOWN @result{} M-n
+S-LEFT @result{} M-- S-RIGHT @result{} M-+
+C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+
@end example
@vindex org-disputed-keys
to have other replacement keys, look at the variable
@code{org-disputed-keys}.
+@item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org}
+@cindex @file{ecomplete.el}
+
+Ecomplete provides ``electric'' address completion in address header
+lines in message buffers. Sadly Orgtbl mode cuts ecompletes power
+supply: No completion happens when Orgtbl mode is enabled in message
+buffers while entering text in address header lines. If one wants to
+use ecomplete one should @emph{not} follow the advice to automagically
+turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but
+instead---after filling in the message headers---turn on Orgtbl mode
+manually when needed in the messages body.
+
+@item @file{filladapt.el} by Kyle Jones
+@cindex @file{filladapt.el}
+
+Org mode tries to do the right thing when filling paragraphs, list items and
+other elements. Many users reported they had problems using both
+@file{filladapt.el} and Org mode, so a safe thing to do is to disable it like
+this:
+
+@lisp
+(add-hook 'org-mode-hook 'turn-off-filladapt-mode)
+@end lisp
+
@item @file{yasnippet.el}
@cindex @file{yasnippet.el}
-The way Org-mode binds the TAB key (binding to @code{[tab]} instead of
-@code{"\t"}) overrules yasnippets' access to this key. The following code
+The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of
+@code{"\t"}) overrules YASnippet's access to this key. The following code
fixed this problem:
@lisp
(add-hook 'org-mode-hook
(lambda ()
(org-set-local 'yas/trigger-key [tab])
- (define-key yas/keymap [tab] 'yas/next-field-group)))
+ (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
+@end lisp
+
+The latest version of yasnippet doesn't play well with Org mode. If the
+above code does not fix the conflict, start by defining the following
+function:
+
+@lisp
+(defun yas/org-very-safe-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)))
@end lisp
@item @file{windmove.el} by Hovav Shacham
@cindex @file{windmove.el}
This package also uses the @kbd{S-<cursor>} keys, so everything written
-in the paragraph above about CUA mode also applies here.
+in the paragraph above about CUA mode also applies here. If you want make
+the windmove function active in locations where Org mode does not have
+special functionality on @kbd{S-@key{cursor}}, add this to your
+configuration:
+
+@lisp
+;; Make windmove work in org-mode:
+(add-hook 'org-shiftup-final-hook 'windmove-up)
+(add-hook 'org-shiftleft-final-hook 'windmove-left)
+(add-hook 'org-shiftdown-final-hook 'windmove-down)
+(add-hook 'org-shiftright-final-hook 'windmove-right)
+@end lisp
@item @file{viper.el} by Michael Kifer
@cindex @file{viper.el}
@kindex C-c /
Viper uses @kbd{C-c /} and therefore makes this key not access the
-corresponding Org-mode command @code{org-sparse-tree}. You need to find
+corresponding Org mode command @code{org-sparse-tree}. You need to find
another key for this command, or override the key in
@code{viper-vi-global-user-map} with
(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
@end lisp
+
+
@end table
+@node org-crypt, , Interaction, Miscellaneous
+@section org-crypt.el
+@cindex @file{org-crypt.el}
+@cindex @code{org-decrypt-entry}
+
+Org-crypt will encrypt the text of an entry, but not the headline, or
+properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
+files.
+
+Any text below a headline that has a @samp{:crypt:} tag will be automatically
+be encrypted when the file is saved. If you want to use a different tag just
+customize the @code{org-crypt-tag-matcher} setting.
+
+To use org-crypt it is suggested that you have the following in your
+@file{.emacs}:
+
+@lisp
+(require 'org-crypt)
+(org-crypt-use-before-save-magic)
+(setq org-tags-exclude-from-inheritance (quote ("crypt")))
+
+(setq org-crypt-key nil)
+ ;; GPG key to use for encryption
+ ;; Either the Key ID or set to nil to use symmetric encryption.
+
+(setq auto-save-default nil)
+ ;; Auto-saving does not cooperate with org-crypt.el: so you need
+ ;; to turn it off if you plan to use org-crypt.el quite often.
+ ;; Otherwise, you'll get an (annoying) message each time you
+ ;; start Org.
+
+ ;; To turn it off only locally, you can insert this:
+ ;;
+ ;; # -*- buffer-auto-save-file-name: nil; -*-
+@end lisp
+
+Excluding the crypt tag from inheritance prevents already encrypted text
+being encrypted again.
@node Hacking, MobileOrg, Miscellaneous, Top
@appendix Hacking
Org.
@menu
-* Hooks:: Who to reach into Org's internals
+* Hooks:: How to reach into Org's internals
* Add-on packages:: Available extensions
* Adding hyperlink types:: New custom link types
+* Adding export back-ends:: How to write new export back-ends
* Context-sensitive commands:: How to add functionality to such commands
-* Tables in arbitrary syntax:: Orgtbl for La@TeX{} and other programs
+* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
-* Extracting agenda information:: Postprocessing of agenda information
+* Speeding up your agendas:: Tips on how to speed up your agendas
+* Extracting agenda information:: Post-processing of agenda information
* Using the property API:: Writing programs that use entry properties
* Using the mapping API:: Mapping over all or selected entries
@end menu
@cindex add-on packages
A large number of add-on packages have been written by various authors.
+
These packages are not part of Emacs, but they are distributed as contributed
-packages with the separate release available at the Org mode home page at
-@uref{http://orgmode.org}. The list of contributed packages, along with
-documentation about each package, is maintained by the Worg project at
+packages with the separate release available at @uref{http://orgmode.org}.
+See the @file{contrib/README} file in the source code directory for a list of
+contributed files. You may also find some more information on the Worg page:
@uref{http://orgmode.org/worg/org-contrib/}.
-
-
-@node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking
+@node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking
@section Adding hyperlink types
@cindex hyperlinks, adding new types
the link description when the link is later inserted into an Org
buffer with @kbd{C-c C-l}.
-When is makes sense for your new link type, you may also define a function
-@code{org-PREFIX-complete-link} that implements special (e.g. completion)
+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)
support for inserting such a link with @kbd{C-c C-l}. Such a function should
not accept any arguments, and return the full link with prefix.
-@node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking
+@node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking
+@section Adding export back-ends
+@cindex Export, writing back-ends
+
+Org 8.0 comes with a completely rewritten export engine which makes it easy
+to write new export back-ends, either from scratch, or from deriving them
+from existing ones.
+
+Your two entry points are respectively @code{org-export-define-backend} and
+@code{org-export-define-derived-backend}. To grok these functions, you
+should first have a look at @file{ox-latex.el} (for how to define a new
+back-end from scratch) and @file{ox-beamer.el} (for how to derive a new
+back-end from an existing one.
+
+When creating a new back-end from scratch, the basic idea is to set the name
+of the back-end (as a symbol) and an an alist of elements and export
+functions. On top of this, you will need to set additional keywords like
+@code{:menu-entry} (to display the back-end in the export dispatcher),
+@code{:export-block} (to specify what blocks should not be exported by this
+back-end), and @code{:options-alist} (to let the user set export options that
+are specific to this back-end.)
+
+Deriving a new back-end is similar, except that you need to set
+@code{:translate-alist} to an alist of export functions that should be used
+instead of the parent back-end functions.
+
+For a complete reference documentation, see
+@url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
+Reference on Worg}.
+
+@node Context-sensitive commands, Tables in arbitrary syntax, Adding export back-ends, Hacking
@section Context-sensitive commands
@cindex context-sensitive commands, hooks
@cindex add-ons, context-sensitive commands
@vindex org-ctrl-c-ctrl-c-hook
Org has several commands that act differently depending on context. The most
-important example it the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
+important example is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property.
Add-ons can tap into this functionality by providing a function that detects
special context for that add-on and executes functionality appropriate for
the context. Here is an example from Dan Davison's @file{org-R.el} which
-allows you to evaluate commands based on the @file{R} programming language. For
-this package, special contexts are lines that start with @code{#+R:} or
+allows you to evaluate commands based on the @file{R} programming language
+@footnote{@file{org-R.el} has been replaced by the Org mode functionality
+described in @ref{Working With Source Code} and is now obsolete.}. For this
+package, special contexts are lines that start with @code{#+R:} or
@code{#+RR:}.
@lisp
The function first checks if the cursor is in such a line. If that is the
case, @code{org-R-apply} is called and the function returns @code{t} to
signal that action was taken, and @kbd{C-c C-c} will stop looking for other
-contexts. If the function finds it should do nothing locally, it returns @code{nil} so that other, similar functions can have a try.
+contexts. If the function finds it should do nothing locally, it returns
+@code{nil} so that other, similar functions can have a try.
@node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking
Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a
frequent feature request has been to make it work with native tables in
-specific languages, for example La@TeX{}. However, this is extremely
+specific languages, for example @LaTeX{}. However, this is extremely
hard to do in a general way, would lead to a customization nightmare,
-and would take away much of the simplicity of the Orgtbl-mode table
+and would take away much of the simplicity of the Orgtbl mode table
editor.
-
This appendix describes a different approach. We keep the Orgtbl mode
table in its native format (the @i{source table}), and use a custom
function to @i{translate} the table to the correct syntax, and to
the burden of writing conversion functions on the user, but it allows
for a very flexible system.
-Bastien added the ability to do the same with lists. You can use Org's
-facilities to edit and structure lists by turning @code{orgstruct-mode}
-on, then locally exporting such lists in another format (HTML, La@TeX{}
-or Texinfo.)
+Bastien added the ability to do the same with lists, in Orgstruct mode. You
+can use Org's facilities to edit and structure lists by turning
+@code{orgstruct-mode} on, then locally exporting such lists in another format
+(HTML, @LaTeX{} or Texinfo.)
@menu
* Radio tables:: Sending and receiving radio tables
-* A LaTeX example:: Step by step, almost a tutorial
+* A @LaTeX{} example:: Step by step, almost a tutorial
* Translator functions:: Copy and modify
-* Radio lists:: Doing the same for lists
+* Radio lists:: Sending and receiving lists
@end menu
-@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax
+@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax
@subsection Radio tables
@cindex radio tables
To define the location of the target table, you first need to create two
-lines that are comments in the current mode, but contain magic words for
-Orgtbl mode to find. Orgtbl mode will insert the translated table
-between these lines, replacing whatever was there before. For example:
+lines that are comments in the current mode, but contain magic words
+@code{BEGIN/END RECEIVE ORGTBL} for Orgtbl mode to find. Orgtbl mode will
+insert the translated table between these lines, replacing whatever was there
+before. For example in C mode where comments are between @code{/* ... */}:
@example
/* BEGIN RECEIVE ORGTBL table_name */
@noindent
@code{table_name} is the reference name for the table that is also used
-in the receiver lines. @code{translation_function} is the Lisp function
+in the receiver lines. @code{translation_function} is the Lisp function
that does the translation. Furthermore, the line can contain a list of
arguments (alternating key and value) at the end. The arguments will be
passed as a property list to the translation function for
Please note that the translator function sees the table @emph{after} the
removal of these columns, the function never knows that there have been
additional columns.
+
+@item :no-escape t
+When non-@code{nil}, do not escape special characters @code{&%#_^} when exporting
+the table. The default value is @code{nil}.
@end table
@noindent
The one problem remaining is how to keep the source table in the buffer
without disturbing the normal workings of the file, for example during
-compilation of a C file or processing of a La@TeX{} file. There are a
+compilation of a C file or processing of a @LaTeX{} file. There are a
number of different solutions:
@itemize @bullet
@item
Sometimes it is possible to put the table after some kind of @i{END}
statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}}
-in La@TeX{}.
+in @LaTeX{}.
@item
You can just comment the table line-by-line whenever you want to process
the file, and uncomment it whenever you need to edit the table. This
-only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment}
+only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment RET}
makes this comment-toggling very easy, in particular if you bind it to a
key.
@end itemize
-@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax
-@subsection A La@TeX{} example of radio tables
-@cindex La@TeX{}, and Orgtbl mode
+@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax
+@subsection A @LaTeX{} example of radio tables
+@cindex @LaTeX{}, and Orgtbl mode
-The best way to wrap the source table in La@TeX{} is to use the
+The best way to wrap the source table in @LaTeX{} is to use the
@code{comment} environment provided by @file{comment.sty}. It has to be
activated by placing @code{\usepackage@{comment@}} into the document
header. Orgtbl mode can insert a radio table skeleton@footnote{By
-default this works only for La@TeX{}, HTML, and Texinfo. Configure the
-variable @code{orgtbl-radio-tables} to install templates for other
-modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will
+default this works only for @LaTeX{}, HTML, and Texinfo. Configure the
+variable @code{orgtbl-radio-table-templates} to install templates for other
+modes.} with the command @kbd{M-x orgtbl-insert-radio-table RET}. You will
be prompted for a table name, let's say we use @samp{salesfigures}. You
will then get the following template:
@end example
@noindent
-@vindex La@TeX{}-verbatim-environments
+@vindex @LaTeX{}-verbatim-environments
The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function
-@code{orgtbl-to-latex} to convert the table into La@TeX{} and to put it
+@code{orgtbl-to-latex} to convert the table into @LaTeX{} and to put it
into the receiver location with name @code{salesfigures}. You may now
-fill in the table, feel free to use the spreadsheet features@footnote{If
+fill in the table---feel free to use the spreadsheet features@footnote{If
the @samp{#+TBLFM} line contains an odd number of dollar characters,
-this may cause problems with font-lock in La@TeX{} mode. As shown in the
+this may cause problems with font-lock in @LaTeX{} mode. As shown in the
example you can fix this by adding an extra line inside the
@code{comment} environment that is used to balance the dollar
expressions. If you are using AUC@TeX{} with the font-latex library, a
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
\end@{comment@}
@end example
-The La@TeX{} translator function @code{orgtbl-to-latex} is already part of
+The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
Orgtbl mode. It uses a @code{tabular} environment to typeset the table
and marks horizontal lines with @code{\hline}. Furthermore, it
interprets the following parameters (see also @pxref{Translator functions}):
@table @code
@item :splice nil/t
When set to t, return only table body lines, don't wrap them into a
-tabular environment. Default is nil.
+tabular environment. Default is @code{nil}.
@item :fmt fmt
A format to be used to wrap each field, it should contain @code{%s} for the
original field value. For example, to wrap each field value in dollars,
you could use @code{:fmt "$%s$"}. This may also be a property list with
-column numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
+column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
A function of one argument can be used in place of the strings; the
function must return a formatted string.
supplied instead of strings.
@end table
-@node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax
+@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax
@subsection Translator functions
@cindex HTML, and Orgtbl mode
@cindex translator function
As you can see, the properties passed into the function (variable
@var{PARAMS}) are combined with the ones newly defined in the function
-(variable @var{PARAMS2}). The ones passed into the function (i.e. the
+(variable @var{PARAMS2}). The ones passed into the function (i.e., the
ones set by the @samp{ORGTBL SEND} line) take precedence. So if you
-would like to use the La@TeX{} translator, but wanted the line endings to
+would like to use the @LaTeX{} translator, but wanted the line endings to
be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
overrule the default with
@end example
For a new language, you can either write your own converter function in
-analogy with the La@TeX{} translator, or you can use the generic function
+analogy with the @LaTeX{} translator, or you can use the generic function
directly. For example, if you have a language where a table is started
with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are
started with @samp{!BL!}, ended with @samp{!EL!}, and where the field
translator, please post it on @email{emacs-orgmode@@gnu.org} so that
others can benefit from your work.
-@node Radio lists, , Translator functions, Tables in arbitrary syntax
+@node Radio lists, , Translator functions, Tables in arbitrary syntax
@subsection Radio lists
@cindex radio lists
@cindex org-list-insert-radio-list
-Sending and receiving radio lists works exactly the same way than sending and
+Sending and receiving radio lists works exactly the same way as sending and
receiving radio tables (@pxref{Radio tables}). As for radio tables, you can
-insert radio lists templates in HTML, La@TeX{} and Texinfo modes by calling
+insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling
@code{org-list-insert-radio-list}.
Here are the differences with radio tables:
@itemize @minus
@item
-Use @code{ORGLST} instead of @code{ORGTBL}.
+Orgstruct mode must be active.
+@item
+Use the @code{ORGLST} keyword instead of @code{ORGTBL}.
@item
The available translation functions for radio lists don't take
parameters.
@kbd{C-c C-c} will work when pressed on the first item of the list.
@end itemize
-Here is a La@TeX{} example. Let's say that you have this in your
-La@TeX{} file:
+Here is a @LaTeX{} example. Let's say that you have this in your
+@LaTeX{} file:
-@cindex #+ORGLIST
+@cindex #+ORGLST
@example
% BEGIN RECEIVE ORGLST to-buy
% END RECEIVE ORGLST to-buy
\begin@{comment@}
-#+ORGLIST: SEND to-buy orgtbl-to-latex
+#+ORGLST: SEND to-buy org-list-to-latex
- a new house
- a new computer
+ a new keyboard
\end@{comment@}
@end example
-Pressing `C-c C-c' on @code{a new house} and will insert the converted
-La@TeX{} list between the two marker lines.
+Pressing @kbd{C-c C-c} on @code{a new house} and will insert the converted
+@LaTeX{} list between the two marker lines.
@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
@section Dynamic blocks
A good example for such a block is the clock table inserted by the
command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
-Dynamic block are enclosed by a BEGIN-END structure that assigns a name
+Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name
to the block and can also specify parameters for the function producing
the content of the block.
-#+BEGIN:dynamic block
+@cindex #+BEGIN:dynamic block
@example
#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
Dynamic blocks are updated with the following commands
@table @kbd
-@kindex C-c C-x C-u
-@item C-c C-x C-u
+@orgcmd{C-c C-x C-u,org-dblock-update}
Update dynamic block at point.
-@kindex C-u C-c C-x C-u
-@item C-u C-c C-x C-u
+@orgkey{C-u C-c C-x C-u}
Update all dynamic blocks in the current file.
@end table
@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,
written in a way such that it does nothing in buffers that are not in
@code{org-mode}.
-@node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking
+You can narrow the current buffer to the current dynamic block (like any
+other block) with @code{org-narrow-to-block}.
+
+@node Special agenda views, Speeding up your agendas, Dynamic blocks, Hacking
@section Special agenda views
@cindex agenda views, user-defined
-Org provides a special hook that can be used to narrow down the
-selection made by any of the agenda views. You may specify a function
-that is used at each match to verify if the match should indeed be part
-of the agenda view, and if not, how much should be skipped.
+@vindex org-agenda-skip-function
+@vindex org-agenda-skip-function-global
+Org provides a special hook that can be used to narrow down the selection
+made by these agenda views: @code{agenda}, @code{agenda*}@footnote{The
+@code{agenda*} view is the same than @code{agenda} except that it only
+considers @emph{appointments}, i.e., scheduled and deadline items that have a
+time specification @code{[h]h:mm} in their time-stamps.}, @code{todo},
+@code{alltodo}, @code{tags}, @code{tags-todo}, @code{tags-tree}. You may
+specify a function that is used at each match to verify if the match should
+indeed be part of the agenda view, and if not, how much should be skipped.
+You can specify a global condition that will be applied to all agenda views,
+this condition would be stored in the variable
+@code{org-agenda-skip-function-global}. More commonly, such a definition is
+applied only to specific custom searches, using
+@code{org-agenda-skip-function}.
Let's say you want to produce a list of projects that contain a WAITING
tag anywhere in the project tree. Let's further assume that you have
marked all tree headings that define a project with the TODO keyword
-PROJECT. In this case you would run a TODO search for the keyword
+PROJECT@. In this case you would run a TODO search for the keyword
PROJECT, but skip the match unless there is a WAITING tag anywhere in
the subtree belonging to the project line.
and @code{org-agenda-skip-subtree-if} in this form, for example:
@table @code
-@item '(org-agenda-skip-entry-if 'scheduled)
+@item (org-agenda-skip-entry-if 'scheduled)
Skip current entry if it has been scheduled.
-@item '(org-agenda-skip-entry-if 'notscheduled)
+@item (org-agenda-skip-entry-if 'notscheduled)
Skip current entry if it has not been scheduled.
-@item '(org-agenda-skip-entry-if 'deadline)
+@item (org-agenda-skip-entry-if 'deadline)
Skip current entry if it has a deadline.
-@item '(org-agenda-skip-entry-if 'scheduled 'deadline)
+@item (org-agenda-skip-entry-if 'scheduled 'deadline)
Skip current entry if it has a deadline, or if it is scheduled.
-@item '(org-agenda-skip-entry-if 'timestamp)
+@item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
+Skip current entry if the TODO keyword is TODO or WAITING.
+@item (org-agenda-skip-entry-if 'todo 'done)
+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")
+@item (org-agenda-skip-subtree-if 'regexp "regular expression")
Same as above, but check and skip the entire subtree.
@end table
(org-agenda-overriding-header "Projects waiting for something: "))))
@end lisp
-@node Extracting agenda information, Using the property API, Special agenda views, Hacking
+@node Speeding up your agendas, Extracting agenda information, Special agenda views, Hacking
+@section Speeding up your agendas
+@cindex agenda views, optimization
+
+When your Org files grow in both number and size, agenda commands may start
+to become slow. Below are some tips on how to speed up the agenda commands.
+
+@enumerate
+@item
+Reduce the number of Org agenda files: this will reduce the slowness caused
+by accessing a hard drive.
+@item
+Reduce the number of DONE and archived headlines: this way the agenda does
+not need to skip them.
+@item
+@vindex org-agenda-dim-blocked-tasks
+Inhibit the dimming of blocked tasks:
+@lisp
+(setq org-agenda-dim-blocked-tasks nil)
+@end lisp
+@item
+@vindex org-startup-folded
+@vindex org-agenda-inhibit-startup
+Inhibit agenda files startup options:
+@lisp
+(setq org-agenda-inhibit-startup nil)
+@end lisp
+@item
+@vindex org-agenda-show-inherited-tags
+@vindex org-agenda-use-tag-inheritance
+Disable tag inheritance in agenda:
+@lisp
+(setq org-agenda-use-tag-inheritance nil)
+@end lisp
+@end enumerate
+
+You can set these options for specific agenda views only. See the docstrings
+of these variables for details on why they affect the agenda generation, and
+this @uref{http://orgmode.org/worg/agenda-optimization.html, dedicated Worg
+page} for further explanations.
+
+@node Extracting agenda information, Using the property API, Speeding up your agendas, Hacking
@section Extracting agenda information
@cindex agenda, pipe
@cindex Scripts, for agenda processing
directly to a printer, or it can be read by a program that does further
processing of the data. The first of these commands is the function
@code{org-batch-agenda}, that produces an agenda view and sends it as
-ASCII text to STDOUT. The command takes a single string as parameter.
+ASCII text to STDOUT@. The command takes a single string as parameter.
If the string has length 1, it is used as a key to one of the commands
you have configured in @code{org-agenda-custom-commands}, basically any
key you can use after @kbd{C-c a}. For example, to directly print the
@example
emacs -batch -l ~/.emacs \
-eval '(org-batch-agenda "a" \
- org-agenda-ndays 30 \
+ org-agenda-span (quote month) \
org-agenda-include-diary nil \
org-agenda-files (quote ("~/org/project.org")))' \
| lpr
Get all properties of the entry at point-or-marker POM.@*
This includes the TODO keyword, the tags, time strings for deadline,
scheduled, and clocking, and any additional properties defined in the
-entry. The return value is an alist, keys may occur multiple times
+entry. The return value is an alist. Keys may occur multiple times
if the property key was used several times.@*
-POM may also be nil, in which case the current entry is used.
-If WHICH is nil or `all', get all properties. If WHICH is
+POM may also be @code{nil}, in which case the current entry is used.
+If WHICH is @code{nil} or `all', get all properties. If WHICH is
`special' or `standard', only get that subclass.
@end defun
@vindex org-use-property-inheritance
+@findex org-insert-property-drawer
@defun org-entry-get pom property &optional inherit
-Get value of PROPERTY for entry at point-or-marker POM. By default,
-this only looks at properties defined locally in the entry. If INHERIT
-is non-nil and the entry does not have the property, then also check
-higher levels of the hierarchy. If INHERIT is the symbol
+Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By default,
+this only looks at properties defined locally in the entry. If @code{INHERIT}
+is non-@code{nil} and the entry does not have the property, then also check
+higher levels of the hierarchy. If @code{INHERIT} is the symbol
@code{selective}, use inheritance if and only if the setting of
-@code{org-use-property-inheritance} selects PROPERTY for inheritance.
+@code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance.
@end defun
@defun org-entry-delete pom property
-Delete the property PROPERTY from entry at point-or-marker POM.
+Delete the property @code{PROPERTY} from entry at point-or-marker POM.
@end defun
@defun org-entry-put pom property value
-Set PROPERTY to VALUE for entry at point-or-marker POM.
+Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM.
@end defun
@defun org-buffer-property-keys &optional include-specials
@end defun
@defun org-insert-property-drawer
-Insert a property drawer at point.
+Insert a property drawer for the current entry. Also
@end defun
@defun org-entry-put-multivalued-property pom property &rest values
-Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a list of
-strings. They will be concatenated, with spaces as separators.
+Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@.
+@code{VALUES} should be a list of strings. They will be concatenated, with
+spaces as separators.
@end defun
@defun org-entry-get-multivalued-property pom property
-Treat the value of the property PROPERTY as a whitespace-separated list of
-values and return the values as a list of strings.
+Treat the value of the property @code{PROPERTY} as a whitespace-separated
+list of values and return the values as a list of strings.
@end defun
@defun org-entry-add-to-multivalued-property pom property value
-Treat the value of the property PROPERTY as a whitespace-separated list of
-values and make sure that VALUE is in this list.
+Treat the value of the property @code{PROPERTY} as a whitespace-separated
+list of values and make sure that @code{VALUE} is in this list.
@end defun
@defun org-entry-remove-from-multivalued-property pom property value
-Treat the value of the property PROPERTY as a whitespace-separated list of
-values and make sure that VALUE is @emph{not} in this list.
+Treat the value of the property @code{PROPERTY} as a whitespace-separated
+list of values and make sure that @code{VALUE} is @emph{not} in this list.
@end defun
@defun org-entry-member-in-multivalued-property pom property value
-Treat the value of the property PROPERTY as a whitespace-separated list of
-values and check if VALUE is in this list.
+Treat the value of the property @code{PROPERTY} as a whitespace-separated
+list of values and check if @code{VALUE} is in this list.
@end defun
+@defopt org-property-allowed-value-functions
+Hook for functions supplying allowed values for a specific property.
+The functions must take a single argument, the name of the property, and
+return a flat list of allowed values. If @samp{:ETC} is one of
+the values, use the values as completion help, but allow also other values
+to be entered. The functions must return @code{nil} if they are not
+responsible for this property.
+@end defopt
+
@node Using the mapping API, , Using the property API, Hacking
@section Using the mapping API
@cindex API, for mapping
is:
@defun org-map-entries func &optional match scope &rest skip
-Call FUNC at each headline selected by MATCH in SCOPE.
-
-FUNC is a function or a Lisp form. The function will be called without
-arguments, with the cursor positioned at the beginning of the headline.
-The return values of all calls to the function will be collected and
-returned as a list.
-
-The call to FUNC will be wrapped into a save-excursion form, so FUNC
-does not need to preserve point. After evaluation, the cursor will be
-moved to the end of the line (presumably of the headline of the
-processed entry) and search continues from there. Under some
-circumstances, this may not produce the wanted results. For example,
-if you have removed (e.g. archived) the current (sub)tree it could
-mean that the next entry will be skipped entirely. In such cases, you
-can specify the position from where search should continue by making
-FUNC set the variable `org-map-continue-from' to the desired buffer
-position.
-
-MATCH is a tags/property/todo match as it is used in the agenda match view.
-Only headlines that are matched by this query will be considered during
-the iteration. When MATCH is nil or t, all headlines will be
-visited by the iteration.
-
-SCOPE determines the scope of this command. It can be any of:
+Call @code{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
+
+@code{FUNC} is a function or a Lisp form. The function will be called
+without arguments, with the cursor positioned at the beginning of the
+headline. The return values of all calls to the function will be collected
+and returned as a list.
+
+The call to @code{FUNC} will be wrapped into a save-excursion form, so
+@code{FUNC} does not need to preserve point. After evaluation, the cursor
+will be moved to the end of the line (presumably of the headline of the
+processed entry) and search continues from there. Under some circumstances,
+this may not produce the wanted results. For example, if you have removed
+(e.g., archived) the current (sub)tree it could mean that the next entry will
+be skipped entirely. In such cases, you can specify the position from where
+search should continue by making @code{FUNC} set the variable
+@code{org-map-continue-from} to the desired buffer position.
+
+@code{MATCH} is a tags/property/todo match as it is used in the agenda match
+view. Only headlines that are matched by this query will be considered
+during the iteration. When @code{MATCH} is @code{nil} or @code{t}, all
+headlines will be visited by the iteration.
+
+@code{SCOPE} determines the scope of this command. It can be any of:
@example
nil @r{the current buffer, respecting the restriction if any}
tree @r{the subtree started with the entry at point}
+region @r{The entries within the active region, if any}
file @r{the current buffer, without restriction}
file-with-archives
@r{the current buffer, and any archives associated with it}
Here are a couple of functions that might be handy:
@defun org-todo &optional arg
-Change the TODO state of the entry, see the docstring of the functions for
-the many possible values for the argument ARG.
+Change the TODO state of the entry. See the docstring of the functions for
+the many possible values for the argument @code{ARG}.
@end defun
@defun org-priority &optional action
-Change the priority of the entry, see the docstring of this function for the
-possible values for ACTION.
+Change the priority of the entry. See the docstring of this function for the
+possible values for @code{ACTION}.
@end defun
@defun org-toggle-tag tag &optional onoff
-Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on}
-or @code{off} will not toggle tag, but ensure that it is either on or off.
+Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to
+either @code{on} or @code{off} will not toggle tag, but ensure that it is
+either on or off.
@end defun
@defun org-promote
@lisp
(org-map-entries
- '(org-todo "UPCOMING")
- "+TOMORROW" 'file 'archive 'comment)
+ '(org-todo "UPCOMING")
+ "+TOMORROW" 'file 'archive 'comment)
@end lisp
The following example counts the number of entries with TODO keyword
@cindex iPhone
@cindex MobileOrg
-@i{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. For information
-about @i{MobileOrg}, see @uref{http://mobileorg.ncogni.to/}).
+@i{MobileOrg} is the name of the mobile companion app for Org mode, currently
+available for iOS and for Android. @i{MobileOrg} offers offline viewing and
+capture support for an Org mode system rooted on a ``real'' computer. It
+does also allow you to record changes to existing entries. The
+@uref{https://github.com/MobileOrg/, iOS implementation} for the
+@i{iPhone/iPod Touch/iPad} series of devices, was started by Richard Moreland
+and is now in the hands Sean Escriva. Android users should check out
+@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
+by Matt Jones. The two implementations are not identical but offer similar
+features.
This appendix describes the support Org has for creating agenda views in a
format that can be displayed by @i{MobileOrg}, and for integrating notes
captured and changes made by @i{MobileOrg} into the main system.
For changing tags and TODO states in MobileOrg, you should have set up the
-customization variables @code{org-todo-keywords} and @code{org-tags-alist} to
-cover all important tags and todo keywords, even if individual files use only
+customization variables @code{org-todo-keywords} and @code{org-tag-alist} to
+cover all important tags and TODO keywords, even if individual files use only
part of these. MobileOrg will also offer you states and tags set up with
-in-buffer settings, but it will understand the logistics of todo state
+in-buffer settings, but it will understand the logistics of TODO state
@i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags
(@pxref{Setting tags}) only for those set in these variables.
@node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg
@section Setting up the staging area
-Org-mode has commands to prepare a directory with files for @i{MobileOrg},
-and to read captured notes from there. If Emacs can directly write to the
-WebDAV directory accessed by @i{MobileOrg}, just point to this directory
-using the variable @code{org-mobile-directory}. Using the @file{tramp}
-method, @code{org-mobile-directory} may point to a remote directory
-accessible through, for example,
-@file{ssh/scp}:
-
-@smallexample
-(setq org-mobile-directory "/scpc:user@@remote.host:org/webdav/")
-@end smallexample
+MobileOrg needs to interact with Emacs through a directory on a server. If you
+are using a public server, you should consider to encrypt the files that are
+uploaded to the server. This can be done with Org mode 7.02 and with
+@i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl}
+installation on your system. To turn on encryption, set a password in
+@i{MobileOrg} and, on the Emacs side, configure the variable
+@code{org-mobile-use-encryption}@footnote{If you can safely store the
+password in your Emacs setup, you might also want to configure
+@code{org-mobile-encryption-password}. Please read the docstring of that
+variable. Note that encryption will apply only to the contents of the
+@file{.org} files. The file names themselves will remain visible.}.
+
+The easiest way to create that directory is to use a free
+@uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use
+Dropbox, or if your version of MobileOrg does not support it, you can use a
+webdav server. For more information, check out the documentation of MobileOrg and also this
+@uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
+When MobileOrg first connects to your Dropbox, it will create a directory
+@i{MobileOrg} inside the Dropbox. After the directory has been created, tell
+Emacs about it:
-If Emacs cannot access the WebDAV directory directly using a @file{tramp}
-method, or you prefer to maintain a local copy, you can use a local directory
-for staging. Other means must then be used to keep this directory in sync
-with the WebDAV directory. In the following example, files are staged in
-@file{~/stage}, and Org-mode hooks take care of moving files to and from the
-WebDAV directory using @file{scp}.
+@lisp
+(setq org-mobile-directory "~/Dropbox/MobileOrg")
+@end lisp
-@smallexample
-(setq org-mobile-directory "~/stage/")
-(add-hook 'org-mobile-post-push-hook
- (lambda () (shell-command "scp -r ~/stage/* user@@wdhost:mobile/")))
-(add-hook 'org-mobile-pre-pull-hook
- (lambda () (shell-command "scp user@@wdhost:mobile/mobileorg.org ~/stage/ ")))
-(add-hook 'org-mobile-post-pull-hook
- (lambda () (shell-command "scp ~/stage/mobileorg.org user@@wdhost:mobile/")))
-@end smallexample
+Org mode has commands to put files for @i{MobileOrg} into that directory,
+and to read captured notes from there.
@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
@section Pushing to MobileOrg
This operation copies all files currently listed in @code{org-mobile-files}
to the directory @code{org-mobile-directory}. By default this list contains
all agenda files (as listed in @code{org-agenda-files}), but additional files
-can be included by customizing @code{org-mobiles-files}. File names will be
-staged with path relative to @code{org-directory}, so all files should be
-inside this directory. The push operation also creates (in the same
-directory) a special Org file @file{agendas.org}. This file is an Org-mode
-style outline, containing every custom agenda view defined by the user.
-While creating the agendas, Org-mode will force@footnote{See the variable
-@code{org-mobile-force-id-on-agenda-items}.} an ID property on all entries
-referenced by the agendas, so that these entries can be uniquely identified
-if @i{MobileOrg} flags them for further action. Finally, Org writes the file
-@file{index.org}, containing links to all other files. If @i{MobileOrg} is
-configured to request this file from the WebDAV server, all agendas and Org
-files will be downloaded to the device. To speed up the download, MobileOrg
-will only read files whose checksums@footnote{stored automatically in the
-file @file{checksums.dat}} have changed.
+can be included by customizing @code{org-mobile-files}. File names will be
+staged with paths relative to @code{org-directory}, so all files should be
+inside this directory@footnote{Symbolic links in @code{org-directory} need to
+have the same name than their targets.}.
+
+The push operation also creates a special Org file @file{agendas.org} with
+all custom agenda view defined by the user@footnote{While creating the
+agendas, Org mode will force ID properties on all referenced entries, so that
+these entries can be uniquely identified if @i{MobileOrg} flags them for
+further action. If you do not want to get these properties in so many
+entries, you can set the variable @code{org-mobile-force-id-on-agenda-items}
+to @code{nil}. Org mode will then rely on outline paths, in the hope that
+these will be unique enough.}.
+
+Finally, Org writes the file @file{index.org}, containing links to all other
+files. @i{MobileOrg} first reads this file from the server, and then
+downloads all agendas and Org files listed in it. To speed up the download,
+MobileOrg will only read files whose checksums@footnote{Checksums are stored
+automatically in the file @file{checksums.dat}} have changed.
@node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg
@section Pulling from MobileOrg
-When @i{MobileOrg} synchronizes with the WebDAV server, it not only pulls the
-Org files for viewing. It also appends captured entries and pointers to
-flagged and changed entries to the file @file{mobileorg.org} on the server.
-Org has a @emph{pull} operation that integrates this information into an
-inbox file and operates on the pointers to flagged entries. Here is how it
-works:
+When @i{MobileOrg} synchronizes with the server, it not only pulls the Org
+files for viewing. It also appends captured entries and pointers to flagged
+and changed entries to the file @file{mobileorg.org} on the server. Org has
+a @emph{pull} operation that integrates this information into an inbox file
+and operates on the pointers to flagged entries. Here is how it works:
@enumerate
@item
If a note has been stored while flagging an entry in @i{MobileOrg}, that note
will be displayed in the echo area when the cursor is on the corresponding
agenda line.
+
@table @kbd
@kindex ?
@item ?
z C-y C-c C-c} to store that flagging note as a normal note in the entry.
Pressing @kbd{?} twice in succession will offer to remove the
@code{:FLAGGED:} tag along with the recorded flagging note (which is stored
-in a property). In this way you indicate, that the intended processing for
+in a property). In this way you indicate that the intended processing for
this flagged entry is finished.
@end table
@end enumerate
@kindex C-c a ?
If you are not able to process all flagged entries directly, you can always
-return to this agenda view using @kbd{C-c a ?}. Note, however, that there is
-a subtle difference. The view created automatically by @kbd{M-x
-org-mobile-pull RET} is guaranteed to search all files that have been
-addressed by the last pull. This might include a file that is not currently
-in your list of agenda files. If you later use @kbd{C-c a ?} to regenerate
-the view, only the current agenda files will be searched.
-
-@node History and Acknowledgments, Main Index, MobileOrg, Top
-@appendix History and Acknowledgments
-@cindex acknowledgements
+return to this agenda view@footnote{Note, however, that there is a subtle
+difference. The view created automatically by @kbd{M-x org-mobile-pull RET}
+is guaranteed to search all files that have been addressed by the last pull.
+This might include a file that is not currently in your list of agenda files.
+If you later use @kbd{C-c a ?} to regenerate the view, only the current
+agenda files will be searched.} using @kbd{C-c a ?}.
+
+@node History and Acknowledgments, GNU Free Documentation License, MobileOrg, Top
+@appendix History and acknowledgments
+@cindex acknowledgments
@cindex history
@cindex thanks
-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 different commands with two or three keys per
-command, only to hide and show parts of the outline tree, that seemed
-entirely unacceptable to me. Also, when using outlines to take notes, I
-constantly wanted to restructure the tree, organizing it parallel to my
-thoughts and plans. @emph{Visibility cycling} and @emph{structure
-editing} were originally implemented in the package
-@file{outline-magic.el}, but quickly moved to the more general
-@file{org.el}. As this environment became comfortable for project
-planning, the next step was adding @emph{TODO entries}, basic
-@emph{timestamps}, and @emph{table support}. These areas highlighted the two main
-goals that Org still has today: to be a new, outline-based,
-plain text mode with innovative and intuitive editing features, and to
-incorporate project planning functionality directly into a notes file.
-
-A special thanks goes to @i{Bastien Guerry} who has not only written a large
-number of extensions to Org (most of them integrated into the core by now),
-but who has also helped in the development and maintenance of Org so much that he
-should be considered the main co-contributor to this package.
+@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
+different commands with two or three keys per command, only to hide and show
+parts of the outline tree, that seemed entirely unacceptable to me. Also,
+when using outlines to take notes, I constantly wanted to restructure the
+tree, organizing it parallel to my thoughts and plans. @emph{Visibility
+cycling} and @emph{structure editing} were originally implemented in the
+package @file{outline-magic.el}, but quickly moved to the more general
+@file{org.el}. As this environment became comfortable for project planning,
+the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and
+@emph{table support}. These areas highlighted the two main goals that Org
+still has today: to be a new, outline-based, plain text mode with innovative
+and intuitive editing features, and to incorporate project planning
+functionality directly into a notes file.
Since the first release, literally thousands of emails to me or to
@email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
complete, if I have forgotten someone, please accept my apologies and
let me know.
+Before I get to this list, a few special mentions are in order:
+
+@table @i
+@item Bastien Guerry
+Bastien has written a large number of extensions to Org (most of them
+integrated into the core by now), including the @LaTeX{} exporter and the plain
+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 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
+Org into a multi-language environment for evaluating code and doing literate
+programming and reproducible research.
+@item John Wiegley
+John has contributed a number of great ideas and patches directly to Org,
+including the attachment system (@file{org-attach.el}), integration with
+Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
+items, habit tracking (@file{org-habits.el}), and encryption
+(@file{org-crypt.el}). Also, the capture system is really an extended copy
+of his great @file{remember.el}.
+@item Sebastian Rose
+Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
+of an ignorant amateur. Sebastian has pushed this part of Org onto a much
+higher level. He also wrote @file{org-info.js}, a Java script for displaying
+web pages derived from Org using an Info-like or a folding interface with
+single-key navigation.
+@end table
+
+@noindent See below for the full list of contributions! Again, please
+let me know what I am missing here!
+
+@section From Bastien
+
+I (Bastien) have been maintaining Org since January 2011. This appendix
+would not be complete without adding a few more acknowledgements and thanks
+to Carsten's ones above.
+
+I am first grateful to Carsten for his trust while handing me over the
+maintainership of Org. His unremitting support is what really helped me
+getting more confident over time, with both the community and the code.
+
+When I took over maintainership, I knew I would have to make Org more
+collaborative than ever, as I would have to rely on people that are more
+knowledgeable than I am on many parts of the code. Here is a list of the
+persons I could rely on, they should really be considered co-maintainers,
+either of the code or the community:
+
+@table @i
+@item Eric Schulte
+Eric is maintaining the Babel parts of Org. His reactivity here kept me away
+from worrying about possible bugs here and let me focus on other parts.
+
+@item Nicolas Goaziou
+Nicolas is maintaining the consistency of the deepest parts of Org. His
+work on @file{org-element.el} and @file{ox.el} has been outstanding, and
+opened the doors for many new ideas and features. He rewrote many of the
+old exporters to use the new export engine, and helped with documenting
+this major change. More importantly (if that's possible), he has been more
+than reliable during all the work done for Org 8.0, and always very
+reactive on the mailing list.
+
+@item Achim Gratz
+Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
+into a flexible and conceptually clean process. He patiently coped with the
+many hiccups that such a change can create for users.
+
+@item Nick Dokos
+The Org mode mailing list would not be such a nice place without Nick, who
+patiently helped users so many times. It is impossible to overestimate such
+a great help, and the list would not be so active without him.
+@end table
+
+I received support from so many users that it is clearly impossible to be
+fair when shortlisting a few of them, but Org's history would not be
+complete if the ones above were not mentioned in this manual.
+
+@section List of contributions
+
@itemize @bullet
@item
@i{Russel Adams} came up with the idea for drawers.
@item
+@i{Suvayu Ali} has steadily helped on the mailing list, providing useful
+feedback on many features and several patches.
+@item
+@i{Luis Anaya} wrote @file{ox-man.el}.
+@item
@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
@item
+@i{Michael Brand} helped by reporting many bugs and testing many features.
+He also implemented the distinction between empty fields and 0-value fields
+in Org's spreadsheets.
+@item
@i{Christophe Bataillon} created the great unicorn logo that we use on the
-Org-mode website.
+Org mode website.
@item
@i{Alex Bochannek} provided a patch for rounding timestamps.
@item
-@i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files.
+@i{Jan Böcker} wrote @file{org-docview.el}.
+@item
+@i{Brad Bozarth} showed how to pull RSS feed data into Org mode files.
@item
@i{Tom Breton} wrote @file{org-choose.el}.
@item
@i{Charles Cave}'s suggestion sparked the implementation of templates
-for Remember.
+for Remember, which are now templates for capture.
@item
@i{Pavel Chalmoviansky} influenced the agenda treatment of items with
specified time.
@item
@i{Sacha Chua} suggested copying some linking code from Planner.
@item
-@i{Baoqiu Cui} contributed the DocBook exporter.
+@i{Toby S. Cubitt} contributed to the code for clock formats.
@item
-@i{Dan Davison} wrote (together with @i{Eric Schulte}) Org Babel.
+@i{Baoqiu Cui} contributed the DocBook exporter. It has been deleted from
+Org 8.0: you can now export to Texinfo and export the @file{.texi} file to
+DocBook using @code{makeinfo}.
@item
@i{Eddward DeVilla} proposed and tested checkbox statistics. He also
came up with the idea of properties, and that there should be an API for
inspired some of the early development, including HTML export. He also
asked for a way to narrow wide table columns.
@item
-@i{Christian Egli} converted the documentation into Texinfo format,
-patched CSS formatting into the HTML exporter, and inspired the agenda.
+@i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
+several years now. He also sponsored the hosting costs until Rackspace
+started to host us for free.
+@item
+@i{Thomas S. Dye} contributed documentation on Worg and helped integrating
+the Org-Babel documentation into the manual.
+@item
+@i{Christian Egli} converted the documentation into Texinfo format, inspired
+the agenda, patched CSS formatting into the HTML exporter, and wrote
+@file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as
+@file{ox-taskjuggler.el} for Org 8.0.
@item
@i{David Emery} provided a patch for custom CSS support in exported
HTML agendas.
@item
+@i{Sean Escriva} took over MobileOrg development on the iPhone platform.
+@item
@i{Nic Ferrier} contributed mailcap and XOXO support.
@item
@i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
@item
@i{Austin Frank} works as a mailing list moderator.
@item
+@i{Eric Fraga} drove the development of BEAMER export with ideas and
+testing.
+@item
+@i{Barry Gidden} did proofreading the manual in preparation for the book
+publication through Network Theory Ltd.
+@item
@i{Niels Giesen} had the idea to automatically archive DONE trees.
@item
-@i{Bastien Guerry} wrote the La@TeX{} exporter and @file{org-bibtex.el}, and
-has been prolific with patches, ideas, and bug reports.
+@i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote
+@file{org-element.el} and @file{org-export.el}, which was a huge step forward
+in implementing a clean framework for Org exporters.
@item
@i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
@item
+@i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
+book.
+@item
@i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
task state change logging, and the clocktable. His clear explanations have
been critical when we started to adopt the Git version control system.
@i{Scott Jaderholm} proposed footnotes, control over whitespace between
folded entries, and column view for properties.
@item
+@i{Matt Jones} wrote @i{MobileOrg Android}.
+@item
@i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
@item
-@i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also
+@i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}.
+@item
+@i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also
provided frequent feedback and some patches.
@item
@i{Matt Lundin} has proposed last-row references for table formulas and named
invisible anchors. He has also worked a lot on the FAQ.
@item
+@i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
+and is a prolific contributor on the mailing list with competent replies,
+small fixes and patches.
+@item
@i{Jason F. McBrayer} suggested agenda export to CSV format.
@item
-@i{Max Mikhanosha} came up with the idea of refiling.
+@i{Max Mikhanosha} came up with the idea of refiling and sticky agendas.
@item
@i{Dmitri Minaev} sent a patch to set priority limits on a per-file
basis.
@i{Tim O'Callaghan} suggested in-file links, search options for general
file links, and TAGS.
@item
+@i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
+version of the reference card.
+@item
@i{Takeshi Okano} translated the manual and David O'Toole's tutorial
into Japanese.
@item
@i{Pete Phillips} helped during the development of the TAGS feature, and
provided frequent feedback.
@item
+@i{Francesco Pizzolante} provided patches that helped speeding up the agenda
+generation.
+@item
@i{Martin Pohlack} provided the code snippet to bundle character insertion
into bundles of 20 for undo.
@item
+@i{Rackspace.com} is hosting our website for free. Thank you Rackspace!
+@item
@i{T.V. Raman} reported bugs and suggested improvements.
@item
@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
@item
@i{Kevin Rogers} contributed code to access VM files on remote hosts.
@item
-@i{Sebastian Rose} wrote @file{org-info.js}, a Java script for displaying
-webpages derived from Org using an Info-like or a folding interface with
-single-key navigation.
-@item
@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
conflict with @file{allout.el}.
@item
@i{Christian Schlauer} proposed angular brackets around links, among
other things.
@item
-@i{Eric Schulte} wrote @file{org-plot.el} and (together with @i{Dan Davison})
-Org Babel, and contributed various patches, small features and modules.
+@i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can
+enjoy folding in non-org buffers by using Org headlines in comments.
+@item
+@i{Paul Sexton} wrote @file{org-ctags.el}.
@item
Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
@file{organizer-mode.el}.
@i{Adam Spiers} asked for global linking commands, inspired the link
extension system, added support for mairix, and proposed the mapping API.
@item
+@i{Ulf Stegemann} created the table to translate special symbols to HTML,
+@LaTeX{}, UTF-8, Latin-1 and ASCII.
+@item
@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
with links transformation to Org syntax.
@item
@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
chapter about publishing.
@item
+@i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter.
+@item
+@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
+enabled source code highlighting in Gnus.
+@item
+@i{Stefan Vollmar} organized a video-recorded talk at the
+Max-Planck-Institute for Neurology. He also inspired the creation of a
+concept index for HTML export.
+@item
@i{J@"urgen Vollmer} contributed code generating the table of contents
in HTML output.
@item
+@i{Samuel Wales} has provided important feedback and bug reports.
+@item
@i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
keyword.
@item
@i{David Wainberg} suggested archiving, and improvements to the linking
system.
@item
-@i{John Wiegley} wrote @file{emacs-wiki.el}, @file{planner.el}, and
-@file{muse.el}, which have some overlap with Org. Initially the development
-of Org was fully independent because I was not aware of the existence of
-these packages. But with time I have occasionally looked at John's code and
-learned a lot from it. John has also contributed a number of great ideas and
-patches directly to Org, including the attachment system
-(@file{org-attach.el}), integration with Apple Mail
-(@file{org-mac-message.el}), hierarchical dependencies of TODO items, habit
-tracking (@file{org-habits.el}) and support for pcomplete.
-@item
@i{Carsten Wimmer} suggested some changes and helped fix a bug in
linking to Gnus.
@item
@end itemize
-@node Main Index, Key Index, History and Acknowledgments, Top
-@unnumbered Concept Index
+@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
-@node Key Index, Variable Index, Main Index, Top
-@unnumbered Key Index
+@node Key Index, Command and Function Index, Main Index, Top
+@unnumbered Key index
@printindex ky
-@node Variable Index, , Key Index, Top
-@unnumbered Variable Index
+@node Command and Function Index, Variable Index, Key Index, Top
+@unnumbered Command and function index
+
+@printindex fn
+
+@node Variable Index, , Command and Function Index, Top
+@unnumbered Variable index
This is not a complete index of variables and faces, only the ones that are
mentioned in the manual. For a more complete list, use @kbd{M-x
@bye
-@ignore
- arch-tag: 7893d1Fe-cc57-4d13-b5e5-f494a1CBC7ac
-@end ignore
-
@c Local variables:
-@c ispell-local-dictionary: "en_US-w_accents"
-@c ispell-local-pdict: "./.aspell.org.pws"
@c fill-column: 77
+@c indent-tabs-mode: nil
+@c paragraph-start: "\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$"
+@c paragraph-separate: "\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$"
@c End: