org-special-block-extras: The block and link types

Sometimes there is a remark or a code snippet that is useful to
have, but not relevant to the discussion at hand and so we want to
/fold away such [[doc:org-block/details][details]]/.

#+begin_details Example use cases
+ ‘Conversation-style’ articles, where the author asks the reader questions
  whose answers are “folded away” so the reader can think about the exercise
  before seeing the answer.

+ Hiding boring but important code snippets, such as a list of import
  declarations or a tedious implementation.
#+end_details

Full syntax ~#+begin_details "title" :background-color "cyan" :title-color "green"~.

Src blocks fold too: the header argument :folded t exports a src block, exactly as Org otherwise would, inside a details block titled by its language; :folded "TITLE" picks the title.

#+begin_src emacs-lisp :folded "How is it done?"
(org-defblock details …)
#+end_src

A page with many folded blocks may offer a button to unfold them all at once: [[toggle-details:][Show me everything]] is that button; pressed again, it folds them all. Without a description, it reads “Unfold all details”.

Anyone who writes about Emacs will likely want to mention keystrokes in an aesthetically pleasing way, such as C-u 80 - to insert 80 dashes, or C-c C-e h o to export an Org-mode file to HTML, or the useful M-s h ..

• kbd:𝒳 will show a tooltip defining 𝒳, as an Emacs Lisp function, if possible. For example, kbd:C-h_t is C-h t; and likewise <kbd:M-s h .> is M-s h. (we need to use <...> since punctuation is not picked up as part of link labels). In contrast, kbd:nope renders as nope without a tooltip (nor a red border).

  You can also supply explicit tooltip description: [[kbd:key sequence][description]] will show as key sequence; i.e., the key sequence in nice key font along with a tooltip explaining it.

• In Emacs itself, each of these displays as 〔C-x C-s〕: the kbd: markup becomes the brackets and each _ a space. Only the markup is displayed differently, so the keys stay editable as ever. Moreover, clicking one runs its keys —after asking, as elisp: links do— so readers may try them on the spot.

Sometimes you want to remark on details without drawing too much attention, and so a tooltip via remark suffices.

It can be annoying to make readers jump to the bottom of the page to
read a footnote.  Instead, I prefer to write an /inline [[doc:org-block/tooltip][remark]]/
containing, say, references or additional explanation.

   /[[tooltip:Allah][The God of Abraham; known as Elohim in the Bible]] does not burden a
       soul beyond what it can bear./ --- Quran 2:286

Or, without specifying an explicit label:

   /Allah[[tooltip:][The God of Abraham; known as Elohim in the Bible]] does not
       burden a soul beyond what it can bear./ --- Quran 2:286

A tooltip opens when its word is hovered with a mouse, or tapped on a phone; it closes when we leave both, tap elsewhere, or press Escape. Its text is Org, exported as Org, so it may hold links —clickable, since moving into the tooltip keeps it open— and any other markup; an Elisp docstring is shown just as it is written. The machinery is tooltips.js, about eighty lines with no dependencies, in the look of tooltips.css; both are inlined into each exported page, which so fetches nothing for them.

Org's own footnotes are such remarks too: in HTML, each footnote's number is a tooltip of its definition, the footnotes section staying below, for print; in LaTeX, each is a margin note, as the margin block's are, numbered as footnotes are. All three of Org's spellings serve: an anonymous [fn::…], a named [fn:NAME] defined elsewhere, and a named inline [fn:NAME: …], which later [fn:NAME] references share.

The Quran was revealed over 23 years[fn::From 610 to 632 CE, in Mecca then Medina.], and the
Torah[fn:torah] and the Gospel[fn:injil: /Injil/, given to Jesus.] are honoured in it as earlier
scriptures; the Gospel[fn:injil] is named in it a dozen times.

[fn:torah] /Tawrat/, given to Moses; see [[https://en.wikipedia.org/wiki/Tawrat][Tawrat]].

A doc:𝒳 link shows the documentation of 𝒳 as a tooltip in HTML, and as a glossary reference in LaTeX. Here 𝒳 is an Emacs Lisp function or variable, a word in the English dictionary —via WordNet's wn, should we have it— or, best of all, a term of our own.

The ~doc~ link type can be used to show tooltips for Emacs Lisp commands such as

                         doc:thread-last
                         
However, it can also be used for your own definitions/glossary.
First define a term as follows, which does not render anything in the resulting HTML.

                 #+begin_documentation Category Theory :label cat
                 A theory of typed composition; e.g., typed monoids.
                 #+end_documentation

Then you can refer to it using the given :label, if any:

                             doc:cat
  
Or else refer to it with underscores in lieu of spaces:

                       doc:Category_Theory

Either approach renders the name of the term, not the way its referenced.
If you want to change what's rendered, provide a description:

                  [[doc:cat][abstract nonsense]]

Finally, if ~doc~ gets a label that is not an Emacs Lisp command, variable, nor a user-defined
definition via #+begin_documentation, then we try to look up its definition via the dictionary:

                          doc:happiness

Our own terms are data in an Org file: an entry is either a documentation block, which exports nothing, or a heading tagged :documentation:, which exports as an ordinary section. The heading's title is the term's name, its :DOC_KEYS: property lists the labels by which we cite it, and its own text is the definition. Either way, the name with underscores in lieu of spaces is a label too; e.g., doc:Category_Theory. Moreover, show:GLOSSARY lists every term the page cites, wherever it sits.

Our glossary, listing every term this page cites ---even those cited further below:

                                     show:GLOSSARY

* Category Theory                                                   :documentation:
:PROPERTIES:
:DOC_KEYS: cat
:END:
A theory of typed composition; e.g., typed monoids.

* Using our terms

A glossary entry may instead be a block, which exports nothing:

#+begin_documentation Monoid :label mon
A set with an associative binary operation that has a unit.
#+end_documentation

Then, doc:cat studies [[doc:mon][monoids]] and their kin.

Terms we cite across many files go in a library: a list of Org files in org-docs-libraries, whose entries —blocks and headings alike— every doc:𝒳 link may cite. The files are read, not exported, so loading them is quick; M-x org-docs-load-libraries reloads them after an edit, and M-x org-docs-insert inserts a doc:𝒳 link by searching all the terms we have.

A radio target is a term too: in A <<<monoid>>> is a set with an associative operation and a unit., the target names the term and its paragraph defines it; so doc:monoid cites it, in the same file or, from a library, in any other.

Finally, a package's whole API makes a glossary of its own: the package-docs block exports a table of the public functions, macros, and variables that a feature defines, each name a doc:𝒳 link whose tooltip is its documentation.

#+begin_package-docs org-deflink
#+end_package-docs

An align block's contents are LaTeX, aligned at each &; as in LaTeX, a line ends in \\, unless it ends in a tag :tag-COLOUR: NAME, which is NAME in that colour and is what [[eqref:NAME]] cites. Following such a link in Emacs visits the line; failing that, any \tag{…NAME…}. An align :numbered t numbers its untagged lines too. Since the contents are LaTeX, shorthands are welcome: the :let switch gives them, as below.

An ~align~ block lines equations up at each =&=; a line may end in a coloured tag, to which an
=eqref:= link refers. Shorthands, such as =->= below, come from the =:let= switch every block has.

#+begin_align :let (-> "\\Rightarrow" == "\\equiv")
p -> q &== \neg p \lor q          :tag-blue: Implication
p \land q &== p == q == p \lor q  :tag-orange: Golden Rule
#+end_align

By [[eqref:Golden Rule]], conjunction is defined by equivalence and disjunction.

To share shorthands among many blocks, name them once, in a table that need not itself export:

#+begin_align :let logic
p -> q &== \neg p \lor q
#+end_align

* Shorthands :noexport:
#+name: logic
| Variable | Value       |
|----------+-------------|
| ->       | \Rightarrow |
| ==       | \equiv      |

The rows above the rule are a header, and are skipped. A Lisp variable serves too, across documents: (setq logic '(-> "\\Rightarrow")) and then :let logic.

To present mathematical formulae in HTML export, we may use LaTeX-style commands such as {\color{red} x} by enclosing them in $-symbols to obtain \({\color{red}x}\). This is known as the MathJax tool —Emacs' default HTML export includes it. (Unfortunately, MathJax does not directly support arbitrary HTML elements to occur within the $-delimiters.)

It is common to declare LaTeX definitions for convenience, but such declarations occur within $-delimiters and thereby produce undesirable extra whitespace. See the superflous vertical whitespace in the Result side below.

Hello, in this blog post I'd like to talk about quantifiers.
# First, I'll define some helpers that I use multiple times...
  $$
 \def\Plus{\color{teal}\bigoplus}
 \def\plus{\;\color{teal}\oplus\;}
 \def\f#1{{\color{brown}f}{\color{violet}(#1)}}
 \def\xstart{\color{red} a}
 \def\xend{\color{cyan} b}
 $$
 
 Anyhow, let's talk about quantifiers...
 $$
 \Plus_{{\color{violet} x} = \xstart}^{\xend} \f{x}
 \; = \;
 \f{{\xstart}} \plus \f{a+1} \plus \f{a+2} \plus \cdots \plus \f{{\xend}}
 $$

 The above “quantification” means [[teal:Loop sequentially with]]
 [[brown:loop-bodies f(x)]] [[teal:fused using ⊕]], using [[violet:x as the
 name of the current element]], [[red:starting at a]] and [[cyan:ending at b]].

As such, we declare the latex-definitions block type which avoids displaying such extra whitespace in the resulting HTML.

Hello, in this blog post I'd like to talk about quantifiers.
 
# First, I'll define some helpers that I use multiple times...   
#+begin_latex-definitions
\def\Plus{\color{teal}\bigoplus}
\def\plus{\;\color{teal}\oplus\;}
\def\f#1{{\color{brown}f}{\color{violet}(#1)}}
\def\xstart{\color{red} a}
\def\xend{\color{cyan} b}
#+end_latex-definitions

Anyhow, let's talk about quantifiers...
$$
\Plus_{{\color{violet} x} = \xstart}^{\xend} \f{x}
\; = \;
\f{{\xstart}} \plus \f{a+1} \plus \f{a+2} \plus \cdots \plus \f{{\xend}}
$$

The above “quantification” means [[teal:Loop sequentially with]]
[[brown:loop-bodies f(x)]] [[teal:fused using ⊕]], using [[violet:x as the
name of the current element]], [[red:starting at a]] and [[cyan:ending at b]].

﴾What You Write﴿

Org lists are already trees, so the ~graph~ block draws them with Graphviz:
nesting makes an edge, and a two-column table styles the item above it.

#+begin_graph :file lambda-calculus.png
#+graph:
| rankdir | LR |

#+node:
| shape | box |

+ λ-calculus
  | shape | ellipse |
  + encodes :: Church encodings
  + <> Combinators
    + S K I
+ Lisp
  + borrows :: [[combinators]]
    | :edge.style | dotted |
#+end_graph

Press =C-c C-c= inside the block to render it to a PNG; =C-u C-c C-c= shows the dot source instead.

﴾What You Get﴿

Org lists are already trees, so the graph block draws them with Graphviz: nesting makes an edge, and a two-column table styles the item above it.

Press C-c C-c inside the block to render it to a PNG; C-u C-c C-c shows the dot source instead.

The graph block is opt-in, so we load it separately with (require 'org-graph-block). Rendering needs the dot executable from Graphviz: HTML export embeds a PNG —or an inline SVG, with tooltips intact, via :svg t— whereas other backends receive the dot source. Inside the block, #+graph:, #+node: and #+edge: tables set Graphviz's defaults; C-h o org-block/graph documents every option.

Just as every src block understands :exports and :results, every block understands these header arguments —ours, those made with org-defblock, Org's own src, example, quote, verse, and center blocks, and any #+begin_𝒳 at all, no declaration needed:

#+begin_box Exercise :let (N 7)
What do the first N odd numbers sum to?
#+end_box

#+begin_box Answer :let (N 7 SUM (* N N)) :folded "Peek at the answer"
The first N odd numbers sum to N × N, which is SUM.
#+end_box

#+begin_remark :noexport t
Ask the class for a proof by induction next week.
#+end_remark

#+begin_parallel :when (eq backend 'html) :boxed "On the web only"
Columns suit wide screens.
#+columnbreak:
Print gets one column.
#+end_parallel

A src block's :folded t is titled by its language, and its code is still exported by Org, as ever. Switches apply before Babel runs, so a src block's :let changes the code it runs, :noexport keeps it from running at all, and :folded folds away its results too. Other switches then apply to a :verbatim showing; e.g., :verbatim demo :folded t folds away a block's source and result alike.

Moreover, :C-c_C-c ACTION gives a block an action in Emacs: pressing C-c C-c within it calls ACTION when it names a function, else evaluates it as a Lisp form; see C-c C-c for your own blocks.

Switches are inherited as a src block's header-args are; e.g., :header-args:red: :let (N 3) in a heading's drawer gives every red block of its subtree that :let.

A block that declares a keyword of the same name keeps it for itself; e.g., a block with its own folded argument receives :folded as usual. Since :when, :let and :C-c_C-c run Lisp written in the document, Emacs asks once before running each distinct form; org-defblock-evaluate-switches may instead allow them freely, or never.

Five blocks, after GitHub's alerts, call out a paragraph with a coloured rule down its left under a titled heading; the title defaults to the block's name.

#+begin_tip
=C-h k= followed by any key tells us what that key does.
#+end_tip

#+begin_warning Mind the gap
=C-x C-c= quits Emacs, unsaved buffers and all ---it asks first, though.
#+end_warning

The colours, icons, and intended uses live in org-callouts. Since a heading tagged :note: is common enough to mean something else entirely, callouts claim neither tags nor link types.

Exported to Markdown (ox-md or ox-gfm), a callout becomes GitHub's own alert, > [!WARNING]; since alerts are untitled, a custom title becomes its bold first paragraph. See Markdown export for what the other blocks become.

Each of the 19 colours that HTML and LaTeX's xcolor share —black, blue, brown, cyan, darkgray, gray, green, lightgray, lime, magenta, olive, orange, pink, purple, red, teal, violet, white, and yellow— is a block, a link, and a tag; color takes any other, by name or hex code. In Emacs, too, each such link shows its text in its colour, as soon as org-special-block-extras-mode is on.

#+begin_red
Look at my text, it's red!
#+end_red

#+begin_pink
Look at my text, it's pink!
#+end_pink

#+begin_color cyan
Look at my text, it's cyan!
#+end_color

green:Look
blue:Here
orange:Buddo!

[[color:#ff0066][Any hex colour]], [[color:navy][any colour's name]], and [[red:][a described red link]].

Org's own quote block, given a bibliography key, cites it, at its pages —the key given as the main argument, or as :key:

#+begin_quote zermelo1908 :pages 20-22
Set theory is that branch of mathematics whose task is to investigate
the fundamental notions of number, order, and function.
#+end_quote

In LaTeX, and so in beamer, this is csquotes' \blockcquote[20-22]{zermelo1908}{…}, cited by our bibliography —biblatex's \addbibresource, BibTeX's \bibliography, or org-cite— which is ours to give; csquotes itself is loaded for us, unless we load it ourselves. In HTML, it is a <blockquote> closed by “— zermelo1908, 20-22”; in Markdown, a quote closed likewise. A quote sans arguments is Org's own, as ever.

The quoted text hugs its braces, \blockcquote[20-22]{zermelo1908}{Set theory …function.}, sans the stray spaces LaTeX would read from its newlines; so does the contents of any block of ours whose LaTeX wraps it in braces, say (format "\\textbf{%s}" contents).

As a link, a quote is inline: [[quote:zermelo1908][set theory is …]] is csquotes' \textcquote{zermelo1908}{…}, and [[quote:][to be]] is just “to be”. A section tagged :quote: is a quote of its text.

Where red:𝒳 colours text, [[highlight:pink][𝒳]] colours its background; the colour defaults to yellow, and the link shows so highlighted in Emacs too.

Skimming readers see [[highlight:yellow][the one sentence that matters]], and [[highlight:pink][the one to reread]].

#+begin_highlight #e5f5e5
A whole paragraph, gently set apart.
#+end_highlight

For the reader who would rather pick the page's background colour themself, [[palette:][Pick a background]] is a button that unfolds a palette of pale colours, org-palette-colors; clicking one makes it the background —try it: Pick a backgroundsnowghostwhitewhitesmokefloralwhiteoldlacelinenantiquewhitepapayawhipblanchedalmondbisquecornsilkivorylemonchiffonseashellhoneydewmintcreamazurealicebluelavenderlavenderblushmistyrosebeigelightyellowlightcyanwhite.

A style block is the page's CSS, taken verbatim; it exports to nothing but HTML.

#+begin_style
h2 { color: teal; }
#+end_style

Exporting to Markdown, with ox-md or ox-gfm, our blocks see backend as html, since md derives from it; (org-export-markdown-p) tells the two apart. A Markdown renderer, such as GitHub's, keeps only some HTML: it strips every style, class, <style>, and <font>, yet keeps <details>, <kbd>, <mark>, <ins>, <abbr title>, <img>, and $$ maths.

Work as-is

badge, melpa, kbd, details, solution, rename, and show export just as they do to HTML, and so render on GitHub —sans colours.

Markdown of their own

these blocks export to Markdown idioms, rather than HTML.

Block	Markdown export
note, tip, …	GitHub's own alert, > [!TIP]; a custom title is a bold line
box	a quote, opening with its title in bold
remark	a > [!NOTE] alert, titled by its editor
highlight	<mark>, which GitHub shows yellow, whatever the colour
spoiler	numbered blanks, with the answers folded away beneath
tree	$$…$$ displays, as GitHub's maths knows no \[…\]
org-demo	the source as a code block, then its result
doc, tooltip, kbd	<abbr> with a plain-text title, as there is no tooltipster
latex-definitions	nothing, lest its definitions show
graph	its image, written to its :file (else graph-HASH.png), linked

Plain HTML

every other block emits the HTML it always does, which a given Markdown renderer may not honour; e.g., on GitHub, colours ---red:𝒳, #+begin_color— and parallel's columns are stripped, leaving plain, stacked text. Then there are style, palette, html-export-style, and toggle-details, which are HTML-only by design: they dress the page itself, and Markdown has no say over the page.

Dislike how a block B exports to Markdown? Advise org-block/B on your own machine; its result is Org, so the export makes of it whatever it does of any Org. By way of example, boxes between horizontal rules:

(advice-add 'org-block/box :around
            (lambda (box backend raw-contents &rest args)
              "In Markdown, a box is its bold title and text, between rules; elsewhere, as before."
              (if (org-export-markdown-p)
                  (format "-----\n*%s*\n\n%s\n-----" (car args) raw-contents)
                (apply box backend raw-contents args))))

Each block names the LaTeX packages it needs —a box, xcolor and tcolorbox; a cited quote, csquotes— and a LaTeX export that uses the block, or its link, loads them just before \begin{document}. So we declare none ourselves; a package we do load, options and all, is left be. To see what a block needs, read the :latex-head of its definition, or evaluate (get 'org-block/box 'org-latex-head) ⇒ ("xcolor" "tcolorbox").

A test, tests/org-pdf-export-tests.el, keeps this honest: it compiles every example of this manual to a PDF, and to beamer slides, declaring no packages at all. It uses LuaLaTeX, which reads Unicode such as 𝒳 and ⇒ as is; pdflatex instead needs a \newunicodechar for each such character. Slides have no margins, so there our margin notes, tooltips, and Org's footnotes are beamer's own footnotes.