[Emacs-diffs] emacs/doc/misc org.texi

[Carsten Dominik]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Carsten Dominik <cdominik>      08/12/07 18:49:39

Modified files:
        doc/misc       : org.texi 

Log message:
        2008-12-02  Carsten Dominik  <address@hidden>
        
                * 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.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/org.texi?cvsroot=emacs&r1=1.22&r2=1.23

Patches:
Index: org.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/org.texi,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -b -r1.22 -r1.23
--- org.texi    24 Nov 2008 12:17:46 -0000      1.22
+++ org.texi    7 Dec 2008 18:49:38 -0000       1.23
@@ -3,8 +3,8 @@
 @setfilename ../../info/org
 @settitle The Org Manual
 
address@hidden VERSION 6.13a
address@hidden DATE November 2008
address@hidden VERSION 6.14
address@hidden 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
 
@@ -3132,10 +3133,12 @@
 @code{org-todo-keyword-faces}.  For example:
 
 @lisp
address@hidden
 (setq org-todo-keyword-faces
       '(("TODO"      . org-warning)
         ("DEFERRED"  . shadow)
         ("CANCELED"  . (:foreground "blue" :weight bold))))
address@hidden 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
address@hidden:work:urgent:}.
+headline.  Tags are normal words containing letters, numbers, @samp{_}, and
address@hidden@@}.  Tags must be preceded and followed by a single colon, e.g.,
address@hidden: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
address@hidden, 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
address@hidden
 
 When a headline matches during a tags search while tag inheritance is turned
-on, all the sublevels in the same tree will match as address@hidden 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 address@hidden 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
address@hidden (not recommended).
 
 @node Setting tags, Tag searches, Tag inheritance, Tags
 @section Setting tags
@@ -3900,11 +3908,13 @@
 @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 address@hidden
-only special values that will be recognized are @samp{"<now>"} for now
-(including time), and @samp{"<today>"}, @samp{<tomorrow>}, and
address@hidden<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
address@hidden"<tomorrow>"} for these days at 0:00 hours, i.e. without a time
+specification.  Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
address@hidden, @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
@@ -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.
 
address@hidden Effort estimates,  , Clocking work time, Dates and Times
address@hidden Effort estimates, Relative timer, Clocking work time, Dates and 
Times
 @section Effort estimates
address@hidden Effort estimates
address@hidden 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.
 
address@hidden Relative timer,  , Effort estimates, Dates and Times
address@hidden Taking notes with a relative timer
address@hidden 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.
+
address@hidden @kbd
address@hidden C-c C-x .
address@hidden 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.
address@hidden C-c C-x -
address@hidden C-c C-x -
+Insert a description list item with the current relative time.  With a prefix
+argument, first reset the timer to 0.
address@hidden address@hidden
address@hidden address@hidden
+One the timer list is started, you can also use @address@hidden to insert
+new timer items.
address@hidden C-c C-x 0
address@hidden 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.
address@hidden table
+
 @node Capture, Agenda Views, Dates and Times, Top
 @chapter Capture
 @cindex capture
@@ -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 :
@@ -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 address@hidden fragments}
@@ -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 address@hidden LOCATION
+property can be inherited from higher in the hierarchy if you configure
address@hidden 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.
 
address@hidden @columnfractions 0.3 0.7
address@hidden @columnfractions 0.32 0.68
address@hidden @code{:link-up}               @tab @code{org-export-html-link-up}
address@hidden @code{:link-home}             @tab 
@code{org-export-html-link-home}
 @item @code{:language}              @tab @code{org-export-default-language}
address@hidden @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}
address@hidden @code{:section-number-format} @tab 
@code{org-export-section-number-format}
 @item @code{:table-of-contents}     @tab @code{org-export-with-toc}
address@hidden @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}
address@hidden @code{:footnotes}             @tab 
@code{org-export-with-footnotes}
address@hidden @code{:drawers}               @tab @code{org-export-with-drawers}
address@hidden @code{:tags}                  @tab @code{org-export-with-tags}
address@hidden @code{:todo-keywords}         @tab 
@code{org-export-with-todo-keywords}
address@hidden @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}
address@hidden @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}
address@hidden @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}
address@hidden @code{:html-extension}        @tab 
@code{org-export-html-extension}
address@hidden @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}
@@ -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
address@hidden Stewart} contributed code to @file{org-w3m.el}, to copy HTML 
content
+with links transformation to Org syntax.
address@hidden
 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
 chapter about publishing.
 @item