Re: RFR: JDK-8175036 All API docs should be built for HTML 5

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: RFR: JDK-8175036 All API docs should be built for HTML 5

Martin Buchholz-3
[+javadoc-dev]

I'm no html expert, so don't trust anything I say, but:

jdk9 javadoc contains constructs that are clearly invalid html5, so generating html5 output creates invalid web pages; they must be cleaned up first.  Someone around here must have the expertise to know how best to write modern html tables with borders.  The existing tables have mostly been cargo-culted from file to file (including in java.util.concurrent).

Even if we can generate clean html5, I suspect it's too early to switch; web standards change more slowly than anything else in the universe except IPv6.  Whenever we're tempted to switch to a "modern" standard, we should listen to How Many More Years? until the feeling goes away.



On Sun, Apr 23, 2017 at 10:11 AM, Magnus Ihse Bursie <[hidden email]> wrote:
Martin,

Does this mean you oppose this change until all Javadoc compiles cleanly with doclint html5?

/Magnus

22 apr. 2017 kl. 19:11 skrev Martin Buchholz <[hidden email]>:

It seems our javadoc is using html constructs that are not valid html5.  If so, we should convert all of those before we start generating html5 output.  That should not be too much work for someone who actually understands css and html5.

On Fri, Apr 21, 2017 at 2:30 AM, Magnus Ihse Bursie <[hidden email]> wrote:
Jon,

Can you please open a separate bug for this? Just adding --doclint-format html5 generates a lot of failures, as Martin points out, so it's not feasible to do as part of this fix.

/Magnus


On 2017-04-21 03:08, Martin Buchholz wrote:
There would be a global cleanup involved for --doclint-format html5
A CSS expert can probably suggest replacements.

     [javac] ... src/main/java/util/Deque.java:30: error: attribute border
for table only accepts "" or "1", use CSS instead: BORDER
     [javac]  * <table BORDER CELLPADDING=3 CELLSPACING=1>


On Thu, Apr 20, 2017 at 3:42 PM, Jonathan Gibbons <
[hidden email]> wrote:

We probably want to set

--doclint-format html5

for javac as well, for the benefit of compilations that run doclint.

-- Jon



On 4/20/17 3:20 PM, Magnus Ihse Bursie wrote:

We should switch all uses of the javadoc tool to generate documentation
in HTML 5, using the -html5 option.

Bug: https://bugs.openjdk.java.net/browse/JDK-8175036
Patch inline:
diff --git a/make/Javadoc.gmk b/make/Javadoc.gmk
--- a/make/Javadoc.gmk
+++ b/make/Javadoc.gmk
@@ -84,7 +84,7 @@
  # The initial set of options for javadoc
  JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords
-notimestamp \
      -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system
none \
-    --expand-requires transitive
+    -html5 --expand-requires transitive

  # Should we add DRAFT stamps to the generated javadoc?
  ifeq ($(VERSION_IS_GA), true)

/Magnus





Reply | Threaded
Open this post in threaded view
|

Re: RFR: JDK-8175036 All API docs should be built for HTML 5

Jonathan Gibbons

Martin

No one disputes that we need to clean up the HTML in our doc comments.  There is also a very strong desire to move to HTML 5 for the JDK documentation to be able to make use of the accessibility features that are available.

The only issue is how to get there from here and how quickly can we do it?

Now that Unified docs are in place, we should be able to start doing experiments to determine the magnitude of the problem.

-- Jon


On 4/24/17 5:00 PM, Martin Buchholz wrote:
[+javadoc-dev]

I'm no html expert, so don't trust anything I say, but:

jdk9 javadoc contains constructs that are clearly invalid html5, so generating html5 output creates invalid web pages; they must be cleaned up first.  Someone around here must have the expertise to know how best to write modern html tables with borders.  The existing tables have mostly been cargo-culted from file to file (including in java.util.concurrent).

Even if we can generate clean html5, I suspect it's too early to switch; web standards change more slowly than anything else in the universe except IPv6.  Whenever we're tempted to switch to a "modern" standard, we should listen to How Many More Years? until the feeling goes away.



On Sun, Apr 23, 2017 at 10:11 AM, Magnus Ihse Bursie <[hidden email]> wrote:
Martin,

Does this mean you oppose this change until all Javadoc compiles cleanly with doclint html5?

/Magnus

22 apr. 2017 kl. 19:11 skrev Martin Buchholz <[hidden email]>:

It seems our javadoc is using html constructs that are not valid html5.  If so, we should convert all of those before we start generating html5 output.  That should not be too much work for someone who actually understands css and html5.

On Fri, Apr 21, 2017 at 2:30 AM, Magnus Ihse Bursie <[hidden email]> wrote:
Jon,

Can you please open a separate bug for this? Just adding --doclint-format html5 generates a lot of failures, as Martin points out, so it's not feasible to do as part of this fix.

/Magnus


On 2017-04-21 03:08, Martin Buchholz wrote:
There would be a global cleanup involved for --doclint-format html5
A CSS expert can probably suggest replacements.

     [javac] ... src/main/java/util/Deque.java:30: error: attribute border
for table only accepts "" or "1", use CSS instead: BORDER
     [javac]  * <table BORDER CELLPADDING=3 CELLSPACING=1>


On Thu, Apr 20, 2017 at 3:42 PM, Jonathan Gibbons <
[hidden email]> wrote:

We probably want to set

--doclint-format html5

for javac as well, for the benefit of compilations that run doclint.

-- Jon



On 4/20/17 3:20 PM, Magnus Ihse Bursie wrote:

We should switch all uses of the javadoc tool to generate documentation
in HTML 5, using the -html5 option.

Bug: https://bugs.openjdk.java.net/browse/JDK-8175036
Patch inline:
diff --git a/make/Javadoc.gmk b/make/Javadoc.gmk
--- a/make/Javadoc.gmk
+++ b/make/Javadoc.gmk
@@ -84,7 +84,7 @@
  # The initial set of options for javadoc
  JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords
-notimestamp \
      -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system
none \
-    --expand-requires transitive
+    -html5 --expand-requires transitive

  # Should we add DRAFT stamps to the generated javadoc?
  ifeq ($(VERSION_IS_GA), true)

/Magnus






Reply | Threaded
Open this post in threaded view
|

Re: RFR: JDK-8175036 All API docs should be built for HTML 5

Martin Buchholz-3


On Mon, Apr 24, 2017 at 5:06 PM, Jonathan Gibbons <[hidden email]> wrote:

There is also a very strong desire to move to HTML 5 for the JDK documentation to be able to make use of the accessibility features that are available.

OK, that's a good reason to do it sooner rather than later!