[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/man/org.texi,v
|
From: |
Carsten Dominik |
|
Subject: |
[Emacs-diffs] Changes to emacs/man/org.texi,v |
|
Date: |
Tue, 19 Jun 2007 08:53:37 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Carsten Dominik <cdominik> 07/06/19 08:53:37
Index: org.texi
===================================================================
RCS file: /sources/emacs/emacs/man/org.texi,v
retrieving revision 1.79
retrieving revision 1.80
diff -u -b -r1.79 -r1.80
--- org.texi 6 Jun 2007 15:14:14 -0000 1.79
+++ org.texi 19 Jun 2007 08:53:36 -0000 1.80
@@ -3,7 +3,7 @@
@setfilename ../info/org
@settitle Org Mode Manual
address@hidden VERSION 4.77
address@hidden VERSION 4.78
@set DATE June 2007
@dircategory Emacs
@@ -80,8 +80,8 @@
* 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
+* Timestamps:: Assign date and time to items
* Agenda views:: Collecting information into views
* Embedded LaTeX:: LaTeX fragments and formulas
* Exporting:: Sharing and publishing of notes
@@ -173,6 +173,12 @@
* Multiple sets in one file:: Mixing it all, and still finding your way
* Per file keywords:: Different files, different requirements
+Tags
+
+* Tag inheritance:: Tags use the tree structure of the outline
+* Setting tags:: How to assign tags to a headline
+* Tag searches:: Searching for combinations of tags
+
Timestamps
* Time stamps:: Assigning a time to a tree entry
@@ -196,12 +202,6 @@
* Tracking TODO state changes:: When did the status change?
* Clocking work time:: When exactly did you work on this item?
-Tags
-
-* Tag inheritance:: Tags use the tree structure of the outline
-* Setting tags:: How to assign tags to a headline
-* Tag searches:: Searching for combinations of tags
-
Agenda Views
* Agenda files:: Files being searched for agenda information
@@ -1040,10 +1040,7 @@
deal with them address@hidden only changes the filling
settings for Emacs. For XEmacs, you should use Kyle E. Jones'
@file{filladapt.el}. To turn this on, put into @file{.emacs}:
address@hidden
-(require 'filladapt)
address@hidden example
-}.
address@hidden(require 'filladapt)}}.
The following commands act on items when the cursor is in the first line
of an item (the line with the bullet or number).
@@ -1056,6 +1053,9 @@
given by the indentation of the bullet/number. Items are always
subordinate to real headlines, however; the hierarchies remain
completely separated.
+
+If @code{org-cycle-include-plain-lists} has not been set, @key{TAB}
+fixes the indentation of the curent line in a heuristic way.
@kindex address@hidden
@item address@hidden
Insert new item at current level. With prefix arg, force a new heading
@@ -1094,8 +1094,9 @@
@kindex C-c C-c
@item C-c C-c
If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
-state of the checkbox. Otherwise, if this is an ordered list, renumber
-the ordered list at the cursor.
+state of the checkbox. If not, make this command makes sure that all
+the items on this list level use the same bullet. Furthermore, if this
+is an ordered list, make sure the numbering is ok.
@end table
@node Tables, Hyperlinks, Document structure, Top
@@ -1641,12 +1642,18 @@
followed by an opening parenthesis, then it is evaluated as a lisp form.
The evaluation should return either a string or a number. Just as with
@file{calc} formulas, you can specify modes and a printf format after a
-semicolon. A reference will be replaced with a string (in double
-quotes) containing the field. If you provide the @samp{N} mode switch,
-all referenced elements will be numbers. Ranges are inserted as
-space-separated fields, so you can embed them in list or vector syntax.
-A few examples, note how the @samp{N} mode is used when we do
-computations in lisp.
+semicolon. With Emacs Lisp forms, you need to be concious about the way
+field references are interpolated into the form. By default, a
+reference will be interpolated as a Lisp string (in double quotes)
+containing the field. If you provide the @samp{N} mode switch, all
+referenced elements will be numbers (non-number fields will be zero) and
+interpolated as Lisp numbers, without quotes. If you provide the
address@hidden flag, all fields will be interpolated literally, without quotes.
+I.e., if you want a reference to be interpreted as a string by the Lisp
+form, enclode the reference operator itself in double quotes, like
address@hidden"$3"}. Ranges are inserted as space-separated fields, so you can
+embed them in list or vector syntax. A few examples, note how the
address@hidden mode is used when we do computations in lisp.
@example
@r{Swap the first two characters of the content of column 1}
@@ -2042,8 +2049,8 @@
@noindent In HTML export (@pxref{HTML export}), such targets will become
named anchors for direct access through @samp{http} address@hidden
-that text before the first headline will never be exported, so the first
-such target must be after the first headline.}.
+that text before the first headline is usually not exported, so the
+first such target should be after the first headline.}.
If no dedicated target exists, Org-mode will search for the words in the
link. In the above example the search would be for @samp{my target}.
@@ -2581,7 +2588,7 @@
same column as the headline (after the asterisks).
address@hidden TODO items, Timestamps, Hyperlinks, Top
address@hidden TODO items, Tags, Hyperlinks, Top
@chapter TODO items
@cindex TODO items
@@ -2960,128 +2967,387 @@
back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}.
@end table
address@hidden Timestamps, Tags, TODO items, Top
address@hidden Timestamps
address@hidden time stamps
address@hidden date stamps
-Items can be labeled with timestamps to make them useful for project
-planning.
address@hidden Tags, Timestamps, TODO items, Top
address@hidden Tags
address@hidden tags
address@hidden headline tagging
address@hidden matching, tags
address@hidden sparse tree, tag based
address@hidden
-* Time stamps:: Assigning a time to a tree entry
-* Creating timestamps:: Commands which insert timestamps
-* Deadlines and scheduling:: Planning your work
-* Progress logging:: Documenting when what work was done.
address@hidden menu
+If you wish to implement a system of labels and contexts for
+cross-correlating information, an excellent way is to assign @i{tags} to
+headlines. Org-mode has extensive support for using tags.
+Every headline can contain a list of tags, at the end of the headline.
+Tags are normal words containing letters, numbers, @samp{_}, and
address@hidden@@}. Tags must be preceded and followed by a single colon; like
address@hidden:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}.
address@hidden Time stamps, Creating timestamps, Timestamps, Timestamps
address@hidden Time stamps, deadlines and scheduling
address@hidden time stamps
address@hidden ranges, time
address@hidden date stamps
address@hidden deadlines
address@hidden scheduling
address@hidden
+* Tag inheritance:: Tags use the tree structure of the outline
+* Setting tags:: How to assign tags to a headline
+* Tag searches:: Searching for combinations of tags
address@hidden menu
-A time stamp is a specification of a date (possibly with time) in a
-special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16 Tue
-09:39>address@hidden is the standard ISO date/time format. If you
-cannot get used to these, see @ref{Custom time format}}. A time stamp
-can appear anywhere in the headline or body of an org-tree entry. Its
-presence causes entries to be shown on specific dates in the agenda
-(@pxref{Weekly/Daily agenda}). We distinguish:
address@hidden Tag inheritance, Setting tags, Tags, Tags
address@hidden Tag inheritance
address@hidden inheritance, of tags
address@hidden sublevels, inclusion into tags match
address@hidden @var
address@hidden Plain time stamp
address@hidden timestamp
-A simple time stamp just assigns a date/time to an item. This is just
-like writing down an appointment in a paper agenda, or like writing down
-an event in a diary, when you want to take note 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.
address@hidden make use of the hierarchical structure of outline trees. If a
+heading has a certain tag, all subheadings will inherit the tag as
+well. For example, in the list
@example
-* Meet Peter at the movies <2006-11-01 Wed 19:15>
+* Meeting with the French group :WORK:
+** Summary by Frank :BOSS:NOTES:
+*** TODO Prepare slides for him :ACTION:
@end example
address@hidden Time stamp with repeater interval
address@hidden timestamp, with repeater interval
-A time stamp may contain a @emph{repeater interval}, indicating that it
-applies not only on the given date, but again and again after a certain
-interval of N days (d), weeks (w), months(m), or years(y). The
-following will show up in the agenda every Wednesday:
address@hidden
+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. This may
+not be what you want, however, and you can influence inheritance and
+searching using the variables @code{org-use-tag-inheritance} and
address@hidden
+
address@hidden Setting tags, Tag searches, Tag inheritance, Tags
address@hidden Setting tags
address@hidden setting tags
address@hidden tags, setting
+
address@hidden address@hidden
+Tags can simply be typed into the buffer at the end of a headline.
+After a colon, @address@hidden offers completion on tags. There is
+also a special command for inserting tags:
+
address@hidden @kbd
address@hidden C-c C-c
address@hidden C-c C-c
address@hidden completion, of tags
+Enter new tags for the current headline. Org-mode will either offer
+completion or a special single-key interface for setting tags, see
+below. After pressing @key{RET}, the tags will be inserted and aligned
+to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
+tags in the current buffer will be aligned to that column, just to make
+things look nice. TAGS are automatically realigned after promotion,
+demotion, and TODO state changes (@pxref{TODO basics}).
address@hidden table
+
+Org will support tag insertion based on a @emph{list of tags}. By
+default this list is constructed dynamically, containing all tags
+currently used in the buffer. You may also globally specify a hard list
+of tags with the variable @code{org-tag-alist}. Finally you can set
+the default tags for a given file with lines like
@example
-* Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
+#+TAGS: @@WORK @@HOME @@TENNISCLUB
+#+TAGS: Laptop Car PC Sailboat
@end example
address@hidden Diary-style sexp entries
-For more complex date specifications, Org-mode supports using the
-special sexp diary entries implemented in the Emacs calendar/diary
-package. For example
+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
-* The nerd meeting on every 2nd Thursday of the month
- <%%(diary-float t 4 2)>
+#+TAGS:
@end example
address@hidden Time/Date range
address@hidden timerange
address@hidden date range
-Two time stamps connected by @samp{--} denote a range. The headline
-will be shown on the first and last day of the range, and on any dates
-that are displayed and fall in the range. Here is an example:
+The default support method for entering tags 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 most tags. This can be done globally with
+
address@hidden
+(setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l)))
address@hidden lisp
+
address@hidden or on a per-file basis with
@example
-** Meeting in Amsterdam
- <2004-08-23 Mon>--<2004-08-26 Thu>
+#+TAGS: @@WORK(w) @@HOME(h) @@TENNISCLUB(t) Laptop(l) PC(p)
@end example
address@hidden Inactive time stamp
address@hidden timestamp, inactive
address@hidden inactive timestamp
-Just like a plain time stamp, but with square brackets instead of
-angular ones. These time stamps are inactive in the sense that they do
address@hidden trigger an entry to show up in the agenda.
address@hidden
+You can also group together tags that are mutually exclusive. With
+curly address@hidden @code{org-mode-alist} use
address@hidden'(:startgroup)} and @code{'(:endgroup)}, respectively. Several
+groups are allowed.}
@example
-* Gillian comes late for the fifth time [2006-11-01 Wed]
+#+TAGS: @{ @@WORK(w) @@HOME(h) @@TENNISCLUB(t) @} Laptop(l) PC(p)
@end example
address@hidden you indicate that at most one of @samp{@@WORK}, @samp{@@HOME},
+and @samp{@@TENNISCLUB} should be selected.
+
address@hidden 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 address@hidden will automatically be assigned to
+tags which have no configured keys.}. In this interface, you can use
+the following keys:
+
address@hidden @kbd
address@hidden a-z...
+Pressing keys assigned to 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.
address@hidden @key{TAB}
address@hidden @key{TAB}
+Enter a tag in the minibuffer, even if the tag is not in the predefined
+list. You will be able to complete on all tags present in the buffer.
address@hidden @key{SPC}
address@hidden @key{SPC}
+Clear all tags for this line.
address@hidden @key{RET}
address@hidden @key{RET}
+Accept the modified set.
address@hidden C-g
+Abort without installing changes.
address@hidden q
+If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
address@hidden !
+Turn off groups of mutually exclusive tags. Use this to (as an
+exception) assign several tags from such a group.
address@hidden C-c
+Toggle auto-exit after the next change (see below).
+If you are using expert mode, the first @kbd{C-c} will display the
+selection window.
@end table
address@hidden Creating timestamps, Deadlines and scheduling, Time stamps,
Timestamps
address@hidden Creating timestamps
address@hidden creating timestamps
address@hidden timestamps, creating
address@hidden
+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},
address@hidden 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
address@hidden@@WORK} would be done with @kbd{C-c C-c w @key{RET}} or
+alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
address@hidden could be done with @kbd{C-c C-c @key{TAB} S a r a h
address@hidden @key{RET}}.
-For Org-mode to recognize time stamps, they need to be in the specific
-format. All commands listed below produce time stamps in the correct
-format.
+If you find that most of the time, you need only a single keypress to
+modify your list of tags, set the variable
address@hidden Then you no longer have to
+press @key{RET} to exit fast tag selection - it will immediately exit
+after the first change. If you then occasionally need more keys, press
address@hidden to turn off auto-exit for the current tag selection process
+(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c
+C-c}). If you set the variable to the value @code{expert}, the special
+window is not even shown for single-key tag selection, it comes up only
+when you press an extra @kbd{C-c}.
+
address@hidden Tag searches, , Setting tags, Tags
address@hidden Tag searches
address@hidden tag searches
address@hidden searching for tags
+
+Once a tags system has been set up, it can be used to collect related
+information into special lists.
@table @kbd
address@hidden C-c .
address@hidden C-c .
-Prompt for a date and insert a corresponding time stamp. When the
-cursor is at a previously used time stamp, it is updated to NOW. When
-this command is used twice in succession, a time range is inserted.
address@hidden
address@hidden C-u C-c .
address@hidden C-u C-c .
-Like @kbd{C-c .}, but use the alternative format which contains date
-and time. The default time can be rounded to multiples of 5 minutes,
-see the option @code{org-time-stamp-rounding-minutes}.
address@hidden
address@hidden C-c !
address@hidden C-c !
-Like @kbd{C-c .}, but insert an inactive time stamp that will not cause
-an agenda entry.
address@hidden
address@hidden C-c <
address@hidden C-c <
-Insert a time stamp corresponding to the cursor date in the Calendar.
address@hidden
address@hidden C-c \
address@hidden C-c \
+Create a sparse tree with all headlines matching a tags search. With a
address@hidden prefix argument, ignore headlines that are not a TODO line.
address@hidden C-c a m
address@hidden C-c a m
+Create a global list of tag matches from all agenda files.
address@hidden headline tags}.
address@hidden C-c a M
address@hidden C-c a M
+Create a global list of tag matches from all agenda files, but check
+only TODO items and force checking subitems (see variable
address@hidden).
address@hidden table
+
address@hidden Boolean logic, for tag searches
+A @i{tags} search string can use Boolean operators @samp{&} for AND and
address@hidden|} for OR. @samp{&} binds more strongly than @samp{|}.
+Parenthesis are currently not 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. Examples:
+
address@hidden @samp
address@hidden +WORK-BOSS
+Select headlines tagged @samp{:WORK:}, but discard those also tagged
address@hidden:BOSS:}.
address@hidden WORK|LAPTOP
+Selects lines tagged @samp{:WORK:} or @samp{:LAPTOP:}.
address@hidden WORK|LAPTOP&NIGHT
+Like before, but require the @samp{:LAPTOP:} lines to be tagged also
address@hidden
address@hidden table
+
address@hidden TODO keyword matching, with tags search
+If you are using multi-state TODO keywords (@pxref{TODO extensions}), it
+can be useful to also match on the TODO keyword. This can be done by
+adding a condition after a slash to a tags match. The syntax is similar
+to the tag matches, but should be applied with consideration: For
+example, a positive selection on several TODO keywords can not
+meaningfully be combined with boolean AND. However, @emph{negative
+selection} combined with AND can be meaningful. To make sure that only
+lines are checked that actually have any TODO keyword, use @kbd{C-c a
+M}, or equivalently start the todo part after the slash with @samp{!}.
+Examples:
+
address@hidden @samp
address@hidden WORK/WAITING
+Select @samp{:WORK:}-tagged TODO lines with the specific TODO
+keyword @samp{WAITING}.
address@hidden WORK/!-WAITING-NEXT
+Select @samp{:WORK:}-tagged TODO lines that are neither @samp{WAITING}
+nor @samp{NEXT}
address@hidden WORK/+WAITING|+NEXT
+Select @samp{:WORK:}-tagged TODO lines that are either @samp{WAITING} or
address@hidden
address@hidden table
+
address@hidden regular expressions, with tags search
+Any element of the tag/todo match can be a regular expression - in this
+case it must be enclosed in curly braces. For example,
address@hidden@address@hidden matches headlines that contain the tag
address@hidden and any tag @i{starting} with @samp{BOSS}.
+
address@hidden level, require for tags match
+You can also require a headline to be of a certain level, by writing
+instead of any TAG an expression like @samp{LEVEL=3}. For example, a
+search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that
+have the tag BOSS and are @emph{not} marked with the todo keyword DONE.
+
address@hidden Timestamps, Agenda views, Tags, Top
address@hidden Timestamps
address@hidden time stamps
address@hidden date stamps
+
+Items can be labeled with timestamps to make them useful for project
+planning.
+
address@hidden
+* Time stamps:: Assigning a time to a tree entry
+* Creating timestamps:: Commands which insert timestamps
+* Deadlines and scheduling:: Planning your work
+* Progress logging:: Documenting when what work was done.
address@hidden menu
+
+
address@hidden Time stamps, Creating timestamps, Timestamps, Timestamps
address@hidden Time stamps, deadlines and scheduling
address@hidden time stamps
address@hidden ranges, time
address@hidden date stamps
address@hidden deadlines
address@hidden scheduling
+
+A time stamp is a specification of a date (possibly with time or a range
+of times) in a special format, either @samp{<2003-09-16 Tue>} or
address@hidden<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue
+12:00-12:30>address@hidden is the standard ISO date/time format. If
+you cannot get used to these, see @ref{Custom time format}}. A time
+stamp can appear anywhere in the headline or body of an org-tree entry.
+Its presence causes entries to be shown on specific dates in the agenda
+(@pxref{Weekly/Daily agenda}). We distinguish:
+
address@hidden @var
address@hidden Plain time stamp
address@hidden timestamp
+A simple time stamp just assigns a date/time to an item. This is just
+like writing down an appointment in a paper agenda, or like writing down
+an event in a diary, when you want to take note 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.
+
address@hidden
+* Meet Peter at the movies <2006-11-01 Wed 19:15>
+* Discussion on climate change <2006-11-02 Thu 20:00-22:00>
address@hidden example
+
address@hidden Time stamp with repeater interval
address@hidden timestamp, with repeater interval
+A time stamp may contain a @emph{repeater interval}, indicating that it
+applies not only on the given date, but again and again after a certain
+interval of N days (d), weeks (w), months(m), or years(y). The
+following will show up in the agenda every Wednesday:
+
address@hidden
+* Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
address@hidden example
+
address@hidden Diary-style sexp entries
+For more complex date specifications, Org-mode supports using the
+special sexp diary entries implemented in the Emacs calendar/diary
+package. For example
+
address@hidden
+* The nerd meeting on every 2nd Thursday of the month
+ <%%(diary-float t 4 2)>
address@hidden example
+
address@hidden Time/Date range
address@hidden timerange
address@hidden date range
+Two time stamps connected by @samp{--} denote a range. The headline
+will be shown on the first and last day of the range, and on any dates
+that are displayed and fall in the range. Here is an example:
+
address@hidden
+** Meeting in Amsterdam
+ <2004-08-23 Mon>--<2004-08-26 Thu>
address@hidden example
+
address@hidden Inactive time stamp
address@hidden timestamp, inactive
address@hidden inactive timestamp
+Just like a plain time stamp, but with square brackets instead of
+angular ones. These time stamps are inactive in the sense that they do
address@hidden trigger an entry to show up in the agenda.
+
address@hidden
+* Gillian comes late for the fifth time [2006-11-01 Wed]
address@hidden example
+
address@hidden table
+
address@hidden Creating timestamps, Deadlines and scheduling, Time stamps,
Timestamps
address@hidden Creating timestamps
address@hidden creating timestamps
address@hidden timestamps, creating
+
+For Org-mode to recognize time stamps, they need to be in the specific
+format. All commands listed below produce time stamps in the correct
+format.
+
address@hidden @kbd
address@hidden C-c .
address@hidden C-c .
+Prompt for a date and insert a corresponding time stamp. When the
+cursor is at a previously used time stamp, it is updated to NOW. When
+this command is used twice in succession, a time range is inserted.
address@hidden
address@hidden C-u C-c .
address@hidden C-u C-c .
+Like @kbd{C-c .}, but use the alternative format which contains date
+and time. The default time can be rounded to multiples of 5 minutes,
+see the option @code{org-time-stamp-rounding-minutes}.
address@hidden
address@hidden C-c !
address@hidden C-c !
+Like @kbd{C-c .}, but insert an inactive time stamp that will not cause
+an agenda entry.
address@hidden
address@hidden C-c <
address@hidden C-c <
+Insert a time stamp corresponding to the cursor date in the Calendar.
address@hidden
@kindex C-c >
@item C-c >
Access the Emacs calendar for the current date. If there is a
@@ -3227,6 +3493,9 @@
just like @address@hidden/@key{right}}. At the end of the stamp, the
time will be changed by one minute.
@item
+If the time stamp contains a range of clock times or a repeater, these
+will not be overlayed, but remain in the buffer as they were.
address@hidden
When you delete a time stamp character-by-character, it will only
disappear from the buffer after @emph{all} (invisible) characters
belonging to the ISO timestamp have been removed.
@@ -3508,263 +3777,7 @@
the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been
worked on or closed during a day.
address@hidden Tags, Agenda views, Timestamps, Top
address@hidden Tags
address@hidden tags
address@hidden headline tagging
address@hidden matching, tags
address@hidden sparse tree, tag based
-
-If you wish to implement a system of labels and contexts for
-cross-correlating information, an excellent way is to assign @i{tags} to
-headlines. Org-mode has extensive support for using tags.
-
-Every headline can contain a list of tags, at the end of the headline.
-Tags are normal words containing letters, numbers, @samp{_}, and
address@hidden@@}. Tags must be preceded and followed by a single colon; like
address@hidden:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}.
-
address@hidden
-* Tag inheritance:: Tags use the tree structure of the outline
-* Setting tags:: How to assign tags to a headline
-* Tag searches:: Searching for combinations of tags
address@hidden menu
-
address@hidden Tag inheritance, Setting tags, Tags, Tags
address@hidden Tag inheritance
address@hidden inheritance, of tags
address@hidden sublevels, inclusion into tags match
-
address@hidden make use of the hierarchical structure of outline trees. If a
-heading has a certain tag, all subheadings will inherit the tag as
-well. For example, in the list
-
address@hidden
-* Meeting with the French group :WORK:
-** Summary by Frank :BOSS:NOTES:
-*** TODO Prepare slides for him :ACTION:
address@hidden example
-
address@hidden
-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. This may
-not be what you want, however, and you can influence inheritance and
-searching using the variables @code{org-use-tag-inheritance} and
address@hidden
-
address@hidden Setting tags, Tag searches, Tag inheritance, Tags
address@hidden Setting tags
address@hidden setting tags
address@hidden tags, setting
-
address@hidden address@hidden
-Tags can simply be typed into the buffer at the end of a headline.
-After a colon, @address@hidden offers completion on tags. There is
-also a special command for inserting tags:
-
address@hidden @kbd
address@hidden C-c C-c
address@hidden C-c C-c
address@hidden completion, of tags
-Enter new tags for the current headline. Org-mode will either offer
-completion or a special single-key interface for setting tags, see
-below. After pressing @key{RET}, the tags will be inserted and aligned
-to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
-tags in the current buffer will be aligned to that column, just to make
-things look nice. TAGS are automatically realigned after promotion,
-demotion, and TODO state changes (@pxref{TODO basics}).
address@hidden table
-
-Org will support tag insertion based on a @emph{list of tags}. By
-default this list is constructed dynamically, containing all tags
-currently used in the buffer. You may also globally specify a hard list
-of tags with the variable @code{org-tag-alist}. Finally you can set
-the default tags for a given file with lines like
-
address@hidden
-#+TAGS: @@WORK @@HOME @@TENNISCLUB
-#+TAGS: Laptop Car PC Sailboat
address@hidden example
-
-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:
-
address@hidden
-#+TAGS:
address@hidden example
-
-The default support method for entering tags 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 most tags. This can be done globally with
-
address@hidden
-(setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l)))
address@hidden lisp
-
address@hidden or on a per-file basis with
-
address@hidden
-#+TAGS: @@WORK(w) @@HOME(h) @@TENNISCLUB(t) Laptop(l) PC(p)
address@hidden example
-
address@hidden
-You can also group together tags that are mutually exclusive. With
-curly address@hidden @code{org-mode-alist} use
address@hidden'(:startgroup)} and @code{'(:endgroup)}, respectively. Several
-groups are allowed.}
-
address@hidden
-#+TAGS: @{ @@WORK(w) @@HOME(h) @@TENNISCLUB(t) @} Laptop(l) PC(p)
address@hidden example
-
address@hidden you indicate that at most one of @samp{@@WORK}, @samp{@@HOME},
-and @samp{@@TENNISCLUB} should be selected.
-
address@hidden 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 address@hidden will automatically be assigned to
-tags which have no configured keys.}. In this interface, you can use
-the following keys:
-
address@hidden @kbd
address@hidden a-z...
-Pressing keys assigned to 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.
address@hidden @key{TAB}
address@hidden @key{TAB}
-Enter a tag in the minibuffer, even if the tag is not in the predefined
-list. You will be able to complete on all tags present in the buffer.
address@hidden @key{SPC}
address@hidden @key{SPC}
-Clear all tags for this line.
address@hidden @key{RET}
address@hidden @key{RET}
-Accept the modified set.
address@hidden C-g
-Abort without installing changes.
address@hidden q
-If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
address@hidden !
-Turn off groups of mutually exclusive tags. Use this to (as an
-exception) assign several tags from such a group.
address@hidden C-c
-Toggle auto-exit after the next change (see below).
-If you are using expert mode, the first @kbd{C-c} will display the
-selection window.
address@hidden table
-
address@hidden
-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},
address@hidden 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
address@hidden@@WORK} would be done with @kbd{C-c C-c w @key{RET}} or
-alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
address@hidden could be done with @kbd{C-c C-c @key{TAB} S a r a h
address@hidden @key{RET}}.
-
-If you find that most of the time, you need only a single keypress to
-modify your list of tags, set the variable
address@hidden Then you no longer have to
-press @key{RET} to exit fast tag selection - it will immediately exit
-after the first change. If you then occasionally need more keys, press
address@hidden to turn off auto-exit for the current tag selection process
-(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c
-C-c}). If you set the variable to the value @code{expert}, the special
-window is not even shown for single-key tag selection, it comes up only
-when you press an extra @kbd{C-c}.
-
address@hidden Tag searches, , Setting tags, Tags
address@hidden Tag searches
address@hidden tag searches
address@hidden searching for tags
-
-Once a tags system has been set up, it can be used to collect related
-information into special lists.
-
address@hidden @kbd
address@hidden C-c \
address@hidden C-c \
-Create a sparse tree with all headlines matching a tags search. With a
address@hidden prefix argument, ignore headlines that are not a TODO line.
address@hidden C-c a m
address@hidden C-c a m
-Create a global list of tag matches from all agenda files.
address@hidden headline tags}.
address@hidden C-c a M
address@hidden C-c a M
-Create a global list of tag matches from all agenda files, but check
-only TODO items and force checking subitems (see variable
address@hidden).
address@hidden table
-
address@hidden Boolean logic, for tag searches
-A @i{tags} search string can use Boolean operators @samp{&} for AND and
address@hidden|} for OR. @samp{&} binds more strongly than @samp{|}.
-Parenthesis are currently not 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. Examples:
-
address@hidden @samp
address@hidden +WORK-BOSS
-Select headlines tagged @samp{:WORK:}, but discard those also tagged
address@hidden:BOSS:}.
address@hidden WORK|LAPTOP
-Selects lines tagged @samp{:WORK:} or @samp{:LAPTOP:}.
address@hidden WORK|LAPTOP&NIGHT
-Like before, but require the @samp{:LAPTOP:} lines to be tagged also
address@hidden
address@hidden table
-
address@hidden TODO keyword matching, with tags search
-If you are using multi-state TODO keywords (@pxref{TODO extensions}), it
-can be useful to also match on the TODO keyword. This can be done by
-adding a condition after a slash to a tags match. The syntax is similar
-to the tag matches, but should be applied with consideration: For
-example, a positive selection on several TODO keywords can not
-meaningfully be combined with boolean AND. However, @emph{negative
-selection} combined with AND can be meaningful. To make sure that only
-lines are checked that actually have any TODO keyword, use @kbd{C-c a
-M}, or equivalently start the todo part after the slash with @samp{!}.
-Examples:
-
address@hidden @samp
address@hidden WORK/WAITING
-Select @samp{:WORK:}-tagged TODO lines with the specific TODO
-keyword @samp{WAITING}.
address@hidden WORK/!-WAITING-NEXT
-Select @samp{:WORK:}-tagged TODO lines that are neither @samp{WAITING}
-nor @samp{NEXT}
address@hidden WORK/+WAITING|+NEXT
-Select @samp{:WORK:}-tagged TODO lines that are either @samp{WAITING} or
address@hidden
address@hidden table
-
address@hidden regular expressions, with tags search
-Any element of the tag/todo match can be a regular expression - in this
-case it must be enclosed in curly braces. For example,
address@hidden@address@hidden matches headlines that contain the tag
address@hidden and any tag @i{starting} with @samp{BOSS}.
-
address@hidden level, require for tags match
-You can also require a headline to be of a certain level, by writing
-instead of any TAG an expression like @samp{LEVEL=3}. For example, a
-search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that
-have the tag BOSS and are @emph{not} marked with the todo keyword DONE.
-
address@hidden Agenda views, Embedded LaTeX, Tags, Top
address@hidden Agenda views, Embedded LaTeX, Timestamps, Top
@chapter Agenda Views
@cindex agenda views
@@ -5578,8 +5591,8 @@
@item
If a headline starts with the word @samp{QUOTE}, the text below the
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.
+codes etc. Lines starting with @samp{:} are also typeset in fixed-width
+font.
@table @kbd
@kindex C-c :
@item C-c :