Re: The eternal "use XXX instead of POD" debate (was: Project Start: ?Section 1)

On Mon, Nov 11, 2002 at 03:50:34PM -0800, Damien Neil wrote:
> POD parsers also go to a fair amount of trouble to infer syntax.  For
> example, a function name like this() will be rendered differently by
> many POD processors.  This is a good thing, in that you don't have to
> litter your documentation with a lot of C<> directives.  This is a bad
> thing, in that there aren't any formal rules on what patterns parsers
> will match, so you're never quite certain what your document will end
> up looking like.

This is a common complaint about Pod.  The main problem is with the
multiple Pod processors that use different inference rules.

> I'd love to see a cleaner POD, with tables, better support for lists,
> and the ability to turn syntax inferencing on a per-document basis.
> Unfortunately, I don't think SDF is it.

I *think* we're almost there.  Sean Burke has been working on revamping
Pod from the ground up for a few months now.  He started with a clear
spec on what should be inferred where and when (perlpodspec) and a
series of modules and tools that obey those rules (Pod::SAX and his
recent rewrite of pod2man and such).

I haven't been keeping up with his efforts, but was among the many
who mentioned the need to have "extensions" to Pod a few months
ago.  I believe that Sean and others are chomping on that nut at
the moment.

> I'd be happy to join in a discussion of how to make a better POD.

Check out [email protected].

Z.