19580 lines
711 KiB
Org Mode
19580 lines
711 KiB
Org Mode
#+TITLE: Org Mode
|
|
#+AUTHOR: Carsten Dominik
|
|
#+EMAIL: tsd@tsdye.com
|
|
#+DATE: {{{modification-time}}}
|
|
#+SUBTITLE: Release {{{version}}}
|
|
#+SUBAUTHOR: with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K.
|
|
|
|
#+LANGUAGE: en
|
|
#+OPTIONS: H:4 num:t toc:t \n:nil ::t |:t ^:nil -:t f:t *:t <:t
|
|
#+OPTIONS: d:nil todo:nil pri:nil tags:not-in-toc
|
|
#+SELECT_TAGS: export
|
|
#+EXCLUDE_TAGS: noexport
|
|
|
|
#+TEXINFO_DIR_CATEGORY: Emacs editing modes
|
|
#+TEXINFO_DIR_TITLE: Org Mode: (org)
|
|
#+TEXINFO_DIR_DESC: Outline-based notes management and organizer
|
|
|
|
# Use proper quote and backtick for code sections in PDF output
|
|
# Cf. Texinfo manual 14.2
|
|
#+TEXINFO_HEADER: @set txicodequoteundirected
|
|
#+TEXINFO_HEADER: @set txicodequotebacktick
|
|
|
|
# Contact Info
|
|
#+TEXINFO_HEADER: @set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
|
|
#+TEXINFO_HEADER: @set MAINTAINER Carsten Dominik
|
|
#+TEXINFO_HEADER: @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
|
|
#+TEXINFO_HEADER: @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
|
|
|
|
#+STARTUP: overview
|
|
#+TODO: FIXME | FIXED
|
|
|
|
* Introduction
|
|
:PROPERTIES:
|
|
:TITLE: Introduction
|
|
:DESCRIPTION: Getting started
|
|
:END:
|
|
#+cindex: introduction
|
|
|
|
** Summary
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Brief summary of what Org-mode does
|
|
:END:
|
|
#+cindex: summary
|
|
|
|
Org is a mode for keeping notes, maintaining TODO lists, and doing
|
|
project planning with a fast and effective plain-text system.
|
|
|
|
Org develops organizational tasks around NOTES files that contain
|
|
lists or information about projects as plain text. Org is implemented
|
|
on top of Outline mode, which makes it possible to keep the content of
|
|
large files well structured. Visibility cycling and structure editing
|
|
help to work with the tree. Tables are easily created with a built-in
|
|
table editor. Org supports TODO items, deadlines, timestamps, and
|
|
scheduling. It dynamically compiles entries into an agenda that
|
|
utilizes and smoothly integrates much of the Emacs calendar and diary.
|
|
Plain text URL-like links connect to websites, emails, Usenet
|
|
messages, BBDB entries, and any files related to the projects. For
|
|
printing and sharing of notes, an Org file can be exported as a
|
|
structured ASCII file, as HTML, or as an iCalendar file.[fn:1] It can
|
|
also serve as a publishing tool for a set of linked web pages.
|
|
|
|
As a project planning environment, Org works by adding metadata to
|
|
outline nodes. Based on this data, specific entries can be extracted
|
|
in queries and create dynamic /agenda views/.
|
|
|
|
Org mode contains the Org Babel environment which allows you to work
|
|
with embedded source code blocks in a file, to facilitate code
|
|
evaluation, documentation, and literate programming techniques.
|
|
|
|
Org's automatic, context-sensitive table editor with spreadsheet
|
|
capabilities can be integrated into any major mode by activating the
|
|
minor Orgtbl mode. Using a translation step, it can be used to
|
|
maintain tables in arbitrary file types, for example in LaTeX. The
|
|
structure editing and list creation capabilities can be used outside
|
|
Org with the minor Orgstruct mode.
|
|
|
|
Org keeps simple things simple. When first fired up, it should feel
|
|
like a straightforward, easy to use outliner. Complexity is not
|
|
imposed, but a large amount of functionality is available when you
|
|
need it. Org is a toolbox and can be used in different ways and for
|
|
different ends, for example:
|
|
|
|
- an outline extension with visibility cycling and structure editing
|
|
- an ASCII system and table editor for taking structured notes
|
|
- a TODO list editor
|
|
- a full agenda and planner with deadlines and work scheduling
|
|
#+pindex: GTD, Getting Things Done
|
|
- an environment in which to implement David Allen's GTD system
|
|
- a simple hypertext system, with HTML and LaTeX export
|
|
- a publishing tool to create a set of interlinked web pages
|
|
- an environment for literate programming
|
|
|
|
#+cindex: FAQ
|
|
|
|
There is a [[http://orgmode.org][website for Org]] that provides links to the newest version
|
|
of Org, as well as additional information, frequently asked questions
|
|
(FAQ), links to tutorials, etc.
|
|
|
|
#+cindex: print edition
|
|
|
|
Version 7.3 of this manual is available as a [[http://www.network-theory.co.uk/org/manual/][paperback book from
|
|
Network Theory Ltd.]]
|
|
|
|
{{{page}}}
|
|
|
|
** Installation
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to install a downloaded version of Org-mode
|
|
:END:
|
|
|
|
#+cindex: installation
|
|
#+cindex: XEmacs
|
|
*Important:* If you have the version of Org that comes with Emacs or
|
|
as a XEmacs package, please skip this section and go directly to
|
|
[[Activation]]. If you downloaded Org as an ELPA package, please read the
|
|
instructions on the [[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)}}}.[fn:2]
|
|
|
|
Installation of Org mode uses a build system, which is described in more
|
|
detail on [[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:
|
|
|
|
- Unpack the distribution archive
|
|
- Change into (~cd~) the Org directory
|
|
- Run ~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
|
|
|
|
- Run ~make config~ again to check the configuration
|
|
- Run ~make install~ or ~sudo make install~ to build and install Org
|
|
mode on your system
|
|
|
|
If you use a cloned Git repository, then the procedure is slightly
|
|
different. The following description assumes that you are using the
|
|
~master~ branch.[fn:3] You could also use the ~maint~ branch instead,
|
|
where the release versions are published, just replace ~master~ with
|
|
~maint~ in the description below.
|
|
|
|
- Change into (~cd~) the Org repository
|
|
- Run ~git checkout master~ to switch to the ~master~ branch of the
|
|
Org repository
|
|
- Run ~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
|
|
|
|
- Run ~make config~ to check the configuration
|
|
- Optionally run ~make test~ to build Org mode and then run the full
|
|
test suite
|
|
- Run ~make update2~ or ~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
|
|
|
|
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:
|
|
|
|
- Change into (~cd~) the Org repository
|
|
- Run ~git checkout master~ to switch to the ~master~ branch of the
|
|
Org repository
|
|
- Run ~make compile~
|
|
|
|
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 ~make uncompiled~.
|
|
|
|
Then add the following line to {{{file(.emacs)}}}:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(add-to-list 'load-path "~/path/to/orgdir/lisp")
|
|
#+end_src
|
|
|
|
{{{noindent}}}
|
|
If you plan to use code files from the {{{file(contrib)}}} subdirectory without
|
|
compiling them, do a similar step for this directory:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
|
|
#+end_src
|
|
|
|
If you want to include those files with the build and install, please
|
|
customize the variable ~ORG_ADD_CONTRIB~ instead in your
|
|
~local.mk~ file. For more details please see this
|
|
[[http://orgmode.org/worg/dev/org-build-system.html#sec-4-1-2][description on Worg]].
|
|
|
|
Installing Info files is system dependent, because of differences in
|
|
the {{{file(install-info)}}} program. The Info documentation is
|
|
installed together with the rest of Org mode. If you don't install Org
|
|
mode, it is possible to install the Info documentation separately if you
|
|
have install-info on your system.[fn:4]
|
|
|
|
The command to do this is:
|
|
|
|
#+begin_example
|
|
make install-info
|
|
#+end_example
|
|
|
|
Do not forget to activate Org as described in the following section.
|
|
{{{page}}}
|
|
|
|
** Activation
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to activate Org-mode for certain buffers
|
|
:END:
|
|
#+cindex: activation
|
|
#+cindex: autoload
|
|
#+cindex: ELPA
|
|
#+cindex: global key bindings
|
|
#+cindex: key bindings, global
|
|
#+findex: org-agenda
|
|
#+findex: org-capture
|
|
#+findex: org-store-link
|
|
#+findex: org-iswitchb
|
|
|
|
Since Emacs 22.2, files with the {{{file(.org)}}} extension use Org mode by
|
|
default. If you are using an earlier version of Emacs, add this line to your
|
|
{{{file(.emacs)}}} file:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
|
|
#+end_src
|
|
|
|
Org mode buffers need font-lock to be turned on - this is the default in
|
|
Emacs.[fn:5]
|
|
|
|
There are compatibility issues between Org mode and some other Elisp
|
|
packages, please take the time to check the list (see [[Conflicts]]).
|
|
|
|
The four Org commands {{{command(org-store-link)}}},
|
|
{{{command(org-capture)}}}, {{{command(org-agenda)}}}, and
|
|
{{{command(org-iswitchb)}}} should be accessible through global keys
|
|
(i.e., anywhere in Emacs, not just in Org buffers). Here are
|
|
suggested bindings for these keys, please modify the keys to your own
|
|
liking.
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(global-set-key "\C-cl" 'org-store-link)
|
|
(global-set-key "\C-cc" 'org-capture)
|
|
(global-set-key "\C-ca" 'org-agenda)
|
|
(global-set-key "\C-cb" 'org-iswitchb)
|
|
#+end_src
|
|
|
|
#+cindex: Org mode, turning on
|
|
With this setup, all files with extension {{{samp(.org)}}} will be put
|
|
into Org mode. As an alternative, make the first line of a file look
|
|
like this:
|
|
|
|
#+begin_example
|
|
MY PROJECTS -*- mode: org; -*-
|
|
#+end_example
|
|
|
|
#+vindex: org-insert-mode-line-in-empty-file
|
|
{{{noindent}}}
|
|
which will select Org mode for this buffer no matter what the file's
|
|
name is. See also the variable
|
|
~org-insert-mode-line-in-empty-file~.
|
|
|
|
Many commands in Org work on the region if the region is /active/. To
|
|
make use of this, you need to have ~transient-mark-mode~
|
|
(~zmacs-regions~ in XEmacs) turned on. In Emacs 23 this is the
|
|
default, in Emacs 22 you need to do this yourself with
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(transient-mark-mode 1)
|
|
#+end_src
|
|
|
|
{{{noindent}}} If you do not like ~transient-mark-mode~, you can
|
|
create an active region by using the mouse to select a region, or
|
|
pressing {{{kbdkey(C-,SPC)}}} twice before moving the cursor.
|
|
|
|
** Feedback
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Bug reports, ideas, patches, etc.
|
|
:END:
|
|
#+cindex: feedback
|
|
#+cindex: bug reports
|
|
#+cindex: maintainer
|
|
#+cindex: author
|
|
|
|
If you find problems with Org, or if you have questions, remarks, or
|
|
ideas about it, please mail to the Org mailing list
|
|
[[mailto:emacs-orgmode@gnu.org]]. If you are not a member of
|
|
the mailing list, your mail will be passed to the list after a
|
|
moderator has approved it.[fn:6]
|
|
|
|
For bug reports, please first try to reproduce the bug with the latest
|
|
version of Org available---if you are running an outdated version, it
|
|
is quite possible that the bug has been fixed already. If the bug
|
|
persists, prepare a report and provide as much information as
|
|
possible, including the version information of Emacs ({{{kbdspckey(M-x
|
|
emacs-version,RET)}}}) and Org ({{{kbdspckey(M-x org-version,RET)}}}),
|
|
as well as the Org related setup in {{{file(.emacs)}}}. The easiest
|
|
way to do this is to use the command {{{kbd(M-x
|
|
org-submit-bug-report)}}}, which will put all this information into an
|
|
Emacs mail buffer so that you only need to add your description. If
|
|
you are not sending the Email from within Emacs, please copy and paste
|
|
the content into your Email program.
|
|
|
|
Sometimes you might face a problem due to an error in your Emacs or
|
|
Org mode setup. Before reporting a bug, it is very helpful to start
|
|
Emacs with minimal customizations and reproduce the problem. Doing so
|
|
often helps you determine if the problem is with your customization or
|
|
with Org mode itself. You can start a typical minimal session with a
|
|
command like the example below.
|
|
|
|
#+begin_src sh :exports code
|
|
$ emacs -Q -l /path/to/minimal-org.el
|
|
#+end_src
|
|
|
|
However if you are using Org mode distributed with Emacs, a minimal
|
|
setup is not necessary. In that case it is sufficient to start Emacs
|
|
as ~emacs -Q~. The ~minimal-org.el~ setup
|
|
file can have contents as shown below.
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
;;; Minimal setup to load latest `org-mode'
|
|
|
|
;; activate debugging
|
|
(setq debug-on-error t
|
|
debug-on-signal nil
|
|
debug-on-quit nil)
|
|
|
|
;; add latest org-mode to load path
|
|
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
|
|
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
|
|
#+end_src
|
|
|
|
If an error occurs, a backtrace can be very useful (see [[How to
|
|
create a useful backtrace]]). Often a small example file helps, along
|
|
with clear information about:
|
|
|
|
1. What exactly did you do?
|
|
2. What did you expect to happen?
|
|
3. What happened instead?
|
|
|
|
{{{noindent}}} Thank you for helping to improve this program.
|
|
|
|
** How to create a useful backtrace
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The best way to report an error
|
|
:END:
|
|
|
|
#+cindex: backtrace of an error
|
|
|
|
If working with Org produces an error with a message you don't
|
|
understand, you may have hit a bug. The best way to report this is by
|
|
providing, in addition to what was mentioned above, a /backtrace/.
|
|
This is information from the built-in debugger about where and how the
|
|
error occurred. Here is how to produce a useful backtrace:
|
|
|
|
1. Reload uncompiled versions of all Org mode Lisp files. The
|
|
backtrace contains much more information if it is produced with
|
|
uncompiled code. To do this, use
|
|
{{{kbdspckey(C-u M-x org-reload,RET)}}} or select ~Org -> Refresh/Reload -> Reload Org uncompiled~ from the menu.
|
|
|
|
2. Go to the ~Options~ menu and select ~Enter Debugger on Error~
|
|
(XEmacs has this option in the ~Troubleshooting~ sub-menu).
|
|
|
|
3. Do whatever you have to do to hit the error. Don't forget to
|
|
document the steps you take.
|
|
|
|
4. When you hit the error, a {{{file(*Backtrace*)}}} buffer will
|
|
appear on the screen. Save this buffer to a file (for example
|
|
using {{{kbd(C-x C-w)}}}) and attach it to your bug report.
|
|
|
|
** Conventions
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Typesetting conventions in the manual
|
|
:END:
|
|
|
|
Conventions for typesetting keywords, keybindings, and commands in
|
|
this manual are described.
|
|
|
|
*** Three types of keywords
|
|
:PROPERTIES:
|
|
:DESCRIPTION: TODO, tags, and properties
|
|
:END:
|
|
|
|
Org mainly uses three types of keywords: TODO keywords, tags and property
|
|
names. In this manual we use the following conventions:
|
|
|
|
- TODO, WAITING :: TODO keywords are written with all capitals, even if they
|
|
are user-defined.
|
|
- boss, ARCHIVE :: User-defined tags are written in lowercase; built-in
|
|
tags with special meaning are written with all capitals.
|
|
- Release, PRIORITY :: User-defined properties are capitalized; built-in
|
|
properties with special meaning are written with all capitals.
|
|
|
|
Moreover, Org uses /option keywords/ (like ~#+TITLE~ to set the title)
|
|
and /environment keywords/ (like ~#+BEGIN_HTML~ to start a ~HTML~
|
|
environment). They are written in uppercase in the manual to enhance
|
|
its readability, but you can use lowercase in your Org files.[fn:7]
|
|
|
|
*** Keybindings and commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Bind useful commands to keys
|
|
:END:
|
|
|
|
#+kindex: C-c a
|
|
#+findex: org-agenda
|
|
#+kindex: C-c c
|
|
#+findex: org-capture
|
|
|
|
The manual suggests two global keybindings: {{{kbd(C-c a)}}} for
|
|
~org-agenda~ and {{{kbd(C-c c)}}} for ~org-capture~. These are only
|
|
suggestions, but the rest of the manual assumes that you are using
|
|
these keybindings.
|
|
|
|
Also, the manual lists both the keys and the corresponding commands
|
|
for accessing a functionality. Org mode often uses the same key for
|
|
different functions, depending on context. The command that is bound
|
|
to such keys has a generic name, like ~org-metaright~. In the manual
|
|
we will, wherever possible, give the function that is internally
|
|
called by the generic command. For example, in the chapter on document
|
|
structure, {{{kbdkey(M-,right)}}} will be listed to call
|
|
~org-do-demote~, while in the chapter on tables, it will be listed to
|
|
call ~org-table-move-column-right~.
|
|
|
|
# If you prefer, you can compile the manual without the command names by unsetting the flag ~cmdnames~ in {{{file(org.texi)}}}.
|
|
|
|
* Document structure
|
|
:PROPERTIES:
|
|
:DESCRIPTION: A tree works like your brain
|
|
:ALT_TITLE: Document Structure
|
|
:END:
|
|
#+cindex: document structure
|
|
#+cindex: structure of document
|
|
|
|
Org is based on Outline mode and provides flexible commands to
|
|
edit the structure of the document.
|
|
|
|
** Outlines
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Org mode is based on Outline mode
|
|
:END:
|
|
#+cindex: outlines
|
|
#+cindex: Outline mode
|
|
|
|
Org is implemented on top of Outline mode. Outlines allow a document
|
|
to be organized in a hierarchical structure, which (at least for me)
|
|
is the best representation of notes and thoughts. An overview of this
|
|
structure is achieved by folding (hiding) large parts of the document
|
|
to show only the general document structure and the parts currently
|
|
being worked on. Org greatly simplifies the use of outlines by
|
|
compressing the entire show/hide functionality into a single command,
|
|
{{{command(org-cycle)}}}, which is bound to the {{{key(TAB)}}} key.
|
|
|
|
** Headlines
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to typeset Org tree headlines
|
|
:END:
|
|
#+cindex: headlines
|
|
#+cindex: outline tree
|
|
#+vindex: org-special-ctrl-a/e
|
|
#+vindex: org-special-ctrl-k
|
|
#+vindex: org-ctrl-k-protect-subtree
|
|
|
|
Headlines define the structure of an outline tree. The headlines in Org
|
|
start with one or more stars, on the left margin.[fn:8] For example:
|
|
|
|
#+begin_src org
|
|
,* Top level headline
|
|
,** Second level
|
|
,*** Third level
|
|
some text
|
|
,*** Third level
|
|
more text
|
|
,* Another top level headline
|
|
#+end_src
|
|
|
|
{{{noindent}}} Some people find the many stars too noisy and would
|
|
prefer an outline that has whitespace followed by a single star as
|
|
headline starters. A setup to realize this is described in the
|
|
section, [[Clean view]].
|
|
|
|
#+vindex: org-cycle-separator-lines
|
|
An empty line after the end of a subtree is considered part of it and
|
|
will be hidden when the subtree is folded. However, if you leave at
|
|
least two empty lines, one empty line will remain visible after folding
|
|
the subtree, in order to structure the collapsed view. See the
|
|
variable ~org-cycle-separator-lines~ to modify this behavior.
|
|
|
|
** Visibility cycling
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Show and hide, much simplified
|
|
:ALT_TITLE: Visibility cycling
|
|
:END:
|
|
#+cindex: cycling, visibility
|
|
#+cindex: visibility cycling
|
|
#+cindex: trees, visibility
|
|
#+cindex: show hidden text
|
|
#+cindex: hide text
|
|
|
|
Outlines make it possible to hide parts of the text in the buffer.
|
|
Org uses just two commands, bound to {{{key(TAB)}}} and
|
|
{{{kbdkey(S-,TAB)}}} to change the visibility in the buffer.
|
|
|
|
#+cindex: subtree visibility states
|
|
#+cindex: subtree cycling
|
|
#+cindex: folded, subtree visibility state
|
|
#+cindex: children, subtree visibility state
|
|
#+cindex: subtree, subtree visibility state
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{key(TAB)}}}, ~org-cycle~ :: Subtrees can be cycled through three
|
|
states:
|
|
#+kindex: TAB
|
|
#+findex: org-cycle
|
|
|
|
#+begin_src example
|
|
,-> FOLDED -> CHILDREN -> SUBTREE --.
|
|
'-----------------------------------'
|
|
#+end_src
|
|
|
|
#+vindex: org-cycle-emulate-tab
|
|
#+vindex: org-cycle-global-at-bob
|
|
|
|
By default, the cursor must be on a headline for this to work,
|
|
but this behavior can be modified with the ~org-cycle-emulate-tab~ option. When the cursor is at the
|
|
beginning of the buffer and the first line is not a headline,
|
|
then {{{key(TAB)}}} actually runs global cycling (see
|
|
below).[fn:9] Also, when called with a prefix argument
|
|
({{{kbdspckey(C-u,TAB)}}}), global cycling is invoked.
|
|
|
|
- {{{kbdkey(S-,TAB)}}} or {{{kbdspckey(C-u,TAB)}}}, ~org-global-cycle~ ::
|
|
Global cycling: Rotate the entire buffer among the states
|
|
|
|
#+cindex: global visibility states
|
|
#+cindex: global cycling
|
|
#+cindex: overview, global visibility state
|
|
#+cindex: contents, global visibility state
|
|
#+cindex: show all, global visibility state
|
|
#+kindex: C-u TAB
|
|
#+kindex: S-TAB
|
|
#+findex: org-global-cycle
|
|
|
|
#+begin_example
|
|
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
|
|
'--------------------------------------'
|
|
#+end_example
|
|
|
|
When {{{kbdkey(S-,TAB)}}} is called with a numeric prefix
|
|
argument, ~N~, the CONTENTS view up to headlines of level N will
|
|
be shown. Note that inside tables, {{{kbdkey(S-,TAB)}}} jumps
|
|
to the previous field.
|
|
|
|
- {{{kbdspckey(C-u C-u C-u,TAB)}}}, ~show-all~ :: Show all, including
|
|
drawers.
|
|
|
|
#+kindex: C-u C-u C-u TAB
|
|
#+findex: show-all
|
|
#+cindex: show all, command
|
|
- {{{kbd(C-c C-r)}}}, ~org-reveal~ :: Reveal context around point,
|
|
showing the current entry, the following heading and the
|
|
hierarchy above. Useful for working near a location that has
|
|
been exposed by a sparse tree command (see [[Sparse trees]]) or an
|
|
agenda command (see [[Agenda commands]]). With a prefix argument
|
|
show, on each level, all sibling headings. With a double prefix
|
|
argument, also show the entire subtree of the parent.
|
|
|
|
#+cindex: revealing context
|
|
#+kindex: C-c C-r
|
|
#+findex: org-reveal
|
|
- {{{kbd(C-c C-k)}}}, ~show-branches~ :: Expose all the headings of
|
|
the subtree, CONTENT view for just one subtree.
|
|
|
|
#+kindex: C-c C-k
|
|
#+findex: show-branches
|
|
#+cindex: show branches, command
|
|
- {{{kbdspckey(C-c,TAB)}}}, ~show-children~ :: Expose all direct
|
|
children of the subtree. With a numeric prefix argument, ~N~,
|
|
expose all children down to level N.
|
|
|
|
#+kindex: C-c TAB
|
|
#+findex: show-children
|
|
#+cindex: show children, command
|
|
- {{{kbd(C-c C-x b)}}}, ~org-tree-to-indirect-buffer~ :: Show the
|
|
current subtree in an indirect buffer.[fn:10] With a numeric
|
|
prefix argument, ~N~, go up to level N and then take that tree.
|
|
If N is negative then go up that many levels. With a
|
|
{{{kbd(C-u)}}} prefix, do not remove the previously used indirect
|
|
buffer.
|
|
|
|
#+kindex: C-c C-x b
|
|
#+findex: org-tree-to-indirect-buffer
|
|
- {{{kbd(C-c C-x v)}}}, ~org-copy-visible~ :: Copy the /visible/ text
|
|
in the region into the kill ring.
|
|
|
|
#+vindex: org-startup-folded
|
|
#+cindex: ~overview~, STARTUP keyword
|
|
#+cindex: ~content~, STARTUP keyword
|
|
#+cindex: ~showall~, STARTUP keyword
|
|
#+cindex: ~showeverything~, STARTUP keyword
|
|
|
|
When Emacs first visits an Org file, the global state is set to
|
|
OVERVIEW, i.e., only the top level headlines are visible. This can be
|
|
configured through the variable ~org-startup-folded~, or on a
|
|
per-file basis by adding one of the following lines anywhere in the
|
|
buffer:
|
|
|
|
#+begin_src org
|
|
,#+STARTUP: overview
|
|
,#+STARTUP: content
|
|
,#+STARTUP: showall
|
|
,#+STARTUP: showeverything
|
|
#+end_src
|
|
|
|
#+cindex: property, VISIBILITY
|
|
|
|
{{{noindent}}} Furthermore, any entries with a {{{samp(VISIBILITY)}}}
|
|
property (see [[Properties and columns]]) will get their visibility
|
|
adapted accordingly. Allowed values for this property are ~folded~,
|
|
~children~, ~content~, and ~all~.
|
|
|
|
#+attr_texinfo: :indic @asis
|
|
- {{{kbdspckey(C-u C-u,TAB)}}}, ~org-set-startup-visibility~ :: Switch
|
|
back to the startup visibility of the buffer, i.e., whatever is
|
|
requested by startup options and {{{samp(VISIBILITY)}}}
|
|
properties in individual entries.
|
|
|
|
** Motion
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Jumping to other headlines
|
|
:END:
|
|
#+cindex: motion, between headlines
|
|
#+cindex: jumping, to headlines
|
|
#+cindex: headline navigation
|
|
The following commands jump to other headlines in the buffer.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-n)}}}, ~outline-next-visible-heading~ :: Next heading.
|
|
#+kindex: C-c C-n
|
|
#+findex: outline-next-visible-heading
|
|
- {{{kbd(C-c C-p)}}}, ~outline-previous-visible-heading~ :: Previous heading.
|
|
#+kindex: C-c C-p
|
|
#+findex: outline-previous-visible-heading
|
|
- {{{kbd(C-c C-f)}}}, ~org-forward-same-level~ :: Next heading same level.
|
|
#+kindex: C-c C-f
|
|
#+findex: org-forward-same-level
|
|
- {{{kbd(C-c C-b)}}}, ~org-backward-same-level~ :: Previous heading same level.
|
|
#+kindex: C-c C-b
|
|
#+findex: org-backward-same-level
|
|
- {{{kbd(C-c C-u)}}}, ~outline-up-heading~ :: Backward to higher level heading.
|
|
#+kindex: C-c C-u
|
|
#+findex: outline-up-heading
|
|
- {{{kbd(C-c C-j)}}}, ~org-goto~ :: Jump to a different place without
|
|
changing the current outline visibility. Shows the document
|
|
structure in a temporary buffer, where you can use the
|
|
following keys to find your destination:
|
|
|
|
#+kindex: C-c C-j
|
|
#+findex: org-goto
|
|
#+vindex: org-goto-auto-isearch
|
|
- {{{key(TAB)}}} :: Cycle visibility.
|
|
- {{{key(down)}}} / {{{key(up)}}} :: Next/previous visible headline.
|
|
- {{{key(RET)}}} :: Select this location.
|
|
- {{{kbd(/)}}} :: Do a Sparse-tree search
|
|
The following keys work if you turn off ~org-goto-auto-isearch~
|
|
- n / p :: Next/previous visible headline.
|
|
- f / b :: Next/previous headline same level.
|
|
- u :: One level up.
|
|
- 0--9 :: Digit argument.
|
|
- q :: Quit.
|
|
|
|
#+vindex: org-goto-interface
|
|
{{{noindent}}} See also the variable ~org-goto-interface~.
|
|
|
|
** Structure editing
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Changing sequence and level of headlines
|
|
:ALT_TITLE: Structure editing
|
|
:END:
|
|
#+cindex: structure editing
|
|
#+cindex: headline, promotion and demotion
|
|
#+cindex: promotion, of subtrees
|
|
#+cindex: demotion, of subtrees
|
|
#+cindex: subtree, cut and paste
|
|
#+cindex: pasting, of subtrees
|
|
#+cindex: cutting, of subtrees
|
|
#+cindex: copying, of subtrees
|
|
#+cindex: sorting, of subtrees
|
|
#+cindex: subtrees, cut and paste
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbdkey(M-,RET)}}}, ~org-insert-heading~ :: Insert new heading
|
|
with same level as current. If the cursor is in a plain list
|
|
item, a new item is created (see [[Plain lists]]). To force
|
|
creation of a new headline, use a prefix argument. When this
|
|
command is used in the middle of a line, the line is split and
|
|
the rest of the line becomes the new headline.[fn:11] If the
|
|
command is used at the beginning of a headline, the new
|
|
headline is created before the current line. If at the
|
|
beginning of any other line, the content of that line is made
|
|
the new heading. If the command is used at the end of a folded
|
|
subtree (i.e., behind the ellipses at the end of a headline),
|
|
then a headline like the current one will be inserted after the
|
|
end of the subtree.
|
|
|
|
#+kindex: M-RET
|
|
#+findex: org-insert-heading
|
|
#+vindex: org-M-RET-may-split-line
|
|
- {{{kbdkey(C-,RET)}}}, ~org-insert-heading-respect-content~ :: Just
|
|
like {{{kbdkey(M-,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: C-RET
|
|
#+findex: org-insert-heading-respect-content
|
|
- {{{kbdkey(M-S-,RET)}}}, ~org-insert-todo-heading~ :: Insert new
|
|
TODO entry with same level as current heading. See also the
|
|
variable ~org-treat-insert-todo-heading-as-state-change~.
|
|
|
|
#+kindex: M-S-RET
|
|
#+findex: org-insert-todo-heading
|
|
#+vindex: org-treat-insert-todo-heading-as-state-change
|
|
- {{{kbdkey(C-S-,RET)}}}, ~org-insert-todo-heading-respect-content~ :: Insert
|
|
new TODO entry with same level as current heading. Like
|
|
{{{kbdkey(C-,RET)}}}, the new headline will be inserted after
|
|
the current subtree.
|
|
|
|
#+kindex: C-S-RET
|
|
#+findex: org-insert-todo-heading-respect-content
|
|
- {{{key(TAB)}}}, ~org-cycle~ :: In a new entry with no text
|
|
yet, the first {{{key(TAB)}}} demotes the entry to become a
|
|
child of the previous one. The next {{{key(TAB)}}} makes it a
|
|
parent, and so on, all the way to top level. Yet another
|
|
{{{key(TAB)}}}, and you are back to the initial level.
|
|
|
|
#+kindex: @key{TAB}
|
|
#+findex: org-cycle
|
|
- {{{kbdkey(M-,left)}}}, ~org-do-promote~ :: Promote current heading
|
|
by one level.
|
|
|
|
#+kindex: M-left
|
|
#+findex: org-do-promote
|
|
- {{{kbdkey(M-,right)}}}, ~org-do-demote~ :: Demote current heading
|
|
by one level.
|
|
|
|
#+kindex: M-right
|
|
#+findex: org-do-demote
|
|
- {{{kbdkey(M-S-,left)}}}, ~org-promote-subtree~ :: Promote the
|
|
current subtree by one level.
|
|
|
|
#+kindex: M-S-left
|
|
#+findex: org-promote-subtree
|
|
- {{{kbdkey(M-S-,right)}}}, ~org-demote-subtree~ :: Demote the
|
|
current subtree by one level.
|
|
|
|
#+kindex: M-S-right
|
|
#+findex: org-demote-subtree
|
|
- {{{kbdkey(M-S-,up)}}}, ~org-move-subtree-up~ :: Move subtree up
|
|
(swap with previous subtree of same level).
|
|
|
|
#+kindex: M-S-up
|
|
#+findex: org-move-subtree-up
|
|
- {{{kbdkey(M-S-,down)}}}, ~org-move-subtree-down~ :: Move subtree
|
|
down (swap with next subtree of same level).
|
|
|
|
#+kindex: M-S-,down
|
|
#+findex: org-move-subtree-down
|
|
- {{{kbd(C-c C-x C-w)}}}, ~org-cut-subtree~ :: Kill subtree, i.e.,
|
|
remove it from buffer but save in kill ring. With a numeric
|
|
prefix argument N, kill N sequential subtrees.
|
|
|
|
#+kindex: C-c C-x C-w
|
|
#+findex: org-cut-subtree
|
|
- {{{kbd(C-c C-x M-w)}}}, ~org-copy-subtree~ :: Copy subtree to kill
|
|
ring. With a numeric prefix argument N, copy the N sequential
|
|
subtrees.
|
|
|
|
#+kindex: C-c C-x M-w
|
|
#+findex: org-copy-subtree
|
|
- {{{kbd(C-c C-x C-y)}}}, ~org-paste-subtree~ :: Yank subtree from
|
|
kill ring. This does modify the level of the subtree to make
|
|
sure the tree fits in nicely at the yank position. The yank
|
|
level can also be specified with a numeric prefix argument, or
|
|
by yanking after a headline marker like {{{samp(****)}}}.
|
|
|
|
#+kindex: C-c C-x C-y
|
|
#+findex: org-paste-subtree
|
|
- {{{kbd(C-y)}}}, ~org-yank~ :: Depending on the variables ~org-yank-adjusted-subtrees~ and ~org-yank-folded-subtrees~,
|
|
Org's internal ~yank~ command will paste subtrees folded and in
|
|
a clever way, using the same command as {{{kbd(C-c C-x C-y)}}}.
|
|
With the default settings, no level adjustment will take place,
|
|
but the yanked tree will be folded unless doing so would
|
|
swallow text previously visible. Any prefix argument to this
|
|
command will force a normal ~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 ~yank-pop~ after a yank, it
|
|
will yank previous kill items plainly, without adjustment and
|
|
folding.
|
|
|
|
#+kindex: C-y
|
|
#+findex: org-yank
|
|
#+vindex: org-yank-adjusted-subtrees
|
|
#+vindex: org-yank-folded-subtrees
|
|
- {{{kbd(C-c C-x c)}}}, ~org-clone-subtree-with-time-shift~ :: Clone
|
|
a subtree by making a number of sibling copies of it. You will
|
|
be prompted for the number of copies to make, and you can also
|
|
specify if any timestamps in the entry should be shifted. This
|
|
can be useful, for example, to create a number of tasks related
|
|
to a series of lectures to prepare. For more details, see the
|
|
docstring of the command ~org-clone-subtree-with-time-shift~.
|
|
|
|
#+kindex: C-c C-x c
|
|
#+findex: org-clone-subtree-with-time-shift
|
|
- {{{kbd(C-c C-w)}}}, ~org-refile~ :: Refile entry or region to a
|
|
different location. See [[Refile and copy]].
|
|
|
|
#+kindex: C-c C-w
|
|
#+findex: org-refile
|
|
- {{{kbd(C-c ^)}}}, ~org-sort~ :: Sort same-level entries. When
|
|
there is an active region, all entries in the region will be
|
|
sorted. Otherwise the children of the current headline are
|
|
sorted. The command prompts for the sorting method, which can
|
|
be alphabetically, numerically, by time (first timestamp with
|
|
active preferred, creation time, scheduled time, deadline
|
|
time), by priority, by TODO keyword (in the sequence the
|
|
keywords have been defined in the setup) or by the value of a
|
|
property. Reverse sorting is possible as well. You can also
|
|
supply your own function to extract the sorting key. With a
|
|
{{{kbd(C-u)}}} prefix, sorting will be case-sensitive.
|
|
|
|
#+kindex: C-c ^
|
|
#+findex: org-sort
|
|
- {{{kbd(C-x n s)}}}, ~org-narrow-to-subtree~ :: Narrow buffer to
|
|
current subtree.
|
|
|
|
#+kindex: C-x n s
|
|
#+findex: org-narrow-to-subtree
|
|
- {{{kbd(C-x n b)}}}, ~org-narrow-to-block~ :: Narrow buffer to
|
|
current block.
|
|
|
|
#+kindex: C-x n b
|
|
#+findex: org-narrow-to-block
|
|
- {{{kbd(C-x n w)}}}, ~widen~ :: Widen buffer to remove narrowing.
|
|
|
|
#+kindex: C-x n w
|
|
#+findex: widen
|
|
- {{{kbd(C-c *)}}}, ~org-toggle-heading~ :: Turn a normal line or
|
|
plain list item into a headline (so that it becomes a
|
|
subheading at its location). Also turn a headline into a normal
|
|
line by removing the stars. If there is an active region, turn
|
|
all lines in the region into headlines. If the first line in
|
|
the region was an item, turn only the item lines into
|
|
headlines. Finally, if the first line is a headline, remove the
|
|
stars from all headlines in the region.
|
|
|
|
#+kindex: C-c *
|
|
#+findex: org-toggle-heading
|
|
|
|
#+cindex: region, active
|
|
#+cindex: active region
|
|
#+cindex: transient mark mode
|
|
|
|
When there is an active region (Transient Mark mode), promotion and
|
|
demotion work on all headlines in the region. To select a region of
|
|
headlines, it is best to place both point and mark at the beginning of
|
|
a line, mark at the beginning of the first headline, and point at the
|
|
line just after the last headline to change. Note that when the
|
|
cursor is inside a table (see [[Tables]]), the Meta-Cursor keys have
|
|
different functionality.
|
|
|
|
** Sparse trees
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Matches embedded in context
|
|
:ALT_TITLE: Sparse trees
|
|
:END:
|
|
#+cindex: sparse trees
|
|
#+cindex: trees, sparse
|
|
#+cindex: folding, sparse trees
|
|
#+cindex: occur, command
|
|
#+vindex: org-show-hierarchy-above
|
|
#+vindex: org-show-following-heading
|
|
#+vindex: org-show-siblings
|
|
#+vindex: org-show-entry-below
|
|
|
|
An important feature of Org mode is the ability to construct /sparse
|
|
trees/ for selected information in an outline tree, so that the entire
|
|
document is folded as much as possible, but the selected information
|
|
is made visible along with the headline structure above it.[fn:12]
|
|
Just try it out and you will see immediately how it works.
|
|
|
|
Org mode contains several commands creating such trees, all these
|
|
commands can be accessed through a dispatcher:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c /)}}}, ~org-sparse-tree~ :: This prompts for an extra
|
|
key to select a sparse-tree creating command.
|
|
|
|
#+kindex: C-c /
|
|
#+findex: org-sparse-tree
|
|
- {{{kbd(C-c / r)}}}, ~org-occur~ :: Prompts for a regexp and shows a
|
|
sparse tree with all matches. If the match is in a headline,
|
|
the headline is made visible. If the match is in the body of an
|
|
entry, headline and body are made visible. In order to provide
|
|
minimal context, also the full hierarchy of headlines above the
|
|
match is shown, as well as the headline following the
|
|
match. Each match is also highlighted; the highlights disappear
|
|
when the buffer is changed by an editing command, or by
|
|
pressing {{{kbd(C-c C-c)}}}.[fn:13] When called with a {{{kbd(C-u)}}}
|
|
prefix argument, previous highlights are kept, so several calls
|
|
to this command can be stacked.
|
|
|
|
#+kindex: C-c / r
|
|
#+findex: org-occur
|
|
#+vindex: org-remove-highlights-with-change
|
|
- {{{kbd(M-g n)}}}, ~next-error~ ::
|
|
@@info:@itemx@@ {{{kbd(M-g M-n)}}}
|
|
|
|
Jump to the next sparse tree match in this buffer.
|
|
|
|
#+kindex: M-g n
|
|
#+kindex: M-g M-n
|
|
#+findex: next-error
|
|
- {{{kbd(M-g p)}}}, ~previous-error~ ::
|
|
@@info:@itemx@@ {{{kbd(M-g M-p)}}}
|
|
|
|
Jump to the previous sparse tree match in this buffer.
|
|
|
|
#+kindex: M-g p
|
|
#+kindex: M-g M-p
|
|
#+findex: previous-error
|
|
#+vindex: org-agenda-custom-commands
|
|
|
|
{{{noindent}}} For frequently used sparse trees of specific search
|
|
strings, you can use the variable ~org-agenda-custom-commands~ to
|
|
define fast keyboard access to specific sparse trees. These commands
|
|
will then be accessible through the agenda dispatcher
|
|
(see [[Agenda dispatcher]]). For example:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands
|
|
'(("f" occur-tree "FIXME")))
|
|
#+end_src
|
|
|
|
{{{noindent}}} will define the key {{{kbd(C-c a f)}}} as a
|
|
shortcut for creating a sparse tree matching the string
|
|
{{{samp(FIXME)}}}.
|
|
|
|
The other sparse tree commands select headings based on TODO keywords,
|
|
tags, or properties and will be discussed later in this manual.
|
|
|
|
#+kindex: C-c C-e v
|
|
#+cindex: printing sparse trees
|
|
#+cindex: visible text, printing
|
|
|
|
To print a sparse tree, you can use the Emacs command
|
|
~ps-print-buffer-with-faces~ which does not print
|
|
invisible parts of the document.[fn:14] Or you can use the command
|
|
{{{kbd(C-c C-e v)}}} to export only the visible part of the
|
|
document and print the resulting file.
|
|
|
|
** Plain lists
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Additional structure within an entry
|
|
:ALT_TITLE: Plain lists
|
|
:END:
|
|
#+cindex: plain lists
|
|
#+cindex: lists, plain
|
|
#+cindex: lists, ordered
|
|
#+cindex: ordered lists
|
|
|
|
Within an entry of the outline tree, hand-formatted lists can provide
|
|
additional structure. They also provide a way to create lists of
|
|
checkboxes (see [[Checkboxes]]). Org supports editing
|
|
such lists, and every exporter (see [[Exporting]])
|
|
can parse and format them.
|
|
|
|
Org knows ordered lists, unordered lists, and description lists.
|
|
|
|
#+attr_texinfo: :table-type table :indic @bullet
|
|
- /Unordered/ list items start with ~-~, ~+~, or ~*~ as bullets.[fn:15]
|
|
|
|
- /Ordered/ list items start with a numeral followed by either a
|
|
period or a right parenthesis,[fn:16] such as ~1.~ or ~1~.[fn:170] If you want a list to
|
|
start with a different value (e.g., 20), start the text of the
|
|
item with ~[@20]~.[fn:17] Those constructs can be used
|
|
in any item of the list in order to enforce a particular
|
|
numbering.
|
|
#+vindex: org-plain-list-ordered-item-terminator
|
|
#+vindex: org-alphabetical-lists
|
|
|
|
- /Description/ list items are unordered list items, and contain the
|
|
separator {{{samp( :: )}}} to distinguish the description /term/ from the description.
|
|
|
|
|
|
Items belonging to the same list must have the same indentation on the
|
|
first line. In particular, if an ordered list reaches number
|
|
{{{samp(10.)}}}, then the 2--digit numbers must be written
|
|
left-aligned with the other numbers in the list. An item ends before
|
|
the next line that is less or equally indented than its bullet/number.
|
|
|
|
#+vindex: org-empty-line-terminates-plain-lists
|
|
A list ends whenever every item has ended, which means before any line less
|
|
or equally indented than items at top level. It also ends before two blank
|
|
lines.[fn:171] In that case, all items are closed. Here is an example:
|
|
|
|
#+begin_src texinfo
|
|
,** Lord of the Rings
|
|
My favorite scenes are (in this order)
|
|
1. The attack of the Rohirrim
|
|
2. Eowyn's fight with the witch king
|
|
+ this was already my favorite scene in the book
|
|
+ I really like Miranda Otto.
|
|
3. Peter Jackson being shot by Legolas
|
|
- on DVD only
|
|
He makes a really funny face when it happens.
|
|
But in the end, no individual scenes matter but the film as a whole.
|
|
Important actors in this film are:
|
|
- @b{Elijah Wood} :: He plays Frodo
|
|
- @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember
|
|
him very well from his role as Mikey Walsh in @i{The Goonies}.
|
|
#+end_src
|
|
|
|
Org supports these lists by tuning filling and wrapping commands to
|
|
deal with them correctly.[fn:18] To turn this on, put into
|
|
{{{file(.emacs)}}}: ~(require 'filladapt)~}, and by exporting them
|
|
properly (see [[Exporting]]). Since indentation is
|
|
what governs the structure of these lists, many structural constructs
|
|
like ~#+BEGIN_ ...~ blocks can be indented to signal that they belong
|
|
to a particular item.
|
|
|
|
#+vindex: org-list-demote-modify-bullet
|
|
#+vindex: org-list-indent-offset
|
|
If you find that using a different bullet for a sub-list (than that used for
|
|
the current list-level) improves readability, customize the variable
|
|
~org-list-demote-modify-bullet~. To get a greater difference of
|
|
indentation between items and theirs sub-items, customize
|
|
~org-list-indent-offset~.
|
|
|
|
#+vindex: org-list-automatic-rules
|
|
The following commands act on items when the cursor is in the first line of
|
|
an item (the line with the bullet or number). Some of them imply the
|
|
application of automatic rules to keep list structure intact. If some of
|
|
these actions get in your way, configure ~org-list-automatic-rules~
|
|
to disable them individually.
|
|
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{key(TAB)}}}, ~org-cycle~ ::
|
|
#+cindex: cycling, in plain lists
|
|
#+kindex: TAB
|
|
#+findex: org-cycle
|
|
#+vindex: org-cycle-include-plain-lists
|
|
|
|
Items can be folded just like headline levels. Normally this
|
|
works only if the cursor is on a plain list item. For more
|
|
details, see the variable ~org-cycle-include-plain-lists~. If
|
|
this variable is set to ~integrate~, plain list items will be
|
|
treated like low-level headlines. The level of an item is then
|
|
given by the indentation of the bullet/number. Items are always
|
|
subordinate to real headlines, however; the hierarchies remain
|
|
completely separated. In a new item with no text yet, the first
|
|
{{{key(TAB)}}} demotes the item to become a child of the
|
|
previous one. Subsequent {{{key(TAB)}}}s move the item to
|
|
meaningful levels in the list and eventually get it back to its
|
|
initial position.
|
|
|
|
- {{{kbdkey(M-,RET)}}}, ~org-insert-heading~ ::
|
|
#+kindex: M-RET
|
|
#+findex: org-insert-heading
|
|
#+vindex: org-M-RET-may-split-line
|
|
#+vindex: org-list-automatic-rules
|
|
|
|
Insert new item at current level. With a prefix argument, force
|
|
a new heading (see [[Structure editing]]). If this command is used
|
|
in the middle of an item, that item is /split/ in two, and the
|
|
second part becomes the new item.[fn:19] If this command is
|
|
executed /before item's body/, the new item is created /before/
|
|
the current one.
|
|
|
|
- {{{kbdkey(M-S-,RET)}}} ::
|
|
#+kindex: M-S-RET
|
|
|
|
Insert a new item with a checkbox (see [[Checkboxes]]).
|
|
|
|
- {{{kbdkey(S-,up)}}} ::
|
|
@@info:@itemx@@ {{{kbdkey(S-,down)}}}
|
|
|
|
Jump to the previous/next item in the current list, but
|
|
only if ~org-support-shift-select~ is off.[fn:20] If not, you can
|
|
still use paragraph jumping commands like {{{kbdkey(C-,up)}}}
|
|
and {{{kbdkey(C-,down)}}} to quite similar effect.
|
|
|
|
#+kindex: S-up
|
|
#+kindex: S-down
|
|
#+cindex: shift-selection-mode
|
|
#+vindex: org-support-shift-select
|
|
#+vindex: org-list-use-circular-motion
|
|
- {{{kbdkey(M-,up)}}} ::
|
|
@@info:@itemx@@ {{{kbdkey(M-,down)}}}
|
|
|
|
Move the item including subitems up/down (swap with
|
|
previous/next item of same indentation).[fn:21] If the list is
|
|
ordered, renumbering is automatic.
|
|
|
|
#+kindex: M-up
|
|
#+kindex: M-down
|
|
- {{{kbdkey(M-,left)}}} ::
|
|
@@info:@itemx@@ {{{kbdkey(M-,right)}}}
|
|
|
|
Decrease/increase the indentation of an item, leaving children
|
|
alone.
|
|
|
|
#+kindex: M-left
|
|
#+kindex: M-right
|
|
- {{{kbdkey(M-S-,left)}}} ::
|
|
@@info:@itemx@@ {{{kbdkey(M-S-,right)}}}
|
|
|
|
Decrease/increase the indentation of the item, including
|
|
subitems. Initially, the item tree is selected based on
|
|
current indentation. When these commands are executed several
|
|
times in direct succession, the initially selected region is
|
|
used, even if the new indentation would imply a different
|
|
hierarchy. To use the new hierarchy, break the command chain
|
|
with a cursor motion or so.
|
|
|
|
#+kindex: M-S-left
|
|
#+kindex: M-S-right
|
|
|
|
As a special case, using this command on the very first item of
|
|
a list will move the whole list. This behavior can be disabled
|
|
by configuring ~org-list-automatic-rules~. The global
|
|
indentation of a list has no influence on the text /after/ the
|
|
list.
|
|
- {{{kbd(C-c C-c)}}} :: If there is a checkbox (see [[Checkboxes]]) in
|
|
the item line, toggle the state of the checkbox. In any case,
|
|
verify bullets and indentation consistency in the whole list.
|
|
|
|
#+kindex: C-c C-c
|
|
- {{{kbd(C-c -)}}} :: Cycle the entire list level through the
|
|
different itemize/enumerate bullets ({{{samp(-)}}},
|
|
{{{samp(+)}}}, {{{samp(*)}}}, {{{samp(1.)}}}, {{{samp(1))}}})
|
|
or a subset of them, depending on ~org-plain-list-ordered-item-terminator~, the type of list, and
|
|
its indentation. With a numeric prefix argument N, select the
|
|
Nth bullet from this list. If there is an active region when
|
|
calling this, selected text will be changed into an item. With
|
|
a prefix argument, all lines will be converted to list items.
|
|
If the first line already was a list item, any item marker will
|
|
be removed from the list. Finally, even without an active
|
|
region, a normal line will be converted into a list item.
|
|
|
|
#+kindex: C-c -
|
|
#+vindex: org-plain-list-ordered-item-terminator
|
|
- {{{kbd(C-c *)}}} :: Turn a plain list item into a headline (so
|
|
that it becomes a subheading at its location). See
|
|
[[Structure editing]], for a detailed explanation.
|
|
|
|
#+kindex: C-c *
|
|
- {{{kbd(C-c C-*)}}} :: Turn the whole plain list into a subtree of
|
|
the current heading. Checkboxes (see [[Checkboxes]]) will become
|
|
TODO (resp. DONE) keywords when unchecked (resp. checked).
|
|
|
|
#+kindex: C-c C-*
|
|
- {{{kbd(S-left/right)}}} :: This command also cycles bullet styles
|
|
when the cursor in on the bullet or anywhere in an item line,
|
|
details depending on ~org-support-shift-select~.
|
|
|
|
#+vindex: org-support-shift-select
|
|
#+kindex: S-left
|
|
#+kindex: S-right
|
|
- {{{kbd(C-c ^)}}} :: Sort the plain list. You will be prompted for
|
|
the sorting method: numerically, alphabetically, by time, or by
|
|
custom function.
|
|
|
|
#+kindex: C-c ^
|
|
|
|
** Drawers
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tucking stuff away
|
|
:END:
|
|
#+cindex: drawers
|
|
#+cindex: #+DRAWERS
|
|
#+cindex: visibility cycling, drawers
|
|
|
|
#+vindex: org-drawers
|
|
#+cindex: org-insert-drawer
|
|
#+kindex: C-c C-x d
|
|
Sometimes you want to keep information associated with an entry, but you
|
|
normally don't want to see it. For this, Org mode has /drawers/.
|
|
Drawers need to be configured with the variable
|
|
~org-drawers~.[fn:172] Drawers
|
|
look like this:
|
|
|
|
#+begin_src org
|
|
,** This is a headline
|
|
Still outside the drawer
|
|
:DRAWERNAME:
|
|
This is inside the drawer.
|
|
:END:
|
|
After the drawer.
|
|
#+end_src
|
|
|
|
|
|
You can interactively insert drawers at point by calling
|
|
~org-insert-drawer~, which is bound to {{{kbd(C-c C-x d)}}}.
|
|
With an active region, this command will put the region inside the
|
|
drawer. With a prefix argument, this command calls
|
|
~org-insert-property-drawer~ and add a property drawer right
|
|
below the current headline. Completion over drawer keywords is also
|
|
possible using {{{key(M-TAB)}}}.
|
|
|
|
Visibility cycling (see [[Visibility cycling]]) on the headline
|
|
will hide and show the entry, but keep the drawer collapsed to a
|
|
single line. In order to look inside the drawer, you need to move the
|
|
cursor to the drawer line and press {{{key(TAB)}}} there. Org mode
|
|
uses the ~PROPERTIES~ drawer for storing properties
|
|
(see [[Properties and columns]]), and you can also arrange for
|
|
state change notes (see [[Tracking TODO state changes]) and
|
|
clock times (see [[Clocking work time]) to be stored in a drawer
|
|
~LOGBOOK~. If you want to store a quick note in the LOGBOOK
|
|
drawer, in a similar way to state changes, use
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-z)}}} :: Add a time-stamped note to the LOGBOOK
|
|
drawer.
|
|
|
|
#+kindex: C-c C-z
|
|
|
|
** Blocks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Folding blocks
|
|
:END:
|
|
#+vindex: org-hide-block-startup
|
|
#+cindex: blocks, folding
|
|
|
|
Org mode uses ~begin~ ... ~end~ blocks for various purposes from including
|
|
source code examples (see [[Literal examples]]) to capturing time logging
|
|
information (see [[Clocking work time]]). These blocks can be folded
|
|
and unfolded by pressing TAB in the begin line. You can also get all
|
|
blocks folded at startup by configuring the variable
|
|
~org-hide-block-startup~ or on a per-file basis by using
|
|
|
|
#+cindex: @code{hideblocks}, STARTUP keyword
|
|
#+cindex: @code{nohideblocks}, STARTUP keyword
|
|
#+begin_src org
|
|
,#+STARTUP: hideblocks
|
|
,#+STARTUP: nohideblocks
|
|
#+end_src
|
|
|
|
** Creating footnotes
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Define footnotes in Org syntax
|
|
:END:
|
|
#+cindex: footnotes
|
|
|
|
Org mode supports the creation of footnotes. In contrast to the
|
|
{{{file(footnote.el)}}} package, Org mode's footnotes are designed for
|
|
work on a larger document, not only for one-off documents like emails.
|
|
The basic syntax is similar to the one used by
|
|
{{{file(footnote.el)}}}, i.e., a footnote is defined in a paragraph
|
|
that is started by a footnote marker in square brackets in column 0,
|
|
no indentation allowed. If you need a paragraph break inside a
|
|
footnote, use the LaTeX idiom ~\par~. The footnote reference is simply
|
|
the marker in square brackets, inside text. For example:
|
|
|
|
#+begin_example
|
|
The Org homepage[fn:1] now looks a lot better than it used to.
|
|
...
|
|
[fn:1] The link is: http://orgmode.org
|
|
#+end_example
|
|
|
|
Org mode extends the number-based syntax to /named/ footnotes and
|
|
optional inline definition. Using plain numbers as markers (as
|
|
{{{file(footnote.el)}}} does) is supported for backward compatibility,
|
|
but not encouraged because of possible conflicts with LaTeX
|
|
snippets (see [[Embedded LaTeX]]). Here are
|
|
the valid references:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~[1]~ :: A plain numeric footnote marker. Compatible with
|
|
{{{file(footnote.el)}}}, but not recommended because
|
|
something like ~[1]~ could easily be part of a
|
|
code snippet.
|
|
|
|
- ~[fn:name]~ :: A named footnote reference, where ~name~ is
|
|
a unique label word, or, for simplicity of automatic
|
|
creation, a number.
|
|
- ~[fn:: This is the inline definition of this footnote]~ :: A
|
|
LaTeX-like anonymous footnote where the definition
|
|
is given directly at the reference point.
|
|
- ~[fn:name: a definition]~ :: An inline definition of a footnote,
|
|
which also specifies a name for the note. Since Org allows
|
|
multiple references to the same note, you can then use ~[fn:name]~ to create additional references.
|
|
|
|
|
|
#+vindex: org-footnote-auto-label
|
|
Footnote labels can be created automatically, or you can create names
|
|
yourself. This is handled by the variable
|
|
~org-footnote-auto-label~ and its corresponding
|
|
~#+STARTUP~ keywords. See the docstring of that variable for
|
|
details.
|
|
|
|
{{{noindent}}} The following command handles footnotes:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x f)}}} :: The footnote action command.
|
|
#+kindex: C-c C-x f
|
|
|
|
When the cursor is on a footnote reference, jump to the
|
|
definition. When it is at a definition, jump to the
|
|
(first) reference.
|
|
|
|
#+vindex: org-footnote-define-inline
|
|
#+vindex: org-footnote-section
|
|
#+vindex: org-footnote-auto-adjust
|
|
|
|
Otherwise, create a new footnote. Depending on the
|
|
variable ~org-footnote-define-inline~, the
|
|
definition will be placed right into the text as part
|
|
of the reference, or separately into the location
|
|
determined by the variable ~org-footnote-section~.[fn:173]
|
|
|
|
When this command is called with a prefix argument, a
|
|
menu of additional options is offered:
|
|
|
|
- {{{kbd(s)}}} :: Sort the footnote definitions by reference sequence.
|
|
During editing, Org makes no effort to sort footnote
|
|
definitions into a particular sequence. If you want them
|
|
sorted, use this command, which will also move entries
|
|
according to ~org-footnote-section~. Automatic sorting
|
|
after each insertion/deletion can be configured using the
|
|
variable ~org-footnote-auto-adjust~.
|
|
- {{{kbd(r)}}} :: Renumber the simple ~fn:N~ footnotes. Automatic
|
|
renumbering after each insertion/deletion can be
|
|
configured using the variable ~org-footnote-auto-adjust~.
|
|
- {{{kbd(S)}}} :: Short for first ~r~, then ~s~ action.
|
|
- {{{kbd(n)}}} :: Normalize the footnotes by collecting all definitions
|
|
(including inline definitions) into a special section, and
|
|
then numbering them in sequence. The references will then
|
|
also be numbers. This is meant to be the final step
|
|
before finishing a document (e.g., sending off an email).
|
|
The exporters do this automatically, and so could
|
|
something like ~message-send-hook~.
|
|
- {{{kbd(d)}}} :: Delete the footnote at point, and all definitions of and
|
|
references to it.
|
|
|
|
Depending on the variable ~org-footnote-auto-adjust~, renumbering
|
|
and sorting footnotes can be automatic after each insertion or
|
|
deletion.[fn:174]
|
|
|
|
- {{{kbd(C-c C-c)}}} :: If the cursor is on a footnote reference, jump to the
|
|
definition. If it is a the definition, jump back to
|
|
the reference. When called at a footnote location with
|
|
a prefix argument, offer the same menu as {{{kbd(C-c C-x f)}}}.
|
|
|
|
#+kindex: C-c C-c
|
|
|
|
- {{{kbd(C-c C-o)}}} or {{{kbd(mouse-1/2)}}} :: Footnote labels are also
|
|
links to the corresponding definition/reference, and you can
|
|
use the usual commands to follow these links.
|
|
|
|
#+kindex: C-c C-o
|
|
#+kindex: mouse-1
|
|
#+kindex: mouse-2
|
|
|
|
** Orgstruct mode
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Structure editing outside Org
|
|
:ALT_TITLE: Orgstruct mode
|
|
:END:
|
|
#+cindex: Orgstruct mode
|
|
#+cindex: minor mode for structure editing
|
|
|
|
If you like the intuitive way the Org mode structure editing and list
|
|
formatting works, you might want to use these commands in other modes
|
|
like Text mode or Mail mode as well. The minor mode ~orgstruct-mode~
|
|
makes this possible. Toggle the mode with {{{kbd(M-x orgstruct-mode)}}}, or turn it on by default, for example in Message
|
|
mode, with one of:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(add-hook 'message-mode-hook 'turn-on-orgstruct)
|
|
(add-hook 'message-mode-hook 'turn-on-orgstruct++)
|
|
#+end_src
|
|
|
|
When this mode is active and the cursor is on a line that looks to Org
|
|
like a headline or the first line of a list item, most structure
|
|
editing commands will work, even if the same keys normally have
|
|
different functionality in the major mode you are using. If the
|
|
cursor is not in one of those special lines, Orgstruct mode lurks
|
|
silently in the shadows. When you use ~orgstruct++-mode~, Org will
|
|
also export indentation and autofill settings into that mode, and
|
|
detect item context after the first line of an item.
|
|
|
|
* Tables
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Pure magic for quick formatting
|
|
:END:
|
|
#+cindex: tables
|
|
#+cindex: editing tables
|
|
|
|
Org comes with a fast and intuitive table editor. Spreadsheet-like
|
|
calculations are supported using the Emacs {{{file(calc)}}} package
|
|
([[info:calc]]).
|
|
|
|
** Built-in table editor
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Simple tables
|
|
:END:
|
|
#+cindex: table editor, built-in
|
|
|
|
Org makes it easy to format tables in plain ASCII. Any line with
|
|
{{{samp(|)}}} as the first non-whitespace character is considered part
|
|
of a table. {{{samp(|)}}} is also the column separator.[fn:22] A table
|
|
might look like this:
|
|
|
|
#+begin_src org
|
|
| Name | Phone | Age |
|
|
|-------+-------+-----|
|
|
| Peter | 1234 | 17 |
|
|
| Anna | 4321 | 25 |
|
|
#+end_src
|
|
|
|
|
|
A table is re-aligned automatically each time you press {{{key(TAB)}}}
|
|
or {{{key(RET)}}} or {{{kbd(C-c C-c)}}} inside the table.
|
|
{{{key(TAB)}}} also moves to the next field ({{{key(RET)}}} to the
|
|
next row) and creates new table rows at the end of the table or before
|
|
horizontal lines. The indentation of the table is set by the first
|
|
line. Any line starting with {{{samp(|-)}}} is considered as a
|
|
horizontal separator line and will be expanded on the next re-align to
|
|
span the whole table width. So, to create the above table, you would
|
|
only type
|
|
|
|
#+begin_src org
|
|
|Name|Phone|Age|
|
|
|-
|
|
#+end_src
|
|
|
|
|
|
{{{noindent}}} and then press {{{key(TAB)}}} to align the table and
|
|
start filling in fields. Even faster would be to type
|
|
~|Name|Phone|Age~ followed by {{{kbdspckey(C-c,RET)}}}.
|
|
|
|
#+vindex: org-enable-table-editor
|
|
#+vindex: org-table-auto-blank-field
|
|
|
|
When typing text into a field, Org treats {{{key(DEL)}}},
|
|
{{{key(Backspace)}}}, and all character keys in a special way, so that
|
|
inserting and deleting avoids shifting other fields. Also, when
|
|
typing /immediately/ after the cursor was moved into a new field with
|
|
{{{key(TAB)}}}, {{{kbdkey(S-,TAB)}}} or {{{key(RET)}}}, the field is
|
|
automatically made blank. If this behavior is too unpredictable for
|
|
you, configure the variables ~org-enable-table-editor~ and
|
|
~org-table-auto-blank-field~.
|
|
*** Creation and conversion
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Creating tabular data in Org
|
|
:END:
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c |)}}}, ~org-table-create-or-convert-from-region~ :: Convert
|
|
the active region to table. If every line contains at least one
|
|
{{{key(TAB)}}} character, the function assumes that the material
|
|
is tab separated. If every line contains a comma, comma-separated
|
|
values (CSV) are assumed. If not, lines are split at whitespace
|
|
into fields. You can use a prefix argument to force a specific
|
|
separator: {{{kbd(C-u)}}} forces CSV, {{{kbd(C-u C-u)}}} forces
|
|
{{{key(TAB)}}}, and a numeric argument ~N~ indicates that at
|
|
least N consecutive spaces, or alternatively a {{{key(TAB)}}}
|
|
will be the separator. If there is no active region, this command
|
|
creates an empty Org table. But it is easier just to start
|
|
typing, like {{{kbdspckey(|Name|Phone|Age,RET)}}} {{{kbdkey(|-
|
|
,TAB)}}}.
|
|
|
|
#+kindex: C-c |
|
|
#+findex: org-table-create-or-convert-from-region
|
|
|
|
*** Re-aligning and field motion
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Navigating and tidying
|
|
:END:
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-c)}}}, ~org-table-align~ :: Re-align the table without
|
|
moving the cursor.
|
|
|
|
#+kindex: C-c C-c
|
|
#+findex: org-table-align
|
|
- {{{kbd(<TAB>)}}}, ~org-table-next-field~ :: Re-align the table, move
|
|
to the next field. Creates a new row if necessary.
|
|
|
|
#+kindex: <TAB>
|
|
#+findex: org-table-next-field
|
|
- {{{kbdkey(S-,TAB)}}}, ~org-table-previous-field~ :: Re-align, move to
|
|
previous field.
|
|
|
|
#+kindex: S-TAB
|
|
#+findex: org-table-previous-field
|
|
- {{{key(RET)}}}, ~org-table-next-row~ :: Re-align the table and move
|
|
down to next row. Creates a new row if necessary. At the
|
|
beginning or end of a line, {{{key(RET)}}} still does NEWLINE, so
|
|
it can be used to split a table.
|
|
|
|
#+kindex: RET
|
|
#+findex: org-table-next-row
|
|
- {{{kbd(M-a)}}}, ~org-table-beginning-of-field~ :: Move to beginning
|
|
of the current table field, or on to the previous field.
|
|
|
|
#+kindex: M-a
|
|
#+findex: org-table-beginning-of-field
|
|
- {{{kbd(M-e)}}}, ~org-table-end-of-field~ :: Move to end of the
|
|
current table field, or on to the next field.
|
|
|
|
#+kindex: M-e
|
|
#+findex: org-table-end-of-field
|
|
|
|
*** Column and row editing
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Insert, kill, or move
|
|
:END:
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbdkey(M-,left)}}}, ~org-table-move-column-left~ ::
|
|
#+kindex: M-left
|
|
#+findex: org-table-move-column-left
|
|
|
|
Move the current column left.
|
|
|
|
- {{{kbdkey(M-,right)}}}, ~org-table-move-column-right~ ::
|
|
#+kindex: M-right
|
|
#+findex: org-table-move-column-right
|
|
|
|
Move the current column right.
|
|
|
|
- {{{kbdkey(M-S-,left)}}}, ~org-table-delete-column~ ::
|
|
#+kindex: M-S-left
|
|
#+findex: org-table-delete-column
|
|
|
|
Kill the current column.
|
|
|
|
- {{{kbdkey(M-S-,right)}}}, ~org-table-insert-column~ ::
|
|
#+kindex: M-S-right
|
|
#+findex: org-table-insert-column
|
|
|
|
Insert a new column to the left of the cursor position.
|
|
|
|
- {{{kbdkey(M-,up)}}}, ~org-table-move-row-up~ ::
|
|
#+kindex: M-up
|
|
#+findex: org-table-move-row-up
|
|
|
|
Move the current row up.
|
|
|
|
- {{{kbdkey(M-,down)}}}, ~org-table-move-row-down~ ::
|
|
#+kindex: M-down
|
|
#+findex: org-table-move-row-down
|
|
|
|
Move the current row down.
|
|
|
|
- {{{kbdkey(M-S-,up)}}}, ~org-table-kill-row~ :: Kill the current row
|
|
or horizontal line.
|
|
|
|
#+kindex: M-S-up
|
|
#+findex: org-table-kill-row
|
|
|
|
- {{{kbdkey(M-S-,down)}}}, ~org-table-insert-row~ :: Insert a new row
|
|
above the current row. With a prefix argument, the line is
|
|
created below the current one.
|
|
|
|
#+kindex: M-S-down
|
|
#+findex: org-table-insert-row
|
|
|
|
- {{{kbd(C-c -)}}}, ~org-table-insert-hline~ :: Insert a horizontal
|
|
line below current row. With a prefix argument, the line is
|
|
created above the current line.
|
|
|
|
#+kindex: C-c -
|
|
#+findex: org-table-insert-hline
|
|
|
|
- {{{kbdspckey(C-c,RET)}}}, ~org-table-hline-and-move~ :: Insert a
|
|
horizontal line below current row, and move the cursor into the
|
|
row below that line.
|
|
|
|
#+kindex: C-c RET
|
|
#+findex: org-table-hline-and-move
|
|
|
|
- {{{kbd(C-c ^)}}}, ~org-table-sort-lines~ :: Sort the table lines in
|
|
the region. The position of point indicates the column to be
|
|
used for sorting, and the range of lines is the range between the
|
|
nearest horizontal separator lines, or the entire table. If
|
|
point is before the first column, you will be prompted for the
|
|
sorting column. If there is an active region, the mark specifies
|
|
the first line and the sorting column, while point should be in
|
|
the last line to be included into the sorting. The command
|
|
prompts for the sorting type (alphabetically, numerically, or by
|
|
time). When called with a prefix argument, alphabetic sorting
|
|
will be case-sensitive.
|
|
|
|
#+kindex: C-c ^
|
|
#+findex: org-table-sort-lines
|
|
*** Regions
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Manipulate parts of a table
|
|
:END:
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x M-w)}}}, ~org-table-copy-region~ :: Copy a rectangular
|
|
region from a table to a special clipboard. Point and mark
|
|
determine edge fields of the rectangle. If there is no active
|
|
region, copy just the current field. The process ignores
|
|
horizontal separator lines.
|
|
|
|
#+kindex: C-c C-x M-w
|
|
#+findex: org-table-copy-region
|
|
- {{{kbd(C-c C-x C-w)}}}, ~org-table-cut-region~ :: Copy a rectangular
|
|
region from a table to a special clipboard, and blank all fields
|
|
in the rectangle. So this is the ``cut'' operation.
|
|
|
|
#+kindex: C-c C-x C-w
|
|
#+findex: org-table-cut-region
|
|
- {{{kbd(C-c C-x C-y)}}}, ~org-table-paste-rectangle~ :: Paste a
|
|
rectangular region into a table. The upper left corner ends up
|
|
in the current field. All involved fields will be overwritten.
|
|
If the rectangle does not fit into the present table, the table
|
|
is enlarged as needed. The process ignores horizontal separator
|
|
lines.
|
|
|
|
#+kindex: C-c C-x C-y
|
|
#+findex: org-table-paste-rectangle
|
|
- {{{kbdkey(M-,RET)}}}, ~org-table-wrap-region~ :: Split the current
|
|
field at the cursor position and move the rest to the line below.
|
|
If there is an active region, and both point and mark are in the
|
|
same column, the text in the column is wrapped to minimum width
|
|
for the given number of lines. A numeric prefix argument may be
|
|
used to change the number of desired lines. If there is no
|
|
region, but you specify a prefix argument, the current field is
|
|
made blank, and the content is appended to the field above.
|
|
|
|
#+kindex: M-RET
|
|
#+findex: org-table-wrap-region
|
|
*** Calculations
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Sum and copy
|
|
:END:
|
|
#+cindex: formula, in tables
|
|
#+cindex: calculations, in tables
|
|
#+cindex: region, active
|
|
#+cindex: active region
|
|
#+cindex: transient mark mode
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c +)}}}, ~org-table-sum~ :: Sum the numbers in the current
|
|
column, or in the rectangle defined by the active region. The
|
|
result is shown in the echo area and can be inserted with
|
|
{{{kbd(C-y)}}}.
|
|
|
|
#+kindex: C-c +
|
|
#+findex: org-table-sum
|
|
- {{{kbdkey(S-,RET)}}}, ~org-table-copy-down~ :: 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 ~org-table-copy-increment~,
|
|
integer field values will be incremented during copy. Integers
|
|
that are too large will not be incremented. Also, a ~0~ prefix
|
|
argument temporarily disables the increment. This key is also
|
|
used by shift-selection and related modes (see [[Conflicts]]).
|
|
|
|
#+kindex: S-RET
|
|
#+findex: org-table-copy-down
|
|
#+vindex: org-table-copy-increment
|
|
|
|
*** Misc
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Some other useful operations
|
|
:END:
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c `)}}}, ~org-table-edit-field~ :: Edit the current field in
|
|
a separate window. This is useful for fields that are not fully
|
|
visible (see [[Column width and alignment]]). When called with a
|
|
{{{kbd(C-u)}}} prefix, just make the full field visible, so that
|
|
it can be edited in place. When called with two {{{kbd(C-u)}}}
|
|
prefixes, make the editor window follow the cursor through the
|
|
table and always show the current field. The follow mode exits
|
|
automatically when the cursor leaves the table, or when you
|
|
repeat this command with {{{kbd(C-u C-u C-c `)}}}.
|
|
|
|
#+kindex: C-c `
|
|
#+findex: org-table-edit-field
|
|
- {{{kbd(M-x org-table-import)}}} :: Import a file as a table. The
|
|
table should be TAB or whitespace separated. Use, for example,
|
|
to import a spreadsheet table or data from a database, because
|
|
these programs generally can write TAB-separated text files.
|
|
This command works by inserting the file into the buffer and then
|
|
converting the region to a table. Any prefix argument is passed
|
|
on to the converter, which uses it to determine the separator.
|
|
|
|
- {{{kbd(C-c |)}}}, ~org-table-create-or-convert-from-region~ :: Tables
|
|
can also be imported by pasting tabular text into the Org buffer,
|
|
selecting the pasted text with {{{kbd(C-x C-x)}}} and then using
|
|
the {{{kbd(C-c |)}}} command (see [[Creation and conversion]]).
|
|
|
|
#+kindex: C-c |
|
|
#+findex: org-table-create-or-convert-from-region
|
|
- {{{kbd(M-x org-table-export)}}} :: Export the table, by default as a
|
|
TAB-separated file. Use for data exchange with, for example,
|
|
spreadsheet or database programs. The format used to export the
|
|
file can be configured in the variable ~org-table-export-default-format~. You may also use properties ~TABLE_EXPORT_FILE~ and ~TABLE_EXPORT_FORMAT~ to specify the file
|
|
name and the format for table export in a subtree. Org supports
|
|
quite general formats for exported tables. The exporter format
|
|
is the same as the format used by Orgtbl radio tables, see
|
|
[[Translator functions], for a detailed description.
|
|
|
|
#+findex: org-table-export
|
|
#+vindex: org-table-export-default-format
|
|
|
|
If you don't like the automatic table editor because it gets in your
|
|
way on lines which you would like to start with {{{samp(|)}}}, you can
|
|
turn it off with
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-enable-table-editor nil)
|
|
#+end_src
|
|
|
|
|
|
{{{noindent}}} Then the only table command that still works is
|
|
{{{kbd(C-c C-c)}}} to do a manual re-align.
|
|
|
|
** Column width and alignment
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Overrule the automatic settings
|
|
:END:
|
|
#+cindex: narrow columns in tables
|
|
#+cindex: alignment in tables
|
|
|
|
The width of columns is automatically determined by the table editor.
|
|
And also the alignment of a column is determined automatically from
|
|
the fraction of number-like versus non-number fields in the column.
|
|
|
|
Sometimes a single field or a few fields need to carry more text,
|
|
leading to inconveniently wide columns. Or maybe you want to make a
|
|
table with several columns having a fixed width, regardless of
|
|
content. To set the width of a column, one field anywhere in the
|
|
column may contain just the string ~<N>~ where ~N~
|
|
is an integer specifying the width of the column in characters.[fn:23]
|
|
The next re-align will then set the width of this column to this
|
|
value.
|
|
|
|
#+begin_example
|
|
|---+------------------------------| |---+--------|
|
|
| | | | | <6> |
|
|
| 1 | one | | 1 | one |
|
|
| 2 | two | ----\ | 2 | two |
|
|
| 3 | This is a long chunk of text | ----/ | 3 | This=> |
|
|
| 4 | four | | 4 | four |
|
|
|---+------------------------------| |---+--------|
|
|
#+end_example
|
|
|
|
{{{noindent}}} Fields that are wider become clipped and end in the
|
|
string {{{samp(=>)}}}. Note that the full text is still in the buffer
|
|
but is hidden. To see the full text, hold the mouse over the
|
|
field---a tool-tip window will show the full content. To edit such a
|
|
field, use the command {{{kbd(C-c `)}}} (that is {{{kbd(C-c)}}}
|
|
followed by the backquote). This will open a new window with the full
|
|
field. Edit it and finish with {{{kbd(C-c C-c)}}}.
|
|
|
|
#+vindex: org-startup-align-all-tables
|
|
|
|
When visiting a file containing a table with narrowed columns, the
|
|
necessary character hiding has not yet happened, and the table needs
|
|
to be aligned before it looks nice. Setting the option
|
|
~org-startup-align-all-tables~ will realign all tables in a file upon
|
|
visiting, but also slow down startup. You can also set this option on
|
|
a per-file basis with:
|
|
|
|
#+begin_src org
|
|
,#+STARTUP: align
|
|
,#+STARTUP: noalign
|
|
#+end_src
|
|
|
|
If you would like to overrule the automatic alignment of number-rich
|
|
columns to the right and of string-rich columns to the left, you can
|
|
use ~<r>~, ~<c>~ or ~<l>~ in a similar fashion.[fn:24] You may also
|
|
combine alignment and field width like this: ~<l10>~.
|
|
|
|
A line that only contains these formatting cookies will be removed
|
|
automatically when exporting the document.
|
|
|
|
** Column groups
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Grouping to trigger vertical lines
|
|
:END:
|
|
#+cindex: grouping columns in tables
|
|
|
|
When Org exports tables, it does so by default without vertical lines
|
|
because that is visually more satisfying in general. Occasionally
|
|
however, vertical lines can be useful to structure a table into groups
|
|
of columns, much like horizontal lines can do for groups of rows. In
|
|
order to specify column groups, you can use a special row where the
|
|
first field contains only {{{samp(/)}}}. The further fields can either
|
|
contain ~<~ to indicate that this column should start a group,
|
|
~>~ to indicate the end of a column, or ~<>~ (no space
|
|
between ~<~ and ~>~) to make a column a group of its own. Boundaries
|
|
between column groups will upon export be marked with vertical lines.
|
|
Here is an example:
|
|
|
|
#+begin_src org
|
|
| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
|
|
|---+-----+-----+-----+---------+------------|
|
|
| / | < | | > | < | > |
|
|
| 1 | 1 | 1 | 1 | 1 | 1 |
|
|
| 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
|
|
| 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
|
|
|---+-----+-----+-----+---------+------------|
|
|
,#+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
|
|
#+end_src
|
|
|
|
It is also sufficient to just insert the column group starters after
|
|
every vertical line you would like to have:
|
|
|
|
#+begin_src org
|
|
| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
|
|
|----+-----+-----+-----+---------+------------|
|
|
| / | < | | | < | |
|
|
#+end_src
|
|
|
|
** The Orgtbl mode minor mode
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The table editor as minor mode
|
|
:ALT_TITLE: Ogtbl mode
|
|
:END:
|
|
#+cindex: Orgtbl mode
|
|
#+cindex: minor mode for tables
|
|
|
|
If you like the intuitive way the Org table editor works, you might
|
|
also want to use it in other modes like Text mode or Mail mode. The
|
|
minor mode Orgtbl mode makes this possible. You can always toggle the
|
|
mode with {{{kbd(M-x orgtbl-mode)}}}. To turn it on by default, for
|
|
example in Message mode, use
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(add-hook 'message-mode-hook 'turn-on-orgtbl)
|
|
#+end_src
|
|
|
|
Furthermore, with some special setup, it is possible to maintain
|
|
tables in arbitrary syntax with Orgtbl mode. For example, it is
|
|
possible to construct LaTeX tables with the underlying ease and
|
|
power of Orgtbl mode, including spreadsheet capabilities. For
|
|
details, see [[Tables in arbitrary syntax]].
|
|
|
|
** The spreadsheet
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The table editor has spreadsheet capabilities
|
|
:END:
|
|
#+cindex: calculations, in tables
|
|
#+cindex: spreadsheet capabilities
|
|
#+cindex: @file{calc} package
|
|
|
|
The table editor makes use of the Emacs {{{file(calc)}}} package to
|
|
implement spreadsheet-like capabilities. It can also evaluate Emacs
|
|
Lisp forms to derive fields from other fields. While fully featured,
|
|
Org's implementation is not identical to other spreadsheets. For
|
|
example, Org knows the concept of a /column formula/ that will be
|
|
applied to all non-header fields in a column without having to copy
|
|
the formula to each relevant field. There is also a formula debugger,
|
|
and a formula editor with features for highlighting fields in the
|
|
table corresponding to the references at the point in the formula,
|
|
moving these references by arrow keys
|
|
|
|
*** References
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to refer to another field or range
|
|
:END:
|
|
#+cindex: references
|
|
|
|
To compute fields in the table from other fields, formulas must
|
|
reference other fields or ranges. In Org, fields can be referenced by
|
|
name, by absolute coordinates, and by relative coordinates. To find
|
|
out what the coordinates of a field are, press {{{kbd(C-c ?)}}} in
|
|
that field, or press {{{kbd(C-c })}}} to toggle the display of a
|
|
grid.
|
|
|
|
**** Field references
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Refer to a particular field
|
|
:END:
|
|
#+cindex: field references
|
|
#+cindex: references, to fields
|
|
|
|
Formulas can reference the value of another field in two ways. Like
|
|
in any other spreadsheet, you may reference fields with a
|
|
letter/number combination like ~B3~, meaning the 2nd field in the 3rd
|
|
row.
|
|
|
|
#+vindex: org-table-use-standard-references
|
|
However, Org prefers to use another, more general representation that
|
|
looks like this:[fn:25]
|
|
|
|
#+begin_example
|
|
@ROW$COLUMN
|
|
#+end_example
|
|
|
|
Column specifications can be absolute like ~$1~, ~$2~, ..., ~$N~, or
|
|
relative to the current column (i.e., the column of the field which is
|
|
being computed) like ~$+1~ or ~$-2~. ~$<~ and ~$>~ are immutable
|
|
references to the first and last column, respectively, and you can use
|
|
~$>>>~ to indicate the third column from the right.
|
|
|
|
The row specification only counts data lines and ignores horizontal
|
|
separator lines (hlines). Like with columns, you can use absolute row
|
|
numbers ~@1~, ~@2~, ..., ~@N~, and row numbers relative to the current
|
|
row like ~@+3~ or ~@-1~. ~@<~ and ~@>~ are immutable references the
|
|
first and last row in the table, respectively.[fn:26] You may also
|
|
specify the row relative to one of the hlines: ~@I~ refers to the
|
|
first hline, ~@II~ to the second, etc. ~@-I~ refers to the first such
|
|
line above the current line, ~@+I~ to the first such line below the
|
|
current line. You can also write ~@III+2~ which is the second data
|
|
line after the third hline in the table.
|
|
~@0~ and ~$0~ refer to the current row and column, respectively, i.e.,
|
|
to the row/column for the field being computed. Also, if you omit
|
|
either the column or the row part of the reference, the current
|
|
row/column is implied.
|
|
|
|
Org's references with /unsigned/ numbers are fixed references in the
|
|
sense that if you use the same reference in the formula for two
|
|
different fields, the same field will be referenced each time. Org's
|
|
references with /signed/ numbers are floating references because the
|
|
same reference operator can reference different fields depending on
|
|
the field being calculated by the formula.
|
|
|
|
Here are a few examples:
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- @2$3 :: 2nd row, 3rd column (same as ~C2~)
|
|
- $5 :: column 5 in the current row (same as ~E&~)
|
|
- @2 :: current column, row 2
|
|
- @-1$-3 :: the field one row up, three columns to the left
|
|
- @-I$2 :: field just under hline above current row, column 2
|
|
- @>$5 :: field in the last row, in column 5
|
|
|
|
**** Range references
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Refer to a range of fields
|
|
:END:
|
|
#+cindex: range references
|
|
#+cindex: references, to ranges
|
|
|
|
You may reference a rectangular range of fields by specifying two
|
|
field references connected by two dots ~..~. If both fields are in
|
|
the current row, you may simply use ~$2..$7~, but if at least one
|
|
field is in a different row, you need to use the general ~@row$column~
|
|
format at least for the first field (i.e., the reference must start
|
|
with ~@~ in order to be interpreted correctly). Examples:
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- $1..$3 :: first three fields in the current row
|
|
- $P..$Q :: range, using column names (see under Advanced)
|
|
- $<<<..$>> :: start in third column, continue to the one but last
|
|
- @2$1..@4$3 :: six fields between these two fields (same as ~A2..C4~)
|
|
- @-1$-2..@-1 :: three numbers from the column to the left, 2 up to
|
|
current row
|
|
- @I..II :: between first and second hline, short for ~@I..@II~
|
|
|
|
|
|
{{{noindent}}} Range references return a vector of values that can be
|
|
fed into Calc vector functions. Empty fields in ranges are normally
|
|
suppressed, so that the vector contains only the non-empty fields (but
|
|
see the ~E~ mode switch below). If there are no non-empty fields,
|
|
~[0]~ is returned to avoid syntax errors in formulas.
|
|
|
|
**** Field coordinates in formulas
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Refer to fields in Lisp or Calc
|
|
:END:
|
|
#+cindex: field coordinates
|
|
#+cindex: coordinates, of field
|
|
#+cindex: row, of field coordinates
|
|
#+cindex: column, of field coordinates
|
|
|
|
For Calc formulas and Lisp formulas ~@#~ and ~$#~ can be used to get
|
|
the row or column number of the field where the formula result goes.
|
|
The traditional Lisp formula equivalents are ~org-table-current-dline~
|
|
and ~org-table-current-column~. Examples:
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- if(@# % 2, $#, string("")) :: column number on odd lines only
|
|
- $3 = remote(FOO, @#$2) :: copy column 2 from table FOO into
|
|
column 3 of the current table
|
|
|
|
{{{noindent}}} For the second example, table FOO must have at least as
|
|
many rows as the current table. Note that this is inefficient for
|
|
large number of rows.[fn:27]
|
|
|
|
**** Named references
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Name columns or constants
|
|
:END:
|
|
#+cindex: named references
|
|
#+cindex: references, named
|
|
#+cindex: name, of column or field
|
|
#+cindex: constants, in calculations
|
|
#+cindex: #+CONSTANTS
|
|
#+vindex: org-table-formula-constants
|
|
|
|
{{{samp($name)}}} is interpreted as the name of a column, parameter or
|
|
constant. Constants are defined globally through the variable
|
|
~org-table-formula-constants~, and locally (for the file) through a
|
|
line like this example:
|
|
|
|
#+begin_src org
|
|
,#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
|
|
#+end_src
|
|
|
|
{{{noindent}}}
|
|
#+vindex: constants-unit-system
|
|
#+pindex: constants.el
|
|
|
|
Also, properties (see [[Properties and columns]]) can be used as constants
|
|
in table formulas: for a property ~:Xyz:~ use the name ~$PROP_Xyz~,
|
|
and the property will be searched in the current outline entry and in
|
|
the hierarchy above it. If you have the {{{file(constants.el)}}}
|
|
package, it will also be used to resolve constants, including natural
|
|
constants like ~$h~ for Planck's constant, and units like ~$km~ for
|
|
kilometers. Column names and parameters can be specified in special
|
|
table lines. These are described in the section, [[Advanced features]].
|
|
All names must start with a letter, and further consist of letters and
|
|
numbers.[fn:175]
|
|
|
|
**** Remote references
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Refer to information in other tables
|
|
:END:
|
|
#+cindex: remote references
|
|
#+cindex: references, remote
|
|
#+cindex: references, to a different table
|
|
#+cindex: name, of column or field
|
|
#+cindex: constants, in calculations
|
|
#+cindex: #+TBLNAME
|
|
|
|
You may also reference constants, fields and ranges from a different
|
|
table, either in the current file or even in a different file. The
|
|
syntax is
|
|
|
|
#+begin_example
|
|
remote(NAME-OR-ID,REF)
|
|
#+end_example
|
|
|
|
{{{noindent}}} where NAME can be the name of a table in the current
|
|
file as set by a ~#+TBLNAME: NAME~ line before the table. It can also
|
|
be the ID of an entry, even in a different file, and the reference
|
|
then refers to the first table in that entry. REF is an absolute field
|
|
or range reference as described above for example ~@3$3~ or
|
|
~$somename~, valid in the referenced table.
|
|
|
|
*** Formula syntax for Calc
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Using Calc to compute stuff
|
|
:END:
|
|
#+cindex: formula syntax, Calc
|
|
#+cindex: syntax, of formulas
|
|
|
|
A formula can be any algebraic expression understood by the Emacs
|
|
{{{file(Calc)}}} package.[fn:28] Before evaluation by ~calc-eval~ (see
|
|
[[info:calc#Calling Calc from Your Programs][Calling Calc from Your Lisp Programs]]), variable substitution takes
|
|
place according to the rules described above.
|
|
|
|
#+cindex: vectors, in table calculations
|
|
The range vectors can be directly fed into the Calc vector functions
|
|
like ~vmean~ and ~vsum~.
|
|
|
|
#+cindex: format specifier
|
|
#+cindex: mode, for @file{calc}
|
|
#+vindex: org-calc-default-modes
|
|
|
|
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 format, however, has been changed to ~(float 8)~ to keep
|
|
tables compact. The default settings can be configured using the
|
|
variable ~org-calc-default-modes~.
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- p20 :: set the internal Calc calculation precision to 20 digits
|
|
- n3 s3 e2 f4 :: normal, scientific, engineering, or fixed format of
|
|
the result of Calc passed back to Org. Calc
|
|
formatting is unlimited in precision as long as the
|
|
Calc calculation precision is greater.
|
|
- D R :: angle modes: degrees, radians
|
|
- F S :: fraction and symbolic modes
|
|
- N :: interpret all fields as numbers, use 0 for non-numbers
|
|
- E :: keep empty fields in ranges
|
|
- L :: literal
|
|
|
|
{{{noindent}}} Unless you use large integer numbers or
|
|
high-precision-calculation and -display for floating point numbers you
|
|
may alternatively provide a ~printf~ format specifier to reformat the
|
|
Calc result after it has been passed back to Org instead of letting
|
|
Calc already do the formatting.[fn:29] A few examples:
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- $1+$2 :: Sum of first and second field
|
|
- $1+$2;%.2f :: Same, format result to two decimals
|
|
- exp($2)+exp($1) :: Math functions can be used
|
|
- $0;%.1f :: Reformat current cell to 1 decimal
|
|
- ($3-32)*5/9 :: Degrees F -> C conversion
|
|
- $c/$1/$cm :: Hz -> cm conversion, using
|
|
{{{file(constants.el)}}}
|
|
- tan($1);Dp3s1 :: Compute in degrees, precision 3, display SCI 1
|
|
- sin($1);Dp3%.1e :: Same, but use ~printf~ specifier for display
|
|
- vmean($2..$7) :: Compute column range mean, using vector
|
|
function
|
|
- vmean($2..$7);EN :: Same, but treat empty fields as 0
|
|
- taylor($3,x=7,2) :: Taylor series of $3, at x=7, second degree
|
|
|
|
Calc also contains a complete set of logical operations. For example
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- if($1<20,teen,string("")) :: "teen" if age $1 less than 20, else empty
|
|
|
|
|
|
Note that you can also use two org-specific flags ~T~ and ~t~ for
|
|
durations computations [[Duration and time values]].
|
|
|
|
You can add your own Calc functions defined in Emacs Lisp with
|
|
~defmath~ and use them in formula syntax for Calc.
|
|
|
|
*** Emacs Lisp forms as formulas
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Writing formulas in Emacs Lisp
|
|
:ALT_TITLE: Formula syntax for Lisp
|
|
:END:
|
|
#+cindex: Lisp forms, as table formulas
|
|
|
|
It is also possible to write a formula in Emacs Lisp. This can be
|
|
useful for string manipulation and control structures, if Calc's
|
|
functionality is not enough.
|
|
|
|
If a formula starts with a single-quote followed by an opening
|
|
parenthesis, then it is evaluated as a Lisp form. The evaluation
|
|
should return either a string or a number. Just as with
|
|
{{{file(calc)}}} formulas, you can specify modes and a printf format
|
|
after a semicolon.
|
|
|
|
With Emacs Lisp forms, you need to be conscious about the way field
|
|
references are interpolated into the form. By default, a reference
|
|
will be interpolated as a Lisp string (in double-quotes) containing
|
|
the field. If you provide the {{{samp(N)}}} mode switch, all
|
|
referenced elements will be numbers (non-number fields will be zero)
|
|
and interpolated as Lisp numbers, without quotes. If you provide the
|
|
{{{samp(L)}}} flag, all fields will be interpolated literally, without
|
|
quotes. I.e., if you want a reference to be interpreted as a string by
|
|
the Lisp form, enclose the reference operator itself in double-quotes,
|
|
like ~"$3"~. Ranges are inserted as space-separated fields, so you can
|
|
embed them in list or vector syntax.
|
|
|
|
Here are a few examples---note how the {{{samp(N)}}} mode is used when
|
|
we do computations in Lisp.
|
|
|
|
Swap the first two characters of the content of column 1:
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
'(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
|
|
#+end_src
|
|
|
|
Add columns 1 and 2, equivalent to Calc's ~$1+$2~:
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
'(+ $1 $2);N
|
|
#+end_src
|
|
|
|
Compute the sum of columns 1-4, like Calc's ~vsum($1..$4)~}:
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
'(apply '+ '($1..$4));N
|
|
#+end_src
|
|
|
|
*** Duration and time values
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to compute duration and time values
|
|
:END:
|
|
#+cindex: Duration, computing
|
|
#+cindex: Time, computing
|
|
#+vindex: org-table-duration-custom-format
|
|
|
|
If you want to compute time values use the ~T~ flag, either in Calc
|
|
formulas or Elisp formulas:
|
|
|
|
#+begin_example
|
|
| Task 1 | Task 2 | Total |
|
|
|---------+----------+----------|
|
|
| 2:12 | 1:47 | 03:59:00 |
|
|
| 3:02:20 | -2:07:00 | 0.92 |
|
|
#+TBLFM: @2$3=$1+$2;T::@3$3=$1+$2;t
|
|
#+end_example
|
|
|
|
Input duration values must be of the form ~[HH:MM[:SS]~, where seconds
|
|
are optional. With the ~T~ flag, computed durations will be displayed
|
|
as ~HH:MM:SS~ (see the first formula above). With the ~t~ flag,
|
|
computed durations will be displayed according to the value of the
|
|
variable ~org-table-duration-custom-format~, which defaults to
|
|
~'hours~ and will display the result as a fraction of hours (see the
|
|
second formula in the example above).
|
|
|
|
Negative duration values can be manipulated as well, and integers will
|
|
be considered as seconds in addition and subtraction.
|
|
|
|
*** Field and range formulas
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Formulas for specific (ranges of) fields
|
|
:END:
|
|
#+cindex: field formula
|
|
#+cindex: range formula
|
|
#+cindex: formula, for individual table field
|
|
#+cindex: formula, for range of fields
|
|
|
|
To assign a formula to a particular field, type it directly into the
|
|
field, preceded by ~:=~, for example ~vsum(@II..III)~. When you press
|
|
{{{key(TAB)}}} or {{{key(RET)}}} or {{{kbd(C-c C-c)}}} with the cursor
|
|
still in the field, the formula will be stored as the formula for this
|
|
field, evaluated, and the current field will be replaced with the
|
|
result.
|
|
|
|
#+cindex: #+TBLFM
|
|
Formulas are stored in a special line starting with ~#+TBLFM:~
|
|
directly below the table. If you type the equation in the fourth field
|
|
of the third data line in the table, the formula will look like
|
|
~@3$4=$1+$2~. When inserting/deleting/swapping column and rows with
|
|
the appropriate commands, /absolute references/ (but not relative
|
|
ones) in stored formulas are modified in order to still reference the
|
|
same field. To avoid this from happening, in particular in range
|
|
references, anchor ranges at the table borders (using ~@<~, ~@>~,
|
|
~$<~, ~$>~), or at hlines using the ~@I~ notation. Automatic
|
|
adaptation of field references does of course not happen if you edit
|
|
the table structure with normal editing commands---then you must fix
|
|
the equations yourself.
|
|
|
|
Instead of typing an equation into the field, you may also use the
|
|
following command
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-u C-c =)}}}, ~org-table-eval-formula~ :: Install a new
|
|
formula for the current field. The command prompts for a
|
|
formula with default taken from the {{{samp(#+TBLFM:)}}} line,
|
|
applies it to the current field, and stores it.
|
|
|
|
#+kindex: C-u C-c =
|
|
#+findex: org-table-eval-formula
|
|
The left-hand side of a formula can also be a special expression in
|
|
order to assign the formula to a number of different fields. There is
|
|
no keyboard shortcut to enter such range formulas. To add them, use
|
|
the formula editor (see [[Editing and debugging formulas]]) or edit the
|
|
~#+TBLFM:~ line directly.
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- $2= :: Column formula, valid for the entire column. This is so
|
|
common that Org treats these formulas in a special way, see
|
|
[[Column formulas]].
|
|
- @3= :: Row formula, applies to all fields in the specified row. ~@@>=~ means the last row.
|
|
- @1$2..@4$3= :: Range formula, applies to all fields in the given
|
|
rectangular range. This can also be used to
|
|
assign a formula to some but not all fields in a
|
|
row.
|
|
- $name= :: Named field, see [[Advanced features]].
|
|
|
|
*** Column formulas
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Formulas valid for an entire column
|
|
:END:
|
|
#+cindex: column formula
|
|
#+cindex: formula, for table column
|
|
|
|
When you assign a formula to a simple column reference like ~$3=~, the
|
|
same formula will be used in all fields of that column, with the
|
|
following very convenient exceptions:
|
|
|
|
- If the table contains horizontal separator hlines with rows above
|
|
and below, everything before the first such hline is considered
|
|
part of the table /header/ and will not be modified by column
|
|
formulas. Therefore a header is mandatory when you use column
|
|
formulas and want to add hlines to group rows, like for example
|
|
to separate a total row at the bottom from the summand rows
|
|
above.
|
|
|
|
- Fields that already get a value from a field/range formula will
|
|
be left alone by column formulas. These conditions make column
|
|
formulas very easy to use.
|
|
|
|
To assign a formula to a column, type it directly into any field in
|
|
the column, preceded by an equal sign, like {{{samp(=$1+$2)}}}. When
|
|
you press {{{key(TAB)}}} or {{{key(RET)}}} or {{{kbd(C-c C-c)}}} with
|
|
the cursor still in the field, the formula will be stored as the
|
|
formula for the current column, evaluated and the current field
|
|
replaced with the result. If the field contains only {{{samp(=)}}},
|
|
the previously stored formula for this column is used. For each
|
|
column, Org will only remember the most recently used formula. In the
|
|
{{{samp(#+TBLFM:)}}} line, column formulas will look like
|
|
{{{samp($4=$1+$2)}}}. The left-hand side of a column formula can not
|
|
be the name of column, it must be the numeric column reference or
|
|
~$>~.
|
|
|
|
Instead of typing an equation into the field, you may also use the
|
|
following command:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c =)}}}, ~org-table-eval-formula~ :: Install a new formula
|
|
for the current column and replace current field with the
|
|
result of the formula. The command prompts for a formula, with
|
|
default taken from the {{{samp(#+TBLFM)}}} line, applies it to
|
|
the current field and stores it. With a numeric prefix
|
|
argument(e.g., {{{kbd(C-5 C-c =)}}}) the command will apply it
|
|
to that many consecutive fields in the current column.
|
|
|
|
#+kindex: C-c =
|
|
#+findex: org-table-eval-formula
|
|
*** Lookup functions
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Lookup functions for searching tables
|
|
:END:
|
|
#+cindex: lookup functions in tables
|
|
#+cindex: table lookup functions
|
|
|
|
Org has three predefined Emacs Lisp functions for lookups in tables.
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE) :: Searches
|
|
for the first element ~S~ in list ~S-LIST~ for which
|
|
|
|
#+findex: org-lookup-first
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(PREDICATE VAL S)
|
|
#+end_src
|
|
is ~t~; returns the value from the corresponding position in
|
|
list ~R-LIST~. The default ~PREDICATE~ is ~equal~. Note that
|
|
the parameters ~VAL~ and ~S~ are passed to ~PREDICATE~ in the
|
|
same order as the correspoding parameters are in the call to ~org-lookup-first~, where ~VAL~ precedes ~S-LIST~. If ~R-LIST~
|
|
is ~nil~, the matching element ~S~ of ~S-LIST~ is returned.
|
|
- (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE) :: Similar
|
|
to ~org-lookup-first~ above, but searches for the /last/
|
|
element for which ~PREDICATE~ is ~t~.
|
|
|
|
#+findex: org-lookup-last
|
|
- (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE) :: Similar
|
|
to ~org-lookup-first~, but searches for /all/ elements for
|
|
which ~PREDICATE~ is ~t~, and returns /all/ corresponding
|
|
values. This function can not be used by itself in a formula,
|
|
because it returns a list of values. However, powerful lookups
|
|
can be built when this function is combined with other Emacs
|
|
Lisp functions.
|
|
|
|
#+findex: org-lookup-all
|
|
|
|
If the ranges used in these functions contain empty fields, the ~E~
|
|
mode for the formula should usually be specified: otherwise empty
|
|
fields will not be included in ~S-LIST~ and/or ~R-LIST~ which can, for
|
|
example, result in an incorrect mapping from an element of ~S-LIST~ to
|
|
the corresponding element of ~R-LIST~.
|
|
|
|
These three functions can be used to implement associative arrays,
|
|
count matching cells, rank results, group data, etc. For practical
|
|
examples see [[http://orgmode.org/worg/org-tutorials/org-lookups.html][this tutorial on Worg]].
|
|
|
|
*** Editing and debugging formulas
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Fixing formulas
|
|
:END:
|
|
#+cindex: formula editing
|
|
#+cindex: editing, of table formulas
|
|
|
|
#+vindex: org-table-use-standard-references You can edit
|
|
individual formulas in the minibuffer or directly in the field. Org
|
|
can also prepare a special buffer with all active formulas of a table.
|
|
When offering a formula for editing, Org converts references to the
|
|
standard format (like ~B3~ or ~D&~) if possible. If you prefer to
|
|
only work with the internal format (like ~@3$2~ or ~$4~), configure
|
|
the variable ~org-table-use-standard-references~.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c =)}}} or {{{kbd(C-u C-c =)}}}, ~org-table-eval-formula~ ::
|
|
|
|
Edit the formula associated with the current column/field in the
|
|
minibuffer. See [[Column formulas]], and [[Field and range formulas]].
|
|
|
|
#+kindex: C-c =
|
|
#+kindex: C-u C-c =
|
|
#+findex: org-table-eval-formula
|
|
- {{{kbd(C-u C-u C-c =)}}}, ~org-table-eval-formula~ :: Re-insert the
|
|
active formula (either a field formula, or a column formula)
|
|
into the current field, so that you can edit it directly in the
|
|
field. The advantage over editing in the minibuffer is that
|
|
you can use the command {{{kbd(C-c ?)}}}.
|
|
|
|
#+kindex: C-u C-u C-c =
|
|
#+findex: org-table-eval-formula
|
|
|
|
- {{{kbd(C-c ?)}}}, ~org-table-field-info~ :: While editing a formula
|
|
in a table field, highlight the field(s) referenced by the
|
|
reference at the cursor position in the formula.
|
|
|
|
#+kindex: C-c ?
|
|
#+findex: org-table-field-info
|
|
|
|
- {{{kbd(C-c })}}}, ~org-table-toggle-coordinate-overlays~ :: Toggle
|
|
the display of row and column numbers for a table, using
|
|
overlays ({{{command(org-table-toggle-coordinate-overlays)}}}).
|
|
These are updated each time the table is aligned; you can force
|
|
it with {{{kbd(C-c C-c)}}}.
|
|
|
|
#+kindex: C-c @}
|
|
#+findex: org-table-toggle-coordinate-overlays
|
|
|
|
- {{{kbd(C-c {)}}}, ~org-table-toggle-formula-debugger~ :: Toggle
|
|
the formula debugger on and off. See below.
|
|
|
|
#+kindex: C-c @{
|
|
#+findex: org-table-toggle-formula-debugger
|
|
|
|
- {{{kbd(C-c ')}}}, ~org-table-edit-formulas~ :: Edit all formulas
|
|
for the current table in a special buffer, where the formulas
|
|
will be displayed one per line. If the current field has an
|
|
active formula, the cursor in the formula editor will mark it.
|
|
While inside the special buffer, Org will automatically
|
|
highlight any field or range reference at the cursor position.
|
|
You may edit, remove and add formulas, and use the following
|
|
commands:
|
|
|
|
#+kindex: C-c '
|
|
#+findex: org-table-edit-formulas
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-c)}}} or {{{kbd(C-x C-s)}}}, ~org-table-fedit-finish~ ::
|
|
|
|
Exit the formula editor and store the modified formulas. With
|
|
{{{kbd(C-u)}}} prefix, also apply the new formulas to the
|
|
entire table.
|
|
|
|
#+kindex: C-x C-s
|
|
#+kindex: C-c C-c
|
|
#+findex: org-table-fedit-finish
|
|
- {{{kbd(C-c C-q)}}}, ~org-table-fedit-abort~ :: Exit the formula
|
|
editor without installing changes.
|
|
|
|
#+kindex: C-c C-q
|
|
#+findex: org-table-fedit-abort
|
|
- {{{kbd(C-c C-r)}}}, ~org-table-fedit-toggle-ref-type~ :: Toggle all
|
|
references in the formula editor between standard (like ~B3~)
|
|
and internal (like ~@3$2~).
|
|
|
|
#+kindex: C-c C-r
|
|
#+findex: org-table-fedit-toggle-ref-type
|
|
- {{{key(TAB)}}}, ~org-table-fedit-lisp-indent~ :: Pretty-print or
|
|
indent Lisp formula at point. When in a line containing a Lisp
|
|
formula, format the formula according to Emacs Lisp rules.
|
|
Another {{{key(TAB)}}} collapses the formula back again. In
|
|
the open formula, {{{key(TAB)}}} re-indents just like in Emacs
|
|
Lisp mode.
|
|
|
|
#+kindex: TAB
|
|
#+findex: org-table-fedit-lisp-indent
|
|
- {{{kbdkey(M-,TAB)}}}, ~lisp-complete-symbol~ :: Complete Lisp
|
|
symbols, just like in Emacs Lisp mode.
|
|
|
|
#+kindex: M-TAB
|
|
#+findex: lisp-complete-symbol
|
|
- {{{kbdkey(S-,up)}}}/{{{key(down)}}}/{{{key(left)}}}/{{{key(right)}}} :: Shift
|
|
the reference at point. For example, if the reference is ~B3~
|
|
and you press {{{kbdkey(S-,right)}}}, it will become ~C3~.
|
|
This also works for relative references and for hline
|
|
references.
|
|
|
|
#+kindex: S-up
|
|
#+kindex: S-down
|
|
#+kindex: S-left
|
|
#+kindex: S-right
|
|
#+findex: org-table-fedit-ref-up
|
|
#+findex: org-table-fedit-ref-down
|
|
#+findex: org-table-fedit-ref-left
|
|
#+findex: org-table-fedit-ref-right
|
|
- {{{kbdkey(M-S-,up)}}}, ~org-table-fedit-line-up~ ::
|
|
|
|
Move the test line for column formulas up in the Org buffer.
|
|
|
|
#+kindex: M-S-up
|
|
#+findex: org-table-fedit-line-up
|
|
|
|
- {{{kbdkey(M-S-,down)}}}, ~org-table-fedit-line-down~ ::
|
|
|
|
Move the test line for column formulas down in the Org buffer.
|
|
|
|
#+kindex: M-S-down
|
|
#+findex: org-table-fedit-line-down
|
|
|
|
- {{{kbdkey(M-,up)}}}, ~org-table-fedit-scroll-up~ ::
|
|
|
|
Scroll up the window displaying the table.
|
|
|
|
#+kindex: M-up
|
|
#+findex: org-table-fedit-scroll-up
|
|
|
|
- {{{kbdkey(M-,down)}}}, ~org-table-fedit-scroll-down~ ::
|
|
|
|
Scroll down the window displaying the table.
|
|
|
|
#+kindex: M-down
|
|
#+findex: org-table-fedit-scroll-down
|
|
|
|
- {{{kbd(C-c })}}} :: Turn the coordinate grid in the table on and
|
|
off.
|
|
|
|
#+kindex: C-c @@
|
|
#+findex: org-table-toggle-coordinate-overlays
|
|
|
|
Making a table field blank does not remove the formula associated with
|
|
the field, because that is stored in a different line (the
|
|
{{{samp(#+TBLFM)}}} line)---during the next recalculation the field
|
|
will be filled again. To remove a formula from a field, you have to
|
|
give an empty reply when prompted for the formula, or to edit the
|
|
{{{samp(#+TBLFM)}}} line.
|
|
|
|
#+kindex: C-c C-c
|
|
You may edit the {{{samp(#+TBLFM)}}} directly and re-apply the changed
|
|
equations with {{{kbd(C-c C-c)}}} in that line or with the normal
|
|
recalculation commands in the table.
|
|
|
|
*** Debugging formulas
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Help fixing formulas
|
|
:END:
|
|
|
|
#+cindex: formula debugging
|
|
#+cindex: debugging, of table formulas
|
|
|
|
When the evaluation of a formula leads to an error, the field content
|
|
becomes the string {{{samp(#ERROR)}}}. If you would like see what is
|
|
going on during variable substitution and calculation in order to find
|
|
a bug, turn on formula debugging in the ~Tbl~ menu and repeat the
|
|
calculation, for example by pressing {{{kbdspckey(C-u C-u C-c =,RET)}}}
|
|
in a field. Detailed information will be displayed.
|
|
|
|
*** Updating the table
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Recomputing all dependent fields
|
|
:END:
|
|
#+cindex: recomputing table fields
|
|
#+cindex: updating, table
|
|
|
|
Recalculation of a table is normally not automatic, but needs to be
|
|
triggered by a command. See [[Advanced features]], for a way to make
|
|
recalculation at least semi-automatic.
|
|
|
|
In order to recalculate a line of a table or the entire table, use the
|
|
following commands:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c *)}}}, ~org-table-recalculate~ :: Recalculate the
|
|
current row by first applying the stored column formulas from
|
|
left to right, and all field/range formulas in the current row.
|
|
|
|
#+kindex: C-c *
|
|
#+findex: org-table-recalculate
|
|
- {{{kbd(C-u C-c *)}}} or {{{kbd(C-u C-c C-c)}}} :: Recompute the
|
|
entire table, line by line. Any lines before the first hline
|
|
are left alone, assuming that these are part of the table
|
|
header.
|
|
|
|
#+kindex: C-u C-c *
|
|
#+kindex: C-u C-c C-c
|
|
- {{{kbd(C-u C-u C-c *)}}} or {{{kbd(C-u C-u C-c C-c)}}}, ~org-table-iterate~ ::
|
|
|
|
Iterate the table by recomputing it until no further changes
|
|
occur. This may be necessary if some computed fields use the
|
|
value of other fields that are computed /later/ in the
|
|
calculation sequence.
|
|
|
|
#+kindex: C-u C-u C-c *
|
|
#+kindex: C-u C-u C-c C-c
|
|
#+findex: org-table-iterate
|
|
- {{{kbd(M-x org-table-recalculate-buffer-tables)}}} :: Recompute
|
|
all tables in the current buffer.
|
|
|
|
#+findex: org-table-recalculate-buffer-tables
|
|
- {{{kbd(M-x org-table-iterate-buffer-tables)}}} :: Iterate all
|
|
tables in the current buffer, in order to converge
|
|
table-to-table dependencies.
|
|
|
|
#+findex: org-table-iterate-buffer-tables
|
|
*** Advanced features
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Field and column names, parameters, and automatic recalc
|
|
:END:
|
|
If you want the recalculation of fields to happen automatically, or if
|
|
you want to be able to assign /names/ to fields and columns,
|
|
you need to reserve the first column of the table for special marking
|
|
characters.[fn:30]
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-#)}}}, ~org-table-rotate-recalc-marks~ :: Rotate the
|
|
calculation mark in first column through the states {{{samp( )}}}, {{{samp(#)}}}, {{{samp(*)}}}, {{{samp(!)}}},
|
|
{{{samp($)}}}. When there is an active region, change all
|
|
marks in the region.
|
|
|
|
#+kindex: C-#
|
|
#+findex: org-table-rotate-recalc-marks
|
|
Here is an example of a table that collects exam results of students
|
|
and makes use of these features:
|
|
|
|
#+begin_src org
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
| ! | | P1 | P2 | P3 | Tot | |
|
|
| # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
|
|
| ^ | | m1 | m2 | m3 | mt | |
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
| # | Peter | 10 | 8 | 23 | 41 | 8.2 |
|
|
| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
| | Average | | | | 25.0 | |
|
|
| ^ | | | | | at | |
|
|
| $ | max=50 | | | | | |
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
,#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
|
|
#+end_src
|
|
|
|
{{{noindent}}} Important: please note that for these special tables,
|
|
recalculating the table with {{{kbd(C-u C-c *)}}} will only affect
|
|
rows that are marked ~#~ or ~*~, and fields that
|
|
have a formula assigned to the field itself. The column formulas are
|
|
not applied in rows with empty first field.
|
|
|
|
#+cindex: marking characters, tables
|
|
The marking characters have the following meaning:
|
|
#+attr_texinfo: :table-type table :indic @samp
|
|
- ! :: The fields in this line define names for the columns, so that
|
|
you may refer to a column as {{{samp($Tot)}}} instead of
|
|
{{{samp($6)}}}.
|
|
- ^ :: This row defines names for the fields @emph{above} the row.
|
|
With such a definition, any formula in the table may use
|
|
{{{samp($m1)}}} to refer to the value {{{samp(10)}}}. Also,
|
|
if you assign a formula to a names field, it will be stored
|
|
as ~$name= ...~.
|
|
- _ :: Similar to {{{samp(^)}}}, but defines names for the fields in
|
|
the row /below/.
|
|
- $ :: Fields in this row can define /parameters/ for formulas. For
|
|
example, if a field in a {{{samp($)}}} row contains
|
|
{{{samp(max=50)}}}, then formulas in this table can refer to
|
|
the value 50 using {{{samp($max)}}}. Parameters work exactly
|
|
like constants, only that they can be defined on a per-table
|
|
basis.
|
|
- # :: Fields in this row are automatically recalculated when
|
|
pressing {{{key(TAB)}}} or {{{key(RET)}}} or
|
|
{{{kbdkey(S-,TAB)}}} in this row. Also, this row is selected
|
|
for a global recalculation with {{{kbd(C-u C-c *)}}}.
|
|
Unmarked lines will be left alone by this command.
|
|
- * :: 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.
|
|
- \nbsp :: Unmarked lines are exempt from recalculation with {{{kbd(C-u C-c *)}}}. All lines that should be recalculated should be
|
|
marked with ~#~ or ~*~.
|
|
- / :: Do not export this line. Useful for lines that contain the
|
|
narrowing ~<N>~ markers or column group markers.
|
|
|
|
|
|
Finally, just to whet your appetite for what can be done with the
|
|
fantastic {{{file(calc.el)}}} package, here is a table that computes
|
|
the Taylor series of degree ~n~ at location ~x~ for a couple of
|
|
functions.
|
|
|
|
#+begin_src org
|
|
|---+-------------+---+-----+--------------------------------------|
|
|
| | Func | n | x | Result |
|
|
|---+-------------+---+-----+--------------------------------------|
|
|
| # | exp(x) | 1 | x | 1 + x |
|
|
| # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
|
|
| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
|
|
| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
|
|
| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
|
|
| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
|
|
|---+-------------+---+-----+--------------------------------------|
|
|
,#+TBLFM: $5=taylor($2,$4,$3);n3
|
|
#+end_src
|
|
|
|
** Org-Plot
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Plotting from Org tables
|
|
:END:
|
|
#+cindex: graph, in tables
|
|
#+cindex: plot tables using Gnuplot
|
|
#+cindex: #+PLOT
|
|
|
|
Org-Plot can produce 2D and 3D graphs of information stored in org
|
|
tables using [[http://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]]. To see this in action, ensure
|
|
that you have both Gnuplot and Gnuplot-mode installed on your system,
|
|
then call ~org-plot/gnuplot~ on the following table.
|
|
|
|
#+begin_src org
|
|
,#+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 |
|
|
| Morels | 257.56 | 17.67 |
|
|
#+end_src
|
|
|
|
Notice that Org Plot is smart enough to apply the table's headers as
|
|
labels. Further control over the labels, type, content, and appearance
|
|
of plots can be exercised through the ~#+PLOT:~ lines preceding a
|
|
table. See below for a complete list of Org-plot options. For more
|
|
information and examples see the [[http://orgmode.org/worg/org-tutorials/org-plot.html][Org-plot tutorial]].
|
|
|
|
Org-Plot recognizes the following options:
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- set :: Specify any {{{command(gnuplot)}}} option to be set when
|
|
graphing.
|
|
- title :: Specify the title of the plot.
|
|
- ind :: Specify which column of the table to use as the ~x~ axis.
|
|
- deps :: Specify the columns to graph as a Lisp style list,
|
|
surrounded by parentheses and separated by spaces for
|
|
example ~dep:(3 4)~ to graph the third and fourth columns
|
|
(defaults to graphing all other columns aside from the ~ind~ column).
|
|
- type :: Specify whether the plot will be ~2d~, ~3d~, or ~grid~.
|
|
- with :: Specify a ~with~ option to be inserted for every col being
|
|
plotted (e.g., ~lines~, ~points~, ~boxes~, ~impulses~,
|
|
etc.). Defaults to ~lines~.
|
|
- file :: If you want to plot to a file, specify ~"{path/to/desired/output-file}"~.
|
|
- labels :: List of labels to be used for the ~deps~ (defaults to
|
|
the column headers if they exist).
|
|
- line :: Specify an entire line to be inserted in the Gnuplot
|
|
script.
|
|
- map :: When plotting ~3d~ or ~grid~ types, set this to ~t~ to
|
|
graph a flat mapping rather than a ~3d~ slope.
|
|
- timefmt :: Specify format of Org mode timestamps as they will be
|
|
parsed by Gnuplot. Defaults to
|
|
{{{samp(%Y-%m-%d-%H:%M:%S)}}}.
|
|
- 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 ~$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.
|
|
|
|
* Hyperlinks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Notes in context
|
|
:ORDERED: t
|
|
:END:
|
|
#+cindex: hyperlinks
|
|
|
|
Like HTML, Org provides links inside a file, external links to
|
|
other files, Usenet articles, emails, and much more.
|
|
|
|
** Link format
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How links in Org are formatted
|
|
:END:
|
|
#+cindex: link format
|
|
#+cindex: format, of links
|
|
|
|
Org will recognize plain URL-like links and activate them as clickable
|
|
links. The general link format, however, looks like this:
|
|
|
|
#+begin_src org
|
|
[[link][description]] or [[link]]
|
|
#+end_src
|
|
|
|
|
|
{{{noindent}}} Once a link in the buffer is complete (all brackets
|
|
present), Org will change the display so that {{{samp(description)}}}
|
|
is displayed instead of ~[[link][description]]~ and {{{samp(link)}}}
|
|
is displayed instead of ~[[link]]~. Links will be highlighted
|
|
in the face ~org-link~, which by default is an underlined face. You
|
|
can directly edit the visible part of a link. Note that this can be
|
|
either the {{{samp(link)}}} part (if there is no description) or the
|
|
{{{samp(description)}}} part. To edit also the invisible
|
|
{{{samp(link)}}} part, use {{{kbd(C-c C-l)}}} with the cursor on the
|
|
link.
|
|
|
|
If you place the cursor at the beginning or just behind the end of the
|
|
displayed text and press {{{key(BACKSPACE)}}}, you will remove the
|
|
(invisible) bracket at that location. This makes the link incomplete
|
|
and the internals are again displayed as plain text. Inserting the
|
|
missing bracket hides the link internals again. To show the internal
|
|
structure of all links, use the menu entry ~Org->Hyperlinks->Literal
|
|
links~.
|
|
|
|
** Internal links
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Links to other places in the current file
|
|
:END:
|
|
#+cindex: internal links
|
|
#+cindex: links, internal
|
|
#+cindex: targets, for links
|
|
#+cindex: property, CUSTOM_ID
|
|
|
|
If the link does not look like a URL, it is considered to be internal
|
|
in the current file. The most important case is a link like
|
|
~[[#my-custom-id]]~ which will link to the entry with the
|
|
~CUSTOM_ID~ property {{{samp(my-custom-id)}}}. Such custom IDs are
|
|
very good for HTML export (see [[HTML export]]) where they produce pretty
|
|
section links. You are responsible yourself to make sure these custom
|
|
IDs are unique in a file.
|
|
|
|
Links such as the two in the following example:
|
|
|
|
#+begin_example
|
|
[[My Target]] or [[My Target][Find my target]]
|
|
#+end_example
|
|
|
|
{{{noindent}}} lead to a text search in the current file.
|
|
|
|
The link can be followed with {{{kbd(C-c C-o)}}} when the cursor is on
|
|
the link, or with a mouse click (see [[Handling links]]). Links to custom
|
|
IDs will point to the corresponding headline. The preferred match for
|
|
a text link is a /dedicated target/: the same string in double angular
|
|
brackets. Targets may be located anywhere; sometimes it is convenient
|
|
to put them into a comment line. For example
|
|
|
|
#+begin_src org
|
|
# <<My Target>>
|
|
#+end_src
|
|
|
|
{{{noindent}}} In HTML export (see [[HTML export]]), such targets will
|
|
become named anchors for direct access through {{{samp(http)}}}
|
|
links.[fn:31]
|
|
|
|
If no dedicated target exists, Org will search for a headline that is
|
|
exactly the link text but may also include a TODO keyword and
|
|
tags.[fn:32] In non-Org files, the search will look for the words in
|
|
the link text. In the above example the search would be for ~my target~.
|
|
|
|
Following a link pushes a mark onto Org's own mark ring. You can
|
|
return to the previous position with {{{kbd(C-c &)}}}. Using this
|
|
command several times in direct succession goes back to positions
|
|
recorded earlier.
|
|
|
|
** Radio targets
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Automatically create internal links
|
|
:END:
|
|
#+cindex: radio targets
|
|
#+cindex: targets, radio
|
|
#+cindex: links, radio targets
|
|
|
|
Org can automatically turn any occurrences of certain target names in
|
|
normal text into a link. So without explicitly creating a link, the
|
|
text connects to the target radioing its position. Radio targets are
|
|
enclosed by triple angular brackets. For example, a target
|
|
~<<<My Target>>>~ causes each occurrence of ~my target~ in
|
|
normal text to become activated as a link. The Org file is scanned
|
|
automatically for radio targets only when the file is first loaded
|
|
into Emacs. To update the target list during editing, press
|
|
{{{kbd(C-c C-c)}}} with the cursor on or at a target.
|
|
|
|
** External links
|
|
:PROPERTIES:
|
|
:DESCRIPTION: URL-like links to the world
|
|
:END:
|
|
#+cindex: links, external
|
|
#+cindex: external links
|
|
#+cindex: links, external
|
|
#+cindex: Gnus links
|
|
#+cindex: BBDB links
|
|
#+cindex: IRC links
|
|
#+cindex: URL links
|
|
#+cindex: file links
|
|
#+cindex: VM links
|
|
#+cindex: RMAIL links
|
|
#+cindex: WANDERLUST links
|
|
#+cindex: MH-E links
|
|
#+cindex: USENET links
|
|
#+cindex: SHELL links
|
|
#+cindex: Info links
|
|
#+cindex: Elisp links
|
|
|
|
Org supports links to files, websites, Usenet and email messages, BBDB
|
|
database entries and links to both IRC conversations and their logs.
|
|
External links are URL-like locators. They start with a short
|
|
identifying string followed by a colon. There can be no space after
|
|
the colon. The following list shows examples for each link type.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~http://www.astro.uva.nl/~dominik~ :: on the web
|
|
- ~doi:10.1000/182~ :: DOI for an electronic resource
|
|
- ~file:/home/dominik/images/jupiter.jpg~ :: file, absolute path
|
|
- ~/home/dominik/images/jupiter.jpg~ :: same as above
|
|
- ~file:papers/last.pdf~ :: file, relative path
|
|
- ~./papers/last.pdf~ :: same as above
|
|
- ~file:/myself@some.where:papers/last.pdf~ :: file, path on remote machine
|
|
- ~/myself@some.where:papers/last.pdf~ :: same as above
|
|
- ~file:sometextfile::NNN~ :: file, jump to line number
|
|
- ~file:projects.org~ :: another Org file
|
|
- ~file:projects.org::some words~ :: text search in Org file[fn:33]
|
|
- ~file:projects.org::*task title~ :: heading search in Org file
|
|
- ~file+sys:/path/to/file~ :: open via OS, like double-click
|
|
- ~file+emacs:/path/to/file~ :: force opening by Emacs
|
|
- ~docview:papers/last.pdf::NNN~ :: open in doc-view mode at page
|
|
- ~id:B7423F4D-2E8A-471B-8810-C40F074717E9~ :: Link to heading by ID
|
|
- ~news:comp.emacs~ :: Usenet link
|
|
- ~mailto:adent@galaxy.net~ :: Mail link
|
|
- ~vm:folder~ :: VM folder link
|
|
- ~vm:folder#id~ :: VM message link
|
|
- ~vm://myself@some.where.org/folder#id~ :: VM on remote machine
|
|
- ~vm-imap:account:folder~ :: VM IMAP folder link
|
|
- ~vm-imap:account:folder#id~ :: VM IMAP message link
|
|
- ~wl:folder~ :: WANDERLUST folder link
|
|
- ~wl:folder#id~ :: WANDERLUST message link
|
|
- ~mhe:folder~ :: MH-E folder link
|
|
- ~mhe:folder#id~ :: MH-E message link
|
|
- ~rmail:folder~ :: RMAIL folder link
|
|
- ~rmail:folder#id~ :: RMAIL message link
|
|
- ~gnus:group~ :: Gnus group link
|
|
- ~gnus:group#id~ :: Gnus article link
|
|
- ~bbdb:R.*Stallman~ :: BBDB link (with regexp)
|
|
- ~irc:/irc.com/#emacs/bob~ :: IRC link
|
|
- ~info:org#External links~ :: Info node link
|
|
- ~shell:ls *.org~ :: A shell command
|
|
- ~elisp:org-agenda~ :: Interactive Elisp command
|
|
- ~elisp:(find-file-other-frame "Elisp.org")~ :: Elisp form to evaluate
|
|
|
|
|
|
For customizing Org to add new link types [[Adding hyperlink types]].
|
|
|
|
A link should be enclosed in double brackets and may contain a
|
|
descriptive text to be displayed instead of the URL (see [[Link format]]),
|
|
for example:
|
|
|
|
#+begin_src org
|
|
[[http://www.gnu.org/software/emacs/][GNU Emacs]]
|
|
#+end_src
|
|
|
|
{{{noindent}}} If the description is a file name or URL that points to
|
|
an image, HTML export (see [[HTML export]]) will inline the image as a
|
|
clickable button. If there is no description at all and the link
|
|
points to an image, that image will be inlined into the exported HTML
|
|
file.
|
|
|
|
#+cindex: square brackets, around links
|
|
#+cindex: plain text external links
|
|
|
|
Org also finds external links in the normal text and activates them as
|
|
links. If spaces must be part of the link (for example in
|
|
{{{samp(bbdb:Richard Stallman)}}}), or if you need to remove
|
|
ambiguities about the end of the link, enclose them in square
|
|
brackets.
|
|
|
|
** Handling links
|
|
:PROPERTIES:
|
|
:DESCRIPTION: URL-like links to the world
|
|
:END:
|
|
#+cindex: links, handling
|
|
|
|
Org provides methods to create a link in the correct syntax, to
|
|
insert it into an Org file, and to follow the link.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c l)}}}, ~org-store-link~ :: Store a link to the current
|
|
location. This is a /global/ command (you must create the key
|
|
binding yourself) which can be used in any buffer to create a
|
|
link. The link will be stored for later insertion into an Org
|
|
buffer (see below). What kind of link will be created depends
|
|
on the current buffer:
|
|
|
|
#+cindex: storing links
|
|
#+kindex: C-c l
|
|
#+findex: org-store-link
|
|
- Org mode buffers :: For Org files, if there is a ~<<target>>~ at the cursor, the link points to the
|
|
target. Otherwise it points to the current headline, which
|
|
will also be the description.[fn:34]
|
|
|
|
#+vindex: org-link-to-org-use-id
|
|
#+cindex: property, CUSTOM_ID
|
|
#+cindex: property, ID
|
|
|
|
If the headline has a ~CUSTOM_ID~ property, a link to this
|
|
custom ID will be stored. In addition or alternatively
|
|
(depending on the value of ~org-link-to-org-use-id~), a
|
|
globally unique ~ID~ property will be created and/or used to
|
|
construct a link.[fn:176] So using this command in Org buffers will
|
|
potentially create two links: a human-readable link from the
|
|
custom ID, and one that is globally unique and works even if
|
|
the entry is moved from file to file. Later, when inserting
|
|
the link, you need to decide which one to use.
|
|
|
|
- Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus :: Pretty
|
|
much all Emacs mail clients are supported. The link will
|
|
point to the current article, or, in some GNUS buffers, to
|
|
the group. The description is constructed from the author
|
|
and the subject.
|
|
|
|
- Web browsers: W3 and W3M :: Here the link will be the current
|
|
URL, with the page title as description.
|
|
|
|
- Contacts: BBDB :: Links created in a BBDB buffer will point to
|
|
the current entry.
|
|
- Chat: IRC :: For IRC links, if you set the variable ~org-irc-link-to-logs~ to ~t~, a ~file:~
|
|
style link to the relevant point in the logs for
|
|
the current conversation is created. Otherwise an ~irc:/~ style link to the
|
|
user/channel/server under the point will be stored.
|
|
|
|
#+vindex: org-irc-link-to-logs
|
|
|
|
- Other files :: For any other files, the link will point to the
|
|
file, with a search string (see [[Search options]])
|
|
pointing to the contents of the current line. If
|
|
there is an active region, the selected words
|
|
will form the basis of the search string. If the
|
|
automatically created link is not working
|
|
correctly or accurately enough, you can write
|
|
custom functions to select the search string and
|
|
to do the search for particular file types---see
|
|
[[Custom searches]]. The key binding {{{kbd(C-c l)}}}
|
|
is only a suggestion---see [[Installation]].
|
|
|
|
- Agenda view :: When the cursor is in an agenda view, the created
|
|
link points to the entry referenced by the
|
|
current line.
|
|
|
|
- {{{kbd(C-c C-l)}}}, ~org-insert-link~ :: Insert a link.[fn:35] This
|
|
prompts for a link to be inserted into the buffer. You can just
|
|
type a link, using text for an internal link, or one of the
|
|
link type prefixes mentioned in the examples above. The link
|
|
will be inserted into the buffer, along with a
|
|
descriptive text.[fn:36] If some text was selected when this command
|
|
is called, the selected text becomes the default description.
|
|
|
|
#+cindex: link completion
|
|
#+cindex: completion, of links
|
|
#+cindex: inserting links
|
|
#+vindex: org-keep-stored-link-after-insertion
|
|
#+kindex: C-c C-l
|
|
#+findex: org-insert-link
|
|
- Inserting stored links :: All links stored during the current
|
|
session are part of the history for this prompt, so you can
|
|
access them with {{{key(up)}}} and {{{key(down)}}} (or
|
|
{{{kbd(M-p/n)}}}).
|
|
|
|
- Completion support :: Completion with {{{key(TAB)}}} will help
|
|
you to insert valid link prefixes like ~http:~ or ~ftp:~, including the prefixes defined through link
|
|
abbreviations (see [[Link abbreviations]]). If you press
|
|
{{{key(RET)}}} after inserting only the
|
|
{{{var(prefix)}}}, Org will offer specific completion
|
|
support for some link types.[fn:37] For example, if you type
|
|
{{{kbdspckey(file,RET)}}}, file name completion (alternative
|
|
access: {{{kbd(C-u C-c C-l)}}}, see below) will be offered,
|
|
and after {{{kbdspckey(bbdb,RET)}}} you can complete contact
|
|
names.
|
|
|
|
- {{{kbd(C-u C-c C-l)}}} :: When {{{kbd(C-c C-l)}}} is called with a
|
|
{{{kbd(C-u)}}} prefix argument, a link to a file will be
|
|
inserted and you may use file name completion to select the
|
|
name of the file. The path to the file is inserted relative to
|
|
the directory of the current Org file, if the linked file is in
|
|
the current directory or in a sub-directory of it, or if the
|
|
path is written relative to the current directory using
|
|
{{{samp(../)}}}. Otherwise an absolute path is used, if
|
|
possible with {{{samp(~/)}}} for your home directory. You can
|
|
force an absolute path with two {{{kbd(C-u)}}} prefixes.
|
|
|
|
#+cindex: file name completion
|
|
#+cindex: completion, of file names
|
|
#+kindex: C-u C-c C-l
|
|
|
|
- {{{kbd(C-c C-l)}}} (with cursor on existing link) :: When the
|
|
cursor is on an existing link, {{{kbd(C-c C-l)}}} allows you to
|
|
edit the link and description parts of the link.
|
|
|
|
#+cindex: following links
|
|
|
|
- {{{kbd(C-c C-o)}}}, ~org-open-at-point~ :: 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 command 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 timestamp, it compiles the agenda for that
|
|
date. Furthermore, it will visit text and remote files in ~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 ~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. If
|
|
the cursor is on a headline, but not on a link, offer all
|
|
links in the headline and entry text. If you want to setup
|
|
the frame configuration for following links, customize ~org-link-frame-setup~.
|
|
|
|
#+vindex: org-file-apps
|
|
#+vindex: org-link-frame-setup
|
|
#+kindex: C-c C-o
|
|
#+findex: org-open-at-point
|
|
- {{{key(RET)}}} :: When ~org-return-follows-link~ is set,
|
|
{{{key(RET)}}} will also follow the link at
|
|
point.
|
|
|
|
#+vindex: org-return-follows-link
|
|
#+kindex: RET
|
|
- {{{key(mouse-2)}}} or {{{key(mouse-1)}}} :: On links,
|
|
{{{kbd(mouse-2)}}} will open the link just as {{{kbd(C-c C-o)}}} would. Under Emacs 22 and later, {{{kbd(mouse-1)}}}
|
|
will also follow a link.
|
|
|
|
#+kindex: mouse-2
|
|
#+kindex: mouse-1
|
|
- {{{key(mouse-3)}}} :: Like {{{kbd(mouse-2)}}}, but force file
|
|
links to be opened with Emacs, and internal links to be
|
|
displayed in another window.[fn:38]
|
|
|
|
#+vindex: org-display-internal-link-with-indirect-buffer
|
|
#+kindex: mouse-3
|
|
- {{{kbd(C-c C-x C-v)}}}, ~org-toggle-inline-images~ ::
|
|
#+cindex: inlining images
|
|
#+cindex: images, inlining
|
|
#+vindex: org-startup-with-inline-images
|
|
#+cindex: ~inlineimages~, STARTUP keyword
|
|
#+cindex: ~noinlineimages~, STARTUP keyword
|
|
#+kindex: C-c C-x C-v
|
|
#+findex: org-toggle-inline-images
|
|
|
|
Toggle the inline display of linked images. Normally this
|
|
will only inline images that have no description part in the
|
|
link, i.e., images that will also be inlined during export.
|
|
When called with a prefix argument, also display images that
|
|
do have a link description. You can ask for inline images to
|
|
be displayed at startup by configuring the variable ~org-startup-with-inline-images~.[fn:177]
|
|
|
|
- {{{kbd(C-c %)}}}, ~org-mark-ring-push~ ::
|
|
#+kindex: C-c %
|
|
#+findex: org-mark-ring-push
|
|
#+cindex: mark ring
|
|
|
|
Push the current position onto the mark ring, to be able to
|
|
return easily. Commands following an internal link do this
|
|
automatically.
|
|
|
|
- {{{kbd(C-c &)}}}, ~org-mark-ring-goto~ ::
|
|
#+kindex: C-c &
|
|
#+findex: org-mark-ring-goto
|
|
#+cindex: links, returning to
|
|
|
|
Jump back to a recorded position. A position is recorded by
|
|
the commands following internal links, and by {{{kbd(C-c %)}}}. Using this command several times in direct succession
|
|
moves through a ring of previously recorded positions.
|
|
|
|
- {{{kbd(C-c C-x C-n)}}}, ~org-next-link~ ::
|
|
@@info:@itemx@@ {{{kbd(C-c C-x C-p)}}}, ~org-previous-link~
|
|
#+cindex: links, finding next/previous
|
|
|
|
#+kindex: C-c C-x C-p
|
|
#+findex: org-previous-link
|
|
#+kindex: C-c C-x C-n
|
|
#+findex: org-next-link
|
|
|
|
Move forward/backward to the next link in the buffer. At the
|
|
limit of the buffer, the search fails once, and then wraps
|
|
around. The key bindings for this are really too long; you
|
|
might want to bind this also to {{{kbd(C-n)}}} and
|
|
{{{kbd(C-p)}}}
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(add-hook 'org-load-hook
|
|
(lambda ()
|
|
(define-key org-mode-map "\C-n" 'org-next-link)
|
|
(define-key org-mode-map "\C-p" 'org-previous-link)))
|
|
#+end_src
|
|
|
|
** Using links outside Org
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Linking from my C source code?
|
|
:END:
|
|
|
|
You can insert and follow links that have Org syntax not only in Org,
|
|
but in any Emacs buffer. For this, you should create two global
|
|
commands, like this (please select suitable global keys yourself):
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(global-set-key "\C-c L" 'org-insert-link-global)
|
|
(global-set-key "\C-c o" 'org-open-at-point-global)
|
|
#+end_src
|
|
|
|
** Link abbreviations
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Shortcuts for writing complex links
|
|
:END:
|
|
#+cindex: link abbreviations
|
|
#+cindex: abbreviation, links
|
|
|
|
Long URLs can be cumbersome to type, and often many similar links are
|
|
needed in a document. For this you can use link abbreviations. An
|
|
abbreviated link looks like this
|
|
|
|
#+begin_src org
|
|
[[linkword:tag][description]]
|
|
#+end_src
|
|
|
|
#+vindex: org-link-abbrev-alist
|
|
|
|
{{{noindent}}} where the tag is optional. The /linkword/ must be a
|
|
word, starting with a letter, followed by letters, numbers,
|
|
{{{samp(-)}}}, and {{{samp(_)}}}. Abbreviations are resolved
|
|
according to the information in the variable ~org-link-abbrev-alist~
|
|
that relates the linkwords to replacement text. Here is an example:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-link-abbrev-alist
|
|
'(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
|
|
("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
|
|
("google" . "http://www.google.com/search?q=")
|
|
("gmap" . "http://maps.google.com/maps?q=%s")
|
|
("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
|
|
("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
|
|
#+end_src
|
|
|
|
If the replacement text contains the string {{{samp(%s)}}}, it will be
|
|
replaced with the tag. Using {{{samp(%h)}}} instead of {{{samp(%s)}}}
|
|
will url-encode the tag (see the example above, where we need to
|
|
encode the URL parameter.) Using {{{samp(%(my-function))}}} will pass
|
|
the tag to a custom function, and replace it by the resulting string.
|
|
|
|
If the replacement text don't contain any specifier, it will simply be
|
|
appended to the string in order to create the link.
|
|
|
|
Instead of a string, you may also specify a function that will be
|
|
called with the tag as the only argument to create the link.
|
|
|
|
With the above setting, you could link to a specific bug with
|
|
~[[bugzilla:129]]~, search the web for {{{samp(OrgMode)}}} with
|
|
~[[google:OrgMode]]~, show the map location of the Free Software
|
|
Foundation ~[[gmap:51 Franklin Street, Boston]]~ or of Carsten office
|
|
~[[omap:Science Park 904, Amsterdam, The Netherlands]]~ and find out what
|
|
the Org author is doing besides Emacs hacking with ~[[ads:Dominik,C]]~.
|
|
|
|
If you need special abbreviations just for a single Org buffer, you
|
|
can define them in the file with
|
|
|
|
#+cindex: #+LINK
|
|
#+begin_src org
|
|
,#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
|
|
,#+LINK: google http://www.google.com/search?q=%s
|
|
#+end_src
|
|
|
|
{{{noindent}}} In-buffer completion (see [[Completion]]) can be used
|
|
after {{{samp([)}}} to complete link abbreviations. You may also
|
|
define a function 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. You can set the link completion function like this:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(org-link-set-parameter "type" :complete #'some-completion-function)
|
|
#+END_SRC
|
|
|
|
** Search options
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Linking to a specific location
|
|
:END:
|
|
#+cindex: search option in file links
|
|
#+cindex: file links, searching
|
|
|
|
File links can contain additional information to make Emacs jump to a
|
|
particular location in the file when following a link. This can be a
|
|
line number or a search option after a double colon.[fn:39]
|
|
For example, when the command {{{kbd(C-c l)}}} creates a link (see
|
|
[[Handling links]]) to a file, it encodes the words in the current line as
|
|
a search string that can be used to find this line back later when
|
|
following the link with {{{kbd(C-c C-o)}}}.
|
|
|
|
Here is the syntax of the different ways to attach a search to a file
|
|
link, together with an explanation:
|
|
|
|
#+begin_src org
|
|
[[file:~/code/main.c::255]]
|
|
[[file:~/xx.org::My Target]]
|
|
[[file:~/xx.org::*My Target]]
|
|
[[file:~/xx.org::#my-custom-id]]
|
|
[[file:~/xx.org::/regexp/]]
|
|
#+end_src
|
|
|
|
#+attr_texinfo: :indic @code
|
|
- 255 :: Jump to line 255.
|
|
- My Target :: Search for a link target ~<<My Target>>~, or do a text search for {{{samp(my target)}}},
|
|
similar to the search in internal links, see [[Internal links]].
|
|
In HTML export (see [[HTML export]]), such a file link will
|
|
become a HTML reference to the corresponding named anchor in the
|
|
linked file.
|
|
- *My Target :: In an Org file, restrict search to headlines.
|
|
- #my-custom-id :: Link to a heading with a ~CUSTOM_ID~ property
|
|
- /regexp/ :: Do a regular expression search for ~regexp~. This
|
|
uses the Emacs command ~occur~ to list all matches
|
|
in a separate window. If the target file is in
|
|
Org mode, ~org-occur~ is used to create a sparse
|
|
tree with the matches. @c If the target file is a
|
|
directory, @c ~grep~ will be used to search all
|
|
files in the directory.
|
|
|
|
As a degenerate case, a file link with an empty file name can be used
|
|
to search the current file. For example, ~[[file:::find me]]~ does a
|
|
search for ~find me~ in the current file, just as
|
|
~[[find me]]~ would.
|
|
|
|
** Custom searches
|
|
:PROPERTIES:
|
|
:DESCRIPTION: When the default search is not enough
|
|
:END:
|
|
#+cindex: custom search strings
|
|
#+cindex: search strings, custom
|
|
|
|
The default mechanism for creating search strings and for doing the
|
|
actual search related to a file link may not work correctly in all
|
|
cases. For example, BibTeX database files have many entries like
|
|
{{{samp(year="1993")}}} which would not result in good search strings,
|
|
because the only unique identification for a BibTeX entry is the
|
|
citation key.
|
|
|
|
#+vindex: org-create-file-search-functions
|
|
#+vindex: org-execute-file-search-functions
|
|
|
|
If you come across such a problem, you can write custom functions to
|
|
set the right search string for a particular file type, and to do the
|
|
search for the string in the file. Using ~add-hook~, these functions
|
|
need to be added to the hook variables
|
|
~org-create-file-search-functions~ and
|
|
~org-execute-file-search-functions~. See the docstring for these
|
|
variables for more information. Org actually uses this mechanism for
|
|
BibTeX database files, and you can use the corresponding code as an
|
|
implementation example. See the file {{{file(org-bibtex.el)}}}.
|
|
|
|
* TODO items
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Every tree branch can be a TODO item
|
|
:ALT_TITLE: TODO Items
|
|
:END:
|
|
#+cindex: TODO items
|
|
|
|
Org mode does not maintain TODO lists as separate documents.[fn:40]
|
|
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
|
|
methods to give you an overview of all the things that you have to do.
|
|
|
|
** TODO basics
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Marking and displaying TODO entries
|
|
:TITLE: Basic TODO functionality
|
|
:END:
|
|
|
|
Any headline becomes a TODO item when it starts with the word
|
|
{{{samp(TODO)}}}, for example:
|
|
|
|
#+begin_src org
|
|
,*** TODO Write letter to Sam Fortune
|
|
#+end_src
|
|
|
|
{{{noindent}}} The most important commands to work with TODO entries
|
|
are:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-t)}}}, ~org-todo~ ::
|
|
#+kindex: C-c C-t
|
|
#+cindex: cycling, of TODO states
|
|
|
|
Rotate the TODO state of the current item among
|
|
|
|
#+begin_example
|
|
,-> (unmarked) -> TODO -> DONE --.
|
|
'--------------------------------'
|
|
#+end_example
|
|
|
|
The same rotation can also be done ``remotely'' from the timeline and
|
|
agenda buffers with the {{{kbd(t)}}} command key (see [[Agenda commands]]).
|
|
|
|
- {{{kbd(C-u C-c C-t)}}} ::
|
|
#+kindex: 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 [[Per-file keywords]], and [[Setting tags]], for
|
|
more information.
|
|
|
|
#+kindex: S-@key{right}
|
|
#+kindex: S-@key{left}
|
|
|
|
- {{{kbdkey(S-,right)}}} {{{kbdkey(S-,left)}}} ::
|
|
|
|
#+vindex: org-treat-S-cursor-todo-selection-as-state-change
|
|
|
|
Select the following/preceding TODO state, similar to cycling.
|
|
Useful mostly if more than two TODO states are possible
|
|
(see [[TODO extensions]]). See also [[Conflicts]], for a discussion of the
|
|
interaction with ~shift-selection-mode~. See also the variable
|
|
~org-treat-S-cursor-todo-selection-as-state-change~.
|
|
|
|
- {{{kbd(C-c / t)}}}, ~org-show-todo-tree~ ::
|
|
#+kindex: C-c / t
|
|
|
|
#+cindex: sparse tree, for TODO
|
|
#+vindex: org-todo-keywords
|
|
|
|
View TODO items in a /sparse tree/ (see [[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 you can also give a list of keywords
|
|
like ~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 ~org-todo-keywords~. With two prefix
|
|
arguments, find all TODO states, both un-done and done.
|
|
|
|
- {{{kbd(C-c a t)}}}, ~org-todo-list~ ::
|
|
#+kindex: C-c a t
|
|
|
|
Show the global TODO list. Collects the TODO items (with not-DONE states)
|
|
from all agenda files (see [[Agenda views]]) into a single buffer. The new
|
|
buffer will be in ~agenda-mode~, which provides commands to examine and
|
|
manipulate the TODO entries from the new buffer (see [[Agenda commands]]).
|
|
See [[Global TODO list]], for more information.
|
|
|
|
- {{{kbdkey(S-M-,RET)}}}, ~org-insert-todo-heading~ ::
|
|
#+kindex: S-M-@key{RET}
|
|
|
|
Insert a new TODO entry below the current one.
|
|
|
|
|
|
{{{noindent}}}
|
|
#+vindex: org-todo-state-tags-triggers
|
|
Changing a TODO state can also trigger tag changes. See the docstring of the
|
|
option ~org-todo-state-tags-triggers~ for details.
|
|
|
|
** TODO extensions
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Work flow and assignments
|
|
:TITLE: Extended use of TODO keywords
|
|
:END:
|
|
|
|
#+cindex: extended TODO keywords
|
|
|
|
#+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
|
|
with /TODO keywords/ (stored in ~org-todo-keywords~). With special
|
|
setup, the TODO keyword system can work differently in different
|
|
files.
|
|
|
|
Note that /tags/ are another way to classify headlines in general and
|
|
TODO items in particular (see [[Tags]]).
|
|
|
|
*** Workflow states
|
|
:PROPERTIES:
|
|
:DESCRIPTION: From TODO to DONE in steps
|
|
:TITLE: TODO keywords as workflow states
|
|
:END:
|
|
#+cindex: TODO workflow
|
|
#+cindex: workflow states as TODO keywords
|
|
|
|
You can use TODO keywords to indicate different /sequential/ states
|
|
in the process of working on an item, for example:[fn:41]
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-todo-keywords
|
|
'((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
|
|
#+end_src
|
|
|
|
The vertical bar separates the TODO keywords (states that /need
|
|
action/) from the DONE states (which need /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
|
|
|
|
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 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. Or you can use
|
|
{{{kbdkey(S-,left)}}} to go backward through the sequence. If you
|
|
define many keywords, you can use in-buffer completion (see [[Completion]]) or
|
|
even a special one-key selection scheme (see [[Fast access to TODO states]])
|
|
to insert these words into the buffer. Changing a TODO state can be
|
|
logged with a timestamp, see [[Tracking TODO state changes]], for
|
|
more information.
|
|
|
|
*** TODO types
|
|
:PROPERTIES:
|
|
:DESCRIPTION: I do this, Fred does the rest
|
|
:TITLE: TODO keywords as types
|
|
:END:
|
|
#+cindex: TODO types
|
|
#+cindex: names as TODO keywords
|
|
#+cindex: types as TODO keywords
|
|
|
|
The second possibility is to use TODO keywords to indicate different
|
|
/types/ of action items. For example, you might want to indicate
|
|
that items are for ``work'' or ``home''. Or, when you work with several
|
|
people on a single project, you might want to assign action items
|
|
directly to persons, by using their names as TODO keywords. This would
|
|
be set up like this:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
|
|
#+end_src
|
|
|
|
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
|
|
the workings of the command {{{kbd(C-c C-t)}}}.[fn:42] 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
|
|
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
|
|
from all agenda files into a single buffer, you would use the numeric prefix
|
|
argument as well when creating the global TODO list: {{{kbd(C-3 C-c a t)}}}.
|
|
|
|
*** Multiple sets in one file
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Mixing it all, and still finding your way
|
|
:TITLE: Multiple keyword sets in one file
|
|
:END:
|
|
#+cindex: TODO keyword sets
|
|
|
|
Sometimes you may want to use different sets of TODO keywords in
|
|
parallel. For example, you may want to have the basic
|
|
~TODO~ / ~DONE~, but also a workflow for bug fixing, and a
|
|
separate state indicating that an item has been canceled (so it is not
|
|
DONE, but also does not require action). Your setup would then look
|
|
like this:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-todo-keywords
|
|
'((sequence "TODO" "|" "DONE")
|
|
(sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
|
|
(sequence "|" "CANCELED")))
|
|
#+end_src
|
|
|
|
The keywords should all be different, this helps Org mode to keep track
|
|
of which subsequence should be used for a given entry. In this setup,
|
|
{{{kbd(C-c C-t)}}} only operates within a subsequence, so it switches from
|
|
~DONE~ to (nothing) to ~TODO~, and from ~FIXED~ to
|
|
(nothing) to ~REPORT~. Therefore you need a mechanism to initially
|
|
select the correct sequence. Besides the obvious ways like typing a
|
|
keyword or using completion, you may also apply the following commands:
|
|
|
|
#+kindex: C-S-@key{right}
|
|
#+kindex: C-S-@key{left}
|
|
#+kindex: C-u C-u C-c C-t
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-u C-u C-c C-t)}}} {{{kbdkey(C-S-,right)}}} {{{kbdkey(C-S-,left)}}} ::
|
|
|
|
These keys jump from one TODO subset to the next. In the above
|
|
example, {{{kbd(C-u C-u C-c C-t)}}} or {{{kbdkey(C-S-,right)}}}
|
|
would jump from ~TODO~ or ~DONE~ to ~REPORT~, and any of the
|
|
words in the second row to ~CANCELED~. Note that the
|
|
{{{kbd(C-S-)}}} key binding conflict with ~shift-selection-mode~
|
|
(see [[Conflicts]]).
|
|
|
|
- {{{kbdkey(S-,right)}}} {{{kbdkey(S-,left)}}} ::
|
|
#+kindex: S-@key{right}
|
|
#+kindex: S-@key{left}
|
|
|
|
{{{kbdkey(S-,left)}}} and {{{kbdkey(S-,right)}}} walk through /all/
|
|
keywords from all sets, so for example {{{kbdkey(S-,right)}}} would switch
|
|
from ~DONE~ to ~REPORT~ in the example above. See also
|
|
[[Conflicts]], for a discussion of the interaction with ~shift-selection-mode~.
|
|
|
|
*** Fast access to TODO states
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Single letter selection of state
|
|
:END:
|
|
If you would like to quickly change an entry to an arbitrary TODO state
|
|
instead of cycling through the states, you can set up keys for single-letter
|
|
access to the states. This is done by adding the selection character after
|
|
each keyword, in parentheses.[fn:43] For example:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-todo-keywords
|
|
'((sequence "TODO(t)" "|" "DONE(d)")
|
|
(sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
|
|
(sequence "|" "CANCELED(c)")))
|
|
#+end_src
|
|
|
|
#+vindex: org-fast-tag-selection-include-todo
|
|
|
|
If you then press {{{kbd(C-c C-t)}}} followed by the selection key,
|
|
the entry will be switched to this state. {{{kbd(SPC)}}} can be used
|
|
to remove any TODO keyword from an entry.[fn:44]
|
|
|
|
*** Per-file keywords
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Different files, different requirements
|
|
:TITLE: Setting up keywords for individual files
|
|
:END:
|
|
#+cindex: keyword options
|
|
#+cindex: per-file keywords
|
|
#+cindex: #+TODO
|
|
#+cindex: #+TYP_TODO
|
|
#+cindex: #+SEQ_TODO
|
|
|
|
It can be very useful to use different aspects of the TODO mechanism in
|
|
different files. For file-local settings, you need to add special lines
|
|
to the file which set the keywords and interpretation for that file
|
|
only. For example, to set one of the two examples discussed above, you
|
|
need one of the following lines, starting in column zero anywhere in the
|
|
file:
|
|
|
|
#+begin_example
|
|
,#+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
|
|
#+end_example
|
|
|
|
{{{noindent}}} (you may also write ~#+SEQ_TODO~ to be explicit about the
|
|
interpretation, but it means the same as ~#+TODO~), or
|
|
|
|
#+begin_example
|
|
,#+TYP_TODO: Fred Sara Lucy Mike | DONE
|
|
#+end_example
|
|
|
|
A setup for using several sets in parallel would be:
|
|
|
|
#+begin_example
|
|
,#+TODO: TODO | DONE
|
|
,#+TODO: REPORT BUG KNOWNCAUSE | FIXED
|
|
,#+TODO: | CANCELED
|
|
#+end_example
|
|
|
|
#+cindex: completion, of option keywords
|
|
#+kindex: M-@key{TAB}
|
|
{{{noindent}}} To make sure you are using the correct keyword, type
|
|
{{{samp(#+)}}} into the buffer and then use {{{kbdkey(M-,TAB)}}} completion.
|
|
|
|
#+cindex: DONE, final TODO keyword
|
|
Remember that the keywords after the vertical bar (or the last keyword
|
|
if no bar is there) must always mean that the item is DONE (although you
|
|
may use a different word). After changing one of these lines, use
|
|
{{{kbd(C-c C-c)}}} with the cursor still in the line to make the changes
|
|
known to Org mode.[fn:45]
|
|
|
|
*** Faces for TODO keywords
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Highlighting states
|
|
:END:
|
|
#+cindex: faces, for TODO keywords
|
|
#+vindex: org-todo @r{(face)}
|
|
#+vindex: org-done @r{(face)}
|
|
#+vindex: org-todo-keyword-faces
|
|
|
|
Org mode highlights TODO keywords with special faces: ~org-todo~
|
|
for keywords indicating that an item still has to be acted upon, and
|
|
~org-done~ for keywords indicating that an item is finished. If
|
|
you are using more than 2 different states, you might want to use
|
|
special faces for some of them. This can be done using the variable
|
|
~org-todo-keyword-faces~. For example:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-todo-keyword-faces
|
|
'(("TODO" . org-warning) ("STARTED" . "yellow")
|
|
("CANCELED" . (:foreground "blue" :weight bold))))
|
|
#+end_src
|
|
|
|
While using a list with face properties as shown for CANCELED /should/
|
|
work, this does not always seem to be the case. If necessary, define a
|
|
special face and use that. A string is interpreted as a color. The variable
|
|
~org-faces-easy-properties~ determines if that color is interpreted as a
|
|
foreground or a background color.
|
|
|
|
*** TODO dependencies
|
|
:PROPERTIES:
|
|
:DESCRIPTION: When one task needs to wait for others
|
|
:END:
|
|
#+cindex: TODO dependencies
|
|
#+cindex: dependencies, of TODO states
|
|
#+vindex: org-enforce-todo-dependencies
|
|
#+cindex: property, ORDERED
|
|
|
|
The structure of Org files (hierarchy and lists) makes it easy to define TODO
|
|
dependencies. Usually, a parent TODO task should not be marked DONE until
|
|
all subtasks (defined as children tasks) are marked as DONE. And sometimes
|
|
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 ~org-enforce-todo-dependencies~, Org will block entries
|
|
from changing state to DONE while they have children that are not DONE.
|
|
Furthermore, if an entry has a property ~ORDERED~, each of its children
|
|
will be blocked until all earlier siblings are marked DONE. Here is an
|
|
example:
|
|
|
|
#+begin_src org
|
|
,* TODO Blocked until (two) is done
|
|
,** DONE one
|
|
,** TODO two
|
|
|
|
,* Parent
|
|
:PROPERTIES:
|
|
:ORDERED: t
|
|
:END:
|
|
,** TODO a
|
|
,** TODO b, needs to wait for (a)
|
|
,** TODO c, needs to wait for (a) and (b)
|
|
#+end_src
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x o)}}}, ~org-toggle-ordered-property~ ::
|
|
#+kindex: C-c C-x o
|
|
#+vindex: org-track-ordered-property-with-tag
|
|
#+cindex: property, ORDERED
|
|
|
|
Toggle the ~ORDERED~ property of the current entry. A property is used
|
|
for this behavior because this should be local to the current entry, not
|
|
inherited like a tag. However, if you would like to /track/ the value of
|
|
this property with a tag for better visibility, customize the variable ~org-track-ordered-property-with-tag~.
|
|
- {{{kbd(C-u C-u C-u C-c C-t)}}} ::
|
|
#+kindex: C-u C-u C-u C-c C-t
|
|
|
|
Change TODO state, circumventing any state blocking.
|
|
|
|
|
|
#+vindex: org-agenda-dim-blocked-tasks
|
|
|
|
If you set the variable ~org-agenda-dim-blocked-tasks~, TODO entries
|
|
that cannot be closed because of such dependencies will be shown in a dimmed
|
|
font or even made invisible in agenda views (see [[Agenda views]]).
|
|
|
|
#+cindex: checkboxes and TODO dependencies
|
|
#+vindex: org-enforce-todo-dependencies
|
|
|
|
You can also block changes of TODO states by looking at checkboxes
|
|
(see [[Checkboxes]]). If you set the variable
|
|
~org-enforce-todo-checkbox-dependencies~, an entry that has unchecked
|
|
checkboxes will be blocked from switching to DONE.
|
|
|
|
If you need more complex dependency structures, for example dependencies
|
|
between entries in different trees or files, check out the contributed
|
|
module {{{file(org-depend.el)}}}.
|
|
|
|
{{{page}}}
|
|
|
|
** Progress logging
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Dates and notes for progress
|
|
:END:
|
|
#+cindex: progress logging
|
|
#+cindex: logging, of progress
|
|
|
|
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
|
|
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 [[Clocking work time]].
|
|
|
|
*** Closing items
|
|
:PROPERTIES:
|
|
:DESCRIPTION: When was this entry marked DONE?
|
|
:END:
|
|
|
|
The most basic logging is to keep track of /when/ a certain TODO
|
|
item was finished. This is achieved with:[fn:46]
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-log-done 'time)
|
|
#+end_src
|
|
|
|
{{{noindent}}} Then each time you turn an entry from a TODO (not-done)
|
|
state into any of the DONE states, a line {{{samp(CLOSED: [timestamp])}}} will be inserted just after the headline. If you turn
|
|
the entry back into a TODO item through further state cycling, that
|
|
line will be removed again. If you want to record a note along with
|
|
the timestamp, use:[fn:47]
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-log-done 'note)
|
|
#+end_src
|
|
|
|
{{{noindent}}} You will then be prompted for a note, and that note
|
|
will be stored below the entry with a {{{samp(Closing Note)}}}
|
|
heading.
|
|
|
|
In the timeline (see [[Timeline for a single file]]) and in the agenda
|
|
(see [[Weekly/daily agenda]]), you can then use the {{{kbd(l)}}} key to
|
|
display the TODO items with a {{{samp(CLOSED)}}} timestamp on each
|
|
day, giving you an overview of what has been done.
|
|
|
|
*** Tracking TODO state changes
|
|
:PROPERTIES:
|
|
:DESCRIPTION: When did the status change?
|
|
:END:
|
|
#+cindex: drawer, for state change recording
|
|
#+vindex: org-log-states-order-reversed
|
|
#+vindex: org-log-into-drawer
|
|
#+cindex: property, LOG_INTO_DRAWER
|
|
|
|
When TODO keywords are used as workflow states (see [[Workflow
|
|
states]]), you might want to keep track of when a state change occurred
|
|
and maybe take a note about this change. You can either record just a
|
|
timestamp, or a time-stamped note for a change. These records will be
|
|
inserted after the headline as an itemized list, newest first.[fn:48]
|
|
When taking a lot of notes, you might want to get the notes out of the
|
|
way into a drawer (see [[Drawers]]). Customize the variable
|
|
~org-log-into-drawer~ to get this behavior---the recommended drawer
|
|
for this is called ~LOGBOOK~.[fn:178] You can also overrule the setting
|
|
of this variable for a subtree by setting a ~LOG_INTO_DRAWER~
|
|
property.
|
|
|
|
Since it is normally too much to record a note for every state, Org
|
|
mode expects configuration on a per-keyword basis for this. This is
|
|
achieved by adding special markers {{{samp(!)}}} (for a timestamp) or
|
|
{{{samp(@)}}} (for a note with timestamp) in parentheses after each
|
|
keyword. For example, with the setting:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(setq org-todo-keywords
|
|
'((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
|
|
#+end_src
|
|
|
|
{{{noindent}}}
|
|
#+vindex: org-log-done
|
|
|
|
you not only define global TODO keywords and fast access keys, but
|
|
also request that a time is recorded when the entry is set to
|
|
DONE, and that a note is recorded when switching to WAIT or
|
|
CANCELED.[fn:49] 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 /leaving/ the WAIT
|
|
state, if and only if the /target/ state does not configure logging
|
|
for entering it. So it has no effect when switching from WAIT to DONE,
|
|
because DONE is configured to record a timestamp only. But when
|
|
switching from WAIT back to TODO, the {{{samp(/!)}}} in the WAIT
|
|
setting now triggers a timestamp even though TODO has no logging
|
|
configured.
|
|
|
|
To record a timestamp without a note for TODO keywords configured with
|
|
{{{samp(@)}}}, just type {{{kbd(C-c C-c)}}} to enter a blank note
|
|
when prompted.
|
|
|
|
You can use the exact same syntax for setting logging preferences local
|
|
to a buffer:
|
|
|
|
#+begin_example
|
|
,#+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@)
|
|
#+end_example
|
|
|
|
#+cindex: property, LOGGING
|
|
|
|
In order to define logging settings that are local to a subtree or a
|
|
single item, define a LOGGING property in this entry. Any non-empty
|
|
LOGGING property resets all logging settings to nil. You may then turn
|
|
on logging for this specific tree using STARTUP keywords like
|
|
~lognotedone~ or ~logrepeat~, as well as adding state specific
|
|
settings like ~TODO(!)~. For example:
|
|
|
|
#+begin_example
|
|
,* TODO Log each state with only a time
|
|
:PROPERTIES:
|
|
:LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
|
|
:END:
|
|
,* TODO Only log when switching to WAIT, and when repeating
|
|
:PROPERTIES:
|
|
:LOGGING: WAIT(@) logrepeat
|
|
:END:
|
|
,* TODO No logging at all
|
|
:PROPERTIES:
|
|
:LOGGING: nil
|
|
:END:
|
|
#+end_example
|
|
|
|
*** Tracking your habits
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How consistent have you been?
|
|
:END:
|
|
:LOGBOOK:
|
|
- State "DONE" from "DONE" [2013-01-07 Mon 14:10]
|
|
- State "DONE" from "" [2013-01-07 Mon 14:10]
|
|
:END:
|
|
#+cindex: habits
|
|
|
|
Org has the ability to track the consistency of a special category of TODOs,
|
|
called "habits." A habit has the following properties:
|
|
|
|
1. You have enabled the ~habits~ module by customizing the variable ~org-modules~.
|
|
|
|
2. The habit is a TODO item, with a TODO keyword representing an
|
|
open state.
|
|
|
|
3. The property ~STYLE~ is set to the value ~habit~.
|
|
|
|
4. The TODO has a scheduled date, usually with a ~.+~ style repeat
|
|
interval. A ~++~ style may be appropriate for habits with time
|
|
constraints, e.g., must be done on weekends, or a ~+~ style for
|
|
an unusual habit that can have a backlog, e.g., weekly reports.
|
|
|
|
5. The TODO may also have minimum and maximum ranges specified by
|
|
using the syntax {{{samp(.+2d/3d)}}}, which says that you want to
|
|
do the task at least every three days, but at most every two
|
|
days.
|
|
|
|
6. You must also have state logging for the ~DONE~ state enabled
|
|
(see [[Tracking TODO state changes]]), in order for historical
|
|
data to be represented in the consistency graph. If it is not
|
|
enabled it is not an error, but the consistency graphs will be
|
|
largely meaningless.
|
|
|
|
|
|
To give you an idea of what the above rules look like in action, here's an
|
|
actual habit with some history:
|
|
|
|
#+begin_example
|
|
,** TODO Shave
|
|
SCHEDULED: <2009-10-17 Sat .+2d/4d>
|
|
- State "DONE" from "TODO" [2009-10-15 Thu]
|
|
- State "DONE" from "TODO" [2009-10-12 Mon]
|
|
- State "DONE" from "TODO" [2009-10-10 Sat]
|
|
- State "DONE" from "TODO" [2009-10-04 Sun]
|
|
- State "DONE" from "TODO" [2009-10-02 Fri]
|
|
- State "DONE" from "TODO" [2009-09-29 Tue]
|
|
- State "DONE" from "TODO" [2009-09-25 Fri]
|
|
- State "DONE" from "TODO" [2009-09-19 Sat]
|
|
- State "DONE" from "TODO" [2009-09-16 Wed]
|
|
- State "DONE" from "TODO" [2009-09-12 Sat]
|
|
:PROPERTIES:
|
|
:STYLE: habit
|
|
:LAST_REPEAT: [2009-10-19 Mon 00:36]
|
|
:END:
|
|
#+end_example
|
|
|
|
What this habit says is: I want to shave at most every 2 days (given
|
|
by the ~SCHEDULED~ date and repeat interval) and at least every 4
|
|
days. If today is the 15th, then the habit first appears in the agenda
|
|
on Oct 17, after the minimum of 2 days has elapsed, and will appear
|
|
overdue on Oct 19, after four days have elapsed.
|
|
|
|
What's really useful about habits is that they are displayed along
|
|
with a consistency graph, to show how consistent you've been at
|
|
getting that task done in the past. This graph shows every day that
|
|
the task was done over the past three weeks, with colors for each day.
|
|
The colors used are:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~Blue~ :: If the task wasn't to be done yet on that day.
|
|
- ~Green~ :: If the task could have been done on that day.
|
|
- ~Yellow~ :: If the task was going to be overdue the next day.
|
|
- ~Red~ :: If the task was overdue on that day.
|
|
|
|
|
|
In addition to coloring each day, the day is also marked with an
|
|
asterisk if the task was actually done that day, and an exclamation
|
|
mark to show where the current day falls in the graph.
|
|
|
|
There are several configuration variables that can be used to change
|
|
the way habits are displayed in the agenda.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~org-habit-graph-column~ :: The buffer column at which the
|
|
consistency graph should be drawn. This will overwrite any text
|
|
in that column, so it is a good idea to keep your habits'
|
|
titles brief and to the point.
|
|
|
|
- ~org-habit-preceding-days~ :: The amount of history, in days before
|
|
today, to appear in consistency graphs.
|
|
|
|
- ~org-habit-following-days~ :: The number of days after today that
|
|
will appear in consistency graphs.
|
|
|
|
- ~org-habit-show-habits-only-for-today~ :: If non-nil, only show
|
|
habits in today's agenda view. This is set to true by default.
|
|
|
|
|
|
Lastly, pressing {{{kbd(K)}}} in the agenda buffer will cause habits
|
|
to temporarily be disabled and they won't appear at all. Press
|
|
{{{kbd(K)}}} again to bring them back. They are also subject to tag
|
|
filtering, if you have habits which should only be done in certain
|
|
contexts, for example.
|
|
|
|
** FIXME Priorities
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Some things are more important than others
|
|
:END:
|
|
#+cindex: priorities
|
|
|
|
If you use Org mode extensively, you may end up with enough TODO items that
|
|
it starts to make sense to prioritize them. Prioritizing can be done by
|
|
placing a /priority cookie/ into the headline of a TODO item, like this:
|
|
|
|
#+begin_example
|
|
,*** TODO [#A] Write letter to Sam Fortune
|
|
#+end_example
|
|
|
|
#+vindex: org-priority-faces
|
|
|
|
{{{noindent}}} By default, Org mode supports three priorities: {{{samp(A)}}},
|
|
{{{samp(B)}}}, and {{{samp(C)}}}. {{{samp(A)}}} is the highest
|
|
priority. An entry without a cookie is treated just like priority
|
|
{{{samp(B)}}}. Priorities make a difference only for sorting in the
|
|
agenda (see [[Weekly/daily agenda]]); outside the agenda, they have no
|
|
inherent meaning to Org mode. The cookies can be highlighted with
|
|
special faces by customizing the variable ~org-priority-faces~.
|
|
|
|
Priorities can be attached to any outline node; they do not need to be TODO
|
|
items.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c XXX)}}} ::
|
|
#+kindex: C-c ,
|
|
# #+kindex: @key{C-c ,}
|
|
# Preceding line won't export to pdf
|
|
#+findex: org-priority
|
|
# Should be C-c ,
|
|
Set the priority of the current headline (~org-priority~). The
|
|
command prompts for a priority character {{{samp(A)}}}, {{{samp(B)}}}
|
|
or {{{samp(C)}}}. When you press {{{key(SPC)}}}} instead, the priority
|
|
cookie is removed from the headline. The priorities can also be
|
|
changed ``remotely'' from the timeline and agenda buffer with the
|
|
{{{kbd(\,)}}} command (see [[Agenda commands]]).
|
|
|
|
- {{{kbdkey(S-,up)}}}, {{{kbdkey(S-,down)}}}, {{{command(org-priority-up)}}}, {{{command(org-priority-down)}}} ::
|
|
#+vindex: org-priority-start-cycle-with-default
|
|
|
|
Increase/decrease priority of current headline.[fn:50] Note
|
|
that these keys are also used to modify timestamps
|
|
(see [[Creating timestamps]]). See also [[Conflicts]], for a
|
|
discussion of the interaction with ~shift-selection-mode~.
|
|
|
|
|
|
#+vindex: org-highest-priority
|
|
#+vindex: org-lowest-priority
|
|
#+vindex: org-default-priority
|
|
|
|
You can change the range of allowed priorities by setting the
|
|
variables ~org-highest-priority~, ~org-lowest-priority~, and
|
|
~org-default-priority~. For an individual buffer, you may set these
|
|
values (highest, lowest, default) like this (please make sure that the
|
|
highest priority is earlier in the alphabet than the lowest priority):
|
|
|
|
#+cindex: #+PRIORITIES
|
|
|
|
#+begin_example
|
|
,#+PRIORITIES: A C B
|
|
#+end_example
|
|
|
|
** Breaking down tasks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Splitting a task into manageable pieces
|
|
:END:
|
|
#+cindex: tasks, breaking down
|
|
#+cindex: statistics, for TODO items
|
|
#+vindex: org-agenda-todo-list-sublevels
|
|
|
|
It is often advisable to break down large tasks into smaller,
|
|
manageable subtasks. You can do this by creating an outline tree below
|
|
a TODO item, with detailed subtasks on the tree.[fn:51] To keep the
|
|
overview over the fraction of subtasks that are already completed,
|
|
insert either {{{samp([/])}}} or {{{samp([%])}}} anywhere in the
|
|
headline. These cookies will be updated each time the TODO status of a
|
|
child changes, or when pressing {{{kbd(C-c C-c)}}} on the cookie. For
|
|
example:
|
|
|
|
#+begin_example
|
|
,* Organize Party [33%]
|
|
,** TODO Call people [1/2]
|
|
,*** TODO Peter
|
|
,*** DONE Sarah
|
|
,** TODO Buy food
|
|
,** DONE Talk to neighbor
|
|
#+end_example
|
|
|
|
#+cindex: property, COOKIE_DATA
|
|
|
|
If a heading has both checkboxes and TODO children below it, the
|
|
meaning of the statistics cookie become ambiguous. Set the property
|
|
~COOKIE_DATA~ to either {{{samp(checkbox)}}} or {{{samp(todo)}}} to
|
|
resolve this issue.
|
|
|
|
#+vindex: org-hierarchical-todo-statistics
|
|
|
|
If you would like to have the statistics cookie count any TODO entries
|
|
in the subtree (not just direct children), configure the variable
|
|
~org-hierarchical-todo-statistics~. To do this for a single subtree,
|
|
include the word {{{samp(recursive)}}} into the value of the
|
|
~COOKIE_DATA~ property.
|
|
|
|
#+begin_example
|
|
,* Parent capturing statistics [2/20]
|
|
:PROPERTIES:
|
|
:COOKIE_DATA: todo recursive
|
|
:END:
|
|
#+end_example
|
|
|
|
If you would like a TODO entry to automatically change to DONE
|
|
when all children are done, you can use the following setup:
|
|
|
|
#+header: :exports code
|
|
#+header: :eval no
|
|
#+begin_src emacs-lisp
|
|
(defun org-summary-todo (n-done n-not-done)
|
|
"Switch entry to DONE when all subentries are done, to TODO otherwise."
|
|
(let (org-log-done org-log-states) ; turn off logging
|
|
(org-todo (if (= n-not-done 0) "DONE" "TODO"))))
|
|
|
|
(add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
|
|
#+end_src
|
|
|
|
Another possibility is the use of checkboxes to identify (a hierarchy
|
|
of) a large number of subtasks (see [[Checkboxes]]).
|
|
|
|
** Checkboxes
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tick-off lists
|
|
:END:
|
|
|
|
#+cindex: checkboxes
|
|
#+vindex: org-list-automatic-rules
|
|
|
|
Every item in a plain list (see [[Plain lists]]) can be made into a
|
|
checkbox by starting it with the string {{{samp([ ])}}}.[fn:52] This
|
|
feature is similar to TODO items (see [[TODO items]]), but is more
|
|
lightweight. Checkboxes are not included into the global TODO list, so
|
|
they are often great to split a task into a number of simple steps. Or
|
|
you can use them in a shopping list. To toggle a checkbox, use
|
|
{{{kbd(C-c C-c)}}}, or use the mouse (thanks to Piotr Zielinski's
|
|
{{{file(org-mouse.el)}}}).
|
|
|
|
Here is an example of a checkbox list.
|
|
|
|
#+begin_example
|
|
,* TODO Organize party [2/4]
|
|
- [-] call people [1/3]
|
|
- [ ] Peter
|
|
- [X] Sarah
|
|
- [ ] Sam
|
|
- [X] order food
|
|
- [ ] think about what music to play
|
|
- [X] talk to the neighbors
|
|
#+end_example
|
|
|
|
Checkboxes work hierarchically, so if a checkbox item has children
|
|
that are checkboxes, toggling one of the children checkboxes will make
|
|
the parent checkbox reflect if none, some, or all of the children are
|
|
checked.
|
|
|
|
#+cindex: statistics, for checkboxes
|
|
#+cindex: checkbox statistics
|
|
#+cindex: property, COOKIE_DATA
|
|
#+vindex: org-hierarchical-checkbox-statistics
|
|
|
|
The {{{samp([2/4])}}} and {{{samp([1/3])}}} in the first and second
|
|
line are cookies indicating how many checkboxes present in this entry
|
|
have been checked off, and the total number of checkboxes present.
|
|
This can give you an idea on how many checkboxes remain, even without
|
|
opening a folded entry. The cookies can be placed into a headline or
|
|
into (the first line of) a plain list item. Each cookie covers
|
|
checkboxes of direct children structurally below the headline/item on
|
|
which the cookie appears.[fn:53] You have to insert the cookie
|
|
yourself by typing either {{{samp([/])}}} or {{{samp([%])}}}. With
|
|
{{{samp([/])}}} you get an {{{samp(n out of m)}}} result, as in the
|
|
examples above. With {{{samp([%])}}} you get information about the
|
|
percentage of checkboxes checked (in the above example, this would be
|
|
{{{samp([50%])}}} and {{{samp([33%])}}}, respectively). In a headline,
|
|
a cookie can count either checkboxes below the heading or TODO states
|
|
of children, and it will display whatever was changed last. Set the
|
|
property ~COOKIE_DATA~ to either {{{samp(checkbox)}}} or
|
|
{{{samp(todo)}}} to resolve this issue.
|
|
|
|
#+cindex: blocking, of checkboxes
|
|
#+cindex: checkbox blocking
|
|
#+cindex: property, ORDERED
|
|
|
|
If the current outline node has an ~ORDERED~ property, checkboxes must
|
|
be checked off in sequence, and an error will be thrown if you try to
|
|
check off a box while there are unchecked boxes above it.
|
|
|
|
{{{noindent}}} The following commands work with checkboxes:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(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.[fn:54] With a double prefix argument, set it to
|
|
{{{samp([-])}}}, which is considered to be an intermediate state.
|
|
|
|
- {{{kbd(C-c C-x C-b)}}}, ~org-toggle-checkbox~ :: Toggle checkbox
|
|
status or (with prefix arg) checkbox presence at point. With
|
|
double prefix argument, set it to {{{samp([-])}}}, which is
|
|
considered to be an intermediate state.
|
|
|
|
- If there is an active region, toggle the first checkbox in the region
|
|
and set all remaining boxes to the same status as the first. With a prefix
|
|
arg, add or remove the checkbox for all items in the region.
|
|
|
|
- If the cursor is in a headline, toggle checkboxes in the region
|
|
between this headline and the next (so /not/ the entire subtree).
|
|
|
|
- If there is no active region, just toggle the checkbox at point.
|
|
|
|
|
|
- {{{kbdkey(M-S-,RET)}}}, ~org-insert-todo-heading~ :: Insert a new
|
|
item with a checkbox. This works only if the cursor is already in
|
|
a plain list item (see [[Plain lists]]).
|
|
|
|
- {{{kbd(C-c C-x o)}}}, ~org-toggle-ordered-property~ ::
|
|
#+kindex: C-c C-x o
|
|
#+vindex: org-track-ordered-property-with-tag
|
|
#+cindex: property, ORDERED
|
|
|
|
Toggle the ~ORDERED~ property of the entry, to toggle if checkboxes
|
|
must be checked off in sequence. A property is used for this
|
|
behavior because this should be local to the current entry, not
|
|
inherited like a tag. However, if you would like to /track/ the
|
|
value of this property with a tag for better visibility,
|
|
customize the variable ~org-track-ordered-property-with-tag~.
|
|
|
|
- {{{kbd(C-c #)}}}, ~org-update-statistics-cookies~ ::
|
|
#+kindex: C-c #
|
|
|
|
Update the statistics cookie in the current outline entry. When
|
|
called with a {{{kbd(C-u)}}} prefix, update the entire file.
|
|
Checkbox statistic cookies are updated automatically if you
|
|
toggle checkboxes with {{{kbd(C-c C-c)}}} and make new ones with
|
|
{{{kbdkey(M-S-,RET)}}}. TODO statistics cookies update when
|
|
changing TODO states. If you delete boxes/entries or add/change
|
|
them by hand, use this command to get things back into sync.
|
|
|
|
* Tags
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tagging headlines and matching sets of tags
|
|
:END:
|
|
#+cindex: tags
|
|
#+cindex: headline tagging
|
|
#+cindex: matching, tags
|
|
#+cindex: sparse tree, tag based
|
|
|
|
An excellent way to implement labels and contexts for
|
|
cross-correlating information is to assign /tags/ to headlines. Org
|
|
mode has extensive support for tags.
|
|
|
|
#+vindex: org-tag-faces
|
|
|
|
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:)}}}. Tags will by default be in
|
|
bold face with the same color as the headline. You may specify special
|
|
faces for specific tags using the variable ~org-tag-faces~, in much
|
|
the same way as you can for TODO keywords (see [[Faces for TODO keywords]]).
|
|
|
|
** Tag inheritance
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tags use the tree structure of an outline
|
|
:END:
|
|
#+cindex: tag inheritance
|
|
#+cindex: inheritance, of tags
|
|
#+cindex: sublevels, inclusion into tags match
|
|
/Tags/ make use of the hierarchical structure of outline trees. If a
|
|
heading has a certain tag, all subheadings will inherit the tag as
|
|
well. For example, in the list
|
|
|
|
#+begin_example
|
|
,* Meeting with the French group :work:
|
|
,** Summary by Frank :boss:notes:
|
|
,*** TODO Prepare slides for him :action:
|
|
#+end_example
|
|
|
|
{{{noindent}}} the final heading will have the tags
|
|
{{{samp(:work:)}}}, {{{samp(:boss:)}}}, {{{samp(:notes:)}}}, and
|
|
{{{samp(:action:)}}} even though the final heading is not explicitly
|
|
marked with those tags. You can also set tags that all entries in a
|
|
file should inherit just as if these tags were defined in a
|
|
hypothetical level zero that surrounds the entire file. Use a line
|
|
like this:[fn:55]
|
|
|
|
#+cindex: #+FILETAGS
|
|
#+begin_example
|
|
,#+FILETAGS: :Peter:Boss:Secret:
|
|
#+end_example
|
|
|
|
#+vindex: org-use-tag-inheritance
|
|
#+vindex: org-tags-exclude-from-inheritance
|
|
|
|
{{{noindent}}} To limit tag inheritance to specific tags, or to turn
|
|
it off entirely, use the variables ~org-use-tag-inheritance~ and
|
|
~org-tags-exclude-from-inheritance~.
|
|
|
|
#+vindex: org-tags-match-list-sublevels
|
|
|
|
When a headline matches during a tags search while tag inheritance is
|
|
turned on, all the sublevels in the same tree will (for a simple match
|
|
form) match as well.[fn:56] The list of matches may then become very
|
|
long. If you only want to see the first tags match in a subtree,
|
|
configure the variable ~org-tags-match-list-sublevels~ (not
|
|
recommended).
|
|
|
|
** Setting tags
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to assign tags to a headline
|
|
:END:
|
|
#+cindex: setting tags
|
|
#+cindex: tags, setting
|
|
#+kindex: M-@key{TAB}
|
|
|
|
Tags can simply be typed into the buffer at the end of a headline.
|
|
After a colon, {{{kbdkey(M-,TAB)}}} offers completion on tags. There is
|
|
also a special command for inserting tags:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-q)}}}, ~org-set-tags-command~ ::
|
|
#+kindex: C-c C-q
|
|
|
|
#+cindex: completion, of tags
|
|
#+vindex: org-tags-column
|
|
|
|
Enter new tags for the current headline. Org mode will either offer
|
|
completion or a special single-key interface for setting tags, see
|
|
below. After pressing {{{key(RET)}}}, the tags will be inserted and aligned
|
|
to ~org-tags-column~. When called with a {{{kbd(C-u)}}} prefix, all
|
|
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 (see [[TODO basics]]).
|
|
|
|
- {{{kbd(C-c C-c)}}}, ~org-set-tags-command~ ::
|
|
#+kindex: C-c C-c
|
|
|
|
When the cursor is in a headline, this does the same as {{{kbd(C-c C-q)}}}.
|
|
|
|
|
|
#+vindex: org-tag-alist
|
|
|
|
Org supports tag insertion based on a /list of tags/. By default this
|
|
list is constructed dynamically, containing all tags currently used in
|
|
the buffer. You may also globally specify a hard list of tags with the
|
|
variable ~org-tag-alist~. Finally you can set the default tags for a
|
|
given file with lines like
|
|
|
|
#+cindex: #+TAGS
|
|
#+begin_example
|
|
,#+TAGS: @work @home @tennisclub
|
|
,#+TAGS: laptop car pc sailboat
|
|
#+end_example
|
|
|
|
If you have globally defined your preferred set of tags using the
|
|
variable ~org-tag-alist~, but would like to use a dynamic tag list
|
|
in a specific file, add an empty TAGS option line to that file:
|
|
|
|
#+begin_example
|
|
,#+TAGS:
|
|
#+end_example
|
|
|
|
#+vindex: org-tag-persistent-alist
|
|
|
|
If you have a preferred set of tags that you would like to use in
|
|
every file, in addition to those defined on a per-file basis by TAGS
|
|
option lines, then you may specify a list of tags with the variable
|
|
~org-tag-persistent-alist~. You may turn this off on a per-file basis
|
|
by adding a STARTUP option line to that file:
|
|
|
|
#+begin_example
|
|
,#+STARTUP: noptag
|
|
#+end_example
|
|
|
|
By default Org mode uses the standard minibuffer completion facilities
|
|
for entering tags. However, it also implements another, quicker, tag
|
|
selection method called /fast tag selection/. This allows you to
|
|
select and deselect tags with just a single key press. For this to
|
|
work well you should assign unique letters to most of your commonly
|
|
used tags. You can do this globally by configuring the variable
|
|
~org-tag-alist~ in your {{{file(.emacs)}}} file. For example, you may
|
|
find the need to tag many items in different files with
|
|
{{{samp(:@home:)}}}. In this case you can set something like:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
|
|
#+end_src
|
|
|
|
{{{noindent}}} If the tag is only relevant to the file you are working
|
|
on, then you can instead set the TAGS option line as:
|
|
|
|
#+begin_example
|
|
,#+TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p)
|
|
#+end_example
|
|
|
|
{{{noindent}}} The tags interface will show the available tags in a splash
|
|
window. If you want to start a new line after a specific tag, insert
|
|
~\n~ into the tag list, like this:
|
|
|
|
#+begin_example
|
|
,#+TAGS: @work(w) @home(h) @tennisclub(t) \n laptop(l) pc(p)
|
|
#+end_example
|
|
|
|
{{{noindent}}} or write them in two lines:
|
|
|
|
#+begin_example
|
|
,#+TAGS: @work(w) @home(h) @tennisclub(t)
|
|
,#+TAGS: laptop(l) pc(p)
|
|
#+end_example
|
|
|
|
{{{noindent}}}
|
|
You can also group together tags that are mutually exclusive by using
|
|
braces, as in:
|
|
|
|
#+begin_example
|
|
,#+TAGS: { @work(w) @home(h) @tennisclub(t) } laptop(l) pc(p)
|
|
#+end_example
|
|
|
|
{{{noindent}}} you indicate that at most one of {{{samp(@work)}}},
|
|
{{{samp(@home)}}}, and {{{samp(@tennisclub)}}} should be selected.
|
|
Multiple such groups are allowed.
|
|
|
|
{{{noindent}}} Don't forget to press {{{kbd(C-c C-c)}}} with the
|
|
cursor in one of these lines to activate any changes.
|
|
|
|
{{{noindent}}} To set these mutually exclusive groups in the variable
|
|
~org-tags-alist~, you must use the dummy tags ~:startgroup~ and
|
|
~:endgroup~ instead of the braces. Similarly, you can use ~:newline~
|
|
to indicate a line break. The previous example would be set globally
|
|
by the following configuration:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-tag-alist '((:startgroup . nil)
|
|
("@@work" . ?w) ("@@home" . ?h)
|
|
("@@tennisclub" . ?t)
|
|
(:endgroup . nil)
|
|
("laptop" . ?l) ("pc" . ?p)))
|
|
#+end_src
|
|
|
|
If at least one tag has a selection key then pressing {{{kbd(C-c C-c)}}} will
|
|
automatically present you with a special interface, listing inherited tags,
|
|
the tags of the current headline, and a list of all valid tags with
|
|
corresponding keys.[fn:57] In this interface, you can use the following
|
|
keys:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(a-z...)}}} ::
|
|
#+kindex: a-z...
|
|
|
|
Pressing keys assigned to tags will add or remove them from the list of
|
|
tags in the current line. Selecting a tag in a group of mutually
|
|
exclusive tags will turn off any other tags from that group.
|
|
|
|
- {{{key(TAB)}}} ::
|
|
#+kindex: @key{TAB}
|
|
|
|
Enter a tag in the minibuffer, even if the tag is not in the predefined
|
|
list. You will be able to complete on all tags present in the buffer.
|
|
You can also add several tags: just separate them with a comma.
|
|
|
|
- {{{key(SPC)}}} ::
|
|
#+kindex: @key{SPC}
|
|
|
|
Clear all tags for this line.
|
|
|
|
- {{{key(RET)}}} ::
|
|
#+kindex: @key{RET}
|
|
|
|
Accept the modified set.
|
|
|
|
- C-g ::
|
|
|
|
Abort without installing changes.
|
|
|
|
- q ::
|
|
|
|
If {{{kbd(q)}}} is not assigned to a tag, it aborts like {{{kbd(C-g)}}}.
|
|
|
|
- ! ::
|
|
|
|
Turn off groups of mutually exclusive tags. Use this to (as an
|
|
exception) assign several tags from such a group.
|
|
|
|
- C-c ::
|
|
|
|
Toggle auto-exit after the next change (see below).
|
|
If you are using expert mode, the first {{{kbd(C-c)}}} will display the
|
|
selection window.
|
|
|
|
|
|
{{{noindent}}} This method lets you assign tags to a headline with
|
|
very few keys. With the above setup, you could clear the current tags
|
|
and set {{{samp(@home)}}}, {{{samp(laptop)}}} and {{{samp(pc)}}} tags
|
|
with just the following keys: {{{ksksksk(C-c C-c,SPC,h l p,RET)}}}. Switching from {{{samp(@home)}}} to
|
|
{{{samp(@work)}}} would be done with {{{kbdspckey(C-c C-c w,RET)}}} or
|
|
alternatively with {{{kbd(C-c C-c C-c w)}}}. Adding the non-predefined
|
|
tag {{{samp(Sarah)}}} could be done with
|
|
{{{ksksksksk(C-c C-c,TAB,S a r a h,RET,RET)}}}.
|
|
|
|
#+vindex: org-fast-tag-selection-single-key
|
|
|
|
If you find that most of the time you need only a single key press to
|
|
modify your list of tags, set the variable
|
|
~org-fast-tag-selection-single-key~. Then you no longer have to press
|
|
{{{key(RET)}}} to exit fast tag selection---it will immediately exit after
|
|
the first change. If you then occasionally need more keys, press
|
|
{{{kbd(C-c)}}} to turn off auto-exit for the current tag selection
|
|
process (in effect: start selection with {{{kbd(C-c C-c C-c)}}}
|
|
instead of {{{kbd(C-c C-c)}}}). If you set the variable to the value
|
|
~expert~, the special window is not even shown for single-key tag
|
|
selection, it comes up only when you press an extra {{{kbd(C-c)}}}.
|
|
|
|
** Tag searches
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Searching for combinations of tags
|
|
:END:
|
|
#+cindex: tag searches
|
|
#+cindex: searching for tags
|
|
|
|
Once a system of tags has been set up, it can be used to collect related
|
|
information into special lists.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c / m)}}}, ~C-c \~ ~org-match-sparse-tree~ ::
|
|
|
|
Create a sparse tree with all headlines matching a tags search. With a
|
|
{{{kbd(C-u)}}} prefix argument, ignore headlines that are not a TODO
|
|
line.
|
|
|
|
- {{{kbd(C-c a m)}}}, ~org-tags-view~ ::
|
|
#+kindex: C-c a m
|
|
|
|
Create a global list of tag matches from all agenda files.
|
|
See [[Matching tags and properties]].
|
|
|
|
- {{{kbd(C-c a M)}}}, ~org-tags-view~ ::
|
|
#+kindex: C-c a M
|
|
#+vindex: org-tags-match-list-sublevels
|
|
|
|
Create a global list of tag matches from all agenda files, but check
|
|
only TODO items and force checking subitems (see variable ~org-tags-match-list-sublevels~).
|
|
|
|
|
|
These commands all prompt for a match string which allows basic
|
|
Boolean logic like {{{samp(+boss+urgent-project1)}}}, to find entries
|
|
with tags {{{samp(boss)}}} and {{{samp(urgent)}}}, but not
|
|
{{{samp(project1)}}}, or {{{samp(Kathy|Sally)}}} to find entries which
|
|
are tagged, like {{{samp(Kathy)}}} or {{{samp(Sally)}}}. The full
|
|
syntax of the search string is rich and allows also matching against
|
|
TODO keywords, entry levels and properties. For a complete description
|
|
with many examples, see [[Matching tags and properties]].
|
|
|
|
* Properties and columns
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Storing information about an entry
|
|
:ALT_TITLE: Properties and Columns
|
|
:END:
|
|
#+cindex: properties
|
|
|
|
A property is a key-value pair associated with an entry. Properties
|
|
can be set so they are associated with a single entry, with every
|
|
entry in a tree, or with every entry in an Org mode file.
|
|
|
|
There are two main applications for properties in Org mode. First,
|
|
properties are like tags, but with a value. Imagine maintaining a file
|
|
where you document bugs and plan releases for a piece of software.
|
|
Instead of using tags like ~:release_1:~, ~:release_2:~, you can use a
|
|
property, say ~:Release:~, that in different subtrees has different
|
|
values, such as ~1.0~ or ~2.0~. Second, you can use properties to
|
|
implement (very basic) database capabilities in an Org buffer. Imagine
|
|
keeping track of your music CDs, where properties could be things such
|
|
as the album, artist, date of release, number of tracks, and so on.
|
|
|
|
Properties can be conveniently edited and viewed in column view
|
|
(see [[Column view]]).
|
|
|
|
** Property syntax
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How properties are spelled out
|
|
:END:
|
|
#+cindex: property syntax
|
|
#+cindex: drawer, for properties
|
|
|
|
Properties are key-value pairs. When they are associated with a single
|
|
entry or with a tree they need to be inserted into a special drawer
|
|
(see [[Drawers]]) with the name ~PROPERTIES~. Each property is specified
|
|
on a single line, with the key (surrounded by colons) first, and the
|
|
value after it. Here is an example:
|
|
|
|
#+begin_example
|
|
,* CD collection
|
|
,** Classic
|
|
,*** Goldberg Variations
|
|
, :PROPERTIES:
|
|
, :Title: Goldberg Variations
|
|
, :Composer: J.S. Bach
|
|
, :Artist: Glen Gould
|
|
, :Publisher: Deutsche Grammophon
|
|
, :NDisks: 1
|
|
, :END:
|
|
#+end_example
|
|
|
|
Depending on the value of ~org-use-property-inheritance~, a property
|
|
set this way will either be associated with a single entry, or the
|
|
sub-tree defined by the entry, see [[Property inheritance]].
|
|
|
|
You may define the allowed values for a particular property
|
|
{{{samp(:Xyz:)}}} by setting a property {{{samp(:Xyz_ALL:)}}}. This
|
|
special property is /inherited/, so if you set it in a level 1 entry,
|
|
it will apply to the entire tree. When allowed values are defined,
|
|
setting the corresponding property becomes easier and is less prone to
|
|
typing errors. For the example with the CD collection, we can
|
|
predefine publishers and the number of disks in a box like this:
|
|
|
|
#+begin_example
|
|
,* CD collection
|
|
, :PROPERTIES:
|
|
, :NDisks_ALL: 1 2 3 4
|
|
, :Publisher_ALL: "Deutsche Grammophon" Philips EMI
|
|
, :END:
|
|
#+end_example
|
|
|
|
If you want to set properties that can be inherited by any entry in a
|
|
file, use a line like:
|
|
|
|
#+cindex: property, _ALL
|
|
#+cindex: #+PROPERTY
|
|
#+begin_example
|
|
,#+PROPERTY: NDisks_ALL 1 2 3 4
|
|
#+end_example
|
|
|
|
If you want to add to the value of an existing property, append a ~+~
|
|
to the property name. The following results in the property ~var~
|
|
having the value ``foo=1 bar=2''.
|
|
|
|
#+cindex: property, +
|
|
#+begin_example
|
|
,#+PROPERTY: var foo=1
|
|
,#+PROPERTY: var+ bar=2
|
|
#+end_example
|
|
|
|
It is also possible to add to the values of inherited properties. The
|
|
following results in the ~genres~ property having the value ``Classic
|
|
Baroque'' under the ~Goldberg Variations~ subtree.
|
|
|
|
#+cindex: property, +
|
|
#+begin_example
|
|
,* CD collection
|
|
,** Classic
|
|
, :PROPERTIES:
|
|
, :GENRES: Classic
|
|
, :END:
|
|
,*** Goldberg Variations
|
|
, :PROPERTIES:
|
|
, :Title: Goldberg Variations
|
|
, :Composer: J.S. Bach
|
|
, :Artist: Glen Gould
|
|
, :Publisher: Deutsche Grammophon
|
|
, :NDisks: 1
|
|
, :GENRES+: Baroque
|
|
, :END:
|
|
#+end_example
|
|
Note that a property can only have one entry per Drawer.
|
|
|
|
#+vindex: org-global-properties
|
|
|
|
Property values set with the global variable ~org-global-properties~
|
|
can be inherited by all entries in all Org files.
|
|
|
|
{{{noindent}}}
|
|
The following commands help to work with properties:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbdkey(M-,TAB)}}}, ~pcomplete~ ::
|
|
#+kindex: M-@key{TAB}
|
|
|
|
After an initial colon in a line, complete property keys. All keys
|
|
used in the current file will be offered as possible completions.
|
|
|
|
- {{{kbd(C-c C-x p)}}}, ~org-set-property~ ::
|
|
#+kindex: C-c C-x p
|
|
|
|
Set a property. This prompts for a property name and a value. If
|
|
necessary, the property drawer is created as well.
|
|
|
|
- C-u M-x org-insert-drawer RET ::
|
|
#+cindex: org-insert-drawer
|
|
|
|
Insert a property drawer into the current entry. The drawer will be
|
|
inserted early in the entry, but after the lines with planning
|
|
information like deadlines.
|
|
|
|
- {{{kbd(C-c C-c)}}}, ~org-property-action~ ::
|
|
#+kindex: C-c C-c
|
|
|
|
With the cursor in a property drawer, this executes property commands.
|
|
|
|
- {{{kbd(C-c C-c s)}}}, ~org-set-property~ ::
|
|
#+kindex: C-c C-c s
|
|
|
|
Set a property in the current entry. Both the property and the value
|
|
can be inserted using completion.
|
|
|
|
- {{{kbdkey(S-,right)}}} {{{kbdkey(S-,left)}}}, ~org-property-next-allowed-value~ ~org-property-previous-allowed-value~ ::
|
|
#+kindex: S-@key{right}
|
|
|
|
Switch property at point to the next/previous allowed value.
|
|
|
|
- {{{kbd(C-c C-c d)}}}, ~org-delete-property~ ::
|
|
#+kindex: C-c C-c d
|
|
|
|
Remove a property from the current entry.
|
|
|
|
- {{{kbd(C-c C-c D)}}}, ~org-delete-property-globally~ ::
|
|
#+kindex: C-c C-c D
|
|
|
|
Globally remove a property, from all entries in the current file.
|
|
|
|
- {{{kbd(C-c C-c c)}}}, ~org-compute-property-at-point~ ::
|
|
#+kindex: C-c C-c c
|
|
|
|
Compute the property at point, using the operator and scope from the
|
|
nearest column format definition.
|
|
|
|
** Special properties
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Access to other Org mode features
|
|
:END:
|
|
#+cindex: properties, special
|
|
|
|
Special properties provide an alternative access method to Org mode
|
|
features, like the TODO state or the priority of an entry, discussed
|
|
in the previous chapters. This interface exists so that you can
|
|
include these states in a column view (see [[Column view]]), or to use
|
|
them in queries. The following property names are special and (except
|
|
for ~:CATEGORY:~) should not be used as keys in the properties drawer:
|
|
|
|
#+cindex: property, special, ID
|
|
#+cindex: property, special, TODO
|
|
#+cindex: property, special, TAGS
|
|
#+cindex: property, special, ALLTAGS
|
|
#+cindex: property, special, CATEGORY
|
|
#+cindex: property, special, PRIORITY
|
|
#+cindex: property, special, DEADLINE
|
|
#+cindex: property, special, SCHEDULED
|
|
#+cindex: property, special, CLOSED
|
|
#+cindex: property, special, TIMESTAMP
|
|
#+cindex: property, special, TIMESTAMP_IA
|
|
#+cindex: property, special, CLOCKSUM
|
|
#+cindex: property, special, CLOCKSUM_T
|
|
#+cindex: property, special, BLOCKED
|
|
# guessing that ITEM is needed in this area; also, should this list be sorted?
|
|
#+cindex: property, special, ITEM
|
|
#+cindex: property, special, FILE
|
|
|
|
#+attr_texinfo: :columns 0.3 0.7
|
|
| ID | A globally unique ID used for synchronization during |
|
|
| | iCalendar or MobileOrg export. |
|
|
| TODO | The TODO keyword of the entry. |
|
|
| TAGS | The tags defined directly in the headline. |
|
|
| ALLTAGS | All tags, including inherited ones. |
|
|
| CATEGORY | The category of an entry. |
|
|
| PRIORITY | The priority of the entry, a string with a single letter. |
|
|
| DEADLINE | The deadline time string, without the angular brackets. |
|
|
| SCHEDULED | The scheduling timestamp, without the angular brackets. |
|
|
| CLOSED | When was this entry closed? |
|
|
| TIMESTAMP | The first keyword-less timestamp in the entry. |
|
|
| TIMESTAMP_IA | The first inactive timestamp in the entry. |
|
|
| CLOCKSUM | The sum of CLOCK intervals in the subtree. ~org-clock-sum~ |
|
|
| | must be run first to compute the values in the current buffer. |
|
|
| CLOCKSUM_T | The sum of CLOCK intervals in the subtree for today. |
|
|
| | ~org-clock-sum-today~ must be run first to compute the |
|
|
| | values in the current buffer. |
|
|
| BLOCKED | "t" if task is currently blocked by children or siblings |
|
|
| ITEM | The headline of the entry. |
|
|
| FILE | The filename the entry is located in. |
|
|
|
|
** Property searches
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Matching property values
|
|
:END:
|
|
#+cindex: properties, searching
|
|
#+cindex: searching, of properties
|
|
|
|
To create sparse trees and special lists with selection based on properties,
|
|
the same commands are used as for tag searches (see [[Tag searches]]).
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c / m)}}}, ~C-c \~ ~org-match-sparse-tree~ ::
|
|
#+kindex: C-c / m
|
|
|
|
Create a sparse tree with all matching entries. With a {{{kbd(C-u)}}}
|
|
prefix argument, ignore headlines that are not a TODO line.
|
|
|
|
- {{{kbd(C-c a m)}}}, ~org-tags-view~ ::
|
|
#+kindex: C-c a m
|
|
|
|
Create a global list of tag/property matches from all agenda files.
|
|
See [[Matching tags and properties]].
|
|
|
|
- {{{kbd(C-c a M)}}}, ~org-tags-view~ ::
|
|
#+kindex: C-c a M
|
|
#+vindex: org-tags-match-list-sublevels
|
|
|
|
Create a global list of tag matches from all agenda files, but check
|
|
only TODO items and force checking of subitems (see variable
|
|
~org-tags-match-list-sublevels~).
|
|
|
|
|
|
The syntax for the search string is described in [[Matching tags and
|
|
properties]].
|
|
|
|
There is also a special command for creating sparse trees based on a
|
|
single property:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c / p)}}} ::
|
|
#+kindex: C-c / p
|
|
|
|
Create a sparse tree based on the value of a property. This first
|
|
prompts for the name of a property, and then for a value. A sparse
|
|
tree is created with all entries that define this property with the
|
|
given value. If you enclose the value in curly braces, it is
|
|
interpreted as a regular expression and matched against the property
|
|
values.
|
|
|
|
** Property inheritance
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Passing values down a tree
|
|
:END:
|
|
#+cindex: properties, inheritance
|
|
#+cindex: inheritance, of properties
|
|
|
|
#+vindex: org-use-property-inheritance
|
|
|
|
The outline structure of Org mode documents lends itself to an
|
|
inheritance model of properties: if the parent in a tree has a certain
|
|
property, the children can inherit this property. Org mode does not
|
|
turn this on by default, because it can slow down property searches
|
|
significantly and is often not needed. However, if you find
|
|
inheritance useful, you can turn it on by setting the variable
|
|
~org-use-property-inheritance~. It may be set to ~t~ to make all
|
|
properties inherited from the parent, to a list of properties that
|
|
should be inherited, or to a regular expression that matches inherited
|
|
properties. If a property has the value {{{samp(nil)}}}, this is
|
|
interpreted as an explicit undefine of the property, so that
|
|
inheritance search will stop at this value and return ~nil~.
|
|
|
|
Org mode has a few properties for which inheritance is hard-coded, at
|
|
least for the special applications for which they are used:
|
|
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~COLUMNS~ ::
|
|
#+cindex: property, COLUMNS
|
|
|
|
The ~:COLUMNS:~ property defines the format of column view (see [[Column
|
|
view]]). It is inherited in the sense that the level where a ~:COLUMNS:~
|
|
property is defined is used as the starting point for a column view
|
|
table, independently of the location in the subtree from where columns
|
|
view is turned on.
|
|
|
|
- ~CATEGORY~ ::
|
|
#+cindex: property, CATEGORY
|
|
|
|
For agenda view, a category set through a ~:CATEGORY:~ property
|
|
applies to the entire subtree.
|
|
|
|
- ~ARCHIVE~ ::
|
|
#+cindex: property, ARCHIVE
|
|
|
|
For archiving, the ~:ARCHIVE:~ property may define the archive
|
|
location for the entire subtree (see [[Moving subtrees]]).
|
|
|
|
- ~LOGGING~ ::
|
|
#+cindex: property, LOGGING
|
|
|
|
The LOGGING property may define logging settings for an entry or a
|
|
subtree (see [[Tracking TODO state changes]]).
|
|
|
|
** Column view
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tabular viewing and editing
|
|
:END:
|
|
|
|
A great way to view and edit properties in an outline tree is /column
|
|
view/. In column view, each outline node is turned into a table row.
|
|
Columns in this table provide access to properties of the entries. Org
|
|
mode implements columns by overlaying a tabular structure over the
|
|
headline of each item. While the headlines have been turned into a
|
|
table row, you can still change the visibility of the outline tree.
|
|
For example, you get a compact table by switching to CONTENTS view
|
|
({{{kbdkey(S-,TAB)}}}} {{{kbdkey(S-,TAB)}}}), or simply {{{kbd(c)}}} while
|
|
column view is active), but you can still open, read, and edit the
|
|
entry below each headline. Or, you can switch to column view after
|
|
executing a sparse tree command and in this way get a table only for
|
|
the selected items. Column view also works in agenda buffers (see
|
|
[[Agenda views]]) where queries have collected selected items, possibly
|
|
from a number of files.
|
|
|
|
*** Defining columns
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The COLUMNS format property
|
|
:END:
|
|
#+cindex: column view, for properties
|
|
#+cindex: properties, column view
|
|
|
|
Setting up a column view first requires defining the columns. This is
|
|
done by defining a column format line.
|
|
|
|
**** Scope of column definitions
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Where defined, where valid?
|
|
:END:
|
|
|
|
To define a column format for an entire file, use a line like:
|
|
|
|
#+cindex: #+COLUMNS
|
|
#+begin_example
|
|
,#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
|
|
#+end_example
|
|
|
|
To specify a format that only applies to a specific tree, add a
|
|
~:COLUMNS:~ property to the top node of that tree, for example:
|
|
|
|
#+begin_example
|
|
,** Top node for columns view
|
|
, :PROPERTIES:
|
|
, :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
|
|
, :END:
|
|
#+end_example
|
|
|
|
If a ~:COLUMNS:~ property is present in an entry, it defines columns
|
|
for the entry itself, and for the entire subtree below it. Since the
|
|
column definition is part of the hierarchical structure of the
|
|
document, you can define columns on level 1 that are general enough
|
|
for all sublevels, and more specific columns further down, when you
|
|
edit a deeper part of the tree.
|
|
|
|
**** Column attributes
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Appearance and content of a column
|
|
:END:
|
|
A column definition sets the attributes of a column. The general
|
|
definition looks like this:
|
|
|
|
%[{{{var(width)}}}]{{{var(property)}}}[({{{var(title)}}})][{{{{var(summary-type)}}}}]
|
|
|
|
{{{noindent}}} Except for the percent sign and the property name, all
|
|
items are optional. The individual parts have the following meaning:
|
|
|
|
#+attr_texinfo: :columns 0.2 0.8
|
|
| Variable | Meaning |
|
|
|-------------------------+--------------------------------------------------------------|
|
|
| {{{var(width)}}} | An integer specifying the width of the column in characters. |
|
|
| | If omitted, the width will be determined automatically. |
|
|
| {{{var(property)}}} | The property that should be edited in this column. |
|
|
| | Special properties representing meta data are allowed here |
|
|
| | as well (see [[Special properties]]) |
|
|
| {{{var(title)}}} | The header text for the column. If omitted, the property |
|
|
| | name is used. |
|
|
| {{{var(summary-type)}}} | The summary type. If specified, the column values for |
|
|
| | parent nodes are computed from the children. |
|
|
|
|
{{{noindent}}} Supported summary types are:
|
|
|
|
#+attr_texinfo: :columns 0.2 0.8
|
|
| Type | Meaning |
|
|
|----------+-----------------------------------------------------------------------|
|
|
| ~+~ | Sum numbers in this column. |
|
|
| ~+;%.1f~ | Like ~+~, but format result with {{{samp(%.1f)}}}. |
|
|
| ~$~ | Currency, short for {{{samp(+;%.2f)}}}. |
|
|
| ~:~ | Sum times, HH:MM, plain numbers are hours. |
|
|
| ~X~ | Checkbox status, {{{samp([X])}}} if all children are {{{samp([X])}}}. |
|
|
| ~X/~ | Checkbox status, {{{samp([n/m])}}}. |
|
|
| ~X%~ | Checkbox status, {{{samp([n%])}}}. |
|
|
| ~min~ | Smallest number in column. |
|
|
| ~max~ | Largest number. |
|
|
| ~mean~ | Arithmetic mean of numbers. |
|
|
| ~:min~ | Smallest time value in column. |
|
|
| ~:max~ | Largest time value. |
|
|
| ~:mean~ | Arithmetic mean of time values. |
|
|
| ~@min~ | Minimum age (in days/hours/mins/seconds). |
|
|
| ~@max~ | Maximum age (in days/hours/mins/seconds). |
|
|
| ~@mean~ | Arithmetic mean of ages (in days/hours/mins/seconds). |
|
|
| ~est+~ | Add low-high estimates. |
|
|
|
|
|
|
{{{noindent}}} Be aware that you can only have one summary type for
|
|
any property you include. Subsequent columns referencing the same
|
|
property will all display the same summary information.
|
|
|
|
The ~est+~ summary type requires further explanation. It is used for
|
|
combining estimates, expressed as low-high ranges. For example,
|
|
instead of estimating a particular task will take 5 days, you might
|
|
estimate it as 5-6 days if you're fairly confident you know how much
|
|
work is required, or 1-10 days if you don't really know what needs to
|
|
be done. Both ranges average at 5.5 days, but the first represents a
|
|
more predictable delivery.
|
|
|
|
When combining a set of such estimates, simply adding the lows and
|
|
highs produces an unrealistically wide result. Instead, ~est+~ adds
|
|
the statistical mean and variance of the sub-tasks, generating a final
|
|
estimate from the sum. For example, suppose you had ten tasks, each of
|
|
which was estimated at 0.5 to 2 days of work. Straight addition
|
|
produces an estimate of 5 to 20 days, representing what to expect if
|
|
everything goes either extremely well or extremely poorly. In
|
|
contrast, ~est+~ estimates the full job more realistically, at 10-15
|
|
days.
|
|
|
|
Here is an example for a complete columns definition, along with allowed
|
|
values.[fn:58]
|
|
|
|
#+begin_example
|
|
:COLUMNS: %25ITEM %9Approved(Approved?){X} %Owner %11Status \
|
|
%10Time_Estimate{:} %CLOCKSUM %CLOCKSUM_T
|
|
:Owner_ALL: Tammy Mark Karl Lisa Don
|
|
:Status_ALL: "In progress" "Not started yet" "Finished" ""
|
|
:Approved_ALL: "[ ]" "[X]"
|
|
#+end_example
|
|
|
|
{{{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 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 field
|
|
{{{samp(Approved)}}}. When no width is given after the {{{samp(%)}}}
|
|
character, the column will be exactly as wide as it needs to be in
|
|
order to fully display all values. The {{{samp(Approved)}}} column
|
|
does have a modified title ({{{samp(Approved?)}}}, with a question
|
|
mark). Summaries will be created for the {{{samp(Time_Estimate)}}}
|
|
column by adding time duration expressions like HH:MM, and for the
|
|
{{{samp(Approved)}}} column, by providing an {{{samp([X])}}} status if
|
|
all children have been checked. The {{{samp(CLOCKSUM)}}} and
|
|
{{{samp(CLOCKSUM_T)}}} columns are special, they lists the sums of
|
|
CLOCK intervals in the subtree, either for all clocks or just for
|
|
today.
|
|
|
|
*** Using column view
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to create and use column view
|
|
:END:
|
|
|
|
The following commands turn column view on or off:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-c)}}}, ~org-columns~ ::
|
|
#+kindex: C-c C-x C-c
|
|
#+vindex: org-columns-default-format
|
|
|
|
Turn on column view. If the cursor is before the first headline in the
|
|
file, column view is turned on for the entire file, using the ~#+COLUMNS~ definition. If the cursor is somewhere inside the outline,
|
|
this command searches the hierarchy, up from point, for a ~:COLUMNS:~
|
|
property that defines a format. When one is found, the column view
|
|
table is established for the tree starting at the entry that contains
|
|
the ~:COLUMNS:~ property. If no such property is found, the format is
|
|
taken from the ~#+COLUMNS~ line or from the variable ~org-columns-default-format~, and column view is established for the
|
|
current entry and its subtree.
|
|
|
|
- {{{kbd(r)}}}, ~org-columns-redo~ ::
|
|
#+kindex: r
|
|
|
|
Recreate the column view, to include recent changes made in the
|
|
buffer.
|
|
|
|
- {{{kbd(g)}}}, ~org-columns-redo~ ::
|
|
#+kindex: g
|
|
|
|
Same as {{{kbd(r)}}}.
|
|
|
|
- {{{kbd(q)}}}, ~org-columns-quit~ ::
|
|
#+kindex: q
|
|
|
|
Exit column view.
|
|
|
|
The following commands let you edit information in column view:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{key(left)}}} {{{key(right)}}} {{{key(up)}}} {{{key(down)}}} ::
|
|
|
|
Move through the column view from field to field.
|
|
|
|
- {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}} ::
|
|
#+kindex: S-@key{left}
|
|
#+kindex: S-@key{right}
|
|
|
|
Switch to the next/previous allowed value of the field. For this, you
|
|
have to have specified allowed values for a property.
|
|
|
|
- {{{kbd(1..9\,0)}}} ::
|
|
#+kindex: 1..9,0
|
|
|
|
Directly select the Nth allowed value, {{{kbd(0)}}} selects the 10th
|
|
value.
|
|
|
|
- {{{kbd(n)}}} {{{kbd(p)}}}, ~org-columns-next-allowed-value~ ~org-columns-previous-allowed-value~ ::
|
|
#+kindex: n
|
|
|
|
Same as {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}}
|
|
|
|
- {{{kbd(e)}}}, ~org-columns-edit-value~ ::
|
|
#+kindex: e
|
|
|
|
Edit the property at point. For the special properties, this will
|
|
invoke the same interface that you normally use to change that
|
|
property. For example, when editing a TAGS property, the tag
|
|
completion or fast selection interface will pop up.
|
|
|
|
- {{{kbd(C-c C-c)}}}, ~org-columns-set-tags-or-toggle~ ::
|
|
#+kindex: C-c C-c
|
|
|
|
When there is a checkbox at point, toggle it.
|
|
|
|
- {{{kbd(v)}}}, ~org-columns-show-value~ ::
|
|
#+kindex: v
|
|
|
|
View the full value of this property. This is useful if the width of
|
|
the column is smaller than that of the value.
|
|
|
|
- {{{kbd(a)}}}, ~org-columns-edit-allowed~ ::
|
|
#+kindex: a
|
|
|
|
Edit the list of allowed values for this property. If the list is found
|
|
in the hierarchy, the modified values is stored there. If no list is
|
|
found, the new value is stored in the first entry that is part of the
|
|
current column view.
|
|
|
|
|
|
The following commands modify column view on-the-fly:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(<)}}} {{{kbd(>)}}}, ~org-columns-narrow~ ~org-columns-widen~ ::
|
|
#+kindex: <
|
|
|
|
Make the column narrower/wider by one character.
|
|
|
|
- {{{kbdkey(S-M-,right)}}}, ~org-columns-new~ ::
|
|
#+kindex: S-M-@key{right}
|
|
|
|
Insert a new column, to the left of the current column.
|
|
|
|
- {{{kbdkey(S-M-,left)}}}, ~org-columns-delete~ ::
|
|
#+kindex: S-M-@key{left}
|
|
|
|
Delete the current column.
|
|
|
|
*** Capturing column view
|
|
:PROPERTIES:
|
|
:DESCRIPTION: A dynamic block for column view
|
|
:END:
|
|
|
|
Since column view is just an overlay over a buffer, it cannot be
|
|
exported or printed directly. If you want to capture a column view,
|
|
use a ~columnview~ dynamic block (see [[Dynamic blocks]]). The frame of
|
|
this block looks like this:
|
|
|
|
#+cindex: #+BEGIN, columnview
|
|
#+begin_example
|
|
,* The column view
|
|
,#+BEGIN: columnview :hlines 1 :id "label"
|
|
|
|
,#+END:
|
|
#+end_example
|
|
|
|
{{{noindent}}} This dynamic block has the following parameters:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:id~ ::
|
|
|
|
This is the most important parameter. Column view is a feature that is
|
|
often localized to a certain (sub)tree, and the capture block might be
|
|
at a different location in the file. To identify the tree whose view
|
|
to capture, you can use 4 values:
|
|
|
|
#+cindex: property, ID
|
|
#+attr_texinfo: :columns 0.35 0.65
|
|
| Value | Meaning |
|
|
|---------------------+---------------------------------------------------------------|
|
|
| local | Use the tree in which the capture block is located. |
|
|
| global | Make a global view, including all headings in the file. |
|
|
| =file:PATH-TO-FILE= | Run column view at the top of this file. |
|
|
| ID | Call column view in the tree that has an ~:ID:~ |
|
|
| | property with the value /label/. You can use |
|
|
| | {{{kbd(M-x org-id-copy)}}} to create a globally unique ID for |
|
|
| | the current entry and copy it to the kill-ring. |
|
|
|
|
- local ::
|
|
|
|
Use the tree in which the capture block is located.
|
|
|
|
- global ::
|
|
|
|
Make a global view, including all headings in the file.
|
|
|
|
- =file:PATH-TO-FILE= ::
|
|
|
|
Run column view at the top of this file.
|
|
|
|
- ID ::
|
|
|
|
Call column view in the tree that has an ~:ID:~ property with the
|
|
value /label/. You can use {{{kbd(M-x org-id-copy)}}} to
|
|
create a globally unique ID for the current entry and copy
|
|
it to the kill-ring.
|
|
|
|
- ~:hlines~ ::
|
|
|
|
When ~t~, insert an hline after every line. When a number ~N~,
|
|
insert an hline before each headline with level ~<=~
|
|
{{{var(N)}}}.
|
|
|
|
- ~:vlines~ ::
|
|
|
|
When set to ~t~, force column groups to get vertical lines.
|
|
|
|
- ~:maxlevel~ ::
|
|
|
|
When set to a number, don't capture entries below this level.
|
|
|
|
- ~:skip-empty-rows~ ::
|
|
|
|
When set to ~t~, skip rows where the only non-empty specifier of the
|
|
column view is ~ITEM~.
|
|
|
|
|
|
|
|
{{{noindent}}} The following commands insert or update the dynamic
|
|
block:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x i)}}}, ~org-insert-columns-dblock~ ::
|
|
#+kindex: 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.
|
|
|
|
- {{{kbd(C-c C-c)}}} {{{kbd(C-c C-x C-u)}}}, ~org-dblock-update~ ::
|
|
#+kindex: C-c C-c
|
|
|
|
Update dynamic block at point. The cursor needs to be in the ~#+BEGIN~
|
|
line of the dynamic block.
|
|
|
|
- {{{kbd(C-u C-c C-x C-u)}}}, ~org-update-all-dblocks~ ::
|
|
#+kindex: C-u C-c C-x C-u
|
|
|
|
Update all dynamic blocks (see [[Dynamic blocks]]). This is useful if you
|
|
have several clock table blocks, column-capturing blocks or other
|
|
dynamic blocks in a buffer.
|
|
|
|
|
|
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 ~#+TBLFM:~ after the table, the table will
|
|
actually be recalculated automatically after an update.
|
|
|
|
An alternative way to capture and process property values into a table
|
|
is provided by Eric Schulte's {{{file(org-collector.el)}}} which is a
|
|
contributed package.[fn:59] It provides a general API to collect
|
|
properties from entries in a certain scope, and arbitrary Lisp
|
|
expressions to process these values before inserting them into a table
|
|
or a dynamic block.
|
|
|
|
** Property API
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Properties for Lisp programmers
|
|
:END:
|
|
#+cindex: properties, API
|
|
#+cindex: API, for properties
|
|
|
|
There is a full API for accessing and changing properties. This API
|
|
can be used by Emacs Lisp programs to work with properties and to
|
|
implement features based on them. For more information see [[Using the
|
|
property API]].
|
|
|
|
* Dates and times
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Making items useful for planning
|
|
:ALT_TITLE: Dates and Times
|
|
:END:
|
|
#+cindex: dates
|
|
#+cindex: times
|
|
#+cindex: timestamp
|
|
#+cindex: date stamp
|
|
|
|
To assist project planning, TODO items can be labeled with a date and/or
|
|
a time. The specially formatted string carrying the date and time
|
|
information is called a /timestamp/ in Org mode. This may be a
|
|
little confusing because timestamp is often used as indicating when
|
|
something was created or last changed. However, in Org mode this term
|
|
is used in a much wider sense.
|
|
|
|
** Timestamps
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Assigning a time to a tree entry
|
|
:TITLE: Timestamps, deadlines, and scheduling
|
|
:END:
|
|
#+cindex: timestamps
|
|
#+cindex: ranges, time
|
|
#+cindex: date stamps
|
|
#+cindex: deadlines
|
|
#+cindex: scheduling
|
|
|
|
A timestamp is a specification of a date (possibly with a time or a
|
|
range of times) in a special format, either ~<2003-09-16 Tue>~ or
|
|
~<2003-09-16 Tue 09:39>~ or ~<2003-09-16 Tue 12:00-12:30>~.[fn:60] A
|
|
timestamp can appear anywhere in the headline or body of an Org tree
|
|
entry. Its presence causes entries to be shown on specific dates in
|
|
the agenda (see [[Weekly/daily agenda]]). We distinguish:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Plain timestamp; Event; Appointment ::
|
|
#+cindex: timestamp
|
|
#+cindex: appointment
|
|
|
|
A simple timestamp just assigns a date/time to an item. This is just
|
|
like writing down an appointment or event in a paper agenda. In the
|
|
timeline and agenda displays, the headline of an entry associated with
|
|
a plain timestamp will be shown exactly on that date.
|
|
|
|
#+begin_example
|
|
,* Meet Peter at the movies
|
|
<2006-11-01 Wed 19:15>
|
|
,* Discussion on climate change
|
|
<2006-11-02 Thu 20:00-22:00>
|
|
#+end_example
|
|
|
|
- Timestamp with repeater interval ::
|
|
#+cindex: timestamp, with repeater interval
|
|
|
|
A timestamp may contain a /repeater interval/, indicating that it
|
|
applies not only on the given date, but again and again after a
|
|
certain interval of N days (d), weeks (w), months (m), or years (y).
|
|
The following will show up in the agenda every Wednesday:
|
|
|
|
#+begin_example
|
|
,* Pick up Sam at school
|
|
<2007-05-16 Wed 12:30 +1w>
|
|
#+end_example
|
|
|
|
- Diary-style sexp entries ::
|
|
|
|
For more complex date specifications, Org mode supports using the
|
|
special sexp diary entries implemented in the Emacs calendar/diary
|
|
package.[fn:61] For example, with optional time:
|
|
|
|
#+begin_example
|
|
,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
|
|
<%%(org-float t 4 2)>
|
|
#+end_example
|
|
|
|
- Time/Date range ::
|
|
#+cindex: timerange
|
|
#+cindex: date range
|
|
|
|
Two timestamps connected by {{{samp(--)}}} denote a range. The headline
|
|
will be shown on the first and last day of the range, and on any dates
|
|
that are displayed and fall in the range. Here is an example:
|
|
|
|
#+begin_example
|
|
,** Meeting in Amsterdam
|
|
<2004-08-23 Mon>--<2004-08-26 Thu>
|
|
#+end_example
|
|
|
|
- Inactive timestamp ::
|
|
#+cindex: timestamp, inactive
|
|
#+cindex: inactive timestamp
|
|
|
|
Just like a plain timestamp, but with square brackets instead of
|
|
angular ones. These timestamps are inactive in the sense that they do /not/ trigger an entry to show up in the agenda.
|
|
|
|
#+begin_example
|
|
,* Gillian comes late for the fifth time
|
|
[2006-11-01 Wed]
|
|
#+end_example
|
|
|
|
** Creating timestamps
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Commands to insert timestamps
|
|
:END:
|
|
For Org mode to recognize timestamps, they need to be in the specific
|
|
format. All commands listed below produce timestamps in the correct
|
|
format.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c .)}}}, ~org-time-stamp~ ::
|
|
#+kindex: C-c .
|
|
|
|
Prompt for a date and insert a corresponding timestamp. When the
|
|
cursor is at an existing timestamp in the buffer, the command is used
|
|
to modify this timestamp instead of inserting a new one. When this
|
|
command is used twice in succession, a time range is inserted.
|
|
|
|
- {{{kbd(C-c !)}}}, ~org-time-stamp-inactive~ ::
|
|
#+kindex: C-c !
|
|
|
|
Like {{{kbd(C-c .)}}}, but insert an inactive timestamp that will not
|
|
cause an agenda entry.
|
|
|
|
- {{{kbd(C-u C-c .)}}} {{{kbd(C-u C-c !)}}} ::
|
|
#+kindex: C-u C-c .
|
|
#+kindex: C-u C-c .
|
|
#+kindex: C-u C-c !
|
|
#+vindex: org-time-stamp-rounding-minutes
|
|
|
|
Like {{{kbd(C-c .)}}} and {{{kbd(C-c !)}}}, but use the alternative
|
|
format which contains date and time. The default time can be rounded
|
|
to multiples of 5 minutes, see the option ~org-time-stamp-rounding-minutes~.
|
|
|
|
- {{{kbd(C-c C-c)}}} ::
|
|
#+kindex: C-c C-c
|
|
|
|
Normalize timestamp, insert/fix day name if missing or wrong.
|
|
|
|
- {{{kbd(C-c <)}}}, ~org-date-from-calendar~ ::
|
|
#+kindex: C-c <
|
|
|
|
Insert a timestamp corresponding to the cursor date in the Calendar.
|
|
|
|
- {{{kbd(C-c >)}}}, ~org-goto-calendar~ ::
|
|
#+kindex: C-c >
|
|
|
|
Access the Emacs calendar for the current date. If there is a
|
|
timestamp in the current line, go to the corresponding date instead.
|
|
|
|
- {{{kbd(C-c C-o)}}}, ~org-open-at-point~ ::
|
|
#+kindex: C-c C-o
|
|
|
|
Access the agenda for the date given by the timestamp or -range at
|
|
point (see [[Weekly/daily agenda]]).
|
|
|
|
- {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}}, ~org-timestamp-down-day~ ~org-timestamp-up-day~ ::
|
|
#+kindex: S-@key{left}
|
|
|
|
Change date at cursor by one day. These key bindings conflict with
|
|
shift-selection and related modes (see [[Conflicts]]).
|
|
|
|
- {{{kbdkey(S-,up)}}} {{{kbdkey(S-,down)}}}, ~org-timestamp-up~ ~org-timestamp-down-down~ ::
|
|
#+kindex: S-@key{up}
|
|
|
|
Change the item under the cursor in a timestamp. The cursor can be on
|
|
a year, month, day, hour or minute. When the timestamp contains a time
|
|
range like {{{samp(15:30-16:30)}}}, modifying the first time will also
|
|
shift the second, shifting the time block with constant length. To
|
|
change the length, modify the second time. Note that if the cursor is
|
|
in a headline and not at a timestamp, these same keys modify the
|
|
priority of an item. (see [[Priorities]]). The key bindings also conflict
|
|
with shift-selection and related modes (see [[Conflicts]]).
|
|
|
|
- {{{kbd(C-c C-y)}}}, ~org-evaluate-time-range~ ::
|
|
#+kindex: C-c C-y
|
|
#+cindex: evaluate time range
|
|
|
|
Evaluate a time range by computing the difference between start and
|
|
end. With a prefix argument, insert result after the time range (in a
|
|
table: into the following column).
|
|
|
|
*** The date/time prompt
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How Org mode helps you enter dates and times
|
|
:END:
|
|
#+cindex: date, reading in minibuffer
|
|
#+cindex: time, reading in minibuffer
|
|
|
|
#+vindex: org-read-date-prefer-future
|
|
|
|
When Org mode prompts for a date/time, the default is shown in default
|
|
date/time format, and the prompt therefore seems to ask for a specific
|
|
format. But it will in fact accept date/time information in a variety
|
|
of formats. Generally, the information should start at the beginning
|
|
of the string. Org mode will find whatever information is in there and
|
|
derive anything you have not specified from the /default date and
|
|
time/. The default is usually the current date and time, but when
|
|
modifying an existing timestamp, or when entering the second stamp of
|
|
a range, it is taken from the stamp in the buffer. When filling in
|
|
information, Org mode assumes that most of the time you will want to
|
|
enter a date in the future: if you omit the month/year and the given
|
|
day/month is /before/ today, it will assume that you mean a future
|
|
date.[fn:62] If the date has been automatically shifted into the
|
|
future, the time prompt will show this with {{{samp((=>F))}}}.
|
|
|
|
For example, let's assume that today is *June 13, 2006*. Here is how
|
|
various inputs will be interpreted, the items filled in by Org mode
|
|
are in *bold*.
|
|
|
|
| Input | Interpretation |
|
|
|--------------+------------------------------------------------------|
|
|
| 3-2-5 | {{{result}}} 2003-02-05 |
|
|
| 2/5/3 | {{{result}}} 2003-02-05 |
|
|
| 14 | {{{result}}} *2006*-*06*-14 |
|
|
| 12 | {{{result}}} *2006*-*07*-12 |
|
|
| 2/5 | {{{result}}} *2007*-02-05 |
|
|
| Fri | {{{result}}} nearest Friday (default date or later) |
|
|
| sep 15 | {{{result}}} *2006*-09-15 |
|
|
| feb 15 | {{{result}}} *2007*-02-15 |
|
|
| sep 12 9 | {{{result}}} 2009-09-12 |
|
|
| 12:45 | {{{result}}} *2006*-*06*-*13* 12:45 |
|
|
| 22 sept 0:34 | {{{result}}} *2006*-09-22 0:34 |
|
|
| w4 | {{{result}}} ISO week for of the current year *2006* |
|
|
| 2012 w4 fri | {{{result}}} Friday of ISO week 4 in 2012 |
|
|
| 2012-w04-5 | {{{result}}} Same as above |
|
|
|
|
|
|
Furthermore you can specify a relative date by giving, as the /first/
|
|
thing in the input: a plus/minus sign, a number and a letter ([dwmy])
|
|
to indicate change in days, weeks, months, or years. With a single
|
|
plus or minus, the date is always relative to today. With a double
|
|
plus or minus, it is relative to the default date. If instead of a
|
|
single letter, you use the abbreviation of day name, the date will be
|
|
the Nth such day, e.g.:
|
|
|
|
| Input | Interpretation |
|
|
|-------+------------------------------------------|
|
|
| +0 | {{{result}}} today |
|
|
| . | {{{result}}} today |
|
|
| +4d | {{{result}}} four days from today |
|
|
| +4 | {{{result}}} same as +4d |
|
|
| +2w | {{{result}}} two weeks from today |
|
|
| ++5 | {{{result}}} five days from default date |
|
|
| +2tue | {{{result}}} second Tuesday from now |
|
|
|
|
|
|
#+vindex: parse-time-months
|
|
#+vindex: parse-time-weekdays
|
|
|
|
The function understands English month and weekday abbreviations. If
|
|
you want to use unabbreviated names and/or other languages, configure
|
|
the variables ~parse-time-months~ and ~parse-time-weekdays~.
|
|
|
|
#+vindex: org-read-date-force-compatible-dates
|
|
|
|
Not all dates can be represented in a given Emacs implementation. By
|
|
default Org mode forces dates into the compatibility range 1970--2037
|
|
which works on all Emacs implementations. If you want to use dates
|
|
outside of this range, read the docstring of the variable
|
|
~org-read-date-force-compatible-dates~.
|
|
|
|
You can specify a time range by giving start and end times or by
|
|
giving a start time and a duration (in HH:MM format). Use one or two
|
|
dash(es) as the separator in the former case and use '+' as the
|
|
separator in the latter case, e.g.:
|
|
|
|
| Range | Result |
|
|
|--------------+----------------------------|
|
|
| 11am-1:15pm | {{{result}}} 11:00-13:15 |
|
|
| 11am--1:15pm | {{{result}}} same as above |
|
|
| 11am+2:15 | {{{result}}} same as above |
|
|
|
|
#+cindex: calendar, for selecting date
|
|
#+vindex: org-popup-calendar-for-date-prompt
|
|
|
|
Parallel to the minibuffer prompt, a calendar is popped up.[fn:63]
|
|
When you exit the date prompt, either by clicking on a date in the
|
|
calendar, or by pressing {{{key(RET)}}}, the date selected in the
|
|
calendar will be combined with the information entered at the prompt.
|
|
You can control the calendar fully from the minibuffer:
|
|
|
|
#+kindex: <
|
|
#+kindex: >
|
|
#+kindex: M-v
|
|
#+kindex: C-v
|
|
#+kindex: mouse-1
|
|
#+kindex: S-@key{right}
|
|
#+kindex: S-@key{left}
|
|
#+kindex: S-@key{down}
|
|
#+kindex: S-@key{up}
|
|
#+kindex: M-S-@key{right}
|
|
#+kindex: M-S-@key{left}
|
|
#+kindex: @key{RET}
|
|
|
|
#+attr_texinfo: :columns 0.3 0.7
|
|
| Key binding | Meaning |
|
|
|---------------------------+----------------------------------------|
|
|
| {{{key(RET)}}} | Choose date at cursor in calendar. |
|
|
| {{{key(mouse-1)}}} | Select date by clicking on it. |
|
|
| {{{kbdkey(S-,right)}}} | One day forward. |
|
|
| {{{kbdkey(S-,left)}}} | One day backward. |
|
|
| {{{kbdkey(S-,down)}}} | One week forward. |
|
|
| {{{kbdkey(S-,up)}}} | One week backward. |
|
|
| {{{kbdkey(M-S-,right)}}} | One month forward. |
|
|
| {{{kbdkey(M-S-,left)}}} | One month backward. |
|
|
| {{{kbd(>)}}} | Scroll calendar forward by one month. |
|
|
| {{{kbd(<)}}} | Scroll calendar backward by one month. |
|
|
| {{{kbd(M-v)}}} | Scroll calendar forward by 3 months. |
|
|
| {{{kbd(C-v)}}} | Scroll calendar backward by 3 months. |
|
|
|
|
|
|
#+vindex: org-read-date-display-live
|
|
|
|
The actions of the date/time prompt may seem complex, but I assure you they
|
|
will grow on you, and you will start getting annoyed by pretty much any other
|
|
way of entering a date/time out there. To help you understand what is going
|
|
on, the current interpretation of your input will be displayed live in the
|
|
minibuffer.[fn:64]
|
|
|
|
*** Custom time format
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Making dates look different
|
|
:END:
|
|
#+cindex: custom date/time format
|
|
#+cindex: time format, custom
|
|
#+cindex: date format, custom
|
|
|
|
#+vindex: org-display-custom-times
|
|
#+vindex: org-time-stamp-custom-formats
|
|
|
|
Org mode uses the standard ISO notation for dates and times as it is
|
|
defined in ISO 8601. If you cannot get used to this and require
|
|
another representation of date and time to keep you happy, you can get
|
|
it by customizing the variables ~org-display-custom-times~ and
|
|
~org-time-stamp-custom-formats~.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-t)}}}, ~org-toggle-time-stamp-overlays~ ::
|
|
#+kindex: C-c C-x C-t
|
|
|
|
Toggle the display of custom formats for dates and times.
|
|
|
|
|
|
{{{noindent}}}
|
|
Org mode needs the default format for scanning, so the custom date/time
|
|
format does not /replace/ the default format---instead it is put
|
|
/over/ the default format using text properties. This has the
|
|
following consequences:
|
|
|
|
|
|
- You cannot place the cursor onto a timestamp anymore, only before or
|
|
after.
|
|
|
|
- The {{{kbdkey(S-,up)}}} {{{kbdkey(S-,down)}}} keys can no longer be
|
|
used to adjust each component of a timestamp. If the cursor is at
|
|
the beginning of the stamp, {{{kbdkey(S-,up)}}}
|
|
{{{kbdkey(S-,down)}}} will change the stamp by one day, just like
|
|
{{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}}. At the end of the
|
|
stamp, the time will be changed by one minute.
|
|
|
|
- If the timestamp contains a range of clock times or a repeater,
|
|
these will not be overlaid, but remain in the buffer as they were.
|
|
|
|
- When you delete a timestamp character-by-character, it will only
|
|
disappear from the buffer after /all/ (invisible) characters
|
|
belonging to the ISO timestamp have been removed.
|
|
|
|
- If the custom timestamp format is longer than the default and you
|
|
are using dates in tables, table alignment will be messed up. If
|
|
the custom format is shorter, things do work as expected.
|
|
|
|
** Deadlines and scheduling
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Planning your work
|
|
:END:
|
|
|
|
A timestamp may be preceded by special keywords to facilitate planning:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~DEADLINE~ ::
|
|
#+cindex: DEADLINE keyword
|
|
|
|
Meaning: the task (most likely a TODO item, though not necessarily) is
|
|
supposed to be finished on that date.
|
|
|
|
#+vindex: org-deadline-warning-days
|
|
|
|
On the deadline date, the task will be listed in the agenda. In
|
|
addition, the agenda for /today/ will carry a warning about the
|
|
approaching or missed deadline, starting ~org-deadline-warning-days~
|
|
before the due date, and continuing until the entry is marked DONE. An
|
|
example:
|
|
|
|
#+begin_example
|
|
,*** TODO write article about the Earth for the Guide
|
|
DEADLINE: <2004-02-29 Sun>
|
|
The editor in charge is [[bbdb:Ford Prefect]]
|
|
#+end_example
|
|
|
|
You can specify a different lead time for warnings for a specific
|
|
deadlines using the following syntax. Here is an example with a
|
|
warning period of 5 days ~DEADLINE: <2004-02-29 Sun -5d>~.
|
|
|
|
- ~SCHEDULED~ ::
|
|
#+cindex: SCHEDULED keyword
|
|
|
|
Meaning: you are planning to start working on that task on the given
|
|
date.
|
|
|
|
#+vindex: org-agenda-skip-scheduled-if-done
|
|
|
|
The headline will be listed under the given date.[fn:65] In addition,
|
|
a reminder that the scheduled date has passed will be present in the
|
|
compilation for /today/, until the entry is marked DONE, i.e., the
|
|
task will automatically be forwarded until completed.
|
|
|
|
#+begin_example
|
|
,*** TODO Call Trillian for a date on New Years Eve.
|
|
SCHEDULED: <2004-12-25 Sat>
|
|
#+end_example
|
|
|
|
{{{noindent}}} *Important:* Scheduling an item in Org mode should /not/ be
|
|
understood in the same way that we understand /scheduling a meeting/.
|
|
Setting a date for a meeting is just a simple appointment, you should
|
|
mark this entry with a simple plain timestamp, to get this item shown
|
|
on the date where it applies. This is a frequent misunderstanding by
|
|
Org users. In Org mode, /scheduling/ means setting a date when you
|
|
want to start working on an action item.
|
|
|
|
|
|
You may use timestamps with repeaters in scheduling and deadline
|
|
entries. Org mode will issue early and late warnings based on the
|
|
assumption that the timestamp represents the /nearest instance/ of
|
|
the repeater. However, the use of diary sexp entries like
|
|
~<%%(org-float t 42)>~
|
|
|
|
in scheduling and deadline timestamps is limited. Org mode does not
|
|
know enough about the internals of each sexp function to issue early and
|
|
late warnings. However, it will show the item on each day where the
|
|
sexp entry matches.
|
|
|
|
*** Inserting deadline/schedule
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Planning items
|
|
:TITLE: Inserting deadlines or schedules
|
|
:END:
|
|
|
|
The following commands allow you to quickly insert a deadline or to schedule
|
|
an item:[fn:66]
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-d)}}}, ~org-deadline~ ::
|
|
#+kindex: C-c C-d
|
|
|
|
Insert {{{samp(DEADLINE)}}} keyword along with a stamp. The insertion
|
|
will happen in the line directly following the headline. Any CLOSED
|
|
timestamp will be removed. When called with a prefix arg, an existing
|
|
deadline will be removed from the entry. Depending on the variable ~org-log-redeadline~, a note will be taken when changing an existing
|
|
deadline.[fn:67]
|
|
|
|
- {{{kbd(C-c C-s)}}}, ~org-schedule~ ::
|
|
#+kindex: C-c C-s
|
|
|
|
Insert {{{samp(SCHEDULED)}}} keyword along with a stamp. The insertion
|
|
will happen in the line directly following the headline. Any
|
|
{{{samp(CLOSED)}}} timestamp will be removed. When called with a
|
|
prefix argument, remove the scheduling date from the entry. Depending
|
|
on the variable ~org-log-reschedule~, a note will be taken when
|
|
changing an existing scheduling time.[fn:68]
|
|
|
|
- {{{kbd(C-c C-x C-k)}}}, ~org-mark-entry-for-agenda-action~ ::
|
|
#+kindex: C-c C-x C-k
|
|
#+kindex: k a
|
|
#+kindex: k s
|
|
|
|
Mark the current entry for agenda action. After you have marked the
|
|
entry like this, you can open the agenda or the calendar to find an
|
|
appropriate date. With the cursor on the selected date, press
|
|
{{{kbd(k s)}}} or {{{kbd(k d)}}} to schedule the marked item.
|
|
|
|
- {{{kbd(C-c / d)}}}, ~org-check-deadlines~ ::
|
|
#+kindex: C-c / d
|
|
#+cindex: sparse tree, for deadlines
|
|
#+vindex: org-deadline-warning-days
|
|
|
|
Create a sparse tree with all deadlines that are either past-due, or
|
|
which will become due within ~org-deadline-warning-days~. With
|
|
{{{kbd(C-u)}}} prefix, show all deadlines in the file. With a numeric
|
|
prefix, check that many days. For example, {{{kbd(C-1 C-c / d)}}}
|
|
shows all deadlines due tomorrow.
|
|
|
|
- {{{kbd(C-c / b)}}}, ~org-check-before-date~ ::
|
|
#+kindex: C-c / b
|
|
|
|
Sparse tree for deadlines and scheduled items before a given date.
|
|
|
|
- {{{kbd(C-c / a)}}}, ~org-check-after-date~ ::
|
|
#+kindex: C-c / a
|
|
|
|
Sparse tree for deadlines and scheduled items after a given date.
|
|
|
|
|
|
Note that ~org-schedule~ and ~org-deadline~ supports setting the date
|
|
by indicating a relative time: e.g. +1d will set the date to the next
|
|
day after today, and --1w will set the date to the previous week
|
|
before any current timestamp.
|
|
|
|
*** Repeated tasks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Items that show up again and again
|
|
:END:
|
|
#+cindex: tasks, repeated
|
|
#+cindex: repeated tasks
|
|
|
|
Some tasks need to be repeated again and again. Org mode helps to
|
|
organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
|
|
or plain timestamp. In the following example:
|
|
|
|
#+begin_example
|
|
,** TODO Pay the rent
|
|
DEADLINE: <2005-10-01 Sat +1m>
|
|
#+end_example
|
|
|
|
{{{noindent}}} the ~+1m~ is a repeater; the intended interpretation is
|
|
that the task has a deadline on <2005-10-01> and repeats itself every
|
|
(one) month starting from that time. You can use yearly, monthly,
|
|
weekly, daily and hourly repeat cookies by using the ~y/w/m/d/h~
|
|
letters. If you need both a repeater and a special warning period in a
|
|
deadline entry, the repeater should come first and the warning period
|
|
last: ~DEADLINE: <2005-10-01 Sat +1m -3d>~.
|
|
|
|
#+vindex: org-todo-repeat-to-state
|
|
|
|
Deadlines and scheduled items produce entries in the agenda when they
|
|
are over-due, so it is important to be able to mark such an entry as
|
|
completed once you have done so. When you mark a DEADLINE or a
|
|
SCHEDULE with the TODO keyword DONE, it will no longer produce entries
|
|
in the agenda. The problem with this is, however, that then also the
|
|
/next/ instance of the repeated entry will not be active. Org mode
|
|
deals with this in the following way: When you try to mark such an
|
|
entry DONE (using {{{kbd(C-c C-t)}}}), it will shift the base date of
|
|
the repeating timestamp by the repeater interval, and immediately set
|
|
the entry state back to TODO.[fn:69] In the example above, setting the
|
|
state to DONE would actually switch the date like this:
|
|
|
|
#+begin_example
|
|
,** TODO Pay the rent
|
|
DEADLINE: <2005-11-01 Tue +1m>
|
|
#+end_example
|
|
|
|
#+vindex: org-log-repeat
|
|
|
|
A timestamp will be added under the deadline, to keep a record that
|
|
you actually acted on the previous instance of this deadline.[fn:70]
|
|
|
|
As a consequence of shifting the base date, this entry will no longer be
|
|
visible in the agenda when checking past dates, but all future instances
|
|
will be visible.
|
|
|
|
With the {{{samp(+1m)}}} cookie, the date shift will always be exactly one
|
|
month. So if you have not paid the rent for three months, marking this
|
|
entry DONE will still keep it as an overdue deadline. Depending on the
|
|
task, this may not be the best way to handle it. For example, if you
|
|
forgot to call your father for 3 weeks, it does not make sense to call
|
|
him 3 times in a single day to make up for it. Finally, there are tasks
|
|
like changing batteries which should always repeat a certain time
|
|
/after/ the last time you did it. For these tasks, Org mode has
|
|
special repeaters {{{samp(++)}}} and {{{samp(.+)}}}. For example:
|
|
|
|
#+begin_example
|
|
,** TODO Call Father
|
|
DEADLINE: <2008-02-10 Sun ++1w>
|
|
Marking this DONE will shift the date by at least one week,
|
|
but also by as many weeks as it takes to get this date into
|
|
the future. However, it stays on a Sunday, even if you called
|
|
and marked it done on Saturday.
|
|
,** TODO Check the batteries in the smoke detectors
|
|
DEADLINE: <2005-11-01 Tue .+1m>
|
|
Marking this DONE will shift the date to one month after
|
|
today.
|
|
#+end_example
|
|
|
|
You may have both scheduling and deadline information for a specific
|
|
task---just make sure that the repeater intervals on both are the
|
|
same.
|
|
|
|
An alternative to using a repeater is to create a number of copies of
|
|
a task subtree, with dates shifted in each copy. The command
|
|
{{{kbd(C-c C-x c)}}} was created for this purpose, it is described in
|
|
[[Structure editing]].
|
|
|
|
** Clocking work time
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tracking how long you spend on a task
|
|
:END:
|
|
#+cindex: clocking time
|
|
#+cindex: time clocking
|
|
|
|
Org mode allows you to clock the time you spend on specific tasks in a
|
|
project. When you start working on an item, you can start the clock. When
|
|
you stop working on that task, or when you mark the task done, the clock is
|
|
stopped and the corresponding time interval is recorded. It also computes
|
|
the total time spent on each subtree of a project.[fn:71] And it remembers a
|
|
history or tasks recently clocked, to that you can jump quickly between a
|
|
number of tasks absorbing your time.
|
|
|
|
To save the clock history across Emacs sessions, use:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-clock-persist 'history)
|
|
(org-clock-persistence-insinuate)
|
|
#+end_src
|
|
|
|
When you clock into a new task after resuming Emacs, the incomplete
|
|
clock will be found (see [[Resolving idle time]]) and you will be prompted
|
|
about what to do with it.[fn:72]
|
|
|
|
*** Clocking commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Starting and stopping a clock
|
|
:END:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-i)}}}, ~org-clock-in~ ::
|
|
#+kindex: C-c C-x C-i
|
|
#+vindex: org-clock-into-drawer
|
|
#+vindex: org-clock-continuously
|
|
#+cindex: property, LOG_INTO_DRAWER
|
|
|
|
Start the clock on the current item (clock-in). This inserts the CLOCK
|
|
keyword together with a timestamp. If this is not the first clocking
|
|
of this item, the multiple CLOCK lines will be wrapped into a ~:LOGBOOK:~ drawer (see also the variable ~org-clock-into-drawer~).
|
|
You can also overrule the setting of this variable for a subtree by
|
|
setting a ~CLOCK_INTO_DRAWER~ or ~LOG_INTO_DRAWER~ property. When
|
|
called with a {{{kbd(C-u)}}} prefix argument, select the task from a
|
|
list of recently clocked tasks. With two {{{kbd(C-u C-u)}}} prefixes,
|
|
clock into the task at point and mark it as the default task; the
|
|
default task will then always be available with letter {{{kbd(d)}}}
|
|
when selecting a clocking task. With three {{{kbd(C-u C-u C-u)}}}
|
|
prefixes, force continuous clocking by starting the clock when the
|
|
last clock stopped.@*
|
|
|
|
#+cindex: property: CLOCK_MODELINE_TOTAL
|
|
#+cindex: property: LAST_REPEAT
|
|
#+vindex: org-clock-modeline-total
|
|
|
|
While the clock is running, the current clocking time is shown in the
|
|
mode line, along with the title of the task. The clock time shown will
|
|
be all time ever clocked for this task and its children. If the task
|
|
has an effort estimate (see [[Effort estimates]]), the mode line displays
|
|
the current clocking time against it.[fn:73] If the task is a
|
|
repeating one (see [[Repeated tasks]]), only the time since the last reset
|
|
of the task will be shown.[fn:74] More control over what time is shown
|
|
can be exercised with the ~CLOCK_MODELINE_TOTAL~ property. It may have
|
|
the values ~current~ to show only the current clocking instance, ~today~ to show all time clocked on this tasks today (see also the
|
|
variable ~org-extend-today-until~), ~all~ to include all time, or ~auto~ which is the default.[fn:75] Clicking with {{{kbd(mouse-1)}}}
|
|
onto the mode line entry will pop up a menu with clocking options.
|
|
|
|
- {{{kbd(C-c C-x C-o)}}}, ~org-clock-out~ ::
|
|
#+kindex: C-c C-x C-o
|
|
#+vindex: org-log-note-clock-out
|
|
|
|
Stop the clock (clock-out). This inserts another timestamp at the same
|
|
location where the clock was last started. It also directly computes
|
|
the resulting time in inserts it after the time range as
|
|
{{{samp(=>HH:MM)}}}. See the variable ~org-log-note-clock-out~ for the
|
|
possibility to record an additional note together with the clock-out
|
|
timestamp.[fn:76]
|
|
|
|
- {{{kbd(C-c C-x C-x)}}}, ~org-clock-in-last~ ::
|
|
#+kindex: C-c C-x C-x
|
|
#+vindex: org-clock-continuously
|
|
|
|
Reclock the last clocked task. With one {{{kbd(C-u)}}} prefix
|
|
argument, select the task from the clock history. With two
|
|
{{{kbd(C-u)}}} prefixes, force continuous clocking by starting the
|
|
clock when the last clock stopped.
|
|
|
|
- {{{kbd(C-c C-x C-e)}}}, ~org-clock-modify-effort-estimate~ ::
|
|
#+kindex: C-c C-x C-e
|
|
|
|
Update the effort estimate for the current clock task.
|
|
- {{{kbd(C-c C-c)}}} {{{kbd(C-c C-y)}}}, ~org-evaluate-time-range~ ::
|
|
#+kindex: C-c C-c
|
|
#+kindex: C-c C-y
|
|
#+kindex: C-c C-c
|
|
|
|
Recompute the time interval after changing one of the timestamps. This
|
|
is only necessary if you edit the timestamps directly. If you change
|
|
them with {{{kbdkey(S-,cursor)}}} keys, the update is automatic.
|
|
|
|
- {{{kbdkey(C-S-,up)}}} {{{kbdkey(C-S-,down)}}}, ~org-clock-timestamps-up/down~ ::
|
|
#+kindex: C-S-@key{up/down}
|
|
|
|
On ~CLOCK~ log lines, increase/decrease both timestamps so that the
|
|
clock duration keeps the same.
|
|
|
|
- {{{kbdkey(S-M-,up)}}} {{{kbdkey(S-M-,down)}}}, ~org-timestamp-up/down~ ::
|
|
#+kindex: S-M-@key{up/down}
|
|
|
|
On ~CLOCK~ log lines, increase/decrease the timestamp at point and the
|
|
one of the previous (or the next clock) timestamp by the same
|
|
duration. For example, if you hit {{{kbdkey(S-M-,up)}}} to increase a
|
|
clocked-out timestamp by five minutes, then the clocked-in timestamp
|
|
of the next clock will be increased by five minutes.
|
|
|
|
- {{{kbd(C-c C-t)}}}, ~org-todo~ ::
|
|
#+kindex: C-c C-t
|
|
|
|
Changing the TODO state of an item to DONE automatically stops the
|
|
clock if it is running in this same item.
|
|
|
|
- {{{kbd(C-c C-x C-q)}}}, ~org-clock-cancel~ ::
|
|
#+kindex: C-c C-x C-q
|
|
|
|
Cancel the current clock. This is useful if a clock was started by
|
|
mistake, or if you ended up working on something else.
|
|
|
|
- {{{kbd(C-c C-x C-j)}}}, ~org-clock-goto~ ::
|
|
#+kindex: C-c C-x C-j
|
|
|
|
Jump to the headline of the currently clocked in task. With a
|
|
{{{kbd(C-u)}}} prefix arg, select the target task from a list of
|
|
recently clocked tasks.
|
|
|
|
- {{{kbd(C-c C-x C-d)}}}, ~org-clock-display~ ::
|
|
#+kindex: C-c C-x C-d
|
|
#+vindex: org-remove-highlights-with-change
|
|
|
|
Display time summaries for each subtree in the current buffer. This
|
|
puts overlays at the end of each headline, showing the total time
|
|
recorded under that heading, including the time of any subheadings.
|
|
You can use visibility cycling to study the tree, but the overlays
|
|
disappear when you change the buffer (see variable ~org-remove-highlights-with-change~) or press {{{kbd(C-c C-c)}}}.
|
|
|
|
|
|
The {{{kbd(l)}}} key may be used in the timeline (see [[Timeline for a
|
|
single file]]) and in the agenda (see [[Weekly/daily agenda]]) to show which
|
|
tasks have been worked on or closed during a day.
|
|
*Important:* note that both ~org-clock-out~ and ~org-clock-in-last~
|
|
can have a global keybinding and will not modify the window
|
|
disposition.
|
|
|
|
*** The clock table
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Detailed reports
|
|
:END:
|
|
#+cindex: clocktable, dynamic block
|
|
#+cindex: report, of clocked time
|
|
|
|
Org mode can produce quite complex reports based on the time clocking
|
|
information. Such a report is called a /clock table/, because it is
|
|
formatted as one or several Org tables.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-r)}}}, ~org-clock-report~ ::
|
|
#+kindex: C-c C-x C-r
|
|
|
|
Insert a dynamic block (see [[Dynamic blocks]]) containing a clock report
|
|
as an Org mode table into the current file. When the cursor is at an
|
|
existing clock table, just update it. When called with a prefix
|
|
argument, jump to the first clock report in the current document and
|
|
update it. The clock table always includes also trees with ~:ARCHIVE:~
|
|
tag.
|
|
|
|
- {{{kbd(C-c C-c)}}} {{{kbd(C-c C-x C-u)}}}, ~org-dblock-update~ ::
|
|
#+kindex: C-c C-c
|
|
|
|
Update dynamic block at point. The cursor needs to be in the ~#+BEGIN~ line of the dynamic block.
|
|
|
|
- {{{kbd(C-u C-c C-x C-u)}}} ::
|
|
#+kindex: C-u C-c C-x C-u
|
|
|
|
Update all dynamic blocks (see [[Dynamic blocks]]). This is useful if you
|
|
have several clock table blocks in a buffer.
|
|
|
|
- {{{kbdkey(S-,left)}}} {{{kbdkey(S-,right)}}}, ~org-clocktable-try-shift~ ::
|
|
|
|
Shift the current ~:block~ interval and update the table. The cursor
|
|
needs to be in the ~#+BEGIN: clocktable~ line for this command. If ~:block~ is ~today~, it will be shifted to ~today-1~ etc.
|
|
|
|
|
|
Here is an example of the frame for a clock table as it is inserted
|
|
into the buffer with the {{{kbd(C-c C-x C-r)}}} command:
|
|
|
|
#+cindex: #+BEGIN, clocktable
|
|
#+begin_example
|
|
,#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
|
|
,#+END: clocktable
|
|
#+end_example
|
|
{{{noindent}}}
|
|
#+vindex: org-clocktable-defaults
|
|
The {{{samp(BEGIN)}}} line and specify a number of options to define the scope,
|
|
structure, and formatting of the report. Defaults for all these options can
|
|
be configured in the variable ~org-clocktable-defaults~.
|
|
|
|
{{{noindent}}} First there are options that determine which clock entries are to
|
|
be selected:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- :maxlevel ::
|
|
|
|
Maximum level depth to which times are listed in the table. Clocks at
|
|
deeper levels will be summed into the upper level.
|
|
|
|
- :scope ::
|
|
|
|
The scope to consider. This can be any of the following:
|
|
|
|
- nil :: the current buffer or narrowed region
|
|
- file :: the full current buffer
|
|
- subtree :: the subtree where the clocktable is located
|
|
- tree {{{var(N)}}} :: the surrounding level {{{var(N)}}} tree, for example ~tree3~
|
|
- tree :: the surrounding level 1 tree
|
|
- agenda :: all agenda files
|
|
- ("file"..) :: scan these files
|
|
- file-with-archives :: current file and its archives
|
|
- agenda-with-archives :: all agenda files, including archives
|
|
|
|
- :block ::
|
|
|
|
The time block to consider. This block is specified either absolute,
|
|
or relative to the current time and may be any of these formats:
|
|
|
|
- 2007-12-31 :: New year eve 2007
|
|
- 2007-12 :: December 2007
|
|
- 2007-W50 :: ISO-week 50 in 2007
|
|
- 2007-Q2 :: 2nd quarter in 2007
|
|
- 2007 :: the year 2007
|
|
- today, yesterday, today-{{{var(N)}}} :: a relative day
|
|
- thisweek, lastweek, thisweek-{{{var(N)}}} :: a relative week
|
|
- thismonth, lastmonth, thismonth-{{{var(N)}}} :: a relative month
|
|
- thisyear, lastyear, thisyear-{{{var(N)}}} :: a relative year
|
|
|
|
Use {{{kbdkey(S-,left)}}} or {{{kbdkey(S-,right)}}} to shift the
|
|
time interval.
|
|
|
|
- :tstart ::
|
|
|
|
A time string specifying when to start considering times.
|
|
|
|
- :tend ::
|
|
|
|
A time string specifying when to stop considering times.
|
|
|
|
- :step ::
|
|
|
|
Set to ~week~ or ~day~ to split the table into chunks. To use this, ~:block~ or ~:tstart~, ~:tend~ are needed.
|
|
|
|
- :stepskip0 ::
|
|
|
|
Do not show steps that have zero time.
|
|
|
|
- :fileskip0 ::
|
|
|
|
Do not show table sections from files which did not contribute.
|
|
|
|
- :tags ::
|
|
|
|
A tags match to select entries that should contribute. See [[Matching
|
|
tags and properties]] for the match syntax.
|
|
|
|
|
|
Then there are options which determine the formatting of the table. There
|
|
options are interpreted by the function ~org-clocktable-write-default~,
|
|
but you can specify your own function using the ~:formatter~ parameter.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- :emphasize ::
|
|
|
|
When ~t~, emphasize level one and level two items.
|
|
|
|
- :lang ::
|
|
|
|
Language to use for descriptive cells like "Task".[fn:77]
|
|
|
|
- :link ::
|
|
|
|
Link the item headlines in the table to their origins.
|
|
|
|
- :narrow ::
|
|
|
|
An integer to limit the width of the headline column in the org table.
|
|
If you write it like {{{samp(50!)}}}, then the headline will also be
|
|
shortened in export.
|
|
|
|
- :indent ::
|
|
|
|
Indent each headline field according to its level.
|
|
|
|
- :tcolumns ::
|
|
|
|
Number of columns to be used for times. If this is smaller than ~:maxlevel~, lower levels will be lumped into one column.
|
|
|
|
- :level ::
|
|
|
|
Should a level number column be included?
|
|
|
|
- :compact ::
|
|
|
|
Abbreviation for ~:level nil :indent t :narrow 40! :tcolumns 1~. All
|
|
are overwritten except if there is an explicit ~:narrow~.
|
|
|
|
- :timestamp ::
|
|
|
|
A timestamp for the entry, when available. Look for SCHEDULED,
|
|
DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.
|
|
|
|
- :properties ::
|
|
|
|
List of properties that should be shown in the table. Each property
|
|
will get its own column.
|
|
|
|
- :inherit-props ::
|
|
|
|
When this flag is ~t~, the values for ~:properties~ will be inherited.
|
|
|
|
- :formula ::
|
|
|
|
Content of a ~#+TBLFM~ line to be added and evaluated. As a special
|
|
case, {{{samp(:formula %)}}} adds a column with % time. If you do not
|
|
specify a formula here, any existing formula below the clock table
|
|
will survive updates and be evaluated.
|
|
|
|
- :formatter ::
|
|
|
|
A function to format clock data and insert it into the buffer.
|
|
|
|
|
|
To get a clock summary of the current level 1 tree, for the current
|
|
day, you could write:
|
|
|
|
#+begin_example
|
|
,#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
|
|
,#+END: clocktable
|
|
#+end_example
|
|
|
|
{{{noindent}}} To use a specific time range you could write:[fn:78]
|
|
|
|
#+begin_example
|
|
,#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
|
|
:tend "<2006-08-10 Thu 12:00>"
|
|
,#+END: clocktable
|
|
#+end_example
|
|
|
|
A summary of the current subtree with % times would be:
|
|
|
|
#+begin_example
|
|
,#+BEGIN: clocktable :scope subtree :link t :formula %
|
|
,#+END: clocktable
|
|
#+end_example
|
|
|
|
A horizontally compact representation of everything clocked during
|
|
last week would be:
|
|
|
|
#+begin_example
|
|
,#+BEGIN: clocktable :scope agenda :block lastweek :compact t
|
|
,#+END: clocktable
|
|
#+end_example
|
|
|
|
*** Resolving idle time
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Resolving time when you've been idle
|
|
:TITLE: Resolving idle time and continuous clocking
|
|
:END:
|
|
|
|
#+cindex: resolve idle time
|
|
#+cindex: idle, resolve, dangling
|
|
|
|
If you clock in on a work item, and then walk away from your
|
|
computer---perhaps to take a phone call---you often need to
|
|
``resolve'' the time you were away by either subtracting it from the
|
|
current clock, or applying it to another one.
|
|
|
|
#+vindex: org-clock-idle-time
|
|
|
|
By customizing the variable ~org-clock-idle-time~ to some integer,
|
|
such as 10 or 15, Emacs can alert you when you get back to your
|
|
computer after being idle for that many minutes, and ask what you want
|
|
to do with the idle time.[fn:79] There will be a question waiting for you
|
|
when you get back, indicating how much idle time has passed
|
|
(constantly updated with the current amount), as well as a set of
|
|
choices to correct the discrepancy:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(k)}}} ::
|
|
#+kindex: k
|
|
|
|
To keep some or all of the minutes and stay clocked in, press
|
|
{{{kbd(k)}}}. Org will ask how many of the minutes to keep. Press
|
|
{{{key(RET)}}} to keep them all, effectively changing nothing, or
|
|
enter a number to keep that many minutes.
|
|
|
|
- {{{kbd(K)}}} ::
|
|
#+kindex: K
|
|
|
|
If you use the shift key and press {{{kbd(K)}}}, it will keep however
|
|
many minutes you request and then immediately clock out of that task.
|
|
If you keep all of the minutes, this is the same as just clocking out
|
|
of the current task.
|
|
|
|
- {{{kbd(s)}}} ::
|
|
#+kindex: s
|
|
|
|
To keep none of the minutes, use {{{kbd(s)}}} to subtract all the away
|
|
time from the clock, and then check back in from the moment you
|
|
returned.
|
|
|
|
- {{{kbd(S)}}} ::
|
|
#+kindex: S
|
|
|
|
To keep none of the minutes and just clock out at the start of the
|
|
away time, use the shift key and press {{{kbd(S)}}}. Remember that
|
|
using shift will always leave you clocked out, no matter which option
|
|
you choose.
|
|
|
|
- {{{kbd(C)}}} ::
|
|
#+kindex: C
|
|
|
|
To cancel the clock altogether, use {{{kbd(C)}}}. Note that if instead
|
|
of canceling you subtract the away time, and the resulting clock
|
|
amount is less than a minute, the clock will still be canceled rather
|
|
than clutter up the log with an empty entry.
|
|
|
|
|
|
What if you subtracted those away minutes from the current clock, and
|
|
now want to apply them to a new clock? Simply clock in to any task
|
|
immediately after the subtraction. Org will notice that you have
|
|
subtracted time ``on the books'', so to speak, and will ask if you
|
|
want to apply those minutes to the next task you clock in on.
|
|
|
|
There is one other instance when this clock resolution magic occurs.
|
|
Say you were clocked in and hacking away, and suddenly your cat chased
|
|
a mouse who scared a hamster that crashed into your UPS's power
|
|
button! You suddenly lose all your buffers, but thanks to auto-save
|
|
you still have your recent Org mode changes, including your last clock
|
|
in.
|
|
|
|
If you restart Emacs and clock into any task, Org will notice that you
|
|
have a dangling clock which was never clocked out from your last
|
|
session. Using that clock's starting time as the beginning of the
|
|
unaccounted-for period, Org will ask how you want to resolve that
|
|
time. The logic and behavior is identical to dealing with away time
|
|
due to idleness; it is just happening due to a recovery event rather
|
|
than a set amount of idle time.
|
|
|
|
You can also check all the files visited by your Org agenda for
|
|
dangling clocks at any time using {{{kbd(M-x org-resolve-clocks RET)}}}
|
|
(or {{{kbd(C-c C-x C-z)}}}).
|
|
|
|
*** Continuous clocking
|
|
#+cindex: continuous clocking
|
|
#+vindex: org-clock-continuously
|
|
|
|
You may want to start clocking from the time when you clocked out the
|
|
previous task. To enable this systematically, set
|
|
~org-clock-continuously~ to ~t~. Each time you clock in, Org retrieves
|
|
the clock-out time of the last clocked entry for this session, and
|
|
start the new clock from there.
|
|
|
|
If you only want this from time to time, use three universal prefix
|
|
arguments with ~org-clock-in~ and two {{{kbd(C-u C-u)}}} with
|
|
~org-clock-in-last~.
|
|
|
|
** Effort estimates
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Planning work effort in advance
|
|
:END:
|
|
#+cindex: effort estimates
|
|
#+cindex: property, Effort
|
|
#+vindex: org-effort-property
|
|
|
|
If you want to plan your work in a very detailed way, or if you need
|
|
to produce offers with quotations of the estimated work effort, you
|
|
may want to assign effort estimates to entries. If you are also
|
|
clocking your work, you may later want to compare the planned effort
|
|
with the actual working time, a great way to improve planning
|
|
estimates. Effort estimates are stored in a special property
|
|
{{{samp(Effort)}}}.[fn:80] You can set the effort for an entry with
|
|
the following commands:
|
|
|
|
#+attr_texinfo: :table-type table :indic @kbd
|
|
- {{{kbd(C-c C-x e)}}}, ~org-set-effort~ ::
|
|
#+kindex: C-c C-x e
|
|
|
|
Set the effort estimate for the current entry. With a numeric prefix
|
|
argument, set it to the Nth allowed value (see below). This command is
|
|
also accessible from the agenda with the {{{kbd(e)}}} key.
|
|
|
|
- {{{kbd(C-c C-x C-e)}}}, ~org-clock-modify-effort-estimate~ ::
|
|
#+kindex: C-c C-x C-e
|
|
|
|
Modify the effort estimate of the item currently being clocked.
|
|
|
|
|
|
Clearly the best way to work with effort estimates is through column
|
|
view (see [[Column view]]). You should start by setting up discrete values
|
|
for effort estimates, and a ~COLUMNS~ format that displays these
|
|
values together with clock sums (if you want to clock your time). For
|
|
a specific buffer you can use:
|
|
|
|
#+begin_example
|
|
,#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
|
|
,#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort){:} %CLOCKSUM
|
|
#+end_example
|
|
|
|
#+vindex: org-global-properties
|
|
#+vindex: org-columns-default-format
|
|
|
|
{{{noindent}}} or, even better, you can set up these values globally
|
|
by customizing the variables ~org-global-properties~ and
|
|
~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 {{{kbdkey(S-,right)}}} and
|
|
{{{kbdkey(S-,left)}}} to change the value. The values you enter will
|
|
immediately be summed up in the hierarchy. In the column next to it,
|
|
any clocked time will be displayed.
|
|
|
|
#+vindex: org-agenda-columns-add-appointments-to-effort-sum
|
|
|
|
If you switch to column view in the daily/weekly agenda, the effort column
|
|
will summarize the estimated work effort for each day, and you can use this to find space in your schedule. To get
|
|
an overview of the entire part of the day that is committed, you can set the
|
|
option ~org-agenda-columns-add-appointments-to-effort-sum~.[fn:179] 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.
|
|
|
|
Effort estimates can be used in secondary agenda filtering that is
|
|
triggered with the {{{kbd(/)}}} key in the agenda (see [[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.
|
|
|
|
** Relative timer
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Notes with a running timer
|
|
:TITLE: Taking notes with a relative timer
|
|
:END:
|
|
#+cindex: relative timer
|
|
|
|
When taking notes during, for example, a meeting or a video viewing, it can
|
|
be useful to have access to times relative to a starting time. Org provides
|
|
such a relative timer and make it easy to create timed notes.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x .)}}}, ~org-timer~ ::
|
|
#+kindex: C-c C-x .
|
|
|
|
Insert a relative time into the buffer. The first time you use this, the
|
|
timer will be started. When called with a prefix argument, the timer is
|
|
restarted.
|
|
|
|
- {{{kbd(C-c C-x -)}}}, ~org-timer-item~ ::
|
|
#+kindex: C-c C-x -
|
|
|
|
Insert a description list item with the current relative time. With a prefix
|
|
argument, first reset the timer to 0.
|
|
|
|
- {{{kbdkey(M-,RET)}}}, ~org-insert-heading~ ::
|
|
#+kindex: M-@key{RET}
|
|
|
|
Once the timer list is started, you can also use {{{kbdkey(M-,RET)}}}
|
|
to insert new timer items.
|
|
|
|
- {{{kbd(C-c C-x \,)}}} ::
|
|
#+kindex: C-c C-x ,
|
|
#+kindex: C-c C-x ,
|
|
|
|
Pause the timer, or continue it if it is already paused
|
|
({{{command(org-timer-pause-or-continue)}}}).
|
|
|
|
- {{{kbd(C-u C-c C-x \,)}}} ::
|
|
#+kindex: C-u C-c C-x ,
|
|
#+kindex: C-u C-c C-x ,
|
|
|
|
Stop the timer. After this, you can only start a new timer, not
|
|
continue the old one. This command also removes the timer from the
|
|
mode line.
|
|
|
|
- {{{kbd(C-c C-x 0)}}}, ~org-timer-start~ ::
|
|
#+kindex: C-c C-x 0
|
|
|
|
Reset the timer without inserting anything into the buffer. By
|
|
default, the timer is reset to 0. When called with a {{{kbd(C-u)}}}
|
|
prefix, reset the timer to specific starting offset. The user is
|
|
prompted for the offset, with a default taken from a timer string at
|
|
point, if any, So this can be used to restart taking notes after a
|
|
break in the process. When called with a double prefix argument
|
|
{{{kbd(C-u C-u)}}}, change all timer strings in the active region by a
|
|
certain amount. This can be used to fix timer strings if the timer was
|
|
not started at exactly the right moment.
|
|
|
|
** Countdown timer
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Starting a countdown timer for a task
|
|
:END:
|
|
#+cindex: Countdown timer
|
|
#+kindex: C-c C-x ;
|
|
#+kindex: ;
|
|
|
|
Calling ~org-timer-set-timer~ from an Org mode buffer runs a countdown
|
|
timer. Use {{{kbd(;)}}} from agenda buffers, {{{key(C-c C-x ;)}}}
|
|
everywhere else.
|
|
~org-timer-set-timer~ prompts the user for a duration and displays a
|
|
countdown timer in the modeline. ~org-timer-default-timer~ sets the
|
|
default countdown value. Giving a prefix numeric argument overrides this
|
|
default value.
|
|
|
|
* Capture - Refile - Archive
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The ins and outs for projects
|
|
:END:
|
|
#+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 does this using a process called /capture/. It also can
|
|
store files related to a task (/attachments/) in a special directory.
|
|
Once in the system, tasks and projects need to be moved around. Moving
|
|
completed project trees to an archive file keeps the system compact
|
|
and fast.
|
|
|
|
** Capture
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Capturing new stuff
|
|
:END:
|
|
#+cindex: capture
|
|
|
|
Org's method for capturing new items is heavily inspired by John
|
|
Wiegley excellent remember package. Up to version 6.36 Org used a
|
|
special setup for {{{file(remember.el)}}}. The file {{{file(org-remember.el)}}}
|
|
is still part of Org mode for backward compatibility with existing
|
|
setups. You can find the documentation for org-remember at
|
|
[[http://orgmode.org/org-remember.pdf]].
|
|
|
|
The new capturing setup described here is preferred and should be used by new
|
|
users. To convert your ~org-remember-templates~, run the following command:
|
|
{{{kbdspckey(M-x org-capture-import-remember-templates,RET)}}}
|
|
|
|
{{{noindent}}} and then customize the new variable with
|
|
{{{kbd(M-x customize-variable org-capture-templates)}}}, check the result, and
|
|
save the customization. You can then use both remember and capture
|
|
until you are familiar with the new mechanism.
|
|
|
|
Capture lets you quickly store notes with little interruption of your work
|
|
flow. The basic process of capturing is very similar to remember, but Org
|
|
does enhance it with templates and more.
|
|
|
|
*** Setting up capture
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Where notes will be stored
|
|
:END:
|
|
|
|
The following customization sets a default target file for notes, and defines
|
|
a global key for capturing new material.[fn:81]
|
|
|
|
#+vindex: org-default-notes-file
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-default-notes-file (concat org-directory "/notes.org"))
|
|
(define-key global-map "\C-cc" 'org-capture)
|
|
#+end_src
|
|
|
|
*** Using capture
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Commands to invoke and terminate capture
|
|
:END:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c c)}}}, ~org-capture~ ::
|
|
#+kindex: C-c c
|
|
#+cindex: date tree
|
|
|
|
Call the command ~org-capture~. Note that this keybinding is global
|
|
and not active by default - you need to install it. If you have
|
|
templates defined (see [[Capture templates]], it will offer these
|
|
templates for selection or use a new Org outline node as the default
|
|
template. It will insert the template into the target file and switch
|
|
to an indirect buffer narrowed to this new node. You may then insert
|
|
the information you want.
|
|
|
|
- {{{kbd(C-c C-c)}}}, ~org-capture-finalize~ ::
|
|
#+kindex: C-c C-c
|
|
|
|
Once you have finished entering information into the capture buffer,
|
|
{{{kbd(C-c C-c)}}} will return you to the window configuration before
|
|
the capture process, so that you can resume your work without further
|
|
distraction. When called with a prefix argument, finalize and then
|
|
jump to the captured item.
|
|
|
|
- {{{kbd(C-c C-w)}}}, ~org-capture-refile~ ::
|
|
#+kindex: C-c C-w
|
|
|
|
Finalize the capture process by refiling the note to a different place
|
|
(see [[Refile and copy]]). Please realize that this is a normal refiling
|
|
command that will be executed---so the cursor position at the moment
|
|
you run this command is important. If you have inserted a tree with a
|
|
parent and children, first move the cursor back to the parent. Any
|
|
prefix argument given to this command will be passed on to the ~org-refile~ command.
|
|
|
|
- {{{kbd(C-c C-k)}}}, ~org-capture-kill~ ::
|
|
#+kindex: C-c C-k
|
|
|
|
Abort the capture process and return to the previous state.
|
|
|
|
|
|
You can also call ~org-capture~ in a special way from the agenda,
|
|
using the {{{kbd(k c)}}} key combination. With this access, timestamps
|
|
inserted by the selected capture template will default to the cursor
|
|
date in the agenda, rather than to the current date.
|
|
|
|
To find the locations of the last stored capture, use ~org-capture~ with
|
|
prefix commands:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-u C-c c)}}} ::
|
|
#+kindex: C-u C-c c
|
|
|
|
Visit the target location of a capture template. You get to select the
|
|
template in the usual way.
|
|
|
|
- {{{kbd(C-u C-u C-c c)}}} ::
|
|
#+kindex: C-u C-u C-c c
|
|
|
|
Visit the last stored capture item in its buffer.
|
|
|
|
|
|
#+vindex: org-capture-bookmark
|
|
#+cindex: org-capture-last-stored
|
|
|
|
You can also jump to the bookmark ~org-capture-last-stored~, which
|
|
will automatically be created unless you set ~org-capture-bookmark~ to
|
|
~nil~.
|
|
|
|
To insert the capture at point in an Org buffer, call ~org-capture~
|
|
with a ~C-0~ prefix argument.
|
|
|
|
*** Capture templates
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Define the outline of different note types
|
|
:END:
|
|
#+cindex: templates, for Capture
|
|
|
|
You can use templates for different types of capture items, and for
|
|
different target locations. The easiest way to create such templates
|
|
is through the customize interface.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c c C)}}} ::
|
|
#+kindex: C-c c C
|
|
|
|
Customize the variable ~org-capture-templates~.
|
|
|
|
|
|
Before we give the formal description of template definitions, let's
|
|
look at an example. Say you would like to use one template to create
|
|
general TODO entries, and you want to put these entries under the
|
|
heading {{{samp(Tasks)}}} in your file {{{file(~/org/gtd.org)}}}.
|
|
Also, a date tree in the file {{{file(journal.org)}}} should capture
|
|
journal entries. A possible configuration would look like:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-capture-templates
|
|
'(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
|
|
"* TODO %?\n %i\n %a")
|
|
("j" "Journal" entry (file+datetree "~/org/journal.org")
|
|
"* %?\nEntered on %U\n %i\n %a")))
|
|
#+end_src
|
|
|
|
{{{noindent}}} If you then press {{{kbd(C-c c t)}}}, Org will prepare
|
|
the template for you like this:
|
|
|
|
#+begin_example
|
|
,* TODO
|
|
[[file:link to where you initiated capture]]
|
|
#+end_example
|
|
|
|
{{{noindent}}} During expansion of the template, ~%a~ has been
|
|
replaced by a link to the location from where you called the capture
|
|
command. This can be extremely useful for deriving tasks from emails,
|
|
for example. You fill in the task definition, press ~C-c C-c~ and Org
|
|
returns you to the same place where you started the capture process.
|
|
|
|
To define special keys to capture to a particular template without
|
|
going through the interactive template selection, you can create your
|
|
key binding like this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(define-key global-map "\C-cx"
|
|
(lambda () (interactive) (org-capture nil "x")))
|
|
#+end_src
|
|
|
|
**** Template elements
|
|
:PROPERTIES:
|
|
:DESCRIPTION: What is needed for a complete template entry
|
|
:END:
|
|
|
|
Now lets look at the elements of a template definition. Each entry in
|
|
~org-capture-templates~ is a list with the following items:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~keys~ ::
|
|
|
|
The keys that will select the template, as a string, characters
|
|
only, for example "a" for a template to be selected with a
|
|
single key, or "BTW" for selection with two keys. When using
|
|
several keys, keys using the same prefix key must be sequential
|
|
in the list and preceded by a 2-element entry explaining the
|
|
prefix key, for example:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
("b" "Templates for marking stuff to buy")
|
|
#+end_src
|
|
|
|
{{{noindent}}} If you do not define a template for the {{{kbd(C)}}}
|
|
key, this key will be used to open the customize buffer for this
|
|
complex variable.
|
|
|
|
- ~description~ ::
|
|
|
|
A short string describing the template, which will be shown during
|
|
selection.
|
|
|
|
- ~type~ ::
|
|
|
|
The type of entry, a symbol. Valid values are:
|
|
|
|
- ~entry~ ::
|
|
|
|
An Org mode node, with a headline. Will be filed as the child of the
|
|
target entry or as a top-level entry. The target file should be an Org
|
|
mode file.
|
|
|
|
- ~item~ ::
|
|
|
|
A plain list item, placed in the first plain list at the target
|
|
location. Again the target file should be an Org file.
|
|
|
|
- ~checkitem~ ::
|
|
|
|
A checkbox item. This only differs from the plain list item by the
|
|
default template.
|
|
|
|
- ~table-line~ ::
|
|
|
|
A new line in the first table at the target location. Where exactly
|
|
the line will be inserted depends on the properties ~:prepend~ and ~:table-line-pos~ (see below).
|
|
|
|
- plain ::
|
|
|
|
Text to be inserted as it is.
|
|
|
|
- target ::
|
|
#+vindex: org-default-notes-file
|
|
|
|
Specification of where the captured item should be placed. In Org mode
|
|
files, targets usually define a node. Entries will become children of this
|
|
node. Other types will be added to the table or list in the body of this
|
|
node. Most target specifications contain a file name. If that file name is
|
|
the empty string, it defaults to ~org-default-notes-file~. A file can
|
|
also be given as a variable, function, or Emacs Lisp form.
|
|
|
|
Valid values are:
|
|
|
|
- ~(file "path/to/file")~ ::
|
|
|
|
Text will be placed at the beginning or end of that file.
|
|
|
|
- ~(id "id of existing org entry")~ ::
|
|
|
|
Filing as child of this entry, or in the body of the entry.
|
|
|
|
- ~(file+headline "path/to/file" "node headline")~ ::
|
|
|
|
Fast configuration if the target heading is unique in the file.
|
|
|
|
- ~(file+olp "path/to/file" "Level 1 heading" "Level 2" ...)~ ::
|
|
|
|
For non-unique headings, the full path is safer.
|
|
|
|
- ~(file+regexp "path/to/file" "regexp to find location")~ ::
|
|
|
|
Use a regular expression to position the cursor.
|
|
|
|
- ~(file+datetree "path/to/file")~ ::
|
|
|
|
Will create a heading in a date tree for today's date.
|
|
|
|
- ~(file+datetree+prompt "path/to/file")~ ::
|
|
|
|
Will create a heading in a date tree, but will prompt for the date.
|
|
|
|
- ~(file+function "path/to/file" function-finding-location)~ ::
|
|
|
|
A function to find the right location in the file.
|
|
|
|
- ~(clock)~ ::
|
|
|
|
File to the entry that is currently being clocked.
|
|
|
|
- ~(function function-finding-location)~ ::
|
|
|
|
Most general way, write your own function to find both
|
|
file and location.
|
|
|
|
- ~template~ ::
|
|
|
|
The template for creating the capture item. If you leave this empty,
|
|
an appropriate default template will be used. Otherwise this is a
|
|
string with escape codes, which will be replaced depending on time and
|
|
context of the capture call. The string with escapes may be loaded
|
|
from a template file, using the special syntax ~(file "path/to/template")~. See below for more details.
|
|
|
|
- ~properties~ ::
|
|
|
|
The rest of the entry is a property list of additional options.
|
|
Recognized properties are:
|
|
|
|
- ~:prepend~ ::
|
|
|
|
Normally new captured information will be appended at the target
|
|
location (last child, last table line, last list item, ...). Setting
|
|
this property will change that.
|
|
|
|
- ~:immediate-finish~ ::
|
|
|
|
When set, do not offer to edit the information, just file it away
|
|
immediately. This makes sense if the template only needs information
|
|
that can be added automatically.
|
|
|
|
- ~:empty-lines~ ::
|
|
|
|
Set this to the number of lines to insert before and after the new
|
|
item. The default is 0, and the only other common value is 1.
|
|
|
|
- ~:clock-in~ ::
|
|
|
|
Start the clock in this item.
|
|
|
|
- ~:clock-keep~ ::
|
|
|
|
Keep the clock running when filing the captured entry.
|
|
|
|
- ~:clock-resume~ ::
|
|
|
|
If starting the capture interrupted a clock, restart that clock when
|
|
finished with the capture. Note that ~:clock-keep~ has precedence over ~:clock-resume~. When setting both to ~t~, the current clock will run
|
|
and the previous one will not be resumed.
|
|
|
|
- ~:unnarrowed~ ::
|
|
|
|
Do not narrow the target buffer, simply show the full buffer. Default
|
|
is to narrow it so that you only see the new material.
|
|
|
|
- ~:table-line-pos~ ::
|
|
|
|
Specification of the location in the table where the new line should
|
|
be inserted. It should be a string like "II-3" meaning that the new
|
|
line should become the third line before the second horizontal
|
|
separator line.
|
|
|
|
- ~:kill-buffer~ ::
|
|
|
|
If the target file was not yet visited when capture was invoked, kill
|
|
the buffer again after capture is completed.
|
|
|
|
**** Template expansion
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Filling in information about time and context
|
|
:END:
|
|
|
|
In the template itself, special {{{kbd(%)}}}-escapes allow dynamic
|
|
insertion of content.[fn:82] The templates are expanded in the order given
|
|
here:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- %[{{{var(file)}}}] ::
|
|
|
|
Insert the contents of the file given by {{{var(file)}}}.
|
|
|
|
- %({{{var(sexp)}}}) ::
|
|
|
|
Evaluate Elisp {{{var(sexp)}}} and replace with the result. The
|
|
{{{var(sexp)}}} must return a string.
|
|
|
|
- %<...> ::
|
|
|
|
The result of format-time-string on the ... format specification.
|
|
|
|
- %t ::
|
|
|
|
Timestamp, date only.
|
|
|
|
- %T ::
|
|
|
|
Timestamp, with date and time.
|
|
|
|
- %u, %U ::
|
|
|
|
Like ~%t~, ~%T~ above, but inactive timestamps.
|
|
|
|
- %i ::
|
|
|
|
Initial content, the region when capture is called while the region is
|
|
active. The entire text will be indented like ~%i~ itself.
|
|
|
|
- %a ::
|
|
|
|
Annotation, normally the link created with ~org-store-link~.
|
|
|
|
- %A ::
|
|
|
|
Like ~%a~, but prompt for the description part.
|
|
|
|
- %l ::
|
|
|
|
Like ~%a~, but only insert the literal link.
|
|
|
|
- %c ::
|
|
|
|
Current kill ring head.
|
|
|
|
- %x ::
|
|
|
|
Content of the X clipboard.
|
|
|
|
- %k ::
|
|
|
|
Title of the currently clocked task.
|
|
|
|
- %K ::
|
|
|
|
Link to the currently clocked task.
|
|
|
|
- %n ::
|
|
|
|
User name (taken from ~user-full-name~).
|
|
|
|
- %f ::
|
|
|
|
File visited by current buffer when org-capture was called.
|
|
|
|
- %F ::
|
|
|
|
Full path of the file or directory visited by current buffer.
|
|
|
|
- %:keyword ::
|
|
|
|
Specific information for certain link types, see below.
|
|
|
|
- %^g ::
|
|
|
|
Prompt for tags, with completion on tags in target file.
|
|
|
|
- %^G ::
|
|
|
|
Prompt for tags, with completion all tags in all agenda files.
|
|
|
|
- %^t ::
|
|
|
|
Like ~%t~, but prompt for date. Similarly ~%^T~, ~%^u~, ~%^U~. You may
|
|
define a prompt like ~%^{Birthday}t~.
|
|
|
|
- %^C ::
|
|
|
|
Interactive selection of which kill or clip to use.
|
|
|
|
- %^L ::
|
|
|
|
Like ~%^C~, but insert as link.
|
|
|
|
- %^{PROP}p ::
|
|
|
|
Prompt the user for a value for property {{{var(prop)}}}.
|
|
|
|
- %^{PROMPT} ::
|
|
|
|
Prompt the user for a string and replace this sequence with it. You
|
|
may specify a default value and a completion table with ~%^{prompt|default|completion2|completion3...}~. The arrow keys access
|
|
a prompt-specific history.
|
|
|
|
- %\n ::
|
|
|
|
Insert the text entered at the nth %^{PROMPT}, where ~n~ is
|
|
a number, starting from 1.
|
|
|
|
- %? ::
|
|
|
|
After completing the template, position cursor here.
|
|
|
|
|
|
{{{noindent}}} For specific link types, the following keywords will be
|
|
defined:[fn:83]
|
|
|
|
#+vindex: org-from-is-user-regexp
|
|
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- bbdb :: ~%:name %:company~
|
|
- irc :: ~%:server %:port %:nick~
|
|
- vm vm-imap wl mh mew rmail :: ~%:type %:subject %:message-id~ ~%:from %:fromname %:fromaddress~ ~%:to %:toname %:toaddress~ ~%:date~ (message date header field) ~%:date-timestamp~ (date as active timestamp) ~%:date-timestamp-inactive~ (date as inactive timestamp) ~%:fromto~ (either "to NAME" or "from NAME")[fn:84]
|
|
- gnus :: ~%:group~, for messages also all email fields
|
|
- w3 w3m :: ~%:url~
|
|
- info :: ~%:file %:node~
|
|
- calendar :: ~%:date~
|
|
|
|
{{{noindent}}} To place the cursor after template expansion use:
|
|
|
|
#+begin_example
|
|
%? After completing the template, position cursor here.
|
|
#+end_example
|
|
|
|
**** Templates in contexts
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Only show a template in a specific context
|
|
:END:
|
|
|
|
#+vindex: org-capture-templates-contexts
|
|
|
|
To control whether a capture template should be accessible from a
|
|
specific context, you can customize ~org-capture-templates-contexts~.
|
|
Let's say, for example, that you have a capture template "p" for
|
|
storing Gnus emails containing patches. Then you would configure this
|
|
option like this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-capture-templates-contexts
|
|
'(("p" (in-mode . "message-mode"))))
|
|
#+end_src
|
|
|
|
You can also tell that the command key "p" should refer to another
|
|
template. In that case, add this command key like this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-capture-templates-contexts
|
|
'(("p" "q" (in-mode . "message-mode"))))
|
|
#+end_src
|
|
|
|
See the docstring of the variable ~org-capture-templates-contexts~ for
|
|
more information.
|
|
|
|
** Attachments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Add files to tasks
|
|
:END:
|
|
#+cindex: attachments
|
|
#+vindex: org-attach-directory
|
|
|
|
It is often useful to associate reference material with an outline
|
|
node/task. Small chunks of plain text can simply be stored in the
|
|
subtree of a project. Hyperlinks (see [[Hyperlinks]]) can establish
|
|
associations with files that live elsewhere on your computer or in the
|
|
cloud, like emails or source code files belonging to a project.
|
|
Another method is /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.[fn:85] If you initialize this directory with
|
|
~git init~, Org will automatically commit changes when it sees them.
|
|
The attachment system has been contributed to Org by John Wiegley.
|
|
|
|
In cases where it seems better to do so, you can also attach a
|
|
directory of your choice to an entry. You can also make children
|
|
inherit the attachment directory from a parent, so that an entire
|
|
subtree uses the same attached directory.
|
|
|
|
{{{noindent}}} The following commands deal with attachments:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-a)}}}, ~org-attach~ ::
|
|
#+kindex: C-c C-a
|
|
|
|
The dispatcher for commands related to the attachment system. After
|
|
these keys, a list of commands is displayed and you must press an
|
|
additional key to select a command:
|
|
|
|
- {{{kbd(a)}}}, ~org-attach-attach~ ::
|
|
#+kindex: C-c C-a a
|
|
#+vindex: org-attach-method
|
|
|
|
Select a file and move it into the task's attachment directory. The
|
|
file will be copied, moved, or linked, depending on ~org-attach-method~. Note that hard links are not supported on all
|
|
systems.
|
|
|
|
- {{{kbd(c)}}}/{{{kbd(m)}}}/{{{kbd(l)}}} ::
|
|
#+kindex: C-c C-a c
|
|
#+kindex: C-c C-a m
|
|
#+kindex: C-c C-a l
|
|
|
|
Attach a file using the copy/move/link method. Note that hard links
|
|
are not supported on all systems.
|
|
|
|
- {{{kbd(n)}}}, ~org-attach-new~ ::
|
|
#+kindex: C-c C-a n
|
|
|
|
Create a new attachment as an Emacs buffer.
|
|
|
|
- {{{kbd(z)}}}, ~org-attach-sync~ ::
|
|
#+kindex: C-c C-a z
|
|
|
|
Synchronize the current task with its attachment directory, in case
|
|
you added attachments yourself.
|
|
|
|
- {{{kbd(o)}}}, ~org-attach-open~ ::
|
|
#+kindex: C-c C-a o
|
|
#+vindex: org-file-apps
|
|
|
|
Open current task's attachment. If there is more than one, prompt for
|
|
a file name first. Opening will follow the rules set by
|
|
~org-file-apps~. For more details, see the information on following
|
|
hyperlinks (see [[Handling links]]).
|
|
|
|
- {{{kbd(O)}}}, ~org-attach-open-in-emacs~ ::
|
|
#+kindex: C-c C-a O
|
|
|
|
Also open the attachment, but force opening the file in Emacs.
|
|
|
|
- {{{kbd(f)}}}, ~org-attach-reveal~ ::
|
|
#+kindex: C-c C-a f
|
|
|
|
Open the current task's attachment directory.
|
|
|
|
- {{{kbd(F)}}}, ~org-attach-reveal-in-emacs~ ::
|
|
#+kindex: C-c C-a F
|
|
|
|
Also open the directory, but force using @command{dired} in Emacs.
|
|
|
|
- {{{kbd(d)}}}, ~org-attach-delete-one~ ::
|
|
#+kindex: C-c C-a d
|
|
|
|
Select and delete a single attachment.
|
|
|
|
- {{{kbd(D)}}}, ~org-attach-delete-all~ ::
|
|
#+kindex: C-c C-a D
|
|
|
|
Delete all of a task's attachments. A safer way is to open the
|
|
directory in {{{command(dired)}}} and delete from there.
|
|
|
|
- {{{kbd(s)}}}, ~org-attach-set-directory~ ::
|
|
#+kindex: C-c C-a s
|
|
#+cindex: property, ATTACH_DIR
|
|
|
|
Set a specific directory as the entry's attachment directory. This
|
|
works by putting the directory path into the ~ATTACH_DIR~ property.
|
|
|
|
- {{{kbd(i)}}}, ~org-attach-set-inherit~ ::
|
|
#+kindex: C-c C-a i
|
|
#+cindex: property, ATTACH_DIR_INHERIT
|
|
|
|
Set the ~ATTACH_DIR_INHERIT~ property, so that children will use the
|
|
same directory for attachments as the parent does.
|
|
|
|
** RSS feeds
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Getting input from RSS feeds
|
|
:END:
|
|
#+cindex: RSS feeds
|
|
#+cindex: Atom feeds
|
|
|
|
Org can add and change entries based on information found in RSS feeds and
|
|
Atom feeds. You could use this to make a task out of each new podcast in a
|
|
podcast feed. Or you could use a phone-based note-creating service on the
|
|
web to import tasks into Org. To access feeds, configure the variable
|
|
~org-feed-alist~. The docstring of this variable has detailed
|
|
information. Here is an example:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-feed-alist
|
|
'(("Slashdot"
|
|
"http://rss.slashdot.org/Slashdot/slashdot"
|
|
"~/txt/org/feeds.org" "Slashdot Entries")))
|
|
#+end_src
|
|
|
|
{{{noindent}}} will configure that new items from the feed provided by
|
|
~rss.slashdot.org~ will result in new entries in the file
|
|
{{{file(~/org/feeds.org)}}} under the heading ~Slashdot Entries~,
|
|
whenever the following command is used:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x g)}}}, ~org-feed-update-all~ ::
|
|
#+kindex: C-c C-x g
|
|
|
|
Collect items from the feeds configured in ~org-feed-alist~ and act
|
|
upon them.
|
|
|
|
- {{{kbd(C-c C-x G)}}}, ~org-feed-goto-inbox~ ::
|
|
#+kindex: C-c C-x G
|
|
|
|
Prompt for a feed name and go to the inbox configured for this feed.
|
|
|
|
|
|
Under the same headline, Org will create a drawer
|
|
{{{samp(FEEDSTATUS)}}} in which it will store information about the
|
|
status of items in the feed, to avoid adding the same item several
|
|
times. You should add {{{samp(FEEDSTATUS)}}} to the list of drawers in
|
|
that file:
|
|
|
|
#+begin_example
|
|
,#+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS
|
|
#+end_example
|
|
|
|
For more information, including how to read atom feeds, see
|
|
{{{file(org-feed.el)}}} and the docstring of ~org-feed-alist~.
|
|
|
|
** Protocols
|
|
:PROPERTIES:
|
|
:DESCRIPTION: External (e.g., browser) access to Emacs and Org
|
|
:TITLE: Protocols for external access
|
|
:END:
|
|
|
|
#+cindex: protocols, for external access
|
|
#+cindex: emacsserver
|
|
|
|
You can set up Org for handling protocol calls from outside
|
|
applications that are passed to Emacs through the
|
|
{{{file(emacsserver)}}}. For example, you can configure bookmarks in
|
|
your web browser to send a link to the current page to Org and create
|
|
a note from it using capture (see [[Capture]]). Or you could create a
|
|
bookmark that will tell Emacs to open the local source file of a
|
|
remote website you are looking at with the browser. See
|
|
[[http://orgmode.org/worg/org-contrib/org-protocol.php]] for detailed
|
|
documentation and setup instructions.
|
|
|
|
** Refile and copy
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Moving/copying a tree from one place to another
|
|
:END:
|
|
#+cindex: refiling notes
|
|
#+cindex: copying notes
|
|
|
|
When reviewing the captured data, you may want to refile or to copy some of
|
|
the entries into a different list, for example into a project. Cutting,
|
|
finding the right location, and then pasting the note is cumbersome. To
|
|
simplify this process, you can use the following special command:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c M-w)}}}, ~org-copy~ ::
|
|
#+kindex: C-c M-w
|
|
#+findex: org-copy
|
|
|
|
Copying works like refiling, except that the original note is not deleted.
|
|
|
|
- {{{kbd(C-c C-w)}}}, ~org-refile~ ::
|
|
#+kindex: C-c C-w
|
|
#+findex: org-refile
|
|
#+vindex: org-reverse-note-order
|
|
#+vindex: org-refile-targets
|
|
#+vindex: org-refile-use-outline-path
|
|
#+vindex: org-outline-path-complete-in-steps
|
|
#+vindex: org-refile-allow-creating-parent-nodes
|
|
#+vindex: org-log-refile
|
|
#+vindex: org-refile-use-cache
|
|
|
|
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 ~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 ~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 ~org-refile-use-outline-path~ and ~org-outline-path-complete-in-steps~. If you would like to be able to
|
|
create new nodes as new parents for refiling on the fly, check the
|
|
variable ~org-refile-allow-creating-parent-nodes~. When the variable ~org-log-refile~ is set, a timestamp or a note will be recorded when
|
|
an entry has been refiled.[fn:86]
|
|
|
|
- {{{kbd(C-u C-c C-w)}}} ::
|
|
#+kindex: C-u C-c C-w
|
|
|
|
Use the refile interface to jump to a heading.
|
|
|
|
- {{{kbd(C-u C-u C-c C-w)}}}, ~org-refile-goto-last-stored~ ::
|
|
#+kindex: C-u C-u C-c C-w
|
|
|
|
Jump to the location where ~org-refile~ last moved a tree to.
|
|
|
|
- {{{kbd(C-2 C-c C-w)}}} ::
|
|
#+kindex: C-2 C-c C-w
|
|
|
|
Refile as the child of the item currently being clocked.
|
|
|
|
- {{{kbd(C-0 C-c C-w)}}} or {{{kbd(C-u C-u C-u C-c C-w)}}}, ~org-refile-cache-clear~ ::
|
|
#+kindex: C-u C-u C-u C-c C-w
|
|
#+kindex: C-0 C-c C-w
|
|
|
|
Clear the target cache. Caching of refile targets can be turned on by
|
|
setting ~org-refile-use-cache~. To make the command see new possible
|
|
targets, you have to clear the cache with this command.
|
|
|
|
** Archiving
|
|
:PROPERTIES:
|
|
:DESCRIPTION: What to do with finished products
|
|
:END:
|
|
#+cindex: archiving
|
|
|
|
When a project represented by a (sub)tree is finished, you may want to
|
|
move the tree out of the way and to stop it from contributing to the
|
|
agenda. Archiving is important to keep your working files compact and
|
|
global searches like the construction of agenda views fast.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-a)}}}, ~org-archive-subtree-default~ ::
|
|
#+kindex: C-c C-x C-a
|
|
#+vindex: org-archive-default-command
|
|
|
|
Archive the current entry using the command specified in the variable ~org-archive-default-command~.
|
|
|
|
*** Moving subtrees
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Moving a tree to an archive file
|
|
:TITLE: Moving a tree to an archive file
|
|
:END:
|
|
#+cindex: external archiving
|
|
|
|
The most common archiving action is to move a project tree to another file,
|
|
the archive file.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}}, ~org-archive-subtree~ ::
|
|
#+kindex: C-c C-x C-s
|
|
#+kindex: C-c $
|
|
#+vindex: org-archive-location
|
|
|
|
Archive the subtree starting at the cursor position to the location
|
|
given by ~org-archive-location~.
|
|
|
|
- {{{Kbd(C-u C-c C-x C-s)}}} ::
|
|
#+kindex: C-u C-c C-x C-s
|
|
|
|
Check if any direct children of the current headline could be moved to
|
|
the archive. To do this, each subtree is checked for open TODO
|
|
entries. If none are found, the command offers to move it to the
|
|
archive location. If the cursor is /not/ on a headline when this
|
|
command is invoked, the level 1 trees will be checked.
|
|
|
|
|
|
#+cindex: archive locations
|
|
|
|
The default archive location is a file in the same directory as the
|
|
current file, with the name derived by appending {{{file(_archive)}}}
|
|
to the current file name. You can also choose what heading to file
|
|
archived items under, with the possibility to add them to a datetree
|
|
in a file. For information and examples on how to specify the file and
|
|
the heading, see the documentation string of the variable
|
|
~org-archive-location~.
|
|
|
|
There is also an in-buffer option for setting this variable, for
|
|
example:[fn:87]
|
|
|
|
#+cindex: #+ARCHIVE
|
|
#+begin_example
|
|
,#+ARCHIVE: %s_done::
|
|
#+end_example
|
|
|
|
#+cindex: property, ARCHIVE
|
|
|
|
{{{noindent}}} If you would like to have a special ARCHIVE location
|
|
for a single entry or a (sub)tree, give the entry an ~:ARCHIVE:~
|
|
property with the location as the value (see [[Properties and columns]]).
|
|
|
|
#+vindex: org-archive-save-context-info
|
|
|
|
When a subtree is moved, it receives a number of special properties
|
|
that record context information like the file from where the entry
|
|
came, its outline path the archiving time etc. Configure the variable
|
|
~org-archive-save-context-info~ to adjust the amount of information
|
|
added.
|
|
|
|
*** Internal archiving
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Switch off a tree but keep it in the file
|
|
:END:
|
|
|
|
If you want to just switch off (for agenda views) certain subtrees
|
|
without moving them to a different file, you can use the ~ARCHIVE
|
|
tag~.
|
|
|
|
A headline that is marked with the ARCHIVE tag (see [[Tags]]) stays at
|
|
its location in the outline tree, but behaves in the following way:
|
|
|
|
- It does not open when you attempt to do so with a visibility cycling
|
|
command (see [[Visibility cycling]]). You can force cycling archived
|
|
subtrees with {{{kbdkey(C-,TAB)}}}, or by setting the option ~org-cycle-open-archived-trees~. Also normal outline commands like ~show-all~ will open archived subtrees.
|
|
|
|
#+vindex: org-cycle-open-archived-trees
|
|
|
|
- During sparse tree construction (see [[Sparse trees]]), matches in
|
|
archived subtrees are not exposed, unless you configure the option ~org-sparse-tree-open-archived-trees~.
|
|
|
|
#+vindex: org-sparse-tree-open-archived-trees
|
|
|
|
- During agenda view construction (see [[Agenda views]]), the content of
|
|
archived trees is ignored unless you configure the option ~org-agenda-skip-archived-trees~, in which case these trees will
|
|
always be included. In the agenda you can press {{{kbd(v a)}}} to
|
|
get archives temporarily included.
|
|
|
|
#+vindex: org-agenda-skip-archived-trees
|
|
|
|
- Archived trees are not exported (see [[Exporting]]), only the headline
|
|
is. Configure the details using the variable ~org-export-with-archived-trees~.
|
|
|
|
#+vindex: org-export-with-archived-trees
|
|
|
|
- Archived trees are excluded from column view unless the variable ~org-columns-skip-archived-trees~ is configured to ~nil~.
|
|
|
|
#+vindex: org-columns-skip-archived-trees
|
|
|
|
|
|
The following commands help manage the ARCHIVE tag:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x a)}}}, ~org-toggle-archive-tag~ ::
|
|
#+kindex: C-c C-x a
|
|
|
|
Toggle the ARCHIVE tag for the current headline. When the tag is set,
|
|
the headline changes to a shadowed face, and the subtree below it is
|
|
hidden.
|
|
|
|
- {{{kbd(C-u C-c C-x a)}}} ::
|
|
#+kindex: C-u C-c C-x a
|
|
|
|
Check if any direct children of the current headline should be
|
|
archived. To do this, each subtree is checked for open TODO entries.
|
|
If none are found, the command offers to set the ARCHIVE tag for the
|
|
child. If the cursor is /not/ on a headline when this command is
|
|
invoked, the level 1 trees will be checked.
|
|
|
|
- {{{kbdkey(C-,TAB)}}}, ~org-force-cycle-archived~ ::
|
|
|
|
Cycle a tree even if it is tagged with ARCHIVE.
|
|
|
|
- {{{kbd(C-c C-x A)}}}, ~org-archive-to-archive-sibling~ ::
|
|
#+kindex: C-c C-x A
|
|
|
|
Move the current entry to the /Archive Sibling/. This is a sibling of
|
|
the entry with the heading {{{samp(Archive)}}} and the tag
|
|
{{{samp(ARCHIVE)}}}. The entry becomes a child of that sibling and in
|
|
this way retains a lot of its original context, including inherited
|
|
tags and approximate position in the outline.
|
|
|
|
* FIXME Agenda views
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Collecting information into views
|
|
:ALT_TITLE: Agenda Views
|
|
:END:
|
|
|
|
Due to the way Org works, TODO items, time-stamped items, and tagged
|
|
headlines can be scattered throughout a file or even a number of
|
|
files. To get an overview of open action items, or of events that are
|
|
important for a particular date, this information must be collected,
|
|
sorted and displayed in an organized way.
|
|
|
|
Org can select items based on various criteria and display them
|
|
in a separate buffer. Seven different view types are provided:
|
|
|
|
- an /agenda/ that is like a calendar and shows information for
|
|
specific dates,
|
|
|
|
- a /TODO list/ that covers all unfinished action items,
|
|
|
|
- a /match view/, showings headlines based on the tags, properties,
|
|
and TODO state associated with them,
|
|
|
|
- a /timeline view/ that shows all events in a single Org file, in
|
|
time-sorted view,
|
|
|
|
- a /text search view/ that shows all entries from multiple files that
|
|
contain specified keywords,
|
|
|
|
- a /stuck projects view/ showing projects that currently don't move
|
|
along, and
|
|
|
|
- /custom views/ that are special searches and combinations of
|
|
different views.
|
|
|
|
|
|
{{{noindent}}} The extracted information is displayed in a special
|
|
/agenda buffer/. This buffer is read-only, but provides commands to
|
|
visit the corresponding locations in the original Org files, and even
|
|
to edit these files remotely.
|
|
|
|
#+vindex: org-agenda-window-setup
|
|
#+vindex: org-agenda-restore-windows-after-quit
|
|
|
|
Two variables control how the agenda buffer is displayed and whether
|
|
the window configuration is restored when the agenda exits:
|
|
~org-agenda-window-setup~ and ~org-agenda-restore-windows-after-quit~.
|
|
|
|
** Agenda files
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Files being searched for agenda information
|
|
:END:
|
|
#+cindex: agenda files
|
|
#+cindex: files for agenda
|
|
#+vindex: org-agenda-files
|
|
|
|
The information to be shown is normally collected from all /agenda
|
|
files/, the files listed in the variable ~org-agenda-files~.[fn:180] If
|
|
a directory is part of this list, all files with the extension
|
|
{{{file(.org)}}} in this directory will be part of the list.
|
|
|
|
Thus, even if you only work with a single Org file, that file should
|
|
be put into the list.[fn:88] You can customize ~org-agenda-files~, but
|
|
the easiest way to maintain it is through the following commands
|
|
|
|
#+cindex: files, adding to agenda list
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c [)}}}, ~org-agenda-file-to-front~ ::
|
|
#+kindex: C-c [
|
|
|
|
Add current file to the list of agenda files. The file is added to the
|
|
front of the list. If it was already in the list, it is moved to the
|
|
front. With a prefix argument, file is added/moved to the end.
|
|
|
|
- {{{kbd(C-c ])}}}, ~org-remove-file~ ::
|
|
#+kindex: C-c ]
|
|
|
|
Remove current file from the list of agenda files.
|
|
|
|
- {{{kbd(C-')}}} {{{kbd(C-)}}}, ~org-cycle-agenda-files~ ::
|
|
#+kindex: C-'
|
|
#+kindex: C-,
|
|
#+cindex: cycling, of agenda files
|
|
|
|
Cycle through agenda file list, visiting one file after the other.
|
|
|
|
- {{{kbd(M-x org-iswitchb)}}} ::
|
|
#+findex: org-iswitchb
|
|
|
|
Command to use an ~iswitchb~-like interface to switch to and between
|
|
Org buffers.
|
|
|
|
|
|
{{{noindent}}} The Org menu contains the current list of files and can
|
|
be used to visit any of them.
|
|
|
|
If you would like to focus the agenda temporarily on a file not in
|
|
this list, or on just one file in the list, or even on only a subtree
|
|
in a file, then this can be done in different ways. For a single
|
|
agenda command, you may press {{{kbd(<)}}} once or several times in
|
|
the dispatcher (see [[Agenda dispatcher]]). To restrict the agenda scope
|
|
for an extended period, use the following commands:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x <)}}}, ~org-agenda-set-restriction-lock~ ::
|
|
#+kindex: C-c C-x <
|
|
|
|
Permanently restrict the agenda to the current subtree. When with a
|
|
prefix argument, or with the cursor before the first headline in a
|
|
file, the agenda scope is set to the entire file. This restriction
|
|
remains in effect until removed with {{{kbd(C-c C-x >)}}}, or by
|
|
typing either {{{kbd(<)}}} or {{{kbd(>)}}} in the agenda dispatcher.
|
|
If there is a window displaying an agenda view, the new restriction
|
|
takes effect immediately.
|
|
|
|
- {{{kbd(C-c C-x >)}}}, ~org-agenda-remove-restriction-lock~ ::
|
|
#+kindex: C-c C-x >
|
|
|
|
Remove the permanent restriction created by {{{kbd(C-c C-x <)}}}.
|
|
|
|
|
|
{{{noindent}}} When working with {{{file(speedbar.el)}}}, you can use
|
|
the following commands in the Speedbar frame:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(<)}}} in the speedbar frame ~org-speedbar-set-agenda-restriction~ ::
|
|
#+kindex: <
|
|
|
|
Permanently restrict the agenda to the item---either an Org file or a
|
|
subtree in such a file---at the cursor in the Speedbar frame. If there
|
|
is a window displaying an agenda view, the new restriction takes
|
|
effect immediately.
|
|
|
|
- {{{kbd(>)}}} in the speedbar frame ~org-agenda-remove-restriction-lock~ ::
|
|
#+kindex: >
|
|
|
|
Lift the restriction.
|
|
|
|
** Agenda dispatcher
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Keyboard access to agenda views
|
|
:TITLE: The agenda dispatcher
|
|
:END:
|
|
#+cindex: agenda dispatcher
|
|
#+cindex: dispatching agenda commands
|
|
|
|
The views are created through a dispatcher, which should be bound to a
|
|
global key---for example {{{kbd(C-c a)}}} (see [[Activation]]). In the
|
|
following we will assume that {{{kbd(C-c a)}}} is indeed how the
|
|
dispatcher is accessed and list keyboard access to commands
|
|
accordingly. After pressing {{{kbd(C-c a)}}}, an additional letter is
|
|
required to execute a command. The dispatcher offers the following
|
|
default commands:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(a)}}} ::
|
|
#+kindex: C-c a a
|
|
|
|
Create the calendar-like agenda (see [[Weekly/daily agenda]]).
|
|
|
|
- {{{kbd(t)}}} or {{{kbd(T)}}} ::
|
|
#+kindex: C-c a t
|
|
#+kindex: C-c a T
|
|
|
|
Create a list of all TODO items (see [[Global TODO list]]).
|
|
|
|
- {{{kbd(m)}}} or {{{kbd(M)}}} ::
|
|
#+kindex: C-c a m
|
|
#+kindex: C-c a M
|
|
|
|
Create a list of headlines matching a TAGS expression (see [[Matching tags and properties]]).
|
|
|
|
- {{{kbd(L)}}} ::
|
|
#+kindex: C-c a L
|
|
|
|
Create the timeline view for the current buffer
|
|
(see [[Timeline for a single file]]).
|
|
|
|
- {{{kbd(s)}}} ::
|
|
#+kindex: C-c a s
|
|
|
|
Create a list of entries selected by a boolean expression of keywords
|
|
and/or regular expressions that must or must not occur in the entry.
|
|
|
|
- {{{kbd(/)}}} ::
|
|
#+kindex: C-c a /
|
|
#+vindex: org-agenda-text-search-extra-files
|
|
|
|
Search for a regular expression in all agenda files and additionally
|
|
in the files listed in ~org-agenda-text-search-extra-files~. This uses
|
|
the Emacs command ~multi-occur~. A prefix argument can be used to
|
|
specify the number of context lines for each match, default is
|
|
1.
|
|
|
|
- {{{kbd(#)}}} or {{{kbd(!)}}} ::
|
|
#+kindex: C-c a #
|
|
#+kindex: C-c a !
|
|
Create a list of stuck projects (see [[Stuck projects]]).
|
|
|
|
- {{{kbd(<)}}} ::
|
|
#+kindex: C-c a <
|
|
|
|
Restrict an agenda command to the current buffer.[fn:89] After
|
|
pressing {{{kbd(<)}}}, you still need to press the character selecting
|
|
the command.
|
|
|
|
- {{{kbd(< <)}}} ::
|
|
#+kindex: C-c a < <
|
|
|
|
If there is an active region, restrict the following agenda command to
|
|
the region. Otherwise, restrict it to the current subtree.[fn:90]
|
|
After pressing {{{kbd(< <)}}}, you still need to press the character
|
|
selecting the command.
|
|
|
|
- {{{kbd(*)}}} ::
|
|
#+kindex: C-c a *
|
|
#+vindex: org-agenda-sticky
|
|
|
|
Toggle sticky agenda views. By default, Org maintains only a single
|
|
agenda buffer and rebuilds it each time you change the view, to make
|
|
sure everything is always up to date. If you switch between views
|
|
often and the build time bothers you, you can turn on sticky agenda
|
|
buffers (make this the default by customizing the variable ~org-agenda-sticky~). With sticky agendas, the dispatcher only
|
|
switches to the selected view, you need to update it by hand with
|
|
{{{kbd(r)}}} or {{{kbd(g)}}}. You can toggle sticky agenda view any
|
|
time with ~org-toggle-sticky-agenda~.
|
|
|
|
|
|
You can also define custom commands that will be accessible through
|
|
the dispatcher, just like the default commands. This includes the
|
|
possibility to create extended agenda buffers that contain several
|
|
blocks together, for example the weekly agenda, the global TODO list
|
|
and a number of special tags matches. See [[Custom agenda views]].
|
|
|
|
** Built-in agenda views
|
|
:PROPERTIES:
|
|
:DESCRIPTION: What is available out of the box?
|
|
:TITLE: The built-in agenda views
|
|
:END:
|
|
In this section we describe the built-in views.
|
|
|
|
*** FIXED Weekly/daily agenda
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The calendar page with current tasks
|
|
:END:
|
|
#+cindex: agenda
|
|
#+cindex: weekly agenda
|
|
#+cindex: daily agenda
|
|
|
|
The purpose of the weekly/daily /agenda/ is to act like a page of a
|
|
paper agenda, showing all the tasks for the current week or day.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c a a)}}}, ~org-agenda-list~ ::
|
|
#+cindex: org-agenda, command
|
|
|
|
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 (like
|
|
{{{kbd(C-u 2 1 C-c a a)}}}) you may set the number of days to be
|
|
displayed.[fn:91]
|
|
|
|
|
|
#+vindex: org-agenda-span
|
|
#+vindex: org-agenda-ndays
|
|
The default number of days displayed in the agenda is set by the variable
|
|
~org-agenda-span~ (or the obsolete ~org-agenda-ndays~). This
|
|
variable can be set to any number of days you want to see by default in the
|
|
agenda, or to a span name, such a ~day~, ~week~, ~month~ or
|
|
~year~.
|
|
|
|
Remote editing from the agenda buffer means, for example, that you can
|
|
change the dates of deadlines and appointments from the agenda buffer.
|
|
The commands available in the Agenda buffer are listed in [[Agenda
|
|
commands]].
|
|
|
|
**** FIXED Calendar/Diary integration
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Integrate the Emacs diary with Org
|
|
:END:
|
|
#+cindex: calendar integration
|
|
#+cindex: diary integration
|
|
#+cindex: Reingold, Edward M.
|
|
|
|
Emacs contains the calendar and diary by Edward M. Reingold. The
|
|
calendar displays a three-month calendar with holidays from different
|
|
countries and cultures. The diary allows you to keep track of
|
|
anniversaries, lunar phases, sunrise/set, recurrent appointments
|
|
(weekly, monthly) and more. In this way, it is quite complementary to
|
|
Org. It can be very useful to combine output from Org with
|
|
the diary.
|
|
|
|
In order to include entries from the Emacs diary into Org mode's
|
|
agenda, you only need to customize the variable
|
|
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-include-diary t)
|
|
#+end_src
|
|
|
|
{{{noindent}}} After that, everything will happen automatically. All diary
|
|
entries including holidays, anniversaries, etc., will be included in the
|
|
agenda buffer created by Org mode. {{{key(SPC)}}}, {{{key(TAB)}}}, and
|
|
{{{key(RET)}}} can be used from the agenda buffer to jump to the diary
|
|
file in order to edit existing diary entries. The {{{kbd(i)}}} command to
|
|
insert new entries for the current date works in the agenda buffer, as
|
|
well as the commands {{{kbd(S)}}}, {{{kbd(M)}}}, and {{{kbd(C)}}} to display
|
|
Sunrise/Sunset times, show lunar phases and to convert to other
|
|
calendars, respectively. {{{kbd(c)}}} can be used to switch back and forth
|
|
between calendar and agenda.
|
|
|
|
If you are using the diary only for sexp entries and holidays, it is
|
|
faster to not use the above setting, but instead to copy or even move
|
|
the entries into an Org file. Org mode evaluates diary-style sexp
|
|
entries, and does it faster because there is no overhead for first
|
|
creating the diary display. Note that the sexp entries must start at
|
|
the left margin, no whitespace is allowed before them. For example,
|
|
the following segment of an Org file will be processed and entries
|
|
will be made in the agenda:[fn:181]
|
|
|
|
#+begin_example
|
|
,* Birthdays and similar stuff
|
|
,#+CATEGORY: Holiday
|
|
%%(org-calendar-holiday) ; special function for holiday names
|
|
,#+CATEGORY: Ann
|
|
%%(org-anniversary 1956 5 14) Arthur Dent is %d years old
|
|
%%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
|
|
#+end_example
|
|
|
|
**** FIXED Anniversaries from BBDB
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Integrate Big Brother Database and Org
|
|
:END:
|
|
|
|
#+cindex: BBDB, anniversaries
|
|
#+cindex: anniversaries, from BBDB
|
|
|
|
If you are using the Big Brothers Database to store your contacts, you will
|
|
very likely prefer to store anniversaries in BBDB rather than in a
|
|
separate Org or diary file. Org supports this and will show BBDB
|
|
anniversaries as part of the agenda. All you need to do is to add the
|
|
following to one of your agenda files:
|
|
|
|
#+begin_example
|
|
,* Anniversaries
|
|
, :PROPERTIES:
|
|
, :CATEGORY: Anniv
|
|
, :END:
|
|
,%%(org-bbdb-anniversaries)
|
|
#+end_example
|
|
|
|
You can then go ahead and define anniversaries for a BBDB record.
|
|
Basically, you need to press {{{kbdspckey(C-o anniversary,RET)}}} with
|
|
the cursor in a BBDB record and then add the date in the format
|
|
~YYYY-MM-DD~ or ~MM-DD~, followed by a space and the class of the
|
|
anniversary ({{{samp(birthday)}}} or {{{samp(wedding)}}}, or a format
|
|
string). If you omit the class, it will default to
|
|
{{{samp(birthday)}}}. Here are a few examples, the header for the file
|
|
{{{file(org-bbdb.el)}}} contains more detailed information.
|
|
|
|
#+begin_example
|
|
1973-06-22
|
|
06-22
|
|
1955-08-02 wedding
|
|
2008-04-14 %s released version 6.01 of org mode, %d years ago
|
|
#+end_example
|
|
|
|
After a change to BBDB, or for the first agenda display during an
|
|
Emacs session, the agenda display will suffer a short delay as Org
|
|
updates its hash with anniversaries. However, from then on things will
|
|
be very fast---much faster in fact than a long list of
|
|
{{{samp(%%(diary-anniversary))}}} entries in an Org or Diary file.
|
|
|
|
**** FIXED Appointment reminders
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Integrate the Emacs appointment facility and Org
|
|
:END:
|
|
#+cindex: @file{appt.el}
|
|
#+cindex: appointment reminders
|
|
#+cindex: appointment
|
|
#+cindex: reminders
|
|
|
|
Org can interact with Emacs appointments notification facility. To add the
|
|
appointments of your agenda files, use the command ~org-agenda-to-appt~.
|
|
This command lets you filter through the list of your appointments and add
|
|
only those belonging to a specific category or matching a regular expression.
|
|
It also reads a ~APPT_WARNTIME~ property which will then override the
|
|
value of ~appt-message-warning-time~ for this appointment. See the
|
|
docstring for details.
|
|
|
|
*** FIXED Global TODO list
|
|
:PROPERTIES:
|
|
:DESCRIPTION: All unfinished action items
|
|
:END:
|
|
#+cindex: global TODO list
|
|
#+cindex: TODO list, global
|
|
|
|
The global TODO list contains all unfinished TODO items formatted and
|
|
collected into a single place.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c a t)}}}, ~org-todo-list~ ::
|
|
|
|
Show the global TODO list. This collects the TODO items from all
|
|
agenda files (see [[Agenda views]]) into a single buffer. By default, this
|
|
lists items with a state the is not a DONE state. The buffer is in ~agenda-mode~, so there are commands to examine and manipulate the
|
|
TODO entries directly from that buffer (see [[Agenda commands]]).
|
|
|
|
- {{{kbd(C-c a T)}}}, ~org-todo-list~ ::
|
|
|
|
#+cindex: TODO keyword matching
|
|
#+vindex: org-todo-keywords
|
|
|
|
Like the above, but allows selection of a specific TODO keyword. You
|
|
can also do this by specifying a prefix argument to {{{kbd(C-c a
|
|
t)}}}. You are prompted for a keyword, and you may also specify
|
|
several keywords by separating them with {{{samp(|)}}} as the boolean
|
|
OR operator. With a numeric prefix, the Nth keyword in ~org-todo-keywords~ is selected.
|
|
|
|
#+kindex: r
|
|
|
|
The {{{kbd(r)}}} key in the agenda buffer regenerates it, and you can give
|
|
a prefix argument to this command to change the selected TODO keyword,
|
|
for example {{{kbd(3 r)}}}. If you often need a search for a specific
|
|
keyword, define a custom command for it (see [[Agenda dispatcher]]).
|
|
|
|
Matching specific TODO keywords can also be done as part of a tags
|
|
search (see [[Tag searches]]).
|
|
|
|
|
|
Remote editing of TODO items means that you can change the state of a
|
|
TODO entry with a single key press. The commands available in the
|
|
TODO list are described in [[Agenda commands]].
|
|
|
|
#+cindex: sublevels, inclusion into TODO list
|
|
|
|
Normally the global TODO list simply shows all headlines with TODO
|
|
keywords. This list can become very long. There are two ways to keep
|
|
it more compact:
|
|
|
|
|
|
- Some people view a TODO item that has been /scheduled/ for execution
|
|
or have a /deadline/ (see [[Timestamps]]) as no longer /open/. Configure
|
|
the variables ~org-agenda-todo-ignore-scheduled~, ~org-agenda-todo-ignore-deadlines~, ~org-agenda-todo-ignore-timestamp~ and/or ~org-agenda-todo-ignore-with-date~ to exclude such items from the
|
|
global TODO list.
|
|
|
|
#+vindex: org-agenda-todo-ignore-scheduled
|
|
#+vindex: org-agenda-todo-ignore-deadlines
|
|
#+vindex: org-agenda-todo-ignore-timestamp
|
|
#+vindex: org-agenda-todo-ignore-with-date
|
|
|
|
- TODO items may have sublevels to break up the task into subtasks. In
|
|
such cases it may be enough to list only the highest level TODO
|
|
headline and omit the sublevels from the global list. Configure the
|
|
variable ~org-agenda-todo-list-sublevels~ to get this behavior.
|
|
|
|
#+vindex: org-agenda-todo-list-sublevels
|
|
|
|
*** Matching tags and properties
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Structured information with fine-tuned search
|
|
:END:
|
|
#+cindex: matching, of tags
|
|
#+cindex: matching, of properties
|
|
#+cindex: tags view
|
|
#+cindex: match view
|
|
|
|
If headlines in the agenda files are marked with /tags/ (see [[Tags]]), or
|
|
have properties (see [[Properties and columns]]), you can select headlines
|
|
based on this metadata and collect them into an agenda buffer. The
|
|
match syntax described here also applies when creating sparse trees
|
|
with {{{kbd(C-c / m)}}}.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c a m)}}}, ~org-tags-view~ ::
|
|
|
|
Produce a list of all headlines that match a given set of tags. The
|
|
command prompts for a selection criterion, which is a boolean logic
|
|
expression with tags, like {{{samp(+work+urgent-withboss)}}} or
|
|
{{{samp(work|home)}}} (see [[Tags]]). If you often need a specific search,
|
|
define a custom command for it (see [[Agenda dispatcher]]).
|
|
|
|
- {{{kbd(C-c a M)}}}, ~org-tags-view~ ::
|
|
|
|
#+vindex: org-tags-match-list-sublevels
|
|
#+vindex: org-agenda-tags-todo-honor-ignore-options
|
|
|
|
Like {{{kbd(C-c a m)}}}, but only select headlines that are also TODO
|
|
items in a not-DONE state and force checking subitems (see the variable ~org-tags-match-list-sublevels~). To exclude scheduled/deadline items,
|
|
see the variable ~org-agenda-tags-todo-honor-ignore-options~. Matching
|
|
specific TODO keywords together with a tags match is also possible,
|
|
see [[Tag searches]].
|
|
|
|
|
|
The commands available in the tags list are described in [[Agenda
|
|
commands]].
|
|
|
|
|
|
#+cindex: Boolean logic, for tag or property searches
|
|
|
|
A search string can use Boolean operators {{{samp(&)}}} for AND and
|
|
{{{samp(|)}}} for OR. {{{samp(&)}}} binds more strongly than
|
|
{{{samp(|)}}}. Parentheses are currently not implemented. Each element
|
|
in the search is either a tag, a regular expression matching tags, or
|
|
an expression like ~PROPERTY OPERATOR VALUE~ with a comparison
|
|
operator, accessing a property value. Each element may be preceded by
|
|
{{{samp(-)}}}, to select against it, and {{{samp(+)}}} is syntactic
|
|
sugar for positive selection. The AND operator {{{samp(&)}}} is
|
|
optional when {{{samp(+)}}} or {{{samp(-)}}} is present. Here are some
|
|
examples, using only tags.
|
|
|
|
#+attr_texinfo: :table-type table :indic @samp
|
|
- +work-boss ::
|
|
|
|
Select headlines tagged {{{samp(:work:)}}}, but discard those also
|
|
tagged {{{samp(:boss:)}}}.
|
|
|
|
- work|laptop ::
|
|
|
|
Selects lines tagged {{{samp(:work:)}}} or {{{samp(:laptop:)}}}.
|
|
|
|
- work|laptop+night ::
|
|
|
|
Like before, but require the {{{samp(:laptop:)}}} lines to be tagged
|
|
also {{{samp(:night:)}}}.
|
|
|
|
|
|
#+cindex: regular expressions, with tags search
|
|
|
|
Instead of a tag, you may also specify a regular expression enclosed
|
|
in curly braces. For example, {{{samp(work+{^boss.*})}}} matches
|
|
headlines that contain the tag {{{samp(:work:)}}} and any tag
|
|
/starting/ with {{{samp(boss)}}}.
|
|
|
|
#+cindex: TODO keyword matching, with tags search
|
|
#+cindex: level, require for tags/property match
|
|
#+cindex: category, require for tags/property match
|
|
#+vindex: org-odd-levels-only
|
|
|
|
You may also test for properties (see [[Properties and columns]]) at the
|
|
same time as matching tags. The properties may be real properties, or
|
|
special properties that represent other metadata (see [[Special
|
|
properties]]). For example, the "property" ~TODO~ represents the TODO
|
|
keyword of the entry. Or, the "property" ~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 /not/ marked with the TODO keyword DONE. In buffers with
|
|
~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.[fn:92]
|
|
|
|
Here are more examples:
|
|
|
|
#+attr_texinfo: :table-type table :indic @samp
|
|
- work+TODO="WAITING" ::
|
|
|
|
Select {{{samp(:work:)}}}-tagged TODO lines with the specific TODO
|
|
keyword {{{samp(WAITING)}}}.
|
|
|
|
- work+TODO="WAITING"|home+TODO="WAITING" ::
|
|
|
|
Waiting tasks both at work and at home.
|
|
|
|
|
|
When matching properties, a number of different operators can be used to test
|
|
the value of a property. Here is a complex example:
|
|
|
|
#+begin_example
|
|
+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:
|
|
|
|
- If the comparison value is a plain number, a numerical comparison is
|
|
done, and the allowed operators are ~<~, ~=~, ~>~, ~<=~, ~>=~, and ~<>~.
|
|
|
|
- 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 double-quotes /and/ angular
|
|
brackets (like {{{samp(DEADLINE<="<2008-12-24 18:30>")}}}), both
|
|
values are assumed to be date/time specifications in the standard
|
|
Org way, and the comparison will be done accordingly. Special values
|
|
that will be recognized are ~"<now>"~ for now (including time), and ~"<today>"~, and ~"<tomorrow>"~ for these days at 0:00 hours, i.e.@:
|
|
without a time specification. Also strings like ~"<+5d>"~ or ~"<-2m>"~ with units ~d~, ~w~, ~m~, and ~y~ for day, week, month,
|
|
and year, respectively, can be used.
|
|
|
|
- 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 ~<>~ 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, a {{{samp(:With:)}}} property that is
|
|
matched by the regular expression {{{samp(Sarah|Denny)}}}, and that
|
|
are scheduled on or after October 11, 2008.
|
|
|
|
Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing
|
|
any other properties will slow down the search. However, once you have
|
|
paid the price by accessing one property, testing additional
|
|
properties is cheap again.
|
|
|
|
You can configure Org mode to use property inheritance during a
|
|
search, but beware that this can slow down searches considerably. See
|
|
[[Property inheritance]], for details.
|
|
|
|
For backward compatibility, and also for typing speed, there is also a
|
|
different way to test TODO states in a search. For this, terminate the
|
|
tags/property part of the search string (which may include several
|
|
terms connected with {{{samp(|)}}}) with a {{{samp(/)}}} and then
|
|
specify a Boolean expression just for TODO keywords. The syntax is
|
|
then similar to that for tags, but should be applied with care: for
|
|
example, a positive selection on several TODO keywords cannot
|
|
meaningfully be combined with boolean AND. However, /negative
|
|
selection/ combined with AND can be meaningful. To make sure that only
|
|
lines are checked that actually have any TODO keyword (resulting in a
|
|
speed-up), use {{{kbd(C-c a M)}}}, or equivalently start the TODO part
|
|
after the slash with {{{samp(!)}}}. Using {{{kbd(C-c a M)}}} or
|
|
{{{samp(/!)}}} will not match TODO keywords in a DONE state. Examples:
|
|
|
|
#+attr_texinfo: :table-type table :indic @samp
|
|
- work/WAITING ::
|
|
|
|
Same as {{{samp(work+TODO="WAITING")}}}
|
|
|
|
- work/!-WAITING-NEXT ::
|
|
|
|
Select {{{samp(:work:)}}}-tagged TODO lines that are neither {{{samp(WAITING)}}}
|
|
nor {{{samp(NEXT)}}}
|
|
|
|
- work/!+WAITING|+NEXT ::
|
|
|
|
Select {{{samp(:work:)}}}-tagged TODO lines that are either
|
|
{{{samp(WAITING)}}} or {{{samp(NEXT)}}}.
|
|
|
|
*** FIXED Timeline for a single file
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Time-sorted view for a single file
|
|
:ALT_TITLE: Timeline
|
|
:END:
|
|
|
|
#+cindex: timeline, single file
|
|
#+cindex: time-sorted view
|
|
|
|
The timeline summarizes all time-stamped items from a single Org mode
|
|
file in a /time-sorted view/. The main purpose of this command is
|
|
to give an overview over events in a project.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c a L)}}}, ~org-timeline~ ::
|
|
|
|
Show a time-sorted view of the Org file, with all time-stamped items.
|
|
When called with a {{{kbd(C-u)}}} prefix, all unfinished TODO entries
|
|
(scheduled or not) are also listed under the current date.
|
|
|
|
|
|
{{{noindent}}} The commands available in the timeline buffer are
|
|
listed in [[Agenda commands]].
|
|
|
|
*** FIXED Search view
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Find entries by searching for text
|
|
:END:
|
|
#+cindex: search view
|
|
#+cindex: text search
|
|
#+cindex: searching, for text
|
|
|
|
This agenda view is a general text search facility for Org mode entries.
|
|
It is particularly useful to find notes.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c a s)}}}, ~org-search-view~ ::
|
|
|
|
This is a special search that lets you select entries by matching a
|
|
substring or specific words using a boolean logic.
|
|
|
|
|
|
For example, the search string {{{samp(computer equipment)}}} will
|
|
find entries that contain {{{samp(computer equipment)}}} as a
|
|
substring. If the two words are separated by more space or a line
|
|
break, the search will still match. Search view can also search for
|
|
specific keywords in the entry, using Boolean logic. The search string
|
|
{{{samp(+computer +wifi -ethernet -{8.11[bg]})}}} will search for
|
|
note entries that contain the keywords ~computer~ and ~wifi~, but not
|
|
the keyword ~ethernet~, and which are also not matched by the regular
|
|
expression ~8.11[bg]~, meaning to exclude both 8.11b and 8.11g. The
|
|
first {{{samp(+)}}} is necessary to turn on word search, other
|
|
{{{samp(+)}}} characters are optional. For more details, see the
|
|
docstring of the command ~org-search-view~.
|
|
|
|
#+vindex: org-agenda-text-search-extra-files
|
|
|
|
Note that in addition to the agenda files, this command will also
|
|
search the files listed in ~org-agenda-text-search-extra-files~.
|
|
|
|
*** FIXED Stuck projects
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Find projects you need to review
|
|
:END:
|
|
#+pindex: GTD, Getting Things Done
|
|
|
|
If you are following a system like David Allen's GTD to organize your
|
|
work, one of the "duties" you have is a regular review to make sure
|
|
that all projects move along. A /stuck/ project is a project that has
|
|
no defined next actions, so it will never show up in the TODO lists
|
|
Org mode produces. During the review, you need to identify such
|
|
projects and define next actions for them.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c a #)}}}, ~org-agenda-list-stuck-projects~ ::
|
|
|
|
List projects that are stuck.
|
|
|
|
- {{{kbd(C-c a !)}}} ::
|
|
|
|
#+vindex: org-stuck-projects
|
|
#+kindex: C-c a !
|
|
|
|
Customize the variable ~org-stuck-projects~ to define what a stuck
|
|
project is and how to find it.
|
|
|
|
|
|
You almost certainly will have to configure this view before it will
|
|
work for you. The built-in default assumes that all your projects are
|
|
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.
|
|
|
|
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. 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 contains the special word IGNORE anywhere, it should not be
|
|
listed either. In this case you would start by identifying eligible
|
|
projects with a tags/todo match (see [[Tag searches]]).
|
|
{{{samp(+PROJECT/-MAYBE-DONE)}}}, and then check for TODO, NEXT,
|
|
@SHOP, and IGNORE in the subtree to identify projects that are not
|
|
stuck. The correct customization for this is:
|
|
|
|
#+begin_src emacs-lisp
|
|
(setq org-stuck-projects
|
|
'("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
|
|
"\\<IGNORE\\>"))
|
|
#+end_src
|
|
|
|
Note that if a project is identified as non-stuck, the subtree of this entry
|
|
will still be searched for stuck projects.
|
|
|
|
** Presentation and sorting
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How agenda items are prepared for display
|
|
:END:
|
|
#+cindex: presentation, of agenda items
|
|
#+vindex: org-agenda-prefix-format
|
|
#+vindex: org-agenda-tags-column
|
|
|
|
Before displaying items in an agenda view, Org mode visually prepares
|
|
the items and sorts them. Each item occupies a single line. The line
|
|
starts with a /prefix/ that contains the /category/ (see [[Categories]])
|
|
of the item and other important information. You can customize in
|
|
which column tags will be displayed through ~org-agenda-tags-column~.
|
|
You can also customize the prefix using the option
|
|
~org-agenda-prefix-format~. This prefix is followed by a cleaned-up
|
|
version of the outline headline associated with the item.
|
|
|
|
*** Categories
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Not all tasks are equal
|
|
:END:
|
|
|
|
#+cindex: category
|
|
#+cindex: #+CATEGORY
|
|
|
|
The category is a broad label assigned to each agenda item. By
|
|
default, the category is simply derived from the file name, but you
|
|
can also specify it with a special line in the buffer, like
|
|
this:[fn:93]
|
|
|
|
#+begin_example
|
|
,#+CATEGORY: Thesis
|
|
#+end_example
|
|
|
|
{{{noindent}}}
|
|
#+cindex: property, CATEGORY
|
|
|
|
If you would like to have a special CATEGORY for a single entry or a
|
|
(sub)tree, give the entry a ~:CATEGORY:~ property with the special
|
|
category you want to apply as the value.
|
|
|
|
{{{noindent}}} The display in the agenda buffer looks best if the
|
|
category is not longer than 10 characters.
|
|
|
|
{{{noindent}}} You can set up icons for category by customizing the
|
|
~org-agenda-category-icon-alist~ variable.
|
|
#+vindex: org-agenda-category-icon-alist
|
|
|
|
*** Time-of-day specifications
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How the agenda knows the time
|
|
:END:
|
|
#+cindex: time-of-day specification
|
|
|
|
Org mode checks each agenda item for a time-of-day specification. The
|
|
time can be part of the timestamp that triggered inclusion into the
|
|
agenda, for example as in ~<2005-05-10 Tue 19:00>~. Time
|
|
ranges can be specified with two timestamps, like: ~<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 integrates the Emacs diary (see [[Weekly/daily agenda]]), time
|
|
specifications in diary entries are recognized as well.
|
|
|
|
For agenda display, Org mode extracts the time and displays it in a
|
|
standard 24 hour format as part of the prefix. The example times in
|
|
the previous paragraphs would end up in the agenda like this:
|
|
|
|
#+begin_example
|
|
8:30-13:00 Arthur Dent lies in front of the bulldozer
|
|
12:45...... Ford Prefect arrives and takes Arthur to the pub
|
|
19:00...... The Vogon reads his poem
|
|
20:30-22:15 Marvin escorts the Hitchhikers to the bridge
|
|
#+end_example
|
|
|
|
#+cindex: time grid
|
|
|
|
If the agenda is in single-day mode, or for the display of today, the
|
|
timed entries are embedded in a time grid, like
|
|
|
|
#+begin_example
|
|
8:00...... ------------------
|
|
8:30-13:00 Arthur Dent lies in front of the bulldozer
|
|
10:00...... ------------------
|
|
12:00...... ------------------
|
|
12:45...... Ford Prefect arrives and takes Arthur to the pub
|
|
14:00...... ------------------
|
|
16:00...... ------------------
|
|
18:00...... ------------------
|
|
19:00...... The Vogon reads his poem
|
|
20:00...... ------------------
|
|
20:30-22:15 Marvin escorts the Hitchhikers to the bridge
|
|
#+end_example
|
|
|
|
#+vindex: org-agenda-use-time-grid
|
|
#+vindex: org-agenda-time-grid
|
|
|
|
The time grid can be turned on and off with the variable
|
|
~org-agenda-use-time-grid~, and can be configured with
|
|
~org-agenda-time-grid~.
|
|
|
|
*** Sorting of agenda items
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The order of things
|
|
:END:
|
|
#+cindex: sorting, of agenda items
|
|
#+cindex: priorities, of agenda items
|
|
|
|
Before being inserted into a view, the items are sorted. How this is
|
|
done depends on the type of view.
|
|
|
|
- For the daily/weekly agenda, the items for each day are sorted. The
|
|
default order is to first collect all items containing an explicit
|
|
time-of-day specification. These entries will be shown at the
|
|
beginning of the list, as a /schedule/ for the day. After that,
|
|
items remain grouped in categories, in the sequence given by ~org-agenda-files~. Within each category, items are sorted by
|
|
priority (see [[Priorities]]), which is composed of the base priority
|
|
(2000 for priority {{{samp(A)}}}, 1000 for {{{samp(B)}}}, and 0 for
|
|
{{{samp(C)}}}), plus additional increments for overdue scheduled or deadline items.
|
|
|
|
#+vindex: org-agenda-files
|
|
|
|
- For the TODO list, items remain in the order of categories, but
|
|
within each category, sorting takes place according to priority (see
|
|
[[Priorities]]). The priority used for sorting derives from the
|
|
priority cookie, with additions depending on how close an item is to
|
|
its due or scheduled date.
|
|
|
|
- For tags matches, items are not sorted at all, but just appear in
|
|
the sequence in which they are found in the agenda files.
|
|
|
|
|
|
#+vindex: org-agenda-sorting-strategy
|
|
|
|
Sorting can be customized using the variable
|
|
~org-agenda-sorting-strategy~, and may also include criteria based on
|
|
the estimated effort of an entry (see [[Effort estimates]]).
|
|
|
|
** FIXME Agenda commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Remote editing of Org trees
|
|
:TITLE: Commands in the agenda buffer
|
|
:END:
|
|
#+cindex: commands, in agenda buffer
|
|
|
|
Entries in the agenda buffer are linked back to the Org file or diary
|
|
file where they originate. You are not allowed to edit the agenda
|
|
buffer itself, but commands are provided to show and jump to the
|
|
original entry location, and to edit the Org files ``remotely'' from
|
|
the agenda buffer. In this way, all information is stored only once,
|
|
removing the risk that your agenda and note files may diverge.
|
|
|
|
Some commands can be executed with mouse clicks on agenda lines. For
|
|
the other commands, the cursor needs to be in the desired line.
|
|
|
|
*** FIXME Motion2
|
|
#+cindex: motion commands in agenda
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(n)}}}, ~org-agenda-next-line~ ::
|
|
#+kindex: n
|
|
|
|
Next line (same as {{{key(down)}}} and {{{kbd(C-n)}}}).
|
|
|
|
- {{{kbd(p)}}}, ~org-agenda-previous-line~ ::
|
|
#+kindex: p
|
|
|
|
Previous line (same as {{{key(up)}}} and {{{kbd(C-p)}}}).
|
|
|
|
*** View/Go to Org file
|
|
#+cindex: view file commands in agenda
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{key(SPC)}}} or {{{key(mouse-3)}}}, ~org-agenda-show-and-scroll-up~ ::
|
|
#+kindex: @key{SPC}
|
|
#+kindex: mouse-3
|
|
|
|
Display the original location of the item in another window. With
|
|
prefix arg, make sure that the entire entry is made visible in the
|
|
outline, not only the heading.
|
|
|
|
- {{{kbd(L)}}}, ~org-agenda-recenter~ ::
|
|
#+kindex: L
|
|
|
|
Display original location and recenter that window.
|
|
|
|
- {{{key(TAB)}}} or {{{key(mouse-2)}}}, ~org-agenda-goto~ ::
|
|
#+kindex: @key{TAB}
|
|
#+kindex: mouse-2
|
|
|
|
Go to the original location of the item in another window.
|
|
|
|
- {{{key(RET)}}}, ~org-agenda-switch-to~ ::
|
|
#+kindex: @key{RET}
|
|
|
|
Go to the original location of the item and delete other windows.
|
|
|
|
- {{{kbd(F)}}}, ~org-agenda-follow-mode~ ::
|
|
#+kindex: F
|
|
#+vindex: org-agenda-start-with-follow-mode
|
|
|
|
Toggle Follow mode. In Follow mode, as you move the cursor through the
|
|
agenda buffer, the other window always shows the corresponding
|
|
location in the Org file. The initial setting for this mode in new
|
|
agenda buffers can be set with the variable ~org-agenda-start-with-follow-mode~.
|
|
|
|
- {{{kbd(C-c C-x b)}}}, ~org-agenda-tree-to-indirect-buffer~ ::
|
|
#+kindex: C-c C-x b
|
|
|
|
Display the entire subtree of the current item in an indirect buffer.
|
|
With a numeric prefix argument N, go up to level N and then take that
|
|
tree. If N is negative, go up that many levels. With a {{{kbd(C-u)}}}
|
|
prefix, do not remove the previously used indirect buffer.
|
|
|
|
- {{{kbd(C-c C-o)}}}, ~org-agenda-open-link~ ::
|
|
#+kindex: C-c C-o
|
|
|
|
Follow a link in the entry. This will offer a selection of any links
|
|
in the text belonging to the referenced Org node. If there is only one
|
|
link, it will be followed without a selection prompt.
|
|
|
|
*** Change display
|
|
#+cindex: change agenda display
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(A)}}} ::
|
|
#+kindex: A
|
|
#+cindex: display changing, in agenda
|
|
|
|
Interactively select another agenda view and append it to the current
|
|
view.
|
|
|
|
- {{{kbd(o)}}} ::
|
|
#+kindex: o
|
|
|
|
Delete other windows.
|
|
|
|
- {{{kbd(v d)}}} or short {{{kbd(d)}}}, ~org-agenda-day-view~ ::
|
|
#+kindex: v d
|
|
#+kindex: d
|
|
#+vindex: org-agenda-span
|
|
|
|
Switch to day view. When switching to day view, this setting becomes
|
|
the default for subsequent agenda refreshes. A numeric prefix argument
|
|
may be used to jump directly to a specific day of the year. For
|
|
example, {{{kbd(32 d)}}} jumps to February 1st. When setting day view,
|
|
a year may be encoded in the prefix argument as well. For example,
|
|
{{{kbd(200712 d)}}} will jump to January 12, 2007. If such a year
|
|
specification has only one or two digits, it will be mapped to the
|
|
interval 1938-2037.
|
|
|
|
- {{{kbd(v w)}}} or short {{{kbd(w)}}}, ~org-agenda-week-view~ ::
|
|
#+kindex: v w
|
|
#+kindex: w
|
|
#+vindex: org-agenda-span
|
|
|
|
Switch to week view. When switching week view, this setting becomes
|
|
the default for subsequent agenda refreshes. A numeric prefix argument
|
|
may be used to jump directly to a specific day of the ISO week. For
|
|
example {{{kbd(9 w)}}} to ISO week number 9. When setting week 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 m)}}}, ~org-agenda-month-view~ ::
|
|
#+kindex: v m
|
|
#+vindex: org-agenda-span
|
|
|
|
Switch to month view. Because month views are slow to create, they do
|
|
not become the default for subsequent agenda refreshes. A numeric
|
|
prefix argument may be used to jump directly to a specific day of the
|
|
month. When setting month view, a year may be encoded in the prefix
|
|
argument as well. For example, {{{kbd(200712 m)}}} will jump to
|
|
December, 2007. If such a year specification has only one or two
|
|
digits, it will be mapped to the interval 1938-2037.
|
|
|
|
- {{{kbd(v y)}}}, ~org-agenda-year-view~ ::
|
|
#+kindex: v y
|
|
#+vindex: org-agenda-span
|
|
|
|
Switch to year view. Because year views are slow to create, they do
|
|
not become the default for subsequent agenda refreshes. A numeric
|
|
prefix argument may be used to jump directly to a specific day of the
|
|
year.
|
|
|
|
- {{{kbdspckey(v,SPC)}}}, ~org-agenda-reset-view~ ::
|
|
#+kindex: v @key{SPC}
|
|
#+vindex: org-agenda-span
|
|
|
|
Reset ~org-agenda-span~ to the current span.
|
|
|
|
- {{{kbd(f)}}}, ~org-agenda-later~ ::
|
|
#+kindex: f
|
|
|
|
Go forward in time to display the following ~org-agenda-current-span~
|
|
days. For example, if the display covers a week, switch to the
|
|
following week. With prefix arg, go forward that many times ~org-agenda-current-span~ days.
|
|
|
|
- {{{kbd(b)}}}, ~org-agenda-earlier~ ::
|
|
#+kindex: b
|
|
|
|
Go backward in time to display earlier dates.
|
|
|
|
- {{{kbd(.)}}}, ~org-agenda-goto-today~ ::
|
|
#+kindex: .
|
|
|
|
Go to today.
|
|
|
|
- {{{kbd(j)}}}, ~org-agenda-goto-date~ ::
|
|
#+kindex: j
|
|
|
|
Prompt for a date and go there.
|
|
|
|
- {{{kbd(J)}}}, ~org-agenda-clock-goto~ ::
|
|
#+kindex: J
|
|
|
|
Go to the currently clocked-in task /in the agenda buffer/.
|
|
|
|
- {{{kbd(D)}}}, ~org-agenda-toggle-diary~ ::
|
|
#+kindex: D
|
|
|
|
Toggle the inclusion of diary entries. See [[Weekly/daily agenda]].
|
|
|
|
- {{{kbd(v l)}}} or {{{kbd(v L)}}} or short {{{kbd(l)}}}, ~org-agenda-log-mode~ ::
|
|
#+kindex: v l
|
|
#+kindex: l
|
|
#+kindex: v L
|
|
#+vindex: org-log-done
|
|
#+vindex: org-agenda-log-mode-items
|
|
|
|
Toggle Logbook mode. In Logbook mode, entries that were marked DONE
|
|
while logging was on (see the variable ~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 ~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. {{{kbd(v L)}}} is
|
|
equivalent to {{{kbd(C-u v l)}}}.
|
|
|
|
- {{{kbd(v [)}}} or short {{{kbd([)}}}, ~org-agenda-manipulate-query-add~ ::
|
|
#+kindex: v [
|
|
#+kindex: [
|
|
|
|
Include inactive timestamps into the current view. Only for
|
|
weekly/daily agenda and timeline views.
|
|
|
|
- {{{kbd(v a)}}}, ~org-agenda-archives-mode~ ::
|
|
#+kindex: v a
|
|
|
|
Toggle Archives mode. In Archives mode, trees that are marked ~ARCHIVED~ are also scanned when producing the agenda. To exit
|
|
archives mode, press {{{kbd(v a)}}} again.
|
|
|
|
- {{{kbd(v A)}}}, ~org-agenda-archives-mode 'files~ ::
|
|
|
|
Toggle Archives mode. In Archives mode, trees that are marked ~ARCHIVED~ are also scanned when producing the agenda, including all
|
|
archive files. To exit archives mode, press {{{kbd(v a)}}}.
|
|
|
|
- {{{kbd(v R)}}} or short {{{kbd(R)}}}, ~org-agenda-clockreport-mode~ ::
|
|
#+kindex: v R
|
|
#+kindex: R
|
|
#+vindex: org-agenda-start-with-clockreport-mode
|
|
#+vindex: org-clock-report-include-clocking-task
|
|
|
|
Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda
|
|
will always show a table with the clocked times for the timespan and
|
|
file scope covered by the current agenda view. The initial setting for
|
|
this mode in new agenda buffers can be set with the variable
|
|
~org-agenda-start-with-clockreport-mode~. By using a prefix argument
|
|
when toggling this mode (i.e., {{{kbd(C-u R)}}}), the clock table will
|
|
not show contributions from entries that are hidden by agenda
|
|
filtering.[fn:94] See also the variable
|
|
~org-clock-report-include-clocking-task~.
|
|
|
|
- {{{kbd(v c)}}} ::
|
|
#+kindex: v c
|
|
#+vindex: org-agenda-clock-consistency-checks
|
|
|
|
Show overlapping clock entries, clocking gaps, and other clocking
|
|
problems in the current agenda range. You can then visit clocking
|
|
lines and fix them manually. See the variable
|
|
~org-agenda-clock-consistency-checks~ for information on how to
|
|
customize the definition of what constituted a clocking problem. To
|
|
return to normal agenda display, press {{{kbd(l)}}} to exit Logbook
|
|
mode.
|
|
|
|
- {{{kbd(v E)}}} or short {{{kbd(E)}}}, ~org-agenda-entry-text-mode~ ::
|
|
#+kindex: v E
|
|
#+kindex: E
|
|
#+vindex: org-agenda-start-with-entry-text-mode
|
|
#+vindex: org-agenda-entry-text-maxlines
|
|
|
|
Toggle entry text mode. In entry text mode, a number of lines from the
|
|
Org outline node referenced by an agenda line will be displayed below
|
|
the line. The maximum number of lines is given by the variable
|
|
~org-agenda-entry-text-maxlines~. Calling this command with a numeric
|
|
prefix argument will temporarily modify that number to the prefix
|
|
value.
|
|
|
|
- {{{kbd(G)}}}, ~org-agenda-toggle-time-grid~ ::
|
|
#+kindex: G
|
|
#+vindex: org-agenda-use-time-grid
|
|
#+vindex: org-agenda-time-grid
|
|
|
|
Toggle the time grid on and off. See also the variables
|
|
~org-agenda-use-time-grid~ and ~org-agenda-time-grid~.
|
|
|
|
- {{{kbd(r)}}}, ~org-agenda-redo~ ::
|
|
#+kindex: r
|
|
|
|
Recreate the agenda buffer, for example to reflect the changes after
|
|
modification of the timestamps of items with {{{kbdkey(S-,left)}}} and
|
|
{{{kbdkey(S-,right)}}}. When the buffer is the global TODO list, a prefix
|
|
argument is interpreted to create a selective list for a specific TODO
|
|
keyword.
|
|
|
|
- {{{kbd(g)}}}, ~org-agenda-redo~ ::
|
|
#+kindex: g
|
|
|
|
Same as {{{kbd(r)}}}.
|
|
|
|
- {{{kbd(C-x C-s)}}} or short {{{kbd(s)}}}, ~org-save-all-org-buffers~ ::
|
|
#+kindex: C-x C-s
|
|
#+kindex: s
|
|
|
|
Save all Org buffers in the current Emacs session, and also the
|
|
locations of IDs.
|
|
|
|
- {{{kbd(C-c C-x C-c)}}}, ~org-agenda-columns~ ::
|
|
#+kindex: C-c C-x C-c
|
|
#+vindex: org-columns-default-format
|
|
|
|
Invoke column view (see [[Column view]]) in the agenda buffer. The column
|
|
view format is taken from the entry at point, or (if there is no entry
|
|
at point), from the first entry in the agenda view. So whatever the
|
|
format for that entry would be in the original buffer (taken from a
|
|
property, from a ~#+COLUMNS~ line, or from the default variable
|
|
~org-columns-default-format~), will be used in the agenda.
|
|
|
|
- {{{kbd(C-c C-x >)}}}, ~org-agenda-remove-restriction-lock~ ::
|
|
#+kindex: C-c C-x >
|
|
|
|
Remove the restriction lock on the agenda, if it is currently
|
|
restricted to a file or subtree (see [[Agenda files]]).
|
|
|
|
*** FIXME Secondary filtering and query editing
|
|
#+cindex: filtering, by tag category and effort, in agenda
|
|
#+cindex: tag filtering, in agenda
|
|
#+cindex: category filtering, in agenda
|
|
#+cindex: effort filtering, in agenda
|
|
#+cindex: query editing, in agenda
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(<)}}}, ~org-agenda-filter-by-category~ ::
|
|
#+kindex: <
|
|
#+vindex: org-agenda-category-filter-preset
|
|
|
|
Filter the current agenda view with respect to the category of the
|
|
item at point. Pressing {{{kbd(<)}}} another time will remove this
|
|
filter. You can add a filter preset through the option
|
|
~org-agenda-category-filter-preset~ (see below).
|
|
|
|
- {{{kbd(/)}}}, ~org-agenda-filter-by-tag~ ::
|
|
#+kindex: /
|
|
#+vindex: org-agenda-tag-filter-preset
|
|
|
|
Filter the current agenda view with respect to a tag and/or effort
|
|
estimates. The difference between this and a custom agenda command is
|
|
that filtering is very fast, so that you can switch quickly between
|
|
different filters without having to recreate the
|
|
agenda.[fn:95]
|
|
|
|
You will be prompted for a tag selection letter; {{{key(SPC)}}} will
|
|
mean any tag at all. Pressing {{{key(TAB)}}} at that prompt will offer
|
|
use completion to select a tag (including any tags that do not have a
|
|
selection character). The command then hides all entries that do not
|
|
contain or inherit this tag. When called with prefix arg, remove the
|
|
entries that /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 ~\~ command.
|
|
|
|
#+vindex: org-sort-agenda-noeffort-is-high
|
|
|
|
In order to filter for effort estimates, you should set up allowed
|
|
efforts globally, for example:
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-global-properties
|
|
'(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
|
|
#+end_src
|
|
|
|
You can then filter for an effort by first typing an operator, one of
|
|
{{{kbd(<)}}}, {{{kbd(>)}}}, and {{{kbd(=)}}}, and then the one-digit
|
|
index of an effort estimate in your array of allowed values, where
|
|
{{{kbd(0)}}} means the 10th value. The filter will then restrict to
|
|
entries with effort smaller-or-equal, equal, or larger-or-equal than
|
|
the selected value. If the digits 0-9 are not used as fast access keys
|
|
to tags, you can also simply press the index digit directly without an
|
|
operator. In this case, {{{kbd(<)}}} will be assumed. For application
|
|
of the operator, entries without a defined effort will be treated
|
|
according to the value of ~org-sort-agenda-noeffort-is-high~. To
|
|
filter for tasks without effort definition, press {{{kbd(?)}}} as the
|
|
operator.
|
|
|
|
Org also supports automatic, context-aware tag filtering. If the
|
|
variable ~org-agenda-auto-exclude-function~ is set to a user-defined
|
|
function, that function can decide which tags should be excluded from
|
|
the agenda automatically. Once this is set, the {{{kbd(/)}}} command
|
|
then accepts {{{kbd(RET)}}} as a sub-option key and runs the auto
|
|
exclusion logic. For example, let's say you use a ~Net~ tag to
|
|
identify tasks which need network access, an ~Errand~ tag for errands
|
|
in town, and a ~Call~ tag for making phone calls. You could
|
|
auto-exclude these tags based on the availability of the Internet, and
|
|
outside of business hours, with something like this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(defun org-my-auto-exclude-function (tag)
|
|
(and (cond
|
|
((string= tag "Net")
|
|
(/= 0 (call-process "/sbin/ping" nil nil nil
|
|
"-c1" "-q" "-t1" "mail.gnu.org")))
|
|
((or (string= tag "Errand") (string= tag "Call"))
|
|
(let ((hour (nth 2 (decode-time))))
|
|
(or (< hour 8) (> hour 21)))))
|
|
(concat "-" tag)))
|
|
(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
|
|
#+end_src
|
|
|
|
- ~\~ ~org-agenda-filter-by-tag-refine~ ::
|
|
#+kindex: XXX
|
|
#+comment: Should be \
|
|
Narrow the current agenda filter by an additional condition. When
|
|
called with prefix arg, remove the entries that /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.
|
|
|
|
- {{{kbd([)}}} {{{kbd(])}}} {{{kbd({)}}} {{{kbd(})}}} in search view ::
|
|
#+kindex: [
|
|
#+kindex: ]
|
|
#+kindex: @{
|
|
#+kindex: @}
|
|
|
|
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 /must/ occur/match in
|
|
the entry. The closing bracket/brace will add a negative search term
|
|
which /must not/ occur/match in the entry for it to be selected.
|
|
|
|
*** FIXME Remote editing
|
|
#+cindex: remote editing, from agenda
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(0--9)}}} ::
|
|
|
|
Digit argument.
|
|
|
|
- {{{kbd(C-_)}}}, ~org-agenda-undo~ ::
|
|
#+kindex: C-_
|
|
#+cindex: undoing remote-editing events
|
|
#+cindex: remote editing, undo
|
|
|
|
Undo a change due to a remote editing command. The change is undone
|
|
both in the agenda buffer and in the remote buffer.
|
|
|
|
- {{{kbd(t)}}}, ~org-agenda-todo~ ::
|
|
#+kindex: t
|
|
|
|
Change the TODO state of the item, both in the agenda and in the
|
|
original org file.
|
|
|
|
- {{{kbdkey(C-S-,right)}}}, ~org-agenda-todo-nextset~ ::
|
|
#+kindex: C-S-@key{right}
|
|
|
|
Switch to the next set of TODO keywords.
|
|
|
|
- {{{kbdkey(C-S-,left)}}}, ~org-agenda-todo-previousset~ ::
|
|
#+kindex: C-S-@key{left}
|
|
|
|
Switch to the previous set of TODO keywords.
|
|
|
|
- {{{kbd(C-k)}}}, ~org-agenda-kill~ ::
|
|
#+kindex: C-k
|
|
#+vindex: org-agenda-confirm-kill
|
|
|
|
Delete the current agenda item along with the entire subtree belonging
|
|
to it in the original Org file. If the text to be deleted remotely is
|
|
longer than one line, the kill needs to be confirmed by the user. See
|
|
variable ~org-agenda-confirm-kill~.
|
|
|
|
- {{{kbd(C-c C-w)}}}, ~org-agenda-refile~ ::
|
|
#+kindex: C-c C-w
|
|
|
|
Refile the entry at point.
|
|
|
|
- {{{kbd(C-c C-x C-a)}}} or short {{{kbd(a)}}}, ~org-agenda-archive-default-with-confirmation~ ::
|
|
#+kindex: C-c C-x C-a
|
|
#+kindex: a
|
|
#+vindex: org-archive-default-command
|
|
|
|
Archive the subtree corresponding to the entry at point using the
|
|
default archiving command set in ~org-archive-default-command~. When
|
|
using the ~a~ key, confirmation will be required.
|
|
|
|
- {{{kbd(C-c C-x a)}}}, ~org-agenda-toggle-archive-tag~ ::
|
|
#+kindex: C-c C-x a
|
|
|
|
Toggle the ARCHIVE tag for the current headline.
|
|
|
|
- {{{kbd(C-c C-x A)}}}, ~org-agenda-archive-to-archive-sibling~ ::
|
|
#+kindex: C-c C-x A
|
|
|
|
Move the subtree corresponding to the current entry to its /archive
|
|
sibling/.
|
|
|
|
- {{{kbd(C-c C-x C-s)}}} or short {{{kbd($)}}}, ~org-agenda-archive~ ::
|
|
#+kindex: C-c C-x C-s
|
|
#+kindex: $
|
|
|
|
Archive the subtree corresponding to the current headline. This means
|
|
the entry will be moved to the configured archive location, most
|
|
likely a different file.
|
|
|
|
- {{{kbd(T)}}}, ~org-agenda-show-tags~ ::
|
|
#+kindex: T
|
|
#+vindex: org-agenda-show-inherited-tags
|
|
|
|
Show all tags associated with the current item. This is useful if you
|
|
have turned off ~org-agenda-show-inherited-tags~, but still want to
|
|
see all tags of a headline occasionally.
|
|
|
|
- {{{kbd(:)}}}, ~org-agenda-set-tags~ ::
|
|
#+kindex: :
|
|
|
|
Set tags for the current headline. If there is an active region in the
|
|
agenda, change a tag for all headings in the region.
|
|
|
|
- {{{kbd(\\\,)}}} ::
|
|
#+kindex: ,
|
|
Set the priority for the current item (~org-agenda-priority~). Org
|
|
mode prompts for the priority character. If you reply with
|
|
{{{key(SPC)}}}, the priority cookie is removed from the entry.
|
|
|
|
- {{{kbd(P)}}}, ~org-agenda-show-priority~ ::
|
|
#+kindex: P
|
|
|
|
Display weighted priority of current item.
|
|
|
|
- {{{kbd(+)}}} {{{kbdkey(S-,up)}}}, ~org-agenda-priority-up~ ::
|
|
#+kindex: +
|
|
|
|
Increase the priority of the current item. The priority is changed in
|
|
the original buffer, but the agenda is not resorted. Use the
|
|
{{{kbd(r)}}} key for this.
|
|
|
|
- {{{kbd(-)}}} {{{kbdkey(S-,down)}}}, ~org-agenda-priority-down~ ::
|
|
#+kindex: -
|
|
|
|
Decrease the priority of the current item.
|
|
|
|
- {{{kbd(z)}}} {{{kbd(C-c C-z)}}}, ~org-agenda-add-note~ ::
|
|
#+kindex: z
|
|
#+vindex: org-log-into-drawer
|
|
|
|
Add a note to the entry. This note will be recorded, and then filed to
|
|
the same location where state change notes are put. Depending on ~org-log-into-drawer~, this may be inside a drawer.
|
|
|
|
- {{{kbd(C-c C-a)}}}, ~org-attach~ ::
|
|
#+kindex: C-c C-a
|
|
|
|
Dispatcher for all command related to attachments.
|
|
|
|
- {{{kbd(C-c C-s)}}}, ~org-agenda-schedule~ ::
|
|
#+kindex: C-c C-s
|
|
|
|
Schedule this item. With prefix arg remove the scheduling timestamp
|
|
|
|
- {{{kbd(C-c C-d)}}}, ~org-agenda-deadline~ ::
|
|
#+kindex: C-c C-d
|
|
|
|
Set a deadline for this item. With prefix arg remove the deadline.
|
|
|
|
- {{{kbdkey(S-,right)}}}, ~org-agenda-do-date-later~ ::
|
|
#+kindex: S-@key{right}
|
|
|
|
Change the timestamp associated with the current line by one day into
|
|
the future. If the date is in the past, the first call to this command
|
|
will move it to today. With a numeric prefix argument, change it by
|
|
that many days. For example, {{{kbdkey(3 6 5 S-,right)}}} will change
|
|
it by a year. With a {{{kbd(C-u)}}} prefix, change the time by one
|
|
hour. If you immediately repeat the command, it will continue to
|
|
change hours even without the prefix arg. With a double
|
|
{{{kbd(C-u C-u)}}} prefix, do the same for changing minutes. The stamp is changed
|
|
in the original Org file, but the change is not directly reflected in
|
|
the agenda buffer. Use {{{kbd(r)}}} or {{{kbd(g)}}} to update the
|
|
buffer.
|
|
|
|
- {{{kbdkey(S-,left)}}}, ~org-agenda-do-date-earlier~ ::
|
|
#+kindex: S-@key{left}
|
|
|
|
Change the timestamp associated with the current line by one day
|
|
into the past.
|
|
|
|
- {{{kbd(>)}}}, ~org-agenda-date-prompt~ ::
|
|
#+kindex: >
|
|
|
|
Change the timestamp associated with the current line. The key
|
|
{{{kbd(>)}}} has been chosen, because it is the same as {{{kbd(S-.)}}}
|
|
on my keyboard.
|
|
|
|
- {{{kbd(I)}}}, ~org-agenda-clock-in~ ::
|
|
#+kindex: I
|
|
|
|
Start the clock on the current item. If a clock is running already, it
|
|
is stopped first.
|
|
|
|
- {{{kbd(O)}}}, ~org-agenda-clock-out~ ::
|
|
#+kindex: O
|
|
|
|
Stop the previously started clock.
|
|
|
|
- {{{kbd(X)}}}, ~org-agenda-clock-cancel~ ::
|
|
#+kindex: X
|
|
|
|
Cancel the currently running clock.
|
|
|
|
- {{{kbd(J)}}}, ~org-agenda-clock-goto~ ::
|
|
#+kindex: J
|
|
|
|
Jump to the running clock in another window.
|
|
|
|
- {{{kbd(k)}}}, ~org-agenda-capture~ ::
|
|
#+kindex: k
|
|
#+cindex: capturing, from agenda
|
|
#+vindex: org-capture-use-agenda-date
|
|
|
|
Like ~org-capture~, but use the date at point as the default date for
|
|
the capture template. See ~org-capture-use-agenda-date~ to make this
|
|
the default behavior of ~org-capture~.
|
|
|
|
*** Bulk remote editing selected entries
|
|
#+cindex: remote editing, bulk, from agenda
|
|
#+vindex: org-agenda-bulk-persistent-marks
|
|
#+vindex: org-agenda-bulk-custom-functions
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(m)}}}, ~org-agenda-bulk-mark~ ::
|
|
#+kindex: m
|
|
|
|
Mark the entry at point for bulk action. With prefix arg, mark that
|
|
many successive entries.
|
|
|
|
- {{{kbd(%)}}}, ~org-agenda-bulk-mark-regexp~ ::
|
|
#+kindex: %
|
|
|
|
Mark entries matching a regular expression for bulk action.
|
|
|
|
- {{{kbd(u)}}}, ~org-agenda-bulk-unmark~ ::
|
|
#+kindex: u
|
|
|
|
Unmark entry for bulk action.
|
|
|
|
- {{{kbd(U)}}}, ~org-agenda-bulk-remove-all-marks~ ::
|
|
#+kindex: U
|
|
|
|
Unmark all marked entries for bulk action.
|
|
|
|
- {{{kbd(B)}}}, ~org-agenda-bulk-action~ ::
|
|
#+kindex: B
|
|
|
|
Bulk action: act on all marked entries in the agenda. This will prompt
|
|
for another key to select the action to be applied. The prefix arg to
|
|
{{{kbd(B)}}} will be passed through to the {{{kbd(s)}}} and
|
|
{{{kbd(d)}}} commands, to bulk-remove these special timestamps. By
|
|
default, marks are removed after the bulk. If you want them to
|
|
persist, set ~org-agenda-bulk-persistent-marks~ to ~t~ or hit
|
|
{{{kbd(p)}}} at the prompt.
|
|
|
|
- {{{kbd(*)}}} ::
|
|
|
|
Toggle persistent marks.
|
|
|
|
- {{{kbd($)}}} ::
|
|
|
|
Archive all selected entries.
|
|
|
|
- {{{kbd(A)}}} ::
|
|
|
|
Archive entries by moving them to their respective archive siblings.
|
|
|
|
- {{{kbd(t)}}} ::
|
|
|
|
Change TODO state. This prompts for a single TODO keyword and changes
|
|
the state of all selected entries, bypassing blocking and suppressing
|
|
logging notes (but not timestamps).
|
|
|
|
- {{{kbd(+)}}} ::
|
|
|
|
Add a tag to all selected entries.
|
|
|
|
- {{{kbd(-)}}} ::
|
|
|
|
Remove a tag from all selected entries.
|
|
|
|
- {{{kbd(s)}}} ::
|
|
|
|
Schedule all items to a new date. To shift existing schedule dates by
|
|
a fixed number of days, use something starting with double plus at the
|
|
prompt, for example {{{samp(++8d)}}} or {{{samp(++2w)}}}.
|
|
|
|
- {{{kbd(d)}}} ::
|
|
|
|
Set deadline to a specific date.
|
|
|
|
- {{{kbd(r)}}} ::
|
|
|
|
Prompt for a single refile target and move all entries. The entries
|
|
will no longer be in the agenda; refresh ({{{kbd(g)}}}) to bring them
|
|
back.
|
|
|
|
- {{{kbd(S)}}} ::
|
|
|
|
Reschedule randomly into the coming N days. N will be prompted for.
|
|
With prefix arg ({{{kbd(C-u B S)}}}), scatter only across weekdays.
|
|
|
|
- {{{kbd(f)}}} ::
|
|
|
|
Apply a function to marked entries.[fn:96] For example, the function
|
|
below sets the CATEGORY property of the entries to web.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(defun set-category ()
|
|
(interactive "P")
|
|
(let* ((marker (or (org-get-at-bol 'org-hd-marker)
|
|
(org-agenda-error)))
|
|
(buffer (marker-buffer marker)))
|
|
(with-current-buffer buffer
|
|
(save-excursion
|
|
(save-restriction
|
|
(widen)
|
|
(goto-char marker)
|
|
(org-back-to-heading t)
|
|
(org-set-property "CATEGORY" "web"))))))
|
|
#+end_src
|
|
|
|
*** Calendar commands
|
|
#+cindex: calendar commands, from agenda
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(c)}}}, ~org-agenda-goto-calendar~ ::
|
|
#+kindex: c
|
|
|
|
Open the Emacs calendar and move to the date at the agenda cursor.
|
|
|
|
- {{{kbd(c)}}}, ~org-calendar-goto-agenda~ ::
|
|
#+kindex: c
|
|
|
|
When in the calendar, compute and show the Org mode agenda for the
|
|
date at the cursor.
|
|
|
|
- {{{kbd(i)}}}, ~org-agenda-diary-entry~ ::
|
|
#+kindex: i
|
|
#+vindex: org-agenda-diary-file
|
|
#+cindex: diary entries, creating from agenda
|
|
|
|
Insert a new entry into the diary, using the date at the cursor and
|
|
(for block entries) the date at the mark. This will add to the Emacs
|
|
diary file, in a way similar to the {{{kbd(i)}}} command in the
|
|
calendar.[fn:97] The diary file will pop up in another window, where
|
|
you can add the entry.
|
|
|
|
If you configure ~org-agenda-diary-file~ to point to an Org mode file,
|
|
Org will create entries (in Org mode syntax) in that file instead.
|
|
Most entries will be stored in a date-based outline tree that will
|
|
later make it easy to archive appointments from previous months/years.
|
|
The tree will be built under an entry with a ~DATE_TREE~ property, or
|
|
else with years as top-level entries. Emacs will prompt you for the
|
|
entry text---if you specify it, the entry will be created in ~org-agenda-diary-file~ without further interaction. If you directly
|
|
press {{{key(RET)}}} at the prompt without typing text, the target
|
|
file will be shown in another window for you to finish the entry
|
|
there. See also the {{{kbd(k r)}}} command.
|
|
|
|
- {{{kbd(M)}}}, ~org-agenda-phases-of-moon~ ::
|
|
#+kindex: M
|
|
|
|
Show the phases of the moon for the three months around current date.
|
|
|
|
- {{{kbd(S)}}}, ~org-agenda-sunrise-sunset~ ::
|
|
#+kindex: S
|
|
|
|
Show sunrise and sunset times. The geographical location must be set
|
|
with calendar variables, see the documentation for the Emacs calendar.
|
|
|
|
- {{{kbd(C)}}}, ~org-agenda-convert-date~ ::
|
|
#+kindex: C
|
|
|
|
Convert the date at cursor into many other cultural and historic
|
|
calendars.
|
|
|
|
- {{{kbd(H)}}}, ~org-agenda-holidays~ ::
|
|
#+kindex: H
|
|
|
|
Show holidays for three months around the cursor date.
|
|
|
|
- {{{kbd(M-x org-export-icalendar-combine-agenda-files)}}} ::
|
|
|
|
Export a single iCalendar file containing entries from all agenda
|
|
files. This is a globally available command, and also available in the
|
|
agenda menu.
|
|
|
|
*** Exporting to a file
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-x C-w)}}}, ~org-agenda-write~ ::
|
|
#+kindex: C-x C-w
|
|
#+cindex: exporting agenda views
|
|
#+cindex: agenda views, exporting
|
|
#+vindex: org-agenda-exporter-settings
|
|
|
|
Write the agenda view to a file. Depending on the extension of the
|
|
selected file name, the view will be exported as HTML (extension
|
|
{{{file(.html)}}} or {{{file(.htm)}}}), Postscript (extension
|
|
{{{file(.ps)}}}), PDF (extension {{{file(.pdf)}}}), and plain text
|
|
(any other extension). When called with a {{{kbd(C-u)}}} prefix
|
|
argument, immediately open the newly created file. Use the variable ~org-agenda-exporter-settings~ to set options for {{{file(ps-print)}}}
|
|
and for {{{file(htmlize)}}} to be used during export.
|
|
|
|
*** Quit and exit
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(q)}}}, ~org-agenda-quit~ ::
|
|
#+kindex: q
|
|
|
|
Quit agenda, remove the agenda buffer.
|
|
|
|
- {{{kbd(x)}}}, ~org-agenda-exit~ ::
|
|
#+kindex: x
|
|
#+cindex: agenda files, removing buffers
|
|
|
|
Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
|
|
for the compilation of the agenda. Buffers created by the user to
|
|
visit Org files will not be removed.
|
|
|
|
** Custom agenda views
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Defining special searches and views
|
|
:END:
|
|
#+cindex: custom agenda views
|
|
#+cindex: agenda views, custom
|
|
|
|
Custom agenda commands serve two purposes: to store and quickly access
|
|
frequently used TODO and tags searches, and to create special composite
|
|
agenda buffers. Custom agenda commands will be accessible through the
|
|
dispatcher (see [[Agenda dispatcher]]), just like the default commands.
|
|
|
|
*** Storing searches
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Type once, use often
|
|
:END:
|
|
|
|
The first application of custom searches is the definition of keyboard
|
|
shortcuts for frequently used searches, either creating an agenda
|
|
buffer, or a sparse tree (the latter covering of course only the
|
|
current buffer).
|
|
|
|
#+kindex: C-c a C
|
|
#+vindex: org-agenda-custom-commands
|
|
|
|
Custom commands are configured in the variable
|
|
~org-agenda-custom-commands~. You can customize this variable, for
|
|
example by pressing {{{kbd(C-c a C)}}}. You can also directly set it
|
|
with Emacs Lisp in {{{file(.emacs)}}}. The following example contains
|
|
all valid search types:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands
|
|
'(("w" todo "WAITING")
|
|
("W" todo-tree "WAITING")
|
|
("u" tags "+boss-urgent")
|
|
("v" tags-todo "+boss-urgent")
|
|
("U" tags-tree "+boss-urgent")
|
|
("f" occur-tree "\\<FIXME\\>")
|
|
("h" . "HOME+Name tags searches") ; description for "h" prefix
|
|
("hl" tags "+home+Lisa")
|
|
("hp" tags "+home+Peter")
|
|
("hk" tags "+home+Kim")))
|
|
#+end_src
|
|
|
|
{{{noindent}}} The initial string in each entry defines the keys you
|
|
have to press after the dispatcher command {{{kbd(C-c a)}}} in order
|
|
to access the command. Usually this will be just a single character,
|
|
but if you have many similar commands, you can also define two-letter
|
|
combinations where the first character is the same in several
|
|
combinations and serves as a prefix key.[fn:98] The second parameter
|
|
is the search type, followed by the string or regular expression to be
|
|
used for the matching. The example above will therefore define:
|
|
|
|
#+attr_texinfo: :table-type table :indic @kbd
|
|
- C-c a w ::
|
|
|
|
A global search for TODO entries with {{{samp(WAITING)}}} as the TODO
|
|
keyword.
|
|
|
|
- C-c a W ::
|
|
|
|
The same search, but only in the current buffer and displaying the
|
|
results as a sparse tree.
|
|
|
|
- C-c a u ::
|
|
|
|
A global tags search for headlines marked {{{samp(:boss:)}}} but not
|
|
{{{samp(:urgent:)}}}.
|
|
|
|
- C-c a v ::
|
|
|
|
The same search as {{{kbd(C-c a u)}}}, but limiting the search to
|
|
headlines that are also TODO items.
|
|
|
|
- C-c a U ::
|
|
|
|
The same search as {{{kbd(C-c a u)}}}, but only in the current buffer and
|
|
displaying the result as a sparse tree.
|
|
|
|
- C-c a f ::
|
|
|
|
Create a sparse tree (again: current buffer only) with all entries
|
|
containing the word {{{samp(FIXME)}}}
|
|
|
|
- C-c a h ::
|
|
|
|
A prefix command for a HOME tags search where you have to press an
|
|
additional key ({{{kbd(l)}}}, {{{kbd(p)}}} or {{{kbd(k)}}}) to select
|
|
a name (Lisa, Peter, or Kim) as additional tag to match.
|
|
|
|
|
|
*** Block agenda
|
|
:PROPERTIES:
|
|
:DESCRIPTION: All the stuff you need in a single buffer
|
|
:END:
|
|
#+cindex: block agenda
|
|
#+cindex: agenda, with block views
|
|
|
|
Another possibility is the construction of agenda views that comprise
|
|
the results of /several/ commands, each of which creates a block in
|
|
the agenda buffer. The available commands include ~agenda~ for the
|
|
daily or weekly agenda (as created with {{{kbd(C-c a a)}}}), ~alltodo~
|
|
for the global TODO list (as constructed with {{{kbd(C-c a t)}}}), and
|
|
the matching commands discussed above: ~todo~, ~tags~, and
|
|
~tags-todo~. Here are two examples:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands
|
|
'(("h" "Agenda and Home-related tasks"
|
|
((agenda "")
|
|
(tags-todo "home")
|
|
(tags "garden")))
|
|
("o" "Agenda and Office-related tasks"
|
|
((agenda "")
|
|
(tags-todo "work")
|
|
(tags "office")))))
|
|
#+end_src
|
|
|
|
{{{noindent}}} This will define {{{kbd(C-c a h)}}} to create a
|
|
multi-block view for stuff you need to attend to at home. The
|
|
resulting agenda buffer will contain your agenda for the current week,
|
|
all TODO items that carry the tag {{{samp(home)}}}, and also all lines
|
|
tagged with {{{samp(garden)}}}. Finally the command {{{kbd(C-c a o)}}}
|
|
provides a similar view for office tasks.
|
|
|
|
*** Setting options for custom commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Changing the rules
|
|
:END:
|
|
#+cindex: options, for custom agenda views
|
|
#+vindex: org-agenda-custom-commands
|
|
|
|
Org mode contains a number of variables regulating agenda construction
|
|
and display. The global variables define the behavior for all agenda
|
|
commands, including the custom commands. However, if you want to
|
|
change some settings just for a single custom view, you can do so.
|
|
Setting options requires inserting a list of variable names and values
|
|
at the right spot in ~org-agenda-custom-commands~. For example:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands
|
|
'(("w" todo "WAITING"
|
|
((org-agenda-sorting-strategy '(priority-down))
|
|
(org-agenda-prefix-format " Mixed: ")))
|
|
("U" tags-tree "+boss-urgent"
|
|
((org-show-following-heading nil)
|
|
(org-show-hierarchy-above nil)))
|
|
("N" search ""
|
|
((org-agenda-files '("~org/notes.org"))
|
|
(org-agenda-text-search-extra-files nil)))))
|
|
#+end_src
|
|
|
|
{{{noindent}}} Now the {{{kbd(C-c a w)}}} command will sort the
|
|
collected entries only by priority, and the prefix format is modified
|
|
to just say {{{samp( Mixed: )}}} instead of giving the category of the
|
|
entry. The sparse tags tree of {{{kbd(C-c a U)}}} will now turn out
|
|
ultra-compact, because neither the headline hierarchy above the match,
|
|
nor the headline following the match will be shown. The command
|
|
{{{kbd(C-c a N)}}} will do a text search limited to only a single
|
|
file.
|
|
|
|
#+vindex: org-agenda-custom-commands
|
|
|
|
For command sets creating a block agenda, ~org-agenda-custom-commands~
|
|
has two separate spots for setting options. You can add options that
|
|
should be valid for just a single command in the set, and options that
|
|
should be valid for all commands in the set. The former are just added
|
|
to the command entry; the latter must come after the list of command
|
|
entries. Going back to the block agenda example (see [[Block
|
|
agenda]]), let's change the sorting strategy for the {{{kbd(C-c a
|
|
h)}}} commands to ~priority-down~, but let's sort the results for
|
|
GARDEN tags query in the opposite order, ~priority-up~. This would
|
|
look like this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands
|
|
'(("h" "Agenda and Home-related tasks"
|
|
((agenda)
|
|
(tags-todo "home")
|
|
(tags "garden"
|
|
((org-agenda-sorting-strategy '(priority-up)))))
|
|
((org-agenda-sorting-strategy '(priority-down))))
|
|
("o" "Agenda and Office-related tasks"
|
|
((agenda)
|
|
(tags-todo "work")
|
|
(tags "office")))))
|
|
#+end_src
|
|
|
|
As you see, the values and parentheses setting is a little complex.
|
|
When in doubt, use the customize interface to set this variable---it
|
|
fully supports its structure. Just one caveat: when setting options in
|
|
this interface, the /values/ are just Lisp expressions. So if the
|
|
value is a string, you need to add the double-quotes around the value
|
|
yourself.
|
|
|
|
#+vindex: org-agenda-custom-commands-contexts
|
|
|
|
To control whether an agenda command should be accessible from a
|
|
specific context, you can customize
|
|
~org-agenda-custom-commands-contexts~. Let's say for example that you
|
|
have an agenda command {{{kbd(o)}}} displaying a view that you only
|
|
need when reading emails. Then you would configure this option like
|
|
this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands-contexts
|
|
'(("o" (in-mode . "message-mode"))))
|
|
#+end_src
|
|
|
|
You can also tell that the command key {{{kbd(o)}}} should refer to another
|
|
command key {{{kbd(r)}}}. In that case, add this command key like this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands-contexts
|
|
'(("o" "r" (in-mode . "message-mode"))))
|
|
#+end_src
|
|
|
|
See the docstring of the variable for more information.
|
|
|
|
** Exporting agenda views
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Writing a view to a file
|
|
:END:
|
|
#+cindex: agenda views, exporting
|
|
|
|
If you are away from your computer, it can be very useful to have a
|
|
printed version of some agenda views to carry around. Org mode can
|
|
export custom agenda views as plain text, HTML, Postscript,
|
|
PDF, and iCalendar files.[fn:99] If you want to
|
|
do this only occasionally, use the following command:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-x C-w)}}}, ~org-agenda-write~ ::
|
|
|
|
#+cindex: exporting agenda views
|
|
#+cindex: agenda views, exporting
|
|
#+vindex: org-agenda-exporter-settings
|
|
|
|
Write the agenda view to a file. Depending on the extension of the
|
|
selected file name, the view will be exported as HTML (extension
|
|
{{{file(.html)}}} or {{{file(.htm)}}}), Postscript (extension
|
|
{{{file(.ps)}}}), iCalendar (extension {{{file(.ics)}}}), or plain
|
|
text (any other extension). Use the variable ~org-agenda-exporter-settings~ to set options for {{{file(ps-print)}}}
|
|
and for {{{file(htmlize)}}} to be used during export, for example:
|
|
|
|
#+vindex: org-agenda-add-entry-text-maxlines
|
|
#+vindex: htmlize-output-type
|
|
#+vindex: ps-number-of-columns
|
|
#+vindex: ps-landscape-mode
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-exporter-settings
|
|
'((ps-number-of-columns 2)
|
|
(ps-landscape-mode t)
|
|
(org-agenda-add-entry-text-maxlines 5)
|
|
(htmlize-output-type 'css)))
|
|
#+end_src
|
|
|
|
|
|
If you need to export certain agenda views frequently, you can
|
|
associate any custom agenda command with a list of output file
|
|
names.[fn:100] Here is an example that first defines custom commands
|
|
for the agenda and the global TODO list, together with a number of
|
|
files to which to export them. Then we define two block agenda
|
|
commands and specify file names for them as well. File names can be
|
|
relative to the current working directory, or absolute.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands
|
|
'(("X" agenda "" nil ("agenda.html" "agenda.ps"))
|
|
("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
|
|
("h" "Agenda and Home-related tasks"
|
|
((agenda "")
|
|
(tags-todo "home")
|
|
(tags "garden"))
|
|
nil
|
|
("~/views/home.html"))
|
|
("o" "Agenda and Office-related tasks"
|
|
((agenda)
|
|
(tags-todo "work")
|
|
(tags "office"))
|
|
nil
|
|
("~/views/office.ps" "~/calendars/office.ics"))))
|
|
#+end_src
|
|
|
|
The extension of the file name determines the type of export. If it is
|
|
{{{file(.html)}}}, Org mode will use the {{{file(htmlize.el)}}}
|
|
package to convert the buffer to HTML and save it to this file name.
|
|
If the extension is {{{file(.ps)}}}, ~ps-print-buffer-with-faces~ is
|
|
used to produce Postscript output. If the extension is
|
|
{{{file(.ics)}}}, iCalendar export is run export over all files that
|
|
were used to construct the agenda, and limit the export to entries
|
|
listed in the agenda. Any other extension produces a plain ASCII file.
|
|
|
|
The export files are /not/ created when you use one of those
|
|
commands interactively because this might use too much overhead.
|
|
Instead, there is a special command to produce /all/ specified
|
|
files in one step:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c a e)}}}, ~org-store-agenda-views~ ::
|
|
|
|
Export all agenda views that have export file names associated with
|
|
them.
|
|
|
|
|
|
You can use the options section of the custom agenda commands to also
|
|
set options for the export commands. For example:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-agenda-custom-commands
|
|
'(("X" agenda ""
|
|
((ps-number-of-columns 2)
|
|
(ps-landscape-mode t)
|
|
(org-agenda-prefix-format " [ ] ")
|
|
(org-agenda-with-colors nil)
|
|
(org-agenda-remove-tags t))
|
|
("theagenda.ps"))))
|
|
#+end_src
|
|
|
|
{{{noindent}}} This command sets two options for the Postscript
|
|
exporter, to make it print in two columns in landscape format---the
|
|
resulting page can be cut in two and then used in a paper agenda. The
|
|
remaining settings modify the agenda prefix to omit category and
|
|
scheduling information, and instead include a checkbox to check off
|
|
items. We also remove the tags to make the lines compact, and we don't
|
|
want to use colors for the black-and-white printer. Settings specified
|
|
in ~org-agenda-exporter-settings~ will also apply, but the settings in
|
|
~org-agenda-custom-commands~ take precedence.
|
|
|
|
{{{noindent}}} From the command line you may also use:
|
|
|
|
#+begin_src sh
|
|
emacs -eval (org-batch-store-agenda-views) -kill
|
|
#+end_src
|
|
|
|
{{{noindent}}} or, if you need to modify some parameters:[fn:101]
|
|
|
|
#+begin_example
|
|
emacs -eval '(org-batch-store-agenda-views \
|
|
org-agenda-span (quote month) \
|
|
org-agenda-start-day "2007-11-01" \
|
|
org-agenda-include-diary nil \
|
|
org-agenda-files (quote ("~/org/project.org")))' \
|
|
-kill
|
|
#+end_example
|
|
|
|
{{{noindent}}} which will create the agenda views restricted to the
|
|
file {{{file(~/org/project.org)}}}, without diary entries and with a
|
|
30-day extent.
|
|
|
|
You can also extract agenda information in a way that allows further
|
|
processing by other programs. See [[Extracting agenda information]], for
|
|
more information.
|
|
|
|
** Using column view in the agenda
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Using column view for collected entries
|
|
:ALT_TITLE: Agenda column view
|
|
:END:
|
|
#+cindex: column view, in agenda
|
|
#+cindex: agenda, column view
|
|
<<Agenda column view>>
|
|
|
|
Column view (see [[Column view]]) is normally used to view and edit
|
|
properties embedded in the hierarchical structure of an Org file. It
|
|
can be quite useful to use column view also from the agenda, where
|
|
entries are collected by certain criteria.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-c)}}}, ~org-agenda-columns~ ::
|
|
|
|
Turn on column view in the agenda.
|
|
|
|
|
|
To understand how to use this properly, it is important to realize that the
|
|
entries in the agenda are no longer in their proper outline environment.
|
|
This causes the following issues:
|
|
|
|
1. Org needs to make a decision which ~COLUMNS~ format to use. Since
|
|
the entries in the agenda are collected from different files, and
|
|
different files may have different ~COLUMNS~ formats, this is a
|
|
non-trivial problem. Org first checks if the variable ~org-agenda-overriding-columns-format~ is currently set, and if so,
|
|
takes the format from there. Otherwise it takes the format
|
|
associated with the first item in the agenda, or, if that item does
|
|
not have a specific format (defined in a property, or in its file),
|
|
it uses ~org-columns-default-format~.
|
|
|
|
#+vindex: org-columns-default-format
|
|
#+vindex: org-overriding-columns-format
|
|
|
|
2. If any of the columns has a summary type defined (see [[Column
|
|
attributes]]), turning on column view in the agenda will visit all
|
|
relevant agenda files and make sure that the computations of this
|
|
property are up to date. This is also true for the special ~CLOCKSUM~ property. Org will then sum the values displayed in the
|
|
agenda. In the daily/weekly agenda, the sums will cover a single
|
|
day; in all other views they cover the entire block. It is vital to
|
|
realize that the agenda may show the same entry /twice/ (for
|
|
example as scheduled and as a deadline), and it may show two
|
|
entries from the same hierarchy (for example a /parent/ and its /child/). In these cases, the summation in the agenda will lead to
|
|
incorrect results because some values will count double.
|
|
|
|
#+cindex: property, special, CLOCKSUM
|
|
|
|
3. When the column view in the agenda shows the ~CLOCKSUM~, that is
|
|
always the entire clocked time for this item. So even in the
|
|
daily/weekly agenda, the clocksum listed in column view may
|
|
originate from times outside the current view. This has the
|
|
advantage that you can compare these values with a column listing
|
|
the planned total effort for a task---one of the major applications
|
|
for column view in the agenda. If you want information about
|
|
clocked time in the displayed period use clock table mode (press
|
|
{{{kbd(R)}}} in the agenda).
|
|
|
|
4. When the column view in the agenda shows the ~CLOCKSUM_T~, that is
|
|
always today's clocked time for this item. So even in the weekly agenda,
|
|
the clocksum listed in column view only originates from today. This lets
|
|
you compare the time you spent on a task for today, with the time already
|
|
spent (via ~CLOCKSUM~) and with the planned total effort for it.
|
|
|
|
#+cindex: property, special, CLOCKSUM_T
|
|
|
|
* FIXME Markup for rich export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Prepare text for rich export
|
|
:ALT_TITLE: Markup
|
|
:END:
|
|
|
|
When exporting Org mode documents, the exporter tries to reflect the
|
|
structure of the document as accurately as possible in the backend.
|
|
Since export targets like HTML, LaTeX, or DocBook allow much richer
|
|
formatting, Org mode has rules on how to prepare text for rich export.
|
|
This section summarizes the markup rules used in an Org mode buffer.
|
|
|
|
** Structural markup elements
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The basic structure as seen by the exporter
|
|
:END:
|
|
|
|
*** Document title
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Where the title is taken from
|
|
:END:
|
|
#+cindex: document title, markup rules
|
|
|
|
{{{noindent}}} The title of the exported document is taken from the
|
|
special line:
|
|
|
|
#+cindex: #+TITLE
|
|
#+begin_example
|
|
,#+TITLE: This is the title of the document
|
|
#+end_example
|
|
|
|
{{{noindent}}} If this line does not exist, the title is derived from
|
|
the first non-empty, non-comment line in the buffer. If no such line
|
|
exists, or if you have turned off exporting of the text before the
|
|
first headline (see below), the title will be the file name without
|
|
extension.
|
|
|
|
#+cindex: property, EXPORT_TITLE
|
|
|
|
If you are exporting only a subtree by marking is as the region, the
|
|
heading of the subtree will become the title of the document. If the
|
|
subtree has a property ~EXPORT_TITLE~, that will take precedence.
|
|
|
|
*** Headings and sections
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The document structure as seen by the exporter
|
|
:END:
|
|
#+cindex: headings and sections, markup rules
|
|
|
|
#+vindex: org-export-headline-levels
|
|
|
|
The outline structure of the document as described in [[Document
|
|
structure]], forms the basis for defining sections of the exported
|
|
document. However, since the outline structure is also used for (for
|
|
example) lists of tasks, only the first three outline levels will be
|
|
used as headings. Deeper levels will become itemized lists. You can
|
|
change the location of this switch globally by setting the variable
|
|
~org-export-headline-levels~, or on a per-file basis with the ~H~ option:
|
|
|
|
#+cindex: #+OPTIONS
|
|
#+begin_example
|
|
,#+OPTIONS: H:4
|
|
#+end_example
|
|
|
|
*** Table of contents
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The if and where of the table of contents
|
|
:END:
|
|
#+cindex: table of contents, markup rules
|
|
|
|
#+vindex: org-export-with-toc
|
|
|
|
The table of contents is normally inserted directly before the first
|
|
headline of the file. If you would like to get it to a different
|
|
location, insert the string ~[TABLE-OF-CONTENTS]~ on a line by itself
|
|
at the desired location. The depth of the table of contents is by
|
|
default the same as the number of headline levels, but you can choose
|
|
a smaller number, or turn off the table of contents entirely, by
|
|
configuring the variable ~org-export-with-toc~, or on a per-file basis
|
|
with the ~toc~ option:
|
|
|
|
#+begin_example
|
|
,#+OPTIONS: toc:2 (only to two levels in TOC)
|
|
,#+OPTIONS: toc:nil (no TOC at all)
|
|
#+end_example
|
|
|
|
*** Initial text
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Text before the first heading?
|
|
:TITLE: Text before the first headline
|
|
:END:
|
|
#+cindex: text before first headline, markup rules
|
|
#+cindex: #+TEXT
|
|
|
|
Org mode normally exports the text before the first headline, and even uses
|
|
the first line as the document title. The text will be fully marked up. If
|
|
you need to include literal HTML, LaTeX, or DocBook code, use the special
|
|
constructs described below in the sections for the individual exporters.
|
|
|
|
#+vindex: org-export-skip-text-before-1st-heading
|
|
|
|
Some people like to use the space before the first headline for setup
|
|
and internal links and therefore would like to control the exported
|
|
text before the first headline in a different way. You can do so by
|
|
setting the variable ~org-export-skip-text-before-1st-heading~ to ~t~.
|
|
On a per-file basis, you can get the same effect with
|
|
{{{samp(#+OPTIONS: skip:t)}}}.
|
|
|
|
{{{noindent}}}
|
|
|
|
If you still want to have some text before the first headline, use the
|
|
~#+TEXT~ construct:
|
|
|
|
#+begin_example
|
|
,#+OPTIONS: skip:t
|
|
,#+TEXT: This text will go before the *first* headline.
|
|
,#+TEXT: [TABLE-OF-CONTENTS]
|
|
,#+TEXT: This goes between the table of contents and the *first* headline
|
|
#+end_example
|
|
|
|
*** Lists
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Lists
|
|
:END:
|
|
#+cindex: lists, markup rules
|
|
|
|
Plain lists as described in [[Plain lists]], are translated to the
|
|
backend's syntax for such lists. Most backends support unordered,
|
|
ordered, and description lists.
|
|
|
|
*** Paragraphs
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Paragraphs
|
|
:END:
|
|
#+cindex: paragraphs, markup rules
|
|
|
|
Paragraphs are separated by at least one empty line. If you need to
|
|
enforce a line break within a paragraph, use ~\\~ at the end
|
|
of a line.
|
|
|
|
To keep the line breaks in a region, but otherwise use normal
|
|
formatting, you can use ~VERSE~ blocks, which can also be used to
|
|
format poetry:
|
|
|
|
#+cindex: #+BEGIN_VERSE
|
|
#+begin_example
|
|
#+BEGIN_VERSE
|
|
Great clouds overhead
|
|
Tiny black birds rise and fall
|
|
Snow covers Emacs
|
|
|
|
-- AlexSchroeder
|
|
#+END_VERSE
|
|
#+end_example
|
|
|
|
When quoting a passage from another document, it is customary to
|
|
format this as a paragraph that is indented on both the left and the
|
|
right margin. You can include quotations in Org mode documents like
|
|
this:
|
|
|
|
#+cindex: #+BEGIN_QUOTE
|
|
#+begin_example
|
|
#+BEGIN_QUOTE
|
|
Everything should be made as simple as possible,
|
|
but not any simpler -- Albert Einstein
|
|
#+END_QUOTE
|
|
#+end_example
|
|
|
|
If you would like to center some text, do it like this:
|
|
#+cindex: #+BEGIN_CENTER
|
|
#+begin_example
|
|
#+BEGIN_CENTER
|
|
Everything should be made as simple as possible, \\
|
|
but not any simpler
|
|
#+END_CENTER
|
|
#+end_example
|
|
|
|
*** Footnote markup
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Footnotes
|
|
:END:
|
|
#+cindex: footnotes, markup rules
|
|
#+cindex: @file{footnote.el}
|
|
|
|
Footnotes defined in the way described in [[Creating footnotes]], will be exported
|
|
by all backends. Org allows multiple references to the same note, and
|
|
multiple footnotes side by side.
|
|
|
|
*** Emphasis and monospace
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Bold, italic, etc.
|
|
:END:
|
|
|
|
#+cindex: underlined text, markup rules
|
|
#+cindex: bold text, markup rules
|
|
#+cindex: italic text, markup rules
|
|
#+cindex: verbatim text, markup rules
|
|
#+cindex: code text, markup rules
|
|
#+cindex: strike-through text, markup rules
|
|
|
|
You can make words **bold**, //italic//, _underlined_, ~=code=~
|
|
and ~~verbatim~~, and, if you must, {{{samp(+strike-through+)}}}. Text
|
|
in the code and verbatim string is not processed for Org mode specific
|
|
syntax; it is exported verbatim.
|
|
|
|
*** Horizontal rules
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Make a line
|
|
:END:
|
|
#+cindex: horizontal rules, markup rules
|
|
|
|
A line consisting of only dashes, and at least 5 of them, will be
|
|
exported as a horizontal line (~<hr/>~ in HTML and ~\hrule~
|
|
in LaTeX).
|
|
|
|
*** Comment lines
|
|
:PROPERTIES:
|
|
:DESCRIPTION: What will *not* be exported
|
|
:END:
|
|
#+cindex: comment lines
|
|
#+cindex: exporting, not
|
|
#+cindex: #+BEGIN_COMMENT
|
|
|
|
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.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c ;)}}} ::
|
|
#+kindex: C-c ;
|
|
|
|
Toggle the COMMENT keyword at the beginning of an entry.
|
|
|
|
** Images and tables
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tables and images can be exported
|
|
:END:
|
|
|
|
#+cindex: tables, markup rules
|
|
#+cindex: #+CAPTION
|
|
#+cindex: #+LABEL
|
|
|
|
Both the native Org mode tables (see [[Tables]]) and tables formatted with
|
|
the {{{file(table.el)}}} package will be exported properly. For Org
|
|
mode tables, the lines before the first horizontal separator line will
|
|
become table header lines. You can use the following lines somewhere
|
|
before the table to assign a caption and a label for cross references,
|
|
and in the text you can refer to the object with
|
|
~\ref{tab:basic-data}~:
|
|
|
|
#+begin_example
|
|
#+CAPTION: This is the caption for the next table (or link)
|
|
#+LABEL: tab:basic-data
|
|
| ... | ...|
|
|
|-----|----|
|
|
#+end_example
|
|
|
|
Optionally, the caption can take the form:
|
|
#+begin_example
|
|
#+CAPTION: [Caption for list of figures]{Caption for table (or link).}
|
|
#+end_example
|
|
|
|
#+cindex: inlined images, markup rules
|
|
|
|
Some backends (HTML, LaTeX, and DocBook) allow you to directly
|
|
include images into the exported document. Org does this, if a link to
|
|
an image files does not have a description part, for example
|
|
~[[./img/a.jpg]]~. If you wish to define a caption for the image and maybe
|
|
a label for internal cross references, make sure that the link is on a
|
|
line by itself and precede it with ~#+CAPTION~ and ~#+LABEL~ as
|
|
follows:
|
|
|
|
#+begin_example
|
|
#+CAPTION: This is the caption for the next figure link (or table)
|
|
#+LABEL: fig:SED-HR4049
|
|
[[./img/a.jpg]]
|
|
#+end_example
|
|
|
|
You may also define additional attributes for the figure. As this is
|
|
backend-specific, see the sections about the individual backends for
|
|
more information.
|
|
|
|
See [[Handling links][the discussion of image links]].
|
|
|
|
** Literal examples
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Source code examples with special formatting
|
|
:END:
|
|
#+cindex: literal examples, markup rules
|
|
#+cindex: code line references, markup rules
|
|
|
|
You can include literal examples that should not be subjected to
|
|
markup. Such examples will be typeset in monospace, so this is well
|
|
suited for source code and similar examples.
|
|
#+cindex: #+BEGIN_EXAMPLE
|
|
|
|
#+begin_example
|
|
,#+BEGIN_EXAMPLE
|
|
Some example from a text file.
|
|
,#+END_EXAMPLE
|
|
#+end_example
|
|
|
|
Note that such blocks may be /indented/ in order to align nicely with
|
|
indented text and in particular with plain list structure (see [[Plain
|
|
lists]]). For simplicity when using small examples, you can also start
|
|
the example lines with a colon followed by a space. There may also be
|
|
additional whitespace before the colon:
|
|
|
|
#+begin_example
|
|
Here is an example
|
|
: Some example from a text file.
|
|
#+end_example
|
|
|
|
#+cindex: formatting source code, markup rules
|
|
|
|
If the example is source code from a programming language, or any
|
|
other text that can be marked up by font-lock in Emacs, you can ask
|
|
for the example to look like the fontified Emacs buffer.[fn:102] This
|
|
is done with the {{{samp(src)}}} block, where you also need to specify
|
|
the name of the major mode that should be used to fontify the example,
|
|
see [[Easy templates]] for shortcuts to easily insert code blocks.[fn:103]
|
|
|
|
#+cindex: #+BEGIN_SRC
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC emacs-lisp
|
|
(defun org-xor (a b)
|
|
"Exclusive or."
|
|
(if a (not b) b))
|
|
#+END_SRC
|
|
#+end_example
|
|
|
|
Both in ~example~ and in ~src~ snippets, you can add a ~-n~ switch to
|
|
the end of the ~BEGIN~ line, to get the lines of the example numbered.
|
|
If you use a ~+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 ~[[(name)]]~ (i.e., the
|
|
reference name enclosed in single parenthesis). In HTML, hovering the
|
|
mouse over such a link will remote-highlight the corresponding code
|
|
line, which is kind of cool.
|
|
|
|
You can also add a ~-r~ switch which /removes/ the labels from the
|
|
source code.[fn:104] With the ~-n~ switch, links to these references
|
|
will be labeled by the line numbers from the code listing, otherwise
|
|
links will use the labels with no parentheses. Here is an example:
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC emacs-lisp -n -r
|
|
(save-excursion (ref:sc)
|
|
(goto-char (point-min)) (ref:jump)
|
|
#+END_SRC
|
|
In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
|
|
jumps to point-min.
|
|
#+end_example
|
|
|
|
#+vindex: org-coderef-label-format
|
|
|
|
If the syntax for the label format conflicts with the language syntax,
|
|
use a ~-l~ switch to change the format, for example
|
|
{{{samp(#+BEGIN_SRC pascal -n -r -l "((%s))")}}}. See also the
|
|
variable ~org-coderef-label-format~.
|
|
|
|
HTML export also allows examples to be published as text areas
|
|
(see [[Text areas in HTML export]]).
|
|
|
|
Because the ~#+BEGIN_...~ and ~#+END_...~ patterns need to be added so
|
|
often, shortcuts are provided using the Easy Templates facility (see
|
|
[[Easy templates]]).
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c ')}}} ::
|
|
#+kindex: C-c '
|
|
|
|
Edit the source code example at point in its native mode. This works
|
|
by switching to a temporary buffer with the source code. You need to
|
|
exit by pressing {{{kbd(C-c ')}}} again.[fn:105] The edited version
|
|
will then replace the old version in the Org buffer. Fixed-width
|
|
regions (where each line starts with a colon followed by a space) will
|
|
be edited using ~artist-mode~ to allow creating ASCII drawings
|
|
easily.[fn:106] Using this command in an empty line will create a new
|
|
fixed-width region.
|
|
|
|
- {{{kbd(C-c l)}}} ::
|
|
#+kindex: C-c l
|
|
|
|
Calling ~org-store-link~ while editing a source code example in a
|
|
temporary buffer created with {{{kbd(C-c ')}}} will prompt for a
|
|
label. Make sure that it is unique in the current buffer, and insert
|
|
it with the proper formatting like {{{samp((ref:label))}}} at the end
|
|
of the current line. Then the label is stored as a link
|
|
{{{samp((label))}}}, for retrieval with {{{kbd(C-c C-l)}}}.
|
|
|
|
** Include files
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Include additional files into a document
|
|
:END:
|
|
#+cindex: include files, markup rules
|
|
|
|
During export, you can include the content of another file. For
|
|
example, to include your {{{file(.emacs)}}} file, you could use:
|
|
|
|
#+cindex: #+INCLUDE
|
|
|
|
#+begin_example
|
|
,#+INCLUDE: "~/.emacs" src emacs-lisp
|
|
#+end_example
|
|
|
|
{{{noindent}}} 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 processed normally. The
|
|
include line will also allow additional keyword parameters ~:prefix1~
|
|
and ~:prefix~ to specify prefixes for the first line and for each
|
|
following line, ~:minlevel~ in order to get Org mode content demoted
|
|
to a specified level, as well as any options accepted by the selected
|
|
markup. For example, to include a file as an item, use:
|
|
|
|
#+begin_example
|
|
,#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " "
|
|
#+end_example
|
|
|
|
You can also include a portion of a file by specifying a lines range
|
|
using the ~:lines~ parameter. The line at the upper end of the range
|
|
will not be included. The start and/or the end of the range may be
|
|
omitted to use the obvious defaults.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- #+INCLUDE: "~/.emacs" :lines "5-10" ::
|
|
|
|
Include lines 5 to 10, 10 excluded.
|
|
|
|
- #+INCLUDE: "~/.emacs" :lines "-10" ::
|
|
|
|
Include lines 1 to 10, 10 excluded.
|
|
|
|
- #+INCLUDE: "~/.emacs" :lines "10-" ::
|
|
|
|
Include lines from 10 to EOF.
|
|
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c ')}}}
|
|
#+kindex: C-c '
|
|
|
|
Visit the include file at point.
|
|
|
|
** Index entries
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Making an index
|
|
:END:
|
|
#+cindex: index entries, for publishing
|
|
|
|
You can specify entries that will be used for generating an index
|
|
during publishing. This is done by lines starting with ~#+INDEX~. An
|
|
entry the contains an exclamation mark will create a sub item. See
|
|
[[Generating an index]] for more information.
|
|
|
|
#+begin_example
|
|
,* Curriculum Vitae
|
|
#+INDEX: CV
|
|
#+INDEX: Application!CV
|
|
#+end_example
|
|
|
|
** Macro replacement
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Use macros to create complex output
|
|
:END:
|
|
#+cindex: macro replacement, during export
|
|
#+cindex: #+MACRO
|
|
|
|
You can define text snippets with a macro:
|
|
|
|
#+begin_example
|
|
,#+MACRO: name replacement text $1, $2 are arguments
|
|
#+end_example
|
|
|
|
{{{noindent}}} which can be referenced anywhere in the document (even in
|
|
code examples) with ~{{{name(arg1,arg2)}}}~. In addition to
|
|
defined macros, ~{{{title}}}~, ~{{{author}}}~, etc.,
|
|
will reference information set by the ~#+TITLE:~, ~#+AUTHOR:~, and
|
|
similar lines. Also, ~{{{date(FORMAT)}}}~ and
|
|
~{{{modification-time(FORMAT)}}}~ refer to current date time
|
|
and to the modification time of the file being exported, respectively.
|
|
~FORMAT~ should be a format string understood by
|
|
~format-time-string~.
|
|
|
|
Macro expansion takes place during export, and some people use it to
|
|
construct complex HTML code.
|
|
|
|
** FIXME Embedded LaTeX
|
|
:PROPERTIES:
|
|
:DESCRIPTION: LaTeX can be freely used inside Org documents
|
|
:ALT_TITLE: Embedded Latex
|
|
:END:
|
|
#+cindex: @TeX{} interpretation
|
|
#+cindex: @LaTeX{} interpretation
|
|
|
|
Plain ASCII is normally sufficient for almost all note taking.
|
|
Exceptions include scientific notes, which often require mathematical
|
|
symbols and the occasional formula. LaTeX is widely used to typeset
|
|
scientific documents.[fn:107] Org mode supports embedding LaTeX
|
|
code into its files, because many academics are used to writing and
|
|
reading LaTeX source code, and because it can be readily processed
|
|
to produce pretty output for a number of export backends.
|
|
|
|
*** Special symbols
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Greek letters and other symbols
|
|
:END:
|
|
#+cindex: math symbols
|
|
#+cindex: special symbols
|
|
#+cindex: @TeX{} macros
|
|
#+cindex: @LaTeX{} fragments, markup rules
|
|
#+cindex: HTML entities
|
|
#+cindex: @LaTeX{} entities
|
|
|
|
You can use LaTeX macros to insert special symbols like
|
|
~\alpha~ to indicate the Greek letter, or ~\to~ to
|
|
indicate an arrow. Completion for these macros is available, just type
|
|
~\~ and maybe a few letters, and press {{{kbdkey(M-,TAB)}}}
|
|
to see possible completions. Unlike LaTeX code, Org mode allows
|
|
these macros to be present without surrounding math delimiters, for
|
|
example:
|
|
|
|
#+begin_example
|
|
Angles are written as Greek letters \alpha, \beta and \gamma.
|
|
#+end_example
|
|
|
|
#+vindex: org-entities
|
|
|
|
During export, these symbols will be transformed into the native
|
|
format of the exporter backend. Strings like ~\alpha~ will be exported
|
|
as ~α~ in the HTML output, and as ~$\alpha$~ in the LaTeX
|
|
output. Similarly, ~\nbsp~ will become ~ ~ in HTML and ~~~ in
|
|
LaTeX. If you need such a symbol inside a word, terminate it like
|
|
this: ~\Aacute{}stor~.
|
|
|
|
A large number of entities is provided, with names taken from both
|
|
HTML and LaTeX; see the variable ~org-entities~ for the complete
|
|
list. ~\-~ is treated as a shy hyphen, and {{{samp(--)}}},
|
|
{{{samp(---)}}}, and {{{samp(...)}}} are all converted into special
|
|
commands creating hyphens of different lengths or a compact set of
|
|
dots.
|
|
|
|
If you would like to see entities displayed as UTF8 characters, use the
|
|
following command:[fn:108]
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x XXX)}}} ::
|
|
#+kindex: C-c C-x XXX
|
|
# Should be \
|
|
Toggle display of entities as UTF-8 characters. This does not change
|
|
the buffer content which remains plain ASCII, but it overlays the
|
|
UTF-8 character for display purposes only.
|
|
|
|
*** FIXME Subscripts and superscripts
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Simple syntax for raising/lowering text
|
|
:END:
|
|
#+cindex: subscript
|
|
#+cindex: superscript
|
|
|
|
Just like in LaTeX, {{{samp(^)}}} and {{{samp(_)}}} are used to
|
|
indicate super- and subscripts. Again, these can be used without
|
|
embedding them in math-mode delimiters. To increase the readability of
|
|
ASCII text, it is not necessary (but OK) to surround multi-character
|
|
sub- and superscripts with curly braces. For example
|
|
|
|
#+begin_example
|
|
The mass of the sun is M_sun = 1.989 x 10^30 kg. The radius of
|
|
the sun is R_{sun} = 6.96 x 10^8 m.
|
|
#+end_example
|
|
|
|
#+vindex: org-export-with-sub-superscripts
|
|
|
|
To avoid interpretation as raised or lowered text, you can quote
|
|
{{{kbd(^)}}} and {{{kbd(_)}}} with a backslash: ~\^~ and ~\_~. If you
|
|
write a text where the underscore is often used in a different
|
|
context, Org's convention to always interpret these as subscripts can
|
|
get in your way. Configure the variable
|
|
~org-export-with-sub-superscripts~ to globally change this convention,
|
|
or use, on a per-file basis:
|
|
|
|
#+begin_example
|
|
,#+OPTIONS: ^:{}
|
|
#+end_example
|
|
|
|
{{{noindent}}} With this setting, ~a_b~ will not be interpreted as a
|
|
subscript, but ~a_{b}~ will.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x XXX)}}} ::
|
|
#+kindex: C-c C-x XXX
|
|
# Should be \
|
|
In addition to showing entities as UTF-8 characters, this command will
|
|
also format sub- and superscripts in a WYSIWYM way.
|
|
|
|
*** LaTeX fragments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Complex formulas made easy
|
|
:END:
|
|
#+cindex: @LaTeX{} fragments
|
|
#+vindex: org-format-latex-header
|
|
|
|
Going beyond symbols and sub- and superscripts, a full formula
|
|
language is needed. Org mode can contain LaTeX math fragments, and
|
|
it supports ways to process these for several export backends. When
|
|
exporting to LaTeX, the code is obviously left as it is. When
|
|
exporting to HTML, Org invokes the [[http://www.mathjax.org][MathJax library]] (see [[Math
|
|
formatting in HTML export]]) to process and display the math.[fn:109]
|
|
Finally, it can also process the mathematical expressions into images
|
|
that can be displayed in a browser or in DocBook documents.[fn:110]
|
|
|
|
LaTeX fragments don't need any special marking at all. The following
|
|
snippets will be identified as LaTeX source code:
|
|
|
|
- Environments of any kind.[fn:111] The only requirement is that the ~\begin~ statement appears on a new line, preceded by only whitespace.
|
|
|
|
- Text within the usual LaTeX math delimiters. To avoid conflicts
|
|
with currency specifications, single ~$~ characters are
|
|
only recognized as math delimiters if the enclosed text contains at
|
|
most two line breaks, is directly attached to the ~$~
|
|
characters with no whitespace in between, and if the closing ~$~ is followed by whitespace, punctuation or a dash. For
|
|
the other delimiters, there is no such restriction, so when in
|
|
doubt, use ~\(...\)~ as inline math delimiters.
|
|
|
|
|
|
{{{noindent}}} For example:
|
|
|
|
#+begin_example
|
|
\begin{equation} % arbitrary environments,
|
|
x=\sqrt{b} % even tables, figures
|
|
\end{equation} % etc
|
|
|
|
If $a^2=b$ and \( b=2 \), then the solution must be
|
|
either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
|
|
#+end_example
|
|
|
|
{{{noindent}}}
|
|
#+vindex: org-format-latex-options
|
|
|
|
If you need any of the delimiter ASCII sequences for other purposes,
|
|
you can configure the option ~org-format-latex-options~ to deselect
|
|
the ones you do not wish to have interpreted by the LaTeX
|
|
converter.
|
|
|
|
#+vindex: org-export-with-LaTeX-fragments
|
|
|
|
LaTeX processing can be configured with the variable
|
|
~org-export-with-LaTeX-fragments~. The default setting is ~t~ which
|
|
means {{{file(MathJax)}}} for HTML, and no processing for DocBook,
|
|
ASCII and LaTeX backends. You can also set this variable on a
|
|
per-file basis using one of these lines:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- #+OPTIONS: LaTeX:t ::
|
|
|
|
Do the right thing automatically (MathJax).
|
|
|
|
- #+OPTIONS: LaTeX:dvipng ::
|
|
|
|
Force using dvipng images.
|
|
|
|
- #+OPTIONS: LaTeX:nil ::
|
|
|
|
Do not process LaTeX fragments at all
|
|
|
|
- #+OPTIONS: LaTeX:verbatim ::
|
|
|
|
Verbatim export, for jsMath or so.
|
|
|
|
*** Previewing LaTeX fragments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: What will this snippet look like?
|
|
:END:
|
|
#+cindex: @LaTeX{} fragments, preview
|
|
|
|
If you have {{{file(dvipng)}}} installed, LaTeX fragments can be
|
|
processed to produce preview images of the typeset expressions:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-l)}}} ::
|
|
#+kindex: C-c C-x C-l
|
|
|
|
Produce a preview image of the LaTeX fragment at point and overlay
|
|
it over the source code. If there is no fragment at point, process all
|
|
fragments in the current entry (between two headlines). When called
|
|
with a prefix argument, process the entire subtree. When called with
|
|
two prefix arguments, or when the cursor is before the first headline,
|
|
process the entire buffer.
|
|
|
|
- {{{kbd(C-c C-c)}}} ::
|
|
#+kindex: C-c C-c
|
|
|
|
Remove the overlay preview images.
|
|
|
|
|
|
#+vindex: org-format-latex-options
|
|
|
|
You can customize the variable ~org-format-latex-options~ to influence
|
|
some aspects of the preview. In particular, the ~:scale~ (and for HTML
|
|
export, ~:html-scale~) property can be used to adjust the size of the
|
|
preview images.
|
|
|
|
*** CDLaTeX mode
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Speed up entering of formulas
|
|
:TITLE: Using CDLaTeX to enter math
|
|
:END:
|
|
#+cindex: CD@LaTeX{}
|
|
|
|
CDLaTeX mode is a minor mode that is normally used in combination
|
|
with a major LaTeX mode like AUCTeX in order to speed-up
|
|
insertion of environments and math templates. Inside Org mode, you can
|
|
make use of some of the features of CDLaTeX mode. You need to
|
|
install {{{file(cdlatex.el)}}} and {{{file(texmathp.el)}}} (the latter
|
|
comes also with AUCTeX) from
|
|
[[http://www.astro.uva.nl/~dominik/Tools/cdlatex]]. Don't use CDLaTeX
|
|
mode itself under Org mode, but use the light version
|
|
~org-cdlatex-mode~ that comes as part of Org mode. Turn it on for the
|
|
current buffer with ~M-x org-cdlatex-mode~, or for all Org files with
|
|
this hook:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(add-hook 'org-mode-hook 'turn-on-org-cdlatex)
|
|
#+end_src
|
|
|
|
When this mode is enabled, the following features are present (for more
|
|
details see the documentation of CDLaTeX mode):
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c {)}}} ::
|
|
#+kindex: C-c @{
|
|
|
|
Insert an environment template.
|
|
|
|
- {{{key(TAB)}}} ::
|
|
#+kindex: @key{TAB}
|
|
|
|
Expand a template if the cursor is inside a LaTeX fragment.[fn:112]
|
|
For example, {{{key(TAB)}}} will expand ~fr~ to ~\frac{}{}~ and
|
|
position the cursor correctly inside the first brace. Another
|
|
{{{key(TAB)}}} will get you into the second brace. Even outside
|
|
fragments, {{{key(TAB)}}} will expand environment abbreviations at the
|
|
beginning of a line. For example, if you write {{{samp(equ)}}} at the
|
|
beginning of a line and press {{{key(TAB)}}}, this abbreviation will
|
|
be expanded to an ~equation~ environment. To get a list of all
|
|
abbreviations, type {{{kbd(M-x cdlatex-command-help)}}}.
|
|
|
|
- {{{kbd(_)}}} {{{kbd(^)}}} ::
|
|
#+kindex: _
|
|
#+kindex: ^
|
|
#+vindex: cdlatex-simplify-sub-super-scripts
|
|
|
|
Pressing {{{kbd(_)}}} and {{{kbd(^)}}} inside a LaTeX fragment will
|
|
insert these characters together with a pair of braces. If you use
|
|
{{{key(TAB)}}} to move out of the braces, and if the braces surround
|
|
only a single character or macro, they are removed again (depending on
|
|
the variable ~cdlatex-simplify-sub-super-scripts~).
|
|
|
|
- {{{kbd(`)}}} ::
|
|
#+kindex: `
|
|
|
|
Pressing the backquote followed by a character inserts math macros,
|
|
also outside LaTeX fragments. If you wait more than 1.5 seconds
|
|
after the backquote, a help window will pop up.
|
|
|
|
- {{{kbd(')}}} ::
|
|
#+kindex: '
|
|
|
|
Pressing the single-quote followed by another character modifies the
|
|
symbol before point with an accent or a font. If you wait more than
|
|
1.5 seconds after the single-quote, a help window will pop up.
|
|
Character modification will work only inside LaTeX fragments;
|
|
outside the quote is normal.
|
|
|
|
* FIXME Exporting
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Sharing and publishing notes
|
|
:END:
|
|
#+cindex: exporting
|
|
|
|
Org mode documents can be exported into a variety of other formats.
|
|
For printing and sharing of notes, ASCII export produces a readable
|
|
and simple version of an Org file. HTML export allows you to publish a
|
|
notes file on the web, while the XOXO format provides a solid base for
|
|
exchange with a broad range of other applications. LaTeX export
|
|
lets you use Org mode and its structured editing functions to easily
|
|
create LaTeX files. DocBook export makes it possible to convert Org
|
|
files to many other formats using DocBook tools. OpenDocument Text
|
|
(ODT) export allows seamless collaboration across organizational
|
|
boundaries. For project management you can create gantt and resource
|
|
charts by using TaskJuggler export. To incorporate entries with
|
|
associated times like deadlines or appointments into a desktop
|
|
calendar program like iCal, Org mode can also produce extracts in the
|
|
iCalendar format. Currently, Org mode only supports export, not import
|
|
of these different formats.
|
|
|
|
Org supports export of selected regions when ~transient-mark-mode~ is
|
|
enabled (default in Emacs 23).
|
|
|
|
** Selective export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Using tags to select and exclude trees
|
|
:END:
|
|
#+cindex: export, selective by tags or TODO keyword
|
|
#+vindex: org-export-select-tags
|
|
#+vindex: org-export-exclude-tags
|
|
#+cindex: org-export-with-tasks
|
|
|
|
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:
|
|
~org-export-select-tags~ and ~org-export-exclude-tags~,
|
|
respectively defaulting to ~:export:~ and ~:noexport:~.
|
|
|
|
1. Org first checks if any of the /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.
|
|
|
|
2. If none of the select tags is found, the whole buffer will be
|
|
selected for export.
|
|
|
|
3. Finally, all subtrees that are marked by any of the /exclude/ tags
|
|
will be removed from the export buffer.
|
|
|
|
|
|
The variable ~org-export-with-tasks~ can be configured to select which
|
|
kind of tasks should be included for export. See the docstring of the
|
|
variable for more information.
|
|
|
|
** FIXME Export options
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Per-file export settings
|
|
:END:
|
|
#+cindex: options, for export
|
|
#+cindex: completion, of option keywords
|
|
|
|
The exporter recognizes special lines in the buffer which provide
|
|
additional information. These lines may be put anywhere in the file.
|
|
The whole set of lines can be inserted into the buffer with
|
|
{{{kbd(C-c C-e t)}}}. For individual lines, a good way to make sure the keyword
|
|
is correct is to type {{{samp(#+)}}} and then use {{{kbdkey(M-,TAB)}}}
|
|
completion (see [[Completion]]). For a summary of other in-buffer settings
|
|
not specifically related to export, see [[In-buffer settings]]. In
|
|
particular, note that you can place commonly-used (export) options in
|
|
a separate file which can be included using ~#+SETUPFILE~.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e t)}}}, ~org-insert-export-options-template~ ::
|
|
#+kindex: C-c C-e t
|
|
|
|
Insert template with export options, see example below.
|
|
|
|
|
|
#+cindex: #+TITLE
|
|
#+cindex: #+AUTHOR
|
|
#+cindex: #+DATE
|
|
#+cindex: #+EMAIL
|
|
#+cindex: #+DESCRIPTION
|
|
#+cindex: #+KEYWORDS
|
|
#+cindex: #+LANGUAGE
|
|
#+cindex: #+TEXT
|
|
#+cindex: #+OPTIONS
|
|
#+cindex: #+BIND
|
|
#+cindex: #+LINK_UP
|
|
#+cindex: #+LINK_HOME
|
|
#+cindex: #+EXPORT_SELECT_TAGS
|
|
#+cindex: #+EXPORT_EXCLUDE_TAGS
|
|
#+cindex: #+XSLT
|
|
#+cindex: #+LaTeX_HEADER
|
|
#+vindex: user-full-name
|
|
#+vindex: user-mail-address
|
|
#+vindex: org-export-default-language
|
|
#+vindex: org-export-date-timestamp-format
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- #+TITLE: ::
|
|
|
|
The title to be shown (default is the buffer name).
|
|
|
|
- #+AUTHOR: ::
|
|
|
|
The author (default taken from ~user-full-name~).
|
|
|
|
- #+DATE: ::
|
|
|
|
A date, an Org timestamp, or a format string for ~format-time-string~.[fn:113]
|
|
|
|
- #+EMAIL: ::
|
|
|
|
His/her email address (default from ~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., en (~org-export-default-language~).
|
|
|
|
- #+TEXT: ::
|
|
|
|
Some descriptive text to be inserted at the beginning.
|
|
|
|
- #+TEXT: ::
|
|
|
|
Several lines may be given.
|
|
|
|
- #+OPTIONS: ::
|
|
|
|
H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
|
|
|
|
- #+BIND: ::
|
|
|
|
Lisp-var lisp-val, e.g., org-export-latex-low-levels itemize. You need
|
|
to confirm using these, or configure ~org-export-allow-BIND~.
|
|
|
|
- #+LINK_UP: ::
|
|
|
|
The ``up'' link of an exported page.
|
|
|
|
- #+LINK_HOME: ::
|
|
|
|
The ``home'' link of an exported page.
|
|
|
|
- #+LaTeX_HEADER: ::
|
|
|
|
Extra line(s) for the LaTeX header, like ~\usepackage{xyz}~.
|
|
|
|
- #+EXPORT_SELECT_TAGS: ::
|
|
|
|
Tags that select a tree for export.
|
|
|
|
- #+EXPORT_EXCLUDE_TAGS: ::
|
|
|
|
Tags that exclude a tree from export.
|
|
|
|
- #+XSLT: ::
|
|
|
|
The XSLT stylesheet used by DocBook exporter to generate FO file.
|
|
|
|
|
|
|
|
{{{noindent}}} The ~#+OPTIONS~ line is a compact form to specify
|
|
export settings.[fn:114] Here you can:
|
|
|
|
#+cindex: headline levels
|
|
#+cindex: section-numbers
|
|
#+cindex: table of contents
|
|
#+cindex: line-break preservation
|
|
#+cindex: quoted HTML tags
|
|
#+cindex: fixed-width sections
|
|
#+cindex: tables
|
|
#+cindex: @TeX{}-like syntax for sub- and superscripts
|
|
#+cindex: footnotes
|
|
#+cindex: special strings
|
|
#+cindex: emphasized text
|
|
#+cindex: @TeX{} macros
|
|
#+cindex: @LaTeX{} fragments
|
|
#+cindex: author info, in export
|
|
#+cindex: time info, in export
|
|
#+vindex: org-export-plist-vars
|
|
#+vindex: org-export-author-info
|
|
#+vindex: org-export-creator-info
|
|
#+vindex: org-export-email-info
|
|
#+vindex: org-export-time-stamp-file
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- H: ::
|
|
|
|
Set the number of headline levels for export.
|
|
|
|
- num: ::
|
|
|
|
Turn on/off section-numbers.
|
|
|
|
- toc: ::
|
|
|
|
Turn on/off table of contents, or set level limit (integer).
|
|
|
|
- \n: ::
|
|
|
|
Turn on/off line-break-preservation (DOES NOT WORK).
|
|
|
|
- @: ::
|
|
|
|
Turn on/off quoted HTML tags.
|
|
|
|
- :: ::
|
|
|
|
Turn on/off fixed-width sections.
|
|
|
|
- |: ::
|
|
|
|
Turn on/off tables,
|
|
|
|
- ^: ::
|
|
|
|
Turn on/off TeX-like syntax for sub- and superscripts. If you write
|
|
"^:{}", ~a_{b}~ will be interpreted, but the simple ~a_b~ will be left
|
|
as it is.
|
|
|
|
- : ::
|
|
|
|
Turn on/off conversion of special strings.
|
|
|
|
- f: ::
|
|
|
|
Turn on/off footnotes like this: ~[1]~.
|
|
|
|
- todo: ::
|
|
|
|
Turn on/off inclusion of TODO keywords into exported text.
|
|
|
|
- tasks: ::
|
|
|
|
Turn on/off inclusion of tasks (TODO items), can be nil to remove all
|
|
tasks, ~todo~ to remove DONE tasks, or list of keywords to keep.
|
|
|
|
- pri: ::
|
|
|
|
Turn on/off priority cookies.
|
|
|
|
- tags: ::
|
|
|
|
Turn on/off inclusion of tags, may also be ~not-in-toc~.
|
|
|
|
- <: ::
|
|
|
|
Turn on/off inclusion of any time/date stamps like DEADLINES.
|
|
|
|
- *: ::
|
|
|
|
Turn on/off emphasized text (bold, italic, underlined).
|
|
|
|
- TeX: ::
|
|
|
|
Turn on/off simple TeX macros in plain text.
|
|
|
|
- LaTeX: ::
|
|
|
|
Configure export of LaTeX fragments. Default ~auto~.
|
|
|
|
- skip: ::
|
|
|
|
Turn on/off skipping the text before the first heading.
|
|
|
|
- author: ::
|
|
|
|
Turn on/off inclusion of author name/email into exported file.
|
|
|
|
- email: ::
|
|
|
|
Turn on/off inclusion of author email into exported file.
|
|
|
|
- creator: ::
|
|
|
|
Turn on/off inclusion of creator info into exported file.
|
|
|
|
- timestamp: ::
|
|
|
|
Turn on/off inclusion creation time into exported file.
|
|
|
|
- d: ::
|
|
|
|
Turn on/off inclusion of drawers, or list drawers to include.
|
|
|
|
|
|
{{{noindent}}} These options take effect in both the HTML and LaTeX
|
|
export, except for ~TeX~ and ~LaTeX~ options, which are respectively
|
|
~t~ and ~nil~ for the LaTeX export.
|
|
|
|
The default values for these and many other options are given by a set
|
|
of variables. For a list of such variables, the corresponding OPTIONS
|
|
keys and also the publishing keys (see [[Project alist]]), see the
|
|
constant ~org-export-plist-vars~.
|
|
|
|
When exporting only a single subtree by selecting it with
|
|
{{{kbd(C-c @)}}} before calling an export command, the subtree can
|
|
overrule some of the file's export settings with properties
|
|
~EXPORT_FILE_NAME~, ~EXPORT_TITLE~, ~EXPORT_TEXT~, ~EXPORT_AUTHOR~,
|
|
~EXPORT_DATE~, and ~EXPORT_OPTIONS~.
|
|
|
|
** The export dispatcher
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to access exporter commands
|
|
:END:
|
|
#+cindex: dispatcher, for export commands
|
|
|
|
All export commands can be reached using the export dispatcher, which
|
|
is a prefix key that prompts for an additional key specifying the
|
|
command. Normally the entire file is exported, but if there is an
|
|
active region that contains one outline tree, the first heading is
|
|
used as document title and the subtrees are exported.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e)}}}, ~org-export~ ::
|
|
#+kindex: C-c C-e
|
|
#+vindex: org-export-run-in-background
|
|
|
|
Dispatcher for export and publishing commands. Displays a help-window
|
|
listing the additional key(s) needed to launch an export or publishing
|
|
command. The prefix arg is passed through to the exporter. A double
|
|
prefix {{{kbd(C-u C-u)}}} causes most commands to be executed in the
|
|
background, in a separate Emacs process.[fn:115]
|
|
|
|
- {{{kbd(C-c C-e v)}}}, ~org-export-visible~ ::
|
|
#+kindex: C-c C-e v
|
|
|
|
Like {{{kbd(C-c C-e)}}}, but only export the text that is currently visible
|
|
(i.e., not hidden by outline visibility).
|
|
|
|
- {{{kbd(C-u C-u C-c C-e)}}}, ~org-export~ ::
|
|
#+kindex: C-u C-u C-c C-e
|
|
#+vindex: org-export-run-in-background
|
|
|
|
Call the exporter, but reverse the setting of ~org-export-run-in-background~, i.e., request background processing if
|
|
not set, or force processing in the current Emacs process if set.
|
|
|
|
** ASCII/Latin-1/UTF-8 export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to flat files with encoding
|
|
:END:
|
|
#+cindex: ASCII export
|
|
#+cindex: Latin-1 export
|
|
#+cindex: UTF-8 export
|
|
|
|
ASCII export produces a simple and very readable version of an Org
|
|
mode file, containing only plain ASCII. Latin-1 and UTF-8 export
|
|
augment the file with special characters and symbols available in
|
|
these encodings.
|
|
|
|
#+cindex: region, active
|
|
#+cindex: active region
|
|
#+cindex: transient-mark-mode
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e a)}}}, ~org-export-as-ascii~ ::
|
|
#+kindex: C-c C-e a
|
|
#+cindex: property, EXPORT_FILE_NAME
|
|
|
|
Export as an ASCII file. For an Org file, {{{file(myfile.org)}}}, the
|
|
ASCII file will be {{{file(myfile.txt)}}}. The file will be
|
|
overwritten without warning. If there is an active region, only the
|
|
region will be exported.[fn:116] If the selected region is a single
|
|
tree, the tree head will become the document title.[fn:117] If the
|
|
tree head entry has or inherits an ~EXPORT_FILE_NAME~ property, that
|
|
name will be used for the export.
|
|
|
|
- {{{kbd(C-c C-e A)}}}, ~org-export-as-ascii-to-buffer~ ::
|
|
#+kindex: C-c C-e A
|
|
|
|
Export to a temporary buffer. Do not create a file.
|
|
|
|
- {{{kbd(C-c C-e n)}}}, ~org-export-as-latin1~ ::
|
|
#+kindex: C-c C-e n
|
|
|
|
Like {{{kbd(C-c C-e a)}}}, but use Latin-1 encoding.
|
|
|
|
- {{{kbd(C-c C-e N)}}}, ~org-export-as-latin1-to-buffer~ ::
|
|
#+kindex: C-c C-e N
|
|
|
|
Like {{{kbd(C-c C-e A)}}}, but use Latin-1 encoding.
|
|
|
|
- {{{kbd(C-c C-e u)}}}, ~org-export-as-utf8~ ::
|
|
#+kindex: C-c C-e u
|
|
|
|
Like {{{kbd(C-c C-e a)}}}, but use UTF-8 encoding.
|
|
|
|
- {{{kbd(C-c C-e U)}}}, ~org-export-as-utf8-to-buffer~ ::
|
|
#+kindex: C-c C-e U
|
|
|
|
Like {{{kbd(C-c C-e A)}}}, but use UTF-8 encoding.
|
|
|
|
|
|
- {{{kbd(C-c C-e v a/n/u)}}} ::
|
|
#+kindex: C-c C-e v a
|
|
#+kindex: C-c C-e v n
|
|
#+kindex: C-c C-e v u
|
|
|
|
Export only the visible part of the document.
|
|
|
|
|
|
#+cindex: headline levels, for exporting
|
|
|
|
In the exported version, the first 3 outline levels will become
|
|
headlines, defining a general document structure. Additional levels
|
|
will be exported as itemized lists. If you want that transition to
|
|
occur at a different level, specify it with a prefix argument, e.g.:
|
|
|
|
#+begin_example
|
|
C-1 C-c C-e a
|
|
#+end_example
|
|
|
|
{{{noindent}}} This setting creates only top level headlines and
|
|
exports the rest as items. When headlines are converted to items, the
|
|
indentation of the text following the headline is changed to fit
|
|
nicely under the item. This is done with the assumption that the first
|
|
body line indicates the base indentation of the body text. Any
|
|
indentation larger than this is adjusted to preserve the layout
|
|
relative to the first line. Should there be lines with less
|
|
indentation than the first one, these are left alone.
|
|
|
|
#+vindex: org-export-ascii-links-to-notes
|
|
|
|
Links will be exported in a footnote-like style, with the descriptive
|
|
part in the text and the link in a note before the next heading. See
|
|
the variable ~org-export-ascii-links-to-notes~ for details and other
|
|
options.
|
|
|
|
** HTML export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to HTML
|
|
:END:
|
|
#+cindex: HTML export
|
|
#+cindex: Gruber, John
|
|
|
|
Org mode contains a HTML (XHTML 1.0 strict) exporter with extensive
|
|
HTML formatting, in ways similar to John Gruber's /markdown/ language,
|
|
but with additional support for tables.
|
|
|
|
*** HTML export commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to invoke HTML export
|
|
:END:
|
|
#+cindex: region, active
|
|
#+cindex: active region
|
|
#+cindex: transient-mark-mode
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e h)}}}, ~org-export-as-html~ ::
|
|
#+kindex: C-c C-e h
|
|
#+cindex: property, EXPORT_FILE_NAME
|
|
|
|
Export as an HTML file. For an Org file {{{file(myfile.org)}}}, the
|
|
HTML file will be {{{file(myfile.html)}}}. The file will be
|
|
overwritten without warning. If there is an active region, only the
|
|
active region will be exported.[fn:118] If the selected region is a
|
|
single tree, the tree head will become the document title.[fn:119] If
|
|
the tree head entry has, or inherits, an ~EXPORT_FILE_NAME~ property,
|
|
that name will be used for the export.
|
|
|
|
- {{{kbd(C-c C-e b)}}}, ~org-export-as-html-and-open~ ::
|
|
#+kindex: C-c C-e b
|
|
|
|
Export as a HTML file and immediately open it with a browser.
|
|
|
|
- {{{kbd(C-c C-e H)}}}, ~org-export-as-html-to-buffer~ ::
|
|
#+kindex: C-c C-e H
|
|
|
|
Export to a temporary buffer. Do not create a file.
|
|
|
|
- {{{kbd(C-c C-e R)}}}, ~org-export-region-as-html~ ::
|
|
#+kindex: C-c C-e R
|
|
|
|
Export the active region to a temporary buffer. With a prefix
|
|
argument, do not produce the file header and footer, but just the
|
|
plain HTML section for the region. This is good for cut-and-paste
|
|
operations.
|
|
|
|
- {{{kbd(C-c C-e v h/b/H/R)}}} ::
|
|
#+kindex: C-c C-e v h
|
|
#+kindex: C-c C-e v b
|
|
#+kindex: C-c C-e v H
|
|
#+kindex: C-c C-e v R
|
|
|
|
Export only the visible part of the document.
|
|
|
|
- {{{kbd(M-x org-export-region-as-html)}}} ::
|
|
|
|
Convert the region to HTML under the assumption that it was in Org
|
|
mode syntax before. This is a global command that can be invoked in
|
|
any buffer.
|
|
|
|
- {{{kbd(M-x org-replace-region-by-HTML)}}} ::
|
|
|
|
Replace the active region (assumed to be in Org mode syntax) by HTML
|
|
code.
|
|
|
|
|
|
#+cindex: headline levels, for exporting
|
|
|
|
In the exported version, the first three outline levels will become
|
|
headlines, defining a general document structure. Additional levels
|
|
will be exported as itemized lists. If you want that transition to
|
|
occur at a different level, specify it with a numeric prefix argument,
|
|
e.g.:
|
|
|
|
#+begin_example
|
|
C-2 C-c C-e b
|
|
#+end_example
|
|
|
|
{{{noindent}}} This setting creates two levels of headings and exports
|
|
the rest as list items.
|
|
|
|
*** HTML preamble and postamble
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to insert a preamble and postamble
|
|
:END:
|
|
#+vindex: org-export-html-preamble
|
|
#+vindex: org-export-html-postamble
|
|
#+vindex: org-export-html-preamble-format
|
|
#+vindex: org-export-html-postamble-format
|
|
#+vindex: org-export-html-validation-link
|
|
#+vindex: org-export-author-info
|
|
#+vindex: org-export-email-info
|
|
#+vindex: org-export-creator-info
|
|
#+vindex: org-export-time-stamp-file
|
|
|
|
The HTML exporter lets you define a preamble and a postamble.
|
|
|
|
The default value for ~org-export-html-preamble~ is ~t~, which means
|
|
that the preamble is inserted depending on the relevant format string
|
|
in ~org-export-html-preamble-format~.
|
|
|
|
Setting ~org-export-html-preamble~ to a string will override the default
|
|
format string. Setting it to a function, will insert the output of the
|
|
function, which must be a string; such a function takes no argument but you
|
|
can check against the value of ~opt-plist~, which contains the list of
|
|
publishing properties for the current file. Setting to ~nil~ will not
|
|
insert any preamble.
|
|
|
|
The default value for ~org-export-html-postamble~ is
|
|
{{{samp('auto)}}}, which means that the HTML exporter will look for
|
|
the value of ~org-export-author-info~, ~org-export-email-info~,
|
|
~org-export-creator-info~ and ~org-export-time-stamp-file~,
|
|
~org-export-html-validation-link~ and build the postamble from these
|
|
values. Setting ~org-export-html-postamble~ to ~t~ will insert the
|
|
postamble from the relevant format string found in
|
|
~org-export-html-postamble-format~. Setting it to ~nil~ will not
|
|
insert any postamble.
|
|
|
|
*** Quoting HTML tags
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Using direct HTML in Org mode
|
|
:END:
|
|
|
|
Plain ~<~ and {{{samp(>)}}} are always transformed to
|
|
{{{samp(<)}}} and {{{samp(>)}}} in HTML export. If you want to
|
|
include simple HTML tags which should be interpreted as such, mark
|
|
them with {{{samp(@)}}} as in {{{samp(@<b>bold text@</b>)}}}. Note
|
|
that this really works only for simple tags. For more extensive HTML
|
|
that should be copied verbatim to the exported file use either ~#+HTML~:
|
|
|
|
#+cindex: #+HTML
|
|
#+cindex: #+BEGIN_HTML
|
|
#+begin_example
|
|
,#+HTML: Literal HTML code for export
|
|
#+end_example
|
|
|
|
{{{noindent}}} or an HTML block:
|
|
#+cindex: #+BEGIN_HTML
|
|
|
|
#+begin_example
|
|
#+BEGIN_HTML
|
|
All lines between these markers are exported literally
|
|
#+END_HTML
|
|
#+end_example
|
|
|
|
*** Links in HTML export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How links will be interpreted and formatted
|
|
:END:
|
|
#+cindex: links, in HTML export
|
|
#+cindex: internal links, in HTML export
|
|
#+cindex: external links, in HTML export
|
|
|
|
Internal links (see [[Internal links]]) will continue to work in HTML.
|
|
This includes automatic links created by radio targets (see [[Radio
|
|
targets]]). Links to external files will still work if the target file
|
|
is on the same /relative/ path as the published Org file. Links to
|
|
other {{{file(.org)}}} files will be translated into HTML links under
|
|
the assumption that a HTML version also exists of the linked file, at
|
|
the same relative path. ~id:~ links can then be used to jump
|
|
to specific entries across files. For information related to linking
|
|
files while publishing them to a publishing directory see [[Publishing
|
|
links]].
|
|
|
|
If you want to specify attributes for links, you can do so using a
|
|
special ~#+ATTR_HTML~ line to define attributes that will be added to
|
|
the ~<a>~ or ~<img>~ tags. Here is an example that sets ~title~ and
|
|
~style~ attributes for a link:
|
|
|
|
#+cindex: #+ATTR_HTML
|
|
#+begin_example
|
|
,#+ATTR_HTML: title="The Org mode homepage" style="color:red;"
|
|
,[[http://orgmode.org]]
|
|
#+end_example
|
|
|
|
*** Tables in HTML export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to modify the formatting of tables
|
|
:END:
|
|
#+cindex: tables, in HTML
|
|
#+vindex: org-export-html-table-tag
|
|
|
|
Org mode tables are exported to HTML using the table tag defined in
|
|
~org-export-html-table-tag~. The default setting makes tables without
|
|
cell borders and frame. If you would like to change this for
|
|
individual tables, place something like the following before the
|
|
table:
|
|
|
|
#+cindex: #+CAPTION
|
|
#+cindex: #+ATTR_HTML
|
|
#+begin_example
|
|
,#+CAPTION: This is a table with lines around and between cells
|
|
,#+ATTR_HTML: border="2" rules="all" frame="border"
|
|
#+end_example
|
|
|
|
*** Images in HTML export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to insert figures into HTML output
|
|
:END:
|
|
#+cindex: images, inline in HTML
|
|
#+cindex: inlining images in HTML
|
|
#+vindex: org-export-html-inline-images
|
|
|
|
HTML export can inline images given as links in the Org file, and it
|
|
can make an image the clickable part of a link. By default, images are
|
|
inlined if a link does not have a description.[fn:120] So
|
|
~[[file:myimg.jpg]]~ will be inlined, while ~[[file:myimg.jpg][the
|
|
image]]~ will just produce a link {{{samp(the image)}}} that points to
|
|
the image. If the description part itself is a ~file:~ link or
|
|
a ~http:~ URL pointing to an image, this image will be inlined and
|
|
activated so that clicking on the image will activate the link. For
|
|
example, to include a thumbnail that will link to a high resolution
|
|
version of the image, you could use:
|
|
|
|
#+begin_example
|
|
[[file:highres.jpg][file:thumb.jpg]]
|
|
#+end_example
|
|
|
|
If you need to add attributes to an inlined image, use a ~#+ATTR_HTML~.
|
|
In the example below we specify the ~alt~ and ~title~ attributes to
|
|
support text viewers and accessibility, and align it to the right.
|
|
|
|
#+cindex: #+CAPTION
|
|
#+cindex: #+ATTR_HTML
|
|
#+begin_example
|
|
,#+CAPTION: A black cat stalking a spider
|
|
,#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"
|
|
[[./img/a.jpg]]
|
|
#+end_example
|
|
|
|
{{{noindent}}} You could use ~http~ addresses just as well.
|
|
|
|
*** Math formatting in HTML export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Beautiful math also on the web
|
|
:END:
|
|
#+cindex: MathJax
|
|
#+cindex: dvipng
|
|
|
|
LaTeX math snippets (see [[LaTeX fragments]]) can be displayed in two
|
|
different ways on HTML pages. The default is to use the [[http://www.mathjax.org][MathJax system]]
|
|
which should work out of the box with Org mode installation because
|
|
~http://orgmode.org~ serves {{{file(MathJax)}}} for Org mode users for
|
|
small applications and for testing purposes.[fn:121] To configure
|
|
{{{file(MathJax)}}}, use the variable
|
|
~org-export-html-mathjax-options~ or insert something like the
|
|
following into the buffer:
|
|
|
|
#+begin_example
|
|
,#+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
|
|
#+end_example
|
|
|
|
{{{noindent}}} See the docstring of the variable
|
|
~org-export-html-mathjax-options~ for the meaning of the parameters in
|
|
this line.
|
|
|
|
If you prefer, you can also request that LaTeX fragments are
|
|
processed into small images that will be inserted into the browser
|
|
page. Before the availability of MathJax, this was the default method
|
|
for Org files. This method requires that the {{{file(dvipng)}}}
|
|
program is available on your system. You can still get this processing
|
|
with the following option:
|
|
|
|
#+begin_example
|
|
,#+OPTIONS: LaTeX:dvipng
|
|
#+end_example
|
|
|
|
*** Text areas in HTML export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: An alternate way to show an example
|
|
:END:
|
|
#+cindex: text areas, in HTML
|
|
|
|
An alternative way to publish literal code examples in HTML is to use
|
|
text areas, where the example can even be edited before pasting it
|
|
into an application. It is triggered by a ~-t~ switch at an ~example~
|
|
or ~src~ block. Using this switch disables any options for syntax and
|
|
label highlighting, and line numbering, which may be present. You may
|
|
also use ~-h~ and ~-w~ switches to specify the height and width of the
|
|
text area, which default to the number of lines in the example, and
|
|
80, respectively. For example
|
|
|
|
#+begin_example
|
|
,#+BEGIN_EXAMPLE -t -w 40
|
|
(defun org-xor (a b)
|
|
"Exclusive or."
|
|
(if a (not b) b))
|
|
,#+END_EXAMPLE
|
|
#+end_example
|
|
|
|
*** CSS support
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Changing the appearance of the output
|
|
:END:
|
|
#+cindex: CSS, for HTML export
|
|
#+cindex: HTML export, CSS
|
|
#+vindex: org-export-html-todo-kwd-class-prefix
|
|
#+vindex: org-export-html-tag-class-prefix
|
|
|
|
You can also give style information for the exported file. The HTML
|
|
exporter assigns the following special CSS classes to appropriate
|
|
parts of the document---your style specifications may change these, in
|
|
addition to any of the standard classes like for headlines, tables,
|
|
etc.[fn:122]
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- p.author :: author information, including email
|
|
- p.date :: publishing date
|
|
- p.creator :: creator info, about org mode version
|
|
- .title :: document title
|
|
- .todo :: TODO keywords, all not-done states
|
|
- .done :: the DONE keywords, all states that count as done
|
|
- .WAITING :: each TODO keyword also uses a class named after itself
|
|
- .timestamp :: timestamp
|
|
- .timestamp-kwd :: keyword associated with a timestamp, like SCHEDULED
|
|
- .timestamp-wrapper :: span around keyword plus timestamp
|
|
- .tag :: tag in a headline
|
|
- ._HOME :: each tag uses itself as a class, "@" replaced by "_"
|
|
- .target :: target for links
|
|
- .linenr :: the line number in a code example
|
|
- .code-highlighted :: for highlighting referenced code lines
|
|
- div.outline-N :: div for outline level N (headline plus text))
|
|
- div.outline-text-N :: extra div for text at outline level N
|
|
- .section-number-N :: section number in headlines, different for each level
|
|
- div.figure :: how to format an inlined image
|
|
- pre.src :: formatted source code
|
|
- pre.example :: normal example
|
|
- p.verse :: verse paragraph
|
|
- div.footnotes :: footnote section headline
|
|
- p.footnote :: footnote definition paragraph, containing a footnote
|
|
- .footref :: a footnote reference number (always a <sup>)
|
|
- .footnum :: footnote number in footnote definition (always <sup>)
|
|
|
|
|
|
#+vindex: org-export-html-style-default
|
|
#+vindex: org-export-html-style-include-default
|
|
#+vindex: org-export-html-style
|
|
#+vindex: org-export-html-extra
|
|
#+vindex: org-export-html-style-default
|
|
|
|
Each exported file contains a compact default style that defines these
|
|
classes in a basic way.[fn:123] You may overwrite these
|
|
settings, or add to them by using the variables ~org-export-html-style~
|
|
(for Org-wide settings) and ~org-export-html-style-extra~ (for more
|
|
fine-grained settings, like file-local settings). To set the latter variable
|
|
individually for each file, you can use a ~#+STYLE:~ line:
|
|
|
|
#+cindex: #+STYLE
|
|
#+begin_example
|
|
,#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
|
|
#+end_example
|
|
|
|
{{{noindent}}} For longer style definitions, you can use several such
|
|
lines. You could also directly write a ~<style>~ ~</style>~ section in
|
|
this way, without referring to an external file.
|
|
|
|
In order to add styles to a subtree, use the ~:HTML_CONTAINER_CLASS:~
|
|
property to assign a class to the tree. In order to specify CSS styles
|
|
for a particular headline, you can use the id specified in a
|
|
~:CUSTOM_ID:~ property.
|
|
|
|
# FIXME: More about header and footer styles
|
|
# FIXME: Talk about links and targets.
|
|
|
|
*** JavaScript support
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Info and folding in a web browser
|
|
:END:
|
|
#+cindex: Rose, Sebastian
|
|
|
|
Sebastian Rose has written a JavaScript program especially designed to
|
|
enhance the web viewing experience of HTML files created with Org. This
|
|
program allows you to view large files in two different ways. The first one
|
|
is an /Info/-like mode where each section is displayed separately and
|
|
navigation can be done with the {{{kbd(n)}}} and {{{kbd(p)}}} keys (and some other keys
|
|
as well, press {{{kbd(?)}}} for an overview of the available keys). The second
|
|
view type is a /folding/ view much like Org provides inside Emacs. The
|
|
script is available at [[http://orgmode.org/org-info.js]] and you can find
|
|
the documentation for it at [[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 ~orgmode.org~ and prefer to install a local
|
|
copy on your own web server.
|
|
|
|
To use the script, you need to make sure that the
|
|
{{{file(org-jsinfo.el)}}} module gets loaded. It should be loaded by
|
|
default, but you can try {{{ksksksk(M-x customize-variable,RET,org-modules,RET)}}}
|
|
to convince yourself that this is indeed the case. All it then takes to make use of the program
|
|
is adding a single line to the Org file:
|
|
|
|
#+cindex: #+INFOJS_OPT
|
|
#+begin_example
|
|
,#+INFOJS_OPT: view:info toc:nil
|
|
#+end_example
|
|
|
|
{{{noindent}}} If this line is found, the HTML header will
|
|
automatically contain the code needed to invoke the script. Using the
|
|
line above, you can set the following viewing options:
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- path: ::
|
|
|
|
The path to the script. The default is to grab the script from
|
|
[[http://orgmode.org/org-info.js]], but you might want to have
|
|
a local copy and use a path like {{{samp(../scripts/org-info.js)}}}.
|
|
|
|
- view: ::
|
|
|
|
Initial view when the website is first shown. Possible values are:
|
|
|
|
- info :: Info-like interface with one section per page.
|
|
- overview :: Folding interface, initially showing only top-level.
|
|
- content :: Folding interface, starting with all headlines visible.
|
|
- showall :: Folding interface, all headlines and text visible.
|
|
|
|
- sdepth: ::
|
|
|
|
Maximum headline level that will still become an independent section
|
|
for info and folding modes. The default is taken from ~org-export-headline-levels~ (= the ~H~ switch in ~#+OPTIONS~). If
|
|
this is smaller than in ~org-export-headline-levels~, each
|
|
info/folding section can still contain child headlines.
|
|
|
|
- toc: ::
|
|
|
|
Should the table of contents /initially/ be visible? Even when ~nil~,
|
|
you can always get to the "toc" with {{{kbd(i)}}}.
|
|
|
|
- tdepth: ::
|
|
|
|
The depth of the table of contents. The defaults are taken from the
|
|
variables ~org-export-headline-levels~ and ~org-export-with-toc~.
|
|
|
|
- ftoc: ::
|
|
|
|
Does the CSS of the page specify a fixed position for the "toc"? If
|
|
yes, the toc will never be displayed as a section.
|
|
|
|
- ltoc: ::
|
|
|
|
Should there be short contents (children) in each section? Make this ~above~ if the section should be above initial text.
|
|
|
|
- mouse: ::
|
|
|
|
Headings are highlighted when the mouse is over them. Should be
|
|
{{{samp(underline)}}} (default) or a background color like
|
|
{{{samp(#cccccc)}}}.
|
|
|
|
- buttons: ::
|
|
|
|
Should view-toggle buttons be everywhere? When ~nil~ (the default),
|
|
only one such button will be present.
|
|
|
|
|
|
#+vindex: org-infojs-options
|
|
#+vindex: org-export-html-use-infojs
|
|
|
|
{{{noindent}}} You can choose default values for these options by
|
|
customizing the variable ~org-infojs-options~. If you always want to
|
|
apply the script to your pages, configure the variable
|
|
~org-export-html-use-infojs~.
|
|
|
|
** LaTeX and PDF export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to LaTeX and processing to PDF
|
|
:END:
|
|
#+cindex: @LaTeX{} export
|
|
#+cindex: PDF export
|
|
#+cindex: Guerry, Bastien
|
|
|
|
Org mode contains a LaTeX exporter written by Bastien Guerry. With
|
|
further processing, this backend is also used to produce PDF
|
|
output.[fn:124] Since the LaTeX output uses {{{file(hyperref)}}} to
|
|
implement links and cross references, the PDF output file will be
|
|
fully linked. Beware of the fact that your ~org~ file has to be
|
|
properly structured in order to be correctly exported: respect the
|
|
hierarchy of sections.
|
|
|
|
*** LaTeX/PDF export commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Invoking export to LaTeX/PDF
|
|
:END:
|
|
#+cindex: region, active
|
|
#+cindex: active region
|
|
#+cindex: transient-mark-mode
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e l)}}}, ~org-export-as-latex~ ::
|
|
#+kindex: C-c C-e l
|
|
#+cindex: property EXPORT_FILE_NAME
|
|
|
|
Export as a LaTeX file. For an Org file {{{file(myfile.org)}}}, the
|
|
LaTeX file will be {{{file(myfile.tex)}}}. The file will be
|
|
overwritten without warning. If there is an active region, only the
|
|
active region will be exported.[fn:125] If the selected region is a
|
|
single tree, the tree head will become the document title.[fn:126] If
|
|
the tree head entry has or inherits an ~EXPORT_FILE_NAME~ property,
|
|
that name will be used for the export.
|
|
|
|
- {{{kbd(C-c C-e L)}}}, ~org-export-as-latex-to-buffer~ ::
|
|
#+kindex: C-c C-e L
|
|
|
|
Export to a temporary buffer. Do not create a file.
|
|
|
|
- {{{kbd(C-c C-e v l/L)}}} ::
|
|
|
|
Export only the visible part of the document.
|
|
|
|
- {{{kbd(M-x org-export-region-as-latex)}}} ::
|
|
|
|
Convert the region to LaTeX under the assumption that it was in Org
|
|
mode syntax before. This is a global command that can be invoked in
|
|
any buffer.
|
|
|
|
- {{{kbd(M-x org-replace-region-by-latex)}}} ::
|
|
|
|
Replace the active region (assumed to be in Org mode syntax) by
|
|
LaTeX code.
|
|
|
|
- {{{kbd(C-c C-e p)}}}, ~org-export-as-pdf~ ::
|
|
#+kindex: C-c C-e p
|
|
|
|
Export as LaTeX and then process to PDF.
|
|
|
|
- {{{kbd(C-c C-e d)}}}, ~org-export-as-pdf-and-open~ ::
|
|
#+kindex: C-c C-e d
|
|
|
|
Export as LaTeX and then process to PDF, then open the resulting
|
|
PDF file.
|
|
|
|
|
|
#+cindex: headline levels, for exporting
|
|
#+vindex: org-latex-low-levels
|
|
|
|
In the exported version, the first 3 outline levels will become
|
|
headlines, defining a general document structure. Additional levels
|
|
will be exported as description lists. The exporter can ignore them or
|
|
convert them to a custom string depending on ~org-latex-low-levels~.
|
|
|
|
If you want that transition to occur at a different level, specify it
|
|
with a numeric prefix argument, e.g.:
|
|
|
|
#+begin_example
|
|
C-2 C-c C-e l
|
|
#+end_example
|
|
|
|
{{{noindent}}} The example setting creates two levels of headings and
|
|
exports the rest as list items.
|
|
|
|
*** Header and sectioning
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Setting up the export file structure
|
|
:TITLE: Header and sectioning structure
|
|
:END:
|
|
#+cindex: @LaTeX{} class
|
|
#+cindex: @LaTeX{} sectioning structure
|
|
#+cindex: @LaTeX{} header
|
|
#+cindex: header, for @LaTeX{} files
|
|
#+cindex: sectioning structure, for @LaTeX{} export
|
|
|
|
By default, the LaTeX output uses the class ~article~.
|
|
|
|
#+vindex: org-export-latex-default-class
|
|
#+vindex: org-export-latex-classes
|
|
#+vindex: org-export-latex-default-packages-alist
|
|
#+vindex: org-export-latex-packages-alist
|
|
#+cindex: #+LaTeX_HEADER
|
|
#+cindex: #+LaTeX_CLASS
|
|
#+cindex: #+LaTeX_CLASS_OPTIONS
|
|
#+cindex: property, LaTeX_CLASS
|
|
#+cindex: property, LaTeX_CLASS_OPTIONS
|
|
|
|
You can change this globally by setting a different value for
|
|
~org-export-latex-default-class~ or locally by adding an option like
|
|
~#+LaTeX_CLASS: myclass~ in your file, or with a ~:LaTeX_CLASS:~
|
|
property that applies when exporting a region containing only this
|
|
(sub)tree. The class must be listed in ~org-export-latex-classes~.
|
|
This variable defines a header template for each class, and allows you
|
|
to define the sectioning structure for each class.[fn:127] You can
|
|
also define your own classes there. ~#+LaTeX_CLASS_OPTIONS~ or a
|
|
~:LaTeX_CLASS_OPTIONS:~ property can specify the options for the
|
|
~\documentclass~ macro. The options to documentclass have to be
|
|
provided, as expected by LaTeX, within square brackets. You can
|
|
also use ~#+LaTeX_HEADER: \usepackage{xyz}~ to add lines to the
|
|
header. See the docstring of ~org-export-latex-classes~ for more
|
|
information. An example is shown below.
|
|
|
|
#+begin_example
|
|
,#+LaTeX_CLASS: article
|
|
,#+LaTeX_CLASS_OPTIONS: [a4paper]
|
|
,#+LaTeX_HEADER: \usepackage{xyz}
|
|
|
|
,* Headline 1
|
|
some text
|
|
#+end_example
|
|
|
|
*** Quoting LaTeX code
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Incorporating literal LaTeX code
|
|
:END:
|
|
|
|
Embedded LaTeX as described in [[Embedded LaTeX]], will be correctly
|
|
inserted into the LaTeX file. This includes simple macros like
|
|
~\ref{LABEL}~ to create a cross reference to a figure. Furthermore,
|
|
you can add special code that should only be present in LaTeX export
|
|
with the following constructs:
|
|
|
|
#+cindex: #+LaTeX
|
|
#+cindex: #+BEGIN_LaTeX
|
|
#+begin_example
|
|
,#+LaTeX: Literal LaTeX code for export
|
|
#+end_example
|
|
|
|
{{{noindent}}} or
|
|
|
|
#+cindex: #+BEGIN_LaTeX
|
|
|
|
#+begin_example
|
|
,#+BEGIN_LaTeX
|
|
All lines between these markers are exported literally
|
|
,#+END_LaTeX
|
|
#+end_example
|
|
|
|
*** Tables in LaTeX export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Options for exporting tables to LaTeX
|
|
:END:
|
|
#+cindex: tables, in @LaTeX{} export
|
|
|
|
For LaTeX export of a table, you can specify a label, a caption and
|
|
placement options (see [[Images and tables]]). You can also use the
|
|
~ATTR_LaTeX~ line to request a ~longtable~ environment for the
|
|
table, so that it may span several pages, or to change the default table
|
|
environment from ~table~ to ~table*~ or to change the default inner
|
|
tabular environment to ~tabularx~ or ~tabulary~. Finally, you can
|
|
set the alignment string, and (with ~tabularx~ or ~tabulary~) the
|
|
width:
|
|
|
|
#+cindex: #+CAPTION
|
|
#+cindex: #+LABEL
|
|
#+cindex: #+ATTR_LaTeX
|
|
#+begin_example
|
|
,#+CAPTION: A long table
|
|
,#+LABEL: tbl:long
|
|
,#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l
|
|
| ..... | ..... |
|
|
| ..... | ..... |
|
|
#+end_example
|
|
|
|
or to specify a multicolumn table with ~tabulary~:
|
|
|
|
#+cindex: #+CAPTION
|
|
#+cindex: #+LABEL
|
|
#+cindex: #+ATTR_LaTeX
|
|
#+begin_example
|
|
,#+CAPTION: A wide table with tabulary
|
|
,#+LABEL: tbl:wide
|
|
,#+ATTR_LaTeX: table* tabulary width=\textwidth
|
|
| ..... | ..... |
|
|
| ..... | ..... |
|
|
#+end_example
|
|
|
|
*** Images in LaTeX export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to insert figures into LaTeX output
|
|
:END:
|
|
#+cindex: images, inline in LaTeX
|
|
#+cindex: inlining images in LaTeX
|
|
|
|
Images that are linked to without a description part in the link, like
|
|
~[[file:img.jpg]]~ or ~[[./img.jpg]]~ will be inserted into the PDF
|
|
output file resulting from LaTeX processing. Org will use an
|
|
~\includegraphics~ macro to insert the image. If you have specified
|
|
a caption and/or a label as described in [[Images and tables]], the
|
|
figure will be wrapped into a ~figure~ environment and thus become
|
|
a floating element. You can use an ~#+ATTR_LaTeX:~ line to specify
|
|
various other options. You can ask org to export an image as a float
|
|
without specifying a label or a caption by using the keyword ~float~
|
|
in this line. Various optional arguments to the ~\includegraphics~
|
|
macro can also be specified in this fashion. To modify the placement
|
|
option of the floating environment, add something like
|
|
{{{samp(placement=[h!])}}} to the attributes. It is to be noted this
|
|
option can be used with tables as well.[fn:128]
|
|
|
|
If you would like to let text flow around the image, add the word
|
|
{{{samp(wrap)}}} to the ~#+ATTR_LaTeX:~ line, which will make the
|
|
figure occupy the left half of the page. To fine-tune, the ~placement~
|
|
field will be the set of additional arguments needed by the
|
|
~wrapfigure~ environment. Note that if you change the size of the
|
|
image, you need to use compatible settings for ~\includegraphics~ and
|
|
~wrapfigure~.
|
|
|
|
#+cindex: #+CAPTION
|
|
#+cindex: #+LABEL
|
|
#+cindex: #+ATTR_LaTeX
|
|
#+begin_example
|
|
,#+CAPTION: The black-body emission of the disk around HR 4049
|
|
,#+LABEL: fig:SED-HR4049
|
|
,#+ATTR_LaTeX: width=5cm,angle=90
|
|
[[./img/sed-hr4049.pdf]]
|
|
|
|
,#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@}
|
|
[[./img/hst.png]]
|
|
#+end_example
|
|
|
|
If you wish to include an image which spans multiple columns in a page, you
|
|
can use the keyword ~multicolumn~ in the ~#+ATTR_LaTeX~ line. This
|
|
will export the image wrapped in a ~figure*~ environment.
|
|
|
|
If you need references to a label created in this way, write
|
|
~\ref{fig:SED-HR4049}~ just like in LaTeX.
|
|
|
|
*** Beamer class export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Turning the file into a presentation
|
|
:END:
|
|
|
|
The LaTeX class {{{file(beamer)}}} allows production of high
|
|
quality presentations using LaTeX and pdf processing. Org mode has
|
|
special support for turning an Org mode file or tree into a
|
|
{{{file(beamer)}}} presentation.
|
|
|
|
When the LaTeX class for the current buffer (as set with ~#+LaTeX_CLASS:
|
|
beamer~) or subtree (set with a ~LaTeX_CLASS~ property) is
|
|
~beamer~, a special export mode will turn the file or tree into a beamer
|
|
presentation. Any tree with not-too-deep level nesting should in principle be
|
|
exportable as a beamer presentation. By default, the top-level entries (or
|
|
the first level below the selected subtree heading) will be turned into
|
|
frames, and the outline structure below this level will become itemize lists.
|
|
You can also configure the variable ~org-beamer-frame-level~ to a
|
|
different level---then the hierarchy above frames will produce the sectioning
|
|
structure of the presentation.
|
|
|
|
A template for useful in-buffer settings or properties can be inserted
|
|
into the buffer with
|
|
{{{kbd(M-x org-insert-beamer-options-template)}}}. Among other things, this will
|
|
install a column view format which is very handy for editing special
|
|
properties used by beamer.
|
|
|
|
You can influence the structure of the presentation using the following
|
|
properties:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~BEAMER_env~ ::
|
|
|
|
The environment that should be used to format this entry. Valid
|
|
environments are defined in the constant ~org-beamer-environments-default~, and you can define more in ~org-beamer-environments-extra~. If this property is set, the entry
|
|
will also get a ~:B_environment:~ tag to make this visible. This tag
|
|
has no semantic meaning, it is only a visual aid.
|
|
|
|
- ~BEAMER_envargs~ ::
|
|
|
|
The beamer-special arguments that should be used for the environment,
|
|
like ~[t]~ or ~[<+->]~ of ~<2-3>~. If the ~BEAMER_col~ property is
|
|
also set, something like ~C[t]~ can be added here as well to set an
|
|
options argument for the implied ~columns~ environment. ~c[t]~ or ~c<2->~ will set an options for the implied ~column~ environment.
|
|
|
|
- ~BEAMER_col~ ::
|
|
|
|
The width of a column that should start with this entry. If this
|
|
property is set, the entry will also get a ~:BMCOL:~ property to make
|
|
this visible. Also this tag is only a visual aid. When this is a plain
|
|
number, it will be interpreted as a fraction of ~\textwidth~.
|
|
Otherwise it will be assumed that you have specified the units, like
|
|
{{{samp(3cm)}}}. The first such property in a frame will start a ~columns~ environment to surround the columns. This environment is
|
|
closed when an entry has a ~BEAMER_col~ property with value 0 or 1, or
|
|
automatically at the end of the frame.
|
|
|
|
- ~BEAMER_extra~ ::
|
|
|
|
Additional commands that should be inserted after the environment has
|
|
been opened. For example, when creating a frame, this can be used to
|
|
specify transitions.
|
|
|
|
|
|
Frames will automatically receive a ~fragile~ option if they contain
|
|
source code that uses the verbatim environment. Special {{{file(beamer)}}}
|
|
specific code can be inserted using ~#+BEAMER:~ and
|
|
~#+BEGIN_BEAMER~ ... ~#+END_BEAMER~ constructs, similar to other export
|
|
backends, but with the difference that ~#+LaTeX:~ stuff will be included
|
|
in the presentation as well.
|
|
|
|
Outline nodes with ~BEAMER_env~ property value {{{samp(note)}}} or
|
|
{{{samp(noteNH)}}} will be formatted as beamer notes, i,e, they will be wrapped
|
|
into ~\note{...}~. The former will include the heading as part of the
|
|
note text, the latter will ignore the heading of that node. To simplify note
|
|
generation, it is actually enough to mark the note with a /tag/ (either
|
|
~:B_note:~ or ~:B_noteNH:~) instead of creating the
|
|
~BEAMER_env~ property.
|
|
|
|
You can turn on a special minor mode ~org-beamer-mode~ for editing
|
|
support with the following line:
|
|
|
|
#+begin_example
|
|
,#+STARTUP: beamer
|
|
#+end_example
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-b)}}}, ~org-beamer-select-environment~ ::
|
|
#+kindex: C-c C-b
|
|
|
|
In ~org-beamer-mode~, this key offers fast selection of a beamer
|
|
environment or the ~BEAMER_col~ property.
|
|
|
|
|
|
Column view provides a great way to set the environment of a node and
|
|
other important parameters. Make sure you are using a COLUMN format
|
|
that is geared toward this special purpose. The command
|
|
{{{kbd(M-x org-insert-beamer-options-template)}}} defines such a format.
|
|
|
|
Here is a simple example Org document that is intended for beamer export.
|
|
|
|
#+begin_example
|
|
,#+LaTeX_CLASS: beamer
|
|
,#+TITLE: Example Presentation
|
|
,#+AUTHOR: Carsten Dominik
|
|
,#+LaTeX_CLASS_OPTIONS: [presentation]
|
|
,#+BEAMER_FRAME_LEVEL: 2
|
|
,#+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@}
|
|
,#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex)
|
|
|
|
,* This is the first structural section
|
|
|
|
,** Frame 1 \\ with a subtitle
|
|
,*** Thanks to Eric Fraga :BMCOL:B_block:
|
|
:PROPERTIES:
|
|
:BEAMER_env: block
|
|
:BEAMER_envargs: C[t]
|
|
:BEAMER_col: 0.5
|
|
:END:
|
|
for the first viable beamer setup in Org
|
|
,*** Thanks to everyone else :BMCOL:B_block:
|
|
:PROPERTIES:
|
|
:BEAMER_col: 0.5
|
|
:BEAMER_env: block
|
|
:BEAMER_envargs: <2->
|
|
:END:
|
|
for contributing to the discussion
|
|
,**** This will be formatted as a beamer note :B_note:
|
|
,** Frame 2 \\ where we will not use columns
|
|
,*** Request :B_block:
|
|
Please test this stuff!
|
|
:PROPERTIES:
|
|
:BEAMER_env: block
|
|
:END:
|
|
#+end_example
|
|
|
|
For more information, see the documentation on Worg.
|
|
|
|
** DocBook export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to DocBook
|
|
:END:
|
|
#+cindex: DocBook export
|
|
#+cindex: PDF export
|
|
#+cindex: Cui, Baoqiu
|
|
|
|
Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is
|
|
exported to DocBook format, it can be further processed to produce other
|
|
formats, including PDF, HTML, man pages, etc., using many available DocBook
|
|
tools and stylesheets.
|
|
|
|
Currently DocBook exporter only supports DocBook V5.0.
|
|
|
|
*** DocBook export commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to invoke DocBook export
|
|
:END:
|
|
#+cindex: region, active
|
|
#+cindex: active region
|
|
#+cindex: transient-mark-mode
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e D)}}}, ~org-export-as-docbook~ ::
|
|
#+kindex: C-c C-e D
|
|
#+cindex: property EXPORT_FILE_NAME
|
|
|
|
Export as a DocBook file. For an Org file, {{{file(myfile.org)}}}, the
|
|
DocBook XML file will be {{{file(myfile.xml)}}}. The file will be
|
|
overwritten without warning. If there is an active region, only the
|
|
region will be exported.[fn:129] If the selected region is a single
|
|
tree, the tree head will become the document title.[fn:130] If the
|
|
tree head entry has, or inherits, an ~EXPORT_FILE_NAME~ property, that
|
|
name will be used for the export.
|
|
|
|
- {{{kbd(C-c C-e V)}}}, ~org-export-as-docbook-pdf-and-open~ ::
|
|
#+kindex: C-c C-e V
|
|
|
|
Export as a DocBook file, process to PDF, then open the resulting PDF
|
|
file.
|
|
|
|
#+vindex: org-export-docbook-xslt-proc-command
|
|
#+vindex: org-export-docbook-xsl-fo-proc-command
|
|
|
|
Note that, in order to produce PDF output based on an exported DocBook
|
|
file, you need to have XSLT processor and XSL-FO processor software
|
|
installed on your system. Check variables ~org-export-docbook-xslt-proc-command~ and ~org-export-docbook-xsl-fo-proc-command~.
|
|
|
|
#+vindex: org-export-docbook-xslt-stylesheet
|
|
|
|
The stylesheet argument ~%s~ in variable ~org-export-docbook-xslt-proc-command~ is replaced by the value of
|
|
variable ~org-export-docbook-xslt-stylesheet~, which needs to be set by
|
|
the user. You can also overrule this global setting on a per-file basis by
|
|
adding an in-buffer setting ~#+XSLT:~ to the Org file.
|
|
|
|
- {{{kbd(C-c C-e v D)}}} ::
|
|
#+kindex: C-c C-e v D
|
|
|
|
Export only the visible part of the document.
|
|
|
|
*** Quoting DocBook code
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Incorporating DocBook code in Org files
|
|
:END:
|
|
You can quote DocBook code in Org files and copy it verbatim into exported
|
|
DocBook file with the following constructs:
|
|
|
|
#+cindex: #+DOCBOOK
|
|
#+cindex: #+BEGIN_DOCBOOK
|
|
#+begin_example
|
|
,#+DOCBOOK: Literal DocBook code for export
|
|
#+end_example
|
|
|
|
{{{noindent}}} or
|
|
#+cindex: #+BEGIN_DOCBOOK
|
|
|
|
#+begin_example
|
|
,#+BEGIN_DOCBOOK
|
|
All lines between these markers are exported by DocBook exporter
|
|
literally.
|
|
,#+END_DOCBOOK
|
|
#+end_example
|
|
|
|
For example, you can use the following lines to include a DocBook warning
|
|
admonition. As to what this warning says, you should pay attention to the
|
|
document context when quoting DocBook code in Org files. You may make
|
|
exported DocBook XML files invalid by not quoting DocBook code correctly.
|
|
|
|
#+begin_example
|
|
,#+BEGIN_DOCBOOK
|
|
<warning>
|
|
<para>You should know what you are doing when quoting DocBook XML code
|
|
in your Org file. Invalid DocBook XML may be generated by
|
|
DocBook exporter if you are not careful!</para>
|
|
</warning>
|
|
,#+END_DOCBOOK
|
|
#+end_example
|
|
|
|
*** Recursive sections
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Recursive sections in DocBook
|
|
:END:
|
|
#+cindex: DocBook recursive sections
|
|
|
|
DocBook exporter exports Org files as articles using the ~article~
|
|
element in DocBook. Recursive sections, i.e., ~section~ elements, are
|
|
used in exported articles. Top level headlines in Org files are
|
|
exported as top level sections, and lower level headlines are exported
|
|
as nested sections. The entire structure of Org files will be exported
|
|
completely, no matter how many nested levels of headlines there are.
|
|
|
|
Using recursive sections makes it easy to port and reuse exported
|
|
DocBook code in other DocBook document types like ~book~ or ~set~.
|
|
|
|
*** Tables in DocBook export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tables are exported as HTML tables
|
|
:END:
|
|
#+cindex: tables, in DocBook export
|
|
|
|
Tables in Org files are exported as HTML tables, which have been
|
|
supported since DocBook V4.3.
|
|
|
|
If a table does not have a caption, an informal table is generated
|
|
using the ~informaltable~ element; otherwise, a formal table will be
|
|
generated using the ~table~ element.
|
|
|
|
*** Images in DocBook export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to insert figures into DocBook output
|
|
:END:
|
|
#+cindex: images, inline in DocBook
|
|
#+cindex: inlining images in DocBook
|
|
|
|
Images that are linked to without a description part in the link, like
|
|
~[[file:img.jpg]]~ or ~[[./img.jpg]]~, will be exported to
|
|
DocBook using ~mediaobject~ elements. Each ~mediaobject~ element
|
|
contains an ~imageobject~ that wraps an ~imagedata~ element. If you
|
|
have specified a caption for an image as described in [[Images and
|
|
tables]], a ~caption~ element will be added in ~mediaobject~. If a label
|
|
is also specified, it will be exported as an ~xml:id~ attribute of the
|
|
~mediaobject~ element.
|
|
|
|
#+vindex: org-export-docbook-default-image-attributes
|
|
|
|
Image attributes supported by the ~imagedata~ element, like ~align~ or
|
|
~width~, can be specified in two ways: you can either customize
|
|
variable ~org-export-docbook-default-image-attributes~ or use the
|
|
~#+ATTR_DOCBOOK:~ line. Attributes specified in variable
|
|
~org-export-docbook-default-image-attributes~ are applied to all
|
|
inline images in the Org file to be exported (unless they are
|
|
overridden by image attributes specified in ~#+ATTR_DOCBOOK:~ lines).
|
|
|
|
The ~#+ATTR_DOCBOOK:~ line can be used to specify additional image
|
|
attributes or override default image attributes for individual images.
|
|
If the same attribute appears in both the ~#+ATTR_DOCBOOK:~ line and
|
|
variable ~org-export-docbook-default-image-attributes~, the former
|
|
takes precedence. Here is an example about how image attributes can be
|
|
set:
|
|
|
|
#+cindex: #+CAPTION
|
|
#+cindex: #+LABEL
|
|
#+cindex: #+ATTR_DOCBOOK
|
|
#+begin_example
|
|
,#+CAPTION: The logo of Org mode
|
|
,#+LABEL: unicorn-svg
|
|
,#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
|
|
[[./img/org-mode-unicorn.svg]]
|
|
#+end_example
|
|
|
|
#+vindex: org-export-docbook-inline-image-extensions
|
|
|
|
By default, DocBook exporter recognizes the following image file
|
|
types: {{{file(jpeg)}}}, {{{file(jpg)}}}, {{{file(png)}}},
|
|
{{{file(gif)}}}, and {{{file(svg)}}}. You can customize variable
|
|
~org-export-docbook-inline-image-extensions~ to add more types to this
|
|
list as long as DocBook supports them.
|
|
|
|
*** Special characters
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to handle special characters
|
|
:TITLE: Special characters in DocBook export
|
|
:END:
|
|
#+vindex: org-export-docbook-doctype
|
|
#+vindex: org-entities
|
|
|
|
Special characters that are written in TeX-like syntax, such as
|
|
~\alpha~, ~\Gamma~, and ~\Zeta~, are supported by DocBook exporter.
|
|
These characters are rewritten to XML entities, like ~α~,
|
|
~Γ~, and ~Ζ~, based on the list saved in variable
|
|
~org-entities~. As long as the generated DocBook file includes the
|
|
corresponding entities, these special characters are recognized.
|
|
|
|
You can customize variable ~org-export-docbook-doctype~ to include the
|
|
entities you need. For example, you can set variable
|
|
~org-export-docbook-doctype~ to the following value to recognize all
|
|
special characters included in XHTML entities:
|
|
|
|
#+begin_example
|
|
"<!DOCTYPE article [
|
|
<!ENTITY % xhtml1-symbol PUBLIC
|
|
\"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
|
|
\"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
|
|
>
|
|
%xhtml1-symbol;
|
|
]>
|
|
"
|
|
#+end_example
|
|
|
|
** OpenDocument Text export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to OpenDocument Text
|
|
:END:
|
|
#+cindex: K, Jambunathan
|
|
#+cindex: ODT
|
|
#+cindex: OpenDocument
|
|
#+cindex: export, OpenDocument
|
|
#+cindex: LibreOffice
|
|
#+cindex: org-odt.el
|
|
#+cindex: org-modules
|
|
|
|
Org Mode supports export to OpenDocument Text (ODT) format using the
|
|
{{{file(org-odt.el)}}} module.[fn:131] Documents created by this
|
|
exporter use the {{{cite(OpenDocument-v1.2 specification)}}} and
|
|
are compatible with LibreOffice 3.4.[fn:132]
|
|
|
|
*** Pre-requisites for ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: What packages ODT exporter relies on
|
|
:END:
|
|
#+cindex: zip
|
|
|
|
The ODT exporter relies on the {{{file(zip)}}} program to create the
|
|
final output. Check the availability of this program before proceeding
|
|
further.
|
|
|
|
*** ODT export commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to invoke ODT export
|
|
:ALT_TITLE: Exporting to ODT
|
|
:END:
|
|
<<x-export-to-odt>>
|
|
|
|
#+cindex: region, active
|
|
#+cindex: active region
|
|
#+cindex: transient-mark-mode
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e o)}}}, ~org-export-as-odt~ ::
|
|
#+kindex: C-c C-e o
|
|
#+cindex: property EXPORT_FILE_NAME
|
|
|
|
Export as OpenDocument Text file.
|
|
|
|
#+vindex: org-export-odt-preferred-output-format
|
|
|
|
If ~org-export-odt-preferred-output-format~ is specified,
|
|
automatically convert the exported file to that format. See
|
|
[[Automatically exporting to other formats]].
|
|
|
|
For an Org file {{{file(myfile.org)}}}, the ODT file will be
|
|
{{{file(myfile.odt)}}}. The file will be overwritten without warning.
|
|
If there is an active region, only the region will be
|
|
exported.[fn:133] If the selected region is a single tree, the tree
|
|
head will become the document title.[fn:134] If the tree head entry
|
|
has, or inherits, an ~EXPORT_FILE_NAME~ property, that name will be
|
|
used for the export.
|
|
|
|
- {{{kbd(C-c C-e O)}}}, ~org-export-as-odt-and-open~ ::
|
|
#+kindex: C-c C-e O
|
|
|
|
Export as an OpenDocument Text file and open the resulting file.
|
|
|
|
#+vindex: org-export-odt-preferred-output-format
|
|
|
|
If ~org-export-odt-preferred-output-format~ is specified, open the
|
|
converted file instead. See [[x-export-to-other-formats][Automatically exporting to other formats]].
|
|
|
|
*** Extending ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to produce ~doc~, ~pdf~ files
|
|
:END:
|
|
|
|
The ODT exporter can interface with a variety of document converters
|
|
and supports popular converters out of the box. As a result, you can
|
|
use it to export to formats like {{{samp(doc)}}} or convert a document
|
|
from one format (say {{{samp(csv)}}}) to another format (say
|
|
{{{samp(ods)}}} or {{{samp(xls)}}}).
|
|
|
|
#+cindex: @file{unoconv}
|
|
#+cindex: LibreOffice
|
|
|
|
If you have a working installation of LibreOffice, a document
|
|
converter is pre-configured for you and you can use it right away. If
|
|
you would like to use {{{file(unoconv)}}} as your preferred converter,
|
|
customize the variable ~org-export-odt-convert-process~ to point to
|
|
~unoconv~. You can also use your own favorite converter or tweak the
|
|
default settings of the {{{file(LibreOffice)}}} and
|
|
{{{samp(unoconv)}}} converters. See [[Configuring a document converter]].
|
|
|
|
**** Automatically exporting to other formats
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Automatic conversion to doc, docx, etc.
|
|
:END:
|
|
<<x-export-to-other-formats>>
|
|
|
|
#+vindex: org-export-odt-preferred-output-format
|
|
|
|
Very often, you will find yourself exporting to ODT format, only to
|
|
immediately save the exported document to other formats like
|
|
{{{samp(doc)}}}, {{{samp(docx)}}}, {{{samp(rtf)}}}, {{{samp(pdf)}}}
|
|
etc. In such cases, you can specify your preferred output format by
|
|
customizing the variable ~org-export-odt-preferred-output-format~.
|
|
This way, the export commands (see [[x-export-to-odt][Exporting to ODT]])
|
|
can be extended to export to a format that is of immediate interest to
|
|
you.
|
|
|
|
**** Converting between document formats
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Interacting with configured converters
|
|
:END:
|
|
# <<x-convert-to-other-formats>>
|
|
|
|
There are many document converters in the wild that support
|
|
conversion to and from various file formats, including, but not
|
|
limited to the ODT format. LibreOffice converter, mentioned above, is
|
|
one such converter. Once a converter is configured, you can interact
|
|
with it using the following command.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(M-x org-export-odt-convert)}}} ::
|
|
#+vindex: org-export-odt-convert
|
|
|
|
Convert an existing document from one format to another. With a prefix
|
|
argument, also open the newly produced file.
|
|
|
|
*** Applying custom styles
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to apply custom styles to the output
|
|
:END:
|
|
#+cindex: styles, custom
|
|
#+cindex: template, custom
|
|
|
|
The ODT exporter ships with a set of OpenDocument styles
|
|
(see [[Working with OpenDocument style files]]) that ensure a well-formatted output.
|
|
These factory styles, however, may not cater to your specific tastes.
|
|
To customize the output, you can either modify the above styles files
|
|
directly, or generate the required styles using an application like
|
|
LibreOffice. The latter method is suitable for expert and non-expert
|
|
users alike, and is described here.
|
|
|
|
Custom styles can be applied in three easy steps:
|
|
|
|
1. Create a sample {{{file(example.org)}}} file with the below
|
|
settings and export it to ODT format.
|
|
|
|
#+begin_example
|
|
,#+OPTIONS: H:10 num:t
|
|
#+end_example
|
|
|
|
2. Open the above {{{file(example.odt)}}} using LibreOffice. Use the
|
|
{{{file(Stylist)}}} to locate the target styles---these typically
|
|
have the {{{samp(Org)}}} prefix---and modify those to your taste.
|
|
Save the modified file either as an OpenDocument Text
|
|
({{{file(.odt)}}}) or OpenDocument Template ({{{file(.ott)}}})
|
|
file.
|
|
|
|
3. Customize the variable ~org-export-odt-styles-file~ and point it to
|
|
the newly created file. For additional configuration options see
|
|
[[x-overriding-factory-styles][Overriding factory styles]].
|
|
|
|
#+cindex: #+ODT_STYLES_FILE
|
|
#+vindex: org-export-odt-styles-file
|
|
|
|
If you would like to choose a style on a per-file basis, you can use
|
|
the ~#+ODT_STYLES_FILE~ option. A typical setting will look like
|
|
one of these two examples:
|
|
|
|
#+begin_example
|
|
,#+ODT_STYLES_FILE: "/path/to/example.ott"
|
|
#+end_example
|
|
|
|
or
|
|
|
|
#+begin_example
|
|
,#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
|
|
#+end_example
|
|
|
|
Although you can use third-party styles and templates for customizing
|
|
your output, this will produce the desired output only if the template
|
|
provides all style names that the {{{samp(ODT)}}} exporter relies
|
|
upon. Unless this condition is met, the output is going to be less
|
|
than satisfactory. It is highly recommended that you only work with
|
|
templates that are directly derived from the factory settings.
|
|
|
|
*** Links in ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How links will be interpreted and formatted
|
|
:END:
|
|
#+cindex: tables, in DocBook export
|
|
|
|
ODT exporter creates native cross-references for internal links. It
|
|
creates Internet-style links for all other links.
|
|
|
|
A link with no description and destined to a regular (un-itemized)
|
|
outline heading is replaced with a cross-reference and section number
|
|
of the heading.
|
|
|
|
A ~\ref{label}~-style reference to an image, table etc. is replaced
|
|
with a cross-reference and sequence number of the labeled entity. See
|
|
[[Labels and captions in ODT export]].
|
|
|
|
*** Tables in ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How tables are exported
|
|
:END:
|
|
|
|
#+cindex: tables, in DocBook export
|
|
|
|
Export of native Org mode tables (see [[Tables]]) and simple
|
|
{{{file(table.el)}}} tables is supported. However, export of complex
|
|
{{{file(table.el)}}} tables---tables that have column or row
|
|
spans---is not supported. Such tables are stripped from the exported
|
|
document.
|
|
|
|
By default, a table is exported with top and bottom frames and with
|
|
rules separating row and column groups (see [[Column groups]]).
|
|
Furthermore, all tables are typeset to occupy the same width. If the
|
|
table specifies alignment and relative width for its columns (see
|
|
[[Column width and alignment]]) then these are honored on export.[fn:135]
|
|
|
|
#+cindex: #+ATTR_ODT
|
|
|
|
You can control the width of the table by specifying ~:rel-width~
|
|
property using an ~#+ATTR_ODT~ line.
|
|
|
|
For example, consider the following table which makes use of all the
|
|
rules mentioned above.
|
|
|
|
#+begin_example
|
|
#+ATTR_ODT: :rel-width 50
|
|
| Area/Month | Jan | Feb | Mar | Sum |
|
|
|---------------+-------+-------+-------+-------|
|
|
| / | < | | | < |
|
|
| <l13> | <r5> | <r5> | <r5> | <r6> |
|
|
| North America | 1 | 21 | 926 | 948 |
|
|
| Middle East | 6 | 75 | 844 | 925 |
|
|
| Asia Pacific | 9 | 27 | 790 | 826 |
|
|
|---------------+-------+-------+-------+-------|
|
|
| Sum | 16 | 123 | 2560 | 2699 |
|
|
#+end_example
|
|
|
|
On export, the table will occupy 50% of text area. The columns will be
|
|
sized (roughly) in the ratio of 13:5:5:5:6. The first column will be
|
|
left-aligned and rest of the columns will be right-aligned. There will
|
|
be vertical rules after separating the header and last columns from
|
|
other columns. There will be horizontal rules separating the header
|
|
and last rows from other rows.
|
|
|
|
If you are not satisfied with the above formatting options, you can
|
|
create custom table styles and associate them with a table using the
|
|
~#+ATTR_ODT~ line. See [[Customizing tables in ODT export]].
|
|
|
|
*** Images in ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to insert images
|
|
:END:
|
|
#+cindex: images, embedding in ODT
|
|
#+cindex: embedding images in ODT
|
|
|
|
You can embed images within the exported document by providing a link to the
|
|
desired image file with no link description. For example, to embed
|
|
{{{samp(img.png)}}} do either of the following:
|
|
|
|
#+begin_example
|
|
[[file:img.png]]
|
|
#+end_example
|
|
|
|
#+begin_example
|
|
[[./img.png]]
|
|
#+end_example
|
|
|
|
You can create clickable images by providing a link whose description
|
|
is a link to an image file. For example, to embed an image
|
|
{{{file(org-mode-unicorn.png)}}}, which when clicked jumps to
|
|
[[http://Orgmode.org]] website, do the following:
|
|
|
|
#+begin_example
|
|
[[http://orgmode.org][./org-mode-unicorn.png]]
|
|
#+end_example
|
|
|
|
#+cindex: #+ATTR_ODT
|
|
|
|
You can control the size and scale of the embedded images using the
|
|
~#+ATTR_ODT~ attribute.
|
|
|
|
#+cindex: identify, ImageMagick
|
|
#+vindex: org-export-odt-pixels-per-inch
|
|
|
|
The exporter specifies the desired size of the image in the final
|
|
document in units of centimeters. In order to scale the embedded
|
|
images, the exporter queries for pixel dimensions of the images using
|
|
either ImageMagick's {{{file(identify)}}} program, or Emacs'
|
|
`create-image' and `image-size' APIs.[fn:136] The pixel dimensions are
|
|
subsequently converted to centimeters using
|
|
~org-export-odt-pixels-per-inch~. The default value of this variable
|
|
is set to ~display-pixels-per-inch~. You can tweak this variable to
|
|
achieve the best results.
|
|
|
|
The examples below illustrate the various possibilities.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Explicitly size the image ::
|
|
|
|
To embed {{{file(img.png)}}} as a 10 cm x 10 cm image, do the
|
|
following:
|
|
|
|
#+begin_example
|
|
#+ATTR_ODT: :width 10 :height 10
|
|
[[./img.png]]
|
|
#+end_example
|
|
|
|
- Scale the image ::
|
|
|
|
To embed {{{file(img.png)}}} at half its size, do the following:
|
|
|
|
#+begin_example
|
|
#+ATTR_ODT: :scale 0.5
|
|
[[./img.png]]
|
|
#+end_example
|
|
|
|
- Scale the image to a specific width ::
|
|
|
|
To embed {{{file(img.png)}}} with a width of 10 cm while retaining the
|
|
original height:width ratio, do the following:
|
|
|
|
#+begin_example
|
|
#+ATTR_ODT: :width 10
|
|
[[./img.png]]
|
|
#+end_example
|
|
|
|
- Scale the image to a specific height ::
|
|
|
|
To embed {{{file(img.png)}}} with a height of 10 cm while retaining
|
|
the original height:width ratio, do the following:
|
|
|
|
#+begin_example
|
|
#+ATTR_ODT: :height 10
|
|
[[./img.png]]
|
|
#+end_example
|
|
|
|
#+cindex: #+ATTR_ODT
|
|
|
|
You can control the manner in which an image is anchored by setting
|
|
the ~:anchor~ property of it's ~#+ATTR_ODT~ line. You can specify one
|
|
of the the following three values for the ~:anchor~ property -
|
|
{{{samp("as-char")}}}, {{{samp("paragraph")}}} and {{{samp("page")}}}.
|
|
|
|
To create an image that is anchored to a page, do the following:
|
|
|
|
#+begin_example
|
|
#+ATTR_ODT: :anchor "page"
|
|
[[./img.png]]
|
|
#+end_example
|
|
|
|
*** Math formatting in ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How LaTeX fragments are formatted
|
|
:END:
|
|
|
|
The ODT exporter has special support for handling math.
|
|
|
|
**** Working with LaTeX math snippets
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to embed LaTeX math fragments
|
|
:END:
|
|
|
|
LaTeX math snippets (see [[LaTeX fragments]]) can be embedded in the ODT
|
|
document in one of the following ways:
|
|
|
|
#+cindex: MathML
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- MathML ::
|
|
|
|
This option is activated on a per-file basis with the following option:
|
|
|
|
#+begin_example
|
|
,#+OPTIONS: LaTeX:t
|
|
#+end_example
|
|
|
|
With this option, LaTeX fragments are first converted into MathML
|
|
fragments using an external LaTeX-to-MathML converter program. The
|
|
resulting MathML fragments are then embedded as an OpenDocument Formula in
|
|
the exported document.
|
|
|
|
#+vindex: org-latex-to-mathml-convert-command
|
|
#+vindex: org-latex-to-mathml-jar-file
|
|
|
|
You can specify the LaTeX-to-MathML converter by customizing the variables ~org-latex-to-mathml-convert-command~ and ~org-latex-to-mathml-jar-file~.
|
|
|
|
If you prefer to use {{{file(MathToWeb)}}} as your converter, you can
|
|
configure the above variables as shown below.[fn:137]
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-latex-to-mathml-convert-command
|
|
"java -jar %j -unicode -force -df %o %I"
|
|
org-latex-to-mathml-jar-file
|
|
"/path/to/mathtoweb.jar")
|
|
#+end_src
|
|
|
|
You can use the following commands to quickly verify the reliability of
|
|
the LaTeX-to-MathML converter.
|
|
|
|
- {{{kbd(M-x org-export-as-odf)}}} ::
|
|
|
|
Convert a LaTeX math snippet to an OpenDocument formula
|
|
({{{file(.odf)}}}) file.
|
|
|
|
- {{{kbd(M-x org-export-as-odf-and-open)}}} ::
|
|
|
|
Convert a LaTeX math snippet to an OpenDocument formula
|
|
({{{file(.odf)}}}) file and open the formula file with the
|
|
system-registered application.
|
|
|
|
- PNG images ::
|
|
#+cindex: dvipng
|
|
|
|
This option is activated on a per-file basis with
|
|
|
|
#+begin_example
|
|
,#+OPTIONS: LaTeX:dvipng
|
|
#+end_example
|
|
|
|
With this option, LaTeX fragments are processed into PNG images and
|
|
the resulting images are embedded in the exported document. This
|
|
method requires that the {{{file(dvipng)}}} program be available on
|
|
your system.
|
|
|
|
**** Working with MathML or OpenDocument formula files
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to embed equations in native format
|
|
:END:
|
|
|
|
For various reasons, you may find embedding LaTeX math snippets in
|
|
an ODT document less than reliable. In that case, you can embed a math
|
|
equation by linking to its MathML ({{{file(.mml)}}}) source or its
|
|
OpenDocument formula ({{{file(.odf)}}}) file as shown below:
|
|
|
|
#+begin_example
|
|
[[./equation.mml]]
|
|
#+end_example
|
|
|
|
or
|
|
|
|
#+begin_example
|
|
[[./equation.odf]]
|
|
#+end_example
|
|
|
|
*** Labels and captions in ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How captions are rendered
|
|
:END:
|
|
|
|
You can label and caption various category of objects---an inline
|
|
image, a table, a LaTeX fragment or a Math formula---using
|
|
~#+LABEL~ and ~#+CAPTION~ lines. See [[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 its appearance in the Org file.
|
|
|
|
In the exported document, a user-provided caption is augmented with
|
|
the category and sequence number. Consider the following inline image
|
|
in an Org file:
|
|
|
|
#+begin_example
|
|
,#+CAPTION: Bell curve
|
|
,#+LABEL: fig:SED-HR4049
|
|
[[./img/a.png]]
|
|
#+end_example
|
|
|
|
It could be rendered as shown below in the exported document.
|
|
|
|
#+begin_example
|
|
Figure 2: Bell curve
|
|
#+end_example
|
|
|
|
#+vindex: org-export-odt-category-strings
|
|
|
|
You can modify the category component of the caption by customizing
|
|
the variable ~org-export-odt-category-strings~. For example, to tag
|
|
all embedded images with the string {{{samp(Illustration)}}} (instead
|
|
of the default {{{samp(Figure)}}}) use the following setting.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-export-odt-category-strings
|
|
'(("en" "Table" "Illustration" "Equation" "Equation")))
|
|
#+end_src
|
|
|
|
With this, previous image will be captioned as below in the exported
|
|
document.
|
|
|
|
#+begin_example
|
|
Illustration 2: Bell curve
|
|
#+end_example
|
|
|
|
*** Literal examples in ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How source and example blocks are formatted
|
|
:END:
|
|
|
|
Export of literal examples (see [[Literal examples]]) with full
|
|
fontification is supported. Internally, the exporter relies on
|
|
{{{file(htmlfontify.el)}}} to generate all style definitions needed
|
|
for a fancy listing.[fn:138] The auto-generated styles have
|
|
{{{samp(OrgSrc)}}} as prefix and inherit their color from the faces
|
|
used by Emacs ~font-lock~ library for the source language.
|
|
|
|
#+vindex: org-export-odt-fontify-srcblocks
|
|
|
|
If you prefer to use your own custom styles for fontification, you can
|
|
do so by customizing the variable
|
|
~org-export-odt-create-custom-styles-for-srcblocks~.
|
|
|
|
#+vindex: org-export-odt-create-custom-styles-for-srcblocks
|
|
|
|
You can turn off fontification of literal examples by customizing the
|
|
variable ~org-export-odt-fontify-srcblocks~.
|
|
|
|
*** Advanced topics in ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Read this if you are a power user
|
|
:END:
|
|
|
|
If you rely heavily on ODT export, you may want to exploit the full
|
|
set of features that the exporter offers. This section describes
|
|
features that would be of interest to power users.
|
|
|
|
**** Configuring a document converter
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to register a document converter
|
|
:END:
|
|
#+cindex: convert
|
|
#+cindex: doc, docx, rtf
|
|
#+cindex: converter
|
|
|
|
The ODT exporter can work with popular converters with little or no
|
|
extra configuration from your side. See [[Extending ODT export]]. If you
|
|
are using a converter that is not supported by default or if you would
|
|
like to tweak the default converter settings, proceed as below.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Register the converter ::
|
|
|
|
#+vindex: org-export-odt-convert-processes
|
|
|
|
Name your converter and add it to the list of known converters by
|
|
customizing the variable ~org-export-odt-convert-processes~. Also
|
|
specify how the converter can be invoked via command-line to effect
|
|
the conversion.
|
|
|
|
- Configure its capabilities ::
|
|
|
|
#+vindex: org-export-odt-convert-capabilities
|
|
# <<x-odt-converter-capabilities>>
|
|
|
|
Specify the set of formats the converter can handle by customizing the
|
|
variable ~org-export-odt-convert-capabilities~. Use the default value
|
|
for this variable as a guide for configuring your converter. As suggested by
|
|
the default setting, you can specify the full set of formats supported by the
|
|
converter and not limit yourself to specifying formats that are related to
|
|
just the OpenDocument Text format.
|
|
|
|
- Choose the converter ::
|
|
|
|
#+vindex: org-export-odt-convert-process
|
|
|
|
Select the newly added converter as the preferred one by customizing the
|
|
variable ~org-export-odt-convert-process~.
|
|
|
|
**** Working with OpenDocument style files
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Explore the internals
|
|
:END:
|
|
#+cindex: styles, custom
|
|
#+cindex: template, custom
|
|
|
|
This section explores the internals of the ODT exporter and the means
|
|
by which it produces styled documents. Read this section if you are
|
|
interested in exploring the automatic and custom OpenDocument styles
|
|
used by the exporter.
|
|
|
|
# <<x-factory-styles>>
|
|
|
|
The ODT exporter relies on two files for generating its output.
|
|
These files are bundled with the distribution under the directory pointed to
|
|
by the variable ~org-odt-styles-dir~. The two files are:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{file(OrgOdtStyles.xml)}}} ::
|
|
<<x-orgodtstyles-xml>>
|
|
|
|
This file contributes to the {{{file(styles.xml)}}} file of the final
|
|
{{{samp(ODT)}}} document. This file is modified to control outline
|
|
numbering based on user settings, and To add styles generated by
|
|
{{{file(htmlfontify.el)}}} for fontification of code blocks.
|
|
|
|
- {{{file(OrgOdtContentTemplate.xml)}}} ::
|
|
<<x-orgodtcontenttemplate-xml>>
|
|
|
|
This file contributes to the {{{file(content.xml)}}} file of the final
|
|
{{{samp(ODT)}}} document. The contents of the Org outline are inserted
|
|
between the ~<office:text>~ and ~</office:text>~
|
|
elements of this file.
|
|
|
|
In addition to serving as a template file for the final
|
|
{{{file(content.xml)}}}, the file also contains automatic styles for
|
|
formatting of tables which are referenced by the exporter, and ~<text:sequence-decl>~ ... ~</text:sequence-decl>~
|
|
elements that control how various entities---tables, images,
|
|
equations, etc.---are numbered.
|
|
|
|
|
|
<<x-overriding-factory-styles>>
|
|
|
|
The following two variables control the location from which the ODT
|
|
exporter picks up the custom styles and content template files. You
|
|
can customize these variables to override the factory styles used by
|
|
the exporter.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~org-export-odt-styles-file~ ::
|
|
<<x-org-export-odt-styles-file>>
|
|
|
|
Use this variable to specify the {{{file(styles.xml)}}} that will be
|
|
used in the final output. You can specify one of the following values:
|
|
|
|
- A {{{file(styles.xml)}}} file ::
|
|
|
|
Use this file instead of the default {{{file(styles.xml)}}}
|
|
|
|
- A {{{file(.odt)}}} or {{{file(.ott)}}} file ::
|
|
|
|
Use the {{{file(styles.xml)}}} contained in the specified OpenDocument
|
|
Text or Template file.
|
|
|
|
- A {{{file(.odt)}}} or {{{file(.ott)}}} file and a subset of files contained within them ::
|
|
|
|
Use the {{{file(styles.xml)}}} contained in the specified OpenDocument
|
|
Text or Template file. Additionally extract the specified member files
|
|
and embed those within the final {{{samp(ODT)}}} document.
|
|
|
|
Use this option if the {{{file(styles.xml)}}} file references
|
|
additional files like header and footer images.
|
|
|
|
- ~nil~ ::
|
|
|
|
Use the default {{{file(styles.xml)}}}
|
|
|
|
- ~org-export-odt-content-template-file~ ::
|
|
<<x-org-export-odt-content-template-file>>
|
|
|
|
Use this variable to specify the blank {{{file(content.xml)}}} that
|
|
will be used in the final output.
|
|
|
|
**** Creating one-off styles
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to produce custom highlighting, etc.
|
|
:END:
|
|
|
|
There are times when you would want one-off formatting in the exported
|
|
document. You can achieve this by embedding raw OpenDocument XML in
|
|
the Org file. The use of this feature is better illustrated with
|
|
couple of examples.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Embedding ODT tags as part of regular text ::
|
|
|
|
You can include simple OpenDocument tags by prefixing them with
|
|
{{{samp(@)}}}. For example, to highlight a region of text do the
|
|
following:
|
|
|
|
#+begin_example
|
|
@<text:span text:style-name="Highlight">This is a
|
|
highlighted text@</text:span>. But this is a
|
|
regular text.
|
|
#+end_example *Hint:* To see the above example in action, edit your
|
|
{{{file(styles.xml)}}} (see [[x-orgodtstyles-xml][Factory styles]]) and
|
|
add a custom {{{samp(Highlight)}}} style as shown below.
|
|
|
|
#+begin_example
|
|
<style:style style:name="Highlight" style:family="text">
|
|
<style:text-properties fo:background-color="#ff0000"/>
|
|
</style:style>
|
|
#+end_example
|
|
|
|
- Embedding a one-line OpenDocument XML ::
|
|
|
|
You can add a simple OpenDocument one-liner using the ~#+ODT:~
|
|
directive. For example, to force a page break do the following:
|
|
|
|
#+begin_example
|
|
#+ODT: <text:p text:style-name="PageBreak"/>
|
|
#+end_example *Hint:* To see the above example in action, edit your
|
|
{{{file(styles.xml)}}} (see [[x-orgodtstyles-xml][Factory styles]]) and
|
|
add a custom {{{samp(PageBreak)}}} style as shown below.
|
|
|
|
#+begin_example
|
|
<style:style style:name="PageBreak" style:family="paragraph"
|
|
style:parent-style-name="Text_20_body">
|
|
<style:paragraph-properties fo:break-before="page"/>
|
|
</style:style>
|
|
#+end_example
|
|
|
|
- Embedding a block of OpenDocument XML ::
|
|
|
|
You can add a large block of OpenDocument XML using the ~#+BEGIN_ODT~ ... ~#+END_ODT~ construct.
|
|
|
|
For example, to create a one-off paragraph that uses bold text, do the
|
|
following:
|
|
|
|
#+begin_example
|
|
#+BEGIN_ODT
|
|
<text:p text:style-name="Text_20_body_20_bold">
|
|
This paragraph is specially formatted and uses bold text.
|
|
</text:p>
|
|
#+END_ODT
|
|
#+end_example
|
|
|
|
**** Customizing tables in ODT export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to define and use table templates
|
|
:END:
|
|
#+cindex: tables, in ODT export
|
|
#+cindex: #+ATTR_ODT
|
|
|
|
You can override the default formatting of the table by specifying a
|
|
custom table style with the ~#+ATTR_ODT~ line. For a discussion on
|
|
default formatting of tables see [[Tables in ODT export]].
|
|
|
|
This feature closely mimics the way table templates are defined in the
|
|
OpenDocument-v1.2 specification.[fn:139]
|
|
|
|
To have a quick preview of this feature, install the following setting and
|
|
export the example table.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-export-odt-table-styles
|
|
(append org-export-odt-table-styles
|
|
'(("TableWithHeaderRowAndColumn" "Custom"
|
|
((use-first-row-styles . t)
|
|
(use-first-column-styles . t)))
|
|
("TableWithFirstRowandLastRow" "Custom"
|
|
((use-first-row-styles . t)
|
|
(use-last-row-styles . t))))))
|
|
#+end_src
|
|
|
|
#+begin_example
|
|
,#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
|
|
| Name | Phone | Age |
|
|
| Peter | 1234 | 17 |
|
|
| Anna | 4321 | 25 |
|
|
#+end_example
|
|
|
|
In the above example, you used a template named {{{samp(Custom)}}} and
|
|
installed two table styles with the names
|
|
{{{samp(TableWithHeaderRowAndColumn)}}} and
|
|
{{{samp(TableWithFirstRowandLastRow)}}}. (*Important:* The
|
|
OpenDocument styles needed for producing the above template have been
|
|
pre-defined for you. These styles are available under the section
|
|
marked {{{samp(Custom Table Template)}}} in
|
|
{{{file(OrgOdtContentTemplate.xml)}}} (see
|
|
[[x-orgodtcontenttemplate-xml][Factory styles]]). If you need additional
|
|
templates you have to define these styles yourself.
|
|
|
|
|
|
To use this feature proceed as follows:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Create a table template[fn:140] ::
|
|
|
|
A table template is nothing but a set of {{{samp(table-cell)}}} and
|
|
{{{samp(paragraph)}}} styles for each of the following table cell
|
|
categories:
|
|
|
|
- Body
|
|
- First column
|
|
- Last column
|
|
- First row
|
|
- Last row
|
|
- Even row
|
|
- Odd row
|
|
- Even column
|
|
- Odd Column
|
|
|
|
The names for the above styles must be chosen based on the name of the
|
|
table template using a well-defined convention.
|
|
|
|
The naming convention is better illustrated with an example. For a
|
|
table template with the name {{{samp(Custom)}}}, the needed style
|
|
names are listed in the following table.
|
|
|
|
| Table cell type | ~table-cell~ style | ~paragraph~ style |
|
|
|-----------------+----------------------------------------+---------------------------------------------|
|
|
| Body | {{{samp(CustomTableCell)}}} | {{{samp(CustomTableParagraph)}}} |
|
|
| First column | {{{samp(CustomFirstColumnTableCell)}}} | {{{samp(CustomFirstColumnTableParagraph)}}} |
|
|
| Last column | {{{samp(CustomLastColumnTableCell)}}} | {{{samp(CustomLastColumnTableParagraph)}}} |
|
|
| First row | {{{samp(CustomFirstRowTableCell)}}} | {{{samp(CustomFirstRowTableParagraph)}}} |
|
|
| Last row | {{{samp(CustomLastRowTableCell)}}} | {{{samp(CustomLastRowTableParagraph)}}} |
|
|
| Even row | {{{samp(CustomEvenRowTableCell)}}} | {{{samp(CustomEvenRowTableParagraph)}}} |
|
|
| Odd row | {{{samp(CustomOddRowTableCell)}}} | {{{samp(CustomOddRowTableParagraph)}}} |
|
|
| Even column | {{{samp(CustomEvenColumnTableCell)}}} | {{{samp(CustomEvenColumnTableParagraph)}}} |
|
|
| Odd column | {{{samp(CustomOddColumnTableCell)}}} | {{{samp(CustomOddColumnTableParagraph)}}} |
|
|
|
|
|
|
To create a table template with the name {{{samp(Custom)}}}, define
|
|
the above styles in the ~<office:automatic-styles>~ ... ~</office:automatic-styles>~ element of the content template file (see
|
|
[[x-orgodtcontenttemplate-xml][Factory styles]]).
|
|
|
|
- Define a table style[fn:141] ::
|
|
|
|
#+vindex: org-export-odt-table-styles
|
|
|
|
To define a table style, create an entry for the style in the variable ~org-export-odt-table-styles~ and specify the following:
|
|
|
|
- the name of the table template created in step (1)
|
|
- the set of cell styles in that template that are to be activated
|
|
|
|
|
|
For example, the entry below defines two different table styles
|
|
{{{samp(TableWithHeaderRowAndColumn)}}} and
|
|
{{{samp(TableWithFirstRowandLastRow)}}} based on the same template
|
|
{{{samp(Custom)}}}. The styles achieve their intended effect by
|
|
selectively activating the individual cell styles in that template.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-export-odt-table-styles
|
|
(append org-export-odt-table-styles
|
|
'(("TableWithHeaderRowAndColumn" "Custom"
|
|
((use-first-row-styles . t)
|
|
(use-first-column-styles . t)))
|
|
("TableWithFirstRowandLastRow" "Custom"
|
|
((use-first-row-styles . t)
|
|
(use-last-row-styles . t))))))
|
|
#+end_src
|
|
|
|
- Associate a table with the table style ::
|
|
|
|
To do this, specify the table style created in step (2) as part of
|
|
the ~ATTR_ODT~ line as shown below.
|
|
|
|
#+begin_example
|
|
,#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
|
|
| Name | Phone | Age |
|
|
| Peter | 1234 | 17 |
|
|
| Anna | 4321 | 25 |
|
|
#+end_example
|
|
|
|
**** Validating OpenDocument XML
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to debug corrupt OpenDocument files
|
|
:END:
|
|
|
|
Occasionally, you will discover that the document created by the ODT
|
|
exporter cannot be opened by your favorite application. One of the
|
|
common reasons for this is that the {{{file(.odt)}}} file is corrupt.
|
|
In such cases, you may want to validate the document against the
|
|
OpenDocument RELAX NG Compact Syntax (RNC) schema.
|
|
|
|
For de-compressing the {{{file(.odt)}}} file[fn:142]:
|
|
[[info:emacs#File Archives]]. For general help with validation (and
|
|
schema-sensitive editing) of XML files: [[info:nxml-mode#Introduction]].
|
|
#+vindex: org-export-odt-schema-dir
|
|
|
|
If you have ready access to OpenDocument {{{file(.rnc)}}} files and
|
|
the needed schema-locating rules in a single folder, you can customize
|
|
the variable ~org-export-odt-schema-dir~ to point to that directory.
|
|
The ODT exporter will take care of updating the
|
|
~rng-schema-locating-files~ for you.
|
|
|
|
** TaskJuggler export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to TaskJuggler
|
|
:END:
|
|
#+cindex: TaskJuggler export
|
|
#+cindex: Project management
|
|
|
|
[[http://www.taskjuggler.org/][TaskJuggler]] is a project management tool. It provides an optimizing
|
|
scheduler that computes your project time lines and resource
|
|
assignments based on the project outline and the constraints that you
|
|
have provided.
|
|
|
|
The TaskJuggler exporter is a bit different from other exporters, such
|
|
as the ~HTML~ and LaTeX exporters for example, in that it does not
|
|
export all the nodes of a document or strictly follow the order of the
|
|
nodes in the document.
|
|
|
|
Instead the TaskJuggler exporter looks for a tree that defines the
|
|
tasks and optionally trees that define the resources and reports for
|
|
this project. It then creates a TaskJuggler file based on these trees
|
|
and the attributes defined in all the nodes.
|
|
|
|
*** TaskJuggler export commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Key bindings for TaskJuggler export
|
|
:END:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e j)}}}, ~org-export-as-taskjuggler~ ::
|
|
#+kindex: C-c C-e j
|
|
|
|
Export as a TaskJuggler file.
|
|
|
|
- {{{kbd(C-c C-e J)}}}, ~org-export-as-taskjuggler-and-open~ ::
|
|
#+kindex: C-c C-e J
|
|
|
|
Export as a TaskJuggler file and then open the file with TaskJugglerUI
|
|
(only for TaskJugglerUI 2.x).
|
|
|
|
*** Tasks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Marking tasks for TaskJuggler export
|
|
:END:
|
|
#+vindex: org-export-taskjuggler-project-tag
|
|
|
|
Create your tasks as you usually do with Org mode. Assign efforts to
|
|
each task using properties (it is easiest to do this in the column
|
|
view). You should end up with something similar to the example by
|
|
Peter Jones in
|
|
[[http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org]].
|
|
Now mark the top node of your tasks with a tag named
|
|
~:taskjuggler_project:~ (or whatever you customized
|
|
~org-export-taskjuggler-project-tag~ to). You are now ready to export
|
|
the project plan with {{{kbd(C-c C-e J)}}} which will export the
|
|
project plan and open a gantt chart in TaskJugglerUI.
|
|
|
|
*** Resources
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Define TaskJuggler resources
|
|
:END:
|
|
#+vindex: org-export-taskjuggler-resource-tag
|
|
|
|
Next you can define resources and assign those to work on specific
|
|
tasks. You can group your resources hierarchically. Tag the top node
|
|
of the resources with ~:taskjuggler_resource:~ (or whatever you
|
|
customized ~org-export-taskjuggler-resource-tag~ to). You can
|
|
optionally assign an identifier (named {{{samp(resource_id)}}}) to the
|
|
resources (using the standard Org properties commands, see [[Property
|
|
syntax]]) or you can let the exporter generate identifiers automatically
|
|
(the exporter picks the first word of the headline as the identifier
|
|
as long as it is unique---see the documentation of
|
|
~org-taskjuggler-get-unique-id~). Using that identifier you can then
|
|
allocate resources to tasks. This is again done with the
|
|
{{{samp(allocate)}}} property on the tasks. Do this in column view or
|
|
when on the task type
|
|
{{{ksksksk(C-c C-x p allocate,RET,<resource_id>,RET)}}}.
|
|
|
|
Once the allocations are done you can again export to TaskJuggler and
|
|
check in the Resource Allocation Graph which person is working on what
|
|
task at what time.
|
|
|
|
*** Export of properties
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Which properties will be exported?
|
|
:END:
|
|
|
|
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)}}}). Scheduling
|
|
information is also taken into account to set start/end dates for
|
|
tasks.
|
|
|
|
The exporter will also export any property on a task resource or
|
|
resource node which is known to TaskJuggler, such as
|
|
{{{samp(limits)}}}, {{{samp(vacation)}}}, {{{samp(shift)}}},
|
|
{{{samp(booking)}}}, {{{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.
|
|
|
|
*** Dependencies
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How the exporter handles dependencies
|
|
:END:
|
|
|
|
The exporter will handle dependencies that are defined in the tasks
|
|
either with the {{{samp(ORDERED)}}} attribute (see [[TODO dependencies]]),
|
|
with the {{{samp(BLOCKER)}}} attribute (see {{{file(org-depend.el)}}})
|
|
or alternatively with a {{{samp(depends)}}} attribute. Both the
|
|
{{{samp(BLOCKER)}}} and the {{{samp(depends)}}} attribute can be
|
|
either {{{samp(previous-sibling)}}} or a reference to an identifier
|
|
(named {{{samp(task_id)}}}) which is defined for another task in the
|
|
project. {{{samp(BLOCKER)}}} and the {{{samp(depends)}}} attribute can
|
|
define multiple dependencies separated by either space or comma. You
|
|
can also specify optional attributes on the dependency by simply
|
|
appending it. The following examples should illustrate this:
|
|
|
|
#+begin_example
|
|
,* Preparation
|
|
, :PROPERTIES:
|
|
, :task_id: preparation
|
|
, :ORDERED: t
|
|
, :END:
|
|
,* Training material
|
|
, :PROPERTIES:
|
|
, :task_id: training_material
|
|
, :ORDERED: t
|
|
, :END:
|
|
,** Markup Guidelines
|
|
, :PROPERTIES:
|
|
, :Effort: 2d
|
|
, :END:
|
|
,** Workflow Guidelines
|
|
, :PROPERTIES:
|
|
, :Effort: 2d
|
|
, :END:
|
|
,* Presentation
|
|
, :PROPERTIES:
|
|
, :Effort: 2d
|
|
, :BLOCKER: training_material { gapduration 1d } preparation
|
|
, :END:
|
|
#+end_example
|
|
|
|
*** Reports
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Gantt charts, etc.
|
|
:END:
|
|
#+vindex: org-export-taskjuggler-default-reports
|
|
|
|
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. By default,
|
|
the exporter will automatically insert some pre-set reports in the
|
|
file. These defaults are defined in
|
|
~org-export-taskjuggler-default-reports~. They can be modified using
|
|
customize along with a number of other options. For a more complete
|
|
list, see
|
|
{{{ksksksk(M-x customize-group,RET,org-export-taskjuggler,RET)}}}.
|
|
|
|
Alternately, the user can tag a tree with
|
|
~org-export-taskjuggler-report-tag~, and define reports in sub-nodes,
|
|
similarly to what is done with tasks or resources. The properties used
|
|
for report generation are defined in
|
|
~org-export-taskjuggler-valid-report-attributes~. In addition, a
|
|
special property named {{{samp(report-kind)}}} is used to define the
|
|
kind of report one wants to generate (by default, a
|
|
{{{samp(taskreport)}}}).
|
|
|
|
For more information and examples see the Org-taskjuggler tutorial at
|
|
[[http://orgmode.org/worg/org-tutorials/org-taskjuggler.html]].
|
|
|
|
** Freemind export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to Freemind mind maps
|
|
:END:
|
|
#+cindex: Freemind export
|
|
#+cindex: mind map
|
|
|
|
The Freemind exporter was written by Lennart Borgman.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e m)}}}, ~org-export-as-freemind~ ::
|
|
#+kindex: C-c C-e m
|
|
|
|
Export as a Freemind mind map. For an Org file {{{file(myfile.org)}}},
|
|
the Freemind file will be {{{file(myfile.mm)}}}.
|
|
|
|
** XOXO export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to XOXO
|
|
:END:
|
|
#+cindex: XOXO export
|
|
|
|
Org mode contains an exporter that produces XOXO-style output.
|
|
Currently, this exporter only handles the general outline structure
|
|
and does not interpret any additional Org mode features.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e x)}}}, ~org-export-as-xoxo~ ::
|
|
#+kindex: C-c C-e x
|
|
|
|
Export as an XOXO file. For an Org file {{{file(myfile.org)}}}, the
|
|
XOXO file will be {{{file(myfile.html)}}}.
|
|
|
|
- {{{kbd(C-c C-e v x)}}} ::
|
|
#+kindex: C-c C-e v x
|
|
|
|
Export only the visible part of the document.
|
|
|
|
** iCalendar export
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Exporting to iCalendar format
|
|
:END:
|
|
#+cindex: iCalendar export
|
|
|
|
#+vindex: org-icalendar-include-todo
|
|
#+vindex: org-icalendar-use-deadline
|
|
#+vindex: org-icalendar-use-scheduled
|
|
#+vindex: org-icalendar-categories
|
|
#+vindex: org-icalendar-alarm-time
|
|
|
|
Some people use Org mode for keeping track of projects, but still
|
|
prefer a standard calendar application for anniversaries and
|
|
appointments. In this case it can be useful to show deadlines and
|
|
other time-stamped items in Org files in the calendar application. Org
|
|
mode can export calendar information in the standard iCalendar format.
|
|
If you also want to have TODO entries included in the export,
|
|
configure the variable ~org-icalendar-include-todo~. Plain timestamps
|
|
are exported as VEVENT, and TODO items as VTODO. It will also create
|
|
events from deadlines that are in non-TODO items. Deadlines and
|
|
scheduling dates in TODO items will be used to set the start and due
|
|
dates for the TODO entry.[fn:143] As categories, it will use the tags
|
|
locally defined in the heading, and the file/tree category.[fn:144]
|
|
See the variable ~org-icalendar-alarm-time~ for a way to assign alarms
|
|
to entries with a time.
|
|
|
|
#+vindex: org-icalendar-store-UID
|
|
#+cindex: property, ID
|
|
|
|
The iCalendar standard requires each entry to have a globally unique
|
|
identifier (UID). Org creates these identifiers during export. If you
|
|
set the variable ~org-icalendar-store-UID~, the UID will be stored in
|
|
the ~:ID:~ property of the entry and re-used next time you report this
|
|
entry. Since a single entry can give rise to multiple iCalendar
|
|
entries (as a timestamp, a deadline, a scheduled item, and as a TODO
|
|
item), Org adds prefixes to the UID, depending on what triggered the
|
|
inclusion of the entry. In this way the UID remains unique, but a
|
|
synchronization program can still figure out from which entry all the
|
|
different instances originate.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e i)}}}, ~org-export-icalendar-this-file~ ::
|
|
#+kindex: C-c C-e i
|
|
|
|
Create iCalendar entries for the current file and store them in the
|
|
same directory, using a file extension {{{file(.ics)}}}.
|
|
|
|
- {{{kbd(C-c C-e I)}}}, ~ org-export-icalendar-all-agenda-files~ ::
|
|
#+kindex: C-c C-e I
|
|
#+vindex: org-agenda-files
|
|
|
|
Like {{{kbd(C-c C-e i)}}}, but do this for all files in ~org-agenda-files~. For each of these files, a separate iCalendar file
|
|
will be written.
|
|
|
|
- {{{kbd(C-c C-e c)}}}, ~org-export-icalendar-combine-agenda-files~ ::
|
|
#+kindex: C-c C-e c
|
|
#+vindex: org-combined-agenda-icalendar-file
|
|
|
|
Create a single large iCalendar file from all files in ~org-agenda-files~ and write it to the file given by ~org-combined-agenda-icalendar-file~.
|
|
|
|
|
|
#+vindex: org-use-property-inheritance
|
|
#+vindex: org-icalendar-include-body
|
|
#+cindex: property, SUMMARY
|
|
#+cindex: property, DESCRIPTION
|
|
#+cindex: property, LOCATION
|
|
|
|
The export will honor SUMMARY, DESCRIPTION and LOCATION properties if
|
|
the selected entries have them.[fn:145] If not, the summary will be
|
|
derived from the headline, and the description from the body (limited
|
|
to ~org-icalendar-include-body~ characters).
|
|
|
|
How this calendar is best read and updated, depends on the application
|
|
you are using. The FAQ covers this issue.
|
|
|
|
* Publishing
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Create a web site of linked Org files
|
|
:END:
|
|
#+cindex: publishing
|
|
#+cindex: O'Toole, David
|
|
|
|
Org includes a publishing management system that allows you to
|
|
configure automatic HTML conversion of /projects/ composed of
|
|
interlinked org files. You can also configure Org to automatically
|
|
upload your exported HTML pages and related attachments, such as
|
|
images and source code files, to a web server.
|
|
|
|
You can also use Org to convert files into PDF, or even combine HTML
|
|
and PDF conversion so that files are available in both formats on the
|
|
server.
|
|
|
|
Publishing has been contributed to Org by David O'Toole.
|
|
|
|
** Configuration
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Defining projects
|
|
:END:
|
|
Publishing needs significant configuration to specify files,
|
|
destination and many other properties of a project.
|
|
|
|
*** Project alist
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The central configuration variable
|
|
:TITLE: The variable ~org-publish-project-alist~
|
|
:END:
|
|
#+cindex: org-publish-project-alist
|
|
#+cindex: projects, for publishing
|
|
#+vindex: org-publish-project-alist
|
|
|
|
Publishing is configured almost entirely through setting the value of
|
|
one variable, called ~org-publish-project-alist~. Each element of the
|
|
list configures one project, and may be in one of the two following
|
|
forms:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
("project-name" :property value :property value ...)
|
|
#+end_src
|
|
|
|
i.e., a well-formed property list with alternating keys and values,
|
|
or:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
("project-name" :components ("project-name" "project-name" ...))
|
|
#+end_src
|
|
|
|
In both cases, projects are configured by specifying property values.
|
|
A project defines the set of files that will be published, as well as
|
|
the publishing configuration to use when publishing those files. When
|
|
a project takes the second form listed above, the individual members
|
|
of the ~:components~ property are taken to be sub-projects, which
|
|
group together files requiring different publishing options. When you
|
|
publish such a "meta-project," all the components will also be
|
|
published, in the sequence given.
|
|
|
|
*** Sources and destinations
|
|
:PROPERTIES:
|
|
:DESCRIPTION: From here to there
|
|
:TITLE: Sources and destinations for files
|
|
:END:
|
|
#+cindex: directories, for publishing
|
|
|
|
Most properties are optional, but some should always be set. In
|
|
particular, Org needs to know where to look for source files, and
|
|
where to put published files.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:base-directory~ ::
|
|
|
|
Directory containing publishing source files
|
|
|
|
- ~:publishing-directory~ ::
|
|
|
|
Directory where output files will be published. You can directly
|
|
publish to a webserver using a file name syntax appropriate for the
|
|
Emacs {{{file(tramp)}}} package. Or you can publish to a local
|
|
directory and use external tools to upload your website
|
|
(see [[Uploading files]]).
|
|
|
|
- ~:preparation-function~ ::
|
|
|
|
Function or list of functions to be called before starting the
|
|
publishing process, for example, to run ~make~ for updating files to
|
|
be published. The project property list is scoped into this call as
|
|
the variable ~project-plist~.
|
|
|
|
- ~:completion-function~ ::
|
|
|
|
Function or list of functions called after finishing the publishing
|
|
process, for example, to change permissions of the resulting files.
|
|
The project property list is scoped into this call as the variable ~project-plist~.
|
|
|
|
*** Selecting files
|
|
:PROPERTIES:
|
|
:DESCRIPTION: What files are part of the project?
|
|
:END:
|
|
#+cindex: files, selecting for publishing
|
|
|
|
By default, all files with extension {{{file(.org)}}} in the base directory
|
|
are considered part of the project. This can be modified by setting the
|
|
following properties:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:base-extension~ ::
|
|
|
|
Extension (without the dot!) of source files. This actually is a
|
|
regular expression. Set this to the symbol ~any~ if you want to get
|
|
all files in ~:base-directory~, even without extension.
|
|
|
|
- ~:exclude~ ::
|
|
|
|
Regular expression to match file names that should not be published,
|
|
even though they have been selected on the basis of their extension.
|
|
|
|
- ~:include~ ::
|
|
|
|
List of files to be included regardless of ~:base-extension~ and ~:exclude~.
|
|
|
|
- ~:recursive~ ::
|
|
|
|
Non-nil means, check base-directory recursively for files to publish.
|
|
|
|
*** Publishing action
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Setting the function doing the publishing
|
|
:END:
|
|
#+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
|
|
~org-publish-org-to-html~ which calls the HTML exporter (see [[HTML
|
|
export]]). But you also can publish your content as PDF files using
|
|
~org-publish-org-to-pdf~, or as ~ascii~, ~latin1~ or
|
|
~utf8~ encoded files using the corresponding functions. If you want to
|
|
publish the Org file itself, but with /archived/, /commented/, and
|
|
/tag-excluded/ trees removed, use ~org-publish-org-to-org~ and set the
|
|
parameters ~:plain-source~ and/or ~:htmlized-source~. This will
|
|
produce {{{file(file.org)}}} and {{{file(file.org.html)}}} in the publishing
|
|
directory.[fn:146] Other files like images only need to be copied to the
|
|
publishing destination; for this you may use ~org-publish-attachment~.
|
|
For non-Org files, you always need to specify the publishing function:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:publishing-function~ ::
|
|
|
|
Function executing the publication of a file. This may also be a list
|
|
of functions, which will all be called in turn.
|
|
|
|
- ~:plain-source~ ::
|
|
|
|
Non-nil means, publish plain source.
|
|
|
|
- ~:htmlized-source~ ::
|
|
|
|
Non-nil means, publish htmlized source.
|
|
|
|
|
|
The function must accept three arguments: a property list containing
|
|
at least a ~:publishing-directory~ property, the name of the file to
|
|
be published, and the path to the publishing directory of the output
|
|
file. It should take the specified file, make the necessary
|
|
transformation (if any) and place the result into the destination
|
|
folder.
|
|
|
|
*** Publishing options
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Tweaking HTML/LaTeX export
|
|
:END:
|
|
#+cindex: options, for publishing
|
|
|
|
The property list can be used to set many export options for the HTML
|
|
and LaTeX exporters. In most cases, these properties correspond to user
|
|
variables in Org. The table below lists these properties along
|
|
with the variable they belong to. See the documentation string for the
|
|
respective variable for details.
|
|
|
|
#+vindex: org-export-html-link-up
|
|
#+vindex: org-export-html-link-home
|
|
#+vindex: org-export-default-language
|
|
#+vindex: org-display-custom-times
|
|
#+vindex: org-export-headline-levels
|
|
#+vindex: org-export-with-section-numbers
|
|
#+vindex: org-export-section-number-format
|
|
#+vindex: org-export-with-toc
|
|
#+vindex: org-export-preserve-breaks
|
|
#+vindex: org-export-with-archived-trees
|
|
#+vindex: org-export-with-emphasize
|
|
#+vindex: org-export-with-sub-superscripts
|
|
#+vindex: org-export-with-special-strings
|
|
#+vindex: org-export-with-footnotes
|
|
#+vindex: org-export-with-drawers
|
|
#+vindex: org-export-with-tags
|
|
#+vindex: org-export-with-todo-keywords
|
|
#+vindex: org-export-with-tasks
|
|
#+vindex: org-export-with-done-tasks
|
|
#+vindex: org-export-with-priority
|
|
#+vindex: org-export-with-TeX-macros
|
|
#+vindex: org-export-with-LaTeX-fragments
|
|
#+vindex: org-export-skip-text-before-1st-heading
|
|
#+vindex: org-export-with-fixed-width
|
|
#+vindex: org-export-with-timestamps
|
|
#+vindex: org-export-author-info
|
|
#+vindex: org-export-email-info
|
|
#+vindex: org-export-creator-info
|
|
#+vindex: org-export-time-stamp-file
|
|
#+vindex: org-export-with-tables
|
|
#+vindex: org-export-highlight-first-table-line
|
|
#+vindex: org-export-html-style-include-default
|
|
#+vindex: org-export-html-style-include-scripts
|
|
#+vindex: org-export-html-style
|
|
#+vindex: org-export-html-style-extra
|
|
#+vindex: org-export-html-link-org-files-as-html
|
|
#+vindex: org-export-html-inline-images
|
|
#+vindex: org-export-html-extension
|
|
#+vindex: org-export-html-table-tag
|
|
#+vindex: org-export-html-expand
|
|
#+vindex: org-export-html-with-timestamp
|
|
#+vindex: org-export-publishing-directory
|
|
#+vindex: org-export-html-preamble
|
|
#+vindex: org-export-html-postamble
|
|
#+vindex: user-full-name
|
|
#+vindex: user-mail-address
|
|
#+vindex: org-export-select-tags
|
|
#+vindex: org-export-exclude-tags
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:link-up~ :: ~org-export-html-link-up~
|
|
- ~:link-home~ :: ~org-export-html-link-home~
|
|
- ~:language~ :: ~org-export-default-language~
|
|
- ~:customtime~ :: ~org-display-custom-times~
|
|
- ~:headline-levels~ :: ~org-export-headline-levels~
|
|
- ~:section-numbers~ :: ~org-export-with-section-numbers~
|
|
- ~:section-number-format~ :: ~org-export-section-number-format~
|
|
- ~:table-of-contents~ :: ~org-export-with-toc~
|
|
- ~:preserve-breaks~ :: ~org-export-preserve-breaks~
|
|
- ~:archived-trees~ :: ~org-export-with-archived-trees~
|
|
- ~:emphasize~ :: ~org-export-with-emphasize~
|
|
- ~:sub-superscript~ :: ~org-export-with-sub-superscripts~
|
|
- ~:special-strings~ :: ~org-export-with-special-strings~
|
|
- ~:footnotes~ :: ~org-export-with-footnotes~
|
|
- ~:drawers~ :: ~org-export-with-drawers~
|
|
- ~:tags~ :: ~org-export-with-tags~
|
|
- ~:todo-keywords~ :: ~org-export-with-todo-keywords~
|
|
- ~:tasks~ :: ~org-export-with-tasks~
|
|
- ~:priority~ :: ~org-export-with-priority~
|
|
- ~:TeX-macros~ :: ~org-export-with-TeX-macros~
|
|
- ~:LaTeX-fragments~ :: ~org-export-with-LaTeX-fragments~
|
|
- ~:latex-listings~ :: ~org-export-latex-listings~
|
|
- ~:skip-before-1st-heading~ :: ~org-export-skip-text-before-1st-heading~
|
|
- ~:fixed-width~ :: ~org-export-with-fixed-width~
|
|
- ~:timestamps~ :: ~org-export-with-timestamps~
|
|
- ~:author~ :: ~user-full-name~
|
|
- ~:email~ :: ~user-mail-address~ : ~addr;addr;..~
|
|
- ~:author-info~ :: ~org-export-author-info~
|
|
- ~:email-info~ :: ~org-export-email-info~
|
|
- ~:creator-info~ :: ~org-export-creator-info~
|
|
- ~:tables~ :: ~org-export-with-tables~
|
|
- ~:table-auto-headline~ :: ~org-export-highlight-first-table-line~
|
|
- ~:style-include-default~ :: ~org-export-html-style-include-default~
|
|
- ~:style-include-scripts~ :: ~org-export-html-style-include-scripts~
|
|
- ~:style~ :: ~org-export-html-style~
|
|
- ~:style-extra~ :: ~org-export-html-style-extra~
|
|
- ~:convert-org-links~ :: ~org-export-html-link-org-files-as-html~
|
|
- ~:inline-images~ :: ~org-export-html-inline-images~
|
|
- ~:html-extension~ :: ~org-export-html-extension~
|
|
- ~:html-preamble~ :: ~org-export-html-preamble~
|
|
- ~:html-postamble~ :: ~org-export-html-postamble~
|
|
- ~:xml-declaration~ :: ~org-export-html-xml-declaration~
|
|
- ~:html-table-tag~ :: ~org-export-html-table-tag~
|
|
- ~:expand-quoted-html~ :: ~org-export-html-expand~
|
|
- ~:timestamp~ :: ~org-export-html-with-timestamp~
|
|
- ~:publishing-directory~ :: ~org-export-publishing-directory~
|
|
- ~:select-tags~ :: ~org-export-select-tags~
|
|
- ~:exclude-tags~ :: ~org-export-exclude-tags~
|
|
- ~:latex-image-options~ :: ~org-export-latex-image-default-option~
|
|
|
|
|
|
Most of the ~org-export-with-*~ variables have the same effect in both
|
|
HTML and LaTeX exporters, except for ~:TeX-macros~ and
|
|
~:LaTeX-fragments~ options, respectively ~nil~ and ~t~ in the LaTeX
|
|
export. See ~org-export-plist-vars~ to check this list of options.
|
|
|
|
#+vindex: org-publish-project-alist
|
|
|
|
When a property is given a value in ~org-publish-project-alist~, its
|
|
setting overrides the value of the corresponding user variable (if
|
|
any) during publishing. Options set within a file (see [[Export
|
|
options]]), however, override everything.
|
|
|
|
*** Publishing links
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Which links keep working after publishing?
|
|
:END:
|
|
#+cindex: links, publishing
|
|
|
|
To create a link from one Org file to another, you would use something
|
|
like ~[[file:foo.org][The foo]]~ or simply ~[[file:foo.org]]~ (see
|
|
[[Hyperlinks]]). When published, this link becomes a link to
|
|
{{{file(foo.html)}}}. In this way, you can interlink the pages of your
|
|
"org web" project and the links will work as expected when you publish
|
|
them to HTML. If you also publish the Org source file and want to link
|
|
to that, use an ~http:~ link instead of a ~file:~ link, because
|
|
~file:~ links are converted to link to the corresponding
|
|
{{{file(html)}}} file.
|
|
|
|
You may also link to related files, such as images. Provided you are
|
|
careful with relative file names, and provided you have also
|
|
configured Org to upload the related files, these links will work too.
|
|
See [[Complex example]], for an example of this usage.
|
|
|
|
Sometimes an Org file to be published may contain links that are only
|
|
valid in your production environment, but not in the publishing
|
|
location. In this case, use the following property to define a
|
|
function for checking link validity:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:link-validation-function~ ::
|
|
Function to validate links
|
|
|
|
|
|
{{{noindent}}} This function must accept two arguments, the file name
|
|
and a directory relative to which the file name is interpreted in the
|
|
production environment. If this function returns ~nil~, then the HTML
|
|
generator will only insert a description into the HTML file, but no
|
|
link. One option for this function is ~org-publish-validate-link~
|
|
which checks if the given file is part of any project in
|
|
~org-publish-project-alist~.
|
|
|
|
*** Site map
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Generating a list of all pages
|
|
:TITLE: Generating a sitemap
|
|
:END:
|
|
#+cindex: sitemap, of published pages
|
|
|
|
The following properties may be used to control publishing of
|
|
a map of files for a given project.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:auto-sitemap~ ::
|
|
|
|
When non-nil, publish a sitemap during ~org-publish-current-project~
|
|
or ~org-publish-all~.
|
|
|
|
- ~:sitemap-filename~ ::
|
|
|
|
Filename for output of sitemap. Defaults to {{{file(sitemap.org)}}} (which
|
|
becomes {{{file(sitemap.html)}}}).
|
|
|
|
- ~:sitemap-title~ ::
|
|
|
|
Title of sitemap page. Defaults to name of file.
|
|
|
|
- ~:sitemap-function~ ::
|
|
|
|
Plug-in function to use for generation of the sitemap. Defaults to ~org-publish-org-sitemap~, which generates a plain list of links to
|
|
all files in the project.
|
|
|
|
- ~:sitemap-sort-folders~ ::
|
|
|
|
Where folders should appear in the sitemap. Set this to ~first~
|
|
(default) or ~last~ to display folders first or last, respectively.
|
|
Any other value will mix files and folders.
|
|
|
|
- ~:sitemap-sort-files~ ::
|
|
|
|
How the files are sorted in the site map. Set this to ~alphabetically~
|
|
(default), ~chronologically~ or ~anti-chronologically~. ~chronologically~ sorts the files with older date first while ~anti-chronologically~ sorts the files with newer date first. ~alphabetically~ sorts the files alphabetically. The date of a file is
|
|
retrieved with ~org-publish-find-date~.
|
|
|
|
- ~:sitemap-ignore-case~ ::
|
|
|
|
Should sorting be case-sensitive? Default ~nil~.
|
|
|
|
- ~:sitemap-file-entry-format~ ::
|
|
|
|
With this option one can tell how a sitemap's entry is formatted in
|
|
the sitemap. This is a format string with some escape sequences: ~%t~
|
|
stands for the title of the file, ~%a~ stands for the author of the
|
|
file and ~%d~ stands for the date of the file. The date is retrieved
|
|
with the ~org-publish-find-date~ function and formatted with ~org-publish-sitemap-date-format~. Default ~%t~.
|
|
|
|
- ~:sitemap-date-format~ ::
|
|
|
|
Format string for the ~format-time-string~ function that tells how a
|
|
sitemap entry's date is to be formatted. This property bypasses ~org-publish-sitemap-date-format~ which defaults to ~%Y-%m-%d~.
|
|
|
|
- ~:sitemap-sans-extension~ ::
|
|
|
|
When non-nil, remove filenames' extensions from the generated sitemap.
|
|
Useful to have cool URIs (see [[http://www.w3.org/Provider/Style/URI]]).
|
|
Defaults to ~nil~.
|
|
|
|
*** Generating an index
|
|
:PROPERTIES:
|
|
:DESCRIPTION: An index that reaches across pages
|
|
:END:
|
|
#+cindex: index, in a publishing project
|
|
|
|
Org mode can generate an index across the files of a publishing project.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:makeindex~ ::
|
|
|
|
When non-nil, generate in index in the file {{{file(theindex.org)}}}
|
|
and publish it as {{{file(theindex.html)}}}.
|
|
|
|
|
|
The file will be created when first publishing a project with the
|
|
~:makeindex~ set. The file only contains a statement
|
|
{{{samp(#+INCLUDE: "theindex.inc")}}}. You can then build around this
|
|
include statement by adding a title, style information, etc.
|
|
|
|
** Uploading files
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to get files up on the server
|
|
:END:
|
|
#+cindex: rsync
|
|
#+cindex: unison
|
|
|
|
For those people already utilizing third party sync tools such as
|
|
{{{command(rsync)}}} or {{{command(unison)}}}, it might be preferable
|
|
not to use the built in remote publishing facilities of Org mode
|
|
which rely heavily on Tramp. Tramp, while very useful and powerful,
|
|
tends not to be so efficient for multiple file transfer and has been
|
|
known to cause problems under heavy usage.
|
|
|
|
Specialized synchronization utilities offer several advantages. In
|
|
addition to timestamp comparison, they also do content and
|
|
permissions/attribute checks. For this reason you might prefer to
|
|
publish your web to a local directory (possibly even in place with
|
|
your Org files) and then use {{{file(unison)}}} or {{{file(rsync)}}}
|
|
to do the synchronization with the remote host.
|
|
|
|
Since Unison (for example) can be configured as to which files to
|
|
transfer to a certain remote destination, it can greatly simplify the
|
|
project publishing definition. Simply keep all files in the correct
|
|
location, process your Org files with ~org-publish~ and let the
|
|
synchronization tool do the rest. You do not need, in this scenario,
|
|
to include attachments such as {{{file(jpg)}}}, {{{file(css)}}} or
|
|
{{{file(gif)}}} files in the project definition since the 3rd party
|
|
tool syncs them.
|
|
|
|
Publishing to a local directory is also much faster than to a remote
|
|
one, so that you can afford more easily to republish entire projects.
|
|
If you set ~org-publish-use-timestamps-flag~ to ~nil~, you gain the
|
|
main benefit of re-including any changed external files such as source
|
|
example files you might include with ~#+INCLUDE:~. The timestamp
|
|
mechanism in Org is not smart enough to detect if included files have
|
|
been modified.
|
|
|
|
** Sample configuration
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Example projects
|
|
:END:
|
|
Below we provide two example configurations. The first one is a simple
|
|
project publishing only a set of Org files. The second example is
|
|
more complex, with a multi-component project.
|
|
|
|
*** Simple example
|
|
:PROPERTIES:
|
|
:DESCRIPTION: One-component publishing
|
|
:TITLE: Example: simple publishing configuration
|
|
:END:
|
|
This example publishes a set of Org files to the {{{file(public_html)}}}
|
|
directory on the local machine.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-publish-project-alist
|
|
'(("org"
|
|
:base-directory "~/org/"
|
|
:publishing-directory "~/public_html"
|
|
:section-numbers nil
|
|
:table-of-contents nil
|
|
:style "<link rel=\"stylesheet\"
|
|
href=\"../other/mystyle.css\"
|
|
type=\"text/css\"/>")))
|
|
#+end_src
|
|
|
|
*** Complex example
|
|
:PROPERTIES:
|
|
:DESCRIPTION: A multi-component publishing example
|
|
:TITLE: Example: complex publishing configuration
|
|
:END:
|
|
This more complicated example publishes an entire website, including
|
|
Org files converted to HTML, image files, Emacs Lisp source code, and
|
|
style sheets. The publishing directory is remote and private files are
|
|
excluded.
|
|
|
|
To ensure that links are preserved, care should be taken to replicate
|
|
your directory structure on the web server, and to use relative file
|
|
paths. For example, if your Org files are kept in {{{file(~/org)}}}
|
|
and your publishable images in {{{file(~/images)}}}, you would link to
|
|
an image with
|
|
|
|
#+begin_example
|
|
file:../images/myimage.png
|
|
#+end_example
|
|
|
|
On the web server, the relative path to the image should be the
|
|
same. You can accomplish this by setting up an "images" folder in the
|
|
right place on the web server, and publishing images to it.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-publish-project-alist
|
|
'(("orgfiles"
|
|
:base-directory "~/org/"
|
|
:base-extension "org"
|
|
:publishing-directory "/ssh:user@@host:~/html/notebook/"
|
|
:publishing-function org-publish-org-to-html
|
|
:exclude "PrivatePage.org" ;; regexp
|
|
:headline-levels 3
|
|
:section-numbers nil
|
|
:table-of-contents nil
|
|
:style "<link rel=\"stylesheet\"
|
|
href=\"../other/mystyle.css\" type=\"text/css\"/>"
|
|
:html-preamble t)
|
|
|
|
("images"
|
|
:base-directory "~/images/"
|
|
:base-extension "jpg\\|gif\\|png"
|
|
:publishing-directory "/ssh:user@@host:~/html/images/"
|
|
:publishing-function org-publish-attachment)
|
|
|
|
("other"
|
|
:base-directory "~/other/"
|
|
:base-extension "css\\|el"
|
|
:publishing-directory "/ssh:user@@host:~/html/other/"
|
|
:publishing-function org-publish-attachment)
|
|
("website" :components ("orgfiles" "images" "other"))))
|
|
#+end_src
|
|
|
|
** Triggering publication
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Publication commands
|
|
:END:
|
|
Once properly configured, Org can publish with the following commands:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-e X)}}}, ~org-publish~ ::
|
|
#+kindex: C-c C-e X
|
|
|
|
Prompt for a specific project and publish all files that belong to it.
|
|
|
|
- {{{kbd(C-c C-e P)}}}, ~org-publish-current-project~ ::
|
|
#+kindex: C-c C-e P
|
|
|
|
Publish the project containing the current file.
|
|
|
|
- {{{kbd(C-c C-e F)}}}, ~org-publish-current-file~ ::
|
|
#+kindex: C-c C-e F
|
|
|
|
Publish only the current file.
|
|
|
|
- {{{kbd(C-c C-e E)}}}, ~org-publish-all~ ::
|
|
#+kindex: C-c C-e E
|
|
|
|
Publish every project.
|
|
|
|
|
|
#+vindex: org-publish-use-timestamps-flag
|
|
|
|
Org uses timestamps to track when a file has changed. The above
|
|
functions normally only publish changed files. You can override this
|
|
and force publishing of all files by giving a prefix argument to any
|
|
of the commands above, or by customizing the variable
|
|
~org-publish-use-timestamps-flag~. This may be necessary in particular
|
|
if files include other files via ~#+SETUPFILE:~ or ~#+INCLUDE:~.
|
|
|
|
* Working with source code
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Export, evaluate, and tangle code blocks
|
|
:ALT_TITLE: Working With Source Code
|
|
:END:
|
|
#+cindex: Schulte, Eric
|
|
#+cindex: Davison, Dan
|
|
#+cindex: source code, working with
|
|
|
|
Source code can be included in Org mode documents using a
|
|
{{{samp(src)}}} block, e.g.:
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC emacs-lisp
|
|
(defun org-xor (a b)
|
|
"Exclusive or."
|
|
(if a (not b) b))
|
|
#+END_SRC
|
|
#+end_example
|
|
|
|
Org mode provides a number of features for working with live source
|
|
code, including editing of code blocks in their native major-mode,
|
|
evaluation of code blocks, converting code blocks into source files
|
|
(known as "tangling" in literate programming), and exporting code
|
|
blocks and their results in several formats. This functionality was
|
|
contributed by Eric Schulte and Dan Davison, and was originally named
|
|
Org-babel.
|
|
|
|
The following sections describe Org mode's code block handling facilities.
|
|
|
|
** Structure of code blocks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Code block syntax described
|
|
:END:
|
|
#+cindex: code block, structure
|
|
#+cindex: source code, block structure
|
|
#+cindex: #+NAME
|
|
#+cindex: #+BEGIN_SRC
|
|
|
|
Live code blocks can be specified with a {{{samp(src)}}} block or
|
|
inline.[fn:147] The structure of a {{{samp(src)}}} block is shown in
|
|
the following example:
|
|
|
|
#+begin_example
|
|
,#+NAME: <name>
|
|
,#+BEGIN_SRC <language> <switches> <header arguments>
|
|
<body>
|
|
,#+END_SRC
|
|
#+end_example
|
|
|
|
The ~#+NAME:~ line is optional, and can be used to name the code
|
|
block. Live code blocks require that a language be specified on the
|
|
~#+BEGIN_SRC~ line. Switches and header arguments are optional.
|
|
#+cindex: source code, inline
|
|
|
|
Live code blocks can also be specified inline using the following
|
|
syntax:
|
|
|
|
#+begin_example
|
|
src_<language>{<body>}
|
|
#+end_example
|
|
|
|
or
|
|
|
|
#+begin_example
|
|
src_<language>[<header arguments>]{<body>}
|
|
#+end_example
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~<#+NAME: name>~ ::
|
|
#+cindex: #+NAME
|
|
|
|
This line associates a name with the code block. This is similar to
|
|
the ~#+TBLNAME: NAME~ lines that can be used to name tables in Org
|
|
mode files. Referencing the name of a code block makes it possible to
|
|
evaluate the block from other places in the file, from other files, or
|
|
from Org mode table formulas (see [[The spreadsheet]]). Names are assumed
|
|
to be unique and the behavior of Org mode when two or more blocks
|
|
share the same name is undefined.
|
|
|
|
- ~<language>~ ::
|
|
#+cindex: source code, language
|
|
|
|
The language of the code in the block (see [[Languages]]).
|
|
|
|
- ~<switches>~ ::
|
|
#+cindex: source code, switches
|
|
|
|
Optional switches control code block export (see the discussion of
|
|
switches in [[Literal examples]]).
|
|
|
|
- ~<header arguments>~ ::
|
|
#+cindex: source code, header arguments
|
|
|
|
Optional header arguments control many aspects of evaluation, export
|
|
and tangling of code blocks (see [[Header arguments]]). Header arguments
|
|
can also be set on a per-buffer or per-subtree basis using properties.
|
|
|
|
- ~<body>~ ::
|
|
|
|
Source code in the specified language.
|
|
|
|
** Editing source code
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Language major-mode editing
|
|
:END:
|
|
#+cindex: code block, editing
|
|
#+cindex: source code, editing
|
|
#+kindex: C-c '
|
|
|
|
Use {{{kbd(C-c ')}}} to edit the current code block. This brings up a
|
|
language major-mode edit buffer containing the body of the code block.
|
|
Saving this buffer will write the new contents back to the Org buffer.
|
|
Use {{{kbd(C-c ')}}} again to exit.
|
|
|
|
The ~org-src-mode~ minor mode will be active in the edit buffer. The
|
|
following variables can be used to configure the behavior of the edit
|
|
buffer. See also the customization group ~org-edit-structure~ for
|
|
further configuration options.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~org-src-lang-modes~ ::
|
|
|
|
If an Emacs major-mode named ~<lang>-mode~ exists, where ~<lang>~ is the language named in the header line of the code block,
|
|
then the edit buffer will be placed in that major-mode. This variable
|
|
can be used to map arbitrary language names to existing major modes.
|
|
|
|
- ~org-src-window-setup~ ::
|
|
|
|
Controls the way Emacs windows are rearranged when the edit buffer is
|
|
created.
|
|
|
|
- ~org-src-preserve-indentation~ ::
|
|
|
|
This variable is especially useful for tangling languages such as
|
|
Python, in which whitespace indentation in the output is meaningful.
|
|
|
|
- ~org-src-ask-before-returning-to-edit-buffer~ ::
|
|
|
|
By default, Org will ask before returning to an open edit buffer. Set this
|
|
variable to nil to switch without asking.
|
|
|
|
|
|
To turn on native code fontification in the Org mode buffer, configure
|
|
the variable ~org-src-fontify-natively~.
|
|
|
|
** Exporting code blocks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Export contents and/or results
|
|
:END:
|
|
#+cindex: code block, exporting
|
|
#+cindex: source code, exporting
|
|
|
|
It is possible to export the /code/ of code blocks, the /results/ of
|
|
code block evaluation, /both/ the code and the results of code block
|
|
evaluation, or /none/. For most languages, the default exports code.
|
|
However, for some languages (e.g., ~ditaa~) the default exports the
|
|
results of code block evaluation. For information on exporting code
|
|
block bodies, see [[Literal examples]].
|
|
|
|
The ~:exports~ header argument can be used to specify export
|
|
behavior with the following arguments:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:exports code~ ::
|
|
|
|
The default in most languages. The body of the code block is exported, as
|
|
described in [[Literal examples]].
|
|
|
|
- ~:exports results~ ::
|
|
|
|
The code block will be evaluated and the results will be placed in the
|
|
Org mode buffer for export, either updating previous results of the
|
|
code block located anywhere in the buffer or, if no previous results
|
|
exist, placing the results immediately after the code block. The body
|
|
of the code block will not be exported.
|
|
|
|
- ~:exports both~ ::
|
|
|
|
Both the code block and its results will be exported.
|
|
|
|
- ~:exports none~ ::
|
|
|
|
Neither the code block nor its results will be exported.
|
|
|
|
|
|
It is possible to inhibit the evaluation of code blocks during export.
|
|
Setting the ~org-export-babel-evaluate~ variable to ~nil~ will ensure
|
|
that no code blocks are evaluated as part of the export process. This
|
|
can be useful in situations where potentially untrusted Org mode files
|
|
are exported in an automated fashion, for example when Org mode is
|
|
used as the markup language for a wiki.
|
|
|
|
** Extracting source code
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Create pure source code files
|
|
:END:
|
|
#+cindex: tangling
|
|
#+cindex: source code, extracting
|
|
#+cindex: code block, extracting source code
|
|
|
|
Creating pure source code files by extracting code from source blocks
|
|
is referred to as "tangling"---a term adopted from the literate
|
|
programming community. During tangling of code blocks their bodies are
|
|
expanded using ~org-babel-expand-src-block~ which can expand both
|
|
variable and ``noweb'' style references (see [[Noweb reference syntax]]).
|
|
|
|
*** Header arguments for tangling
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:tangle no~ ::
|
|
|
|
The default. The code block is not included in the tangled output.
|
|
|
|
- ~:tangle yes~ ::
|
|
|
|
Include the code block in the tangled output. The output file name is
|
|
the name of the org file with the extension {{{samp(.org)}}} replaced
|
|
by the extension for the block language.
|
|
|
|
- ~:tangle filename~ ::
|
|
|
|
Include the code block in the tangled output to file {{{samp(filename)}}}.
|
|
|
|
*** Functions for tangling
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~org-babel-tangle~ ::
|
|
#+kindex: C-c C-v t
|
|
|
|
Tangle the current file. Bound to {{{kbd(C-c C-v t)}}}.
|
|
|
|
With a prefix argument only tangle the current code block.
|
|
|
|
- ~org-babel-tangle-file~ ::
|
|
#+kindex: C-c C-v f
|
|
|
|
Choose a file to tangle. Bound to {{{kbd(C-c C-v f)}}}.
|
|
|
|
*** Hooks for tangling
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~org-babel-post-tangle-hook~ ::
|
|
|
|
This hook is run from within code files tangled by ~org-babel-tangle~.
|
|
Example applications could include post-processing, compilation, or
|
|
evaluation of tangled code files.
|
|
|
|
** Evaluating code blocks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Place results in the Org buffer
|
|
:END:
|
|
#+cindex: code block, evaluating
|
|
#+cindex: source code, evaluating
|
|
#+cindex: #+RESULTS
|
|
|
|
Code blocks can be evaluated and the results of evaluation optionally
|
|
placed in the Org mode buffer.[fn:148] The results of evaluation are
|
|
placed following a line that begins by default with ~#+RESULTS~ and
|
|
optionally a cache identifier and/or the name of the evaluated code
|
|
block. The default value of ~#+RESULTS~ can be changed with the
|
|
customizable variable ~org-babel-results-keyword~.
|
|
|
|
By default, the evaluation facility is only enabled for Lisp code
|
|
blocks specified as ~emacs-lisp~. However, source code blocks in many
|
|
languages can be evaluated within Org mode (see [[Languages]] for a list
|
|
of supported languages and [[Structure of code blocks]] for information on
|
|
the syntax used to define a code block).
|
|
|
|
#+kindex: C-c C-c
|
|
#+kindex: C-c C-v e
|
|
|
|
There are a number of ways to evaluate code blocks. The simplest is to
|
|
press {{{kbd(C-c C-c)}}} or {{{kbd(C-c C-v e)}}} with the point on a
|
|
code block.[fn:149] This will call the ~org-babel-execute-src-block~
|
|
function to evaluate the block and insert its results into the Org
|
|
mode buffer.
|
|
|
|
#+cindex: #+CALL
|
|
|
|
It is also possible to evaluate named code blocks from anywhere in an
|
|
Org mode buffer or an Org mode table. Live code blocks located in the
|
|
current Org mode buffer or in the ``Library of Babel'' (see [[Library of
|
|
Babel]]) can be executed. Named code blocks can be executed with a
|
|
separate ~#+CALL:~ line or inline within a block of text.
|
|
|
|
The syntax of the ~#+CALL:~ line is:
|
|
|
|
#+begin_example
|
|
,#+CALL: <name>(<arguments>)
|
|
,#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
|
|
#+end_example
|
|
|
|
The syntax for inline evaluation of named code blocks is:
|
|
|
|
#+begin_example
|
|
... call_<name>(<arguments>) ...
|
|
... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
|
|
#+end_example
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~<name>~ ::
|
|
|
|
The name of the code block to be evaluated (see [[Structure of code
|
|
blocks]]).
|
|
|
|
- ~<arguments>~ ::
|
|
|
|
Arguments specified in this section will be passed to the code block.
|
|
These arguments use standard function call syntax, rather than header
|
|
argument syntax. For example, a ~#+CALL:~ line that passes the number
|
|
four to a code block named ~double~, which declares the header
|
|
argument ~:var n=2~, would be written as ~#+CALL: double(n=4)~.
|
|
|
|
- ~<inside header arguments>~ ::
|
|
|
|
Inside header arguments are passed through and applied to the named
|
|
code block. These arguments use header argument syntax rather than
|
|
standard function call syntax. Inside header arguments affect how the
|
|
code block is evaluated. For example, ~[:results output]~ will collect
|
|
the results of everything printed to ~STDOUT~ during execution of the
|
|
code block.
|
|
|
|
- ~<end header arguments>~ ::
|
|
|
|
End header arguments are applied to the calling instance and do not
|
|
affect evaluation of the named code block. They affect how the results
|
|
are incorporated into the Org mode buffer and how the call line is
|
|
exported. For example, ~:results html~ will insert the results of the
|
|
call line evaluation in the Org buffer, wrapped in a ~BEGIN_HTML:~
|
|
block.
|
|
|
|
|
|
For more examples of passing header arguments to ~#+CALL:~ lines see
|
|
[[Header arguments in function calls]].
|
|
|
|
** Library of Babel
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Use and contribute to a source code library
|
|
:END:
|
|
#+cindex: babel, library of
|
|
#+cindex: source code, library
|
|
#+cindex: code block, library
|
|
|
|
The ``Library of Babel'' consists of code blocks that can be called
|
|
from any Org mode file. Code blocks defined in the ``Library of
|
|
Babel'' can be called remotely as if they were in the current Org mode
|
|
buffer (see [[Evaluating code blocks]] for information on the syntax of
|
|
remote code block evaluation).
|
|
|
|
|
|
The central repository of code blocks in the ``Library of Babel'' is
|
|
housed in an Org mode file located in the {{{samp(contrib)}}}
|
|
directory of Org mode.
|
|
|
|
Users can add code blocks they believe to be generally useful to their
|
|
``Library of Babel.'' The code blocks can be stored in any Org mode
|
|
file and then loaded into the library with ~org-babel-lob-ingest~.
|
|
|
|
#+kindex: C-c C-v i
|
|
|
|
Code blocks located in any Org mode file can be loaded into the
|
|
``Library of Babel'' with the ~org-babel-lob-ingest~ function, bound
|
|
to {{{kbd(C-c C-v i)}}}.
|
|
|
|
** Languages
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Supported code block languages
|
|
:END:
|
|
#+cindex: babel, languages
|
|
#+cindex: source code, languages
|
|
#+cindex: code block, languages
|
|
|
|
Code blocks in the following languages are supported.
|
|
|
|
#+attr_texinfo: :columns 0.24 0.24 0.04 0.24 0.24
|
|
| Language | Identifier | | Language | Identifier |
|
|
|------------+--------------+---+----------------+--------------|
|
|
| Asymptote | asymptote | | Awk | awk |
|
|
| Emacs Calc | calc | | C | C |
|
|
| C++ | C++ | | Clojure | clojure |
|
|
| CSS | css | | ditaa | ditaa |
|
|
| Graphviz | dot | | Emacs Lisp | emacs-lisp |
|
|
| gnuplot | gnuplot | | Haskell | haskell |
|
|
| Java | java | | | |
|
|
| Javascript | js | | LaTeX | latex |
|
|
| Ledger | ledger | | Lisp | lisp |
|
|
| Lilypond | lilypond | | MATLAB | matlab |
|
|
| Mscgen | mscgen | | Objective Caml | ocaml |
|
|
| Octave | octave | | Org mode | org |
|
|
| Oz | oz | | Perl | perl |
|
|
| Plantuml | plantuml | | Python | python |
|
|
| R | R | | Ruby | ruby |
|
|
| Sass | sass | | Scheme | scheme |
|
|
| GNU Screen | screen | | shell | sh |
|
|
| SQL | sql | | SQLite | sqlite |
|
|
|
|
|
|
Language-specific documentation is available for some languages. If
|
|
available, it can be found at
|
|
[[http://orgmode.org/worg/org-contrib/babel/languages.html]].
|
|
|
|
The variable ~org-babel-load-languages~ controls which languages are
|
|
enabled for evaluation (by default only ~emacs-lisp~ is enabled). This
|
|
variable can be set using the customization interface or by adding
|
|
code like the following example, disables ~emacs-lisp~ evaluation and
|
|
enables evaluation of ~R~ code blocks, to your emacs configuration:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(org-babel-do-load-languages
|
|
'org-babel-load-languages
|
|
'((emacs-lisp . nil)
|
|
(R . t)))
|
|
#+end_src
|
|
|
|
It is also possible to enable support for a language by loading the
|
|
related elisp file with ~require~.
|
|
|
|
{{{noindent}}} The following example adds support for evaluating
|
|
~clojure~ code blocks:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(require 'ob-clojure)
|
|
#+end_src
|
|
|
|
** Header arguments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Configure code block functionality
|
|
:END:
|
|
#+cindex: code block, header arguments
|
|
#+cindex: source code, block header arguments
|
|
|
|
Code block functionality can be configured with header arguments. This
|
|
section provides an overview of the use of header arguments, and then
|
|
describes each header argument in detail.
|
|
|
|
*** Using header arguments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Different ways to set header arguments
|
|
:END:
|
|
|
|
The values of header arguments can be set in six different ways, each
|
|
more specific (and having higher priority) than the last.
|
|
|
|
**** System-wide header arguments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Set global default values
|
|
:END:
|
|
#+vindex: org-babel-default-header-args
|
|
|
|
System-wide values of header arguments can be specified by customizing
|
|
the ~org-babel-default-header-args~ variable:
|
|
|
|
#+begin_example
|
|
:session => "none"
|
|
:results => "replace"
|
|
:exports => "code"
|
|
:cache => "no"
|
|
:noweb => "no"
|
|
#+end_example
|
|
|
|
# #+begin_example
|
|
# org-babel-default-header-args is a variable defined in `org-babel.el'.
|
|
# Its value is
|
|
# ((:session . "none")
|
|
# (:results . "replace")
|
|
# (:exports . "code")
|
|
# (:cache . "no")
|
|
# (:noweb . "no"))
|
|
|
|
|
|
# Documentation:
|
|
# Default arguments to use when evaluating a code block.
|
|
# #+end_example
|
|
|
|
For example, the following code could be used to set the default
|
|
value of ~:noweb~ header arguments to ~yes~. This would have the
|
|
effect of expanding ~:noweb~ references by default when evaluating
|
|
source code blocks.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-babel-default-header-args
|
|
(cons '(:noweb . "yes")
|
|
(assq-delete-all :noweb org-babel-default-header-args)))
|
|
#+end_src
|
|
|
|
**** Language-specific header arguments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Set default values by language
|
|
:END:
|
|
|
|
Each language can define its own set of default header arguments. See
|
|
the language-specific documentation available online at
|
|
[[http://orgmode.org/worg/org-contrib/babel]].
|
|
|
|
**** Buffer-wide header arguments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Set default values for a specific buffer
|
|
:END:
|
|
|
|
Buffer-wide header arguments may be specified as properties through
|
|
the use of ~#+PROPERTY:~ lines placed anywhere in an Org mode file
|
|
(see [[Property syntax]]).
|
|
|
|
For example the following would set ~session~ to ~*R*~, and ~results~
|
|
to ~silent~ for every code block in the buffer, ensuring that all
|
|
execution took place in the same session, and no results would be
|
|
inserted into the buffer.
|
|
|
|
#+begin_example
|
|
,#+PROPERTY: session *R*
|
|
,#+PROPERTY: results silent
|
|
#+end_example
|
|
|
|
**** Header arguments in Org mode properties
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Set default values for a buffer or heading
|
|
:END:
|
|
|
|
Header arguments are also read from Org mode properties (see [[Property
|
|
syntax]]), which can be set on a buffer-wide or per-heading basis. An
|
|
example of setting a header argument for all code blocks in a buffer
|
|
is as follows:
|
|
|
|
#+begin_example
|
|
,#+PROPERTY: tangle yes
|
|
#+end_example
|
|
|
|
#+vindex: org-use-property-inheritance
|
|
|
|
When properties are used to set default header arguments, they are
|
|
looked up with inheritance, regardless of the value of
|
|
~org-use-property-inheritance~. In the following example the value of
|
|
the ~:cache~ header argument will default to ~yes~ in all code blocks
|
|
in the subtree rooted at the following heading:
|
|
|
|
#+begin_example
|
|
,* outline header
|
|
,:PROPERTIES:
|
|
,:cache: yes
|
|
,:END:
|
|
#+end_example
|
|
|
|
#+kindex: C-c C-x p
|
|
#+vindex: org-babel-default-header-args
|
|
|
|
Properties defined in this way override the properties set in
|
|
~org-babel-default-header-args~. It is convenient to use the
|
|
~org-set-property~ function bound to {{{kbd(C-c C-x p)}}} to set
|
|
properties in Org mode documents.
|
|
|
|
**** Code block specific header arguments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The most common way to set values
|
|
:END:
|
|
|
|
The most common way to assign values to header arguments is at the
|
|
code block level. This can be done by listing a sequence of header
|
|
arguments and their values as part of the ~#+BEGIN_SRC~ line.
|
|
Properties set in this way override both the values of
|
|
~org-babel-default-header-args~ and header arguments specified as
|
|
properties. In the following example, the ~:results~ header argument
|
|
is set to ~silent~, meaning the results of execution will not be
|
|
inserted in the buffer, and the ~:exports~ header argument is set to
|
|
~code~, meaning only the body of the code block will be preserved on
|
|
export to HTML or LaTeX.
|
|
|
|
#+begin_example
|
|
#+NAME: factorial
|
|
#+BEGIN_SRC haskell :results silent :exports code :var n=0
|
|
fac 0 = 1
|
|
fac n = n * fac (n-1)
|
|
#+END_SRC
|
|
#+end_example
|
|
|
|
Similarly, it is possible to set header arguments for inline code blocks:
|
|
|
|
#+begin_example
|
|
src_haskell[:exports both]@{fac 5@}
|
|
#+end_example
|
|
|
|
Code block header arguments can span multiple lines using ~#+HEADER:~
|
|
or ~#+HEADERS:~ lines preceding a code block or nested between the
|
|
~#+NAME:~ line and the ~#+BEGIN_SRC~ line of a named code block.
|
|
|
|
#+cindex: #+HEADER:
|
|
#+cindex: #+HEADERS:
|
|
|
|
This is an example of multi-line header arguments on an un-named code
|
|
block:
|
|
|
|
#+begin_example
|
|
,#+HEADERS: :var data1=1
|
|
,#+BEGIN_SRC emacs-lisp :var data2=2
|
|
(message "data1:%S, data2:%S" data1 data2)
|
|
,#+END_SRC
|
|
|
|
,#+RESULTS:
|
|
: data1:1, data2:2
|
|
#+end_example
|
|
|
|
This is an example of multi-line header arguments on a named code block:
|
|
|
|
#+begin_example
|
|
,#+NAME: named-block
|
|
,#+HEADER: :var data=2
|
|
,#+BEGIN_SRC emacs-lisp
|
|
(message "data:%S" data)
|
|
,#+END_SRC
|
|
|
|
,#+RESULTS: named-block
|
|
: data:2
|
|
#+end_example
|
|
|
|
**** Header arguments in function calls
|
|
:PROPERTIES:
|
|
:DESCRIPTION: The most specific level
|
|
:END:
|
|
|
|
At the most specific level, header arguments for ``Library of Babel''
|
|
or ~#+CALL:~ lines can be set as shown in the two examples below. For
|
|
more information on the structure of ~#+CALL:~ lines see [[Evaluating
|
|
code blocks]].
|
|
|
|
The following example will apply the ~:exports results~ header
|
|
argument to the evaluation of the ~#+CALL:~ line:
|
|
|
|
#+begin_example
|
|
,#+CALL: factorial(n=5) :exports results
|
|
#+end_example
|
|
|
|
The following example will apply the ~:session special~ header
|
|
argument to the evaluation of the ~factorial~ code block:
|
|
|
|
#+begin_example
|
|
,#+CALL: factorial[:session special](n=5)
|
|
#+end_example
|
|
|
|
*** Specific header arguments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: List of header arguments
|
|
:END:
|
|
Header arguments consist of an initial colon followed by the name of
|
|
the argument in lowercase letters. Additional header arguments are
|
|
defined on a language-specific basis, see [[Languages]].
|
|
|
|
The following header arguments are defined:
|
|
|
|
**** var
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Pass arguments to code blocks
|
|
:END:
|
|
The ~:var~ header argument is used to pass arguments to code blocks.
|
|
The specifics of how arguments are included in a code block vary by
|
|
language; these are addressed in the language-specific documentation.
|
|
However, the syntax used to specify arguments is the same across all
|
|
languages. In every case, variables require a default value when they
|
|
are declared.
|
|
|
|
The values passed to arguments can either be literal values,
|
|
references, or Emacs Lisp code (see [[Emacs Lisp evaluation of
|
|
variables]]). References include anything in the Org mode file that
|
|
takes a ~#+NAME:~, ~#+TBLNAME:~, or ~#+RESULTS:~ line. This includes
|
|
tables, lists, ~#+BEGIN_EXAMPLE~ blocks, other code blocks, and the
|
|
results of other code blocks.
|
|
|
|
Argument values can be indexed in a manner similar to arrays (see
|
|
[[Indexable variable values]]).
|
|
|
|
The following syntax is used to pass arguments to code blocks using the
|
|
~:var~ header argument:
|
|
|
|
#+begin_example
|
|
:var name=assign
|
|
#+end_example
|
|
|
|
The argument, ~assign~, can either be a literal value, such as a
|
|
string {{{samp("string")}}} or a number {{{samp(9)}}}, or a reference
|
|
to a table, a list, a literal example, another code block (with or
|
|
without arguments), or the results of evaluating another code block.
|
|
|
|
Here are examples of passing values by reference:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- a table named with either ~#+NAME:~ or ~#+TBLNAME:~ ::
|
|
|
|
#+begin_example
|
|
#+TBLNAME: example-table
|
|
| 1 |
|
|
| 2 |
|
|
| 3 |
|
|
| 4 |
|
|
|
|
#+NAME: table-length
|
|
#+BEGIN_SRC emacs-lisp :var table=example-table
|
|
(length table)
|
|
#+END_SRC
|
|
|
|
#+RESULTS: table-length
|
|
: 4
|
|
#+end_example
|
|
|
|
- a simple list named with ~#+NAME:~ ::
|
|
|
|
#+begin_example
|
|
#+NAME: example-list
|
|
- simple
|
|
- not
|
|
- nested
|
|
- list
|
|
|
|
#+BEGIN_SRC emacs-lisp :var x=example-list
|
|
(print x)
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
| simple | list |
|
|
#+end_example
|
|
|
|
Note that nesting is not carried through to the source code block.
|
|
|
|
- a named code block without arguments, optionally followed by parentheses ::
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC emacs-lisp :var length=table-length()
|
|
(* 2 length)
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
: 8
|
|
#+end_example
|
|
|
|
- a named code block with arguments ::
|
|
|
|
#+begin_example
|
|
#+NAME: double
|
|
#+BEGIN_SRC emacs-lisp :var input=8
|
|
(* 2 input)
|
|
#+END_SRC
|
|
|
|
#+RESULTS: double
|
|
: 16
|
|
|
|
#+NAME: squared
|
|
#+BEGIN_SRC emacs-lisp :var input=double(input=1)
|
|
(* input input)
|
|
#+END_SRC
|
|
|
|
#+RESULTS: squared
|
|
: 4
|
|
#+end_example
|
|
|
|
- a literal example block ::
|
|
|
|
#+begin_example
|
|
,#+NAME: literal-example
|
|
,#+BEGIN_EXAMPLE
|
|
A literal example
|
|
on two lines
|
|
,#+END_EXAMPLE
|
|
|
|
,#+NAME: read-literal-example
|
|
,#+BEGIN_SRC emacs-lisp :var x=literal-example
|
|
(concatenate 'string x " for you.")
|
|
,#+END_SRC
|
|
|
|
,#+RESULTS: read-literal-example
|
|
: A literal example
|
|
: on two lines for you.
|
|
#+end_example
|
|
|
|
# ***** Alternate argument syntax
|
|
<<Alternate argument syntax>>
|
|
|
|
It is also possible to specify arguments in a potentially more natural
|
|
way using the ~#+NAME:~ line of a code block. As in the following
|
|
example, arguments can be packed inside of parentheses, separated by
|
|
commas, following the source name.
|
|
|
|
#+begin_example
|
|
,#+NAME: double(input=0, x=2)
|
|
,#+BEGIN_SRC emacs-lisp
|
|
(* 2 (+ input x))
|
|
,#+END_SRC
|
|
#+end_example
|
|
|
|
# ***** Indexable variable values
|
|
<<Indexable variable values>>
|
|
|
|
It is possible to reference portions of variable values by
|
|
/indexing/ into the variables. Indexes are 0 based with negative
|
|
values counting back from the end. If an index is separated by commas
|
|
then each subsequent section will index into the next deepest nesting
|
|
or dimension of the value. Note that this indexing occurs /before/
|
|
other table related header arguments like ~:hlines~, ~:colnames~, and
|
|
~:rownames~ are applied. The following example assigns the last cell
|
|
of the first row the table ~example-table~ to the variable ~data~:
|
|
|
|
#+begin_example
|
|
,#+NAME: example-table
|
|
| 1 | a |
|
|
| 2 | b |
|
|
| 3 | c |
|
|
| 4 | d |
|
|
|
|
,#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
|
|
data
|
|
,#+END_SRC
|
|
|
|
,#+RESULTS:
|
|
: a
|
|
#+end_example
|
|
|
|
Ranges of variable values can be referenced using two integers
|
|
separated by a ~:~, in which case the entire inclusive range is
|
|
referenced. The following example assigns the middle three rows of
|
|
~example-table~ to ~data~.
|
|
|
|
#+begin_example
|
|
#+NAME: example-table
|
|
| 1 | a |
|
|
| 2 | b |
|
|
| 3 | c |
|
|
| 4 | d |
|
|
| 5 | 3 |
|
|
|
|
#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
|
|
data
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
| 2 | b |
|
|
| 3 | c |
|
|
| 4 | d |
|
|
#+end_example
|
|
|
|
Additionally, an empty index, or the single character ~*~, are both
|
|
interpreted to mean the entire range and as such are equivalent to
|
|
~0:-1~, as shown in the following example in which the entire first
|
|
column is referenced:
|
|
|
|
#+begin_example
|
|
#+NAME: example-table
|
|
| 1 | a |
|
|
| 2 | b |
|
|
| 3 | c |
|
|
| 4 | d |
|
|
|
|
#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
|
|
data
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
| 1 | 2 | 3 | 4 |
|
|
#+end_example
|
|
|
|
It is possible to index into the results of code blocks as well as
|
|
tables. Any number of dimensions can be indexed. Dimensions are
|
|
separated from one another by commas, as shown in the following
|
|
example:
|
|
|
|
#+begin_example
|
|
#+NAME: 3D
|
|
#+BEGIN_SRC emacs-lisp
|
|
'(((1 2 3) (4 5 6) (7 8 9))
|
|
((10 11 12) (13 14 15) (16 17 18))
|
|
((19 20 21) (22 23 24) (25 26 27)))
|
|
#+END_SRC
|
|
|
|
#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
|
|
data
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
| 11 | 14 | 17 |
|
|
#+end_example
|
|
|
|
# ***** Emacs Lisp evaluation of variables
|
|
<<Emacs Lisp evaluation of variables>>
|
|
|
|
Emacs lisp code can be used to initialize variable values. When a
|
|
variable value starts with ~(~, ~[~, ~'~ or ~`~ it will be evaluated
|
|
as Emacs Lisp and the result of the evaluation will be assigned as the
|
|
variable value. The following example demonstrates use of this
|
|
evaluation to reliably pass the file-name of the Org mode buffer to a
|
|
code block:[fn:150]
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
|
|
wc -w $filename
|
|
#+END_SRC
|
|
#+end_example
|
|
|
|
Note that values read from tables and lists will not be evaluated as
|
|
Emacs Lisp, as shown in the following example, which contains a Lisp
|
|
list as the sole table element:
|
|
|
|
#+begin_example
|
|
#+NAME: table
|
|
| (a b c) |
|
|
|
|
#+HEADERS: :var data=table[0,0]
|
|
#+BEGIN_SRC perl
|
|
$data
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
: (a b c)
|
|
#+end_example
|
|
|
|
**** results
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Specify the type of results and how they will be collected and handled
|
|
:END:
|
|
There are three classes of ~:results~ header argument. Only one option
|
|
per class may be supplied per code block.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Collection ::
|
|
|
|
These header arguments specify how the results should be collected
|
|
from the code block.
|
|
|
|
- Type ::
|
|
|
|
These header arguments specify what type of result the code block will
|
|
return---which has implications for how they will be inserted into the
|
|
Org mode buffer.
|
|
|
|
- Handling ::
|
|
|
|
These header arguments specify how the results of evaluating the code
|
|
block should be handled.
|
|
|
|
# ***** Collection
|
|
<<Collection>>
|
|
|
|
The following ~:results~ options are mutually exclusive, and specify
|
|
how the results should be collected from the code block.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~value~ ::
|
|
|
|
This is the default. The result is the value of the last statement in
|
|
the code block. This header argument places the evaluation in
|
|
functional mode. Note that in some languages, e.g., Python, use of
|
|
this result type requires that a ~return~ statement be included in the
|
|
body of the source code block.
|
|
|
|
- ~output~ ::
|
|
|
|
The result is the collection of everything printed to STDOUT during
|
|
the execution of the code block. This header argument places the
|
|
evaluation in scripting mode.
|
|
|
|
# ***** Type
|
|
<<Type>>
|
|
|
|
The following ~:results~ options are mutually exclusive and specify
|
|
what type of results the code block will return. By default, results
|
|
are inserted as either a table or scalar depending on their value.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~table~, ~vector~ ::
|
|
|
|
The results should be interpreted as an Org mode table. If a single
|
|
value is returned, it will be converted into a table with one row and
|
|
one column. E.g., ~:results value table~.
|
|
|
|
- ~scalar~, ~verbatim~ ::
|
|
|
|
The results should be interpreted literally---they will not be
|
|
converted into a table. The results will be inserted into the Org mode
|
|
buffer as quoted text. E.g., ~:results value verbatim~.
|
|
|
|
- ~list~ ::
|
|
|
|
The results should be interpreted as an Org mode list. If a single
|
|
scalar value is returned it will be converted into a list with only
|
|
one element.
|
|
|
|
- ~file~ ::
|
|
|
|
The results will be interpreted as the path to a file, and will be
|
|
inserted into the Org mode buffer as a file link. E.g., ~:results
|
|
value file~.
|
|
|
|
- ~raw~ ::
|
|
|
|
The results are interpreted as raw Org mode code and are inserted
|
|
directly into the buffer. If the results look like a table they will
|
|
be aligned as such by Org mode. E.g., ~:results value raw~.
|
|
|
|
- ~org~ ::
|
|
|
|
The results are will be enclosed in a ~BEGIN_SRC org~ block. They are
|
|
not comma-escaped by default but they will be if you hit
|
|
{{{kbd(TAB)}}} in the block and/or if you export the file. E.g., ~:results value org~.
|
|
|
|
- ~html~ ::
|
|
|
|
Results are assumed to be HTML and will be enclosed in a ~BEGIN_HTML~
|
|
block. E.g., ~:results value html~.
|
|
|
|
- ~latex~ ::
|
|
|
|
Results assumed to be LaTeX and are enclosed in a ~BEGIN_LaTeX~
|
|
block. E.g., ~:results value latex~.
|
|
|
|
- ~code~ ::
|
|
|
|
Result are assumed to be parsable code and are enclosed in a code
|
|
block. E.g., ~:results value code~.
|
|
|
|
- ~pp~ ::
|
|
|
|
The result is converted to pretty-printed code and is enclosed in a
|
|
code block. This option currently supports Emacs Lisp, Python, and
|
|
Ruby. E.g., ~:results value pp~.
|
|
|
|
- ~drawer~ ::
|
|
|
|
The result is wrapped in a RESULTS drawer. This can be useful for
|
|
inserting ~raw~ or ~org~ syntax results in such a way that their
|
|
extent is known and they can be automatically removed or replaced.
|
|
|
|
# ***** Handling
|
|
<<Handling>>
|
|
The following ~:results~ options indicate what happens with the
|
|
results once they are collected.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~replace~ ::
|
|
|
|
The default value. Any existing results will be removed, and the new
|
|
results will be inserted into the Org mode buffer in their place.
|
|
E.g., ~:results output replace~.
|
|
|
|
- ~append~ ::
|
|
|
|
If there are pre-existing results of the code block then the new
|
|
results will be appended to the existing results. Otherwise the new
|
|
results will be inserted as with ~replace~.
|
|
|
|
- ~prepend~ ::
|
|
|
|
If there are pre-existing results of the code block then the new
|
|
results will be prepended to the existing results. Otherwise the new
|
|
results will be inserted as with ~replace~.
|
|
|
|
- ~silent~ ::
|
|
|
|
The results will be echoed in the minibuffer but will not be inserted
|
|
into the Org mode buffer. E.g., ~:results output silent~.
|
|
|
|
**** file
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Specify a path for file output
|
|
:END:
|
|
|
|
The header argument ~:file~ is used to specify an external file in
|
|
which to save code block results. After code block evaluation an Org
|
|
mode style ~[[file:]]~ link (see [[Link format]]) to the file will be inserted
|
|
into the Org mode buffer. Some languages including R, gnuplot, dot,
|
|
and ditaa provide special handling of the ~:file~ header argument,
|
|
automatically wrapping the code block body in the boilerplate code
|
|
required to save output to the specified file. This is often useful
|
|
for saving graphical output of a code block to the specified file.
|
|
|
|
The argument to ~:file~ should be either a string specifying the path
|
|
to a file, or a list of two strings in which case the first element of
|
|
the list should be the path to a file and the second a description for
|
|
the link.
|
|
|
|
**** file-desc
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Specify a description for file results
|
|
:END:
|
|
|
|
The value of the ~:file-desc~ header argument is used to provide a
|
|
description for file code block results which are inserted as Org mode
|
|
links (see [[Link format]]). If the ~:file-desc~ header argument is given
|
|
with no value the link path will be placed in both the ``link'' and
|
|
the ``description'' portion of the Org mode link.
|
|
|
|
**** dir
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Specify the default (possibly remote) directory for code block execution
|
|
:TITLE: ~:dir~ and remote execution
|
|
:END:
|
|
|
|
While the ~:file~ header argument can be used to specify the path to
|
|
the output file, ~:dir~ specifies the default directory during code
|
|
block execution. If it is absent, then the directory associated with
|
|
the current buffer is used. In other words, supplying ~:dir path~
|
|
temporarily has the same effect as changing the current directory with
|
|
{{{kbd(M-x cd path)}}}, and then not supplying ~:dir~. Under the
|
|
surface, ~:dir~ simply sets the value of the Emacs variable
|
|
~default-directory~.
|
|
|
|
When using ~:dir~, you should supply a relative path for file output
|
|
(e.g., ~:file myfile.jpg~ or ~:file results/myfile.jpg~) in which
|
|
case that path will be interpreted relative to the default directory.
|
|
|
|
In other words, if you want your plot to go into a folder called
|
|
{{{file(Work)}}} in your home directory, you could use a code block
|
|
like the following example:
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC R :file myplot.png :dir ~/Work
|
|
matplot(matrix(rnorm(100), 10), type="l")
|
|
#+END_SRC
|
|
#+end_example
|
|
|
|
# ***** Remote execution
|
|
<<Remote execution>>
|
|
|
|
A directory on a remote machine can be specified using tramp file
|
|
syntax, in which case the code will be evaluated on the remote
|
|
machine. An example is:
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC R :file plot.png :dir /dand@yakuba.princeton.edu:
|
|
plot(1:10, main=system("hostname", intern=TRUE))
|
|
#+END_SRC
|
|
#+end_example
|
|
|
|
Text results will be returned to the local Org mode buffer as usual,
|
|
and file output will be created on the remote machine with relative
|
|
paths interpreted relative to the remote directory. An Org mode link
|
|
to the remote file will be created.
|
|
|
|
So, in the above example a plot will be created on the remote machine,
|
|
and a link of the following form will be inserted in the org buffer:
|
|
|
|
#+begin_example
|
|
[[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
|
|
#+end_example
|
|
|
|
Most of this functionality follows immediately from the fact that
|
|
~:dir~ sets the value of the Emacs variable ~default-directory~,
|
|
thanks to tramp. Those using XEmacs, or GNU Emacs prior to version 23
|
|
may need to install tramp separately in order for these features to
|
|
work correctly.
|
|
|
|
# ***** Further points
|
|
<<Further points>>
|
|
Please be aware of these further points:
|
|
|
|
- If ~:dir~ is used in conjunction with ~:session~, although it will
|
|
determine the starting directory for a new session as expected, no
|
|
attempt is currently made to alter the directory associated with an
|
|
existing session.
|
|
|
|
- ~:dir~ should typically not be used to create files during export
|
|
with ~:exports results~ or ~:exports both~. The reason is that, in
|
|
order to retain portability of exported material between machines,
|
|
during export links inserted into the buffer will /not/ be expanded
|
|
against ~default directory~. Therefore, if ~default-directory~ is
|
|
altered using ~:dir~, it is probable that the file will be created
|
|
in a location to which the link does not point.
|
|
|
|
**** exports
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Export code and/or results
|
|
:END:
|
|
The ~:exports~ header argument specifies what should be included in HTML
|
|
or LaTeX exports of the Org mode file.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~code~ ::
|
|
|
|
The default. The body of code is included into the exported file.
|
|
E.g., ~:exports code~.
|
|
|
|
- ~results~ ::
|
|
|
|
The result of evaluating the code is included in the exported file.
|
|
E.g., ~:exports results~.
|
|
|
|
- ~both~ ::
|
|
|
|
Both the code and results are included in the exported file. E.g., ~:exports both~.
|
|
|
|
- ~none~ ::
|
|
|
|
Nothing is included in the exported file. E.g., ~:exports none~.
|
|
|
|
**** tangle
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Toggle tangling and specify file name
|
|
:END:
|
|
|
|
The ~:tangle~ header argument specifies whether or not the code
|
|
block should be included in tangled extraction of source code files.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~tangle~ ::
|
|
|
|
The code block is exported to a source code file named after the full
|
|
path (including the directory) and file name (w/o extension) of the
|
|
Org mode file. E.g., ~:tangle yes~.
|
|
|
|
- ~no~ ::
|
|
|
|
The default. The code block is not exported to a source code file.
|
|
E.g., ~:tangle no~.
|
|
|
|
- other ::
|
|
|
|
Any other string passed to the ~:tangle~ header argument is
|
|
interpreted as a path (directory and file name relative to the
|
|
directory of the Org mode file) to which the block will be exported,
|
|
e.g., ~:tangle path~.
|
|
|
|
**** mkdirp
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Toggle creation of parent directories of target files during tangling
|
|
:END:
|
|
|
|
The ~:mkdirp~ header argument can be used to create parent directories
|
|
of tangled files when missing. This can be set to ~yes~ to enable
|
|
directory creation or to ~no~ to inhibit directory creation.
|
|
|
|
**** comments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Toggle insertion of comments in tangled code files
|
|
:END:
|
|
|
|
By default code blocks are tangled to source-code files without any
|
|
insertion of comments beyond those which may already exist in the body
|
|
of the code block. The ~:comments~ header argument can be set as
|
|
follows to control the insertion of extra comments into the tangled
|
|
code file.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~no~ ::
|
|
|
|
The default. No extra comments are inserted during tangling.
|
|
|
|
- ~link~ ::
|
|
|
|
The code block is wrapped in comments which contain pointers back to
|
|
the original Org file from which the code was tangled.
|
|
|
|
- ~yes~ ::
|
|
|
|
A synonym for ``link'' to maintain backwards compatibility.
|
|
|
|
- ~org~ ::
|
|
|
|
Include text from the Org mode file as a comment.
|
|
|
|
The text is picked from the leading context of the tangled code and is
|
|
limited by the nearest headline or source block as the case may be.
|
|
|
|
- ~both~ ::
|
|
|
|
Turns on both the ``link'' and ``org'' comment options.
|
|
|
|
- ~noweb~ ::
|
|
|
|
Turns on the ``link'' comment option, and additionally wraps expanded
|
|
noweb references in the code block body in link comments.
|
|
|
|
**** padline
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Control insertion of padding lines in tangle code files
|
|
:END:
|
|
|
|
Control in insertion of padding lines around code block bodies in tangled
|
|
code files. The default value is ~yes~ which results in insertion of
|
|
newlines before and after each tangled code block. The following arguments
|
|
are accepted:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~yes~ ::
|
|
|
|
Insert newlines before and after each code block body in tangled code
|
|
files.
|
|
|
|
- ~no~ ::
|
|
|
|
Do not insert any newline padding in tangled output.
|
|
|
|
**** no-expand
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Turn off variable assignment and noweb expansion during tangling
|
|
:END:
|
|
|
|
By default, code blocks are expanded with ~org-babel-expand-src-block~
|
|
during tangling. This has the effect of assigning values to variables
|
|
specified with ~:var~ (see [[var]]), and of replacing ``noweb'' references
|
|
(see [[Noweb reference syntax]]) with their targets. The ~:no-expand~
|
|
header argument can be used to turn off this behavior.
|
|
|
|
**** session
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Preserve state of code evaluation
|
|
:END:
|
|
|
|
The ~:session~ header argument starts a session for an interpreted
|
|
language where state is preserved.
|
|
|
|
By default, a session is not started.
|
|
|
|
A string passed to the ~:session~ header argument will give the
|
|
session a name. This makes it possible to run concurrent sessions for
|
|
each interpreted language.
|
|
|
|
**** noweb
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Toggle expansion of noweb references
|
|
:END:
|
|
|
|
The ~:noweb~ header argument controls expansion of ``noweb'' syntax
|
|
references (see [[Noweb reference syntax]]) when the code block is
|
|
evaluated, tangled, or exported. The ~:noweb~ header argument can have
|
|
one of the five values: ~no~, ~yes~, ~tangle~, ~no-export~, or
|
|
~strip-export~.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~no~ ::
|
|
|
|
The default. ``Noweb'' syntax references in the body of the code block
|
|
will not be expanded before the code block is evaluated, tangled or
|
|
exported.
|
|
|
|
- ~yes~ ::
|
|
|
|
``Noweb'' syntax references in the body of the code block will be
|
|
expanded before the code block is evaluated, tangled or exported.
|
|
|
|
- ~tangle~ ::
|
|
|
|
``Noweb'' syntax references in the body of the code block will be
|
|
expanded before the code block is tangled. However, ``noweb'' syntax
|
|
references will not be expanded when the code block is evaluated or
|
|
exported.
|
|
|
|
- ~no-export~ ::
|
|
|
|
``Noweb'' syntax references in the body of the code block will be
|
|
expanded before the block is evaluated or tangled. However, ``noweb''
|
|
syntax references will not be expanded when the code block is
|
|
exported.
|
|
|
|
- ~strip-export~ ::
|
|
|
|
``Noweb'' syntax references in the body of the code block will be
|
|
expanded before the block is evaluated or tangled. However, ``noweb''
|
|
syntax references will not be removed when the code block is exported.
|
|
|
|
- ~eval~ ::
|
|
|
|
``Noweb'' syntax references in the body of the code block will only be
|
|
expanded before the block is evaluated.
|
|
|
|
# ***** Noweb prefix lines
|
|
<<Noweb prefix lines>>
|
|
|
|
Noweb insertions are placed behind the line prefix of the
|
|
~<<reference>>~. Because the ~<<example>>~ noweb reference appears
|
|
behind the SQL comment syntax in the following example, each line of
|
|
the expanded noweb reference will be commented.
|
|
|
|
This code block:
|
|
|
|
#+begin_example
|
|
-- <<example>>
|
|
#+end_example
|
|
|
|
|
|
expands to:
|
|
|
|
#+begin_example
|
|
-- this is the
|
|
-- multi-line body of example
|
|
#+end_example
|
|
|
|
Note that noweb replacement text that does not contain any newlines
|
|
will not be inserted behind the line prefix, so it is always possible
|
|
to use inline noweb references.
|
|
|
|
**** noweb-ref
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Specify block's noweb reference resolution target
|
|
:END:
|
|
|
|
When expanding ``noweb'' style references the bodies of all code block
|
|
with /either/ a block name matching the reference name /or/ a
|
|
~:noweb-ref~ header argument matching the reference name will be
|
|
concatenated together to form the replacement text.
|
|
|
|
By setting this header argument at the sub-tree or file level, simple code
|
|
block concatenation may be achieved. For example, when tangling the
|
|
following Org mode file, the bodies of code blocks will be concatenated into
|
|
the resulting pure code file.[fn:151]
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
|
|
<<fullest-disk>>
|
|
#+END_SRC
|
|
,* the mount point of the fullest disk
|
|
:PROPERTIES:
|
|
:noweb-ref: fullest-disk
|
|
:END:
|
|
|
|
,** query all mounted disks
|
|
#+BEGIN_SRC sh
|
|
df \
|
|
#+END_SRC
|
|
|
|
,** strip the header row
|
|
#+BEGIN_SRC sh
|
|
|sed '1d' \
|
|
#+END_SRC
|
|
|
|
,** sort by the percent full
|
|
#+BEGIN_SRC sh
|
|
|awk '@{print $5 " " $6@}'|sort -n |tail -1 \
|
|
#+END_SRC
|
|
|
|
,** extract the mount point
|
|
#+BEGIN_SRC sh
|
|
|awk '@{print $2@}'
|
|
#+END_SRC
|
|
#+end_example
|
|
|
|
The ~:noweb-sep~ (see [[noweb-sep]]) header argument holds the string used
|
|
to separate accumulate noweb references like those above. By default a
|
|
newline is used.
|
|
|
|
**** noweb-sep
|
|
:PROPERTIES:
|
|
:DESCRIPTION: String used to separate noweb references
|
|
:END:
|
|
|
|
The ~:noweb-sep~ header argument holds the string used to separate
|
|
accumulated noweb references (see [[noweb-ref]]). By default a newline is
|
|
used.
|
|
|
|
**** cache
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Avoid re-evaluating unchanged code blocks
|
|
:END:
|
|
|
|
The ~:cache~ header argument controls the use of in-buffer caching of
|
|
the results of evaluating code blocks. It can be used to avoid
|
|
re-evaluating unchanged code blocks. Note that the ~:cache~ header
|
|
argument will not attempt to cache results when the ~:session~ header
|
|
argument is used, because the results of the code block execution may
|
|
be stored in the session outside of the Org mode buffer. The ~:cache~
|
|
header argument can have one of two values: ~yes~ or ~no~.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~no~ ::
|
|
|
|
The default. No caching takes place, and the code block will be
|
|
evaluated every time it is called.
|
|
|
|
- ~yes~ ::
|
|
|
|
Every time the code block is run a SHA1 hash of the code and arguments
|
|
passed to the block will be generated. This hash is packed into the ~#+RESULTS:~ line and will be checked on subsequent executions of the
|
|
code block. If the code block has not changed since the last time it
|
|
was evaluated, it will not be re-evaluated.
|
|
|
|
|
|
Code block caches notice if the value of a variable argument
|
|
to the code block has changed. If this is the case, the cache is
|
|
invalidated and the code block is re-run. In the following example,
|
|
~caller~ will not be re-run unless the results of ~random~ have
|
|
changed since it was last run.
|
|
|
|
#+begin_example
|
|
#+NAME: random
|
|
#+BEGIN_SRC R :cache yes
|
|
runif(1)
|
|
#+END_SRC
|
|
|
|
#+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
|
|
0.4659510825295
|
|
|
|
#+NAME: caller
|
|
#+BEGIN_SRC emacs-lisp :var x=random :cache yes
|
|
x
|
|
#+END_SRC
|
|
|
|
#+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
|
|
0.254227238707244
|
|
#+end_example
|
|
|
|
**** sep
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Delimiter for writing tabular results outside Org
|
|
:END:
|
|
#+kindex: C-c C-o
|
|
|
|
The ~:sep~ header argument can be used to control the delimiter used
|
|
when writing tabular results out to files external to Org mode. This
|
|
is used either when opening tabular results of a code block by calling
|
|
the ~org-open-at-point~ function bound to {{{kbd(C-c C-o)}}} on the
|
|
code block, or when writing code block results to an external file
|
|
(see [[file]]) header argument.
|
|
|
|
By default, when ~:sep~ is not specified output tables are tab
|
|
delimited.
|
|
|
|
**** hlines
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Handle horizontal lines in tables
|
|
:END:
|
|
|
|
Tables are frequently represented with one or more horizontal lines,
|
|
or hlines. The ~:hlines~ argument to a code block accepts the values
|
|
~yes~ or ~no~, with a default value of ~no~.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~no~ ::
|
|
|
|
Strips horizontal lines from the input table. In most languages this
|
|
is the desired effect because an ~hline~ symbol is interpreted as an
|
|
unbound variable and raises an error. Setting ~:hlines no~ or relying
|
|
on the default value yields the following results.
|
|
|
|
#+begin_example
|
|
#+TBLNAME: many-cols
|
|
| a | b | c |
|
|
|---+---+---|
|
|
| d | e | f |
|
|
|---+---+---|
|
|
| g | h | i |
|
|
|
|
#+NAME: echo-table
|
|
#+BEGIN_SRC python :var tab=many-cols
|
|
return tab
|
|
#+END_SRC
|
|
|
|
#+RESULTS: echo-table
|
|
| a | b | c |
|
|
| d | e | f |
|
|
| g | h | i |
|
|
#+end_example
|
|
|
|
- ~yes~ ::
|
|
|
|
Leaves hlines in the table. Setting ~:hlines yes~ has this effect.
|
|
|
|
#+begin_example
|
|
#+TBLNAME: many-cols
|
|
| a | b | c |
|
|
|---+---+---|
|
|
| d | e | f |
|
|
|---+---+---|
|
|
| g | h | i |
|
|
|
|
#+NAME: echo-table
|
|
#+BEGIN_SRC python :var tab=many-cols :hlines yes
|
|
return tab
|
|
#+END_SRC
|
|
|
|
#+RESULTS: echo-table
|
|
| a | b | c |
|
|
|---+---+---|
|
|
| d | e | f |
|
|
|---+---+---|
|
|
| g | h | i |
|
|
#+end_example
|
|
|
|
**** colnames
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Handle column names in tables
|
|
:END:
|
|
|
|
The ~:colnames~ header argument accepts the values ~yes~, ~no~, or
|
|
~nil~ for unassigned. The default value is ~nil~. Note that the
|
|
behavior of the ~:colnames~ header argument may differ across
|
|
languages. For example Emacs Lisp code blocks ignore the ~:colnames~
|
|
header argument entirely given the ease with which tables with column
|
|
names may be handled directly in Emacs Lisp.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~nil~ ::
|
|
|
|
If an input table looks like it has column names (because its second
|
|
row is an hline), then the column names will be removed from the table
|
|
before processing, then reapplied to the results.
|
|
|
|
#+begin_example
|
|
#+TBLNAME: less-cols
|
|
| a |
|
|
|---|
|
|
| b |
|
|
| c |
|
|
|
|
#+NAME: echo-table-again
|
|
#+BEGIN_SRC python :var tab=less-cols
|
|
return [[val + '*' for val in row] for row in tab]
|
|
#+END_SRC
|
|
|
|
#+RESULTS: echo-table-again
|
|
| a |
|
|
|----|
|
|
| b* |
|
|
| c* |
|
|
#+end_example
|
|
|
|
Please note that column names are not removed before the table is
|
|
indexed using variable indexing. See [[Indexable variable values]].
|
|
|
|
- ~no~ ::
|
|
|
|
No column name pre-processing takes place
|
|
|
|
- ~yes~ ::
|
|
|
|
Column names are removed and reapplied as with ~nil~ even if the table
|
|
does not ``look like'' it has column names (i.e., the second row is
|
|
not an hline).
|
|
|
|
**** rownames
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Handle row names in tables
|
|
:END:
|
|
|
|
The ~:rownames~ header argument can take on the values ~yes~
|
|
or ~no~, with a default value of ~no~.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~no~ ::
|
|
|
|
No row name pre-processing will take place.
|
|
|
|
- ~yes~ ::
|
|
|
|
The first column of the table is removed from the table before
|
|
processing, and is then reapplied to the results.
|
|
|
|
#+begin_example
|
|
#+TBLNAME: with-rownames
|
|
| one | 1 | 2 | 3 | 4 | 5 |
|
|
| two | 6 | 7 | 8 | 9 | 10 |
|
|
|
|
#+NAME: echo-table-once-again
|
|
#+BEGIN_SRC python :var tab=with-rownames :rownames yes
|
|
return [[val + 10 for val in row] for row in tab]
|
|
#+END_SRC
|
|
|
|
#+RESULTS: echo-table-once-again
|
|
| one | 11 | 12 | 13 | 14 | 15 |
|
|
| two | 16 | 17 | 18 | 19 | 20 |
|
|
#+end_example
|
|
|
|
Please note that row names are not removed before the table is indexed
|
|
using variable indexing. See [[Indexable variable values]].
|
|
|
|
**** shebang
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Make tangles files executable
|
|
:END:
|
|
|
|
Setting the ~:shebang~ header argument to a string value (e.g.,
|
|
{{{samp(: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.
|
|
|
|
**** eval
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Limit evaluation of specific code blocks
|
|
:END:
|
|
|
|
The ~:eval~ header argument can be used to limit the evaluation of
|
|
specific code blocks. The ~:eval~ header argument can be useful for
|
|
protecting against the evaluation of dangerous code blocks or to
|
|
ensure that evaluation will require a query regardless of the value of
|
|
the ~org-confirm-babel-evaluate~ variable. The possible values of
|
|
~:eval~ and their effects are shown below.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~never~ or ~no~ ::
|
|
|
|
The code block will not be evaluated under any circumstances.
|
|
|
|
- ~query~ ::
|
|
|
|
Evaluation of the code block will require an affirmative answer to a
|
|
query.
|
|
|
|
- ~never-export~ or ~no-export~ ::
|
|
|
|
The code block will not be evaluated during export but may still be
|
|
called interactively.
|
|
|
|
- ~query-export~ ::
|
|
|
|
Evaluation of the code block during export will require an affirmative
|
|
answer to a query.
|
|
|
|
|
|
If this header argument is not set then evaluation is determined by the value
|
|
of the ~org-confirm-babel-evaluate~ variable (see [[Code evaluation
|
|
security]]).
|
|
|
|
**** wrap
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Mark source block evaluation results
|
|
:END:
|
|
|
|
The ~:wrap~ header argument is used to mark the results of source
|
|
block evaluation. The header argument can be passed a string that will
|
|
be appended to ~#+BEGIN_~ and ~#+END_~, which will then be used to
|
|
wrap the results. If no string is specified then the results will be
|
|
wrapped in a ~#+BEGIN/END_RESULTS~ block.
|
|
|
|
** Results of evaluation
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How evaluation results are handled
|
|
:END:
|
|
#+cindex: code block, results of evaluation
|
|
#+cindex: source code, results of evaluation
|
|
|
|
The way in which results are handled depends on whether a session is
|
|
invoked, as well as on whether ~:results value~ or ~:results output~
|
|
is used. The following table shows the table possibilities. For a full
|
|
listing of the possible results header arguments, see [[results]].
|
|
|
|
| | *Non-session* | *Session* |
|
|
|-------------------+--------------------------+-------------------------------------|
|
|
| ~:results value~ | value of last expression | value of last expression |
|
|
| ~:results output~ | contents of STDOUT | concatenation of interpreter output |
|
|
|
|
|
|
Please note that with ~:results value~, the result in both ~:session~
|
|
and non-session is returned to Org mode as a table (a one- or
|
|
two-dimensional vector of strings or numbers) when appropriate.
|
|
|
|
*** Non-session
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:results value~ ::
|
|
|
|
This is the default. Internally, the value is obtained by wrapping the
|
|
code in a function definition in the external language, and evaluating
|
|
that function. Therefore, code should be written as if it were the
|
|
body of such a function. In particular, note that Python does not
|
|
automatically return a value from a function unless a ~return~
|
|
statement is present, and so a {{{samp(return)}}} statement will
|
|
usually be required in Python.
|
|
|
|
This is the only one of the four evaluation contexts in which the code
|
|
is automatically wrapped in a function definition.
|
|
|
|
- ~:results output~ ::
|
|
|
|
The code is passed to the interpreter as an external process, and the
|
|
contents of the standard output stream are returned as text.[fn:152]
|
|
|
|
*** Session
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:results value~ ::
|
|
|
|
The code is passed to an interpreter running as an interactive Emacs
|
|
inferior process. Only languages which provide tools for interactive
|
|
evaluation of code have session support, so some language (e.g., C and
|
|
ditaa) do not support the ~:session~ header argument, and in other
|
|
languages (e.g., Python and Haskell) which have limitations on the
|
|
code which may be entered into interactive sessions, those limitations
|
|
apply to the code in code blocks using the ~:session~ header argument
|
|
as well.
|
|
|
|
Unless the ~:results output~ option is supplied (see below) the result
|
|
returned is the result of the last evaluation performed by the
|
|
interpreter.[fn:153]
|
|
|
|
- ~:results output~ ::
|
|
|
|
The code is passed to the interpreter running as an interactive Emacs
|
|
inferior process. The result returned is the concatenation of the
|
|
sequence of (text) output from the interactive interpreter. Notice
|
|
that this is not necessarily the same as what would be sent to ~STDOUT~ if the same code were passed to a non-interactive interpreter
|
|
running as an external process. Compare the following two
|
|
examples:
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC python :results output
|
|
print "hello"
|
|
2
|
|
print "bye"
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
: hello
|
|
: bye
|
|
#+end_example
|
|
|
|
In non-session mode, the `2' is not printed and does not appear.
|
|
|
|
#+begin_example
|
|
#+BEGIN_SRC python :results output :session
|
|
print "hello"
|
|
2
|
|
print "bye"
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
: hello
|
|
: 2
|
|
: bye
|
|
#+end_example
|
|
|
|
But in ~:session~ mode, the interactive interpreter receives input `2'
|
|
and prints out its value, `2'. (Indeed, the other print statements are
|
|
unnecessary here).
|
|
|
|
** Noweb reference syntax
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Literate programming in Org mode
|
|
:END:
|
|
#+cindex: code block, noweb reference
|
|
#+cindex: syntax, noweb
|
|
#+cindex: source code, noweb reference
|
|
|
|
The ``noweb'' (see [[http://www.cs.tufts.edu/~nr/noweb/]]) Literate
|
|
Programming system allows named blocks of code to be referenced using
|
|
the familiar Noweb syntax:
|
|
|
|
#+begin_example
|
|
<<code-block-name>>
|
|
#+end_example
|
|
|
|
When a code block is tangled or evaluated, whether or not ``noweb''
|
|
references are expanded depends upon the value of the ~:noweb~ header
|
|
argument. If ~:noweb yes~, then a Noweb reference is expanded before
|
|
evaluation. If ~:noweb no~, the default, then the reference is not
|
|
expanded before evaluation. See the [[noweb-ref]] header argument for a
|
|
more flexible way to resolve noweb references.
|
|
|
|
It is possible to include the /results/ of a code block rather than
|
|
the body. This is done by appending parenthesis to the code block
|
|
name, which may optionally contain arguments to the code block as
|
|
shown below.
|
|
|
|
#+begin_example
|
|
<<code-block-name(optional arguments)>>
|
|
#+end_example
|
|
|
|
Note that the default value, ~:noweb no~, was chosen to ensure that
|
|
correct code is not broken in a language, such as Ruby, where
|
|
~<<arg>>~ is a syntactically valid construct. If ~<<arg>>~ is not
|
|
syntactically valid in languages that you use, then please consider
|
|
setting the default value.
|
|
|
|
If noweb tangling is slow in large Org mode files, consider
|
|
setting the ~*org-babel-use-quick-and-dirty-noweb-expansion*~ variable
|
|
to true. This will result in faster noweb reference resolution at the
|
|
expense of not correctly resolving inherited values of the
|
|
~:noweb-ref~ header argument.
|
|
|
|
** Key bindings and useful functions
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Work quickly with code blocks
|
|
:END:
|
|
#+cindex: code block, key bindings
|
|
|
|
Many common Org mode key sequences are re-bound depending on
|
|
the context.
|
|
|
|
Within a code block, the following key bindings
|
|
are active:
|
|
#+kindex: C-c C-c
|
|
#+kindex: C-c C-o
|
|
#+kindex: C-up
|
|
#+kindex: M-down
|
|
|
|
#+attr_texinfo: :columns 0.2 0.55
|
|
| Key binding | Function |
|
|
|-----------------------+-----------------------------------|
|
|
| {{{kbd(C-c C-c)}}} | ~org-babel-execute-src-block~ |
|
|
| {{{kbd(C-c C-o)}}} | ~org-babel-open-src-block-result~ |
|
|
| {{{kbdkey(C-,up)}}} | ~org-babel-load-in-session~ |
|
|
| {{{kbdkey(M-,down)}}} | ~org-babel-pop-to-session~ |
|
|
|
|
|
|
In an Org mode buffer, the following key bindings are active:
|
|
|
|
#+kindex: C-c C-v p
|
|
#+kindex: C-c C-v C-p
|
|
#+kindex: C-c C-v n
|
|
#+kindex: C-c C-v C-n
|
|
#+kindex: C-c C-v e
|
|
#+kindex: C-c C-v C-e
|
|
#+kindex: C-c C-v o
|
|
#+kindex: C-c C-v C-o
|
|
#+kindex: C-c C-v v
|
|
#+kindex: C-c C-v C-v
|
|
#+kindex: C-c C-v u
|
|
#+kindex: C-c C-v C-u
|
|
#+kindex: C-c C-v g
|
|
#+kindex: C-c C-v C-g
|
|
#+kindex: C-c C-v r
|
|
#+kindex: C-c C-v C-r
|
|
#+kindex: C-c C-v b
|
|
#+kindex: C-c C-v C-b
|
|
#+kindex: C-c C-v s
|
|
#+kindex: C-c C-v C-s
|
|
#+kindex: C-c C-v d
|
|
#+kindex: C-c C-v C-d
|
|
#+kindex: C-c C-v t
|
|
#+kindex: C-c C-v C-t
|
|
#+kindex: C-c C-v f
|
|
#+kindex: C-c C-v C-f
|
|
#+kindex: C-c C-v c
|
|
#+kindex: C-c C-v C-c
|
|
#+kindex: C-c C-v j
|
|
#+kindex: C-c C-v C-j
|
|
#+kindex: C-c C-v l
|
|
#+kindex: C-c C-v C-l
|
|
#+kindex: C-c C-v i
|
|
#+kindex: C-c C-v C-i
|
|
#+kindex: C-c C-v I
|
|
#+kindex: C-c C-v C-I
|
|
#+kindex: C-c C-v z
|
|
#+kindex: C-c C-v C-z
|
|
#+kindex: C-c C-v a
|
|
#+kindex: C-c C-v C-a
|
|
#+kindex: C-c C-v h
|
|
#+kindex: C-c C-v C-h
|
|
#+kindex: C-c C-v x
|
|
#+kindex: C-c C-v C-x
|
|
|
|
#+attr_texinfo: :columns 0.4 0.6
|
|
| Key binding | Function |
|
|
|------------------------------------------------+--------------------------------------------|
|
|
| {{{kbd(C-c C-v p)}}} or {{{kbd(C-c C-v C-p)}}} | ~org-babel-previous-src-block~ |
|
|
| {{{kbd(C-c C-v n)}}} or {{{kbd(C-c C-v C-n)}}} | ~org-babel-next-src-block~ |
|
|
| {{{kbd(C-c C-v e)}}} or {{{kbd(C-c C-v C-e)}}} | ~org-babel-execute-maybe~ |
|
|
| {{{kbd(C-c C-v o)}}} or {{{kbd(C-c C-v C-o)}}} | ~org-babel-open-src-block-result~ |
|
|
| {{{kbd(C-c C-v v)}}} or {{{kbd(C-c C-v C-v)}}} | ~org-babel-expand-src-block~ |
|
|
| {{{kbd(C-c C-v u)}}} or {{{kbd(C-c C-v C-u)}}} | ~org-babel-goto-src-block-head~ |
|
|
| {{{kbd(C-c C-v g)}}} or {{{kbd(C-c C-v C-g)}}} | ~org-babel-goto-named-src-block~ |
|
|
| {{{kbd(C-c C-v r)}}} or {{{kbd(C-c C-v C-r)}}} | ~org-babel-goto-named-result~ |
|
|
| {{{kbd(C-c C-v b)}}} or {{{kbd(C-c C-v C-b)}}} | ~org-babel-execute-buffer~ |
|
|
| {{{kbd(C-c C-v s)}}} or {{{kbd(C-c C-v C-s)}}} | ~org-babel-execute-subtree~ |
|
|
| {{{kbd(C-c C-v d)}}} or {{{kbd(C-c C-v C-d)}}} | ~org-babel-demarcate-block~ |
|
|
| {{{kbd(C-c C-v t)}}} or {{{kbd(C-c C-v C-t)}}} | ~org-babel-tangle~ |
|
|
| {{{kbd(C-c C-v f)}}} or {{{kbd(C-c C-v C-f)}}} | ~org-babel-tangle-file~ |
|
|
| {{{kbd(C-c C-v c)}}} or {{{kbd(C-c C-v C-c)}}} | ~org-babel-check-src-block~ |
|
|
| {{{kbd(C-c C-v j)}}} or {{{kbd(C-c C-v C-j)}}} | ~org-babel-insert-header-arg~ |
|
|
| {{{kbd(C-c C-v l)}}} or {{{kbd(C-c C-v C-l)}}} | ~org-babel-load-in-session~ |
|
|
| {{{kbd(C-c C-v i)}}} or {{{kbd(C-c C-v C-i)}}} | ~org-babel-lob-ingest~ |
|
|
| {{{kbd(C-c C-v I)}}} or {{{kbd(C-c C-v C-I)}}} | ~org-babel-view-src-block-info~ |
|
|
| {{{kbd(C-c C-v z)}}} or {{{kbd(C-c C-v C-z)}}} | ~org-babel-switch-to-session-with-code~ |
|
|
| {{{kbd(C-c C-v a)}}} or {{{kbd(C-c C-v C-a)}}} | ~org-babel-sha1-hash~ |
|
|
| {{{kbd(C-c C-v h)}}} or {{{kbd(C-c C-v C-h)}}} | ~org-babel-describe-bindings~ |
|
|
| {{{kbd(C-c C-v x)}}} or {{{kbd(C-c C-v C-x)}}} | ~org-babel-do-key-sequence-in-edit-buffer~ |
|
|
|
|
|
|
# When possible these keybindings were extended to work when the control key is
|
|
# kept pressed, resulting in the following additional keybindings.
|
|
|
|
# @multitable @columnfractions 0.25 0.75
|
|
# - {{{kbd(C-c C-v C-a)}}} @tab ~org-babel-sha1-hash~
|
|
# - {{{kbd(C-c C-v C-b)}}} @tab ~org-babel-execute-buffer~
|
|
# - {{{kbd(C-c C-v C-f)}}} @tab ~org-babel-tangle-file~
|
|
# - {{{kbd(C-c C-v C-l)}}} @tab ~org-babel-lob-ingest~
|
|
# - {{{kbd(C-c C-v C-p)}}} @tab ~org-babel-expand-src-block~
|
|
# - {{{kbd(C-c C-v C-s)}}} @tab ~org-babel-execute-subtree~
|
|
# - {{{kbd(C-c C-v C-t)}}} @tab ~org-babel-tangle~
|
|
# - {{{kbd(C-c C-v C-z)}}} @tab ~org-babel-switch-to-session~
|
|
# @end multitable
|
|
|
|
** Batch execution
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Call functions from the command line
|
|
:END:
|
|
#+cindex: code block, batch execution
|
|
#+cindex: source code, batch execution
|
|
|
|
It is possible to call functions from the command line. This shell
|
|
script calls ~org-babel-tangle~ on every one of its arguments.
|
|
|
|
Be sure to adjust the paths to fit your system.
|
|
|
|
#+begin_example
|
|
#!/bin/sh
|
|
# -*- mode: shell-script -*-
|
|
#
|
|
# tangle files with org-mode
|
|
#
|
|
DIR=`pwd`
|
|
FILES=""
|
|
|
|
# wrap each argument in the code required to call tangle on it
|
|
for i in $@; do
|
|
FILES="$FILES \"$i\""
|
|
done
|
|
|
|
emacs -Q --batch \
|
|
--eval "(progn
|
|
(add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
|
|
(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\" t))
|
|
(require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
|
|
(mapc (lambda (file)
|
|
(find-file (expand-file-name file \"$DIR\"))
|
|
(org-babel-tangle)
|
|
(kill-buffer)) '($FILES)))" 2>&1 |grep tangled
|
|
#+end_example
|
|
|
|
* FIXME Miscellaneous
|
|
:PROPERTIES:
|
|
:DESCRIPTION: All the rest which did not fit elsewhere
|
|
:END:
|
|
|
|
** FIXME Completion
|
|
:PROPERTIES:
|
|
:DESCRIPTION: M-TAB knows what you need
|
|
:END:
|
|
#+cindex: completion, of @TeX{} symbols
|
|
#+cindex: completion, of TODO keywords
|
|
#+cindex: completion, of dictionary words
|
|
#+cindex: completion, of option keywords
|
|
#+cindex: completion, of tags
|
|
#+cindex: completion, of property keys
|
|
#+cindex: completion, of link abbreviations
|
|
#+cindex: @TeX{} symbol completion
|
|
#+cindex: TODO keywords completion
|
|
#+cindex: dictionary word completion
|
|
#+cindex: option keyword completion
|
|
#+cindex: tag completion
|
|
#+cindex: link abbreviations, completion of
|
|
|
|
Emacs would not be Emacs without completion, and Org mode uses it
|
|
whenever it makes sense. If you prefer an iswitchb- or ido-like
|
|
interface for some of the completion prompts, you can specify your
|
|
preference by setting at most one of the variables
|
|
~org-completion-use-iswitchb~ or ~org-completion-use-ido~.
|
|
|
|
Org supports in-buffer completion. This type of completion does not
|
|
make use of the minibuffer. You simply type a few letters into the
|
|
buffer and use the {{{key(TAB)}}} key to complete text right there.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbdkey(M-,TAB)}}} ::
|
|
#+kindex: M-@key{TAB}
|
|
|
|
Complete word at point.
|
|
|
|
- At the beginning of a headline ::
|
|
|
|
Complete TODO keywords.
|
|
|
|
- After {{{kbd(XXX)}}} ::
|
|
# Should be \
|
|
Complete TeX symbols supported by the exporter.
|
|
|
|
- After {{{samp(*)}}} ::
|
|
|
|
Complete headlines in the current buffer so that they can be used in
|
|
search links like:
|
|
|
|
#+begin_example
|
|
[[*find this headline]]
|
|
#+end_example
|
|
|
|
- After {{{samp(:)}}} in a headline ::
|
|
|
|
Complete tags. The list of tags is taken from the variable ~org-tag-alist~ (possibly set through the {{{samp(#+TAGS)}}} in-buffer
|
|
option, see [[Setting tags]]), or it is created dynamically from all tags
|
|
used in the current buffer.
|
|
|
|
- After {{{samp(:)}}} and not in a headline ::
|
|
|
|
Complete property keys. The list of keys is constructed dynamically
|
|
from all keys used in the current buffer.
|
|
|
|
- After {{{samp([)}}} ::
|
|
|
|
Complete link abbreviations (see [[Link abbreviations]]).
|
|
|
|
- After {{{samp(#+)}}} ::
|
|
|
|
Complete the special keywords like {{{samp(TYP_TODO)}}} or
|
|
{{{samp(OPTIONS)}}} which set file-specific options for Org mode. When
|
|
the option keyword is already complete, pressing {{{kbdkey(M-,TAB)}}}
|
|
again will insert example settings for this keyword.
|
|
|
|
- In the line after {{{samp(#+STARTUP: )}}} ::
|
|
|
|
Complete startup keywords, i.e., valid keys for this line.
|
|
|
|
- Elsewhere ::
|
|
|
|
Complete dictionary words using Ispell.
|
|
|
|
** Easy templates
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Quick insertion of structural elements
|
|
:END:
|
|
#+cindex: template insertion
|
|
#+cindex: insertion, of templates
|
|
|
|
Org mode supports insertion of empty structural elements (like
|
|
~#+BEGIN_SRC~ and ~#+END_SRC~ pairs) with just a few key strokes. This
|
|
is achieved through a native template expansion mechanism. Note that
|
|
Emacs has several other template mechanisms which could be used in a
|
|
similar way, for example {{{file(yasnippet)}}}.
|
|
|
|
To insert a structural element, type a {{{kbd(<)}}}, followed by a
|
|
template selector and {{{kbdkey(,TAB)}}}. Completion takes effect only
|
|
when the above keystrokes are typed on a line by itself.
|
|
|
|
The following template selectors are currently supported:
|
|
#+kindex: s
|
|
#+kindex: e
|
|
#+kindex: q
|
|
#+kindex: v
|
|
#+kindex: c
|
|
#+kindex: l
|
|
#+kindex: L
|
|
#+kindex: h
|
|
#+kindex: H
|
|
#+kindex: a
|
|
#+kindex: A
|
|
#+kindex: i
|
|
#+kindex: I
|
|
|
|
#+attr_texinfo: :columns 0.2 0.7
|
|
| Selector | Template |
|
|
|--------------+---------------------------------------|
|
|
| {{{kbd(a)}}} | ~#+BEGIN_ASCII~ ...~ #+END_ASCII~ |
|
|
| {{{kbd(A)}}} | ~#+ASCII:~ |
|
|
| {{{kbd(c)}}} | ~#+BEGIN_CENTER~ ... ~#+END_CENTER~ |
|
|
| {{{kbd(e)}}} | ~#+BEGIN_EXAMPLE~ ... ~#+END_EXAMPLE~ |
|
|
| {{{kbd(h)}}} | ~#+BEGIN_HTML~ ... ~#+END_HTML~ |
|
|
| {{{kbd(H)}}} | ~#+HTML:~ |
|
|
| {{{kbd(i)}}} | ~#+INDEX:~ |
|
|
| {{{kbd(I)}}} | ~#+INCLUDE:~ |
|
|
| {{{kbd(l)}}} | ~#+BEGIN_LaTeX~ ... ~#+END_LaTeX~ |
|
|
| {{{kbd(L)}}} | ~#+LaTeX:~ |
|
|
| {{{kbd(q)}}} | ~#+BEGIN_QUOTE~ ... ~#+END_QUOTE~ |
|
|
| {{{kbd(s)}}} | ~#+BEGIN_SRC~ ... ~#+END_SRC~ |
|
|
| {{{kbd(v)}}} | ~#+BEGIN_VERSE~ ... ~#+END_VERSE~ |
|
|
|
|
For example, on an empty line, typing "<e" and then pressing TAB, will expand
|
|
into a complete EXAMPLE template.
|
|
|
|
You can install additional templates by customizing the variable
|
|
~org-structure-template-alist~. See the docstring of the variable for
|
|
additional details.
|
|
|
|
** Speed keys
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Electric commands at the beginning of a headline
|
|
:END:
|
|
#+cindex: speed keys
|
|
#+vindex: org-use-speed-commands
|
|
#+vindex: org-speed-commands-user
|
|
|
|
Single keys can be made to execute commands when the cursor is at the
|
|
beginning of a headline, i.e., before the first star. Configure the
|
|
variable ~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 ~org-speed-commands-user~. Speed keys do not only speed
|
|
up navigation and other commands, but they also provide an alternative
|
|
way to execute commands bound to keys that are not or not easily
|
|
available on a TTY, or on a small mobile device with a limited
|
|
keyboard.
|
|
|
|
To see which commands are available, activate the feature and press
|
|
{{{kbd(?)}}} with the cursor at the beginning of a headline.
|
|
|
|
** Code evaluation security
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Org mode files evaluate in-line code
|
|
:TITLE: Code evaluation and security issues
|
|
:END:
|
|
|
|
Org provides tools to work with the code snippets, including
|
|
evaluating them.
|
|
|
|
Running code on your machine always comes with a security risk. Badly
|
|
written or malicious code can be executed on purpose or by accident.
|
|
Org has default settings that will only evaluate source code if you
|
|
give explicit permission to do so, and as a casual user of these
|
|
features you should leave these precautions intact.
|
|
|
|
For people who regularly work with source code, the confirmation
|
|
prompts can become annoying, and you might want to turn them off. This
|
|
can be done, but you must be aware of the risks that are involved.
|
|
|
|
Code evaluation can happen under the following circumstances:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Source code blocks ::
|
|
|
|
Source code blocks can be evaluated during export, or when pressing
|
|
{{{kbd(C-c C-c)}}} in the block. The most important thing to realize
|
|
here is that Org mode files which contain code snippets are, in a
|
|
certain sense, like executable files. So you should accept them and
|
|
load them into Emacs only from trusted sources---just like you would
|
|
do with a program you install on your computer.
|
|
|
|
Make sure you know what you are doing before customizing the variables
|
|
that take off the default security brakes.
|
|
|
|
- ~org-confirm-babel-evaluate~ ::
|
|
|
|
When ~t~ (the default), the user is asked before every code block
|
|
evaluation. When ~nil~, the user is not asked. When set to a function,
|
|
it is called with two arguments (language and body of the code block)
|
|
and should return ~t~ to ask and ~nil~ not to ask.
|
|
|
|
For example, here is how to execute "ditaa" code (which is considered
|
|
safe) without asking:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(defun my-org-confirm-babel-evaluate (lang body)
|
|
(not (string= lang "ditaa"))) ; don't ask for ditaa
|
|
(setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
|
|
#+end_src
|
|
|
|
- Following ~shell~ and ~elisp~ links ::
|
|
|
|
Org has two link types that can directly evaluate code (see [[External
|
|
links]]). These links can be problematic because the code to be
|
|
evaluated is not visible.
|
|
|
|
- ~org-confirm-shell-link-function~ ::
|
|
|
|
Function to queries user about shell link execution.
|
|
|
|
- ~org-confirm-elisp-link-function~ ::
|
|
|
|
Function to query user for Emacs Lisp link execution.
|
|
|
|
- Formulas in tables ::
|
|
|
|
Formulas in tables (see [[The spreadsheet]]) are code that is evaluated
|
|
either by the /calc/ interpreter, or by the /Emacs Lisp/ interpreter.
|
|
|
|
** Customization
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Adapting Org to your taste
|
|
:END:
|
|
#+cindex: customization
|
|
#+cindex: options, for customization
|
|
#+cindex: variables, for customization
|
|
|
|
There are more than 500 variables that can be used to customize Org.
|
|
For the sake of compactness of the manual, I am not describing the
|
|
variables here. A structured overview of customization variables is
|
|
available with {{{kbd(M-x org-customize)}}}. Or select ~Browse Org
|
|
Group~ from the ~Org->Customization~ menu. Many settings can also be
|
|
activated on a per-file basis, by putting special lines into the
|
|
buffer (see [[In-buffer settings]]).
|
|
|
|
** In-buffer settings
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Overview of the #+KEYWORDS
|
|
:TITLE: Summary of in-buffer settings
|
|
:END:
|
|
#+cindex: in-buffer settings
|
|
#+cindex: special keywords
|
|
|
|
Org mode uses special lines in the buffer to define settings on a
|
|
per-file basis. These lines start with a {{{samp(#+)}}} followed by a
|
|
keyword, a colon, and then individual words defining a setting.
|
|
Several setting words can be in the same line, but you can also have
|
|
multiple lines for the keyword. While these settings are described
|
|
throughout the manual, here is a summary. After changing any of those
|
|
lines in the buffer, press {{{kbd(C-c C-c)}}} with the cursor still in
|
|
the line to activate the changes immediately. Otherwise they become
|
|
effective only when the file is visited again in a new Emacs session.
|
|
|
|
#+vindex: org-archive-location
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(#+ARCHIVE: %s_done)}}} ::
|
|
|
|
This line sets the archive location for the agenda file. It applies to
|
|
all subsequent lines, until the next {{{samp(#+ARCHIVE)}}} line or the
|
|
end of the file. The first such line also applies to any entries
|
|
before it. The corresponding variable is ~org-archive-location~.
|
|
|
|
- {{{kbd(#+CATEGORY:)}}} ::
|
|
|
|
This line sets the category for the agenda file. The category applies
|
|
to all subsequent lines, until the next {{{samp(#+CATEGORY)}}} line or
|
|
the end of the file. The first such line also applies to any entries
|
|
before it.
|
|
|
|
- {{{kbd(#+COLUMNS: %25ITEM ...)}}} ::
|
|
#+cindex: property, COLUMNS
|
|
|
|
Set the default format for columns view. This format applies when
|
|
columns view is invoked in locations where no ~COLUMNS~ property
|
|
applies.
|
|
|
|
- {{{kbd(#+CONSTANTS: name1=value1 ...)}}} ::
|
|
#+vindex: org-table-formula-constants
|
|
#+vindex: org-table-formula
|
|
|
|
Set file-local values for constants to be used in table formulas. This
|
|
line sets the local variable ~org-table-formula-constants-local~. The
|
|
global version of this variable is ~org-table-formula-constants~.
|
|
|
|
- {{{kbd(#+FILETAGS: :tag1:tag2:tag3:)}}} ::
|
|
|
|
Set tags that can be inherited by any entry in the file, including the
|
|
top-level entries.
|
|
|
|
- {{{kbd(#+DRAWERS: NAME1 ...)}}} ::
|
|
#+vindex: org-drawers
|
|
|
|
Set the file-local set of additional drawers. The corresponding global
|
|
variable is ~org-drawers~.
|
|
|
|
- {{{kbd(#+LINK: linkword replace)}}} ::
|
|
#+vindex: org-link-abbrev-alist
|
|
|
|
These lines (several are allowed) specify link abbreviations. See
|
|
[[Link abbreviations]]. The corresponding variable is ~org-link-abbrev-alist~.
|
|
|
|
- {{{kbd(#+PRIORITIES: highest lowest default)}}} ::
|
|
#+vindex: org-highest-priority
|
|
#+vindex: org-lowest-priority
|
|
#+vindex: org-default-priority
|
|
|
|
This line sets the limits and the default for the priorities. All
|
|
three must be either letters A-Z or numbers 0-9. The highest priority
|
|
must have a lower ASCII number than the lowest priority.
|
|
|
|
- {{{kbd(#+PROPERTY: Property_Name Value)}}} ::
|
|
|
|
This line sets a default inheritance value for entries in the current
|
|
buffer, most useful for specifying the allowed values of a property.
|
|
|
|
- {{{kbd(#+SETUPFILE: file)}}} ::
|
|
#+cindex: #+SETUPFILE
|
|
|
|
This line defines a file that holds more in-buffer setup. Normally
|
|
this is entirely ignored. Only when the buffer is parsed for
|
|
option-setting lines (i.e., when starting Org mode for a file, when
|
|
pressing {{{kbd(C-c C-c)}}} in a settings line, or when exporting),
|
|
then the contents of this file are parsed as if they had been included
|
|
in the buffer. In particular, the file can be any other Org mode file
|
|
with internal setup. You can visit the file the cursor is in the line
|
|
with {{{kbd(C-c ')}}}.
|
|
|
|
- {{{kbd(#+STARTUP:)}}} ::
|
|
#+cindex: #+STARTUP:
|
|
|
|
This line sets options to be used at startup of Org mode, when an
|
|
Org file is being visited.
|
|
|
|
The first set of options deals with the initial visibility of the
|
|
outline tree. The corresponding variable for global default settings
|
|
is ~org-startup-folded~, with a default value ~t~, which means ~overview~.
|
|
|
|
#+vindex: org-startup-folded
|
|
#+cindex: @code{overview}, STARTUP keyword
|
|
#+cindex: @code{content}, STARTUP keyword
|
|
#+cindex: @code{showall}, STARTUP keyword
|
|
#+cindex: @code{showeverything}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~overview~ :: top-level headlines only
|
|
- ~content~ :: all headlines
|
|
- ~showall~ :: no folding of any entries
|
|
- ~showeverything~ :: show even drawer contents
|
|
|
|
#+vindex: org-startup-indented
|
|
#+cindex: @code{indent}, STARTUP keyword
|
|
#+cindex: @code{noindent}, STARTUP keyword
|
|
|
|
Dynamic virtual indentation is controlled by the variable ~org-startup-indented~.[fn:182]
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~indent~ :: start with ~org-indent-mode~ turned on
|
|
- ~noindent~ :: start with ~org-indent-mode~ turned off
|
|
|
|
#+vindex: org-startup-align-all-tables
|
|
|
|
Then there are options for aligning tables upon visiting a file. This
|
|
is useful in files containing narrowed table columns. The corresponding
|
|
variable is ~org-startup-align-all-tables~, with a default value ~nil~.
|
|
|
|
#+cindex: @code{align}, STARTUP keyword
|
|
#+cindex: @code{noalign}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~align~ :: align all tables
|
|
- ~noalign~ :: don't align tables on startup
|
|
|
|
#+vindex: org-startup-with-inline-images
|
|
|
|
When visiting a file, inline images can be automatically displayed.
|
|
The corresponding variable is ~org-startup-with-inline-images~, with a
|
|
default value ~nil~ to avoid delays when visiting a file.
|
|
|
|
#+cindex: @code{inlineimages}, STARTUP keyword
|
|
#+cindex: @code{noinlineimages}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~inlineimages~ show inline images
|
|
- ~noinlineimages~ don't show inline images on startup
|
|
|
|
#+vindex: org-log-done
|
|
#+vindex: org-log-note-clock-out
|
|
#+vindex: org-log-repeat
|
|
|
|
Logging the closing and reopening of TODO items and clock intervals
|
|
can be configured using these options (see variables ~org-log-done~, ~org-log-note-clock-out~, and ~org-log-repeat~).
|
|
|
|
#+cindex: @code{logdone}, STARTUP keyword
|
|
#+cindex: @code{lognotedone}, STARTUP keyword
|
|
#+cindex: @code{nologdone}, STARTUP keyword
|
|
#+cindex: @code{lognoteclock-out}, STARTUP keyword
|
|
#+cindex: @code{nolognoteclock-out}, STARTUP keyword
|
|
#+cindex: @code{logrepeat}, STARTUP keyword
|
|
#+cindex: @code{lognoterepeat}, STARTUP keyword
|
|
#+cindex: @code{nologrepeat}, STARTUP keyword
|
|
#+cindex: @code{logreschedule}, STARTUP keyword
|
|
#+cindex: @code{lognotereschedule}, STARTUP keyword
|
|
#+cindex: @code{nologreschedule}, STARTUP keyword
|
|
#+cindex: @code{logredeadline}, STARTUP keyword
|
|
#+cindex: @code{lognoteredeadline}, STARTUP keyword
|
|
#+cindex: @code{nologredeadline}, STARTUP keyword
|
|
#+cindex: @code{logrefile}, STARTUP keyword
|
|
#+cindex: @code{lognoterefile}, STARTUP keyword
|
|
#+cindex: @code{nologrefile}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~logdone~ :: record a timestamp when an item is marked DONE
|
|
- ~lognotedone~ :: record timestamp and a note when DONE
|
|
- ~nologdone~ :: don't record when items are marked DONE
|
|
- ~logrepeat~ :: record a time when reinstating a repeating item
|
|
- ~lognoterepeat~ :: record a note when reinstating a repeating item
|
|
- ~nologrepeat~ :: do not record when reinstating repeating item
|
|
- ~lognoteclock-out~ :: record a note when clocking out
|
|
- ~nolognoteclock-out~ :: don't record a note when clocking out
|
|
- ~logreschedule~ :: record a timestamp when scheduling time changes
|
|
- ~lognotereschedule~ :: record a note when scheduling time changes
|
|
- ~nologreschedule~ :: do not record when a scheduling date changes
|
|
- ~logredeadline~ :: record a timestamp when deadline changes
|
|
- ~lognoteredeadline~ :: record a note when deadline changes
|
|
- ~nologredeadline~ :: do not record when a deadline date changes
|
|
- ~logrefile~ :: record a timestamp when refiling
|
|
- ~lognoterefile~ :: record a note when refiling
|
|
- ~nologrefile~ :: do not record when refiling
|
|
|
|
#+vindex: org-hide-leading-stars
|
|
#+vindex: org-odd-levels-only
|
|
|
|
Here are the options for hiding leading stars in outline headings, and
|
|
for indenting outlines. The corresponding variables are ~org-hide-leading-stars~ and ~org-odd-levels-only~, both with a
|
|
default setting ~nil~ (meaning ~showstars~ and ~oddeven~).
|
|
|
|
#+cindex: @code{hidestars}, STARTUP keyword
|
|
#+cindex: @code{showstars}, STARTUP keyword
|
|
#+cindex: @code{odd}, STARTUP keyword
|
|
#+cindex: @code{even}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~hidestars~ :: make all but one of the stars starting a headline invisible.
|
|
- ~showstars~ :: show all stars starting a headline
|
|
- ~indent~ :: virtual indentation according to outline level
|
|
- ~noindent~ :: no virtual indentation according to outline level
|
|
- ~odd~ :: allow only odd outline levels (1, 3, ...)
|
|
- ~oddeven~ :: allow all outline levels
|
|
|
|
#+vindex: org-put-time-stamp-overlays
|
|
#+vindex: org-time-stamp-overlay-formats
|
|
|
|
To turn on custom format overlays over timestamps (variables ~org-put-time-stamp-overlays~ and ~org-time-stamp-overlay-formats~),
|
|
use:
|
|
|
|
#+cindex: @code{customtime}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~customtime~ :: overlay custom time format
|
|
|
|
#+vindex: constants-unit-system
|
|
|
|
The following options influence the table spreadsheet (variable ~constants-unit-system~).
|
|
|
|
#+cindex: @code{constcgs}, STARTUP keyword
|
|
#+cindex: @code{constSI}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~constcgs~ :: {{{file(constants.el)}}} should use the c-g-s unit system
|
|
- ~constSI~ :: {{{file(constants.el)}}} should use the SI unit system
|
|
|
|
#+vindex: org-footnote-define-inline
|
|
#+vindex: org-footnote-auto-label
|
|
#+vindex: org-footnote-auto-adjust
|
|
|
|
To influence footnote settings, use the following keywords. The
|
|
corresponding variables are ~org-footnote-define-inline~, ~org-footnote-auto-label~, and ~org-footnote-auto-adjust~.
|
|
|
|
#+cindex: @code{fninline}, STARTUP keyword
|
|
#+cindex: @code{nofninline}, STARTUP keyword
|
|
#+cindex: @code{fnlocal}, STARTUP keyword
|
|
#+cindex: @code{fnprompt}, STARTUP keyword
|
|
#+cindex: @code{fnauto}, STARTUP keyword
|
|
#+cindex: @code{fnconfirm}, STARTUP keyword
|
|
#+cindex: @code{fnplain}, STARTUP keyword
|
|
#+cindex: @code{fnadjust}, STARTUP keyword
|
|
#+cindex: @code{nofnadjust}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~fninline~ :: define footnotes inline
|
|
- ~fnnoinline~ :: define footnotes in separate section
|
|
- ~fnlocal~ :: define footnotes near first reference, but not inline
|
|
- ~fnprompt~ :: prompt for footnote labels
|
|
- ~fnauto~ :: create ~[fn:1]~-like labels automatically (default)
|
|
- ~fnconfirm~ :: offer automatic label for editing or confirmation
|
|
- ~fnplain~ :: create ~[1]~-like labels automatically
|
|
- ~fnadjust~ :: automatically renumber and sort footnotes
|
|
- ~nofnadjust~ :: do not renumber and sort automatically
|
|
|
|
#+cindex: org-hide-block-startup
|
|
|
|
To hide blocks on startup, use these keywords. The corresponding
|
|
variable is ~org-hide-block-startup~.
|
|
|
|
#+cindex: @code{hideblocks}, STARTUP keyword
|
|
#+cindex: @code{nohideblocks}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~hideblocks~ :: Hide all begin/end blocks on startup
|
|
- ~nohideblocks~ :: Do not hide blocks on startup
|
|
|
|
#+cindex: org-pretty-entities
|
|
|
|
The display of entities as UTF-8 characters is governed by the
|
|
variable ~org-pretty-entities~ and the keywords
|
|
|
|
#+cindex: @code{entitiespretty}, STARTUP keyword
|
|
#+cindex: @code{entitiesplain}, STARTUP keyword
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~entitiespretty~ :: Show entities as UTF-8 characters where possible
|
|
- ~entitiesplain~ :: Leave entities plain
|
|
|
|
- {{{kbd(#+TAGS: TAG1(c1) TAG2(c2))}}} ::
|
|
#+vindex: org-tag-alist
|
|
|
|
These lines (several such lines are allowed) specify the valid tags in
|
|
this file, and (potentially) the corresponding /fast tag selection/
|
|
keys. The corresponding variable is ~org-tag-alist~.
|
|
|
|
- {{{kbd(#+TBLFM:)}}} ::
|
|
|
|
This line contains the formulas for the table directly above the line.
|
|
|
|
- {{{kbd(#+TITLE:)}}}, {{{kbd(#+AUTHOR:)}}}, {{{kbd(#+EMAIL:)}}}, {{{kbd(#+LANGUAGE:)}}}, {{{kbd(#+TEXT:)}}}, {{{kbd(#+DATE:)}}}, {{{kbd(#+OPTIONS:)}}}, {{{kbd(#+BIND:)}}}, {{{kbd(#+XSLT:)}}}, {{{kbd(#+DESCRIPTION:)}}}, {{{kbd(#+KEYWORDS:)}}}, {{{kbd(#+LaTeX_HEADER:)}}}, {{{kbd(#+STYLE:)}}}, {{{kbd(#+LINK_UP:)}}}, {{{kbd(#+LINK_HOME:)}}}, {{{kbd(#+EXPORT_SELECT_TAGS:)}}}, {{{kbd(#+EXPORT_EXCLUDE_TAGS:)}}} ::
|
|
|
|
These lines provide settings for exporting files. For more details see
|
|
[[Export options]].
|
|
|
|
- {{{kbd(#+TODO:)}}}, {{{kbd(#+SEQ_TODO:)}}}, {{{kbd(#+TYP_TODO:)}}} ::
|
|
#+vindex: org-todo-keywords
|
|
|
|
These lines set the TODO keywords and their interpretation in the
|
|
current file. The corresponding variable is ~org-todo-keywords~.
|
|
|
|
** The very busy C-c C-c key
|
|
:PROPERTIES:
|
|
:DESCRIPTION: When in doubt, press C-c C-c
|
|
:TITLE: The very busy C-c C-c key
|
|
:END:
|
|
#+kindex: C-c C-c
|
|
#+cindex: C-c C-c, overview
|
|
|
|
The key {{{kbd(C-c C-c)}}} has many purposes in Org, which are all
|
|
mentioned scattered throughout this manual. One specific function of
|
|
this key is to add /tags/ to a headline (see [[Tags]]). In many
|
|
other circumstances it means something like "Hey Org, look
|
|
here and update according to what you see here." Here is a summary of
|
|
what this means in different contexts.
|
|
|
|
- If there are highlights in the buffer from the creation of a sparse
|
|
tree, or from clock display, remove these highlights.
|
|
- If the cursor is in one of the special ~#+KEYWORD~ lines, this
|
|
triggers scanning the buffer for these lines and updating the
|
|
information.
|
|
- If the cursor is inside a table, realign the table. This command
|
|
works even if the automatic table editor has been turned off.
|
|
- If the cursor is on a ~#+TBLFM~ line, re-apply the formulas to the
|
|
entire table.
|
|
- If the current buffer is a capture buffer, close the note and file
|
|
it. With a prefix argument, file it, without further interaction, to
|
|
the default location.
|
|
- If the cursor is on a ~<<<target>>>~, update radio targets and
|
|
corresponding links in this buffer.
|
|
- If the cursor is in a property line or at the start or end of a
|
|
property drawer, offer property commands.
|
|
- If the cursor is at a footnote reference, go to the corresponding
|
|
definition, and vice versa.
|
|
- If the cursor is on a statistics cookie, update it.
|
|
- If the cursor is in a plain list item with a checkbox, toggle the
|
|
status of the checkbox.
|
|
- If the cursor is on a numbered item in a plain list, renumber the
|
|
ordered list.
|
|
- If the cursor is on the ~#+BEGIN~ line of a dynamic block, the block
|
|
is updated.
|
|
- If the cursor is at a timestamp, fix the day name in the timestamp.
|
|
|
|
** Clean view
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Getting rid of leading stars in the outline
|
|
:TITLE: A cleaner outline view
|
|
:END:
|
|
#+cindex: hiding leading stars
|
|
#+cindex: dynamic indentation
|
|
#+cindex: odd-levels-only outlines
|
|
#+cindex: clean outline view
|
|
|
|
Some people find it noisy and distracting that the Org headlines start
|
|
with a potentially large number of stars, and that text below the
|
|
headlines is not indented. While this is no problem when writing a
|
|
/book-like/ document where the outline headings are really section
|
|
headings, in a more /list-oriented/ outline, indented structure is a
|
|
lot cleaner:
|
|
|
|
#+begin_example
|
|
,* Top level headline | * Top level headline
|
|
,** Second level | * Second level
|
|
,*** 3rd level | * 3rd level
|
|
some text | some text
|
|
,*** 3rd level | * 3rd level
|
|
more text | more text
|
|
,* Another top level headline | * Another top level headline
|
|
#+end_example
|
|
|
|
{{{noindent}}} If you are using at least Emacs 23.2 and version 6.29
|
|
of Org, this kind of view can be achieved dynamically at display time
|
|
using ~org-indent-mode~.[fn:183] In this minor mode, all lines are
|
|
prefixed for display with the necessary amount of space.[fn:154] Also
|
|
headlines are prefixed with additional stars, so that the amount of
|
|
indentation shifts by two spaces per level.[fn:155] All headline stars
|
|
but the last one are made invisible using the ~org-hide~ face---see
|
|
below under {{{samp(2.)}}} for more information on how this
|
|
works.[fn:156] You can turn on ~org-indent-mode~ for all files by
|
|
customizing the variable ~org-startup-indented~, or you can turn it on
|
|
for individual files using
|
|
|
|
#+begin_example
|
|
,#+STARTUP: indent
|
|
#+end_example
|
|
|
|
If you want a similar effect in an earlier version of Emacs and/or
|
|
Org, or if you want the indentation to be hard space characters so
|
|
that the plain text file looks as similar as possible to the Emacs
|
|
display, Org supports you in the following way:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Indentation of text below headlines ::
|
|
|
|
You may indent text below each headline to make the left boundary line up
|
|
with the headline, like
|
|
|
|
#+begin_example
|
|
,*** 3rd level
|
|
more text, now indented
|
|
#+end_example
|
|
|
|
#+vindex: org-adapt-indentation
|
|
|
|
Org supports this with paragraph filling, line wrapping, and structure
|
|
editing,
|
|
preserving or adapting the indentation as appropriate.[fn:157]
|
|
|
|
- Hiding leading stars ::
|
|
#+vindex: org-hide-leading-stars
|
|
|
|
You can modify the display in such a way that all leading stars become
|
|
invisible. To do this in a global way, configure the variable ~org-hide-leading-stars~ or change this on a per-file basis with
|
|
|
|
#+begin_example
|
|
,#+STARTUP: hidestars
|
|
,#+STARTUP: showstars
|
|
#+end_example
|
|
|
|
With hidden stars, the tree becomes:
|
|
|
|
#+begin_example
|
|
,* Top level headline
|
|
, * Second level
|
|
, * 3rd level
|
|
...
|
|
#+end_example
|
|
|
|
#+vindex: org-hide @r{(face)}
|
|
|
|
{{{noindent}}} The leading stars are not truly replaced by whitespace,
|
|
they are only fontified with the face ~org-hide~ that uses the
|
|
background color as font color. If you are not using either white or
|
|
black background, you may have to customize this face to get the
|
|
wanted effect. Another possibility is to set this font such that the
|
|
extra stars are /almost/ invisible, for example using the color ~grey90~ on a white background.
|
|
- Odd levels ::
|
|
#+vindex: org-odd-levels-only
|
|
|
|
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.[fn:158] 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 ~org-odd-levels-only~, or set this
|
|
on a per-file basis with one of the following lines:
|
|
|
|
#+begin_example
|
|
,#+STARTUP: odd
|
|
,#+STARTUP: oddeven
|
|
#+end_example
|
|
|
|
You can convert an Org file from single-star-per-level to the
|
|
double-star-per-level convention with {{{kbdkey(M-x
|
|
org-convert-to-odd-levels , RET)}}} in that file. The reverse
|
|
operation is {{{kbd(M-x org-convert-to-oddeven-levels)}}}.
|
|
|
|
** TTY keys
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Using Org on a tty
|
|
:TITLE: Using Org on a tty
|
|
:END:
|
|
|
|
Because Org contains a large number of commands, by default many of
|
|
Org's core commands are bound to keys that are generally not
|
|
accessible on a tty, such as the cursor keys ({{{key(left)}}},
|
|
{{{key(right)}}}, {{{key(up)}}}, {{{key(down)}}}), {{{key(TAB)}}} and
|
|
{{{key(RET)}}}, in particular when used together with modifiers like
|
|
{{{key(Meta)}}} and/or {{{key(Shift)}}}. To access these commands on a
|
|
tty when special keys are unavailable, the following alternative
|
|
bindings can be used. The tty bindings below will likely be more
|
|
cumbersome; you may find for some of the bindings below that a
|
|
customized workaround suits you better. For example, changing a
|
|
timestamp is really only fun with {{{kbdkey(S-,cursor)}}} keys,
|
|
whereas on a tty you would rather use {{{kbd(C-c .)}}} to re-insert
|
|
the timestamp.
|
|
|
|
#+attr_texinfo: :columns 0.2 0.3 0.1 0.4
|
|
| Default | Alternative 1 | Speed key | Alternative 2 |
|
|
|--------------------------+------------------------------+--------------+---------------------------|
|
|
| {{{kbdkey(S-,TAB)}}} | {{{kbdspckey(C-u,TAB)}}} | {{{kbd(C)}}} | |
|
|
| {{{kbdkey(M-,left)}}} | {{{kbd(C-c C-x l)}}} | {{{kbd(l)}}} | {{{kbdkeys(,Esc,left)}}} |
|
|
| {{{kbdkey(M-S-,left)}}} | {{{kbd(C-c C-x L)}}} | {{{kbd(L)}}} | |
|
|
| {{{kbdkey(M-,right)}}} | {{{kbd(C-c C-x r)}}} | {{{kbd(r)}}} | {{{kbdkeys(,Esc,right)}}} |
|
|
| {{{kbdkey(M-S-,right)}}} | {{{kbd(C-c C-x R)}}} | {{{kbd(R)}}} | |
|
|
| {{{kbdkey(M-,up)}}} | {{{kbd(C-c C-x u)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,up)}}} |
|
|
| {{{kbdkey(M-S-,up)}}} | {{{kbd(C-c C-x U)}}} | {{{kbd(U)}}} | |
|
|
| {{{kbdkey(M-,down)}}} | {{{kbd(C-c C-x d)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,down)}}} |
|
|
| {{{kbdkey(M-S-,down)}}} | {{{kbd(C-c C-x D)}}} | {{{kbd(D)}}} | |
|
|
| {{{kbdkey(S-,RET)}}} | {{{kbd(C-c C-x c)}}} | {{{kbd( )}}} | |
|
|
| {{{kbdkey(M-,RET)}}} | {{{kbd(C-c C-x m)}}} | {{{kbd( )}}} | {{{kbdkeys(,Esc,RET)}}} |
|
|
| {{{kbdkey(M-S-,RET)}}} | {{{kbd(C-c C-x M)}}} | {{{kbd( )}}} | |
|
|
| {{{kbdkey(S-,left)}}} | {{{kbdspckey(C-c,left)}}} | {{{kbd( )}}} | |
|
|
| {{{kbdkey(S-,right)}}} | {{{kbdspckey(C-c,right)}}} | {{{kbd( )}}} | |
|
|
| {{{kbdkey(S-,up)}}} | {{{kbdspckey(C-c,up)}}} | {{{kbd( )}}} | |
|
|
| {{{kbdkey(S-,down)}}} | {{{kbdspckey(C-c,down)}}} | {{{kbd( )}}} | |
|
|
| {{{kbdkey(C-S-,left)}}} | {{{kbdspckey(C-c C-x,left)}}} | {{{kbd( )}}} | |
|
|
| {{{kbdkey(C-S-,right)}}} | {{{kbdspckey(C-c C-x,right)}}} | {{{kbd( )}}} | |
|
|
|
|
** Interaction
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Other Emacs packages
|
|
:TITLE: Interaction with other packages
|
|
:END:
|
|
#+cindex: packages, interaction with other
|
|
Org lives in the world of GNU Emacs and interacts in various ways
|
|
with other code out there.
|
|
|
|
*** FIXME Cooperation
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Packages Org cooperates with
|
|
:TITLE: Packages that Org cooperates with
|
|
:END:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{file(calc.el)}}} by Dave Gillespie ::
|
|
#+cindex: @file{calc.el}
|
|
#+cindex: Gillespie, Dave
|
|
|
|
Org uses the Calc package for implementing spreadsheet functionality
|
|
in its tables (see [[The spreadsheet]]). Org checks for the availability
|
|
of Calc by looking for the function ~calc-eval~ which will have been
|
|
autoloaded during setup if Calc has been installed properly. As of
|
|
Emacs 22, Calc is part of the Emacs distribution. Another possibility
|
|
for interaction between the two packages is using Calc for embedded
|
|
calculations. See [[info:calc:Embedded Mode][GNU Emacs Calc Manual]].
|
|
|
|
- {{{file(constants.el)}}} by Carsten Dominik ::
|
|
#+cindex: @file{constants.el}
|
|
#+cindex: Dominik, Carsten
|
|
#+vindex: org-table-formula-constants
|
|
|
|
In a table formula (see [[The spreadsheet]]), it is possible to use names
|
|
for natural constants or units. Instead of defining your own constants
|
|
in the variable ~org-table-formula-constants~, install the
|
|
{{{file(constants)}}} package which defines a large number of
|
|
constants and units, and lets you use unit prefixes like {{{samp(M)}}}
|
|
for {{{samp(Mega)}}}, etc. You will need version 2.0 of this package,
|
|
available at [[http://www.astro.uva.nl/~dominik/Tools]]. Org checks for
|
|
the function ~constants-get~, which has to be autoloaded in your
|
|
setup. See the installation instructions in the file
|
|
{{{file(constants.el)}}}.
|
|
|
|
- {{{file(cdlatex.el)}}} by Carsten Dominik ::
|
|
#+cindex: @file{cdlatex.el}
|
|
#+cindex: Dominik, Carsten
|
|
|
|
Org mode can make use of the CDLaTeX package to efficiently enter
|
|
LaTeX fragments into Org files. See [[CDLaTeX mode]].
|
|
|
|
- {{{file(imenu.el)}}} by Ake Stenhoff and Lars Lindberg ::
|
|
#+cindex: @file{imenu.el}
|
|
#+cindex: Stenhoff, Ake
|
|
#+cindex: Lindberg, Lars
|
|
|
|
Imenu allows menu access to an index of items in a file. Org mode
|
|
supports Imenu---all you need to do to get the index is the following:
|
|
|
|
#+begin_src emacs-lisp
|
|
(add-hook 'org-mode-hook
|
|
(lambda () (imenu-add-to-menubar "Imenu")))
|
|
#+end_src
|
|
|
|
#+vindex: org-imenu-depth
|
|
|
|
By default the index is two levels deep---you can modify the depth
|
|
using the option ~org-imenu-depth~.
|
|
|
|
- {{{file(remember.el)}}} by John Wiegley ::
|
|
#+cindex: @file{remember.el}
|
|
#+cindex: Wiegley, John
|
|
|
|
Org used to use this package for capture, but no longer does.
|
|
|
|
- {{{file(speedbar.el)}}} by Eric M. Ludlam ::
|
|
#+cindex: @file{speedbar.el}
|
|
#+cindex: Ludlam, Eric M.
|
|
|
|
Speedbar is a package that creates a special frame displaying files and
|
|
index items in files. Org mode supports Speedbar and allows you to
|
|
drill into Org files directly from the Speedbar. It also allows you to
|
|
restrict the scope of agenda commands to a file or a subtree by using
|
|
the command {{{kbd(<)}}} in the Speedbar frame.
|
|
|
|
- {{{file(table.el)}}} by Takaaki Ota ::
|
|
#+kindex: C-c C-c
|
|
#+cindex: table editor, @file{table.el}
|
|
#+cindex: @file{table.el}
|
|
#+cindex: Ota, Takaaki
|
|
|
|
Complex ASCII tables with automatic line wrapping, column- and row-spanning,
|
|
and alignment can be created using the Emacs table package by Takaaki Ota
|
|
([[http://sourceforge.net/projects/table]], and also part of Emacs 22).
|
|
Org mode will recognize these tables and export them properly. Because of
|
|
interference with other Org mode functionality, you unfortunately cannot edit
|
|
these tables directly in the buffer. Instead, you need to use the command
|
|
{{{kbd(C-c ')}}} to edit them, similar to source code snippets.
|
|
|
|
- {{{kbd(C-c ')}}}, ~org-edit-special~ ::
|
|
#+kindex: C-c '
|
|
|
|
Edit a {{{file(table.el)}}} table. Works when the cursor is in a
|
|
table.el table.
|
|
|
|
- {{{kbd(C-c XXX)}}}, ~org-table-create-with-table.el~ ::
|
|
#+kindex: C-c ~
|
|
# Should be ~
|
|
Insert a {{{file(table.el)}}} table. If there is already a table at
|
|
point, this command converts it between the {{{file(table.el)}}}
|
|
format and the Org mode format. See the documentation string of the
|
|
command ~org-convert-table~ for the restrictions under which this is
|
|
possible.
|
|
|
|
{{{file(table.el)}}} is part of Emacs since Emacs 22.
|
|
|
|
- {{{file(footnote.el)}}} by Steven L. Baur ::
|
|
#+cindex: @file{footnote.el}
|
|
#+cindex: Baur, Steven L.
|
|
|
|
Org mode recognizes numerical footnotes as provided by this package.
|
|
However, Org mode also has its own footnote support (see [[Creating footnotes]]),
|
|
which makes using {{{file(footnote.el)}}} unnecessary.
|
|
|
|
*** Conflicts
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Packages that lead to conflicts
|
|
:END:
|
|
|
|
#+cindex: @code{shift-selection-mode}
|
|
#+vindex: org-support-shift-select
|
|
|
|
In Emacs 23, ~shift-selection-mode~ is on by default, meaning that
|
|
cursor motions combined with the shift key should start or enlarge
|
|
regions. This conflicts with the use of {{{kbdkey(S-,cursor)}}}
|
|
commands in Org to change timestamps, TODO keywords, priorities, and
|
|
item bullet types if the cursor is at such a location. By default,
|
|
{{{kbdkey(S-,cursor)}}} commands outside special contexts don't do
|
|
anything, but you can customize the variable
|
|
~org-support-shift-select~. Org mode then tries to accommodate shift
|
|
selection by using it outside of the special contexts where
|
|
special commands apply, and by extending an existing active
|
|
region even if the cursor moves across a special context.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{file(CUA.el)}}} by Kim. F. Storm ::
|
|
#+cindex: @file{CUA.el}
|
|
#+cindex: Storm, Kim. F.
|
|
#+vindex: org-replace-disputed-keys
|
|
|
|
Key bindings in Org conflict with the {{{kbdkey(S-,<cursor>)}}} keys
|
|
used by CUA mode (as well as ~pc-select-mode~ and ~s-region-mode~) to
|
|
select and extend the region. In fact, Emacs 23 has this built-in in
|
|
the form of ~shift-selection-mode~, see previous paragraph. If you are
|
|
using Emacs 23, you probably don't want to use another package for
|
|
this purpose. However, if you prefer to leave these keys to a
|
|
different package while working in Org mode, configure the variable
|
|
~org-replace-disputed-keys~. When set, Org will move the following key
|
|
bindings in Org files, and in the agenda buffer (but not during date
|
|
selection).
|
|
|
|
| S-UP {{{result}}} M-p | S-DOWN {{{result}}} M-n |
|
|
| S-LEFT {{{result}}} M-- | S-RIGHT {{{result}}} M-+ |
|
|
| C-S-LEFT {{{result}}} M-S-- | C-S-RIGHT {{{result}}} M-S-+ |
|
|
|
|
#+vindex: org-disputed-keys
|
|
|
|
Yes, these are unfortunately more difficult to remember. If you want
|
|
to have other replacement keys, look at the variable ~org-disputed-keys~.
|
|
|
|
- {{{file(filladapt.el)}}} by Kyle Jones ::
|
|
#+cindex: @file{filladapt.el}
|
|
#+cindex: Jones, Kyle
|
|
|
|
Org mode tries to do the right thing when filling paragraphs, list
|
|
items and other elements. Many users reported they had problems using
|
|
both {{{file(filladapt.el)}}} and Org mode, so a safe thing to do is
|
|
to disable it like this:
|
|
|
|
#+begin_src emacs-lisp
|
|
(add-hook 'org-mode-hook 'turn-off-filladapt-mode)
|
|
#+end_src
|
|
|
|
- {{{file(yasnippet.el)}}} ::
|
|
#+cindex: @file{yasnippet.el}
|
|
|
|
The way Org mode binds the {{{key(TAB)}}} key (binding to ~[tab]~
|
|
instead of ~"\t"~) overrules YASnippet's access to this key. The
|
|
following code fixed this problem:
|
|
|
|
#+begin_src emacs-lisp
|
|
(add-hook 'org-mode-hook
|
|
(lambda ()
|
|
(setq-local yas/trigger-key [tab])
|
|
(define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
|
|
#+end_src
|
|
|
|
The latest version of yasnippet doesn't play well with Org mode. If the
|
|
above code does not fix the conflict, start by defining the following
|
|
function:
|
|
|
|
#+begin_src emacs-lisp
|
|
(defun yas/org-very-safe-expand ()
|
|
(let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
|
|
#+end_src
|
|
|
|
Then, tell Org mode what to do with the new function:
|
|
|
|
#+begin_src emacs-lisp
|
|
(add-hook 'org-mode-hook
|
|
(lambda ()
|
|
(make-variable-buffer-local 'yas/trigger-key)
|
|
(setq yas/trigger-key [tab])
|
|
(add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
|
|
(define-key yas/keymap [tab] 'yas/next-field)))
|
|
#+end_src
|
|
|
|
- {{{file(windmove.el)}}} by Hovav Shacham ::
|
|
#+cindex: @file{windmove.el}
|
|
#+cindex: Shacham, Hovav
|
|
|
|
This package also uses the {{{kbd(S-<cursor>)}}} keys, so everything
|
|
written in the paragraph above about CUA mode also applies here. If
|
|
you want make the windmove function active in locations where Org mode
|
|
does not have special functionality on {{{kbdkey(S-,cursor)}}}, add
|
|
this to your configuration:
|
|
|
|
#+begin_src emacs-lisp
|
|
;; Make windmove work in org-mode:
|
|
(add-hook 'org-shiftup-final-hook 'windmove-up)
|
|
(add-hook 'org-shiftleft-final-hook 'windmove-left)
|
|
(add-hook 'org-shiftdown-final-hook 'windmove-down)
|
|
(add-hook 'org-shiftright-final-hook 'windmove-right)
|
|
#+end_src
|
|
|
|
- {{{file(viper.el)}}} by Michael Kifer ::
|
|
#+cindex: @file{viper.el}
|
|
#+cindex: Kifer, Michael
|
|
#+kindex: C-c /
|
|
|
|
Viper uses {{{kbd(C-c /)}}} and therefore makes this key not access the
|
|
corresponding Org mode command ~org-sparse-tree~. You need to find
|
|
another key for this command, or override the key in ~viper-vi-global-user-map~ with
|
|
|
|
#+begin_src emacs-lisp
|
|
(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
|
|
#+end_src
|
|
|
|
** org-crypt
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Encrypting Org files
|
|
:END:
|
|
#+cindex: @file{+org-crypt.el}
|
|
#+cindex: @code{org-decrypt-entry}
|
|
|
|
Org-crypt will encrypt the text of an entry, but not the headline, or
|
|
properties. Org-crypt uses the Emacs EasyPG library to encrypt and
|
|
decrypt files.
|
|
|
|
Any text below a headline that has a {{{samp(:crypt:)}}} tag will
|
|
automatically be encrypted when the file is saved. If you want to use
|
|
a different tag just customize the ~org-crypt-tag-matcher~ setting.
|
|
|
|
To use org-crypt it is suggested that you have the following in your
|
|
{{{file(.emacs)}}}:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(require 'org-crypt)
|
|
(org-crypt-use-before-save-magic)
|
|
(setq org-tags-exclude-from-inheritance (quote ("crypt")))
|
|
|
|
(setq org-crypt-key nil)
|
|
;; GPG key to use for encryption
|
|
;; Either the Key ID or set to nil to use symmetric encryption.
|
|
|
|
(setq auto-save-default nil)
|
|
;; Auto-saving does not cooperate with org-crypt.el: so you need
|
|
;; to turn it off if you plan to use org-crypt.el quite often.
|
|
;; Otherwise, you'll get an (annoying) message each time you
|
|
;; start Org.
|
|
|
|
;; To turn it off only locally, you can insert this:
|
|
;;
|
|
;; # -*- buffer-auto-save-file-name: nil; -*-
|
|
#+end_src
|
|
|
|
Excluding the crypt tag from inheritance prevents already encrypted text
|
|
being encrypted again.
|
|
|
|
* Hacking
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to hack your way around
|
|
:APPENDIX: Appendix
|
|
:END:
|
|
#+cindex: hacking
|
|
|
|
This appendix describes some ways a user can extend the functionality
|
|
of Org.
|
|
|
|
** Hooks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to reach into Org's internals
|
|
:END:
|
|
#+cindex: hooks
|
|
|
|
Org has a large number of hook variables that can be used to add
|
|
functionality. This appendix about hacking is going to illustrate the
|
|
use of some of them. A complete list of all hooks with documentation is
|
|
maintained by the Worg project and can be found at
|
|
[[http://orgmode.org/worg/org-configs/org-hooks.php]].
|
|
|
|
** Add-on packages
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Available extensions
|
|
:END:
|
|
#+cindex: add-on packages
|
|
|
|
A large number of add-on packages have been written by various
|
|
authors. These packages are not part of Emacs, but they are
|
|
distributed as contributed packages with the separate release
|
|
available at the Org mode home page at [[http://orgmode.org]]. The
|
|
list of contributed packages, along with documentation about each
|
|
package, is maintained by the Worg project at
|
|
[[http://orgmode.org/worg/org-contrib/]].
|
|
|
|
** Adding hyperlink types
|
|
:PROPERTIES:
|
|
:DESCRIPTION: New custom link types
|
|
:END:
|
|
#+cindex: hyperlinks, adding new types
|
|
|
|
Org has a large number of hyperlink types built-in (see [[Hyperlinks]]).
|
|
If you would like to add new link types, Org 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:
|
|
|
|
#+begin_example
|
|
[[man:printf][The printf manual]]
|
|
#+end_example
|
|
|
|
to show Unix manual pages inside Emacs:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
;;; org-man.el - Support for links to manpages in Org
|
|
|
|
(require 'org)
|
|
|
|
(org-add-link-type "man" 'org-man-open)
|
|
(add-hook 'org-store-link-functions 'org-man-store-link)
|
|
|
|
(defcustom org-man-command 'man
|
|
"The Emacs command to be used to display a man page."
|
|
:group 'org-link
|
|
:type '(choice (const man) (const woman)))
|
|
|
|
(defun org-man-open (path)
|
|
"Visit the manpage on PATH.
|
|
PATH should be a topic that can be thrown at the man command."
|
|
(funcall org-man-command path))
|
|
|
|
(defun org-man-store-link ()
|
|
"Store a link to a manpage."
|
|
(when (memq major-mode '(Man-mode woman-mode))
|
|
;; This is a man page, we do make this link
|
|
(let* ((page (org-man-get-page-name))
|
|
(link (concat "man:" page))
|
|
(description (format "Manpage for %s" page)))
|
|
(org-store-link-props
|
|
:type "man"
|
|
:link link
|
|
:description description))))
|
|
|
|
(defun org-man-get-page-name ()
|
|
"Extract the page name from the buffer name."
|
|
;; This works for both `Man-mode' and `woman-mode'.
|
|
(if (string-match " \\(\\S-+\\)\\*" (buffer-name))
|
|
(match-string 1 (buffer-name))
|
|
(error "Cannot create link to this man page")))
|
|
|
|
(provide 'org-man)
|
|
|
|
;;; org-man.el ends here
|
|
#+end_src
|
|
|
|
{{{noindent}}} You would activate this new link type in
|
|
{{{file(.emacs)}}} with:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(require 'org-man)
|
|
#+end_src
|
|
|
|
{{{noindent}}} Let's go through the file and see what it does.
|
|
#+vindex: org-store-link-functions
|
|
|
|
1. It does ~(require 'org)~ to make sure that {{{file(org.el)}}} has
|
|
been loaded.
|
|
|
|
2. The next line calls ~org-add-link-type~ to define a new link type
|
|
with prefix {{{samp(man)}}}. The call also contains the name of a
|
|
function that will be called to follow such a link.
|
|
|
|
3. The next line adds a function to ~org-store-link-functions~, in
|
|
order to allow the command {{{kbd(C-c l)}}} to record a useful link
|
|
in a buffer displaying a man page.
|
|
|
|
|
|
The rest of the file defines the necessary variables and functions.
|
|
First there is a customization variable that determines which Emacs
|
|
command should be used to display man pages. There are two options,
|
|
~man~ and ~woman~. Then the function to follow a link is defined. It
|
|
gets the link path as an argument---in this case the link path is just
|
|
a topic for the manual command. The function calls the value of
|
|
~org-man-command~ to display the man page.
|
|
|
|
Finally the function ~org-man-store-link~ is defined. When you try to
|
|
store a link with {{{kbd(C-c l)}}}, this function will be called to
|
|
try to make a link. The function must first decide if it is supposed
|
|
to create the link for this buffer type; we do this by checking the
|
|
value of the variable ~major-mode~. If not, the function must exit and
|
|
return the value ~nil~. If yes, the link is created by getting the
|
|
manual topic from the buffer name and prefixing it with the string
|
|
{{{samp(man:)}}}. Then it must call the command ~org-store-link-props~
|
|
and set the ~:type~ and ~:link~ properties. Optionally you can also
|
|
set the ~:description~ property to provide a default for the link
|
|
description when the link is later inserted into an Org buffer with
|
|
{{{kbd(C-c C-l)}}}.
|
|
|
|
When it makes sense for your new link type, you may also define a
|
|
function 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.
|
|
|
|
** Context-sensitive commands
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How to add functionality to such commands
|
|
:END:
|
|
#+cindex: context-sensitive commands, hooks
|
|
#+cindex: add-ons, context-sensitive commands
|
|
#+vindex: org-ctrl-c-ctrl-c-hook
|
|
|
|
Org has several commands that act differently depending on context.
|
|
The most important example is the {{{kbd(C-c C-c)}}} (see [[The very
|
|
busy C-c C-c key]]). Also the {{{kbd(M-cursor)}}} and
|
|
{{{kbd(M-S-cursor)}}} keys have this property.
|
|
|
|
Add-ons can tap into this functionality by providing a function that
|
|
detects special context for that add-on and executes functionality
|
|
appropriate for the context. Here is an example from Dan Davison's
|
|
{{{file(org-R.el)}}} which allows you to evaluate commands based on
|
|
the {{{file(R)}}} programming language.[fn:159] For this package,
|
|
special contexts are lines that start with ~#+R:~ or ~#+RR:~.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(defun org-R-apply-maybe ()
|
|
"Detect if this is context for org-R and execute R commands."
|
|
(if (save-excursion
|
|
(beginning-of-line 1)
|
|
(looking-at "#\\+RR?:"))
|
|
(progn (call-interactively 'org-R-apply)
|
|
t) ;; to signal that we took action
|
|
nil)) ;; to signal that we did not
|
|
|
|
(add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe)
|
|
#+end_src
|
|
|
|
The function first checks if the cursor is in such a line. If that is
|
|
the case, ~org-R-apply~ is called and the function returns ~t~ to
|
|
signal that action was taken, and {{{kbd(C-c C-c)}}} will stop looking
|
|
for other contexts. If the function finds it should do nothing
|
|
locally, it returns ~nil~ so that other, similar functions can have a
|
|
try.
|
|
|
|
** Tables in arbitrary syntax
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Orgtbl for LaTeX and other programs
|
|
:END:
|
|
#+cindex: tables, in other modes
|
|
#+cindex: lists, in other modes
|
|
#+cindex: Orgtbl mode
|
|
|
|
Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a
|
|
frequent feature request has been to make it work with native tables
|
|
in specific languages, for example LaTeX. However, this is
|
|
extremely hard to do in a general way, would lead to a customization
|
|
nightmare, and would take away much of the simplicity of the Orgtbl
|
|
mode table editor.
|
|
|
|
This appendix describes a different approach. We keep the Orgtbl mode
|
|
table in its native format (the source table), and use a custom
|
|
function to /translate/ the table to the correct syntax, and to
|
|
/install/ it in the right location (the target table). This puts
|
|
the burden of writing conversion functions on the user, but it allows
|
|
for a very flexible system.
|
|
|
|
Bastien added the ability to do the same with lists, in Orgstruct
|
|
mode. You can use Org's facilities to edit and structure lists by
|
|
turning ~orgstruct-mode~ on, then locally exporting such lists in
|
|
another format (HTML, LaTeX or Texinfo.)
|
|
|
|
*** Radio tables
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Sending and receiving radio tables
|
|
:END:
|
|
#+cindex: radio tables
|
|
|
|
To define the location of the target table, you first need to create
|
|
two lines that are comments in the current mode, but contain magic
|
|
words for Orgtbl mode to find. Orgtbl mode will insert the translated
|
|
table between these lines, replacing whatever was there before. For
|
|
example:
|
|
|
|
#+begin_example
|
|
/* BEGIN RECEIVE ORGTBL table_name */
|
|
/* END RECEIVE ORGTBL table_name */
|
|
#+end_example
|
|
|
|
{{{noindent}}} Just above the source table, we put a special line that
|
|
tells Orgtbl mode how to translate this table and where to install it.
|
|
For example:
|
|
|
|
#+cindex: #+ORGTBL
|
|
#+begin_example
|
|
,#+ORGTBL: SEND table_name translation_function arguments ...
|
|
#+end_example
|
|
|
|
{{{noindent}}} Here, ~table_name~ is the reference name for the table
|
|
that is also used in the receiver lines. ~translation_function~ is the
|
|
Lisp function that does the translation. Furthermore, the line can
|
|
contain a list of arguments (alternating key and value) at the end.
|
|
The arguments will be passed as a property list to the translation
|
|
function for interpretation. A few standard parameters are already
|
|
recognized and acted upon before the translation function is called:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:skip N~ ::
|
|
|
|
Skip the first N lines of the table. Hlines do count as separate lines
|
|
for this parameter!
|
|
|
|
- ~:skipcols (n1 n2 ...)~ ::
|
|
|
|
List of columns that should be skipped. If the table has a column with
|
|
calculation marks, that column is automatically discarded as well.
|
|
Please note that the translator function sees the table /after/ the
|
|
removal of these columns, the function never knows that there have
|
|
been additional columns.
|
|
|
|
- ~:no-escape t~ ::
|
|
|
|
When non-nil, do not escape special characters ~&%#_^~ when exporting
|
|
the table. The default value is nil.
|
|
|
|
|
|
{{{noindent}}} The one problem remaining is how to keep the source
|
|
table in the buffer without disturbing the normal workings of the
|
|
file, for example during compilation of a C file or processing of a
|
|
LaTeX file. There are a number of different solutions:
|
|
|
|
- The table could be placed in a block comment if that is supported by
|
|
the language. For example, in C mode you could wrap the table
|
|
between {{{samp(/*)}}} and {{{samp(*/)}}} lines.
|
|
|
|
- Sometimes it is possible to put the table after some kind of END
|
|
statement, for example ~\bye~ in TeX and ~\end{document}~ in
|
|
LaTeX.
|
|
|
|
- You can just comment the table line-by-line whenever you want to
|
|
process the file, and uncomment it whenever you need to edit the
|
|
table. This only sounds tedious---the command {{{kbd(M-x
|
|
orgtbl-toggle-comment)}}} makes this comment-toggling very easy, in
|
|
particular if you bind it to a key.
|
|
|
|
*** A LaTeX example
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Step by step, almost a tutorial
|
|
:TITLE: A LaTeX example of radio tables
|
|
:END:
|
|
#+cindex: @LaTeX{}, and Orgtbl mode
|
|
|
|
The best way to wrap the source table in LaTeX is to use the
|
|
~comment~ environment provided by {{{file(comment.sty)}}}. It has to
|
|
be activated by placing ~\usepackage{comment}~ into the document
|
|
header. Orgtbl mode can insert a radio table skeleton with the command
|
|
{{{kbd(M-x orgtbl-insert-radio-table)}}}.[fn:160] You will be prompted
|
|
for a table name, let's say we use {{{samp(salesfigures)}}}. You will
|
|
then get the following template:
|
|
|
|
#+cindex: #+ORGTBL, SEND
|
|
#+begin_example
|
|
% BEGIN RECEIVE ORGTBL salesfigures
|
|
% END RECEIVE ORGTBL salesfigures
|
|
\begin{comment}
|
|
#+ORGTBL: SEND salesfigures orgtbl-to-latex
|
|
| | |
|
|
\end{comment}
|
|
#+end_example
|
|
|
|
#+vindex: @LaTeX{}-verbatim-environments
|
|
|
|
{{{noindent}}} The ~#+ORGTBL: SEND~ line tells Orgtbl mode to use the
|
|
function ~orgtbl-to-latex~ to convert the table into LaTeX and to
|
|
put it into the receiver location with name ~salesfigures~. You may
|
|
now fill in the table---feel free to use the spreadsheet features:[fn:161]
|
|
|
|
#+begin_example
|
|
% BEGIN RECEIVE ORGTBL salesfigures
|
|
% END RECEIVE ORGTBL salesfigures
|
|
\begin{comment}
|
|
#+ORGTBL: SEND salesfigures orgtbl-to-latex
|
|
| Month | Days | Nr sold | per day |
|
|
|-------+------+---------+---------|
|
|
| Jan | 23 | 55 | 2.4 |
|
|
| Feb | 21 | 16 | 0.8 |
|
|
| March | 22 | 278 | 12.6 |
|
|
#+TBLFM: $4=$3/$2;%.1f
|
|
% $ (optional extra dollar to keep font-lock happy, see footnote)
|
|
\end{comment}
|
|
#+end_example
|
|
|
|
{{{noindent}}} When you are done, press {{{kbd(C-c C-c)}}} in the
|
|
table to get the converted 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 that the table translator skips the first 2 lines of the source
|
|
table, and tell the command to work as a splice, i.e., to not
|
|
produce header and footer commands of the target table:
|
|
|
|
#+begin_example
|
|
\begin{tabular}{lrrr}
|
|
Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
|
|
% BEGIN RECEIVE ORGTBL salesfigures
|
|
% END RECEIVE ORGTBL salesfigures
|
|
\end{tabular}
|
|
%
|
|
\begin{comment}
|
|
#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
|
|
| Month | Days | Nr sold | per day |
|
|
|-------+------+---------+---------|
|
|
| Jan | 23 | 55 | 2.4 |
|
|
| Feb | 21 | 16 | 0.8 |
|
|
| March | 22 | 278 | 12.6 |
|
|
#+TBLFM: $4=$3/$2;%.1f
|
|
\end{comment}
|
|
#+end_example
|
|
|
|
The LaTeX translator function ~orgtbl-to-latex~ is already part of
|
|
Orgtbl mode. It uses a ~tabular~ environment to typeset the table and
|
|
marks horizontal lines with ~\hline~. Furthermore, it interprets the
|
|
following parameters (see also see [[Translator functions]]):
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~:splice nil/t~ ::
|
|
|
|
When set to ~t~, return only table body lines, don't wrap them into a
|
|
tabular environment. Default is ~nil~.
|
|
|
|
- ~:fmt fmt~ ::
|
|
|
|
A format to be used to wrap each field, it should contain ~%s~ for the
|
|
original field value. For example, to wrap each field value in
|
|
dollars, you could use ~:fmt "$%s$"~. This may also be a property list
|
|
with column numbers and formats, for example ~:fmt (2 "$%s$" 4
|
|
"%s\\%%")~. A function of one argument can be used in place of the
|
|
strings; the function must return a formatted string.
|
|
|
|
- ~:efmt efmt~ ::
|
|
|
|
Use this format to print numbers with exponentials. The format should
|
|
have ~%s~ twice for inserting mantissa and exponent, for example:
|
|
|
|
#+begin_example
|
|
"%s\\times10^{%s}"
|
|
#+end_example
|
|
|
|
The default is:
|
|
|
|
#+begin_example
|
|
"%s\\,(%s)"
|
|
#+end_example
|
|
|
|
This may also be a property list with column numbers and formats, for
|
|
example:
|
|
|
|
#+begin_example
|
|
:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")
|
|
#+end_example
|
|
|
|
After ~efmt~ has been applied to a value, ~fmt~ will also be applied.
|
|
Similar to ~fmt~, functions of two arguments can be supplied instead
|
|
of strings.
|
|
|
|
*** Translator functions
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Copy and modify
|
|
:END:
|
|
#+cindex: HTML, and Orgtbl mode
|
|
#+cindex: translator function
|
|
|
|
Orgtbl mode has several translator functions built-in: ~orgtbl-to-csv~
|
|
(comma-separated values), ~orgtbl-to-tsv~ (TAB-separated values)
|
|
~orgtbl-to-latex~, ~orgtbl-to-html~, and ~orgtbl-to-texinfo~. Except
|
|
for ~orgtbl-to-html~, these all use a generic translator,
|
|
~orgtbl-to-generic~.[fn:162] For example, ~orgtbl-to-latex~ itself is
|
|
a very short function that computes the column definitions for the
|
|
~tabular~ environment, defines a few field and line separators and
|
|
then hands processing over to the generic translator. Here is the
|
|
entire code:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(defun orgtbl-to-latex (table params)
|
|
"Convert the Orgtbl mode TABLE to LaTeX."
|
|
(let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
|
|
org-table-last-alignment ""))
|
|
(params2
|
|
(list
|
|
:tstart (concat "\\begin@{tabular@}@{" alignment "@}")
|
|
:tend "\\end@{tabular@}"
|
|
:lstart "" :lend " \\\\" :sep " & "
|
|
:efmt "%s\\,(%s)" :hline "\\hline")))
|
|
(orgtbl-to-generic table (org-combine-plists params2 params))))
|
|
#+end_src
|
|
|
|
As you can see, the properties passed into the function (variable
|
|
~PARAMS~) are combined with the ones newly defined in the function
|
|
(variable ~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 ~\\[2mm]~ instead of the default ~\\~, you could just
|
|
overrule the default with:
|
|
|
|
#+begin_example
|
|
,#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
|
|
#+end_example
|
|
|
|
For a new language, you can either write your own converter function
|
|
in analogy with the LaTeX translator, or you can use the generic
|
|
function directly. For example, if you have a language where a table
|
|
is started with {{{samp(!BTBL!)}}}, ended with {{{samp(!ETBL!)}}}, and
|
|
where table lines are started with {{{samp(!BL!)}}}, ended with
|
|
{{{samp(!EL!)}}}, and where the field separator is a TAB, you could
|
|
call the generic translator like this (on a single line!):
|
|
|
|
#+begin_example
|
|
,#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
|
|
:lstart "!BL! " :lend " !EL!" :sep "\t"
|
|
#+end_example
|
|
|
|
{{{noindent}}} Please check the documentation string of the function
|
|
~orgtbl-to-generic~ for a full list of parameters understood by that
|
|
function, and remember that you can pass each of them into
|
|
~orgtbl-to-latex~, ~orgtbl-to-texinfo~, and any other function using
|
|
the generic function.
|
|
|
|
Of course you can also write a completely new function doing
|
|
complicated things the generic translator cannot do. A translator
|
|
function takes two arguments. The first argument is the table, a list
|
|
of lines, each line either the symbol ~hline~ or a list of fields. The
|
|
second argument is the property list containing all parameters
|
|
specified in the {{{samp(#+ORGTBL: SEND)}}} line. The function must
|
|
return a single string containing the formatted table. If you write a
|
|
generally useful translator, please post it to the [[mailto:emacs-orgmode@gnu.org][mailing list]] so
|
|
that others can benefit from your work.
|
|
|
|
*** Radio lists
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Doing the same for lists
|
|
:END:
|
|
#+cindex: radio lists
|
|
#+cindex: org-list-insert-radio-list
|
|
|
|
Sending and receiving radio lists works exactly the same way as
|
|
sending and receiving radio tables (see [[Radio tables]]). As for radio
|
|
tables, you can insert radio list templates in HTML, LaTeX and
|
|
Texinfo modes by calling ~org-list-insert-radio-list~.
|
|
|
|
Here are the differences with radio tables:
|
|
|
|
- Orgstruct mode must be active.
|
|
|
|
- Use the ~ORGLST~ keyword instead of ~ORGTBL~.
|
|
|
|
- The available translation functions for radio lists don't take
|
|
parameters.
|
|
|
|
- {{{kbd(C-c C-c)}}} will work when pressed on the first item of the
|
|
list.
|
|
|
|
|
|
Here is a LaTeX example. Let's say that you have this in your
|
|
LaTeX file:
|
|
|
|
#+cindex: #+ORGLST
|
|
#+begin_example
|
|
% BEGIN RECEIVE ORGLST to-buy
|
|
% END RECEIVE ORGLST to-buy
|
|
\begin{comment}
|
|
#+ORGLST: SEND to-buy org-list-to-latex
|
|
- a new house
|
|
- a new computer
|
|
+ a new keyboard
|
|
+ a new mouse
|
|
- a new life
|
|
\end{comment}
|
|
#+end_example
|
|
|
|
Pressing `C-c C-c' on ~a new house~ will insert the converted
|
|
LaTeX list between the two marker lines.
|
|
|
|
** Dynamic blocks
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Automatically filled blocks
|
|
:END:
|
|
#+cindex: dynamic blocks
|
|
|
|
Org documents can contain /dynamic blocks/. These are specially marked
|
|
regions that are updated by some user-written function. A good example
|
|
for such a block is the clock table inserted by the command
|
|
{{{kbd(C-c C-x C-r)}}} (see [[Clocking work time]]).
|
|
|
|
Dynamic blocks are enclosed by a BEGIN-END structure that assigns a
|
|
name to the block and can also specify parameters for the function
|
|
producing the content of the block.
|
|
|
|
#+cindex: #+BEGIN:dynamic block
|
|
#+begin_example
|
|
,#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
|
|
|
|
,#+END:
|
|
#+end_example
|
|
|
|
Dynamic blocks are updated with the following commands:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(C-c C-x C-u)}}}, ~org-dblock-update~ ::
|
|
#+kindex: C-c C-x C-u
|
|
|
|
Update dynamic block at point.
|
|
|
|
- {{{kbd(C-u C-c C-x C-u)}}} ::
|
|
#+kindex: C-u C-c C-x C-u
|
|
|
|
Update all dynamic blocks in the current file.
|
|
|
|
|
|
Updating a dynamic block means to remove all the text between ~BEGIN~
|
|
and ~END~, parse the ~BEGIN~ line for parameters and then call the
|
|
specific writer function for this block to insert the new content. If
|
|
you want to use the original content in the writer function, you can
|
|
use the extra parameter ~:content~.
|
|
|
|
For a block with name ~myblock~, the writer function is
|
|
~org-dblock-write:myblock~ with as only parameter a property list
|
|
with the parameters given in the begin line. Here is a trivial example
|
|
of a block that keeps track of when the block update function was last
|
|
run:
|
|
|
|
#+begin_example
|
|
,#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
|
|
|
|
,#+END:
|
|
#+end_example
|
|
|
|
{{{noindent}}} The corresponding block writer function could look like
|
|
this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-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)))))
|
|
#+end_src
|
|
|
|
If you want to make sure that all dynamic blocks are always
|
|
up-to-date, you could add the function ~org-update-all-dblocks~ to a
|
|
hook, for example ~before-save-hook~. ~org-update-all-dblocks~ is
|
|
written in a way such that it does nothing in buffers that are not in
|
|
~org-mode~.
|
|
|
|
You can narrow the current buffer to the current dynamic block (like
|
|
any other block) with ~org-narrow-to-block~.
|
|
|
|
** Special agenda views
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Customized views
|
|
:END:
|
|
#+cindex: agenda views, user-defined
|
|
#+vindex: org-agenda-skip-function
|
|
#+vindex: org-agenda-skip-function-global
|
|
|
|
Org provides a special hook that can be used to narrow down the
|
|
selection made by these agenda views: ~agenda~, ~todo~, ~alltodo~,
|
|
~tags~, ~tags-todo~, ~tags-tree~. You may specify a function that is
|
|
used at each match to verify if the match should indeed be part of the
|
|
agenda view, and if not, how much should be skipped. You can specify a
|
|
global condition that will be applied to all agenda views, this
|
|
condition would be stored in the variable
|
|
~org-agenda-skip-function-global~. More commonly, such a definition is
|
|
applied only to specific custom searches, using
|
|
~org-agenda-skip-function~.
|
|
|
|
Let's say you want to produce a list of projects that contain a
|
|
~WAITING~ tag anywhere in the project tree. Let's further assume that
|
|
you have marked all tree headings that define a project with the TODO
|
|
keyword PROJECT. In this case you would run a TODO search for the
|
|
keyword PROJECT, but skip the match unless there is a ~WAITING~ tag
|
|
anywhere in the subtree belonging to the project line.
|
|
|
|
To achieve this, you must write a function that searches the subtree for
|
|
the tag. If the tag is found, the function must return ~nil~ to
|
|
indicate that this match should not be skipped. If there is no such
|
|
tag, return the location of the end of the subtree, to indicate that
|
|
search should continue from there.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(defun my-skip-unless-waiting ()
|
|
"Skip trees that are not waiting"
|
|
(let ((subtree-end (save-excursion (org-end-of-subtree t))))
|
|
(if (re-search-forward ":waiting:" subtree-end t)
|
|
nil ; tag found, do not skip
|
|
subtree-end))) ; tag not found, continue after end of subtree
|
|
#+end_src
|
|
|
|
Now you may use this function in an agenda custom command, for example
|
|
like this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(org-add-agenda-custom-command
|
|
'("b" todo "PROJECT"
|
|
((org-agenda-skip-function 'my-skip-unless-waiting)
|
|
(org-agenda-overriding-header "Projects waiting for something: "))))
|
|
#+end_src
|
|
|
|
#+vindex: org-agenda-overriding-header
|
|
|
|
Note that this also binds ~org-agenda-overriding-header~ to get a
|
|
meaningful header in the agenda view.
|
|
|
|
#+vindex: org-odd-levels-only
|
|
#+vindex: org-agenda-skip-function
|
|
|
|
A general way to create custom searches is to base them on a search
|
|
for entries with a certain level limit. If you want to study all
|
|
entries with your custom search function, simply do a search for
|
|
{{{samp(LEVEL>0)}}}, and then use ~org-agenda-skip-function~ to select
|
|
the entries you really want to have.[fn:163]
|
|
|
|
You may also put a Lisp form into ~org-agenda-skip-function~. In
|
|
particular, you may use the functions ~org-agenda-skip-entry-if~
|
|
and ~org-agenda-skip-subtree-if~ in this form, for example:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{samp((org-agenda-skip-entry-if 'scheduled))}}} ::
|
|
|
|
Skip current entry if it has been scheduled.
|
|
|
|
- {{{samp((org-agenda-skip-entry-if 'notscheduled))}}} ::
|
|
|
|
Skip current entry if it has not been scheduled.
|
|
|
|
- {{{samp((org-agenda-skip-entry-if 'deadline))}}} ::
|
|
|
|
Skip current entry if it has a deadline.
|
|
|
|
- {{{samp((org-agenda-skip-entry-if 'scheduled 'deadline))}}} ::
|
|
|
|
Skip current entry if it has a deadline, or if it is scheduled.
|
|
|
|
- {{{samp((org-agenda-skip-entry-if 'todo '("TODO" "WAITING")))}}} ::
|
|
|
|
Skip current entry if the TODO keyword is TODO or WAITING.
|
|
|
|
- {{{samp((org-agenda-skip-entry-if 'todo 'done))}}} ::
|
|
|
|
Skip current entry if the TODO keyword marks a DONE state.
|
|
|
|
- {{{samp((org-agenda-skip-entry-if 'timestamp))}}} ::
|
|
|
|
Skip current entry if it has any timestamp, may also be deadline or scheduled.
|
|
<<x-agenda-skip-entry-regexp>>
|
|
|
|
- {{{samp((org-agenda-skip-entry-if 'regexp "regular expression"))}}} ::
|
|
|
|
Skip current entry if the regular expression matches in the entry.
|
|
|
|
- {{{samp((org-agenda-skip-entry-if 'notregexp "regular expression"))}}} ::
|
|
|
|
Skip current entry unless the regular expression matches.
|
|
|
|
- {{{samp((org-agenda-skip-subtree-if 'regexp "regular expression"))}}} ::
|
|
|
|
Same as above, but check and skip the entire subtree.
|
|
|
|
|
|
Therefore we could also have written the search for WAITING projects
|
|
like this, even without defining a special function:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(org-add-agenda-custom-command
|
|
'("b" todo "PROJECT"
|
|
((org-agenda-skip-function '(org-agenda-skip-subtree-if
|
|
'regexp ":waiting:"))
|
|
(org-agenda-overriding-header "Projects waiting for something: "))))
|
|
#+end_src
|
|
|
|
** Extracting agenda information
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Post-processing agenda information
|
|
:END:
|
|
#+cindex: agenda, pipe
|
|
#+cindex: Scripts, for agenda processing
|
|
#+vindex: org-agenda-custom-commands
|
|
|
|
Org provides commands to access agenda information for the command
|
|
line in Emacs batch mode. This extracted information can be sent
|
|
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 ~org-batch-agenda~, that produces an agenda view and sends it
|
|
as 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 ~org-agenda-custom-commands~,
|
|
basically any key you can use after {{{kbd(C-c a)}}}. For example, to
|
|
directly print the current TODO list, you could use:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src sh
|
|
emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
|
|
#+end_src
|
|
|
|
If the parameter is a string with 2 or more characters, it is used as
|
|
a tags/TODO match string. For example, to print your local shopping
|
|
list (all items with the tag {{{samp(shop)}}}, but excluding the tag
|
|
{{{samp(NewYork)}}}), you could use:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src sh
|
|
emacs -batch -l ~/.emacs \
|
|
-eval '(org-batch-agenda "+shop-NewYork")' | lpr
|
|
#+end_src
|
|
|
|
{{{noindent}}} You may also modify parameters on the fly like this:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src sh
|
|
emacs -batch -l ~/.emacs \
|
|
-eval '(org-batch-agenda "a" \
|
|
org-agenda-span (quote month) \
|
|
org-agenda-include-diary nil \
|
|
org-agenda-files (quote ("~/org/project.org")))' \
|
|
| lpr
|
|
#+end_src
|
|
|
|
{{{noindent}}} which will produce a 30-day agenda, fully restricted to
|
|
the Org file {{{file(~/org/projects.org)}}}, not even including the
|
|
diary.
|
|
|
|
If you want to process the agenda data in more sophisticated ways, you
|
|
can use the command ~org-batch-agenda-csv~ to get a comma-separated
|
|
list of values for each agenda item. Each line in the output will
|
|
contain a number of fields separated by commas. The fields in a line
|
|
are:
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- category :: The category of the item
|
|
- head :: The headline, without TODO keyword, TAGS and PRIORITY
|
|
- type :: The type of the agenda entry, can be:
|
|
- todo :: selected in TODO match
|
|
- tagsmatch :: selected in tags match
|
|
- diary :: imported from diary
|
|
- deadline :: a deadline
|
|
- scheduled :: scheduled
|
|
- timestamp :: appointment, selected by timestamp
|
|
- closed :: entry was closed on date
|
|
- upcoming-deadline :: warning about nearing deadline
|
|
- past-scheduled :: forwarded scheduled item
|
|
- block :: entry has date block including date
|
|
- todo :: The TODO keyword, if any
|
|
- tags :: All tags including inherited ones, separated by colons
|
|
- date :: The relevant date, like 2007-2-14
|
|
- time :: The time, like 15:00-16:50
|
|
- extra :: String with extra planning info
|
|
- priority-l :: The priority letter if any was given
|
|
- priority-n :: The computed numerical priority
|
|
|
|
{{{noindent}}} Time and date will only be given if a timestamp (or
|
|
deadline/scheduled) led to the selection of the item.
|
|
|
|
A CSV list like this is very easy to use in a post-processing script.
|
|
For example, here is a Perl program that gets the TODO list from
|
|
Emacs/Org and prints all the items, preceded by a checkbox:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src perl
|
|
#!/usr/bin/perl
|
|
|
|
# define the Emacs command to run
|
|
$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
|
|
|
|
# run it and capture the output
|
|
$agenda = qx@{$cmd 2>/dev/null@};
|
|
|
|
# loop over all lines
|
|
foreach $line (split(/\n/,$agenda)) @{
|
|
# get the individual values
|
|
($category,$head,$type,$todo,$tags,$date,$time,$extra,
|
|
$priority_l,$priority_n) = split(/,/,$line);
|
|
# process and print
|
|
print "[ ] $head\n";
|
|
@}
|
|
#+end_src
|
|
|
|
** Using the property API
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Writing programs that use entry properties
|
|
:END:
|
|
#+cindex: API, for properties
|
|
#+cindex: properties, API
|
|
|
|
Here is a description of the functions that can be used to work with
|
|
properties.
|
|
|
|
#+attr_texinfo: :options org-entry-properties &optional pom which
|
|
#+begin_defun
|
|
Get all properties of the entry at point-or-marker POM.
|
|
This includes the TODO keyword, the tags, time strings for deadline,
|
|
scheduled, and clocking, and any additional properties defined in the
|
|
entry. The return value is an alist. Keys may occur multiple times
|
|
if the property key was used several times.@*
|
|
POM may also be nil, in which case the current entry is used.
|
|
If WHICH is nil or `all', get all properties. If WHICH is
|
|
`special' or `standard', only get that subclass.
|
|
#+end_defun
|
|
|
|
#+vindex: org-use-property-inheritance
|
|
#+findex: org-insert-property-drawer
|
|
#+attr_texinfo: :options org-entry-get pom property &optional inherit
|
|
#+begin_defun
|
|
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
|
|
~selective~, use inheritance if and only if the setting of
|
|
~org-use-property-inheritance~ selects PROPERTY for inheritance.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-entry-delete pom property
|
|
#+begin_defun
|
|
Delete the property PROPERTY from entry at point-or-marker POM.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-entry-put pom property value
|
|
#+begin_defun
|
|
Set PROPERTY to VALUE for entry at point-or-marker POM.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-buffer-property-keys &optional include-specials
|
|
#+begin_defun
|
|
Get all property keys in the current buffer.
|
|
#+end_defun
|
|
#+attr_texinfo: :options org-insert-property-drawer
|
|
#+begin_defun
|
|
Insert a property drawer for the current entry. Also
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-entry-put-multivalued-property pom property &rest values
|
|
#+begin_defun
|
|
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
|
|
|
|
#+attr_texinfo: :options org-entry-get-multivalued-property pom property
|
|
#+begin_defun
|
|
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
|
|
|
|
#+attr_texinfo: :options org-entry-add-to-multivalued-property pom property value
|
|
#+begin_defun
|
|
Treat the value of the property PROPERTY as a whitespace-separated list of
|
|
values and make sure that VALUE is in this list.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-entry-remove-from-multivalued-property pom property value
|
|
#+begin_defun
|
|
Treat the value of the property PROPERTY as a whitespace-separated list of
|
|
values and make sure that VALUE is /not/ in this list.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-entry-member-in-multivalued-property pom property value
|
|
#+begin_defun
|
|
Treat the value of the property PROPERTY as a whitespace-separated list of
|
|
values and check if VALUE is in this list.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-property-allowed-value-functions
|
|
#+begin_defopt
|
|
Hook for functions supplying allowed values for a specific property.
|
|
The functions must take a single argument, the name of the property, and
|
|
return a flat list of allowed values. If {{{samp(:ETC)}}} is one of
|
|
the values, use the values as completion help, but allow also other values
|
|
to be entered. The functions must return ~nil~ if they are not
|
|
responsible for this property.
|
|
#+end_defopt
|
|
|
|
** Using the mapping API
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Mapping over all or selected entries
|
|
:END:
|
|
#+cindex: API, for mapping
|
|
#+cindex: mapping entries, API
|
|
|
|
Org has sophisticated mapping capabilities to find all entries satisfying
|
|
certain criteria. Internally, this functionality is used to produce agenda
|
|
views, but there is also an API that can be used to execute arbitrary
|
|
functions for each or selected entries. The main entry point for this API
|
|
is:
|
|
|
|
#+attr_texinfo: :options org-map-entries func &optional match scope &rest skip
|
|
#+begin_defun
|
|
Call FUNC at each headline selected by MATCH in SCOPE.
|
|
|
|
FUNC is a function or a Lisp form. The function will be called without
|
|
arguments, with the cursor positioned at the beginning of the headline.
|
|
The return values of all calls to the function will be collected and
|
|
returned as a list.
|
|
|
|
The call to FUNC will be wrapped into a save-excursion form, so FUNC
|
|
does not need to preserve point. After evaluation, the cursor will be
|
|
moved to the end of the line (presumably of the headline of the
|
|
processed entry) and search continues from there. Under some
|
|
circumstances, this may not produce the wanted results. For example,
|
|
if you have removed (e.g., archived) the current (sub)tree it could
|
|
mean that the next entry will be skipped entirely. In such cases, you
|
|
can specify the position from where search should continue by making
|
|
FUNC set the variable `org-map-continue-from' to the desired buffer
|
|
position.
|
|
|
|
MATCH is a tags/property/todo match as it is used in the agenda match view.
|
|
Only headlines that are matched by this query will be considered during
|
|
the iteration. When MATCH is nil or t, all headlines will be
|
|
visited by the iteration.
|
|
|
|
SCOPE determines the scope of this command. It can be any of:
|
|
|
|
#+attr_texinfo: :table-type table :indic @code
|
|
- nil ::
|
|
|
|
The current buffer, respecting the restriction, if any.
|
|
|
|
- tree ::
|
|
|
|
The subtree started with the entry at point.
|
|
|
|
- region ::
|
|
|
|
The entries within the active region, if any.
|
|
|
|
- file ::
|
|
|
|
The current buffer, without restriction.
|
|
|
|
- file-with-archives ::
|
|
|
|
The current buffer, and any archives associated with it.
|
|
|
|
- agenda ::
|
|
|
|
All agenda files.
|
|
|
|
- agenda-with-archives ::
|
|
|
|
All agenda files with any archive files associated with them.
|
|
|
|
- (file1 file2 ...) ::
|
|
|
|
If this is a list, all files in the list will be scanned.
|
|
|
|
|
|
{{{noindent}}} The remaining args are treated as settings for the
|
|
skipping facilities of the scanner. The following items can be given
|
|
here:
|
|
|
|
#+vindex: org-agenda-skip-function
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- ~archive~ ::
|
|
|
|
Skip trees with the archive tag.
|
|
|
|
- ~comment~ ::
|
|
|
|
Skip trees with the COMMENT keyword.
|
|
|
|
- function or Lisp form ::
|
|
|
|
Will be used as value for ~org-agenda-skip-function~, so whenever the
|
|
function returns t, FUNC will not be called for that entry and search
|
|
will continue from the point where the function leaves it.
|
|
#+end_defun
|
|
|
|
The function given to that mapping routine can really do anything you like.
|
|
It can use the property API (see [[Using the property API]]) to gather more
|
|
information about the entry, or in order to change metadata in the entry.
|
|
Here are a few functions that might be handy:
|
|
|
|
#+attr_texinfo: :options org-todo &optional arg
|
|
#+begin_defun
|
|
Change the TODO state of the entry. See the docstring of the functions for
|
|
the many possible values for the argument ARG.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-priority &optional action
|
|
#+begin_defun
|
|
Change the priority of the entry. See the docstring of this function for the
|
|
possible values for ACTION.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-toggle-tag tag &optional onoff
|
|
#+begin_defun
|
|
Toggle the tag TAG in the current entry. Setting ONOFF to either ~on~
|
|
or ~off~ will not toggle tag, but ensure that it is either on or off.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-promote
|
|
#+begin_defun
|
|
Promote the current entry.
|
|
#+end_defun
|
|
|
|
#+attr_texinfo: :options org-demote
|
|
#+begin_defun
|
|
Demote the current entry.
|
|
#+end_defun
|
|
|
|
The following simple example will turn all entries in the current file
|
|
with a tag ~TOMORROW~ into TODO entries with the keyword ~UPCOMING~.
|
|
Entries in comment trees and in archive trees will be ignored.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(org-map-entries
|
|
'(org-todo "UPCOMING")
|
|
"+TOMORROW" 'file 'archive 'comment)
|
|
#+end_src
|
|
|
|
The following example counts the number of entries with TODO keyword
|
|
~WAITING~, in all agenda files.
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(length (org-map-entries t "/+WAITING" 'agenda))
|
|
#+end_src
|
|
|
|
* MobileOrg
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Viewing and capture on a mobile device
|
|
:APPENDIX: Appendix
|
|
:END:
|
|
#+cindex: iPhone
|
|
#+cindex: MobileOrg
|
|
#+cindex: Moreland, Richard
|
|
#+cindex: Jones, Matt
|
|
|
|
MobileOrg is the name of the mobile companion app for Org mode,
|
|
currently available for iOS and for Android. MobileOrg offers
|
|
offline viewing and capture support for an Org mode system rooted on a
|
|
``real'' computer. It does also allow you to record changes to
|
|
existing entries. The [[http://mobileorg.ncogni.to/][iOS implementation]] for the iPhone/iPod
|
|
Touch/iPad series of devices, was developed by Richard Moreland.
|
|
Android users should check out [[http://wiki.github.com/matburt/mobileorg-android/][MobileOrg Android]] by Matt Jones. The
|
|
two implementations are not identical but offer similar features.
|
|
|
|
This appendix describes the support Org has for creating agenda views
|
|
in a format that can be displayed by MobileOrg, and for integrating
|
|
notes captured and changes made by MobileOrg into the main system.
|
|
|
|
For changing tags and TODO states in MobileOrg, you should have set up
|
|
the customization variables ~org-todo-keywords~ and ~org-tags-alist~
|
|
to cover all important tags and TODO keywords, even if individual
|
|
files use only part of these. MobileOrg will also offer you states and
|
|
tags set up with in-buffer settings, but it will understand the
|
|
logistics of TODO state /sets/ (see [[Per-file keywords]]) and /mutually
|
|
exclusive/ tags (see [[Setting tags]]) only for those set in these
|
|
variables.
|
|
|
|
** Setting up the staging area
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Where to interact with the mobile device
|
|
:END:
|
|
|
|
MobileOrg needs to interact with Emacs through a directory on a
|
|
server. If you are using a public server, you should consider to
|
|
encrypt the files that are uploaded to the server. This can be done
|
|
with Org mode 7.02 and with MobileOrg 1.5 (iPhone version), and you
|
|
need an {{{file(openssl)}}} installation on your system. To turn on
|
|
encryption, set a password in MobileOrg and, on the Emacs side,
|
|
configure the variable ~org-mobile-use-encryption~.[fn:164]
|
|
|
|
The easiest way to create that directory is to use a free [[http://dropbox.com][Dropbox]]
|
|
account.[fn:165] When MobileOrg first connects to your Dropbox, it
|
|
will create a directory MobileOrg inside the Dropbox. After the
|
|
directory has been created, tell Emacs about it:
|
|
|
|
#+header: :eval no
|
|
#+header: :exports code
|
|
#+begin_src emacs-lisp
|
|
(setq org-mobile-directory "~/Dropbox/MobileOrg")
|
|
#+end_src
|
|
|
|
Org mode has commands to put files for MobileOrg into that
|
|
directory, and to read captured notes from there.
|
|
|
|
** Pushing to MobileOrg
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Uploading Org files and agendas
|
|
:END:
|
|
|
|
This operation copies all files currently listed in ~org-mobile-files~
|
|
to the directory ~org-mobile-directory~. By default this list contains
|
|
all agenda files (as listed in ~org-agenda-files~), but additional
|
|
files can be included by customizing ~org-mobile-files~. File names
|
|
will be staged with paths relative to ~org-directory~, so all files
|
|
should be inside this directory.[fn:184]
|
|
|
|
The push operation also creates a special Org file
|
|
{{{file(agendas.org)}}} with all custom agenda view defined by the
|
|
user.[fn:166]
|
|
|
|
Finally, Org writes the file {{{file(index.org)}}}, containing links
|
|
to all other files. MobileOrg first reads this file from the server,
|
|
and then downloads all agendas and Org files listed in it. To speed up
|
|
the download, MobileOrg will only read files whose checksums have
|
|
changed.[fn:167]
|
|
|
|
** Pulling from MobileOrg
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Integrating captured and flagged items
|
|
:END:
|
|
|
|
When MobileOrg synchronizes with the server, it not only pulls the
|
|
Org files for viewing. It also appends captured entries and pointers
|
|
to flagged and changed entries to the file {{{file(mobileorg.org)}}}
|
|
on the server. Org has a /pull/ operation that integrates this
|
|
information into an inbox file and operates on the pointers to flagged
|
|
entries. Here is how it works:
|
|
|
|
1. Org moves all entries found in {{{file(mobileorg.org)}}} and
|
|
appends them to the file pointed to by the variable ~org-mobile-inbox-for-pull~.[fn:168] Each captured entry and each
|
|
editing event will be a top-level entry in the inbox file.
|
|
|
|
2. After moving the entries, Org will attempt to implement the changes
|
|
made in MobileOrg. Some changes are applied directly and without
|
|
user interaction. Examples are all changes to tags, TODO state,
|
|
headline and body text that can be cleanly applied. Entries that
|
|
have been flagged for further action will receive a tag ~:FLAGGED:~, so that they can be easily found again. When there is
|
|
a problem finding an entry or applying the change, the pointer
|
|
entry will remain in the inbox and will be marked with an error
|
|
message. You need to later resolve these issues by hand.
|
|
|
|
3. Org will then generate an agenda view with all flagged entries. The
|
|
user should then go through these entries and do whatever actions
|
|
are necessary. If a note has been stored while flagging an entry in
|
|
MobileOrg, that note will be displayed in the echo area when the
|
|
cursor is on the corresponding agenda line.
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- {{{kbd(?)}}} ::
|
|
#+kindex: ?
|
|
|
|
Pressing {{{kbd(?)}}} in that special agenda will display the full
|
|
flagging note in another window and also push it onto the kill ring.
|
|
So you could use {{{kbd(? z C-y C-c C-c)}}} to store that flagging
|
|
note as a normal note in the entry. Pressing {{{kbd(?)}}} twice in
|
|
succession will offer to remove the ~:FLAGGED:~ tag along with the
|
|
recorded flagging note (which is stored in a property). In this way
|
|
you indicate that the intended processing for this flagged entry is
|
|
finished.
|
|
|
|
|
|
#+kindex: C-c a ?
|
|
|
|
If you are not able to process all flagged entries directly, you can always
|
|
return to this agenda view using {{{kbd(C-c a ?)}}}.[fn:169]
|
|
|
|
* History and acknowledgments
|
|
:PROPERTIES:
|
|
:DESCRIPTION: How Org came into being
|
|
:ALT_TITLE: History and Acknowledgments
|
|
:APPENDIX: Appendix
|
|
:END:
|
|
** From Carsten
|
|
|
|
Org was born in 2003, out of frustration over the user interface of
|
|
the Emacs Outline mode. I was trying to organize my notes and
|
|
projects, and using Emacs seemed to be the natural way to go. However,
|
|
having to remember eleven different commands with two or three keys
|
|
per command, only to hide and show parts of the outline tree, that
|
|
seemed entirely unacceptable to me. Also, when using outlines to take
|
|
notes, I constantly wanted to restructure the tree, organizing it
|
|
parallel to my thoughts and plans. /Visibility cycling/ and /structure
|
|
editing/ were originally implemented in the package
|
|
{{{file(outline-magic.el)}}}, but quickly moved to the more general
|
|
{{{file(org.el)}}}. As this environment became comfortable for project
|
|
planning, the next step was adding /TODO entries/, basic /timestamps/,
|
|
and /table support/. These areas highlighted the two main goals that
|
|
Org still has today: to be a new, outline-based, plain text mode with
|
|
innovative and intuitive editing features, and to incorporate project
|
|
planning functionality directly into a notes file.
|
|
|
|
Since the first release, literally thousands of emails to me or to the
|
|
[[mailto:emacs-orgmode@gnu.org][mailing list]] have provided a constant stream of bug reports, feedback,
|
|
new ideas, and sometimes patches and add-on code. Many thanks to
|
|
everyone who has helped to improve this package. I am trying to keep
|
|
here a list of the people who had significant influence in shaping one
|
|
or more aspects of Org. The list may not be complete, if I have
|
|
forgotten someone, please accept my apologies and let me know.
|
|
|
|
Before I get to this list, a few special mentions are in order:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Bastien Guerry ::
|
|
|
|
Bastien has written a large number of extensions to Org (most of them
|
|
integrated into the core by now), including the LaTeX exporter and
|
|
the plain list parser. His support during the early days, when he
|
|
basically acted as co-maintainer, was central to the success of this
|
|
project. Bastien also invented Worg, helped establishing the Web
|
|
presence of Org, and sponsored hosting costs for the ~orgmode.org~
|
|
website.
|
|
|
|
- Eric Schulte and Dan Davison ::
|
|
|
|
Eric and Dan are jointly responsible for the Org-babel system, which
|
|
turns Org into a multi-language environment for evaluating code and
|
|
doing literate programming and reproducible research.
|
|
|
|
- John Wiegley ::
|
|
|
|
John has contributed a number of great ideas and patches directly to
|
|
Org, including the attachment system ({{{file(org-attach.el)}}}),
|
|
integration with Apple Mail ({{{file(org-mac-message.el)}}}),
|
|
hierarchical dependencies of TODO items, habit tracking
|
|
({{{file(org-habits.el)}}}), and encryption
|
|
({{{file(org-crypt.el)}}}). Also, the capture system is really an
|
|
extended copy of his great {{{file(remember.el)}}}.
|
|
|
|
- Sebastian Rose ::
|
|
|
|
Without Sebastian, the HTML/XHTML publishing of Org would be the
|
|
pitiful work of an ignorant amateur. Sebastian has pushed this part of
|
|
Org onto a much higher level. He also wrote {{{file(org-info.js)}}}, a
|
|
Java script for displaying webpages derived from Org using an
|
|
Info-like or a folding interface with single-key navigation.
|
|
|
|
|
|
{{{noindent}}} See [[List of contributions][below]] for the full list of contributions! Again,
|
|
please let me know what I am missing here!
|
|
|
|
** From Bastien
|
|
|
|
I (Bastien) have been maintaining Org since January 2011. This
|
|
appendix would not be complete without adding a few more
|
|
acknowledgements and thanks to Carsten's ones above.
|
|
|
|
I am first grateful to Carsten for his trust while handing me over the
|
|
maintainership of Org. His support as been great since day one of this
|
|
new adventure, and it helped a lot.
|
|
|
|
When I took over maintainership, I knew I would have to make Org more
|
|
collaborative than ever, as I would have to rely on people that are
|
|
more knowledgeable than I am on many parts of the code. Here is a list
|
|
of the persons I could rely on, they should really be considered
|
|
co-maintainers, either of the code or the community:
|
|
|
|
#+attr_texinfo: :table-type table :indic @asis
|
|
- Eric Schulte ::
|
|
|
|
Eric is maintaining the Babel parts of Org. His reactivity here kept
|
|
me away from worrying about possible bugs here and let me focus on
|
|
other parts.
|
|
|
|
- Nicolas Goaziou ::
|
|
|
|
Nicolas is maintaining the consistency of the deepest parts of Org.
|
|
His work on {{{file(org-element.el)}}} and {{{file(org-export.el)}}}
|
|
has been outstanding, and opened the doors for many new ideas and
|
|
features.
|
|
|
|
- Jambunathan K ::
|
|
|
|
Jambunathan contributed the ODT exporter, definitly 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.
|
|
|
|
- Achim Gratz ::
|
|
|
|
Achim rewrote the building process of Org, turning some /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.
|
|
|
|
- Nick Dokos ::
|
|
|
|
The Org mode mailing list would not be such a nice place without Nick,
|
|
who patiently helped users so many times. It is impossible to
|
|
overestimate such a great help, and the list would not be so active
|
|
without him.
|
|
|
|
|
|
I received support from so many users that it is clearly impossible to be
|
|
fair when shortlisting a few of them---but Org's history would not be
|
|
complete if the ones above were not mentioned in this manual.
|
|
|
|
** List of contributions
|
|
|
|
- Russel Adams came up with the idea for drawers.
|
|
|
|
- Thomas Baumann wrote {{{file(org-bbdb.el)}}} and {{{file(org-mhe.el)}}}.
|
|
|
|
- Christophe Bataillon created the great unicorn logo that we use on
|
|
the Org mode website.
|
|
|
|
- Alex Bochannek provided a patch for rounding timestamps.
|
|
|
|
- Jan Böcker wrote {{{file(org-docview.el)}}}.
|
|
|
|
- Brad Bozarth showed how to pull RSS feed data into Org mode files.
|
|
|
|
- Tom Breton wrote {{{file(org-choose.el)}}}.
|
|
|
|
- Charles Cave's suggestion sparked the implementation of templates
|
|
for Remember, which are now templates for capture.
|
|
|
|
- Pavel Chalmoviansky influenced the agenda treatment of items with
|
|
specified time.
|
|
|
|
- Gregory Chernov patched support for Lisp forms into table
|
|
calculations and improved XEmacs compatibility, in particular by
|
|
porting {{{file(nouline.el)}}} to XEmacs.
|
|
|
|
- Sacha Chua suggested copying some linking code from Planner.
|
|
|
|
- Baoqiu Cui contributed the DocBook exporter.
|
|
|
|
- Eddward DeVilla proposed and tested checkbox statistics. He also
|
|
came up with the idea of properties, and that there should be an API
|
|
for them.
|
|
|
|
- Nick Dokos tracked down several nasty bugs.
|
|
|
|
- Kees Dullemond used to edit projects lists directly in HTML and so
|
|
inspired some of the early development, including HTML export. He
|
|
also asked for a way to narrow wide table columns.
|
|
|
|
- Thomas S. Dye contributed documentation on Worg and helped
|
|
integrating the Org-Babel documentation into the manual.
|
|
|
|
- Christian Egli converted the documentation into Texinfo format,
|
|
inspired the agenda, patched CSS formatting into the HTML exporter,
|
|
and wrote {{{file(org-taskjuggler.el)}}}.
|
|
|
|
- David Emery provided a patch for custom CSS support in exported
|
|
HTML agendas.
|
|
|
|
- Nic Ferrier contributed mailcap and XOXO support.
|
|
|
|
- Miguel A. Figueroa-Villanueva implemented hierarchical checkboxes.
|
|
|
|
- John Foerch figured out how to make incremental search show
|
|
context around a match in a hidden outline tree.
|
|
|
|
- Raimar Finken wrote {{{file(org-git-line.el)}}}.
|
|
|
|
- Mikael Fornius works as a mailing list moderator.
|
|
|
|
- Austin Frank works as a mailing list moderator.
|
|
|
|
- Eric Fraga drove the development of BEAMER export with ideas and
|
|
testing.
|
|
|
|
- Barry Gidden did proofreading the manual in preparation for the
|
|
book publication through Network Theory Ltd.
|
|
|
|
- Niels Giesen had the idea to automatically archive DONE trees.
|
|
|
|
- Nicolas Goaziou rewrote much of the plain list code.
|
|
|
|
- Kai Grossjohann pointed out key-binding conflicts with other packages.
|
|
|
|
- Brian Gough of Network Theory Ltd publishes the Org mode manual as
|
|
a book.
|
|
|
|
- Bernt Hansen has driven much of the support for auto-repeating
|
|
tasks, task state change logging, and the clocktable. His clear
|
|
explanations have been critical when we started to adopt the Git
|
|
version control system.
|
|
|
|
- Manuel Hermenegildo has contributed various ideas, small fixes
|
|
and patches.
|
|
|
|
- Phil Jackson wrote {{{file(org-irc.el)}}}.
|
|
|
|
- Scott Jaderholm proposed footnotes, control over whitespace
|
|
between folded entries, and column view for properties.
|
|
|
|
- Matt Jones wrote /MobileOrg Android/.
|
|
|
|
- Tokuya Kameshima wrote {{{file(org-wl.el)}}} and {{{file(org-mew.el)}}}.
|
|
|
|
- Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He
|
|
also provided frequent feedback and some patches.
|
|
|
|
- Matt Lundin has proposed last-row references for table formulas
|
|
and named invisible anchors. He has also worked a lot on the FAQ.
|
|
|
|
- David Maus wrote {{{file(org-atom.el)}}}, maintains the issues
|
|
file for Org, and is a prolific contributor on the mailing list with
|
|
competent replies, small fixes and patches.
|
|
|
|
- Jason F. McBrayer suggested agenda export to CSV format.
|
|
|
|
- Max Mikhanosha came up with the idea of refiling.
|
|
|
|
- Dmitri Minaev sent a patch to set priority limits on a per-file
|
|
basis.
|
|
|
|
- Stefan Monnier provided a patch to keep the Emacs-Lisp compiler
|
|
happy.
|
|
|
|
- Richard Moreland wrote /MobileOrg/ for the iPhone.
|
|
|
|
- Rick Moynihan proposed allowing multiple TODO sequences in a file
|
|
and being able to quickly restrict the agenda to a subtree.
|
|
|
|
- Todd Neal provided patches for links to Info files and Elisp forms.
|
|
|
|
- Greg Newman refreshed the unicorn logo into its current form.
|
|
|
|
- Tim O'Callaghan suggested in-file links, search options for
|
|
general file links, and TAGS.
|
|
|
|
- Osamu Okano wrote {{{file(orgcard2ref.pl)}}}, a Perl program to
|
|
create a text version of the reference card.
|
|
|
|
- Takeshi Okano translated the manual and David O'Toole's tutorial
|
|
into Japanese.
|
|
|
|
- Oliver Oppitz suggested multi-state TODO items.
|
|
|
|
- Scott Otterson sparked the introduction of descriptive text for
|
|
links, among other things.
|
|
|
|
- Pete Phillips helped during the development of the TAGS feature,
|
|
and provided frequent feedback.
|
|
|
|
- Martin Pohlack provided the code snippet to bundle character
|
|
insertion into bundles of 20 for undo.
|
|
|
|
- T.V. Raman reported bugs and suggested improvements.
|
|
|
|
- Matthias Rempe (Oelde) provided ideas, Windows support, and
|
|
quality control.
|
|
|
|
- Paul Rivier provided the basic implementation of named footnotes.
|
|
He also acted as mailing list moderator for some time.
|
|
|
|
- Kevin Rogers contributed code to access VM files on remote hosts.
|
|
|
|
- Frank Ruell solved the mystery of the ~keymapp nil~ bug, a
|
|
conflict with {{{file(allout.el)}}}.
|
|
|
|
- Jason Riedy generalized the send-receive mechanism for Orgtbl
|
|
tables with extensive patches.
|
|
|
|
- Philip Rooke created the Org reference card, provided lots of
|
|
feedback, developed and applied standards to the Org documentation.
|
|
|
|
- Christian Schlauer proposed angular brackets around links, among
|
|
other things.
|
|
|
|
- Paul Sexton wrote {{{file(org-ctags.el)}}}.
|
|
|
|
- Tom Shannon's {{{file(organizer-mode.el)}}} inspired linking to VM/BBDB/Gnus.
|
|
|
|
- Ilya Shlyakhter proposed the Archive Sibling, line numbering in
|
|
literal examples, and remote highlighting for referenced code lines.
|
|
|
|
- Stathis Sideris wrote the {{{file(ditaa.jar)}}} ASCII to PNG
|
|
converter that is now packaged into Org's {{{file(contrib)}}}
|
|
directory.
|
|
|
|
- Daniel Sinder came up with the idea of internal archiving by
|
|
locking subtrees.
|
|
|
|
- Dale Smith proposed link abbreviations.
|
|
|
|
- James TD Smith has contributed a large number of patches for
|
|
useful tweaks and features.
|
|
|
|
- Adam Spiers asked for global linking commands, inspired the link
|
|
extension system, added support for mairix, and proposed the mapping
|
|
API.
|
|
|
|
- Ulf Stegemann created the table to translate special symbols to
|
|
HTML, LaTeX, UTF-8, Latin-1 and ASCII.
|
|
|
|
- Andy Stewart contributed code to {{{file(org-w3m.el)}}}, to copy
|
|
HTML content with links transformation to Org syntax.
|
|
|
|
- David O'Toole wrote {{{file(org-publish.el)}}} and drafted the
|
|
manual chapter about publishing.
|
|
|
|
- Jambunathan K contributed the ODT exporter.
|
|
|
|
- Sebastien Vauban reported many issues with LaTeX and BEAMER
|
|
export and enabled source code highlighting in Gnus.
|
|
|
|
- Stefan Vollmar organized a video-recorded talk at the
|
|
Max-Planck-Institute for Neurology. He also inspired the creation
|
|
of a concept index for HTML export.
|
|
|
|
- J\"urgen Vollmer contributed code generating the table of contents
|
|
in HTML output.
|
|
|
|
- Samuel Wales has provided important feedback and bug reports.
|
|
|
|
- Chris Wallace provided a patch implementing the {{{samp(QUOTE)}}}
|
|
keyword.
|
|
|
|
- David Wainberg suggested archiving, and improvements to the
|
|
linking system.
|
|
|
|
- Carsten Wimmer suggested some changes and helped fix a bug in
|
|
linking to Gnus.
|
|
|
|
- Roland Winkler requested additional key bindings to make Org work
|
|
on a tty.
|
|
|
|
- Piotr Zielinski wrote {{{file(org-mouse.el)}}}, proposed agenda
|
|
blocks and contributed various ideas and code snippets.
|
|
|
|
* GNU Free Documentation License
|
|
:PROPERTIES:
|
|
:APPENDIX: t
|
|
:DESCRIPTION: The license for this documentation.
|
|
:END:
|
|
|
|
#+TEXINFO: @include ../doc/doclicense.texi
|
|
|
|
* Concept index
|
|
:PROPERTIES:
|
|
:ALT_TITLE: Main Index
|
|
:INDEX: cp
|
|
:DESCRIPTION: Org's concepts and features
|
|
:END:
|
|
|
|
* Key index
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Key bindings and where they are described
|
|
:ALT_TITLE: Key Index
|
|
:INDEX: ky
|
|
:END:
|
|
|
|
* Command and function index
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Command names and some internal functions
|
|
:ALT_TITLE: Command and Function Index
|
|
:INDEX: fn
|
|
:END:
|
|
|
|
* Variable index
|
|
:PROPERTIES:
|
|
:DESCRIPTION: Variables mentioned in the manual
|
|
:ALT_TITLE: Variable Index
|
|
:INDEX: vr
|
|
:END:
|
|
|
|
This is not a complete index of variables and faces, only the ones
|
|
that are mentioned in the manual. For a more complete list, use
|
|
{{{kbdspckey(M-x org-customize,RET)}}} and then click yourself through
|
|
the tree.
|
|
|
|
* Copying
|
|
:PROPERTIES:
|
|
:copying: t
|
|
:END:
|
|
|
|
This manual is for Org version {{{version}}}.
|
|
|
|
Copyright (C) 2004-2013 Free Software Foundation, Inc.
|
|
|
|
#+BEGIN_QUOTE
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
|
|
and with the Back-Cover Texts as in (a) below. A copy of the license
|
|
is included in the section entitled ``GNU Free Documentation License.''
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
|
|
modify this GNU manual. Buying copies from the FSF supports it in
|
|
developing GNU and promoting software freedom.''
|
|
|
|
This document is part of a collection distributed under the GNU Free
|
|
Documentation License. If you want to distribute this document
|
|
separately from the collection, you can do so by adding a copy of the
|
|
license to the document, as described in section 6 of the license.
|
|
#+END_QUOTE
|
|
|
|
* Macro definitions :noexport:
|
|
|
|
# Version macro, with commit hash
|
|
#+MACRO: version (eval (pcase (split-string (org-version nil t) "[ (_]" t) (`(,_ ,_ ,n ,_ ,r . ,_) (format "%s (release_%s)" n r))))
|
|
|
|
# Markup macros. In texinfo export they will be marked up, otherwise
|
|
# they will be inserted verbatim. markup is the generic form that can
|
|
# be used to insert any @-command with the second variable being the
|
|
# text to mark up.
|
|
#+MACRO: markup @@info:@$1{@@$2@@info:}@@
|
|
#+MACRO: kbd {{{markup(kbd,$1)}}}
|
|
#+MACRO: key {{{markup(key,$1)}}}
|
|
#+MACRO: samp {{{markup(samp,$1)}}}
|
|
#+MACRO: command {{{markup(command,$1)}}}
|
|
#+MACRO: file {{{markup(file,$1)}}}
|
|
#+MACRO: var {{{markup(var,$1)}}}
|
|
#+MACRO: cite {{{markup(cite,$1)}}}
|
|
#+MACRO: value {{{markup(value,$1)}}}
|
|
|
|
#+MACRO: kbdkey {{{kbd($1{{{key($2)}}})}}}
|
|
#+MACRO: kbdspckey {{{kbd($1 {{{key($2)}}})}}}
|
|
#+MACRO: ksksksk {{{kbd($1 {{{key($2)}}} $3 {{{key($4)}}})}}}
|
|
#+MACRO: ksksksksk {{{kbd($1 {{{key($2)}}} $3 {{{key($4)}}} {{{key($5)}}})}}}
|
|
#+MACRO: kbdkeys {{{kbd($1{{{key($2)}}}{{{key($3)}}})}}}
|
|
|
|
# Plain macros.
|
|
#+MACRO: noindent @@info:@noindent@@
|
|
#+MACRO: result @@info:@result{}@@
|
|
#+MACRO: page @@info:@page@@
|
|
|
|
* Instructions for use :noexport:
|
|
- [ ] Tangle the makefile, `C-c C-v t'
|
|
- [ ] Execute [[Editing setup][this source code block]]
|
|
- [ ] Asynchronously generate the info file, `C-e i i'
|
|
|
|
* Improvements and fixes [10/12] :noexport:
|
|
- [X] Jon will fix detailed node listing
|
|
- [X] Jon will fix :INDEX: property
|
|
- [ ] New link type to generate pxref? (asked on ML)
|
|
- [X] New macro for kbdkey that preserves space, e.g., `C-c <RET>'
|
|
- [X] Indent examples one more space to match indentation of footnotes
|
|
- [X] How to generate @kbd{\}?
|
|
- [X] How to generate @kbd{~}?
|
|
- [X] How to include GNU Free Documentation License as Appendix D?
|
|
- [X] Straighten out footnotes
|
|
- [X] Truncated footnote (asked on ML)
|
|
- [ ] Resolve macros with XXX arguments
|
|
- [X] Get @appendix instead of @chapter?
|
|
|
|
* Org-mode setup :noexport:
|
|
** Editing setup
|
|
#+name: setup-editing
|
|
#+header: :results silent
|
|
#+header: :noweb yes
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(require 'ox-texinfo)
|
|
(define-key org-mode-map (kbd "C-c e") 'org-export-dispatch)
|
|
(setq org-src-preserve-indentation t)
|
|
(setq org-export-in-background t)
|
|
(setq org-export-async-debug t)
|
|
(setq org-export-async-init-file (expand-file-name "init.el"))
|
|
(setq org-pretty-entities nil)
|
|
(setq org-footnote-auto-adjust nil)
|
|
(setq org-confirm-babel-evaluate nil)
|
|
(org-babel-do-load-languages
|
|
'org-babel-load-languages
|
|
'((emacs-lisp . t)
|
|
(sh . t)))
|
|
(org-add-link-type
|
|
"pxref" nil
|
|
(lambda (path desc format)
|
|
(cond
|
|
((eq format 'html)
|
|
(format "<span class=\"pxref\">%s</span>" path))
|
|
((eq format 'latex)
|
|
(format "\\ref{%s}" path))
|
|
((eq format 'texinfo)
|
|
(format "@pxref{%s,%s}" path desc)))))
|
|
(add-to-list 'org-export-snippet-translation-alist
|
|
'("info" . "texinfo"))
|
|
#+end_src
|
|
|
|
** init.el file
|
|
This source code block requires paths to your Org mode installation.
|
|
Modify accordingly.
|
|
|
|
#+name: emacs-init
|
|
#+header: :tangle init.el
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(setq load-path (cons "~/.emacs.d/src/org-mode/lisp" load-path))
|
|
; (setq load-path (cons "~/.emacs.d/src/org-mode/contrib/lisp" load-path))
|
|
(require 'ox-texinfo)
|
|
(setq org-src-preserve-indentation t)
|
|
(setq org-confirm-babel-evaluate nil)
|
|
(setq org-footnote-auto-adjust nil)
|
|
(org-babel-do-load-languages
|
|
'org-babel-load-languages
|
|
'((emacs-lisp . t)
|
|
(makefile . t)
|
|
(sh . t)))
|
|
(add-to-list 'org-export-snippet-translation-alist
|
|
'("info" . "texinfo"))
|
|
#+end_src
|
|
|
|
** Texi -> Org helpers :noexport:
|
|
This section contains source code blocks that help translate from
|
|
=texinfo= to =Org=.
|
|
|
|
#+name: tsd-helpers
|
|
#+header: :noweb yes
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
<<tsd-index-to-macro>>
|
|
<<tsd-samp-to-macro>>
|
|
<<tsd-kbdkey-to-macro>>
|
|
<<tsd-kbd-to-macro>>
|
|
<<tsd-key-to-macro>>
|
|
<<tsd-command-to-macro>>
|
|
<<tsd-file-to-macro>>
|
|
<<tsd-noindent>>
|
|
<<tsd-example-block-begin>>
|
|
<<tsd-example-block-end>>
|
|
<<tsd-table-begin>>
|
|
<<tsd-table-end>>
|
|
<<tsd-pxref>>
|
|
<<tsd-xref>>
|
|
<<tsd-ref>>
|
|
<<tsd-orgcmd>>
|
|
<<tsd-orgkey>>
|
|
<<tsd-code-to-markup>>
|
|
<<tsd-emph-to-markup>>
|
|
<<tsd-i-to-markup>>
|
|
<<tsd-lisp-begin>>
|
|
<<tsd-lisp-end>>
|
|
#+end_src
|
|
|
|
#+results: tsd-helpers
|
|
: tsd-lisp-end
|
|
|
|
#+name: tsd-index-to-macro
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-index-to-macro ()
|
|
"Make macros out of @[cpfvk]index commands. Doesn't handle commas."
|
|
(interactive)
|
|
(query-replace-regexp "@\\([cpfvk]\\)index\\ \\(.*\\)$" "{{{\\1index(\\2)}}}" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-samp-to-macro
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-samp-to-macro ()
|
|
"Make macros out of @samp commands."
|
|
(interactive)
|
|
(query-replace-regexp "@samp{\\([^}]*\\)}" "{{{samp(\\1)}}}" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-kbdkey-to-macro
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-kbdkey-to-macro ()
|
|
"Make macros out of @kbd,@key commands."
|
|
(interactive)
|
|
(query-replace-regexp "@kbd{\\([^@]*\\)@key{\\([^}]*\\)}}" "{{{kbdkey(\\1,\\2)}}}" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-kbd-to-macro
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-kbd-to-macro ()
|
|
"Make macros out of @kbd commands."
|
|
(interactive)
|
|
(query-replace-regexp "@kbd{\\([^}]*\\)}" "{{{kbd(\\1)}}}" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-key-to-macro
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-key-to-macro ()
|
|
"Make macros out of @key commands."
|
|
(interactive)
|
|
(query-replace-regexp "@key{\\([^}]*\\)}" "{{{key(\\1)}}}" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-command-to-macro
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-command-to-macro ()
|
|
"Make macros out of @command commands."
|
|
(interactive)
|
|
(query-replace-regexp "@command{\\([^}]*\\)}" "{{{command(\\1)}}}" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-file-to-macro
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-file-to-macro ()
|
|
"Make macros out of @file commands."
|
|
(interactive)
|
|
(query-replace-regexp "@file{\\([^}]*\\)}" "{{{file(\\1)}}}" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-noindent
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-noindent ()
|
|
"Make macros out of @noindent commands."
|
|
(interactive)
|
|
(query-replace "@noindent" "{{{noindent}}}" t))
|
|
#+end_src
|
|
|
|
#+name: tsd-example-block-begin
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-example-block-begin ()
|
|
"Convert example blocks."
|
|
(interactive)
|
|
(query-replace "@example" "#+begin_example" t))
|
|
#+end_src
|
|
|
|
#+name: tsd-example-block-end
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-example-block-end ()
|
|
"Convert example blocks."
|
|
(interactive)
|
|
(query-replace "@end example" "#+end_example" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-table-begin
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-table-begin ()
|
|
"Convert table blocks."
|
|
(interactive)
|
|
(query-replace-regexp "@table\\ \\([@a-z]*\\)" "#+attr_texinfo: :table-type table :indic \\1 t))
|
|
#+end_src
|
|
|
|
#+name: tsd-table-end
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-table-end ()
|
|
"Convert table blocks."
|
|
(interactive)
|
|
(query-replace "@end table" "" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-pxref
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-pxref ()
|
|
"Convert @pxref to links."
|
|
(interactive)
|
|
(query-replace-regexp "@pxref{\\([^}]*\\)}" "see \[\[\\1\]\]" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-xref
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-xref ()
|
|
"Convert @xref to links."
|
|
(interactive)
|
|
(query-replace-regexp "@xref{\\([^}]*\\)}" "See \[\[\\1\]\]" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-ref
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-ref ()
|
|
"Convert @ref to links."
|
|
(interactive)
|
|
(query-replace-regexp "@ref{\\([^}]*\\)}" "\[\[\\1\]\]" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-orgcmd
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-orgcmd ()
|
|
"Convert @orgcmd to list entry."
|
|
(interactive)
|
|
(query-replace-regexp "@orgcmd{\\([^,]*\\),\\([^}]*\\)}" "- {{{kbd(\\1)}}}, ~\\2~ ::" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-orgkey
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-orgkey ()
|
|
"Convert @orgkey to list entry."
|
|
(interactive)
|
|
(query-replace-regexp "@orgkey{\\([^}]*\\)}" "- {{{kbd(\\1)}}} ::" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-code-to-markup
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-code-to-markup ()
|
|
"Convert @code to markup."
|
|
(interactive)
|
|
(query-replace-regexp "@code{\\([^}]*\\)}" "~\\1~" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-emph-to-markup
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-emph-to-markup ()
|
|
"Convert @emph to markup."
|
|
(interactive)
|
|
(query-replace-regexp "@emph{\\([^}]*\\)}" "/\\1/" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-i-to-markup
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-i-to-markup ()
|
|
"Convert @i to markup."
|
|
(interactive)
|
|
(query-replace-regexp "@i{\\([^}]*\\)}" "/\\1/" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-b-to-markup
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-b-to-markup ()
|
|
"Convert @b to markup."
|
|
(interactive)
|
|
(query-replace-regexp "@b{\\([^}]*\\)}" "*\\1*" nil))
|
|
#+end_src
|
|
|
|
#+name: tsd-lisp-begin
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-lisp-begin ()
|
|
"Convert @lisp blocks."
|
|
(interactive)
|
|
(query-replace "@lisp" "#+begin_src emacs-lisp" t))
|
|
#+end_src
|
|
|
|
#+name: tsd-lisp-end
|
|
#+header: :results silent
|
|
#+header: :eval no-export
|
|
#+begin_src emacs-lisp
|
|
(defun tsd-lisp-end ()
|
|
"Convert @lisp blocks."
|
|
(interactive)
|
|
(query-replace "@end lisp" "#+end_src" nil))
|
|
#+end_src
|
|
|
|
* Footnotes
|
|
|
|
[fn:1] The iCalendar file will contain TODO and agenda items only.
|
|
|
|
[fn:2] If your Emacs distribution does not come with Org,
|
|
the function ~org-version~ will not be defined.
|
|
|
|
[fn:3] The ~master~ branch is where development takes place.
|
|
|
|
[fn:4] The output from install-info (if any) is system dependent. In
|
|
particular, Debian and its derivatives use two different versions of
|
|
install-info. You may safely ignore the message:
|
|
#+begin_example
|
|
This is not dpkg install-info anymore, but GNU install-info
|
|
See the man page for ginstall-info for command line arguments
|
|
#+end_example
|
|
returned by install-info.
|
|
|
|
[fn:5] If you don't use font-lock globally, turn it on in an Org
|
|
buffer with ~(add-hook 'org-mode-hook 'turn-on-font-lock)~.
|
|
|
|
[fn:6] Please consider subscribing to the mailing list in order to
|
|
minimize the work the mailing list moderators have to do.
|
|
|
|
[fn:7] Easy templates insert lowercase keywords and Babel dynamically
|
|
inserts ~#+results~.
|
|
|
|
[fn:8] See the variables ~org-special-ctrl-a/e~, ~org-special-ctrl-k~,
|
|
and ~org-ctrl-k-protect-subtree~ to configure special behavior of
|
|
{{{kbd(C-a)}}}, {{{kbd(C-e)}}}, and {{{kbd(C-k)}}} in headlines. Note
|
|
also that clocking only works with headings indented less than 30
|
|
stars.
|
|
|
|
[fn:9] See the option ~org-cycle-global-at-bob~.
|
|
|
|
[fn:10] The indirect buffer will contain the entire buffer, but will
|
|
be narrowed to the current tree. Editing the indirect buffer will also
|
|
change the original buffer, but without affecting visibility in that
|
|
buffer. For more information about indirect buffers,
|
|
[[info:emacs:Indirect Buffers][GNU Emacs Manual]].
|
|
|
|
[fn:11] If you do not want the line to be split, customize the
|
|
variable ~org-M-RET-may-split-line~.
|
|
|
|
[fn:12] See also the variables ~org-show-hierarchy-above~,
|
|
~org-show-following-heading~, ~org-show-siblings~, and
|
|
~org-show-entry-below~ for detailed control on how much context is
|
|
shown around each match.
|
|
|
|
[fn:13] This depends on the option ~org-remove-highlights-with-change~.
|
|
|
|
[fn:14] This does not work under XEmacs, because XEmacs uses selective
|
|
display for outlining, not text properties.
|
|
|
|
[fn:15] When using ~*~ as a bullet, lines must be indented or they will
|
|
be seen as top-level headlines. Also, when you are hiding leading
|
|
stars to get a clean outline view, plain list items starting with a
|
|
star may be hard to distinguish from true headlines. In short: even
|
|
though ~*~ is supported, it may be better to not use it for plain list
|
|
items.
|
|
|
|
[fn:16] You can filter out any of them by configuring
|
|
~org-plain-list-ordered-item-terminator~.
|
|
|
|
[fn:17] If there's a checkbox in the item, the cookie must be put
|
|
_before_ the checkbox. If you have activated alphabetical lists, you
|
|
can also use counters like ~[@b]~.
|
|
|
|
[fn:18] Org only changes the filling settings for Emacs. For XEmacs,
|
|
you should use Kyle E. Jones' {{{file(filladapt.el)}}}.
|
|
|
|
[fn:19] If you do not want the item to be split, customize the
|
|
variable ~org-M-RET-may-split-line~.
|
|
|
|
[fn:20] If you want to cycle around items that way, you may customize
|
|
~org-list-use-circular-motion~.
|
|
|
|
[fn:21] See ~org-list-use-circular-motion~ for a cyclic behavior.
|
|
|
|
[fn:24] Centering does not work inside Emacs, but it does have an
|
|
effect when exporting to HTML.
|
|
|
|
[fn:26] For backward compatibility you can also use special names like
|
|
~$LR5~ and ~$LR12~ to refer in a stable way to the fifth and twelfth
|
|
field in the last row of the table. However, this syntax is
|
|
deprecated, it should not be used for new documents. Use ~@>$~
|
|
instead.
|
|
|
|
[fn:25] Org will understand references typed by the user as
|
|
{{{samp(B4)}}}, but it will not use this syntax when offering a
|
|
formula for editing. You can customize this behavior using the
|
|
variable ~org-table-use-standard-references~.
|
|
|
|
[fn:22] To insert a vertical bar into a table field, use ~\vert~ or,
|
|
inside a word ~abc\vert{}def~.
|
|
|
|
[fn:23] This feature does not work on XEmacs.
|
|
|
|
[fn:27] The computation time scales as O(N^2) because table FOO is
|
|
parsed for each field to be copied.
|
|
|
|
[fn:28] The {{{file(calc)}}} package has the non-standard
|
|
convention that ~/~ has lower precedence than ~*~, so that ~a/b*c~ is
|
|
interpreted as ~a/(b*c)~.
|
|
|
|
[fn:29] The ~printf~ reformatting is limited in precision because the
|
|
value passed to it is converted into an ~integer~ or ~double~. The
|
|
~integer~ is limited in size by truncating the signed value to 32
|
|
bits. The ~double~ is limited in precision to 64 bits overall which
|
|
leaves approximately 16 significant decimal digits.
|
|
|
|
[fn:30] Such names must start with an alphabetic character and use
|
|
only alphanumeric/underscore characters.
|
|
|
|
[fn:31] 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.
|
|
|
|
[fn:32] To insert a link targeting a headline, in-buffer completion
|
|
can be used. Just type a star followed by a few optional letters into
|
|
the buffer and press {{{kbdkey(M-,TAB)}}}. All headlines in the
|
|
current buffer will be offered as completions.
|
|
|
|
[fn:33] The actual behavior of the search will depend on the value of
|
|
the variable ~org-link-search-must-match-exact-headline~. If its value
|
|
is ~nil~, then a fuzzy text search will be done. If it is ~t~, then
|
|
only the exact headline will be matched. If the value is
|
|
{{{samp('query-to-create)}}}, then an exact headline will be searched;
|
|
if it is not found, then the user will be queried to create it.
|
|
|
|
[fn:34] If the headline contains a timestamp, it will be removed from
|
|
the link and result in a wrong link -- you should avoid putting a
|
|
timestamp in the headline.
|
|
|
|
[fn:35] Note that you don't have to use this command to insert a link.
|
|
Links in Org are plain text, and you can type or paste them straight
|
|
into the buffer. By using this command, the links are automatically
|
|
enclosed in double brackets, and you will be asked for the optional
|
|
descriptive text.
|
|
|
|
[fn:36] After insertion of a stored link, the link will be removed
|
|
from the list of stored links. To keep it in the list later use, use a
|
|
triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or
|
|
configure the option ~org-keep-stored-link-after-insertion~.
|
|
|
|
[fn:37] This works if a function has been defined in the ~:complete~
|
|
property of a link in ~org-link-parameters~.
|
|
|
|
[fn:38] See the variable ~org-display-internal-link-with-indirect-buffer~.
|
|
|
|
[fn:44] Check also the variable ~org-fast-tag-selection-include-todo~,
|
|
it allows you to change the TODO state through the tags interface
|
|
([[Setting tags]]), in case you like to mingle the two concepts. Note that
|
|
this means you need to come up with unique keys across both sets of
|
|
keywords.
|
|
|
|
[fn:39] For backward compatibility, line numbers can also follow a
|
|
single colon.
|
|
|
|
[fn:40] Of course, you can make a document that contains only long
|
|
lists of TODO items, but this is not required.
|
|
|
|
[fn:41] Changing the variable ~org-todo-keywords~ only becomes
|
|
effective after restarting Org mode in a buffer.
|
|
|
|
[fn:42] This is also true for the {{{kbd(t)}}} command in the timeline
|
|
and agenda buffers.
|
|
|
|
[fn:43] All characters are allowed except ~@^!~, which have a special
|
|
meaning here.
|
|
|
|
[fn:45] Org mode parses these lines only when Org mode is activated
|
|
after visiting a file. {{{kbd(C-c C-c)}}} with the cursor in a line
|
|
starting with {{{samp(#+)}}} is simply restarting Org mode for the
|
|
current buffer.
|
|
|
|
[fn:46] The corresponding in-buffer setting is: ~#+STARTUP: logdone~.
|
|
|
|
[fn:47] The corresponding in-buffer setting is: ~#+STARTUP: lognotedone~.
|
|
|
|
[fn:48] See the variable ~org-log-states-order-reversed~.
|
|
|
|
[fn:54] {{{kbd(C-u C-c C-c)}}} on the /first/ item of a list with no
|
|
checkbox will add checkboxes to the rest of the list.
|
|
|
|
[fn:49] It is possible that Org mode will record two timestamps when
|
|
you are using both ~org-log-done~ and state change logging. 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)}}}.
|
|
|
|
[fn:50] See also the option ~org-priority-start-cycle-with-default~.
|
|
|
|
[fn:51] To keep subtasks out of the global TODO list, see the
|
|
~org-agenda-todo-list-sublevels~.
|
|
|
|
[fn:52] With the exception of description lists. But you can allow it
|
|
by modifying ~org-list-automatic-rules~ accordingly.
|
|
|
|
[fn:53] Set the variable ~org-hierarchical-checkbox-statistics~ if you
|
|
want such cookies to count all checkboxes below the cookie, not just
|
|
those belonging to direct children.
|
|
|
|
[fn:55] As with all these in-buffer settings, pressing
|
|
{{{kbd(C-c C-c)}}} activates any changes in the line.
|
|
|
|
[fn:56] This is only true if the search does not involve more complex
|
|
tests including properties (see [[Property searches]]).
|
|
|
|
[fn:57] Keys will automatically be assigned to tags that have no
|
|
configured keys.
|
|
|
|
[fn:58] Please note that the COLUMNS definition must be on a single
|
|
line---it is wrapped here only because of formatting constraints.
|
|
|
|
[fn:59] Contributed packages are not part of Emacs, but are
|
|
distributed with the main distribution of Org (visit
|
|
[[http://orgmode.org]]).
|
|
|
|
[fn:60] The Org date format is inspired by the standard ISO 8601
|
|
date/time format. To use an alternative format, see [[Custom time
|
|
format]]. The day name is optional when you type the date yourself.
|
|
However, any dates inserted or modified by Org will add that day name,
|
|
for reading convenience.
|
|
|
|
[fn:61] When working with the standard diary sexp functions, you need
|
|
to be very careful with the order of the arguments. That order depends
|
|
evilly on the variable ~calendar-date-style~ (or, for older Emacs
|
|
versions, ~european-calendar-style~). For example, to specify a date
|
|
December 12, 2005, the call might look like ~(diary-date 12 1 2005)~
|
|
or ~(diary-date 1 12 2005)~ or ~(diary-date 2005 12 1)~, depending on
|
|
the settings. This has been the source of much confusion. Org mode
|
|
users can resort to special versions of these functions like
|
|
~org-date~ or ~org-anniversary~. These work just like the
|
|
corresponding ~diary-~ functions, but with stable ISO order of
|
|
arguments (year, month, day) wherever applicable, independent of the
|
|
value of ~calendar-date-style~.
|
|
|
|
[fn:62] See the variable ~org-read-date-prefer-future~. You may
|
|
set that variable to the symbol ~time~ to even make a time before now
|
|
shift the date to tomorrow.
|
|
|
|
[fn:63] If you don't need/want the calendar, configure the variable
|
|
~org-popup-calendar-for-date-prompt~.
|
|
|
|
[fn:64] If you find this distracting, turn off the display with
|
|
~org-read-date-display-live~.
|
|
|
|
[fn:65] It will still be listed on that date after it has been marked
|
|
DONE. If you don't like this, set the variable
|
|
~org-agenda-skip-scheduled-if-done~.
|
|
|
|
[fn:66] The {{{samp(SCHEDULED)}}} and {{{samp(DEADLINE)}}} dates are
|
|
inserted on the line right below the headline. Don't put any text
|
|
between this line and the headline.
|
|
|
|
[fn:67] Note the corresponding ~#+STARTUP~ keywords ~logredeadline~,
|
|
~lognoteredeadline~, and ~nologredeadline~.
|
|
|
|
[fn:68] Note the corresponding ~#+STARTUP~ keywords ~logreschedule~,
|
|
~lognotereschedule~, and ~nologreschedule~.
|
|
|
|
[fn:69] In fact, the target state is taken from, in this sequence, the
|
|
~REPEAT_TO_STATE~ property or the variable ~org-todo-repeat-to-state~.
|
|
If neither of these is specified, the target state defaults to the
|
|
first state of the TODO state sequence.
|
|
|
|
[fn:70] You can change this using the option ~org-log-repeat~, or the
|
|
~#+STARTUP~ options ~logrepeat~, ~lognoterepeat~, and ~nologrepeat~.
|
|
With ~lognoterepeat~, you will also be prompted for a note.
|
|
|
|
[fn:71] Clocking only works if all headings are indented with less
|
|
than 30 stars. This is a hardcoded limitation of ~lmax~ in
|
|
~org-clock-sum~.
|
|
|
|
[fn:72] To resume the clock under the assumption that you have worked
|
|
on this task while outside Emacs, use ~(setq org-clock-persist t)~.
|
|
|
|
[fn:73] To add an effort estimate ``on the fly'', hook a function
|
|
doing this to ~org-clock-in-prepare-hook~.
|
|
|
|
[fn:74] The last reset of the task is recorded by the ~LAST_REPEAT~
|
|
property.
|
|
|
|
[fn:75] See also the variable ~org-clock-modeline-total~.
|
|
|
|
[fn:76] The corresponding in-buffer setting is:
|
|
~#+STARTUP: lognoteclock-out~.
|
|
|
|
[fn:77] Language terms can be set through the variable
|
|
~org-clock-clocktable-language-setup~.
|
|
|
|
[fn:78] Note that all parameters must be specified in a single
|
|
line---the line is broken here only to fit it into the manual.
|
|
|
|
[fn:79] On computers using Mac OS X, idleness is based on actual user
|
|
idleness, not just Emacs' idle time. For X11, you can install a
|
|
utility program {{{file(x11idle.c)}}}, available in the
|
|
~contrib/scripts~ directory of the Org git distribution, to get the
|
|
same general treatment of idleness. On other systems, idle time refers
|
|
to Emacs idle time only.
|
|
|
|
[fn:80] You may change the property being used with the variable
|
|
~org-effort-property~.
|
|
|
|
[fn:86] Note the corresponding ~#+STARTUP~ keywords ~logrefile~,
|
|
~lognoterefile~, and ~nologrefile~.
|
|
|
|
[fn:81] Please select your own key, {{{kbd(C-c c)}}} is only a
|
|
suggestion.
|
|
|
|
[fn:82] If you need one of these sequences literally, escape the
|
|
{{{kbd(%)}}} with a backslash.
|
|
|
|
[fn:83] If you define your own link types (see [[Adding hyperlink
|
|
types]]), any property you store with ~org-store-link-props~ can be
|
|
accessed in capture templates in a similar way.
|
|
|
|
[fn:84] This will always be the other, not the user. See the variable
|
|
~org-from-is-user-regexp~.
|
|
|
|
[fn:85] If you move entries or Org files from one directory to
|
|
another, you may want to configure ~org-attach-directory~ to contain
|
|
an absolute path.
|
|
|
|
[fn:87] For backward compatibility, the following also works: If there
|
|
are several such lines in a file, each specifies the archive location
|
|
for the text below it. The first such line also applies to any text
|
|
before its definition. However, using this method is /strongly/
|
|
deprecated as it is incompatible with the outline structure of the
|
|
document. The correct method for setting multiple archive locations in
|
|
a buffer is using properties.
|
|
|
|
[fn:94] Only tags filtering will be respected here, effort filtering
|
|
is ignored.
|
|
|
|
[fn:88] When using the dispatcher, pressing {{{kbd(<)}}} before
|
|
selecting a command will actually limit the command to the current
|
|
file, and ignore ~org-agenda-files~ until the next dispatcher command.
|
|
|
|
[fn:89] For backward compatibility, you can also press {{{kbd(1)}}} to
|
|
restrict to the current buffer.
|
|
|
|
[fn:90] For backward compatibility, you can also press {{{kbd(0)}}} to
|
|
restrict to the current region/subtree.
|
|
|
|
[fn:91] 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 (see [[Block agenda]]).
|
|
|
|
[fn:92] But see [[x-agenda-skip-entry-regexp][skipping entries based on regexp]].
|
|
|
|
[fn:93] For backward compatibility, the following also works: if
|
|
there are several such lines in a file, each specifies the category
|
|
for the text below it. The first category also applies to any text
|
|
before the first CATEGORY line. However, using this method is
|
|
/strongly/ deprecated as it is incompatible with the outline structure
|
|
of the document. The correct method for setting multiple categories in
|
|
a buffer is using a property.
|
|
|
|
[fn:95] Custom commands can preset a filter by binding the variable
|
|
~org-agenda-tag-filter-preset~ as an option. This filter will then be
|
|
applied to the view and persist as a basic filter through refreshes
|
|
and more secondary filtering. The filter is a global property of the
|
|
entire agenda view---in a block agenda, you should only set this in
|
|
the global options section, not in the section of an individual block.
|
|
|
|
[fn:96] You can also create persistent custom functions through
|
|
~org-agenda-bulk-custom-functions~.
|
|
|
|
[fn:97] The Emacs diary file is parsed for the agenda when
|
|
~org-agenda-include-diary~ is set.
|
|
|
|
[fn:98] You can provide a description for a prefix key by inserting a
|
|
cons cell with the prefix and the description.
|
|
|
|
[fn:99] For HTML you need to install Hrvoje Niksic's
|
|
{{{file(htmlize.el)}}}. To create PDF output, the ghostscript
|
|
{{{file(ps2pdf)}}} utility must be installed on the system. Selecting
|
|
a PDF file will also create the postscript file.
|
|
|
|
[fn:100] If you want to store standard views like the weekly agenda or
|
|
the global TODO list as well, you need to define custom commands for
|
|
them in order to be able to specify file names.
|
|
|
|
[fn:101] Quoting depends on the system you use, please check the FAQ
|
|
for examples.
|
|
|
|
[fn:102] This works automatically for the HTML backend (it requires
|
|
version 1.34 of the {{{file(htmlize.el)}}} package, which is
|
|
distributed with Org). Fontified code chunks in LaTeX can be
|
|
achieved using either the listings package or the [[http://code.google.com/p/minted][minted]] package.
|
|
Refer to ~org-export-latex-listings~ documentation for details.
|
|
|
|
[fn:103] Code in {{{samp(src)}}} blocks may also be evaluated either
|
|
interactively or on export. See [[Working with source code]] for more
|
|
information on evaluating code blocks.
|
|
|
|
[fn:104] Adding ~-k~ to ~-n -r~ will /keep/ the labels in the source
|
|
code while using line numbers for the links, which might be useful to
|
|
explain those in an Org mode example code.
|
|
|
|
[fn:105] Upon exit, lines starting with {{{samp(*)}}}, {{{samp(\,*)}}},
|
|
{{{samp(#+)}}} and {{{samp(\,#+)}}} will get a comma prepended, to keep
|
|
them from being interpreted by Org as outline nodes or special syntax.
|
|
These commas will be stripped for editing with {{{kbd(C-c ')}}}, and
|
|
also for export.
|
|
|
|
[fn:106] You may select a different-mode with the variable
|
|
~org-edit-fixed-width-region-mode~.
|
|
|
|
[fn:107] LaTeX is a macro system based on Donald\nbsp{}E.\nbsp{}Knuth's TeX
|
|
system. Many of the features described here as LaTeX are really
|
|
from TeX, but for simplicity I am blurring this distinction.
|
|
|
|
[fn:108] You can turn this on by default by setting the variable
|
|
~org-pretty-entities~, or on a per-file base with the ~#+STARTUP~
|
|
option ~entitiespretty~.
|
|
|
|
[fn:109] If you plan to use this regularly or on pages with
|
|
significant page views, you should install {{{file(MathJax)}}} on your
|
|
own server in order to limit the load of our server.
|
|
|
|
[fn:110] For this to work you need to be on a system with a working
|
|
LaTeX installation. You also need the {{{file(dvipng)}}} program or
|
|
the {{{file(convert)}}}, respectively available at
|
|
[[http://sourceforge.net/projects/dvipng/]] and from the
|
|
{{{file(ImageMagick)}}} suite. The LaTeX header that will be used
|
|
when processing a fragment can be configured with the variable
|
|
~org-format-latex-header~.
|
|
|
|
[fn:111] When {{{file(MathJax)}}} is used, only the environment
|
|
recognized by {{{file(MathJax)}}} will be processed. When
|
|
{{{file(dvipng)}}} is used to create images, any LaTeX environments
|
|
will be handled.
|
|
|
|
[fn:112] Org mode has a method to test if the cursor is inside such a
|
|
fragment, see the documentation of the function
|
|
~org-inside-LaTeX-fragment-p~.
|
|
|
|
[fn:113] The variable ~org-export-date-timestamp-format~ defines how
|
|
this timestamp will be exported.
|
|
|
|
[fn:114] If you want to configure many options this way, you can use
|
|
several ~#+OPTIONS~ lines.
|
|
|
|
[fn:115] To make this behavior the default, customize the variable
|
|
~org-export-run-in-background~.
|
|
|
|
[fn:116] This requires ~transient-mark-mode~ be turned on.
|
|
|
|
[fn:117] To select the current subtree, use {{{kbd(C-c @)}}}.
|
|
|
|
[fn:118] This requires ~transient-mark-mode~ be turned on.
|
|
|
|
[fn:119] To select the current subtree, use {{{kbd(C-c @)}}}.
|
|
|
|
[fn:120] But see the variable ~org-export-html-inline-images~.
|
|
|
|
[fn:121] If you plan to use this regularly or on pages with
|
|
significant page views, you should install MathJax on your own server
|
|
in order to limit the load of our server. Installation instructions
|
|
can be found on the MathJax website, see
|
|
[[http://www.mathjax.org/resources/docs/?installation.html]].
|
|
|
|
[fn:122] If the classes on TODO keywords and tags lead to conflicts,
|
|
use the variables ~org-export-html-todo-kwd-class-prefix~ and
|
|
~org-export-html-tag-class-prefix~ to make them unique.
|
|
|
|
[fn:123] This style is defined in the constant
|
|
~org-export-html-style-default~, which you should not modify. To turn
|
|
inclusion of these defaults off, customize
|
|
~org-export-html-style-include-default~.
|
|
|
|
[fn:124] The default LaTeX output is designed for processing with
|
|
~pdftex~ or LaTeX. It includes packages that are not compatible
|
|
with ~xetex~ and possibly ~luatex~. See the variables
|
|
~org-export-latex-default-packages-alist~ and
|
|
~org-export-latex-packages-alist~.
|
|
|
|
[fn:125] This requires ~transient-mark-mode~ be turned on.
|
|
|
|
[fn:126] To select the current subtree, use {{{kbd(C-c @)}}}.
|
|
|
|
[fn:127] Into which the values of
|
|
~org-export-latex-default-packages-alist~ and
|
|
~org-export-latex-packages-alist~ are spliced.
|
|
|
|
[fn:128] One can also take advantage of this option to pass other,
|
|
unrelated options into the figure or table environment. For an example
|
|
see the section ``Exporting org files'' in
|
|
[[http://orgmode.org/worg/org-hacks.html]].
|
|
|
|
[fn:129] This requires ~transient-mark-mode~ to be turned on.
|
|
|
|
[fn:130] To select the current subtree, use {{{kbd(C-c @)}}}.
|
|
|
|
[fn:131] ODT export was added in Org mode version 7.8.
|
|
|
|
[fn:132] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications (OpenDocument)
|
|
Version 1.2]].
|
|
|
|
[fn:133] This requires ~transient-mark-mode~ to be turned on.
|
|
|
|
[fn:134] To select the current subtree, use {{{kbd(C-c @)}}}.
|
|
|
|
[fn:135] The column widths are interpreted as weighted ratios with the
|
|
default weight being 1.
|
|
|
|
[fn:136] Use of {{{file(ImageMagick)}}} is only desirable. However, if
|
|
you routinely produce documents that have large images or you export
|
|
your Org files that has images using a Emacs batch script, then the
|
|
use of {{{file(ImageMagick)}}} is mandatory.
|
|
|
|
[fn:137] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]].
|
|
|
|
[fn:138] Your {{{file(htmlfontify.el)}}} library must at least be at
|
|
Emacs 24.1 levels for fontification to be turned on.
|
|
|
|
[fn:139] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]].
|
|
|
|
[fn:140] See the ~<table:table-template>~ element of the
|
|
OpenDocument-v1.2 specification.
|
|
|
|
[fn:141] See the attributes ~table:template-name~,
|
|
~table:use-first-row-styles~, ~table:use-last-row-styles~,
|
|
~table:use-first-column-styles~, ~table:use-last-column-styles~,
|
|
~table:use-banding-rows-styles~, and ~table:use-banding-column-styles~
|
|
of the ~<table:table>~ element in the OpenDocument-v1.2 specification.
|
|
|
|
[fn:142] Note that {{{file(.odt)}}} files are {{{samp(zip)}}}
|
|
archives.
|
|
|
|
[fn:143] See the variables ~org-icalendar-use-deadline~ and
|
|
~org-icalendar-use-scheduled~.
|
|
|
|
[fn:144] To add inherited tags or the TODO state, configure the
|
|
variable ~org-icalendar-categories~.
|
|
|
|
[fn:145] The LOCATION property can be inherited from higher in the
|
|
hierarchy if you configure ~org-use-property-inheritance~ accordingly.
|
|
|
|
[fn:146] The files {{{file(file-source.org)}}} and
|
|
{{{file(file-source.org.html)}}} if source and publishing directories
|
|
are equal. Note that with this kind of setup, you need to add
|
|
~:exclude "-source\\.org"~ to the project definition in
|
|
~org-publish-project-alist~ to prevent the published source files from
|
|
being considered as new org files the next time the project is
|
|
published.
|
|
|
|
[fn:147] Note that {{{samp(src)}}} blocks may be inserted using Org
|
|
mode's [[Easy templates]] system.
|
|
|
|
[fn:148] Whenever code is evaluated there is a potential for that code
|
|
to do harm. Org mode provides safeguards to ensure that code is only
|
|
evaluated after explicit confirmation from the user. For information
|
|
on these safeguards (and on how to disable them) see [[Code evaluation
|
|
security]].
|
|
|
|
[fn:149] The ~org-babel-no-eval-on-ctrl-c-ctrl-c~ variable can be used
|
|
to remove code evaluation from the {{{kbd(C-c C-c)}}} key binding.
|
|
|
|
[fn:150] Note that evaluation of header arguments is guaranteed to
|
|
take place in the original Org mode file, while there is no such
|
|
guarantee for evaluation of the code block body.
|
|
|
|
[fn:151] The example requires that property inheritance be turned on
|
|
for the ~noweb-ref~ property, see [[Property inheritance]].
|
|
|
|
[fn:152] In certain languages this also contains the error output
|
|
stream; this is an area for future work.
|
|
|
|
[fn:153] The last evaluation performed by the interpreter is obtained
|
|
in a language-specific manner: the value of the variable ~_~ in Python
|
|
and Ruby, and the value of ~.Last.value~ in R.
|
|
|
|
[fn:161] If the {{{samp(#+TBLFM)}}} line contains an odd number of
|
|
dollar characters, this may cause problems with font-lock in LaTeX
|
|
mode. As shown in the example you can fix this by adding an extra line
|
|
inside the ~comment~ environment that is used to balance the dollar
|
|
expressions. If you are using AUCTeX with the font-latex library, a
|
|
much better solution is to add the ~comment~ environment to the
|
|
variable ~LaTeX-verbatim-environments~.
|
|
|
|
[fn:162] The HTML translator uses the same code that produces tables
|
|
during HTML export.
|
|
|
|
[fn:154] Note that ~org-indent-mode~ also sets the ~wrap-prefix~
|
|
property, such that ~visual-line-mode~ (or purely setting ~word-wrap~)
|
|
wraps long lines (including headlines) correctly indented.
|
|
|
|
[fn:155] See the variable ~org-indent-indentation-per-level~.
|
|
|
|
[fn:156] Turning on ~org-indent-mode~ sets ~org-hide-leading-stars~ to
|
|
~t~ and ~org-adapt-indentation~ to ~nil~.
|
|
|
|
[fn:157] See also the variable ~org-adapt-indentation~.
|
|
|
|
[fn:158] When you need to specify a level for a property search or
|
|
refile targets, ~LEVEL=2~ will correspond to 3 stars, etc.
|
|
|
|
[fn:159] The {{{file(org-R.el)}}} package has been replaced by the
|
|
Org mode functionality described in [[Working with source code]] and is
|
|
now obsolete.
|
|
|
|
[fn:160] By default this works only for LaTeX, HTML, and Texinfo.
|
|
Configure the variable ~orgtbl-radio-tables~ to install templates for
|
|
other modes.
|
|
|
|
[fn:163] Note that, when using ~org-odd-levels-only~, a level number
|
|
corresponds to order in the hierarchy, not to the number of stars.
|
|
|
|
[fn:164] If you can safely store the password in your Emacs setup, you
|
|
might also want to configure `org-mobile-encryption-password'. Please
|
|
read the docstring of that variable. Note that encryption will apply
|
|
only to the contents of the `.org' files. The file names themselves
|
|
will remain visible.
|
|
|
|
[fn:165] If you cannot use Dropbox, or if your version of MobileOrg
|
|
does not support it, you can use a webdav server. For more
|
|
information, check out the documentation of MobileOrg and also this
|
|
[[http://orgmode.org/worg/org-faq.html#mobileorg_webdav][FAQ entry]].
|
|
|
|
[fn:166] While creating the agendas, Org mode will force ID properties
|
|
on all referenced entries, so that these entries can be uniquely
|
|
identified if /MobileOrg/ flags them for further action. If you do not
|
|
want to get these properties in so many entries, you can set the
|
|
variable ~org-mobile-force-id-on-agenda-items~ to ~nil~. Org mode will
|
|
then rely on outline paths, in the hope that these will be unique
|
|
enough.
|
|
|
|
[fn:167] Checksums are stored automatically in the file
|
|
{{{file(checksums.dat)}}}.
|
|
|
|
[fn:168] The file {{{file(mobileorg.org)}}} will be empty after this
|
|
operation.
|
|
|
|
[fn:169] Note, however, that there is a subtle difference. The view
|
|
created automatically by {{{kbdspckey(M-x org-mobile-pull,RET)}}} is
|
|
guaranteed to search all files that have been addressed by the last
|
|
pull. This might include a file that is not currently in your list of
|
|
agenda files. If you later use {{{kbd(C-c a ?)}}} to regenerate the
|
|
view, only the current agenda files will be searched.
|
|
|
|
[fn:170] You can also get `a.', `A.', `a)' and `A)' by configuring
|
|
`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.
|
|
|
|
[fn:171] See also ~org-empty-line-terminates-plain-lists~.
|
|
|
|
[fn:172] You can define additional drawers on a per-file basis with a
|
|
line like ~#+DRAWERS: HIDDEN STATE~.
|
|
|
|
[fn:173] The corresponding in-buffer setting is: ~#+STARTUP: fninline~ or
|
|
~#+STARTUP: nofninline~.
|
|
|
|
[fn:174] The corresponding in-buffer options are ~#+STARTUP: fnadjust~ and
|
|
~#+STARTUP: nofnadjust~.
|
|
|
|
[fn:175] The file {{{file(constants.el)}}} can supply the values of constants in two
|
|
different unit systems, ~SI~ and ~cgs~. Which one is used depends on
|
|
the value of the variable ~constants-unit-system~. You can use the
|
|
~#+STARTUP:~ options ~constSI~ and ~constcgs~ to set this value for the
|
|
current buffer.
|
|
|
|
[fn:176] The library {{{file(org-id)}}} must first be loaded, either through
|
|
~org-customize~ by enabling ~id~ in ~org-modules~, or by adding
|
|
~(require 'org-id)~ in your {{{file(.emacs)}}}.
|
|
|
|
[fn:177] The variable ~org-startup-with-inline-images~ can be set
|
|
within a buffer with the ~#+STARTUP:~ keywords ~inlineimages~ and
|
|
~noinlineimages~.
|
|
|
|
[fn:178] Note that the ~LOGBOOK~ drawer is unfolded when pressing
|
|
{{{key(SPC)}}} in the agenda to show an entry---use
|
|
{{{kbdspckey(C-u,SPC)}}} to keep it folded here.
|
|
|
|
[fn:179] Please note the pitfalls of summing hierarchical data in a flat
|
|
list ([[Agenda column view]]).
|
|
|
|
[fn:180] If the value of that variable is not a list, but a single file
|
|
name, then the list of agenda files will be maintained in that external
|
|
file.
|
|
|
|
[fn:181] The variable ~org-anniversary~ used in the example
|
|
is just like ~diary-anniversary~, but the argument order is
|
|
always according to ISO and therefore independent of the value of
|
|
~calendar-date-style~.
|
|
|
|
[fn:182] Emacs 23 and Org mode 6.29 are required.
|
|
|
|
[fn:183] Emacs 23.1 can actually crash with ~org-indent-mode~.
|
|
|
|
[fn:184] Symbolic links in ~org-directory~ need to have the same name
|
|
as their targets.
|
|
|
|
|
|
# Local Variables:
|
|
# sentence-end-double-space: t
|
|
# End:
|