RFR: JDK-8172312 Update docs target and image for new combined docs

[Magnus Ihse Bursie]

Here is an updated webrev:
http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.03

The only change compared to the previous webrev is that I have updated 
the title for the JDK javadocs so it does not claim to be Java SE.

I have filed the following follow-up bugs to address Mark's concerns, 
and concerns expressed elsewhere:

* JDK-8178043 Group Java SE, JDK and JavaFX modules in unified javadoc [1]
* JDK-8178037 Move information from jdi-overview.html into jdk.jdi 
module-info.java [2]
* JDK-8178038 Copy jdwp-protocol.html to proper location [3]
* JDK-8178039 Copy jvmti.html to proper location [4]

I hope JDK-8178043 captures the intent of the solution I understand that 
Mark and Jon seemed to agree upon.

I also refer to the previously existing:

* JDK-8175824 Provide more flexible means for setting the overview text 
in the generated docs [5]

which I have amended with the task of also making sure that the values 
of the title text snippets gets proper values.

Since a lot of the continued work on Javadoc changes in JDK 9 is 
dependent on this change, I hope it is now clear for pushing.

/Magnus

[1] https://bugs.openjdk.java.net/browse/JDK-8178043
[2] https://bugs.openjdk.java.net/browse/JDK-8178037
[3] https://bugs.openjdk.java.net/browse/JDK-8178038
[4] https://bugs.openjdk.java.net/browse/JDK-8178039
[5] https://bugs.openjdk.java.net/browse/JDK-8175824


On 2017-04-04 01:38, mark.reinhold at oracle.com wrote:
> 2017/4/3 3:24:52 -0700, magnus.ihse.bursie at oracle.com:
>> I think the distinction you ask for is already there. The two separate
>> make targets "docs-javadoc" and "docs-reference" builds two distinct
>> images "docs" and "javase-docs", respectively. The first of these builds
>> the complete Java SE + JDK documentation, the second build just the Java
>> SE documentation.
> I'm glad that there's an SE-only target, but that's not what I asked
> for.
>
>> I do not think it's a good idea to go further and actually *remove* the
>> Java SE part from the complete "docs" image.
> That's not what I asked for, either.  I suggested making a stronger
> distinction between the specifications of the SE APIs and those of the
> rest of the JDK, by putting the latter in a subdirectory of the same
> image.  Sorry if that wasn't clear.
>
>>                                               Upholding such a formal
>> difference between different parts of the JDK is likely to be just
>> confusing to common Java developers. I believe that enforcing such a cut
>> would eliminate much of the work that has been put into giving the the
>> Java developer community a unified access to all releveant documentation.
> I see your point, but failing to make a strong distinction could also
> confuse developers, since it may lead some to use JDK-specific APIs when
> they really want to write code that's portable to any SE implementation.
>
> Still, there may be better ways to make that distinction, as Jon suggests
> nearby.
>
>> With that said, we should change the heading so that only the
>> javase-docs image claims to be the SE specification.
> Yes, we must do that, at a bare minimum.
>
> - Mark