ndwarshuis
/
org-mode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add documentation for capture

This commit is contained in:
Carsten Dominik 2010-06-25 16:40:47 +02:00
parent 7f21f76d5e
commit 8f83ac51ee
1 changed files with 242 additions and 211 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

453
doc/org.texi
View File

@ -251,18 +251,23 @@ Deadlines and scheduling
Capture - Refile - Archive
* Remember:: Capture new tasks/ideas with little interruption
* Attachments:: Add files to tasks.
* Capture:: Capturing new stuff
* Attachments:: Add files to tasks
* RSS Feeds:: Getting input from RSS feeds
* Protocols:: External (e.g. Browser) access to Emacs and Org
* Refiling notes:: Moving a tree from one place to another
* Archiving:: What to do with finished projects
Remember
Capture
* Setting up Remember for Org:: Some code for .emacs to get things going
* Remember templates:: Define the outline of different note types
* Storing notes:: Directly get the note to where it belongs
* Setting up a capture location:: Where notes will be stored
* Using capture:: Commands to invoke and terminate capture
* Capture templates:: Define the outline of different note types
Capture templates
* Template elements:: What is needed for a complete template entry
* Template expansion:: Filling in information about time and context
Archiving
@ -4373,26 +4378,6 @@ 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}.
@vindex org-complete-tags-always-offer-all-agenda-tags
As said before, when setting tags and @code{org-tag-alist} is nil, then the
list of tags in the current buffer is used. Normally, this behavior is very
convenient, except in org remember buffers (@pxref{Remember}), because there
are no tags that can be calculated dynamically. Here, you most probably want
to have completion for all tags in all agenda files. This can be done by
setting @code{org-complete-tags-always-offer-all-agenda-tags} to non-nil in
those buffers.
@lisp
(add-hook 'org-remember-mode-hook
(lambda ()
(set (make-local-variable
'org-complete-tags-always-offer-all-agenda-tags)
t)))
@end lisp
Of course, you can also set it to @code{t} globally if you always want to
have completion of all tags in all agenda files.
@node Tag searches, , Setting tags, Tags
@section Tag searches
@cindex tag searches
@ -5898,155 +5883,268 @@ not started at exactly the right moment.
An important part of any organization system is the ability to quickly
capture new ideas and tasks, and to associate reference material with them.
Org uses the @file{remember.el} package to create tasks, and stores files
Org does this using a process called @i{capture}. It also can store files
related to a task (@i{attachments}) in a special directory. Once in the
system, tasks and projects need to be moved around. Moving completed project
trees to an archive file keeps the system compact and fast.
@menu
* Remember:: Capture new tasks/ideas with little interruption
* Attachments:: Add files to tasks.
* Capture:: Capturing new stuff
* Attachments:: Add files to tasks
* RSS Feeds:: Getting input from RSS feeds
* Protocols:: External (e.g. Browser) access to Emacs and Org
* Refiling notes:: Moving a tree from one place to another
* Archiving:: What to do with finished projects
@end menu
@node Remember, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
@section Remember
@cindex @file{remember.el}
@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
@section Capture
@cindex capture
The Remember package by John Wiegley lets you store quick notes with little
interruption of your work flow. It is an excellent way to add new notes and
tasks to Org files. The @code{remember.el} package is part of Emacs 23, not
Emacs 22. See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for
more information.
Org significantly expands the possibilities of Remember: you may define
templates for different note types, and associate target files and headlines
with specific templates. It also allows you to select the location where a
note should be stored interactively, on the fly.
Org's method for capturing new items is heavily inspired by John Wiegley
excellent remember package@footnote{Up to version 6.36 Org actually did use a
special setup for @file{remember.el}. @file{org-remember.el} is still part
of Org-mode for backward compatibility with existing setups. But the new
capturing setup described here is preferred and should be used by new users.}
which lets you store quick notes with little interruption of your work flow.
The basic process of capturing is very similar to remember, but Org does
enhance it with templates and more.
@menu
* Setting up Remember for Org:: Some code for .emacs to get things going
* Remember templates:: Define the outline of different note types
* Storing notes:: Directly get the note to where it belongs
* Setting up a capture location:: Where notes will be stored
* Using capture:: Commands to invoke and terminate capture
* Capture templates:: Define the outline of different note types
@end menu
@node Setting up Remember for Org, Remember templates, Remember, Remember
@subsection Setting up Remember for Org
@node Setting up a capture location, Using capture, Capture, Capture
@subsection Setting up a capture location
The following customization will tell Remember to use Org files as
target, and to create annotations compatible with Org links.
The following customization sets a default target@footnote{Using capture
templates, you can define more fine-grained capture locations, see
@ref{Capture templates}.} file for notes, and defines a global
key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.}
for capturing new stuff.
@example
(org-remember-insinuate)
(setq org-directory "~/path/to/my/orgfiles/")
(setq org-default-notes-file (concat org-directory "/notes.org"))
(define-key global-map "\C-cr" 'org-remember)
(define-key global-map "\C-cc" 'org-capture)
@end example
@noindent
The last line binds the command @code{org-remember} to a global
key@footnote{Please select your own key, @kbd{C-c r} is only a
suggestion.}. @code{org-remember} basically just calls Remember,
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. If you
use two prefix arguments, Org jumps to the location where the last
remember note was stored.
@node Using capture, Capture templates, Setting up a capture location, Capture
@subsection Using capture
The Remember buffer will actually use @code{org-mode} as its major mode, so
that all editing features of Org mode are available. In addition to this, a
minor mode @code{org-remember-mode} is turned on, for the single purpose that
you can use its keymap @code{org-remember-mode-map} to override some of
Org mode's key bindings.
@table @kbd
@kindex C-c c
@item C-c c
Call the command @code{org-capture}. If you have templates defined
@pxref{Capture templates}, it will offer these templates for selection or use
a new Org outline node as the default template. It will insert the template
into the target file and switch to an indirect buffer narrowed to this new
node. You may then insert the information you want.
You can also call @code{org-remember} in a special way from the agenda,
using the @kbd{k r} key combination. With this access, any timestamps
inserted by the selected Remember template (see below) will default to
@kindex C-c C-c
@item C-c C-c
Once you are done entering information into the capture buffer,
@kbd{C-c C-c} will return you to the window configuration before the capture
process, so that you can resume your work without further distraction.
@kindex C-c C-w
@item C-c C-w
When this command is used in the capture buffer, it will finalize the capture
process by refiling (@pxref{Refiling notes}) the note to a different place.
@kindex C-c C-k
@item C-c C-k
Abort the capture process and return to the previous state.
@end table
You can also call @code{org-capture} in a special way from the agenda,
using the @kbd{k c} key combination. With this access, any timestamps
inserted by the selected capture template (see below) will default to
the cursor date in the agenda, rather than to the current date.
@node Remember templates, Storing notes, Setting up Remember for Org, Remember
@subsection Remember templates
@cindex templates, for Remember
@node Capture templates, , Using capture, Capture
@subsection Capture templates
@cindex templates, for Capture
In combination with Org, you can use templates to generate
different types of Remember notes. For example, if you would like
to use one template to create general TODO entries, another one for
journal entries, and a third one for collecting random ideas, you could
use:
You can use templates to arrange for different types of capture items, and
for different target locations. The easiest way to set up such templates is
through the customize interface.
@table @kbd
@kindex C-c c C
@item C-c c C
Customize the variable @code{org-capture-templates}.
@end table
Before we give the formal description of template definitions, let's look at
an example. Say you would like to use one template to create general TODO
entries, and you want to put these entries under the heading @samp{Tasks} in
your file @file{~/org/gtd.org}. Also, a date tree in the file
@file{journal.org} should capture journal entries. A possible configuration
would then look like this:
@example
(setq org-remember-templates
'(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks")
("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
(setq org-capture-templates
'(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
"* TODO %?\n %i\n %a")
("j" "Journal" entry (file+datetree "~/org/journal.org")
"* %?\nEntered on %U\n %i\n %a")))
@end example
@vindex org-remember-default-headline
@vindex org-directory
@noindent In these entries, the first string is just a name, and the
character specifies how to select the template. It is useful if the
character is also the first letter of the name. The next string specifies
the template. Two more (optional) strings give the file in which, and the
headline under which, the new note should be stored. The file (if not
present or @code{nil}) defaults to @code{org-default-notes-file}, the heading
to @code{org-remember-default-headline}. If the file name is not an absolute
path, it will be interpreted relative to @code{org-directory}.
The heading can also be the symbols @code{top} or @code{bottom} to send notes
as level 1 entries to the beginning or end of the file, respectively. It may
also be the symbol @code{date-tree}. Then, a tree with year on level 1,
month on level 2 and day on level three will be built in the file, and the
entry will be filed into the tree under the current date@footnote{If the file
contains an entry with a @code{DATE_TREE} property (arbitrary value), the
entire date tree will be built under that entry.}
An optional sixth element specifies the contexts in which the user can select
the template. This element can be 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 modes, and exclude templates for which
this condition is not fulfilled. Templates that do not specify this element
at all, or that use @code{nil} or @code{t} as a value will always be
selectable.
So for example:
@example
(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" "X" my-check)
("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
@end example
@noindent
The first template will only be available when invoking @code{org-remember}
from a 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 org-remember} (or @kbd{M-x 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
@noindent If you then press @kbd{C-c c t}, Org will prepare the template
for you like this:
@example
* TODO
[[file:@var{link to where you called remember}]]
[[file:@var{link to where you initiated capture}]]
@end example
@noindent
During expansion of the template, special @kbd{%}-escapes@footnote{If you
need one of these sequences literally, escape the @kbd{%} with a backslash.}
allow dynamic insertion of content:
During expansion of the template, @code{%a} has been replaced by a link to
the location from where you called the capture command. This can be
extremely useful for deriving tasks from emails, for example. You fill in
the task definition, press @code{C-c C-c} and Org puts you back into the same
place where you started the capture process.
@menu
* Template elements:: What is needed for a complete template entry
* Template expansion:: Filling in information about time and context
@end menu
@node Template elements, Template expansion, Capture templates, Capture templates
@subsubsection Template elements
Now lets look at the elements of a template defintion. Each entry in
@code{org-capture-templates} is a list with the following items:
@table @var
@item keys
The keys that will select the template, as a string, characters
only, for example @code{"a"} for a template to be selected with a
single key, or @code{"bt"} for selection with two keys. When using
several keys, keys using the same prefix key must be sequential
in the list and preceded by a 2-element entry explaining the
prefix key, for example
@example
("b" "Templates for marking stuff to buy")
@end example
@noindent If you do not define a template for the @kbd{C} key, this key will
be used to open the customize buffer for this complex variable.
@item description
A short string describing the template, which will be shown during
selection.
@item type
The type of entry, a symbol. Valid values are:
@table @code
@item entry
An Org-mode node, with a headline. Will be filed as the child of the
target entry or as a top-level entry. The target file should be an Org-mode
file.
@item item
A plain list item, placed in the first plain list a the target
location. Again the target file should be an Org file.
@item checkitem
A checkbox item. This only differs from the plain lis item by the
default template.
@item table-line
a new line in the first table at target location. Where exactly the
line will be inserted depends on the properties @code{:prepend} and
@code{:table-line-pos} (see below)
@item plain
Text to be inserted as it is.
@end table
@item target
Specification of where the captured item should be placed.
In Org-mode files, targets usually define a node. Entries will become
children of this node, other types will be added to the table or list in the
body of this node.
Valid values are:
@table @code
@item (file "path/to/file")
Text will be placed at the beginning or end of that file
@item (id "id of existing org entry")
Filing as child of this entry, or in the body of the entry
@item (file+headline "path/to/file" "node headline")
Fast configuration if the target heading is unique in the file
@item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
For non-unique headings, the full path is safer.
@item (file+regexp "path/to/file" "regexp to find location")
@item (file+datetree "path/to/file")
Will create a heading in a date tree.
@item (file+function "path/to/file" function-finding-location)
A function to find the right location in the file.
@item (clock)
File to the entry that is currently being clocked.
@item (function function-finding-location)
Most general way, write your own function to find both
file and location.
@end table
@item template
The template for creating the capture item. If you leave this
empty, an appropriate default template will be used. Otherwise this is a
string with a number of escape code, which will be replaced depending on time
and context of the capture call. See below for more details.
@item properties
The rest of the entry is a property list of additional options.
Recognized properties are:
@table @code
@item :prepend
Normally new captured information will be appended at
the target location (last child, last table line, last list item...).
Setting this property will change that.
@item :immediate-finish
When set, do not offer to edit the information, just
file it away immediately. This makes sense if the template only needs
information that can be added automatically.
@item :empty-lines
Set this to the number of lines the should be inserted
before and after the new item. Default 0, only common other value is 1.
@item :clock-in
Start the clock in this item.
@item :clock-resume
If Starting the capture interrupted a clock, restart that clock when done
with the capture.
@item :unnarrowed
Do not narrow the target buffer, simply show the full buffer. Default is to
narrow it so that you only see the new stuff.
@end table
@end table
@node Template expansion, , Template elements, Capture templates
@subsubsection Template expansion
In the template itself, special @kbd{%}-escapes@footnote{If you need one of
these sequences literally, escape the @kbd{%} with a backslash.} allow
dynamic insertion of content:
@smallexample
%^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
@r{You may specify a default value and a completion table with}
@r{%^@{prompt|default|completion2|completion3...@}}
@r{The arrow keys access a prompt-specific history.}
%a @r{annotation, normally the link created with @code{org-store-link}}
%A @r{like @code{%a}, but prompt for the description part}
%i @r{initial content, the region when remember is called with C-u.}
%i @r{initial content, the region when capture is called while the}
@r{region is active.}
@r{The entire text will be indented like @code{%i} itself.}
%t @r{timestamp, date only}
%T @r{timestamp with date and time}
@ -6069,17 +6167,17 @@ allow dynamic insertion of content:
%! @r{immediately store note after completing the template}
@r{(skipping the @kbd{C-c C-c} that normally triggers storing)}
%& @r{jump to target location immediately after storing note}
@end example
@end smallexample
@noindent
For specific link types, the following keywords will be
defined@footnote{If you define your own link types (@pxref{Adding
hyperlink types}), any property you store with
@code{org-store-link-props} can be accessed in remember templates in a
@code{org-store-link-props} can be accessed in capture templates in a
similar way.}:
@vindex org-from-is-user-regexp
@example
@smallexample
Link type | Available keywords
-------------------+----------------------------------------------
bbdb | %:name %:company
@ -6092,83 +6190,17 @@ gnus | %:group, @r{for messages also all email fields}
w3, w3m | %:url
info | %:file %:node
calendar | %:date"
@end example
@end smallexample
@noindent
To place the cursor after template expansion use:
@example
@smallexample
%? @r{After completing the template, position cursor here.}
@end example
@noindent
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.
@node Storing notes, , Remember templates, Remember
@subsection Storing notes
@vindex org-remember-clock-out-on-exit
When you are finished preparing a note with Remember, you have to press
@kbd{C-c C-c} to file the note away. If you have started the clock in the
Remember buffer, you will first be asked if you want to clock out
now@footnote{To avoid this query, configure the variable
@code{org-remember-clock-out-on-exit}.}. If you answer @kbd{n}, the clock
will continue to run after the note was filed away.
The handler will then store the note in the file and under the headline
specified in the template, or it will use the default file and headline. The
window configuration will be restored, sending you back to the working
context before the call to Remember. To re-use the location found during the
last call to Remember, exit the Remember buffer with @kbd{C-0 C-c C-c},
i.e. specify a zero prefix argument to @kbd{C-c C-c}. Another special case
is @kbd{C-2 C-c C-c} which files the note as a child of the currently clocked
item, and @kbd{C-3 C-c C-c} files as a sibling of the currently clocked item.
@vindex org-remember-store-without-prompt
If you want to store the note directly to a different place, use
@kbd{C-1 C-c C-c} instead to exit Remember@footnote{Configure the
variable @code{org-remember-store-without-prompt} to make this behavior
the default.}. The handler will then first prompt for a target file---if
you press @key{RET}, the value specified for the template is used.
Then the command offers the headings tree of the selected file, with the
cursor position at the default headline (if you specified one in the
template). You can either immediately press @key{RET} to get the note
placed there. Or you can use the following keys to find a different
location:
@example
@key{TAB} @r{Cycle visibility.}
@key{down} / @key{up} @r{Next/previous visible headline.}
n / p @r{Next/previous visible headline.}
f / b @r{Next/previous headline same level.}
u @r{One level up.}
@c 0-9 @r{Digit argument.}
@end example
@noindent
Pressing @key{RET} or @key{left} or @key{right}
then leads to the following result.
@vindex org-reverse-note-order
@multitable @columnfractions 0.2 0.15 0.65
@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor, first or last
@item @tab @tab depending on @code{org-reverse-note-order}.
@item @tab @key{left}/@key{right} @tab as same level, before/after current heading
@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file or level 1 at beginning
@item @tab @tab depending on @code{org-reverse-note-order}.
@item not on headline @tab @key{RET}
@tab at cursor position, level taken from context.
@end multitable
Before inserting the text into a tree, the function ensures that the text has
a headline, i.e. a first line that starts with a @samp{*}. If not, a
headline is constructed from the current date. If you have indented the text
of the note below the headline, the indentation will be adapted if inserting
the note into the tree requires demotion from level 1.
@end smallexample
@node Attachments, RSS Feeds, Remember, Capture - Refile - Archive
@node Attachments, RSS Feeds, Capture, Capture - Refile - Archive
@section Attachments
@cindex attachments
@ -6320,7 +6352,7 @@ For more information, see @file{org-feed.el} and the docstring of
You can set up Org for handling protocol calls from outside applications that
are passed to Emacs through the @file{emacsserver}. For example, you can
configure bookmarks in your web browser to send a link to the current page to
Org and create a note from it using Remember (@pxref{Remember}). Or you
Org and create a note from it using capture (@pxref{Capture}). Or you
could create a bookmark that will tell Emacs to open the local source file of
a remote website you are looking at with the browser. See
@uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed
@ -7742,7 +7774,7 @@ m @r{Mark the entry at point for action. You can also make entries}
@r{in Org files with @kbd{C-c C-x C-k}.}
d @r{Set the deadline of the marked entry to the date at point.}
s @r{Schedule the marked entry at the date at point.}
r @r{Call @code{org-remember} with the cursor date as default date.}
r @r{Call @code{org-capture} with the cursor date as default date.}
@end example
@noindent
Press @kbd{r} afterward to refresh the agenda and see the effect of the
@ -12518,7 +12550,7 @@ works even if the automatic table editor has been turned off.
If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
the entire table.
@item
If the current buffer is a Remember buffer, close the note and file it.
If the current buffer is a capture buffer, close the note and file it.
With a prefix argument, file it, without further interaction, to the
default location.
@item
@ -12766,8 +12798,7 @@ the option @code{org-imenu-depth}.
@item @file{remember.el} by John Wiegley
@cindex @file{remember.el}
@cindex Wiegley, John
Org cooperates with remember, see @ref{Remember}.
As of Emacs 23, @file{Remember.el} is part of the Emacs distribution.
Org used to use this package for capture, but no longer does.
@item @file{speedbar.el} by Eric M. Ludlam
@cindex @file{speedbar.el}
@cindex Ludlam, Eric M.
@ -14069,7 +14100,7 @@ Org-mode website.
@i{Tom Breton} wrote @file{org-choose.el}.
@item
@i{Charles Cave}'s suggestion sparked the implementation of templates
for Remember.
for Remember, which are now templates for capture.
@item
@i{Pavel Chalmoviansky} influenced the agenda treatment of items with
specified time.