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.
It is not the same format at all. Kwid is merely /inspired/ by Kwiki, which in turn is inspired by the (more usenix) features of modern wiki languages. It is more fair to say that Kwid is much more inspired by Pod than Kwiki. Please read what is considered to be the de facto spec: http://svn.openfoundry.org/pugs/ext/Pugs-Documentation/perlkwid.kwid carefully and recomment. A few notes. 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. This makes the Kwid experiment much less risky, since it will be trivial to convert in either direction. As to the syntax, care has been taken to ensure that all the corner cases are covered. And also covered elegantly. Some people have argued that Kwid is only a syntactic change to Pod. I would argue that they are correct. :) But this does not mean it is not an important change. Kwid has an emphasis on minimizing the markup, and using the markup one might use to discuss programming in everyday email. This is hard to do in POD, but very easy to do in Kwid. Thus a bug win. It is also wrong to imply that important semantic changes cannot be made in the future. Things like introspection and transclusion. But that is not the current concern. In reality, Kwid does vary ever so slightly in semantics from POD. But only in cases where POD seemed to have a wart. For instance Kwid allows named hyperlinks: [The Pugs Source|http://svn.openfoundry.org/pugs]. Cheers, Brian On 15/03/05 11:46 -0500, Aaron Sherman wrote: > Wherein I propose (to the wrong list, sigh) a re-envisioning of Kwid in > a more POD-like form. > > I did leave out some POD markup forms. Assume that, if I did not mention > them, then I think they should keep the same prefix character (e.g. X<>) > Content-Description: Forwarded message - Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT) > From: Aaron Sherman <[EMAIL PROTECTED]> > Date: Tue, 15 Mar 2005 11:43:39 -0500 > To: Stevan Little <[EMAIL PROTECTED]> > Cc: perl6-compiler@perl.org > Subject: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT) > X-Mailer: Ximian Evolution 1.4.6 (1.4.6-2) > > On Tue, 2005-03-15 at 09:37, Stevan Little wrote: > > On Mar 15, 2005, at 12:54 AM, Nigel Hamilton wrote: > > > > There is a need for a higher level 'structural' documentation that > > > hypertext is well suited to cover - something that spans more than one > > > module. This will be especially important for CPan6 and connecting > > > versions, and modules into bigger 'packages'. > > > > Agreed as well. It would be nice if CPAN6 or CP6AN or FreePAN (or > > whatever it will eventually be called) have a more sophisticated > > linking/documentation system which goes beyond the actual single > > module. I even think this would be possible in the current CPAN if we > > could get the L<> construct fixed, but that is another issue. > > Actually, I don't think that's at all another issue. It's the core of > what you're talking about. L<> gives you the ability to link, and in > several different ways. It's also broken in Perl 5, which makes a > replacement sound attractive, but fixing it solves for much of that > need. > > Taking a cue from the wiki world makes sense to me. Kwid is almost ideal > as far as I can tell in that it: > > a) Does everything POD does > b) Is backward compatible with Perl 5 in that it can be ignored by the > parser in the same way. > c) Makes many things easier > > Now, it does need some tweaking, I think, but nothing too severe. It > just makes a few things harder, and a few other things non-POD-like for > no particular reason. I like C<POD> for the ease of including keywords > in C<perl> documentation. It's also B<trivial> to I<recognize> all > markup quickly (visually or programmaticly). > > Kwid /on the other hand/ makes it a bit harder to [=find] that markup, > and is *thus* not quite as easy to de-parse visually. > > I'd be thrilled if we just changed the "."-introduced things to > "="-introduced things: > > = heading level 1 > == heading level 2 > =begin list > * You don't really need the begin > * But it doesn't hurt > * and it allows > some(code()) > to appear inside a list item. > * Hmmm > =end list > > And then replaced [...] and [=...] and /.../ and *...* with their more > POD-like: L[...], C[...], I[...] and B[...] with a bare [foo] working as > a "I have no idea what I'm linking to, but do the right thing" sort of > wikiness, where L[...] is a more structured, POD-like link. For example: > > = Proposed Kwid Changes > == Introduction > It is my I[goal] to introduce an easier to use (for [POD] users) > version of [Kwid], and impose it B[mercilessly] on the heathen > masses! > > Markup can consist of C[[]]-delimited text such as C[[Kwid]] or > a prefixed C[[]]-delimited text such as C[C[Kwid]]. Possible > prefixes are: > =begin list > *= L > A structured link ala POD C[L<>] > *= B, I > Bold or italics > *= C > Code > =end list > Anywhere a C[[]] can be used, a C[{}] can also be used. This is > useful when you need to enclose unbalanced C[{], C[}], C{[}, > or C{]} characters. > > All formatting is introduced with C[=for] just as in POD, so: > > =for html <hr /> > > works as you might expect. C[=begin] is similar, but introduces > a block, ended by C[=end] > > =for html,xhtml,xml <img src="foo.png" alt="A foo!" /> > =begin !html,xhtml,xml > You can't see the image, but it would be pretty! > =end !html,xhtml,xml > > Notice the use of C[!format[,format...]] to indicate all formats > not listed. > > "comment" is the null format, so you can always introduce a > C[=for comment] or C[=begin comment], but lines which start with > C[#] are always treated as comments anyway. > > Lists are introduced with C[=begin list], which is a special > format. A list can be numbered, bulletted or defintion-style. > Each type is introduced differently, e.g.: > > *1 numbered > * bullets > *= term > definition > > Only a C[1] can follow the C[*]. So, your numbered list would > look like: > > *1 First > *1 Second > *1 Third > > This tells Kwid to number your items, but does not allow strange > things like: > > *2 First prime > *3 Second prime > *5 Third prime > > For that, you need C[*=] > > Thoughts? > > > Well, not everyone likes HTML (although I can't imagine why). > > * It's hard for humans to read > * It imposes too much display-think on what should be content-think > * It is not a proper super-set of the other documentation formats. > > XHTML addresses some of this, but still provides far too much > display-oriented power for a high-level markup like POD or Kwid. > > -- > Aaron Sherman <[EMAIL PROTECTED]> > Senior Systems Engineer and Toolsmith > "It's the sound of a satellite saying, 'get me down!'" -Shriekback >
