From ce594bba4eb9ea277d5039431d0803365f593578 Mon Sep 17 00:00:00 2001
From: dhilvert <dhilvert@auricle.dyndns.org>
Date: Fri, 29 Sep 2006 02:22:00 +0000
Subject: [PATCH] doc/: use a stylesheet to generate document meta-information,
 including author,

title, copyright, package name, and package version.

darcs-hash:20060929022238-789c2-96c2f3a8322e31c1f71eccce1623b10c5a77a999.gz
---
 doc/Makefile               |   8 +-
 doc/ale-doc.xsl            | 211 +++++++++++++++++++++++++++++++++++++++++++++
 doc/index.xml              |  11 +--
 doc/package/index.xml      |   4 -
 doc/package/todo/index.xml |   6 +-
 doc/technical/index.xml    |   4 -
 doc/tutorial/index.xml     |   4 -
 doc/user/index.xml         |   4 -
 8 files changed, 224 insertions(+), 28 deletions(-)
 create mode 100644 doc/ale-doc.xsl

diff --git a/doc/Makefile b/doc/Makefile
index b1edd19..37e0663 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -171,7 +171,7 @@ MAN_PARAMS =
 DBX_PARAMS=
 
 # What file extension do you use for DocBook source files?
-DOCBOOK_FILE_EXTENSION = .xml
+DOCBOOK_FILE_EXTENSION = .docbook
 
 # -----------------------------------------------------------------
 #       make(1) functions for building file lists
@@ -402,6 +402,12 @@ debug:
 	@echo $(DIRS_MAN)
 
 # -----------------------------------------------------------------
+#     preprocess xml to docbook.
+# -----------------------------------------------------------------
+%$(DOCBOOK_FILE_EXTENSION): %.xml ale-doc.xsl
+	$(XSLT) $(XSLT_FLAGS) ale-doc.xsl $< > $@
+
+# -----------------------------------------------------------------
 #     pattern rule for making (X)HTML and plain-text output
 # -----------------------------------------------------------------
 %.html: %$(DOCBOOK_FILE_EXTENSION)
diff --git a/doc/ale-doc.xsl b/doc/ale-doc.xsl
new file mode 100644
index 0000000..82ae119
--- /dev/null
+++ b/doc/ale-doc.xsl
@@ -0,0 +1,211 @@
+<!--  
+  -  Copyright 2006 David Hilvert
+  - 
+  -  ALE documentation stylesheet definition.
+  -
+  -  This file is part of the Anti-Lamenessing Engine documentation.
+  -
+  -  The Anti-Lamenessing Engine is free software; you can redistribute it and/or modify
+  -  it under the terms of the GNU General Public License as published by
+  -  the Free Software Foundation; either version 2 of the License, or
+  -  (at your option) any later version.
+  -
+  -  The Anti-Lamenessing Engine is distributed in the hope that it will be useful,
+  -  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  -  GNU General Public License for more details.
+  -
+  -  You should have received a copy of the GNU General Public License
+  -  along with Anti-Lamenessing Engine; if not, write to the Free Software
+  -  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+  -->
+
+<!DOCTYPE xsl:stylesheet [
+
+	<!--
+	  -  Entities
+	  -
+	  -
+	  -  NOTE: all of the below entities operate on edit records, which
+	  -  are expected to conform to exactly one of the following patterns:
+	  -
+	  -  <edit by="GIVEN-NAME SURNAME" on="2006-Sep-24">
+	  -  <edit by="GIVEN-NAME SURNAME" in-month="2006-Sep">
+	  -  <edit by="GIVEN-NAME SURNAME" in-year="2006">
+	  -
+	  -  The first form is preferred for occasional edits; the latter two
+	  -  are provided as shorthand for edits occurring over a number of
+	  -  days in succesion, or for cases where the exact date of the edit
+	  -  is not known (e.g., when basing edit history on copyright notices
+	  -  from older files).
+	  -->
+
+
+	<!--
+	  -  Obtain an editor name from an edit record.
+	  -->
+
+	<!ENTITY editor 'normalize-space(@by)'>
+
+	<!--
+	  -  Obtain an edit year from an edit record.
+	  -->
+
+	<!ENTITY year 'concat(@in-year, substring-before(@in-month, "-"), substring-before(@on, "-"))'>
+
+	<!--
+	  -  Generate a string unique for each (editor, year) combination.
+	  -->
+
+	<!ENTITY editor-year 'concat(&editor;, &year;)'>
+
+	<!--
+	  -  Boolean test to determine whether the current node is within the scope of
+	  -  $objectroot.
+	  -->
+
+	<!ENTITY scope 'count(ancestor::node()|$objectroot) = count(ancestor::node())'>
+
+	<!--
+	  -  Editor first name.
+	  -->
+
+	<!ENTITY editor-firstname 'substring-before(&editor;, " ")'>
+
+	<!--
+	  -  Editor last name
+	  -->
+
+	<!ENTITY editor-surname 'substring-after(&editor;, " ")'>
+
+	<!--
+	  -  Sort order for outputs including editor names.
+	  -->
+
+	<!ENTITY editor-sort-order '&editor-surname;'>
+
+]>
+
+<xsl:stylesheet id="style1"
+                version="1.0"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"
+		xmlns:xi="http://www.w3.org/2001/XInclude">
+
+	<!-- 
+	  -  Product information
+          -->
+
+	<xsl:param name="product-name" select="'ALE'"/>
+
+	<xsl:param name="product-number" select="'0.8.5-prerelease'"/>
+
+	<xsl:param name="copyright-info">
+	  <copyright id="copyright-info">
+	    <year> 2002, 2003, 2004, 2005, 2006 </year>
+	    <holder> David Hilvert </holder>
+	  </copyright>
+	</xsl:param>
+
+	<!-- 
+	  -  Editing information
+          -->
+
+	<xsl:key name="editors" match="edit" use="&editor;"/>
+	<xsl:key name="editor-years" match="edit" use="&editor-year;"/>
+
+	<!-- 
+	  -  If no other template matches, we copy the tree structure unchanged.
+          -->
+
+	<xsl:template match="@*|node()">
+	  <xsl:copy>
+	      <xsl:apply-templates select="@*|node()"/>
+          </xsl:copy>
+	</xsl:template>
+
+	<!-- 
+	  -  Do not pass edit tags to DocBook, as it doesn't understand them.
+          -->
+
+	<xsl:template match="edit"/>
+
+	<!-- 
+	  -  Add package information to titles of articles, books and sets.
+          -->
+
+	<xsl:template match="setinfo/title|bookinfo/title|articleinfo/title">
+	  <title>
+		  <xsl:copy-of select="$product-name"/>
+		  <xsl:text> </xsl:text>
+		  <xsl:copy-of select="$product-number"/>
+		  <xsl:text> </xsl:text>
+	          <xsl:apply-templates/>
+	  </title>
+	</xsl:template>
+
+	<!-- 
+	  -  Generate title, author, and copyright information for articles,
+	  -  books and sets.
+          -->
+
+	<xsl:template match="setinfo|bookinfo|articleinfo">
+	<xsl:copy>
+	  <xsl:param name="objectroot" select=".."/>
+	  <xsl:param name="editors-unique" select="$objectroot//edit[count(.|key('editors', &editor;)[&scope;][1]) = 1]"/>
+	  <xsl:param name="editor-years-unique" select="$objectroot//edit[count(.|key('editor-years', &editor-year;)[&scope;][1]) = 1]"/>
+
+  	  <!-- 
+	    -  Generate the title, if available.
+            -->
+
+	    <xsl:apply-templates select="title"/>
+
+	  <!--
+	    -  Preserve abstracts.
+	    -->
+
+	    <xsl:apply-templates select="abstract"/>
+
+  	  <!-- 
+	    -  Add author information.
+            -->
+
+	    <xsl:for-each select="$editors-unique">
+	      <xsl:sort select="&editor-sort-order;"/>
+	      <author>
+		<firstname>
+		  <xsl:value-of select="&editor-firstname;"/>
+		</firstname>
+		<surname>
+		  <xsl:value-of select="&editor-surname;"/>
+		</surname>
+	      </author>
+	    </xsl:for-each>
+
+  	  <!-- 
+	    -  Add copyright information
+            -->
+
+	    <xsl:for-each select="$editors-unique">
+	      <xsl:sort select="&editor-sort-order;"/>
+	      <xsl:param name="this-editor" select="&editor;"/>
+	      <copyright>
+	      <holder>
+	        <xsl:value-of select="&editor;"/>
+	      </holder>
+	      <xsl:for-each select="$editor-years-unique">
+	        <xsl:if test="&editor; = $this-editor">
+		  <year>
+		    <xsl:value-of select="&year;"/>
+		  </year>
+		</xsl:if>
+	      </xsl:for-each>
+	      </copyright>
+	    </xsl:for-each>
+
+	</xsl:copy>
+	</xsl:template>
+
+
+</xsl:stylesheet>
diff --git a/doc/index.xml b/doc/index.xml
index a6f1373..70c2608 100644
--- a/doc/index.xml
+++ b/doc/index.xml
@@ -1,17 +1,10 @@
 <?xml version="1.0"?>
-
-<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
+<!DOCTYPE set PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
 	"file:///usr/local/share/docbook2X/dtd/Texi-XML">
 
 <set xmlns:xi="http://www.w3.org/2001/XInclude">
 <setinfo>
-  <title>
-    <xi:include href="package-info.xml" xpointer="product-name"/>
-    <xi:include href="package-info.xml" xpointer="product-number"/> 
-    Manuals
-  </title>
-  <xi:include href="package-info.xml" xpointer="author-name"/>
-  <xi:include href="package-info.xml" xpointer="copyright-info"/>
+  <title>Manuals</title>
 </setinfo>
   <xi:include href="package/index.xml"/>
   <xi:include href="tutorial/index.xml"/>
diff --git a/doc/package/index.xml b/doc/package/index.xml
index 6432d3f..2c7bdd4 100644
--- a/doc/package/index.xml
+++ b/doc/package/index.xml
@@ -6,12 +6,8 @@
 <book xmlns:xi="http://www.w3.org/2001/XInclude">
 <bookinfo>
   <title>
-    <xi:include href="../package-info.xml" xpointer="product-name"/>
-    <xi:include href="../package-info.xml" xpointer="product-number"/> 
     Package Manual
   </title>
-  <xi:include href="../package-info.xml" xpointer="author-name"/>
-  <xi:include href="../package-info.xml" xpointer="copyright-info"/>
 </bookinfo>
 <!--  <xi:include href="readme/index.xml"/>
   <xi:include href="news/index.xml"/>
diff --git a/doc/package/todo/index.xml b/doc/package/todo/index.xml
index a53e7d0..52e01db 100644
--- a/doc/package/todo/index.xml
+++ b/doc/package/todo/index.xml
@@ -4,12 +4,14 @@
 	"file:///usr/local/share/docbook2X/dtd/Texi-XML">
 
 <article>
+
+<edit by="David Hilvert" in-month="2006-Sep"/>
+
 <articleinfo xmlns:xi="http://www.w3.org/2001/XInclude">
   <title>To-do list</title>
-  <author><firstname>David</firstname><surname>Hilvert</surname></author>
-  <copyright><year>2006</year><holder>David Hilvert</holder></copyright>
   <abstract>This document contains a tentative list of future versions and features.</abstract>
 </articleinfo>
+
 <section><title>0.8.5 (pre-Beta)</title>
 <note>This release may be combined with the 0.9.0 Beta release.</note>
 <itemizedlist>
diff --git a/doc/technical/index.xml b/doc/technical/index.xml
index 3d7e9aa..ff63b57 100644
--- a/doc/technical/index.xml
+++ b/doc/technical/index.xml
@@ -6,12 +6,8 @@
 <book xmlns:xi="http://www.w3.org/2001/XInclude">
 <bookinfo>
   <title>
-    <xi:include href="../package-info.xml" xpointer="product-name"/>
-    <xi:include href="../package-info.xml" xpointer="product-number"/> 
     Technical Manual
   </title>
-  <xi:include href="../package-info.xml" xpointer="author-name"/>
-  <xi:include href="../package-info.xml" xpointer="copyright-info"/>
 </bookinfo>
 <chapter>
 <section><title>Purpose (foobar)</title>
diff --git a/doc/tutorial/index.xml b/doc/tutorial/index.xml
index 344782a..9aeeeec 100644
--- a/doc/tutorial/index.xml
+++ b/doc/tutorial/index.xml
@@ -6,12 +6,8 @@
 <book xmlns:xi="http://www.w3.org/2001/XInclude">
 <bookinfo>
   <title>
-    <xi:include href="../package-info.xml" xpointer="product-name"/>
-    <xi:include href="../package-info.xml" xpointer="product-number"/> 
     Tutorial
   </title>
-  <xi:include href="../package-info.xml" xpointer="author-name"/>
-  <xi:include href="../package-info.xml" xpointer="copyright-info"/>
 </bookinfo>
 <chapter><title>Introduction</title>
 <section><title>Purpose (foobar)</title>
diff --git a/doc/user/index.xml b/doc/user/index.xml
index e18f59e..555206f 100644
--- a/doc/user/index.xml
+++ b/doc/user/index.xml
@@ -6,12 +6,8 @@
 <book xmlns:xi="http://www.w3.org/2001/XInclude">
 <bookinfo>
   <title>
-    <xi:include href="../package-info.xml" xpointer="product-name"/>
-    <xi:include href="../package-info.xml" xpointer="product-number"/> 
     User Manual
   </title>
-  <xi:include href="../package-info.xml" xpointer="author-name"/>
-  <xi:include href="../package-info.xml" xpointer="copyright-info"/>
 </bookinfo>
 <chapter><title>Introduction</title>
 <section><title>Purpose (foobar)</title>
-- 
2.11.4.GIT