<!-- * preserving the original default indent value -->
<!-- * when $man.indent.refsect is non-zero; -->
<!-- * "u" is a roff unit specifier -->
- <xsl:text>\n(zqu</xsl:text>
+ <xsl:text>▓n(zqu</xsl:text>
</xsl:when>
<xsl:otherwise/> <!-- * otherwise, just leave it empty -->
</xsl:choose>
<!-- * angle bracket and before the closing angle bracket is to -->
<!-- * prevent groff from inserting a linebreak at those points and -->
<!-- * outputting a hyphen character where the break occurs -->
- <xsl:text><\&</xsl:text>
+ <xsl:text><▓&</xsl:text>
<xsl:choose>
<xsl:when test="self::email">
<xsl:variable name="contents">
<xsl:value-of select="normalize-space($contents)"/>
</xsl:when>
</xsl:choose>
- <xsl:text>\&></xsl:text>
+ <xsl:text>▓&></xsl:text>
<xsl:choose>
<xsl:when test="not(following-sibling::*[descendant-or-self::email]
or following-sibling::address/otheraddr/ulink
<xsl:if test="$man.hyphenate.urls = 0 and
$man.break.after.slash = 0">
<xsl:call-template name="suppress.hyphenation"/>
- <xsl:text>\%</xsl:text>
+ <xsl:text>▓%</xsl:text>
</xsl:if>
<xsl:value-of select="$earmark"/>
</xsl:otherwise>
<!-- * This formatting should probably be made user-configurable, -->
<!-- * to allow something other than just square brackets; e.g., -->
<!-- * Angle brackets<10> or Braces{10} -->
- <xsl:text>\&[</xsl:text>
+ <xsl:text>▓&[</xsl:text>
<xsl:value-of select="$notesource.number"/>
<xsl:text>]</xsl:text>
<!-- * Note that the reason for the \& before the opening bracket -->
<xsl:if test="$man.hyphenate.urls = 0
and $man.break.after.slash = 0">
<xsl:call-template name="suppress.hyphenation"/>
- <xsl:text>\%</xsl:text>
+ <xsl:text>▓%</xsl:text>
</xsl:if>
<xsl:value-of select="@url"/>
<xsl:text> </xsl:text>
<!-- * preserving the original default indent value -->
<!-- * when $man.indent.refsect is non-zero; -->
<!-- * "u" is a roff unit specifier -->
- <xsl:text>\n(zqu</xsl:text>
+ <xsl:text>▓n(zqu</xsl:text>
</xsl:when>
<xsl:otherwise/> <!-- * otherwise, just leave it empty -->
</xsl:choose>
<xsl:value-of select="$list-indent"/>
</xsl:if>
<xsl:text> </xsl:text>
- <xsl:text>\h'░</xsl:text>
+ <xsl:text>▓h'░</xsl:text>
<xsl:if test="not($list-indent = '')">
<xsl:text>0</xsl:text>
<xsl:value-of select="$list-indent"/>
</xsl:if>
<xsl:text>'</xsl:text>
<xsl:text>•</xsl:text>
- <xsl:text>\h'+</xsl:text>
+ <xsl:text>▓h'+</xsl:text>
<xsl:if test="not($list-indent = '')">
<xsl:text>0</xsl:text>
<xsl:value-of select="$list-indent - 1"/>
<xsl:value-of select="$list-indent"/>
</xsl:if>
<xsl:text> </xsl:text>
- <xsl:text>\h'░</xsl:text>
+ <xsl:text>▓h'░</xsl:text>
<xsl:if test="not($list-indent = '')">
<xsl:text>0</xsl:text>
<xsl:value-of select="$list-indent"/>
<xsl:text> </xsl:text>
</xsl:if>
<xsl:number format="1."/>
- <xsl:text>\h'+</xsl:text>
+ <xsl:text>▓h'+</xsl:text>
<xsl:if test="not($list-indent = '')">
<xsl:text>0</xsl:text>
<xsl:value-of select="$list-indent - 2"/>
<xsl:apply-templates mode="bold" select="title"/>
<xsl:text> </xsl:text>
</xsl:if>
- <xsl:text>⌂\" line length increase to cope w/ tbl weirdness </xsl:text>
- <xsl:text>⌂ll +(\n(LLu * 62u / 100u) </xsl:text>
+ <xsl:text>⌂▓" line length increase to cope w/ tbl weirdness </xsl:text>
+ <xsl:text>⌂ll +(▓n(LLu * 62u / 100u) </xsl:text>
<!-- * .TS = "Table Start" -->
<xsl:text>⌂TS </xsl:text>
<!-- * first output the table "format" spec, which tells tbl(1) how -->
<xsl:apply-templates/>
<!-- * .TE = "Table End" -->
<xsl:text>⌂TE </xsl:text>
- <xsl:text>⌂\" line length decrease back to previous value </xsl:text>
- <xsl:text>⌂ll ░(\n(LLu * 62u / 100u) </xsl:text>
+ <xsl:text>⌂▓" line length decrease back to previous value </xsl:text>
+ <xsl:text>⌂ll ░(▓n(LLu * 62u / 100u) </xsl:text>
<!-- * put a blank line of space below the table -->
<xsl:text>⌂sp </xsl:text>
</xsl:template>
<xsl:param name="title"/>
<xsl:param name="manual"/>
<xsl:param name="source"/>
- <xsl:text>⌂\" Title: </xsl:text>
+ <xsl:text>⌂▓" Title: </xsl:text>
<xsl:call-template name="replace.dots.and.dashes">
<xsl:with-param name="content" select="$title"/>
</xsl:call-template>
<xsl:text> </xsl:text>
- <xsl:text>⌂\" Author: </xsl:text>
+ <xsl:text>⌂▓" Author: </xsl:text>
<xsl:call-template name="replace.dots.and.dashes">
<xsl:with-param name="content">
<xsl:call-template name="make.roff.metadata.author">
</xsl:with-param>
</xsl:call-template>
<xsl:text> </xsl:text>
- <xsl:text>⌂\" Generator: DocBook XSL Stylesheets v</xsl:text>
+ <xsl:text>⌂▓" Generator: DocBook XSL Stylesheets v</xsl:text>
<xsl:call-template name="replace.dots.and.dashes">
<xsl:with-param name="content" select="$VERSION"/>
</xsl:call-template>
<xsl:text> <http://docbook⌂sf⌂net/></xsl:text>
<xsl:text> </xsl:text>
- <xsl:text>⌂\" Date: </xsl:text>
+ <xsl:text>⌂▓" Date: </xsl:text>
<xsl:call-template name="replace.dots.and.dashes">
<xsl:with-param name="content" select="$date"/>
</xsl:call-template>
<xsl:text> </xsl:text>
- <xsl:text>⌂\" Manual: </xsl:text>
+ <xsl:text>⌂▓" Manual: </xsl:text>
<xsl:call-template name="replace.dots.and.dashes">
<xsl:with-param name="content" select="$manual"/>
</xsl:call-template>
<xsl:text> </xsl:text>
- <xsl:text>⌂\" Source: </xsl:text>
+ <xsl:text>⌂▓" Source: </xsl:text>
<xsl:call-template name="replace.dots.and.dashes">
<xsl:with-param name="content" select="$source"/>
</xsl:call-template>
<xsl:text> </xsl:text>
- <xsl:text>⌂\"</xsl:text>
+ <xsl:text>⌂▓"</xsl:text>
<xsl:text> </xsl:text>
</xsl:template>
<!-- * If the value of man.hypenate is zero (the default), then -->
<!-- * disable hyphenation (".nh" = "no hyphenation") -->
<xsl:if test="$man.hyphenate = 0">
- <xsl:text>⌂\" disable hyphenation </xsl:text>
+ <xsl:text>⌂▓" disable hyphenation </xsl:text>
<xsl:text>⌂nh </xsl:text>
</xsl:if>
<!-- * If the value of man.justify is zero (the default), then -->
<!-- * disable justification (".ad l" means "adjust to left only") -->
<xsl:if test="$man.justify = 0">
- <xsl:text>⌂\" disable justification</xsl:text>
+ <xsl:text>⌂▓" disable justification</xsl:text>
<xsl:text> (adjust text to left margin only) </xsl:text>
<xsl:text>⌂ad l </xsl:text>
</xsl:if>
<xsl:if test="not($man.indent.refsect = 0)">
- <xsl:text>⌂\" store initial "default indentation value" </xsl:text>
- <xsl:text>⌂nr zq \n(IN </xsl:text>
- <xsl:text>⌂\" adjust default indentation </xsl:text>
+ <xsl:text>⌂▓" store initial "default indentation value" </xsl:text>
+ <xsl:text>⌂nr zq ▓n(IN </xsl:text>
+ <xsl:text>⌂▓" adjust default indentation </xsl:text>
<xsl:text>⌂nr IN </xsl:text>
<xsl:value-of select="$man.indent.width"/>
<xsl:text> </xsl:text>
- <xsl:text>⌂\" adjust indentation of SS headings </xsl:text>
- <xsl:text>⌂nr SN \n(IN </xsl:text>
+ <xsl:text>⌂▓" adjust indentation of SS headings </xsl:text>
+ <xsl:text>⌂nr SN ▓n(IN </xsl:text>
</xsl:if>
<!-- * Unless the value of man.break.after.slash is zero (the -->
<!-- * default), tell groff that it is OK to break a line -->
<!-- * after a slash when needed. -->
<xsl:if test="$man.break.after.slash != 0">
- <xsl:text>⌂\" enable line breaks after slashes </xsl:text>
+ <xsl:text>⌂▓" enable line breaks after slashes </xsl:text>
<xsl:text>⌂cflags 4 / </xsl:text>
</xsl:if>
</xsl:template>
<!-- * actually means the title is indented by the value of -->
<!-- * the SN register, which appears by default to be -->
<!-- * about half of the default indentation value -->
- <xsl:text>⌂ti (\n(SNu * 5u / 3u) </xsl:text>
+ <xsl:text>⌂ti (▓n(SNu * 5u / 3u) </xsl:text>
<xsl:call-template name="nested-section-title"/>
<xsl:apply-templates/>
</xsl:otherwise>
<xsl:if test="not($man.indent.refsect = 0)">
<!-- * If default-indentation adjustment is on, then indent the -->
<!-- * child content of this Refsect3 or Refsection. -->
- <xsl:text>(\n(SNu) </xsl:text>
+ <xsl:text>(▓n(SNu) </xsl:text>
</xsl:if>
</xsl:variable>
<xsl:call-template name="nested-section-title"/>
- <xsl:text>⌂RS (\n(SNu) </xsl:text>
+ <xsl:text>⌂RS (▓n(SNu) </xsl:text>
<xsl:apply-templates/>
<xsl:text>⌂RE </xsl:text>
</xsl:template>
>tbl convert : Extracted a nested table</xsl:text>
</xsl:with-param>
</xsl:call-template>
- <xsl:text>[\fInested table\fR]* </xsl:text>
+ <xsl:text>[▓fInested table▓fR]* </xsl:text>
</xsl:when>
<xsl:otherwise>
<!-- * Apply templates to the child contents of this cell, to -->
<xsl:template mode="bold" match="*">
<xsl:for-each select="node()">
- <xsl:text>\fB</xsl:text>
+ <xsl:text>▓fB</xsl:text>
<xsl:apply-templates select="."/>
- <xsl:text>\fR</xsl:text>
+ <xsl:text>▓fR</xsl:text>
</xsl:for-each>
</xsl:template>
<xsl:template mode="italic" match="*">
<xsl:for-each select="node()">
- <xsl:text>\fI</xsl:text>
+ <xsl:text>▓fI</xsl:text>
<xsl:apply-templates select="."/>
- <xsl:text>\fR</xsl:text>
+ <xsl:text>▓fR</xsl:text>
</xsl:for-each>
</xsl:template>
<xsl:if test="$man.hyphenate != 0 and
not(ancestor::cmdsynopsis) and
not(ancestor::funcsynopsis)">
- <xsl:text>\%</xsl:text>
+ <xsl:text>▓%</xsl:text>
</xsl:if>
</xsl:template>
<!-- * in roff source (just to make things easier to read). -->
<xsl:template name="mark.subheading">
<xsl:if test="$man.subheading.divider.enabled != 0">
- <xsl:text>⌂\" </xsl:text>
+ <xsl:text>⌂▓" </xsl:text>
<xsl:value-of select="$man.subheading.divider"/>
<xsl:text> </xsl:text>
</xsl:if>
<refsynopsisdiv>
<src:fragment id='man.string.subst.map.frag'>
<xsl:param name="man.string.subst.map">
+
+ <!-- ******************************************************************** -->
+ <!-- * -->
+ <!-- * The backslash and dot (\, .) characters have special meaning -->
+ <!-- * for roff, so we escape those characters when they appear in -->
+ <!-- * the source content, and we use certain (arbitrarily -->
+ <!-- * selected) Unicode characters as the internal representations -->
+ <!-- * for those characters, then replace them with real -->
+ <!-- * backslashes and dots in output. In addition, for certain -->
+ <!-- * reasons, we do the same thing for dashes. The mappings of -->
+ <!-- * those characters to the Unicode characters we use to -->
+ <!-- * represent them is hard-coded: -->
+ <!-- * -->
+ <!-- * - U+2591 = dash -->
+ <!-- * - U+2593 = backslash -->
+ <!-- * - U+2302 = dot -->
+ <!-- * -->
+ <!-- ******************************************************************** -->
+
+ <!-- * escape dashes in content -->
+ <substitution oldstring="-" newstring="\-"/>
+ <!-- * replace U+2591 marker with dash -->
+ <substitution oldstring="░" newstring="-"/>
+ <!-- * escape backslashes in content -->
<substitution oldstring="\" newstring="\\"/>
- <!-- * escape all dots at the beginnings of lines (because roff -->
- <!-- * interprets them as the start of roff requests) -->
+ <!-- * fix bad font-request capitalization in .SH (stylesheet artifact) -->
+ <substitution oldstring="▓FB" newstring="\fB"/>
+ <substitution oldstring="▓FI" newstring="\fI"/>
+ <substitution oldstring="▓FR" newstring="\fR"/>
+ <!-- * replace U+2593 marker with backslash -->
+ <substitution oldstring="▓" newstring="\"/>
+ <!-- * escape dashes in content (only at line beginnings) -->
<substitution oldstring=" ." newstring=" \&."/>
- <!-- * the stylesheets use U+2302 internally to represent the start of a -->
- <!-- * roff request; for output, we need to convert that internal -->
- <!-- * representation to the character that roff actually uses to mark -->
- <!-- * the start of requests, which is a dot -->
+ <!-- * replace U+2302 marker with dot -->
<substitution oldstring="⌂" newstring="."/>
- <!-- * now, we need to restore single-backslashes in all roff -->
- <!-- * requests (because slash substitution above doubled them) -->
- <substitution oldstring="\\fB" newstring="\fB"/>
- <substitution oldstring="\\fI" newstring="\fI"/>
- <substitution oldstring="\\fR" newstring="\fR"/>
- <substitution oldstring="\\n" newstring="\n"/>
- <substitution oldstring="\\h" newstring="\h"/>
- <!-- * requests in .SH sectsions output from Refsect1-level source -->
- <!-- * end up getting capitalized; the following changes fix that -->
- <substitution oldstring="\\FB" newstring="\fB"/>
- <substitution oldstring="\\FI" newstring="\fI"/>
- <substitution oldstring="\\FR" newstring="\fR"/>
- <substitution oldstring='\\%' newstring='\%'/>
- <substitution oldstring='\\&' newstring='\&'/>
- <substitution oldstring='.\\"' newstring='.\"'/>
- <!-- * although the groff docs do not make it clear, it appears that -->
- <!-- * the only way to get a non-breaking hyphen in roff is to put a -->
- <!-- * backslash in front of it; and, unfortunately, groff is not smart -->
- <!-- * about where it breaks things (for example, it'll break an -->
- <!-- * argument for a command across a line, if that argument contains -->
- <!-- * a dash/hyphen); so, we must globally change all hyphens to "\-" -->
- <substitution oldstring="-" newstring="\-"/>
- <!-- * restore dashes in all roff requests and comments -->
- <substitution oldstring="░" newstring="-"/>
+
+ <!-- ==================================================================== -->
+
<!-- * squeeze multiple newlines before a roff request -->
<substitution oldstring=" ." newstring=" ."/>
<!-- * remove any .sp occurences that directly follow a .PP -->
causes target strings to be replaced in roff requests and escapes,
not just in the visible contents.</para>
- <para>In particular, do not attempt to add a mapping for the
- dot/period character. Doing so will break your output. For an
- explanation, see <xref linkend="Dots"/>.</para>
-
</warning>
<refsect2 id="map">
</para>
</refsect2>
-<refsect2 id="Dots">
- <title>About adding backslashes before dots</title>
- <para>The stylesheets do not add backslashes before
- periods/dots. One reason is that, because string substitution is
- performed over the entire roff source of each man page, it would be
- complicated to replace dots in visible contents without also causing
- them to be replaced in roff requests and escapes; for example,
- without causing, say, the <literal>.TH</literal> roff macro to be
- replaced with <literal>\.TH</literal>. Additionally, backslashes in
- front of periods/dots are needed only in the very rare case where a
- period is the very first character in a line, without any space in
- front of it. A better way to deal with that rare case is to add a
- zero-width space in front of the offending dot(s) in your
- source.</para>
+<refsect2 id="escape-replace">
+ <title>About escaping and replacing backslash, dot, and dash</title>
+ <para>The backslash and dot (\, .) characters have special meaning
+ for roff, so we:
+
+ <itemizedlist>
+ <listitem>
+ <para>escape backslashes and dots where they appear in the
+ source content</para>
+ </listitem>
+ <listitem>
+ <para>use certain (arbitrarily selected) Unicode characters as
+ “markers” – internal representations within the stylesheet – for
+ backslashes and dots</para>
+ </listitem>
+ <listitem>
+ <para>replace the Unicode characters with real backslashes and
+ dotes before output gets serialized</para>
+ </listitem>
+ </itemizedlist>
+
+ In addition, for certain reasons, we do the same thing for
+ dashes.</para>
+
+ <para>The mappings of dash, backslash, and dot to the Unicode
+ characters we use to represent them is hard-coded in the stylesheet:
+
+ <itemizedlist>
+ <listitem><para><literal>U+2591</literal> = dash</para></listitem>
+ <listitem><para><literal>U+2593</literal> = backslash</para></listitem>
+ <listitem><para><literal>U+2302</literal> = dot</para></listitem>
+ </itemizedlist>
+
+ Those Unicode characters were chosen on the assumption that they are
+ never used in content intended for output to man pages. It would be
+ possible to provide a way for configuring the mappings (using XSLT
+ parameters), but doing so would make the stylesheet code much more
+ verbose and harder to read.</para>
</refsect2>
</refsect1>
projects / docbook-dsssl / commitdiff