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
Brian Ingerson
March 16, 2005 13:42
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
On 16/03/05 14:33 -0500, Aaron Sherman wrote:
> On Wed, 2005-03-16 at 14:17, Brian Ingerson wrote:
> > Kwid does this by formally changing
> >  
> >    X<...>
> > 
> > into
> > 
> >    {X...X}
> Ok, where is THAT proposal?! I'm reading the doc that's in
> doc/perlkwid.kwid in the pugs source tree. Hmmm... odd, I just did an
> update and it's GONE now... was I looking at some phantom doc that had
> an old spec for Kwid?!

Sorry, it has been moved around the pugs source tree a bit. It is
currently swinging from the documentation branch:


> > Where `X` is any Pod code like `B`, `I` or `C`. Since there are only 3
> > codes in common use (ignore `L` for a second), Kwid thus uses {*bold*}
> > {/italic/} and {`code`}.

FYI, it turns out that at least one modern format,
[Markdown|], uses
backticks for code. Markdown doesn't really map to the Pod space very
well, but it has a few gems...

> Well, I'm personally not fond of the bare-bracketting with {}, but as
> long as it's not a stand-alone /italic/ like it was in the original doc,
> that sounds fine. Why {/foo/} is more readable than I[foo], I'm not
> sure... but I'll try to take your word for it.

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:

    {/foo \/} bar/}
    {{/foo /} bar/}}
    {/foo { /} } bar/}

Those are 3 possible ways to make I<foo /} bar>. Note that '{ ' and ' }'
are the "asis" or "leave me alone" indicators. But the real point is
that '/}' is rather unlikely to ever show up in italics outside this
> > For L<...>, I decided to use the very common wiki idiom of [...] for a
> > link. Everything in the `...` is the same as Pod.
> There, I think you're making a small mistake, but not a huge one. I'd
> separate out magical wiki-like [foo] from pedantic, pod-like L[foo] so
> that you can get either one. Wiki's [foo] is like a URN, where POD's
> L[foo] is more in tune with a relative URL.

So I will give a little extra info on this...

The idea is to DWIM and there is a lot you can do with the `[...|.../...]`
syntax. Pod's strict syntax is:


/Text/ is obviously the text that should render. /Resource/ can be a
local manpage (ie another Pod document) and then /section/ is a section
in that doc. If /resource/ is empty, the current document is assumed.

/Resource/ can also be a fully qualified url and in that case section
does not apply.

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).

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

> > > While I appreciate several features of Kwid, I feel that it should not
> > > replace POD without first adopting a POD-like simplicity.
> > > 
> > >         Some people have argued that Kwid is only a syntactic change to
> > >         Pod. I would argue that they are correct.
> > > 
> > > They are demonstrably wrong. You cannot Parse Kwid correctly by changing
> > > the syntax of a POD parser.
> > The behaviour of this is completely consistent. You may need to reread the 
> > perlkwid document for it has recently changed.
> Apparently.
> > ie
> > 
> >     * foo
> >     bar
> >     * baz
> >     boom
> >     
> > matches
> > 
> >     * foo bar
> >     * baz boom
> > 
> > matches
> > 
> >     .list
> >     * foo bar
> >     * baz boom
> >     .list.
> Hrm...
> How, then do you differentiate:
>       * Bullet list.
>       1. Numbered list.
>       Other
>               Term/definition lists
> ? In POD, that would be:
>       =item *
>       Bullet list
>       =item 1
>       Numbered list.
>       =item Other
>       Term/definition lists

This makes no sense in html and perlpod says:

   *   And perhaps most importantly, keep the items consistent: either
       use "=item *" for all of them, to produce bullets; or use
       "=item 1.", "=item 2.", etc., to produce numbered lists; or use
       "=item foo", "=item bar", etc. -- namely, things that look
       nothing like bullets or numbers.

In Kwid, therefore, this:

    * Bullet list.
    + Numbered list.
    - Other
    Term/definition lists

would produce 3 single item lists. You can obviously switch types in sublists:

    * Bullet list.
    ++ Numbered list.
    * another bullet
    -- Other
    Term/definition lists

> > I would encourage those interested in further fleshing out Kwid to join
> > irc:// where all of this is actively being
> > discussed.
> 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:


is ignored by the interpreter. This turns out to be the case with both
`perl` (Perl 5) and `pugs`. I am fine with some mailing list discussion
but I would rather spend the cycles on a reference implementation that
could be easily modified later.

Cheers, Brian

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