MJ Shea Consulting and Design

A long-long time ago while working at IBM, I used to use a program called GML to format my c-language source code for printing. By adding a few simple tags inclosed in c-language comments, my program source would be formatted for printing. The printout would include a title page, table of contents, and page numbers. You would think that in this time of you can find anything in the internet, that someone would have written a GML processor for Windows or Linux by now. If they have, I have not seen it.

Instead, I stumbled upon something called AsciiDoc. This is a Python program that processes text files containing "tags" and generates formatted output as HTML, Markdown, Word Documents, and PDFs. It does much more, but those are the formats I am primarily interested in generating.

I suspect that it is possible to edit the AsciiDoc configuration files to do what I used to do with GML. It appears that this requires knowing how AsciiDoc works with regular expressions. I have learned over my carrier that if you need to use regular expressions to accomplish a task, you are doing it wrong. I am convinced that regular expressions were created by Satin himself.

Instead, I created a fairly simple program in C that reads my source code file with a few simple tags and outputs a file that AsciiDoc uses as input. Then I can create a source code listing in any of the following formats. Look here to see how I did it (page coming soon).

When I want to share a document, I usually generate an HTML file that I share. Few want to see the raw text file. Here is the command that does the trick.

The option -a data-uri embeds any images as part of the HTML file for easier sharing.

Generating an MS Word compatible file is a two-step process. AsciiDoc converts the text file into a xlm format. Then a second program called pandoc converts the xml file into a docx file.

The resulting Word file needs editing before you can consider it complete. Pandoc does not format the tables as shown in the HTML version and your title page will need lots of help. However, it is easier to fix the formatting then start with a blank sheet of paper.

Maybe pandoc can be customized to fix these problems. I’ll have to take some time to research this.

I use another program along with AsciiDoc to generate PDF files from text files. The program is called dblatex. Here is the command that does the trick.

Asciidoc comes with another program that uses asciidoc configuration files with dblatex. The reason I use this is that I can put manual page break tags in the *.adoc files (<<<) and then dblatex will insert page breaks as instructed. Here is how you use this option.

The output looks nice enough. However, images are not sized correctly and the original may need to be sized to appear correct in the PDF. In the text document, set the image size width to 400 to make the figure fit.

There must be a better way…

When working with a GIT repository, it helps to include related notes in Markdown (MD) format. To create Markdown files using AsciiDoc, use the following commands.

I suggest saving both the text file and markdown file in the repository. There is no need to save the xml file.

I settled on using ditaa style diagrams in my documents. As raw text, you can read them just fine. As compiled asciidoc output, they look even better. Getting the ditaa processor to work took a little doing.

To install it, go here and download the zip file. Create a folder named "dita" in the asciidoc filters folder. For my install, here is the command line. Use whereis asciidoc to find the location on your machine.

Unzip the asciidoc-ditaa-filter file. Copy all the files to the ditaa folder you created above.

With that, you can change this…

…into this…

Kinda cool…