emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

From: Peter Tomhas <peter.tomhas@gmail.com>
To: emacs-orgmode@gnu.org
Subject: Suggestion for tiniest of manual changes
Date: Sat, 19 Aug 2017 00:06:23 -0500	[thread overview]
Message-ID: <CAJrHO00=WFEttiQDwT=Gteh24L__jokEL23Ha=01+XLjXFTt_w@mail.gmail.com> (raw)

Not being a lisp programmer, I stubbed my toe on section "9.1.3.2
Template expansion" of the manual. I was trying to use %\1, %\2 etc,
following the instructions in the second last item of the big table:
where it says:

%\1 ... %\N   Insert the text entered at the Nth %^{prompt}, where N is
                    a number, starting from 1.

I inserted %\1 into my template and it failed to work. After a wee
while of testing what might be wrong, I guessed that I needed to
backslash-escape the backslash, and it worked. Because that escaping
is both: a. made necessary (as I understand it) by the %\N  being in a
string; and b. only /ever/ invoked within a string, at first I
considered this to be a documentation bug, and I reckoned the entry
should start, "%\\1 ... %\\N". However, it was explained to me on
Reddit[1], that anyone who knows lisp would know to add the escape,
and that having %\\1 in the documentation could cause them to try to
use %\\\\1.

Sounds reasonable, but I still think at least a footnote could help.
As far as I can make out, the current texinfo is as follows:

%\1 @dots{} %\N @r{Insert the text entered at the Nth
%^@{@var{prompt}@}, where @code{N} is}
            @r{a number, starting from 1.}

Perhaps that could become something like (apologies for poorly
formatted texinfo):

%\1 @dots{} %\N @r{Insert the text entered at the Nth
%^@{@var{prompt}@}, where @code{N} is}
            @r{a number, starting from 1.@footnote{As is standard in elisp,
to insert a backslash character within a string, as is required here, it is
necessary to escape it with another backslash. So to insert %\1, %\2 and so
on, one should actually insert %\\1, %\\2, etc.}}

pt

[1] https://www.reddit.com/r/orgmode/comments/6uksnz/orgcapture_in_templates_n_needs_to_be_n/dltsth0/n

next             reply	other threads:[~2017-08-19  5:06 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-08-19  5:06 Peter Tomhas [this message]
2017-08-19  9:12 ` Suggestion for tiniest of manual changes Nicolas Goaziou

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAJrHO00=WFEttiQDwT=Gteh24L__jokEL23Ha=01+XLjXFTt_w@mail.gmail.com' \
    --to=peter.tomhas@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).