On 1/9/12 4:36 PM, Myrna van Lunteren wrote:
On Mon, Jan 9, 2012 at 3:19 PM, Andrew McIntyre<[email protected]> wrote:
On Sat, Jan 7, 2012 at 4:46 PM, Jean T. Anderson<[email protected]> wrote:
I did some checking and that file has been in the subversion respository
since April 2005, added in revision 161353 with the log message "Add single
page HTML output to derby doc build." -- in other words, ever since we
started using DITA to build the docs, so I expect it to be in all
distributions starting with 10.1. I'll check with Andrew next week to see if
he remembers more of the story around this file. Or maybe one of the other
committers on this list who have tweaked this file can comment?
In the meantime, while we untangle the story to all our satisfaction, anyone
who further distributes the derby product should, of course, follow the
advice of their lawyer. If there's any concern about this file, then one
option would be to omit the single book HTML file from your distribution --
perhaps just include the PDF file or link to the single book HTML file on
the apache site.
regards,
-jean
Hi Jean,
We had been using this file to generate single-page HTML documentation
for test and review during the DITA conversion since before the docs
were contributed to Apache. I checked it in when I was moving the doc
build machinery into Subversion. In retrospect, I probably shouldn't
have checked it in, but when someone went to modify it is when we had
the original discussion. There should at least be an entry for it in
the doc-src NOTICES. I can remove the file if it's a problem though,
as the file could be downloaded directly to the release builder's
machine by Ant. Also, there are other, free options for converting
PDFs to HTML files.
- andrew
I think we should probably get rid of this file, and we should really
avoid using it altogether. Is there anyone who has the skill to
replace this file?
Myrna
I ran a quick experiment: I removed fo2html.xsl and verified that I
could build the frames html docs. Here are some solutions listed in
declining order of effort:
1) Remove fo2html.xsl.
+ Easy.
- We will lose the no-frames version of the html docs. I do use the
no-frames version when citing doc passages in posts to derby-user. That
is my only use for the no-frames version. Passage citations would be a
little more cumbersome, but I could live with that.
2) Track down Nikolai Grigoriev and get him to open source this file
under Apache 2.0.
+ Preserves the no-frames version of the docs.
+ Relatively low effort on our part.
- Unbounded problem. We're not certain that we can track him down or
that he would agree to use the Apache 2.0 license.
3) Replace fo2html.xsl with an xsl transformation which we write ourselves.
+ Preserves the no-frames version of the docs.
- Probably outside the current skill sets of our current contributors.
4) Convert the docs to another source format.
+ Would be an opportunity to address our dissatisfactions with DITA,
including its accessibility problems and our inability to generate a doc
index.
- Big effort.
Thanks,
-Rick
