Re: documentation

["Randy J. Ray" <rjray redhat com>]

> > > > > "Christian" == Christian Borup <borup borup com>
> > > > > wrote the following on Tue, 28 Nov 2000 13:25:46 +0100

  Christian> Why DocBook and not pod, as most every other perl module?  It
  Christian> sucks not beeing able to say perldoc Gnome...

It's a matter of scope. POD is suitable for UNIX-style man pages, and can
be reasonably adapted to other display disciplines. But straight
pod-to-html conversions are pretty hideous, due largely to the inherent
limitations of pod. Particularly in the case of the tutorial, I would not
want it hampered by these limitations. I keep a local copy of the tutorial
on every machine I use (desktops at work and at home, laptop that goes
everywhere else), it's great.

  Christian> I guess one could generate pod from the DocBook sources
  Christian> (though hardly very well), but it does seem rather silly.

On the contrary-- it would be a much easier task to derive clean pod from
a well-defined XML source. An XML DTD such as DocBook has room for more
information than pod does. You would be *throwing away* information in the
translation to pod.

Randy
--
-------------------------------------------------------------------------------
Randy J. Ray      | Programming is a Dark Art [...] The programmer is fighting
rjray redhat com  | against the two most destructive forces in the universe:
415-777-9810 x246 | entropy and human stupidity. --Dr. Damian Conway