Derby
  1. Derby
  2. DERBY-4349

Documentation build files incorrectly specify missing stylesheet

    Details

      Description

      A link in the metadata for generated HTML files calls for a stylesheet that is part of the DITA toolkit. There are two problems:

      1. The stylesheet doesn't actually appear in the output directories for the documentation, so it is not used.

      2. The link currently appears with the absolute pathname of the stylesheet in the temp directory for each document. For the Latest Alpha Manuals currently, for example, it looks like this for a page in the Getting Started guide:

      <link href="C:\nightlies\docs-trunk\out\getstarttemp\commonltr.css" type="text/css" rel="stylesheet" />

      Specifying an absolute pathname is obviously not desirable, because the pathname reflects where the docs were built, not where they are installed, and because the temp directory disappears after the docs are built anyway.

      There's a simple fix for each of these problems.

      1. DERBY-4349.diff
        0.8 kB
        Kim Haase
      2. commonltr.css
        5 kB
        Kim Haase
      3. DERBY-4349-2.diff
        0.8 kB
        Kim Haase

        Activity

        Hide
        Kim Haase added a comment -

        The solution for the two stylesheet problems is to make one small change each to the build.xml file and the docs.properties file.

        Adding the following line at the end of docs.properties gets rid of the absolute path:

        args.csspath=

        This results in the following output:

        <link href="commonltr.css" type="text/css" rel="stylesheet" />

        And fixing the following target in build.xml includes the stylesheet in the output directory for each document:

        <target name="html.dita">
        <!-- build to temp directory, then move the files over to the correct -->
        <!-- directory name, prepending the Apache License as we go. -->
        <mkdir dir="$

        {dita.dir}/temp"/>
        <mkdir dir="${basedir}/out/${manual.name}temp"/>
        <copy todir="${basedir}/out/${manual.name}temp">
        <fileset dir="${dita.dir}

        /resource"
        includes="index.html"/>
        <filterchain>
        <tokenfilter>
        <replaceregex pattern="Web Sample" replace="$

        {manual.title}

        "/>
        </tokenfilter>
        </filterchain>
        </copy>
        ...

        Changing the includes line to the following causes the stylesheet to be copied to the temp directory and therefore to the final output directory:

        includes="index.html,commonltr.css"/>

        Including the stylesheet improves the formatting of the HTML pages: It inserts vertical spaces above notes and the topic links at the ends of topics. It puts the terms in definition lists, as well as the introductory words in notes ("Note" or "Important", for example) in bold. It also reduces the size of topic heads and slightly increases the size of sub-heads.

        Show
        Kim Haase added a comment - The solution for the two stylesheet problems is to make one small change each to the build.xml file and the docs.properties file. Adding the following line at the end of docs.properties gets rid of the absolute path: args.csspath= This results in the following output: <link href="commonltr.css" type="text/css" rel="stylesheet" /> And fixing the following target in build.xml includes the stylesheet in the output directory for each document: <target name="html.dita"> <!-- build to temp directory, then move the files over to the correct --> <!-- directory name, prepending the Apache License as we go. --> <mkdir dir="$ {dita.dir}/temp"/> <mkdir dir="${basedir}/out/${manual.name}temp"/> <copy todir="${basedir}/out/${manual.name}temp"> <fileset dir="${dita.dir} /resource" includes="index.html"/> <filterchain> <tokenfilter> <replaceregex pattern="Web Sample" replace="$ {manual.title} "/> </tokenfilter> </filterchain> </copy> ... Changing the includes line to the following causes the stylesheet to be copied to the temp directory and therefore to the final output directory: includes="index.html,commonltr.css"/> Including the stylesheet improves the formatting of the HTML pages: It inserts vertical spaces above notes and the topic links at the ends of topics. It puts the terms in definition lists, as well as the introductory words in notes ("Note" or "Important", for example) in bold. It also reduces the size of topic heads and slightly increases the size of sub-heads.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-4349.diff, which fixes docs.properties and build.xml so that the stylesheet is included in the build. Also attaching commonltr.css so that you can drop it into your local documentation output folder and see what difference it makes to the HTML pages. (It does not affect the PDF or HTML Book docs.)

        If this change is likely to have any unintended consequences, please let me know. (The file doesn't seem to get included in the Japanese documents, for example, though I don't generally build these.)

        Show
        Kim Haase added a comment - Attaching DERBY-4349 .diff, which fixes docs.properties and build.xml so that the stylesheet is included in the build. Also attaching commonltr.css so that you can drop it into your local documentation output folder and see what difference it makes to the HTML pages. (It does not affect the PDF or HTML Book docs.) If this change is likely to have any unintended consequences, please let me know. (The file doesn't seem to get included in the Japanese documents, for example, though I don't generally build these.)
        Hide
        Rick Hillegas added a comment -

        Thanks for the patch, Kim. I applied it to my client and can confirm that it fixes the css links in the generated html: now they are relative filenames pointing at stylesheets in the same directory as the generated html. I can also confirm that this improves the spacing between some elements in the output. Looks good.

        I don't understand the issue with the copying of the stylesheets, however. Before applying the patch, the stylesheets nevertheless were correctly copied to the same directory as the generated html--they just weren't located by the browser because the links pointed to garbage locations.

        Thanks,
        -Rick

        Show
        Rick Hillegas added a comment - Thanks for the patch, Kim. I applied it to my client and can confirm that it fixes the css links in the generated html: now they are relative filenames pointing at stylesheets in the same directory as the generated html. I can also confirm that this improves the spacing between some elements in the output. Looks good. I don't understand the issue with the copying of the stylesheets, however. Before applying the patch, the stylesheets nevertheless were correctly copied to the same directory as the generated html--they just weren't located by the browser because the links pointed to garbage locations. Thanks, -Rick
        Hide
        Kim Haase added a comment -

        You're right, Rick, of course.

        If I use the default build.xml file and don't modify docs.properties, three .css files are copied into the output directory, but they are not used because the pathname is spurious.

        If I use the default build.xml file and modify docs.properties to add "args.csspath=", the .css files are not copied over, so using the correct relative pathname has no effect. (I've been defining args.csspath for a long time so I had forgotten what happened when I didn't.)

        The reason this happens is in the DITA toolkit file ditatargets.xml, but I can't make head nor tail of it. (There's a copy-css target.)

        If I modify build.xml to copy all the css files –

        includes="index.html, *.css"/>

        and modify docs.properties to add "args.csspath=", all three .css files are again copied over, although since only commonltr.css is referred to, I probably only need to copy that one. Copying all three would restore the default behavior, though. What do you think?

        Show
        Kim Haase added a comment - You're right, Rick, of course. If I use the default build.xml file and don't modify docs.properties, three .css files are copied into the output directory, but they are not used because the pathname is spurious. If I use the default build.xml file and modify docs.properties to add "args.csspath=", the .css files are not copied over, so using the correct relative pathname has no effect. (I've been defining args.csspath for a long time so I had forgotten what happened when I didn't.) The reason this happens is in the DITA toolkit file ditatargets.xml, but I can't make head nor tail of it. (There's a copy-css target.) If I modify build.xml to copy all the css files – includes="index.html, *.css"/> and modify docs.properties to add "args.csspath=", all three .css files are again copied over, although since only commonltr.css is referred to, I probably only need to copy that one. Copying all three would restore the default behavior, though. What do you think?
        Hide
        Kim Haase added a comment -

        After some thought and discussion, it probably makes the most sense to restore the previous behavior of copying all three files over (though only one is used currently), but with the docs.properties fix that makes commonltr.css at last accessible.

        Will post a revised patch and commit it in a day or two unless I hear any objections.

        Show
        Kim Haase added a comment - After some thought and discussion, it probably makes the most sense to restore the previous behavior of copying all three files over (though only one is used currently), but with the docs.properties fix that makes commonltr.css at last accessible. Will post a revised patch and commit it in a day or two unless I hear any objections.
        Hide
        Kim Haase added a comment -

        Attaching patch that copies over all three .css files, just in case. Reproduces previous behavior except that the file pointed to by the link will now be accessible.

        Show
        Kim Haase added a comment - Attaching patch that copies over all three .css files, just in case. Reproduces previous behavior except that the file pointed to by the link will now be accessible.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-4349-2.diff to trunk at revision 808424.

        Show
        Kim Haase added a comment - Committed patch DERBY-4349 -2.diff to trunk at revision 808424.
        Hide
        Kristian Waagan added a comment -

        Thanks, Kim.

        I checked this on the test docs build project on Hudson, and the line now reads:
        <link href="commonltr.css" type="text/css" rel="stylesheet" />

        The file referenced is also present in the directory.

        Show
        Kristian Waagan added a comment - Thanks, Kim. I checked this on the test docs build project on Hudson, and the line now reads: <link href="commonltr.css" type="text/css" rel="stylesheet" /> The file referenced is also present in the directory.
        Hide
        Kim Haase added a comment -

        Thanks very much, Kristian, for confirming that the fix does what it is meant to. I think it's safe to close this now.

        Show
        Kim Haase added a comment - Thanks very much, Kristian, for confirming that the fix does what it is meant to. I think it's safe to close this now.
        Hide
        Kristian Waagan added a comment -

        Reopening for backport (see DERBY-4906).

        Show
        Kristian Waagan added a comment - Reopening for backport (see DERBY-4906 ).
        Hide
        Kristian Waagan added a comment -

        While at it, I just backported the fix all the way back to 10.2.

        10.5: r1036820
        10.4: r1036821
        10.3: r1036826
        10.2: r1036831

        Closing the issue again.

        Show
        Kristian Waagan added a comment - While at it, I just backported the fix all the way back to 10.2. 10.5: r1036820 10.4: r1036821 10.3: r1036826 10.2: r1036831 Closing the issue again.

          People

          • Assignee:
            Kim Haase
            Reporter:
            Kim Haase
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development