2017/4/3 3:24:52 -0700, magnus.ihse.bur...@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