comparison man/org.texi @ 70133:36d1ec75581c

* org.texi: (Time stamps): Better explanation of the purpose of different time stamps. (Structure editing, Plain lists): More details on how new items and headings are inserted.

70132:f8b9335f0cad

@c %**start of header
@c @setfilename org
@setfilename ../info/org
@settitle Org Mode Manual

@set VERSION 4.24
@set DATE April 2006

@dircategory Emacs
@direntry
* Org Mode: (org).	outline-based notes management and organizer

@insertcopying
@end ifnottex

@menu
* Introduction::                Getting started
* 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
* Timestamps::                  Assign date and time to items
* Tags::                        Tagging headlines and matching sets of tags
* Agenda Views::                Collecting information into views
* 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

* Summary::                     Brief summary of what Org-mode does
* Installation and activation::  How to install Org-mode
* Feedback::                    Bug reports, ideas, patches etc.

Document Structure

* Outlines::                    Org-mode is based on outline-mode
* Headlines::                   How to typeset org-tree headlines
* Visibility cycling::          Show and hide, much simplified
* Motion::                      Jumping to other headlines
* Structure editing::           Changing sequence and level of headlines
* Archiving::                   Move done task trees to a different place
* Sparse trees::                Matches embedded in context
* Plain Lists::                 Editing hand-formatted lists

Tables

* Built-in table editor::       Simple tables
* Narrow columns::              Stop wasting space in tables   

* Tag inheritance::             Tags use the tree structure of the outline
* Setting tags::                How to assign tags to a headline
* Tag searches::                Searching for combinations of tags

Agenda Views

* Agenda files::                Files being searched for agenda information
* Agenda dispatcher::           Keyboard access to agenda views
* Weekly/Daily Agenda::         The calendar page with current tasks
* Global TODO list::            All unfinished action items
* Matching headline tags::      Structured information with fine-tuned search
* Timeline::                    Time-sorted view for single file
* Agenda commands::             Remote editing of org trees

* Acknowledgments::             These people provided feedback and more

@end detailmenu
@end menu

@node Introduction, Document Structure, Top, Top
@chapter Introduction
@cindex introduction

@menu
* Summary::                     Brief summary of what Org-mode does

@item What did you expect to happen?
@item What happened instead?
@end enumerate
@noindent Thank you for helping to improve this mode.

@node Document Structure, Tables, Introduction, Top
@chapter Document Structure
@cindex document structure
@cindex structure of document

Org-mode is based on outline mode and provides flexible commands to

* Visibility cycling::          Show and hide, much simplified
* Motion::                      Jumping to other headlines
* Structure editing::           Changing sequence and level of headlines
* Archiving::                   Move done task trees to a different place
* Sparse trees::                Matches embedded in context
* Plain Lists::                 Editing hand-formatted lists
@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

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

@noindent Some people find the many stars too noisy and would prefer an
outline that has whitespace followed by a single star as headline
starters.  @ref{Clean view} describes a setup to realize this.

@node Visibility cycling, Motion, Headlines, Document Structure
@section Visibility cycling
@cindex cycling, visibility
@cindex visibility cycling
@cindex trees, visibility
@cindex show hidden text

#+STARTUP: overview
#+STARTUP: content
#+STARTUP: showall
@end example

@node Motion, Structure editing, Visibility cycling, Document Structure
@section Motion
@cindex motion, between headlines
@cindex jumping, to headlines
@cindex headline navigation
The following commands jump to other headlines in the buffer.

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, Archiving, Motion, Document Structure
@section Structure editing
@cindex structure editing
@cindex headline, promotion and demotion
@cindex promotion, of subtrees
@cindex demotion, of subtrees

@table @kbd
@kindex M-@key{RET}
@item M-@key{RET}
Insert new heading with same level as current.  If the cursor is in a
plain list item, a new item is created.  To force creation of a new
headline, use a prefix arg, or first press @key{RET} to get to the
beginning of the next line.
@kindex M-S-@key{RET}
@item M-S-@key{RET}
Insert new TODO entry with same level as current heading.
@kindex M-@key{left}
@item M-@key{left}

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 Archiving, Sparse trees, Structure editing, Document Structure
@section Archiving
@cindex archiving
@cindex filing subtrees

When a project represented by a (sub)tree is finished, you may want

this, see the documentation string of the variable
@code{org-archive-location}.  If you are also using the Org-mode
agenda, archiving to a different file is a good way to keep archived
trees from contributing agenda items.

@node Sparse trees, Plain Lists, Archiving, Document Structure
@section Sparse trees
@cindex sparse trees
@cindex trees, sparse
@cindex folding, sparse trees
@cindex occur, command

Or you can use the command @kbd{C-c C-x v} to copy the visible part of
the document to another file (extension @file{.txt}) which can then be
printed in any desired way.


@node Plain Lists,  , Sparse trees, Document Structure
@section Plain Lists
@cindex plain lists
@cindex lists, plain
@cindex lists, ordered
@cindex ordered lists

given by the indentation of the bullet/number.  However, items are
always subordinate to real headlines, the hierarchies remain
completely separated.
@kindex M-@key{RET}
@item M-@key{RET}
Insert new item at current level.  With prefix arg, for a new heading.
@kindex M-S-@key{up}
@kindex M-S-@key{down}
@item M-S-@key{up}
@itemx M-S-@key{down}
Move the item including subitems up/down (swap with previous/next item

@kindex C-c C-c
@item C-c C-c
Renumber the ordered list at the cursor.
@end table

@node Tables, Hyperlinks, Document Structure, Top
@chapter Tables
@cindex tables
@cindex editing tables

Org-mode has a very fast and intuitive table editor built-in.

@example
# <<My Target>>
@end example

If no dedicated target exists, Org-mode will search for the words in the
link, often removing the need for a dedicated target.  In the above
example the search would be for @samp{my target}.  Links starting with a
star like @samp{*My Target} restrict the search to headlines.  When
searching, Org-mode will first try an exact match, but then move on to

@item C-u C-c C-l
When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
a file will be inserted and you may use file name completion to select
the name of the file.  The path to the file is inserted relative to the
directory of the current org file, if the linked file is in the current
directory or in a subdirectory of it.  Otherwise an absolute path, if
possible with @samp{~/} for your home directory is used.  You can force
an absolute path with two @kbd{C-u} prefixes.

@item C-c C-l @r{with cursor on existing link}
When the cursor is on an existing link, @kbd{C-c C-l} allows to edit the
link and description parts of the link.

@item 255
Jump to line 255.
@item My Target
Search for a link target @samp{<<My Target>>}, or do a text search for
@samp{my target}, similar to the search in internal links, see
@ref{Internal links}.
@item *My Target
In an Org-mode file, restrict search to headlines.
@item /regexp/
Do a regular expression search for @code{regexp}.  This uses the Emacs
command @code{occur} to list all matches in a separate window.  If the

numerical prefix N, show the tree for the Nth keyword in the variable
@code{org-todo-keywords}.
@kindex C-c a t
@item C-c a t
Show the global TODO list.  This collects the TODO items from all
agenda files (@pxref{Agenda Views}) into a single buffer.  The buffer is in
@code{agenda-mode}, so there are commands to examine and manipulate
the TODO entries directly from that buffer (@pxref{Agenda commands}).
@xref{Global TODO list}, for more information.
@item @code{org-agenda-include-all-todo}
If you would like to have all your TODO items listed as part of your

Then each time you turn a TODO entry into DONE using either @kbd{C-c
C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
@samp{CLOSED: [timestamp]} will be inserted just after the headline.
If you turn the entry back into a TODO item again through further
state cycling, that line will be removed again.  In the timeline
(@pxref{Timeline}) and in the agenda (@pxref{Weekly/Daily Agenda}),
you can then use the @kbd{L} key to display the TODO items closed on
each day, giving you an overview of what has been done on a day.

@node TODO extensions, Priorities, Progress logging, TODO items
@section Extended use of TODO keywords

@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 agenda (@pxref{Weekly/Daily Agenda}).

@table @kbd
@kindex @kbd{C-c ,}
@item @kbd{C-c ,}
Set the priority of the current item.  The command prompts for a

A time stamp is a specification of a date (possibly with time) in a
special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16
Tue 09:39>}.  A time stamp can appear anywhere in the headline or body
of an org-tree entry.  Its presence allows entries to be shown on specific
dates in the agenda (@pxref{Weekly/Daily Agenda}).  We distinguish:

@table @var
@cindex timestamp
@item TIMESTAMP
A simple time stamp just assigns a date/time to an item.  In the
timeline and agenda displays, the headline of the entry will be shown
exactly on that date.

@item TIMERANGE
@cindex timerange
Two time stamps connected by @samp{--} denote a time range.  The
headline will be shown on the first and last day of the range, and on

example:

@example
** Meeting in Amsterdam
   <2004-08-23 Mon>--<2004-08-26 Thu>
@end example

@item DEADLINE
@cindex DEADLINE keyword
If a time stamp is preceded by the word @samp{DEADLINE:}, the task

@example
*** TODO write article about the Earth for the Guide
    The editor in charge is <bbdb:Ford Prefect>
    DEADLINE: <2004-02-29 Sun>
@end example

@item SCHEDULED
@cindex SCHEDULED keyword
If a time stamp is preceded by the word @samp{SCHEDULED:}, it means
you are planning to start working on that task on the given date.  The
headline will be listed under the given date.  In addition, a reminder
that the scheduled date has passed will be present in the compilation
for @emph{today}, until the entry is marked DONE.  I.e., the
task will automatically be forwarded.
@end table

@node Creating timestamps,  , Time stamps, Timestamps
@section Creating timestamps
@cindex creating timestamps

instead.

@kindex C-c C-o
@item C-c C-o
Access the agenda for the date given by the time stamp at point
(@pxref{Weekly/Daily Agenda}).

@kindex C-c C-d
@item C-c C-d
Insert @samp{DEADLINE} keyword along with a stamp.
@kindex C-c C-w

@kindex @key{RET}
@item @key{RET}
Choose date in calendar (only if nothing typed into minibuffer).
@end table

@node Tags, Agenda Views, Timestamps, Top
@chapter Tags
@cindex tags
@cindex headline tagging
@cindex matching, tags
@cindex sparse tree, tag based

@samp{:BOSS:}.  The search string @samp{WORK|LAPTOP} selects all lines
tagged @samp{:WORK:} or @samp{:LAPTOP:}.  The string
@samp{WORK|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are
also tagged @samp{NIGHT}.

@node Agenda Views, Exporting, Tags, Top
@chapter Agenda Views
@cindex agenda views

Due to the way Org-mode works, TODO items, time-stamped items, and
tagged headlines can be scattered throughout a file or even a number of

edit these files remotely.

@menu
* Agenda files::                Files being searched for agenda information
* Agenda dispatcher::           Keyboard access to agenda views
* Weekly/Daily Agenda::         The calendar page with current tasks
* Global TODO list::            All unfinished action items
* Matching headline tags::      Structured information with fine-tuned search
* Timeline::                    Time-sorted view for single file
* Agenda commands::             Remote editing of org trees
@end menu

@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views
@section Agenda files

The information to be shown is collected from all @emph{agenda files},
the files listed in the variable @code{org-agenda-files}@footnote{If the
value of that variable is not a list, but a single file name, then the

@noindent
The Org menu contains the current list of files and can be used
to visit any of them.

@node Agenda dispatcher, Weekly/Daily Agenda, Agenda files, Agenda Views
@section The agenda dispatcher
@cindex agenda dispatcher
@cindex dispatching agenda commands
@cindex custom agenda commands
@cindex agenda commands, custom

commands accordingly.  After pressing @kbd{C-c a}, an additional
letter is required to execute a command.  The dispatcher offers the
following default commands:
@table @kbd
@item a
Create the calendar-like agenda (@pxref{Weekly/Daily Agenda}).
@item t / T
Create a list of all TODO items (@pxref{Global TODO list}).
@item m / M
Create a list of headlines matching a TAGS expression (@pxref{Matching
headline tags}).

current buffer and display the result as a sparse tree, and @kbd{C-c a
f} to create a sparse tree with all entries containing the word
@samp{FIXME}.  For more information, look at the documentation string
of the variable @code{org-agenda-custom-commands}.

@node Weekly/Daily Agenda, Global TODO list, Agenda dispatcher, Agenda Views
@section The weekly/daily agenda
@cindex 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.

* Time-of-day specifications::  How the agenda knows the time
* Calendar/Diary integration::  Integrating Anniversaries and more
* Sorting of agenda items::     The order of things
@end menu

@node Categories, Time-of-day specifications, Weekly/Daily Agenda, Weekly/Daily Agenda
@subsection Categories

@cindex category
In the agenda buffer, each entry is preceded by a @emph{category},
which is derived from the file name.  The category can also be set

If there are several such lines in a file, each specifies the category
for the text below it (but the first category also applies to any text
before the first CATEGORY line).  The display in the agenda buffer looks
best if the category is not longer than 10 characters.

@node Time-of-day specifications, Calendar/Diary integration, Categories, Weekly/Daily Agenda
@subsection Time-of-Day Specifications

Org-mode checks each agenda item for a time-of-day specification.  The
time can be part of the time stamp that triggered inclusion into the
agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}.  Time

The time grid can be turned on and off with the variable
@code{org-agenda-use-time-grid}, and can be configured with
@code{org-agenda-time-grid}.


@node Calendar/Diary integration, Sorting of agenda items, Time-of-day specifications, Weekly/Daily Agenda
@subsection Calendar/Diary integration
@cindex calendar integration
@cindex diary integration

Emacs contains the calendar and diary by Edward M. Reingold.  The

well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
Sunrise/Sunset times, show lunar phases and to convert to other
calendars, respectively.  @kbd{c} can be used to switch back and forth
between calendar and agenda.

@node Sorting of agenda items,  , Calendar/Diary integration, Weekly/Daily Agenda
@subsection Sorting of agenda items
@cindex sorting, of agenda items
@cindex priorities, of agenda items
The entries for each day are sorted.  The default order is to first
collect all items containing an explicit time-of-day specification.

Sorting can be customized using the variable
@code{org-agenda-sorting-strategy}.


@node Global TODO list, Matching headline tags, Weekly/Daily Agenda, Agenda Views
@section The global TODO list
@cindex global TODO list
@cindex TODO list, global

The global TODO list contains all unfinished TODO items, formatted and

@table @kbd
@kindex C-c a t
@item C-c a t
Show the global TODO list.  This collects the TODO items from all
agenda files (@pxref{Agenda Views}) into a single buffer.  The buffer is in
@code{agenda-mode}, so there are commands to examine and manipulate
the TODO entries directly from that buffer (@pxref{Agenda commands}).
@xref{Global TODO list}, for more information.
@kindex C-c a T
@item C-c a T

Remote editing of TODO items means that you can change the state of a
TODO entry with a single key press.  The commands available in the
TODO list are described in @ref{Agenda commands}.

@node Matching headline tags, Timeline, Global TODO list, Agenda Views
@section Matching headline tags
@cindex matching, of tags
@cindex tags view

If headlines in the agenda files are marked with @emph{tags}

@end table

The commands available in the tags list are described in @ref{Agenda
commands}.

@node Timeline, Agenda commands, Matching headline tags, Agenda Views
@section Timeline for a single file
@cindex single file summary
@cindex agenda, for single file
@cindex timeline, single file
@cindex time-sorted view

@noindent
The commands available in the timeline buffer are listed in
@ref{Agenda commands}.

@node Agenda commands,  , Timeline, Agenda Views
@section Commands in the agenda buffer
@cindex commands, in agenda buffer

Entries in the agenda buffer are linked back to the org file or diary
file where they originate.  You are not allowed to edit the agenda

for the compilation of the agenda.  Buffers created by the user to
visit org files will not be removed.

@end table

@node Exporting, Miscellaneous, Agenda Views, Top
@chapter Exporting
@cindex exporting

Org-mode documents can be exported into a variety of other formats.  For
printing and sharing of notes, ASCII export produces a readable and

Remember to execute @kbd{M-x normal-mode} after changing this to make
the new style visible to Emacs.  This command restarts org-mode for the
current buffer and forces Emacs to re-evaluate the local variables
section in the buffer.

@node XML export, iCalendar export, HTML export, Exporting
@section XML export
@cindex XML export

@cindex hand-formatted lists
@cindex lists, hand-formatted
@item
Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
or @samp{2)} as enumerator will be recognized and transformed if the
backend supports lists.  See @xref{Plain Lists}.

@cindex underlined text
@cindex bold text
@cindex italic text
@item

70133:36d1ec75581c

@c %**start of header
@c @setfilename org
@setfilename ../info/org
@settitle Org Mode Manual

@set VERSION 4.25
@set DATE April 2006

@dircategory Emacs
@direntry
* Org Mode: (org).	outline-based notes management and organizer

@insertcopying
@end ifnottex

@menu
* Introduction::                Getting started
* 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
* Timestamps::                  Assign date and time to items
* Tags::                        Tagging headlines and matching sets of tags
* Agenda views::                Collecting information into views
* 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

* Summary::                     Brief summary of what Org-mode does
* Installation and activation::  How to install Org-mode
* Feedback::                    Bug reports, ideas, patches etc.

Document structure

* Outlines::                    Org-mode is based on outline-mode
* Headlines::                   How to typeset org-tree headlines
* Visibility cycling::          Show and hide, much simplified
* Motion::                      Jumping to other headlines
* Structure editing::           Changing sequence and level of headlines
* Archiving::                   Move done task trees to a different place
* Sparse trees::                Matches embedded in context
* Plain lists::                 Editing hand-formatted lists

Tables

* Built-in table editor::       Simple tables
* Narrow columns::              Stop wasting space in tables   

* Tag inheritance::             Tags use the tree structure of the outline
* Setting tags::                How to assign tags to a headline
* Tag searches::                Searching for combinations of tags

Agenda views

* Agenda files::                Files being searched for agenda information
* Agenda dispatcher::           Keyboard access to agenda views
* Weekly/Daily agenda::         The calendar page with current tasks
* Global TODO list::            All unfinished action items
* Matching headline tags::      Structured information with fine-tuned search
* Timeline::                    Time-sorted view for single file
* Agenda commands::             Remote editing of org trees

* Acknowledgments::             These people provided feedback and more

@end detailmenu
@end menu

@node Introduction, Document structure, Top, Top
@chapter Introduction
@cindex introduction

@menu
* Summary::                     Brief summary of what Org-mode does

@item What did you expect to happen?
@item What happened instead?
@end enumerate
@noindent Thank you for helping to improve this mode.

@node Document structure, Tables, Introduction, Top
@chapter Document Structure
@cindex document structure
@cindex structure of document

Org-mode is based on outline mode and provides flexible commands to

* Visibility cycling::          Show and hide, much simplified
* Motion::                      Jumping to other headlines
* Structure editing::           Changing sequence and level of headlines
* Archiving::                   Move done task trees to a different place
* Sparse trees::                Matches embedded in context
* Plain lists::                 Editing hand-formatted lists
@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

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

@noindent Some people find the many stars too noisy and would prefer an
outline that has whitespace followed by a single star as headline
starters.  @ref{Clean view} describes a setup to realize this.

@node Visibility cycling, Motion, Headlines, Document structure
@section Visibility cycling
@cindex cycling, visibility
@cindex visibility cycling
@cindex trees, visibility
@cindex show hidden text

#+STARTUP: overview
#+STARTUP: content
#+STARTUP: showall
@end example

@node Motion, Structure editing, Visibility cycling, Document structure
@section Motion
@cindex motion, between headlines
@cindex jumping, to headlines
@cindex headline navigation
The following commands jump to other headlines in the buffer.

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, Archiving, Motion, Document structure
@section Structure editing
@cindex structure editing
@cindex headline, promotion and demotion
@cindex promotion, of subtrees
@cindex demotion, of subtrees

@table @kbd
@kindex M-@key{RET}
@item M-@key{RET}
Insert new heading with same level as current.  If the cursor is in a
plain list item, a new item is created (@pxref{Plain lists}).  To force
creation of a new headline, use a prefix arg, or first press @key{RET}
to get to the beginning of the next line.  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.  If the command is used at the beginning of a
headline, the new headline is created before the current line.  It at
the beginning of any other line, the content of that line is made the
new heading.
@kindex M-S-@key{RET}
@item M-S-@key{RET}
Insert new TODO entry with same level as current heading.
@kindex M-@key{left}
@item M-@key{left}

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 Archiving, Sparse trees, Structure editing, Document structure
@section Archiving
@cindex archiving
@cindex filing subtrees

When a project represented by a (sub)tree is finished, you may want

this, see the documentation string of the variable
@code{org-archive-location}.  If you are also using the Org-mode
agenda, archiving to a different file is a good way to keep archived
trees from contributing agenda items.

@node Sparse trees, Plain lists, Archiving, Document structure
@section Sparse trees
@cindex sparse trees
@cindex trees, sparse
@cindex folding, sparse trees
@cindex occur, command

Or you can use the command @kbd{C-c C-x v} to copy the visible part of
the document to another file (extension @file{.txt}) which can then be
printed in any desired way.


@node Plain lists,  , Sparse trees, Document structure
@section Plain lists
@cindex plain lists
@cindex lists, plain
@cindex lists, ordered
@cindex ordered lists

given by the indentation of the bullet/number.  However, items are
always subordinate to real headlines, the hierarchies remain
completely separated.
@kindex M-@key{RET}
@item M-@key{RET}
Insert new item at current level.  With prefix arg, force a new heading
(@pxref{Structure editing}).  If this command is used in the middle of a
line, the line is @emph{split} and the rest of the line becomes the new
item.  If this command is executed in the @emph{whitespace before a bullet or
number}, the new item is created @emph{before} the current item.  If the
command is executed in the white space before the text that is part of
an item but does not contain the bullet, a bullet is added to the
current line.
@kindex M-S-@key{up}
@kindex M-S-@key{down}
@item M-S-@key{up}
@itemx M-S-@key{down}
Move the item including subitems up/down (swap with previous/next item

@kindex C-c C-c
@item C-c C-c
Renumber the ordered list at the cursor.
@end table

@node Tables, Hyperlinks, Document structure, Top
@chapter Tables
@cindex tables
@cindex editing tables

Org-mode has a very fast and intuitive table editor built-in.

@example
# <<My Target>>
@end example

@noindent In HTML export (@pxref{HTML export}), such targets will become
named anchors for direct access through http links.

If no dedicated target exists, Org-mode will search for the words in the
link, often removing the need for a dedicated target.  In the above
example the search would be for @samp{my target}.  Links starting with a
star like @samp{*My Target} restrict the search to headlines.  When
searching, Org-mode will first try an exact match, but then move on to

@item C-u C-c C-l
When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
a file will be inserted and you may use file name completion to select
the name of the file.  The path to the file is inserted relative to the
directory of the current org file, if the linked file is in the current
directory or in a subdirectory of it, or if the path is written relative
to the current directory using @samp{../}.  Otherwise an absolute path
is used, if possible with @samp{~/} for your home directory.  You can
force an absolute path with two @kbd{C-u} prefixes.

@item C-c C-l @r{with cursor on existing link}
When the cursor is on an existing link, @kbd{C-c C-l} allows to edit the
link and description parts of the link.

@item 255
Jump to line 255.
@item My Target
Search for a link target @samp{<<My Target>>}, or do a text search for
@samp{my target}, similar to the search in internal links, see
@ref{Internal links}.  In HTML export (@pxref{HTML export}), such a file
link will become an html reference to the corresponding named anchor in
the linked file.
@item *My Target
In an Org-mode file, restrict search to headlines.
@item /regexp/
Do a regular expression search for @code{regexp}.  This uses the Emacs
command @code{occur} to list all matches in a separate window.  If the

numerical prefix N, show the tree for the Nth keyword in the variable
@code{org-todo-keywords}.
@kindex C-c a t
@item C-c a t
Show the global TODO list.  This collects the TODO items from all
agenda files (@pxref{Agenda views}) into a single buffer.  The buffer is in
@code{agenda-mode}, so there are commands to examine and manipulate
the TODO entries directly from that buffer (@pxref{Agenda commands}).
@xref{Global TODO list}, for more information.
@item @code{org-agenda-include-all-todo}
If you would like to have all your TODO items listed as part of your

Then each time you turn a TODO entry into DONE using either @kbd{C-c
C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
@samp{CLOSED: [timestamp]} will be inserted just after the headline.
If you turn the entry back into a TODO item again through further
state cycling, that line will be removed again.  In the timeline
(@pxref{Timeline}) and in the agenda (@pxref{Weekly/Daily agenda}),
you can then use the @kbd{L} key to display the TODO items closed on
each day, giving you an overview of what has been done on a day.

@node TODO extensions, Priorities, Progress logging, TODO items
@section Extended use of TODO keywords

@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 agenda (@pxref{Weekly/Daily agenda}).

@table @kbd
@kindex @kbd{C-c ,}
@item @kbd{C-c ,}
Set the priority of the current item.  The command prompts for a

A time stamp is a specification of a date (possibly with time) in a
special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16
Tue 09:39>}.  A time stamp can appear anywhere in the headline or body
of an org-tree entry.  Its presence allows entries to be shown on specific
dates in the agenda (@pxref{Weekly/Daily agenda}).  We distinguish:

@table @var
@cindex timestamp
@item TIMESTAMP
A simple time stamp just assigns a date/time to an item.  This is just
like writing down an appointment in a paper agenda, or like writing down
an event in a diary, when you want to take not of when something
happened.  In the timeline and agenda displays, the headline of an entry
associated with a plain time stamp will be shown exactly on that date.

@item TIMERANGE
@cindex timerange
Two time stamps connected by @samp{--} denote a time range.  The
headline will be shown on the first and last day of the range, and on

example:

@example
** Meeting in Amsterdam
   <2004-08-23 Mon>--<2004-08-26 Thu>
@end example

@item SCHEDULED
@cindex SCHEDULED keyword
If a time stamp is preceded by the word @samp{SCHEDULED:}, it means you
are planning to start working on that task on the given date. So this is
not about recording an event, but about planning your work.  The
headline will be listed under the given date.  In addition, a reminder
that the scheduled date has passed will be present in the compilation
for @emph{today}, until the entry is marked DONE.  I.e., the task will
automatically be forwarded until completed.

@example
*** TODO Call Trillian to ask her out for a date on New Years Eve.
    SCHEDULED: <2004-12-25 Sat>
@end example

@item DEADLINE
@cindex DEADLINE keyword
If a time stamp is preceded by the word @samp{DEADLINE:}, the task

@example
*** TODO write article about the Earth for the Guide
    The editor in charge is <bbdb:Ford Prefect>
    DEADLINE: <2004-02-29 Sun>
@end example
@end table

@node Creating timestamps,  , Time stamps, Timestamps
@section Creating timestamps
@cindex creating timestamps

instead.

@kindex C-c C-o
@item C-c C-o
Access the agenda for the date given by the time stamp at point
(@pxref{Weekly/Daily agenda}).

@kindex C-c C-d
@item C-c C-d
Insert @samp{DEADLINE} keyword along with a stamp.
@kindex C-c C-w

@kindex @key{RET}
@item @key{RET}
Choose date in calendar (only if nothing typed into minibuffer).
@end table

@node Tags, Agenda views, Timestamps, Top
@chapter Tags
@cindex tags
@cindex headline tagging
@cindex matching, tags
@cindex sparse tree, tag based

@samp{:BOSS:}.  The search string @samp{WORK|LAPTOP} selects all lines
tagged @samp{:WORK:} or @samp{:LAPTOP:}.  The string
@samp{WORK|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are
also tagged @samp{NIGHT}.

@node Agenda views, Exporting, Tags, Top
@chapter Agenda Views
@cindex agenda views

Due to the way Org-mode works, TODO items, time-stamped items, and
tagged headlines can be scattered throughout a file or even a number of

edit these files remotely.

@menu
* Agenda files::                Files being searched for agenda information
* Agenda dispatcher::           Keyboard access to agenda views
* Weekly/Daily agenda::         The calendar page with current tasks
* Global TODO list::            All unfinished action items
* Matching headline tags::      Structured information with fine-tuned search
* Timeline::                    Time-sorted view for single file
* Agenda commands::             Remote editing of org trees
@end menu

@node Agenda files, Agenda dispatcher, Agenda views, Agenda views
@section Agenda files

The information to be shown is collected from all @emph{agenda files},
the files listed in the variable @code{org-agenda-files}@footnote{If the
value of that variable is not a list, but a single file name, then the

@noindent
The Org menu contains the current list of files and can be used
to visit any of them.

@node Agenda dispatcher, Weekly/Daily agenda, Agenda files, Agenda views
@section The agenda dispatcher
@cindex agenda dispatcher
@cindex dispatching agenda commands
@cindex custom agenda commands
@cindex agenda commands, custom

commands accordingly.  After pressing @kbd{C-c a}, an additional
letter is required to execute a command.  The dispatcher offers the
following default commands:
@table @kbd
@item a
Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
@item t / T
Create a list of all TODO items (@pxref{Global TODO list}).
@item m / M
Create a list of headlines matching a TAGS expression (@pxref{Matching
headline tags}).

current buffer and display the result as a sparse tree, and @kbd{C-c a
f} to create a sparse tree with all entries containing the word
@samp{FIXME}.  For more information, look at the documentation string
of the variable @code{org-agenda-custom-commands}.

@node Weekly/Daily agenda, Global TODO list, Agenda dispatcher, Agenda views
@section The weekly/daily agenda
@cindex 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.

* Time-of-day specifications::  How the agenda knows the time
* Calendar/Diary integration::  Integrating Anniversaries and more
* Sorting of agenda items::     The order of things
@end menu

@node Categories, Time-of-day specifications, Weekly/Daily agenda, Weekly/Daily agenda
@subsection Categories

@cindex category
In the agenda buffer, each entry is preceded by a @emph{category},
which is derived from the file name.  The category can also be set

If there are several such lines in a file, each specifies the category
for the text below it (but the first category also applies to any text
before the first CATEGORY line).  The display in the agenda buffer looks
best if the category is not longer than 10 characters.

@node Time-of-day specifications, Calendar/Diary integration, Categories, Weekly/Daily agenda
@subsection Time-of-Day Specifications

Org-mode checks each agenda item for a time-of-day specification.  The
time can be part of the time stamp that triggered inclusion into the
agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}.  Time

The time grid can be turned on and off with the variable
@code{org-agenda-use-time-grid}, and can be configured with
@code{org-agenda-time-grid}.


@node Calendar/Diary integration, Sorting of agenda items, Time-of-day specifications, Weekly/Daily agenda
@subsection Calendar/Diary integration
@cindex calendar integration
@cindex diary integration

Emacs contains the calendar and diary by Edward M. Reingold.  The

well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
Sunrise/Sunset times, show lunar phases and to convert to other
calendars, respectively.  @kbd{c} can be used to switch back and forth
between calendar and agenda.

@node Sorting of agenda items,  , Calendar/Diary integration, Weekly/Daily agenda
@subsection Sorting of agenda items
@cindex sorting, of agenda items
@cindex priorities, of agenda items
The entries for each day are sorted.  The default order is to first
collect all items containing an explicit time-of-day specification.

Sorting can be customized using the variable
@code{org-agenda-sorting-strategy}.


@node Global TODO list, Matching headline tags, Weekly/Daily agenda, Agenda views
@section The global TODO list
@cindex global TODO list
@cindex TODO list, global

The global TODO list contains all unfinished TODO items, formatted and

@table @kbd
@kindex C-c a t
@item C-c a t
Show the global TODO list.  This collects the TODO items from all
agenda files (@pxref{Agenda views}) into a single buffer.  The buffer is in
@code{agenda-mode}, so there are commands to examine and manipulate
the TODO entries directly from that buffer (@pxref{Agenda commands}).
@xref{Global TODO list}, for more information.
@kindex C-c a T
@item C-c a T

Remote editing of TODO items means that you can change the state of a
TODO entry with a single key press.  The commands available in the
TODO list are described in @ref{Agenda commands}.

@node Matching headline tags, Timeline, Global TODO list, Agenda views
@section Matching headline tags
@cindex matching, of tags
@cindex tags view

If headlines in the agenda files are marked with @emph{tags}

@end table

The commands available in the tags list are described in @ref{Agenda
commands}.

@node Timeline, Agenda commands, Matching headline tags, Agenda views
@section Timeline for a single file
@cindex single file summary
@cindex agenda, for single file
@cindex timeline, single file
@cindex time-sorted view

@noindent
The commands available in the timeline buffer are listed in
@ref{Agenda commands}.

@node Agenda commands,  , Timeline, Agenda views
@section Commands in the agenda buffer
@cindex commands, in agenda buffer

Entries in the agenda buffer are linked back to the org file or diary
file where they originate.  You are not allowed to edit the agenda

for the compilation of the agenda.  Buffers created by the user to
visit org files will not be removed.

@end table

@node Exporting, Miscellaneous, Agenda views, Top
@chapter Exporting
@cindex exporting

Org-mode documents can be exported into a variety of other formats.  For
printing and sharing of notes, ASCII export produces a readable and

Remember to execute @kbd{M-x normal-mode} after changing this to make
the new style visible to Emacs.  This command restarts org-mode for the
current buffer and forces Emacs to re-evaluate the local variables
section in the buffer.

@c FIXME: More about header and footer styles
@c FIXME: Talk about links and targets.

@node XML export, iCalendar export, HTML export, Exporting
@section XML export
@cindex XML export

@cindex hand-formatted lists
@cindex lists, hand-formatted
@item
Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
or @samp{2)} as enumerator will be recognized and transformed if the
backend supports lists.  See @xref{Plain lists}.

@cindex underlined text
@cindex bold text
@cindex italic text
@item