CodeDown = Markdown as the universal language for program documentation
bucephalus.org at gmail.com
Tue Apr 12 11:10:58 EDT 2011
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>
> > 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 , 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
> . Unfortunately, is uses reStructuredText, not Markdown. Now, if
> someone created a similar tool that used Markdown, that would be
> 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.
> : http://apydia.ematia.de/index.html
> : http://sphinx.pocoo.org/
> \X/ /-\ `/ |_ /-\ |\|
> Waylan Limberg
> Markdown-Discuss mailing list
> Markdown-Discuss at six.pairlist.net
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Markdown-Discuss