Return-Path: <niedermann@isd.uni-stuttgart.de>
Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Delivered-To: mailing list cocoon-dev@xml.apache.org
Received: (qmail 83677 invoked from network); 27 Jun 2000 18:30:27 -0000
Received: from maulaf.isd.uni-stuttgart.de (129.69.110.30)
  by locus.apache.org with SMTP; 27 Jun 2000 18:30:27 -0000
Received: (from niedermann@localhost)
	by maulaf.isd.uni-stuttgart.de (8.9.3/8.9.3) id UAA03045;
	Tue, 27 Jun 2000 20:30:24 +0200
X-Authentication-Warning: maulaf.isd.uni-stuttgart.de: niedermann set sender
 to niedermann@isd.uni-stuttgart.de using -f
To: cocoon-dev@xml.apache.org
Cc: giacomo.pati@pwr.ch
Subject: Re: Docs with Docbook
References: <20000627091538.13523.qmail@web6204.mail.yahoo.com>
From: Hans Ulrich Niedermann <niedermann@isd.uni-stuttgart.de>
Date: 27 Jun 2000 14:45:28 +0200
In-Reply-To: Giacomo Pati's message of "Tue, 27 Jun 2000 02:15:38 -0700 (PDT)"
Message-ID: <nxcya3re1hz.fsf@geograf.isd.uni-stuttgart.de>
Lines: 64
User-Agent: Gnus/5.0806 (Gnus v5.8.6) XEmacs/21.1 (Bryce Canyon)
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Spam-Rating: locus.apache.org 1.6.2 0/1000/N

Hi,

I still wonder what other people have been doing on the docs during
the last few weeks. I know there were some people working on
something using Docbook.

Giacomo Pati <pati_giacomo@yahoo.com> writes:

> --- Hans Ulrich Niedermann <niedermann@isd.uni-stuttgart.de> wrote:

> I've choosen the old document.dtd for the sitemap.xml because the
> infrastructure to build the html pages were there (stylebook). I

I probably would have used document.dtd, too.

> don't know exactly how stylebook works and if there are stylesheets
> which we can use to render the pages. If so maybe we can write
> another stylesheet to transform the older stylebook stylesheets to
> make them process the DocBook DTDs (almost as for those tags we use
> within our documentations). 

I don't think this is feasible. We probably have to either customize
Norm's Docbook stylesheets or write new stylesheets for ourselves.

We probably are going to customize docbook anyways, as Docbook
apparently doesn't allow for several kinds of markup I would consider
usefull when describing software installations out of the box
(e.g. <hostname>). 

> As for now C2 is not capable to be used offline. Maybe stylebook can
> be (easily) changed to handle the DocBook stylesheets (or maybe
> C1). I also think that the HTML docs have priority over the PDF 
> ones because we should be able to put those onto the web ASAP.

Producing HTML from Docbook XML 4.1 with Norman Walsh's XSL
stylesheets version 1.13 works quite well using ant and my xalan
task. Just add <xalan src="foo.xml" xsl="bla.xsl" dest="bar.html"/>
and you're done. 

The results do not look remotely like the stylebook stuff, though, so
they probably will not be used directly for the web site for
production use. But perhaps it is sufficient for developer docs of a
software projekt in early alpha stages.

If one uses Norm's XSL stylesheets out-of-the-box, the HTML results
looks like the files you can see here: 

  <URL:http://www.normans.isd.uni-stuttgart.de/~niedermann/xdocs/>

(View installing.html and sitemap.html and keep in mind  that 
 the <anchor> and <jump> elements are still ignored)

> > If someone could give me some hints, I could also try to get the FOP
> > stuff working with C2 instead of writing another Ant task for FOP. 
> > Unfortunately I can't find a written overall overview about the C2
> > architecture so I don't know where to start.
> 
> Can you explain what do you expect from a "C2 overall architecture
> overview" (is it another documentation candidate)?

I will when I am more that 20% awake in a few days, sorry for the
inconvenience. 

Uli