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 14:30
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
On Thu, 2005-03-17 at 17:07, Brent 'Dax' Royal-Gordon wrote:
> Aaron Sherman <> wrote:

> > and the hacks in
> > pod syntax (e.g. C<< < >>) to get around this are glaring anti-
> > huffmanisms.
> Whatever bracketing character we decide to use, there will always be
> occasions where we need to use it in an unbalanced way within a
> formatting code.

Absolutely yes. See C[...] vs C{...} vs C[\]]

I'm pointing out that the ROUTINE case is to need < and > in unbalanced
ways. Hence we have names for them that to not involve the words "open",
"close", "left" or "right". We could name "[", "fobit", but then people
would automatically call "]" a "right-fobit" or a "close-fobit". We look
at a piece of code or documentation that contains an un-balanced fobit
and we get a little chill because it's WRONG somehow. THAT is the kind
of balanced operator you want to tie your documentation to.

> > > 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.
> Are you looking at your entire source tree, or just the Pod in it? 
> The code in Pod--and especially the short snippets of code typically
> included in a C<> construct--is very different from arbitrary Perl
> code.

I EXPLICITLY ignored POD. I don't have the find+perl that I used handy
any more, but I was counting state every time I saw an "^=[hoib]" and
decrementing state every time I saw an "^=cut" so that I only counted
code... I probably caught some strange gunk after __END__ and __DATA__
tags, but not enough to throw the stats that far off.

It was 23k vs. 44k.

> > 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.
> I definitely support intelligently defining the way Pod handles angle
> brackets which aren't part of a formatting code.  I also think writing
> a reference grammar would be an excellent idea.

Already done, see my previous message. It's still brain-dead in some
places, and I need to re-work it to correctly handle nested operations
(e.g. B[I[...]]), but I'll have that soon. It will also, I've decided,
parse POD. Just as Perl 6 parses Perl 5 by recognizing the first few
statements, AJS Kwid will recognize "=head.*" as an indication that POD
is being used, and parse it into KwidData internally so that the same
tools could be used.

I'm stopping once it works. I'm not looking to fork POD. If people don't
like the proposal, once they can play around with it, then I'll drop it.

Aaron Sherman <>
Senior Systems Engineer and Toolsmith
"It's the sound of a satellite saying, 'get me down!'" -Shriekback

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