Hi Bob, hi Waylan,<div><br></div><div>There seems to be no end in good news .... I definitely need to study all that. Thank you very much!</div><div><br></div><div>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 &lt;code&gt;f(n)&lt;/code&gt;) and the indentation of tabs or four spaces turns a code block .... into &lt;pre&gt;&lt;code&gt;...&lt;/pre&gt;&lt;/code&gt;. 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.</div>
<div><br><br><div class="gmail_quote">On Tue, Apr 12, 2011 at 4:52 PM, Waylan Limberg <span dir="ltr">&lt;<a href="mailto:waylan@gmail.com">waylan@gmail.com</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">On Tue, Apr 12, 2011 at 9:04 AM, Rob McBroom &lt;<a href="mailto:mailinglist0@skurfer.com">mailinglist0@skurfer.com</a>&gt; wrote:<br>
&gt; On Apr 11, 2011, at 5:46 PM, David Chambers wrote:<br>
&gt;<br>
&gt; Check out Jeremy Ashkenas&#39;s docco. Truly beautiful.<br>
&gt;<br>
&gt; People might also be interested in appledoc, which uses Discount to parse<br>
&gt; comments.<br>
<br>
</div>There is also Apydia [1], which uses Python-Markdown (or textile or<br>
reStructuredText) on Python code.<br>
<br>
However, the really powerful documentation library in Python (also<br>
supports C/C++ with other language promised to be coming) is Sphinx<br>
[2]. Unfortunately, is uses reStructuredText, not Markdown. Now, if<br>
someone created a similar tool that used Markdown, that would be<br>
something.<br>
<br>
The great thing about Sphinx is that while is can extract comments<br>
from the source, it is primarily meant to write documentation separate<br>
from the source - which should almost always be a projects primary<br>
documentation. The automatically-generated-from-source reference<br>
should usually be in addition to the primary documentation. At least,<br>
that is if you want a well documented project.<br>
<br>
[1]: <a href="http://apydia.ematia.de/index.html" target="_blank">http://apydia.ematia.de/index.html</a><br>
[2]: <a href="http://sphinx.pocoo.org/" target="_blank">http://sphinx.pocoo.org/</a><br>
<br>
--<br>
----<br>
\X/ /-\ `/ |_ /-\ |\|<br>
<font color="#888888">Waylan Limberg<br>
</font><div><div></div><div class="h5">_______________________________________________<br>
Markdown-Discuss mailing list<br>
<a href="mailto:Markdown-Discuss@six.pairlist.net">Markdown-Discuss@six.pairlist.net</a><br>
<a href="http://six.pairlist.net/mailman/listinfo/markdown-discuss" target="_blank">http://six.pairlist.net/mailman/listinfo/markdown-discuss</a><br>
</div></div></blockquote></div><br></div>