@setfilename ../../info/org
@settitle The Org Manual
-@set VERSION 6.05a
-@set DATE June 2008
+@set VERSION 6.13a
+@set DATE November 2008
@dircategory Emacs
@direntry
@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
* 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::
-* Hacking::
+* Extensions:: Add-ons for Org mode
+* Hacking:: How 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
* 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
* 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::
* Quoting LaTeX code:: Incorporating literal LaTeX code
* Sectioning structure:: Changing sectioning in LaTeX output
@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.
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
@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
@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.
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
* 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 dispables 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
| # | 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
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}.
@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 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 inly 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
:END:
@end example
-
@node Priorities, Breaking down tasks, Progress logging, TODO Items
@section Priorities
@cindex priorities
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:}.
+e.g., @samp{:work:}. Several tags can be specified, as in
+@samp{:work:urgent:}.
@menu
* Tag inheritance:: Tags use the tree structure of the outline
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
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@footnote{The
+only special values that will be recognized are @samp{"<now>"} for now
+(including time), and @samp{"<today>"}, @samp{<tomorrow>}, and
+@samp{<yesterday>} for these days at 0:00 hours, i.e. without a time
+specification.}, and the comparison will be done accordingly.
+@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
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.
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
@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 .
: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
@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
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 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
%^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}
template that will be filled with the previous context information.
@node Storing notes, Refiling notes, Remember templates, Remember
-@section Storing notes
+@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 is filed away.
+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-u C-u C-c C-c}, i.e. specify a double prefix argument to @kbd{C-c
-C-c}.
+@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. If you would like to select a location via a file-pathlike
-completion along the outline path, see the variable
-@code{org-refile-use-outline-path}.
+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 hyperlings
+(@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,
@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.
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
@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}
@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
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 \
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
@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
@end menu
-@node Markup rules, Export options, Exporting, Exporting
+@node Markup rules, Selective export, Exporting, Exporting
@section Markup rules
When exporting Org mode documents, the exporter tries to reflect the
@example
#+BEGIN_VERSE
-Everything should be made as simple as possible,
-but not any simpler -- Albert Einstein
+ Great clouds overhead
+ Tiny black birds rise and fall
+ Snow covers Emacs
+
+ -- AlexSchroeder
#+END_VERSE
@end example
@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.
+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
@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.
+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 '
Toggle the COMMENT keyword at the beginning of an entry.
@end table
-@node Export options, The export dispatcher, Markup rules, Exporting
+@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 #+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})
#+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
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
@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).
+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
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 export, ASCII export, Exporting
+@node HTML export, LaTeX and PDF export, ASCII export, Exporting
@section HTML export
@cindex HTML export
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
+syntax. Here is an example that sets @code{alt} and @code{title} attributes
+for an inlined image:
+
+@example
+[[./img/a.jpg@{@{alt="This is image A" title="Image with no action"@}@}]]
+@end example
+
@node Images, CSS support, Links, HTML export
@subsection Images
.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.
@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::
* Quoting LaTeX code:: Incorporating literal LaTeX code
* Sectioning structure:: Changing sectioning in 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
@table @kbd
@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
@noindent
creates two levels of headings and does the rest as items.
-@node Quoting LaTeX code, Sectioning structure, LaTeX export commands, LaTeX export
+@node Quoting LaTeX code, Sectioning structure, LaTeX/PDF export commands, LaTeX and PDF export
@subsection Quoting LaTeX code
Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly
#+END_LaTeX
@end example
-@node Sectioning structure, , Quoting LaTeX code, LaTeX export
+@node Sectioning structure, , Quoting LaTeX code, LaTeX and PDF 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.
+@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 additonal classes.
-@node XOXO export, iCalendar export, LaTeX export, Exporting
+@node XOXO export, iCalendar export, LaTeX and PDF export, Exporting
@section XOXO export
@cindex XOXO export
@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}.
+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
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
+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
@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}
@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
@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{:tags} @tab @code{org-export-with-tags}
@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{:expand-quoted-html} @tab @code{org-export-html-expand}
@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.
: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)
with
@example
-#+STARTUP: showstars
#+STARTUP: hidestars
@end example
+@noindent
+Note that the opposite behavior is selected with @code{showstars}.
+
With hidden stars, the tree becomes:
@example
@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
@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
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
- to include text in a document that is the result of evaluating some
+ 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}
be found on the Worg pages.
@end table
-
@node Other extensions, , Extensions in the contrib directory, Extensions
@section Other extensions
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
@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
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.
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 tags view.
+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.
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{Christian Schlauer} proposed angular brackets around links, among
other things.
@item
+@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{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
development of Org was fully independent because I was not aware of the
existence of these packages. But with time I have accasionally 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 file
-@code{org-mac-message.el}'
+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