[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/doc/misc/org.texi,v
|
From: |
Carsten Dominik |
|
Subject: |
[Emacs-diffs] Changes to emacs/doc/misc/org.texi,v |
|
Date: |
Thu, 13 Mar 2008 08:49:30 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Carsten Dominik <cdominik> 08/03/13 08:49:29
Index: org.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/org.texi,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- org.texi 24 Feb 2008 10:08:58 -0000 1.4
+++ org.texi 13 Mar 2008 08:49:29 -0000 1.5
@@ -3,8 +3,8 @@
@setfilename ../../info/org
@settitle Org Mode Manual
address@hidden VERSION 5.19
address@hidden DATE January 2008
address@hidden VERSION 5.23
address@hidden DATE March 2008
@dircategory Emacs
@direntry
@@ -245,6 +245,7 @@
* Global TODO list:: All unfinished action items
* Matching tags and properties:: Structured information with fine-tuned search
* Timeline:: Time-sorted view for single file
+* Keyword search:: Finding entries by keyword
* Stuck projects:: Find projects you need to review
Presentation and sorting
@@ -833,12 +834,14 @@
creation of a new headline, use a prefix arg, or first press @key{RET}
to get to the beginning of the next line. When this command is used in
the middle of a line, the line is split and the rest of the line becomes
-the new headline. If the command is used at the beginning of a
-headline, the new headline is created before the current line. If at
-the beginning of any other line, the content of that line is made the
-new heading. If the command is used at the end of a folded subtree
-(i.e. behind the ellipses at the end of a headline), then a headline
-like the current one will be inserted after the end of the subtree.
+the new address@hidden you do not want the line to be split,
+customize the variable @code{org-M-RET-may-split-line}.}. If the
+command is used at the beginning of a headline, the new headline is
+created before the current line. If at the beginning of any other line,
+the content of that line is made the new heading. If the command is
+used at the end of a folded subtree (i.e. behind the ellipses at the end
+of a headline), then a headline like the current one will be inserted
+after the end of the subtree.
@kindex address@hidden
@item address@hidden
Insert a new heading after the current subtree, same level as the
@@ -893,6 +896,13 @@
can also supply your own function to extract the sorting key. With a
@kbd{C-u} prefix, sorting will be case-sensitive. With two @kbd{C-u
C-u} prefixes, duplicate entries will also be removed.
address@hidden C-c *
address@hidden C-c *
+Turn a normal line or plain list item into a headline (so that it
+becomes a subheading at its location). Also turn a headline into a
+normal line by removing the stars. If there is an active region, turn
+all lines in the region into headlines. Or, if the first line is a
+headline, remove the stars from all headlines in the region.
@end table
@cindex region, active
@@ -1015,6 +1025,12 @@
or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
location as the value (@pxref{Properties and columns}).
+When a subtree is moved, it receives a number of special properties that
+record context information like the file from where the entry came, it's
+outline path the archiving time etc. Configure the variable
address@hidden to adjust the amount of information
+added.
+
@node Sparse trees, Plain lists, Archiving, Document structure
@section Sparse trees
@cindex sparse trees
@@ -1150,11 +1166,12 @@
Insert new item at current level. With prefix arg, force a new heading
(@pxref{Structure editing}). If this command is used in the middle of a
line, the line is @emph{split} and the rest of the line becomes the new
-item. If this command is executed in the @emph{whitespace before a bullet or
-number}, the new item is created @emph{before} the current item. If the
-command is executed in the white space before the text that is part of
-an item but does not contain the bullet, a bullet is added to the
-current line.
address@hidden you do not want the line to be split, customize the
+variable @code{org-M-RET-may-split-line}.}. If this command is executed
+in the @emph{whitespace before a bullet or number}, the new item is
+created @emph{before} the current item. If the command is executed in
+the white space before the text that is part of an item but does not
+contain the bullet, a bullet is added to the current line.
@kindex address@hidden
@item address@hidden
Insert a new item with a checkbox (@pxref{Checkboxes}).
@@ -1191,6 +1208,10 @@
Cycle the entire list level through the different itemize/enumerate
bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}).
With prefix arg, select the nth bullet from this list.
+If there is an active region when calling this, all lines will be
+converted to list items. If the first line already was a list item, any
+item markers will be removed from the list. Finally, even without an
+active region, a normal line will be converted into a list item.
@end table
@node Drawers, orgstruct-mode, Plain lists, Document structure
@@ -1252,7 +1273,7 @@
calculations are supported in connection with the Emacs @file{calc}
package
@ifinfo
-(@pxref{Calc,,,calc,Gnu Emacs Calculator Manual}).
+(@pxref{Top,Calc,,calc,Gnu Emacs Calculator Manual}).
@end ifinfo
@ifnotinfo
(see the Emacs Calculator manual for more information about the Emacs
@@ -1412,7 +1433,9 @@
lines.
@c
@kindex C-c C-q
address@hidden address@hidden
@item C-c C-q
address@hidden address@hidden
Wrap several fields in a column like a paragraph. If there is an active
region, and both point and mark are in the same column, the text in the
column is wrapped to minimum width for the given number of lines. A
@@ -2126,8 +2149,8 @@
Finally, just to whet your appetite on what can be done with the
fantastic @file{calc} package, here is a table that computes the Taylor
-series of degree @code{n} at location @code{x} for a couple of functions
-(homework: try that with Excel :-)
+series of degree @code{n} at location @code{x} for a couple of
+functions.
@example
@group
@@ -2268,6 +2291,7 @@
@cindex links, external
@cindex GNUS links
@cindex BBDB links
address@hidden IRC links
@cindex URL links
@cindex file links
@cindex VM links
@@ -2280,10 +2304,10 @@
@cindex elisp links
Org-mode supports links to files, websites, Usenet and email messages,
-and BBDB database entries. External links are URL-like locators. They
-start with a short identifying string followed by a colon. There can be
-no space after the colon. The following list shows examples for each
-link type.
+BBDB database entries and links to both IRC conversations and their
+logs. External links are URL-like locators. They start with a short
+identifying string followed by a colon. There can be no space after
+the colon. The following list shows examples for each link type.
@example
http://www.astro.uva.nl/~dominik @r{on the web}
@@ -2303,6 +2327,7 @@
gnus:group @r{GNUS group link}
gnus:group#id @r{GNUS article link}
bbdb:Richard Stallman @r{BBDB link}
+irc:/irc.com/#emacs/bob @r{IRC link}
shell:ls *.org @r{A shell command}
elisp:(find-file-other-frame "Elisp.org") @r{An elisp form to evaluate}
@end example
@@ -2343,18 +2368,23 @@
Store a link to the current location. This is a @emph{global} command
which can be used in any buffer to create a link. The link will be
stored for later insertion into an Org-mode buffer (see below). For
-Org-mode files, if there is a @samp{<<target>>} at the cursor, the link
-points to the target. Otherwise it points to the current headline. For
-VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will
-indicate the current article/entry. For W3 and W3M buffers, the link
-goes to the current URL. For any other files, the link will point to
-the file, with a search string (@pxref{Search options}) pointing to the
-contents of the current line. If there is an active region, the
-selected words will form the basis of the search string. If the
-automatically created link is not working correctly or accurately
-enough, you can write custom functions to select the search string and
-to do the search for particular file types - see @ref{Custom searches}.
-The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}.
+Org-mode files, if there is a @samp{<<target>>} at the cursor, the
+link points to the target. Otherwise it points to the current
+headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the
+link will indicate the current article/entry. For W3 and W3M buffers,
+the link goes to the current URL. For IRC links, if you set the
+variable @code{org-irc-link-to-logs} to non-nil then @kbd{C-c l} will
+store a @samp{file:/} style link to the relevant point in the logs for
+the current conversation. Otherwise an @samp{irc:/} style link to the
+user/channel/server under the point will be stored. For any other
+files, the link will point to the file, with a search string
+(@pxref{Search options}) pointing to the contents of the current line.
+If there is an active region, the selected words will form the basis
+of the search string. If the automatically created link is not
+working correctly or accurately enough, you can write custom functions
+to select the search string and to do the search for particular file
+types - see @ref{Custom searches}. The key binding @kbd{C-c l} is
+only a suggestion - see @ref{Installation}.
@c
@kindex C-c C-l
@cindex link completion
@@ -2654,7 +2684,9 @@
@kindex C-u C-c C-t
@item C-u C-c C-t
Select a specific keyword using completion or (if it has been set up)
-the fast selection interface.
+the fast selection interface. For the latter, you need to assign keys
+to TODO states, see @ref{Per-file keywords} and @ref{Setting tags} for
+more information.
@kindex address@hidden
@kindex address@hidden
@@ -2663,15 +2695,6 @@
Select the following/preceding TODO state, similar to cycling. Useful
mostly if more than two TODO states are possible (@pxref{TODO
extensions}).
address@hidden C-c C-c
address@hidden C-c C-c
-Use the fast tag interface to directly select a specific TODO state.
-For this you need to assign keys to TODO states, like this:
address@hidden
-#+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d)
address@hidden example
address@hidden See @ref{Per-file keywords} and @ref{Setting tags} for more
-information.
@kindex C-c C-v
@kindex C-c / t
@cindex sparse tree, for TODO
@@ -2742,10 +2765,12 @@
to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may
also use a prefix argument to quickly select a specific state. For
example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
-If you define many keywords, you can use in-buffer completion (see
address@hidden) to insert these words into the buffer. Changing a
-todo state can be logged with a timestamp, see @ref{Tracking TODO state
-changes} for more information.
+Or you can use @kbd{S-left} to go backward through the sequence. If you
+define many keywords, you can use in-buffer completion
+(@pxref{Completion}) or even a special one-key selection scheme
+(@pxref{Fast access to TODO states}) to insert these words into the
+buffer. Changing a todo state can be logged with a timestamp, see
address@hidden TODO state changes} for more information.
@node TODO types, Multiple sets in one file, Workflow states, TODO extensions
@subsection TODO keywords as types
@@ -2845,7 +2870,8 @@
@code{org-use-fast-todo-selection} to @code{t} and make this behavior
the default. Check also the variable
@code{org-fast-tag-selection-include-todo}, it allows to change the TODO
-state through the tags interface (@pxref{Setting tags}).
+state through the tags interface (@pxref{Setting tags}), in case you
+like to mingle the two concepts.
@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states,
TODO extensions
@subsection Setting up keywords for individual files
@@ -2908,15 +2934,22 @@
("CANCELED" . (:foreground "blue" :weight bold))))
@end lisp
+While using a list with face properties as shown for CANCELED
address@hidden work, this does not aways seem to be the case. If
+necessary, define a special face and use that.
+
@page
@node Progress logging, Priorities, TODO extensions, TODO items
@section Progress Logging
@cindex progress logging
@cindex logging, of progress
-Org-mode can automatically record a time stamp and even a note when you
-mark a TODO item as DONE, or even each time you change the state of
-a TODO item.
+Org-mode can automatically record a time stamp and possibly a note when
+you mark a TODO item as DONE, or even each time you change the state of
+a TODO item. This system is highly configurable, settings can be on a
+per-keyword basis and can be localized to a file or even a subtree. For
+information on how to clock working time for a task, see @ref{Clocking
+work time}.
@menu
* Closing items:: When was this entry marked DONE?
@@ -2926,65 +2959,97 @@
@node Closing items, Tracking TODO state changes, Progress logging, Progress
logging
@subsection Closing items
-If you want to keep track of @emph{when} a certain TODO item was
-finished, turn on logging address@hidden corresponding in-buffer
-setting is: @code{#+STARTUP: logdone}. You may also set this for the
-scope of a subtree by adding a @code{:LOGGING:} property with one or more
-of the logging keywords in the value.}
+The most basic logging is to keep track of @emph{when} a certain TODO
+item was finished. This is achieved address@hidden corresponding
+in-buffer setting is: @code{#+STARTUP: logdone}}.
@lisp
-(setq org-log-done t)
+(setq org-log-done 'time)
@end lisp
@noindent
-Then each time you turn a TODO entry into DONE using either @kbd{C-c
-C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
address@hidden: [timestamp]} will be inserted just after the headline. If
-you turn the entry back into a TODO item through further state cycling,
-that line will be removed again. In the timeline (@pxref{Timeline}) and
-in the agenda (@pxref{Weekly/Daily agenda}), you can then use the
address@hidden key to display the TODO items closed on each day, giving you an
-overview of what has been done on a day. If you want to record a note
-along with the timestamp, address@hidden corresponding in-buffer
-setting is: @code{#+STARTUP: lognotedone}}
+Then each time you turn an entry from a TODO (not-done) state into any
+of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted
+just after the headline. If you turn the entry back into a TODO item
+through further state cycling, that line will be removed again. If you
+want to record a note along with the timestamp, address@hidden
+corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}}
@lisp
-(setq org-log-done '(done))
+(setq org-log-done 'note)
@end lisp
address@hidden
+You will then be prompted for a note, and that note will be stored below
+the entry with a @samp{Closing Note} heading.
+
+In the timeline (@pxref{Timeline}) and in the agenda
+(@pxref{Weekly/Daily agenda}), you can then use the @kbd{l} key to
+display the TODO items with a @samp{CLOSED} timestamp on each day,
+giving you an overview of what has been done.
+
@node Tracking TODO state changes, , Closing items, Progress logging
@subsection Tracking TODO state changes
When TODO keywords are used as workflow states (@pxref{Workflow
states}), you might want to keep track of when a state change occurred
-and record a note about this change. With the address@hidden
-corresponding in-buffer setting is: @code{#+STARTUP: lognotestate}.}
+and maybe take a note about this change. Since it is normally too much
+to record a note for every state, Org-mode expects configuration on a
+per-keyword basis for this. This is achieved by adding special markers
address@hidden (for a time stamp) and @samp{@@} (for a note) in parenthesis
+after each keyword. For example, with the setting
@lisp
-(setq org-log-done '(state))
+(setq org-todo-keywords
+ '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
@end lisp
@noindent
-each state change will prompt you for a note that will be attached to
-the current headline. If you press @kbd{C-c C-c} without typing
-anything into the note buffer, only the time of the state change will be
-noted. Very likely you do not want this verbose tracking all the time,
-so it is probably better to configure this behavior with in-buffer
-options. For example, if you are tracking purchases, put these into a
-separate file that contains:
+you not only define global TODO keywords and fast access keys, but also
+request that a time is recorded when the entry is turned into
address@hidden is possible that Org-mode will record two time stamps
+when you are using both @code{org-log-done} and state change logging.
+However, it will never prompt for two notes - if you have configured
+both, the state change recording note will take precedence and cancel
+the @samp{Closing Note}.}, and that a note is recorded when switching to
+WAIT or CANCELED. The setting for WAIT is even more special: The
address@hidden after the slash means that in addition to the note taken when
+entering the state, a time stamp should be recorded when @i{leaving} the
+WAIT state, if and only if the @i{target} state does not configure
+logging for entering it. So it has no effect when switching from WAIT
+to DONE, because DONE is configured to record a timestamp only. But
+when switching from WAIT back to TODO, the @samp{/!} in the WAIT
+setting now triggers a timestamp even though TODO has no logging
+configured.
+
+You can use the exact same syntax for setting logging preferences local
+to a buffer:
address@hidden
+#+SEQ_TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
address@hidden example
+
+In order to define logging settings that are local to a subtree or a
+single item, define a LOGGING property in this entry. Any non-empty
+LOGGING property resets all logging settings to nil. You may then turn
+on logging for this specific tree using STARTUP keywords like
address@hidden or @code{logrepeat}, as well as adding state specific
+settings like @code{TODO(!)}. For example
@example
-#+SEQ_TODO: TODO(t) ORDERED(o) INVOICE(i) PAYED(p) | RECEIVED(r)
-#+STARTUP: lognotestate
+* TODO Log each state with only a time
+ :PROPERTIES:
+ :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
+ :END:
+* TODO Only log when switching to WAIT, and when repeating
+ :PROPERTIES:
+ :LOGGING: WAIT(@@) logrepeat
+ :END:
+* TODO No logging at all
+ :PROPERTIES:
+ :LOGGING: nil
+ :END:
@end example
-If you only need to take a note for some of the states, mark those
-states with an additional @samp{@@}, like this:
-
address@hidden
-#+SEQ_TODO: TODO(t) ORDERED(o@@) INVOICE(i@@) PAYED(p) | RECEIVED(r)
-#+STARTUP: lognotestate
address@hidden example
@node Priorities, Breaking down tasks, Progress logging, TODO items
@section Priorities
@@ -3067,8 +3132,8 @@
Here is an example of a checkbox list.
@example
-* TODO Organize party [3/6]
- - call people [1/3]
+* TODO Organize party [2/4]
+ - [-] call people [1/3]
- [ ] Peter
- [X] Sarah
- [ ] Sam
@@ -3077,9 +3142,14 @@
- [X] talk to the neighbors
@end example
+Checkboxes work hierarchically, so if a checkbox item has children that
+are checkboxes, toggling one of the children checkboxes will make the
+parent checkbox reflect if none, some, or all of the children are
+checked.
+
@cindex statistics, for checkboxes
@cindex checkbox statistics
-The @samp{[3/6]} and @samp{[1/3]} in the first and second line are
+The @samp{[2/4]} and @samp{[1/3]} in the first and second line are
cookies indicating how many checkboxes present in this entry have been
checked off, and the total number of checkboxes are present. This can
give you an idea on how many checkboxes remain, even without opening a
@@ -3409,7 +3479,7 @@
where properties could be things such as the album artist, date of
release, number of tracks, and so on.
-Properties can be conveiently edited and viewed in column view
+Properties can be conveniently edited and viewed in column view
(@pxref{Column view}).
Properties are like tags, but with a value. For example, in a file
@@ -3551,13 +3621,14 @@
searches}), and the same logic applies. For example, a search string
@example
-+work-boss+PRIORITY="A"+Coffee="unlimited"address@hidden|address@hidden
++work-boss+PRIORITY="A"+Coffee="unlimited"+Effort=""address@hidden|address@hidden
@end example
@noindent
finds entries tagged @samp{:work:} but not @samp{:boss:}, which
also have a priority value @samp{A}, a @samp{:Coffee:} property with the
-value @samp{unlimited}, and a @samp{:With:} property that is matched by
+value @samp{unlimited}, an @samp{Effort} property that is undefined or
+empty, and a @samp{:With:} property that is matched by
the regular expression @samp{Sarah\|Denny}.
You can configure Org-mode to use property inheritance during a search,
@@ -3605,6 +3676,9 @@
@item ARCHIVE
For archiving, the @code{:ARCHIVE:} property may define the archive
location for the entire subtree (@pxref{Moving subtrees}).
address@hidden LOGGING
+The LOGGING property may define logging settings for an entry or a
+subtree (@pxref{Tracking TODO state changes}).
@end table
@node Column view, Property API, Property inheritance, Properties and columns
@@ -3696,6 +3770,8 @@
@address@hidden @r{Currency, short for @samp{+;%.2f}.}
@{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.}
@address@hidden @r{Checkbox status, [X] if all children
are [X].}
+ @{X/@} @r{Checkbox status, [n/m].}
+ @address@hidden @r{Checkbox status, [n%].}
@end example
@noindent
@@ -3712,8 +3788,8 @@
The first column, @samp{%25ITEM}, means the first 25 characters of the
item itself, i.e. of the headline. You probably always should start the
-column definition with the ITEM specifier. The other specifiers create
-columns @samp{Owner} with a list of names as allowed values, for
+column definition with the @samp{ITEM} specifier. The other specifiers
+create columns @samp{Owner} with a list of names as allowed values, for
@samp{Status} with four different possible values, and for a checkbox
field @samp{Approved}. When no width is given after the @samp{%}
character, the column will be exactly as wide as it needs to be in order
@@ -3739,6 +3815,12 @@
property. If none is found, the format is taken from the @code{#+COLUMNS}
line or from the variable @code{org-columns-default-format}, and column
view is established for the current entry and its subtree.
address@hidden r
address@hidden r
+Recreate the column view, to included hanges happening in the buffer.
address@hidden g
address@hidden g
+Same as @kbd{r}.
@kindex q
@item q
Exit column view.
@@ -3791,8 +3873,8 @@
Since column view is just an overlay over a buffer, it cannot be
exported or printed directly. If you want to capture a column view, use
-the dynamic block (@pxref{Dynamic blocks}). The frame of this block
-looks like this:
+ths @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
+of this block looks like this:
@example
* The column view
@@ -3820,6 +3902,12 @@
a hline before each headline with level @code{<= N}.
@item :vlines
When set to @code{t}, enforce column groups to get vertical lines.
address@hidden :maxlevel
+When set to a number, don't capture entries below this level.
address@hidden :skip-empty-rows
+When set to @code{t}, skip row where the only non-empty specifier of the
+column view is @code{ITEM}.
+
@end table
@noindent
@@ -4270,15 +4358,17 @@
@subsection Repeated Tasks
Some tasks need to be repeated again and again. Org-mode helps to
-organize such tasks using a so-called repeater in a DEADLINE or
-SCHEDULED time stamp. In the following example
+organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
+or plain time stamp. In the following example
@example
** TODO Pay the rent
DEADLINE: <2005-10-01 Sat +1m>
@end example
the @code{+1m} is a repeater; the intended interpretation is that the
task has a deadline on <2005-10-01> and repeats itself every (one) month
-starting from that time.
+starting from that time. If you need both a repeater and a special
+warning period in a deadline entry, the repeater comes first and the
+warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
Deadlines and scheduled items produce entries in the agenda when they
are over-due, so it is important to be able to mark such an entry as
@@ -4299,14 +4389,37 @@
You will also be prompted for a address@hidden can change this using
the option @code{org-log-repeat}, or the @code{#+STARTUP} options
address@hidden and @code{nologrepeat}.} that will be put under the
-DEADLINE line to keep a record that you actually acted on the previous
-instance of this deadline.
address@hidden, @code{lognoterepeat}, and @code{nologrepeat}.} that
+will be put under the DEADLINE line to keep a record that you actually
+acted on the previous instance of this deadline.
As a consequence of shifting the base date, this entry will no longer be
visible in the agenda when checking past dates, but all future instances
will be visible.
+With the @samp{+1m} cookie, the date shift will always be exactly one
+month. So if you have not payed the rent for three months, marking this
+entry DONE will still keep it as an overdue deadline. Depending on the
+task, this may not be the best way to handle it. For example, if you
+forgot to call you father for 3 weeks, it does not make sense to call
+her 3 times in a single day to make up for it. Finally, there are tasks
+like changing batteries which should always repeat a certain time
address@hidden the last time you did it. For these tasks, Org-mode has
+special repeaters markes with @samp{++} and @samp{.+}. For example:
+
address@hidden
+** TODO Call Father
+ DEADLINE: <2008-02-10 Sun ++1w>
+ Marking this DONE will shift the date by at least one week,
+ but also by as many weeks as it takes to get this date into
+ the future. However, it stays on a Sunday, even if you called
+ and marked it done on Saturday.
+** TODO Check the batteries in the smoke detectors
+ DEADLINE: <2005-11-01 Tue .+1m>
+ Marking this DONE will shift the date to one month after
+ today.
address@hidden example
+
You may have both scheduling and deadline information for a specific
task - just make sure that the repeater intervals on both are the same.
@@ -4326,16 +4439,16 @@
keyword together with a timestamp. If this is not the first clocking of
this item, the multiple CLOCK lines will be wrapped into a
@code{:CLOCK:} drawer (see also the variable
address@hidden
address@hidden).
@kindex C-c C-x C-o
@item C-c C-x C-o
Stop the clock (clock-out). The inserts another timestamp at the same
location where the clock was last started. It also directly computes
the resulting time in inserts it after the time range as @samp{=>
-HH:MM}. See the variable @code{org-log-done} for the possibility to
-record an additional note together with the clock-out time
address@hidden corresponding in-buffer setting is: @code{#+STARTUP:
-lognoteclock-out}}.
+HH:MM}. See the variable @code{org-log-note-clock-out} for the
+possibility to record an additional note together with the clock-out
+time address@hidden corresponding in-buffer setting is:
address@hidden: lognoteclock-out}}.
@kindex C-c C-y
@item C-c C-y
Recompute the time interval after changing one of the time stamps. This
@@ -4393,6 +4506,8 @@
@address@hidden, @code{lastmonth}, @code{thisyear}, or
@code{lastyear}}.
:tstart @r{A time string specifying when to start considering times}
:tend @r{A time string specifying when to stop considering times}
+:step @address@hidden or @code{day}, to split the table into chunks}
+:link @r{Link the item headlines in the table to their origins}
@end example
So to get a clock summary of the current level 1 tree, for the current
day, you could write
@@ -4466,7 +4581,9 @@
but it makes a few things easier: If there is an active region, it will
automatically copy the region into the remember buffer. It also allows
to jump to the buffer and location where remember notes are being
-stored: Just call @code{org-remember} with a prefix argument.
+stored: Just call @code{org-remember} with a prefix argument. If you
+use two prefix arguments, Org-mode jumps to the location where the last
+remember note was stored.
@node Remember templates, Storing notes, Setting up remember, Remember
@section Remember templates
@@ -4494,6 +4611,26 @@
@code{org-default-notes-file}, the heading to
@code{org-remember-default-headline}.
+An optional sixth element specifies the contexts in which the user can
+select the template. This element can be either a list of major modes
+or a function. @code{org-remember} will first check whether the function
+returns @code{t} or if we are in any of the listed major mode, and select
+the template accordingly.
+
+So for example:
+
address@hidden
+(setq org-remember-templates
+ '(("Bug" ?b "* BUG %?\n %i\n %a" "~/org/BUGS.org" "Bugs" (emacs-lisp-mode))
+ ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org" my-check)
+ ("Idea" ?i "* address@hidden@}\n %i\n %a" "~/org/JOURNAL.org" "New
Ideas")))
address@hidden example
+
+The first template will only be available when invoking @code{org-remember}
+from an buffer in @code{emacs-lisp-mode}. The second template will only be
+available when the function @code{my-check} returns @code{t}. The third
+template will be proposed in any context.
+
When you call @kbd{M-x remember} (or @kbd{M-x org-remember}) to remember
something, org will prompt for a key to select the template (if you have
more than one template) and then prepare the buffer like
@@ -4541,6 +4678,7 @@
Link type | Available keywords
-------------------+----------------------------------------------
bbdb | %:name %:company
+bbdb | %::server %:port %:nick
vm, wl, mh, rmail | %:type %:subject %:message-id
| %:from %:fromname %:fromaddress
| %:to %:toname %:toaddress
@@ -4559,7 +4697,7 @@
@end example
@noindent
-If you change you mind about which template to use, call
+If you change your mind about which template to use, call
@code{org-remember} in the remember buffer. You may then select a new
template that will be filled with the previous context information.
@@ -4633,13 +4771,16 @@
refiling the entry and lets you select one with completion. The item is
filed below the target heading as a subitem. Depending on
@code{org-reverse-note-order}, it will be either the first of last
-subitem, and you can toggle the value of this variable for the duration
-of the command by using a @kbd{C-u} address@hidden By default, all level 1
-headlines in the current buffer are considered to be targets, but you
-can have more complex definitions across a number of files. See the
-variable @code{org-refile-targets} for details. The list of targets is
-compiled upon first use, you can update it by using a double prefix
-argument (@kbd{C-u C-u}) to this command.
address@hidden By default, all level 1 headlines in the current buffer are
+considered to be targets, but you can have more complex definitions
+across a number of files. See the variable @code{org-refile-targets}
+for details.
address@hidden C-u C-c C-w
address@hidden C-u C-c C-w
+Use the refile interface to jump to a heading.
address@hidden C-u C-u C-c C-w
address@hidden C- C-u C-c C-w
+Jump to the location where @code{org-refile} last moved a tree to.
@end table
@node Agenda views, Embedded LaTeX, Remember, Top
@@ -4653,7 +4794,7 @@
sorted and displayed in an organized way.
Org-mode can select items based on various criteria, and display them
-in a separate buffer. Six different view types are provided:
+in a separate buffer. Seven different view types are provided:
@itemize @bullet
@item
@@ -4669,6 +4810,9 @@
a @emph{timeline view} that shows all events in a single Org-mode file,
in time-sorted view,
@item
+a @emph{keyword search view} that shows all entries from multiple files
+that contain specified keywords.
address@hidden
a @emph{stuck projects view} showing projects that currently don't move
along, and
@item
@@ -4793,14 +4937,17 @@
tags and properties}).
@item L
Create the timeline view for the current buffer (@pxref{Timeline}).
address@hidden # @r{/} !
-Create a list of stuck projects (@pxref{Stuck projects}).
address@hidden s
+Create a list of entries selected by a boolean expression of keywords
+and/or regular expressions that must or must not occur in the entry.
@item /
Search for a regular expression in all agenda files and additionally in
the files listed in @code{org-agenda-multi-occur-extra-files}. This
uses the Emacs command @code{multi-occur}. A prefix argument can be
used to specify the number of context lines for each match, default is
1.
address@hidden # @r{/} !
+Create a list of stuck projects (@pxref{Stuck projects}).
@item <
Restrict an agenda command to the current address@hidden backward
compatibility, you can also press @kbd{1} to restrict to the current
@@ -4830,6 +4977,7 @@
* Global TODO list:: All unfinished action items
* Matching tags and properties:: Structured information with fine-tuned search
* Timeline:: Time-sorted view for single file
+* Keyword search:: Finding entries by keyword
* Stuck projects:: Find projects you need to review
@end menu
@@ -5003,7 +5151,7 @@
The commands available in the tags list are described in @ref{Agenda
commands}.
address@hidden Timeline, Stuck projects, Matching tags and properties, Built-in
agenda views
address@hidden Timeline, Keyword search, Matching tags and properties, Built-in
agenda views
@subsection Timeline for a single file
@cindex timeline, single file
@cindex time-sorted view
@@ -5024,8 +5172,36 @@
The commands available in the timeline buffer are listed in
@ref{Agenda commands}.
address@hidden Keyword search, Stuck projects, Timeline, Built-in agenda views
address@hidden Keyword search
address@hidden keyword search
address@hidden searching, for keywords
+
+This agenda view is a general text search facility for Org-mode entries.
+It is particularly useful to find notes.
+
address@hidden @kbd
address@hidden C-c a s
address@hidden C-c a s
+This is a special search that lets you select entries by keywords or
+regular expression, using a boolean logic. For example, the search
+string
+
address@hidden
++computer +wifi -ethernet address@hidden@}
address@hidden example
+
address@hidden
+will search for note entries that contain the keywords @code{computer}
+and @code{wifi}, but not the keyword @code{ethernet}, and which are also
+not matched by the regular expression @code{8\.11[bg]}, meaning to
+exclude both 8.11b and 8.11g.
+
+Note that in addition to the agenda files, this command will also search
+the files listed in @code{org-agenda-text-search-extra-files}.
address@hidden table
address@hidden Stuck projects, , Timeline, Built-in agenda views
address@hidden Stuck projects, , Keyword search, Built-in agenda views
@subsection Stuck projects
If you are following a system like David Allen's GTD to organize your
@@ -5281,8 +5457,8 @@
@item D
Toggle the inclusion of diary entries. See @ref{Weekly/Daily agenda}.
@c
address@hidden g
address@hidden g
address@hidden G
address@hidden G
Toggle the time grid on and off. See also the variables
@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
@c
@@ -5293,6 +5469,9 @@
address@hidden When the buffer is the global todo list, a prefix
argument is interpreted to create a selective list for a specific TODO
keyword.
address@hidden g
address@hidden g
+Same as @kbd{r}.
@c
@kindex s
@kindex C-x C-s
@@ -5314,6 +5493,23 @@
@item .
Goto today.
address@hidden editing}
address@hidden query editing, in agenda
+
address@hidden [
address@hidden ]
address@hidden @{
address@hidden @}
address@hidden [ ] @{ @}
+In the @i{search view} (@pxref{Keyword search}), these keys add new
+search words (@kbd{[} and @kbd{]}) or new regular expressions (@address@hidden
+and @address@hidden) to the query string. The opening bracket/brace will add a
+positive search term prefixed by @samp{+}, indicating that this search
+term @i{must} occur/match in the entry. Closing bracket/brace add a
+negative search term which @i{must not} occur/match in the entry for it
+to be selected.
+
+
@tsubheading{Remote editing}
@cindex remote editing, from agenda
@@ -5595,11 +5791,11 @@
@group
(setq org-agenda-custom-commands
'(("h" "Agenda and Home-related tasks"
- ((agenda)
+ ((agenda "")
(tags-todo "home")
(tags "garden")))
("o" "Agenda and Office-related tasks"
- ((agenda)
+ ((agenda "")
(tags-todo "work")
(tags "office")))))
@end group
@@ -5612,7 +5808,6 @@
@samp{home}, and also all lines tagged with @samp{garden}. Finally the
command @kbd{C-c a o} provides a similar view for office tasks.
-
@node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda
views
@subsection Setting Options for custom commands
@cindex options, for custom agenda views
@@ -5632,7 +5827,10 @@
(org-agenda-prefix-format " Mixed: ")))
("U" tags-tree "+boss-urgent"
((org-show-following-heading nil)
- (org-show-hierarchy-above nil)))))
+ (org-show-hierarchy-above nil)))
+ ("N" search ""
+ ((org-agenda-files '("~org/notes.org"))
+ (org-agenda-text-search-extra-files nil)))))
@end group
@end lisp
@@ -5642,7 +5840,8 @@
instead of giving the category of the entry. The sparse tags tree of
@kbd{C-c a U} will now turn out ultra-compact, because neither the
headline hierarchy above the match, nor the headline following the match
-will be shown.
+will be shown. The command @kbd{C-c a N} will do a text search limited
+to only a single file.
For command sets creating a block agenda,
@code{org-agenda-custom-commands} has two separate spots for setting
@@ -5686,8 +5885,8 @@
If you are away from your computer, it can be very useful to have a
printed version of some agenda views to carry around. Org-mode can
export custom agenda views as plain text, address@hidden need to
-install Hrvoje Niksic' @file{htmlize.el}.} and postscript. If you want
-to do this only occasionally, use the command
+install Hrvoje Niksic' @file{htmlize.el}.} postscript, and iCalendar
+files. If you want to do this only occasionally, use the command
@table @kbd
@kindex C-x C-w
@@ -5696,10 +5895,12 @@
@cindex agenda views, exporting
Write the agenda view to a file. Depending on the extension of the
selected file name, the view will be exported as HTML (extension
address@hidden or @file{.htm}), Postscript (extension @file{.ps}), or
-plain text (any other extension). Use the variable
address@hidden to set options for @file{ps-print}
-and for @file{htmlize} to be used during export, for example
address@hidden or @file{.htm}), Postscript (extension @file{.ps}),
+iCalendar (extension @file{.ics}), or plain text (any other extension).
+Use the variable @code{org-agenda-exporter-settings} to
+set options for @file{ps-print} and for @file{htmlize} to be used during
+export, for example
+
@lisp
(setq org-agenda-exporter-settings
'((ps-number-of-columns 2)
@@ -5712,10 +5913,10 @@
any custom agenda command with a list of output file names
@footnote{If you want to store standard views like the weekly agenda
or the global TODO list as well, you need to define custom commands for
-them in order to be able to specify filenames.}. Here is an example
+them in order to be able to specify file names.}. Here is an example
that first does define custom commands for the agenda and the global
todo list, together with a number of files to which to export them.
-Then we define two block agenda commands and specify filenames for them
+Then we define two block agenda commands and specify file names for them
as well. File names can be relative to the current working directory,
or absolute.
@@ -5725,7 +5926,7 @@
'(("X" agenda "" nil ("agenda.html" "agenda.ps"))
("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
("h" "Agenda and Home-related tasks"
- ((agenda)
+ ((agenda "")
(tags-todo "home")
(tags "garden"))
nil
@@ -5735,7 +5936,7 @@
(tags-todo "work")
(tags "office"))
nil
- ("~/views/office.ps"))))
+ ("~/views/office.ps" "~/calendars/office.ics"))))
@end group
@end lisp
@@ -5743,16 +5944,20 @@
@file{.html}, Org-mode will use the @file{htmlize.el} package to convert
the buffer to HTML and save it to this file name. If the extension is
@file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
-postscript output. Any other extension produces a plain ASCII file.
+postscript output. If the extension is @file{.ics}, iCalendar export is
+run export over all files that were used to construct the agenda, and
+limit the export to entries listed in the agenda now. Any other
+extension produces a plain ASCII file.
The export files are @emph{not} created when you use one of those
-commands interactively. Instead, there is a special command to produce
address@hidden specified files in one step:
+commands interactively because this might use too much overhead.
+Instead, there is a special command to produce @emph{all} specified
+files in one step:
@table @kbd
@kindex C-c a e
@item C-c a e
-Export all agenda views that have export filenames associated with
+Export all agenda views that have export file names associated with
them.
@end table
@@ -7318,24 +7523,26 @@
align @r{align all tables}
noalign @r{don't align tables on startup}
@end example
-Logging TODO state changes and clock intervals (variables
address@hidden and @code{org-log-repeat}) can be configured using
-these options.
+Logging closing and reinstating TODO items, and clock intervals
+(variables @code{org-log-done}, @code{org-log-note-clock-out}, and
address@hidden) can be configured using these options.
@cindex @code{logdone}, STARTUP keyword
address@hidden @code{nologging}, STARTUP keyword
@cindex @code{lognotedone}, STARTUP keyword
address@hidden @code{nologdone}, STARTUP keyword
@cindex @code{lognoteclock-out}, STARTUP keyword
address@hidden @code{lognotestate}, STARTUP keyword
address@hidden @code{nolognoteclock-out}, STARTUP keyword
@cindex @code{logrepeat}, STARTUP keyword
address@hidden @code{lognoterepeat}, STARTUP keyword
@cindex @code{nologrepeat}, STARTUP keyword
@example
-logging @r{record a timestamp when an item is marked DONE}
-nologging @r{don't record when items are marked DONE}
+logdone @r{record a timestamp when an item is marked DONE}
lognotedone @r{record timestamp and a note when DONE}
-lognotestate @r{record timestamp and a note when TODO state changes}
-logrepeat @r{record a note when re-instating a repeating item}
-nologrepeat @r{do not record when re-instating repeating item}
-lognoteclock-out @r{record timestamp and a note when clocking out}
+nologdone @r{don't record when items are marked DONE}
+logrepeat @r{record a time when reinstating a repeating item}
+lognoterepeat @r{record a note when reinstating a repeating item}
+nologrepeat @r{do not record when reinstating repeating item}
+lognoteclock-out @r{record a note when clocking out}
+nolognoteclock-out @r{don't record a note when clocking out}
@end example
Here are the options for hiding leading stars in outline headings. The
corresponding variables are @code{org-hide-leading-stars} and
@@ -8270,8 +8477,11 @@
Updating a dynamic block means to remove all the text between BEGIN and
END, parse the BEGIN line for parameters and then call the specific
-writer function for this block to insert the new content. For a block
-with name @code{myblock}, the writer function is
+writer function for this block to insert the new content. If you want
+to use the original content in the writer function, you can use the
+extra parameter @code{:content}.
+
+For a block with name @code{myblock}, the writer function is
@code{org-dblock-write:myblock} with as only parameter a property list
with the parameters given in the begin line. Here is a trivial example
of a block that keeps track of when the block update function was last
@@ -8487,6 +8697,8 @@
@item
@i{Nic Ferrier} contributed mailcap and XOXO support.
@item
address@hidden A. Figueroa-Villanueva} implemented hierarchical checkboxes.
address@hidden
@i{John Foerch} figured out how to make incremental search show context
around a match in a hidden outline tree.
@item
@@ -8607,3 +8819,4 @@
@ignore
arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac
@end ignore
+)
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/doc/misc/org.texi,v,
Carsten Dominik <=