On 10.01.2012 14:46, Rick Hillegas wrote:
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.
Throwing in another option, for which I don't know how much effort is
required (to be honest, I don't even know if it will produce the
document we are pursuing here):
5) Use DITA chunking, see [1].
Based on my little experiment getting the Getting Started guide built
(as XHTML) with the newest version of the DITA toolkit, I suspect we
will have to address a few existing problems with our DITA sources. It
would be good to move up to the most recent version of DITA in any case,
but I don't know how much havoc that may create for the PDF versions of
the manuals.
Any DITA experts on the list that can shed some light on this option?
Regards,
--
Kristian
[1] http://docs.oasis-open.org/dita/v1.1/OS/archspec/chunking.html
Thanks,
-Rick
