Merge branch 'master' of git+ssh://repo.or.cz/srv/git/org-mode

doc/org.texi

@@ -5902,13 +5902,25 @@ trees to an archive file keeps the system compact and fast.
 @cindex capture
 
 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
+excellent remember package.  Up to version 6.36 Org did actually 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
+of Org-mode for backward compatibility with existing setups.  You can find
-capturing setup described here is preferred and should be used by new users.}
+the documentation for org-remember at
-which lets you store quick notes with little interruption of your work flow.
+@url{http://orgmode.org/org-remember.pdf}.
-The basic process of capturing is very similar to remember, but Org does
+
-enhance it with templates and more.
+The new capturing setup described here is preferred and should be used by new
+users.  To convert your @code{org-remember-templates}, run the command
+@example
+@kbd M-x org-capture-import-remember-templates RET
+@end example
+@noindent and then customize the new variable with @kbd{M-x
+customize-variable org-capture-templates}, check the result, and save the
+customization.  You will then be able to use both remember and capture until
+you have gotten used to the new mechanism.
+
+Capture 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 a capture location::  Where notes will be stored
@@ -5919,11 +5931,9 @@ enhance it with templates and more.
 @node Setting up a capture location, Using capture, Capture, Capture
 @subsection Setting up a capture location
 
-The following customization sets a default target@footnote{Using capture
+The following customization sets a default target file for notes, and defines
-templates, you can define more fine-grained capture locations, see
+a global key@footnote{Please select your own key, @kbd{C-c c} is only a
-@ref{Capture templates}.} file for notes, and defines a global
+suggestion.}  for capturing new stuff.
-key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.}
-for capturing new stuff.
 
 @example
 (setq org-default-notes-file (concat org-directory "/notes.org"))
@@ -5958,10 +5968,10 @@ process by refiling (@pxref{Refiling notes}) the note to a different place.
 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,
+You can also call @code{org-capture} in a special way from the agenda, using
-using the @kbd{k c} key combination.  With this access, any timestamps
+the @kbd{k c} key combination.  With this access, any timestamps inserted by
-inserted by the selected capture template (see below) will default to
+the selected capture template will default to the cursor date in the agenda,
-the cursor date in the agenda, rather than to the current date.
+rather than to the current date.
 
 @node Capture templates,  , Using capture, Capture
 @subsection Capture templates
@@ -6078,6 +6088,7 @@ Fast configuration if the target heading is unique in the file
 For non-unique headings, the full path is safer.
 
 @item (file+regexp  "path/to/file" "regexp to find location")
+Use a regular expression to position the cursor.
 
 @item (file+datetree "path/to/file")
 Will create a heading in a date tree.

doc/orgguide.texi

@@ -169,15 +169,15 @@ Dates and Times
 
 Capture - Refile - Archive
 
-* Remember::			Capture new tasks/ideas with little interruption
+* Capture::			
 * 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
+* Setting up a capture location::  Where notes will be stored
-* Remember templates::		Define the outline of different note types
+* Using capture::		Commands to invoke and terminate capture
-* Storing notes::		Directly get the note to where it belongs
+* Capture templates::		Define the outline of different note types
 
 Agenda Views
 
@@ -1525,89 +1525,90 @@ Cave's Date and Time tutorial}@*
 
 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 defines a capture process to create tasks.  It stores files related to a
-related to a task (@i{attachments}) in a special directory.  Once in the
+task (@i{attachments}) in a special directory.  Once in the system, tasks and
-system, tasks and projects need to be moved around.  Moving completed project
+projects need to be moved around.  Moving completed project trees to an
-trees to an archive file keeps the system compact and fast.
+archive file keeps the system compact and fast.
 
 @menu
-* Remember::			Capture new tasks/ideas with little interruption
+* Capture::			
 * Refiling notes::		Moving a tree from one place to another
 * Archiving::			What to do with finished projects
 @end menu
 
-@node Remember, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive
+@node Capture, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive
-@section Remember
+@section Capture
 
-The Remember package by John Wiegley lets you store quick notes with little
+Org's method for capturing new items is heavily inspired by John Wiegley
-interruption of your work flow.  It is an excellent way to add new notes and
+excellent remember package.  It lets you store quick notes with little
-tasks to Org files.  The @code{remember.el} package is part of Emacs 23, not
+interruption of your work flow.  Org lets you define templates for new
-Emacs 22.  See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for
+entries and associate them with different targets for storing notes.
-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.
 
 @menu
-* Setting up Remember for Org::	 Some code for .emacs to get things going
+* Setting up a capture location::  Where notes will be stored
-* Remember templates::		Define the outline of different note types
+* Using capture::		Commands to invoke and terminate capture
-* Storing notes::		Directly get the note to where it belongs
+* Capture templates::		Define the outline of different note types
 @end menu
 
-@node Setting up Remember for Org, Remember templates, Remember, Remember
+@node Setting up a capture location, Using capture, Capture, Capture
-@unnumberedsubsec Setting up Remember for Org
+@unnumberedsubsec Setting up a capture location
 
-The following customization will tell Remember to use Org files as
+The following customization sets a default target@footnote{Using capture
-target, and to create annotations compatible with Org links.
+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.
 
-@smallexample
+@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 smallexample
+@end example
 
-@noindent
+@node Using capture, Capture templates, Setting up a capture location, Capture
-The last line binds the command @code{org-remember} to a global
+@unnumberedsubsec Using capture
-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 Remember templates, Storing notes, Setting up Remember for Org, Remember
+@table @kbd
-@unnumberedsubsec Remember templates
+@item C-c c
+Start a capture process.  You will be placed into a narrowed indirect buffer
+to edit the item.
+@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.
+@item C-c C-w
+Finalize by moving the entry to a refile location (@pxref{Refiling notes}).
+@item C-c C-k
+Abort the capture process and return to the previous state.
+@end table
 
-In combination with Org, you can use templates to generate
+@node Capture templates,  , Using capture, Capture
-different types of Remember notes.  For example, if you would like
+@unnumberedsubsec Capture templates
-to use one template to create general TODO entries, another one for
+
-journal entries, and a third one for collecting random ideas, you could
+You can use templates to generate different types of capture notes, and to
+store them in different places.  For example, if you would like
+to store new tasks under a heading @samp{Tasks} in file @file{TODO.org}, and
+journal entries in a date tree in @file{journal.org} you could
 use:
 
 @smallexample
-(setq org-remember-templates
+(setq org-capture-templates
- '(("Todo" ?t "* TODO %?\n  %i\n  %a" "~/org/TODO.org" "Tasks")
+ '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
-   ("Journal" ?j "* %U %?\n\n  %i\n  %a" "~/org/JOURNAL.org")
+        "* TODO %?\n  %i\n  %a")
-   ("Idea" ?i "* %^@{Title@}\n  %i\n  %a" "~/org/JOURNAL.org" "New Ideas")))
+   ("j" "Journal" entry (file+datetree "~/org/journal.org")
+        "* %?\nEntered on %U\n  %i\n  %a")))
 @end smallexample
 
-@noindent In these entries, the first string is just a name, and the
+@noindent In these entries, the first string is the key to reach the
-character specifies how to select the template.  It is useful if the
+template, the second is a short description.  Then follows the type of the
-character is also the first letter of the name.  The next string specifies
+entry and a definition of the target location for storing the note.  Finally,
-the template.  Two more (optional) strings give the file in which, and the
+the template itself, a string with %-escapes to fill in information based on
-headline under which, the new note should be stored.
+time and context.
 
-When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember
+When you call @kbd{M-x org-capture}, Org will prompt for a key to select the
-something, Org will prompt for a key to select the template (if you have
+template (if you have more than one template) and then prepare the buffer like
-more than one template) and then prepare the buffer like
 @smallexample
 * TODO
-  [[file:@var{link to where you called remember}]]
+  [[file:@var{link to where you were when initiating capture}]]
 @end smallexample
 
 @noindent
@@ -1623,18 +1624,7 @@ possibilities, consult the manual for more.
 %u, %U      @r{like the above, but inactive timestamps}
 @end smallexample
 
-@node Storing notes,  , Remember templates, Remember
+@node Refiling notes, Archiving, Capture, Capture - Refile - Archive
-@unnumberedsubsec Storing notes
-
-When you are finished preparing a note with Remember, you have to press
-@kbd{C-c C-c} to file the note away. 
-
-The handler will 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.
-
-@node Refiling notes, Archiving, Remember, Capture - Refile - Archive
 @section Refiling notes
 
 When reviewing the captured data, you may want to refile some of the entries
@@ -2432,10 +2422,8 @@ code.
 @section iCalendar export
 
 @table @kbd
-@kindex C-c C-e i
 @item C-c C-e i
 Create iCalendar entries for the current file in a @file{.ics} file.
-@kindex C-c C-e c
 @item C-c C-e c
 Create a single large iCalendar file from all files in
 @code{org-agenda-files} and write it to the file given by