* Org syntax inside verbatim/literal blocks @ 2019-08-09 19:02 Štěpán Němec 2019-08-09 20:39 ` Nicolas Goaziou 0 siblings, 1 reply; 8+ messages in thread From: Štěpán Němec @ 2019-08-09 19:02 UTC (permalink / raw) To: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Org syntax inside verbatim/literal blocks 2019-08-09 19:02 Org syntax inside verbatim/literal blocks Štěpán Němec @ 2019-08-09 20:39 ` Nicolas Goaziou 2019-08-09 21:02 ` Štěpán Němec 0 siblings, 1 reply; 8+ messages in thread From: Nicolas Goaziou @ 2019-08-09 20:39 UTC (permalink / raw) To: Štěpán Němec; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Org syntax inside verbatim/literal blocks 2019-08-09 20:39 ` Nicolas Goaziou @ 2019-08-09 21:02 ` Štěpán Němec 2019-08-15 8:13 ` Nicolas Goaziou 0 siblings, 1 reply; 8+ messages in thread From: Štěpán Němec @ 2019-08-09 21:02 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Org syntax inside verbatim/literal blocks 2019-08-09 21:02 ` Štěpán Němec @ 2019-08-15 8:13 ` Nicolas Goaziou 2019-08-15 10:16 ` Štěpán Němec 0 siblings, 1 reply; 8+ messages in thread From: Nicolas Goaziou @ 2019-08-15 8:13 UTC (permalink / raw) To: Štěpán Němec; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Org syntax inside verbatim/literal blocks 2019-08-15 8:13 ` Nicolas Goaziou @ 2019-08-15 10:16 ` Štěpán Němec 2019-08-17 13:24 ` Nicolas Goaziou 0 siblings, 1 reply; 8+ messages in thread From: Štěpán Němec @ 2019-08-15 10:16 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode [-- 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 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: Org syntax inside verbatim/literal blocks 2019-08-15 10:16 ` Štěpán Němec @ 2019-08-17 13:24 ` Nicolas Goaziou 2019-08-17 14:00 ` Štěpán Němec 0 siblings, 1 reply; 8+ messages in thread From: Nicolas Goaziou @ 2019-08-17 13:24 UTC (permalink / raw) To: Štěpán Němec; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Org syntax inside verbatim/literal blocks 2019-08-17 13:24 ` Nicolas Goaziou @ 2019-08-17 14:00 ` Štěpán Němec 2019-08-17 14:36 ` Nicolas Goaziou 0 siblings, 1 reply; 8+ messages in thread From: Štěpán Němec @ 2019-08-17 14:00 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Org syntax inside verbatim/literal blocks 2019-08-17 14:00 ` Štěpán Němec @ 2019-08-17 14:36 ` Nicolas Goaziou 0 siblings, 0 replies; 8+ messages in thread From: Nicolas Goaziou @ 2019-08-17 14:36 UTC (permalink / raw) To: Štěpán Němec; +Cc: emacs-orgmode Š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, ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2019-08-17 14:37 UTC | newest] Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2019-08-09 19:02 Org syntax inside verbatim/literal blocks Štěpán Němec 2019-08-09 20:39 ` Nicolas Goaziou 2019-08-09 21:02 ` Štěpán Němec 2019-08-15 8:13 ` Nicolas Goaziou 2019-08-15 10:16 ` Štěpán Němec 2019-08-17 13:24 ` Nicolas Goaziou 2019-08-17 14:00 ` Štěpán Němec 2019-08-17 14:36 ` Nicolas Goaziou
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).