On 16/03/05 12:00 -0500, Aaron Sherman wrote:
> On Tue, 2005-03-15 at 13:48, Brian Ingerson wrote:
> > Aaron,
> >
> > Upon reading this, it is unclear to me whether you have read about the
> > Kwid format or you are simply guessing that Kwid is the same syntax
> > used by Kwiki.
>
> I read the Kwid documentation from the Pugs distribution in depth.
>
> To create Kwid I carefully studied the POD information model
> (the semantic tree that POD parses to). Kwid uses the exact same
> info model. This means that switching between the two without
> loss of information is possible.
>
> I noted that in my original message.
>
> This makes the Kwid experiment much less risky
>
> Risk was not my concern. My concern was a Wiki-like model which is
> inconsistent with many of the goals of POD. POD is intended to be PLAIN
> OLD documentation.
I think consistency with "goals" is fine, but consistency with the "data
model" is more important. POD has a very nice data model that maps well
to other formats. It is really well done. So logic stands that any
format which can map cleanly to POD and yet offer an advantages to the
author is a benefit to the author without needing to retool the
extensions. Further any dialect can be converted to any other without
information or structure loss.
POD's syntax is certainly good enough, but doesn't match the way that
people commonly write structured prose; especially in this era of text
based formatting such as in wikis. POD's syntax /elegance/ also tends to
break down into workarounds too fast in edge cases.
NOTE: POD does have some minor warts in the data model, but they can be
fixed later on.
> Kwid breaks this model of simplicity by introducing unique boundary
> characters for many types of operations, and by making the overall
> presentation more complex.
Let's look at an example and explore the rationale:
Pod uses this syntax B<bold stuff> which is fine, but it is a very
common idiom to use *bold stuff* outside of Pod. Usenet posts, email,
irc, etc. People use this, they grok it, and lots of tools grok it as
well. (I'm thinking irc clients as an example).
So how do we get *there* formally and avoid making a mess where * is
just supposed to be an asterisk?
Kwid does this by formally changing
X<...>
into
{X...X}
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`}.
This has a subtle but significant advantage over X<...>. The difference
is that instead of the ending marker being '>' it is 'X}', which is
orders of magnitude less likely to show up in the content being escaped.
This means you avoid the X<< ... >> mess almost entirely.
But the better part of this is that the Kwid forms can be relaxed to
drop the curlies in most cases. This technique uses the principle of
"hugging". So you can say *$a = $b * $c* and get the bolded equation
since the middle * isn't hugging anything. Hugging is a nontrivial
heuristic, but let's just say it Does The Right Thing. And if you aren't
sure just say {*$a = $b * $c*}. ie, just add some curlies to what you
already have.
*Bold* and /italics/ are rather obvious, intuitive and commonly used.
Backticks for `code` was chosen because backticks are rarely used in
code. Except of course when writing about Kwid itself. But to get
C<`code`> you just go to the curlies: {``code``}. Simple. Backticks also
seem to be right visually, but that's just my opinion.
For L<...>, I decided to use the very common wiki idiom of [...] for a
link. Everything in the `...` is the same as Pod.
I is purely subjective whether Kwid's overall presentation is more or
less complex than Pod's. Kwid attempts to elegantly move towards the
modern internet era of social software, with the hope that those
participating in those arenas might feel more at home.
> 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.
>
> For example, the behavior of
>
> * foo
> bar
The behaviour of this is completely consistent. You may need to reread the
perlkwid document for it has recently changed.
ie
* foo
bar
* baz
boom
matches
* foo bar
* baz boom
matches
.list
* foo bar
* baz boom
.list.
The explicit `.list` is only needed when the parser cannot guess from
the context.
...
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.
Cheers, Brian
