CodeDown = Markdown as the universal language for program documentation
David Chambers
david.chambers.05 at gmail.com
Mon Apr 11 17:46:01 EDT 2011
Check out Jeremy Ashkenas <https://github.com/jashkenas>'s
docco<http://jashkenas.github.com/docco/>.
Truly beautiful.
David
On 11 April 2011 13:32, bucephalus org <bucephalus.org at gmail.com> wrote:
> Hi Sherwood,
>
> Thank you very much for your interest and reply!
>
> On Mon, Apr 11, 2011 at 9:05 PM, Sherwood Botsford <sgbotsford at gmail.com>wrote:
>
>> Interesting concept, but I think you have it partially reversed.
>>
>> You want php -> codedown -> web
>>
>> I think it would be better:
>>
>> codedown -> php
>> codedown -> markdown -> web
>>
>
> I am not sure, if I understand what you mean. But I am under the
> impression, that maybe you don't understand what the general idea of
> CodeDown is. There is not separate code called "CodeDown", that could or
> should be translated into PHP or Markdown. There is only the source code of
> a particular given programming language, say PHP.
>
> Consider the following simple script, called `example.php`, comprising the
> following code
>
> <?php
> /*
> tripleThis($n) returns the three-fold of the given number $n.
> */
> function tripleThis ($n) {
> return 3 * $n;
> }
> ?>
>
> This is plain standard PHP, with one comment between /*...*/.
> I can run this through my ElephantMark converter, like so
>
> php elephantmark.php example.php
>
> and that returns an empty HTML document, pretty much like this
>
> <html>
> <body>
> </body>
> </html>
>
> You can also run the example.php script itself and use the triple()
> function, as usual with PHP!
>
> The thing is, that a little modification of the script (in fact, there are
> three simple syntax rules), turns it into a potential self-documentation of
> the script. But note, that the script as PHP script is totally unchanged!
>
> For example, by turning the ordinary command /*...*/ into what I called a
> Markdown block /*** ... ***/, allows us to apply proper Markdown (as a
> super-set of HTML). And putting the function definition between two lines of
> // // // makes that part a literal block.
> So our modified example.php is now say
>
> <?php
>
> /***
> # A nice function
>
> `tripleThis($n)` returns the three-fold of the given number `$n`.
>
> Its implementation is as follows:
> ***/
>
> // // //
> function tripleThis ($n) {
> return 3 * $n;
> }
> // // //
>
> ?>
>
> If we now run the same command
>
> php elephantmark.php example.php
>
> the output will be a HTML document
>
> <html>
> <body>
> <h1>A nice function</h1>
> <p>
> <code>tripleThis($n)</code> returns the three-fold of the given
> number <code>$n$</code>.
> </p>
> <p>
> Its implementation is as follows:
> </p>
> <pre><code>function tripleThis($n) {
> return 3 * $n;
> }
> </code></pre>
> </body>
> </html>
>
> So this is a HTML document generated from the PHP source, which is thus
> both, a PHP script and its own documentation.
> (I left away the intermediate step, that the script is first translated
> into Markdown, and that is then translated into HTML. But the normal user
> will not need this intermediate Markdown step.)
>
>
>
>> One of the weaknesses for most programming is that people postpone writing
>> the documentation.
>>
>> In one of the few programming courses I had, the instructor had us write
>> the user manual first. THEN write the top level description of the program,
>> including documenting the algorithms. ONLY then could we write the
>> program. After we had to correct the previous levels.
>
>
> This is exactly the way I personally use my ElephantMark (or PhpCodeDown)
> all the time! Both the PHP program and its HTML documentation can grow
> gradually and simultaneously, and both have the same single source file!
>
>
>>
>
> There is a lot of merit in this for anything that is too complicated to fit
>> into a single file.
>>
>> In addition this approach requires no changes to markdown.
>>
>> Codedown then only has to recognize a different commenting style for
>> whatever language you are using, which I think would make it quick to write.
>>
>
> I am not sure again, if I understand this last part. But maybe, it only
> makes sense in your interpretation.
>
>
> Thank you again, Sherwood, for your comment.
> I think, for people knowing Markdown, the CodeDown idea is all too simple:
> you just need one, two, or three syntax rules concerning the modification of
> comments in the original programming language. And just that makes it so
> universal and easy.
> But maybe, it is so simple, that it is too difficult for me to explain.
>
> Greetings,
> Thomas
>
>
>
>
>
>
>>
>>
>>
>> On Mon, Apr 11, 2011 at 10:17 AM, bucephalus org <bucephalus.org@
>> gmail.com> wrote:
>>
>>> Dear Markdown enthusiasts out there!
>>>
>>>
>>> Sure, I don't need to tell you how great an versatile Markdown is for
>>> writing standard documents.
>>> I think, that it would make a really great universal standard as a
>>> programming documentation language, too, and maybe "CodeDown" would be a
>>> good title for this approach.
>>>
>>>
>>> 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.
>>>
>>> In the past, I often used Perl'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's literal programming concept, and most standard documentation tools
>>> are not even capable of realizing that.
>>>
>>> In a first conversion step, these blocks would turn into Markdown, and in
>>> a second conversion step, the Markdown is converted to HTML.
>>>
>>> phpToMarkdown
>>> markdownToHtml
>>> PHP source code ------------------------------> Markdown
>>> --------------------------> HTML
>>>
>>>
>>> For the markdownToHtml function, I used Michel Fortin's PHP Markdown, so
>>> my actual converter is a pretty small script. I called it ElephantMark (see
>>> http://www-bucephalus-org.blogspot.com/2011/01/elephantmark.html) and
>>> the according script is its own documentation.
>>>
>>>
>>> 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
>>>
>>> haskellToMarkdown
>>> markdownToHtml
>>> Haskell source code ---------------------------------> Markdown
>>> ------------------------> HTML
>>>
>>>
>>> For the markdownToHtml part I used the very powerful Pandoc module,
>>> written by John MacFarlane.
>>> This week, I'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.
>>>
>>>
>>> During the preparations for the talk, I thought I should call the whole
>>> idea "CodeDown", including "Php(Code)Down" as the CodeDown for PHP,
>>> "PythonCodeDown" as the CodeDown for Python, etc. There could even be a
>>> general CodeDown tool, that does the conversion for all these particular
>>> languages alltogether.
>>>
>>>
>>>
>>> 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't spare on your comments, answers or questions.
>>>
>>>
>>> Greetings, Thomas
>>> (bucephalus.org)
>>>
>>>
>>> _______________________________________________
>>> Markdown-Discuss mailing list
>>> Markdown-Discuss at six.pairlist.net
>>> http://six.pairlist.net/mailman/listinfo/markdown-discuss
>>>
>>>
>>
>> _______________________________________________
>> Markdown-Discuss mailing list
>> Markdown-Discuss at six.pairlist.net
>> http://six.pairlist.net/mailman/listinfo/markdown-discuss
>>
>>
>
> _______________________________________________
> Markdown-Discuss mailing list
> Markdown-Discuss at six.pairlist.net
> http://six.pairlist.net/mailman/listinfo/markdown-discuss
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20110411/7d71d3d7/attachment.htm>
More information about the Markdown-Discuss
mailing list