Merge pull request #306 from ndw/iss-305

Add parameter to trim leading blank lines off verbatim environments
docbook · Apr 10, 2023 · c75a917 · c75a917
2 parents 8a64ea0 + 9fde000
commit c75a917
Show file tree

Hide file tree

Showing 8 changed files with 206 additions and 25 deletions.
diff --git a/buildSrc/src/main/groovy/org/docbook/xsltng/gradle/ValidationTasks.groovy b/buildSrc/src/main/groovy/org/docbook/xsltng/gradle/ValidationTasks.groovy
@@ -33,7 +33,7 @@ class ValidationTasks {
     if (base in publishersDocuments) {
       schema = "${project.projectDir}/src/test/resources/publishers.rng"
     } else if (base == 'olink.001' || base.startsWith('fit.')
-               || base.startsWith("xinclude.")
+               || base.startsWith('xinclude.')
                || base.startsWith('iso690.')) {
       schema = "${project.projectDir}/src/test/resources/docbookxi.rng"
     } else if (base.startsWith('transclusion.')) {

diff --git a/properties.gradle b/properties.gradle
@@ -2,8 +2,8 @@
 ext {
   xslTNGtitle = 'DocBook xslTNG'
   xslTNGbaseName = 'docbook-xslTNG'
-  xslTNGversion = '2.1.1'
-  guideVersion = '2.1.1'
+  xslTNGversion = '2.1.2'
+  guideVersion = '2.1.2'
   guidePrerelease = false
 
   docbookVersion = '5.2CR5'
@@ -18,5 +18,5 @@ ext {
   metadataExtractorVersion = '2.18.0'
   jingVersion = '20220510'
   xmlresolverVersion = '5.1.2'
-  sincludeVersion = '5.1.1'
+  sincludeVersion = '5.2.4'
 }
diff --git a/src/guide/xml/changelog.xml b/src/guide/xml/changelog.xml
@@ -2,6 +2,22 @@
             xmlns:xlink="http://www.w3.org/1999/xlink">
 <?db revhistory-style="list"?>
 
+<revision xml:id="r212">
+<revnumber>2.1.2</revnumber>
+<date>2023-04-10</date>
+<revdescription>
+<itemizedlist>
+<listitem>
+<para>Added a <parameter>verbatim-trim-leading-blank-lines</parameter> parameter. This
+is analagous to the <parameter>verbatim-trim-trailing-blank-lines</parameter> parameter except
+for leading blank lines instead of trailing ones. It is false by default, for backwards
+compatibility, but note that some syntax highlighters may trim leading (and trailing)
+blank links anyway.</para>
+</listitem>
+</itemizedlist>
+</revdescription>
+</revision>
+
 <revision xml:id="r211">
 <revnumber>2.1.1</revnumber>
 <date>2023-04-08</date>

diff --git a/src/guide/xml/ref-functions.xml b/src/guide/xml/ref-functions.xml
@@ -1693,6 +1693,33 @@ element’s name is listed in
 </refsection>
 </refentry>
 
+<refentry xml:id="f_verbatim-trim-leading">
+<?db filename="f_verbatim-trim-leading"?>
+<refmeta>
+<refentrytitle>f:verbatim-trim-leading</refentrytitle>
+<refmiscinfo>{http://docbook.org/ns/docbook/functions}verbatim-trim-leading#1</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>f:verbatim-trim-leading</refname>
+<refpurpose>Return true if leading blank lines should be trimmed</refpurpose>
+<refclass>function</refclass>
+</refnamediv>
+<refsection>
+<title>Description</title>
+<para>This function examines a verbatim environment, the <literal>$context</literal>,
+and returns true if leading blank lines should be trimmed from it.
+A <tag class="pi">db</tag><indexterm><primary>db processing instruction</primary>
+</indexterm> processing instruction with a
+<literal>verbatim-trim-leading</literal><indexterm>
+<primary>db processing instruction</primary>
+<secondary>verbatim-trim-leading pseudo-attribute</secondary>
+</indexterm> pseudo-attribute may be used to override the
+<parameter>verbatim-trim-leading-blank-lines</parameter> parameter on a
+case-by-case basis.
+</para>
+</refsection>
+</refentry>
+
 <refentry xml:id="f_verbatim-trim-trailing">
 <?db filename="f_verbatim-trim-trailing"?>
 <refmeta>

diff --git a/src/guide/xml/ref-params.xml b/src/guide/xml/ref-params.xml
@@ -4505,6 +4505,30 @@ style by default. For a discussion of verbatim elements and styles, see
 </refsection>
 </refentry>
 
+<refentry>
+  <refmeta>
+    <fieldsynopsis>
+      <varname>verbatim-trim-leading-blank-lines</varname>
+      <initializer>'false'</initializer>
+    </fieldsynopsis>
+    <refmiscinfo class="version">2.1.2</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refpurpose>Trim leading blank lines off of verbatim environments?</refpurpose>
+  </refnamediv>
+<refsection>
+<title>Description</title>
+<para>If a verbatim environment is processed with a syntax highlighter, the
+highlighter may remove leading blank lines. This option will produce that result
+for verbatim environments that are not syntax highlighted.</para>
+<para>If leading blank lines aren’t significant, setting
+<parameter>verbatim-trim-leading-blank-lines</parameter> will cause
+the stylesheets to trim blank (that is, entirely empty) lines from
+the beginning of verbatim environments.</para>
+<para>(This parameter is false by default for backwards compatibility.)</para>
+</refsection>
+</refentry>
+
 <refentry>
   <refmeta>
     <fieldsynopsis>
@@ -4513,7 +4537,7 @@ style by default. For a discussion of verbatim elements and styles, see
     </fieldsynopsis>
   </refmeta>
   <refnamediv>
-    <refpurpose>Trim trailing blank lines off verbatim environments?</refpurpose>
+    <refpurpose>Trim trailing blank lines off of verbatim environments?</refpurpose>
   </refnamediv>
 <refsection>
 <title>Description</title>

diff --git a/src/main/xslt/modules/verbatim.xsl b/src/main/xslt/modules/verbatim.xsl
@@ -84,6 +84,7 @@
   <xsl:param name="style" as="xs:string" select="f:verbatim-style(.)"/>
   <xsl:param name="highlight" as="xs:string*" select="f:verbatim-highlight(.)"/>
   <xsl:param name="numbered" as="xs:boolean" select="f:verbatim-numbered(.)"/>
+  <xsl:param name="trim-leading" as="xs:boolean" select="f:verbatim-trim-leading(.)"/>
   <xsl:param name="trim-trailing" as="xs:boolean" select="f:verbatim-trim-trailing(.)"/>
 
   <xsl:variable name="areaspec" as="element(db:areaspec)?">
@@ -112,6 +113,7 @@
       <xsl:with-param name="highlight" select="$highlight"/>
       <xsl:with-param name="numbered" select="$numbered"/>
       <xsl:with-param name="inject" select="$areaspec"/>
+      <xsl:with-param name="trim-leading" select="$trim-leading"/>
       <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
     </xsl:apply-templates>
 
@@ -127,6 +129,7 @@
   <xsl:param name="style" as="xs:string" select="f:verbatim-style(.)"/>
   <xsl:param name="highlight" as="xs:string*" select="f:verbatim-highlight(.)"/>
   <xsl:param name="numbered" as="xs:boolean" select="f:verbatim-numbered(.)"/>
+  <xsl:param name="trim-leading" as="xs:boolean" select="f:verbatim-trim-leading(.)"/>
   <xsl:param name="trim-trailing" as="xs:boolean" select="f:verbatim-trim-trailing(.)"/>
   <xsl:param name="inject" as="item()?" select="()"/>
 
@@ -149,6 +152,7 @@
     <xsl:with-param name="style" select="$style"/>
     <xsl:with-param name="highlight" select="$highlight"/>
     <xsl:with-param name="numbered" select="$numbered"/>
+    <xsl:with-param name="trim-leading" select="$trim-leading"/>
     <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
     <xsl:with-param name="inject" select="$injectarr"/>
   </xsl:call-template>
@@ -158,6 +162,7 @@
   <xsl:param name="style" as="xs:string" required="yes"/>
   <xsl:param name="highlight" as="xs:string*" required="yes"/>
   <xsl:param name="numbered" as="xs:boolean" required="yes"/>
+  <xsl:param name="trim-leading" as="xs:boolean" required="yes"/>
   <xsl:param name="trim-trailing" as="xs:boolean" required="yes"/>
   <xsl:param name="inject" as="array(*)?" select="()"/>
 
@@ -167,7 +172,7 @@
                        || ', style: ' || $style
                        || ', highlight: ' || string-join($highlight,',')
                        || ', numbered: ' || $numbered
-                       || ', trim: ' || $trim-trailing"/>
+                       || ', trim: ' || $trim-leading || '/' || $trim-trailing"/>
   <xsl:for-each use-when="'verbatim' = $v:debug" select="array:flatten($inject)">
     <xsl:message select="'  inject '||position()||':', .?line, .?column"/>
   </xsl:for-each>
@@ -187,6 +192,7 @@
       <xsl:call-template name="tp:verbatim-plain">
         <xsl:with-param name="highlight" select="$highlight"/>
         <xsl:with-param name="numbered" select="$numbered"/>
+        <xsl:with-param name="trim-leading" select="$trim-leading"/>
         <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
         <xsl:with-param name="inject" select="$inject"/>
       </xsl:call-template>
@@ -195,6 +201,7 @@
       <xsl:call-template name="tp:verbatim-table">
         <xsl:with-param name="highlight" select="$highlight"/>
         <xsl:with-param name="numbered" select="$numbered"/>
+        <xsl:with-param name="trim-leading" select="$trim-leading"/>
         <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
         <xsl:with-param name="inject" select="$inject"/>
       </xsl:call-template>
@@ -203,6 +210,7 @@
       <xsl:call-template name="tp:verbatim-lines">
         <xsl:with-param name="highlight" select="$highlight"/>
         <xsl:with-param name="numbered" select="$numbered"/>
+        <xsl:with-param name="trim-leading" select="$trim-leading"/>
         <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
         <xsl:with-param name="inject" select="$inject"/>
       </xsl:call-template>
@@ -225,6 +233,7 @@
       </xsl:if>
       <xsl:call-template name="tp:verbatim-raw">
         <xsl:with-param name="highlight" select="$highlight"/>
+        <xsl:with-param name="trim-leading" select="$trim-leading"/>
         <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
         <xsl:with-param name="numbered" select="$numbered"/>
       </xsl:call-template>
@@ -236,6 +245,7 @@
       <xsl:call-template name="tp:verbatim-plain">
         <xsl:with-param name="highlight" select="$highlight"/>
         <xsl:with-param name="numbered" select="$numbered"/>
+        <xsl:with-param name="trim-leading" select="$trim-leading"/>
         <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
         <xsl:with-param name="inject" select="$inject"/>
       </xsl:call-template>
@@ -246,13 +256,15 @@
 <xsl:template name="tp:verbatim-plain" as="element()">
   <xsl:param name="highlight" as="xs:string*" required="yes"/>
   <xsl:param name="numbered" as="xs:boolean" required="yes"/>
+  <xsl:param name="trim-leading" as="xs:boolean" required="yes"/>
   <xsl:param name="trim-trailing" as="xs:boolean" required="yes"/>
   <xsl:param name="inject" as="array(*)?" select="()"/>
 
   <xsl:variable name="lines" as="array(*)">
     <xsl:call-template name="tp:verbatim-array">
       <xsl:with-param name="highlight" select="$highlight"/>
       <xsl:with-param name="numbered" select="$numbered"/>
+      <xsl:with-param name="trim-leading" select="$trim-leading"/>
       <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
       <xsl:with-param name="inject" select="$inject"/>
     </xsl:call-template>
@@ -295,6 +307,7 @@
 <xsl:template name="tp:verbatim-raw" as="element()">
   <xsl:param name="highlight" as="xs:string*" required="yes"/>
   <xsl:param name="numbered" as="xs:boolean" required="yes"/>
+  <xsl:param name="trim-leading" as="xs:boolean" required="yes"/>
   <xsl:param name="trim-trailing" as="xs:boolean" required="yes"/>
 
   <xsl:variable name="body" as="item()*">
@@ -323,13 +336,15 @@
 <xsl:template name="tp:verbatim-table" as="element()">
   <xsl:param name="highlight" as="xs:string*" required="yes"/>
   <xsl:param name="numbered" as="xs:boolean" required="yes"/>
+  <xsl:param name="trim-leading" as="xs:boolean" required="yes"/>
   <xsl:param name="trim-trailing" as="xs:boolean" required="yes"/>
   <xsl:param name="inject" as="array(*)?" select="()"/>
 
   <xsl:variable name="lines" as="array(*)">
     <xsl:call-template name="tp:verbatim-array">
       <xsl:with-param name="highlight" select="$highlight"/>
       <xsl:with-param name="numbered" select="$numbered"/>
+      <xsl:with-param name="trim-leading" select="$trim-leading"/>
       <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
       <xsl:with-param name="inject" select="$inject"/>
     </xsl:call-template>
@@ -488,13 +503,15 @@
 <xsl:template name="tp:verbatim-lines" as="element()">
   <xsl:param name="highlight" as="xs:string*" required="yes"/>
   <xsl:param name="numbered" as="xs:boolean" required="yes"/>
+  <xsl:param name="trim-leading" as="xs:boolean" required="yes"/>
   <xsl:param name="trim-trailing" as="xs:boolean" required="yes"/>
   <xsl:param name="inject" as="array(*)?" select="()"/>
 
   <xsl:variable name="lines" as="array(*)">
     <xsl:call-template name="tp:verbatim-array">
       <xsl:with-param name="highlight" select="$highlight"/>
       <xsl:with-param name="numbered" select="$numbered"/>
+      <xsl:with-param name="trim-leading" select="$trim-leading"/>
       <xsl:with-param name="trim-trailing" select="$trim-trailing"/>
       <xsl:with-param name="inject" select="$inject"/>
     </xsl:call-template>
@@ -711,6 +728,7 @@
 <xsl:template name="tp:verbatim-array" as="array(*)">
   <xsl:param name="highlight" as="xs:string*" required="yes"/>
   <xsl:param name="numbered" as="xs:boolean" required="yes"/>
+  <xsl:param name="trim-leading" as="xs:boolean" required="yes"/>
   <xsl:param name="trim-trailing" as="xs:boolean" required="yes"/>
   <xsl:param name="inject" as="array(*)?" select="()"/>
 
@@ -742,7 +760,7 @@
     <xsl:apply-templates select="$formatted" mode="mp:flatten-markup"/>
   </xsl:variable>
 
-  <xsl:variable name="lines" select="fp:make-lines($flattened/node(), $trim-trailing)"/>
+  <xsl:variable name="lines" select="fp:make-lines($flattened/node(), $trim-leading, $trim-trailing)"/>
   <xsl:variable name="lines" select="fp:balance-markup($lines)"/>
 
   <xsl:variable name="lines" select="if (exists($inject))
@@ -797,31 +815,55 @@
 
 <xsl:function name="fp:make-lines" as="array(*)">
   <xsl:param name="body" as="node()*"/>
+  <xsl:param name="trim-leading" as="xs:boolean"/>
   <xsl:param name="trim-trailing" as="xs:boolean"/>
 
-  <xsl:variable name="lines" select="fp:make-lines($body, (), [])"/>
-  <xsl:sequence select="if ($trim-trailing)
-                        then fp:trim-trailing-blank-lines($lines)
-                        else $lines"/>
-</xsl:function>
+  <xsl:variable name="lines" select="fp:make-lines-array($body, (), [])"/>
 
-<xsl:function name="fp:trim-trailing-blank-lines">
-  <xsl:param name="lines" as="array(*)"/>
-  <xsl:variable name="last" select="array:size($lines)"/>
   <xsl:choose>
-    <xsl:when test="$last gt 0
-                    and count(array:get($lines, $last)) = 1
-                    and normalize-space(array:get($lines, $last)) = ''">
-      <xsl:sequence select="fp:trim-trailing-blank-lines(
-                               array:remove($lines, $last))"/>
+    <xsl:when test="array:size($lines) = 0">
+      <xsl:sequence select="$lines"/>
     </xsl:when>
     <xsl:otherwise>
-      <xsl:sequence select="$lines"/>
+      <xsl:variable name="range" as="xs:integer+">
+        <xsl:iterate select="1 to array:size($lines)">
+          <xsl:param name="first" select="1"/>
+          <xsl:param name="last" select="1"/>
+          <xsl:on-completion select="($first, $last)"/>
+
+          <xsl:variable name="line" select="array:get($lines, .)"/>
+          <xsl:choose>
+            <xsl:when test="count($line) = 1 and normalize-space($line) = ''">
+              <xsl:next-iteration>
+                <xsl:with-param name="first"
+                                select="if ($trim-leading and $first eq .) then . + 1 else $first"/>
+                <xsl:with-param name="last"
+                                select="if ($trim-trailing) then $last else ."/>
+              </xsl:next-iteration>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:next-iteration>
+                <xsl:with-param name="first" select="$first"/>
+                <xsl:with-param name="last" select="."/>
+              </xsl:next-iteration>
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:iterate>
+      </xsl:variable>
+
+      <xsl:choose>
+        <xsl:when test="$range[1] gt $range[2]">
+          <xsl:sequence select="array { }"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:sequence select="array:subarray($lines, $range[1], $range[2] - $range[1] + 1)"/>
+        </xsl:otherwise>
+      </xsl:choose>
     </xsl:otherwise>
   </xsl:choose>
 </xsl:function>
 
-<xsl:function name="fp:make-lines" as="array(*)">
+<xsl:function name="fp:make-lines-array" as="array(*)">
   <xsl:param name="body" as="node()*"/>
   <xsl:param name="curline" as="item()*"/>
   <xsl:param name="linearray" as="array(*)"/>
@@ -850,15 +892,15 @@
                                 else subsequence($lines, 2, count($lines) - 2)"/>
           <xsl:variable name="arr" select="array:append($linearray, ($curline, $first))"/>
           <xsl:variable name="arr" select="fp:array-append($arr, $middle)"/>
-          <xsl:sequence select="fp:make-lines($cdr, $last, $arr)"/>
+          <xsl:sequence select="fp:make-lines-array($cdr, $last, $arr)"/>
         </xsl:when>
         <xsl:otherwise>
-          <xsl:sequence select="fp:make-lines($cdr, ($curline, $car), $linearray)"/>
+          <xsl:sequence select="fp:make-lines-array($cdr, ($curline, $car), $linearray)"/>
         </xsl:otherwise>
       </xsl:choose>
     </xsl:when>
     <xsl:otherwise>
-      <xsl:sequence select="fp:make-lines($cdr, ($curline, $car), $linearray)"/>
+      <xsl:sequence select="fp:make-lines-array($cdr, ($curline, $car), $linearray)"/>
     </xsl:otherwise>
   </xsl:choose>
 </xsl:function>
@@ -1674,6 +1716,14 @@
                         else f:is-true($verbatim-trim-trailing-blank-lines)"/>
 </xsl:function>
 
+<xsl:function name="f:verbatim-trim-leading" as="xs:boolean">
+  <xsl:param name="context" as="element()"/>
+  <xsl:variable name="pi" select="f:pi($context, 'verbatim-trim-leading')"/>
+  <xsl:sequence select="if ($pi)
+                        then f:is-true($pi)
+                        else f:is-true($verbatim-trim-leading-blank-lines)"/>
+</xsl:function>
+
 <xsl:function name="fp:line-number" as="xs:string">
   <xsl:param name="ln" as="xs:integer"/>
   <xsl:param name="width" as="xs:integer"/>