You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by "Waldhoff, Rodney" <rw...@us.britannica.com> on 2002/01/16 14:54:28 UTC
RE: Latka docs (Re: cvs commit: jakarta-commons/latka/doc index.x
ml)
The real reason the Latka documentation is currently in Docbook XML format
is that it was originally a chapter from a developer's guide "book" we were
working on for internal use here. More comments inline...
> Jeff Turner wrote:
>
> > It would be nice if we could use docbook within the standard
> > Anakia-based website system. It should be doable simply be
> > transforming
> > the docbook to "stylebook" before running Anakia. This is what
> > Avalon
> > does (though using Cocoon instead of Anakia). The stylesheet is:
> >
> > jakarta-avalon/src/documentation/stylesheets/docbook2body.xsl
Sweet. So we can do [docbook]--/xslt/-->[stylebook]--/anakia/-->[html]? Is
that right? At least close (since stylebook and site2 aren't quite the
same)?
> >
> > There's also a Docbook -> PDF stylesheet in Avalon.
> >
This is precisely the appeal of using docbook:
1) It's well defined and documented (http://www.oasis-open.org/docbook/xml/;
http://www.docbook.org/xml/; etc.)
2) It's well suited for multiple output formats (not just websites)
3) It's used widely enough to have all kinds of tools, stylesheets, etc.
already available for it.
The downside is that it's a bit complicated because of its scope. Simply
using a subset can mitigate this problem. The Latka docs were originally
written for the "Simplified DocBook" subset
(http://www.oasis-open.org/committees/docbook/xml/simple/index.shtml) but
may have drifted from that slightly.
> I'm all for:
> a) whatever is being used being documented
Docbook's got us covered there.
> b) keeping commons sites consistent
docbook2body.xsl has as covered there, no?
> The site.vsl at least has some comments.
If you're looking for documentation on DocBook XML see any of the above
links, or http://docbook.org/ or http://nwalsh.com/docbook/ etc.
The current Latka documentation was generated from the XML file by
stylesheets available at http://sourceforge.net/projects/docbook (These are
rather well written, if complicated, stylesheets by the way. A nice set of
stylesheets for study.)
If you search the web a bit, you'll find dozens of DocBook/DocBookXML
processing tools, including XSL and DSSSL stylesheets, as well as
Java/Perl/C/etc. code meant to handle DocBook files directly.
> I've gotten all the current Latka documentation into the 'standard' xml
> format. BTW, does a DTD/Schema for the xml format exist anywhere?
For our "conventional" (not standard) XML format (which I use quite a
lot--see commons/xdoc, httpclient/xdoc, pool/xdoc, etc.--so don't get me
wrong) it seems to be <body>/<section> tags, containing whatever
xmlified-HTML you choose to put inside. This is *the* major problem with
trying to use the current website XML to generate anything but HTML, or for
that matter, to generate specific flavors of HTML--you'll never know what
someone is going to put inside. As an XML document, it defines some very
high level structure, but nothing else.
> dIon Gillard, Multitask Consulting
- Rod