CodeDown = Markdown as the universal language for program documentation

[bucephalus org]

Hi Bob, hi Waylan,

There seems to be no end in good news .... I definitely need to study all
that. Thank you very much!

What I like in Markdown, compare to other lightweight-markups and in this
context of program documentation, is the two little, but very useful
features: backticks around a phrase turn it into code (i.e. `f(n)` turns
into <code>f(n)</code>) and the indentation of tabs or four spaces turns a
code block .... into <pre><code>...</pre></code>. This is probably the most
convenient markup for inline and block code, one can imagine. Even more
natural than the LaTeX $...$ for inline and $$...$$ for block code.


On Tue, Apr 12, 2011 at 4:52 PM, Waylan Limberg <waylan at gmail.com> wrote:


> On Tue, Apr 12, 2011 at 9:04 AM, Rob McBroom <mailinglist0 at skurfer.com>

> wrote:

> > On Apr 11, 2011, at 5:46 PM, David Chambers wrote:

> >

> > Check out Jeremy Ashkenas's docco. Truly beautiful.

> >

> > People might also be interested in appledoc, which uses Discount to parse

> > comments.

>

> There is also Apydia [1], which uses Python-Markdown (or textile or

> reStructuredText) on Python code.

>

> However, the really powerful documentation library in Python (also

> supports C/C++ with other language promised to be coming) is Sphinx

> [2]. Unfortunately, is uses reStructuredText, not Markdown. Now, if

> someone created a similar tool that used Markdown, that would be

> something.

>

> The great thing about Sphinx is that while is can extract comments

> from the source, it is primarily meant to write documentation separate

> from the source - which should almost always be a projects primary

> documentation. The automatically-generated-from-source reference

> should usually be in addition to the primary documentation. At least,

> that is if you want a well documented project.

>

> [1]: http://apydia.ematia.de/index.html

> [2]: http://sphinx.pocoo.org/

>

> --

> ----

> \X/ /-\ `/ |_ /-\ |\|

> Waylan Limberg

> _______________________________________________

> 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/20110412/c329a58d/attachment-0001.html>