8295914: Add a header to generated HTML files in specs

Reviewed-by: erikj, iris

make/Docs.gmk

@@ -593,6 +593,9 @@ ifeq ($(ENABLE_PANDOC), true)
   # html, if we have pandoc (otherwise we'll just skip this).
 
   GLOBAL_SPECS_DEFAULT_CSS_FILE := $(DOCS_OUTPUTDIR)/resources/jdk-default.css
+  # Unset the following to suppress the link to the tool guides
+  NAV_LINK_GUIDES := --nav-link-guides
+  HEADER_RIGHT_SIDE_INFO := '<strong>$(subst &amp;,&,$(JDK_SHORT_NAME))$(DRAFT_MARKER_STR)</strong>'
 
   $(foreach m, $(ALL_MODULES), \
     $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
@@ -609,7 +612,8 @@ ifeq ($(ENABLE_PANDOC), true)
             REPLACEMENTS := \
 		@@VERSION_SPECIFICATION@@ => $(VERSION_SPECIFICATION) ; \
 		@@VERSION_STRING@@ => $(VERSION_STRING), \
-            POST_PROCESS := $(TOOL_FIXUPPANDOC), \
+            POST_PROCESS := $(TOOL_FIXUPPANDOC) --insert-nav --nav-right-info $(HEADER_RIGHT_SIDE_INFO) \
+                --nav-subdirs $($m_$f_NOF_SUBDIRS) $(NAV_LINK_GUIDES), \
         )) \
         $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \
       ) \
@@ -643,7 +647,8 @@ ifeq ($(ENABLE_PANDOC), true)
 		@@VERSION_SHORT@@ => $(VERSION_SHORT) ; \
 		@@VERSION_SPECIFICATION@@ => $(VERSION_SPECIFICATION), \
             OPTIONS := --toc -V include-before='$(SPECS_TOP)' -V include-after='$(SPECS_BOTTOM_1)', \
-            POST_PROCESS := $(TOOL_FIXUPPANDOC), \
+            POST_PROCESS := $(TOOL_FIXUPPANDOC) --insert-nav --nav-right-info $(HEADER_RIGHT_SIDE_INFO) \
+                --nav-subdirs 1 --nav-link-guides, \
             EXTRA_DEPS := $(PANDOC_HTML_MANPAGE_FILTER) \
                 $(PANDOC_HTML_MANPAGE_FILTER_SOURCE), \
         )) \

make/data/docs-resources/resources/jdk-default.css

@@ -157,7 +157,6 @@ table.centered td {
   font-size: 80%;
   padding: 6px;
   margin: -2.5em -2.5em 2.5em -2.5em;
-  background-color: #CBDAE4;
 }
 
 .legal-footer {
@@ -183,3 +182,55 @@ nav#TOC ul ul li {
 nav#TOC ul ul li::before {
     content: " \2022  "
 }
+
+header#title-block-header {
+    margin-top:-2em;
+}
+
+header#title-block-header div.navbar {
+    margin: 0 -2.5em 2.5em -2.5em;
+    padding: 0 2.5em;
+    background-color:#4D7A97;
+    color:#FFFFFF;
+    float:left;
+    width:100%;
+    clear:right;
+    min-height:2.8em;
+    padding-top:10px;
+    overflow:hidden;
+    font-size:12px;
+}
+
+header#title-block-header div.navbar div {
+    float:right;
+    font-size:11px;
+    height:2.9em;
+    margin: auto 0;
+}
+
+header#title-block-header ul {
+    display:block;
+    margin:0 25px 0 0;
+    padding:0;
+}
+header#title-block-header ul li {
+    list-style:none;
+    float:left;
+    padding: 5px 6px;
+    text-transform:uppercase;
+}
+
+header#title-block-header li.no-link {
+    background-color:#F8981D;
+    color:#253441;
+    margin: auto 5px;
+}
+
+header#title-block-header a:link, header#title-block-header a:active, header#title-block-header a:visited {
+    color:#ffffff;
+    text-decoration:none;
+    text-transform:uppercase;
+}
+header#title-block-header a:hover {
+    color:#bb7a2a;
+}

make/jdk/src/classes/build/tools/fixuppandoc/Main.java

@@ -37,6 +37,7 @@ import java.io.Writer;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
 import java.util.List;
@@ -46,6 +47,8 @@ import java.util.Objects;
 import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
 import static java.nio.charset.StandardCharsets.UTF_8;
 
 /**
@@ -120,21 +123,31 @@ public class Main {
     private void run(String... args) throws IOException {
         Path inFile = null;
         Path outFile = null;
+        NavBar navbar = null;
 
         for (int i = 0; i < args.length; i++) {
             String arg = args[i];
             if (arg.equals("-o") && i + 1 < args.length) {
                 outFile = Path.of(args[++i]);
+            } else if (arg.equals("--insert-nav")) {
+                navbar = new NavBar();
+            } else if (arg.equals("--nav-right-info") && i + 1 < args.length) {
+                navbar.rightSideInfo(args[++i]);
+            } else if (arg.equals("--nav-subdirs") && i + 1 < args.length) {
+                navbar.subdirs(Integer.parseInt(args[++i]));
+            } else if (arg.equals("--nav-link-guides")) {
+                navbar.linkGuides(true);
             } else if (arg.startsWith("-")) {
                 throw new IllegalArgumentException(arg);
             } else if (inFile == null) {
                 inFile = Path.of(arg);
             } else {
+                System.err.println("ARGV: " + Arrays.toString(args));
                 throw new IllegalArgumentException(arg);
             }
         }
 
-        new Fixup().run(inFile, outFile);
+        new Fixup(navbar).run(inFile, outFile);
     }
 
     /**
@@ -148,6 +161,9 @@ public class Main {
         /** A stream for reporting errors. */
         PrintStream err = System.err;
 
+        /** A manager for the navigation bar, null if not required. */
+        NavBar navbar;
+
         /**
          * Flag to indicate when {@code <main>} is permitted around palpable content.
          * Set within {@code <body>}; disabled within elements in which {@code <main>}
@@ -174,6 +190,10 @@ public class Main {
          */
         Table table;
 
+        Fixup(NavBar navbar) {
+            this.navbar = navbar;
+        }
+
         /**
          * Run the program, copying an input file to an output file.
          * If the input file is {@code null}, input is read from the standard input.
@@ -282,7 +302,10 @@ public class Main {
                     }
                     // <main> is not permitted within these elements
                     allowMain = false;
-                    if (name.equals("nav") && Objects.equals(attrs.get("id"), "TOC")) {
+                    if (navbar != null && name.equals("header") && Objects.equals(attrs.get("id"), "title-block-header")) {
+                        flushBuffer();
+                        navbar.write(out);
+                    } else if (name.equals("nav") && Objects.equals(attrs.get("id"), "TOC")) {
                         out.write(buffer.toString()
                                 .replaceAll(">$", " title=\"Table Of Contents\">"));
                         buffer.setLength(0);
@@ -436,6 +459,65 @@ public class Main {
         }
     }
 
+    class NavBar {
+        private int subdirs = 0;
+        private boolean linkGuides = false;
+        private String rightSideInfo = "";
+
+        void subdirs(int subdirs) {
+            this.subdirs = subdirs;
+        }
+
+        void linkGuides(boolean linkGuides) {
+            this.linkGuides = linkGuides;
+        }
+
+        void rightSideInfo(String rightSideInfo) {
+            this.rightSideInfo = rightSideInfo;
+        }
+
+        void write(PrintWriter out) {
+            get().lines().forEach(out::println);
+        }
+
+        String get() {
+            String pathToSpecs = "../".repeat(subdirs);
+            String api = pathToSpecs + "../api/index.html";
+            String specs = pathToSpecs + "index.html";
+            String guides = pathToSpecs + "man/index.html";
+
+            StringBuilder sb = new StringBuilder();
+            sb.append("\n");
+            sb.append("<div class=\"navbar\">"); // full enclosing banner
+            if (rightSideInfo != null) {
+                sb.append("<div>").append(rightSideInfo).append("</div>");
+            }
+            sb.append("<nav>"); // nav links
+            var links = new ArrayList<>(List.of(
+                    link(api, "API"),
+                    link(specs, "OTHER SPECIFICATIONS")
+                ));
+            if (linkGuides) {
+                links.add(link(guides, "TOOL GUIDES"));
+            }
+            sb.append(list(links));
+            sb.append("</nav>");
+            sb.append("</div>");
+            sb.append("\n");
+            return sb.toString();
+        }
+
+        String list(List<String> items) {
+            return items.stream()
+                    .map(i -> "<li>" + i)
+                    .collect(Collectors.joining("\n", "<ul>", "</ul>"));
+        }
+
+        private String link(String href, String label) {
+            return "<a href=\"" + href + "\">" + label + "</a>";
+        }
+    }
+
     /**
      * Storage for the content of a {@code <table>} element} until we can determine
      * whether we should add {@code scope="row"} to the cells in a given column,