Category: Documentation

DAPS in a Container

JSEvansLeave a comment

DAPS is OpenSUSE’s “DocBook Authoring and Publishing Suite” that is used to build documentation for SUSE and OpenSUSE. It actually requires A LOT of dependencies when being installed and for that reason alone, it’s actually better to run it in a container. This is my image and how I use it.

docker run -v ~/myproject/:/home/user jsevans/daps:latest daps -d DC-project epub

Command Breakdown:

docker run – Run the command in the container:

-v ~/myproject/:/home/user – Maps a local directory called ~/myproject to a directory in the container called /home/user. /home/user is the default directory that is used by the daps command, so it is best to map this directory rather than needing any extra command line components.

jsevans/daps:latest – This is the image that I’ve created. It is based on OpenSUSE Tumbleweed but it is stable enough for this use. However, it is a large image ~1.2GB due to the number of dependencies.

daps -d DC-project epub – This is the actual command line argument for creating an EPUB ebook using DAPS. I use Asciidoc as my markup language since I don’t really want to learn docbook.

My Dockerfile:

FROM opensuse/tumbleweed
MAINTAINER Jason Evans <jsevans@opensuse.com>

RUN zypper refresh
RUN zypper --non-interactive in daps git

ENV HOME /home/user
RUN useradd --create-home --home-dir $HOME user \
&& chown -R user $HOME

WORKDIR $HOME
USER user

CMD [ "/usr/bin/daps" ]
Advertisement

Documentation and Asciidoc

JSEvansLeave a comment

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.