comparison man/org.texi @ 71246:f32b17d18b4b

(ASCII export): Document indentation adaptation. (Setting tags): Document mutually-exclusive tags.

71245:92cdf6b94754

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

@set VERSION 4.35
@set DATE May 2006

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

Instead of typing an equation into the field, you may also use the
command @kbd{C-c =}.  It prompts for a formula (with default taken
from the @samp{#+TBLFM:} line) and applies it to the current field.  A
numerical prefix (e.g. @kbd{C-5 C-c =}) will apply it to that many
subsequent fields in the current column.

@cindex recomputing table fields
To recompute all the fields in a line, use the command @kbd{C-c *}.
It re-applies all stored equations to the current row, from left to
right.  With a @kbd{C-u} prefix, this will be done to every line in

@cindex time, reading in minibuffer
@cindex calendar, for selecting date
When Org-mode prompts for a date/time, the function reading your input
will replace anything you choose not to specify with the current date
and time.  For details, see the documentation string of
@command{org-read-date}.  Also, a calendar will pop up to allow
selecting a date.  The calendar can be fully controlled from the
minibuffer, and a date can be selected with the following commands:

@table @kbd
@kindex <

@example
#+TAGS: @@WORK @@HOME @@TENNISCLUB
#+TAGS: Laptop Car PC Sailboat
@end example

The default method Org-mode uses to support setting tags is completion.
However, it also implements a much better method: @emph{fast tag
selection}.  This method allows to select and deselect tags with a
single key per tag.  To function efficiently, you need to assign unique
keys to all tags.  This can be done globally with

@lisp
(setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l)))
@end lisp

@noindent or on a per-file basis with

@example
#+TAGS: @@WORK(w)  @@HOME(h)  @@TENNISCLUB(t)
#+TAGS: Laptop(l)  Car(c)  PC(p) Sailboat(s)
@end example

@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
these lines to activate any changes.

If selection keys have been configured, pressing @kbd{C-c C-c} will
automatically present you with a special interface, listing inherited
tags, the tags of the current headline, and a list of all legal tags
with corresponding keys.  Pressing keys for the tags will add or remove
them from the list of tags in the current line.  @key{SPC} clears all
tags for this line, @kbd{RET} accepts the modified set, and @kbd{C-g}
aborts without installing changes.  This method lets you assign tags to
a headline with very few keys.  With the above setup, you could clear
the current tags and set @samp{@@HOME}, @samp{Laptop} and @samp{PC} tags
with just the following keys: @kbd{C-c C-c @key{SPC} h l p @key{RET}}.

What if you have globally defined your preferred set of tags using the
variable @code{org-tag-alist}, but would like to use a dynamic tag list
in a specific file?  Just add and empty TAGS option line to that file:

@example
#+TAGS:
@end example

@example
@kbd{C-1 C-c C-x a}
@end example

@noindent
creates only top level headlines and does the rest as items.

@node HTML export, XOXO export, ASCII export, Exporting
@section HTML export
@cindex HTML export

@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

@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 (see the
customization group @code{org-export-general}, and the following section

@tab Function executing the publication of a file.
@end multitable

The function must accept two arguments: a property list containing at
least a @code{:publishing-directory} property, and the name of the file
to be published.  I should take the specified file, make the necessary
transformation (if any) and place the result into the destination folder.
You can write your own publishing function, but @code{org-publish}
provides one for attachments (files that only need to be copied):
@code{org-publish-attachment}.

@subsection Third-party extensions for Org-mode

The following extensions for Org-mode have been written by other people:

@table @asis
@cindex @file{org-checklet.el}
@item @file{org-checklet.el} by Frank Ruell
Provides checklist of items which can be either checked or unchecked.
This is similar to the TODO functionality in Org-mode, but never shows
up in the agenda.  @file{org-checklet} is freely available at
@url{http://www.emacswiki.org/cgi-bin/emacs/org-checklet.el}.
@cindex @file{org-mouse.el}
@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.  Best of all, it provides a context-sensitive menu on

other things.
@item
Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s
@file{organizer-mode.el}.
@item
@i{David O'Toole} wrote @file{org-publish.el} and came up with lots of
ideas for small changes.
@item
@i{J@"urgen Vollmer} contributed code generating the table of contents
in HTML output.
@item
@i{Chris Wallace} provided a patch implementing the @samp{QUOTE}

71246:f32b17d18b4b

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

@set VERSION 4.36
@set DATE June 2006

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

Instead of typing an equation into the field, you may also use the
command @kbd{C-c =}.  It prompts for a formula (with default taken
from the @samp{#+TBLFM:} line) and applies it to the current field.  A
numerical prefix (e.g. @kbd{C-5 C-c =}) will apply it to that many
consecutive fields in the current column.

@cindex recomputing table fields
To recompute all the fields in a line, use the command @kbd{C-c *}.
It re-applies all stored equations to the current row, from left to
right.  With a @kbd{C-u} prefix, this will be done to every line in

@cindex time, reading in minibuffer
@cindex calendar, for selecting date
When Org-mode prompts for a date/time, the function reading your input
will replace anything you choose not to specify with the current date
and time.  For details, see the documentation string of
@command{org-read-date}.  Also, a calender will pop up to allow
selecting a date.  The calendar can be fully controlled from the
minibuffer, and a date can be selected with the following commands:

@table @kbd
@kindex <

@example
#+TAGS: @@WORK @@HOME @@TENNISCLUB
#+TAGS: Laptop Car PC Sailboat
@end example

The default support method is minibuffer completion.  However, Org-mode
also implements a much better method: @emph{fast tag selection}.  This
method allows to select and deselect tags with a single key per tag.  To
function efficiently, you should assign unique keys to all tags.  This
can be done globally with

@lisp
(setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l)))
@end lisp

@noindent or on a per-file basis with

@example
#+TAGS: @@WORK(w)  @@HOME(h)  @@TENNISCLUB(t)  Laptop(l)  PC(p)
@end example

@noindent
You can also group together tags that are mutually exclusive.  With
curly braces@footnote{In @code{org-mode-alist} use
@code{'(:startgroup)} and @code{'(:endgroup)}, respectively.  Several
groups are allowed.}

@example
#+TAGS: @{ @@WORK(w)  @@HOME(h)  @@TENNISCLUB(t) @}  Laptop(l)  PC(p)
@end example

@noindent you indicate that at most one of @samp{@@WORK}, @samp{@@HOME},
and @samp{@@SAILBOAT} should be selected.

@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
these lines to activate any changes.

If at least one tag has a selection key, pressing @kbd{C-c C-c} will
automatically present you with a special interface, listing inherited
tags, the tags of the current headline, and a list of all legal tags
with corresponding keys@footnote{Keys will automatically assigned to
tags which have no configured keys.}.  Pressing keys for the tags will
add or remove them from the list of tags in the current line.  Selecting
a tag in a group of mutually exclusive tags will turn off any other tags
from that group.  @key{SPC} clears all tags for this line, @kbd{RET}
accepts the modified set, and @kbd{C-g} aborts without installing
changes.  This method lets you assign tags to a headline with very few
keys.  With the above setup, you could clear the current tags and set
@samp{@@HOME}, @samp{Laptop} and @samp{PC} tags with just the following
keys: @kbd{C-c C-c @key{SPC} h l p @key{RET}}.  Switching from
@samp{@@HOME} to @samp{@@WORK} would be done with @kbd{C-c C-c w
@key{RET}}.

What if you have globally defined your preferred set of tags using the
variable @code{org-tag-alist}, but would like to use a dynamic tag list
in a specific file?  Just add an empty TAGS option line to that file:

@example
#+TAGS:
@end example

@example
@kbd{C-1 C-c C-x a}
@end example

@noindent
creates only top level headlines and does the rest as items.  When
headlines are converted to items, the indentation of the text following
the headline is changed to fit nicely under the item.  This is done with
the assumption that the first bodyline indicates the base indenation of
the body text.  Any indenation larger than this is adjusted to preserve
the layout relative to the first line.  Should there be lines with less
indentation than the first, these are left alone.

@node HTML export, XOXO export, ASCII export, Exporting
@section HTML export
@cindex HTML export

@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

@table @kbd
@kindex C-c :
@item C-c :
Toggle fixed-width for entry (QUOTE) or region, see below.
@end table

@cindex linebreak, forced
@item 
A double backslash @emph{at the end of a line} enforces a line break at
this position.
@end itemize

If these conversions conflict with your habits of typing ASCII text,
they can all be turned off with corresponding variables (see the
customization group @code{org-export-general}, and the following section

@tab Function executing the publication of a file.
@end multitable

The function must accept two arguments: a property list containing at
least a @code{:publishing-directory} property, and the name of the file
to be published.  It should take the specified file, make the necessary
transformation (if any) and place the result into the destination folder.
You can write your own publishing function, but @code{org-publish}
provides one for attachments (files that only need to be copied):
@code{org-publish-attachment}.

@subsection Third-party extensions for Org-mode

The following extensions for Org-mode have been written by other people:

@table @asis
@cindex @file{org-mouse.el}
@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.  Best of all, it provides a context-sensitive menu on

other things.
@item
Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s
@file{organizer-mode.el}.
@item
@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
chapter about publishing.
@item
@i{J@"urgen Vollmer} contributed code generating the table of contents
in HTML output.
@item
@i{Chris Wallace} provided a patch implementing the @samp{QUOTE}