db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rick Hillegas <Richard.Hille...@Sun.COM>
Subject Re: Feedback requested on proposed change to documentation format
Date Mon, 06 Oct 2008 14:58:15 GMT
Hi Kim,

+1 to a documentation format which lets us build indexes and 
intra-document hotlinks. If we migrate to a new system, I hope that it 
preserves the following features of the old system:

1) Is driven by an ant script. This would make it easy to integrate into 
a master target which the release manager could use to build 
documentation and code.

2) Only uses tools which come with Apache-compatible licenses.

3) Only uses tools which are easy to get off the web without a lot of 
prep and license click-through.


Kim Haase wrote:
> I'd like to know what the Derby community thinks about the possibility 
> of changing the source format of the Derby documentation from DITA to 
> DocBook and using a different build system. DocBook is a schema that 
> can use an XML DTD, like that of DITA; see http://www.docbook.org/ for 
> more information.
> Our DITA toolkit has some problems that the Derby community hasn't 
> been able to solve with our current level of resources:
> - It does not allow us to create book indexes or to create live links 
> between manuals. The feedback we've received is that this makes the 
> documentation hard to use.
> - Links to tables usually don't work in the PDF or HTML Book versions.
> - Building the PDF and HTML Book versions of the docs causes errors 
> and warnings that we can't seem to get rid of.
> Conversion of the documentation source to DocBook would be a one-time 
> task that I'd be willing to take on. I can also use an existing 
> DocBook build system that, like the DITA toolkit, uses only freely 
> available open-source tools. The only change is that it would need to 
> convert from Gnu make to Ant to be compatible with the Apache license. 
> The goal would be to make it no more difficult to build the 
> documentation than it is today (and ideally easier). I would hope to 
> complete the project for the next release of Derby (10.5).
> Before I explore these possibilities further, I'd like feedback from 
> the community. It seems that few people are currently working on the 
> Derby documentation, but many of you are using it. I would be grateful 
> for your thoughts.
> Kim Haase

View raw message