]> git.stg.codes - stg.git/blob - doc/xslt/params/man.th.title.max.length.xml
Minor change in stg's Makefile.
[stg.git] / doc / xslt / params / man.th.title.max.length.xml
1 <refentry xmlns="http://docbook.org/ns/docbook"
2           xmlns:xlink="http://www.w3.org/1999/xlink"
3           xmlns:xi="http://www.w3.org/2001/XInclude"
4           xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
5           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
6           version="5.0" xml:id="man.th.title.max.length">
7 <refmeta>
8 <refentrytitle>man.th.title.max.length</refentrytitle>
9 <refmiscinfo class="other" otherclass="datatype">integer</refmiscinfo>
10 </refmeta>
11 <refnamediv>
12 <refname>man.th.title.max.length</refname>
13 <refpurpose>Maximum length of title in header/footer</refpurpose>
14 </refnamediv>
15
16 <refsynopsisdiv>
17 <src:fragment xml:id="man.th.title.max.length.frag">
18 <xsl:param name="man.th.title.max.length">20</xsl:param>
19 </src:fragment>
20 </refsynopsisdiv>
21
22 <refsection><info><title>Description</title></info>
23
24 <para>Specifies the maximum permitted length of the title part of the
25 man-page <literal>.TH</literal> title line header/footer. If the title
26 exceeds the maxiumum specified, it is truncated down to the maximum
27 permitted length.</para>
28
29 <refsection><info><title>Details</title></info>
30   
31
32 <para>Every man page generated using the DocBook stylesheets has a
33 title line, specified using the <literal>TH</literal> roff
34 macro. Within that title line, there is always, at a minimum, a title,
35 followed by a section value (representing a man "section" -- usually
36 just a number).</para>
37
38 <para>The title and section are displayed, together, in the visible
39 header of each page. Where in the header they are displayed depends on
40 OS the man page is viewed on, and on what version of nroff/groff/man
41 is used for viewing the page. But, at a minimum and across all
42 systems, the title and section are displayed on the right-hand column
43 of the header. On many systems -- those with a modern groff, including
44 Linux systems -- they are displayed twice: both in the left and right
45 columns of the header.</para>
46
47 <para>So if the length of the title exceeds a certain percentage of
48 the column width in which the page is viewed, the left and right
49 titles can end up overlapping, making them unreadable, or breaking to
50 another line, which doesn't look particularly good.</para>
51
52 <para>So the stylesheets provide the
53 <parameter>man.th.title.max.length</parameter> parameter as a means
54 for truncating titles that exceed the maximum length that can be
55 viewing properly in a page header.</para>
56
57 <para>The default value is reasonable but somewhat arbitrary. If you
58 have pages with long titles, you may want to experiment with changing
59 the value in order to achieve the correct aesthetic results.</para>
60 </refsection>
61
62 </refsection>
63 </refentry>