Improve code documentation

jhellingman · Apr 21, 2024 · a2482a1 · a2482a1
1 parent 670cb98
commit a2482a1
Show file tree

Hide file tree

Showing 12 changed files with 83 additions and 26 deletions.
diff --git a/merge-documents.xsl b/merge-documents.xsl
@@ -90,8 +90,13 @@
     </xsl:function>
 
 
+    <xd:doc mode="prefix-id">
+        <xd:short>Mode used to prefix ids with a given prefix.</xd:short>
+    </xd:doc>
+
+
     <xd:doc>
-        <xd:short>Do not mess with language IDs.</xd:short>
+        <xd:short>Do not change language IDs.</xd:short>
     </xd:doc>
 
     <xsl:template match="language/@id" mode="prefix-id">
@@ -100,7 +105,7 @@
 
 
     <xd:doc>
-        <xd:short>Translate IDs in <code>@id</code> attribute.</xd:short>
+        <xd:short>Translate IDs in <code>@id</code> attributes.</xd:short>
     </xd:doc>
 
     <xsl:template match="@id" mode="prefix-id">

diff --git a/modules/block.xsl b/modules/block.xsl
@@ -161,6 +161,12 @@
     </xsl:function>
 
 
+    <xd:doc>
+        <xd:short>Generate a link to a facsimile image.</xd:short>
+        <xd:detail>Generate a direct HTML link to a facsimile image.</xd:detail>
+        <xd:param name="url">The URL of the facsimile image.</xd:param>
+    </xd:doc>
+
     <xsl:function name="f:facsimile-direct-link">
         <xsl:param name="url" as="xs:string"/>
         <xsl:variable name="url" select="f:translate-xref-url($url, substring(f:get-document-lang(), 1, 2))"/>
@@ -176,7 +182,6 @@
 
     <xd:doc>
         <xd:short>Generate anchor for a <code>pb</code>-element.</xd:short>
-        <xd:detail>Generate an anchor for a <code>pb</code>-element.</xd:detail>
     </xd:doc>
 
     <xsl:template name="pb-anchor">
@@ -223,12 +228,10 @@
     <!--=== Thematic Breaks ================================================-->
 
     <xd:doc>
-        <xd:short>Handle a milestone (thematic break).</xd:short>
-        <xd:detail>Handle a document milestone. This is mostly used to encode thematic breaks. Generates
-        slightly different outputs, depending on the <code>@type</code> and <code>@rend</code>-attributes.</xd:detail>
+        <xd:short>A map with various types of milestone markers.</xd:short>
     </xd:doc>
 
-    <xsl:variable name="milestone-markers" select="
+    <xsl:variable name="milestone-markers" as="map(xs:string, xs:string)" select="
         map {
             'dots'     : '. . . . . . . . . . . . . . . . . . . . .',
             'dashes'   : '- - - - - - - - - - - - - - - - - - - - -',
@@ -240,6 +243,12 @@
         }">
     </xsl:variable>
 
+    <xd:doc>
+        <xd:short>Handle a milestone (thematic break).</xd:short>
+        <xd:detail>Handle a document milestone. This is mostly used to encode thematic breaks. Generates
+            slightly different outputs, depending on the <code>@type</code> and <code>@rend</code>-attributes.</xd:detail>
+    </xd:doc>
+
     <xsl:template match="milestone[@unit='theme' or @unit='tb']">
         <xsl:call-template name="closepar"/>
         <xsl:choose>
@@ -289,7 +298,7 @@
     </xsl:template>
 
 
-    <xsl:function name="f:repeat">
+    <xsl:function name="f:repeat" as="xs:string">
         <xsl:param name="input" as="xs:string"/>
         <xsl:param name="separator" as="xs:string"/>
         <xsl:param name="count" as="xs:integer"/>
@@ -398,10 +407,10 @@
     <xd:doc>
         <xd:short>Determine the nesting level of a quotation in a paragraph.</xd:short>
         <xd:detail>Count from the most direct ancestor that is a block element, for now consider p, note, cell, item, and q[f:is-block(.)];
-             count the number of q ancestors between that and self.</xd:detail>
+             count the number of <code>q</code> ancestors between that and self.</xd:detail>
     </xd:doc>
 
-    <xsl:function name="f:quote-nesting-level">
+    <xsl:function name="f:quote-nesting-level" as="xs:integer">
         <xsl:param name="q" as="element(q)"/>
         <xsl:sequence select="count($q/ancestor::q[ancestor::*[name() = ('p', 'note', 'cell', 'item') or f:is-block(.)]]) + 1"/>
     </xsl:function>
@@ -693,7 +702,7 @@
     <xsl:template name="handle-initial-image">
         <xsl:context-item as="element()" use="required"/>
         <xsl:choose>
-            <xsl:when test="f:useInitialImageWithFloat()">
+            <xsl:when test="f:use-initial-image-with-float()">
                 <xsl:call-template name="initial-image-with-float"/>
             </xsl:when>
             <xsl:otherwise>
@@ -703,8 +712,8 @@
     </xsl:template>
 
 
-    <xsl:function name="f:useInitialImageWithFloat" as="xs:boolean">
-        <xsl:sequence select="$optionPrinceMarkup = 'Yes' or f:is-epub() or f:is-set('pg.compliant')"/>
+    <xsl:function name="f:use-initial-image-with-float" as="xs:boolean">
+        <xsl:sequence select="f:is-pdf() or f:is-epub() or f:is-set('pg.compliant')"/>
     </xsl:function>
 
 
@@ -727,7 +736,9 @@
     </xsl:template>
 
 
-    <xsl:variable name="open-quotation-mark" select="('&ldquo;', '&lsquo;', '&rsquo;', '&bdquo;', '&laquo;', '&raquo;')"/>
+    <xd:doc>A list of open quotation marks, used when handling decorative initials.</xd:doc>
+
+    <xsl:variable name="open-quotation-mark" select="('&ldquo;', '&lsquo;', '&rsquo;', '&bdquo;', '&laquo;', '&raquo;')" as="xs:string*"/>
 
     <xsl:function name="f:replaced-initial" as="xs:string">
         <xsl:param name="text" as="xs:string"/>
@@ -775,7 +786,7 @@
 
     <xsl:template name="handle-initial-image-css">
         <xsl:context-item as="element()" use="required"/>
-        <xsl:if test="not(f:useInitialImageWithFloat())">
+        <xsl:if test="not(f:use-initial-image-with-float())">
             <xsl:if test="generate-id() = generate-id(key('rend', name() || ':' || @rend)[1])">
                 <xsl:variable name="css-properties" select="f:translate-rend-ladder(@rend, name())"/>
                 <xsl:variable name="scale-factor" select="xs:decimal(f:get-setting('images.scale'))" as="xs:decimal"/>

diff --git a/modules/css.xsl b/modules/css.xsl
@@ -68,7 +68,7 @@
         </xsl:call-template>
 
         <!-- Pull in CSS sheet for print (when using Prince). -->
-        <xsl:if test="f:is-set('css.useCommonPrint') and $optionPrinceMarkup = 'Yes'">
+        <xsl:if test="f:is-set('css.useCommonPrint') and f:is-pdf()">
             <style type="text/css" media="print">
                 <xsl:value-of select="f:css-stylesheet('../style/print.css')"/>
             </style>

diff --git a/modules/functions.xsl b/modules/functions.xsl
@@ -11,7 +11,7 @@
 
     <xd:doc type="stylesheet">
         <xd:short>Utility functions, used by tei2html</xd:short>
-        <xd:detail>This stylesheet contains several utility functions, used by tei2html and tei2epub.</xd:detail>
+        <xd:detail><p>This stylesheet contains several utility functions, used by <code>tei2html</code> and <code>tei2epub</code>.</p></xd:detail>
         <xd:author>Jeroen Hellingman</xd:author>
         <xd:copyright>2021, Jeroen Hellingman</xd:copyright>
     </xd:doc>
@@ -61,8 +61,8 @@
 
     <xd:doc>
         <xd:short>Provide a default value when a value is null.</xd:short>
-        <xd:param name="value" type="string">The value to be tested.</xd:param>
-        <xd:param name="default" type="string">The default value.</xd:param>
+        <xd:param name="value">The value to be tested.</xd:param>
+        <xd:param name="default">The default value.</xd:param>
     </xd:doc>
 
     <xsl:function name="f:if-null">
@@ -71,6 +71,11 @@
         <xsl:sequence select="if (not($value)) then $default else $value"/>
     </xsl:function>
 
+    <xd:doc mode="plain-text">
+        <xd:short>Mode to convert nodes tree to plain text. Only one branch of choice elements will be included.</xd:short>
+    </xd:doc>
+
+    <xsl:mode name="plain-text"/>
 
     <xd:doc>
         <xd:short>Convert a node tree to plain text. Only one branch of choice elements will be included.</xd:short>

diff --git a/modules/levenshtein.xsl b/modules/levenshtein.xsl
@@ -9,9 +9,19 @@
                 exclude-result-prefixes="f xd xs">
 
     <xd:doc type="stylesheet">
+        <xd:short>Functions to calculate the Levenshtein distance between two strings.</xd:short>
+        <xd:detail>
+            <p>This stylesheet is based on the algorithm given by Jeni Tennison, see his article
+                <a href="https://www.jenitennison.com/2007/05/06/levenshtein-distance-on-the-diagonal.html"><i>Levenshtein distance on the diagonal</i></a>.
+            </p>
+        </xd:detail>
+    </xd:doc>
+
+    <xd:doc>
         <xd:short>Calculate the Levenshtein distance between two strings.</xd:short>
-        <xd:detail>This stylesheet is based on the algorithm given by Jeni Tennison, see
-            https://www.jenitennison.com/2007/05/06/levenshtein-distance-on-the-diagonal.html.</xd:detail>
+        <xd:detail><p>This is the top-level function, intended to be called by external stylesheets.</p></xd:detail>
+        <xd:param name="a">The first string.</xd:param>
+        <xd:param name="b">The second string.</xd:param>
     </xd:doc>
 
     <xsl:function name="f:levenshtein" as="xs:integer">
@@ -28,6 +38,11 @@
                 (1, 0, 1), 2)"/>
     </xsl:function>
 
+    <xd:doc>
+        <xd:short>Calculate the Levenshtein distance between two strings.</xd:short>
+        <xd:detail><p>This function should not be called by external stylesheets.</p></xd:detail>
+    </xd:doc>
+
     <xsl:function name="f:calculate-levenshtein-distance" as="xs:integer">
         <xsl:param name="chars1" as="xs:integer*"/>
         <xsl:param name="chars2" as="xs:integer*"/>

diff --git a/modules/utils.xsl b/modules/utils.xsl
@@ -549,6 +549,10 @@
         <xsl:sequence select="exists($root//*[f:rend-value(./@rend, 'align-with') = $node/@id])"/>
     </xsl:function>
 
+    <xsl:function name="f:is-pdf" as="xs:boolean">
+        <xsl:sequence select="$optionPrinceMarkup = 'Yes'"/>
+    </xsl:function>
+
     <xsl:function name="f:is-epub" as="xs:boolean">
         <xsl:sequence select="$outputFormat = 'epub'"/>
     </xsl:function>

diff --git a/schemas/xsltdoc.xsd b/schemas/xsltdoc.xsd
@@ -20,8 +20,10 @@
       <xs:element name="short" type="HtmlText"/>
       <xs:element name="detail" type="HtmlText"/>
       <xs:element name="author" type="xs:string"/>
+      <xs:element name="since" type="xs:string"/>
       <xs:element name="cvsId" type="xs:string"/>
       <xs:element name="copyright" type="xs:string"/>
+      <xs:element name="private" type="xs:boolean"/>
       <xs:element name="param" type="Param" minOccurs="0" maxOccurs="unbounded"/>
     </xs:sequence>
     <xs:attribute name="type" type="DocType"/>
@@ -37,6 +39,7 @@
       <xs:enumeration value="mode"/>
       <xs:enumeration value="string"/>
       <xs:enumeration value="mode"/>
+      <xs:enumeration value="void"/>
     </xs:restriction>
   </xs:simpleType>
 
@@ -47,7 +50,9 @@
   </xs:complexType>
 
   <xs:complexType name="Param" mixed="true">
-    <xs:any namespace="http://www.w3.org/1999/xhtml" minOccurs="0" maxOccurs="unbounded"/>
+    <xs:sequence>
+      <xs:any namespace="http://www.w3.org/1999/xhtml" minOccurs="0" maxOccurs="unbounded"/>
+    </xs:sequence>
     <xs:attribute name="name" type="xs:string"/>
     <xs:attribute name="type" type="ParamType"/>
   </xs:complexType>
@@ -59,7 +64,16 @@
     <xs:restriction base="xs:string">
       <xs:enumeration value="string"/>
       <xs:enumeration value="boolean"/>
+      <xs:enumeration value="int"/>
+      <xs:enumeration value="node-set"/>
     </xs:restriction>
   </xs:simpleType>
 
+  <!-- The tag mode is only used as a temporary object in the XSLT code! -->
+  <xs:element name="mode" type="Mode"/>
+
+  <xs:complexType name="Mode">
+    <xs:attribute name="name" type="xs:string"/>
+  </xs:complexType>
+
 </xs:schema>
diff --git a/tei2html.xsl b/tei2html.xsl
@@ -70,7 +70,7 @@
     <xsl:variable name="outputMethod" select="document('')/xsl:stylesheet/xsl:output/@method"/>
     <xsl:variable name="outputFormat" select="'html5'"/>
 
-    <xsl:variable name="p.element" select="if ($optionPrinceMarkup = 'Yes') then 'div' else 'p'"/>
+    <xsl:variable name="p.element" select="if (f:is-pdf()) then 'div' else 'p'"/>
 
     <!--====================================================================-->
 

diff --git a/tei2html5.xsl b/tei2html5.xsl
@@ -69,7 +69,7 @@
     <xsl:variable name="outputMethod" select="document('')/xsl:stylesheet/xsl:output/@method"/>
     <xsl:variable name="outputFormat" select="'html5'"/>
 
-    <xsl:variable name="p.element" select="if ($optionPrinceMarkup = 'Yes') then 'div' else 'p'"/>
+    <xsl:variable name="p.element" select="if (f:is-pdf()) then 'div' else 'p'"/>
 
     <!--====================================================================-->
 

diff --git a/tei2xhtml.xsl b/tei2xhtml.xsl
@@ -68,7 +68,7 @@
     <xsl:variable name="outputMethod" select="document('')/xsl:stylesheet/xsl:output/@method"/>
     <xsl:variable name="outputFormat" select="'html5'"/>
 
-    <xsl:variable name="p.element" select="if ($optionPrinceMarkup = 'Yes') then 'div' else 'p'"/>
+    <xsl:variable name="p.element" select="if (f:is-pdf()) then 'div' else 'p'"/>
 
     <!--====================================================================-->
 

diff --git a/tools/SgmlSupport.pm b/tools/SgmlSupport.pm
@@ -1515,6 +1515,8 @@ BEGIN {
 
     $ent{'Peso'}        = chr(0x20B1);  # Peso sign
     $ent{'Euro'}        = chr(0x20AC);  # Euro sign
+    $ent{'Rupee'}       = "Re.";        # Rupee sign (singular; also seen as R with strike-through, not in Unicode).
+    $ent{'Rupees'}      = "Rs.";        # Rupees sign (plural; could also use U+20A8. Do not use the modern Indian rupee U+20B9 sign here!)
 
     $ent{'triangle'}    = chr(0x25B3);  # White triangle
 

diff --git a/xspec/test-tei2html.xsl b/xspec/test-tei2html.xsl
@@ -3,6 +3,7 @@
 
 <xsl:stylesheet version="3.0"
     xmlns="http://www.w3.org/1999/xhtml"
+    xmlns:f="urn:stylesheet-functions"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
     <xsl:include href="../modules/functions.xsl"/>
@@ -50,7 +51,7 @@
     <xsl:variable name="outputMethod" select="document('')/xsl:stylesheet/xsl:output/@method"/>
     <xsl:variable name="outputFormat" select="'html'"/>
 
-    <xsl:variable name="p.element" select="if ($optionPrinceMarkup = 'Yes') then 'div' else 'p'"/>
+    <xsl:variable name="p.element" select="if (f:is-pdf()) then 'div' else 'p'"/>
 
     <xsl:template match="/">
         <xsl:apply-templates/>