docs: Add a section for evolving gflags

This patch adds a new section for evolving gflags in the documentation
and changes some of the XSLT logic to be more consistent.

It would be nice to replace the XSLT with a Python script.

Change-Id: I791d91e4f7ace4483958d26a60817857899fb474
Reviewed-on: http://gerrit.cloudera.org:8080/6489
Tested-by: Kudu Jenkins
Reviewed-by: Will Berkeley <[email protected]>

docs/configuration_reference.adoc

@@ -28,9 +28,9 @@
 :sectlinks:
 :experimental:
 
-The contents of this file are generated from the output of the `--helpxml`
-flag for each binary, during the build of the documentation. Do not edit this file
-or the included files manually.
+// The contents of this file are generated from the output of the `--helpxml`
+// flag for each binary, during the build of the documentation. Do not edit
+// this file or the included files manually.
 
 // This gets replaced by the script that builds the docs
 @@CONFIGURATION_REFERENCE@@

docs/configuration_reference_unsupported.adoc

@@ -27,12 +27,12 @@
 :sectlinks:
 :experimental:
 
-The contents of this file are generated from the output of the `--helpxml`
-flag for each binary, during the build of the documentation. Do not edit this file
-or the included files manually.
+// The contents of this file are generated from the output of the `--helpxml`
+// flag for each binary, during the build of the documentation. Do not edit
+// this file or the included files manually.
 
 WARNING: These flags are unsupported and are included for informational purposes only.
-They are subject to change or be removed at any time.
+They are subject to being changed or removed at any time.
 
 // This gets replaced by the script that builds the docs
 @@CONFIGURATION_REFERENCE@@

docs/support/scripts/make_docs.sh

@@ -146,7 +146,7 @@ for binary in ${binaries[@]}; do
   # Create the supported config reference
   xsltproc \
     --stringparam binary $binary \
-    --stringparam support-level stable \
+    --stringparam support-level supported \
     -o $GEN_DOC_DIR/${binary}_configuration_reference.adoc \
       $SOURCE_ROOT/docs/support/xsl/gflags_to_asciidoc.xsl \
     ${GEN_DOC_DIR}/$binary.xml
@@ -184,7 +184,7 @@ cp $SOURCE_ROOT/docs/images/* "$OUTPUT_DIR/images/"
 
 echo
 echo ----------------------------
-echo "Docs built in $OUTPUT_DIR."
+echo "Docs built in $OUTPUT_DIR"
 
 # If we're building the site, try to run Jekyll for them to make
 # it a bit easier to quickly preview the results.

docs/support/xsl/gflags_to_asciidoc.xsl

@@ -59,16 +59,22 @@ limitations under the License.
 :sectlinks:
 :experimental:
 
-<xsl:if test="$support-level = 'stable'">
-[[<xsl:value-of select="$binary"/>_stable]]
+<!--start supported -->
+<xsl:if test="$support-level = 'supported'">
+[[<xsl:value-of select="$binary"/>_supported]]
 = `<xsl:value-of select="$binary"/>` Flags
 
+[[<xsl:value-of select="$binary"/>_stable]]
 == Stable Flags
 
 Flags tagged `stable` and not `advanced` are safe to use for common
 configuration tasks.
 
-<xsl:for-each select="flag"><xsl:if test="contains(tags, 'stable') and not(contains(tags, 'advanced')) and not(contains(tags, 'hidden'))">
+<xsl:for-each select="flag">
+  <xsl:if test="contains(tags, 'stable') and
+                not(contains(tags, 'advanced')) and
+                not(contains(tags, 'hidden')) and
+                not(contains(tags, 'unsafe'))">
 [[<xsl:value-of select="$binary"/>_<xsl:value-of select="name"/>]]
 === `--<xsl:value-of select="name"/>`
 
@@ -82,7 +88,7 @@ configuration tasks.
 |===
 {nbsp}
 
-</xsl:if>
+  </xsl:if>
 </xsl:for-each>
 
 
@@ -92,7 +98,11 @@ configuration tasks.
 Flags tagged `stable` and `advanced` are supported, but should be considered
 "expert" options and should be used carefully and after thorough testing.
 
-<xsl:for-each select="flag"><xsl:if test="contains(tags, 'stable') and contains(tags, 'advanced') and not(contains(tags, 'hidden'))">
+<xsl:for-each select="flag">
+  <xsl:if test="contains(tags, 'stable') and
+                contains(tags, 'advanced') and
+                not(contains(tags, 'hidden')) and
+                not(contains(tags, 'unsafe'))">
 [[<xsl:value-of select="$binary"/>_<xsl:value-of select="name"/>]]
 === `--<xsl:value-of select="name"/>`
 
@@ -106,21 +116,55 @@ Flags tagged `stable` and `advanced` are supported, but should be considered
 |===
 {nbsp}
 
-</xsl:if>
+  </xsl:if>
 </xsl:for-each>
+
+[[<xsl:value-of select="$binary"/>_evolving]]
+== Evolving Flags
+
+Flags tagged `evolving` (or not tagged with a stability tag) are not yet
+considered final, and while they may be useful for tuning, they are subject to
+being changed or removed without notice.
+
+<xsl:for-each select="flag">
+  <xsl:if test="not(contains(tags, 'stable')) and
+                not(contains(tags, 'experimental')) and
+                not(contains(tags, 'hidden')) and
+                not(contains(tags, 'unsafe'))">
+[[<xsl:value-of select="$binary"/>_<xsl:value-of select="name"/>]]
+=== `--<xsl:value-of select="name"/>`
+
+<xsl:value-of select="meaning"/>
+
+[cols="1h,3d", width="50%"]
+|===
+| Type | <xsl:value-of select="type"/>
+| Default | <xsl:choose><xsl:when test="default != ''">`<xsl:value-of select="default"/>`</xsl:when><xsl:otherwise>none</xsl:otherwise></xsl:choose>
+| Tags | <xsl:value-of select="tags"/>
+|===
+{nbsp}
+
+  </xsl:if>
+</xsl:for-each>
+
 '''
 </xsl:if>
-<!--end stable -->
+<!--end supported -->
 
 <!-- start unsupported -->
 <xsl:if test="$support-level = 'unsupported'">
 [[<xsl:value-of select="$binary"/>_unsupported]]
 = `<xsl:value-of select="$binary"/>` Unsupported Flags
 
-Flags marked `advanced` or `experimental` and not marked `stable`, or flags with no stability tag, are *unsupported* and are included
-for informational purposes only. They are subject to change or be removed without notice.
+Flags not marked `stable` or `evolving` are considered experimental and are
+*unsupported*. They are included here for informational purposes only and are
+subject to being changed or removed without notice.
 
-<xsl:for-each select="flag"><xsl:if test="not(contains(tags, 'stable')) and (contains(tags, 'advanced') or contains(tags, 'experimental')) and not(contains(tags, 'hidden'))">
+<xsl:for-each select="flag">
+  <xsl:if test="not(contains(tags, 'stable')) and
+                not(contains(tags, 'evolving')) and
+                not(contains(tags, 'hidden')) and
+                not(contains(tags, 'unsafe'))">
 [[<xsl:value-of select="$binary"/>_<xsl:value-of select="name"/>]]
 == `--<xsl:value-of select="name"/>`
 
@@ -132,7 +176,7 @@ for informational purposes only. They are subject to change or be removed withou
 | Default | <xsl:choose><xsl:when test="default != ''">`<xsl:value-of select="default"/>`</xsl:when><xsl:otherwise>none</xsl:otherwise></xsl:choose>
 | Tags | <xsl:value-of select="tags"/>
 |===
-</xsl:if>
+  </xsl:if>
 </xsl:for-each>
 '''
 </xsl:if>