AsciiDoc

Introduction

Lightweight Doxygen comments embedded in the library source code is an excellent way to provide short-form, tool-tip style documentation. On the other hand, long form documentation complete with cross links, references, examples etc., is best built and maintained outside the source code itself though most likely in files that are located in the same repository.

What markup format should those long form pages use?

Markdown is by far the best known lightweight markup language. These days it is used just about everywhere on the web. It is so simple to learn that you can get up to speed in just a couple of minutes, yet it provides enough features to enable you to write most shorter documents. It has chapters/sections, paragraphs, the usual text formatting such as italic, bold, monospaced etc., along with lists, tables, and so on. Code blocks can be made stand out from regular text which is handy for documentation purposes.

The format is ubiquitous so if you download a Markdown file to your tablet or computer and click on it the chances are excellent that it will open and get rendered in some very reasonable way (though not necessarily the exact same way that it looks to someone reading it on a different device or application).

Markdown is just simple text with some character combinations used to suggest formatting. If you can write text, you can write Markdown. Moreover, there are a huge number of tools available that enable you to view the formatted output more or less as you type it. Every editor will have a plugin that renders Markdown. There are also some excellent dedicated Markdown editors.

Of course, our GF2++ is a math library so it is handy to be able to have a formula or two in the documentation. That wasn’t part of the original Markdown but these days most flavors allow you to embed \(\TeX\) equations like:

\[ \mathbf{u} \cdot \mathbf{v} = \sum_i u_i \times v_i.\]

However, even with all that, Markdown is far from ideal for writing software documentation. It shines when everything fits in a single file but it misses some key features once a project spills over to many files. Links between files can be created in Markdown but you can’t really even simply include one file or part of a file in another (for example have a code snippet in one file and then include the relevant section as text into another).

There is also no native support for some really useful things that are common in technical documentation. For example, callouts where you highlight lines of sample code with explanatory materials, and admonitions where you warn the user of some particular issue or other. Of course Markdown does allow you to embed HTML in the document so all things are possible but, once you go that route, definitely no longer easy.

As the documentation grows you will inevitably be led to exploring alternatives and the one we settled on is AsciiDoc.

AsciiDoc itself can be a pretty lightweight markup language. In fact, if you restrict yourself to the same feature set as Markdown, an AsciiDoc .adoc file will look very similar to the equivalent Markdown .md one. Here is a cheat-sheet that shows the equivalence between the two forms of markup.

However, AsciiDoc is extensible and much more powerful than Markdown.

For example, the AsciiDoc include directive allows you to embed some snippets of text in multiple locations without resorting to copy-paste.

Explanations can easily be added to particular code lines by using callouts such as:

  auto v = GF2::Vector<>::random(16); (1)

1	This creates a `GF2::Vector` of size 16 with a random fill where the vector elements are equally likely to be 0 or 1.

AsciiDoc also has admonitions as a way to highlight warnings so the reader’s attention is drawn to particular gotchas that might trip them up. Those can also be used to highlight tips and informational notes etc. such as:

These features and many others are standard in AsciiDoc and very simple to use.

AsciiDoc is not nearly as well known as Markdown but nonetheless your editor probably has a plug-in to make writing it pleasant and to enable previewing the formatted output as you go.

Asciidoctor

These days, Asciidoctor is the principal tool used to process AsciiDoc files. It is a mature open source program that can convert AsciiDoc to HTML, PDF, EPUB, DocBook, manual pages etc. It is written in Ruby and works on all the usual platforms, Windows, macOS, and Linux.

There is also a JavaScript version so you can install a browser extension and then simply open an AsciiDoc file to see it nicely rendered with active links etc. That can be quite handy when you are authoring material as you can see previews in a browser even if your editor doesn’t have any specific AsciiDoc support.

Of course you can hardly expect all your library users to install a browser plugin just to read your documentation!

Instead you might use Asciidoctor to convert all the .adoc files into HTML.

Suppose the AsciiDoc content is in files and subdirectories sitting beneath a documentation/manual/pages/ directory. Then you can sit in the parent documentation/manual/ and use the the following Asciidoctor command to convert all the .adoc files in pages/ into their .html equivalents.

$ asciidoctor -R pages -D html pages/**/*.adoc

The .html files will in be found in an identical directory layout in the sibling documentation/manual/html/ directory.

A reader can then browse through those HTML files without any need for an AsciiDoc plug-in. However, all Asciidoctor gives you is a simple tree of files without any of the navigation niceties you would expect in a modern website so the job is not yet done!