Documentation and Asciidoc
A few weeks ago I wrote a guide for installing OpenSUSE Kubic. I wrote it using my team at work’s lab manual templates in LibreOffice and then exported the output as a PDF. If you ever take a course from SUSE Training, you will receive a complete lab manual like this as a part of your course materials.
I received some good and some less-than-good feedback for this guide from people at SUSECON and on IRC. So a few days ago I began converting the source files from LibreOffice .odt files to AsciiDoc text files and I put them on github.
AsciiDoc is great as a markup language. I can make some very nice and professional output with only a basic “cheat sheet”. The problem is what format do you want your exported to be like? If you want just a standard html, then you can use the asciidoc or the asciidoctor application to export it to html and it looks great. If you want PDF, which is generally how I like distributing documents like this, it isn’t quite what I’m looking for.
So far, I’ve found three ways to export from AsciiDoc to PDF. You can use asciidoctor-pdf which is a plugin for asciidoctor. The asciidoctor-pdf output is nice. It looks quite professional. In the build that I’m linking to, there are some formatting issues that I hadn’t tackled yet, but overall it’s a nice looking document. The second method is with DAPS. DAPS is a technical writing tool from the SUSE Documentation team. In the latest version, 3.0.0, it works natively with AsciiDoc. An intro to AsciiDoc with DAPS can be found here. The output from my files looks like this. Again, it looks pretty nice. However if you look at both of these PDF files from asciidoctor and DAPS, and compare it with the link to my original PDF from LibreOffice above, you will see some important changes. In the original, we in the SUSE Training team have a specific color palette that we use for our documents and I wanted to create a nearly 1:1 translation from LibreOffice to AsciiDoc. Bold Monospace Blue for commands, Bold Monospace Green for urls and filenames, Bold Light Gray for field names. Also, page breaks between sections. This isn’t possible at the time being without me learning how to write my own custom XSLT stylesheets (which probably isn’t going to happen). Is this a negative on AsciiDoc? No, it’s still easier than learning Docbook or TeX. It means that I will need to change how I format my documents using AsciiDoc’s conventions if I use these tools, not my own.
I mentioned that there are three ways to export from AsciiDoc to PDF. The third is with a tool called AsciidocFX. This is a really cool tool that seems to no longer be actively maintained. It gave me the formatting that I wanted in the PDF output, but sadly it gave me a ugly title page which I can probably live with for now. I have mixed feelings about this project. On the one hand, it gives me pretty much what I want but on the other hand, if it isn’t being actively maintained, it’s a bummer. I also have the question whether the color palette that we use for training docs is really as important I think and perhaps I should stick with the standard formatting so that anything that I write look, at least from a format perspective, like what anyone else would write.
I will decide on a standard format soon. The OpenSUSE Kubic installation guide won’t be the last free guide that I write. I’m constantly working on new guides, slide decks, etc. for my day job at SUSE Training, but I also want to contribute to the various open-source communities that I work with more and I think this is a great way to do it.