From f71c7a80327c6a733634310e22f6be56b1de37e4 Mon Sep 17 00:00:00 2001
From: "David B. Kinder" <david.b.kinder@intel.com>
Date: Wed, 20 Apr 2022 14:09:22 -0700
Subject: [PATCH] doc: use DX-friendly names in configuration option
 documentation

Change the generated config option documentation to use the DX-friendly
names defined for the configurator UI (instead of the XML element name
hierarchy previously used).

Options are grouped by the top-level section (aka complex type) they
belong to and then sorted alphabetically with these groups.

Use badges to indicate where options can be found in the configurator UI
and whether they're applicable to the Hypervisor or Pre/Post/Service VM.
Add a custom css style for the config-option doc that puts the first
paragraph of a glossary item on the same line as the glossary term so
these badges look pretty.

Added a acrn-custom.js patch that copies the alt text for images into a
title property for images within the config-doc document.  This provides
tooltip text when hovering over the badges.

Don't display options not visible in the configurator UI (elements with
acrn:views="").

A missing acrn:views or acrn:applicable-vm means we look for an
applicable value from an ancestor element.

Add processing of a second xs:documentation element within an
xs:annotation element. This second documentation element's content will
be appended as a new paragraph to the first xs:documentation content in
the generated documentation. Only the first xs:documentation element is
used by the Configurator for its tooltips.

Update documents that were referring to options by their XML names.

Because we're now using a glossary to provide links to config options,
we can't duplicate option names or glosary names anywhere in the doc
set.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
---
 doc/developer-guides/doc_guidelines.rst   |   6 +-
 doc/glossary.rst                          |   1 -
 doc/reference/config-options.rst          |  48 ++-
 doc/reference/images/Advanced.svg         |   1 +
 doc/reference/images/Basic.svg            |   1 +
 doc/reference/images/Hypervisor.svg       |   1 +
 doc/reference/images/Not-available.svg    |   1 +
 doc/reference/images/Post-launched-VM.svg |   1 +
 doc/reference/images/Pre-launched-VM.svg  |   1 +
 doc/reference/images/README               |   3 +
 doc/reference/images/Service-VM.svg       |   1 +
 doc/scripts/configdoc.xsl                 | 398 ++++++++++++----------
 doc/static/acrn-custom.css                |  28 ++
 doc/static/acrn-custom.js                 |   5 +
 doc/tutorials/nvmx_virtualization.rst     |  10 +-
 doc/tutorials/vcat_configuration.rst      |  10 +-
 16 files changed, 328 insertions(+), 188 deletions(-)
 create mode 100644 doc/reference/images/Advanced.svg
 create mode 100644 doc/reference/images/Basic.svg
 create mode 100644 doc/reference/images/Hypervisor.svg
 create mode 100644 doc/reference/images/Not-available.svg
 create mode 100644 doc/reference/images/Post-launched-VM.svg
 create mode 100644 doc/reference/images/Pre-launched-VM.svg
 create mode 100644 doc/reference/images/README
 create mode 100644 doc/reference/images/Service-VM.svg

diff --git a/doc/developer-guides/doc_guidelines.rst b/doc/developer-guides/doc_guidelines.rst
index 749b38834..481423585 100644
--- a/doc/developer-guides/doc_guidelines.rst
+++ b/doc/developer-guides/doc_guidelines.rst
@@ -751,9 +751,9 @@ During the documentation ``make html`` processing, the documentation annotations
 in the ``.xsd`` files are extracted and transformed into reStructuredText using
 an XSLT transformation found in ``doc/scripts/configdoc.xsl``. The generated
 option documentation is organized and formatted to make it easy to create links
-to specific option descriptions using an ``:option:`` role, for example,
-``:option:`hv.DEBUG_OPTIONS.BUILD_TYPE``` would link to
-:option:`hv.DEBUG_OPTIONS.BUILD_TYPE`.
+to specific option descriptions using an ``:term:`` role, for example,
+``:term::`Build type``` would link to
+:term:`Build type`.
 
 The transformed option documentation is
 created in the ``_build/rst/reference/configdoc.txt`` file and included by
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 350359676..8921490a4 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -177,7 +177,6 @@ Glossary of Terms
       post-launched standard, and post-launched real-time.  *(Historically, a
       User VM was also called a User OS, or simply UOS.)*
 
-   VM
    Virtual Machine
      A compute resource that uses software instead of physical hardware to run a
      program. Multiple VMs can run independently on the same physical machine,
diff --git a/doc/reference/config-options.rst b/doc/reference/config-options.rst
index ba848e177..e3809d5fa 100644
--- a/doc/reference/config-options.rst
+++ b/doc/reference/config-options.rst
@@ -20,8 +20,7 @@ Within this option documentation, we refer to some common type
 definitions:
 
 Boolean
-  A true or false value specified as either ``y`` or ``n``. Other
-  values such as ``t`` or ``f`` are not supported.
+  A true or false value specified as either ``y`` or ``n``.
 
 Hexadecimal
   A base-16 (integer) value represented by a leading ``0x`` or ``0X`` followed by
@@ -36,6 +35,51 @@ String
   A sequence of UTF-8 characters.  String-length limits or specific
   string value restrictions are defined in the option description.
 
+.. comment These images are used in generated option documentation
+
+.. |icon-advanced| image:: images/Advanced.svg
+   :alt: Find this option on the Configurator's Advanced Parameters tab
+.. |icon-basic| image:: images/Basic.svg
+   :alt: Find this option on the Configurator's Basic Parameters tab
+.. |icon-not-available| image:: images/Not-available.svg
+   :alt: This is a hidden option and not user-editable using the Configurator
+.. |icon-post-launched-vm| image:: images/Post-launched-VM.svg
+   :alt: Find this option on a Configurator Post-launched VM tab
+.. |icon-pre-launched-vm| image:: images/Pre-launched-VM.svg
+   :alt: Find this option on a Configurator Pre-launched VM tab
+.. |icon-service-vm| image:: images/Service-VM.svg
+   :alt: Find this option on the Configurator Service VM tab
+.. |icon-hypervisor| image:: images/Hypervisor.svg
+   :alt: Find this option on the Configurator's Hypervisor Global Settings tab
+
+We use icons within an option description to indicate where the option can be
+found within the Configurator UI:
+
+.. list-table::
+   :header-rows: 1
+
+   * - **Hypervisor/VM Tab**
+     - **Basic/Advanced Tab**
+
+   * - |icon-hypervisor|
+         Find this option on the Configurator's **Hypervisor Global Settings** tab
+     - |icon-basic|
+           Find this option on the Hypervisor's or VM's **Basic Parameters** tab
+
+   * - |icon-pre-launched-vm|
+          Find this option on a Configurator **Pre-Launched VM** tab
+     - |icon-advanced|
+           Find this option on the Hypervisor's or VM's **Advanced Parameters** tab
+
+   * - |icon-post-launched-vm|
+           Find this option on a Configurator **Post-Launched VM** tab
+     -
+
+   * - |icon-service-vm|
+           Find this option on the Configurator **Service VM** tab
+     -
+
+-----
 
 .. comment This configdoc.txt is generated during the doc build process
    from the acrn config schema files found in misc/config_tools/schema
diff --git a/doc/reference/images/Advanced.svg b/doc/reference/images/Advanced.svg
new file mode 100644
index 000000000..ab87cdc5b
--- /dev/null
+++ b/doc/reference/images/Advanced.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="125" height="20" role="img" aria-label="Advanced Parameter"><title>Advanced Parameter</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="125" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#e05d44"/><rect x="0" width="125" height="20" fill="#e05d44"/><rect width="125" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="625" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="1150">Advanced Parameter</text><text x="625" y="140" transform="scale(.1)" fill="#fff" textLength="1150">Advanced Parameter</text></g></svg>
\ No newline at end of file
diff --git a/doc/reference/images/Basic.svg b/doc/reference/images/Basic.svg
new file mode 100644
index 000000000..d9b5a299b
--- /dev/null
+++ b/doc/reference/images/Basic.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="99" height="20" role="img" aria-label="Basic Parameter"><title>Basic Parameter</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="99" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#007ec6"/><rect x="0" width="99" height="20" fill="#007ec6"/><rect width="99" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="495" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="890">Basic Parameter</text><text x="495" y="140" transform="scale(.1)" fill="#fff" textLength="890">Basic Parameter</text></g></svg>
\ No newline at end of file
diff --git a/doc/reference/images/Hypervisor.svg b/doc/reference/images/Hypervisor.svg
new file mode 100644
index 000000000..0e4fa83c8
--- /dev/null
+++ b/doc/reference/images/Hypervisor.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="69" height="20" role="img" aria-label="Hypervisor"><title>Hypervisor</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="69" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#2b978f"/><rect x="0" width="69" height="20" fill="#2b978f"/><rect width="69" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="345" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="590">Hypervisor</text><text x="345" y="140" transform="scale(.1)" fill="#fff" textLength="590">Hypervisor</text></g></svg>
\ No newline at end of file
diff --git a/doc/reference/images/Not-available.svg b/doc/reference/images/Not-available.svg
new file mode 100644
index 000000000..490d214e2
--- /dev/null
+++ b/doc/reference/images/Not-available.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="185" height="20" role="img" aria-label="Not available in Configurator UI"><title>Not available in Configurator UI</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="185" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#9f9f9f"/><rect x="0" width="185" height="20" fill="#9f9f9f"/><rect width="185" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="925" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="1750">Not available in Configurator UI</text><text x="925" y="140" transform="scale(.1)" fill="#fff" textLength="1750">Not available in Configurator UI</text></g></svg>
\ No newline at end of file
diff --git a/doc/reference/images/Post-launched-VM.svg b/doc/reference/images/Post-launched-VM.svg
new file mode 100644
index 000000000..f2206aef6
--- /dev/null
+++ b/doc/reference/images/Post-launched-VM.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="109" height="20" role="img" aria-label="Post-launched VM"><title>Post-launched VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="109" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#998265"/><rect x="0" width="109" height="20" fill="#998265"/><rect width="109" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="545" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="990">Post-launched VM</text><text x="545" y="140" transform="scale(.1)" fill="#fff" textLength="990">Post-launched VM</text></g></svg>
\ No newline at end of file
diff --git a/doc/reference/images/Pre-launched-VM.svg b/doc/reference/images/Pre-launched-VM.svg
new file mode 100644
index 000000000..3e87e0b22
--- /dev/null
+++ b/doc/reference/images/Pre-launched-VM.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="103" height="20" role="img" aria-label="Pre-launched VM"><title>Pre-launched VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="103" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#4c1"/><rect x="0" width="103" height="20" fill="#4c1"/><rect width="103" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="515" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="930">Pre-launched VM</text><text x="515" y="140" transform="scale(.1)" fill="#fff" textLength="930">Pre-launched VM</text></g></svg>
\ No newline at end of file
diff --git a/doc/reference/images/README b/doc/reference/images/README
new file mode 100644
index 000000000..2557e6d0b
--- /dev/null
+++ b/doc/reference/images/README
@@ -0,0 +1,3 @@
+These icon badges were created using https://shields.io static badges.
+Standard colors were used except for the Hypervisor #69BFAD (acrn-lightgreen) and post-launched VM
+#998265 (acrn-brown) colors defined in the acrn-custom.css
diff --git a/doc/reference/images/Service-VM.svg b/doc/reference/images/Service-VM.svg
new file mode 100644
index 000000000..6ca6bd34f
--- /dev/null
+++ b/doc/reference/images/Service-VM.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="71" height="20" role="img" aria-label="Service VM"><title>Service VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="71" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#dfb317"/><rect x="0" width="71" height="20" fill="#dfb317"/><rect width="71" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="355" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="610">Service VM</text><text x="355" y="140" transform="scale(.1)" fill="#fff" textLength="610">Service VM</text></g></svg>
\ No newline at end of file
diff --git a/doc/scripts/configdoc.xsl b/doc/scripts/configdoc.xsl
index 2784c433d..67e7ede7f 100644
--- a/doc/scripts/configdoc.xsl
+++ b/doc/scripts/configdoc.xsl
@@ -1,165 +1,226 @@
 <?xml version="1.0" encoding="utf-8"?>
-
-<xsl:stylesheet
-    version="1.0"
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-    xmlns:xs="http://www.w3.org/2001/XMLSchema">
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:acrn="https://projectacrn.org" version="1.0">
   <xsl:output method="text"/>
-
-  <xsl:variable name="newline" select="'&#xa;'"/>
+  <xsl:variable name="newline" select="'&#10;'"/>
   <xsl:variable name="section_adornment" select="'#*=-%+@`'"/>
-
-  <xsl:variable name="vLower" select= "'abcdefghijklmnopqrstuvwxyz'"/>
-  <xsl:variable name="vUpper" select= "'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/>
-
-  <!--
-      Visitors of XSD elements
-  -->
-
+  <xsl:variable name="vLower" select="'abcdefghijklmnopqrstuvwxyz'"/>
+  <xsl:variable name="vUpper" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/>
+  <!-- xslt script to autogenerate config option documentation -->  
+  <!-- Get things started with the ACRNConfigType element -->
   <xsl:template match="/xs:schema">
-
     <xsl:apply-templates select="xs:complexType[@name='ACRNConfigType']">
       <xsl:with-param name="level" select="2"/>
       <xsl:with-param name="prefix" select="''"/>
+      <xsl:with-param name="parent" select="."/>
     </xsl:apply-templates>
-
   </xsl:template>
-
+  <!-- Walk through all the ACRNConfigType element's children -->
   <xsl:template match="xs:complexType[@name='ACRNConfigType']">
     <xsl:param name="level"/>
     <xsl:param name="prefix"/>
-
     <xsl:apply-templates select="descendant::xs:element">
       <xsl:with-param name="level" select="$level"/>
       <xsl:with-param name="prefix" select="$prefix"/>
+      <xsl:with-param name="parent" select="."/>
     </xsl:apply-templates>
   </xsl:template>
-
+  <!-- ... and process all the child elements -->
   <xsl:template match="xs:element">
     <xsl:param name="level"/>
     <xsl:param name="prefix"/>
-
+    <xsl:param name="parent"/>
     <xsl:variable name="ty">
       <xsl:choose>
-	<xsl:when test="@type">
-	  <xsl:value-of select="@type" />
-	</xsl:when>
-	<xsl:otherwise>
-	  <xsl:value-of select=".//xs:alternative[1]/@type" />
-	</xsl:otherwise>
+        <xsl:when test="@type">
+          <xsl:value-of select="@type"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select=".//xs:alternative[1]/@type"/>
+        </xsl:otherwise>
       </xsl:choose>
     </xsl:variable>
-
+    <!-- dxnamePure and dxname hold the element name with and without spaces converted to underscores -->
+    <xsl:variable name="dxnamePure">
+      <xsl:choose>
+        <xsl:when test=".//descendant::xs:annotation/@acrn:title">
+          <xsl:value-of select=".//descendant::xs:annotation/@acrn:title"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="@name"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:variable name="dxname">
+      <xsl:value-of select="translate($dxnamePure,' ','_')"/>
+    </xsl:variable>
     <!-- Only visit elements having complex types. Those having simple types are
-         described as an option.. -->
+         described as an option -->
     <xsl:choose>
       <xsl:when test="//xs:complexType[@name=$ty]">
-<!-- for top level sections (level 2) put a begin/end comment for
-     potential use in rst include directives -->
-       <xsl:if test="$level = 2">
-         <xsl:value-of select="concat('.. section-start ', $prefix, @name, $newline)"/>
-       </xsl:if>
-       <!-- The section header -->
-       <xsl:if test="$level &lt;= 4">
-         <xsl:call-template name="section-header">
-           <xsl:with-param name="title" select="concat($prefix, @name)"/>
-           <xsl:with-param name="label" select="concat($prefix, @name)"/>
-           <xsl:with-param name="level" select="$level"/>
-         </xsl:call-template>
-
-         <!-- Description of this menu / entry -->
-         <xsl:call-template name="print-annotation" >
+        <!-- The section header -->
+        <xsl:if test="$level &lt;= 4">
+          <xsl:call-template name="section-header">
+            <xsl:with-param name="title" select="$dxnamePure"/>
+            <xsl:with-param name="label" select="concat($prefix, $dxname)"/>
+            <xsl:with-param name="level" select="$level"/>
+          </xsl:call-template>
+          <!-- Description of this menu / entry -->
+          <xsl:call-template name="print-annotation">
             <xsl:with-param name="indent" select="''"/>
-         </xsl:call-template>
-
-         <xsl:value-of select="$newline"/>
-<!-- Occurence requirements (removed, but save just in case)
-         <xsl:call-template name="print-occurs">
-           <xsl:with-param name="name" select="@name"/>
-         </xsl:call-template>
--->
+          </xsl:call-template>
           <xsl:value-of select="$newline"/>
-       </xsl:if>
-
-       <!-- Visit the complex type to generate menus and/or entries -->
-       <xsl:apply-templates select="//xs:complexType[@name=$ty]">
-         <xsl:with-param name="level" select="$level"/>
-         <xsl:with-param name="name" select="concat($prefix, @name)"/>
-       </xsl:apply-templates>
-<!-- for top level sections (level 2) put a begin/end comment for
-     potential use in rst include directives -->
-       <xsl:if test="$level = 2">
-         <xsl:value-of select="concat('.. section-end ', $prefix, @name, $newline)"/>
-       </xsl:if>
+          <!-- use a sorted glossary to show a sorted list of config options in this section -->
+          <xsl:value-of select="concat('.. glossary::',$newline,' :sorted:',$newline,$newline)"/>
+        </xsl:if>
+        <!-- Visit the complex type to generate menus and/or entries -->
+        <xsl:apply-templates select="//xs:complexType[@name=$ty]">
+          <xsl:with-param name="level" select="$level"/>
+          <xsl:with-param name="name" select="concat($prefix, $dxname)"/>
+          <xsl:with-param name="parent" select="."/>
+        </xsl:apply-templates>
+      </xsl:when>
+      <xsl:when test="xs:annotation/@acrn:views=''">
+        <!-- don't document elements if not viewable -->
       </xsl:when>
       <xsl:otherwise>
-       <!-- Write a section header for elements with a simple type -->
+        <!-- No longer writing a section header for elements with a simple type
        <xsl:if test="$level = 3">
          <xsl:call-template name="section-header">
-           <xsl:with-param name="title" select="concat($prefix, @name)"/>
-           <xsl:with-param name="label" select="concat($prefix, @name)"/>
+           <xsl:with-param name="title" select="$dxnamePure"/>
+           <xsl:with-param name="label" select="concat($prefix, $dxname)"/>
            <xsl:with-param name="level" select="$level"/>
          </xsl:call-template>
-       </xsl:if>
-
-       <xsl:call-template name="option-header">
-         <xsl:with-param name="label" select="concat($prefix, @name)"/>
-       </xsl:call-template>
-       <xsl:value-of select="$newline"/>
-       <!-- Print the description, type, and occurrence requirements -->
-       <xsl:text>   - </xsl:text>
-       <xsl:call-template name="print-annotation" >
-          <xsl:with-param name="indent" select="'     '"/>
-       </xsl:call-template>
-       <xsl:choose>
-         <xsl:when test="//xs:simpleType[@name=$ty]">
-           <xsl:apply-templates select="//xs:simpleType[@name=$ty]"/>
-         </xsl:when>
-         <xsl:when test="starts-with($ty, 'xs:')">
-           <xsl:text>   - </xsl:text>
-           <xsl:value-of select="concat(translate(substring($ty, 4,1), $vLower, $vUpper), substring($ty,5))"/>
-           <xsl:value-of select="$newline"/>
-         </xsl:when>
-         <xsl:otherwise>
-<!-- element doesn't have a named type, check for an unnamed simpleType child -->
-           <xsl:apply-templates select="descendant::xs:simpleType">
-             <xsl:with-param name="level" select="$level"/>
-             <xsl:with-param name="prefix" select="''"/>
-           </xsl:apply-templates>
-         </xsl:otherwise>
-       </xsl:choose>
-<!-- removing occurs info for now
-       <xsl:text>   - </xsl:text>
-       <xsl:call-template name="print-occurs" >
-           <xsl:with-param name="name" select="@name"/>
-       </xsl:call-template>
+        </xsl:if> -->
+        <!-- print option as a glossary item -->
+        <!-- put a sortable character in front of options not available in UI -->
+        <!-- <xsl:if test="xs:annotation/@acrn:views=''">
+            <xsl:text> ~</xsl:text>
+        </xsl:if> -->
+        <xsl:value-of select="concat(' ',$dxnamePure,$newline)"/>
+        <!-- print icons for basic/advanced, hypervisor/VM applicability -->
+        <xsl:variable name="option-icons">
+          <!-- acrn:views describes if this option appears on a "basic" or "advanced" tab, or not at all
+                when the value is "".  If the acrn:views attribute is missing, then the containing parent's
+                acrn:views value is used instead. Similarly for the acrn:applicable-vms attribute.  -->
+          <xsl:choose>
+            <xsl:when test="contains($prefix,'Hypervisor')">
+              <xsl:text>|icon-hypervisor| </xsl:text>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:choose>
+                <xsl:when test="count(xs:annotation/@acrn:applicable-vms)=0">
+                  <xsl:if test="contains($parent/xs:annotation/@acrn:applicable-vms,'pre-launched') or contains($parent/../xs:annotation/@acrn:applicable-vms,'pre-launched') or    contains($parent/../../xs:annotation/@acrn:applicable-vms,'pre-launched')">
+                    <xsl:text>|icon-pre-launched-vm| </xsl:text>
+                  </xsl:if>
+                  <xsl:if test="contains($parent/xs:annotation/@acrn:applicable-vms,'post-launched') or  contains($parent/../xs:annotation/@acrn:applicable-vms,'post-launched') or  contains($parent/../../xs:annotation/@acrn:applicable-vms,'post-launched')">
+                    <xsl:text>|icon-post-launched-vm| </xsl:text>
+                  </xsl:if>
+                  <xsl:if test="contains($parent/xs:annotation/@acrn:applicable-vms,'service-vm') or  contains($parent/../xs:annotation/@acrn:applicable-vms,'service-vm') or      contains($parent/../../xs:annotation/@acrn:applicable-vms,'service-vm')">
+                    <xsl:text>|icon-service-vm| </xsl:text>
+                  </xsl:if>
+                </xsl:when>
+                <xsl:otherwise>
+                  <xsl:if test="contains(xs:annotation/@acrn:applicable-vms,'pre-launched')">
+                    <xsl:text>|icon-pre-launched-vm| </xsl:text>
+                  </xsl:if>
+                  <xsl:if test="contains(xs:annotation/@acrn:applicable-vms,'post-launched')">
+                    <xsl:text>|icon-post-launched-vm| </xsl:text>
+                  </xsl:if>
+                  <xsl:if test="contains(xs:annotation/@acrn:applicable-vms,'service-vm')">
+                    <xsl:text>|icon-service-vm| </xsl:text>
+                  </xsl:if>
+                </xsl:otherwise>
+              </xsl:choose>
+            </xsl:otherwise>
+          </xsl:choose>
+          <xsl:text>/ </xsl:text>
+          <xsl:if test="xs:annotation/@acrn:views=''">
+            <xsl:text>|icon-not-available| </xsl:text>
+          </xsl:if>
+          <xsl:if test="count(xs:annotation/@acrn:views)=0">
+            <xsl:if test="contains($parent/xs:annotation/@acrn:views,'basic') or  contains($parent/../xs:annotation/@acrn:views,'basic') or contains($parent/../../xs:annotation/@acrn:views,'basic')">
+              <xsl:text>|icon-basic| </xsl:text>
+            </xsl:if>
+            <xsl:if test="contains($parent/xs:annotation/@acrn:views,'advanced') or  contains($parent/../xs:annotation/@acrn:views,'advanced') or contains($parent/../../xs:annotation/@acrn:views,'advanced')">
+              <xsl:text>|icon-advanced| </xsl:text>
+            </xsl:if>
+          </xsl:if>
+          <xsl:if test="contains(xs:annotation/@acrn:views,'basic')">
+            <xsl:text>|icon-basic| </xsl:text>
+          </xsl:if>
+          <xsl:if test="contains(xs:annotation/@acrn:views,'advanced')">
+            <xsl:text>|icon-advanced| </xsl:text>
+          </xsl:if>
+        </xsl:variable>
+        <xsl:if test="$option-icons!=''">
+          <xsl:value-of select="concat('   ',$option-icons,$newline)"/>
+        </xsl:if>
+        <xsl:value-of select="$newline"/>
+        <!-- Print the description, type, and occurrence requirements -->
+        <xsl:text>   - </xsl:text>
+        <xsl:call-template name="print-annotation">
+          <xsl:with-param name="indent" select="'     '"/>
+        </xsl:call-template>
+        <xsl:choose>
+          <xsl:when test="//xs:simpleType[@name=$ty]">
+            <xsl:apply-templates select="//xs:simpleType[@name=$ty]">
+              <xsl:with-param name="level" select="$level"/>
+              <xsl:with-param name="prefix" select="''"/>
+              <xsl:with-param name="parent" select="$parent"/>
+            </xsl:apply-templates>
+          </xsl:when>
+          <xsl:when test="starts-with($ty, 'xs:')">
+            <xsl:text>   - </xsl:text>
+            <!-- if unnamed type such as xs:string or xs:integer, print that simple type name with an uppercase first letter -->
+            <xsl:value-of select="concat(translate(substring($ty, 4,1), $vLower, $vUpper), substring($ty,5),' value')"/>
+            <xsl:value-of select="$newline"/>
+          </xsl:when>
+          <xsl:otherwise>
+            <!-- element doesn't have a named type, check for an unnamed simpleType child -->
+            <xsl:apply-templates select="descendant::xs:simpleType">
+              <xsl:with-param name="level" select="$level"/>
+              <xsl:with-param name="prefix" select="''"/>
+              <xsl:with-param name="parent" select="$parent"/>
+            </xsl:apply-templates>
+          </xsl:otherwise>
+        </xsl:choose>
+        <!-- Removed printing occurrance information
+                <xsl:text>   - </xsl:text>
+        <xsl:call-template name="print-occurs">
+          <xsl:with-param name="name" select="$dxnamePure"/>
+        </xsl:call-template> -->
         <xsl:value-of select="$newline"/>
--->
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
-
   <xsl:template match="xs:complexType">
     <xsl:param name="level"/>
     <xsl:param name="name"/>
-
+    <xsl:param name="parent"/>
     <!-- Visit the sub-menus -->
     <xsl:apply-templates select="descendant::xs:element">
       <xsl:with-param name="level" select="$level + 1"/>
       <xsl:with-param name="prefix" select="concat($name, '.')"/>
+      <xsl:with-param name="parent" select="$parent"/>
     </xsl:apply-templates>
   </xsl:template>
-
   <xsl:template match="xs:simpleType">
     <xsl:text>   - </xsl:text>
-    <xsl:call-template name="print-annotation" >
-       <xsl:with-param name="indent" select="'     '"/>
-    </xsl:call-template>
+    <xsl:choose>
+      <xsl:when test="xs:annotation/xs:documentation">
+        <xsl:call-template name="print-annotation">
+          <xsl:with-param name="indent" select="'     '"/>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:text>No type annotation found</xsl:text>
+        <xsl:value-of select="$newline"/>
+      </xsl:otherwise>
+    </xsl:choose>
   </xsl:template>
-
   <xsl:template name="print-occurs">
     <xsl:param name="name"/>
-  <!-- use the min/maxOccurs data to figure out if this is an optional
+    <!-- use the min/maxOccurs data to figure out if this is an optional
        item, and how many occurrences are allowed -->
     <xsl:variable name="min">
       <xsl:choose>
@@ -169,7 +230,6 @@
         <xsl:otherwise>1</xsl:otherwise>
       </xsl:choose>
     </xsl:variable>
-
     <xsl:variable name="max">
       <xsl:choose>
         <xsl:when test="@maxOccurs">
@@ -178,10 +238,9 @@
         <xsl:otherwise>1</xsl:otherwise>
       </xsl:choose>
     </xsl:variable>
-
-    <xsl:text>The **</xsl:text>
+    <xsl:text>The ``</xsl:text>
     <xsl:value-of select="$name"/>
-    <xsl:text>** option is </xsl:text>
+    <xsl:text>`` option is </xsl:text>
     <xsl:choose>
       <xsl:when test="$min = 0">
         <xsl:text>optional</xsl:text>
@@ -190,13 +249,12 @@
         <xsl:text>required</xsl:text>
       </xsl:otherwise>
     </xsl:choose>
-    <xsl:text> and with </xsl:text>
-
+    <xsl:text> (</xsl:text>
     <xsl:choose>
       <xsl:when test="($min = $max) or ($min = 0)">
         <xsl:value-of select="$max"/>
         <xsl:text> occurrence</xsl:text>
-        <xsl:if test="$max &gt;  1">
+        <xsl:if test="$max &gt;  1 or $max='unbounded'">
           <xsl:text>s</xsl:text>
         </xsl:if>
       </xsl:when>
@@ -207,10 +265,9 @@
         <xsl:text> occurrences</xsl:text>
       </xsl:otherwise>
     </xsl:choose>
-    <xsl:text>.</xsl:text>
+    <xsl:text>).</xsl:text>
     <xsl:value-of select="$newline"/>
   </xsl:template>
-
   <xsl:template name="print-annotation">
     <xsl:param name="indent"/>
     <!-- append an (Optional) annotation if minOccurs=0) -->
@@ -218,11 +275,16 @@
       <xsl:choose>
         <xsl:when test="@minOccurs">
           <xsl:if test="@minOccurs = 0">
-             <xsl:text> *(Optional)*</xsl:text>
+            <xsl:text> *(Optional)*</xsl:text>
+          </xsl:if>
+          <xsl:if test="@minOccurs != 0">
+            <xsl:text> *(Required)**</xsl:text>
           </xsl:if>
         </xsl:when>
         <!-- could show (Required) here instead, but it seemed too noisy -->
-        <xsl:otherwise><xsl:text></xsl:text></xsl:otherwise>
+        <xsl:otherwise>
+          <xsl:text/>
+        </xsl:otherwise>
       </xsl:choose>
     </xsl:variable>
     <!-- append a default value annotation if default was defined -->
@@ -231,16 +293,23 @@
         <xsl:when test="@default">
           <xsl:value-of select="concat(' (Default value is ``', @default, '``)')"/>
         </xsl:when>
-        <xsl:otherwise><xsl:text></xsl:text></xsl:otherwise>
+        <xsl:otherwise>
+          <xsl:text/>
+        </xsl:otherwise>
       </xsl:choose>
     </xsl:variable>
-
     <xsl:choose>
       <xsl:when test="xs:annotation">
-         <xsl:call-template name="printIndented">
-           <xsl:with-param name="text" select="concat(xs:annotation/xs:documentation, $optional, $default)"/>
-           <xsl:with-param name="indent" select="$indent"/>
-         </xsl:call-template>
+        <xsl:call-template name="printIndented">
+          <xsl:with-param name="text" select="concat(xs:annotation/xs:documentation[1], $default)"/>
+          <xsl:with-param name="indent" select="$indent"/>
+        </xsl:call-template>
+        <!-- append a second xs:annotation if found.  This allows more content for the documentation that
+              won't be included in the Configurator tooltip -->
+        <xsl:call-template name="printIndented">
+          <xsl:with-param name="text" select="concat($newline, xs:annotation/xs:documentation[2])"/>
+          <xsl:with-param name="indent" select="$indent"/>
+        </xsl:call-template>
       </xsl:when>
       <xsl:otherwise>
         <!-- <xsl:text>&lt;description is missing &gt;</xsl:text> -->
@@ -248,23 +317,20 @@
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
-
   <!--
       Library Routines
   -->
-
   <xsl:template name="repeat">
     <xsl:param name="string"/>
     <xsl:param name="times"/>
-    <xsl:if test="$times > 0">
+    <xsl:if test="$times &gt; 0">
       <xsl:value-of select="$string"/>
       <xsl:call-template name="repeat">
-       <xsl:with-param name="string" select="$string"/>
-       <xsl:with-param name="times" select="$times - 1"/>
+        <xsl:with-param name="string" select="$string"/>
+        <xsl:with-param name="times" select="$times - 1"/>
       </xsl:call-template>
     </xsl:if>
   </xsl:template>
-
   <xsl:template name="section-header">
     <xsl:param name="title"/>
     <xsl:param name="label"/>
@@ -275,51 +341,39 @@
     <xsl:value-of select="concat($title, $newline)"/>
     <xsl:call-template name="repeat">
       <xsl:with-param name="string">
-       <xsl:value-of select="substring($section_adornment, $level, 1)"/>
+        <xsl:value-of select="substring($section_adornment, $level, 1)"/>
       </xsl:with-param>
       <xsl:with-param name="times" select="string-length($title)"/>
     </xsl:call-template>
     <xsl:value-of select="concat($newline, $newline)"/>
   </xsl:template>
-
-  <xsl:template name="option-header">
-    <xsl:param name="label"/>
-    <!-- we're using the reST option directive for creating linkable
-         config option sections using the :option: role.  This also
-         gives us the option directive HTML formatting. -->
-    <xsl:value-of select="$newline"/>
-    <xsl:text>.. option:: </xsl:text>
-    <xsl:value-of select="$label"/>
-    <xsl:value-of select="$newline"/>
-  </xsl:template>
-
-<xsl:template name="printIndented">
-  <xsl:param name="text"/>
-  <xsl:param name="indent"/>
-  <!-- Handle multi-line documentation text and indent it properly for
+  <xsl:template name="printIndented">
+    <xsl:param name="text"/>
+    <xsl:param name="indent"/>
+    <!-- Handle multi-line documentation text and indent it properly for
        the bullet list display we're using for node descriptions (but not for
        heading descriptions -->
-  <xsl:if test="$text">
-    <xsl:variable name="thisLine" select="substring-before($text, $newline)"/>
-    <xsl:variable name="nextLine" select="substring-after($text, $newline)"/>
-    <xsl:choose>
-      <xsl:when test="$thisLine or $nextLine">
-        <!-- $text contains at least one newline, and there's more coming so print it -->
-        <xsl:value-of select="concat($thisLine, $newline)"/>
-        <!-- watch for two newlines in a row and avoid writing the indent -->
-        <xsl:if test="substring-before(concat($nextLine, $newline), $newline)" >
-          <xsl:value-of select="$indent"/>
-        </xsl:if>
-        <!-- and recurse to process the rest -->
-        <xsl:call-template name="printIndented">
-          <xsl:with-param name="text" select="$nextLine"/>
-          <xsl:with-param name="indent" select="$indent"/>
-        </xsl:call-template>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:value-of select="concat($text, $newline)"/>
-      </xsl:otherwise>
-    </xsl:choose>
-  </xsl:if>
-</xsl:template>
+    <xsl:if test="$text">
+      <xsl:variable name="thisLine" select="substring-before($text, $newline)"/>
+      <xsl:variable name="nextLine" select="substring-after($text, $newline)"/>
+      <xsl:choose>
+        <xsl:when test="$thisLine or $nextLine">
+          <!-- $text contains at least one newline, and there's more coming so print it -->
+          <xsl:value-of select="concat($thisLine, $newline)"/>
+          <!-- watch for two newlines in a row and avoid writing the indent -->
+          <xsl:if test="substring-before(concat($nextLine, $newline), $newline)">
+            <xsl:value-of select="$indent"/>
+          </xsl:if>
+          <!-- and recurse to process the rest -->
+          <xsl:call-template name="printIndented">
+            <xsl:with-param name="text" select="$nextLine"/>
+            <xsl:with-param name="indent" select="$indent"/>
+          </xsl:call-template>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="concat($text, $newline)"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:if>
+  </xsl:template>
 </xsl:stylesheet>
diff --git a/doc/static/acrn-custom.css b/doc/static/acrn-custom.css
index b2267f7c7..5b87d6e43 100644
--- a/doc/static/acrn-custom.css
+++ b/doc/static/acrn-custom.css
@@ -389,3 +389,31 @@ html.writer-html5 .rst-content table.docutils td p {
    margin-bottom: 0;
    font-size: .9rem;
 }
+
+/* Simulate look of an option directive on glossary items (particularly used on
+ * config option listings so we can use a glossary to sort config options within
+ * a section of options*/
+div#scenario-configuration-options dl.glossary dt  {
+    display: table;
+    margin: 6px 10px;
+    font-weight: bold;
+    color: #000;
+    line-height: normal;
+    background: #e7f2fa;
+    color: #2980b9;
+    border-top: 3px solid #6ab0de;
+    padding: 6px;
+    position: relative;
+}
+div#scenario-configuration-options dl.glossary dt  {
+   float: left;
+   clear: left;
+}
+div#scenario-configuration-options dl.glossary dd>p  {
+   padding-top: 12px;
+   line-height: normal;
+   clear: right;
+}
+div#scenario-configuration-options dl.glossary dd ul  {
+   clear: both;
+}
diff --git a/doc/static/acrn-custom.js b/doc/static/acrn-custom.js
index 9385120ea..095da3e24 100644
--- a/doc/static/acrn-custom.js
+++ b/doc/static/acrn-custom.js
@@ -6,4 +6,9 @@ $(document).ready(function(){
 
    /* open external links in a new tab */
    $('a[class*=external]').attr({target: '_blank', rel: 'noopener'});
+
+   /* copy image alt tags in config option page as title for hover text tool tip by browser */
+   $("div#scenario-configuration-options img[alt]").each(function(){
+       $(this).attr('title', $(this).attr('alt'));
+   });
 });
diff --git a/doc/tutorials/nvmx_virtualization.rst b/doc/tutorials/nvmx_virtualization.rst
index eacdf8dce..1c02e7758 100644
--- a/doc/tutorials/nvmx_virtualization.rst
+++ b/doc/tutorials/nvmx_virtualization.rst
@@ -124,7 +124,7 @@ with these settings:
 
 #. Configure system level features:
 
-   - Edit :option:`hv.FEATURES.SCHEDULER` to ``SCHED_NOOP`` to disable CPU sharing
+   - Edit ``hv.features.scheduler`` to ``SCHED_NOOP`` to disable CPU sharing
 
      .. code-block:: xml
         :emphasize-lines: 3,18
@@ -150,11 +150,11 @@ with these settings:
 
 #. In each guest VM configuration:
 
-   - Edit :option:`vm.nested_virtualization_support` on the Service VM section and set it to `y`
+   - Edit ``vm.nested_virtualization_support`` on the Service VM section and set it to `y`
      to enable the nested virtualization feature on the Service VM.
-   - Edit :option:`vm.lapic_passthrough` and set it to `y` to enable local
+   - Edit ``vm.lapic_passthrough`` and set it to `y` to enable local
      APIC passthrough on the Service VM.
-   - Edit :option:`vm.cpu_affinity.pcpu_id` to assign ``pCPU`` IDs to run the Service VM. If you are
+   - Edit ``vm.cpu_affinity.pcpu_id`` to assign ``pCPU`` IDs to run the Service VM. If you are
      using debug build and need the hypervisor console, don't assign
      ``pCPU0`` to the Service VM.
 
@@ -179,7 +179,7 @@ with these settings:
      the PCI-vUART for the Service VM. Refer to :ref:`Enable vUART Configurations <vuart_config>`
      for more details about VUART configuration.
 
-   - Set :option:`vm.console_vuart` to ``PCI``
+   - Set ``vm.console_vuart`` to ``PCI``
 
      .. code-block:: xml
         :emphasize-lines: 1
diff --git a/doc/tutorials/vcat_configuration.rst b/doc/tutorials/vcat_configuration.rst
index 6d4e0befe..adb7a4f41 100644
--- a/doc/tutorials/vcat_configuration.rst
+++ b/doc/tutorials/vcat_configuration.rst
@@ -13,12 +13,12 @@ into XML in the scenario file:
 
 #. Configure system level features:
 
-   - Edit :option:`hv.FEATURES.RDT.RDT_ENABLED` to `y` to enable RDT
+   - Edit ``hv.FEATURES.RDT.RDT_ENABLED`` to `y` to enable RDT
 
-   - Edit :option:`hv.FEATURES.RDT.CDP_ENABLED` to `n` to disable CDP.
+   - Edit ``hv.FEATURES.RDT.CDP_ENABLED`` to `n` to disable CDP.
      vCAT requires CDP to be disabled.
 
-   - Edit :option:`hv.FEATURES.RDT.VCAT_ENABLED` to `y` to enable vCAT
+   - Edit ``hv.FEATURES.RDT.VCAT_ENABLED`` to `y` to enable vCAT
 
      .. code-block:: xml
         :emphasize-lines: 3,4,5
@@ -34,9 +34,9 @@ into XML in the scenario file:
 
 #. In each Guest VM configuration:
 
-   - Edit :option:`vm.virtual_cat_support` to 'y' to enable the vCAT feature on the VM.
+   - Edit ``vm.virtual_cat_support`` to 'y' to enable the vCAT feature on the VM.
 
-   - Edit :option:`vm.clos.vcpu_clos` to assign COS IDs to the VM.
+   - Edit ``vm.clos.vcpu_clos`` to assign COS IDs to the VM.
 
      If ``GUEST_FLAG_VCAT_ENABLED`` is not specified for a VM (abbreviated as RDT VM):
      ``vcpu_clos`` is per CPU in a VM and it configures each CPU in a VM to a desired COS ID.