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<>)
--- Begin Message ---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
--- End Message ---
