So, why is this particular wheel being reinvented?

There's already a perfectly good documentation format for Perl that has a much less bletcherous syntax. It's POD.

Now POD has its flaws, as anyone who's ever written a book in it will argue (and several of the people who've done so are actually on the Perl 6 design team), but it's also fairly nice in what it does include and how it does it.

More than that, whatever the document format of Perl 6, it must be portable to all of the systems where Perl 6 runs (and saying "every flavor of GNU/Linux that I've come across" doesn't really impress me with portability). It must be lightweight enough that it can be part of the core distribution. It should be sufficiently advanced over POD in Perl 5 to make up for any differences in syntax. It should fix as many of the warts of POD in Perl 5 as possible. It ought to be similar to POD in Perl 5 where possible, as change for the sake of arbitrary change is a lousy design goal. It needs to be extensible, which is one of the main problems of POD in Perl 5, and it should allow better reuse and introspection and customization than Perl 5's POD.

It's also very nice to control the document formatter used for the core documentation rather than relying on upstream to review patches and release new versions.

In reply to Re: Perl 6 Pod -- reinventing the wheel? by chromatic
in thread Perl6 Pod -- reinventing the wheel? by j3

Title:
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, details, 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, summary, 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.