org-special-block-extras
A unified interface for special blocks and links: defblock

MELPA

Abstract

The aim is to write something once using Org-mode markup then generate the markup for multiple backends. That is, write once, generate many!

In particular, we are concerned with ‘custom’, or ‘special’, blocks which delimit how a particular region of text is supposed to be formatted according to the possible export backends. In some sense, special blocks are meta-blocks. Rather than writing text in, say, LaTeX environments using LaTeX commands or in HTML div's using HTML tags, we promote using Org-mode markup in special blocks —Org markup cannot be used explicitly within HTML or LaTeX environments.

Special blocks, like centre and quote, allow us to use Org-mode as the primary interface regardless of whether the final result is an HTML or PDF article; sometime we need to make our own special blocks to avoid a duplication of effort. However, this can be difficult and may require familiarity with relatively advanced ELisp concepts, such as macros and hooks; as such, users may not be willing to put in the time and instead use ad-hoc solutions.

We present a new macro, defblock, which is similar in-spirit to Lisp's standard defun except that where the latter defines functions, ours defines new special blocks for Emacs' Org-mode —as well as, simultaneously, defining new Org link types. Besides the macro, the primary contribution of this effort is an interface for special blocks that admits arguments and is familar to Org users —namely, we ‘try to reuse’ the familiar src-block interface, including header-args, but for special blocks.

It is hoped that the ease of creating custom special blocks will be a gateway for many Emacs users to start using Lisp.

A 5-page PDF covering ELisp fundamentals can be found here.

This article is featured in EmacsConf2020, with slides here: No pictures, instead we use this system to make the slides have a variety of styling information; i.e., we write Org and the result looks nice. “Look ma, no HTML required!”

minimal-working-example-multiforms.png

Figure 1: Write in Emacs using Org-mode, export beautifully to HTML or LaTeX

Super Simple Intro to Emacs’ Org-mode

Emacs’ Org-mode is an outliner, a rich markup language, spreadsheet tool, literate programming system, and so much more. It is an impressive reason to use Emacs (•̀ᴗ•́)و

Org-mode syntax is very natural; e.g., the following is Org-mode! 

+ Numbered and bulleted lists are as expected.
  - Do the things:
    1.  This first
    2.  This second
    44. [@44] This forty-fourth
  - =[@𝓃]= at the beginning of an iterm forces
    list numbering to start at 𝓃
  - =[ ]= or =[X]= at the beginning for checkbox lists
  - Use =Alt ↑, ↓= to move items up and down lists;
    renumbering happens automatically.

+ Definitions lists:
   ~- term :: def~
+ Use a comment, such as =# separator=, between two lists
  to communicate that these are two lists that /happen/ to be
  one after the other. Or use any /non-indented/ text to split
  a list into two.

* My top heading, section
  words
** Child heading, subsection
  more words
*** Grandchild heading, subsubsection
    even more!

Export In Emacs, press C-c C-e h o to obtain an HTML webpage ---like this one!— of the Org-mode markup; use C-c C-e l o to obtain a PDF rendition.

You can try Org-mode notation and see how it renders live at: http://mooz.github.io/org-js/

You make a heading by writing * heading at the start of a line, then you can TAB to fold/unfold its contents. A table of contents, figures, tables can be requested as follows: 

# figures not implemented in the HTML backend
# The 𝓃 is optional and denotes headline depth
#+toc: headlines 𝓃
#+toc: figures
#+toc: tables

provides support for numerous other kinds of markup elements, such as red:hello which becomes “ hello ”.

Working with tables 

#+ATTR_HTML: :width 100%
#+name: my-tbl
#+caption: Example table
| Who? | What? |
|------+-------|
| me   | Emacs |
| you  | Org   |

Note the horizontal rule makes a header row and is formed by typing | - then pressing TAB . You can TAB between cells.

Working with links

Link syntax is [[source url][description]]; e.g., we can refer to the above table with [[my-tbl][woah]]. Likewise for images: file:path-to-image.

Mathematics

Source

\[ \sin^2 x + \cos^2 x = \int_\pi^{\pi + 1} 1 dx = {3 \over 3} \]

Result

\[ \sin^2 x + \cos^2 x = \int_\pi^{\pi + 1} 1 dx = {3 \over 3} \]

Source

#+name: euler
\begin{equation}
e ^ {i \pi} + 1 = 0
\end{equation}

See equation [[euler]].

Result

\begin{equation} \label{org44b9165} e ^ {i \pi} + 1 = 0 \end{equation}

See equation \eqref{org44b9165}.

Source code

Source

#+BEGIN_SRC C -n
int tot = 1;                    (ref:start)
for (int i = 0; i != 10; i++)   (ref:loop)
   tot *= i;                    (ref:next)
printf("The factorial of 10 is %d", tot);
#+END_SRC

Result

1: int tot = 1; (start)
2: for (int i = 0; i != 10; i++) (loop)
3:    tot *= i; (next)
4: printf("The factorial of 10 is %d", tot);

The labels (ref:name) refer to the lines in the source code and can be referenced with link syntax: [[(name)]]. Hovering over the link, in the HTML export, will dynamically highlight the corresponding line of code. To strip-out the labels from the displayed block, use -r -n in the header so it becomes #+begin_src C -r -n, now the references become line numbers.

Another reason to use Org: If you use :results raw, you obtain dynamic templates that may use Org-markup:

Source

#+BEGIN_SRC C
printf("*bold* +%d+ (strikethrough) /slanted/", 12345);
#+END_SRC

♯+RESULTS:
*bold* +12345+ (strikethrough) /slanted/

Result

printf("*bold* +%d+ (strikethrough) /slanted/", 12345);

♯+RESULTS: bold 12345 (strikethrough) slanted

The #+RESULTS: is obtained by pressing C-c C-c on the src block, to execute it and obtain its result.

Also: Notice that a C program can be run without a main ;-)

That is, we can write code in between prose that is intended to be read like an essay:

literate-programming.png

Single source of truth: This mini-tutorial can be included into other Org files by declaring

#+include: ~/.emacs.d/init.org::#Mini-tutorial-on-Org-mode

For more, see https://orgmode.org/features.html.

Table of Contents

The full article may be read as a PDF or as HTML —or visit the repo. Installation instructions are below.