I tried out the 1.5.4 toolkit and found that the bug that made us insert the " " characters in the first place has been fixed. It used to be that if you didn't put a non-breaking space between a "ph" element and another element, the two elements were munged together, so that what you intended as "The Derby ij tool" came out "The Derbyij tool".

The <ph conref="../conrefs.dita#prod/productshortname"></ph> <codeph>ij</codeph> tool

With 1.5.4, if you replace the " " with a space, the toolkit preserves the space in the output. So if we are able to move to this version of the toolkit, we can safely remove those characters from the source.

Unassigning Laura.

I didn't find a toc.html in the zip, but the index.html file was there and had both a DOCTYPE tag and a META tag with charset, so upgrading DITA may allow us to back out the fixes for DERBY-4408.

I ran some of the files through http://validator.w3.org/. index.html fails validation because of DERBY-5359, and so did all the other html files I checked. The other html files had an additional error, that's not seen with the html files produced by the old DITA, caused by these lines:

<meta name="copyright" content="Apache Software Foundation 2004, @COPYRIGHT_YEAR@" type="primary"/>

The html validator says there is no attribute 'type'. The old DITA version didn't add a copyright meta tag.

Wow, the PDF file looks a lot better than the ones produced by the old toolkit. (There are still some problems with words that overflow columns, but those are probably insoluble.)

The lack of support for " " reveals that they still haven't fixed the bug that whitespace between a <ph> element and another element is ignored. If you remove the " " here, you get "DerbyConnection" in the output.

<ph conref="../conrefs.dita#prod/productshortname"></ph> <i>Connection</i>

Also, the attempt to force four spaces doesn't show up in the output:

the CHAR(6) value '18    ' (18 followed by four spaces)

These are the only two occurrences of " " in the Reference Manual. The Getting Started guide has 11, and Tools has 5; the other 3 books have none. Maybe we can figure out a way to define this character?

The HTML looks exactly as it does now, as far as I can tell. The TOC page fails accessibility standards (see DERBY-5135 and sub-tasks) because the html element lacks a lang attribute; the other pages have this, though. The tables fail because of the empty summary attribute. I'm pretty sure the DITA DTD still doesn't support a summary attribute in the table source. (We had to add a template to one of the XSL stylesheets to generate one in the output.)

It would be helpful to see the output from a book with figures (the Tuning or Developer's guide) to make sure those come out all right.

So in general, they've improved the PDF output considerably, and there's not much change in the HTML.

I had a go at generating the reference manual using the current version of DITA (which is 1.5.4 at the moment).

See the attched file 'refderby-raw-dita1_5_4.pdf'.
I'm also including the HTML version for preview ('refderby-raw-xhtml-dita1_5_4.zip').

Note that the content was generated by invoking DITA without any Derby specific configuration. It may be used to evaluate if the newer version adds benefits compared to the old DITA version out-of-the-box. It does not give a definite answer, as some configuration may be needed to enable some new improvements etc.

I had to remove all uses of " " (DITA says referenced but not defined), and also to create the the directory "out/ref" manually. These things can probably be properly fixed later.
Also, the HTML version is not with frames (requires some configuration).

Removed reference to 1.3 version of DITA. As of 2010-11-19, the latest version of the DITA toolkit is 1.5.2.

Unfortunately, I've hit a dead end on this issue due to licensing problems. Upgrading to DITA-OT 1.4.1 would not provide indexes because (1) indexes are not available for XHTML docs and (2) the PDF index generation depends on software that, though it has a free personal license, that license is not consistent with use within Apache (or any other organization, for that matter.) (Andrew mentioned this problem in email to derby-dev on 16 Nov 07.)

Laura raised the issue of indexing support on the DITA Help forum (http://sourceforge.net/forum/message.php?msg_id=4127959) and by my reading of the response, getting a solution with a reasonable license doesn't look promising.

DITA 1.4.1 does come with an Apache license. There is no longer a separate download for an Apache licensed toolkit. I haven't yet succeeded in creating pdf with 1.4.1. If there is any reason to upgrade given that we will not get indexes, I can pursue this.

It would be wonderful if we could get a toolkit that improves the output for PDF and the one-file HTML in particular. I hope it doesn't need too much customizing for our needs. Thanks for taking this on. (Whether it works out for 10.4 or later.)

I've successfully built a doc using DITA Open Toolkit 1.4.1. If nobody objects, I'd like to take this issue.

Not much activity on this issue lately. I guess this means that this isn't a candidate for 10.4?

Is there a plan to have the 10.2 branch use the new DITA open toolkit? Doesn't seem like an appropriate change for 10.2. Should the fix version just be 10.3.0.0?

Reassigning to 10.2.3.0.

If the DITA 3.1 toolkit does not fix the appearance of choice tables in HTML, create a new JIRA issue to fix this in the Derby style sheet (XSL file I believe).