# HG changeset patch
# User mr
# Date 1497889242 -7200
# Node ID 88a3b10827779a4a216ff5b373125c17631584ff
# Parent  f21f9c907adfc6b2b08873890866ba111d126a3a
8182408: Simplify the API-specification overview page
Reviewed-by: erikj, mchung, jrose, alanb

diff -r f21f9c907adf -r 88a3b1082777 make/Docs.gmk
--- a/make/Docs.gmk	Sat Jun 17 08:02:30 2017 +0100
+++ b/make/Docs.gmk	Mon Jun 19 18:20:42 2017 +0200
@@ -116,9 +116,9 @@
 # General text snippets
 
 FULL_COMPANY_NAME := Oracle and/or its affiliates
-COMPANY_ADDRESS := 500 Oracle Parkway<br>Redwood Shores, CA 94065 USA
+COMPANY_ADDRESS := 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 
-JAVA_PLATFORM := Java&trade; Platform
+JAVA_PLATFORM := Java Platform
 
 ifeq ($(IS_DRAFT), true)
   DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong>
@@ -127,46 +127,44 @@
   else
     DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)]
   endif
-  DRAFT_TEXT := Please note that the specifications and other information \
-      contained herein are not final and are subject to change. The \
-      information is being made available to you solely for purpose of \
-      evaluation.
+  DRAFT_TEXT := This specification is not final and is subject to change. \
+      Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
 endif
 
 JAVADOC_BOTTOM := \
-    <span style="font-size:smaller"> \
-    <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature</a><br> \
-    For further API reference and developer documentation, see \
+    <a href="$(BUG_SUBMIT_URL)">Report a bug or suggest an enhancement</a><br> \
+    For further API reference and developer documentation see the \
     <a href="$(JAVADOC_BASE_URL)" target="_blank">Java SE \
-    Documentation</a>. That documentation contains more detailed, \
-    developer-targeted descriptions, with conceptual overviews, definitions \
+    Documentation</a>, which contains more detailed, \
+    developer-targeted descriptions with conceptual overviews, definitions \
     of terms, workarounds, and working code examples.<br> \
     Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \
     the US and other countries.<br> \
     <a href="$(COPYRIGHT_URL)">Copyright</a> \
-    &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME). \
-    $(COMPANY_ADDRESS). All rights reserved. \
-    Use is subject to <a href="$(LICENSE_URL)">license terms</a>. Also see the \
+    &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \
+    $(COMPANY_ADDRESS).<br>All rights reserved. \
+    Use is subject to <a href="$(LICENSE_URL)">license terms</a> and the \
     <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
-    $(DRAFT_MARKER_STR)</span>
+    $(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
+
 
 JAVADOC_TOP := \
-    <div style="background-color: $(HASH)EEEEEE"><div style="padding: 6px; \
-    margin-top: 2px; margin-bottom: 6px; margin-left: 6px; margin-right: \
-    6px; text-align: justify; font-size: 80%; font-family: Helvetica, Arial, \
-    sans-serif; font-weight: normal;">$(DRAFT_TEXT)</div></div>
+    <div style="padding: 6px; text-align: center; font-size: 80%; \
+    font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
+    font-weight: normal;">$(DRAFT_TEXT)</div>
 
 ################################################################################
 # JDK javadoc titles/text snippets
 
-JDK_SHORT_NAME := JDK&trade; $(VERSION_SPECIFICATION)
-JDK_LONG_NAME := Standard Edition Development Kit (JDK&trade;) $(VERSION_SPECIFICATION)
+JDK_SHORT_NAME := Java SE $(VERSION_SPECIFICATION) &amp; JDK $(VERSION_SPECIFICATION)
+JDK_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition \
+    <span style="white-space: nowrap;">&amp; Java Development Kit</span>
 
 ################################################################################
 # Java SE javadoc titles/text snippets
 
-JAVASE_SHORT_NAME := SE $(VERSION_SPECIFICATION)
-JAVASE_LONG_NAME := Standard Edition $(VERSION_SPECIFICATION)
+JAVASE_SHORT_NAME := Java SE $(VERSION_SPECIFICATION)
+JAVASE_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition
 
 ################################################################################
 # Functions
@@ -199,23 +197,19 @@
   $1_OVERVIEW_TEXT := \
       <!DOCTYPE html> \
       <html><head></head><body> \
-      <p>This document is the API specification for $$($1_FULL_NAME).</p> \
       #
   ifneq ($$($1_GROUPS),)
     $1_OVERVIEW_TEXT += \
-        <dl> \
-        #
+      <p>This document is divided into \
+      $$(subst 2,two,$$(subst 3,three,$$(words $$($1_GROUPS)))) sections:</p> \
+      <blockquote><dl> \
+      #
     $1_OVERVIEW_TEXT += $$(foreach g, $$($1_GROUPS), \
-        <dt><a href="\#$$g">$$($$g_GROUP_NAME)</a></dt> \
-        <dd>$$($$g_GROUP_DESCRIPTION)</dt> \
+        <dt style="margin-top: 8px;"><a href="\#$$g">$$($$g_GROUP_NAME)</a></dt> \
+        <dd style="margin-top: 8px;">$$($$g_GROUP_DESCRIPTION)</dt> \
     )
     $1_OVERVIEW_TEXT += \
-        </dl> \
-        #
-  endif
-  ifeq ($$(IS_DRAFT), true)
-    $1_OVERVIEW_TEXT += \
-        <p><strong>$$(DRAFT_TEXT)</strong></p> \
+        </dl><blockquote> \
         #
   endif
   $1_OVERVIEW_TEXT += \
@@ -273,13 +267,16 @@
   $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \
       $$(JAVADOC_DISABLED_DOCLINT)))
 
-  $1_FULL_NAME := $$(JAVA_PLATFORM), $$($1_LONG_NAME) \
-      $$(DRAFT_MARKER_TITLE)
-  $1_DOC_TITLE := $$($1_FULL_NAME)<br>API Specification
-  $1_WINDOW_TITLE := $$(subst &trade;,,$$(JAVA_PLATFORM) $$($1_SHORT_NAME)) \
+  $1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API Specification
+  $1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME)) \
     $$(DRAFT_MARKER_TITLE)
-  $1_HEADER_TITLE := <strong>$$(JAVA_PLATFORM)<br>$$($1_SHORT_NAME)</strong> \
-      $$(DRAFT_MARKER_STR)
+  ifeq ($(VERSION_IS_GA), true) # Workaround stylesheet bug
+    $1_HEADER_PAD := 14
+  else
+    $1_HEADER_PAD := 9
+  endif
+  $1_HEADER_TITLE := <div style="margin-top: $$($1_HEADER_PAD)px;"><strong>$$($1_SHORT_NAME)</strong> \
+      $$(DRAFT_MARKER_STR)</div>
 
   $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)'
   $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)'
@@ -373,18 +370,18 @@
 JavaSE_GROUP_MODULES := $(call ColonList, $(sort java.se.ee \
     $(call FindTransitiveIndirectDepsForModules, java.se.ee)))
 JavaSE_GROUP_DESCRIPTION := \
-    The Java Platform, Standard Edition ("Java SE") APIs define the core Java \
-    platform for general-purpose computing. These APIs are in modules with \
-    names starting with the string "java.". \
+    The Java Platform, Standard Edition (Java SE) APIs define the core Java \
+    platform for general-purpose computing. These APIs are in modules whose \
+    names start with {@code java}. \
     #
 JDK_GROUPS += JavaSE
 
 JDK_GROUP_NAME := JDK
 JDK_GROUP_MODULES := jdk.*
 JDK_GROUP_DESCRIPTION := \
-    The Java Development Kit ("JDK") APIs define an implementation of the Java \
-    SE Platform which may include platform-specific details. These APIs are in \
-    modules with names starting with the string "jdk.". \
+    The Java Development Kit (JDK) APIs are specific to the JDK and will not \
+    necessarily be available in all implementations of the Java SE Platform. \
+    These APIs are in modules whose names start with {@code jdk}. \
     #
 JDK_GROUPS += JDK
 
@@ -395,9 +392,9 @@
   JavaFX_GROUP_NAME := JavaFX
   JavaFX_GROUP_MODULES := javafx.*
   JavaFX_GROUP_DESCRIPTION := \
-      The JavaFX APIs define a set of user interface (UI) controls, graphics, \
+      The JavaFX APIs define a set of user-interface controls, graphics, \
       media, and web packages for developing rich client applications. These \
-      APIs are in modules with names starting with the string "javafx.". \
+      APIs are in modules whose names start with {@code javafx}. \
       #
   JDK_GROUPS += JavaFX
 endif
@@ -419,7 +416,7 @@
 ################################################################################
 # Setup generation of the Java SE API documentation (javadoc + modulegraph)
 
-# The Java SE module scope is just java.se.ee and it's transitive indirect
+# The Java SE module scope is just java.se.ee and its transitive indirect
 # exports.
 JAVASE_MODULES := java.se.ee