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
