develooper Front page | perl.perl6.language | Postings from March 2005

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

Thread Previous | Thread Next
Aaron Sherman
March 17, 2005 05:31
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
On Thu, 2005-03-17 at 02:17 -0800, Brent 'Dax' Royal-Gordon wrote:
> David Storrs <> wrote:
> > Aside from links, that's pretty much the entire perlpodtut boiled down
> > into 7 bullets; a little experimentation to get the hang of it and it
> > all holds together nicely, easy to remember.
> Yes, yes, yes. Pod is one of the things Perl 5 did almost exactly right.

Absolutely, and that's why I'd like to see more POD details preserved.

> It's simple, intuitive, and stays out of your way.  It gives you most of
> the formatting primitives you actually *need*, and nicely balances the
> need for easy-to-remember and easy-to-type formatting codes with the
> need to avoid using them on accident.  It's a very clean,
> low-punctuation format, which makes it visually distinctive from the
> surrounding code.

This is the spirit in which I've absorbed some of Kwid into my proposal
only where it supports those goals. I've removed some extra formatting
characters because I thought that they added too many chances for
overlap with real documentation. I've also searched my local PODs to see
where AJS Kwid would overlap POD and cause problems (6.4% of my local
PODs, for example, start some lines with "*", which would be a minor,
but notable problem, but 13.1% start a line with "-" which is a larger
problem, thus my "*1" which could easily be "*-" if we prefer that).

> Specifically, I like the use of angle brackets in Pod.  Angle brackets
> are simple, distinctive shapes; they remain wide in variable-width

This is aesthetic preference. I could cite the reasons that I have an
aesthetic preference for the other syntax, but the reality is that angle
brackets aren't angle brackets; they are less-than (E<lt>) and greater-
than signs (E<gt>). We ignore this fact at our peril, and the hacks in
pod syntax (e.g. C<< < >>) to get around this are glaring anti-

> The most common use of them in Perl 5--method call/dereference--is
> going away in Perl 6

Hmm, I remain unconvinced of that as the most common use, especially
with the copious use of =>. Still, in my local source tree you're right,
though by < a factor of 2.

Perl 6 also adds new uses of E<gt> and E<lt> for pipelining, and further
expands the usefulness of the => operator as a pair constructor. Rules
also add new uses of these characters, but those are balanced, so
improving POD with a real grammar specification would solve for that.

> Pod needs incremental improvements--tables

Oops, forgot that one. I'll add it tonight, when I get home from work.

> (maybe) footnotes

Good point, and I'd add that to X[...] rather than introducing something
new, personally.

> simpler links, tweaks to =begin/=end, etc.

I think everything you list above is EXACTLY AJS Kwid, with one
exception, which is the dreaded paradigm shift of using [] instead of <>

Much as it may be an EMOTIONAL sticking point, it's a very minor thing.
If we can agree on everything else, and I suspect we can, then let's
come back to that.

> Pod does *not* need to be ripped
> out and replaced with something very different,

yes, yes, yes!

>  especially something
> that involves adding "line noise" to documents intended for human
> consumption.

yes, yes, yes!

Thanks Brent, I'm not sure if you intended your mail as an endorsement,
but other than one sticking point, you and I appear to be on the same
page. Thank you for your message.

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About