From 2f001510203e4124429626b4343282e22ba7d20f Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sun, 9 Dec 2018 12:32:16 +0100 Subject: [PATCH 1/3] org-manual: Small markup fixes * doc/org-manual.org (Template elements): (Template expansion): (Attachments): Replace ~ with =. --- doc/org-manual.org | 118 ++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 59 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 3d2211474..488f3eecc 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -7260,15 +7260,15 @@ Now lets look at the elements of a template definition. Each entry in top level. Check out the ~:time-prompt~ and ~:tree-type~ properties below for additional options. - - ~(file+function "filename" function-finding-location)~ :: + - =(file+function "filename" function-finding-location)= :: A function to find the right location in the file. - - ~(clock)~ :: + - =(clock)= :: File to the entry that is currently being clocked. - - ~(function function-finding-location)~ :: + - =(function function-finding-location)= :: Most general way: write your own function which both visits the file and moves point to the right location. @@ -7361,120 +7361,120 @@ In the template itself, special "%-escapes"[fn:83] allow dynamic insertion of content. The templates are expanded in the order given here: -- ~%[FILE]~ :: +- =%[FILE]= :: Insert the contents of the file given by {{{var(FILE)}}}. -- ~%(SEXP)~ :: +- =%(EXP)= :: - Evaluate Elisp SEXP and replace with the result. The - {{{var(SEXP)}}} must return a string. + Evaluate Elisp expression {{{var(EXP)}}} and replace it with the + result. The {{{var(EXP)}}} form must return a string. -- ~%~ :: +- =%= :: The result of format-time-string on the {{{var(FORMAT)}}} specification. -- ~%t~ :: +- =%t= :: Timestamp, date only. -- ~%T~ :: +- =%T= :: Timestamp, with date and time. -- ~%u~, ~%U~ :: +- =%u=, =%U= :: - Like ~%t~, ~%T~ above, but inactive timestamps. + Like =%t=, =%T= above, but inactive timestamps. -- ~%i~ :: +- =%i= :: Initial content, the region when capture is called while the region is active. The entire text will be indented like ~%i~ itself. -- ~%a~ :: +- =%a= :: Annotation, normally the link created with ~org-store-link~. -- ~%A~ :: +- =%A= :: - Like ~%a~, but prompt for the description part. + Like =%a=, but prompt for the description part. -- ~%l~ :: +- =%l= :: - Like ~%a~, but only insert the literal link. + Like =%a=, but only insert the literal link. -- ~%c~ :: +- =%c= :: Current kill ring head. -- ~%x~ :: +- =%x= :: Content of the X clipboard. -- ~%k~ :: +- =%k= :: Title of the currently clocked task. -- ~%K~ :: +- =%K= :: Link to the currently clocked task. -- ~%n~ :: +- =%n= :: User name (taken from ~user-full-name~). -- ~%f~ :: +- =%f= :: File visited by current buffer when org-capture was called. -- ~%F~ :: +- =%F= :: Full path of the file or directory visited by current buffer. -- ~%:keyword~ :: +- =%:keyword= :: Specific information for certain link types, see below. -- ~%^g~ :: +- =%^g= :: Prompt for tags, with completion on tags in target file. -- ~%^G~ :: +- =%^G= :: Prompt for tags, with completion all tags in all agenda files. -- ~%^t~ :: +- =%^t= :: - Like ~%t~, but prompt for date. Similarly ~%^T~, ~%^u~, ~%^U~. You may - define a prompt like ~%^{Birthday}t~. + Like =%t=, but prompt for date. Similarly =%^T=, =%^u=, =%^U=. You may + define a prompt like =%^{Birthday}t=. -- ~%^C~ :: +- =%^C= :: Interactive selection of which kill or clip to use. -- ~%^L~ :: +- =%^L= :: - Like ~%^C~, but insert as link. + Like =%^C=, but insert as link. -- ~%^{PROP}p~ :: +- =%^{PROP}p= :: - Prompt the user for a value for property PROP. + Prompt the user for a value for property {{{var(PROP)}}}. -- ~%^{PROMPT}~ :: +- =%^{PROMPT}= :: Prompt the user for a string and replace this sequence with it. You may specify a default value and a completion table with - ~%^{prompt|default|completion2|completion3...}~. The arrow keys + =%^{prompt|default|completion2|completion3...}=. The arrow keys access a prompt-specific history. -- ~%\n~ :: +- =%\N= :: - Insert the text entered at the Nth ~%^{PROMPT}~, where N is - a number, starting from 1. + Insert the text entered at the {{{var(N)}}}th =%^{PROMPT}=, where + {{{var(N)}}} is a number, starting from 1. -- ~%?~ :: +- =%?= :: After completing the template, position point here. @@ -7484,20 +7484,20 @@ For specific link types, the following keywords are defined[fn:84]: #+vindex: org-from-is-user-regexp | Link type | Available keywords | |--------------+----------------------------------------------------------| -| bbdb | ~%:name~, ~%:company~ | -| irc | ~%:server~, ~%:port~, ~%:nick~ | -| mh, rmail | ~%:type~, ~%:subject~, ~%:message-id~ | -| | ~%:from~, ~%:fromname~, ~%:fromaddress~ | -| | ~%:to~, ~%:toname~, ~%:toaddress~ | -| | ~%:date~ (message date header field) | -| | ~%:date-timestamp~ (date as active timestamp) | -| | ~%:date-timestamp-inactive~ (date as inactive timestamp) | -| | ~%:fromto~ (either "to NAME" or "from NAME")[fn:85] | -| gnus | ~%:group~, for messages also all email fields | -| w3, w3m | ~%:url~ | -| info | ~%:file~, ~%:node~ | -| calendar | ~%:date~ | -| org-protocol | ~%:link~, ~%:description~, ~%:annotation~ | +| bbdb | =%:name=, =%:company= | +| irc | =%:server=, =%:port=, =%:nick= | +| mh, rmail | =%:type=, =%:subject=, =%:message-id= | +| | =%:from=, =%:fromname=, =%:fromaddress= | +| | =%:to=, =%:toname=, =%:toaddress= | +| | =%:date= (message date header field) | +| | =%:date-timestamp= (date as active timestamp) | +| | =%:date-timestamp-inactive= (date as inactive timestamp) | +| | =%:fromto= (either "to NAME" or "from NAME")[fn:85] | +| gnus | =%:group=, for messages also all email fields | +| w3, w3m | =%:url= | +| info | =%:file=, =%:node= | +| calendar | =%:date= | +| org-protocol | =%:link=, =%:description=, =%:annotation= | **** Templates in contexts :PROPERTIES: @@ -7541,9 +7541,9 @@ cloud, like emails or source code files belonging to a project. Another method is /attachments/, which are files located in a directory belonging to an outline node. Org uses directories named by the unique ID of each entry. These directories are located in the -~data~ directory which lives in the same directory where your Org file -lives[fn:86]. If you initialize this directory with =git init=, Org -automatically commits changes when it sees them. The attachment +=data/= directory which lives in the same directory where your Org +file lives[fn:86]. If you initialize this directory with =git init=, +Org automatically commits changes when it sees them. The attachment system has been contributed to Org by John Wiegley. In cases where it seems better to do so, you can attach a directory of From 601f373e3fd1874bb2603ffe608de550e2177877 Mon Sep 17 00:00:00 2001 From: Allen Li Date: Fri, 7 Dec 2018 19:35:56 -0800 Subject: [PATCH 2/3] Document %i prefix in capture templates * doc/org-manual.org (Template expansion): Fix documentation. * lisp/org-capture.el (org-capture-templates): Fix docstring. --- doc/org-manual.org | 5 +++-- lisp/org-capture.el | 6 ++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 488f3eecc..54bbf2a86 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -7390,8 +7390,9 @@ here: - =%i= :: Initial content, the region when capture is called while the - region is active. The entire text will be indented like ~%i~ - itself. + region is active. If there is text before =%i= on the same line, + such as indentation, and =%i= is not inside a =%(exp)= form, that + prefix is added before every line in the inserted text. - =%a= :: diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 0446594dc..2946b6fc5 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -287,8 +287,10 @@ be replaced with content and expanded: with `org-capture-use-agenda-date' set. %T Time stamp as above, with date and time. %u, %U Like the above, but inactive time stamps. - %i Initial content, copied from the active region. If %i is - indented, the entire inserted text will be indented as well. + %i Initial content, copied from the active region. If + there is text before %i on the same line, such as + indentation, and %i is not inside a %(sexp), that prefix + will be added before every line in the inserted text. %a Annotation, normally the link created with `org-store-link'. %A Like %a, but prompt for the description part. %l Like %a, but only insert the literal link. From adec504d5ba3f2089cb689ce5a59692a8ebf6735 Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sun, 9 Dec 2018 23:36:04 +0100 Subject: [PATCH 3/3] org-manual: Improve %(sexp) capture template placeholder documentation * doc/org-manual.org (Template expansion): Improve documentation for %(sexp) documentation. --- doc/org-manual.org | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 54bbf2a86..051ffaa4d 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -7368,7 +7368,11 @@ here: - =%(EXP)= :: Evaluate Elisp expression {{{var(EXP)}}} and replace it with the - result. The {{{var(EXP)}}} form must return a string. + result. The {{{var(EXP)}}} form must return a string. Only + placeholders pre-existing within the template, or introduced with + =%[file]=, are expanded this way. Since this happens after + expanding non-interactive "%-escapes", those can be used to fill + the expression. - =%= ::