Add documentation for capture

doc/org.texi

@@ -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}
-
-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.
+@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
+@section Capture
+@cindex capture
 
-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.
-
-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.
-
-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
-the cursor date in the agenda, rather than to the current date.
+@node Using capture, Capture templates, Setting up a capture location, Capture
+@subsection Using capture
 
-@node Remember templates, Storing notes, Setting up Remember for Org, Remember
-@subsection Remember templates
-@cindex templates, for Remember
+@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.
 
-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:
+@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.
 
-@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")))
-@end example
+@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.
 
-@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}.
+@node Capture templates,  , Using capture, Capture
+@subsection Capture templates
+@cindex templates, for Capture
 
-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.}
+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.
 
-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.
+@table @kbd
+@kindex C-c c C
+@item C-c c C
+Customize the variable @code{org-capture-templates}.
+@end table
 
-So for example:
+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
- '(("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")))
+(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
 
-@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.