Org syntax inside verbatim/literal blocks

Org syntax inside verbatim/literal blocks

[Štěpán Němec]

I notice that even inside example blocks, some strings are still parsed
as Org syntax, e.g. the asterisk becomes a bogus heading:

#+begin_example
*  _____
 \|   @ \
  |_____/
   /\ /\
#+end_example

When I enclose the text in a region and use
`org-insert-structure-template' to surround it with begin and end lines,
a comma is prepended to the asterisk automatically (doc string of
`org-escape-code-in-region' uses the word "append", which is usually
used in the sense of "add to the end", though).

But all I could find in the manual regarding "verbatim", "escaping" etc.
are sections 12.2 and 16.3, neither of which mentions comma.

I'd prefer if there were some kind of a _real_ verbatim block without
need for escaping anything, but failing that, could this matter be
clarified in the documentation?

  Thanks,

  Štěpán

Re: Org syntax inside verbatim/literal blocks

[Nicolas Goaziou]

Hello,

Štěpán Němec <stepnem@gmail.com> writes:

> I notice that even inside example blocks, some strings are still parsed
> as Org syntax, e.g. the asterisk becomes a bogus heading:
>
> #+begin_example
> *  _____
>  \|   @ \
>   |_____/
>    /\ /\
> #+end_example

This is expected. Headlines bind stronger than example blocks.

> When I enclose the text in a region and use
> `org-insert-structure-template' to surround it with begin and end lines,
> a comma is prepended to the asterisk automatically (doc string of
> `org-escape-code-in-region' uses the word "append", which is usually
> used in the sense of "add to the end", though).
>
> But all I could find in the manual regarding "verbatim", "escaping" etc.
> are sections 12.2 and 16.3, neither of which mentions comma.

See "Literal Examples" section, fourth footnote.

Regards,

-- 
Nicolas Goaziou

Re: Org syntax inside verbatim/literal blocks

[Štěpán Němec]

On Fri, 09 Aug 2019 22:39:44 +0200
Nicolas Goaziou wrote:

>> But all I could find in the manual regarding "verbatim", "escaping" etc.
>> are sections 12.2 and 16.3, neither of which mentions comma.
>
> See "Literal Examples" section, fourth footnote.

Thanks.

I think it would be much more helpful if, instead of a footnote to one
related special case (`org-edit-special'), this information was indexed
("escape character" and "comma" come to mind) and also mentioned in or
linked to from section 16.3 (Escape Character).

What do you think?

-- 
Štěpán

Re: Org syntax inside verbatim/literal blocks

[Nicolas Goaziou]

Hello,

Štěpán Němec <stepnem@gmail.com> writes:

> I think it would be much more helpful if, instead of a footnote to one
> related special case (`org-edit-special'), this information was indexed
> ("escape character" and "comma" come to mind) and also mentioned in or
> linked to from section 16.3 (Escape Character).

Certainly. Would you want to provide a patch to the manual?

Regards,

-- 
Nicolas Goaziou

Re: Org syntax inside verbatim/literal blocks

[Štěpán Němec]

[-- Attachment #1: Type: text/plain, Size: 363 bytes --]


> Certainly. Would you want to provide a patch to the manual?

Yes, thank you, patch attached (on top of current maint branch).

I don't know how robust the footnote indexing is, e.g. putting #+cindex
above instead of below [fn] lead to errors during 'make info'; but the
version attached does work (for the texinfo export at least).

-- 
Štěpán


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-Index-and-link-to-information-on-literal-.patch --]
[-- Type: text/x-patch, Size: 1889 bytes --]

From bcd5049620e938c8687f239c10248db3805de721 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= <stepnem@gmail.com>
Date: Thu, 15 Aug 2019 11:57:17 +0200
Subject: [PATCH] org-manual: Index and link to information on literal block
 comma escape

* doc/org-manual.org (Escape Character): Mention comma and link to the "Literal
Examples" section.
(Footnotes): Index explanation of comma escape inside literal blocks.
---
 doc/org-manual.org | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 1418abb50..06d5eb262 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18292,8 +18292,9 @@ init file[fn:146].
 You may sometimes want to write text that looks like Org syntax, but
 should really read as plain text.  Org may use a specific escape
 character in some situations, e.g., a backslash in macros (see [[*Macro
-Replacement]]).  In the general case, however, we suggest to use the
-zero width space.  You can get it with one of the following:
+Replacement]]) or a comma in source code and example blocks (see
+[[*Literal Examples]]).  In the general case, however, we suggest to use
+the zero width space.  You can get it with one of the following:
 
 : C-x 8 <RET> zero width space <RET>
 : C-x 8 <RET> 200B <RET>
@@ -21354,7 +21355,10 @@ information on evaluating code blocks.
 while using line numbers for the links, which might be useful to
 explain those in an Org mode example code.
 
-[fn:117] Upon exit, lines starting with =*=, =,*=, =#+= and =,#+= get
+[fn:117]
+#+cindex: escape character
+#+cindex: comma
+Upon exit, lines starting with =*=, =,*=, =#+= and =,#+= get
 a comma prepended, to keep them from being interpreted by Org as
 outline nodes or special syntax.  These commas are stripped when
 editing with {{{kbd(C-c ')}}}, and also before export.
-- 
2.22.0

Re: Org syntax inside verbatim/literal blocks

[Nicolas Goaziou]

Hello,

Štěpán Němec <stepnem@gmail.com> writes:

> Yes, thank you, patch attached (on top of current maint branch).
>
> I don't know how robust the footnote indexing is, e.g. putting #+cindex
> above instead of below [fn] lead to errors during 'make info'; but the
> version attached does work (for the texinfo export at least).

Thank you.

I thought the idea was to move the information outside of the footnote.
I applied a different patch, in master. Let me know if it is enough.

Side note: you cannot use CINDEX keyword in a footnote definition
because Texinfo inlines them, which is not compatible with @cindex
commands.

Regards,

-- 
Nicolas Goaziou

Re: Org syntax inside verbatim/literal blocks

[Štěpán Němec]

On Sat, 17 Aug 2019 15:24:56 +0200
Nicolas Goaziou wrote:

> I thought the idea was to move the information outside of the footnote.
> I applied a different patch, in master. Let me know if it is enough.

I agree that is even better; I guess I was aiming at minimal changes,
plus the footnote indexing thing seemed an interesting challenge...

> Side note: you cannot use CINDEX keyword in a footnote definition
> because Texinfo inlines them, which is not compatible with @cindex
> commands.

Hm, but the version in my patch does seem to work correctly, i.e. it is
exported as (snipped)

 You need to exit by pressing @kbd{C-c '} again@footnote{@cindex escape character
 @cindex comma
 Upon exit, lines starting with @samp{*}, @samp{,*}, @samp{#+} and @samp{,#+} get

... which seems to produce a valid info file (looks the same as before
and the index entries work). Is it just a corner case, not a feature?

(I'm merely being curious at this point, I agree your version is better.)

Thank you.

-- 
Štěpán

Re: Org syntax inside verbatim/literal blocks

[Nicolas Goaziou]

Štěpán Němec <stepnem@gmail.com> writes:

> Hm, but the version in my patch does seem to work correctly, i.e. it is
> exported as (snipped)
>
>  You need to exit by pressing @kbd{C-c '} again@footnote{@cindex escape character
>  @cindex comma
>  Upon exit, lines starting with @samp{*}, @samp{,*}, @samp{#+} and @samp{,#+} get
>
> ... which seems to produce a valid info file (looks the same as before
> and the index entries work). Is it just a corner case, not a feature?

You must be right then. I assumed @cindex could not fit into @footnote
but I stand corrected.

Regards,