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
Sam Vilain
March 17, 2005 14:48
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
Aaron Sherman wrote:
>>Sam "mugwump" Vilain refers to each of these syntaxes as /Pod dialects/.
>>He is working on more formally defining the common model or "AST" that
>>these dialects map to.
> Why? Seriously, why on earth do you want to encourage the proliferation
> of variant markup languages?! There aren't enough?
> My effort here was to try to PREVENT the proliferation (e.g. by Kwid and
> POD butting heads and ending up in a stalemate). The only problem is
> that, presented with a compromise, the Kwid folks seem to be content to
> ADD it to the list of variants rather than, in fact, compromise and
> collapse the list.
> I'll continue only as far as is needed to propose this in full as an
> example parser / converter, and then I'm going to stop. My goal is not
> to proliferate the number of markups further, and I'd MUCH rather see
> Perl 6 rely on POD than fragment the SINGLE MOST IMPORTANT TASK in
> creating code to share with the world: documentation.

Well, I don't think anyone wants to see as many POD dialects as there
are wiki text formats (BBCode, anyone?).  Maybe there will be something
very close to the original POD, but with a verbose way of making tables,
and an enhanced linking syntax.  But otherwise identical to the original
Perl 5 POD.

Note that POD dialects, and differing POD conventions already exist in
Perl 5 and are in common use.  They were designed in the original POD
with the =for tag.  At the moment, tools like `pod2html' have to be
heavily aware of the POD dialect, which I think is sub-optimal when it
comes to some of the really interesting things people have achieved
with POD.  Look at MarkOv's OODoc, or Test::Inline, for instance.

All I'm trying to do is giving these beasts a name, and defining a
mechanism by which they can be used by tools that only know how to deal
with "standard" documents - thus giving users the freedom to define a
local convention if one of them doesn't quite fit their needs.

Using a local Subversion repository, and Request Tracker, and want to
be able to put hyperlinks in POD to refer to these entities?  No
problem, just extend the dialect and add a link style.  Then select
from a dozen output tools or variants to see which one works for you.


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About