ElephantMark

a simple PHP documentation tool with Markdown markup

Sure, (X)HTML is the standard format for documentations, and that is great. This holds even more for people writing programs. But then, writing or reading HTML code directly is a bit awkward and a couple of lightweight markup languages have emerged to make that easier. In the past, I often used Perls POD. But recently, I discovered Markdown, which is even more convenient and versatile as a general tool.

I think, Markdown is also very suitable as a format in program comments. For example, wrapping a piece of code ... into code tags <code>....</code> is achieved by simply placing backticks around it. Putting a block of code inside a <pre><code>....</code></pre> with converting special characters (&, <, > etc.) into HTML entities is simply done by indenting the lines with 4 spaces or 1 tab. All this is very intuitive and effortless.

With ElephantMark, I now have a tool that puts this idea into practice for PHP. ElephantMark is two things: It states three short and simple rules that turn ordinary PHP comments into Markdown text pieces. Secondly, it is a script elephantmark.php, that actually does this conversion and can be used like phpdoc.

ElephantMark is no competition for standard documentation tools. Professional programmers, building big libraries, will need smarter tools with features like automatic cross references etc. The idea of using Markdown in source code comments is probably more interesting for people, that need to write in many different programming languages and use PHP only occasionally. ElephantMark is understood in five minutes, there is no entire new documentation language to learn.

In its current version 1, elephantmark.php makes use of the Markdown-to-HTML converter markdown.php, written by Michel Fortin. This is a great tool itself, thank you very much! Currently, one needs both these scripts for ElephantMark conversions. But maybe, there is a way to merge them into one file for future versions.

So, here is the script, which is its own manual:

elephantmark.php