Derby
  1. Derby
  2. DERBY-5905

Derby html documentation doesn't render properly and prints garbage on Internet Explorer

    Details

    • Type: Bug Bug
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.8.2.2, 10.9.1.0, 10.10.1.1
    • Fix Version/s: 10.8.3.0, 10.9.2.2, 10.10.1.1
    • Component/s: Documentation
    • Labels:
      None
    • Issue & fix info:
      High Value Fix

      Description

      There have been reports that DERBY html documentation does not render on Internet Explorer 8 and 9.

      Kristian reports on IE8
      Just tried with IE8, and with the Getting Started manual I get this when I view the source:
      """
      <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
      <HTML><HEAD>
      <META content="text/html; charset=utf-8" http-equiv=Content-Type></HEAD>
      <BODY></BODY></HTML>
      <snipped garbage as to not put it in jira>

      Not sure how that last line will turn out in your email clients, but it is indeed garbage and you can see that the body-tag is empty. Nothing is rendered in the browser. We are using frames though - that's not exactly state-of-the-art... We are also using the wrong DOCTYPE. I'm suspecting that the HTML is invalid too, but haven't checked.

      On IE9 I had heard that the reference HTML manual prints garbage.
      http://db.apache.org/derby/manuals/index.html#latest

      1. ASF.LICENSE.NOT.GRANTED--screenshot-1.jpg
        295 kB
        Siddharth Srivastava
      2. d5905-1a-move-comments.diff
        3 kB
        Knut Anders Hatlen
      3. d5905-2a-lang-attribute.diff
        2 kB
        Knut Anders Hatlen

        Issue Links

          Activity

          Hide
          Rick Hillegas added a comment -

          For the record, the manual displays fine on my mac using the following browsers:

          Firefox 5.0.1
          Safari 5.1.7
          Chrome 21.0.1180.75
          Opera 9.80

          Show
          Rick Hillegas added a comment - For the record, the manual displays fine on my mac using the following browsers: Firefox 5.0.1 Safari 5.1.7 Chrome 21.0.1180.75 Opera 9.80
          Hide
          Siddharth Srivastava added a comment -

          Attaching a screenshot of http://db.apache.org/derby/docs/10.9/ref/ on IE9.
          Looks like garbage since there are no links

          Show
          Siddharth Srivastava added a comment - Attaching a screenshot of http://db.apache.org/derby/docs/10.9/ref/ on IE9. Looks like garbage since there are no links
          Hide
          Siddharth Srivastava added a comment -

          The HTML manuals on http://db.apache.org/derby/manuals/index.html#latest also behave exactly the same on IE9 (see attached screenshot)

          Show
          Siddharth Srivastava added a comment - The HTML manuals on http://db.apache.org/derby/manuals/index.html#latest also behave exactly the same on IE9 (see attached screenshot)
          Hide
          Kristian Waagan added a comment -

          Looks like IE isn't able to deal with the '<?xml version="1.0" encoding="UTF-8"?>' tag in our docs.
          I don't know if there is something else in the page that causes IE to fall over in combination with that XML prolouge, or if the tag alone is enough.

          Does anyone know the details on this?
          I.e. the specifics on the ?xml-tag, the doctype tag, and relevant meta tags for IE?

          Another remark is that when I copied one of the pages that IE wasn't able to display online to my local drive, IE was able to display it. It used IE8 Quirks mode, but I don't know what it's trying to do for the online version since everything just "hangs"/stops before I can tell what's going on.

          Show
          Kristian Waagan added a comment - Looks like IE isn't able to deal with the '<?xml version="1.0" encoding="UTF-8"?>' tag in our docs. I don't know if there is something else in the page that causes IE to fall over in combination with that XML prolouge, or if the tag alone is enough. Does anyone know the details on this? I.e. the specifics on the ?xml-tag, the doctype tag, and relevant meta tags for IE? Another remark is that when I copied one of the pages that IE wasn't able to display online to my local drive, IE was able to display it. It used IE8 Quirks mode, but I don't know what it's trying to do for the online version since everything just "hangs"/stops before I can tell what's going on.
          Hide
          Kim Haase added a comment -

          Before 10.8, the '<?xml version="1.0" encoding="UTF-8"?>' tag appeared after the commented-out Apache license code; at 10.8 and after, the tag appears at the top of the file. Could that make a difference?

          I also notice that if I open the HTML files that I generated on my local system, IE can read them just fine. (No idea if any Quirks are involved.) Only if I look at the ones deployed on an internal web server prior to putting them on an external website do I see the problem.

          Show
          Kim Haase added a comment - Before 10.8, the '<?xml version="1.0" encoding="UTF-8"?>' tag appeared after the commented-out Apache license code; at 10.8 and after, the tag appears at the top of the file. Could that make a difference? I also notice that if I open the HTML files that I generated on my local system, IE can read them just fine. (No idea if any Quirks are involved.) Only if I look at the ones deployed on an internal web server prior to putting them on an external website do I see the problem.
          Hide
          Knut Anders Hatlen added a comment -

          Another data point: I can view the docs in IE9 if I remove the Apache licence header comment, or if I move the licence header inside the <html> tag. I didn't have to remove the <?xml version="1.0" encoding="UTF-8"?> declaration.

          Show
          Knut Anders Hatlen added a comment - Another data point: I can view the docs in IE9 if I remove the Apache licence header comment, or if I move the licence header inside the <html> tag. I didn't have to remove the <?xml version="1.0" encoding="UTF-8"?> declaration.
          Hide
          Kim Haase added a comment -

          Great find – moving the license header inside the <html> tag would be the simplest and cleanest solution, I think. As long as it's near the top of each file I think we're okay. Seems to work in IE 8 too – I tried on our internal doc staging server.

          Show
          Kim Haase added a comment - Great find – moving the license header inside the <html> tag would be the simplest and cleanest solution, I think. As long as it's near the top of each file I think we're okay. Seems to work in IE 8 too – I tried on our internal doc staging server.
          Hide
          Knut Anders Hatlen added a comment -

          The attached patch, d5905-1a-move-comments.diff, makes the changes needed to move the license comment after the <html> tag in index.html, toc.html and the topic files. I built the getting started guide and verified that it looked OK in IE9. I've also run the resulting html files through http://validator.w3.org/, and no other problems than the already known issue DERBY-5359 were found.

          Show
          Knut Anders Hatlen added a comment - The attached patch, d5905-1a-move-comments.diff, makes the changes needed to move the license comment after the <html> tag in index.html, toc.html and the topic files. I built the getting started guide and verified that it looked OK in IE9. I've also run the resulting html files through http://validator.w3.org/ , and no other problems than the already known issue DERBY-5359 were found.
          Hide
          Knut Anders Hatlen added a comment -

          Kristian said:

          > Another remark is that when I copied one of the pages that IE wasn't
          > able to display online to my local drive, IE was able to display it.
          > It used IE8 Quirks mode, but I don't know what it's trying to do for
          > the online version since everything just "hangs"/stops before I can
          > tell what's going on.

          I'm not sure exactly what quirks mode does, but I searched for the
          problems we're seeing, and found that Internet Explorer takes comments
          that come before the DOCTYPE declaration as a signal to enable quirks
          mode. See for example this thread:
          http://stackoverflow.com/questions/941100/can-html-comments-appear-before-the-doctype-declaration

          So in any case it sounds safest to move the license comment away from
          the declaration to prevent any interaction with that mechanism in IE.

          Show
          Knut Anders Hatlen added a comment - Kristian said: > Another remark is that when I copied one of the pages that IE wasn't > able to display online to my local drive, IE was able to display it. > It used IE8 Quirks mode, but I don't know what it's trying to do for > the online version since everything just "hangs"/stops before I can > tell what's going on. I'm not sure exactly what quirks mode does, but I searched for the problems we're seeing, and found that Internet Explorer takes comments that come before the DOCTYPE declaration as a signal to enable quirks mode. See for example this thread: http://stackoverflow.com/questions/941100/can-html-comments-appear-before-the-doctype-declaration So in any case it sounds safest to move the license comment away from the declaration to prevent any interaction with that mechanism in IE.
          Hide
          Kim Haase added a comment -

          I applied the patch and verified that the output on my server looks fine in IE 8 too. Thanks, Knut!

          Show
          Kim Haase added a comment - I applied the patch and verified that the output on my server looks fine in IE 8 too. Thanks, Knut!
          Hide
          Knut Anders Hatlen added a comment -

          Thanks Kim. I've committed the patch to trunk with revision 1374347.

          Let's see if that makes the docs on the website readable again once the build job kicks in.

          We should probably backport the fix to 10.8 and 10.9 if it didn't break something else. The 10.7 docs don't seem to have this problem.

          Show
          Knut Anders Hatlen added a comment - Thanks Kim. I've committed the patch to trunk with revision 1374347. Let's see if that makes the docs on the website readable again once the build job kicks in. We should probably backport the fix to 10.8 and 10.9 if it didn't break something else. The 10.7 docs don't seem to have this problem.
          Hide
          Kim Haase added a comment -

          I mentioned this issue to my manager, who reports that the problem exists currently on IE 7 too. I don't think any of us had that version to check against.

          Show
          Kim Haase added a comment - I mentioned this issue to my manager, who reports that the problem exists currently on IE 7 too. I don't think any of us had that version to check against.
          Hide
          Siddharth Srivastava added a comment -

          The behavior of IE7 can be emulated by using <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" >
          Ref: http://msdn.microsoft.com/en-us/library/cc288325%28VS.85%29.aspx#SetMode

          Show
          Siddharth Srivastava added a comment - The behavior of IE7 can be emulated by using <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" > Ref: http://msdn.microsoft.com/en-us/library/cc288325%28VS.85%29.aspx#SetMode
          Hide
          Siddharth Srivastava added a comment -

          Do we have the modified version publicly available somewhere ?
          I just tested the unpatched version of http://db.apache.org/derby/docs/10.9/ref/ on browsershots with all the prominent browsers.
          Here is the result: http://browsershots.org/http://db.apache.org/derby/docs/10.9/ref/
          Results from MSIE 7 on Win XP (http://browsershots.org/screenshots/231c1a5e465b54000c77ce19252f2766) seems interesting. Probably we can test the patched version there as well.

          Show
          Siddharth Srivastava added a comment - Do we have the modified version publicly available somewhere ? I just tested the unpatched version of http://db.apache.org/derby/docs/10.9/ref/ on browsershots with all the prominent browsers. Here is the result: http://browsershots.org/http://db.apache.org/derby/docs/10.9/ref/ Results from MSIE 7 on Win XP ( http://browsershots.org/screenshots/231c1a5e465b54000c77ce19252f2766 ) seems interesting. Probably we can test the patched version there as well.
          Hide
          Knut Anders Hatlen added a comment -

          Thanks for testing it, Siddharth. I wasn't aware of Browsershots. Looks useful.

          The docs build job ran earlier today, but the rebuilt manuals have not been uploaded to the web site yet (I think a cronjob will take care of that very shortly). In the meantime, the latest version can be read directly from Apache's Jenkins server: https://builds.apache.org/job/Derby-docs/ws/trunk/out/ref/index.html

          I've tested the above URL in IE9, and it looks fine as far as I can tell. I've also submitted the URL to Browsershots, but it's still sitting in the queue there.

          Show
          Knut Anders Hatlen added a comment - Thanks for testing it, Siddharth. I wasn't aware of Browsershots. Looks useful. The docs build job ran earlier today, but the rebuilt manuals have not been uploaded to the web site yet (I think a cronjob will take care of that very shortly). In the meantime, the latest version can be read directly from Apache's Jenkins server: https://builds.apache.org/job/Derby-docs/ws/trunk/out/ref/index.html I've tested the above URL in IE9, and it looks fine as far as I can tell. I've also submitted the URL to Browsershots, but it's still sitting in the queue there.
          Hide
          Kristian Waagan added a comment -

          The docs look fine in IE8 too.

          FYI, I ran the deploy-job manually, but it will still take a little while before the updated docs go live (once we've migrated to svnpubsub this delay will be history).

          Show
          Kristian Waagan added a comment - The docs look fine in IE8 too. FYI, I ran the deploy-job manually, but it will still take a little while before the updated docs go live (once we've migrated to svnpubsub this delay will be history).
          Hide
          Kim Haase added a comment -

          The current trunk docs do indeed look fine (in IE8, for me).

          I guess the next step is to backport the fix to 10.9 and 10.8 and regenerate those docs too?

          Show
          Kim Haase added a comment - The current trunk docs do indeed look fine (in IE8, for me). I guess the next step is to backport the fix to 10.9 and 10.8 and regenerate those docs too?
          Hide
          Knut Anders Hatlen added a comment -

          I've backported the fix to 10.8 (revision 1375449) and 10.9 (revision 1375447). I don't think we have any automated build jobs that update the docs for old branches on the web site, so we'll have to update them manually. We usually only update them when there's a new release on the branch. Does anyone see any problems with making the web site display docs that don't exactly match the docs in the latest released version on the branch?

          Show
          Knut Anders Hatlen added a comment - I've backported the fix to 10.8 (revision 1375449) and 10.9 (revision 1375447). I don't think we have any automated build jobs that update the docs for old branches on the web site, so we'll have to update them manually. We usually only update them when there's a new release on the branch. Does anyone see any problems with making the web site display docs that don't exactly match the docs in the latest released version on the branch?
          Hide
          Rick Hillegas added a comment -

          Hi Knut,

          I can't think of any significant confusion which would be caused by posting branch docs which contain a couple extra bug fixes. Even if we had introduced some significant confusion in some topic, I think the harm caused by that would be dwarfed by the harm caused by not being able to read the docs at all. So I would say +1 to posting new versions of the branch docs. Thanks.

          Show
          Rick Hillegas added a comment - Hi Knut, I can't think of any significant confusion which would be caused by posting branch docs which contain a couple extra bug fixes. Even if we had introduced some significant confusion in some topic, I think the harm caused by that would be dwarfed by the harm caused by not being able to read the docs at all. So I would say +1 to posting new versions of the branch docs. Thanks.
          Hide
          Knut Anders Hatlen added a comment -

          Thanks, Rick. I've updated the 10.9 docs by running a full docs build from revision 1375584 on the 10.9 branch and copying the resulting docs to /www/db.apache.org/derby/docs/10.9 on minotaur, overwriting the old (10.9.1.0) docs. They haven't gone live on the web server yet, but I expect they'll be there in less than an hour. Note that I also regenerated the PDFs, even though this issue only affects the HTML docs, so that there won't be a mismatch between the HTML version and the PDF version of the manuals.

          If everything looks OK when the updated docs have propagated to the web server, I plan to do the same with the 10.8 docs tomorrow.

          Show
          Knut Anders Hatlen added a comment - Thanks, Rick. I've updated the 10.9 docs by running a full docs build from revision 1375584 on the 10.9 branch and copying the resulting docs to /www/db.apache.org/derby/docs/10.9 on minotaur, overwriting the old (10.9.1.0) docs. They haven't gone live on the web server yet, but I expect they'll be there in less than an hour. Note that I also regenerated the PDFs, even though this issue only affects the HTML docs, so that there won't be a mismatch between the HTML version and the PDF version of the manuals. If everything looks OK when the updated docs have propagated to the web server, I plan to do the same with the 10.8 docs tomorrow.
          Hide
          Kim Haase added a comment -

          It seems as if something weird is going on, possibly as an interaction between DERBY-5905 and DERBY-5359.

          Before the changes for these two issues, the html tag for the output looked like this (see the current 10.8 docs on the website for examples):

          <html lang="en-us" xml:lang="en-us">

          Now, after applying the patches, when I run "ant getstart" I get the following warnings:

          [xslt] /export/home/chaase/derbydoc/trunk/DITA-OT1.1.2.1/xsl/map2htmtoc.xsl:9:18: Warning! Cannot add attribute lang after child nodes or before an element is produced. Attribute will be ignored.

          [xslt] /export/home/chaase/derbydoc/trunk/DITA-OT1.1.2.1/xsl/dita2xhtml.xsl:8:18: Warning! Cannot add attribute lang after child nodes or before an element is produced. Attribute will be ignored.

          So the html tag in an output file that I generate now looks like this:

          <html xmlns="http://www.w3.org/1999/xhtml">

          On the web site itself, however, for the trunk and 10.9 docs the tag is just

          <html>

          I'm completely befuddled by this, so I'm just reporting what I am seeing. But we need the lang attributes for accessibility, in addition to the xmlns attribute.

          Show
          Kim Haase added a comment - It seems as if something weird is going on, possibly as an interaction between DERBY-5905 and DERBY-5359 . Before the changes for these two issues, the html tag for the output looked like this (see the current 10.8 docs on the website for examples): <html lang="en-us" xml:lang="en-us"> Now, after applying the patches, when I run "ant getstart" I get the following warnings: [xslt] /export/home/chaase/derbydoc/trunk/DITA-OT1.1.2.1/xsl/map2htmtoc.xsl:9:18: Warning! Cannot add attribute lang after child nodes or before an element is produced. Attribute will be ignored. [xslt] /export/home/chaase/derbydoc/trunk/DITA-OT1.1.2.1/xsl/dita2xhtml.xsl:8:18: Warning! Cannot add attribute lang after child nodes or before an element is produced. Attribute will be ignored. So the html tag in an output file that I generate now looks like this: <html xmlns="http://www.w3.org/1999/xhtml"> On the web site itself, however, for the trunk and 10.9 docs the tag is just <html> I'm completely befuddled by this, so I'm just reporting what I am seeing. But we need the lang attributes for accessibility, in addition to the xmlns attribute.
          Hide
          Knut Anders Hatlen added a comment -

          Thanks, Kim. I hadn't noticed that the lang attributes had disappeared. I'll take a look and see if I understand what's going on. I think this is not related to DERBY-5359, as the trunk docs on the website haven't been updated with that fix yet. That's probably why you see a slightly different result when you build it yourself from head of trunk, which includes both fixes.

          Show
          Knut Anders Hatlen added a comment - Thanks, Kim. I hadn't noticed that the lang attributes had disappeared. I'll take a look and see if I understand what's going on. I think this is not related to DERBY-5359 , as the trunk docs on the website haven't been updated with that fix yet. That's probably why you see a slightly different result when you build it yourself from head of trunk, which includes both fixes.
          Hide
          Knut Anders Hatlen added a comment -

          The problem appeared because the attributes must be added to the <html> node before any child nodes are added to it. The original fix inserted the license comment right after the <html> node, which made it non-empty when setTopicLanguage (or setTocLanguage) was called. The fix is to add the attributes before the comment is added (this won't change the order in which the elements appear, just the order in which they are processed/generated).

          The patch d5905-2a-lang-attribute.diff makes this change. Committed to trunk with revision 1375956.

          Show
          Knut Anders Hatlen added a comment - The problem appeared because the attributes must be added to the <html> node before any child nodes are added to it. The original fix inserted the license comment right after the <html> node, which made it non-empty when setTopicLanguage (or setTocLanguage) was called. The fix is to add the attributes before the comment is added (this won't change the order in which the elements appear, just the order in which they are processed/generated). The patch d5905-2a-lang-attribute.diff makes this change. Committed to trunk with revision 1375956.
          Hide
          Knut Anders Hatlen added a comment -

          I backported the 2a patch to 10.9 with revision 1375963, and uploaded re-built 10.9 docs based on that revision to the web site.

          Show
          Knut Anders Hatlen added a comment - I backported the 2a patch to 10.9 with revision 1375963, and uploaded re-built 10.9 docs based on that revision to the web site.
          Hide
          Knut Anders Hatlen added a comment -

          Backported to 10.8 with revision 1376000, and uploaded re-built 10.8 docs to the web site.

          Show
          Knut Anders Hatlen added a comment - Backported to 10.8 with revision 1376000, and uploaded re-built 10.8 docs to the web site.
          Hide
          Kim Haase added a comment -

          Wow, you figured that out very quickly. Thanks! It works now – no warnings, and the lang attribute is back. On the trunk the DERBY-5359 fix puts the xmlns attribute before the lang attribute. That should be fine.

          Show
          Kim Haase added a comment - Wow, you figured that out very quickly. Thanks! It works now – no warnings, and the lang attribute is back. On the trunk the DERBY-5359 fix puts the xmlns attribute before the lang attribute. That should be fine.
          Hide
          Kathey Marsden added a comment -

          Can this be resolved now?

          Show
          Kathey Marsden added a comment - Can this be resolved now?
          Hide
          Knut Anders Hatlen added a comment -

          Yes, I think the work on this issue is done. Marking as fixed.

          Show
          Knut Anders Hatlen added a comment - Yes, I think the work on this issue is done. Marking as fixed.

            People

            • Assignee:
              Knut Anders Hatlen
              Reporter:
              Kathey Marsden
            • Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development