I want to draw a vertical arrow using ASCII characters, and that results in pipes being the first character on several lines.
But org-mode thinks I'm trying to create a table, and it formats it in an unintended way.
3 Answers
There are a couple of options as discussed in the comments.
The basic idea is to prevent Org mode from interpreting | as the beginning of the table. That happens only when the | character is at the beginning of the line, so the trick is to escape it by preceding it with another character, usually some sort of a space character - see the manual section on Escape characters. Two that are often used are a non-breaking space (hereafter abbreviated nbsp) and a zero-width space (abbreviated zwsp). The advantage of a zwsp is that it is almost invisible; its disadvantage is that it's almost invisible :-) You can only see it if you put your cursor on it (in my case, it turns from the usual rectangle to a thin vertical line). An nbsp is more visible, perhaps intrusively so: it is shown as an underscore _.
You can enter a zwsp as Unicode with C-x 8 RET zero width space RET. You can enter an nbsp as Unicode with C-x 8 RET non-breaking space RET.
In addition, Org mode allows the use of org-entities: these are very visible ways to insert special characters and have them treated specially for export (but you can show them as UTF-8 characters by calling the function org-toggle-pretty-entities). There is a predefined set of them: see the variable org-entities for the value - e.g. \nbsp is defined there as a non-breaking space, so you can say
\nbsp| THis | is | not | a | table | to escape the |. You can also add your own entities by customizing the org-entities-user variable, e.g. there is no entity for a zero-width space but you can define your own. In the question I linked to in my comment, John Kitchin shows how to do that:
(add-to-list 'org-entities-user '("zwsp" "\\hspace{0pt}" ; latex nil ; not in math-mode "​" ; html "" ; ascii nil ; latin1 not sure what to put here "" ; utf-8 )) so you could use \zwsp in your file. These serve as explicit visible reminders of what you did: invisibility is not their forte :-) :
\zwsp| This | is | not | a | table | But as mentioned, you can always turn them into "pretty" entities: the buffer will look as if you are using "real" UTF-8 characters, but the file will actually contain the explicit long form of the entity.
One additional note: this escaping mechanism comes in useful anywhere where you want to avoid Org mode interpreting something based on its syntax. In this question, it's about avoiding the interpretation of | as the beginning of a table line; in the linked question, it is about forcing Org mode to interpret a ^ as a superscript. In this question, it's about avoiding the interpretation of 3. as a numbered list entry if it falls at the beginning of a line. And there is this answer by Kaushal Modi about not exporting *foo* as bold, which also links to a discussion on the Org mode mailing list about inserting explicit Unicode characters vs using entities. Kaushal also includes another answer that deals with org-entities in a more convenient way.
- 1Ackchually, if one already gets involved with customizing entities, perhaps the pipe symbol itself could be added as an entity—so it's displayed as a bar but is seen as something like
\pipeby Org.aaa– aaa2022-02-12 06:51:13 +00:00Commented Feb 12, 2022 at 6:51 - Yes, although that wouldn't work for all the other applications of
\nbsp/\zwspthat are mentioned in the linked questions.NickD– NickD2022-02-12 13:26:42 +00:00Commented Feb 12, 2022 at 13:26
If you are drawing ASCII art, you could use an artist-mode code block:
#+begin_src artist +-----------------------+ | | | Some Box | | | +-----+-----------------+ | | | An arrow | | V +------+------+ | | | Another | | Box | | | +-------------+ #+end_src More documentation on "literal examples" markup, of which artist-mode is an instance: https://orgmode.org/manual/Literal-Examples.html
Keyboard shortcuts for easily inserting them: https://orgmode.org/manual/Structure-Templates.html
- 1
ditaa(here and here) would be another option for box-and-arrow diagrams, as would be graphviz/dotNickD– NickD2022-02-11 16:41:22 +00:00Commented Feb 11, 2022 at 16:41
As an alternative to using specific modes tailored to ASCII art, you could just denote a block of text as ‘preformatted’ by putting it between lines saying #+begin_example and #+end_example. Then, Org syntax won't work inside the block, so all kinds of ASCII stuff can be used boldly. Additionally, these blocks can be formatted in monospace if the rest of the file is in a proportional font.
(I'm not sure if there's a better-fitting syntax for ‘plain text’ preformatted blocks, as ‘example’ carries a semantic connotation. Personally I'm hijacking #+begin_src for that, but this is undocumented.)
- Did some digging in the docs: "available structure types are defined in org-structure-template-alist, see the docstring for adding or changing values" (source: orgmode.org/manual/Structure-Templates.html). So I guess it should be possible to define our own semantic block.Chrisuu– Chrisuu2022-02-13 17:08:50 +00:00Commented Feb 13, 2022 at 17:08
- @Calculemus Uuuh, I think that's just snippets called with hotkeys. There's probably no way to add block types that easily, seeing as existing ones require special handling from Org (mostly when exporting to other formats, or to highlight and run code in
srcblocks).aaa– aaa2022-02-13 21:01:49 +00:00Commented Feb 13, 2022 at 21:01
|character. You can do that in a number of ways, but the one I use is the only one I remember:\nbsp| This is not a | table . |. See also Escape character in the manual for a less intrusive option.\zwspfor a zero-width space. In general, I prefer visible manifestations of "invisible" things, but YMMV.C-x 8 RET up arrow RET.