Front page | perl.perl5.porters |
Postings from August 2001
perlpod and perlpodspec
From: Sean M. Burke
August 11, 2001 03:34
perlpod and perlpodspec
Message ID: email@example.com
(CC any replies to firstname.lastname@example.org too; sorry if this is a repost.)
Over the past several years, I have heard nothing but griping from all
quarters about the perpetually underspecified state of perlpod, when
considered as a pod specification.
A markup language without a clear specification simply invites everyone,
including implementors, to have their own shaky idea of what the language
means. And that, along with the general tendency for markup language
parsing to produce write-only code, explains much of the upsetting current
state of Pod::* modules.
I started modifying perlpod to make it at least most of what I'd want in a
real specification, ended up rewriting practically every line, and then
adding more, and more, and more, until it became clear that I should cut it
into two documents: a rewritten perlpod (a reference to POD, suitable for
most authors), and a new document I call perlpodspec, which includes notes
toward a specification, as well as my ideas about what should be expected
of POD parsers and formatters. (Contrary to first glance, perlpodspec is
basically more about "I bet you didn't think of this case..." than about
dictates of "Thou shalt..." and "Thou shalt not...".)
A prime goal of mine has been, wherever possible, to /not/ introduce /any/
radically new features. There are a very few very minor innovations to
existing features (mostly along lines that I consider to be either
necessary or inevitable). But these draft documents of mine are basically
general clarification and describing what I consider to be best current
practice of current parsers and renderers.
I look forward to real advances in future pod (and Pod::*), but I think
that first, we absolutely must nail down what pod is /now/.
Lest this fall into the usual mire of total unproductiveness that threatens
all pod discussion, I will welcome comments on these documents for at most
two weeks, and then I will emit an amended version of each document,
submitted for inclusion in future versions of Perl 5.
Rest assured -- there's something in these documents for everyone to hate!
That's what makes it a specification!
Sean M. Burke email@example.com http://www.spinn.net/~sburke/