summaryrefslogtreecommitdiffstats
path: root/2020/info/22.md
blob: b68d47dcadc1feeb2166f55958f7ce9fd02453a8 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
# Powering-up Special Blocks
Musa Al-hassy

Users will generally only make use of a few predefined \`special
blocks', such as \`example, centre, quote', and will not bother with
the effort required to make new ones.  When new encapsulating notions
are required, users will either fallback on HTML or LaTeX specific
solutions, usually littered with \`#+ATTR' clauses to pass around
configurations or parameters.

Efforts have been exerted to mitigate the trouble of producing new
special blocks.  However, the issue of passing parameters is still
handled in a clumsy fashion; e.g., by having parameters be expressed
in a special block's content using specific keywords.

We present a novel approach to making special blocks in a familiar
fashion and their use also in a familiar fashion. We achieve the
former by presenting \`\`defblock'', an anaphoric macro exceedingly
similar to \`\`defun'', and for the latter we mimic the usual
\`\`src''-block syntax for argument passing to support special blocks.

For instance, here is a sample declaration.

    (defblock stutter () (reps 2)
      "Output the CONTENTS of the block REPS many times"
      (org-parse (s-repeat reps contents)))

Here is an invocation that passes an *optional* argument; which
defaults to 2 when not given.

<div class="stutter">
<p>
Emacs for the win ⌣̈
</p>

</div>

Upon export, to HTML or LaTeX for instance, the contents of this block
are repeated (\`stuttered') 5 times.  The use of \`\`src''-like
invocation may lead to a decrease in \`#+ATTR' clauses.

In the presentation, we aim to show a few \`practical' special blocks
that users may want: A block that &#x2026;

-   translates *some selected* text &#x2014;useful for multilingual blogs
-   hides *some selected* text &#x2014;useful for learning, quizzes
-   folds/boxes text &#x2014;useful in blogs for folding away details

In particular, all of these examples will be around ~5 lines long!

We also have a larger collection of more useful block types, already
implemented.

The notable features of the system are as follows.

-   Familiar \`\`defun'' syntax for making block &#x2014;\`\`defblock''
-   Familiar \`\`src'' syntax for passing arguments &#x2014;e.g., \`\`:key
    value''
-   Fine-grained control over export translation phases &#x2014;c.f.,
    \`\`org-parse'' above
-   **Modular**: New blocks can be made out of existing blocks really
    quickly using \`\`blockcall'' &#x2014;similar to Lisp's \`\`funcall''.  We
    will show how to fuse two blocks to make a new one, also within ~5
    lines.

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

## Resources

<https://alhassy.github.io/org-special-block-extras/emacs-conf-2020>