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

  * 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.


Reply via email to