<div>Dear Markdown enthusiasts out there!</div><div><br></div><div><br></div><div>Sure, I don&#39;t need to tell you how great an versatile Markdown is for writing standard documents.</div><div>I think, that it would make a really great universal standard as a programming documentation language, too, and maybe &quot;CodeDown&quot; would be a good title for this approach.</div>
<div><br></div><div><br></div><div>The idea started when I was trying to document some PHP scripts. I need to use different programming languages for different purposes, but I am not a full time programmer. The problem is, that for most of these languages, the standard documentation tools are yet another language on their own, and I already have difficulties remembering the idioms of the programming languages. When I was working on the PHP scripts, I was looking for a standard tool to write some docs, but I was overwhelmed by phpDocumentor.</div>
<div><br></div><div>In the past, I often used Perl&#39;s POD to write tutorials for some of my programs, and that always did a good job. But a while ago I discovered Markdown, and I found that even more convenient and intuitive. I thought, it would be very easy to use that as the format for literal programming in PHP: by a simple modification of the usual comment delimiters /* ... */ and // in PHP, these comments would become designated blocks for Markdown comments or delimiters for source code parts, that would appear in the documentation. The possibility these literal code blocks is an essential part of Donald Knuth&#39;s literal programming concept, and most standard documentation tools are not even capable of realizing that.</div>
<div><br></div><div>In a first conversion step, these blocks would turn into Markdown, and in a second conversion step, the Markdown is converted to HTML.</div><div><br></div><div>                                  phpToMarkdown                      markdownToHtml</div>
<div>    PHP source code  ------------------------------&gt; Markdown --------------------------&gt; HTML</div><div><br></div><div><br></div><div>For the markdownToHtml function, I used Michel Fortin&#39;s PHP Markdown, so my actual converter is a pretty small script. I called it ElephantMark (see <a href="http://www-bucephalus-org.blogspot.com/2011/01/elephantmark.html">http://www-bucephalus-org.blogspot.com/2011/01/elephantmark.html</a>) and the according script is its own documentation.</div>
<div><br></div><div><br></div><div>This approach can be used for any mainstream programming language. My current favorite is Haskell, and I wrote a HaskellDown module, that does similar things for Haskell. The main converter is just a composition of two functions</div>
<div><br></div><div>                                    haskellToMarkdown                   markdownToHtml</div><div>    Haskell source code ---------------------------------&gt; Markdown ------------------------&gt; HTML</div>
<div><br></div><div><br></div><div>For the markdownToHtml part I used the very powerful Pandoc module, written by John MacFarlane. </div><div>This week, I&#39;ll give a talk about it on a meeting of the Dutch Haskell User Group, and I intend to publish it, as soon as possible.</div>
<div><br></div><div><br></div><div>During the preparations for the talk, I thought I should call the whole idea &quot;CodeDown&quot;, including &quot;Php(Code)Down&quot; as the CodeDown for PHP, &quot;PythonCodeDown&quot; as the CodeDown for Python, etc. There could even be a general CodeDown tool, that does the conversion for all these particular languages alltogether.</div>
<div><br></div><div><br></div><div><br></div><div>But before I put any more work into this project, I would like to find out, if there is really a general interest or support for this idea. Please, don&#39;t spare on your comments, answers or questions.</div>
<div><br></div><div><br></div><div>Greetings, Thomas</div><div>(<a href="http://bucephalus.org">bucephalus.org</a>)</div><div><br></div>