Derby
  1. Derby
  2. DERBY-1992

Upgrade to DITA Open Toolkit to the latest version

    Details

    • Type: Improvement Improvement
    • Status: Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: 11.0.0.0
    • Fix Version/s: 11.0.0.0
    • Component/s: Build tools
    • Labels:
      None

      Description

      There are major improvements in the DITA Open Toolkit, including improvements in
      the display of index entries. Derby is currently on version 1.1.2.1 and needs to upgrade to a later version of
      the DITA Open Toolkit. The latest version of the DITA Open Toolkit can be found here: http://sourceforge.net/projects/dita-ot/

      1. refderby-raw-xhtml-dita1_5_4.zip
        886 kB
        Kristian Waagan
      2. refderby-raw-dita1_5_4.pdf
        1.42 MB
        Kristian Waagan

        Activity

        Hide
        Kim Haase added a comment -

        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.

        Show
        Kim Haase added a comment - 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.
        Hide
        Kristian Waagan added a comment -

        Unassigning Laura.

        Show
        Kristian Waagan added a comment - Unassigning Laura.
        Hide
        Knut Anders Hatlen added a comment -

        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.

        Show
        Knut Anders Hatlen added a comment - 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.
        Hide
        Kim Haase added a comment -

        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.

        Show
        Kim Haase added a comment - 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.
        Hide
        Kristian Waagan added a comment -

        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).

        Show
        Kristian Waagan added a comment - 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).
        Hide
        Rick Hillegas added a comment -

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

        Show
        Rick Hillegas added a comment - Removed reference to 1.3 version of DITA. As of 2010-11-19, the latest version of the DITA toolkit is 1.5.2.
        Hide
        Michelle Caisse added a comment -

        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.

        Show
        Michelle Caisse added a comment - 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.
        Hide
        Kim Haase added a comment -

        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.)

        Show
        Kim Haase added a comment - 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.)
        Hide
        Michelle Caisse added a comment -

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

        Show
        Michelle Caisse added a comment - I've successfully built a doc using DITA Open Toolkit 1.4.1. If nobody objects, I'd like to take this issue.
        Hide
        Dyre Tjeldvoll added a comment -

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

        Show
        Dyre Tjeldvoll added a comment - Not much activity on this issue lately. I guess this means that this isn't a candidate for 10.4?
        Hide
        Daniel John Debrunner added a comment -

        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?

        Show
        Daniel John Debrunner added a comment - 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?
        Hide
        Rick Hillegas added a comment -

        Reassigning to 10.2.3.0.

        Show
        Rick Hillegas added a comment - Reassigning to 10.2.3.0.
        Hide
        Laura Stewart added a comment -

        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).

        Show
        Laura Stewart added a comment - 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).

          People

          • Assignee:
            Unassigned
            Reporter:
            Laura Stewart
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:

              Development