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. Kwid breaks this model of simplicity by introducing
unique boundary characters for many types of operations, and by making
the overall presentation more complex.
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
Is totally dependent on what context it is enclosed in (.list or
top-level). This cannot be emulated with simple syntactic changes to a
POD parser.
Interestingly, this is one of the main benefits of Kwid, IMHO.
Re-read what I wrote and think about it. I think you'll find that it
avoids some of the major pitfalls of old-POD and incorporates all of the
useful features of Kwid while maintaining a simplicity that is as
elegant as POD's.
POD 1:1 mappings:
POD My Kwid Proposal
x<...> x[...] or x{...} (where x is C, B, I, X, L, etc)
=item * *
=item foo *= foo
=item n *1
=for someformat =for someformat
=over n =begin list
The one obvious thing to POD users is the replacement of <> with [] or
{}. Why is this? Because < and > are used in un-balanced ways in a large
number of situations, so they should not be the primary bracketing
constructs. Also because the visual cue to many users of POD is that
it's SGML-like, and that way lies danger, since POD's <>-bracketed
constructs are not intended to be balanced.
Also, there should be a "=begin block" which in HTML would be
<blockquote>, and in POD would be "=over n".
Kwid 1:1 mappings:
Kwid My Kwid Proposal
* *
.list =begin list ... =end list
.someformat =begin someformat ... =end someformat
.comment =begin comment ... =end comment
[generic] [generic]
Extensions I proposed:
=begin x,y,z Section used only in the given formats
=begin !x,y,z Section NOT used in the given formats
As you can see, what I proposed IS a simple syntactic transformation of
Kwid.
--
Aaron Sherman <[EMAIL PROTECTED]>
Senior Systems Engineer and Toolsmith
"It's the sound of a satellite saying, 'get me down!'" -Shriekback
