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.
Emacs Stack Exchange is a question and answer site for those using, extending or developing Emacs. It only takes a minute to sign up.
Sign up to join this communityThere 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.
\pipe
by Org.
\nbsp
/\zwsp
that are mentioned in the linked questions.
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
ditaa
(here and here) would be another option for box-and-arrow diagrams, as would be graphviz/dot
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.)
src
blocks).
|
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.\zwsp
for a zero-width space. In general, I prefer visible manifestations of "invisible" things, but YMMV.C-x 8 RET up arrow RET
.