Re: Gripes about Pod6 (S26)
Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ My plan is to keep writing my own various docs in Pandoc Markdown (regardless of what programming language I'm working in at the moment), and if I *really* need POD5 or POD6, just use Pandoc to convert them to html, and then find a module on the CPAN to convert the resulting html to POD5 or POD6 (Pandoc doesn't currently convert directly to either Pod). I encourage others to do the same. It's funny; the Python folks left their previous doc format (LaTeX), and went (IMO) in the right direction, but ended up going with the less attractive [reST] rather than Markdown. [reST]: http://docutils.sourceforge.net/rst.html ---John
Re: Gripes about Pod6 (S26)
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_Markov62 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
Re: Gripes about Pod6 (S26)
On Tue, Feb 9, 2010 at 9:31 AM, John Gabriele jmg3...@gmail.com wrote:
Personally, I've always thought that Perl has a very natural feel to
{snip}
Gah. Sorry for the quasi-double-post. I posted on google groups, it
didn't show up, then I jumped the gun and posted a similar message to
the ML.
---John
Re: Gripes about Pod6 (S26)
Personally, I've always thought that Perl has a very natural and
well-worn feel to it, and deserves a doc markup format that also feels
natural. What works very well for me is [Markdown] (and [Pandoc]'s
Markdown has mostly just the right additions, IMO).
[Markdown]: http://daringfireball.net/projects/markdown/
[Pandoc]: http://johnmacfarlane.net/pandoc/
(Note: Pandoc is written in Haskell. For anyone who's interested, I
put up some quick notes on installing Haskell + Pandoc specifically
onto Ubuntu 9.04 at
http://unexpected-vortices.com/docs/doc-notes/installing-pandoc.html.)
My own plan is to keep writing my docs in Pandoc Markdown (regardless
of what language I'm working in at the moment), and if I *really* need
POD or Pod, I'll just use Pandoc to convert them to some intermediate
format, and then find a module on the CPAN to convert *that* to POD or
Pod. I encourage others to do the same.
Further, for API-style docs, I've been experimenting with extracting
specifically-marked markdown-formatted code comments and then passing
them through pandoc. For example, maybe something like this:
#
# forage
# --
#
# This function will hunt around for any
# nuts that may or may not be present on
# the system.
#
# *Warning:* Not compatible with most
# squirrel-related modules.
#
# Args:
#
# * search-radius: default is 5 meters
# * default behaviour if confronted by cat ...
#
#
sub forage {
# ...
}
It's funny; the Python folks left their previous doc format (LaTeX),
and went in the right direction (IMO), but ended up going with the
less attractive [reST], rather than Markdown.
[reST]: http://docutils.sourceforge.net/rst.html
---John
