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 <[email protected]> wrote: > Hi Sherwood, > > Thank you very much for your interest and reply! > > On Mon, Apr 11, 2011 at 9:05 PM, Sherwood Botsford > <[email protected]>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 >>> [email protected] >>> http://six.pairlist.net/mailman/listinfo/markdown-discuss >>> >>> >> >> _______________________________________________ >> Markdown-Discuss mailing list >> [email protected] >> http://six.pairlist.net/mailman/listinfo/markdown-discuss >> >> > > _______________________________________________ > Markdown-Discuss mailing list > [email protected] > http://six.pairlist.net/mailman/listinfo/markdown-discuss > >
_______________________________________________ Markdown-Discuss mailing list [email protected] http://six.pairlist.net/mailman/listinfo/markdown-discuss
