p>I write most of my documents in asciidoc as it advertises, and mostly does, that almost any publish ready output can be produced from the same source. All was fine until I wanted to include formulae in a doc. It took a while but I got there in the end. This is what I did.

Finding how to do this was not easy as the relevent pages in the Asciidoc web site are broken and demonstrate exactly how it doesn't work. I wanted two output formats HTML and pdf. For the pdf I wanted the revision history populated from the documents git log. I didn't want this in the HTML version. Obvioulsy I wanted the formulae to render correctly in both.

I tried asciimath markup but this doesn't work for the pdf and I tried latexmath but this didn't work for HTML. This fundamentally broke the requirement to 'write once', 'publish many'. Part of the issue was an older version of asccidoc I had installed and a lack of one of the requirements in my case it was texlive-upquote. I also updated asciidoc to the gihub version.

Trying again I has success but I had to figure out the command line options for asciidoc and a2x.

For HTML

asciidoc -a asciimath FILENAME

For pdf

a2x -a docinfo -a asciimath FILENAME

For producing the docinfo file containing the git log in XML I wrote a bash script.

#!/bin/sh
# Create a docinfo file for an asciidoc file from it's git log.

infile=$1
outfile=${infile%.*}-docinfo.xml
isgit=$(git status >/dev/null 2>&1 && echo Hello World)
if [ "$isgit" == "" ]
then exit 0 # As we want the next command to run whether the docinfo file is produced or not.
fi
echo "<revhistory>" > $outfile
log=$(git log --date=short --pretty=format:"<revision><revnumber><![CDATA[%h]]></revnumber> <date><![CDATA[%cd]]></date> <authorinitials><![CDATA[%an]]></authorinitials> <revremark><![CDATA[%s]]></revremark></revision>" -- $infile)
echo $log >> $outfile
echo  "</revhistory>" >> $outfile

To sum up. Use the latest asciidoc, make sure you have all the requirements installed and you're good to go.

Last changed: 13. August, 2018 at 20:37

Comments