Mercurial > emacs

changeset 100271:ba4358a5f1c6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
2008-12-02 Carsten Dominik <carsten.dominik@gmail.com> * org.texi (Using the mapping API): Fix bug in mapping example. (Publishing options): Make the list of properties complete again, in correspondence to the variable `org-export-plist-vars'. (Property searches): Document new special values for time comparisons. (Tag inheritance): Refine the description of tag inheritance. (Project alist): Add info about the publishing sequence of components. (Effort estimates): Document the new relativer timer.
author Carsten Dominik <dominik@science.uva.nl>
date Sun, 07 Dec 2008 18:49:38 +0000
parents 9fcd88412d5c
children f36b68742b4a
files doc/misc/org.texi
diffstat 1 files changed, 110 insertions(+), 42 deletions(-) [+]
line wrap: on
line diff
--- a/doc/misc/org.texi	Sun Dec 07 18:49:09 2008 +0000
+++ b/doc/misc/org.texi	Sun Dec 07 18:49:38 2008 +0000
@@ -3,8 +3,8 @@
 @setfilename ../../info/org
 @settitle The Org Manual
 
-@set VERSION 6.13a
-@set DATE November 2008
+@set VERSION 6.14
+@set DATE December 2008
 
 @dircategory Emacs
 @direntry
@@ -219,6 +219,7 @@
 * Deadlines and scheduling::    Planning your work
 * Clocking work time::          Tracking how long you spend on a task
 * Effort estimates::            Planning work effort in advance
+* Relative timer::              Notes with a running timer
 
 Creating timestamps
 
@@ -945,7 +946,7 @@
 make sure the tree fits in nicely at the yank position.  The yank level can
 also be specified with a numeric prefix argument, or by yanking after a
 headline marker like @samp{****}.
-@kindex C-y 
+@kindex C-y
 @item C-y
 Depending on the variables @code{org-yank-adjusted-subtrees} and
 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
@@ -3132,10 +3133,12 @@
 @code{org-todo-keyword-faces}.  For example:
 
 @lisp
+@group
 (setq org-todo-keyword-faces
       '(("TODO"      . org-warning)
         ("DEFERRED"  . shadow)
         ("CANCELED"  . (:foreground "blue" :weight bold))))
+@end group
 @end lisp
 
 While using a list with face properties as shown for CANCELED
@@ -3439,10 +3442,13 @@
 support for tags.
 
 Every headline can contain a list of tags; they occur at the end of the
-headline.  Tags are normal words containing letters, numbers, @samp{_},
-and @samp{@@}.  Tags must be preceded and followed by a single colon,
-e.g., @samp{:work:}.  Several tags can be specified, as in
-@samp{:work:urgent:}.
+headline.  Tags are normal words containing letters, numbers, @samp{_}, and
+@samp{@@}.  Tags must be preceded and followed by a single colon, e.g.,
+@samp{:work:}.  Several tags can be specified, as in @samp{:work:urgent:}.
+Tags will by default get a bold face with the same color as the headline.
+You may specify special faces for specific tags using the variable
+@code{org-tag-faces}, much in the same way as you can do for TODO keywords
+(@pxref{Faces for TODO keywords}).
 
 @menu
 * Tag inheritance::             Tags use the tree structure of the outline
@@ -3479,14 +3485,16 @@
 
 @noindent
 To limit tag inheritance to specific tags, or to turn it off entirely, use
-the variable @code{org-use-tag-inheritance}.
+the variables @code{org-use-tag-inheritance} and
+@code{org-tags-exclude-from-inheritance}.
 
 When a headline matches during a tags search while tag inheritance is turned
-on, all the sublevels in the same tree will match as well@footnote{This is
-only true if the the search does not involve more complex tests including
-properties (@pxref{Property searches}).}.  The list of matches may then
-become very long.  If you only want to see the first tags match in a subtree,
-configure the variable @code{org-tags-match-list-sublevels}.
+on, all the sublevels in the same tree will (for a simple match form) match
+as well@footnote{This is only true if the the search does not involve more
+complex tests including properties (@pxref{Property searches}).}.  The list
+of matches may then become very long.  If you only want to see the first tags
+match in a subtree, configure the variable
+@code{org-tags-match-list-sublevels} (not recommended).
 
 @node Setting tags, Tag searches, Tag inheritance, Tags
 @section Setting tags
@@ -3896,20 +3904,22 @@
 @samp{>=}, and @samp{<>}.
 @item
 If the comparison value is enclosed in double
-quotes, a string comparison is done, and the same operators are allowed.  
+quotes, a string comparison is done, and the same operators are allowed.
 @item
 If the comparison value is enclosed in double quotes @emph{and} angular
 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
-assumed to be date/time specifications in the standard Org way@footnote{The
-only special values that will be recognized are @samp{"<now>"} for now
-(including time), and @samp{"<today>"}, @samp{<tomorrow>}, and
-@samp{<yesterday>} for these days at 0:00 hours, i.e. without a time
-specification.}, and the comparison will be done accordingly.
+assumed to be date/time specifications in the standard Org way, and the
+comparison will be done accordingly.  Special values that will be recognized
+are @code{"<now>"} for now (including time), and @code{"<today>"}, and
+@code{"<tomorrow>"} for these days at 0:00 hours, i.e. without a time
+specification.  Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
+@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
+respectively, can be used.
 @item
 If the comparison value is enclosed
 in curly braces, a regexp match is performed, with @samp{=} meaning that the
 regexp matches the property value, and @samp{<>} meaning that it does not
-match.  
+match.
 @end itemize
 
 So the search string in the example finds entries tagged @samp{:work:} but
@@ -4262,6 +4272,7 @@
 * Deadlines and scheduling::    Planning your work
 * Clocking work time::          Tracking how long you spend on a task
 * Effort estimates::            Planning work effort in advance
+* Relative timer::              Notes with a running timer
 @end menu
 
 
@@ -4890,9 +4901,9 @@
 the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
 worked on or closed during a day.
 
-@node Effort estimates,  , Clocking work time, Dates and Times
+@node Effort estimates, Relative timer, Clocking work time, Dates and Times
 @section Effort estimates
-@cindex Effort estimates
+@cindex effort estimates
 
 If you want to plan your work in a very detailed way, or if you need to
 produce offers with quotations of the estimated work effort, you may want to
@@ -4936,6 +4947,40 @@
 these estimates defined consistently, two or three key presses will narrow
 down the list to stuff that fits into an available time slot.
 
+@node Relative timer,  , Effort estimates, Dates and Times
+@section Taking notes with a relative timer
+@cindex relative timer
+
+When taking notes during, for example, a meeting or a video viewing, it can
+be useful to have access to times relative to a starting time.  Org provides
+such a relative timer and make it easy to create timed notes.
+
+@table @kbd
+@kindex C-c C-x .
+@item C-c C-x .
+Insert a relative time into the buffer.  The first time you use this, the
+timer will be started.  When called with a prefix argument, the timer is
+restarted.
+@kindex C-c C-x -
+@item C-c C-x -
+Insert a description list item with the current relative time.  With a prefix
+argument, first reset the timer to 0.
+@kindex M-@key{RET}
+@item M-@key{RET}
+One the timer list is started, you can also use @kbd{M-@key{RET}} to insert
+new timer items.
+@kindex C-c C-x 0
+@item C-c C-x 0
+Reset the timer without inserting anything into the buffer.  By default, the
+timer is reset to 0.  When called with a @kbd{C-u} prefix, reset the timer to
+specific starting offset.  The user is prompted for the offset, with a
+default taken from a timer string at point, if any, So this can be used to
+restart taking notes after a break in the process.  When called with a double
+prefix argument @kbd{C-c C-u}, change all timer strings in the active region
+by a certain amount.  This can be used to fix timer strings if the timer was
+not started at exactly the right moment.
+@end table
+
 @node Capture, Agenda Views, Dates and Times, Top
 @chapter Capture
 @cindex capture
@@ -5252,15 +5297,15 @@
 to select a command:
 
 @table @kbd
-@kindex C-c C-a a 
-@item a 
+@kindex C-c C-a a
+@item a
 Select a file and move it into the task's attachment directory.  The file
 will be copied, moved, or linked, depending on @code{org-attach-method}.
 Note that hard links are not supported on all systems.
 
 @kindex C-c C-a c
-@kindex C-c C-a m 
-@kindex C-c C-a l 
+@kindex C-c C-a m
+@kindex C-c C-a l
 @item c/m/l
 Attach a file using the copy/move/link method.
 Note that hard links are not supported on all systems.
@@ -6156,8 +6201,9 @@
 @c
 @kindex T
 @item T
-Show all tags associated with the current item.  Because of
-inheritance, this may be more than the tags listed in the line itself.
+Show all tags associated with the current item.  This is useful if you have
+turned off @code{org-agenda-show-inherited-tags}, but still want to see all
+tags of a headline occasionally.
 @c
 @kindex :
 @item :
@@ -7166,7 +7212,7 @@
  Great clouds overhead
  Tiny black birds rise and fall
  Snow covers Emacs
- 
+
      -- AlexSchroeder
 #+END_VERSE
 @end example
@@ -7461,6 +7507,10 @@
            @r{the simple @code{a_b} will be left as it is.}
 -:         @r{turn on/off conversion of special strings.}
 f:         @r{turn on/off footnotes like this[1].}
+todo:      @r{turn on/off inclusion of TODO keywords into exported text}
+pri:       @r{turn on/off priority cookies}
+tags:      @r{turn on/off inclusion of tags, may also be @code{not-in-toc}}
+<:         @r{turn on/off inclusion of any time/date stamps like DEADLINES}
 *:         @r{turn on/off emphasized text (bold, italic, underlined)}
 TeX:       @r{turn on/off simple @TeX{} macros in plain text}
 LaTeX:     @r{turn on/off La@TeX{} fragments}
@@ -7943,7 +7993,7 @@
 @code{org-icalendar-use-scheduled}.}.  As categories, it will use the tags
 locally defined in the heading, and the file/tree category@footnote{To add
 inherited tags or the TODO state, configure the variable
-@code{org-icalendar-categories}.}. 
+@code{org-icalendar-categories}.}.
 
 The iCalendar standard requires each entry to have a globally unique
 identifier (UID).  Org creates these identifiers during export.  If you set
@@ -7972,9 +8022,11 @@
 @code{org-combined-agenda-icalendar-file}.
 @end table
 
-The export will honor SUMMARY, DESCRIPTION and LOCATION properties if
-the selected entries have them.  If not, the summary will be derived
-from the headline, and the description from the body (limited to
+The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
+property can be inherited from higher in the hierarchy if you configure
+@code{org-use-property-inheritance} accordingly.} properties if the selected
+entries have them.  If not, the summary will be derived from the headline,
+and the description from the body (limited to
 @code{org-icalendar-include-body} characters).
 
 How this calendar is best read and updated, that depends on the application
@@ -8049,7 +8101,8 @@
 of the ``components'' property are taken to be components of the
 project, which group together files requiring different publishing
 options. When you publish such a ``meta-project'' all the components
-will also publish.
+will also publish.  The @code{:components} are published in the sequence
+provided.
 
 @node Sources and destinations, Selecting files, Project alist, Configuration
 @subsection Sources and destinations for files
@@ -8133,22 +8186,32 @@
 with the variable they belong to.  See the documentation string for the
 respective variable for details.
 
-@multitable @columnfractions 0.3 0.7
+@multitable @columnfractions 0.32 0.68
+@item @code{:link-up}               @tab @code{org-export-html-link-up}
+@item @code{:link-home}             @tab @code{org-export-html-link-home}
 @item @code{:language}              @tab @code{org-export-default-language}
+@item @code{:customtime}            @tab @code{org-display-custom-times}
 @item @code{:headline-levels}       @tab @code{org-export-headline-levels}
 @item @code{:section-numbers}       @tab @code{org-export-with-section-numbers}
+@item @code{:section-number-format} @tab @code{org-export-section-number-format}
 @item @code{:table-of-contents}     @tab @code{org-export-with-toc}
+@item @code{:preserve-breaks}       @tab @code{org-export-preserve-breaks}
 @item @code{:archived-trees}        @tab @code{org-export-with-archived-trees}
 @item @code{:emphasize}             @tab @code{org-export-with-emphasize}
 @item @code{:sub-superscript}       @tab @code{org-export-with-sub-superscripts}
 @item @code{:special-strings}       @tab @code{org-export-with-special-strings}
+@item @code{:footnotes}             @tab @code{org-export-with-footnotes}
+@item @code{:drawers}               @tab @code{org-export-with-drawers}
+@item @code{:tags}                  @tab @code{org-export-with-tags}
+@item @code{:todo-keywords}         @tab @code{org-export-with-todo-keywords}
+@item @code{:priority}              @tab @code{org-export-with-priority}
 @item @code{:TeX-macros}            @tab @code{org-export-with-TeX-macros}
 @item @code{:LaTeX-fragments}       @tab @code{org-export-with-LaTeX-fragments}
+@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading}
 @item @code{:fixed-width}           @tab @code{org-export-with-fixed-width}
 @item @code{:timestamps}            @tab @code{org-export-with-timestamps}
 @item @code{:author-info}           @tab @code{org-export-author-info}
 @item @code{:creator-info}          @tab @code{org-export-creator-info}
-@item @code{:tags}                  @tab @code{org-export-with-tags}
 @item @code{:tables}                @tab @code{org-export-with-tables}
 @item @code{:table-auto-headline}   @tab @code{org-export-highlight-first-table-line}
 @item @code{:style-include-default} @tab @code{org-export-html-style-include-default}
@@ -8156,6 +8219,8 @@
 @item @code{:style-extra}           @tab @code{org-export-html-style-extra}
 @item @code{:convert-org-links}     @tab @code{org-export-html-link-org-files-as-html}
 @item @code{:inline-images}         @tab @code{org-export-html-inline-images}
+@item @code{:html-extension}        @tab @code{org-export-html-extension}
+@item @code{:html-table-tag}        @tab @code{org-export-html-table-tag}
 @item @code{:expand-quoted-html}    @tab @code{org-export-html-expand}
 @item @code{:timestamp}             @tab @code{org-export-html-with-timestamp}
 @item @code{:publishing-directory}  @tab @code{org-export-publishing-directory}
@@ -8639,7 +8704,7 @@
 where the outline headings are really section headlines.  However, in a more
 list-oriented outline, it is clear that an indented structure is a lot
 cleaner, as can be seen by comparing the two columns in the following
-example: 
+example:
 
 @example
 @group
@@ -8658,7 +8723,7 @@
 separate features that, combined, achieve just that.
 
 @enumerate
-@item 
+@item
 @emph{Indentation of text below headlines}@*
 You may indent text below each headline to make the left boundary line up
 with the headline, like
@@ -8974,7 +9039,7 @@
 @item @file{org-annotate-file.el} by @i{Philip Jackson}
       Annotate a file with org syntax, in a separate file, with links back to
       the annotated file.
-@item @file{org-annotation-helper.el} by @i{Bastien Guerry and Daniel E. German} 
+@item @file{org-annotation-helper.el} by @i{Bastien Guerry and Daniel E. German}
       Call @i{remember} directly from Firefox/Opera, or from Adobe Reader.
       When activating a special link or bookmark, Emacs receives a trigger to
       create a note with a link back to the website.  Requires some setup, a
@@ -9702,7 +9767,7 @@
 certain criteria.  Internally, this functionality is used to produce agenda
 views, but there is also an API that can be used to execute arbitrary
 functions for each or selected entries.  The main entry point for this API
-is: 
+is:
 
 @defun org-map-entries func &optional match scope &rest skip
 Call FUNC at each headline selected by MATCH in SCOPE.
@@ -9750,7 +9815,7 @@
 It can uce the property API (@pxref{Using the property API}) to gather more
 information about the entry, or in order to change metadate in the entry.
 Here are a couple of functions that might be handy:
- 
+
 @defun org-todo &optional arg
 Change the TODO state of the entry, see the docstring of the functions for
 the many possible values for the argument ARG.
@@ -9788,7 +9853,7 @@
 @code{WAITING}, in all agenda files.
 
 @lisp
-(length (org-map-entries t "/+WAITING" nil 'agenda))
+(length (org-map-entries t "/+WAITING" 'agenda))
 @end lisp
 
 @node History and Acknowledgments, Main Index, Hacking, Top
@@ -9970,6 +10035,9 @@
 @i{Adam Spiers} asked for global linking commands, inspired the link
 extension system, added support for mairix, and proposed the mapping API.
 @item
+@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
+with links transformation to Org syntax.
+@item
 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
 chapter about publishing.
 @item