We use Markdown for a number of internal and external writing purposes.

A primary reason is that it is a very low impact markup, for those times when you know you will want to emphasize an occasional word, but don’t really want to worry about whether the text is headed for LaTeX, HTML, or will just be read as-is by humans.

The fact that it also makes it really simple to quote code fragments is why it is heavily favored at the programmer’s Q&A site Stack Overflow and its extended family of related sites.

WordPress also supports Markdown, but as I’m finding that support is not without “quirks”. More on that will be found at this blog in the Experiments category.

When writing internal documentation, you likely want to have the Markdown transformed into something more powerful such as LaTeX, and perhaps ultimately rendered as PDF for distribution to a client or end-user. For that, the Pandoc tool is invaluable. Pandoc can manage all of the gory details of creating a PDF using LaTeX as an intermediate form, assuming that LaTeX is available. For Windows, the easiest way I know to achieve that is to install MiKTeX.

Pandoc is extremely powerful. It processes a number of document formats into an internal form, which it can write out to files in a number of formats. I most frequently use it to transform Markdown to PDF with mostly default settings. I also use its LaTeX output to write some chapters of larger documents in Markdown, allowing other content and the document fore-matter and configuration to be specified directly in LaTeX.

While Pandoc is the cornerstone of our handling Markdown documents, there are a few other documentation tools we use that should be mentioned.

Doxygen is a tool that processes C (and C-like) source code, extracting information from specially formatted comments along with declarations to write documentation for the implementation of programs. It is especially valuable when documenting libraries and public APIs, at least in languages that taste enough like C for it to process.

The AT&T Graphviz[graph] project provides a variety of tools that make generation of charts showing data flow, relationships between objects, and other graph structures easy. It processes a simple declarative source file and produces nearly optimally arranged graphs. Doxygen will use it if available to show some features of the program structure. I’ve found it a valuable resource to visualize other information when it is inherently a graph.

Mscgen is handy for drawing state charts, which are most useful to show the order of messages between various participants in a protocol. Doxygen also knows about mscgen and can use it if available. Apparently since its introduction a number of clones and extended versions have sprung up. I may want to survey that for a future article and possibly use.