Add section tree output to the tags backend

This adds the section tree to the tags JSON output, including which tags are in each section and the section IDs. For example for the RISC-V Privileged spec it outputs:

```
{
  "tags": {
    "norm:ext:Sm:highest_priv_mode": "machine-mode (M-mode), which is the highest privilege mode in a RISC-V\nhart.",
    "norm:ext:Sm:mode_at_reset": "M-mode is used for low-level access to a hardware platform and\nis the first mode entered at reset.",
    "norm:ext:Sm:access_all_lower_priv_CSRs": "M-mode code can access all CSRs at lower privilege levels.",
...
    "norm:csr:mstatus:sz_rw": "The mstatus register is an MXLEN-bit read/write register formatted as\nshown in <<mstatusreg-rv32>> for RV32 and <<mstatusreg>> for RV64.",
    "norm:csr:mstatush:sz_rw_rv32": "For RV32 only, mstatush is a 32-bit read/write register formatted as shown in <<mstatushreg>>.",
    "norm:csr:mstatush:encoding": "Bits 30:4 of mstatush generally contain the same fields found in bits 62:36 of mstatus for RV64. Fields SD, SXL, and UXL do not exist in mstatush."
  },
  "sections": {
    "title": "",
    "id": "",
    "children": [
      {
        "title": "Preface",
        "id": "_preface",
        "children": [],
        "tags": []
      },
...
      {
        "title": "Machine-Level ISA, Version 1.13",
        "id": "machine",
        "children": [
          {
            "title": "Machine-Level CSRs",
            "id": "_machine_level_csrs",
            "children": [
              {
                "title": "Machine ISA (misa) Register",
                "id": "misa",
                "children": [],
                "tags": [
                  "norm:csr:misa:sw_rw",
                  "norm:csr:misa:always_readable",
                  "norm:param:MISA_CSR_IMPLEMENTED:can_be_zero",
...
                  "norm:csrfld:misa:e:not_i",
                  "norm:csrfld:misa:extensions:dependencies",
                  "norm:csr:misa:inc_ialign"
                ]
              },
              {
                "title": "Machine Vendor ID (mvendorid) Register",
                "id": "_machine_vendor_id_mvendorid_register",
                "children": [],
                "tags": [
                  "norm:csr:mvendorid:sz_ro_meaning",
                  "norm:csr:mvendorid:always_readable",
                  "norm:csr:mvendorid:encoding",
                  "norm:csr:mvendorid:bank_1_less_than_JEDEC"
                ]
              },
```

Signed-off-by: Tim Hutt <[email protected]>

Author: Timmmm

converters/tags.rb

@@ -1,10 +1,26 @@
 require 'json'
 
+# This is an Asciidoctor backend that allows extracting the content
+# from tagged snippets of text.
 class TagsConverter
   include Asciidoctor::Converter
   register_for("tags")
 
+  # Hash{String => String} - map from tag ID to its text contents.
   @tag_map = {}
+  # Array<String> - the stack of currently open sections in the
+  # section tree. Each `Section` contains
+  #
+  #  * title: String            - Section title.
+  #  * id: String               - Generated ID for the title which can be used for HTML links.
+  #  * children: Array<Section> - Child sections.
+  #  * tags: Array<String>      - List of tags in this section directly (not in children).
+  #
+  # This always starts with a root section with an empty title and id.
+  @section_stack = []
+
+  # Prefix on IDs that we require. We can't look at all IDs because
+  # it includes a load of auto-generated ones.
   @prefix = ""
 
   def initialize(backend, opts = {})
@@ -18,23 +34,64 @@ def initialize(backend, opts = {})
   # `node` is an `AbstractNode`.
   def convert(node, transform = node.node_name, opts = nil)
     if transform == "document" then
+      # This is the top level node. First clear the outputs.
       @tag_map = {}
+      # Root node of the section tree. For simplicity we always
+      # have one root node with an empty title.
+      @section_stack = [{
+        "title" => "",
+        "id" => "",
+        "children" => [],
+        "tags" => [],
+      }]
+
       # Calling node.content will recursively call convert() on all the nodes
       # and also expand blocks, creating inline nodes. We call this to convert
       # all nodes to text, and record their content in the tag map. Then we
       # throw away the text and output the tag map as JSON instead.
       node.content
+
+      # We must always add and remove an equal number of sections from the stack
+      # and we started with one so should end with one.
+      fail "Tags backend section logic error" if @section_stack.length != 1
+
       JSON.pretty_generate({
         "tags": @tag_map,
+        "sections": @section_stack.first,
       })
     else
-      # Output the text content of this node.
+
+      # If it's a section add it to the section tree.
+      if transform == "section" then
+        section = {
+          "title" => node.title,
+          "id" => node.id,
+          "children" => [],
+          "tags" => [],
+        }
+
+        @section_stack.last["children"] << section
+        @section_stack << section
+      end
+
+      # Recursively get the text content of this node.
       content = if node.inline? then node.text else node.content end
+
+      # Capture the content in the tag map and section tree if
+      # this node is tagged appropriately.
       unless node.id.nil?
         if node.id.start_with?(@prefix)
           @tag_map[node.id] = content
+          @section_stack.last["tags"] << node.id
         end
       end
+
+      # If it's a section, we've recursed through it (via `node.content`)
+      # so pop it from the stack.
+      if transform == "section" then
+        @section_stack.pop()
+      end
+
       content
     end
   end