Markdown Discuss - Apr 2011 - CodeDown = Markdown as the universal language for program documentation

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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://six.pairlist.net/pipermail/markdown-discuss/attachments/20110411/f8a1fcbd/attachment.html>

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

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.

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.





Respectfully,

Sherwood of Sherwood's Forests

Sherwood Botsford
Sherwood's Forests --  http://Sherwoods-Forests.com
780-848-2548
50042 Range Rd 31
Warburg, Alberta T0C 2T0




On Mon, Apr 11, 2011 at 10:17 AM, bucephalus org
<bucephalus.org at 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://six.pairlist.net/pipermail/markdown-discuss/attachments/20110411/4151330c/attachment.html>

Hello.

I just must say that I have tried Fletcher Penneys version of multi markdown
recently.
The 3.x version seems to me to be very suitable for the task of converting to
LaTeX,
which is slightly more complicated than converting to HTML. 
I have tried pandoc, but I find it far more easier to work with multimarkdown.

You should consider trying it.

Tommy

Den 11. apr. 2011 kl. 18.17 skrev bucephalus org:
> 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
Best regards



Tommy Bollman
--------------------------------------------------------------------------------------------------
Mollison's Bureaucracy Hypothesis:
	If an idea can survive a bureaucratic review
	and be implemented it wasn't worth doing.