Adding more XSLTdoc Documentation.

jhellingman · Dec 5, 2011 · 81af70a · 81af70a
1 parent 78538f9
commit 81af70a
Show file tree

Hide file tree

Showing 6 changed files with 96 additions and 22 deletions.
diff --git a/review-translations.xsl b/review-translations.xsl
@@ -1,20 +1,25 @@
 <xsl:transform
     xmlns:msg="http://www.gutenberg.ph/2006/schemas/messages"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:xd="http://www.pnp-software.com/XSLTdoc"
     version="1.0"
-    exclude-result-prefixes="msg"
->
+    exclude-result-prefixes="msg xd">
 
     <xsl:output
         doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"
         doctype-system="http://www.w3.org/TR/html4/loose.dtd"
         method="html"
         encoding="UTF-8"/>
 
-    <!-- review translations in our messages.xml -->
+    <xd:doc type="stylesheet">
+        <xd:short>TEI stylesheet to review translations in our localization xml-files.</xd:short>
+        <xd:detail> </xd:detail>
+        <xd:author>Jeroen Hellingman</xd:author>
+        <xd:copyright>2011, Jeroen Hellingman</xd:copyright>
+    </xd:doc>
 
-    <xsl:variable name="srclang" select="'en'"/>
-    <xsl:variable name="destlang" select="'de'"/>
+    <xsl:param name="srclang" select="'en'"/>
+    <xsl:param name="destlang" select="'de'"/>
 
     <xsl:strip-space elements="*"/>
 

diff --git a/samples/PhilippineFolkTales.xml → ...ippine Folk Tales/PhilippineFolkTales.xml b/samples/PhilippineFolkTales.xml → ...ippine Folk Tales/PhilippineFolkTales.xml
diff --git a/tei2html.xsl b/tei2html.xsl
@@ -63,15 +63,31 @@
 
     <!--====================================================================-->
 
+    <xd:doc type="string">Name used as prefix for generated file names (not relevant for HTML, but required for some included stylesheets).</xd:doc>
     <xsl:param name="basename" select="'book'"/>
-    <xsl:param name="path" select="''"/> <!-- Not used for HTML versions -->
 
+    <xd:doc type="string">Path in which generated file will be placed (not relevant for HTML, but required for some included stylesheets).</xd:doc>
+    <xsl:param name="path" select="''"/>
+
+    <xd:doc type="string">Generate special markup used by PrinceXML to generate PDF files (Yes or No).</xd:doc>
     <xsl:param name="optionPrinceMarkup" select="'No'"/>
+
+    <xd:doc type="string">Generate special markup used in ePub files (Yes or No).</xd:doc>
     <xsl:param name="optionEPubMarkup" select="'No'"/>
+
+    <xd:doc type="string">Generate special markup used in ePub3 files (Yes or No).</xd:doc>
     <xsl:param name="optionEPub3" select="'No'"/>
+
+    <xd:doc type="string">Generate Project Gutenberg headers and footers (Yes or No).</xd:doc>
     <xsl:param name="optionPGHeaders" select="'No'"/>
+
+    <xd:doc type="string">Output paragraph numbers, using the value of the @n attribute (Yes or No).</xd:doc>
     <xsl:param name="optionParagraphNumbers" select="'No'"/>
+
+    <xd:doc type="string">Include images in the generated output (Yes or No).</xd:doc>
     <xsl:param name="optionIncludeImages" select="'Yes'"/>
+
+    <xd:doc type="string">Include external links in the generated output (Yes or No).</xd:doc>
     <xsl:param name="optionExternalLinks" select="'Yes'"/>
 
 

diff --git a/tei2wl.xsl b/tei2wl.xsl
@@ -3,10 +3,16 @@
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     xmlns:fn="http://www.w3.org/2005/xpath-functions"
     xmlns:f="urn:stylesheet-functions"
-    exclude-result-prefixes="f fn xs"
+    xmlns:xd="http://www.pnp-software.com/XSLTdoc"
+    exclude-result-prefixes="f fn xd xs"
     >
 
-<!-- Stylesheet to produce a word frequency list (per language) from any XML document -->
+    <xd:doc type="stylesheet">
+        <xd:short>Stylesheet to produce a word frequency list (per language) from any XML document</xd:short>
+        <xd:detail> </xd:detail>
+        <xd:author>Jeroen Hellingman</xd:author>
+        <xd:copyright>2011, Jeroen Hellingman</xd:copyright>
+    </xd:doc>
 
 <xsl:output omit-xml-declaration="yes" indent="yes"/>
 

diff --git a/utils.xsl b/utils.xsl
@@ -38,7 +38,7 @@
 
     <xd:doc>
         <xd:short>Generate an HTML anchor.</xd:short>
-        <xd:detail>Generate an HTML anchor with an id attribute for the current node.</xd:detail>
+        <xd:detail>Generate an HTML anchor with an <code>id</code> attribute for the current node.</xd:detail>
     </xd:doc>
 
     <xsl:template name="generate-anchor">
@@ -47,12 +47,23 @@
         </a>
     </xsl:template>
 
+    <xd:doc>
+        <xd:short>Generate an <code>id</code> attribute.</xd:short>
+        <xd:detail>Generate an <code>id</code> attribute for the current node.</xd:detail>
+    </xd:doc>
+
     <xsl:template name="generate-id-attribute">
         <xsl:attribute name="id">
             <xsl:call-template name="generate-id"/>
         </xsl:attribute>
     </xsl:template>
 
+    <xd:doc>
+        <xd:short>Generate an <code>id</code>-attribute.</xd:short>
+        <xd:detail>Generate an <code>id</code>-attribute for a node (default: current node).</xd:detail>
+        <xd:param>The node for which the <code>id</code>-attribute is generated.</xd:param>
+    </xd:doc>
+
     <xsl:template name="generate-id-attribute-for">
         <xsl:param name="node" select="." as="element()"/>
         <xsl:attribute name="id">
@@ -62,25 +73,37 @@
         </xsl:attribute>
     </xsl:template>
 
+    <xd:doc>
+        <xd:short>Generate an <code>id</code>-value.</xd:short>
+        <xd:detail>Generate an <code>id</code>-value for the current node.</xd:detail>
+        <xd:param name="node">The node for which the <code>id</code>-value is generated.</xd:param>
+    </xd:doc>
+
     <xsl:template name="generate-id">
         <xsl:call-template name="generate-id-for">
             <xsl:with-param name="node" select="."/>
         </xsl:call-template>
     </xsl:template>
 
-    <!--
-        We want to generate ids that are slightly more stable than using generate-id().
-        The general idea is to use an explicit id if that is present, and otherwise create
-        an id based on the path to the first ancestor node that does have an id. If,
-        for example the third paragraph of a division with id 'ch2' has no id of itself,
-        we generate: "ch2_p_3" as an id. The second note in this paragraph would receive
-        the id "ch2_p_3_note_2".
-
-        Safe ID syntax:
-            HTML:       [A-Za-z][A-Za-z0-9_:.-]*
-            CSS:        -?[_a-zA-Z]+[_a-zA-Z0-9-]*
-            Combined:   [A-Za-z][A-Za-z0-9_-]*
-    -->
+    <xd:doc>
+        <xd:short>Generate a stable <code>id</code>-value.</xd:short>
+        <xd:detail>
+            <p>We want to generate ids that are slightly more stable than using generate-id().
+            The general idea is to use an explicit id if that is present, and otherwise create
+            an id based on the path to the first ancestor node that does have an id. If,
+            for example the third paragraph of a division with id '<code>ch2</code>' has no id of itself,
+            we generate: "<code>ch2_p_3</code>" as an id. The second note in this paragraph would receive
+            the id "<code>ch2_p_3_note_2</code>".</p>
+
+            <table>
+                <tr><th>Language    </th><th>Safe ID syntax </th></tr>
+                <tr><td>HTML:       </td><td><code>[A-Za-z][A-Za-z0-9_:.-]*</code></td></tr>
+                <tr><td>CSS:        </td><td><code>-?[_a-zA-Z]+[_a-zA-Z0-9-]*</code></td></tr>
+                <tr><td>Combined:   </td><td><code>[A-Za-z][A-Za-z0-9_-]*</code></td></tr>
+            </table>
+        </xd:detail>
+        <xd:param name="node">The node for which the <code>id</code>-value is generated (default: the current node).</xd:param>
+    </xd:doc>
 
     <xsl:template name="generate-stable-id-for">
         <xsl:param name="node" select="."/>
@@ -122,6 +145,17 @@
         </xsl:choose>
     </xsl:template>
 
+    <xd:doc>
+        <xd:short>Generate an <code>id</code>-value.</xd:short>
+        <xd:detail>
+            <p>Generate an <code>id</code>-value for a node (by default the current node).</p>
+            <p>The generated id will re-use the existing <code>id</code> attribute if present, or use the <code>generate-id()</code> function otherwise.
+            Such generated id's will be prefixed with the letter 'x'</p>
+        </xd:detail>
+        <xd:param name="node">The node for which the <code>id</code>-value is generated.</xd:param>
+        <xd:param name="position" type="string">A value appended after the generated <code>id</code>.</xd:param>
+    </xd:doc>
+
     <xsl:template name="generate-id-for">
         <xsl:param name="node" select="." as="element()"/>
         <xsl:param name="position"/>
@@ -214,6 +248,14 @@
     <!--====================================================================-->
     <!-- Generate labels for heads in the correct language -->
 
+    <xd:doc>
+        <xd:short>Translate the <code>type</code>-attribute of a division.</xd:short>
+        <xd:detail>
+            <p>Translate the <code>type</code>-attribute of a division to a string in the currently active language.</p>
+        </xd:detail>
+        <xd:param name="type" type="string">The value of the <code>type</code>-attribute.</xd:param>
+    </xd:doc>
+
     <xsl:function name="f:translate-div-type" as="xs:string">
         <xsl:param name="type"/>
         <xsl:variable name="type" select="lower-case($type)"/>

diff --git a/xsltdoc.config b/xsltdoc.config
@@ -30,7 +30,12 @@
   <RootStylesheets>
     <File href="tei2html.xsl"/>
     <File href="tei2epub.xsl"/>
+
+    <File href="review-translations.xsl"/>
+    <File href="tei2wl.xsl"/>
+    <File href="tei2dc.xsl"/>
     <File href="pgtei2tei.xsl"/>
+    <File href="tei2pgtei.xsl"/>
   </RootStylesheets>
 
   <!--