AsciiDoc and manpages

I came across AsciiDoc whilst completing the documentation for yt, one of my smaller bash projects. I had just completed a rewrite and was looking for a better way of documenting its functionality than to use nroff, which is quite archaic. Markdown was out of the question — I already use it for all my README files on github; what I needed was something new. Something with which I could play.

Enter AsciiDoc, the mature version of Markdown. While Markdown has its place for small projects, AsciiDoc blows it out of the water when it comes to more complex tasks like writing a book or several articles, both of which probably need to share content. AsciiDoc’s syntax is simple, concise and (most importantly) consistent. Writing and generating the manpage was a breeze:

a2x -f manpage yt.1.asciidoc

Reading the manpages for asciidoc and a2x got me thinking. Why not design a website with AsciiDoc? It provides everything I need and the default HTML theme is quite nice. A few days later, I stumbled upon someone who had had the same idea.

Websites and Makefiles

A new project was born. Good timing as well, I had been planning to redesign my homepage anyway. The old page was a mixture of HTML and PHP. It used to be simple and small enough, but extensive editing turned it into quite a mess in the end. AsciiDoc was a simple and convenient alternative — and that’s what a homepage should be: simple. Not only simple to use, but also simple to set up, expand and maintain. When I wrote articles for my old blog, I had to write HTML. That meant dealing with tags, manual paragraphs and a lot of divs. With AsciiDoc comes much-needed simplicity, which reminded me of a passage in Walden:

Our life is frittered away by detail. An honest man has hardly need to count more than his ten fingers, or in extreme cases he may add his ten toes, and lump the rest. Simplicity, simplicity, simplicity! I say, let your affairs be as two or three, and not a hundred or a thousand; instead of a million count half a dozen, and keep your accounts on your thumb-nail.
— Henry David Thoreau

With AsciiDoc as the “backend”, the only thing that needed work was the build system. I wanted to use a tool that already existed instead of writing my own bash script, so I turned to Make. After a bit of fiddling, I got what I wanted:

CC = asciidoc -b xhtml11 -a linkcss -a stylesdir=style -a stylesheet=custom.css \
         -a disable-javascript -a icons -a source-highlighter=pygments \
         -a badges -a favicon -a iconsdir=res/ -f conf/xhtml11.conf

# Location of the raw asciidoc files

# Location of the generated html files

OBJECTS = $(wildcard $(TXT)/*.txt)
HTML = $(addprefix $(SITE)/, $(notdir $(patsubst %.txt, %.html, $(OBJECTS))))

all: $(HTML)

        rm -f $(HTML)

update: all
        rsync -avmhO --no-perms site/ hephaestus:www/

$(SITE)/%.html: $(TXT)/%.txt conf/*
        $(CC) --out-file=$@ $<

.PHONY: all clean update


AsciiDoc has support for syntax-highlighting (pygments), macros, callouts, themes and a lot more. Check out the AsciiDoc User Guide if you’re interested in what AsciiDoc can do. More than 90% of the features are readily available for the HTML backend.

What remains to be done

Right now I am quite happy with the site. I thought about including support for an Atom feed but decided against it. As easy as it would be with AsciiDoc’s support for macros and XSL, it still is something of a bother (it’s XML after all). Maybe in the future.

Sein und Zeit

My homepage went through a lot of different iterations. The first version was a Blogger site I set up in 2009. Shortly afterwards I acquired my own web space at bplaced, on which I set up a WordPress blog (image). After writing 21 pages worth of articles on it (I think it was more than a hundred), newblog was born in October 2011: no more Wordpress (but still PHP).

The advent of /newblog (image) was met with a burst of activity on my side. Wordpress “WYSIWYG” madness was gone, which meant that articles were easier to write. I published around 50 articles until I lost motivation after enrolling at university. The blog was abandoned, and a new minimalistic (but quite cluttered) front page (image) was added in August 2013.

I have kept the front page up-to-date for the last two years, but it was a pain. Let’s see how long my motivation — and with it this iteration of — will last now.