[Emacs-diffs] Changes to emacs/man/org.texi

[Carsten Dominik]

Index: emacs/man/org.texi
diff -u emacs/man/org.texi:1.35 emacs/man/org.texi:1.36
--- emacs/man/org.texi:1.35     Fri Dec 16 14:32:16 2005
+++ emacs/man/org.texi  Tue Dec 20 08:07:37 2005
@@ -4,7 +4,7 @@
 @setfilename ../info/org
 @settitle Org Mode Manual
 
address@hidden VERSION 4.00
address@hidden VERSION 4.01
 @set DATE December 2005
 
 @dircategory Emacs
@@ -229,7 +229,7 @@
 
 @example
 @address@hidden as an outline extension with visibility cycling and structure 
editing}
address@hidden@bullet{} as an ASCII system and table editor to take structured 
notes}
address@hidden@bullet{} as an ASCII system and table editor for taking 
structured notes}
 @address@hidden as an ASCII table editor with spreadsheet-like capabilities}
 @address@hidden as a simple hypertext system, with HTML export}
 @address@hidden as a TODO list editor}
@@ -532,7 +532,7 @@
 @node Archiving, Sparse trees, Structure editing, Document Structure
 @section Archiving
 @cindex archiving
address@hidden filing subtries
address@hidden filing subtrees
 
 When a project represented by a (sub)tree is finished, you may want
 to move the tree to an archive place, either in the same file under a
@@ -618,12 +618,24 @@
 
 @example
 * Meeting with the French group      :WORK:
-** Summary by Frank                  :BOSS:
+** Summary by Frank                  :BOSS:NOTES:
 *** TODO Prepare slides for him      :ACTION:
 @end example
 @noindent
-the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:}, and
address@hidden:ACTION:}.
+the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:},
address@hidden:NOTES:}, and @samp{:ACTION:}.  When executing tag searches and
+Org-mode finds that a certain headline matches the search criterion,
+it will not check any sublevel headline, assuming that these likely
+also match, and that the list of matches can become very long.  You
+can influence inheritance and searching using the variables
address@hidden and
address@hidden
+
address@hidden address@hidden
+Tags can simply be typed into the buffer.  After a colon,
address@hidden@key{TAB}} offers completion on all tags being used in the
+current buffer.  There are also special commands for inserting tags,
+and for executing searches based on tags.
 
 @table @kbd
 @kindex C-c C-c
@@ -631,29 +643,33 @@
 @cindex completion, of tags
 Enter new tags for the current headline.  The minibuffer will prompt
 for a list of tags and offer completion with respect to all other tags
-used in the current buffer.  After pressing @key{RET}, the tags will
+used in the current buffer.  Several tags, separated by colons, may be
+specified at the prompt.  After pressing @key{RET}, the tags will
 be inserted and aligned to @code{org-tags-column}.  When called with a
 @kbd{C-u} prefix, align all tags in the current buffer to that column,
-just to make things look nice.  Tags can also be just typed into the
-buffer, with @address@hidden support.
address@hidden address@hidden
address@hidden address@hidden
-Tags can also be typed directly into the buffer, using
address@hidden@key{TAB}} completion.
+just to make things look nice.  TAGS are automatically realigned after
+promotion, demotion, and TODO state changes (@pxref{TODO basics}).
 @kindex C-c \
 @item C-c \
-Create a sparse tree with all headlines matching a given set of tags.
-The command prompts for the tags to match.  The criterion is just a
-list of tags separated by @samp{+} or @samp{-} for positive and
-negative selection.  For example, @samp{+WORK-BOSS} would select all
-headlines that are tagged @samp{:WORK:}, but discard those also tagged
address@hidden:BOSS:}.
+Create a sparse tree with all headlines matching a tags search.
 @kindex C-c a m
 @item C-c a m
 Create a global list of tag matches from all agenda files.
 @xref{Matching headline tags}.
 @end table
 
+A tags search string can use Boolean operators @samp{&} for AND and
address@hidden|} for OR.  @samp{&} binds more strongly than
address@hidden|}. Parenthesis are currently no implemented.  A tag may also be
+preceded by @samp{-}, to select against it, and @samp{+} is syntactic
+sugar for positive selection.  The AND operator @samp{&} is optional
+when @samp{+} or @samp{-} is present.  For example, @samp{+WORK-BOSS}
+would select all headlines that are tagged @samp{:WORK:}, but discard
+those also tagged @samp{:BOSS:}.  The search string @samp{WORK|LAPTOP}
+selects all lines tagged @samp{:WORK:} or @samp{:LAPTOP:}. The string
address@hidden|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are
+also tagged @samp{NIGHT}.
+
 @node Plain Lists,  , Tags, Document Structure
 @section Plain Lists
 @cindex plain lists
@@ -692,7 +708,7 @@
 @end example
 
 Org-mode supports these lists by tuning filling and wrapping commands
-to correctly deal with them.  Futhermore, the following commands act
+to correctly deal with them.  Furthermore, the following commands act
 on items when the cursor is in the first line of an item (the line
 with the bullet or number).
 
@@ -1322,11 +1338,11 @@
 
 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
+on a small letter inside the word) as links.  While in Wiki 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
@@ -2020,32 +2036,16 @@
 @chapter Agenda Views
 @cindex agenda views
 
address@hidden
-We have already described three commands to filter important
-information in an org file into a sparse tree (@pxref{Sparse trees}):
-
address@hidden sparse trees
address@hidden @bullet
address@hidden
-The TODO tree, (@kbd{C-c C-v}), see @ref{TODO items}.
address@hidden
-The occur tree @kbd{C-c /}, see @ref{TODO items}.
address@hidden
-Checking upcoming deadlines with @kbd{C-c C-w}, see @ref{Creating
-timestamps}.
address@hidden itemize
address@hidden
address@hidden ignore
-
-Org-mode can collect and sort selected items into a separate buffer.
-The information to be listed is collected from all @emph{agenda
-files}, the files listed in the variable @code{org-agenda-files}.
-Thus even if you only work with a single Org-mode file, this file must
-be put into that address@hidden using the dispatcher pressing
address@hidden before selecting a command will actually limit the command to
-the current file, and ignore @code{org-agenda-files} until the next
-dispatcher command.}.  You can customize this variable, but the easiest
-way to maintain it is through the following commands
+Org-mode can select items based of various criteria, and display them
+in a separate buffer.  The information to be shown is collected from
+all @emph{agenda files}, the files listed in the variable
address@hidden  Thus even if you only work with a single
+Org-mode file, this file must be put into that address@hidden
+using the dispatcher pressing @kbd{1} before selecting a command will
+actually limit the command to the current file, and ignore
address@hidden until the next dispatcher command.}.  You can
+customize @code{org-agenda-files}, but the easiest way to maintain it
+is through the following commands
 
 @cindex files, adding to agenda list
 @table @kbd
@@ -2084,11 +2084,21 @@
 corresponding locations in the original Org-mode files, and even to
 edit these files remotely.
 
address@hidden custom agenda commands
address@hidden agenda commands, custom
 The views are created through a dispatcher that should be bound to a
 global key, for example @kbd{C-c a} (@pxref{Installation and
 Activation}).  In the following we will assume that @kbd{C-c a} is
 indeed how the dispatcher is accessed and list keyboard access to
-commands accordingly.
+commands accordingly.  The dispatcher offers a number of default
+commands, for example to create a TODO list or a the calendar-like
+agenda.  You can also define a number of custom searches for tags and
+specific TODO keywords through the variable
address@hidden
address@hidden C-c a C
+These commands will be offered by the dispatcher just like the default
+commands.  If you press @kbd{C-c a C}, you will get a customization
+buffer for this variable.
 
 @menu
 * Agenda::                      Your weekly planner
@@ -2230,7 +2240,7 @@
 for example @kbd{3 r}.
 @end table
 
-Remote editing of TDOD items means that you can change the state of a
+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}.
 
@@ -2241,15 +2251,15 @@
 
 If headlines in the agenda files are marked with @emph{tags}
 (@pxref{Tags}), you can select headlines based on the tags that apply
-to them and collect them into an ageenda buffer.
+to them and collect them into an agenda buffer.
 
 @table @kbd
 @kindex C-c a m
 @item C-c a m
 Produce a list of all headlines that match a given set of tags.  The
-command prompts for a selection criterion, which is a simple list of
-TAGS with positive and negative selection, like
address@hidden
+command prompts for a selection criterion, which is a boolean logic
+expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or
address@hidden|HOME} (@pxref{Tags}).
 @kindex C-c a M
 @item C-c a M
 Like @kbd{C-c a m}, but only select headlines that are also TODO
@@ -2396,6 +2406,10 @@
 Change the TODO state of the item, both in the agenda and in the
 original org file.
 
address@hidden :
address@hidden :
+Set tags for the current headline.
+
 @kindex ,
 @item ,
 Set the priority for the current item.  Org-mode prompts for the
@@ -2900,7 +2914,7 @@
 After @samp{*}, complete CamelCase versions of all headlines in the
 buffer.
 @item
-After @samp{:}, complete tags used elswhere in the buffer.
+After @samp{:}, complete tags used elsewhere 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
@@ -2917,11 +2931,11 @@
 @cindex options, for customization
 @cindex variables, for customization
 
-There is a large number of variables which can be used to customize
+There are more than 100 variables that can be used to customize
 Org-mode.  For the sake of compactness of the manual, we are not
-describing the variables here.  For an overview of customization
-variables, use @kbd{M-x org-customize}.  Or select @code{Browse Org
-Group} from the @code{Org->Customization} menu.
+describing the variables here.  A structured overview of customization
+variables is available with @kbd{M-x org-customize}.  Or select
address@hidden Org Group} from the @code{Org->Customization} menu.
 
 @node FAQ, Interaction, Customization, Miscellaneous
 @section Frequently asked questions
@@ -3167,59 +3181,63 @@
 
 Org-mode was written by Carsten Dominik, who still maintains it at the
 Org-mode homepage @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
-The following people have helped the development along with ideas,
-suggestions and patches.
+The following people (in alphabetic order) have helped the development
+along with ideas, suggestions and patches.  Many thanks to all of you,
+Org-mode would not be what it is without your input.
 
 @itemize @bullet
 @item
-Matthias Rempe (Oelde) provided ideas, a patch introducing Windows
-NT/2000 support, and quality control.
address@hidden
-Kevin Rogers contributed code to access VM files on remote hosts.
+Pavel Chalmoviansky reported bugs and suggested improvements
+related to the agenda treatment of items with specified time.
 @item
-Juergen Vollmer contributed code generating the table of contents
-in HTML output, and other export improvements.
+Sacha Chua, the current maintainer of Planner, suggested to copy
+linking code from Planner (I took code for RMAIL and Wanderlust).
 @item
 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
+Kai Grossjohann pointed out that a number of key bindings in Org-mode
+conflict with other packages.
address@hidden
+Stefan Monnier provided a patch with lots of little fixes to keep the
+Emacs-Lisp compiler happy.
address@hidden
+Tim O'Callaghan suggested in-file links, search options for
+general file links, and TAGS.
address@hidden
+Oliver Oppitz made useful suggestions.
address@hidden
+Pete Phillips helped the development of the TAGS feature with beta
+testing and suggestions.
address@hidden
+Matthias Rempe (Oelde) provided ideas, a patch introducing Windows
+NT/2000 support, and quality control.
address@hidden
+Kevin Rogers contributed code to access VM files on remote hosts.
address@hidden
 Philip Rooke created the Org-mode reference card.  He also helped with
 beta testing and contributed a number of very useful ideas.
 @item
 Christian Schlauer proposed angular brackets around links, among other
 things.
 @item
-David Wainberg suggested to implement an archiving mechanism and helped
-testing.
address@hidden
 Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
 @file{organizer-mode.el}.
 @item
-Scheduling TODO items was inspired by John Wiegley's @file{planner.el}.
+Juergen Vollmer contributed code generating the table of contents
+in HTML output, and other export improvements.
 @item
-Sacha Chua, the current maintainer of Planner, suggested to copy
-linking code from Planner (I took code for RMAIL and Wanderlust).
+David Wainberg suggested to implement an archiving mechanism and helped
+testing.
 @item
-Oliver Oppitz made useful suggestions.
+Scheduling TODO items was inspired by John Wiegley's @file{planner.el}.
 @item
 Carsten Wimmer suggested some changes and helped fix a bug in linking
 to GNUS.
address@hidden
-Pavel Chalmoviansky reported bugs and suggested improvements related
-to the agenda treatment of items with specified time.
address@hidden
-Stefan Monnier provided a patch with lots of little fixes to keep the
-Emacs-Lisp compiler happy.
address@hidden
-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 needed to
 use Org-mode on a tty.
address@hidden
-Tim O'Callaghan suggested in-file links, search options for
-general file links, and TAGS.
 @c @item
 @c Nic Ferrier and Christian Egli implemented XML export.
 @end itemize