@setfilename ../../info/org
@settitle The Org Manual
-@set VERSION 6.02b
-@set DATE April 2008
+@set VERSION 6.16
+@set DATE December 2008
@dircategory Emacs
@direntry
@copying
This manual is for Org (version @value{VERSION}).
-Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 Free Software Foundation
+Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
+and with the Back-Cover Texts as in (a) below. A copy of the license
+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
* Tags:: Tagging headlines and matching sets of tags
* Properties and Columns:: Storing information about an entry
* Dates and Times:: Making items useful for planning
-* Remember:: Quickly adding nodes to the outline tree
+* Capture:: Creating tasks and attaching files
* Agenda Views:: Collecting information into views
* Embedded LaTeX:: LaTeX fragments and formulas
* Exporting:: Sharing and publishing of notes
* Publishing:: Create a web site of linked Org files
* Miscellaneous:: All the rest which did not fit elsewhere
-* Extensions and Hacking:: It is possible to write add-on code
+* Extensions:: Add-ons for Org mode
+* Hacking:: How to hack your way around
* History and Acknowledgments:: How Org came into being
* Main Index:: An index of Org's concepts and features
* Key Index:: Key bindings and where they are described
* Column groups:: Grouping to trigger vertical lines
* Orgtbl mode:: The table editor as minor mode
* The spreadsheet:: The table editor has spreadsheet capabilities
+* Org Plot:: Plotting from org tables
The spreadsheet
* Deadlines and scheduling:: Planning your work
* Clocking work time:: Tracking how long you spend on a task
* Effort estimates:: Planning work effort in advance
+* Relative timer:: Notes with a running timer
Creating timestamps
* Inserting deadline/schedule:: Planning items
* Repeated tasks:: Items that show up again and again
+Capture
+
+* Remember:: Capture new tasks/ideas with little interruption
+* Attachments:: Add files to tasks.
+
Remember
* Setting up Remember:: Some code for .emacs to get things going
Exporting
+* Markup rules:: Which structures are recognized?
+* 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
* HTML export:: Exporting to HTML
-* LaTeX export:: Exporting to LaTeX
+* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF
* XOXO export:: Exporting to XOXO
* iCalendar export:: Exporting in iCalendar format
-* Text interpretation:: How the exporter looks at the file
+
+Markup rules
+
+* Document title:: How the document title is determined
+* Headings and sections:: The main structure of the exported document
+* Table of contents:: If, where, how to create a table of contents
+* Initial text:: Text before the first headline
+* Lists:: Plain lists are exported
+* Paragraphs:: What determines beginning and ending
+* Literal examples:: Source code and other examples
+* Include files:: Include the contents of a file during export
+* Tables exported:: Tables are exported richly
+* Inlined images:: How to inline images during export
+* Footnotes:: Numbers like [1]
+* Emphasis and monospace:: To bold or not to bold
+* TeX macros and LaTeX fragments:: Create special, rich export.
+* Horizontal rules:: A line across the page
+* Comment lines:: Some lines will not be exported
HTML export
-* HTML Export commands:: How to invoke LaTeX export
+* HTML Export commands:: How to invoke HTML export
* Quoting HTML tags:: Using direct HTML in Org mode
* Links:: Transformation of links for HTML
-* Images:: How to include images
+* Images in HTML export::
* CSS support:: Changing the appearance of the output
* Javascript support:: Info and Folding in a web browser
-LaTeX export
+LaTeX and PDF export
-* LaTeX export commands:: How to invoke LaTeX export
+* LaTeX/PDF export commands:: Which key invokes which commands
* Quoting LaTeX code:: Incorporating literal LaTeX code
* Sectioning structure:: Changing sectioning in LaTeX output
-
-Text interpretation by the exporter
-
-* Comment lines:: Some lines will not be exported
-* Initial text:: Text before the first headline
-* Footnotes:: Numbers like [1]
-* Quoted examples:: Inserting quoted chunks of text
-* Enhancing text:: Subscripts, symbols and more
-* Export options:: How to influence the export settings
+* Tables in LaTeX export:: Options for exporting tables to LaTeX
+* Images in LaTeX export:: How to insert figures into LaTeX output
Publishing
* Cooperation:: Packages Org cooperates with
* Conflicts:: Packages that lead to conflicts
-Extensions, Hooks and Hacking
+Extensions
+
+* Extensions in the contrib directory:: These come with the Org distro
+* Other extensions:: These you have to find on the web.
+
+Hacking
-* Extensions:: Existing 3rd-party extensions
* Adding hyperlink types:: New custom link types
* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
* 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
@iftex
@b{Important:} @i{If you use copy-and-paste to copy lisp code from the
-PDF documentation as viewed by Acrobat reader to your .emacs file, the
+PDF documentation as viewed by some PDF viewers to your .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 two lines
+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.
the file's name is. See also the variable
@code{org-insert-mode-line-in-empty-file}.
+Many commands in Org work on the region is the region is active. To make use
+of this, you need to have @code{transient-mark-mode} (@code{zmacs-regions} in
+XEmacs) turned on. In Emacs 23 this is the default, in Emacs 22 you need to
+do this yourself with
+
+@lisp
+(transient-mark-mode 1)
+@end lisp
+
@node Feedback, Conventions, Activation, Introduction
@section Feedback
@cindex feedback
@cindex maintainer
@cindex author
-If you find problems with Org, or if you have questions, remarks,
-or ideas about it, please contact the maintainer @value{MAINTAINER} at
-@value{MAINTAINEREMAIL}.
+If you find problems with Org, or if you have questions, remarks, or ideas
+about it, please mail to the Org mailing list @code{emacs-orgmode@@gnu.org}.
+If you are not a member of the mailing list, your mail will be reviewed by a
+moderator and then passed through to the list.
For bug reports, please provide as much information as possible,
including the version information of Emacs (@kbd{C-h v emacs-version
tables, @kbd{S-@key{TAB}} jumps to the previous field.
@cindex show all, command
-@kindex C-c C-a
-@item C-c C-a
-Show all.
+@kindex C-u C-u C-u @key{TAB}
+@item C-u C-u C-u @key{TAB}
+Show all, including drawers.
@kindex C-c C-r
@item C-c C-r
Reveal context around point, showing the current entry, the following heading
#+STARTUP: showall
@end example
+@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
+requested by startup options and @samp{VISIBILITY} properties in individual
+entries.
+@end table
+
@node Motion, Structure editing, Visibility cycling, Document Structure
@section Motion
@cindex motion, between headlines
@example
@key{TAB} @r{Cycle visibility.}
@key{down} / @key{up} @r{Next/previous visible headline.}
+@key{RET} @r{Select this location.}
+@kbd{/} @r{Do a Sparse-tree search}
+@r{The following keys work if you turn off @code{org-goto-auto-isearch}}
n / p @r{Next/previous visible headline.}
f / b @r{Next/previous headline same level.}
u @r{One level up.}
0-9 @r{Digit argument.}
-@key{RET} @r{Select this location.}
+q @r{Quit}
@end example
+See also the variable@code{org-goto-interface}.
@end table
@node Structure editing, Archiving, Motion, Document Structure
after the end of the subtree.
@kindex C-@key{RET}
@item C-@key{RET}
-Insert a new heading after the current subtree, same level as the
-current headline. This command works from anywhere in the entry.
+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}
Insert new TODO entry with same level as current heading.
+@kindex C-S-@key{RET}
+@item C-S-@key{RET}
+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 M-@key{left}
@item M-@key{left}
Promote current heading by one level.
@item M-S-@key{down}
Move subtree down (swap with next subtree of same level).
@kindex C-c C-x C-w
-@kindex C-c C-x C-k
@item C-c C-x C-w
-@itemx C-c C-x C-k
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
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
+Depending on the variables @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, level adjustment will take place and
+yanked trees will be folded unless doing so would swallow text previously
+visible. Any prefix argument to this command will force a normal @code{yank}
+to be executed, with the prefix passed along. A good way to 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-w
@item C-c C-w
-Refile entry to a different location. @xref{Refiling notes}.
+Refile entry or region to a different location. @xref{Refiling notes}.
@kindex C-c ^
@item C-c ^
Sort same-level entries. When there is an active region, all entries in the
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
+Narrow buffer to current subtree.
+@kindex C-x n w
+@item C-x n w
+Widen buffer to remove a narrowing.
@kindex C-c *
@item C-c *
Turn a normal line or plain list item into a headline (so that it
@item
During agenda view construction (@pxref{Agenda Views}), the content of
archived trees is ignored unless you configure the option
-@code{org-agenda-skip-archived-trees}.
+@code{org-agenda-skip-archived-trees}, in which case these trees will always
+be included. In the agenda you can press the @kbd{v} key to get archives
+temporarily included.
@item
Archived trees are not exported (@pxref{Exporting}), only the headline
is. Configure the details using the variable
@cindex external archiving
Once an entire project is finished, you may want to move it to a different
-location. Org can move it to an @emph{Attic Sibling} in the same tree, to a
+location. Org can move it to an @emph{Archive Sibling} in the same tree, to a
different tree in the current file, or to a different file, the archive file.
@table @kbd
@kindex C-c C-x A
@item C-c C-x A
-Move the current entry to the @emph{Attic Sibling}. This is a sibling of the
-entry with the heading @samp{Attic} and the tag @samp{ARCHIVE}
+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}
(@pxref{ARCHIVE tag}). The entry becomes a child of that sibling and in this
way retains a lot of its original context, including inherited tags and
approximate position in the outline.
@cindex folding, sparse trees
@cindex occur, command
-An important feature of Org mode is the ability to construct
-@emph{sparse trees} for selected information in an outline tree, so that
-the entire document is folded as much as possible, but the selected
-information is made visible along with the headline structure above
-it@footnote{See also the variables @code{org-show-hierarchy-above},
-@code{org-show-following-heading}, and @code{org-show-siblings} for
-detailed control on how much context is shown around each match.}. Just
-try it out and you will see immediately how it works.
+An important feature of Org mode is the ability to construct @emph{sparse
+trees} for selected information in an outline tree, so that the entire
+document is folded as much as possible, but the selected information is made
+visible along with the headline structure above it@footnote{See also the
+variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
+@code{org-show-siblings}, and @code{org-show-entry-below} for detailed
+control on how much context is shown around each match.}. Just try it out
+and you will see immediately how it works.
Org mode contains several commands creating such trees, all these
commands can be accessed through a dispatcher:
This prompts for an extra key to select a sparse-tree creating command.
@kindex C-c / r
@item C-c / r
-Occur. 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 is shown, as well as the headline following
-the match. Each match is also highlighted; the highlights disappear
-when the buffer is changed by an editing command, 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.
+Occur. 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
+is shown, as well as the headline following the match. Each match is also
+highlighted; the highlights disappear when the buffer is changed by an
+editing command@footnote{depending on the option
+@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.
@end table
@noindent
checkboxes (@pxref{Checkboxes}). Org supports editing such lists,
and the HTML exporter (@pxref{Exporting}) parses and formats them.
-Org knows ordered and unordered lists. 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. Ordered list items start with a numeral followed by either a
-period or a right parenthesis, such as @samp{1.} or @samp{1)}. 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:
+Org knows ordered lists, unordered lists, and description lists.
+@itemize @bullet
+@item
+@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.
+@item
+@emph{Ordered} list items start with a numeral followed by either a period or
+a right parenthesis, such as @samp{1.} or @samp{1)}.
+@item
+@emph{Description} list items are like unordered list items, but contain the
+separator @samp{ :: } to separate the description @emph{term} from the
+description.
+@end itemize
+
+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:
@example
@group
** Lord of the Rings
My favorite scenes are (in this order)
1. The attack of the Rohirrim
- 2. Eowyns fight with the witch king
+ 2. Eowyn's fight with the witch king
+ this was already my favorite scene in the book
+ I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
- on DVD only
He makes a really funny face when it happens.
- But in the end, not individual scenes matter but the film as a whole.
+ But in the end, no individual scenes matter but the film as a whole.
+ Important actors in this film are:
+ - @b{Elijah Wood} :: He plays Frodo
+ - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember
+ him very well from his role as Mikey Walsh in the Goonies.
@end group
@end example
deal with them correctly@footnote{Org only changes the filling
settings for Emacs. For XEmacs, you should use Kyle E. Jones'
@file{filladapt.el}. To turn this on, put into @file{.emacs}:
-@code{(require 'filladapt)}}.
+@code{(require 'filladapt)}}, and by exporting them properly
+(@pxref{Exporting}).
The following commands act on items when the cursor is in the first line
of an item (the line with the bullet or number).
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.
+@kindex S-@key{left}
+@kindex S-@key{right}
+@item S-@key{left}/@key{right}
+Also cycle bullet styles when in the first line of an item.
@end table
@node Drawers, Orgstruct mode, Plain lists, Document Structure
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 a drawer for
-storing properties (@pxref{Properties and Columns}).
+storing properties (@pxref{Properties and Columns}), and another one for
+storing clock times (@pxref{Clocking work time}).
@node Orgstruct mode, , Drawers, Document Structure
@section The Orgstruct minor mode
* Column groups:: Grouping to trigger vertical lines
* Orgtbl mode:: The table editor as minor mode
* The spreadsheet:: The table editor has spreadsheet capabilities
+* Org Plot:: Plotting from org tables
@end menu
@node Built-in table editor, Narrow columns, Tables, Tables
@kindex C-c C-x C-y
@item C-c C-x C-y
Paste a rectangular region into a table.
-The upper right corner ends up in the current field. All involved fields
+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 S-@key{RET}
@item S-@key{RET}
-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 values will be
-incremented during copy. This key is also used by CUA mode
-(@pxref{Cooperation}).
+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
+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 CUA mode (@pxref{Cooperation}).
@tsubheading{Miscellaneous}
@kindex C-c `
@item C-c |
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}.
+@kbd{C-c |} command (see above under @i{Creation and conversion}).
@c
@item M-x org-table-export
Export the table, by default as a TAB-separated file. Useful for data
used to export the file can be configured in the variable
@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.
+name and the format for table export in a subtree. Org supports quite
+general formats for exported tables. The exporter format is the same as the
+format used by Orgtbl radio tables, see @ref{Translator functions} for a
+detailed description.
@end table
If you don't like the automatic table editor because it gets in your
| # | 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))
+#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2)))
@end example
It is also sufficient to just insert the column group starters after
Orgtbl mode, including spreadsheet capabilities. For details, see
@ref{Tables in arbitrary syntax}.
-@node The spreadsheet, , Orgtbl mode, Tables
+@node The spreadsheet, Org Plot, Orgtbl mode, Tables
@section The spreadsheet
@cindex calculations, in tables
@cindex spreadsheet capabilities
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
A formula can contain an optional mode string after a semicolon. This
string consists of flags to influence Calc and other modes during
execution. By default, Org uses the standard Calc modes (precision
-12, angular units degrees, fraction and symbolic modes off. The display
+12, angular units degrees, fraction and symbolic modes off). The display
format, however, has been changed to @code{(float 5)} to keep tables
compact. The default settings can be configured using the variable
@code{org-calc-default-modes}.
@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 the Calc's
+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
ones) in stored formulas are modified in order to still reference the
same field. Of cause 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}.
Instead of typing an equation into the field, you may also use the
following command
@kindex C-#
@item C-#
Rotate the calculation mark in first column through the states @samp{},
-@samp{#}, @samp{*}, @samp{!}, @samp{$}. The meaning of these characters
-is discussed below. When there is an active region, change all marks in
-the region.
+@samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
+change all marks in the region.
@end table
Here is an example of a table that collects exam results of students and
| ^ | | m1 | m2 | m3 | mt | |
|---+---------+--------+--------+--------+-------+------|
| # | Peter | 10 | 8 | 23 | 41 | 8.2 |
-| # | Sara | 6 | 14 | 19 | 39 | 7.8 |
| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
|---+---------+--------+--------+--------+-------+------|
| | Average | | | | 29.7 | |
@end group
@end example
+@page
+@node Org Plot, , The spreadsheet, Tables
+@section Org Plot
+@cindex graph, in tables
+@cindex plot tables using gnuplot
+
+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.
+
+@example
+@group
+#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
+| Sede | Max cites | H-index |
+|-----------+-----------+---------|
+| Chile | 257.72 | 21.39 |
+| Leeds | 165.77 | 19.68 |
+| Sao Paolo | 71.00 | 11.50 |
+| Stockholm | 134.19 | 14.33 |
+| Morelia | 257.56 | 17.67 |
+@end group
+@end example
+
+Notice that Org Plot is smart enough to apply the tables headers as labels.
+Further control over the labels, type, content, and appearance of plots can
+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://legito.org/worg/org-tutorials/org-plot.php}.
+
+@subsubheading Plot Options
+
+@table @code
+@item set
+Specify any @file{gnuplot} option to be set when graphing.
+
+@item title
+Specify the title of the plot.
+
+@item ind
+Specify which column of the table to use as the @code{x} axis.
+
+@item deps
+Specify the columns to graph as a lisp style list, surrounded by parenthesis
+and separated by spaces for example @code{dep:(3 4)} to graph the third and
+fourth columns (defaults to graphing all other columns aside from the ind
+column).
+
+@item type
+Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
+
+@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...).
+Defaults to 'lines'.
+
+@item file
+If you want to plot to a file specify the @code{"path/to/desired/output-file"}.
+
+@item labels
+List of labels to be used for the deps (defaults to column headers if they
+exist).
+
+@item line
+Specify an entire line to be inserted in the gnuplot script.
+
+@item map
+When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
+flat mapping rather than a @code{3d} slope.
+
+@item timefmt
+Specify format of org-mode timestamps as they will be parsed by gnuplot.
+Defaults to '%Y-%m-%d-%H:%M:%S'.
+
+@item script
+If you want total control you can specify a script file (place the file name
+between double quotes) which will be used to plot. Before plotting, every
+instance of @code{$datafile} in the specified script will be replaced with
+the path to the generated data file. Note even if you set this option you
+may still want to specify the plot type, as that can impact the content of
+the data file.
+@end table
+
@node Hyperlinks, TODO Items, Tables, Top
@chapter Hyperlinks
@cindex hyperlinks
@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.}.
+named anchors for direct access through @samp{http} links@footnote{Note that
+text before the first headline is usually not exported, so the first such
+target should be after the first headline, or in the line directly before the
+first headline.}.
If no dedicated target exists, Org will search for the words in the
link. In the above example the search would be for @samp{my target}.
@example
http://www.astro.uva.nl/~dominik @r{on the web}
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}
news:comp.emacs @r{Usenet link}
-mailto:adent@@galaxy.net @r{Mail link}
+mailto:adent@@galaxy.net @r{Mail link}
vm:folder @r{VM folder link}
vm:folder#id @r{VM message link}
-vm://myself@@some.where.org/folder#id @r{VM on remote machine}
+vm://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}
rmail:folder#id @r{RMAIL message link}
gnus:group @r{Gnus group link}
gnus:group#id @r{Gnus article link}
-bbdb:Richard Stallman @r{BBDB link}
+bbdb:R.*Stallman @r{BBDB link (with regexp)}
irc:/irc.com/#emacs/bob @r{IRC link}
shell:ls *.org @r{A shell command}
-elisp:(find-file-other-frame "Elisp.org") @r{An elisp form to evaluate}
+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
@kindex C-c l
@cindex storing links
@item C-c l
-Store a link to the current location. This is a @emph{global} command
-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). 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. For VM, Rmail, Wanderlust, MH-E, Gnus and BBDB buffers, the
-link will indicate the current article/entry. For W3 and W3M buffers,
-the link goes to the current URL. For IRC links, if you set the
-variable @code{org-irc-link-to-logs} to non-nil then @kbd{C-c l} will
-store a @samp{file:/} style link to the relevant point in the logs for
-the current conversation. Otherwise an @samp{irc:/} style link to the
-user/channel/server under the point will be stored. For any other
-files, the link will point to the file, with a search string
-(@pxref{Search options}) pointing to the contents of the current line.
-If there is an active region, the selected words will form the basis
-of the search string. If the automatically created link is not
-working correctly or accurately enough, you can write custom functions
-to select the search string and to do the search for particular file
-types - see @ref{Custom searches}. The key binding @kbd{C-c l} is
-only a suggestion - see @ref{Installation}.
+Store a link to the current location. This is a @emph{global} command 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). 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, either by text, or, if @file{org-id.el} is
+loaded, by ID property. For VM, Rmail, Wanderlust, MH-E, Gnus and BBDB
+buffers, the link will indicate the current article/entry. For W3 and W3M
+buffers, the link goes to the current URL. For IRC links, if you set the
+variable @code{org-irc-link-to-logs} to non-nil then @kbd{C-c l} will store a
+@samp{file:/} style link to the relevant point in the logs for the current
+conversation. Otherwise an @samp{irc:/} style link to the user/channel/server
+under the point will be stored. For any other files, the link will point to
+the file, with a search string (@pxref{Search options}) pointing to the
+contents of the current line. If there is an active region, the selected
+words will form the basis of the search string. If the automatically created
+link is not working correctly or accurately enough, you can write custom
+functions to select the search string and to do the search for particular
+file types - see @ref{Custom searches}. The key binding @kbd{C-c l} is only
+a suggestion - see @ref{Installation}.
@c
@kindex C-c C-l
@cindex link completion
@kindex C-c C-o
@item C-c C-o
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 cursor is on an internal link, this commands runs the
-corresponding search. When the cursor is on a TAG list in a headline,
-it creates the corresponding TAGS view. If the cursor is on a time
-stamp, it compiles the agenda for that date. Furthermore, it will visit
-text and remote files in @samp{file:} links with Emacs and select a
-suitable application for local non-text files. Classification of files
-is based on file extension only. See option @code{org-file-apps}. If
-you want to override the default application and visit the file with
-Emacs, use a @kbd{C-u} prefix.
+@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
+cursor is on an internal link, this commands runs the corresponding search.
+When the cursor is on a TAG list in a headline, it creates the corresponding
+TAGS view. If the cursor is on a time stamp, it compiles the agenda for that
+date. Furthermore, it will visit text and remote files in @samp{file:} links
+with Emacs and select a suitable application for local non-text files.
+Classification of files is based on file extension only. See option
+@code{org-file-apps}. If you want to override the default application and
+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.
@c
@kindex mouse-2
@kindex mouse-1
@code{org-execute-file-search-functions}. See the docstring for these
variables for more information. Org actually uses this mechanism
for Bib@TeX{} database files, and you can use the corresponding code as
-an implementation example. Search for @samp{BibTeX links} in the source
-file.
-
-
+an implementation example. See the file @file{org-bibtex.el}.
@node TODO Items, Tags, Hyperlinks, Top
@chapter TODO Items
@cindex TODO items
-Org mode does not maintain TODO lists as separate documents. Instead,
-TODO items are an integral part of the notes file, because TODO items
-usually come up while taking notes! With Org mode, simply mark any
-entry in a tree as being a TODO item. In this way, information is not
-duplicated, and the entire context from which the TODO item emerged is
-always present.
+Org mode does not maintain TODO lists as separate documents@footnote{Of
+course, you can make a document that contains only long lists of TODO items,
+but this is not required.}. Instead, TODO items are an integral part of the
+notes file, because TODO items usually come up while taking notes! With Org
+mode, simply mark any entry in a tree as being a TODO item. In this way,
+information is not duplicated, and the entire context from which the TODO
+item emerged is always present.
Of course, this technique for managing TODO items scatters them
throughout your notes file. Org mode compensates for this by providing
Insert a new TODO entry below the current one.
@end table
+@noindent
+Changing a TODO state can also trigger tag changes. See the docstring of the
+option @code{org-todo-state-tags-triggers} for details.
+
@node TODO extensions, Progress logging, TODO basics, TODO Items
@section Extended use of TODO keywords
@cindex extended TODO keywords
@end lisp
The vertical bar separates the TODO keywords (states that @emph{need
-action}) from the DONE states (which need @emph{no further action}. If
+action}) from the DONE states (which need @emph{no further action}). If
you don't provide the separator bar, the last state is used as the DONE
state.
@cindex completion, of TODO keywords
@code{org-todo-keyword-faces}. For example:
@lisp
+@group
(setq org-todo-keyword-faces
'(("TODO" . org-warning)
("DEFERRED" . shadow)
("CANCELED" . (:foreground "blue" :weight bold))))
+@end group
@end lisp
While using a list with face properties as shown for CANCELED
:END:
@end example
-
@node Priorities, Breaking down tasks, Progress logging, TODO Items
@section Priorities
@cindex priorities
@cindex tasks, breaking down
It is often advisable to break down large tasks into smaller, manageable
-subtasks. You can do this by creating an outline tree below a TODO
-item, with detailed subtasks on the tree@footnote{To keep subtasks out
-of the global TODO list, see the
-@code{org-agenda-todo-list-sublevels}.}. Another possibility is the use
-of checkboxes to identify (a hierarchy of) a large number of subtasks
-(@pxref{Checkboxes}).
+subtasks. You can do this by creating an outline tree below a TODO item,
+with detailed subtasks on the tree@footnote{To keep subtasks out of the
+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. For example:
+
+@example
+* Organize Party [33%]
+** TODO Call people [1/2]
+*** TODO Peter
+*** DONE Sarah
+** TODO Buy food
+** DONE Talk to neighbor
+@end example
+
+If you would like a TODO entry to automatically change to DONE when all
+children are done, you can use the following setup:
+
+@example
+(defun org-summary-todo (n-done n-not-done)
+ "Switch entry to DONE when all subentries are done, to TODO otherwise."
+ (let (org-log-done org-log-states) ; turn off logging
+ (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
+
+(add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
+@end example
+
+
+Another possibility is the use of checkboxes to identify (a hierarchy of) a
+large number of subtasks (@pxref{Checkboxes}).
@node Checkboxes, , Breaking down tasks, TODO Items
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}}. If you
delete boxes or add/change them by hand, use this command to get things
-back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}.
+back into sync. Or simply toggle any checkbox twice with @kbd{C-c C-c}.
@end table
@node Tags, Properties and Columns, TODO Items, Top
support for tags.
Every headline can contain a list of tags; they occur at the end of the
-headline. Tags are normal words containing letters, numbers, @samp{_},
-and @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:}.
+headline. Tags are normal words containing letters, numbers, @samp{_}, and
+@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 get a bold face with the same color as the headline.
+You may specify special faces for specific tags using the variable
+@code{org-tag-faces}, much in the same way as you can do for TODO keywords
+(@pxref{Faces for TODO keywords}).
@menu
* Tag inheritance:: Tags use the tree structure of the outline
@noindent
the final heading will have the tags @samp{:work:}, @samp{:boss:},
@samp{:notes:}, and @samp{:action:} even though the final heading is not
-explicitly marked with those tags. When executing tag searches and
-Org mode finds that a certain headline matches the search criterion, it
-will not check any sublevel headline, assuming that these also match and
-that the list of matches could become very long because of that. If you
-do want the sublevels be tested and listed as well, you may set the
-variable @code{org-tags-match-list-sublevels}. To limit tag inheritance
-to specific tags, or to turn it off entirely, use the variable
-@code{org-use-tag-inheritance}.
+explicitly marked with those tags. You can also set tags that all entries in
+a file should inherit as if these tags would be defined in a hypothetical
+level zero that surrounds the entire file.
+
+@example
+#+FILETAGS: :Peter:Boss:Secret:
+@end example
+
+@noindent
+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}.
+
+When a headline matches during a tags search while tag inheritance is turned
+on, all the sublevels in the same tree will (for a simple match form) match
+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
@section Setting tags
also a special command for inserting tags:
@table @kbd
-@kindex C-c C-c
-@item C-c C-c
+@kindex C-c C-q
+@item C-c C-q
@cindex completion, of tags
Enter new tags for the current headline. Org mode will either offer
completion or a special single-key interface for setting tags, see
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
+When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
@end table
Org will support tag insertion based on a @emph{list of tags}. By
@end table
@cindex TODO keyword matching, with tags search
-If you are using multi-state TODO keywords (@pxref{TODO extensions}), it
-can be useful to also match on the TODO keyword. This can be done by
-adding a condition after a slash to a tags match. The syntax is similar
-to the tag matches, but should be applied with consideration: For
-example, a positive selection on several TODO keywords can not
-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, use @kbd{C-c a
-M}, or equivalently start the TODO part after the slash with @samp{!}.
-Examples:
+You may also test for TODO keywords (@pxref{TODO extensions}) and properties
+(@pxref{Properties and Columns}) at the same time as matching tags. For a
+guide on how to match properties, see @ref{Property searches}. To match a
+specific TODO keyword, include an expression like @samp{+TODO="NEXT"} as one
+of the terms in a tags search.
+
+There is also the possibility to end the tags part of the match (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 the tag matches, but should be applied with consideration: For
+example, a positive selection on several TODO keywords can not 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:
@table @samp
-@item work/WAITING
+@item work+TODO="WAITING"
Select @samp{:work:}-tagged TODO lines with the specific TODO
keyword @samp{WAITING}.
+@item work+TODO="WAITING"|home+TODO="WAITING"
+Waiting tasks both at work and at home.
+@item work/WAITING
+Same as the first example.
@item work/!-WAITING-NEXT
Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
nor @samp{NEXT}
-@item work/+WAITING|+NEXT
+@item work/!+WAITING|+NEXT
Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
@samp{NEXT}.
@end table
Any element of the tag/todo match can be a regular expression - in this
case it must be enclosed in curly braces. For example,
@samp{work+@{^boss.*@}} matches headlines that contain the tag
-@samp{:work:} and any tag @i{starting} with @samp{boss}.
+@samp{:work:} and any tag @i{starting} with @samp{boss}. You may also use a
+regular expression in @samp{TODO=@{^W@}} which would match TODO keywords
+starting with the letter @samp{W}.
@cindex level, require for tags/property match
@cindex category, require for tags/property match
@samp{+LEVEL=3+boss/-DONE} lists all level three headlines that have the
tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE.
+Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any
+other properties will slow down the search.
+
@node Properties and Columns, Dates and Times, Tags, Top
@chapter Properties and Columns
@cindex properties
using tags like @code{:release_1:}, @code{:release_2:}, one 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 CD's,
+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.
Properties can be conveniently edited and viewed in column view
(@pxref{Column view}).
-Properties are like tags, but with a value. For example, in a file
-where you document bugs and plan releases of a piece of software,
-instead of using tags like @code{:release_1:}, @code{:release_2:}, it
-can be more efficient to use a property @code{:Release:} with a value
-@code{1.0} or @code{2.0}. Second, you can use properties to implement
-(very basic) database capabilities in an Org buffer, for example to
-create a list of Music CD's you own. You can edit and view properties
-conveniently in column view (@pxref{Column view}).
-
@menu
* Property syntax:: How properties are spelled out
* Special properties:: Access to other Org mode features
* CD collection
:PROPERTIES:
:NDisks_ALL: 1 2 3 4
- :Publisher_ALL: "Deutsche Grammophon" Phillips EMI
+ :Publisher_ALL: "Deutsche Grammophon" Philips EMI
:END:
@end example
the same logic applies. For example, here is a search string:
@example
-+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2+With=@{Sarah\|Denny@}
++work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \
+ +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
@end example
@noindent
+The type of comparison will depend on how the comparison value is written:
+@itemize @minus
+@item
If the comparison value is a plain number, a numerical comparison is done,
and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
-@samp{>=}, and @samp{<>}. If the comparison value is enclosed in double
-quotes, a string comparison is done, and the same operators are allowed. If
-the comparison value is enclosed in curly braces, a regexp match is
-performed, with @samp{=} meaning that the regexp matches the property value,
-and @samp{<>} meaning that it does not match. So the search string in the
-example finds entries tagged @samp{:work:} but not @samp{:boss:}, which also
-have a priority value @samp{A}, a @samp{:Coffee:} property with the value
-@samp{unlimited}, an @samp{Effort} property that is numerically smaller than
-2, and a @samp{:With:} property that is matched by the regular expression
-@samp{Sarah\|Denny}.
+@samp{>=}, and @samp{<>}.
+@item
+If the comparison value is enclosed in double
+quotes, a string comparison is done, and the same operators are allowed.
+@item
+If the comparison value is enclosed in double quotes @emph{and} angular
+brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
+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
+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.
+@item
+If the comparison value is enclosed
+in curly braces, a regexp match is performed, with @samp{=} meaning that the
+regexp matches the property value, and @samp{<>} meaning that it does not
+match.
+@end itemize
+
+So the search string in the example finds entries tagged @samp{:work:} but
+not @samp{:boss:}, which also have a priority value @samp{A}, a
+@samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
+property that is numerically smaller than 2, a @samp{:With:} property that is
+matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
+on or after October 11, 2008.
You can configure Org mode to use property inheritance during a search, but
beware that this can slow down searches considerably. See @ref{Property
@item S-@key{left}/@key{right}
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
Make the column narrower/wider by one character.
@kindex S-M-@key{right}
@item S-M-@key{right}
-Insert a new column, to the right of the current column.
+Insert a new column, to the left of the current column.
@kindex S-M-@key{left}
@item S-M-@key{left}
Delete the current column.
this @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
of this block looks like this:
+@cindex #+BEGIN: columnview
@example
* The column view
#+BEGIN: columnview :hlines 1 :id "label"
@example
local @r{use the tree in which the capture block is located}
global @r{make a global view, including all headings in the file}
-"label" @r{call column view in the tree that has and @code{:ID:}}
- @r{property with the value @i{label}}
+"label" @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{the current entry and copy it to the kill-ring.}
@end example
@item :hlines
When @code{t}, insert a hline after every line. When a number N, insert
The following commands insert or update the dynamic block:
@table @kbd
-@kindex C-c C-x r
-@item C-c C-x r
+@kindex C-c C-x i
+@item C-c C-x i
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
you have several clock table blocks in a buffer.
@end table
+You can add formulas to the column view table and you may add plotting
+instructions in front of the table - these will survive an update of the
+block. If there is a @code{#+TBLFM:} after the table, the table will
+actually be recalculated automatically after an update.
+
@node Property API, , Column view, Properties and Columns
@section The Property API
@cindex properties, API
features based on them. For more information see @ref{Using the
property API}.
-@node Dates and Times, Remember, Properties and Columns, Top
+@node Dates and Times, Capture, Properties and Columns, Top
@chapter Dates and Times
@cindex dates
@cindex times
* Deadlines and scheduling:: Planning your work
* Clocking work time:: Tracking how long you spend on a task
* Effort estimates:: Planning work effort in advance
+* Relative timer:: Notes with a running timer
@end menu
@table @kbd
@kindex C-c .
@item C-c .
-Prompt for a date and insert a corresponding time stamp. When the
-cursor is at a previously used time stamp, it is updated to NOW. When
-this command is used twice in succession, a time range is inserted.
+Prompt for a date and insert a corresponding time stamp. When the cursor is
+at an existing time stamp 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-u C-c .
@item C-u C-c .
future date@footnote{See the variable
@code{org-read-date-prefer-future}.}.
-For example, lets assume that today is @b{June 13, 2006}. Here is how
+For example, let's assume that today is @b{June 13, 2006}. Here is how
various inputs will be interpreted, the items filled in by Org mode are
in @b{bold}.
14 --> @b{2006}-@b{06}-14
12 --> @b{2006}-@b{07}-12
Fri --> nearest Friday (defaultdate or later)
-sep 15 --> @b{2006}-11-15
+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
the nth such day. E.g.
@example
++0 --> today
+. --> today
+4d --> four days from today
+4 --> same as above
+2w --> two weeks from today
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.
+@c
+@kindex C-c C-x C-k
+@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.
@end table
@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling
A timestamp@footnote{You can change this using the option
@code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
@code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you
-will aslo be prompted for a note.} will be added under the deadline, to keep
+will also be prompted for a note.} will be added under the deadline, to keep
a record that you actually acted on the previous instance of this deadline.
As a consequence of shifting the base date, this entry will no longer be
with letter @kbd{d}.
@kindex C-c C-x C-o
@item C-c C-x C-o
-Stop the clock (clock-out). The inserts another timestamp at the same
+Stop the clock (clock-out). This inserts another timestamp at the same
location where the clock was last started. It also directly computes
the resulting time in inserts it after the time range as @samp{=>
HH:MM}. See the variable @code{org-log-note-clock-out} for the
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.
+@cindex #+BEGIN: clocktable
@example
#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
#+END: clocktable
: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.}
:link @r{Link the item headlines in the table to their origins}
+:formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
+ @r{As a special case, @samp{:formula %} adds column with % time.}
+ @r{If you do not specify a formula here, any existing formula}
+ @r{below the clock table will survive updates and be evaluated.}
@end example
So 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 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
the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
worked on or closed during a day.
-@node Effort estimates
+@node Effort estimates, Relative timer, Clocking work time, Dates and Times
@section Effort estimates
-@cindex Effort estimates
+@cindex effort estimates
If you want to plan your work in a very detailed way, or if you need to
produce offers with quotations of the estimated work effort, you may want to
@end example
@noindent
-or you can set up these values globally by customizing the variables
-@code{org-global-properties} and @code{org-columns-default-format}. In
-particular if you want to use this setup also in the agenda, a global setup
-may be advised.
+or, even better, you can set up these values globally by customizing the
+variables @code{org-global-properties} and @code{org-columns-default-format}.
+In particular if you want to use this setup also in the agenda, a global
+setup may be advised.
The way to assign estimates to individual items is then to switch to column
mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the
If you switch to column view in the daily/weekly agenda, the effort column
will summarize the estimated work effort for each day@footnote{Please note
the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
-column view}.}, and you can use this to find space in your schedule. To get
+column view}).}, and you can use this to find space in your schedule. To get
an overview of the entire part of the day that is committed, you can set the
option @code{org-agenda-columns-add-appointments-to-effort-sum}. The
appointments on a day that take place over a specified time interval will
then also be added to the load estimate of the day.
-@node Remember, Agenda Views, Dates and Times, Top
-@chapter Remember
+Effort estimates can be used in secondary agenda filtering that is triggered
+with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have
+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
+@section Taking notes with a relative timer
+@cindex relative timer
+
+When taking notes during, for example, a meeting or a video viewing, it can
+be useful to have access to times relative to a starting time. Org provides
+such a relative timer and make it easy to create timed notes.
+
+@table @kbd
+@kindex C-c C-x .
+@item C-c C-x .
+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 -
+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}
+One the timer list is started, you can also use @kbd{M-@key{RET}} to insert
+new timer items.
+@kindex C-c C-x 0
+@item C-c C-x 0
+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
+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 Capture, Agenda Views, Dates and Times, Top
+@chapter Capture
+@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} package to create tasks, and stores files
+related to a task (@i{attachments}) in a special directory.
+
+@menu
+* Remember:: Capture new tasks/ideas with little interruption
+* Attachments:: Add files to tasks.
+@end menu
+
+@node Remember, Attachments, Capture, Capture
+@section Remember
@cindex @file{remember.el}
The @i{Remember} package by John Wiegley lets you store quick notes with
@end menu
@node Setting up Remember, Remember templates, Remember, Remember
-@section Setting up Remember
+@subsection Setting up Remember
The following customization will tell @i{remember} to use org files as
target, and to create annotations compatible with Org links.
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 time stamps
+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, Remember
-@section Remember templates
+@subsection Remember templates
@cindex templates, for remember
In combination with Org, you can use templates to generate
@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}.
-
-An optional sixth element specifies the contexts in which the user can
-select the template. This element can be either 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 mode, and select
-the template accordingly.
+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 note as level 1
+entries to the beginning or end of the file, respectively.
+
+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 mode, 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" my-check)
+ ("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
available when the function @code{my-check} returns @code{t}. The third
template will be proposed in any context.
-When you call @kbd{M-x remember} (or @kbd{M-x org-remember}) to remember
-something, org will prompt for a key to select the template (if you have
+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
@example
* TODO
@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.}
+ @r{The entire text will be indented like @code{%i} itself.}
%t @r{time stamp, date only}
%T @r{time stamp with date and time}
%u, %U @r{like the above, but inactive time stamps}
%^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}
-%i @r{initial content, the region when remember is called with C-u.}
- @r{The entire text will be indented like @code{%i} itself.}
%c @r{Current kill ring head.}
%x @r{Content of the X clipboard.}
%^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.}
+%^@{prop@}p @r{Prompt the user for a value for property @code{prop}}
%:keyword @r{specific information for certain link types, see below}
%[pathname] @r{insert the contents of the file given by @code{pathname}}
%(sexp) @r{evaluate elisp @code{(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
@noindent
template that will be filled with the previous context information.
@node Storing notes, Refiling notes, Remember templates, Remember
-@section Storing notes
-
-When you are finished preparing a note with @i{remember}, you have to
-press @kbd{C-c C-c} to file the note away. The handler will store the
-note in the file and under the headline specified in the template, or it
-will use the default file and headlines. The window configuration will
-be restored, sending you back to the working context before the call to
-@code{remember}. To re-use the location found during the last call to
-@code{remember}, exit the remember buffer with @kbd{C-u C-u C-c C-c},
-i.e. specify a double prefix argument to @kbd{C-c C-c}.
+@subsection Storing notes
+
+When you are finished preparing a note with @i{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 headlines.
+The window configuration will be restored, sending you back to the working
+context before the call to @code{remember}. To re-use the location found
+during the last call to @code{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.
If you want to store the note directly to a different place, use
-@kbd{C-u C-c C-c} instead to exit remember@footnote{Configure the
+@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.
@tab at cursor position, level taken from context.
@end multitable
-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 and some additional
-data. 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.
+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.
@node Refiling notes, , Storing notes, Remember
-@section Refiling notes
+@subsection Refiling notes
@cindex refiling notes
Remember is usually used to quickly capture notes and tasks into one or
@table @kbd
@kindex C-c C-w
@item C-c C-w
-Refile the entry at point. This command offers possible locations for
-refiling the entry and lets you select one with completion. The item is
-filed below the target heading as a subitem. Depending on
-@code{org-reverse-note-order}, it will be either the first of last
-subitem.@* By default, all level 1 headlines in the current buffer are
-considered to be targets, but you can have more complex definitions
-across a number of files. See the variable @code{org-refile-targets}
-for details.
+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.
+Depending on @code{org-reverse-note-order}, it will be either the first or
+last subitem.@*
+By default, all level 1 headlines in the current buffer are considered to be
+targets, but you can have more complex definitions across a number of files.
+See the variable @code{org-refile-targets} for details. If you would like to
+select a location via a file-path-like completion along the outline path, see
+the variables @code{org-refile-use-outline-path} and
+@code{org-outline-path-complete-in-steps}.
@kindex C-u C-c C-w
@item C-u C-c C-w
Use the refile interface to jump to a heading.
Jump to the location where @code{org-refile} last moved a tree to.
@end table
-@node Agenda Views, Embedded LaTeX, Remember, Top
+@node Attachments, , Remember, Capture
+@section Attachments
+@cindex attachments
+
+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
+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
+uses directories named by the unique ID of each entry. These directories are
+located in the @file{data} directory which lives in the same directory where
+your org-file lives@footnote{If you move entries or Org-files from one
+directory to the next, you may want to configure @code{org-attach-directory}
+to contain an absolute path.}. If you initialize this directory with
+@code{git-init}, Org will automatically commit changes when it sees them.
+The attachment system has been contributed to Org by John Wiegley.
+
+@noindent The following commands deal with attachments.
+
+@table @kbd
+
+@kindex C-c C-a
+@item C-c C-a
+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
+to select a command:
+
+@table @kbd
+@kindex C-c C-a a
+@item a
+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}.
+Note that hard links are not supported on all systems.
+
+@kindex C-c C-a c
+@kindex C-c C-a m
+@kindex C-c C-a l
+@item c/m/l
+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
+Create a new attachment as an Emacs buffer.
+
+@kindex C-c C-a z
+@item z
+Synchronize the current task with its attachment directory, in case you added
+attachments yourself.
+
+@kindex C-c C-a o
+@item o
+Open current task's attachment. If there are 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
+Also open the attachment, but force opening the file in Emacs.
+
+@kindex C-c C-a f
+@item f
+Open the current task's attachment directory.
+
+@kindex C-c C-a F
+@item F
+Also open the directory, but force using @code{dired} in Emacs.
+
+@kindex C-c C-a d
+@item d
+Select and delete a single attachment.
+
+@kindex C-c C-a D
+@item D
+Delete all of a task's attachments. A safer way is to open the directory in
+dired and delete from there.
+@end table
+@end table
+
+@node Agenda Views, Embedded LaTeX, Capture, Top
@chapter Agenda Views
@cindex agenda views
a @emph{TODO list} that covers all unfinished
action items,
@item
-a @emph{tags view}, showings headlines based on
-the tags associated with them,
+a @emph{match view}, showings headlines based on the tags, properties and
+TODO state associated with them,
@item
a @emph{timeline view} that shows all events in a single Org file,
in time-sorted view,
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 <
+@kindex C-c C-x >
+@item C-c C-x >
Remove the permanent restriction created by @kbd{C-c C-x <}.
@end table
Speedbar frame, either an Org file or a subtree in such a file.
If there is a window displaying an agenda view, the new restriction takes
effect immediately.
-@kindex <
+@kindex >
@item > @r{in the speedbar frame}
Lift the restriction again.
@end table
@cindex org-agenda, command
@kindex C-c a a
@item C-c a a
-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.} (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})
+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})
@end table
Remote editing from the agenda buffer means, for example, that you can
@cindex matching, of tags
@cindex matching, of properties
@cindex tags view
+@cindex match view
If headlines in the agenda files are marked with @emph{tags}
(@pxref{Tags}), you can select headlines based on the tags that apply
level-2 headlines, and that a project is not stuck if it has at least
one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
-Lets assume that you, in your own way of using Org mode, identify
+Let's assume that you, in your own way of using Org mode, identify
projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
-indicate a project that should not be considered yet. Lets further
+indicate a project that should not be considered yet. Let's further
assume that the TODO keyword DONE marks finished projects, and that NEXT
and TODO indicate next actions. The tag @@SHOP indicates shopping and
is a next action even without the NEXT tag. Finally, if the project
@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
In the headline of the entry itself, a time(range) may also appear as
-plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda
+plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda
integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
specifications in diary entries are recognized as well.
8:30-13:00 Arthur Dent lies in front of the bulldozer
12:45...... Ford Prefect arrives and takes Arthur to the pub
19:00...... The Vogon reads his poem
- 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
+ 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
@end example
@cindex time grid
18:00...... ------------------
19:00...... The Vogon reads his poem
20:00...... ------------------
- 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
+ 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
@end example
The time grid can be turned on and off with the variable
Sorting can be customized using the variable
@code{org-agenda-sorting-strategy}, and may also include criteria based on
-the estimated effort of an entry.
-@c FIXME: link!!!!!!!!
-
+the estimated effort of an entry (@pxref{Effort estimates}).
@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
@section Commands in the agenda buffer
@item mouse-3
@itemx @key{SPC}
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
@kindex l
@item l
Toggle Logbook mode. In Logbook mode, entries that where marked DONE while
-logging was on (variable @code{org-log-done}) are shown in the agenda,
-as are entries that have been clocked on that day.
+logging was on (variable @code{org-log-done}) are shown in the agenda, as are
+entries that have been clocked on that day. You can configure the entry
+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.
+@c
+@kindex v
+@item v
+Toggle Archives mode. In archives mode, trees that are marked are also
+scanned when producing the agenda. When you call this command with a
+@kbd{C-u} prefix argument, even all archive files are included. To exit
+archives mode, press @kbd{v} again.
@c
@kindex R
@item R
@code{#+COLUMNS} line, or from the default variable
@code{org-columns-default-format}), will be used in the agenda.
-@tsubheading{Query editing}
+@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 /
+Filter the current agenda view with respect to a tag and/or effort estimates.
+The difference between this and a custom agenda commands is that filtering is
+very fast, so that you can switch quickly between different filters without
+having to recreate the agenda.
+
+You will be prompted for a tag selection letter. 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.
+
+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.
+
+@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.
+
@kindex [
@kindex ]
@kindex @{
@kindex @}
@item [ ] @{ @}
-In the @i{search view} (@pxref{Keyword search}), these keys 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. Closing bracket/brace add a
-negative search term which @i{must not} occur/match in the entry for it
-to be selected.
+In the @i{search view} (@pxref{Keyword search}), these keys 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.
@tsubheading{Remote editing}
@c
@kindex A
@item A
-Move the subtree correspoding to the current entry to its @emph{Archive
+Move the subtree corresponding to the current entry to its @emph{Archive
Sibling}.
@c
@kindex $
@item $
Archive the subtree corresponding to the current headline. This means the
-entry will be moved to the configured archive locatin, most likely a
+entry will be moved to the configured archive location, most likely a
different file.
@c
@kindex T
@item T
-Show all tags associated with the current item. Because of
-inheritance, this may be more than the tags listed in the line itself.
+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 :
@itemx S-@key{down}
Decrease the priority of the current item.
@c
+@kindex C-c C-a
+@item C-c C-a
+Dispatcher for all command related to attachments.
+@c
@kindex C-c C-s
@item C-c C-s
Schedule this item
@item C-c C-d
Set a deadline for this item.
@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
+Press @kbd{r} afterward to refresh the agenda and see the effect of the
+command.
+@c
@kindex S-@key{right}
@item S-@key{right}
Change the time stamp associated with the current line by one day into the
If you are away from your computer, it can be very useful to have a
printed version of some agenda views to carry around. Org mode can
export custom agenda views as plain text, HTML@footnote{You need to
-install Hrvoje Niksic' @file{htmlize.el}.} postscript, and iCalendar
+install Hrvoje Niksic's @file{htmlize.el}.}, postscript, and iCalendar
files. If you want to do this only occasionally, use the command
@table @kbd
emacs -f org-batch-store-agenda-views -kill
@end example
@noindent
-or, if you need to modify some parameters
+or, if you need to modify some parameters@footnote{Quoting may depend on the
+system you use, please check th FAQ for examples.}
@example
emacs -eval '(org-batch-store-agenda-views \
org-agenda-ndays 30 \
($category,$head,$type,$todo,$tags,$date,$time,$extra,
$priority_l,$priority_n) = split(/,/,$line);
- # proccess and print
+ # process and print
print "[ ] $head\n";
@}
@end group
During HTML export (@pxref{HTML export}), these symbols are translated
into the proper syntax for HTML, for the above examples this is
-@samp{α} and @samp{→}, respectively.
+@samp{α} and @samp{→}, respectively. If you need such a symbol
+inside a word, terminate it like this: @samp{\Aacute@{@}stor}.
@node Subscripts and superscripts, LaTeX fragments, Math symbols, Embedded LaTeX
@section Subscripts and superscripts
Org mode can also produce extracts in the iCalendar format. Currently
Org mode only supports export, not import of these different formats.
-When exporting, Org mode uses special conventions to enrich the output
-produced. @xref{Text interpretation}, for more details.
-
-@table @kbd
-@kindex C-c C-e
-@item C-c C-e
-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. If the option
-@code{org-export-run-in-background} is set, Org will run the command in the
-background if that seems useful for the specific command (i.e. commands that
-write to a file).
-@kindex C-u C-u C-c C-e
-@item C-u C-u C-c C-e
-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 st.
-@end table
+Org supports export of selected regions when @code{transient-mark-mode} is
+enabled (default in Emacs 23).
@menu
+* Markup rules:: Which structures are recognized?
+* 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
* HTML export:: Exporting to HTML
-* LaTeX export:: Exporting to LaTeX
+* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF
* XOXO export:: Exporting to XOXO
* iCalendar export:: Exporting in iCalendar format
-* Text interpretation:: How the exporter looks at the file
@end menu
-@node ASCII export, HTML export, Exporting, Exporting
-@section ASCII export
-@cindex ASCII export
+@node Markup rules, Selective export, Exporting, Exporting
+@section Markup rules
-ASCII export produces a simple and very readable version of an Org mode
-file.
+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 or La@TeX{} allow much richer formatting, Org mode
+has rules how to prepare text for rich export. This section summarizes the
+markup rule used in an Org mode 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
-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, only the region will be
-exported. If the selected region is a single tree, 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 a
-@item C-c C-e v a
-Export only the visible part of the document.
-@end table
+@menu
+* Document title:: How the document title is determined
+* Headings and sections:: The main structure of the exported document
+* Table of contents:: If, where, how to create a table of contents
+* Initial text:: Text before the first headline
+* Lists:: Plain lists are exported
+* Paragraphs:: What determines beginning and ending
+* Literal examples:: Source code and other examples
+* Include files:: Include the contents of a file during export
+* Tables exported:: Tables are exported richly
+* Inlined images:: How to inline images during export
+* Footnotes:: Numbers like [1]
+* Emphasis and monospace:: To bold or not to bold
+* TeX macros and LaTeX fragments:: Create special, rich export.
+* Horizontal rules:: A line across the page
+* Comment lines:: Some lines will not be exported
+@end menu
-@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,
+@node Document title, Headings and sections, Markup rules, Markup rules
+@subheading Document title
+@cindex document title, markup rules
+
+@noindent
+The title of the exported document is taken from the special line
@example
-@kbd{C-1 C-c C-e a}
+#+TITLE: This is the title of the document
@end example
@noindent
-creates only top level headlines and does the rest as items. When
-headlines are converted to items, the indentation of the text following
-the headline is changed to fit nicely under the item. This is done with
-the assumption that the first body line indicates the base indentation of
-the body text. Any indentation larger than this is adjusted to preserve
-the layout relative to the first line. Should there be lines with less
-indentation than the first, these are left alone.
+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.
-@node HTML export, LaTeX export, ASCII export, Exporting
-@section HTML export
-@cindex HTML export
+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.
-Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive
-HTML formatting, in ways similar to John Grubers @emph{markdown}
-language, but with additional support for tables.
+@node Headings and sections, Table of contents, Document title, Markup rules
+@subheading Headings and sections
+@cindex headings and sections, markup rules
-@menu
-* HTML Export commands:: How to invoke LaTeX export
-* Quoting HTML tags:: Using direct HTML in Org mode
-* Links:: Transformation of links for HTML
-* Images:: How to include images
-* CSS support:: Changing the appearance of the output
-* Javascript support:: Info and Folding in a web browser
-@end menu
+The outline structure of the document as described in @ref{Document
+Structure} forms the basis for defining sections of the exported document.
+However, since the outline structure is also used for (for example) lists of
+tasks, only the first three outline levels will be used as headings. Deeper
+levels will become itemized lists. You can change the location of this
+switch, globally by setting the variable @code{org-headline-levels}, or on a
+per file basis with a line
-@node HTML Export commands, Quoting HTML tags, HTML export, HTML export
-@subsection HTML export commands
+@example
+#+OPTIONS: H:4
+@end example
-@cindex region, active
-@cindex active region
-@cindex Transient mark mode
-@table @kbd
-@kindex C-c C-e h
-@item C-c C-e h
-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, only
-the region will be exported. If the selected region is a single tree,
-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
+@node Table of contents, Initial text, Headings and sections, Markup rules
+@subheading Table of contents
+@cindex table of contents, markup rules
-@cindex headline levels, for exporting
-In the exported version, the first 3 outline levels will become headlines,
+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
+
+@example
+#+OPTIONS: toc:2 (only to two levels in TOC)
+#+OPTIONS: toc:nil (no TOC at all)
+@end example
+
+@node Initial text, Lists, Table of contents, Markup rules
+@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 or La@TeX{} code, use the special constructs
+described below in the sections for the individual exporters.
+
+Some people like to use the space before the first headline for setup and
+internal links and therefore would like to control the exported text before
+the first headline in a different way. You can do so by setting the variable
+@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file
+basis, you can get the same effect with @samp{#+OPTIONS: skip:t}.
+
+@noindent
+If you still want to have some text before the first headline, use the
+@code{#+TEXT} construct:
+
+@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
+@end example
+
+@node Lists, Paragraphs, Initial text, Markup rules
+@subheading Lists
+@cindex lists, markup rules
+
+Plain lists as described in @ref{Plain lists} are translated to the back-ends
+syntax for such lists. Most back-ends support unordered, ordered, and
+description lists.
+
+@node Paragraphs, Literal examples, Lists, Markup rules
+@subheading Paragraphs, line breaks, and quoting
+@cindex paragraphs, markup rules
+
+Paragraphs are separated by at least one empty line. If you need to enforce
+a line break within a paragraph, use @samp{\\} at the end of a line.
+
+To keep the line breaks in a region, but otherwise use normal formatting, you
+can use this construct, which can also be used to format poetry.
+
+@example
+#+BEGIN_VERSE
+ Great clouds overhead
+ Tiny black birds rise and fall
+ Snow covers Emacs
+
+ -- AlexSchroeder
+#+END_VERSE
+@end example
+
+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:
+
+@example
+#+BEGIN_QUOTE
+Everything should be made as simple as possible,
+but not any simpler -- Albert Einstein
+#+END_QUOTE
+@end example
+
+
+@node Literal examples, Include files, Paragraphs, Markup rules
+@subheading Literal examples
+@cindex literal examples, markup rules
+
+You can include literal examples that should not be subjected to
+markup. Such examples will be typeset in monospace, so this is well suited
+for source code and similar examples.
+@cindex #+BEGIN_EXAMPLE
+
+@example
+#+BEGIN_EXAMPLE
+Some example from a text file.
+#+END_EXAMPLE
+@end example
+
+For simplicity when using small examples, you can also start the example
+lines with a colon:
+
+@example
+: Some example from a text file.
+@end example
+
+@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 only for
+the HTML back-end, and requires the @file{htmlize.el} package version 1.34 or
+later.}. 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:
+@cindex #+BEGIN_SRC
+
+@example
+#+BEGIN_SRC emacs-lisp
+(defun org-xor (a b)
+ "Exclusive or."
+ (if a (not b) b))
+#+END_SRC
+@end example
+
+@table @kbd
+@kindex C-c '
+@item C-c '
+Edit the source code example at point in its native mode. This works by
+switching to an indirect buffer, narrowing the buffer and switching to the
+other mode. 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.}. 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.
+@end table
+
+
+@node Include files, Tables exported, Literal examples, Markup rules
+@subheading Include files
+@cindex include files, markup rules
+
+During export, you can include the content of another file. For example, to
+include your .emacs file, you could use:
+@cindex #+INCLUDE
+
+@example
+#+INCLUDE: "~/.emacs" src emacs-lisp
+@end example
+
+The optional second and third parameter are the markup (@samp{quote},
+@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
+language for formatting the contents. The markup is optional, if it is not
+given, the text will be assumed to be in Org mode format and will be
+processed normally. The include line will also allow additional keyword
+parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the
+first line and for each following line. For example, to include a file as an
+item, use
+
+@example
+#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " "
+@end example
+
+@table @kbd
+@kindex C-c '
+@item C-c '
+Visit the include file at point.
+@end table
+
+@node Tables exported, Inlined images, Include files, Markup rules
+@subheading Tables
+@cindex tables, markup rules
+
+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:
+
+@example
+#+CAPTION: This is the caption for the next table (or link)
+#+LABEL: tbl:basic-data
+@end example
+
+@node Inlined images, Footnotes, Tables exported, Markup rules
+@subheading Inlined Images
+@cindex inlined images, markup rules
+
+Some backends (HTML and LaTeX) allow 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 can use (before, but close to the link)
+
+@example
+#+CAPTION: This is the caption for the next figure link (or table)
+#+LABEL: fig:SED-HR4049
+@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.
+
+@node Footnotes, Emphasis and monospace, Inlined images, Markup rules
+@subheading Footnotes
+@cindex footnotes, markup rules
+@cindex @file{footnote.el}
+
+@kindex C-c !
+Numbers in square brackets are treated as footnote markers, and lines
+starting with such a marker are interpreted as the footnote itself. You can
+use the Emacs package @file{footnote.el} to create footnotes@footnote{The
+@file{footnote} package uses @kbd{C-c !} to invoke its commands. This
+binding conflicts with the Org mode command for inserting inactive time
+stamps. You could use the variable @code{footnote-prefix} to switch
+footnotes commands to another key. Or, if you are too used to this binding,
+you could use @code{org-replace-disputed-keys} and @code{org-disputed-keys}
+to change the settings in Org.}. For example:
+
+@example
+The Org homepage[1] now looks a lot better than it used to.
+
+[1] The link is: http://orgmode.org
+@end example
+
+@node Emphasis and monospace, TeX macros and LaTeX fragments, Footnotes, Markup rules
+@subheading Emphasis and monospace
+
+@cindex underlined text, markup rules
+@cindex bold text, markup rules
+@cindex italic text, markup rules
+@cindex verbatim text, markup rules
+@cindex code text, markup rules
+@cindex strike-through text, markup rules
+You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
+and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text
+in the code and verbatim string is not processed for Org mode specific
+syntax, it is exported verbatim.
+
+@node TeX macros and LaTeX fragments, Horizontal rules, Emphasis and monospace, Markup rules
+@subheading @TeX{} macros and La@TeX{} fragments
+@cindex LaTeX fragments, markup rules
+@cindex TeX macros, markup rules
+@cindex HTML entities
+@cindex LaTeX entities
+
+A @TeX{}-like syntax is used to specify special characters. Where possible,
+these will be transformed into the native format of the exporter back-end.
+Strings like @code{\alpha} will be exported as @code{α} in the HTML
+output, and as @code{$\alpha$} in the La@TeX{} output. Similarly,
+@code{\nbsp} will become @code{ } in HTML and @code{~} in La@TeX{}.
+This applies for a large number of entities, with names taken from both HTML
+and La@TeX{}, see the variable @code{org-html-entities} for the complete
+list. If you are unsure about a name, use @kbd{M-@key{TAB}} for completion
+after having types the backslash and maybe a few characters
+(@pxref{Completion}).
+
+La@TeX{} fragments are converted into images for HTML export, and they are
+written literally into the La@TeX{} export. See also @ref{Embedded LaTeX}.
+
+Finally, @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 Horizontal rules, Comment lines, TeX macros and LaTeX fragments, Markup rules
+@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).
+
+@node Comment lines, , Horizontal rules, Markup rules
+@subheading Comment lines
+@cindex comment lines
+@cindex exporting, not
+
+Lines starting with @samp{#} in column zero 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 ;
+@item C-c ;
+Toggle the COMMENT keyword at the beginning of an entry.
+@end table
+
+@node Selective export, Export options, Markup rules, Exporting
+@section Selective export
+@cindex export, selective by 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}.
+
+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.
+
+@noindent
+If none of the select tags is found, the whole buffer will be selected for
+export.
+
+@noindent
+Finally, all subtrees that are marked by any of the @emph{exclude} tags will
+be removed from the export buffer.
+
+@node Export options, The export dispatcher, Selective export, Exporting
+@section Export options
+@cindex options, for export
+
+@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}).
+
+@table @kbd
+@kindex C-c C-e t
+@item C-c C-e t
+Insert template with export options, see example below.
+@end table
+
+@cindex #+TITLE:
+@cindex #+AUTHOR:
+@cindex #+DATE:
+@cindex #+EMAIL:
+@cindex #+LANGUAGE:
+@cindex #+TEXT:
+@cindex #+OPTIONS:
+@cindex #+LINK_UP:
+@cindex #+LINK_HOME:
+@cindex #+EXPORT_SELECT_TAGS:
+@cindex #+EXPORT_EXCLUDE_TAGS:
+@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})
+#+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 ...
+#+LINK_UP: the ``up'' link of an exported page
+#+LINK_HOME: the ``home'' link of an exported page
+#+EXPORT_SELECT_TAGS: Tags that select a tree for export
+#+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export
+@end example
+
+@noindent
+The OPTIONS line is a compact@footnote{If you want to configure many options
+this way, you can use several OPTIONS lines.} form to specify export 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
+
+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}, 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.
+
+@table @kbd
+@kindex C-c C-e
+@item C-c C-e
+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
+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 st.
+@end table
+
+@node ASCII export, HTML export, The export dispatcher, Exporting
+@section ASCII export
+@cindex ASCII export
+
+ASCII export produces a simple and very readable version of an Org mode
+file.
+
+@cindex region, active
+@cindex active region
+@cindex transient-mark-mode
+@table @kbd
+@kindex C-c C-e a
+@item C-c C-e a
+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} 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 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,
+
+@example
+@kbd{C-1 C-c C-e a}
+@end example
+
+@noindent
+creates only top level headlines and does the rest as items. When
+headlines are converted to items, the indentation of the text following
+the headline is changed to fit nicely under the item. This is done with
+the assumption that the first body line indicates the base indentation of
+the body text. Any indentation larger than this is adjusted to preserve
+the layout relative to the first line. Should there be lines with less
+indentation than the first, these are left alone.
+
+@node HTML export, LaTeX and PDF export, ASCII 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
+* Quoting HTML tags:: Using direct HTML in Org mode
+* Links:: Transformation of links for HTML
+* Images in HTML export::
+* CSS support:: Changing the appearance of the output
+* Javascript support:: Info and Folding in a web browser
+@end menu
+
+@node HTML Export commands, Quoting HTML tags, HTML export, HTML export
+@subsection HTML export commands
+
+@cindex region, active
+@cindex active region
+@cindex transient-mark-mode
+@table @kbd
+@kindex C-c C-e h
+@item C-c C-e h
+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} 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 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
+
+@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,
@end example
@noindent or
+@cindex #+BEGIN_HTML
@example
#+BEGIN_HTML
@end example
-@node Links, Images, Quoting HTML tags, HTML export
+@node Links, Images in HTML export, Quoting HTML tags, HTML export
@subsection Links
@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
-files only if they match a dedicated @samp{<<target>>}. Automatic links
-created by radio targets (@pxref{Radio targets}) will also work in the
-HTML file. Links to external files will still work if the HTML file is
-in the same directory as the Org file. Links to other @file{.org}
-files will be translated into HTML links under the assumption that an
-HTML version also exists of the linked file. For information related to
-linking files while publishing them to a publishing directory see
-@ref{Publishing links}.
-
-@node Images, CSS support, Links, HTML export
+Internal links (@pxref{Internal links}) will continue to work in HTML.
+Automatic links created by radio targets (@pxref{Radio targets}) will also
+work in the HTML file. Links to external files will still work if the HTML
+file is in the same directory as the Org file. Links to other @file{.org}
+files will be translated into HTML links under the assumption that an HTML
+version also exists of the linked file. For information related to linking
+files while publishing them to a publishing directory see @ref{Publishing
+links}.
+
+If you want to specify attributes for links, you can do so using a special
+@code{#+ATTR_HTML} line to define attributes that will be added to the
+@code{<a>} or @code{<img>} tags. Here is an example that sets @code{alt} and
+@code{title} attributes for an inlined image:
+
+@example
+#+ATTR_HTML: alt="This is image A" title="Image with no action"
+[[./img/a.jpg]]
+@end example
+
+@node Images in HTML export, CSS support, Links, HTML export
@subsection Images
@cindex images, inline in HTML
@noindent
and you could use @code{http} addresses just as well.
-@node CSS support, Javascript support, Images, HTML export
+@node CSS support, Javascript support, Images in HTML export, HTML export
@subsection CSS support
@cindex CSS, for HTML export
@cindex HTML export, CSS
.target @r{target for links}
@end example
-The default style specification can be configured through the option
-@code{org-export-html-style}. If you want to use a file-local style,
-you may use file variables, best wrapped into a COMMENT section at the
-end of the outline tree. For example@footnote{Under Emacs 21, the
-continuation lines for a variable value should have no @samp{#} at the
-start of the line.}:
+Each exported files 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
+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
@example
-* COMMENT html style specifications
-
-# Local Variables:
-# org-export-html-style: " <style type=\"text/css\">
-# p @{font-weight: normal; color: gray; @}
-# h1 @{color: black; @}
-# </style>"
-# End:
+#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
@end example
-Remember to execute @kbd{M-x normal-mode} after changing this to make
-the new style visible to Emacs. This command restarts Org mode for the
-current buffer and forces Emacs to re-evaluate the local variables
-section in the buffer.
+@noindent
+For longer style definitions, you can use several such lines. You could also
+directly write a @code{<style>} @code{</style>} section in this way, without
+referring to an external file.
@c FIXME: More about header and footer styles
@c FIXME: Talk about links and targets.
@emph{Sebastian Rose} has written a JavaScript program especially designed to
enhance the web viewing experience of HTML files created with Org. This
-program allows to view large files in two different ways. The first one is
+program allows you to view large files in two different ways. The first one is
an @emph{Info}-like mode where each section is displayed separately and
navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
as well, press @kbd{?} for an overview of the available keys). The second
-view type is a @emph{folding} view much like Org provides it inside Emacs.
+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/org-infojs.html}.
-We are serving the script from 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
-copy on your own web server.
+find the documentation for it at
+@url{http://orgmode.org/worg/code/org-info-js/org-info.js.html}. We are
+serving the script from 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 copy on
+your own web server.
-To use the script, you need to make sure that the @file{org-infojs.el} module
-gets loaded. It should be loaded by default, 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:
+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:
@example
-#+INFOSJ_OPT: view:info toc:nil
+#+INFOJS_OPT: view:info toc:nil
@end example
@noindent
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 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{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-headline-levels} and @code{org-export-with-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?}
mouse: @r{Headings are highlighted when the mouse is over them. Should be}
@r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
@code{org-infojs-options}. If you always want to apply the script to your
pages, configure the variable @code{org-export-html-use-infojs}.
-@node LaTeX export, XOXO export, HTML export, Exporting
-@section LaTeX export
+@node LaTeX and PDF export, XOXO export, HTML export, Exporting
+@section LaTeX and PDF export
@cindex LaTeX export
+@cindex PDF export
-Org mode contains a La@TeX{} exporter written by Bastien Guerry.
+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 LaTeX output uses @file{hyperref} to implement links and cross
+references, the PDF output file will be fully linked.
@menu
-* LaTeX export commands:: How to invoke LaTeX export
+* LaTeX/PDF export commands:: Which key invokes which commands
* Quoting LaTeX code:: Incorporating literal LaTeX code
* Sectioning structure:: Changing sectioning in LaTeX output
+* Tables in LaTeX export:: Options for exporting tables to LaTeX
+* Images in LaTeX export:: How to insert figures into LaTeX output
@end menu
-@node LaTeX export commands, Quoting LaTeX code, LaTeX export, LaTeX export
+@node LaTeX/PDF export commands, Quoting LaTeX code, 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
-Export as La@TeX{} file @file{myfile.tex}.
+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} 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 L
@item C-c C-e L
Export to a temporary buffer, do not create a file.
@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 LaTeX and then process to PDF.
+@kindex C-c C-e d
+@item C-c C-e d
+Export as LaTeX and then process to PDF, then open the resulting PDF file.
@end table
@cindex headline levels, for exporting
with a numeric prefix argument. For example,
@example
-@kbd{C-2 C-c C-e l}
-@end example
-
-@noindent
-creates two levels of headings and does the rest as items.
-
-@node Quoting LaTeX code, Sectioning structure, LaTeX export commands, LaTeX export
-@subsection Quoting LaTeX code
-
-Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly
-inserted into the La@TeX{} file. Furthermore, you can add special code
-that should only be present in La@TeX{} export with the following
-constructs:
-
-@example
-#+LaTeX: Literal LaTeX code for export
-@end example
-
-@noindent or
-
-@example
-#+BEGIN_LaTeX
-All lines between these markers are exported literally
-#+END_LaTeX
-@end example
-
-
-
-@node Sectioning structure, , Quoting LaTeX code, LaTeX export
-@subsection Sectioning structure
-@cindex LaTeX class
-@cindex LaTeX sectioning structure
-
-By default, the La@TeX{} output uses the class @code{article}.
-
-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. The class should be
-listed in @code{org-export-latex-classes}, where you can also define the
-sectioning structure for each class.
-
-
-@node XOXO export, iCalendar export, LaTeX export, Exporting
-@section XOXO export
-@cindex XOXO export
-
-Org mode contains an exporter that produces XOXO-style output.
-Currently, this exporter only handles the general outline structure and
-does not interpret any additional Org mode features.
-
-@table @kbd
-@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
-
-@node iCalendar export, Text interpretation, XOXO export, Exporting
-@section iCalendar export
-@cindex iCalendar export
-
-Some people like to 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 have deadlines and
-other time-stamped items in Org files show up 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}.
-
-@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
-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
-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
-
-The export will honor SUMMARY, DESCRIPTION and LOCATION 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 Text interpretation, , iCalendar export, Exporting
-@section Text interpretation by the exporter
-
-The exporter backends interpret additional structure in the Org file
-in order to produce better output.
-
-@menu
-* Comment lines:: Some lines will not be exported
-* Initial text:: Text before the first headline
-* Footnotes:: Numbers like [1]
-* Quoted examples:: Inserting quoted chunks of text
-* Enhancing text:: Subscripts, symbols and more
-* Export options:: How to influence the export settings
-@end menu
-
-@node Comment lines, Initial text, Text interpretation, Text interpretation
-@subsection Comment lines
-@cindex comment lines
-@cindex exporting, not
-
-Lines starting with @samp{#} in column zero are treated as comments
-and will never be exported. Also entire subtrees starting with the
-word @samp{COMMENT} will never be exported.
-
-@table @kbd
-@kindex C-c ;
-@item C-c ;
-Toggle the COMMENT keyword at the beginning of an entry.
-@end table
-
-@node Initial text, Footnotes, Comment lines, Text interpretation
-@subsection Text before the first headline
-
-Org mode normally ignores any text before the first headline when
-exporting, leaving this region for internal links to speed up navigation
-etc. However, in publishing-oriented files, you might want to have some
-text before the first headline, like a small introduction, special HTML
-code with a navigation bar, etc. You can ask to have this part of the
-file exported as well by setting the variable
-@code{org-export-skip-text-before-1st-heading} to @code{nil}. On a
-per-file basis, you can get the same effect with
-
-@example
-#+OPTIONS: skip:nil
-@end example
-
-The text before the first headline will be fully processed
-(@pxref{Enhancing text}), and the first non-comment line becomes the
-title of the exported document. If you need to include literal HTML,
-use the special constructs described in @ref{Quoting HTML tags}. 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.
-
-Finally, if you want to use the space before the first headline for
-internal purposes, but @emph{still} want to place something before the
-first headline when exporting the file, you can use the @code{#+TEXT}
-construct:
-
-@example
-#+OPTIONS: skip:t
-#+TEXT: This text will go before the *first* headline.
-#+TEXT: We place the table of contents here:
-#+TEXT: [TABLE-OF-CONTENTS]
-#+TEXT: This goes between the table of contents and the first headline
+@kbd{C-2 C-c C-e l}
@end example
-@node Footnotes, Quoted examples, Initial text, Text interpretation
-@subsection Footnotes
-@cindex footnotes
-@cindex @file{footnote.el}
+@noindent
+creates two levels of headings and does the rest as items.
-Numbers in square brackets are treated as footnotes, so that you can use
-the Emacs package @file{footnote.el} to create footnotes. For example:
+@node Quoting LaTeX code, Sectioning structure, LaTeX/PDF export commands, LaTeX and PDF export
+@subsection Quoting LaTeX code
-@example
-The Org homepage[1] clearly needs help from
-a good web designer.
+Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly
+inserted into the La@TeX{} file. Furthermore, you can add special code
+that should only be present in La@TeX{} export with the following
+constructs:
-[1] The link is: http://orgmode.org
+@example
+#+LaTeX: Literal LaTeX code for export
@end example
-@noindent
-@kindex C-c !
-Note that the @file{footnote} package uses @kbd{C-c !} to invoke its
-commands. This binding conflicts with the Org mode command for
-inserting inactive time stamps. You could use the variable
-@code{footnote-prefix} to switch footnotes commands to another key. Or,
-if you are too used to this binding, you could use
-@code{org-replace-disputed-keys} and @code{org-disputed-keys} to change
-the settings in Org.
-
-@node Quoted examples, Enhancing text, Footnotes, Text interpretation
-@subsection Quoted examples
-@cindex quoted examples
-@cindex examples, quoted
-@cindex text, fixed width
-@cindex fixed width text
-
-When writing technical documents, you often need to insert examples that
-are not further interpreted by Org mode. For historical reasons, there
-are several ways to do this:
+@noindent or
+@cindex #+BEGIN_LaTeX
-@itemize @bullet
-@item
-If a headline starts with the word @samp{QUOTE}, the text below the
-headline will be typeset as fixed-width, to allow quoting of computer
-codes etc.
-@item
-Lines starting with @samp{:} are also typeset in fixed-width font.
-@table @kbd
-@kindex C-c :
-@item C-c :
-Toggle fixed-width for entry (QUOTE) or region, see below.
-@end table
-@item
-Finally, text between
@example
-#+BEGIN_EXAMPLE
-quoted text
-#+END_EXAMPLE
+#+BEGIN_LaTeX
+All lines between these markers are exported literally
+#+END_LaTeX
@end example
-will also be exported in this way.
-@end itemize
+@node Sectioning structure, Tables in LaTeX export, Quoting LaTeX code, LaTeX and PDF export
+@subsection Sectioning structure
+@cindex LaTeX class
+@cindex LaTeX sectioning structure
-@node Enhancing text, Export options, Quoted examples, Text interpretation
-@subsection Enhancing text for export
-@cindex enhancing text
-@cindex richer text
+By default, the La@TeX{} output uses the class @code{article}.
-Some of the export backends of Org mode allow for sophisticated text
-formatting, this is true in particular for the HTML and La@TeX{}
-backends. Org mode has a number of typing conventions that allow to
-produce a richly formatted output.
+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. 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.
-@itemize @bullet
-@cindex hand-formatted lists
-@cindex lists, hand-formatted
-@item
-Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
-or @samp{2)} as enumerator will be recognized and transformed if the
-backend supports lists. See @xref{Plain lists}.
+@node Tables in LaTeX export, Images in LaTeX export, Sectioning structure, LaTeX and PDF export
+@subsection Tables in LaTeX export
+@cindex tables, in LaTeX export
-@cindex underlined text
-@cindex bold text
-@cindex italic text
-@cindex verbatim text
-@item
-You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
-and @code{~verbatim~}, and, if you must, @samp{+strikethrough+}. Text
-in the code and verbatim string is not processed for Org mode specific
-syntax, it is exported verbatim.
+For LaTeX export of a table, you can specify a label and a caption
+(@pxref{Tables exported}). You can also use the @code{ATTR_LaTeX} line to
+request a longtable environment for the table, so that it may span several
+pages:
-@cindex horizontal rules, in exported files
-@item
-A line consisting of only dashes, and at least 5 of them, will be
-exported as a horizontal line (@samp{<hr/>} in HTML).
+@example
+#+CAPTION: A long table
+#+LABEL: tbl:long
+#+ATTR_LaTeX: longtable
+| ..... | ..... |
+| ..... | ..... |
+@end example
-@cindex LaTeX fragments, export
-@cindex TeX macros, export
-@item
-Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML
-entities or images (@pxref{Embedded LaTeX}).
-@cindex tables, export
-@item
-Tables are transformed into native tables under the exporter, if the
-export backend supports this. Data fields before the first horizontal
-separator line will be formatted as table header fields.
+@node Images in LaTeX export, , Tables in LaTeX export, LaTeX and PDF export
+@subsection 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 files resulting from LaTeX output. 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{Markup rules}, the figure will
+be wrapped into a @code{figure} environment and thus become a floating
+element. Finally, you can use an @code{#+ATTR_LaTeX:} line to specify the
+options that can be used in the optional argument of the
+@code{\includegraphics} macro.
-@cindex fixed width
-@item
-If a headline starts with the word @samp{QUOTE}, the text below the
-headline will be typeset as fixed-width, to allow quoting of computer
-codes etc. Lines starting with @samp{:} are also typeset in fixed-width
-font.
-@table @kbd
-@kindex C-c :
-@item C-c :
-Toggle fixed-width for entry (QUOTE) or region, see below.
-@end table
-Finally, text between
@example
-#+BEGIN_EXAMPLE
-quoted text
-#+END_EXAMPLE
+#+CAPTION: The black-body emission of the disk around HR 4049
+#+LABEL: fig:SED-HR4049
+#+ATTR_LaTeX: width=5cm,angle=90
+[[./img/sed-hr4049.pdf]]
@end example
-will also be exported in this way.
-@cindex linebreak, forced
-@item
-A double backslash @emph{at the end of a line} enforces a line break at
-this position.
-@cindex HTML entities, LaTeX entities
-@item
-Strings like @code{\alpha} will be exported as @code{α}, in the
-HTML output. These strings are exported as @code{$\alpha$} in the
-La@TeX{} output. Similarly, @code{\nbsp} will become @code{ } in
-HTML and in La@TeX{}. This applies for a long list of entities, see
-the variable @code{org-html-entities} for the complete list.
-@c FIXME
-@end itemize
+@node XOXO export, iCalendar export, LaTeX and PDF export, Exporting
+@section XOXO export
+@cindex XOXO export
-If these conversions conflict with your habits of typing ASCII text,
-they can all be turned off with corresponding variables. See the
-customization group @code{org-export-general}, and the following section
-which explains how to set export options with special lines in a
-buffer.
+Org mode contains an exporter that produces XOXO-style output.
+Currently, this exporter only handles the general outline structure and
+does not interpret any additional Org mode features.
+@table @kbd
+@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
-@node Export options, , Enhancing text, Text interpretation
-@subsection Export options
-@cindex options, for export
+@node iCalendar export, , XOXO export, Exporting
+@section iCalendar export
+@cindex iCalendar export
-@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}).
+Some people like to 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 have deadlines and other time-stamped items
+in Org files show up 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}. iCalendar export will export plain time
+stamps 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}.}.
+
+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
-@kindex C-c C-e t
-@item C-c C-e t
-Insert template with export options, see example below.
+@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
+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
+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
-#+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})
-#+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 ...
-@end example
-
-@noindent
-The OPTIONS line is a compact form to specify export settings. Here
-you can:
-@cindex headline levels
-@cindex section-numbers
-@cindex table of contents
-@cindex linebreak 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 linebreak-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 foototes like this[1].}
-*: @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}
-timestamp: @r{turn on/off inclusion creation time into exported file}
-d: @r{turn on/off inclusion of drawers}
-@end example
+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).
-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.
+How this calendar is best read and updated, that depends on the application
+you are using. The FAQ covers this issue.
@node Publishing, Miscellaneous, Exporting, Top
@chapter Publishing
of the ``components'' property are taken to be components of the
project, which group together files requiring different publishing
options. When you publish such a ``meta-project'' all the components
-will also publish.
+will also publish. The @code{:components} are published in the sequence
+provided.
@node Sources and destinations, Selecting files, Project alist, Configuration
@subsection Sources and destinations for files
@item @code{:publishing-directory}
@tab Directory (possibly remote) where output files will be published.
@item @code{:preparation-function}
-@tab Function called before starting publishing process, for example to
+@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
@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-publish-org-to-html} which calls the HTML exporter
-(@pxref{HTML export}). But you also can publish your files in La@TeX{} by
-using the function @code{org-publish-org-to-latex} instead. Other files
-like images only need to be copied to the publishing destination. For
-non-Org files, you need to specify the publishing function.
-
+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 files in La@TeX{} by using the
+function @code{org-publish-org-to-latex} instead, or as PDF files using
+@code{org-publish-org-to-pdf}. Other files like images only need to be
+copied to the publishing destination. For non-Org files, you need to provide
+your own publishing function:
@multitable @columnfractions 0.3 0.7
@item @code{:publishing-function}
with the variable they belong to. See the documentation string for the
respective variable for details.
-@multitable @columnfractions 0.3 0.7
+@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{: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{:tags} .@tab @code{org-export-with-tags}
+@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{: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{: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}
+@item @code{:select-tags} @tab @code{org-export-select-tags}
+@item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
@end multitable
If you use several email addresses, separate them by a semi-column.
You may also link to related files, such as images. Provided you are
careful with relative pathnames, and provided you have also configured
@code{org-publish} to upload the related files, these links will work
-too. @ref{Complex example} for an example of this usage.
+too. See @ref{Complex example} for an example of this usage.
Sometime an Org file to be published may contain links that are
only valid in your production environment, but not in the publishing
:publishing-directory "~/public_html"
:section-numbers nil
:table-of-contents nil
- :style "<link rel=stylesheet
+ :style "<link rel=\"stylesheet\"
href=\"../other/mystyle.css\"
type=\"text/css\">")))
@end lisp
:headline-levels 3
:section-numbers nil
:table-of-contents nil
- :style "<link rel=stylesheet
+ :style "<link rel=\"stylesheet\"
href=\"../other/mystyle.css\" type=\"text/css\">"
:auto-preamble t
:auto-postamble nil)
functions normally only publish changed files. You can override this and
force publishing of all files by giving a prefix argument.
-@node Miscellaneous, Extensions and Hacking, Publishing, Top
+@node Miscellaneous, Extensions, Publishing, Top
@chapter Miscellaneous
@menu
line set 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:
+Set tags that can be inherited by any entry in the file, including the
+top-level entries.
@item #+DRAWERS: NAME1 .....
Set the file-local set of drawers. The corresponding global variable is
@code{org-drawers}.
@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
+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:
This line sets options to be used at startup of Org mode, when an
Org file is being visited. The first set of options deals with the
lognoteclock-out @r{record a note when clocking out}
nolognoteclock-out @r{don't record a note when clocking out}
@end example
-Here are the options for hiding leading stars in outline headings. The
-corresponding variables are @code{org-hide-leading-stars} and
-@code{org-odd-levels-only}, both with a default setting @code{nil}
-(meaning @code{showstars} and @code{oddeven}).
+Here are the options for hiding leading stars in outline headings, and for
+indenting outlines. The corresponding variables are
+@code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a
+default setting @code{nil} (meaning @code{showstars} and @code{oddeven}).
@cindex @code{hidestars}, STARTUP keyword
@cindex @code{showstars}, STARTUP keyword
@cindex @code{odd}, STARTUP keyword
@example
hidestars @r{make all but one of the stars starting a headline invisible.}
showstars @r{show all stars starting a headline}
+indent @r{virtual indentation according to outline level}
+noindent @r{no virtual indentation according to outline level}
odd @r{allow only odd outline levels (1,3,...)}
oddeven @r{allow all outline levels}
@end example
@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
@section A cleaner outline view
@cindex hiding leading stars
+@cindex dynamic indentation
+@cindex odd-levels-only outlines
@cindex clean outline view
-Some people find it noisy and distracting that the Org headlines
-are starting with a potentially large number of stars. For example
-the tree from @ref{Headlines}:
+Some people find it noisy and distracting that the Org headlines are starting
+with a potentially large number of stars, and that text below the headlines
+is not indented. This is not really a problem when you are writing a book
+where the outline headings are really section headlines. However, in a more
+list-oriented outline, it is clear that an indented structure is a lot
+cleaner, as can be seen by comparing the two columns in the following
+example:
@example
-* Top level headline
-** Second level
-*** 3rd level
- some text
-*** 3rd level
- more text
-* Another top level headline
+@group
+* Top level headline | * Top level headline
+** Second level | * Second level
+*** 3rd level | * 3rd level
+some text | some text
+*** 3rd level | * 3rd level
+more text | more text
+* Another top level headline | * Another top level headline
+@end group
@end example
@noindent
-Unfortunately this is deeply ingrained into the code of Org and
-cannot be easily changed. You can, however, modify the display in such
-a way that all leading stars become invisible and the outline more easy
-to read. To do this, customize the variable
-@code{org-hide-leading-stars} like this:
+It is non-trivial to make such a look work in Emacs, but Org contains three
+separate features that, combined, achieve just that.
-@lisp
-(setq org-hide-leading-stars t)
-@end lisp
+@enumerate
+@item
+@emph{Indentation of text below headlines}@*
+You may indent text below each headline to make the left boundary line up
+with the headline, like
-@noindent
-or change this on a per-file basis with one of the lines (anywhere in
-the buffer)
+@example
+*** 3rd level
+ more text, now indented
+@end example
+
+A good way to get this indentation is by hand, and Org supports this with
+paragraph filling, line wrapping, and structure editing@footnote{See also the
+variable @code{org-adapt-indentation}.} preserving or adapting the
+indentation appropriate. A different approach would be to have a way to
+automatically indent lines according to outline structure by adding overlays
+or text properties. But I have not yet found a robust and efficient way to
+do this in large files.
+
+@item
+@emph{Hiding leading stars}@* You can modify the display in such a way that
+all leading stars become invisible. To do this in a global way, configure
+the variable @code{org-hide-leading-stars} or change this on a per-file basis
+with
@example
-#+STARTUP: showstars
#+STARTUP: hidestars
@end example
@noindent
-Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate
-the modifications.
+Note that the opposite behavior is selected with @code{showstars}.
-With stars hidden, the tree becomes:
+With hidden stars, the tree becomes:
@example
+@group
* Top level headline
* Second level
* 3rd level
- some text
- * 3rd level
- more text
-* Another top level headline
+ ...
+@end group
@end example
@noindent
stars are @i{almost} invisible, for example using the color
@code{grey90} on a white background.
-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:
-
-@example
-* Top level headline
- * Second level
- * 3rd level
- some text
- * 3rd level
- more text
-* Another top level headline
-@end example
-
-@noindent
-In order to make the structure editing and export commands handle this
-convention correctly, use
-
-@lisp
-(setq org-odd-levels-only t)
-@end lisp
-
-@noindent
-or set this on a per-file basis with one of the following lines (don't
-forget to press @kbd{C-c C-c} with the cursor in the startup line to
-activate changes immediately).
+@item
+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. 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 a per-file basis with one of the
+following lines:
@example
#+STARTUP: odd
double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
RET} in that file. The reverse operation is @kbd{M-x
org-convert-to-oddeven-levels}.
+@end enumerate
@node TTY keys, Interaction, Clean view, Miscellaneous
@section Using Org on a tty
@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab
@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}}
@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab
-@item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{@key{Esc} @key{right}}
+@item @kbd{M-@key{right}} @tab @kbd{C-c C-x i} @tab @kbd{@key{Esc} @key{right}}
@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab
@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{@key{Esc} @key{up}}
@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab
may use the command @code{org-table-iterate} (@kbd{C-u C-c *}) to
recalculate until convergence.
@item
-A single letter cannot be made bold, for example @samp{*a*}.
-@item
The exporters work well, but could be made more efficient.
@end itemize
-@node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top
-@appendix Extensions, Hooks and Hacking
+@node Extensions, Hacking, Miscellaneous, Top
+@appendix Extensions
+
+This appendix lists the extension modules that have been written for Org.
+Many of these extensions live in the @file{contrib} directory of the Org
+distribution, others are available somewhere on the web.
+
+@menu
+* Extensions in the contrib directory:: These come with the Org distro
+* Other extensions:: These you have to find on the web.
+@end menu
+
+@node Extensions in the contrib directory, Other extensions, Extensions, Extensions
+@section Extensions in the @file{contrib} directory
+
+A number of extension are distributed with Org when you download it from its
+homepage. Please note that these extensions are @emph{not} distributed as
+part of Emacs, so if you use Org as delivered with Emacs, you still need to
+go to @url{http://orgmode.org} to get access to these modules.
+
+@table @asis
+@item @file{org-annotate-file.el} by @i{Philip Jackson}
+ Annotate a file with org syntax, in a separate file, with links back to
+ the annotated file.
+@item @file{org-annotation-helper.el} by @i{Bastien Guerry and Daniel E. German}
+ Call @i{remember} directly from Firefox/Opera, or from Adobe Reader.
+ When activating a special link or bookmark, Emacs receives a trigger to
+ create a note with a link back to the website. Requires some setup, a
+ detailed description is in
+ @file{contrib/packages/org-annotation-helper}.
+@item @file{org-bookmark.el} by @i{Tokuya Kameshima}
+ Support for links to Emacs bookmarks.
+@item @file{org-depend.el} by @i{Carsten Dominik}
+ TODO dependencies for Org-mode. Make TODO state changes in one entry
+ trigger changes in another, or be blocked by the state of another
+ entry. Also, easily create chains of TODO items with exactly one
+ active item at any time.
+@item @file{org-elisp-symbol.el} by @i{Bastien Guerry}
+ Org links to emacs-lisp symbols. This can create annotated links that
+ exactly point to the definition location of a variable of function.
+@item @file{org-eval.el} by @i{Carsten Dominik}
+ The @code{<lisp>} tag, adapted from Emacs Wiki and Emacs Muse, allows
+ text to be included in a document that is the result of evaluating some
+ code. Other scripting languages like @code{perl} can be supported with
+ this package as well.
+@item @file{org-eval-light.el} by @i{Eric Schulte}
+ User-controlled evaluation of code in an Org buffer.
+@item @file{org-exp-blocks.el} by @i{Eric Schulte}
+ Preprocess user-defined blocks for export.
+@item @file{org-expiry.el} by @i{Bastien Guerry}
+ Expiry mechanism for Org entries.
+@item @file{org-indent.el} by @i{Carsten Dominik}
+ Dynamic indentation of Org outlines. The plan is to indent an outline
+ according to level, but so far this is too hard for a proper and stable
+ implementation. Still, it works somewhat.
+@item @file{org-interactive-query.el} by @i{Christopher League}
+ Interactive modification of tags queries. After running a general
+ query in Org, this package allows to narrow down the results by adding
+ more tags or keywords.
+@item @file{org-mairix.el} by @i{Georg C. F. Greve}
+ Hook mairix search into Org for different MUAs.
+@item @file{org-man.el} by @i{Carsten Dominik}
+ Support for links to manpages in Org-mode.
+@item @file{org-mtags.el} by @i{Carsten Dominik}
+ Support for some Muse-like tags in Org-mode. This package allows you
+ to write @code{<example>} and @code{<src>} and other syntax copied from
+ Emacs Muse, right inside an Org file. The goal here is to make it easy
+ to publish the same file using either org-publish or Muse.
+@item @file{org-panel.el} by @i{Lennart Borgman}
+ Simplified and display-aided access to some Org commands.
+@item @file{org-registry.el} by @i{Bastien Guerry}
+ A registry for Org links, to find out from where links point to a given
+ file or location.
+@item @file{org2rem.el} by @i{Bastien Guerry}
+ Convert org appointments into reminders for the @file{remind} program.
+@item @file{org-screen.el} by @i{Andrew Hyatt}
+ Visit screen sessions through Org-mode links.
+@item @file{org-toc.el} by @i{Bastien Guerry}
+ Table of contents in a separate buffer, with fast access to sections
+ and easy visibility cycling.
+@item @file{orgtbl-sqlinsert.el} by @i{Jason Riedy}
+ Convert Org-mode tables to SQL insertions. Documentation for this can
+ be found on the Org pages.
+@end table
+
+@node Other extensions, , Extensions in the contrib directory, Extensions
+@section Other extensions
+
+@i{TO BE DONE}
+
+@node Hacking, History and Acknowledgments, Extensions, Top
+@appendix Hacking
-This appendix lists extensions for Org written by other authors.
-It also covers some aspects where users can extend the functionality of
+This appendix covers some aspects where users can extend the functionality of
Org.
@menu
-* Extensions:: Existing 3rd-party extensions
* Adding hyperlink types:: New custom link types
* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
* Using the property API:: Writing programs that use entry properties
+* Using the mapping API:: Mapping over all or selected entries
@end menu
-@node Extensions, Adding hyperlink types, Extensions and Hacking, Extensions and Hacking
-@section Third-party extensions for Org
-@cindex extension, third-party
-
-There are lots of extensions that have been written by other people. Most of
-them have either been integrated into Org by now, or they can be found in the
-Org distribution, in the @file{contrib} directory. The list has gotten too
-long to cover in any detail here, but there is a seaparate manual for these
-extensions.
-
-@node Adding hyperlink types, Tables in arbitrary syntax, Extensions, Extensions and Hacking
+@node Adding hyperlink types, Tables in arbitrary syntax, Hacking, Hacking
@section Adding hyperlink types
@cindex hyperlinks, adding new types
Org has a large number of hyperlink types built-in
(@pxref{Hyperlinks}). If you would like to add new link types, it
-provides an interface for doing so. Lets look at an example file
+provides an interface for doing so. Let's look at an example file
@file{org-man.el} that will add support for creating links like
@samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside
emacs:
@end lisp
@noindent
-Lets go through the file and see what it does.
+Let's go through the file and see what it does.
@enumerate
@item
It does @code{(require 'org)} to make sure that @file{org.el} has been
the link description when the link is later inserted into an Org
buffer with @kbd{C-c C-l}.
-@node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Extensions and Hacking
+@node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Hacking
@section Tables and lists in arbitrary syntax
@cindex tables, in other modes
@cindex lists, in other modes
@table @code
@item :skip N
-Skip the first N lines of the table. Hlines do count!
+Skip the first N lines of the table. Hlines do count as separate lines for
+this parameter!
+
@item :skipcols (n1 n2 ...)
List of columns that should be skipped. If the table has a column with
calculation marks, that column is automatically discarded as well.
be prompted for a table name, lets say we use @samp{salesfigures}. You
will then get the following template:
+@cindex #+ORGTBL: SEND
@example
% BEGIN RECEIVE ORGTBL salesfigures
% END RECEIVE ORGTBL salesfigures
The La@TeX{} 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:
+interprets the following parameters (see also @ref{Translator functions}):
@table @code
@item :splice nil/t
@cindex HTML, and Orgtbl mode
@cindex translator function
-Orgtbl mode has several translator functions built-in:
-@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and
-@code{orgtbl-to-texinfo}. Except for @code{orgtbl-to-html}@footnote{The
-HTML translator uses the same code that produces tables during HTML
-export.}, these all use a generic translator, @code{orgtbl-to-generic}.
-For example, @code{orgtbl-to-latex} itself is a very short function that
-computes the column definitions for the @code{tabular} environment,
-defines a few field and line separators and then hands over to the
-generic translator. Here is the entire code:
+Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv}
+(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values)
+@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}.
+Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same
+code that produces tables during HTML export.}, these all use a generic
+translator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex}
+itself is a very short function that computes the column definitions for the
+@code{tabular} environment, defines a few field and line separators and then
+hands over to the generic translator. Here is the entire code:
@lisp
@group
Pressing `C-c C-c' on @code{a new house} and will insert the converted
La@TeX{} list between the two marker lines.
-@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking
+@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
@section Dynamic blocks
@cindex dynamic blocks
to the block and can also specify parameters for the function producing
the content of the block.
+#+BEGIN:dynamic block
@example
#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
written in a way that is does nothing in buffers that are not in
@code{org-mode}.
-@node Special agenda views, Using the property API, Dynamic blocks, Extensions and Hacking
+@node Special agenda views, Using the property API, Dynamic blocks, Hacking
@section Special agenda views
@cindex agenda views, user-defined
@lisp
(org-add-agenda-custom-command
'("b" todo "PROJECT"
- ((org-agenda-skip-function 'my-org-waiting-projects)
+ ((org-agenda-skip-function 'my-skip-unless-waiting)
(org-agenda-overriding-header "Projects waiting for something: "))))
@end lisp
(org-agenda-overriding-header "Projects waiting for something: "))))
@end lisp
-@node Using the property API, , Special agenda views, Extensions and Hacking
+@node Using the property API, Using the mapping API, Special agenda views, Hacking
@section Using the property API
@cindex API, for properties
@cindex properties, API
Insert a property drawer at point.
@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.
+@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.
+@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.
values and check if VALUE is in this list.
@end defun
-@node History and Acknowledgments, Main Index, Extensions and Hacking, Top
+@node Using the mapping API, , Using the property API, Hacking
+@section Using the mapping API
+@cindex API, for mapping
+@cindex mapping entries, API
+
+Org has sophisticated mapping capabilities to find all entries satisfying
+certain criteria. Internally, this functionality is used to produce agenda
+views, but there is also an API that can be used to execute arbitrary
+functions for each or selected entries. The main entry point for this API
+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.
+
+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:
+
+@example
+nil @r{the current buffer, respecting the restriction if any}
+tree @r{the subtree started with the entry at point}
+file @r{the current buffer, without restriction}
+file-with-archives
+ @r{the current buffer, and any archives associated with it}
+agenda @r{all agenda files}
+agenda-with-archives
+ @r{all agenda files with any archive files associated with them}
+(file1 file2 ...)
+ @r{if this is a list, all files in the list will be scanned}
+@end example
+
+The remaining args are treated as settings for the skipping facilities of
+the scanner. The following items can be given here:
+
+@example
+archive @r{skip trees with the archive tag}
+comment @r{skip trees with the COMMENT keyword}
+function or Lisp form
+ @r{will be used as value for @code{org-agenda-skip-function},}
+ @r{so whenever the the function returns t, FUNC}
+ @r{will not be called for that entry and search will}
+ @r{continue from the point where the function leaves it}
+@end example
+@end defun
+
+The function given to that mapping routine can really do anything you like.
+It can use the property API (@pxref{Using the property API}) to gather more
+information about the entry, or in order to change metadata in the entry.
+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.
+@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.
+@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.
+@end defun
+
+@defun org-promote
+Promote the current entry.
+@end defun
+
+@defun org-demote
+Demote the current entry.
+@end defun
+
+Here is a simple example that will turn all entries in the current file with
+a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}.
+Entries in comment trees and in archive trees will be ignored.
+
+@lisp
+(org-map-entries
+ '(org-todo "UPCOMING")
+ "+TOMORROW" 'file 'archive 'comment)
+@end lisp
+
+The following example counts the number of entries with TODO keyword
+@code{WAITING}, in all agenda files.
+
+@lisp
+(length (org-map-entries t "/+WAITING" 'agenda))
+@end lisp
+
+@node History and Acknowledgments, Main Index, Hacking, Top
@appendix History and Acknowledgments
@cindex acknowledgments
@cindex history
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 writen a large
+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 has also helped the development and maintenance of Org so much that he
should be considered co-author of this package.
@item
@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
@item
+@i{Christophe Bataillon} created the great unicorn logo that we use on the
+Org-mode website.
+@item
@i{Alex Bochannek} provided a patch for rounding time stamps.
@item
@i{Charles Cave}'s suggestion sparked the implementation of templates
task state change logging, and the clocktable. His clear explanations have
been critical when we started to adopt the GIT version control system.
@item
+@i{Manuel Hermenegildo} has contributed various ideas, small fixed and
+patches.
+@item
@i{Phil Jackson} wrote @file{org-irc.el}.
@item
@i{Scott Jaderholm} proposed footnotes, control over whitespace between
@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
conflict with @file{allout.el}.
@item
-@i{Jason Riedy} sent a patch to fix a bug with export of TODO keywords.
+@i{Jason Riedy} generalized the send-receive mechanism for orgtbl tables with
+extensive patches.
@item
-@i{Philip Rooke} created the Org reference card and provided lots
-of feedback.
+@i{Philip Rooke} created the Org reference card, provided lots
+of feedback, developed and applied standards to the Org documentation.
@item
@i{Christian Schlauer} proposed angular brackets around links, among
other things.
@item
-Linking to VM/BBDB/Gnus was inspired by @i{Tom Shannon}'s
+@i{Eric Schulte} wrote @file{org-plot.el}.
+@item
+Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
@file{organizer-mode.el}.
@item
@i{Ilya Shlyakhter} proposed the Archive Sibling.
@item
+@i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
+now packaged into Org's @file{contrib} directory.
+@item
@i{Daniel Sinder} came up with the idea of internal archiving by locking
subtrees.
@item
@i{Dale Smith} proposed link abbreviations.
@item
-@i{Adam Spiers} asked for global linking commands and inspired the link
-extension system. support mairix.
+@i{James TD Smith} has contributed a large number of patches for useful
+tweaks and features.
+@item
+@i{Adam Spiers} asked for global linking commands, inspired the link
+extension system, added support for mairix, and proposed the mapping API.
+@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.
@i{David Wainberg} suggested archiving, and improvements to the linking
system.
@item
-@i{John Wiegley} wrote @file{emacs-wiki.el} and @file{planner.el}. The
-development of Org was fully independent, and both systems are really
-different beasts in their basic ideas and implementation details. I later
-looked at John's code, however, and learned from his implementation of (i)
-links where the link itself is hidden and only a description is shown, and
-(ii) popping up a calendar to select a date. John has also contributed a
-number of great ideas and patches directly to Org, including the file
-@code{org-mac-message.el}'
+@i{John Wiegley} wrote @file{emacs-wiki.el}, @file{planner.el}, and
+@file{muse.el}, which have similar goals as 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}) and integration with Apple Mail
+(@file{org-mac-message.el}).
@item
@i{Carsten Wimmer} suggested some changes and helped fix a bug in
linking to Gnus.
@c ispell-local-pdict: "./.aspell.org.pws"
@c fill-column: 77
@c End:
+
HCoop / bpt / emacs.git / blobdiff