From 5d8ff159be960a083ab483f769d38d09119561dc Mon Sep 17 00:00:00 2001
From: David Lichteblau <david@lichteblau.com>
Date: Thu, 26 Apr 2007 00:39:47 +0200
Subject: [PATCH] stylesheets erklaert

---
 doc/cleanup.xsl  | 37 +++++++++++++++++++++
 doc/html.xsl     | 99 +++++++++++++++++++++++++++++++++++---------------------
 doc/paginate.xsl |  8 +++++
 3 files changed, 108 insertions(+), 36 deletions(-)

diff --git a/doc/cleanup.xsl b/doc/cleanup.xsl
index 9f11cf3..e644814 100644
--- a/doc/cleanup.xsl
+++ b/doc/cleanup.xsl
@@ -1,3 +1,40 @@
+<!--
+    The first stylesheet to be used, this file cleans up the structure
+    of the Lisp-generated XML file by extracting elements from all
+    docstrings into their parent elements, so that only the textual
+    description remains in the <documentation-string>.
+
+    Example (input):
+
+    <class name="foo">
+      <cpl>...</cpl>
+
+      <documentation-string>
+	The foo class.
+	<see-slot id="foo">See also the foo function.</see-slot>
+	Beware bugs.
+      </documentation-string>
+    </class>
+
+    Output:
+
+    <class name="foo">
+      <cpl>...</cpl>
+
+      <see-also>
+	<slot>
+	  <see id="foo">See also the foo function.</see>
+	</slot>
+      </see-also>
+
+      <documentation-string>
+	The foo class.
+	Beware bugs.
+      </documentation-string>
+    </class>
+
+  -->
+
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:output method="xml" indent="yes"/>
 
diff --git a/doc/html.xsl b/doc/html.xsl
index f41b32c..2e2b833 100644
--- a/doc/html.xsl
+++ b/doc/html.xsl
@@ -1,3 +1,16 @@
+<!--
+    This this the main stylesheet.
+    Input must have been cleaned up using cleanup.xsl already.
+
+    This stylesheet does nearly all of the formatting work, but still keeps
+    all data together in one big XML document.
+
+    A <page> element is produced for each package and symbol.
+
+    The contents of each <page> will be mostly HTML, with the exception
+    of a few formatting elements like <columns> that are replaced later.
+
+  -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:output method="xml" indent="yes"/>
 
@@ -13,6 +26,11 @@
     <xsl:apply-templates/>
   </xsl:template>
 
+
+  <!--
+      page generation templates
+    -->
+
   <xsl:template match="documentation">
     <main-page title="@title">
       Index of packages:
@@ -31,42 +49,6 @@
     </main-page>
   </xsl:template>
 
-  <xsl:template match="class" mode="symbol-index">
-    <a href="{@id}.html">
-      <tt><xsl:value-of select="@name"/></tt>
-    </a>
-    <xsl:text>, class</xsl:text>
-    <xsl:call-template name="undocumented"/>
-    <br/>
-  </xsl:template>
-
-  <xsl:template match="function" mode="symbol-index">
-    <a href="{@id}.html">
-      <tt><xsl:value-of select="@name"/></tt>
-    </a>
-    <xsl:text>, function</xsl:text>
-    <xsl:call-template name="undocumented"/>
-    <br/>
-  </xsl:template>
-
-  <xsl:template match="macro" mode="symbol-index">
-    <a href="{@id}.html">
-      <tt><xsl:value-of select="@name"/></tt>
-    </a>
-    <xsl:text>, macro</xsl:text>
-    <xsl:call-template name="undocumented"/>
-    <br/>
-  </xsl:template>
-
-  <xsl:template match="variable" mode="symbol-index">
-    <a href="{@id}.html">
-      <tt><xsl:value-of select="@name"/></tt>
-    </a>
-    <xsl:text>, variable</xsl:text>
-    <xsl:call-template name="undocumented"/>
-    <br/>
-  </xsl:template>
-
   <xsl:template match="package">
     <page base="../"
 	  pathname="pages/{@id}.html"
@@ -207,6 +189,51 @@
     </page>
   </xsl:template>
 
+
+  <!--
+      Symbol index
+    -->
+  <xsl:template match="class" mode="symbol-index">
+    <a href="{@id}.html">
+      <tt><xsl:value-of select="@name"/></tt>
+    </a>
+    <xsl:text>, class</xsl:text>
+    <xsl:call-template name="undocumented"/>
+    <br/>
+  </xsl:template>
+
+  <xsl:template match="function" mode="symbol-index">
+    <a href="{@id}.html">
+      <tt><xsl:value-of select="@name"/></tt>
+    </a>
+    <xsl:text>, function</xsl:text>
+    <xsl:call-template name="undocumented"/>
+    <br/>
+  </xsl:template>
+
+  <xsl:template match="macro" mode="symbol-index">
+    <a href="{@id}.html">
+      <tt><xsl:value-of select="@name"/></tt>
+    </a>
+    <xsl:text>, macro</xsl:text>
+    <xsl:call-template name="undocumented"/>
+    <br/>
+  </xsl:template>
+
+  <xsl:template match="variable" mode="symbol-index">
+    <a href="{@id}.html">
+      <tt><xsl:value-of select="@name"/></tt>
+    </a>
+    <xsl:text>, variable</xsl:text>
+    <xsl:call-template name="undocumented"/>
+    <br/>
+  </xsl:template>
+
+
+  <!--
+      Other templates
+    -->
+
   <xsl:template match="arguments">
     <h3>Arguments</h3>
     <div class="indent">
diff --git a/doc/paginate.xsl b/doc/paginate.xsl
index 8800fc5..84cd98b 100644
--- a/doc/paginate.xsl
+++ b/doc/paginate.xsl
@@ -1,3 +1,11 @@
+<!--
+    The final stylesheet for HTML generation.
+
+    This file splits up the XML document and its <page> elements into
+    individual HTML files.
+
+    A few formatting elements like <columns> are resolved here.
+  -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:output method="html"
 	      indent="yes"
-- 
2.11.4.GIT