Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

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 "" 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".)

In reply to Perl6 Pod -- reinventing the wheel? by j3

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others wandering the Monastery: (3)
    As of 2020-11-27 03:23 GMT
    Find Nodes?
      Voting Booth?

      No recent polls found