Updated embedded doc in XSL source files:

 - added dbhtml@dir PIs to control where output goes when
   generation HTML version of docs

 - put xml:id instances on root elements of embedded doc

 - changed all *info instances to just info (DocBook 5) and some
   @id instance to @xml-id

diff --git a/xsl/common/common.xsl b/xsl/common/common.xsl
index 30476ef6e99fce010c0e676b11711daf445fe9a0..4484286772b342538ead513374d410c7676a0b60 100644 (file)
--- a/xsl/common/common.xsl
+++ b/xsl/common/common.xsl
@@ -14,38 +14,24 @@
      See ../README or http://docbook.sf.net/release/xsl/current/ for
      copyright and other information.
 
-     This file contains general templates common to both the HTML and FO
-     versions of the DocBook stylesheets.
      ******************************************************************** -->
 
-<doc:reference xmlns="">
-<referenceinfo>
-<releaseinfo role="meta">
-$Id$
-</releaseinfo>
-<author><surname>Walsh</surname>
-<firstname>Norman</firstname></author>
-<copyright><year>1999-2007</year>
-<holder>Norman Walsh</holder>
-</copyright>
-</referenceinfo>
-<title>Common Template Reference</title>
-
-<partintro id="partintro">
-<title>Introduction</title>
-
-<para>This is technical reference documentation for the “common”
-templates in the DocBook XSL Stylesheets. The common templates are
-“common” because they are shared across output formats (that is,
-they’re not output-format-dependent).</para>
-
-<para>This documentation is not intended to be <quote>user</quote>
-documentation.  It is provided for developers writing
-customization layers for the stylesheets, and for anyone who's
-interested in <quote>how it works</quote>.</para>
-
-</partintro>
-
+<doc:reference xmlns="" xml:id="base">
+  <info>
+    <releaseinfo role="meta">
+      $Id$
+    </releaseinfo>
+  </info>
+  <title>Common » Base Template Reference</title>
+  <!-- * yes, partintro is a valid child of a reference... -->
+  <partintro xml:id="partintro">
+    <title>Introduction</title>
+    <para>This is technical reference documentation for the “base”
+      set of common templates in the DocBook XSL Stylesheets.</para>
+    <para>This is not intended to be user documentation. It is
+      provided for developers writing customization layers for the
+      stylesheets.</para>
+  </partintro>
 </doc:reference>
 
 <!-- ==================================================================== -->

diff --git a/xsl/common/refentry.xsl b/xsl/common/refentry.xsl
index 4373e4849cc0b11d8e02f523244faff09f1e3821..d3fa7dd5c16f32ac5965f3c479a494d2934e6345 100644 (file)
--- a/xsl/common/refentry.xsl
+++ b/xsl/common/refentry.xsl
@@ -16,36 +16,25 @@
      ******************************************************************** -->
 
 <!-- ==================================================================== -->
-<doc:reference xmlns="">
-  <referenceinfo>
+<doc:reference xmlns="" xml:id="refentry">
+  <info>
     <releaseinfo role="meta">
       $Id$
     </releaseinfo>
-    <corpauthor>The DocBook Project</corpauthor>
-    <copyright>
-      <year>2005-2007</year>
-      <holder>The DocBook Project</holder>
-    </copyright>
-  </referenceinfo>
-  <title>Refentry Metadata-Gathering Template Reference</title>
-
-  <partintro id="partintro">
+  </info>
+  <title>Common » Refentry Metadata Template Reference</title>
+  <!-- * yes, partintro is a valid child of a reference... -->
+  <partintro xml:id="partintro">
     <title>Introduction</title>
-
-    <para>This is technical reference documentation for the "refentry
-    metadata gathering" templates in the DocBook XSL Stylesheets.</para>
-
+    <para>This is technical reference documentation for the “refentry
+    metadata” templates in the DocBook XSL Stylesheets.</para>
     <para>This is not intended to be user documentation. It is provided
-    for developers writing customization layers for the
-    stylesheets.</para>
-
+    for developers writing customization layers for the stylesheets.</para>
     <note>
       <para>Currently, only the manpages stylesheets make use of these
       templates. They are, however, potentially useful elsewhere.</para>
     </note>
-
   </partintro>
-
 </doc:reference>
 
 <!-- ==================================================================== -->

diff --git a/xsl/common/utility.xsl b/xsl/common/utility.xsl
index f483f8e35b579716c34f32648c8568044646a084..3c01be0ba02f9900cbbbe047fdd2e9204c88cb09 100644 (file)
--- a/xsl/common/utility.xsl
+++ b/xsl/common/utility.xsl
@@ -7,7 +7,7 @@
                 version='1.0'>
 
 <!-- ********************************************************************
-     $Id: common.xsl 6867 2007-06-25 04:36:37Z xmldoc $
+     $Id$
      ********************************************************************
 
      This file is part of the XSL DocBook Stylesheet distribution.
@@ -15,42 +15,33 @@
      copyright and other information.
 
      ******************************************************************** -->
-
-<doc:reference xmlns="">
-<referenceinfo>
-<releaseinfo role="meta">
-$Id: common.xsl 6867 2007-06-25 04:36:37Z xmldoc $
-</releaseinfo>
-<corpauthor>The DocBook Project Development Team</corpauthor>
-<copyright><year>2007</year>
-<holder>The DocBook Project</holder>
-</copyright>
-</referenceinfo>
-<title>Utility Template Reference</title>
-
-<partintro id="partintro">
-<title>Introduction</title>
-
-<para>This is technical reference documentation for the
-  miscellaneous utility templates in the DocBook XSL
-  Stylesheets.</para>
-
-<note>
-<para>These templates are defined in a separate file from the set
-  of “common” templates because some of the comment templates
-  reference DocBook XSL stylesheet parameters, requiring the
-  entire set of parameters to be imported/included in any
-  stylesheet that imports/includes the common templates.</para>
-<para>The utility templates don’t import or include any DocBook
-  XSL stylesheet parameters, so the utility templates can be used
-  without importing the whole set of parameters.</para>
-</note>
-
-<para>The following documentation is not intended to be
-  <quote>user</quote> documentation.  It is provided for developers
-  writing customization layers for the stylesheets, and for anyone
-  who's interested in <quote>how it works</quote>.</para>
-</partintro>
+<doc:reference xmlns="" xml:id="utility">
+  <info>
+    <releaseinfo role="meta">
+      $Id$
+    </releaseinfo>
+  </info>
+  <title>Common » Utility Template Reference</title>
+  <!-- * yes, partintro is a valid child of a reference... -->
+  <partintro xml:id="partintro">
+    <title>Introduction</title>
+    <para>This is technical reference documentation for the
+      miscellaneous utility templates in the DocBook XSL
+      Stylesheets.</para>
+    <note>
+      <para>These templates are defined in a separate file from the set
+        of “common” templates because some of the comment templates
+        reference DocBook XSL stylesheet parameters, requiring the
+        entire set of parameters to be imported/included in any
+        stylesheet that imports/includes the common templates.</para>
+      <para>The utility templates don’t import or include any DocBook
+        XSL stylesheet parameters, so the utility templates can be used
+        without importing the whole set of parameters.</para>
+    </note>
+    <para>This is not intended to be user documentation. It is
+      provided for developers writing customization layers for the
+      stylesheets.</para>
+  </partintro>
 </doc:reference>
 
 <!-- ====================================================================== -->

diff --git a/xsl/docsrcx/reference.xml b/xsl/docsrcx/reference.xml
index 91dc8ed6957f7cc18cd3a4eda9c4c701c6ab13c4..d26b4558243a17682fa9f8c8b5acb842a59e9930 100644 (file)
--- a/xsl/docsrcx/reference.xml
+++ b/xsl/docsrcx/reference.xml
@@ -7,6 +7,15 @@
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xml:base="../docsrcx/"
   >
+  <!-- * WARNING WARNING WARNING -->
+  <!-- * WARNING WARNING WARNING -->
+  <!-- * -->
+  <!-- * This document has duplicate IDs in it and is intended for -->
+  <!-- * processing using the chunk.xsl stylesheet to generate chunked -->
+  <!-- * output from it (not for generating a single HTML output file) -->
+  <!-- * -->
+  <!-- * WARNING WARNING WARNING -->
+  <!-- * WARNING WARNING WARNING -->
   <title>DocBook XSL Stylesheets: Reference Documentation</title>
   <info><releaseinfo role="meta">$Id: reference.dbk 6970 2007-07-08 20:15:09Z xmldoc $ </releaseinfo>
     <xi:include href="./authors.xml"/>
@@ -58,6 +67,7 @@
     </info>
     <part xml:id="html">
       <?dbhtml dir="html"?>
+      <?dbhtml filename="index.html"?>
       <xi:include href="../html/param.xml" xpointer="xpointer(/book/bookinfo/title)" />
       <partintro xml:id="htmlintro">
         <xi:include href="../html/param.xml"
@@ -67,6 +77,7 @@
     </part>
     <part xml:id="fo">
       <?dbhtml dir="fo"?>
+      <?dbhtml filename="index.html"?>
       <xi:include href="../fo/param.xml" xpointer="xpointer(/book/bookinfo/title)" />
       <partintro xml:id="fointro">
         <xi:include href="../fo/param.xml"
@@ -76,6 +87,7 @@
     </part>
     <part xml:id="manpages">
       <?dbhtml dir="manpages"?>
+      <?dbhtml filename="index.html"?>
       <xi:include href="../manpages/param.xml" xpointer="xpointer(/book/bookinfo/title)" />
       <partintro xml:id="manintro">
         <xi:include href="../manpages/param.xml"
@@ -85,6 +97,7 @@
     </part>
     <part xml:id="roundtrip">
       <?dbhtml dir="roundtrip"?>
+      <?dbhtml filename="index.html"?>
       <xi:include href="../roundtrip/param.xml" xpointer="xpointer(/book/bookinfo/title)" />
       <partintro xml:id="roundtripintro">
         <xi:include href="../roundtrip/param.xml"
@@ -94,6 +107,7 @@
     </part>
     <part xml:id="slides-html">
       <?dbhtml dir="slides/html"?>
+      <?dbhtml filename="index.html"?>
       <xi:include href="../slides/html/param.xml" xpointer="xpointer(/book/bookinfo/title)" />
       <partintro xml:id="slideshtmlintro">
         <xi:include href="../slides/html/param.xml"
@@ -103,6 +117,7 @@
     </part>
     <part xml:id="slides-fo">
       <?dbhtml dir="slides/fo"?>
+      <?dbhtml filename="index.html"?>
       <xi:include href="../slides/fo/param.xml" xpointer="xpointer(/book/bookinfo/title)" />
       <partintro xml:id="slidesfointro">
         <xi:include href="../slides/fo/param.xml"
@@ -112,6 +127,7 @@
     </part>
     <part xml:id="website">
       <?dbhtml dir="website"?>
+      <?dbhtml filename="index.html"?>
       <xi:include href="../website/param.xml" xpointer="xpointer(/book/bookinfo/title)" />
       <partintro xml:id="websiteintro">
         <xi:include href="../website/param.xml"
@@ -121,6 +137,8 @@
     </part>
   </book>
   <book xml:id="pi"><title>DocBook XSL Stylesheets User Reference: PIs</title>
+    <?dbhtml dir="pi"?>
+    <?dbhtml filename="index.html"?>
     <info>
       <abstract>
         <para>This is generated reference documentation for all
@@ -137,7 +155,6 @@
       </abstract>
     </info>
     <part xml:id="pi-html">
-      <?dbhtml dir="pi"?>
       <xi:include href="../html/pi.xml" xpointer="xpointer(/reference/title)" />
       <xi:include href="../html/pi.xml"
         xpointer="xpointer(/reference/partintro)" />
@@ -149,7 +166,6 @@
       </reference>
     </part>
     <part xml:id="pi-fo">
-      <?dbhtml dir="pi"?>
       <xi:include href="../fo/pi.xml" xpointer="xpointer(/reference/title)" />
       <xi:include href="../fo/pi.xml"
         xpointer="xpointer(/reference/partintro)" />
@@ -161,7 +177,6 @@
       </reference>
     </part>
     <part xml:id="pi-common">
-      <?dbhtml dir="pi"?>
       <xi:include href="../common/pi.xml" xpointer="xpointer(/reference/title)" />
       <xi:include href="../common/pi.xml"
         xpointer="xpointer(/reference/partintro)" />
@@ -183,60 +198,32 @@
           the stylesheets.</para>
       </abstract>
     </info>
-    <part xml:id="lib">
+    <reference xml:id="lib">
       <?dbhtml dir="lib"?>
-      <xi:include href="../lib/lib.xml" xpointer="xpointer(/book/bookinfo/title)" />
-      <partintro id="libintro">
-        <xi:include href="../lib/lib.xml" xpointer="xpointer(/book/preface/node())" />
-      </partintro>
-      <xi:include href="../lib/lib.xml" xpointer="xpointer(/book/reference)" />
-    </part>
-    <part xml:id="common">
-      <?dbhtml dir="common"?>
-      <xi:include href="../common/common.xml" xpointer="xpointer(/reference/title)" />
-      <xi:include href="../common/common.xml" xpointer="xpointer(/reference/partintro)" />
-      <reference xml:id="commontemplates">
-        <title>Templates</title>
-        <xi:include
-          href="../common/common.xml" xpointer="xpointer(/reference/refentry)" />
-      </reference>
-    </part>
-    <part xml:id="refentry">
-      <?dbhtml dir="common"?>
-      <xi:include href="../common/refentry.xml" xpointer="xpointer(/reference/title)" />
-      <xi:include href="../common/refentry.xml" xpointer="xpointer(/reference/partintro)" />
-      <reference xml:id="refmetatemplates">
-        <title>Templates</title>
-        <xi:include href="../common/refentry.xml" xpointer="xpointer(/reference/refentry)" />
-      </reference>
-    </part>
-    <part xml:id="utility">
+      <?dbhtml filename="index.html"?>
+      <xi:include href="../lib/lib.xml" xpointer="xpointer(/book/node())"/>
+    </reference>
+    <part xml:id="common-part"><title>Common Template Reference</title>
       <?dbhtml dir="common"?>
-      <xi:include href="../common/utility.xml" xpointer="xpointer(/reference/title)" />
-      <xi:include href="../common/utility.xml" xpointer="xpointer(/reference/partintro)" />
-      <reference xml:id="utilitytemplates">
-        <title>Templates</title>
-        <xi:include href="../common/utility.xml" xpointer="xpointer(/reference/refentry)" />
-      </reference>
-    </part>
-    <part xml:id="fo-table">
-      <?dbhtml dir="fo"?>
-      <xi:include href="../fo/table.xml" xpointer="xpointer(/reference/title)" />
-      <xi:include href="../fo/table.xml"
-        xpointer="xpointer(/reference/partintro)" />
-      <reference xml:id="fotabletemplates">
-        <title>Templates</title>
-        <xi:include href="../fo/table.xml" xpointer="xpointer(/reference/refentry)" />
-      </reference>
-    </part>
-    <part xml:id="template">
-      <?dbhtml dir="template"?>
-      <xi:include href="../template/titlepage.xml" xpointer="xpointer(/reference/title)" />
-      <xi:include href="../template/titlepage.xml" xpointer="xpointer(/reference/partintro)" />
-      <reference xml:id="titlepagetemplates">
-        <title>Templates</title>
-        <xi:include href="../template/titlepage.xml" xpointer="xpointer(/reference/refentry)" />
-      </reference>
-    </part>
+      <?dbhtml filename="index.html"?>
+      <info>
+        <abstract>
+          <para>This is technical reference documentation for the
+            “base”, “refentry”, and “utility” sets of common
+            templates in the DocBook XSL Stylesheets. These
+            templates are “common” in that they are shared across
+            output formats (that is, they’re not
+            output-format-dependent)</para>
+          <para>This documentation is not intended to be user
+            documentation. It is provided for developers writing
+            customization layers for the stylesheets.</para>
+        </abstract>
+      </info>
+        <xi:include href="../common/common.xml"/>
+        <xi:include href="../common/refentry.xml"/>
+        <xi:include href="../common/utility.xml"/>
+    </part>
+    <xi:include href="../fo/table.xml"/>
+    <xi:include href="../template/titlepage.xml"/>
   </book>
 </set>

diff --git a/xsl/fo/table.xsl b/xsl/fo/table.xsl
index 276afeade10388a18dd869083713b597abf456a9..f1d2f64293658fb7796f8777920c8dbe8c37d556 100644 (file)
--- a/xsl/fo/table.xsl
+++ b/xsl/fo/table.xsl
@@ -22,31 +22,22 @@
 
      ******************************************************************** -->
 
-<doc:reference xmlns="">
-<referenceinfo>
-<releaseinfo role="meta">
-$Id$
-</releaseinfo>
-<author><surname>Walsh</surname>
-<firstname>Norman</firstname></author>
-<copyright><year>1999</year><year>2000</year>
-<holder>Norman Walsh</holder>
-</copyright>
-</referenceinfo>
-<title>Formatting Object Table Reference</title>
-
-<partintro id="partintro">
-<title>Introduction</title>
-
-<para>This is technical reference documentation for the FO
-table-processing templates in the DocBook XSL Stylesheets.</para>
-
-<para>This is not intended to be <quote>user</quote> documentation.
-It is provided for developers writing customization layers for the
-stylesheets, and for anyone who's interested in <quote>how it
-works</quote>.</para>
-
-</partintro>
+<doc:reference xmlns="" xml:id="table-templates">
+  <?dbhtml dir="fo"?>
+  <info>
+    <releaseinfo role="meta">
+      $Id$
+    </releaseinfo>
+  </info>
+  <title>Formatting Object Table Reference</title>
+  <partintro xml:id="partintro">
+    <title>Introduction</title>
+    <para>This is technical reference documentation for the FO
+      table-processing templates in the DocBook XSL Stylesheets.</para>
+    <para>This is not intended to be user documentation.  It is
+      provided for developers writing customization layers for the
+      stylesheets.</para>
+  </partintro>
 </doc:reference>
 
 <!-- ==================================================================== -->

diff --git a/xsl/lib/lib.xweb b/xsl/lib/lib.xweb
index c2d5453d1b514801dc8ac01e5d2b1f7ededd9d4f..cf959820d578c060cda4503ec48317dc2c7e2c19 100644 (file)
--- a/xsl/lib/lib.xweb
+++ b/xsl/lib/lib.xweb
@@ -1,39 +1,42 @@
 <?xml version="1.0" encoding="utf-8"?>
-<book xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
-      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-      xmlns:dyn="http://exslt.org/dynamic"
-      xmlns:saxon="http://icl.com/saxon">
-<bookinfo>
-<title>XSL Library Template Reference</title>
-<releaseinfo role="cvs">$Id$
-</releaseinfo>
-<corpauthor>The DocBook Project</corpauthor>
-<copyright>
-  <year>1999</year>
-  <year>2000</year>
-  <year>2001</year>
-  <year>2002</year>
-  <year>2005</year>
-  <year>2006</year>
-  <holder>Norman Walsh</holder>
-</copyright>
-</bookinfo>
-
-<preface id="intro"><title>Introduction</title>
-
-<para>This is technical reference documentation for the
-vocabulary-independent “library” templates in the DocBook XSL
-Stylesheets.</para>
-
-<para>This is not intended to be <quote>user</quote> documentation.
-It is provided for developers writing customization layers for the
-stylesheets, and for anyone who's interested in <quote>how it
-works</quote>.</para>
-
-</preface>
-
-<reference id="generallibrary">
-<title>General Library Templates</title>
+<book xml:id="lib.xml"
+  xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:dyn="http://exslt.org/dynamic"
+  xmlns:saxon="http://icl.com/saxon">
+  <info>
+    <title>XSL Library Template Reference</title>
+    <releaseinfo role="cvs">$Id$</releaseinfo>
+    <author>
+      <personname>
+        <surname>Walsh</surname><firstname>Norman</firstname>
+      </personname>
+    </author>
+    <author>
+      <orgname>The DocBook Project</orgname>
+    </author>
+    <copyright>
+      <year>1999-2007</year>
+      <holder>Norman Walsh</holder>
+    </copyright>
+    <copyright>
+      <year>2001-2007</year>
+      <holder>The DocBook Project</holder>
+    </copyright>
+  </info>
+  <preface id="intro"><title>Introduction</title>
+    <para>This is technical reference documentation for the
+      vocabulary-independent “library” templates in the DocBook XSL
+      Stylesheets.</para>
+    <para>This is not intended to be user documentation.  It is
+      provided for developers writing customization layers for the
+      stylesheets.</para>
+  </preface>
+
+<!-- ================================================================== -->
+
+  <reference id="generallibrary">
+    <title>General Library Templates</title>
 
 <refentry id="dot.count">
 <refnamediv>

diff --git a/xsl/template/titlepage.xsl b/xsl/template/titlepage.xsl
index 01aa9f0a16fa696f427aef6f32a7053383181a18..9e220a77cd83a5f8299ecff9f14f340b8fd54678 100644 (file)
--- a/xsl/template/titlepage.xsl
+++ b/xsl/template/titlepage.xsl
@@ -26,32 +26,23 @@
   <xsl:text>&#x0a;</xsl:text>
 </xsl:template>
 
-<doc:reference xmlns="">
-<referenceinfo>
-<releaseinfo role="meta">
-$Id$
-</releaseinfo>
-<author><surname>Walsh</surname>
-<firstname>Norman</firstname></author>
-<copyright><year>1999</year><year>2000</year>
-<holder>Norman Walsh</holder>
-</copyright>
-</referenceinfo>
-<title>Template Stylesheet Reference</title>
-
-<partintro id="intro_partintro">
-<title>Introduction</title>
-
-<para>This is technical reference documentation for the
-“titlepage” templates in the DocBook XSL Stylesheets.</para>
-
-<para>This is not intended to be <quote>user</quote> documentation.
-It is provided for developers writing customization layers for the
-stylesheets, and for anyone who's interested in <quote>how it
-works</quote>.</para>
-
-</partintro>
-
+<doc:reference xmlns="" xml:id="template">
+  <?dbhtml dir="template"?>
+  <?dbhtml filename="index.html"?>
+  <info>
+    <releaseinfo role="meta">
+      $Id$
+    </releaseinfo>
+  </info>
+  <title>Titlepage Template Stylesheet Reference</title>
+  <partintro xml:id="intro_partintro">
+    <title>Introduction</title>
+    <para>This is technical reference documentation for the
+      “titlepage” templates in the DocBook XSL Stylesheets.</para>
+    <para>This is not intended to be user documentation.  It is
+      provided for developers writing customization layers for the
+      stylesheets.</para>
+  </partintro>
 </doc:reference>
 
 <!-- ==================================================================== -->