/
03-01-AsciiDoc.Rmd
153 lines (122 loc) · 8.92 KB
/
03-01-AsciiDoc.Rmd
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
## AsciiDoc | DocBook
AsciiDoc is a document format semantically equivalent to DocBook XML, but using plain text markup.
Hence, the claim is that apart from the default outputs provided by AsciiDoc tools, it is also possible to produce
PDF, LaTeX, man pages, e-books, etc. by using DocBook toolchains.
<aside>
**W** [AsciiDoc](https://en.wikipedia.org/wiki/AsciiDoc), [DocBook](https://en.wikipedia.org/wiki/DocBook)
</aside>
AsciiDoc tooling was initially written in Python in the early 2000s.
A decade later, an independent implementation written in Ruby and named Asciidoctor was released.
A transpile of Asciidoctor to JavaScript using [Opal](https://github.com/opal/opal) is also provided, which is named
Asciidoctor.js.
Moreover, CLI binaries built from Asciidoctor.js are available, but not from Asciidoctor.
<aside>
- [asciidoc.org](https://asciidoc.org/)
- [asciidoctor.org](https://asciidoctor.org/)
- [asciidoctor/asciidoctor](https://github.com/asciidoctor/asciidoctor)
- [asciidoctor/asciidoctor.js](https://github.com/asciidoctor/asciidoctor.js)
- [rtomayko/tilt](https://github.com/rtomayko/tilt)
- [opal/opal](https://github.com/opal/opal)
</aside>
AsciiDoc (the format) is currently being developed in a working group of the Eclipse Foundation.
The goal is to prevent further divergence between Python AsciiDoc tools and Asciidoctor.
<aside>
- [asciidoc-wg.eclipse.org](https://asciidoc-wg.eclipse.org/)
- [projects.eclipse.org: AsciiDoc Language](https://projects.eclipse.org/projects/technology.asciidoc)
- [Hacker News #24849348](https://news.ycombinator.com/item?id=24849348)
</aside>
Since Asciidoctor seems to have stronger momentum than AsciiDoc, we will focus on the former.
The main generators provided by Asciidoctor are HTML5, DocBook 5 and man pages.
Additional converters, such as PDF and EPUB 3, are provided through separate gems.
Moreover, it uses Tilt for templating, which allows users to customize the generated output without writing a custom
converter from scratch.
Asciidoctor also provides a default stylesheet and built-in integrations like Font Awesome (for icons), highlight.js,
Rouge, and Pygments (for source highlighting), and MathJax (for STEM processing).
The default HTML5 theme is based on [Foundation](https://foundation.zurb.com/).
### Interesting features
Overall, the syntax looks nice, clear and powerful.
It feels much readable than solutions based on markdown or restructuredtext.
A built-in mechanism is provided for defining *blocks* with custom parameters and layout.
Those are named *delimited blocks*.
That's a powerful mechanism that, at first sight, allows users to extend the markup language and matching templates
without having to deal with the backend/generator.
That is, no Ruby knowledge is required, a priori, for creating and using custom *delimited block* types.
<aside>
- [asciidoctor.org/docs: Building blocks in AsciiDoc](https://asciidoctor.org/docs/asciidoc-writers-guide/#building-blocks-in-asciidoc)
- [asciidoctor.org/docs: AsciiDoc vs Markdown](https://asciidoctor.org/docs/asciidoc-vs-markdown/)
</aside>
The support of diagram tools is awesome.
It provides a common syntax for including GraphViz, WaveDrom, Mermaid, Symbolator, PlantUML...
Each figure can be generated as SVG, PNG or TXT.
The figures can be written in the asciidoc sources or included from a source file.
<aside>
- [docs.asciidoctor.org: Asciidoctor Diagram](https://docs.asciidoctor.org/diagram-extension/latest/)
</aside>
Direct PDF generation through [Prawn](https://github.com/prawnpdf/prawn) is supported.
It allows generating nice looking PDFs while tweaking the design through CSS attributes.
Features such as Asciidoctor Diagram work nicely when generating both HTML and PDF outputs.
See, for instance, [stnolting.github.io/neorv32](https://stnolting.github.io/neorv32/)
([PDF](https://github.com/stnolting/neorv32/releases/download/nightly/NEORV32-nightly.pdf)).
### Drawbacks
Although several features are available through templating and delimited blocks *in theory*, *in practice* many tweaks
and customisations do require writing plugins in Ruby/JavaScript or using wrappers around asciidoctor itself.
Overall, multiple HTML themes are available and it seems easy to customize the CSS output.
However, the author did not find examples showcasing different templates with a clearly different structure/layout.
That is, themes or skins are available, but not templates.
<aside>
- [themes.asciidoctor.org/preview](http://themes.asciidoctor.org/preview/)
- [Produce Custom Themes Using the Asciidoctor Stylesheet Factory](https://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/)
</aside>
#### Multi-page HTML documents
Asciidoctor supports writing complex documents in multiple source files, using includes for composing the final
structure.
However, generating multiple HTML pages for one document is not supported.
By default, each document is compiled to a single HTML page.
That is unfortunate for very long documents, such as books or datasheets, because lots of scrolling is required.
Asciidoctor allows customising the theme/style of the HTML output and extending it, but generation of multiple pages
cannot be done on top of the default template.
One might generate documents/pages separatedly and then inject the TOC or wrap them together.
Nonetheless, several internal cross-reference features would need to be taken care of.
Therefore, the recommendation is to develop a custom template.
There are several of those in GitHub/GitLab repositories, but they tend to be very specific; so it's best to use them as
a reference.
There is some info about how to achieve it in [asciidoctor/asciidoctor#3948](https://github.com/asciidoctor/asciidoctor/issues/3948).
Yet, there is no tutorial, how-to or API reference available yet.
Some users tried writing custom converters (see, for instance, [owenh000/asciidoctor-multipage](https://github.com/owenh000/asciidoctor-multipage)); however, none of them made it into the official resources nor seems to have traction.
There is a sibling project by the authors of asciidoctor named [Antora](https://antora.org/), written in JavaScript.
Antora allows building multi-page sites from sources located in multiple repositories (but can also be used in single
repository projects).
Antora uses asciidoctor.js; therefore, plugins for Antora are not the same as the ones for asciidoctor.
If an extension is written in JavaScript, asciidoctor cannot be used, the JS variant is required.
On the other hand, if written in Ruby, it might be possible to use it in asciidoctor and also compile it from Ruby to JS
(to some extent) for usage in asciidoctor.js or Antora.
Yet, there is a warning in [docs.asciidoctor.org: Compile Ruby Extensions to JavaScript](https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/compile-ruby-extension/):
> This is an advanced technique that has some limitations.
> The recommended way to use extensions in Asciidoctor.js is to write them directly in JavaScript.
Therefore, writing extensions which work with asciidoctor and Antora is a non-trivial task itself.
It might be reasonable if one is to develop a custom workflow for some mid or large project; but it is not a quick to
follow solution.
#### Collapsible ToC
Since multi-page HTML generation is not straightforward with asciidoctor, having collapsible items in the Table of
Contents shown at the side would easen the navigation.
In fact, when PDFs are generated, bookmarks are included, which allows PDF viewers to show collapsible trees.
Unfortunately, the default HTML5 template in asciidoctor does not support collapsing the items in the sidebar.
Again, several solutions were proposed (see [asciidoctor/asciidoctor#699](https://github.com/asciidoctor/asciidoctor/issues/699)),
but there is no official or documented solution.
#### LaTeX
Due to the context explained above, LaTeX output is a requirement for the author, and this workflow is
not completely explained in the docs.
There are brief references to `a2x` (which uses either Apache FOP or `dblatex`) and `asciidoctor-fopub`.
Among those, `dblatex` seems the most adequate, because `fopub` requires passing XSL parameters or modifying the XSLT
for altering the PDF output.
There is also `asciidoctor-latex`, which defines an extended syntax to closely match some LaTeX features (mathematical
formulas and environments); it can generate HTML or LaTeX.
Still, the first class citizen in AsciiDoc seems to be HTML5 output, and much of the docs are focused on it.
Unfortunately, the author did not had time yet for trying the different alternatives for generating LaTeX output.
Anyway, ready-to-use templates for journal articles à la [rticles](#rstudio) seem not to be available.
<aside>
- [asciidoctor.org/docs: PDFs](https://asciidoctor.org/docs/user-manual/#pdfs)
- [dblatex.sourceforge.net](http://dblatex.sourceforge.net/)
- [asciidoctor/asciidoctor-fopub](https://github.com/asciidoctor/asciidoctor-fopub)
- [asciidoctor/asciidoctor-latex](https://github.com/asciidoctor/asciidoctor-latex)
</aside>