Realize that you are trying to convince a group who uses POD at the command
line (no, not everybody) to use a complete markup language. We're talking about
self-commenting code, sir, not a strict documentation system with indices and
the likes in any formal sense. Even if a documentation system does need a
revamp, one like POD with its goals and means doesn't require complete markup,
and from what I've seen on CPAN, the less authors have to deal with in terms of
official structural grammar in incidental text within their modules, the better
off everyone is.
No language that I know of has anything like this, or considers it warranted.
Perl is among a select few that even allows documentation within its
programming code. Maybe the presentation could be fixed up a bit, but as for
official grammars, POD is _already_ heads and tails above the rest. (viz.
Javadoc, Python """ docs, and C++/Pascal documentation that relies on /** and
{(* nastiness).
What, in programming, do you need? Multimedia? Rigid structure within
<moduletype></moduletype> tags? <os></os> tags? (Though the latter might me
beneficial in POD.)
One of the goals of POD is that it be easily translated into other formats. XML
is one of the end formats to translate TO, not an applicable format to
translate FROM. The more structured the original format, the more difficult it
becomes to end up with HTML/Postscript/TeX/Word/WinHelp/HtmlHelp/Text and all
of the other pod2x's that I can't think of at the moment. If you want XML,
provide a translator first, and see how many people actually use it over the
other formats that get translated TO. Currently, the two most used formats are
text at the command line, and HTML.
This doesn't say that POD can't use improvement, because it's nearly
universally recognized that it can (a la Larry), but moving from POD to XML is
as horrendous as moving from Perl to Python/Java/C++ _within_ Perl, and I
believe is an accurate allusion.
On Sunday, October 01, 2000 9:50 AM, Frank Tobin [SMTP:[EMAIL PROTECTED]] wrote:
> Adam Turoff, at 03:22 -0400 on Sun, 1 Oct 2000, wrote:
>
> > POD has three mighty significant advantages over XML:
> > - it is easy to learn
>
> True, but XML is also easy to learn, and is more in-line with what the
> user will probably already know, as covered in the RFC.
>
> > - it is to write
>
> True, but XML is not hard to write; if you want, you could make a real
> simple DTD with very small tags.
>
> > - it is easy to ignore, if you're spelunking for Perl code
> > Try and do that, when <body> interferes with <STDIN> syntactically.
>
> No reason there couldn't be a perl-style delimiter, with __*__.
>
> > DocBook, my doctype of choice, comes with a handy-dandy 600 page reference.
> > Terms like %qandaset.mix; and "entity reference" are far from easy to
> > understand to the beginner. Especially when compared to '=head1' and
> > '=head2'.
>
> I'm not supporting DocBook. The concept of <h1>foo</h1>, I would guess,
> is not that hard to grasp. Furthermore, the same syntax is used
> consistently throughout the document; there is no separate syntax between
> 'headers' and 'body'.
>
>
> > These are deficiencies in the POD language definition and the POD
> > toolchain. It can be fixed by tweaking the definition of POD
> > and writing better tools. It's not a reason to throw out POD
> > entirely because something more hyped is available to replace it.
>
> As covered, I'm worried POD will continually outgrow it's original design,
> and become messier and messier.
>
> > You must be kidding if you're seriously recommending XHTML as a
> > replacement for POD.
>
> I never stated I specifically supported using XHTML over pod; it was just
> an example of a DTD.
>
>
> > Moving to XHTML is one huge step backwards, because it is presentational
> > markup instead of structural markup. XHTML+CSS as a structural
> > model is a sick joke.
>
> Ah, yes, we all know how great HTML with author-defined presentationss
> per-instance-of-element are...
>
> > Moving towards a system that adds any friction to the documentation
> > process is a *>HUGE<* mistake.
>
> If this is a valid argument, then why not just use comments insetad of
> POD? XML does require some more work, granted. But it pays off.
>
> --
> Frank Tobin http://www.uiuc.edu/~ftobin/
