bk commit - mysqldoc@docsrva tree (paul:1.3227)

[paul]

Below is the list of changes that have just been committed into a local
mysqldoc repository of paul. When paul does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.3227 05/08/10 09:39:49 paul@stripped +2 -0
  Tweaks to manpage-markup processing.

  xsl.d/dbk-prep.xsl
    1.11 05/08/10 09:39:44 paul@stripped +62 -56
    Tweaks to manpage-markup processing.

  make.d/xml-prep
    1.7 05/08/10 09:39:43 paul@stripped +4 -1
    Tweaks to manpage-markup processing.

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	paul
# Host:	frost.snake.net
# Root:	/Volumes/frost2/MySQL/bk/mysqldoc

--- 1.6/make.d/xml-prep	2005-07-25 18:06:41 -05:00
+++ 1.7/make.d/xml-prep	2005-08-10 09:39:43 -05:00
@@ -20,9 +20,12 @@
 	$(XSLTPROC) \
 		$(DBK_PREP_XSL) $< | $(BUG_PREP) > $@
 
+# For manpage preprocessing, suppress the mapping of <refentry>
+# elements to <section> elements that is done by default.
+
 %-manprepped.xml: %.xml $(DBK_PREP_XSL_DEPS) $(BUG_PREP)
 	$(XSLTPROC) \
-		--param generate.manpages 1 \
+		--param map.refentry.to.section 0 \
 		$(DBK_PREP_XSL) $< | $(BUG_PREP) > $@
 
 # For Texinfo processing, we may need to exclude elements that cause

--- 1.10/xsl.d/dbk-prep.xsl	2005-08-09 11:28:54 -05:00
+++ 1.11/xsl.d/dbk-prep.xsl	2005-08-10 09:39:44 -05:00
@@ -18,7 +18,8 @@
   - Map <glossentry>, <glossterm>, <glossdef> to <varlistentry>, <term>,
     <listitem>.
 - Handle <refentry> elements differentially for manpage and non-manpage
-  output. (Depends on the setting of the $generate.manpages parameter.)
+  output. (Depends on the setting of the $map.refentry.to.section
+  parameter.)
 - The <qandaset> elements cause problems for FOP (the symptom is
   that it terminates after writing a message like "The id "id830898"
   already exists in this document".  This error occurs unpredictably,
@@ -48,48 +49,41 @@
 <xsl:preserve-space elements="*"/>
 
 <!--
-  Whether to generate output for manpage production.  The default is
-  0 (false); that is, map <refentry> elements to <section> elements.
-  This allows subsequently invoked stylesheets that use this preprocessor
-  not to have to know about <refentry> structure.  Set to 1 (true)
-  for generating manpages, which are based on <refentry> elements.
-
-TODO:
-At some point, could change the later processors to know about refentry
-directly. Then the only thing that would need to be done here would be
-to strip off the wrapper <section> elements.
--->
-
-<xsl:param name="generate.manpages" select="0"/>
-
-<!--
   <section> and <refentry> cannot appear at the same level within
   their parent.  To get around this so that valid source documents
   can be written, sections from which manpages can be generated are
   represented as <refentry> children of a <section>.  That is, the
   <section> (and required <title> element) are used as a "wrapper."
 
-  However, if such documents were formatted as is, we'd end up with
-  an extraneous level in the TOC.  Also, we don't want refentry markup
-  when not formatting manpage output.  So we preprocess <section>
-  elements that have one or more <refentry> children as follows:
-
-  - If $generate.manpages is 0, discard the "wrapper" <section> and <title>
-    and map the <refentry> markup onto <section>.  The result has only
-    <section> elements and no <refentry> elements.
-  - If $generate.manpages is not 0, discard the "wrapper" <section> and
-    <title>, and pass through the <refentry> children.  Note that the
-    resulting document may be invalid, because it might have a mix of
-    <section> and <refentry> at the same level.  However, we don't care
-    at this point because the document will be used only for generating
-    manpage output and we don't care about the <section> elements, or
-    indeed even about validity.  I suppose we could actually preprocess
-    by producing output consisting *only* of the <refentry> elements, but
-    that might mess up <xref> resolution...
+  However, these wrapper <section> and <title> tags really are just
+  dummy tags.  If documents marked up this way were formatted as
+  is, we'd end up with an extraneous level in the TOC.  Also, we don't
+  want <refentry> markup when not formatting manpage output.  So we
+  preprocess <section> elements that have one or more <refentry>
+  children according to the value of the $map.refentry.to.section
+  parameter:
+
+  - If $map.refentry.to.section is non-zero, discard the wrapper <section>
+    and <title> and map the <refentry> markup onto <section>.  The
+    result has only <section> elements and no <refentry> elements.
+  - If $map.refentry.to.section is zero, discard the wrapper <section>
+    and <title>, and pass through the <refentry> children.  Note that
+    the resulting document may be invalid, because it might have a mix
+    of <section> and <refentry> at the same level.  However, we don't
+    care at this point because the document will be used only for
+    generating manpage output and we don't care about the <section>
+    elements, or indeed even about validity.  I suppose we could
+    actually preprocess by producing output consisting *only* of the
+    <refentry> elements, but that might mess up <xref> resolution...
+
+  The default is 1 (true), which allows subsequently invoked stylesheets
+  that use this preprocessor not to have to know about <refentry>
+  structure.  Set to 0 (false) for generating manpages, which need
+  to see <refentry> elements.
 
   One additional subtlety:
 
-  In a manual page, the first section typically is a general description.
+  In a manpage, the first subsection typically is a general description.
   For non-manpage production, write out this information with the
   <section> (and <title>) tags stripped.  That way, we don't have:
 
@@ -112,13 +106,20 @@
 
   By doing this, we avoid an "empty" first page that has only the
   title and the TOC for the other sections.
+
+  TODO:
+  At some point, could change the later processors to know about refentry
+  directly. Then the only thing that would need to be done here would be
+  to strip off the wrapper <section> elements.
 -->
 
+<xsl:param name="map.refentry.to.section" select="1"/>
+
 <!--
-  For a <section> that contains <refentry> elements, process only
+  For a <section> that contains <refentry> children, process only
   those elements.  This has the effect of discarding the <section>
-  and its <title>.  The <refentry> elements are handled differentially
-  depending on the $generate.manpages setting.
+  tags and the section <title> element.  The <refentry> children are
+  handled differentially depending on the $map.refentry.to.section value.
 -->
 
 <xsl:template match="section[child::refentry]">
@@ -128,18 +129,28 @@
 
 <!--
   Handle <refentry>.
-  If $generate.manpages is 0:
+  If $map.refentry.to.section is 0:
+    Pass <refentry> through unchanged.
+  Otherwise:
     Map <refentry> to <section>, using <refmeta> information to
     generate the <title> and ignoring everything else but <refsection>.
     Also, for the first <refsection>, omit only the non-<title> content,
     which has the effect of stripping the <refsection> tags and the <title>.
-  Otherwise:
-    Pass <refentry> through unchanged.
+    refmeta/refentrytitle should name the program described by the manpage.
+    refmeta/refmiscinfo should be the same as refnamediv/refpurpose, but
+    properly capitalized for a section title.
 -->
 
 <xsl:template match="refentry">
   <xsl:choose>
-    <xsl:when test="$generate.manpages = 0">
+    <xsl:when test="$map.refentry.to.section = 0">
+      <!-- pass refentry through unchanged -->
+      <refentry>
+        <xsl:copy-of select="@*"/>
+        <xsl:apply-templates/>
+      </refentry>
+    </xsl:when>
+    <xsl:otherwise>
       <!-- map refentry to section -->
       <section>
         <xsl:copy-of select="@*"/>
@@ -153,38 +164,33 @@
         <xsl:apply-templates select="refsection[1]/node()[not(self::title)]"/>
         <xsl:apply-templates select="refsection[position() &gt; 1]"/>
       </section>
-    </xsl:when>
-    <xsl:otherwise>
-      <refentry>
-        <xsl:copy-of select="@*"/>
-        <xsl:apply-templates/>
-      </refentry>
     </xsl:otherwise>
   </xsl:choose>
 </xsl:template>
 
 <!--
   Handle <refsection>.
-  If $generate.manpages is 0:
-    Map <refsection> to <section>
-  Otherwise:
+  If $map.refentry.to.section is 0:
     Pass <refsection> through unchanged.
+  Otherwise:
+    Map <refsection> to <section>
 -->
 
 <xsl:template match="refsection">
   <xsl:choose>
-    <xsl:when test="$generate.manpages = 0">
-      <!-- map refsection to section -->
-      <section>
+    <xsl:when test="$map.refentry.to.section = 0">
+      <!-- pass refsection through unchanged -->
+      <refsection>
         <xsl:copy-of select="@*"/>
         <xsl:apply-templates/>
-      </section>
+      </refsection>
     </xsl:when>
     <xsl:otherwise>
-      <refsection>
+      <!-- map refsection to section -->
+      <section>
         <xsl:copy-of select="@*"/>
         <xsl:apply-templates/>
-      </refsection>
+      </section>
     </xsl:otherwise>
   </xsl:choose>
 </xsl:template>