@c %**start of header
@setfilename ../../info/org
@settitle The Org Manual
-@set VERSION 7.9.2 (GNU Emacs 24.3)
+@set VERSION 7.9.3f (GNU Emacs 24.3)
@c Use proper quote and backtick for code sections in PDF output
@c Cf. Texinfo manual 14.2
@copying
This manual is for Org version @value{VERSION}.
-Copyright @copyright{} 2004-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2004--2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+modify this GNU manual.''
@end quotation
@end copying
@contents
@ifnottex
+@c FIXME These hand-written next,prev,up node pointers make editing a lot
+@c harder. There should be no need for them, makeinfo can do it
+@c automatically for any document with a normal structure.
@node Top, Introduction, (dir), (dir)
@top Org Mode Manual
* Hacking:: How to hack your way around
* MobileOrg:: Viewing and capture on a mobile device
* History and Acknowledgments:: How Org came into being
+* GNU Free Documentation License:: The license for this documentation.
* Main Index:: An index of Org's concepts and features
* Key Index:: Key bindings and where they are described
* Command and Function Index:: Command names and some internal functions
Introduction
* Summary:: Brief summary of what Org does
-* Installation:: How to install a downloaded version of Org
+* Installation:: Installing Org
* Activation:: How to activate Org for certain buffers
* Feedback:: Bug reports, ideas, patches etc.
* Conventions:: Typesetting conventions in the manual
* Capture:: Capturing new stuff
* Attachments:: Add files to tasks
* RSS Feeds:: Getting input from RSS feeds
-* Protocols:: External (e.g.@: Browser) access to Emacs and Org
+* Protocols:: External (e.g., Browser) access to Emacs and Org
* Refiling notes:: Moving a tree from one place to another
* Archiving:: What to do with finished projects
@menu
* Summary:: Brief summary of what Org does
-* Installation:: How to install a downloaded version of Org
+* Installation:: Installing Org
* Activation:: How to activate Org for certain buffers
* Feedback:: Bug reports, ideas, patches etc.
* Conventions:: Typesetting conventions in the manual
@r{@bullet{} an environment for literate programming}
@end example
-
@cindex FAQ
There is a website for Org which provides links to the newest
version of Org, as well as additional information, frequently asked
-questions (FAQ), links to tutorials, etc@. This page is located at
+questions (FAQ), links to tutorials, etc. This page is located at
@uref{http://orgmode.org}.
@cindex print edition
@cindex installation
@cindex XEmacs
-@b{Important:} @i{If you the version of Org that comes with Emacs or as a
-XEmacs package, please skip this section and go directly to @ref{Activation}.
-If you downloaded Org as an ELPA package, please read the instructions on the
-@uref{http://orgmode.org/elpa.html, Org ELPA page}. To see what version of Org
-(if any) is part of your Emacs distribution, type @kbd{M-x org-version} (if
-your Emacs distribution does not come with Org, this function will not be
-defined).}
-
-Installation of Org mode uses a build system, which is described in more
-detail on @uref{http://orgmode.org/worg/dev/org-build-system.html, Worg}.
-
-If you have downloaded Org from the Web as a distribution @file{.zip} or
-@file{.tar.gz} archive, take the following steps to install it:
+Org is part of recent distributions of GNU Emacs, so you normally don't need
+to install it. If, for one reason or another, you want to install Org on top
+of this pre-packaged version, there are three ways to do it:
@itemize @bullet
-@item Unpack the distribution archive.
-@item Change into (@code{cd}) the Org directory.
-@item Run @code{make help config}
-and then check and edit the file @file{local.mk} if the default configuration
-does not match your system. Set the name of the Emacs binary (likely either
-@file{emacs} or @file{xemacs}), and the paths to the directories where local
-Lisp and Info files will be installed. If the Emacs binary is not in your
-path, give the full path to the executable. Avoid spaces in any path names.
-@item Run @code{make config}
-again to check the configuration.
-@item Optionally run @code{make test}
-to build Org mode and then run the full testsuite.
-@item Run @code{make install} or @code{sudo make install}
-to build and install Org mode on your system.
+@item By using Emacs package system.
+@item By downloading Org as an archive.
+@item By using Org's git repository.
@end itemize
-If you use a cloned Git repository, then the procedure is slightly different.
-The following description assumes that you are using the @code{master} branch
-(where the development is done). You could also use the @code{maint} branch
-instead, where the release versions are published, just replace @code{master}
-with @code{maint} in the description below.
-
-@itemize @bullet
-@item Change into (@code{cd}) the Org repository.
-@item Run @code{git checkout master}
-to switch to the @code{master} branch of the Org repository.
-@item Run @code{make help}
-and then check and edit the file @file{local.mk}. You must set the name of
-the Emacs binary (likely either @file{emacs} or @file{xemacs}), and the paths
-to the directories where local Lisp and Info files will be installed. If the
-Emacs binary is not in your path, you must give the full path to the
-executable. Avoid spaces in any path names.
-@item Run @code{make config}
-to check the configuration.
-@item Run @code{make update2} or @code{make up2}
-to update the Git repository and build and install Org mode. The latter
-invocation runs the complete test suite before installation and installs only
-if the build passes all tests.
-@end itemize
+We @b{strongly recommend} to stick to a single installation method.
-If you don't have access to the system-wide directories and you don't want to
-install somewhere into your home directory, you can run Org directly from the
-distribution directory or Org repository by compiling Org mode in place:
+@subsubheading Using Emacs packaging system
-@itemize @bullet
-@item Change into (@code{cd}) the Org repository.
-@item Run @code{git checkout master}
-to switch to the @code{master} branch of the Org repository.
-@item Run @code{make compile}
-@end itemize
+Recent Emacs distributions include a packaging system which lets you install
+Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
+To make sure your Org configuration is well taken into account, initialize
+the package system with @code{(package-initialize)} before setting any Org
+option. If you want to use Org's package repository, check out the
+@uref{http://orgmode.org/elpa.html, Org ELPA page}.
-Last but not least you can also run Org mode directly from an Org repository
-without any compilation. Simply replace the last step in the recipe above
-with @code{make uncompiled}.
+@subsubheading Downloading Org as an archive
-Then add the following line to @file{.emacs}:
+You can download Org latest release from @uref{http://orgmode.org/, Org's
+website}. In this case, make sure you set the load-path correctly in your
+@file{.emacs}:
@example
(add-to-list 'load-path "~/path/to/orgdir/lisp")
@end example
-@noindent
-If you plan to use code from the @file{contrib} subdirectory without
-compiling them, do a similar step for this directory:
+The downloaded archive contains contributed libraries that are not included
+in Emacs. If you want to use them, add the @file{contrib} directory to your
+load-path:
@example
(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
@end example
-If you want to include those files with the build and install, please
-customize the variable @code{ORG_ADD_CONTRIB} instead in your @code{local.mk}
-file, for more details please see this
-@uref{http://orgmode.org/worg/dev/org-build-system.html#sec-4-1-2,
-description on Worg}.
+Optionally, you can compile the files and/or install them in your system.
+Run @code{make help} to list compilation and installation options.
+
+@subsubheading Using Org's git repository
-Installing Info files is system dependent, because of differences in the
-@file{install-info} program. The Info documentation is installed together
-with the rest of Org mode. If you don't install Org mode, it is possible to
-install the Info documentation seperately (you need to have
-install-info@footnote{The output from install-info (if any) is system
-dependent. In particular Debian and its derivatives use two different
-versions of install-info and you may see the message:
+You can clone Org's repository and install Org like this:
@example
-This is not dpkg install-info anymore, but GNU install-info
-See the man page for ginstall-info for command line arguments
+$ cd ~/src/
+$ git clone git://orgmode.org/org-mode.git
+$ make autoloads
@end example
-@noindent which can be safely ignored.}
-on your system).
+Note that in this case, @code{make autoloads} is mandatory: it defines Org's
+version in @file{org-version.el} and Org's autoloads in
+@file{org-loaddefs.el}.
-@example
-make install-info
-@end example
+Remember to add the correct load-path as described in the method above.
-Do not forget to activate Org as described in the following section.
-@page
+You can also compile with @code{make}, generate the documentation with
+@code{make doc}, create a local configuration with @code{make config} and
+install Org with @code{make install}. Please run @code{make help} to get
+the list of compilation/installation options.
+
+For more detailed explanations on Org's build system, please check the Org
+Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
+Worg}.
@node Activation, Feedback, Installation, Introduction
@section Activation
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
@end lisp
-Org mode buffers need font-lock to be turned on - this is the default in
+Org mode buffers need font-lock to be turned on: this is the default in
Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
The four Org commands @command{org-store-link}, @command{org-capture},
@command{org-agenda}, and @command{org-iswitchb} should be accessible through
-global keys (i.e.@: anywhere in Emacs, not just in Org buffers). Here are
+global keys (i.e., anywhere in Emacs, not just in Org buffers). Here are
suggested bindings for these keys, please modify the keys to your own
liking.
@lisp
@cindex show children, command
@orgcmd{C-c @key{TAB},show-children}
Expose all direct children of the subtree. With a numeric prefix argument N,
-expose all children down to level N.
+expose all children down to level N@.
@orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
Show the current subtree in an indirect buffer@footnote{The indirect
buffer
@end table
@vindex org-startup-folded
+@vindex org-agenda-inhibit-startup
@cindex @code{overview}, STARTUP keyword
@cindex @code{content}, STARTUP keyword
@cindex @code{showall}, STARTUP keyword
@cindex @code{showeverything}, STARTUP keyword
When Emacs first visits an Org file, the global state is set to
-OVERVIEW, i.e.@: only the top level headlines are visible. This can be
+OVERVIEW, i.e., only the top level headlines are visible. This can be
configured through the variable @code{org-startup-folded}, or on a
per-file basis by adding one of the following lines anywhere in the
buffer:
#+STARTUP: showeverything
@end example
+The startup visibility options are ignored when the file is open for the
+first time during the agenda generation: if you want the agenda to honor
+the startup visibility, set @code{org-agenda-inhibit-startup} to nil.
+
@cindex property, VISIBILITY
@noindent
Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
@code{all}.
@table @asis
@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
-Switch back to the startup visibility of the buffer, i.e.@: whatever is
+Switch back to the startup visibility of the buffer, i.e., whatever is
requested by startup options and @samp{VISIBILITY} properties in individual
entries.
@end table
variable @code{org-M-RET-may-split-line}.}. If the command is used at the
beginning of a headline, the new headline is created before the current line.
If at the beginning of any other line, the content of that line is made the
-new heading. If the command is used at the end of a folded subtree (i.e.@:
+new heading. If the command is used at the end of a folded subtree (i.e.,
behind the ellipses at the end of a headline), then a headline like the
current one will be inserted after the end of the subtree.
@orgcmd{C-@key{RET},org-insert-heading-respect-content}
level).
@orgcmd{M-S-@key{down},org-move-subtree-down}
Move subtree down (swap with next subtree of same level).
+@orgcmd{M-h,org-mark-element}
+Mark the element at point. Hitting repeatedly will mark subsequent elements
+of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
+hitting @key{M-h} immediately again will mark the next one.
+@orgcmd{C-c @@,org-mark-subtree}
+Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
+of the same level than the marked subtree.
@orgcmd{C-c C-x C-w,org-cut-subtree}
-Kill subtree, i.e.@: remove it from buffer but save in kill ring.
+Kill subtree, i.e., remove it from buffer but save in kill ring.
With a numeric prefix argument N, kill N sequential subtrees.
@orgcmd{C-c C-x M-w,org-copy-subtree}
Copy subtree to kill ring. With a numeric prefix argument N, copy the N
@samp{A)} by configuring @code{org-alphabetical-lists}. To minimize
confusion with normal text, those are limited to one character only. Beyond
that limit, bullets will automatically fallback to numbers.}. If you want a
-list to start with a different value (e.g.@: 20), start the text of the item
+list to start with a different value (e.g., 20), start the text of the item
with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
must be put @emph{before} the checkbox. If you have activated alphabetical
lists, you can also use counters like @code{[@@b]}.}. Those constructs can
Org mode supports the creation of footnotes. In contrast to the
@file{footnote.el} package, Org mode's footnotes are designed for work on a
larger document, not only for one-off documents like emails. The basic
-syntax is similar to the one used by @file{footnote.el}, i.e.@: a footnote is
+syntax is similar to the one used by @file{footnote.el}, i.e., a footnote is
defined in a paragraph that is started by a footnote marker in square
brackets in column 0, no indentation allowed. If you need a paragraph break
inside a footnote, use the @LaTeX{} idiom @samp{\par}. The footnote reference
n @r{Normalize the footnotes by collecting all definitions (including}
@r{inline definitions) into a special section, and then numbering them}
@r{in sequence. The references will then also be numbers. This is}
- @r{meant to be the final step before finishing a document (e.g.@: sending}
+ @r{meant to be the final step before finishing a document (e.g., sending}
@r{off an email). The exporters do this automatically, and so could}
@r{something like @code{message-send-hook}.}
d @r{Delete the footnote at point, and all definitions of and references}
@section The built-in table editor
@cindex table editor, built-in
-Org makes it easy to format tables in plain ASCII. Any line with @samp{|} as
+Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} as
the first non-whitespace character is considered part of a table. @samp{|}
is also the column separator@footnote{To insert a vertical bar into a table
field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
@end example
Column specifications can be absolute like @code{$1},
-@code{$2},...@code{$@var{N}}, or relative to the current column (i.e.@: the
+@code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
column of the field which is being computed) like @code{$+1} or @code{$-2}.
@code{$<} and @code{$>} are immutable references to the first and last
column, respectively, and you can use @code{$>>>} to indicate the third
However, this syntax is deprecated, it should not be used for new documents.
Use @code{@@>$} instead.} row in the table, respectively. You may also
specify the row relative to one of the hlines: @code{@@I} refers to the first
-hline, @code{@@II} to the second, etc@. @code{@@-I} refers to the first such
+hline, @code{@@II} to the second, etc. @code{@@-I} refers to the first such
line above the current line, @code{@@+I} to the first such line below the
current line. You can also write @code{@@III+2} which is the second data line
after the third hline in the table.
@code{@@0} and @code{$0} refer to the current row and column, respectively,
-i.e. to the row/column for the field being computed. Also, if you omit
+i.e., to the row/column for the field being computed. Also, if you omit
either the column or the row part of the reference, the current row/column is
implied.
$P..$Q @r{range, using column names (see under Advanced)}
$<<<..$>> @r{start in third column, continue to the one but last}
@@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
-@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row}
+@@-1$-2..@@-1 @r{in the first row up, 3 fields from 2 columns on the left}
@@I..II @r{between first and second hline, short for @code{@@I..@@II}}
@end example
'(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
@r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}}
'(+ $1 $2);N
-@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}}
+@r{Compute the sum of columns 1--4, like Calc's @code{vsum($1..$4)}}
'(apply '+ '($1..$4));N
@end example
Install a new formula for the current column and replace current field with
the result of the formula. The command prompts for a formula, with default
taken from the @samp{#+TBLFM} line, applies it to the current field and
-stores it. With a numeric prefix argument(e.g.@: @kbd{C-5 C-c =}) the command
+stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
will apply it to that many consecutive fields in the current column.
@end table
Selects this line for global recalculation with @kbd{C-u C-c *}, but
not for automatic recalculation. Use this when automatic
recalculation slows down editing too much.
-@item
+@item @w{ }
Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
All lines that should be recalculated should be marked with @samp{#}
or @samp{*}.
Org-Plot can produce 2D and 3D graphs of information stored in org tables
using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
-@uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To see
-this in action, ensure that you have both Gnuplot and Gnuplot mode installed
-on your system, then call @code{org-plot/gnuplot} on the following table.
+@uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
+that you have both Gnuplot and Gnuplot mode installed on your system, then
+call @code{org-plot/gnuplot} on the following table.
@example
@group
@item with
Specify a @code{with} option to be inserted for every col being plotted
-(e.g.@: @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
+(e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
Defaults to @code{lines}.
@item file
For Org files, if there is a @samp{<<target>>} at the cursor, the link points
to the target. Otherwise it points to the current headline, which will also
be the description@footnote{If the headline contains a timestamp, it will be
-removed from the link and result in a wrong link -- you should avoid putting
+removed from the link and result in a wrong link---you should avoid putting
timestamp in the headline.}.
-@vindex org-link-to-org-use-id
+@vindex org-id-link-to-org-use-id
@cindex property, CUSTOM_ID
@cindex property, ID
If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
will be stored. In addition or alternatively (depending on the value of
-@code{org-link-to-org-use-id}), a globally unique @code{ID} property will be
-created and/or used to construct a link. So using this command in Org
+@code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
+be created and/or used to construct a link@footnote{The library @code{org-id}
+must first be loaded, either through @code{org-customize} by enabling
+@code{id} in @code{org-modules} , or by adding @code{(require 'org-id)} in
+your @file{.emacs}.}. So using this command in Org
buffers will potentially create two links: a human-readable from the custom
ID, and one that is globally unique and works even if the entry is moved from
file to file. Later, when inserting the link, you need to decide which one
@cindex @code{inlineimages}, STARTUP keyword
@cindex @code{noinlineimages}, STARTUP keyword
Toggle the inline display of linked images. Normally this will only inline
-images that have no description part in the link, i.e.@: images that will also
+images that have no description part in the link, i.e., images that will also
be inlined during export. When called with a prefix argument, also display
images that do have a link description. You can ask for inline images to be
displayed at startup by configuring the variable
@noindent
In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
complete link abbreviations. You may also define a function
-@code{org-PREFIX-complete-link} that implements special (e.g.@: completion)
+@code{org-PREFIX-complete-link} that implements special (e.g., completion)
support for inserting such a link with @kbd{C-c C-l}. Such a function should
not accept any arguments, and return the full link with prefix.
@table @kbd
@orgcmd{C-c C-t,org-todo}
@cindex cycling, of TODO states
+@vindex org-use-fast-todo-selection
+
Rotate the TODO state of the current item among
@example
'--------------------------------'
@end example
-The same rotation can also be done ``remotely'' from the timeline and
-agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
+If TODO keywords have fast access keys (see @ref{Fast access to TODO
+states}), you will be prompted for a TODO keyword through the fast selection
+interface; this is the default behavior when
+@var{org-use-fast-todo-selection} is @code{non-nil}.
+
+The same rotation can also be done ``remotely'' from the timeline and agenda
+buffers with the @kbd{t} command key (@pxref{Agenda commands}).
@orgkey{C-u C-c C-t}
-Select a specific keyword using completion or (if it has been set up)
-the fast selection interface. For the latter, you need to assign keys
-to TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, for
-more information.
+When TODO keywords have no selection keys, select a specific keyword using
+completion; otherwise force cycling through TODO states with no prompt. When
+@var{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
+selection interface.
@kindex S-@key{right}
@kindex S-@key{left}
View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
entire buffer, but shows all TODO items (with not-DONE state) and the
headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
-/ T}), search for a specific TODO. You will be prompted for the keyword, and
+/ T}), search for a specific TODO@. You will be prompted for the keyword, and
you can also give a list of keywords like @code{KWD1|KWD2|...} to list
entries that match any one of these keywords. With a numeric prefix argument
N, show the tree for the Nth keyword in the variable
@vindex org-todo-keywords
By default, marked TODO entries have one of only two states: TODO and
-DONE. Org mode allows you to classify TODO items in more complex ways
+DONE@. Org mode allows you to classify TODO items in more complex ways
with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
special setup, the TODO keyword system can work differently in different
files.
state.
@cindex completion, of TODO keywords
With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
-to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may
+to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
also use a numeric prefix argument to quickly select a specific state. For
-example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
+example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
define many keywords, you can use in-buffer completion
(@pxref{Completion}) or even a special one-key selection scheme
In this case, different keywords do not indicate a sequence, but rather
different types. So the normal work flow would be to assign a task to a
-person, and later to mark it DONE. Org mode supports this style by adapting
+person, and later to mark it DONE@. Org mode supports this style by adapting
the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
@kbd{t} command in the timeline and agenda buffers.}. When used several
times in succession, it will still cycle through all names, in order to first
select the right type for a task. But when you return to the item after some
time and execute @kbd{C-c C-t} again, it will switch from any name directly
-to DONE. Use prefix arguments or completion to quickly select a specific
+to DONE@. Use prefix arguments or completion to quickly select a specific
name. You can also review the items of a specific TODO type in a sparse tree
by using a numeric prefix to @kbd{C-c / t}. For example, to see all things
Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items
@cindex property, ORDERED
The structure of Org files (hierarchy and lists) makes it easy to define TODO
dependencies. Usually, a parent TODO task should not be marked DONE until
-all subtasks (defined as children tasks) are marked as DONE. And sometimes
+all subtasks (defined as children tasks) are marked as DONE@. And sometimes
there is a logical sequence to a number of (sub)tasks, so that one task
cannot be acted upon before all siblings above it are done. If you customize
the variable @code{org-enforce-todo-dependencies}, Org will block entries
-from changing state to DONE while they have children that are not DONE.
+from changing state to DONE while they have children that are not DONE@.
Furthermore, if an entry has a property @code{ORDERED}, each of its children
-will be blocked until all earlier siblings are marked DONE. Here is an
+will be blocked until all earlier siblings are marked DONE@. Here is an
example:
@example
Org mode can automatically record a timestamp and possibly a note when
you mark a TODO item as DONE, or even each time you change the state of
-a TODO item. This system is highly configurable, settings can be on a
+a TODO item. This system is highly configurable; settings can be on a
per-keyword basis and can be localized to a file or even a subtree. For
information on how to clock working time for a task, see @ref{Clocking
work time}.
However, it will never prompt for two notes---if you have configured
both, the state change recording note will take precedence and cancel
the @samp{Closing Note}.}, and that a note is recorded when switching to
-WAIT or CANCELED. The setting for WAIT is even more special: the
+WAIT or CANCELED@. The setting for WAIT is even more special: the
@samp{!} after the slash means that in addition to the note taken when
entering the state, a timestamp should be recorded when @i{leaving} the
WAIT state, if and only if the @i{target} state does not configure
accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
it with the string @samp{[ ]}. This feature is similar to TODO items
(@pxref{TODO Items}), but is more lightweight. Checkboxes are not included
-into the global TODO list, so they are often great to split a task into a
+in the global TODO list, so they are often great to split a task into a
number of simple steps. Or you can use them in a shopping list. To toggle a
checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
@file{org-mouse.el}).
@orgcmd{C-c C-c,org-toggle-checkbox}
Toggle checkbox status or (with prefix arg) checkbox presence at point.
With a single prefix argument, add an empty checkbox or remove the current
-one@footnote{`C-u C-c C-c' on the @emph{first} item of a list with no checkbox
+one@footnote{@kbd{C-u C-c C-c} on the @emph{first} item of a list with no checkbox
will add checkboxes to the rest of the list.}. With a double prefix argument, set it to @samp{[-]}, which is
considered to be an intermediate state.
@orgcmd{C-c C-x C-b,org-toggle-checkbox}
@noindent
@vindex org-use-tag-inheritance
@vindex org-tags-exclude-from-inheritance
-To limit tag inheritance to specific tags, or to turn it off entirely, use
-the variables @code{org-use-tag-inheritance} and
-@code{org-tags-exclude-from-inheritance}.
+To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
+To turn it off entirely, use @code{org-use-tag-inheritance}.
@vindex org-tags-match-list-sublevels
When a headline matches during a tags search while tag inheritance is turned
match in a subtree, configure the variable
@code{org-tags-match-list-sublevels} (not recommended).
+@vindex org-agenda-use-tag-inheritance
+Tag inheritance is relevant when the agenda search tries to match a tag,
+either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
+types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
+have your tags correctly set in the agenda, so that tag filtering works fine,
+with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
+this: the default value includes all agenda types, but setting this to nil
+can really speed up agenda generation.
+
@node Setting tags, Tag searches, Tag inheritance, Tags
@section Setting tags
@cindex setting tags
To create sparse trees and special lists with selection based on properties,
the same commands are used as for tag searches (@pxref{Tag searches}).
@table @kbd
-@orgcmdkkc{C-c / m,C-c \,org-match-sparse-tree}
+@orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
Create a sparse tree with all matching entries. With a
@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
@orgcmd{C-c a m,org-tags-view}
The @code{est+} summary type requires further explanation. It is used for
combining estimates, expressed as low-high ranges. For example, instead
of estimating a particular task will take 5 days, you might estimate it as
-5-6 days if you're fairly confident you know how much work is required, or
-1-10 days if you don't really know what needs to be done. Both ranges
+5--6 days if you're fairly confident you know how much work is required, or
+1--10 days if you don't really know what needs to be done. Both ranges
average at 5.5 days, but the first represents a more predictable delivery.
When combining a set of such estimates, simply adding the lows and highs
estimated at 0.5 to 2 days of work. Straight addition produces an estimate
of 5 to 20 days, representing what to expect if everything goes either
extremely well or extremely poorly. In contrast, @code{est+} estimates the
-full job more realistically, at 10-15 days.
+full job more realistically, at 10--15 days.
Here is an example for a complete columns definition, along with allowed
values.
@noindent
The first column, @samp{%25ITEM}, means the first 25 characters of the
-item itself, i.e.@: of the headline. You probably always should start the
+item itself, i.e., of the headline. You probably always should start the
column definition with the @samp{ITEM} specifier. The other specifiers
create columns @samp{Owner} with a list of names as allowed values, for
@samp{Status} with four different possible values, and for a checkbox
@example
* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
- <%%(org-float t 4 2)>
+ <%%(diary-float t 4 2)>
@end example
@item Time/Date range
single plus or minus, the date is always relative to today. With a
double plus or minus, it is relative to the default date. If instead of
a single letter, you use the abbreviation of day name, the date will be
-the Nth such day, e.g.@:
+the Nth such day, e.g.:
@example
+0 @result{} today
You can specify a time range by giving start and end times or by giving a
start time and a duration (in HH:MM format). Use one or two dash(es) as the
separator in the former case and use '+' as the separator in the latter
-case, e.g.@:
+case, e.g.:
@example
11am-1:15pm @result{} 11:00-13:15
addition, the agenda for @emph{today} will carry a warning about the
approaching or missed deadline, starting
@code{org-deadline-warning-days} before the due date, and continuing
-until the entry is marked DONE. An example:
+until the entry is marked DONE@. An example:
@example
*** TODO write article about the Earth for the Guide
@vindex org-agenda-skip-scheduled-if-done
The headline will be listed under the given date@footnote{It will still
-be listed on that date after it has been marked DONE. If you don't like
+be listed on that date after it has been marked DONE@. If you don't like
this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
addition, a reminder that the scheduled date has passed will be present
-in the compilation for @emph{today}, until the entry is marked DONE, i.e.@:
+in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
the task will automatically be forwarded until completed.
@example
assumption that the timestamp represents the @i{nearest instance} of
the repeater. However, the use of diary sexp entries like
@c
-@code{<%%(org-float t 42)>}
+@code{<%%(diary-float t 42)>}
@c
in scheduling and deadline timestamps is limited. Org mode does not
know enough about the internals of each sexp function to issue early and
@end table
Note that @code{org-schedule} and @code{org-deadline} supports
-setting the date by indicating a relative time: e.g. +1d will set
+setting the date by indicating a relative time: e.g., +1d will set
the date to the next day after today, and --1w will set the date
to the previous week before any current timestamp.
* Capture:: Capturing new stuff
* Attachments:: Add files to tasks
* RSS Feeds:: Getting input from RSS feeds
-* Protocols:: External (e.g.@: Browser) access to Emacs and Org
+* Protocols:: External (e.g., Browser) access to Emacs and Org
* Refiling notes:: Moving a tree from one place to another
* Archiving:: What to do with finished projects
@end menu
@table @kbd
@orgcmd{C-c c,org-capture}
Call the command @code{org-capture}. Note that this keybinding is global and
-not active by default - you need to install it. If you have templates
+not active by default: you need to install it. If you have templates
@cindex date tree
defined @pxref{Capture templates}, it will offer these templates for
selection or use a new Org outline node as the default template. It will
@cindex Boolean logic, for tag/property searches
A search string can use Boolean operators @samp{&} for AND and @samp{|} for
-OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently
+OR@. @samp{&} binds more strongly than @samp{|}. Parentheses are currently
not implemented. Each element in the search is either a tag, a regular
expression matching tags, or an expression like @code{PROPERTY OPERATOR
VALUE} with a comparison operator, accessing a property value. Each element
entry. Or, the ``property'' @code{LEVEL} represents the level of an entry.
So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines
that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword
-DONE. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
+DONE@. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
The ITEM special property cannot currently be used in tags/property
searches@footnote{But @pxref{x-agenda-skip-entry-regexp,
assumed to be date/time specifications in the standard Org way, and the
comparison will be done accordingly. Special values that will be recognized
are @code{"<now>"} for now (including time), and @code{"<today>"}, and
-@code{"<tomorrow>"} for these days at 0:00 hours, i.e.@: without a time
+@code{"<tomorrow>"} for these days at 0:00 hours, i.e., without a time
specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
respectively, can be used.
connected with @samp{|}) with a @samp{/} and then specify a Boolean
expression just for TODO keywords. The syntax is then similar to that for
tags, but should be applied with care: for example, a positive selection on
-several TODO keywords cannot meaningfully be combined with boolean AND.
+several TODO keywords cannot meaningfully be combined with boolean AND@.
However, @emph{negative selection} combined with AND can be meaningful. To
make sure that only lines are checked that actually have any TODO keyword
(resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
month view, a year may be encoded in the prefix argument as well. For
example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
specification has only one or two digits, it will be mapped to the interval
-1938-2037. @kbd{v @key{SPC}} will reset to what is set in
+1938--2037. @kbd{v @key{SPC}} will reset to what is set in
@code{org-agenda-span}.
@c
@orgcmd{f,org-agenda-later}
covered by the current agenda view. The initial setting for this mode in new
agenda buffers can be set with the variable
@code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
-when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show
+when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
contributions from entries that are hidden by agenda filtering@footnote{Only
tags filtering will be respected here, effort filtering is ignored.}. See
also the variable @code{org-clock-report-include-clocking-task}.
@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
+or larger-or-equal than the selected value. If the digits 0--9 are not used
as fast access keys to tags, you can also simply press the index digit
directly without an operator. In this case, @kbd{<} will be assumed. For
application of the operator, entries without a defined effort will be treated
@tsubheading{Remote editing}
@cindex remote editing, from agenda
-@item 0-9
+@item 0--9
Digit argument.
@c
@cindex undoing remote-editing events
buffer).
@kindex C-c a C
@vindex org-agenda-custom-commands
+@cindex agenda views, main example
+@cindex tags, as an agenda view
+@cindex todo, as an agenda view
+@cindex tags-todo
+@cindex todo-tree
+@cindex occur-tree
+@cindex tags-tree
Custom commands are configured in the variable
@code{org-agenda-custom-commands}. You can customize this variable, for
Peter, or Kim) as additional tag to match.
@end table
+Note that the @code{*-tree} agenda views need to be called from an
+Org buffer as they operate on the current buffer only.
+
@node Block agenda, Setting Options, Storing searches, Custom agenda views
@subsection Block agenda
@cindex block agenda
@cindex exporting, not
@cindex #+BEGIN_COMMENT
-Lines starting with zero or more whitespace characters followed by @samp{#}
-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.
+Lines starting with zero or more whitespace characters followed by one
+@samp{#} and a whitespace are treated as comments and will never be exported.
+Also entire subtrees starting with the word @samp{COMMENT} will never be
+exported. Finally, regions surrounded by @samp{#+BEGIN_COMMENT}
+... @samp{#+END_COMMENT} will not be exported.
@table @kbd
@kindex C-c ;
numbered. If you use a @code{+n} switch, the numbering from the previous
numbered snippet will be continued in the current one. In literal examples,
Org will interpret strings like @samp{(ref:name)} as labels, and use them as
-targets for special hyperlinks like @code{[[(name)]]} (i.e.@: the reference name
+targets for special hyperlinks like @code{[[(name)]]} (i.e., the reference name
enclosed in single parenthesis). In HTML, hovering the mouse over such a
link will remote-highlight the corresponding code line, which is kind of
cool.
#+INCLUDE: "~/.emacs" src emacs-lisp
@end example
@noindent
-The optional second and third parameter are the markup (e.g.@: @samp{quote},
+The optional second and third parameter are the markup (e.g., @samp{quote},
@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
language for formatting the contents. The markup is optional; if it is not
given, the text will be assumed to be in Org mode format and will be
#+AUTHOR: the author (default taken from @code{user-full-name})
#+DATE: a date, an Org timestamp@footnote{@code{org-export-date-timestamp-format} defines how this timestamp will be exported.}, or a format string for @code{format-time-string}
#+EMAIL: his/her email address (default from @code{user-mail-address})
-#+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag
-#+KEYWORDS: the page keywords, e.g.@: for the XHTML meta tag
-#+LANGUAGE: language for HTML, e.g.@: @samp{en} (@code{org-export-default-language})
+#+DESCRIPTION: the page description, e.g., for the XHTML meta tag
+#+KEYWORDS: the page keywords, e.g., for the XHTML meta tag
+#+LANGUAGE: language for HTML, e.g., @samp{en} (@code{org-export-default-language})
#+TEXT: Some descriptive text to be inserted at the beginning.
#+TEXT: Several lines may be given.
#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
-#+BIND: lisp-var lisp-val, e.g.@:: @code{org-export-latex-low-levels itemize}
+#+BIND: lisp-var lisp-val, e.g., @code{org-export-latex-low-levels itemize}
@r{You need to confirm using these, or configure @code{org-export-allow-BIND}}
#+LINK_UP: the ``up'' link of an exported page
#+LINK_HOME: the ``home'' link of an exported page
the variable @code{org-export-run-in-background}.}.
@orgcmd{C-c C-e v,org-export-visible}
Like @kbd{C-c C-e}, but only export the text that is currently visible
-(i.e.@: not hidden by outline visibility).
+(i.e., not hidden by outline visibility).
@orgcmd{C-u C-u C-c C-e,org-export}
@vindex org-export-run-in-background
Call the exporter, but reverse the setting of
-@code{org-export-run-in-background}, i.e.@: request background processing if
+@code{org-export-run-in-background}, i.e., request background processing if
not set, or force processing in the current Emacs process if set.
@end table
@cindex UTF-8 export
ASCII export produces a simple and very readable version of an Org mode
-file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file
+file, containing only plain ASCII@. Latin-1 and UTF-8 export augment the file
with special characters and symbols available in these encodings.
@cindex region, active
@cindex links, in HTML export
@cindex internal links, in HTML export
@cindex external links, in HTML export
-Internal links (@pxref{Internal links}) will continue to work in HTML. This
+Internal links (@pxref{Internal links}) will continue to work in HTML@. This
includes automatic links created by radio targets (@pxref{Radio
targets}). Links to external files will still work if the target file is on
the same @i{relative} path as the published Org file. Links to other
script is available at @url{http://orgmode.org/org-info.js} and you can find
the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}.
We host the script at our site, but if you use it a lot, you might
-not want to be dependent on @url{orgmode.org} and prefer to install a local
+not want to be dependent on @url{http://orgmode.org} and prefer to install a local
copy on your own web server.
To use the script, you need to make sure that the @file{org-jsinfo.el} module
@cindex DocBook recursive sections
DocBook exporter exports Org files as articles using the @code{article}
-element in DocBook. Recursive sections, i.e.@: @code{section} elements, are
+element in DocBook. Recursive sections, i.e., @code{section} elements, are
used in exported articles. Top level headlines in Org files are exported as
top level sections, and lower level headlines are exported as nested
sections. The entire structure of Org files will be exported completely, no
LibreOffice. The latter method is suitable for expert and non-expert
users alike, and is described here.
-@subsubsection Applying custom styles - the easy way
+@subsubsection Applying custom styles: the easy way
@enumerate
@item
@item
Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
-to locate the target styles - these typically have the @samp{Org} prefix -
-and modify those to your taste. Save the modified file either as an
+to locate the target styles---these typically have the @samp{Org} prefix---and
+modify those to your taste. Save the modified file either as an
OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file.
@item
@cindex tables, in DocBook export
Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el}
-tables is supported. However, export of complex @file{table.el} tables -
-tables that have column or row spans - is not supported. Such tables are
+tables is supported. However, export of complex @file{table.el} tables---tables
+that have column or row spans---is not supported. Such tables are
stripped from the exported document.
By default, a table is exported with top and bottom frames and with rules
@cindex #+ATTR_ODT
You can control the manner in which an image is anchored by setting the
@code{:anchor} property of it's @code{#+ATTR_ODT} line. You can specify one
-of the the following three values for the @code{:anchor} property -
+of the the following three values for the @code{:anchor} property:
@samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}.
To create an image that is anchored to a page, do the following:
@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export
@subsection Labels and captions in ODT export
-You can label and caption various category of objects - an inline image, a
-table, a @LaTeX{} fragment or a Math formula - using @code{#+LABEL} and
+You can label and caption various category of objects---an inline image, a
+table, a @LaTeX{} fragment or a Math formula---using @code{#+LABEL} and
@code{#+CAPTION} lines. @xref{Images and tables}. ODT exporter enumerates
each labeled or captioned object of a given category separately. As a
result, each such object is assigned a sequence number based on order of it's
@item
It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
-elements that control how various entities - tables, images, equations etc -
-are numbered.
+elements that control how various entities---tables, images, equations,
+etc.---are numbered.
@end enumerate
@end itemize
-@subsubheading Custom table styles - an illustration
+@subsubheading Custom table styles: an illustration
To have a quick preview of this feature, install the below setting and export
the table that follows.
(@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need
additional templates you have to define these styles yourselves.
-@subsubheading Custom table styles - the nitty-gritty
+@subsubheading Custom table styles: the nitty-gritty
To use this feature proceed as follows:
@enumerate
@subsection Export of properties
-The exporter also takes TODO state information into consideration, i.e.@: if a
+The exporter also takes TODO state information into consideration, i.e., if a
task is marked as done it will have the corresponding attribute in
TaskJuggler (@samp{complete 100}). Also it will export any property on a task
resource or resource node which is known to TaskJuggler, such as
@samp{efficiency}, @samp{journalentry}, @samp{rate} for resources or
@samp{account}, @samp{start}, @samp{note}, @samp{duration}, @samp{end},
@samp{journalentry}, @samp{milestone}, @samp{reference}, @samp{responsible},
-@samp{scheduling}, etc for tasks.
+@samp{scheduling}, etc.@: for tasks.
@subsection Dependencies
@subsection Reports
@vindex org-export-taskjuggler-default-reports
-TaskJuggler can produce many kinds of reports (e.g.@: gantt chart, resource
+TaskJuggler can produce many kinds of reports (e.g., gantt chart, resource
allocation, etc). The user defines what kind of reports should be generated
for a project in the TaskJuggler file. The exporter will automatically insert
some default reports in the file. These defaults are defined in
in the standard iCalendar format. If you also want to have TODO entries
included in the export, configure the variable
@code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT,
-and TODO items as VTODO. It will also create events from deadlines that are
+and TODO items as VTODO@. It will also create events from deadlines that are
in non-TODO items. Deadlines and scheduling dates in TODO items will be used
to set the start and due dates for the TODO entry@footnote{See the variables
@code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}.
@lisp
("project-name" :property value :property value ...)
- @r{i.e.@: a well-formed property list with alternating keys and values}
+ @r{i.e., a well-formed property list with alternating keys and values}
@r{or}
("project-name" :components ("project-name" "project-name" ...))
@samp{file:foo.org.} (@pxref{Hyperlinks}). When published, this link
becomes a link to @file{foo.html}. In this way, you can interlink the
pages of your "org web" project and the links will work as expected when
-you publish them to HTML. If you also publish the Org source file and want
+you publish them to HTML@. If you also publish the Org source file and want
to link to that, use an @code{http:} link instead of a @code{file:} link,
because @code{file:} links are converted to link to the corresponding
@file{html} file.
@cindex source code, working with
Source code can be included in Org mode documents using a @samp{src} block,
-e.g.@:
+e.g.:
@example
#+BEGIN_SRC emacs-lisp
It is possible to export the @emph{code} of code blocks, the @emph{results}
of code block evaluation, @emph{both} the code and the results of code block
evaluation, or @emph{none}. For most languages, the default exports code.
-However, for some languages (e.g.@: @code{ditaa}) the default exports the
+However, for some languages (e.g., @code{ditaa}) the default exports the
results of code block evaluation. For information on exporting code block
bodies, see @ref{Literal examples}.
@lisp
(setq org-babel-default-header-args
-(cons '(:noweb . "yes")
-(assq-delete-all :noweb org-babel-default-header-args)))
+ (cons '(:noweb . "yes")
+ (assq-delete-all :noweb org-babel-default-header-args)))
@end lisp
@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments
@example
* outline header
-:PROPERTIES:
-:cache: yes
-:END:
+ :PROPERTIES:
+ :cache: yes
+ :END:
@end example
@kindex C-c C-x p
@cindex #+HEADERS:
Multi-line header arguments on an un-named code block:
+
@example
#+HEADERS: :var data1=1
#+BEGIN_SRC emacs-lisp :var data2=2
@end example
Multi-line header arguments on a named code block:
+
@example
#+NAME: named-block
#+HEADER: :var data=2
The following will apply the @code{:exports results} header argument to the
evaluation of the @code{#+CALL:} line.
+
@example
#+CALL: factorial(n=5) :exports results
@end example
The following will apply the @code{:session special} header argument to the
evaluation of the @code{factorial} code block.
+
@example
#+CALL: factorial[:session special](n=5)
@end example
@item table
an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line
+
@example
#+TBLNAME: example-table
| 1 |
the value of the Emacs variable @code{default-directory}.
When using @code{:dir}, you should supply a relative path for file output
-(e.g.@: @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
+(e.g., @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
case that path will be interpreted relative to the default directory.
In other words, if you want your plot to go into a folder called @file{Work}
-- <<example>>
@end example
-
expands to:
@example
@item @code{yes}
Column names are removed and reapplied as with @code{nil} even if the table
-does not ``look like'' it has column names (i.e.@: the second row is not an
+does not ``look like'' it has column names (i.e., the second row is not an
hline)
@end itemize
@subsubsection @code{:shebang}
Setting the @code{:shebang} header argument to a string value
-(e.g.@: @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
+(e.g., @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
first line of any tangled file holding the code block, and the file
permissions of the tangled file are set to make it executable.
@end example
In non-session mode, the `2' is not printed and does not appear.
+
@example
#+BEGIN_SRC python :results output :session
print "hello"
will insert example settings for this keyword.
@item
In the line after @samp{#+STARTUP: }, complete startup keywords,
-i.e.@: valid keys for this line.
+i.e., valid keys for this line.
@item
Elsewhere, complete dictionary words using Ispell.
@end itemize
@vindex org-speed-commands-user
Single keys can be made to execute commands when the cursor is at the
-beginning of a headline, i.e.@: before the first star. Configure the variable
+beginning of a headline, i.e., before the first star. Configure the variable
@code{org-use-speed-commands} to activate this feature. There is a
pre-defined list of commands, and you can add more such commands using the
variable @code{org-speed-commands-user}. Speed keys do not only speed up
For example, here is how to execute "ditaa" code (which is considered safe)
without asking:
+
@example
(defun my-org-confirm-babel-evaluate (lang body)
(not (string= lang "ditaa"))) ; don't ask for ditaa
@vindex org-lowest-priority
@vindex org-default-priority
This line sets the limits and the default for the priorities. All three
-must be either letters A-Z or numbers 0-9. The highest priority must
+must be either letters A--Z or numbers 0--9. The highest priority must
have a lower ASCII number than the lowest priority.
@item #+PROPERTY: Property_Name Value
This line sets a default inheritance value for entries in the current
@item #+SETUPFILE: file
This line defines a file that holds more in-buffer setup. Normally this is
entirely ignored. Only when the buffer is parsed for option-setting lines
-(i.e.@: when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
+(i.e., when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
settings line, or when exporting), then the contents of this file are parsed
as if they had been included in the buffer. In particular, the file can be
any other Org mode file with internal setup. You can visit the file the
stars but the last one are made invisible using the @code{org-hide}
face@footnote{Turning on @code{org-indent-mode} sets
@code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
-@code{nil}.} - see below under @samp{2.} for more information on how this
+@code{nil}.}; see below under @samp{2.} for more information on how this
works. You can turn on @code{org-indent-mode} for all files by customizing
the variable @code{org-startup-indented}, or you can turn it on for
individual files using
Things become cleaner still if you skip all the even levels and use only odd
levels 1, 3, 5..., effectively adding two stars to go from one outline level
to the next@footnote{When you need to specify a level for a property search
-or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}. In this
+or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}. In this
way we get the outline view shown at the beginning of this section. In order
to make the structure editing and export commands handle this convention
correctly, configure the variable @code{org-odd-levels-only}, or set this on
constants in the variable @code{org-table-formula-constants}, install
the @file{constants} package which defines a large number of constants
and units, and lets you use unit prefixes like @samp{M} for
-@samp{Mega}, etc@. You will need version 2.0 of this package, available
+@samp{Mega}, etc. You will need version 2.0 of this package, available
at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for
the function @code{constants-get}, which has to be autoloaded in your
setup. See the installation instructions in the file
@lisp
(defun yas/org-very-safe-expand ()
- (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
+ (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
@end lisp
Then, tell Org mode what to do with the new function:
@lisp
(add-hook 'org-mode-hook
(lambda ()
- (make-variable-buffer-local 'yas/trigger-key)
- (setq yas/trigger-key [tab])
- (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
- (define-key yas/keymap [tab] 'yas/next-field)))
+ (make-variable-buffer-local 'yas/trigger-key)
+ (setq yas/trigger-key [tab])
+ (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
+ (define-key yas/keymap [tab] 'yas/next-field)))
@end lisp
@item @file{windmove.el} by Hovav Shacham
buffer with @kbd{C-c C-l}.
When it makes sense for your new link type, you may also define a function
-@code{org-PREFIX-complete-link} that implements special (e.g.@: completion)
+@code{org-PREFIX-complete-link} that implements special (e.g., completion)
support for inserting such a link with @kbd{C-c C-l}. Such a function should
not accept any arguments, and return the full link with prefix.
table inserted between the two marker lines.
Now let's assume you want to make the table header by hand, because you
-want to control how columns are aligned, etc@. In this case we make sure
+want to control how columns are aligned, etc. In this case we make sure
that the table translator skips the first 2 lines of the source
-table, and tell the command to work as a @i{splice}, i.e.@: to not produce
+table, and tell the command to work as a @i{splice}, i.e., to not produce
header and footer commands of the target table:
@example
As you can see, the properties passed into the function (variable
@var{PARAMS}) are combined with the ones newly defined in the function
-(variable @var{PARAMS2}). The ones passed into the function (i.e.@: the
+(variable @var{PARAMS2}). The ones passed into the function (i.e., the
ones set by the @samp{ORGTBL SEND} line) take precedence. So if you
would like to use the @LaTeX{} translator, but wanted the line endings to
be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
\end@{comment@}
@end example
-Pressing `C-c C-c' on @code{a new house} and will insert the converted
+Pressing @kbd{C-c C-c} on @code{a new house} and will insert the converted
@LaTeX{} list between the two marker lines.
@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
@lisp
(defun org-dblock-write:block-update-time (params)
- (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
- (insert "Last block update at: "
- (format-time-string fmt (current-time)))))
+ (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
+ (insert "Last block update at: "
+ (format-time-string fmt (current-time)))))
@end lisp
If you want to make sure that all dynamic blocks are always up-to-date,
Let's say you want to produce a list of projects that contain a WAITING
tag anywhere in the project tree. Let's further assume that you have
marked all tree headings that define a project with the TODO keyword
-PROJECT. In this case you would run a TODO search for the keyword
+PROJECT@. In this case you would run a TODO search for the keyword
PROJECT, but skip the match unless there is a WAITING tag anywhere in
the subtree belonging to the project line.
directly to a printer, or it can be read by a program that does further
processing of the data. The first of these commands is the function
@code{org-batch-agenda}, that produces an agenda view and sends it as
-ASCII text to STDOUT. The command takes a single string as parameter.
+ASCII text to STDOUT@. The command takes a single string as parameter.
If the string has length 1, it is used as a key to one of the commands
you have configured in @code{org-agenda-custom-commands}, basically any
key you can use after @kbd{C-c a}. For example, to directly print the
@vindex org-use-property-inheritance
@findex org-insert-property-drawer
@defun org-entry-get pom property &optional inherit
-Get value of PROPERTY for entry at point-or-marker POM. By default,
+Get value of PROPERTY for entry at point-or-marker POM@. By default,
this only looks at properties defined locally in the entry. If INHERIT
is non-nil and the entry does not have the property, then also check
higher levels of the hierarchy. If INHERIT is the symbol
@end defun
@defun org-entry-put-multivalued-property pom property &rest values
-Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a list of
+Set PROPERTY at point-or-marker POM to VALUES@. VALUES should be a list of
strings. They will be concatenated, with spaces as separators.
@end defun
moved to the end of the line (presumably of the headline of the
processed entry) and search continues from there. Under some
circumstances, this may not produce the wanted results. For example,
-if you have removed (e.g.@: archived) the current (sub)tree it could
+if you have removed (e.g., archived) the current (sub)tree it could
mean that the next entry will be skipped entirely. In such cases, you
can specify the position from where search should continue by making
FUNC set the variable `org-map-continue-from' to the desired buffer
@lisp
(org-map-entries
- '(org-todo "UPCOMING")
- "+TOMORROW" 'file 'archive 'comment)
+ '(org-todo "UPCOMING")
+ "+TOMORROW" 'file 'archive 'comment)
@end lisp
The following example counts the number of entries with TODO keyword
all agenda files (as listed in @code{org-agenda-files}), but additional files
can be included by customizing @code{org-mobile-files}. File names will be
staged with paths relative to @code{org-directory}, so all files should be
-inside this directory. The push operation also creates a special Org file
-@file{agendas.org} with all custom agenda view defined by the
-user@footnote{While creating the agendas, Org mode will force ID properties
-on all referenced entries, so that these entries can be uniquely identified
-if @i{MobileOrg} flags them for further action. If you do not want to get
-these properties in so many entries, you can set the variable
-@code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then
-rely on outline paths, in the hope that these will be unique enough.}.
+inside this directory@footnote{Symbolic links in @code{org-directory} need to
+have the same name than their targets.}.
+
+The push operation also creates a special Org file @file{agendas.org} with
+all custom agenda view defined by the user@footnote{While creating the
+agendas, Org mode will force ID properties on all referenced entries, so that
+these entries can be uniquely identified if @i{MobileOrg} flags them for
+further action. If you do not want to get these properties in so many
+entries, you can set the variable @code{org-mobile-force-id-on-agenda-items}
+to @code{nil}. Org mode will then rely on outline paths, in the hope that
+these will be unique enough.}.
+
Finally, Org writes the file @file{index.org}, containing links to all other
files. @i{MobileOrg} first reads this file from the server, and then
downloads all agendas and Org files listed in it. To speed up the download,
agenda files. If you later use @kbd{C-c a ?} to regenerate the view, only
the current agenda files will be searched.} using @kbd{C-c a ?}.
-@node History and Acknowledgments, Main Index, MobileOrg, Top
+@node History and Acknowledgments, GNU Free Documentation License, MobileOrg, Top
@appendix History and acknowledgments
@cindex acknowledgments
@cindex history
opened the doors for many new ideas and features.
@item Jambunathan K
-Jambunathan contributed the ODT exporter, definitly a killer feature of
+Jambunathan contributed the ODT exporter, definitely a killer feature of
Org mode. He also contributed the new HTML exporter, which is another core
feature of Org. Here too, I knew I could rely on him to fix bugs in these
areas and to patiently explain the users what was the problems and solutions.
@item Achim Gratz
Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
into a flexible and conceptually clean process. He patiently coped with the
-many hicups that such a change can create for users.
+many hiccups that such a change can create for users.
@item Nick Dokos
The Org mode mailing list would not be such a nice place without Nick, who
@end table
I received support from so many users that it is clearly impossible to be
-fair when shortlisting a few of them -- but Org's history would not be
+fair when shortlisting a few of them, but Org's history would not be
complete if the ones above were not mentioned in this manual.
@section List of contributions
@end itemize
-@node Main Index, Key Index, History and Acknowledgments, Top
+@node GNU Free Documentation License, Main Index, History and Acknowledgments, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@node Main Index, Key Index, GNU Free Documentation License, Top
@unnumbered Concept index
@printindex cp
HCoop / bpt / emacs.git / blobdiff