Added several parameters for manpages output.

I have chosen to use a man.* naming strategy for all man-only
params (which these all are), even though in some cases the params
are basically the same as existing params (man.alignment and
man.hyphenate are basically same as the corresponding FO params,
man.output.encoding is same thing as chunker.output.encoding,
man.output.quietly is same as chunk.quietly).

One reason I went with create new params instead of reusing
existing ones is that this allows default values to be used for
manpages output that are different than the ones for whatever
other output format. For example, I set default for man.alignment
to "left" and man.hyphenation to "false". The corresponding FO
params have defaults of "justify" and "true".

And, as far as the man.* naming strategy, yeah, I guess it it
redundant. If, for example, all the HTML-only params started with
html.*, I guess it might not be so great idea. Or maybe it would
be. Anyway, I don't think there will probably ever be more than 30
man.* params total (god help us). And for developers at least, I
think it is helpful to be able to sort params by prefix if they
want to. Because, well, we now have 434 separate files in the
params/ directory. Going through those to find, say, just the
ones that relate to manpages output is a whole lot easier if they
all start with the same prefix.

diff --git a/xsl/params/man.alignment.xml b/xsl/params/man.alignment.xml
new file mode 100644 (file)
index 0000000..02a7174
--- /dev/null
+++ b/xsl/params/man.alignment.xml
@@ -0,0 +1,22 @@
+<refentry id="man.alignment">
+<refmeta>
+<refentrytitle>man.alignment</refentrytitle>
+
+</refmeta>
+<refnamediv>
+<refname>man.alignment</refname>
+<refpurpose>Specifies default text alignment for man-page output</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.alignment.frag'><xsl:param name="man.alignment">left</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>This parameter controls the alignment (roff
+"filling-and-adjusting" behavior) used for most body text in man-page
+output.</para>
+
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.charmap.subset.profile.xml b/xsl/params/man.charmap.subset.profile.xml
new file mode 100644 (file)
index 0000000..a7b2926
--- /dev/null
+++ b/xsl/params/man.charmap.subset.profile.xml
@@ -0,0 +1,259 @@
+<refentry id="man.charmap.subset.profile">
+<refmeta>
+<refentrytitle>man.charmap.subset.profile</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.charmap.subset.profile</refname>
+<refpurpose>Profile of character map subset to use in place of full map</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.charmap.subset.profile.frag'>
+<xsl:param name="man.charmap.subset.profile">
+@*[local-name() = 'class'] = 'roffControl' or
+@*[local-name() = 'class'] = 'C1ControlsAndLatin-1Supplement_symbols' or
+@*[local-name() = 'class'] = 'GeneralPunctuation_spaces' or
+@*[local-name() = 'class'] = 'GeneralPunctuation_dashes' or
+@*[local-name() = 'class'] = 'GeneralPunctuation_quotes' or
+@*[local-name() = 'class'] = 'GeneralPunctuation_bullets' or
+@*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
+@*[local-name() = 'name'] = 'WORD JOINER' or
+@*[local-name() = 'name'] = 'SERVICE MARK' or
+@*[local-name() = 'name'] = 'TRADE MARK SIGN' or
+@*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
+</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of the
+<parameter>man.charmap.use.subset</parameter> parameter is non-zero,
+The character-map subset specified by the
+<parameter>man.charmap.subset.profile</parameter> parameter is used
+instead of the full roff character map.</para>
+
+<para>The value of <parameter>man.charmap.subset.profile</parameter>
+is a string representating an XPath expression that matches attribute
+names and values for <tag>output-character</tag> elements in the
+character map.</para>
+
+<para>The attributes supported in the standard roff character map
+included in the distribution are:
+<variablelist>
+  <varlistentry>
+    <term>character</term>
+    <listitem>
+      <simpara>a raw Unicode character or numeric Unicode
+      character-entity value (either in decimal or hex)</simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>name</term>
+    <listitem>
+      <simpara>a standard full/long ISO/Unicode character name (e.g.,
+      "OHM SIGN")</simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>class</term>
+    <listitem>
+      <simpara>a "block" name, which consists of a standard Unicode
+      block name but with spaces removed and with, in some cases, a
+      _<replaceable>something</replaceable> string appended; for the
+      full list of block names supported in the standard roff
+      character map, see <xref
+      linkend="supported_blocknames"/>.</simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>entity</term>
+    <listitem>
+      <simpara>an ISO entity name (e.g., "ohm")</simpara>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>string</term>
+    <listitem>
+      <simpara>a string representating an roff/groff escape-code (with
+      "@esc@" used in place of the backslash), or a simple ASCII
+      string</simpara>
+    </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>The value of <parameter>man.charmap.subset.profile</parameter>
+is evaluated as an XPath expression at run-time to select a portion of
+the roff character map to use. You can tune the subset used by adding
+or removing parts. For example, if you need to use a wide range of
+mathematical operators in a document, and you want to have them
+converted into roff markup properly, you can might add the following:
+
+<literallayout class="monospaced" >@*[local-name() = 'class'] ='MathematicalOperators' </literallayout>
+
+That will cause a additional set of around 67 additional "math"
+characters to be converted into roff markup. </para>
+
+<note>
+<para>Depending on which XSLT engine you use, either the EXSLT
+<function>dyn:evaluate</function> extension function (for xsltproc or
+Xalan) or <function>saxon:evaluate</function> extensio function (for
+Saxon) are used to dynamically evaluate the value of
+<parameter>man.charmap.subset.profile</parameter> at run-time. If you
+don't use xsltproc, Saxon, Xalan -- or some other XSLT engine that
+supports <function>dyn:evaluate</function> -- you must either set the
+value of the <parameter>man.charmap.use.subset</parameter> parameter
+to zero and process your documents using the full character map
+instead, or set the value of the
+<parameter>man.charmap.enabled</parameter> parameter to zero instead
+(so that character-map processing is disabled completely.</para>
+</note>
+
+<para>An alternative to using
+<parameter>man.charmap.subset.profile</parameter>, is to create your
+own custom character map, and set the value of
+<parameter>man.charmap.uri</parameter> to the URI/filename for
+that. If you use a custom character map, you will probably want to
+include in it just the characters you want to use, and so you will
+most likely also want to set the value of
+<parameter>man.charmap.use.subset</parameter>to zero.</para>
+<para>You can create a
+custom character map by making a copy of the <ulink
+url="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl"
+>standard roff character map</ulink> provided in the distribution, and
+then adding to, changing, and/or deleting from that.</para>
+
+<caution>
+<para>If you author your DocBook XML source in UTF-8 or UTF-16
+encoding and aren't sure what OSes or environments your man-page
+output might end up being viewed on, and not sure what version of
+nroff/groff those environments might have, you should be careful about
+what Unicode symbols and special characters you use in your source and
+what parts you add to the value of
+<parameter>man.charmap.subset.profile</parameter>.</para>
+<para>Many of the escape codes used are specific to groff and using
+them may not provide the expected output on an OS or environment that
+uses nroff instead of groff.</para>
+<para>On the other hand, if you intend for your man-page output to be
+viewed only on modern systems (for example, GNU/Linux systems, FreeBSD
+systems, or Cygwin environments) that have a good, up-to-date groff,
+then you can safely include a wide range of Unicode symbols and
+special characters in your UTF-8 or UTF-16 encoded DocBook XML source
+and add any of the supported Unicode block names to the value of
+<parameter>man.charmap.subset.profile</parameter>.</para>
+</caution>
+
+
+<para>For other details, see the documentation for the
+<parameter>man.charmap.use.subset</parameter> parameter.</para>
+
+<refsect2 id="supported_blocknames">
+  <title>Supported "block" names</title>
+
+  <para>Below is the full list of "block" names supported in the
+  standard roff stylesheet provided in the distribution, along with a
+  description of which codepoints from the Unicode range corresponding
+  to that block name are supported.</para>
+
+<itemizedlist>
+  <listitem>
+    <para>C1ControlsAndLatin-1Supplement_symbols (x00a0 to x00ff, symbols)</para>
+  </listitem>
+  <listitem>
+    <para>C1ControlsAndLatin-1Supplement_letters (x00a0 to x00ff, letters)</para>
+  </listitem>
+  <listitem>
+    <para>LatinExtended-A (x0100 to x017f, partial)</para>
+  </listitem>
+  <listitem>
+    <para>LatinExtended-B (x0192 only)</para>
+  </listitem>
+  <listitem>
+    <para>SpacingModifierLetters (x02b0 to x02ee, partial)</para>
+  </listitem>
+  <listitem>
+    <para>GreekandCoptic (x0370 to x03ff, partial)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_spaces (x2000 to x206f, spaces)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_dashes (x2010 to x2015)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_quotes (x2000 to x206f, quotation marks)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_daggers (x2000 to x206f, daggers)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_bullets (x2000 to x206f, bullets)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_leaders (x2024 and x2025)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_ellipses (x2026)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_primes (x2032 to x2034)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_wordjoiner (x2060)</para>
+  </listitem>
+  <listitem>
+    <para>GeneralPunctuation_other (x2000 to x206f, except for
+    anything in any of the other GeneralPunctuation_* sets
+    above, partial)</para>
+  </listitem>
+  <listitem>
+    <para>SuperscriptsandSubscripts (x2070 to x209f)</para>
+  </listitem>
+  <listitem>
+    <para>CurrencySymbols (x20a0 to x20b1)</para>
+  </listitem>
+  <listitem>
+    <para>LetterlikeSymbols_servicemark (x2120)</para>
+  </listitem>
+  <listitem>
+    <para>LetterlikeSymbols_trademark (x2122)</para>
+  </listitem>
+  <listitem>
+    <para>LetterlikeSymbols (x2100 to x214b, except for the above two,
+    partial)</para>
+  </listitem>
+  <listitem>
+    <para>NumberForms (x2150 to x218f)</para>
+  </listitem>
+  <listitem>
+    <para>Arrows (x2190 to x21ff, partial)</para>
+  </listitem>
+  <listitem>
+    <para>MathematicalOperators (x2200 to x22ff, partial)</para>
+  </listitem>
+  <listitem>
+    <para>ControlPictures (x2400 to x243f)</para>
+  </listitem>
+  <listitem>
+    <para>EnclosedAlphanumerics (x2460 to x24ff)</para>
+  </listitem>
+  <listitem>
+    <para>GeometricShapes (x25a0 to x25f7, partial)</para>
+  </listitem>
+  <listitem>
+    <para>MiscellaneousSymbols (x2600 to x26ff, partial)</para>
+  </listitem>
+  <listitem>
+    <para>Dingbats (x2700 to x27be, partial)</para>
+  </listitem>
+  <listitem>
+    <para>AlphabeticPresentationForms (xfb00 to xfb04 only)</para>
+  </listitem>
+  <listitem>
+    <para>ArabicPresentationForms-B_wordjoiner (xfeff)</para>
+  </listitem>
+</itemizedlist>
+</refsect2>
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.charmap.uri.xml b/xsl/params/man.charmap.uri.xml
new file mode 100644 (file)
index 0000000..50939da
--- /dev/null
+++ b/xsl/params/man.charmap.uri.xml
@@ -0,0 +1,38 @@
+<refentry id="man.charmap.uri">
+<refmeta>
+<refentrytitle>man.charmap.uri</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.charmap.uri</refname>
+<refpurpose>URI for custom roff character map</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.charmap.uri.frag'>
+<xsl:param name="man.charmap.uri" select="''"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>For converting certain Unicode symbols and special characters in
+UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
+equivalents in man-page output, the DocBook XSL Stylesheets
+distribution includes an <ulink
+url="http://www.w3.org/TR/xslt20/#character-maps" >XSLT character
+map</ulink>. That character map can be considered the standard roff
+character map for the distribution.</para>
+
+<para>If the value of the <parameter>man.charmap.uri</parameter>
+parameter is non-empty, that value is used as the URI for the location
+for an alternate roff character map to use in place of the standard
+roff character map provided in the distribution.</para>
+
+<warning>
+<para>Do not set a value for <parameter>man.charmap.uri</parameter>
+unless you have a custom roff character map that differs from the
+standard one provided in the distribution.</para>
+</warning>
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.charmap.use.subset.xml b/xsl/params/man.charmap.use.subset.xml
new file mode 100644 (file)
index 0000000..c9146c9
--- /dev/null
+++ b/xsl/params/man.charmap.use.subset.xml
@@ -0,0 +1,66 @@
+<refentry id="man.charmap.use.subset">
+<refmeta>
+<refentrytitle>man.charmap.use.subset</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.charmap.use.subset</refname>
+<refpurpose>Use subset of character map instead of full map?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.charmap.use.subset.frag'>
+<xsl:param name="man.charmap.use.subset" select="1"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of the
+<parameter>man.charmap.use.subset</parameter> parameter is non-zero,
+a subset of the roff character map is used instead of the full roff
+character map. The profile of the subset used is specified by the
+<parameter>man.charmap.subset.profile</parameter> parameter.</para>
+
+<note>
+  <para>You may want to experiment with setting a non-zero value of
+  <parameter>man.charmap.use.subset</parameter>, so that the full
+  character map is used. Depending on which XSLT engine you run,
+  setting a non-zero value for
+  <parameter>man.charmap.use.subset</parameter> may significantly
+  increase the time needed to process your documents. Or it may
+  not. For example, if you set it and run it with xsltproc, it seems
+  to dramatically increase processing time; on the other hand, if you
+  set it and run it with Saxon, it does not seem to increase
+  processing time significantly</para>
+</note>
+
+<refsect2>
+<title>Details</title>
+<para>For converting certain Unicode symbols and special characters in
+UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
+equivalents in man-page output, the DocBook XSL Stylesheets
+distribution includes a <ulink
+url="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl"
+>roff character map</ulink> that contains more than 800 character
+mappings. That character map can be considered the standard roff
+character map for the distribution.</para>
+
+<note>
+<para>You can use the <parameter>man.charmap.uri</parameter>
+parameter to specify a URI for the location for an alternate roff
+character map to use in place of the standard roff character map
+provided in the distribution.</para>
+</note>
+
+<para>Because it is not terrifically efficient to use the standard
+800-character character map in full -- and for most (or all) users,
+never necessary to use it in full -- the DocBook XSL Stylesheets
+support a mechanism for using, within any given character map, a
+subset of character mappings instead of the full set. You can use the
+<parameter>man.charmap.subset.profile</parameter> parameter to tune
+the profile of that subset to use.</para>
+
+</refsect2>
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.hyphenate.xml b/xsl/params/man.hyphenate.xml
new file mode 100644 (file)
index 0000000..665b503
--- /dev/null
+++ b/xsl/params/man.hyphenate.xml
@@ -0,0 +1,21 @@
+<refentry id="hyphenate">
+<refmeta>
+<refentrytitle>man.hyphenate</refentrytitle>
+
+</refmeta>
+<refnamediv>
+<refname>man.hyphenate</refname>
+<refpurpose>Specifies hyphenation behavior for man-page output</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.hyphenate.frag'><xsl:param name="man.hyphenate">false</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If the value of this parameter is <literal>true</literal>, words
+may be hyphenated in man output. Otherwise, they may not.</para>
+
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.output.encoding.xml b/xsl/params/man.output.encoding.xml
new file mode 100644 (file)
index 0000000..d98ed86
--- /dev/null
+++ b/xsl/params/man.output.encoding.xml
@@ -0,0 +1,23 @@
+<refentry id="man.output.encoding">
+<refmeta>
+<refentrytitle>man.output.encoding</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.output.encoding</refname>
+<refpurpose>Encoding used for man-page output</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.output.encoding.frag'>
+<xsl:param name="man.output.encoding" select="'ISO-8859-1'"/></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>This parameter specifies the encoding to use for files generated
+by the manpages stylesheet. Not all processors support specification
+of this parameter.</para>
+
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.output.quietly.xml b/xsl/params/man.output.quietly.xml
new file mode 100644 (file)
index 0000000..5232f11
--- /dev/null
+++ b/xsl/params/man.output.quietly.xml
@@ -0,0 +1,25 @@
+<refentry id="man.output.quietly">
+<refmeta>
+<refentrytitle>man.output.quietly</refentrytitle>
+
+</refmeta>
+<refnamediv>
+<refname>man.output.quietly</refname>
+<refpurpose>Suppress filename messages emitted when generating output?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.output.quietly.frag'>
+<xsl:param name="man.output.quietly" select="0"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If zero (the default), for each man-page file created, a message
+with the name of the file is emitted. If non-zero, the files are
+output "quietly" -- that is, the filename messages are
+suppressed.</para>
+
+</refsect1>
+</refentry>