On Wed, Feb 10, 2010 at 8:50 AM, Mark Overmeer <m...@overmeer.net> wrote: > * John Gabriele (jmg3...@gmail.com) [100209 14:31]: >> [Markdown]: http://daringfireball.net/projects/markdown/ >> [Pandoc]: http://johnmacfarlane.net/pandoc/ >> [reST]: http://docutils.sourceforge.net/rst.html > > Or, more Perl like: > [OODoc] http://perl.overmeer.net/oodoc/ > http://perl.overmeer.net/oodoc/html/jump.cgi?OODoc_Parser_Markov&62
It's interesting to me that language implementations very often have their own NIH doc markup formats. For example: * Perl 5: POD * Perl 6: Pod * Python: reST * Ruby: rdoc * PLT Scheme: Scribble * Java: Javadoc I think Haskell may have something that their Haddock program uses. Also, IIRC, C and C++ users often use doxygen (though I realize that tool can be use with other languages as well). I used to wonder why these languages just don't use some generally accepted generic standard, such as LaTeX, Texinfo, or Docbook, or maybe even the MoinMoin wiki syntax (which is fairly common among wikis). After having used almost all of those tools, what I found was that: * it's tiresome to have to re-learn each different format if going back to edit old docs (or other people's docs) * it's a bother to have to set up my editor for every different format (and syntax highlighting doesn't always work right) * I tended to always come back to the simplest (and prettiest) thing that worked (Pandoc's Markdown) * I often ended up looking at my docs in `less` instead of taking the time to convert them to some other format for better viewing * many forums and blogs already use Markdown, most people already know it, many often use it without even knowing it Also though, interesting aside: Parrot is already at v2.0.0. It supports many languages. It's possible that someone might want to contribute docs to more than one of its hosted language implementations, so, using a common doc format might be desirable. Parrot also is often thought of as being very Perl-centric. Having it's biggest most sophisticated project use a common simple doc format might help shed that perception. ---John
