Merge pull request #560 from gmlueck/gmlueck/accordion-toc

Expandable TOC for HTML output

adoc/Makefile

@@ -144,7 +144,8 @@ ADOCOPTS     = --doctype book $(ADOCMISCOPTS) $(ATTRIBOPTS) \
 
 ADOCHTMLEXTS = --require $(CURDIR)/config/katex_replace.rb \
   --require $(CURDIR)/config/loadable_html.rb \
-  --require $(CURDIR)/config/synopsis.rb
+  --require $(CURDIR)/config/synopsis.rb \
+  --require $(CURDIR)/config/accordion_toc.rb
 
 # ADOCHTMLOPTS relies on the relative runtime path from the output HTML
 # file to the katex scripts being set with KATEXDIR. This is overridden

adoc/config/accordion_toc.rb

@@ -0,0 +1,9 @@
+# Copyright (c) 2011-2024 The Khronos Group, Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+#require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+RUBY_ENGINE == 'opal' ? (require 'accordion_toc/extension') : (require_relative 'accordion_toc/extension')
+
+Asciidoctor::Extensions.register do
+    postprocessor MakeAccordionToc
+end

adoc/config/accordion_toc/extension.rb

@@ -0,0 +1,183 @@
+# Copyright (c) 2011-2024 The Khronos Group, Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+include ::Asciidoctor
+
+# Make the table of contents (TOC) expandable in the HTML render.  A clickable
+# icon allows the user to expand or collapse each TOC entry.  The number of TOC
+# levels that are initially expanded is controlled by the "toclevels-expanded"
+# Asciidoc attribute.  For example:
+#
+# :toclevels-expanded: 1
+#
+# expands the first level of headings in the TOC.  Thus, both the first and
+# second heading levels are visible initially.  To expand all levels initially,
+# use the value "-1".  To leave all levels initially unexpanded, use the value
+# "0".
+#
+# A clickable icon is also added to the TOC title (usually "Table of Contents").
+# Clicking this icon fully expands or fully collapses all TOC levels.  If
+# "toclevels-expanded" is 0, the initial state is "collapsed" (so the first
+# click on the icon will fully expand all levels).  If "toclevels-expanded" is
+# any other value, the initial state is "expanded" (so the first click on the
+# icon will fully collapse all levels).
+#
+# This extension also relies on some custom CSS styling.  See the CSS entries
+# for the class name "toc-parent".
+
+class MakeAccordionToc < Extensions::Postprocessor
+  TocStart = /^<div id="toc"/
+  TocTitle = /^<div id="toctitle">/
+  Li = /^<li>/
+  Ul = /^<ul (class="sectlevel\d*")>/
+  EndUl = /^<\/ul>/
+  EndHead = /^<\/head>/
+
+  # Add a click handler to the <span class="toc-parent"> elements.  When the
+  # element is clicked:
+  #
+  # * The class "toc-expanded" is toggled on the <span>, which changes the icon.
+  # * The <ul> element that follows the <span> is made visible / invisible.
+  #
+  # Note that this script assumes that the <ul> element is two siblings beyond
+  # the <span> that is clicked.  This assumes the HTML format generated by
+  # Asciidoctor looks like:
+  #
+  # <li>
+  #   <span class="toc-parent"></span>   <-- <span> generated by this extension below
+  #   <a href="#...">...</a>
+  #   <ul class="...">
+  #
+  # Also add a click handler to the <span id="toc-top> element.  When this is
+  # clicked, all "toc-parent" elements are toggled between expanded and
+  # collapsed.
+  Script =
+'<script>
+    function addTocClickHandlers(){
+      var toc_parents = document.getElementsByClassName("toc-parent");
+      var toc_top = document.getElementById("toc-top");
+
+      for (element of toc_parents) {
+        element.addEventListener("click", function() {
+          this.classList.toggle("toc-expanded");
+          var ul = this.nextElementSibling.nextElementSibling;
+          if (ul.style.display === "block") {
+            ul.style.display = "none";
+          } else {
+            ul.style.display = "block";
+          }
+        });
+      }
+
+      toc_top.addEventListener("click", function() {
+        var is_expanded = this.classList.toggle("toc-expanded");
+        for (element of toc_parents) {
+          if (is_expanded) {
+            element.classList.add("toc-expanded");
+            var ul = element.nextElementSibling.nextElementSibling;
+            ul.style.display = "block";
+          }
+          else {
+            element.classList.remove("toc-expanded");
+            var ul = element.nextElementSibling.nextElementSibling;
+            ul.style.display = "none";
+          }
+        }
+      });
+    }
+
+    window.addEventListener("load", addTocClickHandlers);
+</script>
+'
+
+  # Postprocess the HTML performing the following modifications:
+  #
+  # * Each heading in the TOC is represented by an <li> element.  If the heading
+  #   has sub-headings, the <li> is follows by a <ul>.  Find these <li> elements
+  #   that have sub-headings and add a <span class="toc-parent"> after the <li>.
+  #   The script above uses the class name to attach a click handler.  The CSS
+  #   style sheet also uses the class name to attach an icon that the user can
+  #   click.
+  #
+  # * Keep track of the heading levels and modify the <li> and <ul> elements to
+  #   initially expand the N topmost levels according to the attribute
+  #   "toclevels-expanded".  The <li> element for an expanded level is given the
+  #   class name "toc-expanded".  The CSS style sheet uses this to change the
+  #   icon to indicate that the TOC level is expanded.  For an unexpanded
+  #   element, we hide the <ul> that follows by adding 'style="display:none;"'.
+  #
+  # * Add a <span id="toc-top"> element to the TOC title line.  The script above
+  #   uses the ID to attach a click handler, and the CSS style sheet uses the ID
+  #   to attach a clickable icon.
+  #
+  # The Asciidoctor postprocessor pass just gets a big string of HTML, not a DOM
+  # tree.  Rather then trying to parse the HTML, we do some fairly simplistic
+  # pattern matching to find the relevant HTML elements.  This pattern matching
+  # relies on the current output format of the Asciidoctor HTML generator.  If
+  # that format changes in the future, we will either need to change the
+  # pattern matching in this script or do something more robust by really
+  # parsing the HTML.
+  def process document, output
+
+    if document.basebackend? 'html'
+      if document.attr? 'toclevels-expanded'
+        toc_levels_expanded = (document.attr 'toclevels-expanded').to_i
+      else
+        toc_levels_expanded = -1
+      end
+      new_output = ''
+      is_in_toc = false
+      hide_next_ul = false
+      toc_level = 0
+      output.lines.map.each_cons(2) do |line, next_line|
+        # Keep track of the TOC level by counting the nesting of the <ul> and
+        # </ul> elements that are in the TOC.
+        is_in_toc = true if TocStart.match(line)
+        toc_level+=1 if is_in_toc and Ul.match(line)
+        if is_in_toc and EndUl.match(line)
+          toc_level -= 1
+          is_in_toc = false if toc_level == 0
+        end
+
+        # Add a <span id="toc-top"> to the TOC title.
+        if is_in_toc and toc_level == 0
+          if toc_levels_expanded == 0
+            line.sub! TocTitle, '\0<span id="toc-top"></span>'
+          else
+            line.sub! TocTitle, '\0<span id="toc-top" class="toc-expanded"></span>'
+          end
+        end
+
+        # If an <li> is followed by a <ul>, then the <li> represents a heading
+        # that has sub-headings.
+        if is_in_toc and Li.match(line) and Ul.match(next_line)
+          if (toc_levels_expanded >= 0) and (toc_level > toc_levels_expanded)
+            line.sub! Li, '<li><span class="toc-parent"></span>'
+            hide_next_ul = true
+          else
+            line.sub! Li, '<li><span class="toc-parent toc-expanded"></span>'
+          end
+        end
+
+        # If a <ul> is under an unexpanded <li>, make it invisible.  This just
+        # sets the initial display.  The user can still change the visibility
+        # by clicking the icon.
+        if is_in_toc and Ul.match(line) and hide_next_ul
+          line.sub! Ul, '<ul \1 style="display:none;">'
+          hide_next_ul = false
+        end
+
+        # Add the script that sets up the click handlers.
+        if EndHead.match(line)
+          line = Script + "</head>\n"
+        end
+        new_output << line
+      end
+      output = new_output
+    end
+    output
+
+  end
+end

adoc/config/khronos.css

@@ -363,6 +363,50 @@ b.button:after { content: "]"; padding: 0 2px 0 3px; }
 #content #toc > :first-child { margin-top: 0; }
 #content #toc > :last-child { margin-bottom: 0; }
 
+/*
+ * Add a triangle icon to the left of TOC entries that have sub-headings.
+ * The triangle points down if the heading is expanded in the TOC, and it
+ * points right if the TOC heading is unexpanded.  This is paired with a
+ * click handler that allows the user to change the expansion of each TOC
+ * entry.
+ */
+span.toc-parent:before {
+  content: "\25B6";
+  font-size: 0.6em;
+  display: block;
+  padding-top: 0.1em;
+  position: absolute;
+  z-index: 1001;
+  width: 1.5ex;
+  margin-left: -1.9ex;
+  display: block;
+}
+span.toc-parent.toc-expanded:before {
+  content: "\25BC";
+}
+
+/*
+ * Add a double-chevron icon to the left of the TOC title.  The chevrons point
+ * down when all TOC levels are expanded and they point up when all TOC levels
+ * are collapsed.  This is also paired with a click handler to expand /
+ * collapse all TOC levels.
+ */
+#toc-top:before {
+  content: "\AB";
+  transform: rotate(90deg);
+  font-size: 0.9em;
+  display: block;
+  padding-left: 0.2em;
+  position: absolute;
+  z-index: 1001;
+  width: 1.5ex;
+  margin-left: -1.5ex;
+  display: block;
+}
+#toc-top.toc-expanded:before {
+  content: "\BB";
+}
+
 #footer { max-width: 100%; background-color: none; padding: 1.25em; }
 
 #footer-text { color: black; line-height: 1.44; }

adoc/syclbase.adoc

@@ -21,6 +21,7 @@ The Khronos{regtitle} {SYCL_NAME}{tmtitle} Working Group
 :icons: font
 :toc2:
 :toclevels: 10
+:toclevels-expanded: 0
 :sectnumlevels: 10
 :max-width: 100%
 :numbered: