<!-- ================================================================== -->
- <!-- * The prepare.manpage.contents template is called after -->
- <!-- * everything else has been done, just before writing the actual -->
- <!-- * man-page files to the filesystem. It works on the entire roff -->
- <!-- * source for each man page (not just the visible contents). -->
+ <!-- * The prepare.manpage.contents template is called after all -->
+ <!-- * other processing has been done, before serializing the -->
+ <!-- * result of all the other processing. It basically works on -->
+ <!-- * the result as one big string. -->
<xsl:template name="prepare.manpage.contents">
<xsl:param name="content" select="''"/>
- <!-- * First do "essential" string/character substitutions; for -->
- <!-- * example, the backslash character _must_ be substituted with -->
- <!-- * a double backslash, to prevent it from being interpreted as -->
- <!-- * a roff escape -->
+ <!-- * If user has provided a "local" string-substitution map to -->
+ <!-- * be applied /before/ the standard string-substitution map, -->
+ <!-- * apply it. -->
+ <xsl:variable name="pre.adjusted.content">
+ <xsl:choose>
+ <xsl:when test="$man.string.subst.map.local.pre">
+ <!-- * normalized value of man.string.subst.map.local.pre -->
+ <!-- * is non-empty, so get contents of map and apply them -->
+ <xsl:call-template name="apply-string-subst-map">
+ <xsl:with-param name="content" select="$content"/>
+ <xsl:with-param name="map.contents"
+ select="exsl:node-set($man.string.subst.map.local.pre)/*"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <!-- * value of man.string.subst.map.local.pre is empty, -->
+ <!-- * so just copy original contents -->
+ <xsl:value-of select="$content"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+ <!-- * Apply standard string-substitution map. The main purpose -->
+ <!-- * of this map is to escape certain characters that have -->
+ <!-- * special meaning in roff, and to replace certain characters -->
+ <!-- * used within the stylesheet internally to represent roff -->
+ <!-- * markup characters. -->
<xsl:variable name="adjusted.content">
<xsl:call-template name="apply-string-subst-map">
- <xsl:with-param name="content" select="$content"/>
+ <xsl:with-param name="content" select="$pre.adjusted.content"/>
<xsl:with-param name="map.contents"
select="exsl:node-set($man.string.subst.map)/*"/>
</xsl:call-template>
</xsl:variable>
+ <!-- * If user has provided a "local" string-substitution map to -->
+ <!-- * be applied /after/ the standard string-substitution map, -->
+ <!-- * apply it. -->
+ <xsl:variable name="post.adjusted.content">
+ <xsl:choose>
+ <xsl:when test="$man.string.subst.map.local.post">
+ <!-- * normalized value of man.string.subst.map.local.post -->
+ <!-- * is non-empty, so get contents of map and apply them -->
+ <xsl:call-template name="apply-string-subst-map">
+ <xsl:with-param name="content" select="$adjusted.content"/>
+ <xsl:with-param name="map.contents"
+ select="exsl:node-set($man.string.subst.map.local.post)/*"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <!-- * value of man.string.subst.map.local.post is empty, -->
+ <!-- * so just copy original contents -->
+ <xsl:value-of select="$adjusted.content"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
<!-- * Optionally, apply a character map to replace Unicode -->
<!-- * symbols and special characters. -->
<xsl:choose>
<xsl:when test="$man.charmap.enabled != 0">
<xsl:call-template name="apply-character-map">
- <xsl:with-param name="content" select="$adjusted.content"/>
+ <xsl:with-param name="content" select="$post.adjusted.content"/>
<xsl:with-param name="map.contents"
select="exsl:node-set($man.charmap.contents)/*"/>
</xsl:call-template>
<!ENTITY man.links.list.heading SYSTEM "../params/man.links.list.heading.xml">
<!ENTITY variablelist.term.separator SYSTEM "../params/variablelist.term.separator.xml">
<!ENTITY variablelist.term.break.after SYSTEM "../params/variablelist.term.break.after.xml">
+<!ENTITY man.string.subst.map.local.pre SYSTEM "../params/man.string.subst.map.local.pre.xml">
<!ENTITY man.string.subst.map SYSTEM "../params/man.string.subst.map.xml">
+<!ENTITY man.string.subst.map.local.post SYSTEM "../params/man.string.subst.map.local.post.xml">
<!ENTITY man.charmap.enabled SYSTEM "../params/man.charmap.enabled.xml">
<!ENTITY man.charmap.use.subset SYSTEM "../params/man.charmap.use.subset.xml">
<!ENTITY man.charmap.uri SYSTEM "../params/man.charmap.uri.xml">
&man.charmap.uri;
&man.charmap.use.subset;
&man.charmap.subset.profile;
+&man.string.subst.map.local.pre;
&man.string.subst.map;
+&man.string.subst.map.local.post;
</reference>
<reference id="refmeta">
<title>Refentry metadata gathering</title>
<src:fragref linkend="man.output.in.separate.dir.frag"/>
<src:fragref linkend="man.output.base.dir.frag"/>
<src:fragref linkend="man.output.subdirs.enabled.frag"/>
+<src:fragref linkend="man.string.subst.map.local.pre.frag"/>
<src:fragref linkend="man.string.subst.map.frag"/>
+<src:fragref linkend="man.string.subst.map.local.post.frag"/>
<src:fragref linkend="man.links.are.numbered.frag"/>
<src:fragref linkend="man.links.are.underlined.frag"/>
<src:fragref linkend="man.links.list.enabled.frag"/>
--- /dev/null
+<refentry xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ id="man.string.subst.map.local.post">
+<refmeta>
+<refentrytitle>man.string.subst.map.local.post</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.string.subst.map.local.post</refname>
+<refpurpose>Specifies “local” string substitutions</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.string.subst.map.local.post.frag'>
+<xsl:param name="man.string.subst.map.local.post"></xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>Use the <parameter>man.string.subst.map.local.post</parameter>
+parameter to specify any “local” string substitutions to perform over
+the entire roff source for each man page <emphasis>after</emphasis>
+performing the string substitutions specified by the <parameter
+>man.string.subst.map</parameter> parameter.</para>
+
+<para>For details about the format of this parameter, see the
+documentation for the <parameter>man.string.subst.map</parameter>
+parameter.</para>
+
+</refsect1>
+</refentry>
--- /dev/null
+<refentry xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ id="man.string.subst.map.local.pre">
+<refmeta>
+<refentrytitle>man.string.subst.map.local.pre</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.string.subst.map.local.pre</refname>
+<refpurpose>Specifies “local” string substitutions</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.string.subst.map.local.pre.frag'>
+ <xsl:param name="man.string.subst.map.local.pre"></xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>Use the <parameter>man.string.subst.map.local.pre</parameter>
+parameter to specify any “local” string substitutions to perform over
+the entire roff source for each man page <emphasis>before</emphasis>
+performing the string substitutions specified by the <parameter
+>man.string.subst.map</parameter> parameter.</para>
+
+<para>For details about the format of this parameter, see the
+documentation for the <parameter>man.string.subst.map</parameter>
+parameter.</para>
+
+</refsect1>
+</refentry>
before applying the roff character map.</para>
<para>You can use <parameter>man.string.subst.map</parameter> as a
-"lightweight" character map to perform "essential" substitutions --
+“lightweight” character map to perform “essential” substitutions --
that is, substitutions that are <emphasis>always</emphasis> performed,
even if the value of the <parameter>man.charmap.enabled</parameter>
parameter is zero. For example, you can use it to replace quotation
<warning>
<para>Do you not change value of the
- <parameter>man.string.subst.map</parameter> parameter unless
- you are sure what you are doing. If you remove any of the default
- mappings, you are likely to end up with broken output. And be very
- careful about adding anything to it. Because it is used for doing
- string substitution over the entire roff source of each man page, it
- causes target strings to be replaced in roff requests and escapes,
- not just in the visible contents.</para>
+ <parameter>man.string.subst.map</parameter> parameter unless you are
+ sure what you are doing. First consider adding your
+ string-substitution mappings to either or both of the following
+ parameters:
+ <variablelist>
+ <varlistentry>
+ <term><parameter>man.string.subst.map.local.pre</parameter></term>
+ <listitem><para>applied before
+ <parameter>man.string.subst.map</parameter></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>man.string.subst.map.local.post</parameter></term>
+ <listitem><para>applied after
+ <parameter>man.string.subst.map</parameter></para></listitem>
+ </varlistentry>
+ </variablelist>
+ By default, both of those parameters contain no
+ string substitutions. They are intended as a means for you to
+ specify your own local string-substitution mappings.</para>
+
+ <para>If you remove any of default mappings from the value of the
+ <parameter>man.string.subst.map</parameter> parameter, you are
+ likely to end up with broken output. And be very about adding
+ anything to it; it’s used for doing string substitution over the
+ entire roff source of each man page – it causes target strings to be
+ replaced in roff requests and escapes, not just in the visible
+ contents of the page.</para>
</warning>
projects / docbook-dsssl / commitdiff