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
