Merge pull request #477 from ndw/panelset

Support panelset presentation; tinker with CSS in various places

src/guide/resources/css/guide.css

@@ -40,7 +40,7 @@ h2 {
 
 .a-detail {
     width: 100%;
-    font-size: 11pt;
+    font-size: 0.85rem;
     display: table;
     border: 1px solid #afafaf;
 }
@@ -176,14 +176,6 @@ span.obsolete {
     text-decoration: line-through;
 }
 
-@page landscape {
-  size: landscape;
-}
-
-.landscape {
-  page: landscape;
-}
-
 .admonition {
   break-inside: avoid;
 }

src/guide/xml/ref-params.xml

@@ -5699,4 +5699,55 @@ be disabled by setting the parameter to “false”.</para>
 </refsection>
 </refentry>  
 
+<refentry>
+  <refmeta>
+    <fieldsynopsis>
+      <type>xs:string</type>
+      <varname>variablelist-panelset</varname>
+      <initializer>'true'</initializer>
+    </fieldsynopsis>
+    <refmiscinfo class="version">2.2.1</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refpurpose>Enable the “panelset” rendering for variable lists?</refpurpose>
+  </refnamediv>
+<refsection>
+<title>Description</title>
+
+<para>If this parameter <glossterm>is true</glossterm>, a “panel set” rendering
+may be selected for <tag>variablelist</tag> elements by placing <literal>panelset</literal>
+in its <tag class="attribute">role</tag> attribute. In interactive presentations, these
+render as selectable, alternative “panels”. In other presentations, they render as a
+normal list.</para>
+
+<variablelist role="panelset">
+<varlistentry>
+<term>Why</term>
+<listitem>
+<para>Panels are often used to show equivalent code samples in different
+languages (Groovy or Kotlin, JavaScript or TypeScript) or different
+versions of a language (Python 2.x or Python 3.x).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>What</term>
+<listitem>
+<para>The actual content of the individual panels is constrainted only by
+the content model of <tag>listitem</tag> in <tag>variablelist</tag>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>How</term>
+<listitem>
+<para>With the <code>panelset</code> role attribute value. But note that in print
+output, this option is <code>false</code> by default.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsection>
+</refentry>  
+
 </reference>

src/main/scss/media-all.scss

@@ -17,6 +17,7 @@
     --hovered-color: rgb(235,235,235);
     --focused-color: rgb(221,221,221);
     --modal-overlay-color: rgba(255,255,255,0.85);
+    --panelset-color: #fafaf0;
 
     --border-color: var(--primary-color);
 
@@ -316,7 +317,7 @@ pre code,
     border: none;
     background-color: inherit;
     padding: 0;
-    font-size: inherit;
+    font-size: 0.85rem; /* code = 85% */
     margin: 0;
 }
 

src/main/scss/media-paged.scss

@@ -194,3 +194,13 @@ span.footnote p {
     padding-top: 0;
     margin-top: 0;
 }
+
+/* ============================================================ */
+
+@page landscape {
+  size: landscape;
+}
+
+.landscape {
+  page: landscape;
+}

src/main/scss/media-screen.scss

@@ -389,6 +389,58 @@ nav.top div {
     border-radius: 4px;
 }
 
+/* ============================================================ */
+/* Panel sets */
+/* Based on https://codepen.io/alvarotrigo/pen/RwLzvQz by Álvaro */
+
+.panelset {
+    display: flex;
+    flex-wrap: wrap;
+}
+
+.panelset label {
+    order: 1;
+    display: block;
+    padding: 1rem 2rem;
+    margin-right: 0.2rem;
+    cursor: pointer;
+    transition: background ease 0.2s;
+    border-top-left-radius: 0.5em;
+    border-top-right-radius: 0.5em;
+    color: var(--primary-color);
+}
+
+.panelset .paneltab {
+    order: 99; /* Put the tabs last */
+    flex-grow: 1;
+    width: 100%;
+    display: none;
+    padding: 1rem;
+    border-top: 1px solid var(--focused-color);
+    background-color: var(--panelset-color);
+}
+
+.panelset input[type="radio"] {
+    display: none;
+}
+
+.panelset input[type="radio"]:checked + label {
+    border-bottom: 2px solid var(--focused-color);
+    background-color: var(--panelset-color);
+    color: var(--on-background-color);
+}
+
+.panelset label:hover {
+    border-top: 2px solid var(--focused-color);
+    border-bottom: 2px solid var(--focused-color);
+    color: var(--on-background-color);
+    border-radius: 0;
+}
+
+.panelset input[type="radio"]:checked + label + .paneltab {
+    display: block;
+}
+
 /* ============================================================ */
 
 @media screen and (max-width: 1199px) {

src/main/xslt/docbook-paged.xsl

@@ -19,6 +19,7 @@
 <xsl:param name="xlink-style-default" select="'inline'"/>
 <xsl:param name="paper-size" select="'A4'"/>
 <xsl:param name="titleabbrev-passthrough" select="'false'"/>
+<xsl:param name="variablelist-panelset" select="'false'"/>
 
 <!-- ============================================================ -->
 

src/main/xslt/modules/lists.xsl

@@ -355,6 +355,34 @@
 
 <!-- ============================================================ -->
 
+<xsl:template match="db:variablelist[f:is-true($variablelist-panelset)
+                                     and contains-token(@role, 'panelset')]">
+  <div class="panelset variablelist">
+    <xsl:apply-templates select="." mode="m:attributes"/>
+    <xsl:apply-templates select="." mode="m:generate-titlepage"/>
+    <xsl:apply-templates select="* except db:varlistentry"/>
+    <div class="panelset">
+      <xsl:for-each select="db:varlistentry">
+        <!-- inline style so that the radio button is not displayed -->
+        <!-- even if the CSS is missing -->
+        <input type="radio" name="tabs" id="{f:id(.)}" style="display:none">
+          <xsl:if test="position() = 1">
+            <xsl:attribute name="checked" select="'checked'"/>
+          </xsl:if>
+        </input>
+        <label for="{f:id(.)}">
+          <xsl:apply-templates select="db:term/node()"/>
+        </label>
+        <div class="paneltab">
+          <xsl:apply-templates select="db:listitem/node()"/>
+        </div>
+      </xsl:for-each>
+    </div>
+  </div>
+</xsl:template>
+
+<!-- ============================================================ -->
+
 <xsl:template match="db:segmentedlist">
   <xsl:variable name="presentation"
                 select="f:pi(., 'segmentedlist-style', $segmentedlist-style)"/>

src/test/resources/expected/panelset.001.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" class="no-js"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><script>(function(H){H.className=H.className.replace(/\bno-js\b/,'js')})(document.documentElement)</script><title>Unit Test: panelset.001</title><link href="./css/pygments.css" rel="stylesheet"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><link href="https://purl.org/dc/elements/1.1/" rel="schema.dc"/><meta content="2011-04-22T17:02:00-06:00" name="dc.modified"/><meta content="DocBook xslTNG" name="generator"/><link href="./css/docbook.css" rel="stylesheet" media="screen"/><script src="./js/copy-verbatim.js" defer="defer"></script></head><body class="home"><nav class="top"></nav><main><article class="article component"><header><h1>Unit Test: panelset.001</h1></header><p>This unit test is an experiment in providing a “panel set” presentation
+for a variable list.</p><div class="panelset variablelist"><div class="panelset"><input type="radio" name="tabs" id="R_variablelist1_varlistentry1" style="display:none" checked="checked"/><label for="R_variablelist1_varlistentry1">docbook.py</label><div class="paneltab"><div class="pre-wrap highlight" db-startinglinenumber="1" db-numberoflines="17"><pre class="language-python long numbered programlisting verbatim verblines"><span class="line" db-line="1"><span class="ln"> 1 <span class="nsep">|</span></span><span class="ld"><code><span class="ch">#!/usr/bin/env python3</span></code></span></span>
+<span class="line" db-line="2"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code> </code></span></span>
+<span class="line" db-line="3"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="sd">"""This is a wrapper script around the Saxon command line interface.</span></code></span></span>
+<span class="line" db-line="4"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="sd">It attempts to make sure that the classpath is correct and that third</span></code></span></span>
+<span class="line" db-line="5"><span class="ln"> 5 <span class="nsep">|</span></span><span class="ld"><code><span class="sd">party and other libraries are available."""</span></code></span></span>
+<span class="line" db-line="6"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code> </code></span></span>
+<span class="line" db-line="7"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">os</span></code></span></span>
+<span class="line" db-line="8"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">sys</span></code></span></span>
+<span class="line" db-line="9"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">json</span></code></span></span>
+<span class="line" db-line="10"><span class="ln">10 <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">shutil</span></code></span></span>
+<span class="line" db-line="11"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">subprocess</span></code></span></span>
+<span class="line" db-line="12"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">from</span> <span class="nn">pathlib</span> <span class="kn">import</span> <span class="n">Path</span></code></span></span>
+<span class="line" db-line="13"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">from</span> <span class="nn">xml.dom.minidom</span> <span class="kn">import</span> <span class="n">parse</span><span class="p">,</span> <span class="n">Node</span></code></span></span>
+<span class="line" db-line="14"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code> </code></span></span>
+<span class="line" db-line="15"><span class="ln">15 <span class="nsep">|</span></span><span class="ld"><code> </code></span></span>
+<span class="line" db-line="16"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="k">class</span> <span class="nc">JavaClassRunnerException</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span></code></span></span>
+<span class="line" db-line="17"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="w">    </span><span class="sd">"""Subclass of Exception for errors raised by the runner."""</span></code></span></span>
+</pre></div><p>And so on, for another 600 lines or so.</p></div><input type="radio" name="tabs" id="R_variablelist1_varlistentry2" style="display:none"/><label for="R_variablelist1_varlistentry2">linkcheck.py</label><div class="paneltab"><div class="pre-wrap highlight" db-startinglinenumber="1" db-numberoflines="19"><pre class="language-python long numbered programlisting verbatim verblines"><span class="line" db-line="1"><span class="ln"> 1 <span class="nsep">|</span></span><span class="ld"><code><span class="ch">#!/usr/bin/env python3</span></code></span></span>
+<span class="line" db-line="2"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code> </code></span></span>
+<span class="line" db-line="3"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="sd">"""This is yet another link checker. Was it better to write my own</span></code></span></span>
+<span class="line" db-line="4"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="sd">than find an existing cross-platform version? Maybe not, but it</span></code></span></span>
+<span class="line" db-line="5"><span class="ln"> 5 <span class="nsep">|</span></span><span class="ld"><code><span class="sd">appeared to be easier."""</span></code></span></span>
+<span class="line" db-line="6"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code> </code></span></span>
+<span class="line" db-line="7"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">re</span></code></span></span>
+<span class="line" db-line="8"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">os</span></code></span></span>
+<span class="line" db-line="9"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">sys</span></code></span></span>
+<span class="line" db-line="10"><span class="ln">10 <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">json</span></code></span></span>
+<span class="line" db-line="11"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">glob</span></code></span></span>
+<span class="line" db-line="12"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="kn">import</span> <span class="nn">click</span></code></span></span>
+<span class="line" db-line="13"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="k">try</span><span class="p">:</span></code></span></span>
+<span class="line" db-line="14"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code>    <span class="kn">import</span> <span class="nn">html5_parser</span></code></span></span>
+<span class="line" db-line="15"><span class="ln">15 <span class="nsep">|</span></span><span class="ld"><code>    <span class="kn">import</span> <span class="nn">lxml.etree</span></code></span></span>
+<span class="line" db-line="16"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code>    <span class="kn">from</span> <span class="nn">saxonche</span> <span class="kn">import</span> <span class="n">PySaxonProcessor</span></code></span></span>
+<span class="line" db-line="17"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code>    <span class="n">importOk</span> <span class="o">=</span> <span class="kc">True</span></code></span></span>
+<span class="line" db-line="18"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code><span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span></code></span></span>
+<span class="line" db-line="19"><span class="ln">   <span class="nsep">|</span></span><span class="ld"><code>    <span class="n">importOk</span> <span class="o">=</span> <span class="kc">False</span></code></span></span>
+</pre></div><p>And so on for another 150 lines or so.</p></div><input type="radio" name="tabs" id="R_variablelist1_varlistentry3" style="display:none"/><label for="R_variablelist1_varlistentry3">Something else</label><div class="paneltab"><p>More things.</p><div class="admonition note"><div><div class="icon">ⓘ</div><div class="body"><header><div class="title">Note</div></header><div><p>The content of an individual panel is just ordinary
+      DocBook <code>listitem</code> content.</p></div></div></div></div></div></div></div></article></main><nav class="bottom"></nav></body></html>

src/test/resources/xml/panelset.001.xml

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="utf-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+<info>
+<title>Unit Test: panelset.001</title>
+</info>
+
+<para>This unit test is an experiment in providing a “panel set” presentation
+for a variable list.</para>
+
+<variablelist role="panelset">
+  <varlistentry>
+    <term>docbook.py</term>
+    <listitem>
+      <programlisting language="python">#!/usr/bin/env python3
+
+"""This is a wrapper script around the Saxon command line interface.
+It attempts to make sure that the classpath is correct and that third
+party and other libraries are available."""
+
+import os
+import sys
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from xml.dom.minidom import parse, Node
+
+
+class JavaClassRunnerException(Exception):
+    """Subclass of Exception for errors raised by the runner."""
+</programlisting>
+<para>And so on, for another 600 lines or so.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>linkcheck.py</term>
+    <listitem>
+      <programlisting language="python">#!/usr/bin/env python3
+
+"""This is yet another link checker. Was it better to write my own
+than find an existing cross-platform version? Maybe not, but it
+appeared to be easier."""
+
+import re
+import os
+import sys
+import json
+import glob
+import click
+try:
+    import html5_parser
+    import lxml.etree
+    from saxonche import PySaxonProcessor
+    importOk = True
+except ImportError:
+    importOk = False
+
+</programlisting>
+<para>And so on for another 150 lines or so.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Something else</term>
+    <listitem>
+      <para>More things.</para>
+      <note><para>The content of an individual panel is just ordinary
+      DocBook <code>listitem</code> content.</para></note>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</article>