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 16, 2005 21:49
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
On Wed, 2005-03-16 at 13:42 -0800, Brian Ingerson wrote:

First off, thanks for your kind responses. I'm sure I just got confused
by some web page I was looking at, and overwrote part of my stack that
I'd just populated from the Kwid doc. And thanks also for pointing me to
the Kwid docs  where they live now.

> In short you don't need to worry about I[[ $foo[3] ]]. Since the ending
> marker is '/}', you only ever need to worry about escaping anything but
> '/}' itself. I might as well show how that would be done:

We're suffering a major disconnect over the nature of bracketting.

I see no reason to I[[ $foo[3] ]] at all.

That would simply be I[$foo[3]] ... we are using a real parser here, no?
I can't imagine basing this on some pile of regexps, and we all have
"matched the balanced brackets" tools at our disposal, regardless of
what parser / parser-generator we're using these days.

Here's a simple Parse::RecDescent grammar for my proposal, so that we
can talk about it in more reasonable terms. Please note that I'm
TERRIBLE with P::RD, so I'm sure someone can figure out why I keep
ending up with the string "text_chunk" in my resulting syntax tree ;-)

See attached program and sample input. Just run on

> For some reason Pod does not allow L<text|url> but there seems to be no
> obvious reason. (This is the the only major thing where Kwid strays from
> Pod's info model).

That's not POD's info model, that's POD's implementation limitation.

> I am not certain what use case `L[...]` could get you that isn't already
> covered by `[...]`.

I'm very happy with the modern Wiki convention (keep in mind, when we
talk about Wiki, we're talking about something that's either nearly as
old as or older than the Web, depending on what you count as it's birth)
of using [...] as a sort of magical indexer. Like I said elsewhere, you
might have:

  [Kwid] in your document.

This is a hint that you expect there to be a thing named "Kwid"
somewhere and you wish that somewhere to be applied thusly:

  L[Kwid|somewhere] in your document.

Where L[Kwid] would simply fail because it is as strict as POD, and it
won't find L[Kwid|perlkwid].

Other examples of this DWIMery:

  [] => L[|]
  [;-)] => 
	=for html <img src="winksmily.png" alt=";-)" />
	=for !html ;-)

> > How, then do you differentiate:
> > 
> >       * Bullet list.
> >       1. Numbered list.
> >       Other
> >               Term/definition lists
> In Kwid, therefore, this:
>     * Bullet list.
>     + Numbered list.
>     - Other
>     Term/definition lists

That was the answer I was looking for, thanks.

I'm not thrilled with it (again, too many special characters that people
might have thought they could get away with using in their
documentation), but it's not too bad at all.

> > Sorry, no access to IRC at work. If the specification of core pieces of
> > P6 are being done off-list, why is there a list?
> Honestly this project was started as an /experiment/ and was not
> intended to distract p6l. Kwid requires no extra input from the language
> side as long as:
>     =kwid
>     ...
>     =cut

Well, look over AJS Kwid, and see what you think. The bullet syntax you
give could work fine as a replacement for what I demonstrate, but I
think everything else is pretty much 1:1. Now it's just a matter of: do
you make it Wikiish or PODish?

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