Annotate the public/confidential/shared parts of the BE template. Rewrite some examples that used internal labels to be safe for external version. Also remove some obsolete parts such as no-longer existent Make variables. -- MOS_MIGRATED_REVID=87241538

diff --git a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
index fb52a4c..e80b2c5 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java

@@ -59,21 +59,16 @@
    */
   public void generateDocumentation(String[] inputDirs, String outputRootDir)
       throws BuildEncyclopediaDocException, IOException {
-    BufferedWriter bw = null;
     File buildEncyclopediaPath = setupDirectories(outputRootDir);
-    try {
-      bw = new BufferedWriter(new FileWriter(buildEncyclopediaPath));
+    try (BufferedWriter bw = new BufferedWriter(new FileWriter(buildEncyclopediaPath))) {
       bw.write(DocgenConsts.HEADER_COMMENT);
+      bw.write("\n");  // for the benefit of the block-beginning comment at the top of the template
 
       Set<RuleDocumentation> ruleDocEntries = collectAndProcessRuleDocs(inputDirs, false);
       writeRuleClassDocs(ruleDocEntries, bw);
 
+      bw.write("\n");  // for the benefit of the block-beginning comment at the top of the template
       bw.write(SourceFileReader.readTemplateContents(DocgenConsts.FOOTER_TEMPLATE));
-
-    } finally {
-      if (bw != null) {
-        bw.close();
-      }
     }
   }
 
@@ -196,6 +191,7 @@
       }
     }
 
+    bw.write("\n");  // for the benefit of the block-beginning comment at the top of the template
     bw.write(SourceFileReader.readTemplateContents(DocgenConsts.HEADER_TEMPLATE,
         generateBEHeaderMapping(docEntries)));
 
@@ -205,6 +201,7 @@
         DocgenConsts.VAR_SECTION_TEST,     getRuleDocs(testDocs),
         DocgenConsts.VAR_SECTION_GENERATE, getRuleDocs(generateDocs),
         DocgenConsts.VAR_SECTION_OTHER,    getRuleDocs(otherDocs));
+    bw.write("\n");  // for the benefit of the block-beginning comment at the top of the template
     bw.write(SourceFileReader.readTemplateContents(DocgenConsts.BODY_TEMPLATE, sectionMapping));
   }
 

diff --git a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
index a2e7583..161d7b6 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java

@@ -13,6 +13,8 @@
 // limitations under the License.
 package com.google.devtools.build.docgen;
 
+import com.google.common.base.Joiner;
+import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.devtools.build.lib.util.FileType;
 import com.google.devtools.build.lib.util.FileTypeSet;
@@ -62,13 +64,16 @@
   public static final String FLAG_DEPRECATED = "DEPRECATED";
   public static final String FLAG_GENERIC_RULE = "GENERIC_RULE";
 
-  public static final String HEADER_COMMENT =
-      "<!DOCTYPE html>\n"
-      + "<!--\n"
-      + " This document is synchronized with Blaze releases.\n"
-      + " To edit, submit changes to the Blaze source code.\n"
-      + " Generated by: blaze build java/com/google/devtools/build/docgen:build-encyclopedia.html\n"
-      + "-->\n";
+  public static final String HEADER_COMMENT = Joiner.on("\n").join(ImmutableList.<String>of(
+      "<!-- begin-block:shared -->",
+      "<!DOCTYPE html>",
+      "<!--",
+      " This document is synchronized with Blaze releases.",
+      " To edit, submit changes to the Blaze source code.",
+      "-->",
+      "",
+      "<!-- begin-block:internal -->",
+      "<!-- Generated by //java/com/google/devtools/build/docgen:build-encyclopedia.html -->"));
 
   public static final String BUILD_ENCYCLOPEDIA_NAME = "build-encyclopedia.html";