From mboxrd@z Thu Jan 1 00:00:00 1970 From: Phil Rooke Subject: [PATCH] The docstring of org-capture-templates Date: Wed, 07 Jul 2010 16:40:41 +0100 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from [140.186.70.92] (port=46298 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OWX9Z-000426-DT for emacs-orgmode@gnu.org; Wed, 07 Jul 2010 12:07:21 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OWX9U-0003Kc-Vl for emacs-orgmode@gnu.org; Wed, 07 Jul 2010 12:07:17 -0400 Received: from mail-gx0-f169.google.com ([209.85.161.169]:51396) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OWX9U-0003K7-Qn for emacs-orgmode@gnu.org; Wed, 07 Jul 2010 12:07:12 -0400 Received: by gxk4 with SMTP id 4so3387373gxk.0 for ; Wed, 07 Jul 2010 09:07:10 -0700 (PDT) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org A few minor corrections and suggestions for the org-capture-templates docstring diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 2b02b77..8b6bd03 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -97,14 +97,16 @@ keys The keys that will select the template, as a string, characters description A short string describing the template, will be shown during selection. -type The type of entry. Valid are: +type The type of entry. Valid types are: entry an Org-mode node, with a headline. Will be filed as the child of the target entry or as a top-level entry. - item a plain list item, placed in the first plain - list a the target location. - checkitem a checkbox item. This only differs from the - plain lis item by the default template. + item a plain list item, will be placed in the + first plain list at the target + location. + checkitem a checkbox item. This differs from the + plain list item only is so far as it uses a + different default template. table-line a new line in the first table at target location. plain text to be inserted as it is. @@ -119,7 +121,7 @@ target Specification of where the captured item should be placed. Text will be placed at the beginning or end of that file (id \"id of existing org entry\") - Filing as child of this entry, or in the body of the entry + File as child of this entry, or in the body of the entry (file+headline \"path/to/file\" \"node headline\") Fast configuration if the target heading is unique in the file @@ -128,20 +130,20 @@ target Specification of where the captured item should be placed. For non-unique headings, the full path is safer (file+regexp \"path/to/file\" \"regexp to find location\") + File to the entry matching regexp (file+datetree \"path/to/file\") - Will create a heading in a date tree. + Will create a heading in a date tree (file+function \"path/to/file\" function-finding-location) - A function to find the right location in the file. + A function to find the right location in the file (clock) - File to the entry that is currently being clocked. + File to the entry that is currently being clocked (function function-finding-location) Most general way, write your own function to find both - file and location. - + file and location template The template for creating the capture item. If you leave this empty, an appropriate default template will be used. See below @@ -156,7 +158,7 @@ template The template for creating the capture item. If you leave this The rest of the entry is a property list of additional options. Recognized properties are: - :prepend Normally new captured information will be appended at + :prepend Normally newly captured information will be appended at the target location (last child, last table line, last list item...). Setting this property will change that. @@ -183,12 +185,12 @@ properties are: which means that the new line should become the third line before the second horizontal separaor line. -The template defined the text to be inserted. Often then this is an org-mode +The template defines the text to be inserted. Often this is an org-mode entry (so the first line should start with a star) that will be filed as a child of the target headline. It can also be freely formatted text. Furthermore, the following %-escapes will be replaced with content: - %^{prompt} Prompt the user for a string and replace this sequence with it. + %^{prompt} prompt the user for a string and replace this sequence with it. A default value and a completion table ca be specified like this: %^{prompt|default|completion2|completion3|...} %t time stamp, date only @@ -202,13 +204,13 @@ Furthermore, the following %-escapes will be replaced with content: indented, the entire inserted text will be indented as well. %c current kill ring head %x content of the X clipboard - %^C Interactive selection of which kill or clip to use - %^L Like %^C, but insert as link + %^C interactive selection of which kill or clip to use + %^L like %^C, but insert as link %k title of currently clocked task %K link to currently clocked task %^g prompt for tags, with completion on tags in target file - %^G prompt for tags, with completion all tags in all agenda files - %^{prop}p Prompt the user for a value for property `prop' + %^G prompt for tags, with completion on all tags in all agenda files + %^{prop}p prompt the user for a value for property `prop' %:keyword specific information for certain link types, see below %[pathname] insert the contents of the file given by `pathname' %(sexp) evaluate elisp `(sexp)' and replace with the result