Re: RFC 357 (v1) Perl should use XML for documentation instead of POD

[Peter Buckingham]

Philip Newton wrote:
> On 4 Oct 2000, at 14:06, John Porter wrote:
> 
> > I am of the opinion that any documentation which requires, or at least
> > would significantly benefit from, the use of something heavy like SGML
> > is best done OUTSIDE THE CODE.  There's no reason you can't have
> > document files accompanying the perl code files, for gosh sakes.
> 
> I disagree slightly. One of the benefits of Pod is that it can be
> intermingled with Perl code; [snip]

why not just use a literate programming tool like noweb? this allows you to
document right next to your code. it allows you (currently) to use latex or html
(might be simple to extend to sgml and xml). it allows you to rearrange your
code in a more explainable order.

Mark-Jason Dominus wrote an article on perl.com explaining why pod is not a
literate programming tool. people seem to want a super-funky documentation tool.
they _already_ exist, and there is no reason to change perl, let someone else do
the dirty work.

peter

-- 
        I'm free to speak my mind anywhere
        And I'll never mind anywhere
        Anywhere I roam
        Where I lay my head is home  -- "Wherever I May Roam" Metallica