I’d written the API documentation for the BT Library in DocBook. This was in 2004, so it seemed a good choice at the time. Now, it seems less good. I decided I wanted to use a more lightweight documentation format. There’s plenty to choose from. However, after (very little) diligent research, I chose to move to AsciiDoc.
The two principle reasons were:
-
AsciiDoc seemed a richer and more capable markup language than the other main candidate, MarkDown.
-
I could see a reasonable migration path.
Migration Path
-
Converted DocBook to AsciiDoc using pandoc:
pandoc -wrap=none -f docbook -t asciidoc bt.xml >btlib.adoc
This handled the bulk of the conversion, but it’s not perfect.
-
Wrote an awk script to fix the API function call specifications. See below.
-
Added table annotations to obtain the desired presentation.
-
The entire revision history was missing from the AsciiDoc file, so converted it by hand and added to
btlib.adoc. -
Added document header, which included the creation of a Table of Contents via the
:toc:keyword. -
Converted
btcommand descriptions from a table to a Description List to give a more pleasing presentation. -
Manually added a Colophon section.
HMTL Production
In order to create an HTML version of the AsciiDoc format, I used AsciiDoctor. This is very simple:
asciidoctor btlib.adoc
This creates btlib.html and the supporting CSS, asciidoctor.css. The
site creation toolchain I use needed a small update to handle the single
page B Tree Library documentation
I am now free of the DocBook burden.
Awk script for API function call specifications
The pandoc conversion turned DocBook function call specifications into
something like this:
=== Creating a B Tree File #include "btree.h" BTA* btcrt char* fid int nkeys int shared
Well, the content is there, but not a lot of meaning (there’s also a blank line between each token, which I have omitted). The awk script to fix this up is below.
BEGIN {
in_decl = 0;
FTYPE = 1;
FUNC = 2;
VARTYPE = 3;
VAR = 4;
comma = "";
}
/^#include/ {
in_decl = 1;
next_token = FTYPE;
print("[source, C]\n----");
print($0 "\n");
next;
}
{
if (in_decl == 1) {
if (NF == 1) {
if (next_token == FTYPE) {
printf("%s ", $1);
next_token = FUNC;
}
else if (next_token == FUNC) {
printf("%s(", $1);
next_token = VARTYPE;
comma = "";
}
else if (next_token == VARTYPE) {
printf("%s%s ", comma, $1);
next_token = VAR;
comma = ", ";
}
else if (next_token == VAR) {
printf("%s", $1);
next_token = VARTYPE;
}
}
else if (NF == 0) {
next;
}
else {
in_decl = 0;
print(");");
print("----");
print($0);
}
}
else {
print($0);
}
}
It converts the example shown above into:
=== Creating a B Tree File [source, C] ---- #include "btree.h" BTA* btcrt(char* fid, int nkeys, int shared); ----
Authoring in AsciiDoc
I’ve since updated the site toolchain to allow the authoring of journal entries in AsciiDoc, rather than writing HTML by hand. This is the first entry using AsciiDoc.
