Review Request: JDK-8180208 Provide a new docs bundle page

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

Review Request: JDK-8180208 Provide a new docs bundle page

Mandy Chung
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
Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Jonathan Gibbons
Mandy,

The <html> tag on line 2 of
http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/webrev.00/jdk/make/src/classes/build/tools/docs/docs-bundle-page.html.html

should have
     lang="en"

One line 50,
     class="striped" is unnecessary, since we are not referring to a
class in a stylesheet. The inline style in the <head> takes care of
everything.

-- Jon

On 05/11/2017 03:58 PM, 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

Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Weijun Wang
In reply to this post by Mandy Chung

On 05/12/2017 06:58 AM, 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

jdk.crypto.mscapi is not listed.

--Max

>
> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Mandy Chung

> On May 11, 2017, at 7:25 PM, Weijun Wang <[hidden email]> wrote:
>
>
> On 05/12/2017 06:58 AM, 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
>
> jdk.crypto.mscapi is not listed.

jdk.crypto.mscapi and jdk.crypto.ucrypto are platform-specific.  We need to figure a better way to include the platform-specific in a docs bundle.  We will address that in JDK 10.  They are mentioned in existing documentations today and so no change in that regards.

Mandy
Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Mandy Chung
In reply to this post by Jonathan Gibbons

> On May 11, 2017, at 4:08 PM, Jonathan Gibbons <[hidden email]> wrote:
>
> Mandy,
>
> The <html> tag on line 2 of
> http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/webrev.00/jdk/make/src/classes/build/tools/docs/docs-bundle-page.html.html
>
> should have
>    lang=“en"
>

Fixed.

> One line 50,
>    class="striped" is unnecessary, since we are not referring to a class in a stylesheet. The inline style in the <head> takes care of everything.

Leftover from previous edit.  Removed.

Webrev with updated module grouping:
  http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/webrev.01/

Updated doc bundle page:
  http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/docs/docs-index.html

Mandy
Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Magnus Ihse Bursie
In reply to this post by Mandy Chung
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.

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.

3) Is this really correct?

+JDK_DOCS_INDEX_HTML := $(JAVADOC_OUTPUTDIR)/docs-index.html

I assumed the output would be index.html?

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?

What's a "Group"? Isn't that more like "Area"? Why use "Standard"
instead of "Java SE"?

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.

/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

Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Mandy Chung

> On May 12, 2017, at 5:31 AM, Magnus Ihse Bursie <[hidden email]> 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

> 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.

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 <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 <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
>

Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Magnus Ihse Bursie


On 2017-05-12 17:04, Mandy Chung wrote:

>
>> On May 12, 2017, at 5:31 AM, Magnus Ihse Bursie
>> <[hidden email]
>> <mailto:[hidden email]>> 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
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Mandy Chung
Thanks Magnus for the review and feedback.

Updated webrev:
   http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/webrev.02

- Merged with the recent changesets in jdk9/dev.
- Renamed docs-jdk-index-html target to docs-jdk-index.
- Keep the “Java SE” column header.  Add a new table header to separate the other modules.
- I keep the API Specification there and improve this page as a follow-up issue.

http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/docs/docs-index.html

> On May 12, 2017, at 10:18 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>> 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.

Thanks.  I renamed it.

>
> 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.
>

Yup and they give different views of the modules.  The API specification shows a complete list of the modules whereas this page gives a quick overview of some high level grouping.

> 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.

I see the confusion you are pointing out.   I don’t have a good suggestion.

Mandy

Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Magnus Ihse Bursie

On 2017-05-12 20:09, Mandy Chung wrote:
> Thanks Magnus for the review and feedback.
>
> Updated webrev:
>     http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/webrev.02
>
> - Merged with the recent changesets in jdk9/dev.
> - Renamed docs-jdk-index-html target to docs-jdk-index.
> - Keep the “Java SE” column header.  Add a new table header to separate the other modules.
> - I keep the API Specification there and improve this page as a follow-up issue.

Looks good to me!

>
> http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/docs/docs-index.html
>
>> On May 12, 2017, at 10:18 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>>> 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.
> Thanks.  I renamed it.
>
>> 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.
>>
> Yup and they give different views of the modules.  The API specification shows a complete list of the modules whereas this page gives a quick overview of some high level grouping.
>
>> 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.
> I see the confusion you are pointing out.   I don’t have a good suggestion.

Maybe skip the three-bullet item list and rephrase it somewhat.

"The complete API specification is available from [this
overview](api/index.html). The following table guides to to some
important entry points".

Or something like that. I don't know. Should probably be done in a
follow-up.

/Magnus

>
> Mandy
>

Reply | Threaded
Open this post in threaded view
|

Re: Review Request: JDK-8180208 Provide a new docs bundle page

Mandy Chung

> On May 12, 2017, at 11:17 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>
>
> Maybe skip the three-bullet item list and rephrase it somewhat.
>
> "The complete API specification is available from [this overview](api/index.html). The following table guides to to some important entry points".
>
> Or something like that. I don't know. Should probably be done in a follow-up.


I prefer to follow up separately.

I rename “API Specification” to “JDK API Specification” in this patch.  It might not make a difference.

thanks
Mandy