What should we do about StyleBook?

[ne...@ca.ibm.com]

Hi folks,

With the release of Xerces 1.3.0 looming in the fairly near future, I
thought it might be a good time for some discussion of the role of
StyleBook in the project.

For those who don't know, StyleBook is the tool which, along with Xalan, is
used to convert most of our documentation from their native XML to HTML
that people like to browse.  It does things like make sure all the neat
banners get applied in the right places consistently on all the pages.

The trouble is that, as far as I can tell, StyleBook is pretty much
completely unmaintained; I guess its designers have moved on to greater
things with projects like Cocoon.  Thus we're confronted by the unpleasant
long-term prospect of relying on code that may become obsolete at any
time--when jdk1.4 comes out perhaps?

But unfortunately there are more immediate problems.  For instance,
StyleBook can't run under JDK1.1.8.  Nor does it like running under Unix:
it can't handle reading from jar files on anything but a Windows system
(this is probably why people have had problems building Xerces from source
on Unix platforms from time to time).  You also can't run it from a vanilla
command shell under Unix; you've got to do it from X.

None of these are of vital concern--how many users want to build the docs
anyway?  But it seems to me they underline the difficulties of relying on
unmaintained code.

So I think we have three choices:

1.  To ``adopt'' StyleBook--that is, to keep letting it do its thing but to
find some way of incorpporating necessary bugfixes into it.

2.  To find some other package for converting our docs into HTML.

3.  To convert our docs into HTML and leave them in that form, so that all
modifications/additions would be done in that language.

3. is an unpleasant option vis-a-vis maintainability.  Does anyone know of
another package that would allow us to go the second route?  In some ways 1
is the most obvious choice, but  are we certain we'll have the time to keep
dragging StyleBook along?  Does anyone know what other Apache projects that
use StyleBook--and I think there are several--are thinking about these
questions?

Any ideas more than welcome!

Cheers,
Neil


Neil Graham
XML Parser Development
IBM Toronto Lab
Phone:  416-448-3519, T/L 778-3519
E-mail:  neilg@ca.ibm.com

Re: What should we do about StyleBook?

[Andy Clark <an...@apache.org>]

Mike Pogue wrote:
> Was the PDF output thing ever made available for people to use?
> It's really cool (if I do say so).

Since the C++ folks make the PDF available, I'm guessing that the
tool is freely available as part of Apache as well. But I have no
idea where that would be.

-- 
Andy Clark * IBM, TRL - Japan * andyc@apache.org

Re: What should we do about StyleBook?

[Mike Pogue <mp...@apache.org>]

Was the PDF output thing ever made available for people to use?
It's really cool (if I do say so).

Mike

----- Original Message ----- 
From: "Andy Clark" <an...@apache.org>
To: <xe...@xml.apache.org>
Sent: Wednesday, January 24, 2001 7:05 PM
Subject: Re: What should we do about StyleBook?


> Eric Hodges wrote:
> > What does keeping the docs in XML buy you?
> 
> Output to PDF, for one.
> 
> -- 
> Andy Clark * IBM, TRL - Japan * andyc@apache.org
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
> For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
> 

Re: What should we do about StyleBook?

[Andy Clark <an...@apache.org>]

Eric Hodges wrote:
> What does keeping the docs in XML buy you?

Output to PDF, for one.

-- 
Andy Clark * IBM, TRL - Japan * andyc@apache.org

Re: What should we do about StyleBook?

[Eric Hodges <ha...@swbell.net>]

----- Original Message -----
From: <ne...@ca.ibm.com>
To: <xe...@xml.apache.org>
Sent: Wednesday, January 24, 2001 4:41 PM
Subject: What should we do about StyleBook?


>
> 3.  To convert our docs into HTML and leave them in that form, so that all
> modifications/additions would be done in that language.
>
> 3. is an unpleasant option vis-a-vis maintainability.  Does anyone know of
> another package that would allow us to go the second route?  In some ways
1
> is the most obvious choice, but  are we certain we'll have the time to
keep
> dragging StyleBook along?  Does anyone know what other Apache projects
that
> use StyleBook--and I think there are several--are thinking about these
> questions?

What does keeping the docs in XML buy you?