forked from mirrors/org-mode
2691 lines
86 KiB
Plaintext
2691 lines
86 KiB
Plaintext
\input texinfo @c -*- texinfo -*-
|
|
@c %**start of header
|
|
@setfilename orgguide.info
|
|
@settitle Org Mode Compact Guide
|
|
@documentencoding UTF-8
|
|
@documentlanguage en
|
|
@set txicodequoteundirected
|
|
@set txicodequotebacktick
|
|
@set MAINTAINERSITE @uref{https://orgmode.org,maintainers webpage}
|
|
@set MAINTAINER Carsten Dominik
|
|
@set MAINTAINEREMAIL @email{carsten at orgmode dot org}
|
|
@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
|
|
@c %**end of header
|
|
|
|
@copying
|
|
Copyright @copyright{} 2004--2019 Free Software Foundation, Inc.
|
|
|
|
@quotation
|
|
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.''
|
|
in the full Org manual, which is distributed together with this
|
|
compact guide.
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
|
|
modify this GNU manual.''
|
|
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* Org Guide: (orgguide). Abbreviated Org mode manual.
|
|
@end direntry
|
|
|
|
@finalout
|
|
@titlepage
|
|
@title Org Mode Compact Guide
|
|
@subtitle Release 9.3
|
|
@author The Org Mode Developers
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Org Mode Compact Guide
|
|
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Introduction:: Welcome!
|
|
* Document Structure:: A tree works like your brain.
|
|
* Tables:: Pure magic for quick formatting.
|
|
* Hyperlinks:: Notes in context.
|
|
* TODO Items:: Every tree branch can be a TODO item.
|
|
* Tags:: Tagging headlines and matching sets of tags.
|
|
* Properties:: Storing information about an entry.
|
|
* Dates and Times:: Making items useful for planning.
|
|
* Capture, Refile, Archive: Capture Refile Archive. The ins and outs for projects.
|
|
* Agenda Views:: Collecting information into views.
|
|
* Markup:: Compose beautiful documents.
|
|
* Exporting:: Sharing and publishing notes.
|
|
* Publishing:: Create a web site of linked Org files.
|
|
* Working with Source Code:: Export, evaluate, and tangle code blocks.
|
|
* Miscellaneous:: All the rest which did not fit elsewhere.
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
|
|
Document Structure
|
|
|
|
* Headlines:: How to typeset Org tree nodes.
|
|
* Visibility Cycling:: Show and hide, much simplified.
|
|
* Motion:: Jumping to other headlines.
|
|
* Structure Editing:: Changing sequence and level of headlines.
|
|
* Sparse Trees:: Matches embedded in context.
|
|
* Plain Lists:: Additional structure within an entry.
|
|
|
|
TODO Items
|
|
|
|
* TODO Basics:: Marking and displaying TODO entries.
|
|
* Multi-state Workflow:: More than just on/off.
|
|
* Progress Logging:: Dates and notes for progress.
|
|
* Priorities:: Some things are more important than others.
|
|
* Breaking Down Tasks:: Splitting a task into manageable pieces.
|
|
* Checkboxes:: Tick-off lists.
|
|
|
|
Dates and Times
|
|
|
|
* Timestamps:: Assigning a time to a tree entry.
|
|
* Creating Timestamps:: Commands that insert timestamps.
|
|
* Deadlines and Scheduling:: Planning your work.
|
|
* Clocking Work Time:: Tracking how long you spent on a task.
|
|
|
|
Capture, Refile, Archive
|
|
|
|
* Capture:: Capturing new stuff.
|
|
* Refile and Copy:: Moving/copying a tree from one place to another.
|
|
* Archiving:: What to do with finished products.
|
|
|
|
Agenda Views
|
|
|
|
* Agenda Files:: Files being searched for agenda information.
|
|
* Agenda Dispatcher:: Keyboard access to agenda views.
|
|
* Built-in Agenda Views:: What is available out of the box?
|
|
* Global TODO List:: All unfinished action items.
|
|
* Matching Tags and Properties:: Structured information with fine-tuned search.
|
|
* Search View:: Find entries by searching for text.
|
|
* Agenda Commands:: Remote editing of Org trees.
|
|
* Custom Agenda Views:: Defining special searches and views.
|
|
|
|
Markup
|
|
|
|
* Paragraphs:: The basic unit of text.
|
|
* Emphasis and Monospace:: Bold, italic, etc.
|
|
* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents.
|
|
* Literal examples:: Source code examples with special formatting.
|
|
* Images:: Display an image.
|
|
* Creating Footnotes:: Edit and read footnotes.
|
|
|
|
Exporting
|
|
|
|
* The Export Dispatcher:: The main interface.
|
|
* Export Settings:: Common export settings.
|
|
* Table of Contents:: The if and where of the table of contents.
|
|
* Include Files:: Include additional files into a document.
|
|
* Comment Lines:: What will not be exported.
|
|
* ASCII/UTF-8 Export:: Exporting to flat files with encoding.
|
|
* HTML Export:: Exporting to HTML.
|
|
* @LaTeX{} Export:: Exporting to @LaTeX{} and processing to PDF.
|
|
* iCalendar Export:: Exporting to iCalendar.
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
Org is a mode for keeping notes, maintaining TODO lists, and doing
|
|
project planning with a fast and effective plain-text system. It is
|
|
also an authoring and publishing system, and it supports working with
|
|
source code for literal programming and reproducible research.
|
|
|
|
This document is a much compressed derivative of the @ref{Top,comprehensive Org
|
|
mode manual,,org,}. It contains all basic features and commands, along with
|
|
important hints for customization. It is intended for beginners who
|
|
would shy back from a 200 pages manual because of sheer size.
|
|
|
|
@anchor{Installation}
|
|
@heading Installation
|
|
|
|
@quotation Important
|
|
If you are using a version of Org that is part of the Emacs
|
|
distribution, please skip this section and go directly to @ref{Activation}.
|
|
|
|
@end quotation
|
|
|
|
If you have downloaded Org from the web, either as a distribution
|
|
@samp{.zip} or @samp{.tar} file, or as a Git archive, it is best to run it
|
|
directly from the distribution directory. You need to add the @samp{lisp/}
|
|
subdirectories to the Emacs load path. To do this, add the following
|
|
line to your Emacs init file:
|
|
|
|
@example
|
|
(add-to-list 'load-path "~/path/to/orgdir/lisp")
|
|
(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
|
|
@end example
|
|
|
|
|
|
@noindent
|
|
If you have been using git or a tar ball to get Org, you need to run
|
|
the following command to generate autoload information.
|
|
|
|
@example
|
|
make autoloads
|
|
@end example
|
|
|
|
@anchor{Activation}
|
|
@heading Activation
|
|
|
|
Add the following lines to your Emacs init file. The last four lines
|
|
define @emph{global} keys for some commands---please choose suitable keys
|
|
yourself.
|
|
|
|
@lisp
|
|
;; The following lines are always needed. Choose your own keys.
|
|
(global-set-key (kbd "C-l") 'org-store-link)
|
|
(global-set-key (kbd "C-a") 'org-agenda)
|
|
(global-set-key (kbd "C-c") 'org-capture)
|
|
(global-set-key (kbd "C-b") 'org-switchb)
|
|
@end lisp
|
|
|
|
Files with extension @samp{.org} will be put into Org mode automatically.
|
|
|
|
@anchor{Feedback}
|
|
@heading Feedback
|
|
|
|
If you find problems with Org, or if you have questions, remarks, or
|
|
ideas about it, please mail to the Org mailing list
|
|
@email{emacs-orgmode@@gnu.org}. For information on how to submit bug
|
|
reports, see the main manual.
|
|
|
|
@node Document Structure
|
|
@chapter Document Structure
|
|
|
|
Org is an outliner. Outlines allow a document to be organized in
|
|
a hierarchical structure, which, least for me, is the best
|
|
representation of notes and thoughts. An overview of this structure
|
|
is achieved by folding, i.e., 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 and hide functionalities into a single command,
|
|
@code{org-cycle}, which is bound to the @kbd{@key{TAB}} key.
|
|
|
|
@menu
|
|
* Headlines:: How to typeset Org tree nodes.
|
|
* Visibility Cycling:: Show and hide, much simplified.
|
|
* Motion:: Jumping to other headlines.
|
|
* Structure Editing:: Changing sequence and level of headlines.
|
|
* Sparse Trees:: Matches embedded in context.
|
|
* Plain Lists:: Additional structure within an entry.
|
|
@end menu
|
|
|
|
@node Headlines
|
|
@section Headlines
|
|
|
|
Headlines define the structure of an outline tree. The headlines in
|
|
Org start with one or more stars, on the left margin@footnote{See the variable @code{org-special-ctrl-a/e} to configure special
|
|
behavior of @kbd{C-a} and @kbd{C-e} in headlines.}. For
|
|
example:
|
|
|
|
@example
|
|
* Top level headline
|
|
** Second level
|
|
*** Third level
|
|
some text
|
|
*** Third level
|
|
more text
|
|
* Another top level headline
|
|
@end example
|
|
|
|
Note that a headline named after @code{org-footnote-section}, which
|
|
defaults to @samp{Footnotes}, is considered as special. A subtree with
|
|
this headline will be silently ignored by exporting functions.
|
|
|
|
Some people find the many stars too noisy and would prefer an outline
|
|
that has whitespace followed by a single star as headline starters.
|
|
See @ref{Miscellaneous} for a setup to realize this.
|
|
|
|
@node Visibility Cycling
|
|
@section Visibility Cycling
|
|
|
|
Outlines make it possible to hide parts of the text in the buffer.
|
|
Org uses just two commands, bound to @kbd{@key{TAB}} and
|
|
@{@{@{kbd@{S-TAB)@}@}@} to change the visibility in the buffer.
|
|
|
|
@table @asis
|
|
@item @kbd{@key{TAB}}
|
|
@emph{Subtree cycling}: Rotate current subtree among the states
|
|
|
|
@example
|
|
,-> FOLDED -> CHILDREN -> SUBTREE --.
|
|
'-----------------------------------'
|
|
@end example
|
|
|
|
|
|
When called with a prefix argument (@kbd{C-u @key{TAB}}), or with the
|
|
Shift key, global cycling is invoked.
|
|
|
|
@item @kbd{S-@key{TAB}}
|
|
@itemx @kbd{C-u @key{TAB}}
|
|
@emph{Global cycling}: Rotate the entire buffer among the states
|
|
|
|
@example
|
|
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
|
|
'--------------------------------------'
|
|
@end example
|
|
|
|
@item @kbd{C-u C-u C-u @key{TAB}}
|
|
Show all, including drawers.
|
|
@end table
|
|
|
|
When Emacs first visits an Org file, the global state is set to
|
|
OVERVIEW, i.e., only the top level headlines are visible. This can be
|
|
configured through the variable @code{org-startup-folded}, or on a per-file
|
|
basis by adding a @samp{STARTUP} keyword to @samp{overview}, @samp{content}, or
|
|
@samp{showall}, like this:
|
|
|
|
@example
|
|
#+STARTUP: content
|
|
@end example
|
|
|
|
@node Motion
|
|
@section Motion
|
|
|
|
The following commands jump to other headlines in the buffer.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-n}
|
|
Next heading.
|
|
|
|
@item @kbd{C-c C-p}
|
|
Previous heading.
|
|
|
|
@item @kbd{C-c C-f}
|
|
Next heading same level.
|
|
|
|
@item @kbd{C-c C-b}
|
|
Previous heading same level.
|
|
|
|
@item @kbd{C-c C-u}
|
|
Backward to higher level heading.
|
|
@end table
|
|
|
|
@node Structure Editing
|
|
@section Structure Editing
|
|
|
|
@table @asis
|
|
@item @kbd{M-@key{RET}}
|
|
Insert new heading with same level as current. If point is in
|
|
a plain list item, a new item is created (see @ref{Plain Lists}). When
|
|
this command is used in the middle of a line, the line is split and
|
|
the rest of the line becomes the new headline@footnote{If you do not want the line to be split, customize the variable
|
|
@code{org-M-RET-may-split-line}.}.
|
|
|
|
@item @kbd{M-S-@key{RET}}
|
|
Insert new TODO entry with same level as current heading.
|
|
|
|
@item @kbd{@key{TAB}} in new
|
|
@itemx empty entry
|
|
In a new entry with no text yet, @kbd{@key{TAB}} cycles through
|
|
reasonable levels.
|
|
|
|
@item @kbd{M-@key{LEFT}}
|
|
@itemx @kbd{M-@key{RIGHT}}
|
|
Promote or demote current heading by one level.
|
|
|
|
@item @kbd{M-@key{UP}}
|
|
@itemx @kbd{M-@key{DOWN}}
|
|
Move subtree up or down, i.e., swap with previous or next subtree of
|
|
same level.
|
|
|
|
@item @kbd{C-c C-w}
|
|
Refile entry or region to a different location. See @ref{Refile and Copy}.
|
|
|
|
@item @kbd{C-x n s}
|
|
@itemx @kbd{C-x n w}
|
|
Narrow buffer to current subtree and widen it again.
|
|
@end table
|
|
|
|
When there is an active region (Transient Mark mode), promotion and
|
|
demotion work on all headlines in the region.
|
|
|
|
@node Sparse Trees
|
|
@section Sparse Trees
|
|
|
|
An important feature of Org mode is the ability to construct @emph{sparse
|
|
trees} for selected information in an outline tree, so that the entire
|
|
document is folded as much as possible, but the selected information
|
|
is made visible along with the headline structure above it@footnote{See also the variable @code{org-show-context-detail} to decide how
|
|
much context is shown around each match.}.
|
|
Just try it out and you will see immediately how it works.
|
|
|
|
Org mode contains several commands creating such trees, all these
|
|
commands can be accessed through a dispatcher:
|
|
|
|
@table @asis
|
|
@item @kbd{C-c /}
|
|
This prompts for an extra key to select a sparse-tree creating
|
|
command.
|
|
|
|
@item @kbd{C-c / r}
|
|
Occur. Prompts for a regexp and shows a sparse tree with all
|
|
matches. Each match is also highlighted; the highlights disappear
|
|
by pressing @kbd{C-c C-c}.
|
|
|
|
The other sparse tree commands select headings based on TODO
|
|
keywords, tags, or properties and will be discussed later in this
|
|
manual.
|
|
@end table
|
|
|
|
@node Plain Lists
|
|
@section Plain 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 @ref{Checkboxes}). Org supports editing such lists, and
|
|
every exporter (see @ref{Exporting}) can parse and format them.
|
|
|
|
Org knows ordered lists, unordered lists, and description lists.
|
|
|
|
@itemize
|
|
@item
|
|
@emph{Unordered} list items start with @samp{-}, @samp{+}, or @samp{*} as bullets.
|
|
|
|
@item
|
|
@emph{Ordered} list items start with @samp{1.}, or @samp{1)}.
|
|
|
|
@item
|
|
@emph{Description} list use @samp{::} to separate the @emph{term} from the
|
|
description.
|
|
@end itemize
|
|
|
|
Items belonging to the same list must have the same indentation on the
|
|
first line. An item ends before the next line that is indented like
|
|
its bullet/number, or less. A list ends when all items are closed, or
|
|
before two blank lines. An example:
|
|
|
|
@example
|
|
* 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.
|
|
Important actors in this film are:
|
|
- Elijah Wood :: He plays Frodo
|
|
- Sean Astin :: He plays Sam, Frodo's friend.
|
|
@end example
|
|
|
|
The following commands act on items when point is in the first line of
|
|
an item (the line with the bullet or number).
|
|
|
|
@table @asis
|
|
@item @kbd{@key{TAB}}
|
|
Items can be folded just like headline levels.
|
|
|
|
@item @kbd{M-@key{RET}}
|
|
Insert new item at current level. With a prefix argument, force
|
|
a new heading (see @ref{Structure Editing}).
|
|
|
|
@item @kbd{M-S-@key{RET}}
|
|
Insert a new item with a checkbox (see @ref{Checkboxes}).
|
|
|
|
@item @kbd{M-S-@key{UP}}
|
|
@itemx @kbd{M-S-@key{DOWN}}
|
|
Move the item including subitems up/down (swap with previous/next
|
|
item of same indentation). If the list is ordered, renumbering is
|
|
automatic.
|
|
|
|
@item @kbd{M-@key{LEFT}}
|
|
@itemx @kbd{M-@key{RIGHT}}
|
|
Decrease/increase the indentation of an item, leaving children
|
|
alone.
|
|
|
|
@item @kbd{M-S-@key{LEFT}}
|
|
@itemx @kbd{M-S-@key{RIGHT}}
|
|
Decrease/increase the indentation of the item, including subitems.
|
|
|
|
@item @kbd{C-c C-c}
|
|
If there is a checkbox (see @ref{Checkboxes}) in the item line, toggle
|
|
the state of the checkbox. Also verify bullets and indentation
|
|
consistency in the whole list.
|
|
|
|
@item @kbd{C-c -}
|
|
Cycle the entire list level through the different itemize/enumerate
|
|
bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}).
|
|
@end table
|
|
|
|
@node Tables
|
|
@chapter Tables
|
|
|
|
Org comes with a fast and intuitive table editor. Spreadsheet-like
|
|
calculations are supported in connection with the Emacs Calc package
|
|
(see @ref{Top,GNU Emacs Calculator Manual,,calc,}).
|
|
|
|
Org makes it easy to format tables in plain ASCII@. Any line with @samp{|}
|
|
as the first non-whitespace character is considered part of a table.
|
|
@samp{|} is also the column separator. A table might look like this:
|
|
|
|
@example
|
|
| Name | Phone | Age |
|
|
|-------+-------+-----|
|
|
| Peter | 1234 | 17 |
|
|
| Anna | 4321 | 25 |
|
|
@end example
|
|
|
|
A table is re-aligned automatically each time you press @kbd{@key{TAB}}
|
|
or @kbd{@key{RET}} or @kbd{C-c C-c} inside the table.
|
|
@kbd{@key{TAB}} also moves to the next field (@kbd{@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
|
|
|
|
@example
|
|
|Name|Phone|Age|
|
|
|-
|
|
@end example
|
|
|
|
|
|
@noindent
|
|
and then press @kbd{@key{TAB}} to align the table and start filling in
|
|
fields. Even faster would be to type @samp{|Name|Phone|Age} followed by
|
|
@kbd{C-c @key{RET}}.
|
|
|
|
When typing text into a field, Org treats @kbd{DEL},
|
|
@kbd{Backspace}, and all character keys in a special way, so that
|
|
inserting and deleting avoids shifting other fields. Also, when
|
|
typing @emph{immediately after point was moved into a new field with
|
|
@kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the field is
|
|
automatically made blank.
|
|
|
|
@anchor{Creation and conversion}
|
|
@heading Creation and conversion
|
|
|
|
@table @asis
|
|
@item @kbd{C-c |}
|
|
Convert the active region to table. If every line contains at least
|
|
one @kbd{@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.
|
|
|
|
If there is no active region, this command creates an empty Org
|
|
table. But it is easier just to start typing, like @kbd{| N a m e | P h o n e | A g e @key{RET} | - @key{TAB}}.
|
|
@end table
|
|
|
|
@anchor{Re-aligning and field motion}
|
|
@heading Re-aligning and field motion
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-c}
|
|
Re-align the table without moving point.
|
|
|
|
@item @kbd{@key{TAB}}
|
|
Re-align the table, move to the next field. Creates a new row if
|
|
necessary.
|
|
|
|
@item @kbd{S-@key{TAB}}
|
|
Re-align, move to previous field.
|
|
|
|
@item @kbd{@key{RET}}
|
|
Re-align the table and move down to next row. Creates a new row if
|
|
necessary.
|
|
|
|
@item @kbd{S-@key{UP}}
|
|
@itemx @kbd{S-@key{DOWN}}
|
|
@itemx @kbd{S-@key{LEFT}}
|
|
@itemx @kbd{S-@key{RIGHT}}
|
|
Move a cell up, down, left, and right by swapping with adjacent
|
|
cell.
|
|
@end table
|
|
|
|
@anchor{Column and row editing}
|
|
@heading Column and row editing
|
|
|
|
@table @asis
|
|
@item @kbd{M-@key{LEFT}}, @kbd{M-@key{RIGHT}}
|
|
Move the current column left/right.
|
|
|
|
@item @kbd{M-S-@key{LEFT}}
|
|
Kill the current column.
|
|
|
|
@item @kbd{M-S-@key{RIGHT}}
|
|
Insert a new column to the left of point position.
|
|
|
|
@item @kbd{M-@key{UP}}, @kbd{M-@key{DOWN}}
|
|
Move the current row up/down.
|
|
|
|
@item @kbd{M-S-@key{UP}}
|
|
Kill the current row or horizontal line.
|
|
|
|
@item @kbd{M-S-@key{DOWN}}
|
|
Insert a new row above the current row. With a prefix argument, the
|
|
line is created below the current one.
|
|
|
|
@item @kbd{C-c -}
|
|
Insert a horizontal line below current row. With a prefix argument,
|
|
the line is created above the current line.
|
|
|
|
@item @kbd{C-c @key{RET}}
|
|
Insert a horizontal line below current row, and move the point into
|
|
the row below that line.
|
|
|
|
@item @kbd{C-c ^}
|
|
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.
|
|
@end table
|
|
|
|
@node Hyperlinks
|
|
@chapter Hyperlinks
|
|
|
|
Like HTML, Org provides links inside a file, external links to other
|
|
files, Usenet articles, emails, and much more.
|
|
|
|
Org recognizes plain URIs, possibly wrapped within angle brackets, and
|
|
activate them as clickable links. The general link format, however,
|
|
looks like this:
|
|
|
|
@example
|
|
[[LINK][DESCRIPTION]]
|
|
@end example
|
|
|
|
|
|
@noindent
|
|
or alternatively
|
|
|
|
@example
|
|
[[LINK]]
|
|
@end example
|
|
|
|
|
|
Once a link in the buffer is complete, with all brackets present, Org
|
|
changes the display so that @samp{DESCRIPTION} is displayed instead of
|
|
@samp{[[LINK][DESCRIPTION]]} and @samp{LINK} is displayed instead of @samp{[[LINK]]}.
|
|
To edit the invisible @var{LINK} part, use @kbd{C-c C-l}
|
|
with the point on the link.
|
|
|
|
@anchor{Internal links}
|
|
@heading Internal links
|
|
|
|
If the link does not look like a URL, it is considered to be internal
|
|
in the current file. The most important case is a link like
|
|
@samp{[[#my-custom-id]]} which links to the entry with the @samp{CUSTOM_ID} property
|
|
@samp{my-custom-id}.
|
|
|
|
Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]} lead
|
|
to a text search in the current file for the corresponding target,
|
|
which looks like @samp{<<My Target>>}.
|
|
|
|
@anchor{External Links}
|
|
@heading External 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. Here are some examples:
|
|
|
|
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
|
@item @samp{http://www.astro.uva.nl/=dominik}
|
|
@tab on the web
|
|
@item @samp{file:/home/dominik/images/jupiter.jpg}
|
|
@tab file, absolute path
|
|
@item @samp{/home/dominik/images/jupiter.jpg}
|
|
@tab same as above
|
|
@item @samp{file:papers/last.pdf}
|
|
@tab file, relative path
|
|
@item @samp{./papers/last.pdf}
|
|
@tab same as above
|
|
@item @samp{file:projects.org}
|
|
@tab another Org file
|
|
@item @samp{docview:papers/last.pdf::NNN}
|
|
@tab open in DocView mode at page @var{NNN}
|
|
@item @samp{id:B7423F4D-2E8A-471B-8810-C40F074717E9}
|
|
@tab link to heading by ID
|
|
@item @samp{news:comp.emacs}
|
|
@tab Usenet link
|
|
@item @samp{mailto:adent@@galaxy.net}
|
|
@tab mail link
|
|
@item @samp{mhe:folder#id}
|
|
@tab MH-E message link
|
|
@item @samp{rmail:folder#id}
|
|
@tab Rmail message link
|
|
@item @samp{gnus:group#id}
|
|
@tab Gnus article link
|
|
@item @samp{bbdb:R.*Stallman}
|
|
@tab BBDB link (with regexp)
|
|
@item @samp{irc:/irc.com/#emacs/bob}
|
|
@tab IRC link
|
|
@item @samp{info:org#Hyperlinks}
|
|
@tab Info node link
|
|
@end multitable
|
|
|
|
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. Here are a few
|
|
examples,, together with an explanation:
|
|
|
|
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
|
@item @samp{file:~/code/main.c::255}
|
|
@tab Find line 255
|
|
@item @samp{file:~/xx.org::My Target}
|
|
@tab Find @samp{<<My Target>>}
|
|
@item @samp{[[file:~/xx.org::#my-custom-id]]}
|
|
@tab Find entry with a custom ID
|
|
@end multitable
|
|
|
|
@anchor{Handling Links}
|
|
@heading Handling Links
|
|
|
|
Org provides methods to create a link in the correct syntax, to insert
|
|
it into an Org file, and to follow the link.
|
|
|
|
The main function is @code{org-store-link}, called with @kbd{M-x org-store-link}. Because of its importance, we suggest to bind it
|
|
to a widely available key (see @ref{Activation}). It stores a link to the
|
|
current location. The link is stored for later insertion into an Org
|
|
buffer---see below.
|
|
|
|
From an Org buffer, the following commands create, navigate or, more
|
|
generally, act on links.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-l}
|
|
Insert a link. This prompts for a link to be inserted into the
|
|
buffer. You can just type a link, or use history keys @kbd{@key{UP}}
|
|
and @kbd{@key{DOWN}} to access stored links. You will be prompted
|
|
for the description part of the link.
|
|
|
|
When called with a @kbd{C-u} prefix argument, file name
|
|
completion is used to link to a file.
|
|
|
|
@item @kbd{C-c C-l} (with point on existing link)
|
|
When point is on an existing link, @kbd{C-c C-l} allows you to
|
|
edit the link and description parts of the link.
|
|
|
|
@item @kbd{C-c C-o}
|
|
Open link at point.
|
|
|
|
@item @kbd{C-c &}
|
|
Jump back to a recorded position. A position is recorded by the
|
|
commands following internal links, and by @kbd{C-c %}. Using
|
|
this command several times in direct succession moves through a ring
|
|
of previously recorded positions.
|
|
@end table
|
|
|
|
@node TODO Items
|
|
@chapter TODO Items
|
|
|
|
Org mode does not require TODO lists to live in separate documents.
|
|
Instead, TODO items are part of a 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 TODO items remain in the context from which they
|
|
emerged.
|
|
|
|
Org mode provides methods to give you an overview of all the things
|
|
that you have to do, collected from many files.
|
|
|
|
@menu
|
|
* TODO Basics:: Marking and displaying TODO entries.
|
|
* Multi-state Workflow:: More than just on/off.
|
|
* Progress Logging:: Dates and notes for progress.
|
|
* Priorities:: Some things are more important than others.
|
|
* Breaking Down Tasks:: Splitting a task into manageable pieces.
|
|
* Checkboxes:: Tick-off lists.
|
|
@end menu
|
|
|
|
@node TODO Basics
|
|
@section Basic TODO Functionality
|
|
|
|
Any headline becomes a TODO item when it starts with the word @samp{TODO},
|
|
for example:
|
|
|
|
@example
|
|
*** TODO Write letter to Sam Fortune
|
|
@end example
|
|
|
|
|
|
The most important commands to work with TODO entries are:
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-t}
|
|
Rotate the TODO state of the current item among
|
|
|
|
@example
|
|
,-> (unmarked) -> TODO -> DONE --.
|
|
'--------------------------------'
|
|
@end example
|
|
|
|
|
|
The same rotation can also be done ``remotely'' from the agenda buffer
|
|
with the @kbd{t} command key (see @ref{Agenda Commands}).
|
|
|
|
@item @kbd{S-@key{RIGHT}}
|
|
@itemx @kbd{S-@key{LEFT}}
|
|
Select the following/preceding TODO state, similar to cycling.
|
|
|
|
@item @kbd{C-c / t}
|
|
View TODO items in a @emph{sparse tree} (see @ref{Sparse Trees}). Folds the
|
|
entire buffer, but shows all TODO items---with not-DONE state---and
|
|
the headings hierarchy above them.
|
|
|
|
@item @kbd{M-x org-agenda t}
|
|
Show the global TODO list. Collects the TODO items (with not-DONE
|
|
states) from all agenda files (see @ref{Agenda Views}) into a single
|
|
buffer. See @ref{Global TODO List}, for more information.
|
|
|
|
@item @kbd{S-M-@key{RET}}
|
|
Insert a new TODO entry below the current one.
|
|
@end table
|
|
|
|
Changing a TODO state can also trigger tag changes. See the docstring
|
|
of the option @code{org-todo-state-tags-triggers} for details.
|
|
|
|
@node Multi-state Workflow
|
|
@section Multi-state Workflow
|
|
|
|
You can use TODO keywords to indicate @@emph@{sequential@} working progress
|
|
states:
|
|
|
|
@lisp
|
|
(setq org-todo-keywords
|
|
'((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
|
|
@end lisp
|
|
|
|
@noindent
|
|
The vertical bar separates the @samp{TODO} keywords (states that @emph{need
|
|
action}) from the @samp{DONE} states (which need @emph{no further action}). If
|
|
you do not provide the separator bar, the last state is used as the
|
|
@samp{DONE} state. With this setup, the command @kbd{C-c C-t} cycles
|
|
an entry from @samp{TODO} to @samp{FEEDBACK}, then to @samp{VERIFY}, and finally to
|
|
@samp{DONE} and @samp{DELEGATED}.
|
|
|
|
Sometimes you may want to use different sets of TODO keywords in
|
|
parallel. For example, you may want to have the basic @samp{TODO=/=DONE},
|
|
but also a workflow for bug fixing. Your setup would then look like
|
|
this:
|
|
|
|
@lisp
|
|
(setq org-todo-keywords
|
|
'((sequence "TODO(t)" "|" "DONE(d)")
|
|
(sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")))
|
|
@end lisp
|
|
|
|
@noindent
|
|
The keywords should all be different, this helps Org mode to keep
|
|
track of which subsequence should be used for a given entry. The
|
|
example also shows how to define keys for fast access of a particular
|
|
state, by adding a letter in parenthesis after each keyword---you will
|
|
be prompted for the key after @kbd{C-c C-t}.
|
|
|
|
To define TODO keywords that are valid only in a single file, use the
|
|
following text anywhere in the file.
|
|
|
|
@example
|
|
#+TODO: TODO(t) | DONE(d)
|
|
#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f)
|
|
#+TODO: | CANCELED(c)
|
|
@end example
|
|
|
|
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.
|
|
|
|
@node Progress Logging
|
|
@section Progress Logging
|
|
|
|
To record a timestamp and a note when changing a TODO state, call the
|
|
command @code{org-todo} with a prefix argument.
|
|
|
|
@table @asis
|
|
@item @kbd{C-u C-c C-t}
|
|
Prompt for a note and record a the time of the TODO state change.
|
|
@end table
|
|
|
|
Org mode can also automatically record a timestamp and optionally 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 @ref{Clocking Work Time}.
|
|
|
|
@anchor{Closing items}
|
|
@subheading Closing items
|
|
|
|
The most basic logging is to keep track of @emph{when} a certain TODO item
|
|
was marked as done. This can be achieved with@footnote{The corresponding in-buffer setting is @samp{#+STARTUP: logdone}.}
|
|
|
|
@lisp
|
|
(setq org-log-done 'time)
|
|
@end lisp
|
|
|
|
@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]} is inserted just
|
|
after the headline.
|
|
|
|
If you want to record a note along with the timestamp, use@footnote{The corresponding in-buffer setting is @samp{#+STARTUP:
|
|
logenotedone}.}
|
|
|
|
@lisp
|
|
(setq org-log-done 'note)
|
|
@end lisp
|
|
|
|
@noindent
|
|
You are then be prompted for a note, and that note is stored below the
|
|
entry with a @samp{Closing Note} heading.
|
|
|
|
@anchor{Tracking TODO state changes}
|
|
@subheading Tracking TODO state changes
|
|
|
|
You might want to keep track of TODO state changes. You can either
|
|
record just a timestamp, or a time-stamped note for a change. These
|
|
records are inserted after the headline as an itemized list. When
|
|
taking a lot of notes, you might want to get the notes out of the way
|
|
into a drawer. Customize the variable @code{org-log-into-drawer} to get
|
|
this behavior.
|
|
|
|
For state logging, Org mode expects configuration on a per-keyword
|
|
basis. This is achieved by adding special markers @samp{!} (for
|
|
a timestamp) and @samp{@@} (for a note) in parentheses after each keyword.
|
|
For example:
|
|
|
|
@example
|
|
#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
|
|
@end example
|
|
|
|
|
|
@noindent
|
|
defines TODO keywords and fast access keys, and also request that
|
|
a time is recorded when the entry is set to @samp{DONE}, and that a note is
|
|
recorded when switching to @samp{WAIT} or @samp{CANCELED}. The same syntax
|
|
works also when setting @code{org-todo-keywords}.
|
|
|
|
@node Priorities
|
|
@section 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 @emph{priority cookie} into the headline of a TODO item,
|
|
like this
|
|
|
|
@example
|
|
*** TODO [#A] Write letter to Sam Fortune
|
|
@end example
|
|
|
|
|
|
Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. @samp{A} is the
|
|
highest, @samp{B} the default if none is given. Priorities make
|
|
a difference only in the agenda.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c ,}
|
|
Set the priority of the current headline. Press @kbd{A},
|
|
@kbd{B} or @kbd{C} to select a priority, or @kbd{@key{SPC}}
|
|
to remove the cookie.
|
|
|
|
@item @kbd{S-@key{UP}} (@code{org-priority-up})
|
|
@itemx @kbd{S-@key{DOWN}} (@code{org-priority-down})
|
|
Increase/decrease the priority of the current headline.
|
|
@end table
|
|
|
|
@node Breaking Down Tasks
|
|
@section Breaking Tasks Down into Subtasks
|
|
|
|
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. To keep an
|
|
overview of the fraction of subtasks that have already been marked
|
|
as done, insert either @samp{[/]} or @samp{[%]} anywhere in the headline. These
|
|
cookies are updated each time the TODO status of a child changes, or
|
|
when pressing @kbd{C-c C-c} on the cookie. For example:
|
|
|
|
@example
|
|
* Organize Party [33%]
|
|
** TODO Call people [1/2]
|
|
*** TODO Peter
|
|
*** DONE Sarah
|
|
** TODO Buy food
|
|
** DONE Talk to neighbor
|
|
@end example
|
|
|
|
@node Checkboxes
|
|
@section Checkboxes
|
|
|
|
Every item in a plain list (see @ref{Plain Lists}) can be made into
|
|
a checkbox by starting it with the string @samp{[ ]}. Checkboxes are not
|
|
included into the global TODO list, so they are often great to split
|
|
a task into a number of simple steps.
|
|
|
|
Here is an example of a checkbox list.
|
|
|
|
@example
|
|
* TODO Organize party [2/4]
|
|
- [-] call people [1/2]
|
|
- [ ] Peter
|
|
- [X] Sarah
|
|
- [X] order food
|
|
@end example
|
|
|
|
Checkboxes work hierarchically, so if a checkbox item has children
|
|
that are checkboxes, toggling one of the children checkboxes makes the
|
|
parent checkbox reflect if none, some, or all of the children are
|
|
checked.
|
|
|
|
The following commands work with checkboxes:
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-c}
|
|
Toggle checkbox status or---with prefix argument---checkbox presence
|
|
at point.
|
|
|
|
@item @kbd{M-S-@key{RET}}
|
|
Insert a new item with a checkbox. This works only if point is
|
|
already in a plain list item (see @ref{Plain Lists}).
|
|
@end table
|
|
|
|
@node Tags
|
|
@chapter Tags
|
|
|
|
An excellent way to implement labels and contexts for
|
|
cross-correlating information is to assign @emph{tags} to headlines. Org
|
|
mode has extensive support for tags.
|
|
|
|
Every headline can contain a list of tags; they occur at the end of
|
|
the headline. Tags are normal words containing letters, numbers, @samp{_},
|
|
and @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
|
|
@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. Tags
|
|
by default are in bold face with the same color as the headline.
|
|
|
|
@anchor{Tag inheritance}
|
|
@heading Tag inheritance
|
|
|
|
Tags make use of the hierarchical structure of outline trees. If
|
|
a heading has a certain tag, all subheadings inherit the tag as well.
|
|
For example, in the list
|
|
|
|
@example
|
|
* Meeting with the French group :work:
|
|
** Summary by Frank :boss:notes:
|
|
*** TODO Prepare slides for him :action:
|
|
@end example
|
|
|
|
@noindent
|
|
the final heading has 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@footnote{As with all these in-buffer settings, pressing @kbd{C-c C-c} activates any changes in the line.}:
|
|
|
|
@example
|
|
#+FILETAGS: :Peter:Boss:Secret:
|
|
@end example
|
|
|
|
@anchor{Setting tags}
|
|
@heading Setting tags
|
|
|
|
Tags can simply be typed into the buffer at the end of a headline.
|
|
After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
|
|
also a special command for inserting tags:
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-q}
|
|
Enter new tags for the current headline. Org mode either offers
|
|
completion or a special single-key interface for setting tags, see
|
|
below.
|
|
|
|
@item @kbd{C-c C-c}
|
|
When point is in a headline, this does the same as @kbd{C-c C-q}.
|
|
@end table
|
|
|
|
Org supports tag insertion based on a @emph{list of tags}. By default this
|
|
list is constructed dynamically, containing all tags currently used in
|
|
the buffer. You may also globally specify a hard list of tags with
|
|
the variable @code{org-tag-alist}. Finally you can set the default tags
|
|
for a given file using the @samp{TAGS} keyword, like
|
|
|
|
@example
|
|
#+TAGS: @@work @@home @@tennisclub
|
|
#+TAGS: laptop car pc sailboat
|
|
@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 @emph{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
|
|
@code{org-tag-alist} in your Emacs init 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:
|
|
|
|
@lisp
|
|
(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
|
|
@end lisp
|
|
|
|
If the tag is only relevant to the file you are working on, then you
|
|
can instead set the @samp{TAGS} keyword as:
|
|
|
|
@example
|
|
#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
|
|
@end example
|
|
|
|
@anchor{Tag groups}
|
|
@heading Tag groups
|
|
|
|
A tag can be defined as a @emph{group tag} for a set of other tags. The
|
|
group tag can be seen as the ``broader term'' for its set of tags.
|
|
|
|
You can set group tags by using brackets and inserting a colon between
|
|
the group tag and its related tags:
|
|
|
|
@example
|
|
#+TAGS: [ GTD : Control Persp ]
|
|
@end example
|
|
|
|
|
|
@noindent
|
|
or, if tags in the group should be mutually exclusive:
|
|
|
|
@example
|
|
#+TAGS: @{ Context : @@Home @@Work @}
|
|
@end example
|
|
|
|
|
|
When you search for a group tag, it return matches for all members in
|
|
the group and its subgroups. In an agenda view, filtering by a group
|
|
tag displays or hide headlines tagged with at least one of the members
|
|
of the group or any of its subgroups.
|
|
|
|
If you want to ignore group tags temporarily, toggle group tags
|
|
support with @code{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}.
|
|
|
|
@anchor{Tag searches}
|
|
@heading Tag searches
|
|
|
|
@table @asis
|
|
@item @kbd{C-c / m} or @kbd{C-c \}
|
|
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.
|
|
|
|
@item @kbd{M-x org-agenda m}
|
|
Create a global list of tag matches from all agenda files. See
|
|
@ref{Matching Tags and Properties}.
|
|
|
|
@item @kbd{M-x org-agenda M}
|
|
Create a global list of tag matches from all agenda files, but check
|
|
only TODO items and force checking subitems (see the option
|
|
@code{org-tags-match-list-sublevels}).
|
|
@end table
|
|
|
|
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 more detailed description
|
|
with many examples, see @ref{Matching Tags and Properties}.
|
|
|
|
@node Properties
|
|
@chapter Properties
|
|
|
|
Properties are key-value pairs associated with an entry. They live in
|
|
a special drawer with the name @samp{PROPERTIES}. Each property is
|
|
specified on a single line, with the key (surrounded by colons) first,
|
|
and the value after it:
|
|
|
|
@example
|
|
* CD collection
|
|
** Classic
|
|
*** Goldberg Variations
|
|
:PROPERTIES:
|
|
:Title: Goldberg Variations
|
|
:Composer: J.S. Bach
|
|
:Publisher: Deutsche Grammophon
|
|
:NDisks: 1
|
|
:END:
|
|
@end example
|
|
|
|
You may define the allowed values for a particular property @samp{Xyz} by
|
|
setting a property @samp{Xyz_ALL}. This special property is @emph{inherited},
|
|
so if you set it in a level 1 entry, it applies 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 pre-define publishers and the number of
|
|
disks in a box like this:
|
|
|
|
@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:
|
|
|
|
@example
|
|
#+PROPERTY: NDisks_ALL 1 2 3 4
|
|
@end example
|
|
|
|
|
|
The following commands help to work with properties:
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-x p}
|
|
Set a property. This prompts for a property name and a value.
|
|
|
|
@item @kbd{C-c C-c d}
|
|
Remove a property from the current entry.
|
|
@end table
|
|
|
|
To create sparse trees and special lists with selection based on
|
|
properties, the same commands are used as for tag searches (see
|
|
@ref{Tags}). The syntax for the search string is described in @ref{Matching Tags and Properties}.
|
|
|
|
@node Dates and Times
|
|
@chapter Dates and Times
|
|
|
|
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 @emph{timestamp} in Org mode.
|
|
|
|
@menu
|
|
* Timestamps:: Assigning a time to a tree entry.
|
|
* Creating Timestamps:: Commands that insert timestamps.
|
|
* Deadlines and Scheduling:: Planning your work.
|
|
* Clocking Work Time:: Tracking how long you spent on a task.
|
|
@end menu
|
|
|
|
@node Timestamps
|
|
@section Timestamps
|
|
|
|
A timestamp is a specification of a date---possibly with a time or
|
|
a range of times---in a special format, either @samp{<2003-09-16 Tue>} or
|
|
@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}.
|
|
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 [BROKEN LINK: *The Weekly/daily Agenda]). We distinguish:
|
|
|
|
@table @asis
|
|
@item Plain timestamp; Event; 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.
|
|
|
|
@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
|
|
|
|
@item Timestamp with repeater interval
|
|
A timestamp may contain a @emph{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 shows up in the agenda every Wednesday:
|
|
|
|
@example
|
|
* Pick up Sam at school
|
|
<2007-05-16 Wed 12:30 +1w>
|
|
@end example
|
|
|
|
@item Diary-style expression entries
|
|
@cindex diary style timestamps
|
|
@cindex sexp timestamps
|
|
For more complex date specifications, Org mode supports using the
|
|
special expression diary entries implemented in the Emacs Calendar
|
|
package. For example, with optional time:
|
|
|
|
@example
|
|
* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
|
|
<%%(diary-float t 4 2)>
|
|
@end example
|
|
|
|
@item Time/Date range
|
|
Two timestamps connected by @samp{--} denote a range.
|
|
|
|
@example
|
|
** Meeting in Amsterdam
|
|
<2004-08-23 Mon>--<2004-08-26 Thu>
|
|
@end example
|
|
|
|
@item 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 @emph{not} trigger an entry to show up in the agenda.
|
|
|
|
@example
|
|
* Gillian comes late for the fifth time
|
|
[2006-11-01 Wed]
|
|
@end example
|
|
@end table
|
|
|
|
@node Creating Timestamps
|
|
@section Creating Timestamps
|
|
|
|
For Org mode to recognize timestamps, they need to be in the specific
|
|
format. All commands listed below produce timestamps in the correct
|
|
format.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c .}
|
|
Prompt for a date and insert a corresponding timestamp. When point
|
|
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. With
|
|
a prefix argument, it also adds the current time.
|
|
|
|
@item @kbd{C-c !}
|
|
Like @kbd{C-c .}, but insert an inactive timestamp that does
|
|
not cause an agenda entry.
|
|
|
|
@item @kbd{S-@key{LEFT}}
|
|
@itemx @kbd{S-@key{RIGHT}}
|
|
Change date at point by one day.
|
|
|
|
@item @kbd{S-@key{UP}}
|
|
@itemx @kbd{S-@key{DOWN}}
|
|
On the beginning or enclosing bracket of a timestamp, change its
|
|
type. Within a timestamp, change the item under point. Point 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
|
|
also shifts the second, shifting the time block with constant
|
|
length. To change the length, modify the second time.
|
|
@end table
|
|
|
|
|
|
When Org mode prompts for a date/time, it accepts any string
|
|
containing some date and/or time information, and intelligently
|
|
interprets the string, deriving defaults for unspecified information
|
|
from the current date and time. You can also select a date in the
|
|
pop-up calendar. See the manual for more information on how exactly
|
|
the date/time prompt works.
|
|
|
|
@node Deadlines and Scheduling
|
|
@section Deadlines and Scheduling
|
|
|
|
A timestamp may be preceded by special keywords to facilitate
|
|
planning:
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-d}
|
|
Insert @samp{DEADLINE} keyword along with a time stamp, in the line
|
|
following the headline.
|
|
|
|
Meaning: the task---most likely a TODO item, though not
|
|
necessarily---is supposed to be finished on that date.
|
|
|
|
On the deadline date, the task is listed in the agenda. In
|
|
addition, the agenda for @emph{today} carries a warning about the
|
|
approaching or missed deadline, starting @code{org-deadline-warning-days}
|
|
before the due date, and continuing until the entry is marked as
|
|
done. An example:
|
|
|
|
@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
|
|
|
|
@item @kbd{C-c C-s}
|
|
Insert @samp{SCHEDULED} keyword along with a stamp, in the line following
|
|
the headline.
|
|
|
|
Meaning: you are planning to start working on that task on the given
|
|
date@footnote{This is quite different from what is normally understood by
|
|
@emph{scheduling a meeting}, which is done in Org by just inserting a time
|
|
stamp without keyword.}.
|
|
|
|
The headline is listed under the given date@footnote{It will still be listed on that date after it has been marked
|
|
as done. If you do not like this, set the variable
|
|
@code{org-agenda-skip-scheduled-if-done}.}. In addition,
|
|
a reminder that the scheduled date has passed is present in the
|
|
compilation for @emph{today}, until the entry is marked as done, i.e.,
|
|
the task is automatically forwarded until completed.
|
|
|
|
@example
|
|
*** TODO Call Trillian for a date on New Years Eve.
|
|
SCHEDULED: <2004-12-25 Sat>
|
|
@end example
|
|
@end table
|
|
|
|
Some tasks need to be repeated again and again. Org mode helps to
|
|
organize such tasks using a so-called repeater in a @samp{DEADLINE},
|
|
@samp{SCHEDULED}, or plain timestamps. In the following example:
|
|
|
|
@example
|
|
** TODO Pay the rent
|
|
DEADLINE: <2005-10-01 Sat +1m>
|
|
@end example
|
|
|
|
@noindent
|
|
the @samp{+1m} is a repeater; the intended interpretation is that the task
|
|
has a deadline on @samp{<2005-10-01>} and repeats itself every (one) month
|
|
starting from that time.
|
|
|
|
@node Clocking Work Time
|
|
@section Clocking Work Time
|
|
|
|
Org mode allows you to clock the time you spend on specific tasks in
|
|
a project.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-x C-i}
|
|
Start the clock on the current item (clock-in). This inserts the
|
|
@samp{CLOCK} keyword together with a timestamp. When called with
|
|
a @kbd{C-u} prefix argument, select the task from a list of
|
|
recently clocked tasks.
|
|
|
|
@item @kbd{C-c C-x C-o}
|
|
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}.
|
|
|
|
@item @kbd{C-c C-x C-e}
|
|
Update the effort estimate for the current clock task.
|
|
|
|
@item @kbd{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.
|
|
|
|
@item @kbd{C-c C-x C-j}
|
|
Jump to the headline of the currently clocked in task. With
|
|
a @kbd{C-u} prefix argument, select the target task from a list
|
|
of recently clocked tasks.
|
|
@end table
|
|
|
|
The @kbd{l} key may be used in the agenda (see [BROKEN LINK: *The Weekly/daily Agenda]) to show which tasks have been worked on or closed during
|
|
a day.
|
|
|
|
@node Capture Refile Archive
|
|
@chapter Capture, Refile, Archive
|
|
|
|
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 @emph{capture}. It also can
|
|
store files related to a task (@emph{attachments}) in a special directory.
|
|
Once in the system, tasks and projects need to be moved around.
|
|
Moving completed project trees to an archive file keeps the system
|
|
compact and fast.
|
|
|
|
@menu
|
|
* Capture:: Capturing new stuff.
|
|
* Refile and Copy:: Moving/copying a tree from one place to another.
|
|
* Archiving:: What to do with finished products.
|
|
@end menu
|
|
|
|
@node Capture
|
|
@section Capture
|
|
|
|
Capture lets you quickly store notes with little interruption of your
|
|
work flow. You can define templates for new entries and associate
|
|
them with different targets for storing notes.
|
|
|
|
@anchor{Setting up capture}
|
|
@subheading Setting up capture
|
|
|
|
The following customization sets a default target@footnote{Using capture templates, you get finer control over capture
|
|
locations. See @ref{Capture templates}.} file for notes.
|
|
|
|
@lisp
|
|
(setq org-default-notes-file (concat org-directory "/notes.org"))
|
|
@end lisp
|
|
|
|
You may also define a global key for capturing new material (see
|
|
@ref{Activation}).
|
|
|
|
@anchor{Using capture}
|
|
@subheading Using capture
|
|
|
|
@table @asis
|
|
@item @kbd{M-x org-capture}
|
|
Start a capture process, placing you into a narrowed indirect buffer
|
|
to edit.
|
|
|
|
@item @kbd{C-c C-c}
|
|
Once you have finished entering information into the capture buffer,
|
|
@kbd{C-c C-c} returns you to the window configuration before
|
|
the capture process, so that you can resume your work without
|
|
further distraction.
|
|
|
|
@item @kbd{C-c C-w}
|
|
Finalize the capture process by refiling the note to a different
|
|
place (see @ref{Refile and Copy}).
|
|
|
|
@item @kbd{C-c C-k}
|
|
Abort the capture process and return to the previous state.
|
|
@end table
|
|
|
|
@anchor{Capture templates}
|
|
@subheading Capture templates
|
|
|
|
You can use templates for different types of capture items, and for
|
|
different target locations. 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 @samp{~/org/gtd.org}. Also, a date tree
|
|
in the file @samp{journal.org} should capture journal entries. A possible
|
|
configuration would look like:
|
|
|
|
@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 lisp
|
|
|
|
If you then press @kbd{t} from the capture menu, Org will prepare
|
|
the template for you like this:
|
|
|
|
@example
|
|
* TODO
|
|
[[file:LINK TO WHERE YOU INITIATED CAPTURE]]
|
|
@end example
|
|
|
|
|
|
@noindent
|
|
During expansion of the template, special %-escapes@footnote{If you need one of these sequences literally, escape the @samp{%}
|
|
with a backslash.} allow
|
|
dynamic insertion of content. Here is a small selection of the
|
|
possibilities, consult the manual for more.
|
|
|
|
@multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
|
@item @samp{%a}
|
|
@tab annotation, normally the link created with @code{org-store-link}
|
|
@item @samp{%i}
|
|
@tab initial content, the region when capture is called with @kbd{C-u}
|
|
@item @samp{%t}, @samp{%T}
|
|
@tab timestamp, date only, or date and time
|
|
@item @samp{%u}, @samp{%U}
|
|
@tab like above, but inactive timestamps
|
|
@item @samp{%?}
|
|
@tab after completing the template, position point here
|
|
@end multitable
|
|
|
|
@node Refile and Copy
|
|
@section Refile and Copy
|
|
|
|
When reviewing the captured data, you may want to refile or to copy
|
|
some of the entries into a different list, for example into a project.
|
|
Cutting, finding the right location, and then pasting the note is
|
|
cumbersome. To simplify this process, you can use the following
|
|
special command:
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-w}
|
|
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.
|
|
|
|
By default, all level 1 headlines in the current buffer are
|
|
considered to be targets, but you can have more complex definitions
|
|
across a number of files. See the variable @code{org-refile-targets} for
|
|
details.
|
|
|
|
@item @kbd{C-u C-c C-w}
|
|
Use the refile interface to jump to a heading.
|
|
|
|
@item @kbd{C-u C-u C-c C-w}
|
|
Jump to the location where @code{org-refile} last moved a tree to.
|
|
|
|
@item @kbd{C-c M-w}
|
|
Copying works like refiling, except that the original note is not
|
|
deleted.
|
|
@end table
|
|
|
|
@node Archiving
|
|
@section 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.
|
|
|
|
The most common archiving action is to move a project tree to another
|
|
file, the archive file.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-x C-a}
|
|
Archive the current entry using the command specified in the
|
|
variable @code{org-archive-default-command}.
|
|
|
|
@item @kbd{C-c C-x C-s} or short @kbd{C-c $}
|
|
Archive the subtree starting at point position to the location given
|
|
by @code{org-archive-location}.
|
|
@end table
|
|
|
|
The default archive location is a file in the same directory as the
|
|
current file, with the name derived by appending @samp{_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
|
|
@code{org-archive-location}.
|
|
|
|
There is also an in-buffer option for setting this variable, for
|
|
example:
|
|
|
|
@example
|
|
#+ARCHIVE: %s_done::
|
|
@end example
|
|
|
|
@node Agenda Views
|
|
@chapter Agenda Views
|
|
|
|
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.
|
|
|
|
The extracted information is displayed in a special @emph{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. Remote editing from the agenda buffer means,
|
|
for example, that you can change the dates of deadlines and
|
|
appointments from the agenda buffer. For commands available in the
|
|
Agenda buffer, see @ref{Agenda Commands}.
|
|
|
|
@menu
|
|
* Agenda Files:: Files being searched for agenda information.
|
|
* Agenda Dispatcher:: Keyboard access to agenda views.
|
|
* Built-in Agenda Views:: What is available out of the box?
|
|
* Global TODO List:: All unfinished action items.
|
|
* Matching Tags and Properties:: Structured information with fine-tuned search.
|
|
* Search View:: Find entries by searching for text.
|
|
* Agenda Commands:: Remote editing of Org trees.
|
|
* Custom Agenda Views:: Defining special searches and views.
|
|
@end menu
|
|
|
|
@node Agenda Files
|
|
@section Agenda Files
|
|
|
|
The information to be shown is normally collected from all @emph{agenda
|
|
files}, the files listed in the variable @code{org-agenda-files}.
|
|
|
|
@table @asis
|
|
@item @kbd{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.
|
|
|
|
@item @kbd{C-c ]}
|
|
Remove current file from the list of agenda files.
|
|
|
|
@item @kbd{C-'}
|
|
@itemx @kbd{C-,}
|
|
Cycle through agenda file list, visiting one file after the other.
|
|
@end table
|
|
|
|
@node Agenda Dispatcher
|
|
@section The Agenda Dispatcher
|
|
|
|
The views are created through a dispatcher, accessible with @kbd{M-x org-agenda}, or, better, bound to a global key (see @ref{Activation}).
|
|
It displays a menu from which an additional letter is required to
|
|
execute a command. The dispatcher offers the following default
|
|
commands:
|
|
|
|
@table @asis
|
|
@item @kbd{a}
|
|
Create the calendar-like agenda (see [BROKEN LINK: *The Weekly/daily Agenda]).
|
|
|
|
@item @kbd{t}
|
|
@itemx @kbd{T}
|
|
Create a list of all TODO items (see @ref{Global TODO List}).
|
|
|
|
@item @kbd{m}
|
|
@itemx @kbd{M}
|
|
Create a list of headlines matching a given expression (see
|
|
@ref{Matching Tags and Properties}).
|
|
|
|
@item @kbd{s}
|
|
@kindex s @r{(Agenda dispatcher)}
|
|
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.
|
|
@end table
|
|
|
|
@node Built-in Agenda Views
|
|
@section The Weekly/Daily Agenda
|
|
|
|
The purpose of the weekly/daily @emph{agenda} is to act like a page of
|
|
a paper agenda, showing all the tasks for the current week or day.
|
|
|
|
@table @asis
|
|
@item @kbd{M-x org-agenda a}
|
|
Compile an agenda for the current week from a list of Org files.
|
|
The agenda shows the entries for each day.
|
|
@end table
|
|
|
|
Org mode understands the syntax of the diary and allows you to use
|
|
diary expression entries directly in Org files:
|
|
|
|
@example
|
|
* Holidays
|
|
:PROPERTIES:
|
|
:CATEGORY: Holiday
|
|
:END:
|
|
%%(org-calendar-holiday) ; special function for holiday names
|
|
|
|
* Birthdays
|
|
:PROPERTIES:
|
|
:CATEGORY: Ann
|
|
:END:
|
|
%%(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
|
|
|
|
Org can interact with Emacs appointments notification facility. To
|
|
add the appointments of your agenda files, use the command
|
|
@code{org-agenda-to-appt}.
|
|
|
|
@node Global TODO List
|
|
@section The Global TODO List
|
|
|
|
The global TODO list contains all unfinished TODO items formatted and
|
|
collected into a single place. Remote editing of TODO items lets you
|
|
can change the state of a TODO entry with a single key press. For
|
|
commands available in the TODO list, see @ref{Agenda Commands}.
|
|
|
|
@table @asis
|
|
@item @kbd{M-x org-agenda t}
|
|
Show the global TODO list. This collects the TODO items from all
|
|
agenda files (see @ref{Agenda Views}) into a single buffer.
|
|
|
|
@item @kbd{M-x org-agenda T}
|
|
Like the above, but allows selection of a specific TODO keyword.
|
|
@end table
|
|
|
|
@node Matching Tags and Properties
|
|
@section Matching Tags and Properties
|
|
|
|
If headlines in the agenda files are marked with @emph{tags} (see @ref{Tags}),
|
|
or have properties (see @ref{Properties}), 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}.
|
|
|
|
@table @asis
|
|
@item @kbd{M-x org-agenda m}
|
|
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 @ref{Tags}). If you often need a specific search, define a custom
|
|
command for it (see @ref{Agenda Dispatcher}).
|
|
|
|
@item @kbd{M-x org-agenda M}
|
|
Like @kbd{m}, but only select headlines that are also TODO
|
|
items.
|
|
@end table
|
|
|
|
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 @samp{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.
|
|
|
|
@table @asis
|
|
@item @samp{+work-boss}
|
|
Select headlines tagged @samp{work}, but discard those also tagged
|
|
@samp{boss}.
|
|
|
|
@item @samp{work|laptop}
|
|
Selects lines tagged @samp{work} or @samp{laptop}.
|
|
|
|
@item @samp{work|laptop+night}
|
|
Like before, but require the @samp{laptop} lines to be tagged also
|
|
@samp{night}.
|
|
@end table
|
|
|
|
You may also test for properties at the same time as matching tags,
|
|
see the manual for more information.
|
|
|
|
@node Search View
|
|
@section Search View
|
|
|
|
This agenda view is a general text search facility for Org mode
|
|
entries. It is particularly useful to find notes.
|
|
|
|
@table @asis
|
|
@item @kbd{M-x org-agenda s} (@code{org-search-view})
|
|
@kindex s @r{(Agenda dispatcher)}
|
|
@findex org-search-view
|
|
This is a special search that lets you select entries by matching
|
|
a substring or specific words using a boolean logic.
|
|
@end table
|
|
|
|
For example, the search string @samp{computer equipment} matches entries
|
|
that contain @samp{computer equipment} as a substring.
|
|
|
|
Search view can also search for specific keywords in the entry, using
|
|
Boolean logic. The search string @samp{+computer
|
|
+wifi -ethernet -@{8\.11[bg]@}} matches note entries that contain the
|
|
keywords @samp{computer} and @samp{wifi}, but not the keyword @samp{ethernet}, and
|
|
which are also not matched by the regular expression @samp{8\.11[bg]},
|
|
meaning to exclude both @samp{8.11b} and @samp{8.11g}.
|
|
|
|
Note that in addition to the agenda files, this command also searches
|
|
the files listed in @code{org-agenda-text-search-extra-files}.
|
|
|
|
@node Agenda Commands
|
|
@section Commands in the 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. This is just a selection of the many commands, explore
|
|
the agenda menu and the manual for a complete list.
|
|
|
|
@anchor{Motion (1)}
|
|
@subheading Motion
|
|
|
|
@table @asis
|
|
@item @kbd{n}
|
|
Next line (same as @kbd{@key{DOWN}} and @kbd{C-n}).
|
|
|
|
@item @kbd{p}
|
|
Previous line (same as @kbd{@key{UP}} and @kbd{C-p}).
|
|
@end table
|
|
|
|
@anchor{View/Go to Org file}
|
|
@subheading View/Go to Org file
|
|
|
|
@table @asis
|
|
@item @kbd{@key{SPC}}
|
|
Display the original location of the item in another window.
|
|
With a prefix argument, make sure that drawers stay folded.
|
|
|
|
@item @kbd{@key{TAB}}
|
|
Go to the original location of the item in another window.
|
|
|
|
@item @kbd{@key{RET}}
|
|
Go to the original location of the item and delete other windows.
|
|
@end table
|
|
|
|
@anchor{Change display}
|
|
@subheading Change display
|
|
|
|
@table @asis
|
|
@item @kbd{o}
|
|
Delete other windows.
|
|
|
|
@item @kbd{v d} or short @kbd{d}
|
|
Switch to day view.
|
|
|
|
@item @kbd{v w} or short @kbd{w}
|
|
Switch to week view.
|
|
|
|
@item @kbd{f}
|
|
Go forward in time to display the span following the current one.
|
|
For example, if the display covers a week, switch to the following
|
|
week.
|
|
|
|
@item @kbd{b}
|
|
Go backward in time to display earlier dates.
|
|
|
|
@item @kbd{.}
|
|
Go to today.
|
|
|
|
@item @kbd{j}
|
|
Prompt for a date and go there.
|
|
|
|
@item @kbd{v l} or @kbd{v L} or short @kbd{l}
|
|
Toggle Logbook mode. In Logbook mode, entries that were marked as
|
|
done while logging was on (see the variable @code{org-log-done}) are
|
|
shown in the agenda, as are entries that have been clocked on that
|
|
day. When called with a @kbd{C-u} prefix argument, show all
|
|
possible logbook entries, including state changes.
|
|
|
|
@item @kbd{r}
|
|
@itemx @kbd{g}
|
|
Recreate the agenda buffer, for example to reflect the changes after
|
|
modification of the timestamps of items.
|
|
|
|
@item @kbd{s}
|
|
@kindex C-x C-s
|
|
@findex org-save-all-org-buffers
|
|
@kindex s
|
|
Save all Org buffers in the current Emacs session, and also the
|
|
locations of IDs.
|
|
@end table
|
|
|
|
@anchor{Remote editing}
|
|
@subheading Remote editing
|
|
|
|
@table @asis
|
|
@item @kbd{0--9}
|
|
Digit argument.
|
|
|
|
@item @kbd{t}
|
|
Change the TODO state of the item, both in the agenda and in the
|
|
original Org file.
|
|
|
|
@item @kbd{C-k}
|
|
Delete the current agenda item along with the entire subtree
|
|
belonging to it in the original Org file.
|
|
|
|
@item @kbd{C-c C-w}
|
|
Refile the entry at point.
|
|
|
|
@item @kbd{a}
|
|
Archive the subtree corresponding to the entry at point using the
|
|
default archiving command set in @code{org-archive-default-command}.
|
|
|
|
@item @kbd{$}
|
|
Archive the subtree corresponding to the current headline.
|
|
|
|
@item @kbd{C-c C-s}
|
|
Schedule this item. With a prefix argument, remove the
|
|
scheduling timestamp
|
|
|
|
@item @kbd{C-c C-d}
|
|
Set a deadline for this item. With a prefix argument, remove the
|
|
deadline.
|
|
|
|
@item @kbd{S-@key{RIGHT}}
|
|
Change the timestamp associated with the current line by one day
|
|
into the future.
|
|
|
|
@item @kbd{S-@key{LEFT}}
|
|
Change the timestamp associated with the current line by one day
|
|
into the past.
|
|
|
|
@item @kbd{I}
|
|
Start the clock on the current item.
|
|
|
|
@item @kbd{O}
|
|
Stop the previously started clock.
|
|
|
|
@item @kbd{X}
|
|
Cancel the currently running clock.
|
|
|
|
@item @kbd{J}
|
|
Jump to the running clock in another window.
|
|
@end table
|
|
|
|
@anchor{Quit and exit}
|
|
@subheading Quit and exit
|
|
|
|
@table @asis
|
|
@item @kbd{q}
|
|
Quit agenda, remove the agenda buffer.
|
|
|
|
@item @kbd{x}
|
|
Exit agenda, remove the agenda buffer and all buffers loaded by
|
|
Emacs for the compilation of the agenda.
|
|
@end table
|
|
|
|
@node Custom Agenda Views
|
|
@section Custom Agenda Views
|
|
|
|
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).
|
|
|
|
Custom commands are configured in the variable
|
|
@code{org-agenda-custom-commands}. You can customize this variable, for
|
|
example by pressing @kbd{C} from the agenda dispatcher (see @ref{Agenda Dispatcher}). You can also directly set it with Emacs Lisp in
|
|
the Emacs init file. The following example contains all valid agenda
|
|
views:
|
|
|
|
@lisp
|
|
(setq org-agenda-custom-commands
|
|
'(("w" todo "WAITING")
|
|
("u" tags "+boss-urgent")
|
|
("v" tags-todo "+boss-urgent")))
|
|
@end lisp
|
|
|
|
The initial string in each entry defines the keys you have to press
|
|
after the dispatcher command in order to access the command. Usually
|
|
this is just a single character. 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:
|
|
|
|
@table @asis
|
|
@item @kbd{w}
|
|
as a global search for TODO entries with @samp{WAITING} as the TODO
|
|
keyword.
|
|
|
|
@item @kbd{u}
|
|
as a global tags search for headlines tagged @samp{boss} but not
|
|
@samp{urgent}.
|
|
|
|
@item @kbd{v}
|
|
The same search, but limiting it to headlines that are also TODO
|
|
items.
|
|
@end table
|
|
|
|
@node Markup
|
|
@chapter Markup for Rich Contents
|
|
|
|
Org is primarily about organizing and searching through your
|
|
plain-text notes. However, it also provides a lightweight yet robust
|
|
markup language for rich text formatting and more. Used in
|
|
conjunction with the export framework (see @ref{Exporting}), you can author
|
|
beautiful documents in Org.
|
|
|
|
@menu
|
|
* Paragraphs:: The basic unit of text.
|
|
* Emphasis and Monospace:: Bold, italic, etc.
|
|
* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents.
|
|
* Literal examples:: Source code examples with special formatting.
|
|
* Images:: Display an image.
|
|
* Creating Footnotes:: Edit and read footnotes.
|
|
@end menu
|
|
|
|
@node Paragraphs
|
|
@section Paragraphs
|
|
|
|
Paragraphs are separated by at least one empty line. If you need to
|
|
enforce a line break within a paragraph, use @samp{\\} at the end of
|
|
a line.
|
|
|
|
To preserve the line breaks, indentation and blank lines in a region,
|
|
but otherwise use normal formatting, you can use this construct, which
|
|
can also be used to format poetry.
|
|
|
|
@example
|
|
#+BEGIN_VERSE
|
|
Great clouds overhead
|
|
Tiny black birds rise and fall
|
|
Snow covers Emacs
|
|
|
|
---AlexSchroeder
|
|
#+END_VERSE
|
|
@end example
|
|
|
|
When quoting a passage from another document, it is customary to
|
|
format this as a paragraph that is indented on both the left and the
|
|
right margin. You can include quotations in Org documents like this:
|
|
|
|
@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:
|
|
|
|
@example
|
|
#+BEGIN_CENTER
|
|
Everything should be made as simple as possible, \\
|
|
but not any simpler
|
|
#+END_CENTER
|
|
@end example
|
|
|
|
@node Emphasis and Monospace
|
|
@section Emphasis and Monospace
|
|
|
|
You can make words @samp{*bold*}, @samp{/italic/}, @samp{_underlined_}, @samp{=verbatim=}
|
|
and @samp{~code~}, and, if you must, @samp{+strike-through+}. Text in the code
|
|
and verbatim string is not processed for Org specific syntax; it is
|
|
exported verbatim.
|
|
|
|
@node Embedded @LaTeX{}
|
|
@section Embedded @LaTeX{}
|
|
|
|
For scientific notes which need to be able to contain mathematical
|
|
symbols and the occasional formula, Org mode supports embedding @LaTeX{}
|
|
code into its files. You can directly use @TeX{}-like syntax for special
|
|
symbols, enter formulas and entire @LaTeX{} environments.
|
|
|
|
@example
|
|
The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand,
|
|
the radius of Alpha Centauri is R_@{Alpha Centauri@} = 1.28 x R_@{sun@}.
|
|
|
|
\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
|
|
|
|
@node Literal examples
|
|
@section Literal examples
|
|
|
|
You can include literal examples that should not be subjected to
|
|
markup. Such examples are typeset in monospace, so this is well
|
|
suited for source code and similar examples.
|
|
|
|
@example
|
|
#+BEGIN_EXAMPLE
|
|
Some example from a text file.
|
|
#+END_EXAMPLE
|
|
@end example
|
|
|
|
For simplicity when using small examples, you can also start the
|
|
example lines with a colon followed by a space. There may also be
|
|
additional whitespace before the colon:
|
|
|
|
@example
|
|
Here is an example
|
|
: Some example from a text file.
|
|
@end example
|
|
|
|
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.
|
|
|
|
@example
|
|
#+BEGIN_SRC emacs-lisp
|
|
(defun org-xor (a b)
|
|
"Exclusive or."
|
|
(if a (not b) b))
|
|
#+END_SRC
|
|
@end example
|
|
|
|
To edit the example in a special buffer supporting this language, use
|
|
@kbd{C-c '} to both enter and leave the editing buffer.
|
|
|
|
@node Images
|
|
@section Images
|
|
|
|
An image is a link to an image file that does not have a description
|
|
part, for example
|
|
|
|
@example
|
|
./img/cat.jpg
|
|
@end example
|
|
|
|
|
|
If you wish to define a caption for the image and maybe a label for
|
|
internal cross references (see @ref{Hyperlinks}), make sure that the
|
|
link is on a line by itself and precede it with @samp{CAPTION} and @samp{NAME}
|
|
keywords as follows:
|
|
|
|
@example
|
|
#+CAPTION: This is the caption for the next figure link (or table)
|
|
#+NAME: fig:SED-HR4049
|
|
[[./img/a.jpg]]
|
|
@end example
|
|
|
|
@node Creating Footnotes
|
|
@section Creating Footnotes
|
|
|
|
A footnote is defined in a paragraph that is started by a footnote
|
|
marker in square brackets in column 0, no indentation allowed. The
|
|
footnote reference is simply the marker in square brackets, inside
|
|
text. For example:
|
|
|
|
@example
|
|
The Org homepage[fn:1] now looks a lot better than it used to.
|
|
...
|
|
[fn:1] The link is: https://orgmode.org
|
|
@end example
|
|
|
|
The following commands handle footnotes:
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-x f}
|
|
The footnote action command. When point is on a footnote reference,
|
|
jump to the definition. When it is at a definition, jump to the
|
|
(first) reference. Otherwise, create a new footnote. When this
|
|
command is called with a prefix argument, a menu of additional
|
|
options including renumbering is offered.
|
|
|
|
@item @kbd{C-c C-c}
|
|
Jump between definition and reference.
|
|
@end table
|
|
|
|
@node Exporting
|
|
@chapter Exporting
|
|
|
|
Org can convert and export documents to a variety of other formats
|
|
while retaining as much structure (see @ref{Document Structure}) and markup
|
|
(see @ref{Markup}) as possible.
|
|
|
|
@menu
|
|
* The Export Dispatcher:: The main interface.
|
|
* Export Settings:: Common export settings.
|
|
* Table of Contents:: The if and where of the table of contents.
|
|
* Include Files:: Include additional files into a document.
|
|
* Comment Lines:: What will not be exported.
|
|
* ASCII/UTF-8 Export:: Exporting to flat files with encoding.
|
|
* HTML Export:: Exporting to HTML.
|
|
* @LaTeX{} Export:: Exporting to @LaTeX{} and processing to PDF.
|
|
* iCalendar Export:: Exporting to iCalendar.
|
|
@end menu
|
|
|
|
@node The Export Dispatcher
|
|
@section The Export Dispatcher
|
|
|
|
The export dispatcher is the main interface for Org's exports.
|
|
A hierarchical menu presents the currently configured export formats.
|
|
Options are shown as easy toggle switches on the same screen.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-e}
|
|
Invokes the export dispatcher interface.
|
|
@end table
|
|
|
|
Org exports the entire buffer by default. If the Org buffer has an
|
|
active region, then Org exports just that region.
|
|
|
|
@node Export Settings
|
|
@section Export Settings
|
|
|
|
The exporter recognizes special lines in the buffer which provide
|
|
additional information. These lines may be put anywhere in the file:
|
|
|
|
@example
|
|
#+TITLE: I'm in the Mood for Org
|
|
@end example
|
|
|
|
|
|
Most proeminent export options include:
|
|
|
|
@multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
|
@item @samp{TITLE}
|
|
@tab the title to be shown
|
|
@item @samp{AUTHOR}
|
|
@tab the author (default taken from @code{user-full-name})
|
|
@item @samp{DATE}
|
|
@tab a date, fixed, or an Org timestamp
|
|
@item @samp{EMAIL}
|
|
@tab email address (default from @code{user-mail-address})
|
|
@item @samp{LANGUAGE}
|
|
@tab language code, e.g., @samp{en}
|
|
@end multitable
|
|
|
|
Option keyword sets can be inserted from the export dispatcher (see
|
|
@ref{The Export Dispatcher}) using the @samp{Insert template} command by
|
|
pressing @kbd{#}.
|
|
|
|
@node Table of Contents
|
|
@section Table of Contents
|
|
|
|
The table of contents includes all headlines in the document. Its
|
|
depth is therefore the same as the headline levels in the file. If
|
|
you need to use a different depth, or turn it off entirely, set the
|
|
@code{org-export-with-toc} variable accordingly. You can achieve the same
|
|
on a per file basis, using the following @samp{toc} item in @samp{OPTIONS}
|
|
keyword:
|
|
|
|
@example
|
|
#+OPTIONS: toc:2 (only include two levels in TOC)
|
|
#+OPTIONS: toc:nil (no default TOC at all)
|
|
@end example
|
|
|
|
Org normally inserts the table of contents directly before the first
|
|
headline of the file.
|
|
|
|
@node Include Files
|
|
@section Include Files
|
|
|
|
During export, you can include the content of another file. For
|
|
example, to include your @samp{.emacs} file, you could use:
|
|
|
|
@example
|
|
#+INCLUDE: "~/.emacs" src emacs-lisp
|
|
@end example
|
|
|
|
|
|
@noindent
|
|
The first parameter is the file name to include. The optional second
|
|
parameter specifies the block type: @samp{example}, @samp{export} or @samp{src}. The
|
|
optional third parameter specifies the source code language to use for
|
|
formatting the contents. This is relevant to both @samp{export} and @samp{src}
|
|
block types.
|
|
|
|
You can visit the included file with @kbd{C-c '}.
|
|
|
|
@node Comment Lines
|
|
@section Comment Lines
|
|
|
|
Lines starting with zero or more whitespace characters followed by one
|
|
@samp{#} and a whitespace are treated as comments and, as such, are not
|
|
exported.
|
|
|
|
Likewise, regions surrounded by @samp{#+BEGIN_COMMENT} @dots{} @samp{#+END_COMMENT}
|
|
are not exported.
|
|
|
|
Finally, a @samp{COMMENT} keyword at the beginning of an entry, but after
|
|
any other keyword or priority cookie, comments out the entire subtree.
|
|
The command below helps changing the comment status of a headline.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c ;}
|
|
Toggle the @samp{COMMENT} keyword at the beginning of an entry.
|
|
@end table
|
|
|
|
@node ASCII/UTF-8 Export
|
|
@section ASCII/UTF-8 Export
|
|
|
|
ASCII export produces an output file containing only plain ASCII
|
|
characters. This is the simplest and most direct text output. It
|
|
does not contain any Org markup. UTF-8 export uses additional
|
|
characters and symbols available in this encoding standards.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-e t a}
|
|
@itemx @kbd{C-c C-e t u}
|
|
Export as an ASCII file with a @samp{.txt} extension. For @samp{myfile.org},
|
|
Org exports to @samp{myfile.txt}, overwriting without warning. For
|
|
@samp{myfile.txt}, Org exports to @samp{myfile.txt.txt} in order to prevent
|
|
data loss.
|
|
@end table
|
|
|
|
@node HTML Export
|
|
@section HTML Export
|
|
|
|
Org mode contains an HTML exporter with extensive HTML formatting
|
|
compatible with XHTML 1.0 strict standard.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-e h h}
|
|
Export as HTML file with a @samp{.html} extension. For @samp{myfile.org}, Org
|
|
exports to @samp{myfile.html}, overwriting without warning. @{@{@{kbd@{C-c
|
|
C-e h o)@}@}@} exports to HTML and opens it in a web browser.
|
|
@end table
|
|
|
|
The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and @samp{>}.
|
|
To include raw HTML code in the Org file so the HTML export back-end
|
|
can insert that HTML code in the output, use this inline syntax:
|
|
@samp{@@@@html:...@@@@}. For example:
|
|
|
|
@example
|
|
@@@@html:<b>@@@@bold text@@@@html:</b>@@@@
|
|
@end example
|
|
|
|
|
|
For larger raw HTML code blocks, use these HTML export code blocks:
|
|
|
|
@example
|
|
#+HTML: Literal HTML code for export
|
|
|
|
#+BEGIN_EXPORT html
|
|
All lines between these markers are exported literally
|
|
#+END_EXPORT
|
|
@end example
|
|
|
|
@node @LaTeX{} Export
|
|
@section @LaTeX{} Export
|
|
|
|
The @LaTeX{} export back-end can handle complex documents, incorporate
|
|
standard or custom @LaTeX{} document classes, generate documents using
|
|
alternate @LaTeX{} engines, and produce fully linked PDF files with
|
|
indexes, bibliographies, and tables of contents, destined for
|
|
interactive online viewing or high-quality print publication.
|
|
|
|
By default, the @LaTeX{} output uses the @emph{article} class. You can change
|
|
this by adding an option like @samp{#+LATEX_CLASS: myclass} in your file.
|
|
The class must be listed in @code{org-latex-classes}.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-e l l}
|
|
Export to a @LaTeX{} file with a @samp{.tex} extension. For @samp{myfile.org},
|
|
Org exports to @samp{myfile.tex}, overwriting without warning.
|
|
|
|
@item @kbd{C-c C-e l p}
|
|
Export as @LaTeX{} file and convert it to PDF file.
|
|
|
|
@item @kbd{C-c C-e l o}
|
|
Export as @LaTeX{} file and convert it to PDF, then open the PDF using
|
|
the default viewer.
|
|
@end table
|
|
|
|
The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code, see
|
|
@ref{Embedded @LaTeX{}}. There are three ways to embed such code in the Org
|
|
file and they all use different quoting syntax.
|
|
|
|
Inserting in-line quoted with @@ symbols:
|
|
|
|
@example
|
|
Code embedded in-line @@@@latex:any arbitrary LaTeX code@@@@ in a paragraph.
|
|
@end example
|
|
|
|
|
|
Inserting as one or more keyword lines in the Org file:
|
|
|
|
@example
|
|
#+LATEX: any arbitrary LaTeX code
|
|
@end example
|
|
|
|
|
|
Inserting as an export block in the Org file, where the back-end
|
|
exports any code between begin and end markers:
|
|
|
|
@example
|
|
#+BEGIN_EXPORT latex
|
|
any arbitrary LaTeX code
|
|
#+END_EXPORT
|
|
@end example
|
|
|
|
@node iCalendar Export
|
|
@section iCalendar Export
|
|
|
|
A large part of Org mode's interoperability success is its ability to
|
|
easily export to or import from external applications. The iCalendar
|
|
export back-end takes calendar data from Org files and exports to the
|
|
standard iCalendar format.
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-e c f}
|
|
Create iCalendar entries from the current Org buffer and store them
|
|
in the same directory, using a file extension @samp{.ics}.
|
|
|
|
@item @kbd{C-c C-e c c}
|
|
Create a combined iCalendar file from Org files in
|
|
@code{org-agenda-files} and write it to
|
|
@code{org-icalendar-combined-agenda-file} file name.
|
|
@end table
|
|
|
|
@node Publishing
|
|
@chapter Publishing
|
|
|
|
Org includes a publishing management system that allows you to
|
|
configure automatic HTML conversion of @emph{projects} composed of
|
|
interlinked Org files. You can also configure Org to automatically
|
|
upload your exported HTML pages and related attachments, such as
|
|
images and source code files, to a web server.
|
|
|
|
You can also use Org to convert files into PDF, or even combine HTML
|
|
and PDF conversion so that files are available in both formats on the
|
|
server.
|
|
|
|
For detailed instructions about setup, see the manual. Here is an
|
|
example:
|
|
|
|
@lisp
|
|
(setq org-publish-project-alist
|
|
'(("org"
|
|
:base-directory "~/org/"
|
|
:publishing-directory "~/public_html"
|
|
:section-numbers nil
|
|
:table-of-contents nil
|
|
:style "<link rel=\"stylesheet\"
|
|
href=\"../other/mystyle.css\"
|
|
type=\"text/css\"/>")))
|
|
@end lisp
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-e P x}
|
|
Prompt for a specific project and publish all files that belong to
|
|
it.
|
|
|
|
@item @kbd{C-c C-e P p}
|
|
Publish the project containing the current file.
|
|
|
|
@item @kbd{C-c C-e P f}
|
|
Publish only the current file.
|
|
|
|
@item @kbd{C-c C-e P a}
|
|
Publish every project.
|
|
@end table
|
|
|
|
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.
|
|
|
|
@node Working with Source Code
|
|
@chapter Working with Source Code
|
|
|
|
Org mode provides a number of features for working with source code,
|
|
including editing of code blocks in their native major mode,
|
|
evaluation of code blocks, tangling of code blocks, and exporting code
|
|
blocks and their results in several formats.
|
|
|
|
A source code block conforms to this structure:
|
|
|
|
@example
|
|
#+NAME: <name>
|
|
#+BEGIN_SRC <language> <switches> <header arguments>
|
|
<body>
|
|
#+END_SRC
|
|
@end example
|
|
|
|
@noindent
|
|
where:
|
|
|
|
@itemize
|
|
@item
|
|
@samp{<name>} is a string used to uniquely name the code block,
|
|
|
|
@item
|
|
@samp{<language>} specifies the language of the code block, e.g.,
|
|
@samp{emacs-lisp}, @samp{shell}, @samp{R}, @samp{python}, etc.,
|
|
|
|
@item
|
|
@samp{<switches>} can be used to control export of the code block,
|
|
|
|
@item
|
|
@samp{<header arguments>} can be used to control many aspects of code
|
|
block behavior as demonstrated below,
|
|
|
|
@item
|
|
@samp{<body>} contains the actual source code.
|
|
@end itemize
|
|
|
|
Use @kbd{C-c '} to edit the current code block. It opens a new
|
|
major mode edit buffer containing the body of the source code block,
|
|
ready for any edits. Use @kbd{C-c '} again to close the buffer
|
|
and return to the Org buffer.
|
|
|
|
@anchor{Using header arguments}
|
|
@heading Using header arguments
|
|
|
|
A header argument is specified with an initial colon followed by the
|
|
argument's name in lowercase.
|
|
|
|
Header arguments can be set in several ways; Org prioritizes them in
|
|
case of overlaps or conflicts by giving local settings a higher
|
|
priority.
|
|
|
|
@table @asis
|
|
@item System-wide header arguments
|
|
Those are specified by customizing @code{org-babel-default-header-args}
|
|
variable, or, for a specific language @var{LANG}
|
|
@code{org-babel-default-header-args:LANG}.
|
|
|
|
@item Header arguments in properties
|
|
You can set them using @samp{header-args} property (see @ref{Properties})---or
|
|
@samp{header-args:LANG} for language @var{LANG}. Header arguments
|
|
set through properties drawers apply at the sub-tree level on down.
|
|
|
|
@item Header arguments in code blocks
|
|
Header arguments are most commonly set at the source code block
|
|
level, on the @samp{BEGIN_SRC} line:
|
|
|
|
@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
|
|
|
|
Code block header arguments can span multiple lines using @samp{HEADER}
|
|
keyword on each line.
|
|
@end table
|
|
|
|
@anchor{Evaluating code blocks}
|
|
@heading Evaluating code blocks
|
|
|
|
Use @kbd{C-c C-c} to evaluate the current code block and insert
|
|
its results in the Org document. By default, evaluation is only
|
|
turned on for @samp{emacs-lisp} code blocks, however support exists for
|
|
evaluating blocks in many languages. For a complete list of supported
|
|
languages see the manual. The following shows a code block and its
|
|
results.
|
|
|
|
@example
|
|
#+BEGIN_SRC emacs-lisp
|
|
(+ 1 2 3 4)
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
: 10
|
|
@end example
|
|
|
|
The following syntax is used to pass arguments to code blocks using
|
|
the @samp{var} header argument.
|
|
|
|
@example
|
|
:var NAME=ASSIGN
|
|
@end example
|
|
|
|
|
|
@noindent
|
|
@var{NAME} is the name of the variable bound in the code block
|
|
body. @var{ASSIGN} is a literal value, such as a string,
|
|
a number, a reference to a table, a list, a literal example, another
|
|
code block---with or without arguments---or the results of evaluating
|
|
a code block.
|
|
|
|
@anchor{Results of evaluation}
|
|
@heading Results of evaluation
|
|
|
|
How Org handles results of a code block execution depends on many
|
|
header arguments working together. The primary determinant, however,
|
|
is the @samp{results} header argument. It controls the @emph{collection},
|
|
@emph{type}, @emph{format}, and @emph{handling} of code block results.
|
|
|
|
@table @asis
|
|
@item Collection
|
|
How the results should be collected from the code block. You may
|
|
choose either @samp{output} or @samp{value} (the default).
|
|
|
|
@item Type
|
|
What result types to expect from the execution of the code block.
|
|
You may choose among @samp{table}, @samp{list}, @samp{scalar}, and @samp{file}. Org
|
|
tries to guess it if you do not provide it.
|
|
|
|
@item Format
|
|
How Org processes results. Some possible values are @samp{code},
|
|
@samp{drawer}, @samp{html}, @samp{latex}, @samp{link}, and @samp{raw}.
|
|
|
|
@item Handling
|
|
How to insert the results once properly formatted. Allowed values
|
|
are @samp{silent}, @samp{replace} (the default), @samp{append}, or @samp{prepend}.
|
|
@end table
|
|
|
|
Code blocks which output results to files---e.g.: graphs, diagrams and
|
|
figures---can accept a @samp{:file FILENAME} header argument, in which case
|
|
the results are saved to the named file, and a link to the file is
|
|
inserted into the buffer.
|
|
|
|
@anchor{Exporting code blocks}
|
|
@heading Exporting code blocks
|
|
|
|
It is possible to export the @emph{code} of code blocks, the @emph{results} of
|
|
code block evaluation, @emph{both} the code and the results of code block
|
|
evaluation, or @emph{none}. Org defaults to exporting @emph{code} for most
|
|
languages.
|
|
|
|
The @samp{exports} header argument is to specify if that part of the Org
|
|
file is exported to, say, HTML or @LaTeX{} formats. It can be set to
|
|
either @samp{code}, @samp{results}, @samp{both} or @samp{none}.
|
|
|
|
@anchor{Extracting source code}
|
|
@heading Extracting source code
|
|
|
|
Use @kbd{C-c C-v t} to create pure source code files by
|
|
extracting code from source blocks in the current buffer. This is
|
|
referred to as ``tangling''---a term adopted from the literate
|
|
programming community. During tangling of code blocks their bodies
|
|
are expanded using @code{org-babel-expand-src-block}, which can expand both
|
|
variable and ``Noweb'' style references. In order to tangle a code
|
|
block it must have a @samp{tangle} header argument, see the manual for
|
|
details.
|
|
|
|
@node Miscellaneous
|
|
@chapter Miscellaneous
|
|
|
|
|
|
|
|
@anchor{Completion}
|
|
@heading Completion
|
|
|
|
Org has in-buffer completions with @kbd{M-@key{TAB}}. No minibuffer is
|
|
involved. Type one or more letters and invoke the hot key to complete
|
|
the text in-place.
|
|
|
|
For example, this command will complete @TeX{} symbols after @samp{\}, TODO
|
|
keywords at the beginning of a headline, and tags after @samp{:} in
|
|
a headline.
|
|
|
|
@anchor{Structure Templates}
|
|
@heading Structure Templates
|
|
|
|
To quickly insert empty structural blocks, such as @samp{#+BEGIN_SRC}
|
|
@dots{} @samp{#+END_SRC}, or to wrap existing text in such a block, use
|
|
|
|
@table @asis
|
|
@item @kbd{C-c C-,}
|
|
Prompt for a type of block structure, and insert the block at point.
|
|
If the region is active, it is wrapped in the block.
|
|
@end table
|
|
|
|
@anchor{Clean view}
|
|
@heading Clean view
|
|
|
|
Org's default outline with stars and no indents can become too
|
|
cluttered for short documents. For @emph{book-like} long documents, the
|
|
effect is not as noticeable. Org provides an alternate stars and
|
|
indentation scheme, as shown on the right in the following table. It
|
|
uses only one star and indents text to line with the heading:
|
|
|
|
@example
|
|
* Top level headline | * Top level headline
|
|
** Second level | * Second level
|
|
*** Third level | * Third level
|
|
some text | some text
|
|
*** Third level | * Third level
|
|
more text | more text
|
|
* Another top level headline | * Another top level headline
|
|
@end example
|
|
|
|
This kind of view can be achieved dynamically at display time using
|
|
Org Indent mode (@kbd{M-x org-indent-mode @key{RET}}), which prepends
|
|
intangible space to each line. You can turn on Org Indent mode for
|
|
all files by customizing the variable @code{org-startup-indented}, or you
|
|
can turn it on for individual files using
|
|
|
|
@example
|
|
#+STARTUP: indent
|
|
@end example
|
|
|
|
|
|
If you want 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 by helping to indent (with @kbd{@key{TAB}}) text below
|
|
each headline, by hiding leading stars, and by only using levels 1, 3,
|
|
etc to get two characters indentation for each level. To get this
|
|
support in a file, use
|
|
|
|
@example
|
|
#+STARTUP: hidestars odd
|
|
@end example
|
|
|
|
@bye |