Commit 891f4676 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

New file.

parent a4231b04
This source diff could not be displayed because it is too large. You can view the blob instead.
\input texinfo
@c %**start of header
@setfilename ../info/org
@settitle Org Mode Manual
@set VERSION 3.03
@set DATE December 2004
@dircategory Emacs
@direntry
* Org Mode: (org.info). Outline-based notes management and organizer
@end direntry
@c Version and Contact Info
@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
@set MAINTAINER Carsten Dominik
@set MAINTAINEREMAIL @email{dominik@@science.uva.nl}
@set MAINTAINERCONTACT @uref{mailto:dominik@@science.uva.nl,contact the maintainer}
@c %**end of header
@finalout
@c Macro definitions
@c Subheadings inside a table. Need a difference between info and the rest.
@macro tsubheading{text}
@ifinfo
@subsubheading \text\
@end ifinfo
@ifnotinfo
@item @b{\text\}
@end ifnotinfo
@end macro
@copying
This manual is for Org-mode (version @value{VERSION}).
Copyright @copyright{} 2004 Free Software Foundation
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying
@titlepage
@title Org Mode Manual
@subtitle Release @value{VERSION}
@author by Carsten Dominik
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@c Output the table of contents at the beginning.
@contents
@ifnottex
@node Top, Introduction, (dir), (dir)
@top Org Mode Manual
@insertcopying
@end ifnottex
@menu
* Introduction:: Getting started
* Document Structure:: A tree works like your brain
* TODO items:: Every tree branch can be a TODO item
* Tables:: Pure magic for quick formatting
* Hyperlinks:: Notes in context
* Timestamps:: Assign date and time to items
* Timeline and Agenda:: Use time-stamped items to produce an agenda
* Exporting:: Sharing and publishing of notes
* Miscellaneous:: All the rest which did not fit elsewhere
* Index:: The fast road to specific information
* Key Index:: Key bindings and where they are described
@detailmenu
--- The Detailed Node Listing ---
Introduction
* Summary:: Brief summary of what Org-mode does
* Installation:: How to install Org-mode
Document Structure
* Outlines:: Org-mode is based on outline-mode
* Headlines:: How to typeset org-tree headlines
* Visibility cycling:: Show ad hide, much simplified
* Motion:: Jumping to other headlines
* Structure editing:: Changing sequence and level of headlines
* Sparse trees:: Matches embedded in context
TODO items
* TODO basics:: Marking and displaying TODO entries
* Priorities:: Some things are more important than others
* TODO extensions:: Workflow and assignments
Extended use of TODO keywords
* Workflow states:: From TODO to DONE in steps
* TODO types:: I do this, Fred the rest
* Per file keywords:: Different files, different requirements
Tables
* Built-in table editor:: Simple tables
* table.el:: Complex tables
Hyperlinks
* Links:: URL-like links to the world
* Remember:: Org-trees store quick notes
Timestamps
* Time stamps:: Assigning a time to a tree entry
* Creating timestamps:: Commands which insert timestamps
Timeline and Agenda
* Timeline (single file):: Time-sorted view for single file
* Agenda (multiple files):: Your weekly planner
* Agenda commands:: Remote editing of org trees
* Calendar/Diary integration:: Integrating Anniversaries and more
Calendar/Diary integration
* Diary to agenda:: Agenda incorporates the diary
* Agenda to diary:: Diary incorporates the agenda
Exporting
* Export commands:: Commands which export and display
* HTML formatting:: Interpretation of the buffer content
* Export options:: How to influence exports
* Comment lines:: Lines which will not be exported
Miscellaneous
* Completion:: M-TAB knows what you need
* Customization:: Adapting Org-mode to your taste
* Tips and Tricks:: An author-imposed FAQ, sort of
* Interaction:: Other Emacs packages
* Acknowledgments:: These people provided feedback and more
* Bugs:: Things which do not work perfectly
@end detailmenu
@end menu
@node Introduction, Document Structure, Top, Top
@chapter Introduction
@cindex introduction
@menu
* Summary:: Brief summary of what Org-mode does
* Installation:: How to install Org-mode
@end menu
@node Summary, Installation, Introduction, Introduction
@section Summary
@cindex summary
Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
project planning with a fast and effective plain-text system.
Org-mode develops organizational tasks around NOTES files that contain
information about projects as plain text. Org-mode is implemented on
top of outline-mode, which makes it possible to keep the content of
large files well structured. Visibility cycling and structure editing
help to work with the tree. Tables are easily created with a built-in
table editor. Org-mode supports ToDo items, deadlines, time stamps,
and scheduling. It dynamically compiles entries into an agenda.
Plain text URL-like links connect to websites, emails, usenet
messages, BBDB entries, and any files related to the projects. For
printing and sharing of notes, an Org-mode file can be exported as a
structured ASCII file, or as HTML.
Org-mode keeps simple things simple. Not every outline branch needs
to be an action item, not every action item needs to have priority or
scheduling information associated with it. Org-mode can be used on
different levels and in different ways, for example
@example
@r{@bullet{} as an outline extension with visibility cycling and structure editing}
@r{@bullet{} as an ASCII system and table editor to take structured notes}
@r{@bullet{} as a simple hypertext system, with HTML export}
@r{@bullet{} as a TODO list editor}
@r{@bullet{} as a full agenda and planner with deadlines and work scheduling}
@end example
@node Installation, , Summary, Introduction
@section Installation
@cindex installation
@cindex autoload
@cindex global keybindings
@cindex keybindings, global
The instructions below assume that you have downloaded Org-mode from
the web. If Org-mode is part of the Emacs distribution or an XEmacs
package, you only need to add to @file{.emacs} the last three Lisp
lines below - all the rest will be taken care of automatically.
Byte-compile @file{org.el} and put it on your load path. If you'd
like to use the Info documentation, copy the file @file{org} into the
directory containing info files and run the command @code{install-info
org}.
Then copy the following lines into @file{.emacs}. The last two lines
define @emph{global} keys for the commands @command{org-store-link}
and @command{org-agenda} - please choose suitable keys yourself.
@c FIXME: autoloads not necessary when part of emacs
@lisp
(autoload 'org-mode "org" "Org mode" t)
(autoload 'org-diary "org" "Diary entries from Org mode")
(autoload 'org-agenda "org" "Multi-file agenda from Org mode" t)
(autoload 'org-store-link "org" "Store a link to the current location" t)
(add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
(define-key global-map "\C-cl" 'org-store-link)
(define-key global-map "\C-ca" 'org-agenda)
@end lisp
@cindex org-mode, turning on
@noindent
This will put all files with extension @samp{.org} into Org-mode. As
an alternative, make the first line of a file look like this:
@example
MY PROJECTS -*- mode: org; -*-
@end example
@noindent which will select Org-mode for this buffer no matter what
the file's name is.
@node Document Structure, TODO items, Introduction, Top
@chapter Document Structure
@cindex document structure
@cindex structure of document
Org-mode is based on outline mode and provides flexible commands to
edit the structure of the document.
@menu
* Outlines:: Org-mode is based on outline-mode
* Headlines:: How to typeset org-tree headlines
* Visibility cycling:: Show ad hide, much simplified
* Motion:: Jumping to other headlines
* Structure editing:: Changing sequence and level of headlines
* Sparse trees:: Matches embedded in context
@end menu
@node Outlines, Headlines, Document Structure, Document Structure
@section Outlines
@cindex outlines
@cindex outline-mode
Org-mode is implemented on top of outline-mode. Outlines allow to
organize a document in a hierarchical structure, which (at least for
me) is the best representation of notes and thoughts. Overview over
this structure is achieved by folding (hiding) large parts of the
document to show only the general document structure and the parts
currently being worked on. Org-mode greatly simplifies the use of
outlines by compressing the entire show/hide functionality into a
single command @command{org-cycle}, which is bound to the @key{TAB}
key.
@node Headlines, Visibility cycling, Outlines, Document Structure
@section Headlines
@cindex headlines
@cindex outline tree
Headlines define the structure of an outline tree. The Headlines in
Org-mode start with one or more stars, for example
@example
* Top level headline
** Second level
*** 3rd level
some text
*** 3rd level
more text
* Another top level headline
@end example
@node Visibility cycling, Motion, Headlines, Document Structure
@section Visibility cycling
@cindex visibility cycling
@cindex trees, visibility
Outlines make it possible to hide parts of the text in the buffer.
Org-mode uses a single command bound to the @key{TAB} key to change
the visibility in the buffer.
@cindex subtree visibility states
@cindex folded, subtree visibility state
@cindex children, subtree visibility state
@cindex subtree, subtree visibility state
@table @kbd
@kindex @key{TAB}
@item @key{TAB}
Rotate current subtree between the states
@example
,-> FOLDED -> CHILDREN -> SUBTREE --.
'-----------------------------------'
@end example
At the beginning of the buffer (or when called with @kbd{C-u}), this does
the same as the command @kbd{S-@key{TAB}} below.
@cindex global visibility states
@cindex overview, global visibility state
@cindex contents, global visibility state
@cindex show all, global visibility state
@kindex S-@key{TAB}
@item S-@key{TAB}
Rotate the entire buffer between the states
@example
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
'--------------------------------------'
@end example
Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
@cindex show all, command
@kindex C-c C-a
@item C-c C-a
Show all.
@end table
@node Motion, Structure editing, Visibility cycling, Document Structure
@section Motion
@cindex motion, between headlines
@cindex jumping, to headlines
The following commands jump to other headlines in the buffer.
@table @kbd
@kindex C-c C-n
@item C-c C-n
Next heading.
@kindex C-c C-p
@item C-c C-p
Previous heading.
@kindex C-c C-f
@item C-c C-f
Next heading same level.
@kindex C-c C-b
@item C-c C-b
Previous heading same level.
@kindex C-c C-u
@item C-c C-u
Backward to higher level heading.
@kindex C-c C-j
@item C-c C-j
Jump to a different place without changing the current outline
visibility. Shows the document structure in a temporary buffer, where
you can use visibility cycling (@key{TAB}) to find your destination.
After pressing @key{RET}, the cursor moves to the selected location in
the original buffer, and the headings hierarchy above it is made
visible.
@end table
@node Structure editing, Sparse trees, Motion, Document Structure
@section Structure editing
@cindex structure editing
@cindex headline, promotion and demotion
@cindex promotion, of subtrees
@cindex demotion, of subtrees
@cindex subtree, cut and paste
@cindex pasting, subtrees
@cindex cutting, subtrees
@cindex copying, subtrees
@table @kbd
@kindex M-@key{RET}
@item M-@key{RET}
Insert new heading with same level as current
@kindex M-@key{left}
@item M-@key{left}
Promote current heading by one level
@kindex M-@key{right}
@item M-@key{right}
Demote current heading by one level
@kindex M-S-@key{left}
@item M-S-@key{left}
Promote the current subtree by one level
@kindex M-S-@key{right}
@item M-S-@key{right}
Demote the current subtree by one level
@kindex M-S-@key{up}
@item M-S-@key{up}
Move subtree up (swap with previous subtree of same level)
@kindex M-S-@key{down}
@item M-S-@key{down}
Move subtree down (swap with next subtree of same level)
@kindex C-c C-h C-w
@item C-c C-h C-w
Kill subtree, i.e. remove it from buffer but save in kill ring.
@kindex C-c C-h M-w
@item C-c C-h M-w
Copy subtree to kill ring.
@kindex C-c C-h C-y
@item C-c C-h C-y
Yank subtree from kill ring. This does modify the level of subtree to
make sure the tree fits in nicely at the yank position. The yank
level can also be specified with a prefix arg, or by yanking after a
headline marker like @samp{****}.
@end table
@cindex region, active
@cindex active region
@cindex transient-mark-mode
When there is an active region (transient-mark-mode), promotion and
demotion work on all headlines in the region. To select a region of
headlines, it is best to place both point and mark at the beginning of a
line, mark at the beginning of the first headline, and point at the line
just after the last headline to change. Note that when the cursor is
inside a table (@pxref{Tables}), the Meta-Cursor keys have different
functionality.
@node Sparse trees, , Structure editing, Document Structure
@section Sparse trees
@cindex sparse trees
@cindex trees, sparse
@cindex folding, sparse trees
@cindex occur, command
An important feature of Org-mode is the ability to construct
@emph{sparse trees} for selected information in an outline tree. A
sparse tree means that the entire document is folded as much as
possible, but the selected information is made visible along with the
headline structure above it. Just try it out and you will see
immediately how it works.
Org-mode contains several commands creating such trees. The most
basic one is @command{org-occur}:
@table @kbd
@kindex C-c /
@item C-c /
Occur. Prompts for a regexp and shows a sparse tree with all matches.
If the match is in a headline, the headline is made visible. If the
match is in the body of an entry, headline and body are made visible.
In order to provide minimal context, also the full hierarchy of
headlines above the match is shown, as well as the headline following
the match.
@end table
Other commands are using this feature as well. For example @kbd{C-c
C-v} creates a sparse TODO tree (@pxref{TODO basics}).
@node TODO items, Tables, Document Structure, Top
@chapter TODO items
@cindex TODO items
Org-mode does not maintain TODO lists as a separate document. TODO
items are an integral part of the notes file, because TODO items
usually come up while taking notes! With Org-mode, you simply mark
any entry in a tree as being a TODO item. In this way, the
information is not duplicated, and the entire context from which the
item emerged is always present when you check.
Of course, this technique causes TODO items to be scattered throughout
your file. Org-mode provides methods to give you an overview over all
things you have to do.
@menu
* TODO basics:: Marking and displaying TODO entries
* Priorities:: Some things are more important than others
* TODO extensions:: Workflow and assignments
@end menu
@node TODO basics, Priorities, TODO items, TODO items
@section Basic TODO functionality
Any headline can become a TODO item by starting it with the word TODO,
for example
@example
*** TODO Write letter to Sam Fortune
@end example
@noindent
The most important commands to work with TODO entries are:
@table @kbd
@kindex C-c C-t
@item C-c C-t
Rotate the TODO state of the current item between
@example
,-> (unmarked) -> TODO -> DONE --.
'--------------------------------'
@end example
@kindex C-c C-v
@cindex sparse tree, for TODO
@item C-c C-v
View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds
the entire buffer, but shows all TODO items and the headings hierarchy
above them. With prefix arg, show also the DONE entries.
@end table
@node Priorities, TODO extensions, TODO basics, TODO items
@section Priorities
@cindex priorities
If you use Org-mode extensively to organize your work, you may end up
with a number of TODO entries so large that you'd like to prioritize
them. You can do this by placing a @emph{priority cookie} into the
headline, like this
@example
*** TODO [#A] Write letter to Sam Fortune
@end example
@noindent
With its standard setup, Org-mode supports priorities @samp{A},
@samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry
without a cookie is treated as priority @samp{B}. Priorities make a
difference only in the multi-file agenda (@pxref{Agenda (multiple files)}).
@table @kbd
@kindex @kbd{C-c ,}
@item @kbd{C-c ,}
Set the priority of the current item. The command prompts for a
priority character @samp{A}, @samp{B} or @samp{C}. When you press
@key{SPC} instead, the priority cookie is removed from the headline.
@kindex S-@key{up}
@kindex S-@key{down}
@item S-@key{up}
@itemx S-@key{down}
Increase/decrease priority of current item. Note that these keys are
also used to modify time stamps (@pxref{Creating timestamps}).
@end table
@node TODO extensions, , Priorities, TODO items
@section Extended use of TODO keywords
@cindex extended TODO keywords
The default implementation of TODO entries is just two states: TODO
and DONE. You can, however, use the TODO feature for more
complicated things by configuring the variables
@code{org-todo-keywords} and @code{org-todo-interpretation}. Using
special setup, you can even use TODO keywords in different ways in
different org files.
@menu
* Workflow states:: From TODO to DONE in steps
* TODO types:: I do this, Fred the rest
* Per file keywords:: Different files, different requirements
@end menu
@node Workflow states, TODO types, TODO extensions, TODO extensions
@subsection TODO keywords as workflow states
@cindex TODO workflow
@cindex workflow states as TODO keywords
You can use TODO keywords to indicate different states in the process
of working on an item, for example
@lisp
(setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE")
org-todo-interpretation 'sequence)
@end lisp
With this setup, the command @kbd{C-c C-t} will cycle an entry from
TODO to FEEDBACK, then to VERIFY, and finally too DONE. You may also
use a prefix argument to quickly select a specific state. For example
@kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
If you define many keywords, you can use in-buffer completion (see
@ref{Completion}) to insert these words into the buffer.
@node TODO types, Per file keywords, Workflow states, TODO extensions
@subsection TODO keywords as types
@cindex TODO types
@cindex names as TODO keywords
@cindex types as TODO keywords
The second possibility is to use TODO keywords to indicate different
types of action items. For example, when you work with several people
on a single project, you might want to assign action items to
persons.
@lisp
(setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
org-todo-interpretation 'type)
@end lisp
In this case, different keywords do not indicate a sequence, but
rather different levels. This changes the behavior of the command
@kbd{C-c C-t} slightly. When used several times in succession, it
will still cycle through all names. But when when you return to the
item after some time and execute @kbd{C-c C-t} again, it will switch
from each name directly to DONE. Use prefix arguments or completion
to quickly select a specific name.
@node Per file keywords, , TODO types, TODO extensions
@subsection Setting up TODO keywords for individual files
@cindex keyword options
@cindex per file keywords
It can be very useful to use different aspects of the TODO mechanism
in different files. For this you need to add special lines to the
file which set the keywords and interpretation for that file only.
For example, to set one of the two examples discussed above, you
need one of the following lines, starting in column zero anywhere in
the file:
@example
#+SEQ_TODO: TODO FEEDBACK VERIFY DONE
#+TYP_TODO: Fred Sara Lucy Mike DONE
@end example
@cindex Completing option keywords
@kindex M-@key{TAB}
@noindent To make sure you are using the correct keyword, type
@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
@cindex DONE, final TODO keyword
Remember that the last keyword must always mean that the
item is DONE (you may use a different word, though). After changing
these lines, use @kbd{M-x normal-mode} to make the changes known to
Org-mode. Also note that in each file, only one of the two aspects
of TODO keywords can be used.
If you want to use very many keywords, for example when working with a
large group of people, you may split the names over several lines: