From mboxrd@z Thu Jan 1 00:00:00 1970 From: Peter Tomhas Subject: Suggestion for tiniest of manual changes Date: Sat, 19 Aug 2017 00:06:23 -0500 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:36677) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1divxs-00055w-54 for emacs-orgmode@gnu.org; Sat, 19 Aug 2017 01:06:29 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1divxq-00017r-S8 for emacs-orgmode@gnu.org; Sat, 19 Aug 2017 01:06:28 -0400 Received: from mail-wm0-x234.google.com ([2a00:1450:400c:c09::234]:35076) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1divxq-00017S-Gb for emacs-orgmode@gnu.org; Sat, 19 Aug 2017 01:06:26 -0400 Received: by mail-wm0-x234.google.com with SMTP id m85so12850823wma.0 for ; Fri, 18 Aug 2017 22:06:25 -0700 (PDT) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: emacs-orgmode@gnu.org 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