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

[mark.reinhold at oracle.com]

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