Here are some of my latest thoughts on org-special-block-extras… 
Articles on this page
- org-special-block-extras: demos that are tests, rather than docs
- org-special-block-extras: Org lists, drawn as Graphviz graphs
- Powering-up Special Blocks: EmacsConf 2020 slides
- Tooltips for Glossaries, Dictionaries, and Documentation
- Badge Links
- Permalinks ---Org's own =<
>=, made visible--- - Editor Comments
- :fire: HTML Export Styles ---=#+html_export_style: THEME=
- Colours
- org-special-block-extras: Make your own blocks and links
- org-special-block-extras: The block and link types
- org-special-block-extras: Write Once, Export Everywhere
org-special-block-extras: demos that are tests, rather than docs
org-special-block-extras: Org lists, drawn as Graphviz graphs
Powering-up Special Blocks: EmacsConf 2020 slides
Tooltips for Glossaries, Dictionaries, and Documentation
Sometimes I want to use the same tooltipA remark, CONTENTS, on MARKER in the text: in HTML, a tooltip on MARKER, hovered on a desktop, tapped on a
phone; in LaTeX, MARKER followed by CONTENTS as a margin note, numbered by COUNTER, as footnotes are; in beamer, whose
slides have no margins, a footnote. Sans MARKER, the note’s number alone in LaTeX, and “°” in HTML.
It’s a /Allah[[margin:][The God of Abraham]] does not burden a soul …/
#+begin_tooltip simple
Squint, and Maybe ℕ is ℕ.
#+end_tooltip
exercise.
The block is one-off, “inline footnotes”; Org’s own [fn::…] are such remarks too. For a note used repeatedly, consider
declaring it with ‘documentation’ and citing it with ‘doc’.
WIDTH, COUNTER, and COLOR are LaTeX’s: the note is WIDTH wide, coloured COLOR, its number in black. Since verbatim
environments fail as arguments to \marginpar, CONTENTS is saved in a minipage within a LaTeX box, then unfolded in the
margin; hence, src blocks may appear within margin notes (•̀ᴗ•́)و For LaTeX, a ‘#+resize:’ line has the rest of the
note resized, to 1.3 the margin’s width ---requiring \usepackage{adjustbox}.
‘tooltip’ is an alias, for when we think in HTML rather than LaTeX.
An alias of ‘org-block/margin’.
Regarding the Lisp function:
+ BACKEND refers to the current export backend.
+ RAW-CONTENTS refers to the text as the user wrote it, sans its least indentation.
⇒ Its body asks, by &context, for CONTENTS: the ‘org parsed’ version of user text.
⇒ CONTENTS and RAW-CONTENTS are identical for the description of a link; whence the LINK? of &context is non-nil.
For example, upon LaTeX export, the Org special block
#+begin_tooltip
Hello, world
#+end_tooltip
is rewritten to the result of the call
(org-block/tooltip ‘latex "Hello, world") multiple times, so I write
the tooltip content once in a documentationA glossary entry: CONTENTS defines NAME, cited as doc:LABEL; a heading tagged :documentation: is one too.
The entries live in ‘org--docs’.
A documentation entry may have its LABEL, its primary identifier,
be:
1. Omitted
2. Given as a single symbol
3. Given as a many aliases ’(lbl₀ lbl₁ … lblₙ)
The third case is for when there is no canonical label to refer to
an entry, or it is convenient to use multiple labels for the same
entry.
In all of the above cases, two additional labels are included:
The entry name with spaces replaced by underscores, and again but
all lower case.
Documentation blocks are not shown upon export;
unless SHOW is non-nil, in which case they are shown
using the ‘box’ block, with the provided COLOR passed to it.
Alternatively, a heading tagged :documentation: is an entry, which
exports as an ordinary section: its title is the NAME, its :DOC_KEYS:
property holds the labels, and its own text is the entry.
* Category Theory :documentation:
:PROPERTIES:
:DOC_KEYS: cat cats
:END:
A theory of typed composition; e.g., typed monoids.
Entries are read afresh before each export, so they may be cited before
they are defined; see ‘org--docs-prepare’.
Regarding the Lisp function:
+ BACKEND refers to the current export backend.
+ RAW-CONTENTS refers to the text as the user wrote it, sans its least indentation.
⇒ Its body asks, by &context, for CONTENTS: the ‘org parsed’ version of user text.
⇒ CONTENTS and RAW-CONTENTS are identical for the description of a link; whence the LINK? of &context is non-nil.
For example, upon LaTeX export, the Org special block
#+begin_documentation
Hello, world
#+end_documentation
is rewritten to the result of the call
(org-block/documentation ‘latex "Hello, world") block and then
reference it using the the doc/bin/bash: line 1: wn: command not found
link type.
Badge Links
Badges provide a quick and colourful summary of key features of a project, such as whether it's maintained, its license, and if it's documented.
Permalinks ---Org's own =<>=, made visible---
Sometimes we want to point explicitly at a particular location in an article, such as within a #+begin_details
block. Org already has two kinds of target for this; we merely make the first one visible.
Editor Comments
“Editor Comments” are intended to be top-level first-class comments in an article that are inline with the surrounding text and are delimited in such a way that they are visible but drawing attention. I first learned about this idea from Wolfram Kahl —who introduced me to Emacs many years ago. We
:fire: HTML Export Styles ---=#+html_export_style: THEME=
It's annoying to have to introduce HTML into your Org —especially when you don't know HTML and don't want to learn it just to have a pretty webpage.
Colours
Let's develop blocks for colouring text and link types for inline colouring;
e.g., colorFormat text according to a given COLOR, which is black by default.
Regarding the Lisp function:
+ BACKEND refers to the current export backend.
+ RAW-CONTENTS refers to the text as the user wrote it, sans its least indentation.
⇒ Its body asks, by &context, for CONTENTS: the ‘org parsed’ version of user text.
⇒ CONTENTS and RAW-CONTENTS are identical for the description of a link; whence the LINK? of &context is non-nil.
For example, upon LaTeX export, the Org special block
#+begin_color
Hello, world
#+end_color
is rewritten to the result of the call
(org-block/color ‘latex "Hello, world") and tealShow text in teal color.
Regarding the Lisp function:
+ BACKEND refers to the current export backend.
+ RAW-CONTENTS refers to the text as the user wrote it, sans its least indentation.
⇒ Its body asks, by &context, for CONTENTS: the ‘org parsed’ version of user text.
⇒ CONTENTS and RAW-CONTENTS are identical for the description of a link; whence the LINK? of &context is non-nil.
For example, upon LaTeX export, the Org special block
#+begin_teal
Hello, world
#+end_teal
is rewritten to the result of the call
(org-block/teal ‘latex "Hello, world").
org-special-block-extras: Make your own blocks and links
Every block and link above is made with the very tools below, so a new one of our own is a
defun away.
org-special-block-extras: The block and link types
It can be useful to draw attention to some important text by
enclosing it in a boxEnclose text in a box, possibly with a TITLE.
By default, the box’s BACKGROUND-COLOR is green for HTML and red for LaTeX;
for LaTeX, there are also FRAME-COLOR and TITLE-BACKGROUND-COLOR.
SHADOW is an alternate style of boxing: It shows the contents in a centred
box with a shadow colour being the given non-nil value of SHADOW.
If SHADOW is a hexadecimal colour, it should be a string enclosed in double quotes.
More accurately, the following are all valid uses:
#+begin_box title :shadow t
#+begin_box title :shadow inset
#+begin_box title :shadow "pink"
#+begin_box title :shadow pink
#+begin_box title :shadow (cyan pink orange yellow)
#+begin_box title :shadow (cyan "inset pink" orange)
#+begin_box title :shadow (:left cyan :right pink :deep-right orange :deep-left yellow)
Notice that prefixing colours with ‘inset’ causes the colour to be within the box,
rather than spread, with blur, around the box. The use of ‘inset’ swaps left and right.
The HTML export uses a padded div, whereas the LaTeX export
requires the tcolorbox package; Markdown, sans colours, gets a quote opening with TITLE in bold.
Regarding the Lisp function:
+ BACKEND refers to the current export backend.
+ RAW-CONTENTS refers to the text as the user wrote it, sans its least indentation.
⇒ Its body asks, by &context, for CONTENTS: the ‘org parsed’ version of user text.
⇒ CONTENTS and RAW-CONTENTS are identical for the description of a link; whence the LINK? of &context is non-nil.
For example, upon LaTeX export, the Org special block
#+begin_box
Hello, world
#+end_box
is rewritten to the result of the call
(org-block/box ‘latex "Hello, world").
org-special-block-extras: Write Once, Export Everywhere
Life & Computing Science by Musa Al-hassy is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License