Hi chromatic. Listen, I'm not trying to sell Texinfo (though I do like it pretty well), and I haven't looked closely enough at Perl6's Pod to suggest whether or not I think it's better than some other format. My original post was asking if and why this wheel is being reinvented. Evidently it is, and the leaders of the Perl community think it is justified or else they wouldn't be using TheDamian's formidable skills to work on it. But I'm still curious about the "why".

What's not bletcherous about the # @directive syntax,

If you're used to Texinfo, POD looks kinda' ugly. Same thing vice versa. Eye of the beholder and all.

What exactly is portable about "it runs on Linux and Windows users can just use HTML"?

What's portable about it is, if there's some problem building makeinfo on your platform, you could always browse the docs as html (either in a GUI or text-based html browser).

You don't know how big the Texinfo distribution is, so I assume you likewise have no informed idea about the platforms it supports!

Well, this seems to be the latest version: texinfo-4.8a.tar.bz2    26-Sep-2006 18:39    1.5M

It's standard GNU fare (./configure; make; make install), so that means it'll likely build on most Unixy platforms (including Mac OS X). Dunno about MS Windows.

It needs to be extensible, which is one of the main problems of POD in Perl 5,

Dunno what you mean here. What do you need in a doc system that's not in Texinfo? And why would it be hard to extend Texinfo?

What exactly is easy to extend about Texinfo unless the Perl 6 maintainers fork their own version and add their own features, rather than relying on upstream to make those changes?

I'd suggest that if the Perl6 maintainers needed a feature, and submitted a patch that it might get accepted. But I see your point: that could certainly be a pain in the neck. Noted. In the end, you could be stuck writing your own makeinfo_pod6.pl.

How exactly is making everyone who wants to write POD in Perl 6 learn a completely new style of syntax with a new escaping system that POD has never needed before not an arbitrary change?

Perhaps the changes being made to POD are not as substantial as I'd assumed. From a casual user's perspective, it looks like this: Perl5's POD evidently needs sprucing up (i.e. to be more compact, uniform, and expressive). Joe-user says, "well, I use <formatting/markup system X> and it's fairly compact, uniform, and expressive -- why should I take the time to learn Perl6 Pod when I could just use X?".

So, on the one hand, yes, changing from Perl5's POD to something completely different would make a hoard of folks annoyed that they have to learn a different markup to write Perl6 docs. OTOH, some other subset of users would be relieved that they no longer have to use *2* different markups (POD *and* DocBook/LaTeX/Texinfo/doxygen/whatever) depending upon what they're documenting. I'm not suggesting that the 2nd subset is larger than the hoard though.

Is Texinfo seriously an order of magnitude better than the POD 6 proposal?

I doubt it. Though, as long as we're here, consider this:

• What if you already know and use markup X (where, I'm thinking Texinfo here)? If Perl6 Pod became "just like X", now your productivity at creating docs all of a sudden just went up substantially.
• If Perl6 Pod went X, now the developers who were going to be reworking Perl5's POD tools are now freed-up and can instead spend time hacking Perl6.
• The Perl community would be doing its part to stave off the "Yet Another Doc Format" situation.

Anyway, those were just a few thoughts. I'm sure Perl6 Pod will be very nice, complete, and stable system that new users will learn and get used to when they take up Perl6. It would be nice, IMO, to instead use a system that's similar to an already-in-place standard that many folks already know, but I guess that describes Perl5's POD just as well as some of the other alternatives.