Details

    • Type: Bug
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 7.0, 6.5
    • Component/s: general/javadocs
    • Labels:
    • Lucene Fields:
      New

      Description

      As of jdk9-ea-b158, ant documentation seems to build the core javadocs just fine, but fails on the lucene/memory/ javadocs...

      javadocs:
          [mkdir] Created dir: /home/hossman/lucene/dev/lucene/build/docs/memory
      
      download-java8-javadoc-packagelist:
        [javadoc] Generating Javadoc
        [javadoc] Javadoc execution
        [javadoc] Loading source files for package org.apache.lucene.index.memory...
        [javadoc] Constructing Javadoc information...
        [javadoc] Standard Doclet version 9-ea
        [javadoc] Building tree for all the packages and classes...
        [javadoc] javadoc: warning - invalid usage of tag &pa
        [javadoc] javadoc: warning - invalid usage of tag &pid
        [javadoc] javadoc: warning - invalid usage of tag &page
        [javadoc] Building index for all the packages and classes...
        [javadoc] Building index for all classes...
        [javadoc] Generating /home/hossman/lucene/dev/lucene/build/docs/memory/help-doc.html...
        [javadoc] Note: Custom tags that were not seen:  @lucene.internal
        [javadoc] 3 warnings
      
      BUILD FAILED
      /home/hossman/lucene/dev/build.xml:93: The following error occurred while executing this line:
      /home/hossman/lucene/dev/lucene/build.xml:251: The following error occurred while executing this line:
      /home/hossman/lucene/dev/lucene/common-build.xml:2179: The following error occurred while executing this line:
      /home/hossman/lucene/dev/lucene/module-build.xml:549: The following error occurred while executing this line:
      /home/hossman/lucene/dev/lucene/module-build.xml:65: The following error occurred while executing this line:
      /home/hossman/lucene/dev/lucene/module-build.xml:78: The following error occurred while executing this line:
      /home/hossman/lucene/dev/lucene/common-build.xml:2155: Javadocs warnings were found!
      
      Total time: 1 minute 0 seconds
      

      looking at the generated html files turns up this...

      hossman@tray:~/lucene/dev [master] $ find lucene/build/docs/memory -name \*.html | xargs grep -C5 "&pa"
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- but rather thrown away immediately after tokenization.
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- <p>
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- For some interesting background information on search technology, see Bob Wyman's
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- <a target="_blank" href="http://bobwyman.pubsub.com/main/2005/05/mary_hodder_poi.html">Prospective Search</a>, 
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- Jim Gray's
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html: <a target="_blank" href="http://www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=293&page=4">
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- A Call to Arms - Custom subscriptions</a>, and Tim Bray's
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- <a target="_blank" href="http://www.tbray.org/ongoing/When/200x/2003/07/30/OnSearchTOC">On Search, the Series</a>.
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- 
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- <p>
      lucene/build/docs/memory/org/apache/lucene/index/memory/MemoryIndex.html- <b>Example Usage</b> 
      

      The source java file has this...

       * Jim Gray's
       * <a target="_blank" href="http://www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=293&page=4">
       * A Call to Arms - Custom subscriptions</a>, and Tim Bray's
      

      ...which does in fact seem to be invalid HTML ... aren't & always suppose to be encoded as & ... even in URLs?

      I'm suprised the java8 javadocs/linter don't warn about this.

      1. LUCENE-7726.patch
        2 kB
        Uwe Schindler

        Issue Links

          Activity

          Hide
          thetaphi Uwe Schindler added a comment - - edited

          ...which does in fact seem to be invalid HTML ... aren't & always suppose to be encoded as & ... even in URLs?

          That's the problem. Easy to fix. Just commit a fix or open issue about it. I noticed it already about a month ago, but had no time to fix it.

          Show
          thetaphi Uwe Schindler added a comment - - edited ...which does in fact seem to be invalid HTML ... aren't & always suppose to be encoded as & ... even in URLs? That's the problem. Easy to fix. Just commit a fix or open issue about it. I noticed it already about a month ago, but had no time to fix it.
          Hide
          thetaphi Uwe Schindler added a comment - - edited

          I'm suprised the java8 javadocs/linter don't warn about this.

          We don't have a full HTML validator involved. In addition, for HTML5, the entity escaping can be left out, if it is unambiguous. This mimics the behaviour most browsers out there always had (because most web devs out there did this wrong). So the produced HTML is valid (HTML5) and also leads to no problems in HTML4 browsers. But we should still fix it.

          The requirement to escape also attributes is a requirement of just Java 9's Javac (which is a bug from the HTML5 perspective, but a good thing, too).

          Show
          thetaphi Uwe Schindler added a comment - - edited I'm suprised the java8 javadocs/linter don't warn about this. We don't have a full HTML validator involved. In addition, for HTML5, the entity escaping can be left out, if it is unambiguous. This mimics the behaviour most browsers out there always had (because most web devs out there did this wrong). So the produced HTML is valid (HTML5) and also leads to no problems in HTML4 browsers. But we should still fix it. The requirement to escape also attributes is a requirement of just Java 9's Javac (which is a bug from the HTML5 perspective, but a good thing, too).
          Hide
          thetaphi Uwe Schindler added a comment -

          There is also another TODO (separate issue, I'll open one): pegdown (the markdown processor) is also incompatible to Java 9; but it reached its end of life. The developer points to a new replacement lib - I just have to rewrite the Java code a bit. This is on my "mental TODO list...." since build 154 of Java 9.

          Show
          thetaphi Uwe Schindler added a comment - There is also another TODO (separate issue, I'll open one): pegdown (the markdown processor) is also incompatible to Java 9; but it reached its end of life. The developer points to a new replacement lib - I just have to rewrite the Java code a bit. This is on my "mental TODO list...." since build 154 of Java 9.
          Hide
          thetaphi Uwe Schindler added a comment -

          Patch fixing this issue. You can still not build full documentation because of failing "pegdown" processor, but that's a separate issue.

          Show
          thetaphi Uwe Schindler added a comment - Patch fixing this issue. You can still not build full documentation because of failing "pegdown" processor, but that's a separate issue.
          Hide
          jira-bot ASF subversion and git services added a comment -

          Commit 8684fe794437e483039a027dcd21a14d56773a12 in lucene-solr's branch refs/heads/master from Uwe Schindler
          [ https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=8684fe7 ]

          LUCENE-7726: Fix HTML entity bugs in Javadocs to be able to build with Java 9

          Show
          jira-bot ASF subversion and git services added a comment - Commit 8684fe794437e483039a027dcd21a14d56773a12 in lucene-solr's branch refs/heads/master from Uwe Schindler [ https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=8684fe7 ] LUCENE-7726 : Fix HTML entity bugs in Javadocs to be able to build with Java 9
          Hide
          jira-bot ASF subversion and git services added a comment -

          Commit e51e50e557fe7d2652080179994d08bea3b74239 in lucene-solr's branch refs/heads/branch_6x from Uwe Schindler
          [ https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=e51e50e ]

          LUCENE-7726: Fix HTML entity bugs in Javadocs to be able to build with Java 9

          Show
          jira-bot ASF subversion and git services added a comment - Commit e51e50e557fe7d2652080179994d08bea3b74239 in lucene-solr's branch refs/heads/branch_6x from Uwe Schindler [ https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=e51e50e ] LUCENE-7726 : Fix HTML entity bugs in Javadocs to be able to build with Java 9
          Hide
          thetaphi Uwe Schindler added a comment -

          Thanks Hoss Man for reminding me!

          Show
          thetaphi Uwe Schindler added a comment - Thanks Hoss Man for reminding me!
          Hide
          thetaphi Uwe Schindler added a comment -

          FYI, here is the HTML5 definition of "ambiguous ampersand": https://www.w3.org/TR/html5/syntax.html#syntax-ambiguous-ampersand
          In fact, Java 9's Javadocs and Javac parser do not use that definition, which may be seen as a bug, but in fact this definition is just horrible and was added to make sloppy web developers happy...

          Show
          thetaphi Uwe Schindler added a comment - FYI, here is the HTML5 definition of "ambiguous ampersand": https://www.w3.org/TR/html5/syntax.html#syntax-ambiguous-ampersand In fact, Java 9's Javadocs and Javac parser do not use that definition, which may be seen as a bug, but in fact this definition is just horrible and was added to make sloppy web developers happy...

            People

            • Assignee:
              thetaphi Uwe Schindler
              Reporter:
              hossman Hoss Man
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development