Friday, July 12, 2013

Docbook admonitions

For the better part of a year, I've been attempting to get Docbook to produce admonition graphics (i.e., note, important, and warning). Having worked with Publican, I wanted a similar format without all of the baggage that comes with Publican.

Publican fans should make note that I'm using a home-grown web editor for my Docbook work. I save brain cells by not having to remember which switches to use when running xsltproc at the command line. Publican was a nightmare in getting it to work with a similar interface (ask if you want either).

In any case, I've switched from running Docbook 4.5 to 5.0. The "good":

  • The syntax is cleaned up a bit.

  • Admonition graphics now work.

  • One more thing off of my "to do" list!


The bad:

  • I had to rewrite a chunk of the web editor's code to get it to work with 5.0.

  • The syntax checker is more rigid than the previous version (see closing tag discussion below)


The really ugly:

  • Primarily, everything that I've written to date. The older version was tolerant of missing close tags if a more-senior opening tag was declared. This is no longer the case. It appears that all closing tags must be explicit.

  • Then there's my hand-drawn graphics. The same gene set that prevents anyone in my family from being able to carry a tune, appears to also prevent any of us from being able to draw anything attractive. I need to find a nice set of "note", "important", and "warning" icons that are Creative Commons licensed, so that I can start throwing my docs up online.


The only other thing left to do is to fix the syntax content and to tweak the features on the web editor. Notes in the wiki and tool plus docs online shortly.