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

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

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

Thread Previous | Thread Next

From:

Brian Ingerson

Date:

March 16, 2005 13:42

Subject:

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

Message ID:

20050316214242.GA22268@ttul.org

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:

    ext/Pugs-Documentation/perlkwid.kwid

> > 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|http://daringfireball.net/projects/markdown/syntax], 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
discussion.

> > 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:

    L<text|resource/"section">

/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://irc.freenode.net/#kwid 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:

    =kwid
    ...
    =cut

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