@setfilename ../info/org
@settitle Org Mode Manual
-@set VERSION 4.22
+@set VERSION 4.25
@set DATE April 2006
@dircategory Emacs
@menu
* Introduction:: Getting started
-* Document Structure:: A tree works like your brain
+* 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
+* 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
* Installation and activation:: How to install Org-mode
* Feedback:: Bug reports, ideas, patches etc.
-Document Structure
+Document structure
* Outlines:: Org-mode is based on outline-mode
* Headlines:: How to typeset org-tree 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
+* Plain lists:: Editing hand-formatted lists
Tables
* Setting tags:: How to assign tags to a headline
* Tag searches:: Searching for combinations of tags
-Agenda Views
+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
+* 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
Exporting
-* ASCII export:: Export as a structured ASCII file
-* HTML export:: Export as an HTML file
-* iCalendar export:: Create calendar entries.
+* ASCII export:: Exporting to plain ASCII
+* HTML export:: Exporting to HTML
+* XML export:: Exporting to XML
+* iCalendar export:: Exporting in iCalendar format
+* Text interpretation:: How the exporter looks at the file
-HTML export
+Text interpretation by the exporter
-* HTML formatting:: Interpretation of the buffer content
-* Export options:: How to influence exports
-* Comment lines:: Lines which will not be exported
+* Comment lines:: Some lines will not be exported
+* Enhancing text:: Subscripts, symbols and more
+* Export options:: How to influence the export settings
Miscellaneous
* Completion:: M-TAB knows what you need
* Customization:: Adapting Org-mode to your taste
-* Updating settings:: How to tell Org-mode that settings have changed
+* Summary of in-buffer settings:: Using special lines to set options
+* The very busy C-c C-c key:: When in doubt, press C-c C-c
* Clean view:: Getting rid of leading stars in the outline
* TTY keys:: Using Org-mode on a tty
* FAQ:: Frequently asked questions
@end detailmenu
@end menu
-@node Introduction, Document Structure, Top, Top
+@node Introduction, Document structure, Top, Top
@chapter Introduction
@cindex introduction
@end enumerate
@noindent Thank you for helping to improve this mode.
-@node Document Structure, Tables, Introduction, Top
+@node Document structure, Tables, Introduction, Top
@chapter Document Structure
@cindex document structure
@cindex structure of document
* 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
+* Plain lists:: Editing hand-formatted lists
@end menu
-@node Outlines, Headlines, Document Structure, Document Structure
+@node Outlines, Headlines, Document structure, Document structure
@section Outlines
@cindex outlines
@cindex outline-mode
single command @command{org-cycle}, which is bound to the @key{TAB}
key.
-@node Headlines, Visibility cycling, Outlines, Document Structure
+@node Headlines, Visibility cycling, Outlines, Document structure
@section Headlines
@cindex headlines
@cindex outline tree
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
+@node Visibility cycling, Motion, Headlines, Document structure
@section Visibility cycling
@cindex cycling, visibility
@cindex visibility cycling
buffer:
@example
-#+STARTUP: fold
-#+STARTUP: nofold
+#+STARTUP: overview
#+STARTUP: content
+#+STARTUP: showall
@end example
-@node Motion, Structure editing, Visibility cycling, Document Structure
+@node Motion, Structure editing, Visibility cycling, Document structure
@section Motion
@cindex motion, between headlines
@cindex jumping, to headlines
visible.
@end table
-@node Structure editing, Archiving, Motion, Document Structure
+@node Structure editing, Archiving, Motion, Document structure
@section Structure editing
@cindex structure editing
@cindex headline, promotion and demotion
@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.
+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.
inside a table (@pxref{Tables}), the Meta-Cursor keys have different
functionality.
-@node Archiving, Sparse trees, Structure editing, Document Structure
+@node Archiving, Sparse trees, Structure editing, Document structure
@section Archiving
@cindex archiving
@cindex filing subtrees
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
+@node Sparse trees, Plain lists, Archiving, Document structure
@section Sparse trees
@cindex sparse trees
@cindex trees, sparse
printed in any desired way.
-@node Plain Lists, , Sparse trees, Document Structure
-@section Plain Lists
+@node Plain lists, , Sparse trees, Document structure
+@section Plain lists
@cindex plain lists
@cindex lists, plain
@cindex lists, ordered
completely separated.
@kindex M-@key{RET}
@item M-@key{RET}
-Insert new item at current level. With prefix arg, for a new heading.
+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}
Renumber the ordered list at the cursor.
@end table
-@node Tables, Hyperlinks, Document Structure, Top
+@node Tables, Hyperlinks, Document structure, Top
@chapter Tables
@cindex tables
@cindex editing tables
Convert the active region to table. If every line contains at least one
TAB character, the function assumes that the material is tab separated.
If not, lines are split at whitespace into fields. You can use a prefix
-argument to indicate the minimum number of consequtive spaces required
-to indentify a field separator (default: just one).@*
+argument to indicate the minimum number of consecutive spaces required
+to identify a field separator (default: just one).@*
If there is no active region, this command creates an empty Org-mode
table. However, it's easier to just start typing, like
@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
The width of columns is automatically determined by the table editor.
Sometimes a single field or a few fields need to carry more text,
-leading to unconveniently wide columns. To limit@footnote{This feature
+leading to inconveniently wide columns. To limit@footnote{This feature
does not work on XEmacs.} the width of a column, one field anywhere in
the column must carry the string @samp{<N>} where @samp{N} is an integer
specifying the width of the column in characters. The next re-align
@file{calc} package. Note that @file{calc} has the slightly
non-standard convention that @samp{/} has lower precedence than
@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}. Before
-evaluation by @code{calc-eval} (@pxref{Calling Calc from Your Lisp
+evaluation by @code{calc-eval} (@pxref{Calling Calc from Your
Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU Emacs
Calc Manual}), variable substitution takes place:
# <<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
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.
+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
@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}.
+@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/
@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
+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.
@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}),
+(@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.
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}).
+difference only in the agenda (@pxref{Weekly/Daily agenda}).
@table @kbd
@kindex @kbd{C-c ,}
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:
+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.
+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
<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
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
@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}).
+(@pxref{Weekly/Daily agenda}).
@kindex C-c C-d
@item C-c C-d
Choose date in calendar (only if nothing typed into minibuffer).
@end table
-@node Tags, Agenda Views, Timestamps, Top
+@node Tags, Agenda views, Timestamps, Top
@chapter Tags
@cindex tags
@cindex headline tagging
@samp{WORK|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are
also tagged @samp{NIGHT}.
-@node Agenda Views, Exporting, Tags, Top
+@node Agenda views, Exporting, Tags, Top
@chapter Agenda Views
@cindex agenda views
@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
+* 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
+@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 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
+@node Agenda dispatcher, Weekly/Daily agenda, Agenda files, Agenda views
@section The agenda dispatcher
@cindex agenda dispatcher
@cindex dispatching agenda commands
following default commands:
@table @kbd
@item a
-Create the calendar-like agenda (@pxref{Weekly/Daily Agenda}).
+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
@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
+@node Weekly/Daily agenda, Global TODO list, Agenda dispatcher, Agenda views
@section The weekly/daily agenda
@cindex agenda
* Sorting of agenda items:: The order of things
@end menu
-@node Categories, Time-of-day specifications, Weekly/Daily Agenda, Weekly/Daily Agenda
+@node Categories, Time-of-day specifications, Weekly/Daily agenda, Weekly/Daily agenda
@subsection Categories
@cindex category
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
+@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
@code{org-agenda-time-grid}.
-@node Calendar/Diary integration, Sorting of agenda items, Time-of-day specifications, Weekly/Daily Agenda
+@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
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
+@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
@code{org-agenda-sorting-strategy}.
-@node Global TODO list, Matching headline tags, Weekly/Daily Agenda, Agenda Views
+@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
@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
+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.
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
+@node Matching headline tags, Timeline, Global TODO list, Agenda views
@section Matching headline tags
@cindex matching, of tags
@cindex tags view
The commands available in the tags list are described in @ref{Agenda
commands}.
-@node Timeline, Agenda commands, Matching headline tags, Agenda Views
+@node Timeline, Agenda commands, Matching headline tags, Agenda views
@section Timeline for a single file
@cindex single file summary
@cindex agenda, for single file
The commands available in the timeline buffer are listed in
@ref{Agenda commands}.
-@node Agenda commands, , Timeline, Agenda Views
+@node Agenda commands, , Timeline, Agenda views
@section Commands in the agenda buffer
@cindex commands, in agenda buffer
@end table
-@node Exporting, Miscellaneous, Agenda Views, Top
+@node Exporting, Miscellaneous, Agenda views, Top
@chapter Exporting
@cindex exporting
-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.
+Org-mode documents can be exported into a variety of other formats. For
+printing and sharing of notes, ASCII export produces a readable and
+simple version of an Org-mode file. HTML export allows to publish a
+notes file on the web, while the XML format provides a solid base for
+exchange with a broad range of other applications. To incorporate
+entries with associated times like deadlines or appointments into a
+desktop calendar program like iCal, Org-mode can also produce extracts
+in the iCalendar format. Currently Org-mode only supports export, not
+import of these different formats.
+
+When exporting, Org-mode uses special conventions to enrich the output
+produced. @xref{Text interpretation}, for more details.
@menu
-* ASCII export:: Export as a structured ASCII file
-* HTML export:: Export as an HTML file
-* iCalendar export:: Create calendar entries.
+* ASCII export:: Exporting to plain ASCII
+* HTML export:: Exporting to HTML
+* XML export:: Exporting to XML
+* iCalendar export:: Exporting in iCalendar format
+* Text interpretation:: How the exporter looks at the file
@end menu
@node ASCII export, HTML export, Exporting, Exporting
@section ASCII export
@cindex ASCII export
+ASCII export produces an simple and very readable version of an Org-mode
+file.
+
@cindex region, active
@cindex active region
@cindex transient-mark-mode
@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.
+creates only top level headlines and does the rest as items.
-@node HTML export, iCalendar export, ASCII export, Exporting
+@node HTML export, XML export, ASCII export, Exporting
@section HTML export
@cindex HTML export
@kindex C-c C-x b
@item C-c C-x b
Export as HTML file and open it with a browser.
-@kindex C-c C-x t
-@item C-c C-x t
-Insert template with export options, see below.
-@kindex C-c :
-@item C-c :
-Toggle fixed-width for entry (QUOTE) or region, see below.
@end table
@cindex headline levels, for exporting
@noindent
creates two levels of headings and does the rest as items.
+If you want to include HTML tags which should be interpreted as such,
+mark them with a @samp{@@} like in @samp{@@<b>bold text@@</b>}.
+Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
+@samp{>} in HTML export.
+
+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. 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
+
+Org-mode contains an XML exporter that produces XOXO-style XML.
+Currently, this exporter only handles the general outline structure and
+does not interpret any additional Org-mode features.
+
+@table @kbd
+@kindex C-c C-x C-x
+@item C-c C-x C-x
+Export as XML file @file{myfile.xml}.
+@end table
+
+@node iCalendar export, Text interpretation, XML export, Exporting
+@section iCalendar export
+@cindex 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:
+
+@cindex applescript, for calendar update
+@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 Text interpretation, , iCalendar export, Exporting
+@section Text interpretation by the exporter
+
+The exporter backends interpret additional structure in the Org-mode file
+in order to produce better output.
+
@menu
-* HTML formatting:: Interpretation of the buffer content
-* Export options:: How to influence exports
-* Comment lines:: Lines which will not be exported
+* Comment lines:: Some lines will not be exported
+* Enhancing text:: Subscripts, symbols and more
+* Export options:: How to influence the export settings
@end menu
-@node HTML formatting, Export options, HTML export, HTML export
-@subsection HTML formatting
+@node Comment lines, Enhancing text, Text interpretation, Text interpretation
+@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.
+
+@table @kbd
+@kindex C-c ;
+@item C-c ;
+Toggle the COMMENT keyword at the beginning of an entry.
+@end table
+
+
+
+@node Enhancing text, Export options, Comment lines, Text interpretation
+@subsection Enhancing text for export
+@cindex enhancing text
+@cindex richer text
+
+Some of the export backends of Org-mode allow for sophisticated text
+formatting, this is true in particular for the HTML backend. Org-mode
+has a number of typing conventions that allow to produce a richly
+formatted output.
-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}.
+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
letters, and press @kbd{M-@key{TAB}} to see possible completions.
@end itemize
-@cindex tables, export to HTML
+@cindex tables, export
@item
-Tables are transformed into HTML tables. Data fields before the first
-horizontal separator line will be formatted as table header fields.
+Tables are transformed into native tables under the exporter, if the
+export backend supports this. Data fields before the first horizontal
+separator line will be formatted as table header fields.
@cindex fixed width
@item
headline will be typeset as fixed-width, to allow quoting of computer
codes etc. Lines starting with @samp{:} are also typeset in
fixed-width font.
-
-@cindex HTML tags
-@item
-If you want to include HTML tags which should be interpreted as such,
-mark them with a @samp{@@} like in @samp{@@<b>bold text@@</b>}.
-Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
-@samp{>} in HTML export.
+@table @kbd
+@kindex C-c :
+@item C-c :
+Toggle fixed-width for entry (QUOTE) or region, see below.
+@end table
@end itemize
If these conversions conflict with your habits of typing ASCII text,
-they can all be turned off with corresponding variables.
+they can all be turned off with corresponding variables (see the
+customization group @code{org-export-general}, and the following section
+which explains how to set export options with special lines in a
+buffer.
-@node Export options, Comment lines, HTML formatting, HTML export
+@node Export options, , Enhancing text, Text interpretation
@subsection Export options
@cindex options, for export
correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
(@pxref{Completion}).
+@table @kbd
+@kindex C-c C-x t
+@item C-c C-x t
+Insert template with export options, see example below.
+@end table
+
@example
#+TITLE: the title to be shown (default is the buffer name)
#+AUTHOR: the author (default taken from @code{user-full-name})
TeX: @r{turn on/off @TeX{} macros}
@end example
-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. This command reastarts org-mode for the
-current buffer and forces Emacs to re-evaluate the loval variables
-section in the buffer.
-
-@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. This applies also for
-ASCII export.
-
-@table @kbd
-@kindex C-c ;
-@item C-c ;
-Toggle the COMMENT keyword at the beginning of an entry.
-@end table
-
-@node iCalendar export, , HTML export, Exporting
-@section iCalendar export
-@cindex 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:
-
-@cindex applescript, for calendar update
-@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
@menu
* Completion:: M-TAB knows what you need
* Customization:: Adapting Org-mode to your taste
-* Updating settings:: How to tell Org-mode that settings have changed
+* Summary of in-buffer settings:: Using special lines to set options
+* The very busy C-c C-c key:: When in doubt, press C-c C-c
* Clean view:: Getting rid of leading stars in the outline
* TTY keys:: Using Org-mode on a tty
* FAQ:: Frequently asked questions
@end table
-@node Customization, Updating settings, Completion, Miscellaneous
+@node Customization, Summary of in-buffer settings, Completion, Miscellaneous
@section Customization
@cindex customization
@cindex options, for customization
Org-mode. For the sake of compactness of the manual, we are not
describing the variables here. A structured overview of customization
variables is available with @kbd{M-x org-customize}. Or select
-@code{Browse Org Group} from the @code{Org->Customization} menu.
+@code{Browse Org Group} from the @code{Org->Customization} menu. Many
+settings can also be activated on a per-file basis, by putting special
+lines into the buffer (@pxref{Summary of in-buffer settings}).
+
+@node Summary of in-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
+@section Summary of in-buffer settings
+@cindex in-buffer settings
+@cindex special keywords
+
+Org-mode uses special lines in the buffer to define settings on a
+per-file basis. These lines start with a @samp{#+} followed by a
+keyword, a colon, and then individual words defining a setting. Several
+settings words con be in the same line, but you can also have multiple
+lines for the keyword. While these settings are described throughout
+the manual, here is a summary. After changing any of those lines in the
+buffer, press @kbd{C-c C-c} with the cursor still in the line to
+activate the changes immediately. Otherwise they become effective only
+when the file is visited again in a new Emacs session.
-@node Updating settings, Clean view, Customization, Miscellaneous
-@section Updating settings after changes
-@cindex updating, after setting changes
+@table @kbd
+@item #+STARTUP:
+This line sets options to be used at startup of org-mode, when an
+Org-mode file is being visited. The first set of options deals with the
+initial visibility of the outline tree. The corresponding variable for
+global default settings is @code{org-startup-folded}, with a default
+value @code{t}, which means @code{overview}.
+@example
+overview @r{top-level headlines only}
+content @r{all headlines}
+showall @r{no folding at all, show everything}
+@end example
+Then there are options for aligning tables upon visiting a file. This
+is useful in files containing narrowed table columns. The corresponding
+variable is @code{org-startup-align-all-tables}, with a default value
+@code{nil}.
+@example
+align @r{align all tables}
+noalign @r{don't align table on startup}
+@end example
+Here are the options for hiding leading stars in outline headings. The
+corresponding variables are @code{org-hide-leading-stars} and
+@code{org-odd-levels-only}, both with a default setting @code{nil}
+(meaning @code{showstars} and @code{oddeven}).
+@example
+hidestars @r{make all but one of the stars starting a headline invisible.}
+showstars @r{show all stars starting a headline}
+odd @r{allow only odd outline levels (1,3,...)}
+oddeven @r{allow all outline levels}
+@end example
+@item #+SEQ_TODO: #+TYP_TODO:
+These lines that the TODO keywords and their interpretation in the
+current file. The corresponding variables are @code{org-todo-keywords}
+and @code{org-todo-interpretation}.
+@item #+CATEGORY:
+This line sets the category for the agenda file. The category applies
+for all subsequent lines until the next @samp{#+CATEGORY} line, or the
+end of the file.
+@item #+TBLFM:
+This line contains the formulas for the table directly above the line.
+@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:
+These line provide setting for exporting files. For more details see
+@ref{Export options}.
+@end table
+
+@node The very busy C-c C-c key, Clean view, Summary of in-buffer settings, Miscellaneous
+@section The very busy C-c C-c key
@kindex C-c C-c
-Org-mode uses special lines in the buffer to set file-local values for a
-number of user options. When such settings are changed, you need to
-inform Org-mode that something has be modified and that it should
-recheck the buffer for setting. This is done with the command @kbd{C-c
-C-c} in the following situations:
+The key @kbd{C-c C-c} has many purposes in org-mode, which are all
+mentioned scattered throughout this manual. One specific function of
+this key is to add @emph{tags} to a headline (@pxref{Tags}). In many
+other circumstances it means something like @emph{Hey Org-mode, look
+here and update according to what you see here}. Here is a summary what
+this means in different contexts.
-@itemize @bullet
+@itemize @minus
+@c @item
+@c If the cursor is in a headline, prompt for tags and insert them
+@c into the current line, aligned to `org-tags-column'. When called
+@c with prefix arg, realign all tags in the current buffer.
+@item
+If the cursor is in one of the special #+KEYWORD lines, this
+triggers scanning the buffer for these lines and updating the
+information.
@item
-After changing any of the special buffer lines starting with @samp{#+},
-for example @samp{#+STARTUP}, @samp{#+CATEGORY}. Org-mode will then
-read these settings and activate them (see @ref{Visibility cycling},
-@ref{Narrow columns}, @ref{Clean view}, @ref{Per file keywords},
-@ref{Categories})
+If the cursor is inside a table, realign the table. This command
+works even if the automatic table editor has been turned off.
@item
-After editing by hand a @samp{#+TBLFM} line containing formulas for a
-table. When pressing @kbd{C-c C-c} in that line, all formulas are
-re-applied to the entire table (@pxref{Editing/debugging formulas}).
+If the cursor is on a #+TBLFM line, re-apply the formulas to
+the entire table.
@item
-In a table, @kbd{C-c C-c} does force a re-align, even if the table
-editor is turned off (@pxref{Built-in table editor})
+If the cursor is inside a table created by the @file{table.el} package,
+activate that table.
+@item
+If the current buffer is a remember buffer, close note and file it.
+with a prefix argument, file it without further interaction to the default
+location.
@item
-In an ordered plain list, @kbd{C-c C-c} forces a renumbering of the list
-(@pxref{Plain Lists}).
+If the cursor is on a <<<target>>>, update radio targets and corresponding
+links in this buffer.
@item
-After adding a new radio target @samp{<<<New target>>>}, @kbd{C-c C-c}
-must be used with the cursor on that target to activate it throughout
-the buffer.
+If the cursor is on a numbered item in a plain list, renumber the
+ordered list.
@end itemize
-@node Clean view, TTY keys, Updating settings, Miscellaneous
+@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
@section A cleaner outline view
@cindex hiding leading stars
@cindex clean outline view
link text. Please give them back to me, don't tell me it is not
possible!}@*
@c
-Would I let you down like that? If you must (even if I don't understand
-why), you can do this
+Would I let you down like that? If you must, you can do this
+
@lisp
(setq org-link-style 'plain
org-link-format "<%s>")
&%%(org-diary) ~/path/to/another/org-file.org
@end example
-If you now launch the calendar and press @kbd{d} to display a diary,
-the headlines of entries containing a timestamp, date range, schedule,
-or deadline referring to the selected date will be listed. Just like
-in Org-mode's agenda view, the diary for @emph{today} contains
-additional entries for overdue deadlines and scheduled items. See
-also the documentation of the @command{org-diary} function.
+If you now launch the calendar and press @kbd{d} to display a diary, the
+headlines of entries containing a timestamp, date range, schedule, or
+deadline referring to the selected date will be listed. Just like in
+Org-mode's agenda view, the diary for @emph{today} contains additional
+entries for overdue deadlines and scheduled items. See also the
+documentation of the @command{org-diary} function. Under XEmacs, it is
+not possible to jump back from the diary to the org, this works only in
+the agenda buffer.
@end enumerate
@item @file{org-mouse.el} by Piotr Zielinski
This package implements extended mouse functionality for Org-mode. It
allows you to cycle visibility and to edit the document structure with
-the mouse. It also provides a context-sensitive menu that changes
-depending on the context of a mouse-click. Use a search engine to find
-this package on the web.
+the mouse. Best of all, it provides a context-sensitive menu on
+@key{mouse-3} that changes depending on the context of a mouse-click.
+Use a search engine to find this package on the web.
@cindex @file{table.el}
@item @file{table.el} by Takaaki Ota
Org mode cooperates with table.el, see @ref{table.el}. @file{table.el}
If a formula uses @emph{calculated} fields further down the row,
multiple recalculation may be needed to get all fields consistent.
@item
-Under XEmacs, if Org-mode entries are included into the diary, it is
-not possible to jump back from the diary to the org file. Apparently,
-the text properties are lost when the fancy-diary-display is used.
-However, from Org-mode's timeline and agenda buffers (created with
-@kbd{C-c C-r} and @kbd{C-c a}), things do work correctly.
-@item
You can only make a single word boldface or italic. To emphasize
several words in a row, each must have the emphasize markers, like in
@samp{*three* *bold* *words*}.
@item
Sacha Chua suggested to copy some linking code from Planner.
@item
+Kees Dullemond inspired the use of narrowed tabled columns.
+@item
Christian Egli converted the documentation into TeXInfo format, patched
CSS formatting into the HTML exporter, and inspired the agenda.
@item