This weekend I wrote a lot of documentation. I spent around 12 hours on it in total. I knew there was no way I could stand being in LibreOffice for 12 hours, but I also knew that the consumers would prefer a prettier format than just plain text. I've been writing READMEs lately using markdown format, which converts to pretty HTML on github, so I decided to go that direction. Boy did it work well, once I found the magic tool: pandoc! Read on for more details…
Markdown is a great format because it's pretty in text, and it's easy to write, but it also can produce pretty other formats such as HTML. It's basically straight text with headers underlined by lines of “="s (H1) or ”-“s (H2), bulleted lists are just indented with a ”*“ or ”+“ or ”-“ to mark the bullets, pre-formatted blocks are indented 4 spaces, etc…
So the text is easy to write and also easy to read as text. And this meant that I could use vi to edit the text, which makes me happy!
I probably should have looked at this before I got started (but I figured worst case I could deliver the results as straight text), but at the end I needed to figure out how to convert it to a prettier format. After some searching I found "pandoc” the “general markup converter”.
It worked great, it supports a ton of formats including Markdown and ODT, so I ran:
pandoc -f markdown -t odt -o file.odt file.markdown
This produced a file I could load into LibreOffice and review for mark-up. There were a few places I had to tweak the formatting, I probably spent 15 minutes on this, and had results that I liked quite a lot.
Then I used LibreOffice to write out a PDF. I wanted Evelyn to review it, and often she hasn't had her laptop with her lately, so I used the excellent “Calibre” program to take the ODT and dump it to her Kindle.
I had never used pandoc before, but I am sure to make use of it again. It is a great tool!comments powered by Disqus