http://www.perlmonks.org?node_id=585945

I noticed that Damian recently posted a draft of Synopsis 26 (Perl6 Pod) to perl.perl6.language. It looks like a great deal of effort has been put into making POD into a more general and complete doc format. But I'm left wondering, is a very large wheel being reinvented here?

It looks as if there are already numerous doc formatting markups available that could fairly easily be used in place of POD if a more complete doc format is wanted. The one that immediately jumps out at me is Texinfo.

I won't enumerate every feature of Texinfo here, but suffice it to say that it seems to have most every feature you'd want for this sort of job (generates multiple output formats, is indexable, searchable, and so on). Furthermore, it would be trivial to incorporate it into perl code. For example, maybe have "POTD" ("Plain Old Texinfo Docs") start with '#@' instead of '#'. For example:

#!/usr/bin/perl use strict; use warnings; #@ @node A few good subs #@ @chapter A few good subs #@ #@ This is a line of POTD. This module contains #@ some functions and might be used as follows: #@ @verbatim #@ do_something(); # Magic happens here! #@ @end verbatim #@ # ------------------ # Subroutines # ------------------ #@ @node do_something #@ @section do_something #@ #@ You'd use this @emph{awesome} function for: #@ #@ @itemize #@ @item #@ When you want to do foo. #@ #@ @item #@ When you want to do bar, since foo obviously #@ isn't cutting it. #@ @end itemize sub do_something { print "Magic goes here.\n"; } print "hi.\n"; do_something; print "bye!\n";

Then a "potd2whatever.pl" tool could simply start off as something like:

#!/usr/bin/perl use warnings; use strict; my @lines = (); while ( <> ) { if (/^#@/) { s/^#@[ \t]*//; push @lines, $_; } } my $lines = join '', @lines; # Now pipe $lines through any one of: # - texi2dvi # - texi2pdf # - makeinfo

Some more observations:

  • The Texinfo licensing is compatible with Perl.
  • Texinfo is a very mature and stable tool (and also happens to be the standard and official GNU tool for the job).
  • Texinfo -- like Perl itself -- comes with (or at least is available for) every flavor of GNU/Linux that I've come across.
  • It's fairly pleasant to type.
  • You can even put mathematics into texi docs, which I think is a big plus.

Seems like the Perl + Texinfo would go together like peanut butter and jelly. So, why is this particular wheel being reinvented?

(Edit: Fixed the above code to remove the '#@' from the beginning of each line.)

(Edit: Corrected spelling of "Damian".)