Friday, January 21, 2011


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:


1 comment:

  1. Thanks for an interesting blog. What I find most remarkable is that both teams have managed to grow their matchday
    income despite the economical crises in Spain. How have they managed that, is it the pre-season tours that generate the growth or is it the local Spanish supporters that spend more money on football? Compared to German teams like Dortmund it
    is really striking how much more revenue per spectator they make."cheap web design"
    From the article referenced in the blog post I understand that Spanish ticket prices are indeed very high, but the stadiums are generally not sold out. This begs the question if it really makes sense to invest in stadium development? I know Atletico and Valencia are already doing it, but it seems to have caused at least Valencia economical troubles.