From 9bf78c7db463a583efb27f5c0e80b70bd1605b88 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 17:32:29 +0200 Subject: [PATCH 1/3] Point to a PDF copy of the old org-remember documentation --- doc/org.texi | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/org.texi b/doc/org.texi index b4696a55c..5a417747a 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -5905,7 +5905,9 @@ 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.} +capturing setup described here is preferred and should be used by new users. +You can find the documentation for org-remember at +@url{http://orgmode.org/org-remember.pdf}.} 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. From 808115a4cf65a655f9091695116e6c441e9758b8 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 17:54:48 +0200 Subject: [PATCH 2/3] Document org-capture in the guide --- doc/orgguide.texi | 142 +++++++++++++++++++++------------------------- 1 file changed, 65 insertions(+), 77 deletions(-) diff --git a/doc/orgguide.texi b/doc/orgguide.texi index b2f132bc7..fd999a8a2 100644 --- a/doc/orgguide.texi +++ b/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 -* 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 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 -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. +Org defines a capture process to create tasks. It stores 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 +* 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 -@section Remember +@node Capture, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive +@section 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. It lets you store quick notes with little +interruption of your work flow. Org lets you define templates for new +entries and associate them with different targets for storing notes. @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 -@unnumberedsubsec Setting up Remember for Org +@node Setting up a capture location, Using capture, Capture, Capture +@unnumberedsubsec 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. -@smallexample -(org-remember-insinuate) -(setq org-directory "~/path/to/my/orgfiles/") +@example (setq org-default-notes-file (concat org-directory "/notes.org")) -(define-key global-map "\C-cr" 'org-remember) -@end smallexample +(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 +@unnumberedsubsec Using capture -@node Remember templates, Storing notes, Setting up Remember for Org, Remember -@unnumberedsubsec Remember templates +@table @kbd +@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 -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 +@node Capture templates, , Using capture, Capture +@unnumberedsubsec Capture templates + +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 - '(("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 smallexample -@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. +@noindent In these entries, the first string is the key to reach the +template, the second is a short description. Then follows the type of the +entry and a definition of the target location for storing the note. Finally, +the template itself, a string with %-escapes to fill in information based on +time and 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 +When you call @kbd{M-x org-capture}, Org will prompt for a key to select the +template (if you have 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 -@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 +@node Refiling notes, Archiving, Capture, 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 From 312081b3760fcb076835d4db6167fa4f1ece93f4 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Fri, 25 Jun 2010 18:28:04 +0200 Subject: [PATCH 3/3] More tweaks at the capture documentation --- doc/org.texi | 43 ++++++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 5a417747a..0bf2f2b73 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -5902,15 +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 -capturing setup described here is preferred and should be used by new users. -You can find the documentation for org-remember at -@url{http://orgmode.org/org-remember.pdf}.} -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. +of Org-mode for backward compatibility with existing setups. You can find +the documentation for org-remember at +@url{http://orgmode.org/org-remember.pdf}. + +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 @@ -5921,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 -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. +The following customization sets a default target 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 (setq org-default-notes-file (concat org-directory "/notes.org")) @@ -5960,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, -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. +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 will default to the cursor date in the agenda, +rather than to the current date. @node Capture templates, , Using capture, Capture @subsection Capture templates @@ -6080,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.