| List: | Commits | « Previous MessageNext Message » | |
| From: | paul | Date: | February 17 2006 2:48pm |
| Subject: | svn commit - mysqldoc@docsrva: r1363 - in trunk: . make.d xsl.d | ||
| View as plain text | |||
Author: paul Date: 2006-02-17 14:48:02 +0100 (Fri, 17 Feb 2006) New Revision: 1363 Log: r7654@frost: paul | 2006-02-17 07:45:58 -0600 Factor out <refentry>-mapping templates from dbk-prep.xsl to separate stylesheet so they can be included in other stylesheets. Added: trunk/xsl.d/map-refentry.xsl Modified: trunk/ trunk/make.d/vars-docbook trunk/xsl.d/dbk-prep.xsl Property changes on: trunk ___________________________________________________________________ Name: svk:merge - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:7649 bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:3157 + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:7654 bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:3157 Modified: trunk/make.d/vars-docbook =================================================================== --- trunk/make.d/vars-docbook 2006-02-17 13:43:58 UTC (rev 1362) +++ trunk/make.d/vars-docbook 2006-02-17 13:48:02 UTC (rev 1363) @@ -89,7 +89,9 @@ # Transform that preps a file for further formatting DBK_PREP_XSL = $(XSL_DIR)/dbk-prep.xsl -DBK_PREP_XSL_DEPS = $(DBK_PREP_XSL) +DBK_PREP_XSL_DEPS = \ + $(DBK_PREP_XSL) \ + $(XSL_DIR)/map-refentry.xsl # Similar, but specific to Texinfo production Modified: trunk/xsl.d/dbk-prep.xsl =================================================================== --- trunk/xsl.d/dbk-prep.xsl 2006-02-17 13:43:58 UTC (rev 1362) +++ trunk/xsl.d/dbk-prep.xsl 2006-02-17 13:48:02 UTC (rev 1363) @@ -2,42 +2,45 @@ <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <!-- -dbk-prep.xsl - prep a DocBook document for formatting + dbk-prep.xsl - prep a DocBook document for formatting -This is an identity transform, with the following exceptions: + This is an identity transform, with the following exceptions: -- Strip leading newline from body of <programlisting> and <screen> - elements. This helps reduce leading around listings in PDF output. - (Trailing newline seems not to matter.) -- Glossary entries are written using <glossxxx> elements. However, - these appear to cause problems for FOP (it simply quits with - "[ERROR] null" which is none too helpful). To - make the problem go away, we do this: - - Map <glossdiv> to <variablelist> - - <title> within <glossdiv> becomes the <title> of the <variablelist>. - - Map <glossentry>, <glossterm>, <glossdef> to <varlistentry>, <term>, - <listitem>. -- Handle <refentry> elements differentially for manpage and non-manpage - 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, - except that it is associated with the use of Q/A constructs. To - make the problem go away, we map <qandaset>, <qandaentry>, <question>, - <answer> to simple numbered paragraphs. -- Strip comments (by not processing them). Also, if the comment is - followed by a text node that begins with a newline, remove the - newline as well. The effect of that is to completely remove the - last line on which the comment occurs, which helps to prevent - extraneous blank lines in <programlisting> elements that contain - comments. + - Strip leading newline from body of <programlisting> and <screen> + elements. This helps reduce leading around listings in PDF output. + (Trailing newline seems not to matter.) + - Glossary entries are written using <glossxxx> elements. However, + these appear to cause problems for FOP (it simply quits with + "[ERROR] null" which is none too helpful). To + make the problem go away, we do this: + - Map <glossdiv> to <variablelist> + - <title> within <glossdiv> becomes the <title> of the <variablelist>. + - Map <glossentry>, <glossterm>, <glossdef> to <varlistentry>, <term>, + <listitem>. + - Handle <refentry> elements differentially for manpage and non-manpage + 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, + except that it is associated with the use of Q/A constructs. To + make the problem go away, we map <qandaset>, <qandaentry>, <question>, + <answer> to simple numbered paragraphs. + - Strip comments (by not processing them). Also, if the comment is + followed by a text node that begins with a newline, remove the + newline as well. The effect of that is to completely remove the + last line on which the comment occurs, which helps to prevent + extraneous blank lines in <programlisting> elements that contain + comments. + - Look for <remark role="repository.revision"/> and replace it with the + value of the $repository.revision parameter (which is passed in by + the command that invokes this stylesheet). It is REQUIRED that processing instructions be preserved, because we use the <?dbtimestamp?> PI to produce a timestamp in the stylesheets used by later processing stages. - Other whitespace is preserved + Other whitespace is preserved. --> <xsl:output @@ -49,6 +52,10 @@ doctype-system="http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" /> +<!-- include refentry-mapping templates --> + +<xsl:include href="map-refentry.xsl"/> + <xsl:preserve-space elements="*"/> <!-- @@ -64,7 +71,7 @@ <xsl:template match="remark[@role='repository.revision']"> <xsl:if test="$repository.revision != ''"> <xsl:text>(</xsl:text> - <!-- use @condition attribute or "revision" is @condition not present --> + <!-- use @condition attribute or "revision" if @condition not present --> <xsl:choose> <xsl:when test="@condition != ''"> <xsl:value-of select="@condition"/> @@ -80,156 +87,9 @@ </xsl:template> <!-- - <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, 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 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: - - <section> - <title>program-name - program-purpose</title> - <section> - <para>description of program ... </para> - </section> - <section> other sections ... </section> - <section> other sections ... </section> - - We have this instead: - - <section> - <title>program-name - program-purpose</title> - <para>description of program ... </para> - <para>description of program ... </para> - <section> other sections ... </section> - <section> other sections ... </section> - - 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> children, process only - those elements. This has the effect of discarding the <section> - 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]"> - <!-- process refentry children --> - <xsl:apply-templates select="refentry"/> -</xsl:template> - -<!-- - Handle <refentry>. - 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>. - refmeta/refentrytitle should name the program described by the manpage. - refmeta/refmiscinfo[@class='refman'] should be the same as - refnamediv/refpurpose, but properly capitalized for a section title. ---> - -<xsl:template match="refentry"> - <xsl:choose> - <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="@*"/> - <title> - <!-- program-name — program-purpose --> - <xsl:apply-templates select="refmeta/refentrytitle/node()"/> - <xsl:text> — </xsl:text> - <xsl:apply-templates select="refmeta/refmiscinfo[@class='refman']/node()"/> - </title> - <xsl:text>
</xsl:text> - <xsl:apply-templates select="refsection[1]/node()[not(self::title)]"/> - <xsl:apply-templates select="refsection[position() > 1]"/> - </section> - </xsl:otherwise> - </xsl:choose> -</xsl:template> - -<!-- - Handle <refsection>. - 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="$map.refentry.to.section = 0"> - <!-- pass refsection through unchanged --> - <refsection> - <xsl:copy-of select="@*"/> - <xsl:apply-templates/> - </refsection> - </xsl:when> - <xsl:otherwise> - <!-- map refsection to section --> - <section> - <xsl:copy-of select="@*"/> - <xsl:apply-templates/> - </section> - </xsl:otherwise> - </xsl:choose> -</xsl:template> - -<!-- Map <qanda> elements to paragraphs - The handling here is substandard. It's a quick job simply to get + The handling here is substandard. It's a quick job simply to keep <qanda> from killing FOP. There is no leading TOC of the questions, for example. --> @@ -261,23 +121,9 @@ </xsl:template> <!-- - Match text elements that are the first child of <programlisting> - and chop any leading newline. + Map glossary tags to variable list --> -<xsl:template match="text()[1][parent::programlisting]"> - <xsl:choose> - <xsl:when test="starts-with(., '
')"> - <xsl:value-of select="substring(.,2)"/> - </xsl:when> - <xsl:otherwise> - <xsl:value-of select="."/> - </xsl:otherwise> - </xsl:choose> -</xsl:template> - -<!-- glossary entry elements --> - <!-- glossary becomes appendix --> <xsl:template match="glossary"> @@ -331,6 +177,22 @@ </xsl:template> <!-- + Match text elements that are the first child of <programlisting> + and chop any leading newline. +--> + +<xsl:template match="text()[1][parent::programlisting]"> + <xsl:choose> + <xsl:when test="starts-with(., '
')"> + <xsl:value-of select="substring(.,2)"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="."/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<!-- Match text nodes that follow a comment. If the text begins with a newline, remove the newline. Added: trunk/xsl.d/map-refentry.xsl =================================================================== --- trunk/xsl.d/map-refentry.xsl 2006-02-17 13:43:58 UTC (rev 1362) +++ trunk/xsl.d/map-refentry.xsl 2006-02-17 13:48:02 UTC (rev 1363) @@ -0,0 +1,149 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + +<!-- + map-refentry.xsl - map <refentry> elements to <section> + + <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, 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 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: + + <section> + <title>program-name - program-purpose</title> + <section> + <para>description of program ... </para> + </section> + <section> other sections ... </section> + <section> other sections ... </section> + + We have this instead: + + <section> + <title>program-name - program-purpose</title> + <para>description of program ... </para> + <para>description of program ... </para> + <section> other sections ... </section> + <section> other sections ... </section> + + By doing this, we avoid an "empty" first page that has only the + title and the TOC for the other sections. +--> + +<xsl:param name="map.refentry.to.section" select="1"/> + +<!-- + For a <section> that contains <refentry> children, process only + those elements. This has the effect of discarding the <section> + 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]"> + <!-- process refentry children --> + <xsl:apply-templates select="refentry"/> +</xsl:template> + +<!-- + Handle <refentry>. + 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>. + refmeta/refentrytitle should name the program described by the manpage. + refmeta/refmiscinfo[@class='refman'] should be the same as + refnamediv/refpurpose, but properly capitalized for a section title. +--> + +<xsl:template match="refentry"> + <xsl:choose> + <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="@*"/> + <title> + <!-- program-name — program-purpose --> + <xsl:apply-templates select="refmeta/refentrytitle/node()"/> + <xsl:text> — </xsl:text> + <xsl:apply-templates select="refmeta/refmiscinfo[@class='refman']/node()"/> + </title> + <xsl:text>
</xsl:text> + <xsl:apply-templates select="refsection[1]/node()[not(self::title)]"/> + <xsl:apply-templates select="refsection[position() > 1]"/> + </section> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<!-- + Handle <refsection>. + 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="$map.refentry.to.section = 0"> + <!-- pass refsection through unchanged --> + <refsection> + <xsl:copy-of select="@*"/> + <xsl:apply-templates/> + </refsection> + </xsl:when> + <xsl:otherwise> + <!-- map refsection to section --> + <section> + <xsl:copy-of select="@*"/> + <xsl:apply-templates/> + </section> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +</xsl:stylesheet>
| Thread | ||
|---|---|---|
| • svn commit - mysqldoc@docsrva: r1363 - in trunk: . make.d xsl.d | paul | 17 Feb |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.674 sec. using MySQL 5.1.14-beta-log