db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <jlev...@mutagen.net>
Subject Re: Derby documentation in XML DITA
Date Wed, 08 Dec 2004 22:24:20 GMT

--- scott hutinger <s-hutinger@wiu.edu> wrote:
> So at this point, I think we should do a manual
> transforms -> html and 
> see what the problems are.  Jeff has found the
> parent child problem, 
> which is what forrest uses by default to create the
> website.  I'm 
> certain he has found others.  Then focus on the pdf
> files.  I think Jeff 
> has already done that.  I'm looking at the dita-dtd
> stuff currently.  
> Jeff, were you using the XSLT Scripts referenced in
> the dita 
> XSL-README.txt?  Also, we might want to see if any
> more information on 
> the subject is publicly available.
> A good case study that might get someone up a bit
> faster with a bit of 
> good background information might be:
> http://xml.coverpages.org/DITA-LeslieSIGDOC2001.pdf
> "Transforming Documentation from the XML Doctypes
> used for the Apache 
> Website to DITA: a Case Study" by Donald M Leslie.
> I am sure a bunch more exist, as when I was looking
> around I found a lot 
> of use and papers on the subject.
> scott

Cool link Scott!  It looks like they had the same
problems with the PDF using FOP that I did.  It just
doesnt look very professional.  Thats why I think we
need someone who is saavy with XSL to fiddle with our
transformations to fix that up, if possible.

Yes, I used the XSLT scripts that came with the dita
download.  Specifically, I have toyed with using
map2EclipseAll.xsl for the xhtml transform (great for
creating xhtml output that gets used in a potential
Eclipse information center), and map2WebHTMLTOC.xsl to
create a nice html table of contents that links to the
xhtml files.  For the PDF, I use topicmerge.xsl to
create one file, dita2fo_shell.xsl to create a .fo, 
and then FOP for a .ps file, and then distill the .ps
output with Acrobat.  Lots of problems with this
process, as I'll mention later in this note...

I think dita2fo_shell.xsl was recommended in that
XSL-README.txt file, but the others I used based on my
own experimentation.  If you do go the eclipse
infocenter route, you need to do more than just create
the xhtml files.  You also need an XML nav tree file,
the html one wont work in Eclipse.  So in that case, I
think I just used map2EclipseTOC.xsl to create the xml

I created some batch files for Windows (Linux users,
any volunteers for creating similar Linux
versions?)that you can use to rapidly create these
outputs. They are for use with saxon.  I'm attaching
them to this note.  To use these, place them in your
saxon install directory, and place the getting started
guide dita files in a directory called
"gettingstartedguide".  Also, place the dita package
files in the saxon hierarchy.  For example, place the
xsl files from the dita package in an xsl directory
right there in the saxon install directory.  Then just
run the batch files from the command line.  Here's a
description of each batch file:

This one creates xhtml, and also an html table of
contents file called getstartmap.htm that you can use
to navigate the xhtml files.  The batch file creates a
temporary file during the transform process that
basically removes a part of one of the xsl files that
was causing some formatting problems in some of the
reference topics.

This one creates the same xhtml files as the last one,
but it then creates an xml table of contents, instead
of the html one.  This is ideal for creating an entire
set for use with an Eclipse infocenter.

I wanted to create a batch file for the PDF transform,
but for some reason, I'm having problems with the
topicmerge.xsl file in my batch files.  This is a
necessary step in order to create one PDF file for the
entire book instead of many.  The problems with the
topicmerge.xsl file also prevent me from making a
batch file to create one large html file for the
entire book.  The problem seems to be that the result
of the topicmerge transform is a dita file that looks
invalid.  If someone wants to play around with this,
if you are more successful than me then please post
any solutions you find!  I'm going to continue to play
with it and see if I can get a working transform.

Finally, Scott mentioned errors in the html output. 
The first one, as he mentioned, is the missing
parent-child links problem.  The only other problem
I've found is that any links to other topics have
trouble pulling the names out of the conrefs file.  So
for example, if there is a topic that is called
"Welcome to Derby", it pulls the word "Derby" from the
gsconrefs.dita file perfectly, but if another topic
tries to link to that topic, the link says "Welcome to
" with the word Derby missing.

View raw message