stylesheets/evergreen_docbook_files/docbook-xsl-1.75.2/params/man.th.title.max.length.xml

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