A couple of Wikis, static XHTML, self-made XML, documents in a custom Lotus Notes database, text files here and there (often in Markdown syntax), and a pile of e-mails contain the bulk of documentation I've created during the past several years at a client. (It's a mess, but it could be worse.) I have got to clean this up before starting on new adventures.

Transforming Wiki markup to Markdown is possible. Parsing the HTML generated by Lotus Domino on documents which contain text and images pasted into a Notes database is very difficult. Transforming haphazardly created text to anything is far from possible, and the same applies to e-mail.

So how to solve this? Believe me, there was only one way out of that mess: copy and paste into a decent text format, and for that I chose Markdown. The copy and pasting bit is easy; with a good text editor, creating some indentations, inserting headlines and formatting the text a bit is also easy, so that proceeded rather quickly.

I temporarily "augmented" Markdown's syntax, inserting keywords into the individual documents I created; these keywords specify Git repositories containing code, pointers to online documentation, references to other chapters, etc.

So far so good, but how to get that printed out neatly? I settled for MultiMarkdown; it has support for LaTeX (and thus PDF output), supports document meta-data and chapters, and its XSLT transformer is easily adjusted. This I did in order to force the memoir package to use the fancyvrb package for creating listings, reducing the font size a bit to fit more onto a page.

The rest is electric: a trivial script takes the document files in order, runs them through a bit of sed, puts the result through MultiMarkdown, and out comes a PDF. I cheated on the title page: that I created separately.

I then ran (well, drove) down to the local copy shop and had the results printed and bound. My going-away gift, so to speak. On the other hand, maybe I shouldn't have bothered: no one will read it anyway. ;-)

Flattr this
Books and documentation :: 25 Feb 2010 :: e-mail

Comments

blog comments powered by Disqus