@setfilename ../info/org
@settitle Org Mode Manual
-@set VERSION 3.16
-@set DATE September 2005
+@set VERSION 3.23
+@set DATE December 2005
@dircategory Emacs
@direntry
* 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
Hyperlinks
-* Links:: URL-like links to the world
+* Internal Links:: CamelCaseWords as internal links
+* External Links:: URL-like links to the world
+* Managing links:: Creating, inserting and following
+* Search Options:: Linking to a specific location
* Remember:: Org-trees store quick notes
TODO items
Exporting
-* Export commands:: Commands which export and display
+* ASCII export:: Export as a structured ASCII file
+* HTML export:: Export as an HTML file
+* iCalendar export:: Create calendar entries.
+
+HTML export
+
* HTML formatting:: Interpretation of the buffer content
* Export options:: How to influence exports
* Comment lines:: Lines which will not be exported
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.
+structured ASCII file, as HTML, or (todo and agenda items only) as an
+iCalendar file.
-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
+Org-mode keeps simple things simple. When first fired up, it should
+feel like a simple but easy to use outliner. Complexity is not
+imposed, but a large amount of functionality is available when you
+need 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 an ASCII table editor with some spreadsheet-like capabilities}
+@r{@bullet{} as an ASCII table editor with spreadsheet-like capabilities}
@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}
If Org-mode is part of the Emacs distribution or an XEmacs package,
you only need to copy the following lines to your @file{.emacs} file.
-The last two lines define @emph{global} keys for the commands
-@command{org-store-link} and @command{org-agenda} - please choose
-suitable keys yourself.
+The last three lines define @emph{global} keys for the commands
+@command{org-store-link}, @command{org-agenda}, and
+@code{org-todo-list} - please choose suitable keys yourself.
@lisp
;; The following lines are always needed. Choose your own keys.
(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)
+(define-key global-map "\C-ct" 'org-todo-list)
@end lisp
If you have downloaded Org-mode from the Web, you must byte-compile
(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-todo-list "org" "Global TODO list from Org mode" t)
(autoload 'org-store-link "org" "Store a link to the current location" t)
(autoload 'orgtbl-mode "org" "Org tables as a minor mode" t)
(autoload 'turn-on-orgtbl "org" "Org tables as a minor mode")
* 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
@cindex outline tree
Headlines define the structure of an outline tree. The Headlines in
-Org-mode start with one or more stars, for example
+Org-mode start with one or more stars, on the left margin. For
+example
@example
* Top level headline
@table @kbd
@kindex M-@key{RET}
@item M-@key{RET}
-Insert new heading with same level as current
+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.
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)
+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)
agenda, archiving to a different file is a good way to keep archived
trees from contributing agenda items.
-@node Sparse trees, , Archiving, Document Structure
+@node Sparse trees, Plain Lists, Archiving, Document Structure
@section Sparse trees
@cindex sparse trees
@cindex trees, sparse
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.
+the match. Each match is also highlighted, the highlights disappear
+when the buffer is changed with an editing command.
@end table
Other commands are using this feature as well. For example @kbd{C-c
the document to another file (extension @file{.txt}) which then can be
printed in any desired way.
+@node Plain Lists, , Sparse trees, Document Structure
+@section Plain Lists
+@cindex plain lists
+@cindex lists, plain
+
+Headlines define the structure of the Org-mode file, and also lists
+(for example TODO items (@pxref{TODO items}) should be created using
+headline levels. However, when taking notes, the plain text is
+sometimes easier to read with hand-formatted lists. Org-mode supports
+editing such lists, and the HTML exporter (@pxref{Exporting}) does
+parse and format them.
+
+Org-mode knows ordered and unordered lists. Unordered list items
+start with @samp{-}, @samp{+}, or @samp{*}@footnote{When using
+@samp{*} as a bullet, lines must be indented or they will be seen as
+top-level headlines.} as bullets. Ordered list items start with
+@samp{1.} or @samp{1)}. Items belonging to the same list must have
+the same indentation on the first line. In particular, if an ordered
+list reaches number @samp{10.}, also the 2--digit numbers must be
+written left-aligned with the other numbers in the list. Indentation
+also determines the end of a list item. It ends before the next line
+that is indented like the bullet/number, or less. For example:
+
+@example
+** Lord of the Rings
+My favorite scenes are (in this order)
+1. Eowyns fight with the witch king
+ + this was already my favorite scene in the book
+ + I really like Miranda Otto.
+2. The attack of the Rohirrim
+3. Peter Jackson being shot by Legolas
+ - on DVD only
+ He makes a really funny face when it happens.
+@end example
+
+Org-mode supports these lists by tuning filling and wrapping commands
+to correctly deal with them. Futhermore, the following commands act
+on items when the cursor is in the first line of an item (the line
+with the bullet or number).
+
+@table @kbd
+@kindex @key{TAB}
+@item @key{TAB}
+Items can be folded just like headline levels if you set the variable
+@code{org-cycle-include-plain-lists}. The level of an item is then
+given by the indentation of the bullet/number. However, items are
+always subortinate 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
+of same intentation). If the list is ordered, renumbering is
+automatic.
+@kindex M-S-@key{left}
+@kindex M-S-@key{right}
+@item M-S-@key{left}
+@itemx M-S-@key{right}
+Decrease/increase the indentation of the item, including subitems.
+Initially, the item tree is selected based on current indentation.
+When these commands are executed several times in direct succession,
+the initially selected region is used, even if the new indentation
+would imply a different hierarchy. To use the new hierarchy, break
+the command chain with a cursor motion or so.
+@kindex 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
Insert a horizontal line below current row. With prefix arg, the line
is created above the current line.
+@kindex C-c ^
+@item C-c ^
+Sort the table lines in the region. Point and mark must be in the first
+and last line to be included, and must be in the column that should be
+used for sorting. The command prompts for numerical versus
+alphanumerical sorting.
+
@tsubheading{Regions}
@kindex C-c C-x M-w
@item C-c C-x M-w
@end example
The range vectors can be directly fed into the calc vector functions
-like functions @samp{vmean} and @samp{vsum}.
+like @samp{vmean} and @samp{vsum}.
@samp{$name} is interpreted as the name of a column, parameter or
constant. Constants are defined globally through the variable
@code{org-table-formula-constants}. If you have the
@file{constants.el} package, it will also be used to resolve
-constants, including natural constants like @samp{$k} for Planck's
+constants, including natural constants like @samp{$h} for Planck's
constant, units like @samp{$km} for kilometers. Column names and
parameters can be specified in special table lines. These are
described below, see @ref{Advanced features}.
The fields in this line define names for the columns, so that you may
refer to a column as @samp{$Tot} instead of @samp{$6}.
@item ^
-This row define names for the fields @emph{above} the row. With such
+This row defines names for the fields @emph{above} the row. With such
a definition, any formula in the table may use @samp{$m1} to refer to
the value @samp{10}. Also, named fields can have their own formula
associated with them.
@item _
Similar to @samp{^}, but defines names for the fields in the row
-@emph{below}.
+@emph{below}.
@item $
Fields in this row can define @emph{parameters} for formulas. For
example, if a field in a @samp{$} row contains @samp{max=50}, then
Selects this line for global recalculation with @kbd{C-u C-c *}, but
not for automatic recalculation. Use this when automatic
recalculation slows down editing too much.
-@item
+@item
Unmarked lines are exempted from recalculation with @kbd{C-u C-c *}.
All lines that should be recalculated should be marked with @samp{#}
or @samp{*}.
@kindex C-c C-c
You may edit the @samp{#+TBLFM} directly and re-apply
the changed equations with @kbd{C-c C-c} in that line, or with the
-normal recalculation commands in the table.
+normal recalculation commands in the table.
@kindex C-c '
@kindex C-c C-c
@chapter Hyperlinks
@cindex hyperlinks
-Just like HMTL, Org-mode provides links to other files, Usenet
-articles, emails and much more.
+Just like HMTL, Org-mode provides links inside a file, and external
+links to other files, Usenet articles, emails and much more.
@menu
-* Links:: URL-like links to the world
+* Internal Links:: CamelCaseWords as internal links
+* External Links:: URL-like links to the world
+* Managing links:: Creating, inserting and following
+* Search Options:: Linking to a specific location
* Remember:: Org-trees store quick notes
@end menu
-@node Links, Remember, Hyperlinks, Hyperlinks
-@section Links
+@node Internal Links, External Links, Hyperlinks, Hyperlinks
+@section Internal Links
+@cindex internal links
+@cindex links, internal
+@cindex CamelCase links
+
+Similar to Wiki implementations, Org-mode interprets words spelled in
+CamelCase (i.e. mixed case with at least one capital letter following
+on a small letter inside the word) as links. While in Wiki
+implementations these links usually point to another file, in Org-mode
+they point to a target in the current file. Targets are CamelCased
+words in double angular brackets, and may be located anywhere, also in
+a comment line. For example
+@example
+# <<MyTarget>>
+@end example
+
+Each occurence of @samp{MyTarget} in the file is an active link that
+can be followed with @kbd{C-c C-o} or with a mouse click
+(@pxref{Managing links}). If no dedicated target exists, org-mode will
+search for the words in the link separated by white space, in the
+above example for @samp{my target}. If the link starts with a star
+like @samp{*MyTarget}, the search is restricted to headlines.
+Org-mode will first try an exact match of a full headline, but then
+move on to more and more lenient searches. The link @samp{*MyTargets}
+will find any of the following
+@example
+** My targets
+** TODO my targets are bright
+** my 20 targets are
+@end example
+@cindex completion, of CamelCase links
+@cindex CamelCase links, completion of
+It is therefore often not even necessary to set a dedicated target.
+The link will automatically find a target. If you want to see what
+lines in the current buffer are matched by a given CamelCase link,
+open the link with @kbd{C-u C-c C-o}. Even if there are several
+matches, org-mode will usually find the right one since it tries
+targets and exact matches first. To insert links targeting a
+headline, in-buffer completion can be used. Just type a star followed
+by a few optional letters into the buffer and press @kbd{M-@key{TAB}}.
+CamelCased versions of all headlines in the current buffer will be
+offered as completions. @xref{Managing links}, for more commands
+creating links.
+
+@node External Links, Managing links, Internal Links, Hyperlinks
+@section External Links
@cindex links
+@cindex external links
+@cindex links, external
@cindex GNUS links
@cindex BBDB links
@cindex URL links
<http://www.astro.uva.nl/~dominik> @r{on the web}
<file:/home/dominik/images/jupiter.jpg> @r{file, absolute path}
<file:papers/last.pdf> @r{file, relative path}
-<file:~/code/main.c:255> @r{file, with line number}
<news:comp.emacs> @r{Usenet link}
<mailto:adent@@galaxy.net> @r{Mail link}
<vm:folder> @r{VM folder link}
recommended to avoid problems with punctuation and other text following
the link. See also the variable @code{org-allow-space-in-links}.
-@cindex storing links
+
+@node Managing links, Search Options, External Links, Hyperlinks
+@section Managing links
+
+Org-mode provides methods to create a link in the correct syntax, to
+insert it into an org-mode file, and to follow the link.
+
@table @kbd
@kindex C-c l
+@cindex storing links
@item C-c l
Store a link to the current location. This is a @emph{global} command
which can be used in any buffer to create a link. The link will be
-stored for later insertion into an Org-mode buffer (see below). For VM,
-RMAIL, WANDERLUST, GNUS and BBDB buffers, the link will point to the
-current article/entry. For W3 and W3M buffer, the link goes to the
-current URL. For any other files, the link will just point to the file.
-The key binding @kbd{C-c l} is only a suggestion - see
-@ref{Installation and Activation}.
+stored for later insertion into an Org-mode buffer (see below). For
+VM, RMAIL, WANDERLUST, GNUS and BBDB buffers, the link will point to
+the current article/entry. For W3 and W3M buffer, the link goes to
+the current URL. For Org-mode files, the current headline is
+targeted. For any other files, the link will point to the file, with
+a CamelCase (@pxref{Search Options}) search string pointing to the
+contents of the current line. If there is an active region, the
+selected words will form the basis of the search string. The key
+binding @kbd{C-c l} is only a suggestion - see @ref{Installation and
+Activation}.
@kindex C-c C-l
@cindex completion, of links
Like @kbd{mouse-2}, but force file links to be opened with Emacs.
@end table
-@node Remember, , Links, Hyperlinks
+
+@node Search Options, Remember, Managing links, Hyperlinks
+@section Search options in file links
+
+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@footnote{For backward
+compatibility, line numbers can also follow a single colon.} colon.
+For example:
+@example
+<file:~/code/main.c::255>
+<file:~/xx.org::MyTarget>
+<file:~/xx.org::find me>
+<file:~/xx.org::/regexp/>
+@end example
+@noindent Here is what these options do.
+
+@table @code
+@item 255
+Jump to line 255.
+@item MyGoal
+Search for a link target with name MyGoal, or do a text search for
+@samp{my target}, similar to the CamelCase search in internal links,
+see @ref{Internal Links}.
+@item find me
+Do a normal text search for the text @samp{find me}.
+@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
+target file is in Org-mode, @code{org-occur} is used to create a
+sparse tree with the matches.
+@c If the target file is a directory,
+@c @code{grep} will be used to search all files in the directory.
+@end table
+
+To use the search options also for a search in the current file, a
+file link with an empty file name can be used. For example,
+@code{<file:::find me>} does a search for @samp{find me} in the
+current file.
+
+@node Remember, , Search Options, Hyperlinks
@section Remember
@cindex @file{remember.el}
to file away notes either to a default file, or directly to the
correct location in your Org-mode outline tree. The following
customization@footnote{The two autoload forms are only necessary if
-@file{org.el} is not part of the Emacs distribution or and XEmacs
+@file{org.el} is not part of the Emacs distribution or an XEmacs
package.} will tell @emph{Remember} to use org files as target, and to
create annotations compatible with Org-mode links.
@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.
+above them. With prefix arg, show also the DONE entries. With
+numerical prefix N, show the tree for the Nth keyword in the variable
+@code{org-todo-keywords}.
+@kindex C-c t
+@item C-c t
+Show the global TODO list. This collects the TODO items from all
+agenda files (@pxref{Agenda}) 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}).
+A prefix argument can be used to collect only TODO entries of a
+particular type. With a C-u prefix you are prompted for a keyword.
+With a numeric prefix, the Nth keyword in @code{org-todo-keywords} is
+selected.
+@kindex r
+The @kbd{r} key in the agenda
+buffer regenerates it, and you can give a prefix argument to this
+command to change the selected TODO keyword, for example @kbd{3 r}.
+The key binding @kbd{C-c t} is only a suggestion - see
+@ref{Installation and Activation}.
+@kindex C-u C-c a
@item C-u C-c a
A @kbd{C-u} argument to the @code{org-agenda command} (@pxref{Agenda})
-collects all unfinished TODO items into a single place.
+includes all unfinished TODO items at the beginning of todays agenda.
@end table
@node TODO extensions, Priorities, TODO basics, TODO items
The second possibility is to use TODO keywords to indicate different
types of action items. For example, you might want to indicate that
-items are for ``work'' or ``home''. Or, when you work with several
-people on a single project, you might want to assign action items
-directly to persons, by using their names as TODO keywords. This
-would be set up like this:
+items are for ``work'' or ``home''. If you are into David Allen's
+@emph{Getting Things DONE}, you might want to use todo types
+@samp{NEXTACTION}, @samp{WAITING}, @samp{MAYBE}. Or, when you work
+with several people on a single project, you might want to assign
+action items directly to persons, by using their names as TODO
+keywords. This would be set up like this:
@lisp
(setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
command @kbd{C-c C-t} is changed slightly@footnote{This is also true
for the @kbd{t} command in the timeline and agenda buffers.}. When
used several times in succession, it will still cycle through all
-names. But 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.
+names. But 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.
+You can also review the items of a specific TODO type in a sparse tree
+by using a numeric prefix to @kbd{C-c C-v}. For example, to see all
+things Lucy has to do, you would use @kbd{C-3 C-c C-v}. To collect
+collect Lucy's items from all agenda files into a single buffer, you
+would use the prefix arg as well when creating the global todo list:
+@kbd{C-3 C-c t}.
@node Per file keywords, , TODO types, TODO extensions
@subsection Setting up TODO keywords for individual files
(@pxref{Interaction}).
@end table
-
-
@node Timestamps, Timeline and Agenda, TODO items, Top
@chapter Timestamps
@kindex C-c !
@item C-c !
Like @kbd{C-c .}, but insert an inactive time stamp not triggering the
-agenda.
+agenda.
@kindex C-c <
@item C-c <
@table @kbd
@kindex C-c [
@item C-c [
-Add current file to the list of agenda files
+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 prefix arg, file is added/moved to the end.
@kindex C-c ]
@item C-c ]
Remove current file from the list of agenda files.
+@kindex C-,
+@item C-,
+Cycle through agenda file list.
@end table
@noindent
The Org menu contains the list of all files and can be used to quickly
@example
#+CATEGORY: Thesis
@end example
-@noindent
-After changing this line, press @kbd{C-c C-c} with the cursor still in
-the line, to make the changes known to org-mode. Otherwise, the
-change will only be active the next time you visit this file with
-Emacs.
-
-The display in the agenda buffer looks best if the category is not
-longer than 10 characters.
+If there are several such lines in a file, each specifies the category
+for the text below it. The display in the agenda buffer looks best if
+the category is not longer than 10 characters.
@subsection Time-of-Day Specifications
@item r
Recreate the agenda buffer, for example to reflect the changes
after modification of the time stamps of items with S-@key{left} and
-S-@key{right}.
+S-@key{right}. When the buffer is the global todo list, a prefix
+argument is interpreted to create a selective list for a specific TODO
+keyword.
@kindex @key{right}
@item @key{right}
@item H
Show holidays for three month around the cursor date.
+@kindex C-c C-x C-c
+@item C-c C-x C-c
+Export a single iCalendar file containing entries from all agenda files.
+Not available in timelines.
+
@tsubheading{Quit and Exit}
@kindex q
@item q
@node Exporting, Miscellaneous, Timeline and Agenda, Top
@chapter Exporting
@cindex exporting
-@cindex ASCII export
-@cindex HTML export
-@cindex headline levels, for exporting
-For printing and sharing of notes, an Org-mode document can be
-exported as an ASCII file, or as HTML. In the exported version, the
-first 3 outline levels will become headlines, defining a general
-document structure. Additional levels will be exported as itemize
-lists. If you want that transition to occur at a different level,
-specify it with a prefix argument. For example,
-
-@example
-@kbd{M-1 M-x org-export-as-html}
-@end example
-@noindent
-creates only top level headlines and does the rest as items.
+For printing and sharing of notes, Org-mode documents can be exported
+as ASCII or HTML files. To incorporate entries with associated times
+like deadlines or appointments into a desktop calendar program like
+iCal, Org-mode can also produce extracts in the iCalendar format.
@menu
-* 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
+* ASCII export:: Export as a structured ASCII file
+* HTML export:: Export as an HTML file
+* iCalendar export:: Create calendar entries.
@end menu
-@node Export commands, HTML formatting, Exporting, Exporting
-@section Export commands
+@node ASCII export, HTML export, Exporting, Exporting
+@section ASCII export
+@cindex ASCII export
@cindex region, active
@cindex active region
will be exported. For an org file @file{myfile.org}, the ASCII file
will be @file{myfile.txt}. The file will be overwritten without
warning.
+@end table
+
+@cindex headline levels, for exporting
+In the exported version, the first 3 outline levels will become
+headlines, defining a general document structure. Additional levels
+will be exported as itemize lists. If you want that transition to occur
+at a different level, specify it with a prefix argument. For example,
+@example
+@kbd{C-1 C-c C-x a org-export-as-ascii}
+@end example
+@noindent
+creates only top level headlines and does the rest as items. Lines
+starting with @samp{#} and subtrees starting with the word @samp{COMMENT}
+will not be exported.
+
+@node HTML export, iCalendar export, ASCII export, Exporting
+@section HTML export
+@cindex HTML export
+
+Org-mode contains an HTML exporter with extensive HTML formatting, in
+ways similar to John Grubers @emph{markdown} language, but with
+additional support for tables.
+
+@cindex region, active
+@cindex active region
+@cindex transient-mark-mode
+@table @kbd
@kindex C-c C-x h
@item C-c C-x h
Export as HTML file @file{myfile.html}.
Toggle fixed-width for entry (QUOTE) or region, see below.
@end table
-@node HTML formatting, Export options, Export commands, Exporting
-@section HTML formatting
+@cindex headline levels, for exporting
+In the exported version, the first 3 outline levels will become
+headlines, defining a general document structure. Additional levels
+will be exported as itemize lists. If you want that transition to occur
+at a different level, specify it with a prefix argument. For example,
+@example
+@kbd{C-2 C-c C-x b}
+@end example
+@noindent
+creates two levels of headings and does the rest as items.
+
+@menu
+* HTML formatting:: Interpretation of the buffer content
+* Export options:: How to influence exports
+* Comment lines:: Lines which will not be exported
+@end menu
+
+@node HTML formatting, Export options, HTML export, HTML export
+@subsection HTML formatting
Not all text is transferred literally to the exported HTML file. The
exporter implements the following interpretation:
@itemize @bullet
+
+@cindex hand-formatted lists
+@cindex lists, hand-formatted
+@item
+Hand-formatted lists with @samp{-}, @samp{*} or @samp{+} as
+bullet, or with @samp{1.} or @samp{2)} as enumerator will be recognized and
+transformed into HTML lists. See @xref{Plain Lists}.
+
@cindex underlined text
@cindex bold text
@cindex italic text
If these conversions conflict with your habits of typing ASCII text,
they can all be turned off with corresponding variables.
-@node Export options, Comment lines, HTML formatting, Exporting
-@section Export options
+@node Export options, Comment lines, HTML formatting, HTML export
+@subsection Export options
@cindex options, for export
@cindex completion, of option keywords
TeX: @r{turn on/off @TeX{} macros}
@end example
-@node Comment lines, , Export options, Exporting
-@section Comment lines
+You can also give style information for the exported file. The
+default specification can be configured through the option
+@code{org-export-html-style}. If you want to use a file-local style,
+you may use file variables, best wrapped into a COMMENT section at the
+end of the outline tree. For example:
+
+@example
+* COMMENT HTML style specifications
+
+# Local Variables:
+# org-export-html-style: " <style type=\"text/css\">
+ p @{font-weight: normal; color: gray; @}
+ h1 @{color: black; @}
+ </style>"
+# End: ***
+@end example
+
+Remember to execute @kbd{M-x normal-mode} after changing this to make
+the new style visible to Emacs.
+
+@node Comment lines, , Export options, HTML export
+@subsection Comment lines
@cindex comment lines
@cindex exporting, not
Lines starting with @samp{#} in column zero are treated as comments
and will never be exported. Also entire subtrees starting with the
word @samp{COMMENT} will never be exported. Finally, any text before
-the first headline will not be exported either.
+the first headline will not be exported either. This applies also for
+ASCII export.
@table @kbd
@kindex C-c ;
Toggle the COMMENT keyword at the beginning of an entry.
@end table
+@node iCalendar export, , HTML export, Exporting
+@section iCalendar export
+
+Some people like to use Org-mode for keeping track of projects, but
+still prefer a standard calendar application for anniversaries and
+appointments. In this case it can be useful to have deadlines and
+other time-stamped items in Org-mode files show up in the calendar
+application. Org-mode can export calendar information in the standard
+iCalendar format.
+
+@table @kbd
+@kindex C-c C-x i
+@item C-c C-x i
+Create iCalendar entries for the current file and store them in the same
+directory, using a file extension @file{.ics}.
+@kindex C-c C-x C-i
+@item C-c C-x C-i
+Like @kbd{C-c C-x i}, but do this for all files in
+@code{org-agenda-files}. For each of these files, a separate iCalendar
+file will be written.
+@kindex C-c C-x c
+@item C-c C-x c
+Create a single large iCalendar file from all files in
+@code{org-agenda-files} and write it to the file given by
+@code{org-combined-agenda-icalendar-file}.
+@end table
+
+How this calendar is best read and updated, depends on the application
+you are using. For example, when using iCal under Apple MacOS X, you
+could create a new calendar @samp{OrgMode} (the default name for the
+calendar created by @kbd{C-c C-x c}, see the variables
+@code{org-icalendar-combined-name} and
+@code{org-combined-agenda-icalendar-file}). Then set Org-mode to
+overwrite the corresponding file
+@file{~/Library/Calendars/OrgMode.ics}. You may even use AppleScript
+to make iCal re-read the calendar files each time a new version of
+@file{OrgMode.ics} is produced. Here is the setup needed for this:
+
+@lisp
+(setq org-combined-agenda-icalendar-file
+ "~/Library/Calendars/OrgMode.ics")
+(add-hook 'org-after-save-iCalendar-file-hook
+ (lambda ()
+ (shell-command
+ "osascript -e 'tell application \"iCal\" to reload calendars'")))
+@end lisp
+
@node Miscellaneous, Index, Exporting, Top
@chapter Miscellaneous
@cindex completion, of TODO keywords
@cindex completion, of dictionary words
@cindex completion, of option keywords
+@cindex completion, of CamelCase links
Org-mode supports in-buffer completion. This type of completion does
not make use of the minibuffer. You simply type a few letters into
@item
After @samp{\}, complete @TeX{} symbols supported by the exporter.
@item
+After @samp{*}, complete CamelCase versions of all headlines in the
+buffer.
+@item
After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
@samp{OPTIONS} which set file-specific options for Org-mode. When the
option keyword is already complete, pressing @kbd{M-@key{TAB}} again
@i{before} the horizontal line. How can I quickly move to the line
@i{below} the horizontal line instead?}@*
Press @key{down} (to get on the separator line) and then @key{TAB}.
+Or configure the variable @code{org-table-tab-jumps-over-hlines}.
@item @b{How can I change the indentation of an entire table without
fixing every line by hand?}@*
have found too hard to fix.
@itemize @bullet
-@item
-If you call @code{fill-paragraph} (bound to @kbd{M-q}) in a table, the
-filling is correctly disabled. However, if some text directly
-(without an empty line in between) precedes or follows a table, calling
-@code{fill-paragraph} in that text will also fill the table like
-normal text. Also, @code{fill-region} does bypass the
-@code{fill-paragraph} code and will fill tables like normal text.
+@c @item
+@c If you call @code{fill-paragraph} (bound to @kbd{M-q}) in a table, the
+@c filling is correctly disabled. However, if some text directly
+@c (without an empty line in between) precedes or follows a table, calling
+@c @code{fill-paragraph} in that text will also fill the table like
+@c normal text. Also, @code{fill-region} does bypass the
+@c @code{fill-paragraph} code and will fill tables like normal text.
@item
Text in an entry protected with the @samp{QUOTE} keyword should not
autowrap.
Juergen Vollmer contributed code generating the table of contents
in HTML output, and other export improvements.
@item
-Christian Egli converted the documentation into TeXInfo format. He
-also showed me his plans for a multifile summary for Org-mode. Some of
-his ideas have found their way into the agenda.
+Christian Egli converted the documentation into TeXInfo format and
+patched basic CSS formatting support into the HTML exporter. He also
+inspired the agenda by showing me his plans for a multifile summary.
@item
Philip Rooke created the Org-mode reference card. He also helped with
beta testing and contributed a number of very useful ideas.
@item
Scheduling TODO items was inspired by John Wiegley's @file{planner.el}.
@item
-Sacha Chua, the current maintainer of Planner, offered linking code
-from Planner. I made use of the offer for links to RMAIL and Wanderlust.
+Sacha Chua, the current maintainer of Planner, suggested to copy
+linking code from Planner (I took code for RMAIL and Wanderlust).
@item
-Oliver Oppitz sent several useful suggestions.
+Oliver Oppitz made useful suggestions.
@item
Carsten Wimmer suggested some changes and helped fix a bug in linking
to GNUS.
@item
Kai Grossjohann pointed out that a number of key bindings in Org-mode
conflict with other packages.
-@item
-Roland Winkler pointed out that additional keybindings are need to use
-Org-mode on a tty.
+@item
+Roland Winkler pointed out that additional keybindings are needed to
+use Org-mode on a tty.
+@item
+Tim O'Callaghan suggested in-file links, and search options for
+general file links.
+@c @item
+@c Nic Ferrier and Christian Egli implemented XML export.
@end itemize
@node Index, Key Index, Miscellaneous, Top