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>