On 2017-05-12 17:04, Mandy Chung wrote:
On May 12, 2017, at 5:31 AM, Magnus Ihse Bursie
<[email protected]
<mailto:[email protected]>> wrote:
Mandy,
Build changes mostly look good. I have a few requests:
1) Please rename the target docs-jdk-index instead of
docs-jdk-index-html.
Will fix.
2) I'm glad you added a LogInfo line, however
+ $(call LogInfo, Generating docs bundle page at $@)
will print the full path to the output file, and we try to avoid it.
I'd be happy with just "$(call LogInfo, Generating docs bundle
page)", since it's unique.
OK.
3) Is this really correct?
+JDK_DOCS_INDEX_HTML := $(JAVADOC_OUTPUTDIR)/docs-index.html
I assumed the output would be index.html?
This is what I mentioned to coordinate with you. You have a patch
coming to stop building the technotes that I don’t know I should wait
for your patch before changing it to index.html
I see. JDK-8175825 (Stop including pubs repo) is pushed now, so there
should be no conflict with an index.html from there.
Regarding the generated page, I don't want to be bikeshedding, but I
think there's some room for improvement here... Maybe that should be
defered to a separate bug, I don't know. "Outside Java SE" just
sounds like a weird way to say "Misc" -- how can it be listed in the
"Standard" column and still be outside?
There are two options: making “Standard” to “Java SE” and move
java.smartcardio and java.jnlp to another column. I’ll follow up
with Alex who proposes to make this column “Standard”. We can always
follow up with a separate issue to improve this.
What's a "Group"? Isn't that more like "Area"? Why use "Standard"
instead of "Java SE"?
It isn’t really an area.
Shouldn't there be any indication that the module links are shortcuts
into the same place that the very first link "API Specification"
points to? Now it sounds like it's completely different documents.
It links to the module summary page which can include other
information over time e.g. links to other specification such as JNI etc.
I don't think I made myself clear. On the page you are creating, the
link for e.g. java.base goes to the module summary page for java.base,
but the
The API link goes go api/index.html, which in turn links to e.g. the
module summary page for java.base, while the but e.g. the "API
specification" goes to the api/index.html page, which is just yet
another collection of links to the module summary pages. It's like two
different entry points to the collection of module summaries, one that
is in alphabetic order and generated by javadoc, and one that's grouped
per domain and generated by your tool.
This is, in itself, not a problem. Both entry points can make perfect sense.
What I'm trying to point out that this fact, that the "API
specification" link is just another entry point to the same stuff that
the table further down is linking to, is not made very clear. If you
start with this page, you might very well come off with the impression
that there's *two* sets of documentations, the "API specification" and
the links to the different modules.
/Magnus
Mandy
/Magnus
On 2017-05-12 00:58, Mandy Chung wrote:
The old docs bundle page (aka layer cake) is legacy and not maintained. In JDK
9, we replace it with a simple page listing modules by groups. This page can
continuously be improved.
http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/docs/docs-index.html
This is generated by a build tool. Webrev at:
http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/webrev.00/index.html
The makefile generates this page in docs-index.html.
Magnus - we will follow up whether you or I make the change to replace
index.html.
thanks
Mandy
