develooper Front page | perl.perl6.language | Postings from March 2005

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

Thread Previous | Thread Next
From:
Brian Ingerson
Date:
March 15, 2005 10:48
Subject:
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
20050315184836.GB9284@ttul.org
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 <ajs@ajs.com>
> Date: Tue, 15 Mar 2005 11:43:39 -0500
> To: Stevan Little <stevan@iinteractive.com>
> 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 <ajs@ajs.com>
> Senior Systems Engineer and Toolsmith
> "It's the sound of a satellite saying, 'get me down!'" -Shriekback
> 

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About