9.1.3.2 Template expansion: documentation issue

9.1.3.2 Template expansion: documentation issue

[Karl Eichwalder]

In 9.1.3.2 Template expansion, you say:

      %\n         Insert the text entered at the nth %^{PROMPT}, where 
‘n’ is

but in my 25.1.1, you must use "%\\n".

Maybe, it is also worth noting that

      %^{PROP}p   Prompt the user for a value for property PROP.

will get inserted at the end of a list of properties, but white-space 
will stay
in place:

      :PROP_A:   a
      %^{PROP}p
      :PROP_Z:   z

==>

      :PROP_A:   a

      :PROP_Z:   z
      :PROP:     foo

To avoid white-space issues and an unexpected sorting order, you must 
write (and you lose the preset values):

      :PROPERTIES:%^{PROP_A}p%^{PROP}p%^{PROP_Z}p


-- 
Karl Eichwalder

Re: 9.1.3.2 Template expansion: documentation issue

[Nicolas Goaziou]

Hello,

Karl Eichwalder <ke@gnu.franken.de> writes:

> In 9.1.3.2 Template expansion, you say:
>
>      %\n         Insert the text entered at the nth %^{PROMPT}, where
> ‘n’ is
>
> but in my 25.1.1, you must use "%\\n".

No, you mustn't. The placeholder really is "%\n", but Elisp require
backslash characters to be escaped in strings. So, when you write your
template as a string, you use "%\\n" because it is the only way to have
"%\n".

> Maybe, it is also worth noting that
>
>      %^{PROP}p   Prompt the user for a value for property PROP.
>
> will get inserted at the end of a list of properties, but white-space
> will stay
> in place:
>
>      :PROP_A:   a
>      %^{PROP}p
>      :PROP_Z:   z
>
> ==>
>
>      :PROP_A:   a
>
>      :PROP_Z:   z
>      :PROP:     foo
>
> To avoid white-space issues and an unexpected sorting order, you must
> write (and you lose the preset values):
>
>      :PROPERTIES:%^{PROP_A}p%^{PROP}p%^{PROP_Z}p

You are mis-using %^{prop}p. Granted, `org-capture-templates' docstring
is not particularly clear on this point.

Unlike other placeholders %^{prop}p can be used anywhere in the
template, since it delegates its job to `org-entry-put'. As
a consequence, you shouldn't put it where you expect the property to be
inserted.

Besides, there is no order in properties drawers, so there is no
guarantee that `org-entry-put' will preserve yours.

Would you want to suggest a better wording to explain this in
`org-capture-templates' docstring (and in the related part of the
manual)?

Regards,

-- 
Nicolas Goaziou