1
0

param.xml 128 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220
  1. <?xml version="1.0" encoding="ASCII"?>
  2. <book version="5.0">
  3. <info>
  4. <title>Manpages Parameter Reference</title>
  5. <releaseinfo role="meta">
  6. $Id: param.xweb 9130 2011-10-11 08:05:37Z dpawson $
  7. </releaseinfo>
  8. <author>
  9. <orgname>The DocBook Project</orgname>
  10. </author>
  11. <copyright>
  12. <year>2005-2011</year>
  13. <holder>The DocBook Project</holder>
  14. </copyright>
  15. <abstract>
  16. <para>This is reference documentation for all user-configurable
  17. parameters in the DocBook XSL "manpages" stylesheet (for
  18. generating groff/nroff output). Note that the manpages
  19. stylesheet is a customization layer of the DocBook XSL HTML
  20. stylesheet. Therefore, you can also use a number of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../html/">HTML stylesheet parameters</link>
  21. to control manpages output (in addition to the
  22. manpages-specific parameters listed in this section).</para>
  23. </abstract>
  24. </info>
  25. <reference xml:id="general">
  26. <title>Hyphenation, justification, and breaking</title>
  27. <refentry version="5.0" xml:id="man.hyphenate">
  28. <refmeta>
  29. <refentrytitle>man.hyphenate</refentrytitle>
  30. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  31. </refmeta>
  32. <refnamediv>
  33. <refname>man.hyphenate</refname>
  34. <refpurpose>Enable hyphenation?</refpurpose>
  35. </refnamediv>
  36. <refsynopsisdiv>
  37. <programlisting xml:id="man.hyphenate.frag">
  38. &lt;xsl:param name="man.hyphenate"&gt;0&lt;/xsl:param&gt;</programlisting>
  39. </refsynopsisdiv>
  40. <refsection><info><title>Description</title></info>
  41. <para>If non-zero, hyphenation is enabled.</para>
  42. <note>
  43. <para>The default value for this parameter is zero because groff is
  44. not particularly smart about how it does hyphenation; it can end up
  45. hyphenating a lot of things that you don't want hyphenated. To
  46. mitigate that, the default behavior of the stylesheets is to suppress
  47. hyphenation of computer inlines, filenames, and URLs. (You can
  48. override the default behavior by setting non-zero values for the
  49. <parameter>man.hyphenate.urls</parameter>,
  50. <parameter>man.hyphenate.filenames</parameter>, and
  51. <parameter>man.hyphenate.computer.inlines</parameter> parameters.) But
  52. the best way is still to just globally disable hyphenation, as the
  53. stylesheets do by default.</para>
  54. <para>The only good reason to enabled hyphenation is if you have also
  55. enabled justification (which is disabled by default). The reason is
  56. that justified text can look very bad unless you also hyphenate it; to
  57. quote the <quote>Hypenation</quote> node from the groff info page:
  58. <blockquote>
  59. <para><emphasis>Since the odds are not great for finding a set of
  60. words, for every output line, which fit nicely on a line without
  61. inserting excessive amounts of space between words, 'gtroff'
  62. hyphenates words so that it can justify lines without inserting too
  63. much space between words.</emphasis></para>
  64. </blockquote>
  65. So, if you set a non-zero value for the
  66. <parameter>man.justify</parameter> parameter (to enable
  67. justification), then you should probably also set a non-zero value for
  68. <parameter>man.hyphenate</parameter> (to enable hyphenation).</para>
  69. </note>
  70. </refsection>
  71. </refentry>
  72. <refentry version="5.0" xml:id="man.hyphenate.urls">
  73. <refmeta>
  74. <refentrytitle>man.hyphenate.urls</refentrytitle>
  75. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  76. </refmeta>
  77. <refnamediv>
  78. <refname>man.hyphenate.urls</refname>
  79. <refpurpose>Hyphenate URLs?</refpurpose>
  80. </refnamediv>
  81. <refsynopsisdiv>
  82. <programlisting xml:id="man.hyphenate.urls.frag">
  83. &lt;xsl:param name="man.hyphenate.urls"&gt;0&lt;/xsl:param&gt;</programlisting>
  84. </refsynopsisdiv>
  85. <refsection><info><title>Description</title></info>
  86. <para>If zero (the default), hyphenation is suppressed for output of
  87. the <tag>ulink</tag> <tag class="attribute">url</tag> attribute.</para>
  88. <note>
  89. <para>If hyphenation is already turned off globally (that is, if
  90. <parameter>man.hyphenate</parameter> is zero, setting
  91. <parameter>man.hyphenate.urls</parameter> is not necessary.</para>
  92. </note>
  93. <para>If <parameter>man.hyphenate.urls</parameter> is non-zero, URLs
  94. will not be treated specially and are subject to hyphenation just like
  95. other words.</para>
  96. <note>
  97. <para>If you are thinking about setting a non-zero value for
  98. <parameter>man.hyphenate.urls</parameter> in order to make long
  99. URLs break across lines, you'd probably be better off
  100. experimenting with setting the
  101. <parameter>man.break.after.slash</parameter> parameter first. That
  102. will cause long URLs to be broken after slashes.</para>
  103. </note>
  104. </refsection>
  105. </refentry>
  106. <refentry version="5.0" xml:id="man.hyphenate.filenames">
  107. <refmeta>
  108. <refentrytitle>man.hyphenate.filenames</refentrytitle>
  109. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  110. </refmeta>
  111. <refnamediv>
  112. <refname>man.hyphenate.filenames</refname>
  113. <refpurpose>Hyphenate filenames?</refpurpose>
  114. </refnamediv>
  115. <refsynopsisdiv>
  116. <programlisting xml:id="man.hyphenate.filenames.frag">
  117. &lt;xsl:param name="man.hyphenate.filenames"&gt;0&lt;/xsl:param&gt;</programlisting>
  118. </refsynopsisdiv>
  119. <refsection><info><title>Description</title></info>
  120. <para>If zero (the default), hyphenation is suppressed for
  121. <tag>filename</tag> output.</para>
  122. <note>
  123. <para>If hyphenation is already turned off globally (that is, if
  124. <parameter>man.hyphenate</parameter> is zero, setting
  125. <parameter>man.hyphenate.filenames</parameter> is not
  126. necessary.</para>
  127. </note>
  128. <para>If <parameter>man.hyphenate.filenames</parameter> is non-zero,
  129. filenames will not be treated specially and are subject to hyphenation
  130. just like other words.</para>
  131. <note>
  132. <para>If you are thinking about setting a non-zero value for
  133. <parameter>man.hyphenate.filenames</parameter> in order to make long
  134. filenames/pathnames break across lines, you'd probably be better off
  135. experimenting with setting the
  136. <parameter>man.break.after.slash</parameter> parameter first. That
  137. will cause long pathnames to be broken after slashes.</para>
  138. </note>
  139. </refsection>
  140. </refentry>
  141. <refentry version="5.0" xml:id="man.hyphenate.computer.inlines">
  142. <refmeta>
  143. <refentrytitle>man.hyphenate.computer.inlines</refentrytitle>
  144. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  145. </refmeta>
  146. <refnamediv>
  147. <refname>man.hyphenate.computer.inlines</refname>
  148. <refpurpose>Hyphenate computer inlines?</refpurpose>
  149. </refnamediv>
  150. <refsynopsisdiv>
  151. <programlisting xml:id="man.hyphenate.computer.inlines.frag">
  152. &lt;xsl:param name="man.hyphenate.computer.inlines"&gt;0&lt;/xsl:param&gt;</programlisting>
  153. </refsynopsisdiv>
  154. <refsection><info><title>Description</title></info>
  155. <para>If zero (the default), hyphenation is suppressed for
  156. <quote>computer inlines</quote> such as environment variables,
  157. constants, etc. This parameter current affects output of the following
  158. elements:
  159. <simplelist type="inline">
  160. <member><tag>classname</tag></member>
  161. <member><tag>constant</tag></member>
  162. <member><tag>envar</tag></member>
  163. <member><tag>errorcode</tag></member>
  164. <member><tag>option</tag></member>
  165. <member><tag>replaceable</tag></member>
  166. <member><tag>userinput</tag></member>
  167. <member><tag>type</tag></member>
  168. <member><tag>varname</tag></member>
  169. </simplelist>
  170. </para>
  171. <note>
  172. <para>If hyphenation is already turned off globally (that is, if
  173. <parameter>man.hyphenate</parameter> is zero, setting the
  174. <parameter>man.hyphenate.computer.inlines</parameter> is not
  175. necessary.</para>
  176. </note>
  177. <para>If <parameter>man.hyphenate.computer.inlines</parameter> is
  178. non-zero, computer inlines will not be treated specially and will be
  179. hyphenated like other words when needed.</para>
  180. </refsection>
  181. </refentry>
  182. <refentry version="5.0" xml:id="man.justify">
  183. <refmeta>
  184. <refentrytitle>man.justify</refentrytitle>
  185. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  186. </refmeta>
  187. <refnamediv>
  188. <refname>man.justify</refname>
  189. <refpurpose>Justify text to both right and left margins?</refpurpose>
  190. </refnamediv>
  191. <refsynopsisdiv>
  192. <programlisting xml:id="man.justify.frag">
  193. &lt;xsl:param name="man.justify"&gt;0&lt;/xsl:param&gt;</programlisting>
  194. </refsynopsisdiv>
  195. <refsection><info><title>Description</title></info>
  196. <para>If non-zero, text is justified to both the right and left
  197. margins (or, in roff terminology, "adjusted and filled" to both the
  198. right and left margins). If zero (the default), text is adjusted to
  199. the left margin only -- producing what is traditionally called
  200. "ragged-right" text.</para>
  201. <note>
  202. <para>The default value for this parameter is zero because justified
  203. text looks good only when it is also hyphenated. Without hyphenation,
  204. excessive amounts of space often end up getting between words, in
  205. order to "pad" lines out to align on the right margin.</para>
  206. <para>The problem is that groff is not particularly smart about how it
  207. does hyphenation; it can end up hyphenating a lot of things that you
  208. don't want hyphenated. So, disabling both justification and
  209. hyphenation ensures that hyphens won't get inserted where you don't
  210. want to them, and you don't end up with lines containing excessive
  211. amounts of space between words.</para>
  212. <para>However, if do you decide to set a non-zero value for the
  213. <parameter>man.justify</parameter> parameter (to enable
  214. justification), then you should probably also set a non-zero value for
  215. <parameter>man.hyphenate</parameter> (to enable hyphenation).</para>
  216. <para>Yes, these default settings run counter to how most existing man
  217. pages are formatted. But there are some notable exceptions, such as
  218. the <literal>perl</literal> man pages.</para>
  219. </note>
  220. </refsection>
  221. </refentry>
  222. <refentry version="5.0" xml:id="man.break.after.slash">
  223. <refmeta>
  224. <refentrytitle>man.break.after.slash</refentrytitle>
  225. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  226. </refmeta>
  227. <refnamediv>
  228. <refname>man.break.after.slash</refname>
  229. <refpurpose>Enable line-breaking after slashes?</refpurpose>
  230. </refnamediv>
  231. <refsynopsisdiv>
  232. <programlisting xml:id="man.break.after.slash.frag">
  233. &lt;xsl:param name="man.break.after.slash"&gt;0&lt;/xsl:param&gt;</programlisting>
  234. </refsynopsisdiv>
  235. <refsection><info><title>Description</title></info>
  236. <para>If non-zero, line-breaking after slashes is enabled. This is
  237. mainly useful for causing long URLs or pathnames/filenames to be
  238. broken up or "wrapped" across lines (though it also has the side
  239. effect of sometimes causing relatively short URLs and pathnames to be
  240. broken up across lines too).</para>
  241. <para>If zero (the default), line-breaking after slashes is
  242. disabled. In that case, strings containing slashes (for example, URLs
  243. or filenames) are not broken across lines, even if they exceed the
  244. maximum column widith.</para>
  245. <warning>
  246. <para>If you set a non-zero value for this parameter, check your
  247. man-page output carefuly afterwards, in order to make sure that the
  248. setting has not introduced an excessive amount of breaking-up of URLs
  249. or pathnames. If your content contains mostly short URLs or
  250. pathnames, setting a non-zero value for
  251. <parameter>man.break.after.slash</parameter> will probably result in
  252. in a significant number of relatively short URLs and pathnames being
  253. broken across lines, which is probably not what you want.</para>
  254. </warning>
  255. </refsection>
  256. </refentry>
  257. </reference>
  258. <reference xml:id="indent">
  259. <title>Indentation</title>
  260. <refentry version="5.0" xml:id="man.indent.width">
  261. <refmeta>
  262. <refentrytitle>man.indent.width</refentrytitle>
  263. <refmiscinfo class="other" otherclass="datatype">length</refmiscinfo>
  264. </refmeta>
  265. <refnamediv>
  266. <refname>man.indent.width</refname>
  267. <refpurpose>Specifies width used for adjusted indents</refpurpose>
  268. </refnamediv>
  269. <refsynopsisdiv>
  270. <programlisting xml:id="man.indent.width.frag">
  271. &lt;xsl:param name="man.indent.width"&gt;4&lt;/xsl:param&gt;
  272. </programlisting>
  273. </refsynopsisdiv>
  274. <refsection><info><title>Description</title></info>
  275. <para>The <parameter>man.indent.width</parameter> parameter specifies
  276. the width used for adjusted indents. The value of
  277. <parameter>man.indent.width</parameter> is used for indenting of
  278. lists, verbatims, headings, and elsewhere, depending on whether the
  279. values of certain <literal>man.indent.*</literal> boolean parameters
  280. are non-zero.</para>
  281. <para>The value of <parameter>man.indent.width</parameter> should
  282. include a valid roff measurement unit (for example,
  283. <literal>n</literal> or <literal>u</literal>). The default value of
  284. <literal>4n</literal> specifies a 4-en width; when viewed on a
  285. console, that amounts to the width of four characters. For details
  286. about roff measurment units, see the <literal>Measurements</literal>
  287. node in the groff info page.</para>
  288. </refsection>
  289. </refentry>
  290. <refentry version="5.0" xml:id="man.indent.refsect">
  291. <refmeta>
  292. <refentrytitle>man.indent.refsect</refentrytitle>
  293. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  294. </refmeta>
  295. <refnamediv>
  296. <refname>man.indent.refsect</refname>
  297. <refpurpose>Adjust indentation of refsect* and refsection?</refpurpose>
  298. </refnamediv>
  299. <refsynopsisdiv>
  300. <programlisting xml:id="man.indent.refsect.frag">
  301. &lt;xsl:param name="man.indent.refsect" select="0"&gt;&lt;/xsl:param&gt;</programlisting>
  302. </refsynopsisdiv>
  303. <refsection><info><title>Description</title></info>
  304. <para>If the value of <parameter>man.indent.refsect</parameter> is
  305. non-zero, the width of the left margin for
  306. <tag>refsect1</tag>, <tag>refsect2</tag> and
  307. <tag>refsect3</tag> contents and titles (and first-level,
  308. second-level, and third-level nested
  309. <tag>refsection</tag>instances) is adjusted by the value of
  310. the <parameter>man.indent.width</parameter> parameter. With
  311. <parameter>man.indent.width</parameter> set to its default value of
  312. <literal>3n</literal>, the main results are that:
  313. <itemizedlist>
  314. <listitem>
  315. <para>contents of <tag>refsect1</tag> are output with a
  316. left margin of three characters instead the roff default of seven
  317. or eight characters</para>
  318. </listitem>
  319. <listitem>
  320. <para>contents of <tag>refsect2</tag> are displayed in
  321. console output with a left margin of six characters instead the of
  322. the roff default of seven characters</para>
  323. </listitem>
  324. <listitem>
  325. <para> the contents of <tag>refsect3</tag> and nested
  326. <tag>refsection</tag> instances are adjusted
  327. accordingly.</para>
  328. </listitem>
  329. </itemizedlist>
  330. If instead the value of <parameter>man.indent.refsect</parameter> is
  331. zero, no margin adjustment is done for <literal>refsect*</literal>
  332. output.</para>
  333. <tip>
  334. <para>If your content is primarly comprised of
  335. <tag>refsect1</tag> and <tag>refsect2</tag> content
  336. (or the <tag>refsection</tag> equivalent)&#160;&#8211; with few or
  337. no <tag>refsect3</tag> or lower nested sections , you may be
  338. able to &#8220;conserve&#8221; space in your output by setting
  339. <parameter>man.indent.refsect</parameter> to a non-zero value. Doing
  340. so will &#8220;squeeze&#8221; the left margin in such as way as to provide an
  341. additional four characters of &#8220;room&#8221; per line in
  342. <tag>refsect1</tag> output. That extra room may be useful
  343. if, for example, you have many verbatim sections with long lines in
  344. them.</para>
  345. </tip>
  346. </refsection>
  347. </refentry>
  348. <refentry version="5.0" xml:id="man.indent.blurbs">
  349. <refmeta>
  350. <refentrytitle>man.indent.blurbs</refentrytitle>
  351. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  352. </refmeta>
  353. <refnamediv>
  354. <refname>man.indent.blurbs</refname>
  355. <refpurpose>Adjust indentation of blurbs?</refpurpose>
  356. </refnamediv>
  357. <refsynopsisdiv>
  358. <programlisting xml:id="man.indent.blurbs.frag">
  359. &lt;xsl:param name="man.indent.blurbs" select="1"&gt;&lt;/xsl:param&gt;</programlisting>
  360. </refsynopsisdiv>
  361. <refsection><info><title>Description</title></info>
  362. <para>If the value of <parameter>man.indent.blurbs</parameter> is
  363. non-zero, the width of the left margin for
  364. <tag>authorblurb</tag>, <tag>personblurb</tag>, and
  365. <tag>contrib</tag> output is set to the value of the
  366. <parameter>man.indent.width</parameter> parameter
  367. (<literal>3n</literal> by default). If instead the value of
  368. <parameter>man.indent.blurbs</parameter> is zero, the built-in roff
  369. default width (<literal>7.2n</literal>) is used.</para>
  370. </refsection>
  371. </refentry>
  372. <refentry version="5.0" xml:id="man.indent.lists">
  373. <refmeta>
  374. <refentrytitle>man.indent.lists</refentrytitle>
  375. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  376. </refmeta>
  377. <refnamediv>
  378. <refname>man.indent.lists</refname>
  379. <refpurpose>Adjust indentation of lists?</refpurpose>
  380. </refnamediv>
  381. <refsynopsisdiv>
  382. <programlisting xml:id="man.indent.lists.frag">
  383. &lt;xsl:param name="man.indent.lists" select="1"&gt;&lt;/xsl:param&gt;</programlisting>
  384. </refsynopsisdiv>
  385. <refsection><info><title>Description</title></info>
  386. <para>If the value of <parameter>man.indent.lists</parameter> is
  387. non-zero, the width of the left margin for list items in
  388. <tag>itemizedlist</tag>,
  389. <tag>orderedlist</tag>,
  390. <tag>variablelist</tag> output (and output of some other
  391. lists) is set to the value of the
  392. <parameter>man.indent.width</parameter> parameter
  393. (<literal>4n</literal> by default). If instead the value of
  394. <parameter>man.indent.lists</parameter> is zero, the built-in roff
  395. default width (<literal>7.2n</literal>) is used.</para>
  396. </refsection>
  397. </refentry>
  398. <refentry version="5.0" xml:id="man.indent.verbatims">
  399. <refmeta>
  400. <refentrytitle>man.indent.verbatims</refentrytitle>
  401. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  402. </refmeta>
  403. <refnamediv>
  404. <refname>man.indent.verbatims</refname>
  405. <refpurpose>Adjust indentation of verbatims?</refpurpose>
  406. </refnamediv>
  407. <refsynopsisdiv>
  408. <programlisting xml:id="man.indent.verbatims.frag">
  409. &lt;xsl:param name="man.indent.verbatims" select="1"&gt;&lt;/xsl:param&gt;</programlisting>
  410. </refsynopsisdiv>
  411. <refsection><info><title>Description</title></info>
  412. <para>If the value of <parameter>man.indent.verbatims</parameter> is
  413. non-zero, the width of the left margin for output of verbatim
  414. environments (<tag>programlisting</tag>,
  415. <tag>screen</tag>, and so on) is set to the value of the
  416. <parameter>man.indent.width</parameter> parameter
  417. (<literal>3n</literal> by default). If instead the value of
  418. <parameter>man.indent.verbatims</parameter> is zero, the built-in roff
  419. default width (<literal>7.2n</literal>) is used.</para>
  420. </refsection>
  421. </refentry>
  422. </reference>
  423. <reference xml:id="fonts">
  424. <title>Fonts</title>
  425. <refentry version="5.0" xml:id="man.font.funcprototype">
  426. <refmeta>
  427. <refentrytitle>man.font.funcprototype</refentrytitle>
  428. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  429. </refmeta>
  430. <refnamediv>
  431. <refname>man.font.funcprototype</refname>
  432. <refpurpose>Specifies font for funcprototype output</refpurpose>
  433. </refnamediv>
  434. <refsynopsisdiv>
  435. <programlisting xml:id="man.font.funcprototype.frag">
  436. &lt;xsl:param name="man.font.funcprototype"&gt;BI&lt;/xsl:param&gt;
  437. </programlisting>
  438. </refsynopsisdiv>
  439. <refsection><info><title>Description</title></info>
  440. <para>The <parameter>man.font.funcprototype</parameter> parameter
  441. specifies the font for <tag>funcprototype</tag> output. It
  442. should be a valid roff font name, such as <literal>BI</literal> or
  443. <literal>B</literal>.</para>
  444. </refsection>
  445. </refentry>
  446. <refentry version="5.0" xml:id="man.font.funcsynopsisinfo">
  447. <refmeta>
  448. <refentrytitle>man.font.funcsynopsisinfo</refentrytitle>
  449. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  450. </refmeta>
  451. <refnamediv>
  452. <refname>man.font.funcsynopsisinfo</refname>
  453. <refpurpose>Specifies font for funcsynopsisinfo output</refpurpose>
  454. </refnamediv>
  455. <refsynopsisdiv>
  456. <programlisting xml:id="man.font.funcsynopsisinfo.frag">
  457. &lt;xsl:param name="man.font.funcsynopsisinfo"&gt;B&lt;/xsl:param&gt;
  458. </programlisting>
  459. </refsynopsisdiv>
  460. <refsection><info><title>Description</title></info>
  461. <para>The <parameter>man.font.funcsynopsisinfo</parameter> parameter
  462. specifies the font for <tag>funcsynopsisinfo</tag> output. It
  463. should be a valid roff font name, such as <literal>B</literal> or
  464. <literal>I</literal>.</para>
  465. </refsection>
  466. </refentry>
  467. <refentry version="5.0" xml:id="man.font.links">
  468. <refmeta>
  469. <refentrytitle>man.font.links</refentrytitle>
  470. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  471. </refmeta>
  472. <refnamediv>
  473. <refname>man.font.links</refname>
  474. <refpurpose>Specifies font for links</refpurpose>
  475. </refnamediv>
  476. <refsynopsisdiv>
  477. <programlisting xml:id="man.font.links.frag">
  478. &lt;xsl:param name="man.font.links"&gt;B&lt;/xsl:param&gt;
  479. </programlisting>
  480. </refsynopsisdiv>
  481. <refsection><info><title>Description</title></info>
  482. <para>The <parameter>man.font.links</parameter> parameter
  483. specifies the font for output of links (<tag>ulink</tag> instances
  484. and any instances of any element with an <tag class="attribute">xlink:href</tag> attribute).</para>
  485. <para>The value of <parameter>man.font.links</parameter> must be
  486. either <literal>B</literal> or <literal>I</literal>, or empty. If
  487. the value is empty, no font formatting is applied to links.</para>
  488. <para>If you set <parameter>man.endnotes.are.numbered</parameter> and/or
  489. <parameter>man.endnotes.list.enabled</parameter> to zero (disabled), then
  490. you should probably also set an empty value for
  491. <parameter>man.font.links</parameter>. But if
  492. <parameter>man.endnotes.are.numbered</parameter> is non-zero (enabled),
  493. you should probably keep
  494. <parameter>man.font.links</parameter> set to
  495. <literal>B</literal> or <literal>I</literal><footnote><para>The
  496. main purpose of applying a font format to links in most output
  497. formats it to indicate that the formatted text is
  498. &#8220;clickable&#8221;; given that links rendered in man pages are
  499. not &#8220;real&#8221; hyperlinks that users can click on, it might
  500. seem like there is never a good reason to have font formatting for
  501. link contents in man output.</para>
  502. <para>In fact, if you suppress the
  503. display of inline link references (by setting
  504. <parameter>man.endnotes.are.numbered</parameter> to zero), there is no
  505. good reason to apply font formatting to links. However, if
  506. <parameter>man.endnotes.are.numbered</parameter> is non-zero, having
  507. font formatting for links (arguably) serves a purpose: It provides
  508. &#8220;context&#8221; information about exactly what part of the text
  509. is being &#8220;annotated&#8221; by the link. Depending on how you
  510. mark up your content, that context information may or may not
  511. have value.</para></footnote>.</para>
  512. </refsection>
  513. <refsection><info><title>Related Parameters</title></info>
  514. <para><parameter>man.endnotes.list.enabled</parameter>,
  515. <parameter>man.endnotes.are.numbered</parameter></para>
  516. </refsection>
  517. </refentry>
  518. <refentry version="5.0" xml:id="man.font.table.headings">
  519. <refmeta>
  520. <refentrytitle>man.font.table.headings</refentrytitle>
  521. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  522. </refmeta>
  523. <refnamediv>
  524. <refname>man.font.table.headings</refname>
  525. <refpurpose>Specifies font for table headings</refpurpose>
  526. </refnamediv>
  527. <refsynopsisdiv>
  528. <programlisting xml:id="man.font.table.headings.frag">
  529. &lt;xsl:param name="man.font.table.headings"&gt;B&lt;/xsl:param&gt;
  530. </programlisting>
  531. </refsynopsisdiv>
  532. <refsection><info><title>Description</title></info>
  533. <para>The <parameter>man.font.table.headings</parameter> parameter
  534. specifies the font for <tag>table</tag> headings. It should be
  535. a valid roff font, such as <literal>B</literal> or
  536. <literal>I</literal>.</para>
  537. </refsection>
  538. </refentry>
  539. <refentry version="5.0" xml:id="man.font.table.title">
  540. <refmeta>
  541. <refentrytitle>man.font.table.title</refentrytitle>
  542. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  543. </refmeta>
  544. <refnamediv>
  545. <refname>man.font.table.title</refname>
  546. <refpurpose>Specifies font for table headings</refpurpose>
  547. </refnamediv>
  548. <refsynopsisdiv>
  549. <programlisting xml:id="man.font.table.title.frag">
  550. &lt;xsl:param name="man.font.table.title"&gt;B&lt;/xsl:param&gt;
  551. </programlisting>
  552. </refsynopsisdiv>
  553. <refsection><info><title>Description</title></info>
  554. <para>The <parameter>man.font.table.title</parameter> parameter
  555. specifies the font for <tag>table</tag> titles. It should be
  556. a valid roff font, such as <literal>B</literal> or
  557. <literal>I</literal>.</para>
  558. </refsection>
  559. </refentry>
  560. </reference>
  561. <reference xml:id="synopsis">
  562. <title>SYNOPSIS section</title>
  563. <refentry version="5.0" xml:id="man.funcsynopsis.style">
  564. <refmeta>
  565. <refentrytitle>man.funcsynopsis.style</refentrytitle>
  566. <refmiscinfo class="other" otherclass="datatype">list</refmiscinfo>
  567. <refmiscinfo class="other" otherclass="value">ansi</refmiscinfo>
  568. <refmiscinfo class="other" otherclass="value">kr</refmiscinfo>
  569. </refmeta>
  570. <refnamediv>
  571. <refname>man.funcsynopsis.style</refname>
  572. <refpurpose>What style of <tag>funcsynopsis</tag> should be generated?</refpurpose>
  573. </refnamediv>
  574. <refsynopsisdiv>
  575. <programlisting xml:id="man.funcsynopsis.style.frag">&lt;xsl:param name="man.funcsynopsis.style"&gt;ansi&lt;/xsl:param&gt;</programlisting>
  576. </refsynopsisdiv>
  577. <refsection><info><title>Description</title></info>
  578. <para>If <parameter>man.funcsynopsis.style</parameter> is
  579. <literal>ansi</literal>, ANSI-style function synopses are
  580. generated for a <tag>funcsynopsis</tag>, otherwise K&amp;R-style
  581. function synopses are generated.</para>
  582. </refsection>
  583. </refentry>
  584. </reference>
  585. <reference xml:id="authors">
  586. <title>AUTHORS and COPYRIGHT sections</title>
  587. <refentry version="5.0" xml:id="man.authors.section.enabled">
  588. <refmeta>
  589. <refentrytitle>man.authors.section.enabled</refentrytitle>
  590. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  591. </refmeta>
  592. <refnamediv>
  593. <refname>man.authors.section.enabled</refname>
  594. <refpurpose>Display auto-generated AUTHORS section?</refpurpose>
  595. </refnamediv>
  596. <refsynopsisdiv>
  597. <programlisting xml:id="man.authors.section.enabled.frag">
  598. &lt;xsl:param name="man.authors.section.enabled"&gt;1&lt;/xsl:param&gt;
  599. </programlisting>
  600. </refsynopsisdiv>
  601. <refsection><info><title>Description</title></info>
  602. <para>If the value of
  603. <parameter>man.authors.section.enabled</parameter> is non-zero
  604. (the default), then an <literal>AUTHORS</literal> section is
  605. generated near the end of each man page. The output of the
  606. <literal>AUTHORS</literal> section is assembled from any
  607. <tag>author</tag>, <tag>editor</tag>, and <tag>othercredit</tag>
  608. metadata found in the contents of the child <tag>info</tag> or
  609. <tag>refentryinfo</tag> (if any) of the <tag>refentry</tag>
  610. itself, or from any <tag>author</tag>, <tag>editor</tag>, and
  611. <tag>othercredit</tag> metadata that may appear in <tag>info</tag>
  612. contents of any ancestors of the <tag>refentry</tag>.</para>
  613. <para>If the value of
  614. <parameter>man.authors.section.enabled</parameter> is zero, the
  615. the auto-generated <literal>AUTHORS</literal> section is
  616. suppressed.</para>
  617. <para>Set the value of
  618. <parameter>man.authors.section.enabled</parameter> to zero if
  619. you want to have a manually created <literal>AUTHORS</literal>
  620. section in your source, and you want it to appear in output
  621. instead of the auto-generated <literal>AUTHORS</literal>
  622. section.</para>
  623. </refsection>
  624. </refentry>
  625. <refentry version="5.0" xml:id="man.copyright.section.enabled">
  626. <refmeta>
  627. <refentrytitle>man.copyright.section.enabled</refentrytitle>
  628. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  629. </refmeta>
  630. <refnamediv>
  631. <refname>man.copyright.section.enabled</refname>
  632. <refpurpose>Display auto-generated COPYRIGHT section?</refpurpose>
  633. </refnamediv>
  634. <refsynopsisdiv>
  635. <programlisting xml:id="man.copyright.section.enabled.frag">
  636. &lt;xsl:param name="man.copyright.section.enabled"&gt;1&lt;/xsl:param&gt;
  637. </programlisting>
  638. </refsynopsisdiv>
  639. <refsection><info><title>Description</title></info>
  640. <para>If the value of
  641. <parameter>man.copyright.section.enabled</parameter> is non-zero
  642. (the default), then a <literal>COPYRIGHT</literal> section is
  643. generated near the end of each man page. The output of the
  644. <literal>COPYRIGHT</literal> section is assembled from any
  645. <tag>copyright</tag> and <tag>legalnotice</tag> metadata found in
  646. the contents of the child <tag>info</tag> or
  647. <tag>refentryinfo</tag> (if any) of the <tag>refentry</tag>
  648. itself, or from any <tag>copyright</tag> and
  649. <tag>legalnotice</tag> metadata that may appear in <tag>info</tag>
  650. contents of any ancestors of the <tag>refentry</tag>.</para>
  651. <para>If the value of
  652. <parameter>man.copyright.section.enabled</parameter> is zero, the
  653. the auto-generated <literal>COPYRIGHT</literal> section is
  654. suppressed.</para>
  655. <para>Set the value of
  656. <parameter>man.copyright.section.enabled</parameter> to zero if
  657. you want to have a manually created <literal>COPYRIGHT</literal>
  658. section in your source, and you want it to appear in output
  659. instead of the auto-generated <literal>COPYRIGHT</literal>
  660. section.</para>
  661. </refsection>
  662. </refentry>
  663. </reference>
  664. <reference xml:id="endnotes">
  665. <title>Endnotes and link handling</title>
  666. <refentry version="5.0" xml:id="man.endnotes.list.enabled">
  667. <refmeta>
  668. <refentrytitle>man.endnotes.list.enabled</refentrytitle>
  669. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  670. </refmeta>
  671. <refnamediv>
  672. <refname>man.endnotes.list.enabled</refname>
  673. <refpurpose>Display endnotes list at end of man page?</refpurpose>
  674. </refnamediv>
  675. <refsynopsisdiv>
  676. <programlisting xml:id="man.endnotes.list.enabled.frag">
  677. &lt;xsl:param name="man.endnotes.list.enabled"&gt;1&lt;/xsl:param&gt;
  678. </programlisting>
  679. </refsynopsisdiv>
  680. <refsection><info><title>Description</title></info>
  681. <para>If the value of <parameter>man.endnotes.list.enabled</parameter> is
  682. non-zero (the default), then an endnotes list is added to the end of
  683. the output man page.</para>
  684. <para>If the value of <parameter>man.endnotes.list.enabled</parameter> is
  685. zero, the list is suppressed &#8212; unless link numbering is enabled (that
  686. is, if <parameter>man.endnotes.are.numbered</parameter> is non-zero), in
  687. which case, that setting overrides the
  688. <parameter>man.endnotes.list.enabled</parameter> setting, and the
  689. endnotes list is still displayed. The reason is that inline
  690. numbering of notesources associated with endnotes only makes sense
  691. if a (numbered) list of endnotes is also generated.</para>
  692. <note>
  693. <para>Leaving
  694. <parameter>man.endnotes.list.enabled</parameter> at its default
  695. (non-zero) value ensures that no &#8220;out of line&#8221; information (such
  696. as the URLs for hyperlinks and images) gets lost in your
  697. man-page output. It just gets &#8220;rearranged&#8221;.</para>
  698. <para>So if you&#8217;re thinking about disabling endnotes listing by
  699. setting the value of
  700. <parameter>man.endnotes.list.enabled</parameter> to zero:
  701. Before you do so, first take some time to carefully consider
  702. the information needs and experiences of your users. The &#8220;out
  703. of line&#8221; information has value even if the presentation of it
  704. in text output is not as interactive as it may be in other
  705. output formats.</para>
  706. <para>As far as the specific case of URLs: Even though the URLs
  707. displayed in text output may not be &#8220;real&#8221; (clickable)
  708. hyperlinks, many X terminals have convenience features for
  709. recognizing URLs and can, for example, present users with
  710. an options to open a URL in a browser with the user clicks on
  711. the URL is a terminal window. And short of those, users with X
  712. terminals can always manually cut and paste the URLs into a web
  713. browser.</para>
  714. <para>Also, note that various &#8220;man to html&#8221; tools, such as the
  715. widely used <command><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://users.actrix.gen.nz/michael/vhman2html.html">man2html</link></command> (<literal>VH-Man2html</literal>)
  716. application, automatically mark up URLs with <literal>a@href</literal> markup
  717. during conversion &#8212; resulting in &#8220;real&#8221; hyperlinks in HTML
  718. output from those tools.</para>
  719. </note>
  720. <para>To &#8220;turn off&#8221; numbering of endnotes in the
  721. endnotes list, set <parameter>man.endnotes.are.numbered</parameter>
  722. to zero. The endnotes list will
  723. still be displayed; it will just be displayed without the
  724. numbers<footnote><para>It can still make sense to have
  725. the list of endnotes displayed even if you have endnotes numbering turned
  726. off. In that case, your endnotes list basically becomes a &#8220;list
  727. of references&#8221; without any association with specific text in
  728. your document. This is probably the best option if you find the inline
  729. endnotes numbering obtrusive. Your users will still have access to all the &#8220;out of line&#8221;
  730. such as URLs for hyperlinks.</para></footnote>
  731. </para>
  732. <para>The default heading for the endnotes list is
  733. <literal>NOTES</literal>. To change that, set a non-empty
  734. value for the <parameter>man.endnotes.list.heading</parameter>
  735. parameter.</para>
  736. <para>In the case of notesources that are links: Along with the
  737. URL for each link, the endnotes list includes the contents of the
  738. link. The list thus includes only non-empty<footnote>
  739. <para>A &#8220;non-empty&#8221; link is one that looks like
  740. this:<literallayout class="monospaced"> &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"&gt;manpages&lt;/ulink&gt;</literallayout>
  741. an &#8220;empty link&#8221; is on that looks like this:<literallayout class="monospaced"> &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/&gt;</literallayout>
  742. </para></footnote> links.
  743. Empty links are never included, and never numbered. They are simply
  744. displayed inline, without any numbering.</para>
  745. <para>In addition, if there are multiple instances of links in a
  746. <tag>refentry</tag> that have the same URL, the URL is listed only
  747. once. The contents listed for that link in the endnotes list are
  748. the contents of the first link which has that URL.</para>
  749. <para>If you disable endnotes listing, you should probably also set
  750. <parameter>man.links.are.underlined</parameter> to zero (to disable
  751. link underlining).</para>
  752. </refsection>
  753. </refentry>
  754. <refentry version="5.0" xml:id="man.endnotes.list.heading">
  755. <refmeta>
  756. <refentrytitle>man.endnotes.list.heading</refentrytitle>
  757. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  758. </refmeta>
  759. <refnamediv>
  760. <refname>man.endnotes.list.heading</refname>
  761. <refpurpose>Specifies an alternate name for endnotes list</refpurpose>
  762. </refnamediv>
  763. <refsynopsisdiv>
  764. <programlisting xml:id="man.endnotes.list.heading.frag">
  765. &lt;xsl:param name="man.endnotes.list.heading"&gt;&lt;/xsl:param&gt;
  766. </programlisting>
  767. </refsynopsisdiv>
  768. <refsection><info><title>Description</title></info>
  769. <para>If the value of the
  770. <parameter>man.endnotes.are.numbered</parameter> parameter
  771. and/or the <parameter>man.endnotes.list.enabled</parameter>
  772. parameter is non-zero (the defaults for both are non-zero), a
  773. numbered list of endnotes is generated near the end of each man
  774. page. The default heading for the list of endnotes is the
  775. equivalent of the English word <literal>NOTES</literal> in
  776. the current locale. To cause an alternate heading to be displayed,
  777. set a non-empty value for the
  778. <parameter>man.endnotes.list.heading</parameter> parameter &#8212;
  779. for example, <literal>REFERENCES</literal>.</para>
  780. </refsection>
  781. </refentry>
  782. <refentry version="5.0" xml:id="man.endnotes.are.numbered">
  783. <refmeta>
  784. <refentrytitle>man.endnotes.are.numbered</refentrytitle>
  785. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  786. </refmeta>
  787. <refnamediv>
  788. <refname>man.endnotes.are.numbered</refname>
  789. <refpurpose>Number endnotes?</refpurpose>
  790. </refnamediv>
  791. <refsynopsisdiv>
  792. <programlisting xml:id="man.endnotes.are.numbered.frag">
  793. &lt;xsl:param name="man.endnotes.are.numbered"&gt;1&lt;/xsl:param&gt;
  794. </programlisting>
  795. </refsynopsisdiv>
  796. <refsection><info><title>Description</title></info>
  797. <para>If the value of <parameter>man.endnotes.are.numbered</parameter> is
  798. non-zero (the default), then for each non-empty<footnote>
  799. <para>A &#8220;non-empty&#8221; notesource is one that looks like
  800. this:<literallayout class="monospaced"> &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"&gt;manpages&lt;/ulink&gt;</literallayout>
  801. an &#8220;empty&#8221; notesource is on that looks like this:<literallayout class="monospaced"> &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/&gt;</literallayout>
  802. </para></footnote> &#8220;notesource&#8221;:
  803. <itemizedlist>
  804. <listitem>
  805. <para>a number (in square brackets) is displayed inline after the
  806. rendered inline contents (if any) of the notesource</para>
  807. </listitem>
  808. <listitem>
  809. <para>the contents of the notesource are included in a
  810. numbered list of endnotes that is generated at the end of
  811. each man page; the number for each endnote corresponds to
  812. the inline number for the notesource with which it is
  813. associated</para>
  814. </listitem>
  815. </itemizedlist>
  816. The default heading for the list of endnotes is
  817. <literal>NOTES</literal>. To output a different heading, set a value
  818. for the <parameter>man.endnotes.section.heading</parameter>
  819. parameter.</para>
  820. <note>
  821. <para>The endnotes list is also displayed (but without
  822. numbers) if the value of
  823. <parameter>man.endnotes.list.enabled</parameter> is
  824. non-zero.</para>
  825. </note>
  826. <para>If the value of <parameter>man.endnotes.are.numbered</parameter> is
  827. zero, numbering of endnotess is suppressed; only inline
  828. contents (if any) of the notesource are displayed inline.
  829. <important>
  830. <para>If you are thinking about disabling endnote numbering by setting
  831. the value of <parameter>man.endnotes.are.numbered</parameter> to zero,
  832. before you do so, first take some time to carefully
  833. consider the information needs and experiences of your users. The
  834. square-bracketed numbers displayed inline after notesources may seem
  835. obstrusive and aesthetically unpleasing<footnote><para>As far as notesources that are links, ytou might
  836. think it would be better to just display URLs for non-empty
  837. links inline, after their content, rather than displaying
  838. square-bracketed numbers all over the place. But it's not better. In
  839. fact, it's not even practical, because many (most) URLs for links
  840. are too long to be displayed inline. They end up overflowing the
  841. right margin. You can set a non-zero value for
  842. <parameter>man.break.after.slash</parameter> parameter to deal with
  843. that, but it could be argued that what you end up with is at least
  844. as ugly, and definitely more obstrusive, then having short
  845. square-bracketed numbers displayed inline.</para></footnote>,
  846. but in a text-only output format, the
  847. numbered-notesources/endnotes-listing mechanism is the only
  848. practical way to handle this kind of content.</para>
  849. <para>Also, users of &#8220;text based&#8221; browsers such as
  850. <command>lynx</command> will already be accustomed to seeing inline
  851. numbers for links. And various "man to html" applications, such as
  852. the widely used <command><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://users.actrix.gen.nz/michael/vhman2html.html">man2html</link></command> (<literal>VH-Man2html</literal>)
  853. application, can automatically turn URLs into "real" HTML hyperlinks
  854. in output. So leaving <parameter>man.endnotes.are.numbered</parameter>
  855. at its default (non-zero) value ensures that no information is
  856. lost in your man-page output. It just gets
  857. &#8220;rearranged&#8221;.</para>
  858. </important>
  859. </para>
  860. <para>The handling of empty links is not affected by this
  861. parameter. Empty links are handled simply by displaying their URLs
  862. inline. Empty links are never auto-numbered.</para>
  863. <para>If you disable endnotes numbering, you should probably also set
  864. <parameter>man.font.links</parameter> to an empty value (to
  865. disable font formatting for links.</para>
  866. </refsection>
  867. <refsection><info><title>Related Parameters</title></info>
  868. <para><parameter>man.endnotes.list.enabled</parameter>,
  869. <parameter>man.font.links</parameter></para>
  870. </refsection>
  871. </refentry>
  872. <refentry version="5.0" xml:id="man.base.url.for.relative.links">
  873. <refmeta>
  874. <refentrytitle>man.base.url.for.relative.links</refentrytitle>
  875. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  876. </refmeta>
  877. <refnamediv>
  878. <refname>man.base.url.for.relative.links</refname>
  879. <refpurpose>Specifies a base URL for relative links</refpurpose>
  880. </refnamediv>
  881. <refsynopsisdiv>
  882. <programlisting xml:id="man.base.url.for.relative.links.frag">&lt;xsl:param name="man.base.url.for.relative.links"&gt;[set $man.base.url.for.relative.links]/&lt;/xsl:param&gt;</programlisting>
  883. </refsynopsisdiv>
  884. <refsection><info><title>Description</title></info>
  885. <para>For any &#8220;notesource&#8221; listed in the auto-generated
  886. &#8220;NOTES&#8221; section of output man pages (which is generated when
  887. the value of the
  888. <parameter>man.endnotes.list.enabled</parameter> parameter
  889. is non-zero), if the notesource is a link source with a
  890. relative URI, the URI is displayed in output with the value
  891. of the
  892. <parameter>man.base.url.for.relative.links</parameter>
  893. parameter prepended to the value of the link URI.</para>
  894. <note>
  895. <para>A link source is an notesource that references an
  896. external resource:
  897. <itemizedlist>
  898. <listitem>
  899. <para>a <tag>ulink</tag> element with a <tag class="attribute">url</tag> attribute</para>
  900. </listitem>
  901. <listitem>
  902. <para>any element with an <tag class="attribute">xlink:href</tag> attribute</para>
  903. </listitem>
  904. <listitem>
  905. <para>an <tag>imagedata</tag>, <tag>audiodata</tag>, or
  906. <tag>videodata</tag> element</para>
  907. </listitem>
  908. </itemizedlist>
  909. </para>
  910. </note>
  911. <para>If you use relative URIs in link sources in your DocBook
  912. <tag>refentry</tag> source, and you leave
  913. <parameter>man.base.url.for.relative.links</parameter>
  914. unset, the relative links will appear &#8220;as is&#8221; in the &#8220;Notes&#8221;
  915. section of any man-page output generated from your source.
  916. That&#8217;s probably not what you want, because such relative
  917. links are only usable in the context of HTML output. So, to
  918. make the links meaningful and usable in the context of
  919. man-page output, set a value for
  920. <parameter>man.base.url.for.relative.links</parameter> that
  921. points to the online version of HTML output generated from
  922. your DocBook <tag>refentry</tag> source. For
  923. example:
  924. <programlisting>&lt;xsl:param name="man.base.url.for.relative.links"
  925. &gt;http://www.kernel.org/pub/software/scm/git/docs/&lt;/xsl:param&gt;</programlisting>
  926. </para>
  927. </refsection>
  928. <refsection><info><title>Related Parameters</title></info>
  929. <para><parameter>man.endnotes.list.enabled</parameter></para>
  930. </refsection>
  931. </refentry>
  932. </reference>
  933. <reference xml:id="lists">
  934. <title>Lists</title>
  935. <refentry version="5.0" xml:id="man.segtitle.suppress">
  936. <refmeta>
  937. <refentrytitle>man.segtitle.suppress</refentrytitle>
  938. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  939. </refmeta>
  940. <refnamediv>
  941. <refname>man.segtitle.suppress</refname>
  942. <refpurpose>Suppress display of segtitle contents?</refpurpose>
  943. </refnamediv>
  944. <refsynopsisdiv>
  945. <programlisting xml:id="man.segtitle.suppress.frag">
  946. &lt;xsl:param name="man.segtitle.suppress" select="0"&gt;&lt;/xsl:param&gt;</programlisting>
  947. </refsynopsisdiv>
  948. <refsection><info><title>Description</title></info>
  949. <para>If the value of <parameter>man.segtitle.suppress</parameter> is
  950. non-zero, then display of <tag>segtitle</tag> contents is
  951. suppressed in output.</para>
  952. </refsection>
  953. </refentry>
  954. </reference>
  955. <reference xml:id="charmap">
  956. <title>Character/string substitution</title>
  957. <refentry version="5.0" xml:id="man.charmap.enabled">
  958. <refmeta>
  959. <refentrytitle>man.charmap.enabled</refentrytitle>
  960. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  961. </refmeta>
  962. <refnamediv>
  963. <refname>man.charmap.enabled</refname>
  964. <refpurpose>Apply character map before final output?</refpurpose>
  965. </refnamediv>
  966. <refsynopsisdiv>
  967. <programlisting xml:id="man.charmap.enabled.frag">
  968. &lt;xsl:param name="man.charmap.enabled" select="1"&gt;&lt;/xsl:param&gt;
  969. </programlisting>
  970. </refsynopsisdiv>
  971. <refsection><info><title>Description</title></info>
  972. <para>If the value of the <parameter>man.charmap.enabled</parameter>
  973. parameter is non-zero, a "character map" is used to substitute certain
  974. Unicode symbols and special characters with appropriate roff/groff
  975. equivalents, just before writing each man-page file to the
  976. filesystem. If instead the value of
  977. <parameter>man.charmap.enabled</parameter> is zero, Unicode characters
  978. are passed through "as is".</para>
  979. <refsection><info><title>Details</title></info>
  980. <para>For converting certain Unicode symbols and special characters in
  981. UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
  982. equivalents in man-page output, the DocBook XSL Stylesheets
  983. distribution includes a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">roff character map</link> that is compliant with the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
  984. map</link> format as detailed in the XSLT 2.0 specification. The map
  985. contains more than 800 character mappings and can be considered the
  986. standard roff character map for the distribution.</para>
  987. <para>You can use the <parameter>man.charmap.uri</parameter>
  988. parameter to specify a URI for the location for an alternate roff
  989. character map to use in place of the standard roff character map
  990. provided in the distribution.</para>
  991. <para>You can also use a subset of a character map. For details,
  992. see the <parameter>man.charmap.use.subset</parameter>,
  993. <parameter>man.charmap.subset.profile</parameter>, and
  994. <parameter>man.charmap.subset.profile.english</parameter>
  995. parameters.</para>
  996. </refsection>
  997. </refsection>
  998. </refentry>
  999. <refentry version="5.0" xml:id="man.charmap.uri">
  1000. <refmeta>
  1001. <refentrytitle>man.charmap.uri</refentrytitle>
  1002. <refmiscinfo class="other" otherclass="datatype">uri</refmiscinfo>
  1003. </refmeta>
  1004. <refnamediv>
  1005. <refname>man.charmap.uri</refname>
  1006. <refpurpose>URI for custom roff character map</refpurpose>
  1007. </refnamediv>
  1008. <refsynopsisdiv>
  1009. <programlisting xml:id="man.charmap.uri.frag">
  1010. &lt;xsl:param name="man.charmap.uri"&gt;&lt;/xsl:param&gt;
  1011. </programlisting>
  1012. </refsynopsisdiv>
  1013. <refsection><info><title>Description</title></info>
  1014. <para>For converting certain Unicode symbols and special characters in
  1015. UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
  1016. equivalents in man-page output, the DocBook XSL Stylesheets
  1017. distribution includes an <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
  1018. map</link>. That character map can be considered the standard roff
  1019. character map for the distribution.</para>
  1020. <para>If the value of the <parameter>man.charmap.uri</parameter>
  1021. parameter is non-empty, that value is used as the URI for the location
  1022. for an alternate roff character map to use in place of the standard
  1023. roff character map provided in the distribution.</para>
  1024. <warning>
  1025. <para>Do not set a value for <parameter>man.charmap.uri</parameter>
  1026. unless you have a custom roff character map that differs from the
  1027. standard one provided in the distribution.</para>
  1028. </warning>
  1029. </refsection>
  1030. </refentry>
  1031. <refentry version="5.0" xml:id="man.charmap.use.subset">
  1032. <refmeta>
  1033. <refentrytitle>man.charmap.use.subset</refentrytitle>
  1034. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  1035. </refmeta>
  1036. <refnamediv>
  1037. <refname>man.charmap.use.subset</refname>
  1038. <refpurpose>Use subset of character map instead of full map?</refpurpose>
  1039. </refnamediv>
  1040. <refsynopsisdiv>
  1041. <programlisting xml:id="man.charmap.use.subset.frag">
  1042. &lt;xsl:param name="man.charmap.use.subset" select="1"&gt;&lt;/xsl:param&gt;
  1043. </programlisting>
  1044. </refsynopsisdiv>
  1045. <refsection><info><title>Description</title></info>
  1046. <para>If the value of the
  1047. <parameter>man.charmap.use.subset</parameter> parameter is non-zero,
  1048. a subset of the roff character map is used instead of the full roff
  1049. character map. The profile of the subset used is determined either
  1050. by the value of the
  1051. <parameter>man.charmap.subset.profile</parameter>
  1052. parameter (if the source is not in English) or the
  1053. <parameter>man.charmap.subset.profile.english</parameter>
  1054. parameter (if the source is in English).</para>
  1055. <note>
  1056. <para>You may want to experiment with setting a non-zero value of
  1057. <parameter>man.charmap.use.subset</parameter>, so that the full
  1058. character map is used. Depending on which XSLT engine you run,
  1059. setting a non-zero value for
  1060. <parameter>man.charmap.use.subset</parameter> may significantly
  1061. increase the time needed to process your documents. Or it may
  1062. not. For example, if you set it and run it with xsltproc, it seems
  1063. to dramatically increase processing time; on the other hand, if you
  1064. set it and run it with Saxon, it does not seem to increase
  1065. processing time nearly as much.</para>
  1066. <para>If processing time is not a important concern and/or you can
  1067. tolerate the increase in processing time imposed by using the full
  1068. character map, set <parameter>man.charmap.use.subset</parameter> to
  1069. zero.</para>
  1070. </note>
  1071. <refsection><info><title>Details</title></info>
  1072. <para>For converting certain Unicode symbols and special characters in
  1073. UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
  1074. equivalents in man-page output, the DocBook XSL Stylesheets
  1075. distribution includes a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">roff character map</link> that is compliant with the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
  1076. map</link> format as detailed in the XSLT 2.0 specification. The map
  1077. contains more than 800 character mappings and can be considered the
  1078. standard roff character map for the distribution.</para>
  1079. <note>
  1080. <para>You can use the <parameter>man.charmap.uri</parameter>
  1081. parameter to specify a URI for the location for an alternate roff
  1082. character map to use in place of the standard roff character map
  1083. provided in the distribution.</para>
  1084. </note>
  1085. <para>Because it is not terrifically efficient to use the standard
  1086. 800-character character map in full -- and for most (or all) users,
  1087. never necessary to use it in full -- the DocBook XSL Stylesheets
  1088. support a mechanism for using, within any given character map, a
  1089. subset of character mappings instead of the full set. You can use the
  1090. <parameter>man.charmap.subset.profile</parameter> or
  1091. <parameter>man.charmap.subset.profile.english</parameter>
  1092. parameter to tune the profile of that subset to use.</para>
  1093. </refsection>
  1094. </refsection>
  1095. </refentry>
  1096. <refentry version="5.0" xml:id="man.charmap.subset.profile">
  1097. <refmeta>
  1098. <refentrytitle>man.charmap.subset.profile</refentrytitle>
  1099. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  1100. </refmeta>
  1101. <refnamediv>
  1102. <refname>man.charmap.subset.profile</refname>
  1103. <refpurpose>Profile of character map subset</refpurpose>
  1104. </refnamediv>
  1105. <refsynopsisdiv>
  1106. <programlisting xml:id="man.charmap.subset.profile.frag">
  1107. &lt;xsl:param name="man.charmap.subset.profile"&gt;
  1108. @*[local-name() = 'block'] = 'Miscellaneous Technical' or
  1109. (@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
  1110. (@*[local-name() = 'class'] = 'symbols' or
  1111. @*[local-name() = 'class'] = 'letters')
  1112. ) or
  1113. @*[local-name() = 'block'] = 'Latin Extended-A'
  1114. or
  1115. (@*[local-name() = 'block'] = 'General Punctuation' and
  1116. (@*[local-name() = 'class'] = 'spaces' or
  1117. @*[local-name() = 'class'] = 'dashes' or
  1118. @*[local-name() = 'class'] = 'quotes' or
  1119. @*[local-name() = 'class'] = 'bullets'
  1120. )
  1121. ) or
  1122. @*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
  1123. @*[local-name() = 'name'] = 'WORD JOINER' or
  1124. @*[local-name() = 'name'] = 'SERVICE MARK' or
  1125. @*[local-name() = 'name'] = 'TRADE MARK SIGN' or
  1126. @*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
  1127. &lt;/xsl:param&gt;
  1128. </programlisting>
  1129. </refsynopsisdiv>
  1130. <refsection><info><title>Description</title></info>
  1131. <para>If the value of the
  1132. <parameter>man.charmap.use.subset</parameter> parameter is non-zero,
  1133. and your DocBook source is not written in English (that
  1134. is, if the <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute on the root element
  1135. in your DocBook source or on the first <tag>refentry</tag>
  1136. element in your source has a value other than
  1137. <literal>en</literal>), then the character-map subset specified
  1138. by the <parameter>man.charmap.subset.profile</parameter>
  1139. parameter is used instead of the full roff character map.</para>
  1140. <para>Otherwise, if the <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute on the root
  1141. element in your DocBook
  1142. source or on the first <tag>refentry</tag> element in your source
  1143. has the value <literal>en</literal> or if it has no <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute, then the character-map
  1144. subset specified by the
  1145. <parameter>man.charmap.subset.profile.english</parameter>
  1146. parameter is used instead of
  1147. <parameter>man.charmap.subset.profile</parameter>.</para>
  1148. <para>The difference between the two subsets is that
  1149. <parameter>man.charmap.subset.profile</parameter> provides
  1150. mappings for characters in Western European languages that are
  1151. not part of the Roman (English) alphabet (ASCII character set).</para>
  1152. <para>The value of <parameter>man.charmap.subset.profile</parameter>
  1153. is a string representing an XPath expression that matches attribute
  1154. names and values for <tag namespace="http://docbook.sf.net/xmlns/unichar/1.0">output-character</tag>
  1155. elements in the character map.</para>
  1156. <para>The attributes supported in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">standard roff character map included in the distribution</link> are:
  1157. <variablelist>
  1158. <varlistentry>
  1159. <term>character</term>
  1160. <listitem>
  1161. <simpara>a raw Unicode character or numeric Unicode
  1162. character-entity value (either in decimal or hex); all
  1163. characters have this attribute</simpara>
  1164. </listitem>
  1165. </varlistentry>
  1166. <varlistentry>
  1167. <term>name</term>
  1168. <listitem>
  1169. <simpara>a standard full/long ISO/Unicode character name (e.g.,
  1170. "OHM SIGN"); all characters have this attribute</simpara>
  1171. </listitem>
  1172. </varlistentry>
  1173. <varlistentry>
  1174. <term>block</term>
  1175. <listitem>
  1176. <simpara>a standard Unicode "block" name (e.g., "General
  1177. Punctuation"); all characters have this attribute. For the full
  1178. list of Unicode block names supported in the standard roff
  1179. character map, see <xref linkend="BlocksAndClasses"/>.</simpara>
  1180. </listitem>
  1181. </varlistentry>
  1182. <varlistentry>
  1183. <term>class</term>
  1184. <listitem>
  1185. <simpara>a class of characters (e.g., "spaces"). Not all
  1186. characters have this attribute; currently, it is used only with
  1187. certain characters within the "C1 Controls And Latin-1
  1188. Supplement" and "General Punctuation" blocks. For details, see
  1189. <xref linkend="BlocksAndClasses"/>.</simpara>
  1190. </listitem>
  1191. </varlistentry>
  1192. <varlistentry>
  1193. <term>entity</term>
  1194. <listitem>
  1195. <simpara>an ISO entity name (e.g., "ohm"); not all characters
  1196. have this attribute, because not all characters have ISO entity
  1197. names; for example, of the 800 or so characters in the standard
  1198. roff character map included in the distribution, only around 300
  1199. have ISO entity names.
  1200. </simpara>
  1201. </listitem>
  1202. </varlistentry>
  1203. <varlistentry>
  1204. <term>string</term>
  1205. <listitem>
  1206. <simpara>a string representing an roff/groff escape-code (with
  1207. "@esc@" used in place of the backslash), or a simple ASCII
  1208. string; all characters in the roff character map have this
  1209. attribute</simpara>
  1210. </listitem>
  1211. </varlistentry>
  1212. </variablelist>
  1213. </para>
  1214. <para>The value of <parameter>man.charmap.subset.profile</parameter>
  1215. is evaluated as an XPath expression at run-time to select a portion of
  1216. the roff character map to use. You can tune the subset used by adding
  1217. or removing parts. For example, if you need to use a wide range of
  1218. mathematical operators in a document, and you want to have them
  1219. converted into roff markup properly, you might add the following:
  1220. <literallayout class="monospaced"> @*[local-name() = 'block'] ='MathematicalOperators' </literallayout>
  1221. That will cause a additional set of around 67 additional "math"
  1222. characters to be converted into roff markup. </para>
  1223. <note>
  1224. <para>Depending on which XSLT engine you use, either the EXSLT
  1225. <function>dyn:evaluate</function> extension function (for xsltproc or
  1226. Xalan) or <function>saxon:evaluate</function> extension function (for
  1227. Saxon) are used to dynamically evaluate the value of
  1228. <parameter>man.charmap.subset.profile</parameter> at run-time. If you
  1229. don't use xsltproc, Saxon, Xalan -- or some other XSLT engine that
  1230. supports <function>dyn:evaluate</function> -- you must either set the
  1231. value of the <parameter>man.charmap.use.subset</parameter> parameter
  1232. to zero and process your documents using the full character map
  1233. instead, or set the value of the
  1234. <parameter>man.charmap.enabled</parameter> parameter to zero instead
  1235. (so that character-map processing is disabled completely.</para>
  1236. </note>
  1237. <para>An alternative to using
  1238. <parameter>man.charmap.subset.profile</parameter> is to create your
  1239. own custom character map, and set the value of
  1240. <parameter>man.charmap.uri</parameter> to the URI/filename for
  1241. that. If you use a custom character map, you will probably want to
  1242. include in it just the characters you want to use, and so you will
  1243. most likely also want to set the value of
  1244. <parameter>man.charmap.use.subset</parameter> to zero.</para>
  1245. <para>You can create a
  1246. custom character map by making a copy of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">standard roff character map</link> provided in the distribution, and
  1247. then adding to, changing, and/or deleting from that.</para>
  1248. <caution>
  1249. <para>If you author your DocBook XML source in UTF-8 or UTF-16
  1250. encoding and aren't sure what OSes or environments your man-page
  1251. output might end up being viewed on, and not sure what version of
  1252. nroff/groff those environments might have, you should be careful about
  1253. what Unicode symbols and special characters you use in your source and
  1254. what parts you add to the value of
  1255. <parameter>man.charmap.subset.profile</parameter>.</para>
  1256. <para>Many of the escape codes used are specific to groff and using
  1257. them may not provide the expected output on an OS or environment that
  1258. uses nroff instead of groff.</para>
  1259. <para>On the other hand, if you intend for your man-page output to be
  1260. viewed only on modern systems (for example, GNU/Linux systems, FreeBSD
  1261. systems, or Cygwin environments) that have a good, up-to-date groff,
  1262. then you can safely include a wide range of Unicode symbols and
  1263. special characters in your UTF-8 or UTF-16 encoded DocBook XML source
  1264. and add any of the supported Unicode block names to the value of
  1265. <parameter>man.charmap.subset.profile</parameter>.</para>
  1266. </caution>
  1267. <para>For other details, see the documentation for the
  1268. <parameter>man.charmap.use.subset</parameter> parameter.</para>
  1269. <refsection xml:id="BlocksAndClasses"><info><title>Supported Unicode block names and "class" values</title></info>
  1270. <para>Below is the full list of Unicode block names and "class"
  1271. values supported in the standard roff stylesheet provided in the
  1272. distribution, along with a description of which codepoints from the
  1273. Unicode range corresponding to that block name or block/class
  1274. combination are supported.</para>
  1275. <itemizedlist>
  1276. <listitem>
  1277. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=C1%20Controls%20and%20Latin-1%20Supplement%20(Latin-1%20Supplement)">C1 Controls And Latin-1 Supplement (Latin-1 Supplement)</link> (x00a0 to x00ff)
  1278. <itemizedlist><info><title>class values</title></info>
  1279. <listitem>
  1280. <para>symbols</para>
  1281. </listitem>
  1282. <listitem>
  1283. <para>letters</para>
  1284. </listitem>
  1285. </itemizedlist></para>
  1286. </listitem>
  1287. <listitem>
  1288. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Latin%20Extended-A">Latin Extended-A</link> (x0100 to x017f, partial)</para>
  1289. </listitem>
  1290. <listitem>
  1291. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Spacing%20Modifier%20Letters">Spacing Modifier Letters</link> (x02b0 to x02ee, partial)</para>
  1292. </listitem>
  1293. <listitem>
  1294. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Greek%20and%20Coptic">Greek and Coptic</link> (x0370 to x03ff, partial)</para>
  1295. </listitem>
  1296. <listitem>
  1297. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=General%20Punctuation">General Punctuation</link> (x2000 to x206f, partial)
  1298. <itemizedlist><info><title>class values</title></info>
  1299. <listitem>
  1300. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8192&amp;end=8203">spaces</link></para>
  1301. </listitem>
  1302. <listitem>
  1303. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8208&amp;end=8213">dashes</link></para>
  1304. </listitem>
  1305. <listitem>
  1306. <para>quotes</para>
  1307. </listitem>
  1308. <listitem>
  1309. <para>daggers</para>
  1310. </listitem>
  1311. <listitem>
  1312. <para>bullets</para>
  1313. </listitem>
  1314. <listitem>
  1315. <para>leaders</para>
  1316. </listitem>
  1317. <listitem>
  1318. <para>primes</para>
  1319. </listitem>
  1320. </itemizedlist>
  1321. </para>
  1322. </listitem>
  1323. <listitem>
  1324. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Superscripts%20and%20Subscripts">Superscripts and Subscripts</link> (x2070 to x209f)</para>
  1325. </listitem>
  1326. <listitem>
  1327. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Currency%20Symbols">Currency Symbols</link> (x20a0 to x20b1)</para>
  1328. </listitem>
  1329. <listitem>
  1330. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Letterlike%20Symbols">Letterlike Symbols</link> (x2100 to x214b)</para>
  1331. </listitem>
  1332. <listitem>
  1333. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Number%20Forms">Number Forms</link> (x2150 to x218f)</para>
  1334. </listitem>
  1335. <listitem>
  1336. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Arrows">Arrows</link> (x2190 to x21ff, partial)</para>
  1337. </listitem>
  1338. <listitem>
  1339. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Mathematical%20Operators">Mathematical Operators</link> (x2200 to x22ff, partial)</para>
  1340. </listitem>
  1341. <listitem>
  1342. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Control%20Pictures">Control Pictures</link> (x2400 to x243f)</para>
  1343. </listitem>
  1344. <listitem>
  1345. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Enclosed%20Alphanumerics">Enclosed Alphanumerics</link> (x2460 to x24ff)</para>
  1346. </listitem>
  1347. <listitem>
  1348. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Geometric%20Shapes">Geometric Shapes</link> (x25a0 to x25f7, partial)</para>
  1349. </listitem>
  1350. <listitem>
  1351. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Miscellaneous%20Symbols">Miscellaneous Symbols</link> (x2600 to x26ff, partial)</para>
  1352. </listitem>
  1353. <listitem>
  1354. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Dingbats">Dingbats</link> (x2700 to x27be, partial)</para>
  1355. </listitem>
  1356. <listitem>
  1357. <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Alphabetic%20Presentation%20Forms">Alphabetic Presentation Forms</link> (xfb00 to xfb04 only)</para>
  1358. </listitem>
  1359. </itemizedlist>
  1360. </refsection>
  1361. </refsection>
  1362. </refentry>
  1363. <refentry version="5.0" xml:id="man.charmap.subset.profile.english">
  1364. <refmeta>
  1365. <refentrytitle>man.charmap.subset.profile.english</refentrytitle>
  1366. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  1367. </refmeta>
  1368. <refnamediv>
  1369. <refname>man.charmap.subset.profile.english</refname>
  1370. <refpurpose>Profile of character map subset</refpurpose>
  1371. </refnamediv>
  1372. <refsynopsisdiv>
  1373. <programlisting xml:id="man.charmap.subset.profile.english.frag">
  1374. &lt;xsl:param name="man.charmap.subset.profile.english"&gt;
  1375. @*[local-name() = 'block'] = 'Miscellaneous Technical' or
  1376. (@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
  1377. @*[local-name() = 'class'] = 'symbols')
  1378. or
  1379. (@*[local-name() = 'block'] = 'General Punctuation' and
  1380. (@*[local-name() = 'class'] = 'spaces' or
  1381. @*[local-name() = 'class'] = 'dashes' or
  1382. @*[local-name() = 'class'] = 'quotes' or
  1383. @*[local-name() = 'class'] = 'bullets'
  1384. )
  1385. ) or
  1386. @*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
  1387. @*[local-name() = 'name'] = 'WORD JOINER' or
  1388. @*[local-name() = 'name'] = 'SERVICE MARK' or
  1389. @*[local-name() = 'name'] = 'TRADE MARK SIGN' or
  1390. @*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
  1391. &lt;/xsl:param&gt;
  1392. </programlisting>
  1393. </refsynopsisdiv>
  1394. <refsection><info><title>Description</title></info>
  1395. <para>If the value of the
  1396. <parameter>man.charmap.use.subset</parameter> parameter is
  1397. non-zero, and your DocBook source is written in English (that
  1398. is, if its <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute on the root element
  1399. in your DocBook source or on the first <tag>refentry</tag>
  1400. element in your source has the value <literal>en</literal> or if
  1401. it has no <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute), then the
  1402. character-map subset specified by the
  1403. <parameter>man.charmap.subset.profile.english</parameter>
  1404. parameter is used instead of the full roff character map.</para>
  1405. <para>Otherwise, if the <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute
  1406. on the root element in your DocBook source or on the first
  1407. <tag>refentry</tag> element in your source has a value other
  1408. than <literal>en</literal>, then the character-map subset
  1409. specified by the
  1410. <parameter>man.charmap.subset.profile</parameter> parameter is
  1411. used instead of
  1412. <parameter>man.charmap.subset.profile.english</parameter>.</para>
  1413. <para>The difference between the two subsets is that
  1414. <parameter>man.charmap.subset.profile</parameter> provides
  1415. mappings for characters in Western European languages that are
  1416. not part of the Roman (English) alphabet (ASCII character set).</para>
  1417. <para>The value of <parameter>man.charmap.subset.profile.english</parameter>
  1418. is a string representing an XPath expression that matches attribute
  1419. names and values for <tag namespace="http://docbook.sf.net/xmlns/unichar/1.0">output-character</tag> elements in the character map.</para>
  1420. <para>For other details, see the documentation for the
  1421. <parameter>man.charmap.subset.profile.english</parameter> and
  1422. <parameter>man.charmap.use.subset</parameter> parameters.</para>
  1423. </refsection>
  1424. </refentry>
  1425. <refentry version="5.0" xml:id="man.string.subst.map.local.pre">
  1426. <refmeta>
  1427. <refentrytitle>man.string.subst.map.local.pre</refentrytitle>
  1428. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  1429. </refmeta>
  1430. <refnamediv>
  1431. <refname>man.string.subst.map.local.pre</refname>
  1432. <refpurpose>Specifies &#8220;local&#8221; string substitutions</refpurpose>
  1433. </refnamediv>
  1434. <refsynopsisdiv>
  1435. <programlisting xml:id="man.string.subst.map.local.pre.frag">
  1436. &lt;xsl:param name="man.string.subst.map.local.pre"&gt;&lt;/xsl:param&gt;
  1437. </programlisting>
  1438. </refsynopsisdiv>
  1439. <refsection><info><title>Description</title></info>
  1440. <para>Use the <parameter>man.string.subst.map.local.pre</parameter>
  1441. parameter to specify any &#8220;local&#8221; string substitutions to perform over
  1442. the entire roff source for each man page <emphasis>before</emphasis>
  1443. performing the string substitutions specified by the <parameter>man.string.subst.map</parameter> parameter.</para>
  1444. <para>For details about the format of this parameter, see the
  1445. documentation for the <parameter>man.string.subst.map</parameter>
  1446. parameter.</para>
  1447. </refsection>
  1448. </refentry>
  1449. <refentry version="5.0" xml:id="man.string.subst.map">
  1450. <refmeta>
  1451. <refentrytitle>man.string.subst.map</refentrytitle>
  1452. <refmiscinfo class="other" otherclass="datatype">rtf</refmiscinfo>
  1453. </refmeta>
  1454. <refnamediv>
  1455. <refname>man.string.subst.map</refname>
  1456. <refpurpose>Specifies a set of string substitutions</refpurpose>
  1457. </refnamediv>
  1458. <refsynopsisdiv>
  1459. <programlisting xml:id="man.string.subst.map.frag">
  1460. &lt;xsl:param name="man.string.subst.map"&gt;
  1461. &lt;!-- * remove no-break marker at beginning of line (stylesheet artifact) --&gt;
  1462. &lt;ss:substitution oldstring="&#9618;&#9600;" newstring="&#9618;"&gt;&lt;/ss:substitution&gt;
  1463. &lt;!-- * replace U+2580 no-break marker (stylesheet-added) w/ no-break space --&gt;
  1464. &lt;ss:substitution oldstring="&#9600;" newstring="\ "&gt;&lt;/ss:substitution&gt;
  1465. &lt;!-- ==================================================================== --&gt;
  1466. &lt;!-- * squeeze multiple newlines before a roff request --&gt;
  1467. &lt;ss:substitution oldstring="
  1468. ." newstring="
  1469. ."&gt;&lt;/ss:substitution&gt;
  1470. &lt;!-- * remove any .sp instances that directly precede a .PP --&gt;
  1471. &lt;ss:substitution oldstring=".sp
  1472. .PP" newstring=".PP"&gt;&lt;/ss:substitution&gt;
  1473. &lt;!-- * remove any .sp instances that directly follow a .PP --&gt;
  1474. &lt;ss:substitution oldstring=".sp
  1475. .sp" newstring=".sp"&gt;&lt;/ss:substitution&gt;
  1476. &lt;!-- * squeeze multiple .sp instances into a single .sp--&gt;
  1477. &lt;ss:substitution oldstring=".PP
  1478. .sp" newstring=".PP"&gt;&lt;/ss:substitution&gt;
  1479. &lt;!-- * squeeze multiple newlines after start of no-fill (verbatim) env. --&gt;
  1480. &lt;ss:substitution oldstring=".nf
  1481. " newstring=".nf
  1482. "&gt;&lt;/ss:substitution&gt;
  1483. &lt;!-- * squeeze multiple newlines after REstoring margin --&gt;
  1484. &lt;ss:substitution oldstring=".RE
  1485. " newstring=".RE
  1486. "&gt;&lt;/ss:substitution&gt;
  1487. &lt;!-- * U+2591 is a marker we add before and after every Parameter in --&gt;
  1488. &lt;!-- * Funcprototype output --&gt;
  1489. &lt;ss:substitution oldstring="&#9617;" newstring=" "&gt;&lt;/ss:substitution&gt;
  1490. &lt;!-- * U+2592 is a marker we add for the newline before output of &lt;sbr&gt;; --&gt;
  1491. &lt;ss:substitution oldstring="&#9618;" newstring="
  1492. "&gt;&lt;/ss:substitution&gt;
  1493. &lt;!-- * --&gt;
  1494. &lt;!-- * Now deal with some other characters that are added by the --&gt;
  1495. &lt;!-- * stylesheets during processing. --&gt;
  1496. &lt;!-- * --&gt;
  1497. &lt;!-- * bullet --&gt;
  1498. &lt;ss:substitution oldstring="&#8226;" newstring="\(bu"&gt;&lt;/ss:substitution&gt;
  1499. &lt;!-- * left double quote --&gt;
  1500. &lt;ss:substitution oldstring="&#8220;" newstring="\(lq"&gt;&lt;/ss:substitution&gt;
  1501. &lt;!-- * right double quote --&gt;
  1502. &lt;ss:substitution oldstring="&#8221;" newstring="\(rq"&gt;&lt;/ss:substitution&gt;
  1503. &lt;!-- * left single quote --&gt;
  1504. &lt;ss:substitution oldstring="&#8216;" newstring="\(oq"&gt;&lt;/ss:substitution&gt;
  1505. &lt;!-- * right single quote --&gt;
  1506. &lt;ss:substitution oldstring="&#8217;" newstring="\(cq"&gt;&lt;/ss:substitution&gt;
  1507. &lt;!-- * copyright sign --&gt;
  1508. &lt;ss:substitution oldstring="&#169;" newstring="\(co"&gt;&lt;/ss:substitution&gt;
  1509. &lt;!-- * registered sign --&gt;
  1510. &lt;ss:substitution oldstring="&#174;" newstring="\(rg"&gt;&lt;/ss:substitution&gt;
  1511. &lt;!-- * ...servicemark... --&gt;
  1512. &lt;!-- * There is no groff equivalent for it. --&gt;
  1513. &lt;ss:substitution oldstring="&#8480;" newstring="(SM)"&gt;&lt;/ss:substitution&gt;
  1514. &lt;!-- * ...trademark... --&gt;
  1515. &lt;!-- * We don't do "\(tm" because for console output, --&gt;
  1516. &lt;!-- * groff just renders that as "tm"; that is: --&gt;
  1517. &lt;!-- * --&gt;
  1518. &lt;!-- * Product&amp;#x2122; -&gt; Producttm --&gt;
  1519. &lt;!-- * --&gt;
  1520. &lt;!-- * So we just make it to "(TM)" instead; thus: --&gt;
  1521. &lt;!-- * --&gt;
  1522. &lt;!-- * Product&amp;#x2122; -&gt; Product(TM) --&gt;
  1523. &lt;ss:substitution oldstring="&#8482;" newstring="(TM)"&gt;&lt;/ss:substitution&gt;
  1524. &lt;/xsl:param&gt;
  1525. </programlisting>
  1526. </refsynopsisdiv>
  1527. <refsection><info><title>Description</title></info>
  1528. <para>The <parameter>man.string.subst.map</parameter> parameter
  1529. contains <link linkend="map">a map</link> that specifies a set of
  1530. string substitutions to perform over the entire roff source for each
  1531. man page, either just before generating final man-page output (that
  1532. is, before writing man-page files to disk) or, if the value of the
  1533. <parameter>man.charmap.enabled</parameter> parameter is non-zero,
  1534. before applying the roff character map.</para>
  1535. <para>You can use <parameter>man.string.subst.map</parameter> as a
  1536. &#8220;lightweight&#8221; character map to perform &#8220;essential&#8221; substitutions --
  1537. that is, substitutions that are <emphasis>always</emphasis> performed,
  1538. even if the value of the <parameter>man.charmap.enabled</parameter>
  1539. parameter is zero. For example, you can use it to replace quotation
  1540. marks or other special characters that are generated by the DocBook
  1541. XSL stylesheets for a particular locale setting (as opposed to those
  1542. characters that are actually in source XML documents), or to replace
  1543. any special characters that may be automatically generated by a
  1544. particular customization of the DocBook XSL stylesheets.</para>
  1545. <warning>
  1546. <para>Do you not change value of the
  1547. <parameter>man.string.subst.map</parameter> parameter unless you are
  1548. sure what you are doing. First consider adding your
  1549. string-substitution mappings to either or both of the following
  1550. parameters:
  1551. <variablelist>
  1552. <varlistentry>
  1553. <term><parameter>man.string.subst.map.local.pre</parameter></term>
  1554. <listitem><para>applied before
  1555. <parameter>man.string.subst.map</parameter></para></listitem>
  1556. </varlistentry>
  1557. <varlistentry>
  1558. <term><parameter>man.string.subst.map.local.post</parameter></term>
  1559. <listitem><para>applied after
  1560. <parameter>man.string.subst.map</parameter></para></listitem>
  1561. </varlistentry>
  1562. </variablelist>
  1563. By default, both of those parameters contain no
  1564. string substitutions. They are intended as a means for you to
  1565. specify your own local string-substitution mappings.</para>
  1566. <para>If you remove any of default mappings from the value of the
  1567. <parameter>man.string.subst.map</parameter> parameter, you are
  1568. likely to end up with broken output. And be very careful about adding
  1569. anything to it; it&#8217;s used for doing string substitution over the
  1570. entire roff source of each man page &#8211; it causes target strings to be
  1571. replaced in roff requests and escapes, not just in the visible
  1572. contents of the page.</para>
  1573. </warning>
  1574. <refsection xml:id="map">
  1575. <info>
  1576. <title>Contents of the substitution map</title>
  1577. </info>
  1578. <para>The string-substitution map contains one or more
  1579. <tag>ss:substitution</tag> elements, each of which has two
  1580. attributes:
  1581. <variablelist>
  1582. <varlistentry>
  1583. <term>oldstring</term>
  1584. <listitem>
  1585. <simpara>string to replace</simpara>
  1586. </listitem>
  1587. </varlistentry>
  1588. <varlistentry>
  1589. <term>newstring</term>
  1590. <listitem>
  1591. <simpara>string with which to replace <tag class="attribute">oldstring</tag></simpara>
  1592. </listitem>
  1593. </varlistentry>
  1594. </variablelist>
  1595. It may also include XML comments (that is, delimited with
  1596. "<literal>&lt;!--</literal>" and "<literal>--&gt;</literal>").
  1597. </para>
  1598. </refsection>
  1599. </refsection>
  1600. </refentry>
  1601. <refentry version="5.0" xml:id="man.string.subst.map.local.post">
  1602. <refmeta>
  1603. <refentrytitle>man.string.subst.map.local.post</refentrytitle>
  1604. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  1605. </refmeta>
  1606. <refnamediv>
  1607. <refname>man.string.subst.map.local.post</refname>
  1608. <refpurpose>Specifies &#8220;local&#8221; string substitutions</refpurpose>
  1609. </refnamediv>
  1610. <refsynopsisdiv>
  1611. <programlisting xml:id="man.string.subst.map.local.post.frag">
  1612. &lt;xsl:param name="man.string.subst.map.local.post"&gt;&lt;/xsl:param&gt;
  1613. </programlisting>
  1614. </refsynopsisdiv>
  1615. <refsection><info><title>Description</title></info>
  1616. <para>Use the <parameter>man.string.subst.map.local.post</parameter>
  1617. parameter to specify any &#8220;local&#8221; string substitutions to perform over
  1618. the entire roff source for each man page <emphasis>after</emphasis>
  1619. performing the string substitutions specified by the <parameter>man.string.subst.map</parameter> parameter.</para>
  1620. <para>For details about the format of this parameter, see the
  1621. documentation for the <parameter>man.string.subst.map</parameter>
  1622. parameter.</para>
  1623. </refsection>
  1624. </refentry>
  1625. </reference>
  1626. <reference xml:id="refmeta">
  1627. <title>Refentry metadata gathering</title>
  1628. <refentry version="5.0" xml:id="refentry.meta.get.quietly">
  1629. <refmeta>
  1630. <refentrytitle>refentry.meta.get.quietly</refentrytitle>
  1631. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  1632. </refmeta>
  1633. <refnamediv>
  1634. <refname>refentry.meta.get.quietly</refname>
  1635. <refpurpose>Suppress notes and warnings when gathering refentry metadata?</refpurpose>
  1636. </refnamediv>
  1637. <refsynopsisdiv>
  1638. <programlisting xml:id="refentry.meta.get.quietly.frag">
  1639. &lt;xsl:param name="refentry.meta.get.quietly" select="0"&gt;&lt;/xsl:param&gt;
  1640. </programlisting>
  1641. </refsynopsisdiv>
  1642. <refsection><info><title>Description</title></info>
  1643. <para>If zero (the default), notes and warnings about &#8220;missing&#8221; markup
  1644. are generated during gathering of refentry metadata. If non-zero, the
  1645. metadata is gathered &#8220;quietly&#8221; -- that is, the notes and warnings are
  1646. suppressed.</para>
  1647. <tip>
  1648. <para>If you are processing a large amount of <tag>refentry</tag>
  1649. content, you may be able to speed up processing significantly by
  1650. setting a non-zero value for
  1651. <parameter>refentry.meta.get.quietly</parameter>.</para>
  1652. </tip>
  1653. </refsection>
  1654. </refentry>
  1655. <refentry version="5.0" xml:id="refentry.date.profile">
  1656. <refmeta>
  1657. <refentrytitle>refentry.date.profile</refentrytitle>
  1658. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  1659. </refmeta>
  1660. <refnamediv>
  1661. <refname>refentry.date.profile</refname>
  1662. <refpurpose>Specifies profile for refentry "date" data</refpurpose>
  1663. </refnamediv>
  1664. <refsynopsisdiv>
  1665. <programlisting xml:id="refentry.date.profile.frag">
  1666. &lt;xsl:param name="refentry.date.profile"&gt;
  1667. (($info[//date])[last()]/date)[1]|
  1668. (($info[//pubdate])[last()]/pubdate)[1]
  1669. &lt;/xsl:param&gt;
  1670. </programlisting>
  1671. </refsynopsisdiv>
  1672. <refsection><info><title>Description</title></info>
  1673. <para>The value of <parameter>refentry.date.profile</parameter> is a
  1674. string representing an XPath expression. It is evaluated at run-time
  1675. and used only if <parameter>refentry.date.profile.enabled</parameter>
  1676. is non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering
  1677. logic "hard coded" into the stylesheets is used.</para>
  1678. <para> The <literal>man(7)</literal> man page describes this content
  1679. as "the date of the last revision". In man pages, it is the content
  1680. that is usually displayed in the center footer.</para>
  1681. </refsection>
  1682. </refentry>
  1683. <refentry version="5.0" xml:id="refentry.date.profile.enabled">
  1684. <refmeta>
  1685. <refentrytitle>refentry.date.profile.enabled</refentrytitle>
  1686. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  1687. </refmeta>
  1688. <refnamediv>
  1689. <refname>refentry.date.profile.enabled</refname>
  1690. <refpurpose>Enable refentry "date" profiling?</refpurpose>
  1691. </refnamediv>
  1692. <refsynopsisdiv>
  1693. <programlisting xml:id="refentry.date.profile.enabled.frag">
  1694. &lt;xsl:param name="refentry.date.profile.enabled"&gt;0&lt;/xsl:param&gt;</programlisting>
  1695. </refsynopsisdiv>
  1696. <refsection><info><title>Description</title></info>
  1697. <para>If the value of
  1698. <parameter>refentry.date.profile.enabled</parameter> is non-zero, then
  1699. during <tag>refentry</tag> metadata gathering, the info profile
  1700. specified by the customizable
  1701. <parameter>refentry.date.profile</parameter> parameter is used.</para>
  1702. <para>If instead the value of
  1703. <parameter>refentry.date.profile.enabled</parameter> is zero (the
  1704. default), then "hard coded" logic within the DocBook XSL stylesheets
  1705. is used for gathering <tag>refentry</tag> "date" data.</para>
  1706. <para>If you find that the default <tag>refentry</tag>
  1707. metadata-gathering behavior is causing incorrect "date" data to show
  1708. up in your output, then consider setting a non-zero value for
  1709. <parameter>refentry.date.profile.enabled</parameter> and adjusting the
  1710. value of <parameter>refentry.date.profile</parameter> to cause correct
  1711. data to be gathered. </para>
  1712. <para>Note that the terms "source" and "date" have special meanings in
  1713. this context. For details, see the documentation for the
  1714. <parameter>refentry.date.profile</parameter> parameter.</para>
  1715. </refsection>
  1716. </refentry>
  1717. <refentry version="5.0" xml:id="refentry.manual.profile">
  1718. <refmeta>
  1719. <refentrytitle>refentry.manual.profile</refentrytitle>
  1720. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  1721. </refmeta>
  1722. <refnamediv>
  1723. <refname>refentry.manual.profile</refname>
  1724. <refpurpose>Specifies profile for refentry "manual" data</refpurpose>
  1725. </refnamediv>
  1726. <refsynopsisdiv>
  1727. <programlisting xml:id="refentry.manual.profile.frag">
  1728. &lt;xsl:param name="refentry.manual.profile"&gt;
  1729. (($info[//title])[last()]/title)[1]|
  1730. ../title/node()
  1731. &lt;/xsl:param&gt;
  1732. </programlisting>
  1733. </refsynopsisdiv>
  1734. <refsection><info><title>Description</title></info>
  1735. <para>The value of <parameter>refentry.manual.profile</parameter> is
  1736. a string representing an XPath expression. It is evaluated at
  1737. run-time and used only if
  1738. <parameter>refentry.manual.profile.enabled</parameter> is
  1739. non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
  1740. "hard coded" into the stylesheets is used.</para>
  1741. <para>In man pages, this content is usually displayed in the middle of
  1742. the header of the page. The <literal>man(7)</literal> man page
  1743. describes this as "the title of the manual (e.g., <citetitle>Linux
  1744. Programmer's Manual</citetitle>)". Here are some examples from
  1745. existing man pages:
  1746. <itemizedlist>
  1747. <listitem>
  1748. <para><citetitle>dpkg utilities</citetitle>
  1749. (<command>dpkg-name</command>)</para>
  1750. </listitem>
  1751. <listitem>
  1752. <para><citetitle>User Contributed Perl Documentation</citetitle>
  1753. (<command>GET</command>)</para>
  1754. </listitem>
  1755. <listitem>
  1756. <para><citetitle>GNU Development Tools</citetitle>
  1757. (<command>ld</command>)</para>
  1758. </listitem>
  1759. <listitem>
  1760. <para><citetitle>Emperor Norton Utilities</citetitle>
  1761. (<command>ddate</command>)</para>
  1762. </listitem>
  1763. <listitem>
  1764. <para><citetitle>Debian GNU/Linux manual</citetitle>
  1765. (<command>faked</command>)</para>
  1766. </listitem>
  1767. <listitem>
  1768. <para><citetitle>GIMP Manual Pages</citetitle>
  1769. (<command>gimp</command>)</para>
  1770. </listitem>
  1771. <listitem>
  1772. <para><citetitle>KDOC Documentation System</citetitle>
  1773. (<command>qt2kdoc</command>)</para>
  1774. </listitem>
  1775. </itemizedlist>
  1776. </para>
  1777. </refsection>
  1778. </refentry>
  1779. <refentry version="5.0" xml:id="refentry.manual.profile.enabled">
  1780. <refmeta>
  1781. <refentrytitle>refentry.manual.profile.enabled</refentrytitle>
  1782. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  1783. </refmeta>
  1784. <refnamediv>
  1785. <refname>refentry.manual.profile.enabled</refname>
  1786. <refpurpose>Enable refentry "manual" profiling?</refpurpose>
  1787. </refnamediv>
  1788. <refsynopsisdiv>
  1789. <programlisting xml:id="refentry.manual.profile.enabled.frag">
  1790. &lt;xsl:param name="refentry.manual.profile.enabled"&gt;0&lt;/xsl:param&gt;</programlisting>
  1791. </refsynopsisdiv>
  1792. <refsection><info><title>Description</title></info>
  1793. <para>If the value of
  1794. <parameter>refentry.manual.profile.enabled</parameter> is
  1795. non-zero, then during <tag>refentry</tag> metadata gathering, the info
  1796. profile specified by the customizable
  1797. <parameter>refentry.manual.profile</parameter> parameter is
  1798. used.</para>
  1799. <para>If instead the value of
  1800. <parameter>refentry.manual.profile.enabled</parameter> is zero (the
  1801. default), then "hard coded" logic within the DocBook XSL stylesheets
  1802. is used for gathering <tag>refentry</tag> "manual" data.</para>
  1803. <para>If you find that the default <tag>refentry</tag>
  1804. metadata-gathering behavior is causing incorrect "manual" data to show
  1805. up in your output, then consider setting a non-zero value for
  1806. <parameter>refentry.manual.profile.enabled</parameter> and adjusting
  1807. the value of <parameter>refentry.manual.profile</parameter> to cause
  1808. correct data to be gathered. </para>
  1809. <para>Note that the term "manual" has a special meanings in this
  1810. context. For details, see the documentation for the
  1811. <parameter>refentry.manual.profile</parameter> parameter.</para>
  1812. </refsection>
  1813. </refentry>
  1814. <refentry version="5.0" xml:id="refentry.source.name.suppress">
  1815. <refmeta>
  1816. <refentrytitle>refentry.source.name.suppress</refentrytitle>
  1817. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  1818. </refmeta>
  1819. <refnamediv>
  1820. <refname>refentry.source.name.suppress</refname>
  1821. <refpurpose>Suppress "name" part of refentry "source" contents?</refpurpose>
  1822. </refnamediv>
  1823. <refsynopsisdiv>
  1824. <programlisting xml:id="refentry.source.name.suppress.frag">
  1825. &lt;xsl:param name="refentry.source.name.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
  1826. </refsynopsisdiv>
  1827. <refsection><info><title>Description</title></info>
  1828. <para>If the value of
  1829. <parameter>refentry.source.name.suppress</parameter> is non-zero, then
  1830. during <tag>refentry</tag> metadata gathering, no "source name" data
  1831. is added to the <tag>refentry</tag> "source" contents. Instead (unless
  1832. <parameter>refentry.version.suppress</parameter> is also non-zero),
  1833. only "version" data is added to the "source" contents.</para>
  1834. <para>If you find that the <tag>refentry</tag> metadata gathering
  1835. mechanism is causing unwanted "source name" data to show up in your
  1836. output -- for example, in the footer (or possibly header) of a man
  1837. page -- then you might consider setting a non-zero value for
  1838. <parameter>refentry.source.name.suppress</parameter>.</para>
  1839. <para>Note that the terms "source", "source name", and "version" have
  1840. special meanings in this context. For details, see the documentation
  1841. for the <parameter>refentry.source.name.profile</parameter>
  1842. parameter.</para>
  1843. </refsection>
  1844. </refentry>
  1845. <refentry version="5.0" xml:id="refentry.source.name.profile">
  1846. <refmeta>
  1847. <refentrytitle>refentry.source.name.profile</refentrytitle>
  1848. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  1849. </refmeta>
  1850. <refnamediv>
  1851. <refname>refentry.source.name.profile</refname>
  1852. <refpurpose>Specifies profile for refentry "source name" data</refpurpose>
  1853. </refnamediv>
  1854. <refsynopsisdiv>
  1855. <programlisting xml:id="refentry.source.name.profile.frag">
  1856. &lt;xsl:param name="refentry.source.name.profile"&gt;
  1857. (($info[//productname])[last()]/productname)[1]|
  1858. (($info[//corpname])[last()]/corpname)[1]|
  1859. (($info[//corpcredit])[last()]/corpcredit)[1]|
  1860. (($info[//corpauthor])[last()]/corpauthor)[1]|
  1861. (($info[//orgname])[last()]/orgname)[1]|
  1862. (($info[//publishername])[last()]/publishername)[1]
  1863. &lt;/xsl:param&gt;
  1864. </programlisting>
  1865. </refsynopsisdiv>
  1866. <refsection><info><title>Description</title></info>
  1867. <para>The value of <parameter>refentry.source.name.profile</parameter>
  1868. is a string representing an XPath expression. It is evaluated at
  1869. run-time and used only if
  1870. <parameter>refentry.source.name.profile.enabled</parameter> is
  1871. non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
  1872. "hard coded" into the stylesheets is used.</para>
  1873. <para>A "source name" is one part of a (potentially) two-part
  1874. <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>
  1875. "source" field. In man pages, it is usually displayed in the left
  1876. footer of the page. It typically indicates the software system or
  1877. product that the item documented in the man page belongs to. The
  1878. <literal>man(7)</literal> man page describes it as "the source of
  1879. the command", and provides the following examples:
  1880. <itemizedlist>
  1881. <listitem>
  1882. <para>For binaries, use something like: GNU, NET-2, SLS
  1883. Distribution, MCC Distribution.</para>
  1884. </listitem>
  1885. <listitem>
  1886. <para>For system calls, use the version of the kernel that you
  1887. are currently looking at: Linux 0.99.11.</para>
  1888. </listitem>
  1889. <listitem>
  1890. <para>For library calls, use the source of the function: GNU, BSD
  1891. 4.3, Linux DLL 4.4.1.</para>
  1892. </listitem>
  1893. </itemizedlist>
  1894. </para>
  1895. <para>In practice, there are many pages that simply have a Version
  1896. number in the "source" field. So, it looks like what we have is a
  1897. two-part field,
  1898. <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>,
  1899. where:
  1900. <variablelist>
  1901. <varlistentry>
  1902. <term>Name</term>
  1903. <listitem>
  1904. <para>product name (e.g., BSD) or org. name (e.g., GNU)</para>
  1905. </listitem>
  1906. </varlistentry>
  1907. <varlistentry>
  1908. <term>Version</term>
  1909. <listitem>
  1910. <para>version number</para>
  1911. </listitem>
  1912. </varlistentry>
  1913. </variablelist>
  1914. Each part is optional. If the <replaceable>Name</replaceable> is a
  1915. product name, then the <replaceable>Version</replaceable> is probably
  1916. the version of the product. Or there may be no
  1917. <replaceable>Name</replaceable>, in which case, if there is a
  1918. <replaceable>Version</replaceable>, it is probably the version
  1919. of the item itself, not the product it is part of. Or, if the
  1920. <replaceable>Name</replaceable> is an organization name, then there
  1921. probably will be no <replaceable>Version</replaceable>.</para>
  1922. </refsection>
  1923. </refentry>
  1924. <refentry version="5.0" xml:id="refentry.source.name.profile.enabled">
  1925. <refmeta>
  1926. <refentrytitle>refentry.source.name.profile.enabled</refentrytitle>
  1927. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  1928. </refmeta>
  1929. <refnamediv>
  1930. <refname>refentry.source.name.profile.enabled</refname>
  1931. <refpurpose>Enable refentry "source name" profiling?</refpurpose>
  1932. </refnamediv>
  1933. <refsynopsisdiv>
  1934. <programlisting xml:id="refentry.source.name.profile.enabled.frag">
  1935. &lt;xsl:param name="refentry.source.name.profile.enabled"&gt;0&lt;/xsl:param&gt;</programlisting>
  1936. </refsynopsisdiv>
  1937. <refsection><info><title>Description</title></info>
  1938. <para>If the value of
  1939. <parameter>refentry.source.name.profile.enabled</parameter> is
  1940. non-zero, then during <tag>refentry</tag> metadata gathering, the info
  1941. profile specified by the customizable
  1942. <parameter>refentry.source.name.profile</parameter> parameter is
  1943. used.</para>
  1944. <para>If instead the value of
  1945. <parameter>refentry.source.name.profile.enabled</parameter> is zero (the
  1946. default), then "hard coded" logic within the DocBook XSL stylesheets
  1947. is used for gathering <tag>refentry</tag> "source name" data.</para>
  1948. <para>If you find that the default <tag>refentry</tag>
  1949. metadata-gathering behavior is causing incorrect "source name" data to
  1950. show up in your output, then consider setting a non-zero value for
  1951. <parameter>refentry.source.name.profile.enabled</parameter> and
  1952. adjusting the value of
  1953. <parameter>refentry.source.name.profile</parameter> to cause correct
  1954. data to be gathered. </para>
  1955. <para>Note that the terms "source" and "source name" have special
  1956. meanings in this context. For details, see the documentation for the
  1957. <parameter>refentry.source.name.profile</parameter> parameter.</para>
  1958. </refsection>
  1959. </refentry>
  1960. <refentry version="5.0" xml:id="refentry.version.suppress">
  1961. <refmeta>
  1962. <refentrytitle>refentry.version.suppress</refentrytitle>
  1963. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  1964. </refmeta>
  1965. <refnamediv>
  1966. <refname>refentry.version.suppress</refname>
  1967. <refpurpose>Suppress "version" part of refentry "source" contents?</refpurpose>
  1968. </refnamediv>
  1969. <refsynopsisdiv>
  1970. <programlisting xml:id="refentry.version.suppress.frag">
  1971. &lt;xsl:param name="refentry.version.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
  1972. </refsynopsisdiv>
  1973. <refsection><info><title>Description</title></info>
  1974. <para>If the value of <parameter>refentry.version.suppress</parameter>
  1975. is non-zero, then during <tag>refentry</tag> metadata gathering, no
  1976. "version" data is added to the <tag>refentry</tag> "source"
  1977. contents. Instead (unless
  1978. <parameter>refentry.source.name.suppress</parameter> is also
  1979. non-zero), only "source name" data is added to the "source"
  1980. contents.</para>
  1981. <para>If you find that the <tag>refentry</tag> metadata gathering
  1982. mechanism is causing unwanted "version" data to show up in your output
  1983. -- for example, in the footer (or possibly header) of a man page --
  1984. then you might consider setting a non-zero value for
  1985. <parameter>refentry.version.suppress</parameter>.</para>
  1986. <para>Note that the terms "source", "source name", and "version" have
  1987. special meanings in this context. For details, see the documentation
  1988. for the <parameter>refentry.source.name.profile</parameter>
  1989. parameter.</para>
  1990. </refsection>
  1991. </refentry>
  1992. <refentry version="5.0" xml:id="refentry.version.profile">
  1993. <refmeta>
  1994. <refentrytitle>refentry.version.profile</refentrytitle>
  1995. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  1996. </refmeta>
  1997. <refnamediv>
  1998. <refname>refentry.version.profile</refname>
  1999. <refpurpose>Specifies profile for refentry "version" data</refpurpose>
  2000. </refnamediv>
  2001. <refsynopsisdiv>
  2002. <programlisting xml:id="refentry.version.profile.frag">
  2003. &lt;xsl:param name="refentry.version.profile"&gt;
  2004. (($info[//productnumber])[last()]/productnumber)[1]|
  2005. (($info[//edition])[last()]/edition)[1]|
  2006. (($info[//releaseinfo])[last()]/releaseinfo)[1]
  2007. &lt;/xsl:param&gt;
  2008. </programlisting>
  2009. </refsynopsisdiv>
  2010. <refsection><info><title>Description</title></info>
  2011. <para>The value of <parameter>refentry.version.profile</parameter> is
  2012. a string representing an XPath expression. It is evaluated at
  2013. run-time and used only if
  2014. <parameter>refentry.version.profile.enabled</parameter> is
  2015. non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
  2016. "hard coded" into the stylesheets is used.</para>
  2017. <para>A "source.name" is one part of a (potentially) two-part
  2018. <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>
  2019. "source" field. For more details, see the documentation for the
  2020. <parameter>refentry.source.name.profile</parameter> parameter.</para>
  2021. </refsection>
  2022. </refentry>
  2023. <refentry version="5.0" xml:id="refentry.version.profile.enabled">
  2024. <refmeta>
  2025. <refentrytitle>refentry.version.profile.enabled</refentrytitle>
  2026. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2027. </refmeta>
  2028. <refnamediv>
  2029. <refname>refentry.version.profile.enabled</refname>
  2030. <refpurpose>Enable refentry "version" profiling?</refpurpose>
  2031. </refnamediv>
  2032. <refsynopsisdiv>
  2033. <programlisting xml:id="refentry.version.profile.enabled.frag">
  2034. &lt;xsl:param name="refentry.version.profile.enabled"&gt;0&lt;/xsl:param&gt;</programlisting>
  2035. </refsynopsisdiv>
  2036. <refsection><info><title>Description</title></info>
  2037. <para>If the value of
  2038. <parameter>refentry.version.profile.enabled</parameter> is
  2039. non-zero, then during <tag>refentry</tag> metadata gathering, the info
  2040. profile specified by the customizable
  2041. <parameter>refentry.version.profile</parameter> parameter is
  2042. used.</para>
  2043. <para>If instead the value of
  2044. <parameter>refentry.version.profile.enabled</parameter> is zero (the
  2045. default), then "hard coded" logic within the DocBook XSL stylesheets
  2046. is used for gathering <tag>refentry</tag> "version" data.</para>
  2047. <para>If you find that the default <tag>refentry</tag>
  2048. metadata-gathering behavior is causing incorrect "version" data to show
  2049. up in your output, then consider setting a non-zero value for
  2050. <parameter>refentry.version.profile.enabled</parameter> and adjusting
  2051. the value of <parameter>refentry.version.profile</parameter> to cause
  2052. correct data to be gathered. </para>
  2053. <para>Note that the terms "source" and "version" have special
  2054. meanings in this context. For details, see the documentation for the
  2055. <parameter>refentry.version.profile</parameter> parameter.</para>
  2056. </refsection>
  2057. </refentry>
  2058. <refentry version="5.0" xml:id="refentry.manual.fallback.profile">
  2059. <refmeta>
  2060. <refentrytitle>refentry.manual.fallback.profile</refentrytitle>
  2061. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  2062. </refmeta>
  2063. <refnamediv>
  2064. <refname>refentry.manual.fallback.profile</refname>
  2065. <refpurpose>Specifies profile of "fallback" for refentry "manual" data</refpurpose>
  2066. </refnamediv>
  2067. <refsynopsisdiv>
  2068. <programlisting xml:id="refentry.manual.fallback.profile.frag">
  2069. &lt;xsl:param name="refentry.manual.fallback.profile"&gt;
  2070. refmeta/refmiscinfo[not(@class = 'date')][1]/node()&lt;/xsl:param&gt;
  2071. </programlisting>
  2072. </refsynopsisdiv>
  2073. <refsection><info><title>Description</title></info>
  2074. <para>The value of
  2075. <parameter>refentry.manual.fallback.profile</parameter> is a string
  2076. representing an XPath expression. It is evaluated at run-time and
  2077. used only if no "manual" data can be found by other means (that is,
  2078. either using the <tag>refentry</tag> metadata-gathering logic "hard
  2079. coded" in the stylesheets, or the value of
  2080. <parameter>refentry.manual.profile</parameter>, if it is
  2081. enabled).</para>
  2082. <important>
  2083. <para>Depending on which XSLT engine you run, either the EXSLT
  2084. <function>dyn:evaluate</function> extension function (for xsltproc or
  2085. Xalan) or <function>saxon:evaluate</function> extension function (for
  2086. Saxon) are used to dynamically evaluate the value of
  2087. <parameter>refentry.manual.fallback.profile</parameter> at
  2088. run-time. If you don't use xsltproc, Saxon, Xalan -- or some other
  2089. XSLT engine that supports <function>dyn:evaluate</function> -- you
  2090. must manually disable fallback processing by setting an empty value
  2091. for the <parameter>refentry.manual.fallback.profile</parameter>
  2092. parameter.</para>
  2093. </important>
  2094. </refsection>
  2095. </refentry>
  2096. <refentry version="5.0" xml:id="refentry.source.fallback.profile">
  2097. <refmeta>
  2098. <refentrytitle>refentry.source.fallback.profile</refentrytitle>
  2099. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  2100. </refmeta>
  2101. <refnamediv>
  2102. <refname>refentry.source.fallback.profile</refname>
  2103. <refpurpose>Specifies profile of "fallback" for refentry "source" data</refpurpose>
  2104. </refnamediv>
  2105. <refsynopsisdiv>
  2106. <programlisting xml:id="refentry.source.fallback.profile.frag">
  2107. &lt;xsl:param name="refentry.source.fallback.profile"&gt;
  2108. refmeta/refmiscinfo[not(@class = 'date')][1]/node()&lt;/xsl:param&gt;
  2109. </programlisting>
  2110. </refsynopsisdiv>
  2111. <refsection><info><title>Description</title></info>
  2112. <para>The value of
  2113. <parameter>refentry.source.fallback.profile</parameter> is a string
  2114. representing an XPath expression. It is evaluated at run-time and used
  2115. only if no "source" data can be found by other means (that is, either
  2116. using the <tag>refentry</tag> metadata-gathering logic "hard coded" in
  2117. the stylesheets, or the value of the
  2118. <parameter>refentry.source.name.profile</parameter> and
  2119. <parameter>refentry.version.profile</parameter> parameters, if those
  2120. are enabled).</para>
  2121. <important>
  2122. <para>Depending on which XSLT engine you run, either the EXSLT
  2123. <function>dyn:evaluate</function> extension function (for xsltproc or
  2124. Xalan) or <function>saxon:evaluate</function> extension function (for
  2125. Saxon) are used to dynamically evaluate the value of
  2126. <parameter>refentry.source.fallback.profile</parameter> at
  2127. run-time. If you don't use xsltproc, Saxon, Xalan -- or some other
  2128. XSLT engine that supports <function>dyn:evaluate</function> -- you
  2129. must manually disable fallback processing by setting an empty value
  2130. for the <parameter>refentry.source.fallback.profile</parameter>
  2131. parameter.</para>
  2132. </important>
  2133. </refsection>
  2134. </refentry>
  2135. </reference>
  2136. <reference xml:id="th">
  2137. <title>Page header/footer</title>
  2138. <refentry version="5.0" xml:id="man.th.extra1.suppress">
  2139. <refmeta>
  2140. <refentrytitle>man.th.extra1.suppress</refentrytitle>
  2141. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2142. </refmeta>
  2143. <refnamediv>
  2144. <refname>man.th.extra1.suppress</refname>
  2145. <refpurpose>Suppress extra1 part of header/footer?</refpurpose>
  2146. </refnamediv>
  2147. <refsynopsisdiv>
  2148. <programlisting xml:id="man.th.extra1.suppress.frag">
  2149. &lt;xsl:param name="man.th.extra1.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
  2150. </refsynopsisdiv>
  2151. <refsection><info><title>Description</title></info>
  2152. <para>If the value of <parameter>man.th.extra1.suppress</parameter> is
  2153. non-zero, then the <literal>extra1</literal> part of the
  2154. <literal>.TH</literal> title line header/footer is suppressed.</para>
  2155. <para>The content of the <literal>extra1</literal> field is almost
  2156. always displayed in the center footer of the page and is, universally,
  2157. a date.</para>
  2158. </refsection>
  2159. </refentry>
  2160. <refentry version="5.0" xml:id="man.th.extra2.suppress">
  2161. <refmeta>
  2162. <refentrytitle>man.th.extra2.suppress</refentrytitle>
  2163. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2164. </refmeta>
  2165. <refnamediv>
  2166. <refname>man.th.extra2.suppress</refname>
  2167. <refpurpose>Suppress extra2 part of header/footer?</refpurpose>
  2168. </refnamediv>
  2169. <refsynopsisdiv>
  2170. <programlisting xml:id="man.th.extra2.suppress.frag">
  2171. &lt;xsl:param name="man.th.extra2.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
  2172. </refsynopsisdiv>
  2173. <refsection><info><title>Description</title></info>
  2174. <para>If the value of <parameter>man.th.extra2.suppress</parameter> is
  2175. non-zero, then the <literal>extra2</literal> part of the
  2176. <literal>.TH</literal> title line header/footer is suppressed.</para>
  2177. <para>The content of the <literal>extra2</literal> field is usually
  2178. displayed in the left footer of the page and is typically "source"
  2179. data, often in the form
  2180. <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>;
  2181. for example, "GTK+ 1.2" (from the <literal>gtk-options(7)</literal>
  2182. man page).</para>
  2183. <note>
  2184. <para>You can use the
  2185. <parameter>refentry.source.name.suppress</parameter> and
  2186. <parameter>refentry.version.suppress</parameter> parameters to
  2187. independently suppress the <replaceable>Name</replaceable> and
  2188. <replaceable>Version</replaceable> parts of the
  2189. <literal>extra2</literal> field.</para>
  2190. </note>
  2191. </refsection>
  2192. </refentry>
  2193. <refentry version="5.0" xml:id="man.th.extra3.suppress">
  2194. <refmeta>
  2195. <refentrytitle>man.th.extra3.suppress</refentrytitle>
  2196. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2197. </refmeta>
  2198. <refnamediv>
  2199. <refname>man.th.extra3.suppress</refname>
  2200. <refpurpose>Suppress extra3 part of header/footer?</refpurpose>
  2201. </refnamediv>
  2202. <refsynopsisdiv>
  2203. <programlisting xml:id="man.th.extra3.suppress.frag">
  2204. &lt;xsl:param name="man.th.extra3.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
  2205. </refsynopsisdiv>
  2206. <refsection><info><title>Description</title></info>
  2207. <para>If the value of <parameter>man.th.extra3.suppress</parameter> is
  2208. non-zero, then the <literal>extra3</literal> part of the
  2209. <literal>.TH</literal> title line header/footer is
  2210. suppressed.</para>
  2211. <para>The content of the <literal>extra3</literal> field is usually
  2212. displayed in the middle header of the page and is typically a "manual
  2213. name"; for example, "GTK+ User's Manual" (from the
  2214. <literal>gtk-options(7)</literal> man page).</para>
  2215. </refsection>
  2216. </refentry>
  2217. <refentry version="5.0" xml:id="man.th.title.max.length">
  2218. <refmeta>
  2219. <refentrytitle>man.th.title.max.length</refentrytitle>
  2220. <refmiscinfo class="other" otherclass="datatype">integer</refmiscinfo>
  2221. </refmeta>
  2222. <refnamediv>
  2223. <refname>man.th.title.max.length</refname>
  2224. <refpurpose>Maximum length of title in header/footer</refpurpose>
  2225. </refnamediv>
  2226. <refsynopsisdiv>
  2227. <programlisting xml:id="man.th.title.max.length.frag">
  2228. &lt;xsl:param name="man.th.title.max.length"&gt;20&lt;/xsl:param&gt;
  2229. </programlisting>
  2230. </refsynopsisdiv>
  2231. <refsection><info><title>Description</title></info>
  2232. <para>Specifies the maximum permitted length of the title part of the
  2233. man-page <literal>.TH</literal> title line header/footer. If the title
  2234. exceeds the maxiumum specified, it is truncated down to the maximum
  2235. permitted length.</para>
  2236. <refsection><info><title>Details</title></info>
  2237. <para>Every man page generated using the DocBook stylesheets has a
  2238. title line, specified using the <literal>TH</literal> roff
  2239. macro. Within that title line, there is always, at a minimum, a title,
  2240. followed by a section value (representing a man "section" -- usually
  2241. just a number).</para>
  2242. <para>The title and section are displayed, together, in the visible
  2243. header of each page. Where in the header they are displayed depends on
  2244. OS the man page is viewed on, and on what version of nroff/groff/man
  2245. is used for viewing the page. But, at a minimum and across all
  2246. systems, the title and section are displayed on the right-hand column
  2247. of the header. On many systems -- those with a modern groff, including
  2248. Linux systems -- they are displayed twice: both in the left and right
  2249. columns of the header.</para>
  2250. <para>So if the length of the title exceeds a certain percentage of
  2251. the column width in which the page is viewed, the left and right
  2252. titles can end up overlapping, making them unreadable, or breaking to
  2253. another line, which doesn't look particularly good.</para>
  2254. <para>So the stylesheets provide the
  2255. <parameter>man.th.title.max.length</parameter> parameter as a means
  2256. for truncating titles that exceed the maximum length that can be
  2257. viewing properly in a page header.</para>
  2258. <para>The default value is reasonable but somewhat arbitrary. If you
  2259. have pages with long titles, you may want to experiment with changing
  2260. the value in order to achieve the correct aesthetic results.</para>
  2261. </refsection>
  2262. </refsection>
  2263. </refentry>
  2264. <refentry version="5.0" xml:id="man.th.extra2.max.length">
  2265. <refmeta>
  2266. <refentrytitle>man.th.extra2.max.length</refentrytitle>
  2267. <refmiscinfo class="other" otherclass="datatype">integer</refmiscinfo>
  2268. </refmeta>
  2269. <refnamediv>
  2270. <refname>man.th.extra2.max.length</refname>
  2271. <refpurpose>Maximum length of extra2 in header/footer</refpurpose>
  2272. </refnamediv>
  2273. <refsynopsisdiv>
  2274. <programlisting xml:id="man.th.extra2.max.length.frag">
  2275. &lt;xsl:param name="man.th.extra2.max.length"&gt;30&lt;/xsl:param&gt;
  2276. </programlisting>
  2277. </refsynopsisdiv>
  2278. <refsection><info><title>Description</title></info>
  2279. <para>Specifies the maximum permitted length of the
  2280. <literal>extra2</literal> part of the man-page part of the
  2281. <literal>.TH</literal> title line header/footer. If the
  2282. <literal>extra2</literal> content exceeds the maxiumum specified, it
  2283. is truncated down to the maximum permitted length.</para>
  2284. <para>The content of the <literal>extra2</literal> field is usually
  2285. displayed in the left footer of the page and is typically "source"
  2286. data indicating the software system or product that the item
  2287. documented in the man page belongs to, often in the form
  2288. <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>;
  2289. for example, "GTK+ 1.2" (from the <literal>gtk-options(7)</literal>
  2290. man page).</para>
  2291. <para>The default value for this parameter is reasonable but somewhat
  2292. arbitrary. If you are processing pages with long "source" information,
  2293. you may want to experiment with changing the value in order to achieve
  2294. the correct aesthetic results.</para>
  2295. </refsection>
  2296. </refentry>
  2297. <refentry version="5.0" xml:id="man.th.extra3.max.length">
  2298. <refmeta>
  2299. <refentrytitle>man.th.extra3.max.length</refentrytitle>
  2300. <refmiscinfo class="other" otherclass="datatype">integer</refmiscinfo>
  2301. </refmeta>
  2302. <refnamediv>
  2303. <refname>man.th.extra3.max.length</refname>
  2304. <refpurpose>Maximum length of extra3 in header/footer</refpurpose>
  2305. </refnamediv>
  2306. <refsynopsisdiv>
  2307. <programlisting xml:id="man.th.extra3.max.length.frag">
  2308. &lt;xsl:param name="man.th.extra3.max.length"&gt;30&lt;/xsl:param&gt;
  2309. </programlisting>
  2310. </refsynopsisdiv>
  2311. <refsection><info><title>Description</title></info>
  2312. <para>Specifies the maximum permitted length of the
  2313. <literal>extra3</literal> part of the man-page <literal>.TH</literal>
  2314. title line header/footer. If the <literal>extra3</literal> content
  2315. exceeds the maxiumum specified, it is truncated down to the maximum
  2316. permitted length.</para>
  2317. <para>The content of the <literal>extra3</literal> field is usually
  2318. displayed in the middle header of the page and is typically a "manual
  2319. name"; for example, "GTK+ User's Manual" (from the
  2320. <literal>gtk-options(7)</literal> man page).</para>
  2321. <para>The default value for this parameter is reasonable but somewhat
  2322. arbitrary. If you are processing pages with long "manual names" -- or
  2323. especially if you are processing pages that have both long "title"
  2324. parts (command/function, etc. names) <emphasis>and</emphasis> long
  2325. manual names -- you may want to experiment with changing the value in
  2326. order to achieve the correct aesthetic results.</para>
  2327. </refsection>
  2328. </refentry>
  2329. </reference>
  2330. <reference xml:id="output">
  2331. <title>Output</title>
  2332. <refentry version="5.0" xml:id="man.output.manifest.enabled">
  2333. <refmeta>
  2334. <refentrytitle>man.output.manifest.enabled</refentrytitle>
  2335. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2336. </refmeta>
  2337. <refnamediv>
  2338. <refname>man.output.manifest.enabled</refname>
  2339. <refpurpose>Generate a manifest file?</refpurpose>
  2340. </refnamediv>
  2341. <refsynopsisdiv>
  2342. <programlisting xml:id="man.output.manifest.enabled.frag">&lt;xsl:param name="man.output.manifest.enabled" select="0"&gt;&lt;/xsl:param&gt;</programlisting>
  2343. </refsynopsisdiv>
  2344. <refsection><info><title>Description</title></info>
  2345. <para>If non-zero, a list of filenames for man pages generated by
  2346. the stylesheet transformation is written to the file named by the
  2347. <parameter>man.output.manifest.filename</parameter> parameter.</para>
  2348. </refsection>
  2349. </refentry>
  2350. <refentry version="5.0" xml:id="man.output.manifest.filename">
  2351. <refmeta>
  2352. <refentrytitle>man.output.manifest.filename</refentrytitle>
  2353. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  2354. </refmeta>
  2355. <refnamediv>
  2356. <refname>man.output.manifest.filename</refname>
  2357. <refpurpose>Name of manifest file</refpurpose>
  2358. </refnamediv>
  2359. <refsynopsisdiv>
  2360. <programlisting xml:id="man.output.manifest.filename.frag">&lt;xsl:param name="man.output.manifest.filename"&gt;MAN.MANIFEST&lt;/xsl:param&gt;</programlisting>
  2361. </refsynopsisdiv>
  2362. <refsection><info><title>Description</title></info>
  2363. <para>The <parameter>man.output.manifest.filename</parameter> parameter
  2364. specifies the name of the file to which the manpages manifest file
  2365. is written (if the value of the
  2366. <parameter>man.output.manifest.enabled</parameter> parameter is
  2367. non-zero).</para>
  2368. </refsection>
  2369. </refentry>
  2370. <refentry version="5.0" xml:id="man.output.in.separate.dir">
  2371. <refmeta>
  2372. <refentrytitle>man.output.in.separate.dir</refentrytitle>
  2373. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2374. </refmeta>
  2375. <refnamediv>
  2376. <refname>man.output.in.separate.dir</refname>
  2377. <refpurpose>Output man-page files in separate output directory?</refpurpose>
  2378. </refnamediv>
  2379. <refsynopsisdiv>
  2380. <programlisting xml:id="man.output.in.separate.dir.frag">
  2381. &lt;xsl:param name="man.output.in.separate.dir" select="0"&gt;&lt;/xsl:param&gt;
  2382. </programlisting>
  2383. </refsynopsisdiv>
  2384. <refsection><info><title>Description</title></info>
  2385. <para>If the value of <literal>man.output.in.separate.dir</literal>
  2386. parameter is non-zero, man-page files are output in a separate
  2387. directory, specified by the <parameter>man.output.base.dir</parameter>
  2388. parameter; otherwise, if the value of
  2389. <literal>man.output.in.separate.dir</literal> is zero, man-page files
  2390. are not output in a separate directory.</para>
  2391. </refsection>
  2392. </refentry>
  2393. <refentry version="5.0" xml:id="man.output.lang.in.name.enabled">
  2394. <refmeta>
  2395. <refentrytitle>man.output.lang.in.name.enabled</refentrytitle>
  2396. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2397. </refmeta>
  2398. <refnamediv>
  2399. <refname>man.output.lang.in.name.enabled</refname>
  2400. <refpurpose>Include $LANG value in man-page filename/pathname?</refpurpose>
  2401. </refnamediv>
  2402. <refsynopsisdiv>
  2403. <programlisting xml:id="man.output.lang.in.name.enabled.frag">
  2404. &lt;xsl:param name="man.output.lang.in.name.enabled" select="0"&gt;&lt;/xsl:param&gt;
  2405. </programlisting>
  2406. </refsynopsisdiv>
  2407. <refsection><info><title>Description</title></info>
  2408. <para>The <parameter>man.output.lang.in.name.enabled</parameter>
  2409. parameter specifies whether a <literal>$lang</literal> value is
  2410. included in man-page filenames and pathnames.</para>
  2411. <para>If the value of
  2412. <parameter>man.output.lang.in.name.enabled</parameter> is non-zero,
  2413. man-page files are output with the <literal>$lang</literal> value
  2414. included in their filenames or pathnames as follows;
  2415. <itemizedlist>
  2416. <listitem>
  2417. <para>if <parameter>man.output.subdirs.enabled</parameter> is
  2418. non-zero, each file is output to, e.g., a
  2419. <filename>man/<replaceable>$lang</replaceable>/man8/foo.8</filename>
  2420. pathname</para>
  2421. </listitem>
  2422. <listitem>
  2423. <para>if <parameter>man.output.subdirs.enabled</parameter> is
  2424. zero, each file is output with a
  2425. <literal>foo.<replaceable>$lang</replaceable>.8</literal>
  2426. filename</para>
  2427. </listitem>
  2428. </itemizedlist>
  2429. </para>
  2430. </refsection>
  2431. </refentry>
  2432. <refentry version="5.0" xml:id="man.output.base.dir">
  2433. <refmeta>
  2434. <refentrytitle>man.output.base.dir</refentrytitle>
  2435. <refmiscinfo class="other" otherclass="datatype">uri</refmiscinfo>
  2436. </refmeta>
  2437. <refnamediv>
  2438. <refname>man.output.base.dir</refname>
  2439. <refpurpose>Specifies separate output directory</refpurpose>
  2440. </refnamediv>
  2441. <refsynopsisdiv>
  2442. <programlisting xml:id="man.output.base.dir.frag">&lt;xsl:param name="man.output.base.dir"&gt;man/&lt;/xsl:param&gt;</programlisting>
  2443. </refsynopsisdiv>
  2444. <refsection><info><title>Description</title></info>
  2445. <para>The <parameter>man.output.base.dir</parameter> parameter
  2446. specifies the base directory into which man-page files are output. The
  2447. <parameter>man.output.subdirs.enabled</parameter> parameter controls
  2448. whether the files are output in subdirectories within the base
  2449. directory.</para>
  2450. <note>
  2451. <para>The values of the <parameter>man.output.base.dir</parameter>
  2452. and <parameter>man.output.subdirs.enabled</parameter> parameters are
  2453. used only if the value of
  2454. <parameter>man.output.in.separate.dir</parameter> parameter is
  2455. non-zero. If the value of the
  2456. <parameter>man.output.in.separate.dir</parameter> is zero, man-page
  2457. files are not output in a separate directory.</para>
  2458. </note>
  2459. </refsection>
  2460. </refentry>
  2461. <refentry version="5.0" xml:id="man.output.subdirs.enabled">
  2462. <refmeta>
  2463. <refentrytitle>man.output.subdirs.enabled</refentrytitle>
  2464. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2465. </refmeta>
  2466. <refnamediv>
  2467. <refname>man.output.subdirs.enabled</refname>
  2468. <refpurpose>Output man-page files in subdirectories within base output directory?</refpurpose>
  2469. </refnamediv>
  2470. <refsynopsisdiv>
  2471. <programlisting xml:id="man.output.subdirs.enabled.frag">
  2472. &lt;xsl:param name="man.output.subdirs.enabled" select="1"&gt;&lt;/xsl:param&gt;
  2473. </programlisting>
  2474. </refsynopsisdiv>
  2475. <refsection><info><title>Description</title></info>
  2476. <para>The <parameter>man.output.subdirs.enabled</parameter> parameter
  2477. controls whether man-pages files are output in subdirectories within
  2478. the base directory specified by the directory specified by the
  2479. <parameter>man.output.base.dir</parameter> parameter.</para>
  2480. <note>
  2481. <para>The values of the <parameter>man.output.base.dir</parameter>
  2482. and <parameter>man.output.subdirs.enabled</parameter> parameters are
  2483. used only if the value of
  2484. <parameter>man.output.in.separate.dir</parameter> parameter is
  2485. non-zero. If the value of the
  2486. <parameter>man.output.in.separate.dir</parameter> is zero, man-page
  2487. files are not output in a separate directory.</para>
  2488. </note>
  2489. </refsection>
  2490. </refentry>
  2491. <refentry version="5.0" xml:id="man.output.quietly">
  2492. <refmeta>
  2493. <refentrytitle>man.output.quietly</refentrytitle>
  2494. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2495. </refmeta>
  2496. <refnamediv>
  2497. <refname>man.output.quietly</refname>
  2498. <refpurpose>Suppress filename messages emitted when generating output?</refpurpose>
  2499. </refnamediv>
  2500. <refsynopsisdiv>
  2501. <programlisting xml:id="man.output.quietly.frag">
  2502. &lt;xsl:param name="man.output.quietly" select="0"&gt;&lt;/xsl:param&gt;
  2503. </programlisting>
  2504. </refsynopsisdiv>
  2505. <refsection><info><title>Description</title></info>
  2506. <para>If zero (the default), for each man-page file created, a message
  2507. with the name of the file is emitted. If non-zero, the files are
  2508. output "quietly" -- that is, the filename messages are
  2509. suppressed.</para>
  2510. <tip>
  2511. <para>If you are processing a large amount of <tag>refentry</tag>
  2512. content, you may be able to speed up processing significantly by
  2513. setting a non-zero value for
  2514. <parameter>man.output.quietly</parameter>.</para>
  2515. </tip>
  2516. </refsection>
  2517. </refentry>
  2518. <refentry version="5.0" xml:id="man.output.encoding">
  2519. <refmeta>
  2520. <refentrytitle>man.output.encoding</refentrytitle>
  2521. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  2522. </refmeta>
  2523. <refnamediv>
  2524. <refname>man.output.encoding</refname>
  2525. <refpurpose>Encoding used for man-page output</refpurpose>
  2526. </refnamediv>
  2527. <refsynopsisdiv>
  2528. <programlisting xml:id="man.output.encoding.frag">
  2529. &lt;xsl:param name="man.output.encoding"&gt;UTF-8&lt;/xsl:param&gt;
  2530. </programlisting>
  2531. </refsynopsisdiv>
  2532. <refsection><info><title>Description</title></info>
  2533. <para>This parameter specifies the encoding to use for files generated
  2534. by the manpages stylesheet. Not all processors support specification
  2535. of this parameter.</para>
  2536. <important>
  2537. <para>If the value of the <parameter>man.charmap.enabled</parameter>
  2538. parameter is non-zero (the default), keeping the
  2539. <parameter>man.output.encoding</parameter> parameter at its default
  2540. value (<literal>UTF-8</literal>) or setting it to
  2541. <literal>UTF-16</literal> <emphasis role="bold">does not cause your
  2542. man pages to be output in raw UTF-8 or UTF-16</emphasis> -- because
  2543. any Unicode characters for which matches are found in the enabled
  2544. character map will be replaced with roff escape sequences before the
  2545. final man-page files are generated.</para>
  2546. <para>So if you want to generate "real" UTF-8 man pages, without any
  2547. character substitution being performed on your content, you need to
  2548. set <parameter>man.charmap.enabled</parameter> to zero (which will
  2549. completely disable character-map processing). </para>
  2550. <para>You may also need to set
  2551. <parameter>man.charmap.enabled</parameter> to zero if you want to
  2552. output man pages in an encoding other than <literal>UTF-8</literal>
  2553. or <literal>UTF-16</literal>. Character-map processing is based on
  2554. Unicode character values and may not work with other output
  2555. encodings.</para>
  2556. </important>
  2557. </refsection>
  2558. </refentry>
  2559. <refentry version="5.0" xml:id="man.output.better.ps.enabled">
  2560. <refmeta>
  2561. <refentrytitle>man.output.better.ps.enabled</refentrytitle>
  2562. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2563. </refmeta>
  2564. <refnamediv>
  2565. <refname>man.output.better.ps.enabled</refname>
  2566. <refpurpose>Enable enhanced print/PostScript output?</refpurpose>
  2567. </refnamediv>
  2568. <refsynopsisdiv>
  2569. <programlisting xml:id="man.output.better.ps.enabled.frag">
  2570. &lt;xsl:param name="man.output.better.ps.enabled"&gt;0&lt;/xsl:param&gt;
  2571. </programlisting>
  2572. </refsynopsisdiv>
  2573. <refsection><info><title>Description</title></info>
  2574. <para>If the value of the
  2575. <parameter>man.output.better.ps.enabled</parameter> parameter is
  2576. non-zero, certain markup is embedded in each generated man page
  2577. such that PostScript output from the <command>man -Tps</command>
  2578. command for that page will include a number of enhancements
  2579. designed to improve the quality of that output.</para>
  2580. <para>If <parameter>man.output.better.ps.enabled</parameter> is
  2581. zero (the default), no such markup is embedded in generated man
  2582. pages, and no enhancements are included in the PostScript
  2583. output generated from those man pages by the <command>man
  2584. -Tps</command> command.</para>
  2585. <warning>
  2586. <para>The enhancements provided by this parameter rely on
  2587. features that are specific to groff (GNU troff) and that are
  2588. not part of &#8220;classic&#8221; AT&amp;T troff or any of its
  2589. derivatives. Therefore, any man pages you generate with this
  2590. parameter enabled will be readable only on systems on which
  2591. the groff (GNU troff) program is installed, such as GNU/Linux
  2592. systems. The pages <emphasis role="bold">will not not be
  2593. readable on systems on with the classic troff (AT&amp;T
  2594. troff) command is installed</emphasis>.</para>
  2595. </warning>
  2596. <para>The value of this parameter only affects PostScript output
  2597. generated from the <command>man</command> command. It has no
  2598. effect on output generated using the FO backend.</para>
  2599. <tip>
  2600. <para>You can generate PostScript output for any man page by
  2601. running the following command:</para>
  2602. <programlisting> man <replaceable>FOO</replaceable> -Tps &gt; <replaceable>FOO</replaceable>.ps</programlisting>
  2603. <para>You can then generate PDF output by running the following
  2604. command:</para>
  2605. <programlisting> ps2pdf <replaceable>FOO</replaceable>.ps</programlisting>
  2606. </tip>
  2607. </refsection>
  2608. </refentry>
  2609. </reference>
  2610. <reference xml:id="other">
  2611. <title>Other</title>
  2612. <refentry version="5.0" xml:id="man.table.footnotes.divider">
  2613. <refmeta>
  2614. <refentrytitle>man.table.footnotes.divider</refentrytitle>
  2615. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  2616. </refmeta>
  2617. <refnamediv>
  2618. <refname>man.table.footnotes.divider</refname>
  2619. <refpurpose>Specifies divider string that appears before table footnotes</refpurpose>
  2620. </refnamediv>
  2621. <refsynopsisdiv>
  2622. <programlisting xml:id="man.table.footnotes.divider.frag">
  2623. &lt;xsl:param name="man.table.footnotes.divider"&gt;----&lt;/xsl:param&gt;
  2624. </programlisting>
  2625. </refsynopsisdiv>
  2626. <refsection><info><title>Description</title></info>
  2627. <para>In each table that contains footenotes, the string specified by
  2628. the <parameter>man.table.footnotes.divider</parameter> parameter is
  2629. output before the list of footnotes for the table.</para>
  2630. </refsection>
  2631. </refentry>
  2632. <refentry version="5.0" xml:id="man.subheading.divider.enabled">
  2633. <refmeta>
  2634. <refentrytitle>man.subheading.divider.enabled</refentrytitle>
  2635. <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
  2636. </refmeta>
  2637. <refnamediv>
  2638. <refname>man.subheading.divider.enabled</refname>
  2639. <refpurpose>Add divider comment to roff source before/after subheadings?</refpurpose>
  2640. </refnamediv>
  2641. <refsynopsisdiv>
  2642. <programlisting xml:id="man.subheading.divider.enabled.frag">
  2643. &lt;xsl:param name="man.subheading.divider.enabled"&gt;0&lt;/xsl:param&gt;
  2644. </programlisting>
  2645. </refsynopsisdiv>
  2646. <refsection><info><title>Description</title></info>
  2647. <para>If the value of the
  2648. <parameter>man.subheading.divider.enabled</parameter> parameter is
  2649. non-zero, the contents of the
  2650. <parameter>man.subheading.divider</parameter> parameter are used to
  2651. add a "divider" before and after subheadings in the roff
  2652. output. <emphasis role="bold">The divider is not visisble in the
  2653. rendered man page</emphasis>; it is added as a comment, in the source,
  2654. simply for the purpose of increasing reability of the source.</para>
  2655. <para>If <parameter>man.subheading.divider.enabled</parameter> is zero
  2656. (the default), the subheading divider is suppressed.</para>
  2657. </refsection>
  2658. </refentry>
  2659. <refentry version="5.0" xml:id="man.subheading.divider">
  2660. <refmeta>
  2661. <refentrytitle>man.subheading.divider</refentrytitle>
  2662. <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  2663. </refmeta>
  2664. <refnamediv>
  2665. <refname>man.subheading.divider</refname>
  2666. <refpurpose>Specifies string to use as divider comment before/after subheadings</refpurpose>
  2667. </refnamediv>
  2668. <refsynopsisdiv>
  2669. <programlisting xml:id="man.subheading.divider.frag">
  2670. &lt;xsl:param name="man.subheading.divider"&gt;========================================================================&lt;/xsl:param&gt;
  2671. </programlisting>
  2672. </refsynopsisdiv>
  2673. <refsection><info><title>Description</title></info>
  2674. <para>If the value of the
  2675. <parameter>man.subheading.divider.enabled</parameter> parameter is
  2676. non-zero, the contents of the
  2677. <parameter>man.subheading.divider</parameter> parameter are used to
  2678. add a "divider" before and after subheadings in the roff
  2679. output. <emphasis role="bold">The divider is not visisble in the
  2680. rendered man page</emphasis>; it is added as a comment, in the source,
  2681. simply for the purpose of increasing reability of the source.</para>
  2682. <para>If <parameter>man.subheading.divider.enabled</parameter> is zero
  2683. (the default), the subheading divider is suppressed.</para>
  2684. </refsection>
  2685. </refentry>
  2686. </reference>
  2687. <appendix xml:id="stylesheet">
  2688. <title>The Stylesheet</title>
  2689. <para>The <filename>param.xsl</filename> stylesheet is just a
  2690. wrapper around all of these parameters.</para>
  2691. <programlisting xml:id="top">
  2692. &lt;xsl:stylesheet exclude-result-prefixes="src" version="1.0"&gt;
  2693. &lt;!-- This file is generated from param.xweb --&gt;
  2694. &lt;!-- ********************************************************************
  2695. $Id: param.xweb 9130 2011-10-11 08:05:37Z dpawson $
  2696. ********************************************************************
  2697. This file is part of the XSL DocBook Stylesheet distribution.
  2698. See ../README or http://docbook.sf.net/release/xsl/current/ for
  2699. copyright and other information.
  2700. ******************************************************************** --&gt;
  2701. &lt;src:fragref linkend="man.authors.section.enabled.frag"&gt;&lt;/src:fragref&gt;
  2702. &lt;src:fragref linkend="man.break.after.slash.frag"&gt;&lt;/src:fragref&gt;
  2703. &lt;src:fragref linkend="man.base.url.for.relative.links.frag"&gt;&lt;/src:fragref&gt;
  2704. &lt;src:fragref linkend="man.charmap.enabled.frag"&gt;&lt;/src:fragref&gt;
  2705. &lt;src:fragref linkend="man.charmap.subset.profile.frag"&gt;&lt;/src:fragref&gt;
  2706. &lt;src:fragref linkend="man.charmap.subset.profile.english.frag"&gt;&lt;/src:fragref&gt;
  2707. &lt;src:fragref linkend="man.charmap.uri.frag"&gt;&lt;/src:fragref&gt;
  2708. &lt;src:fragref linkend="man.charmap.use.subset.frag"&gt;&lt;/src:fragref&gt;
  2709. &lt;src:fragref linkend="man.copyright.section.enabled.frag"&gt;&lt;/src:fragref&gt;
  2710. &lt;src:fragref linkend="man.endnotes.are.numbered.frag"&gt;&lt;/src:fragref&gt;
  2711. &lt;src:fragref linkend="man.endnotes.list.enabled.frag"&gt;&lt;/src:fragref&gt;
  2712. &lt;src:fragref linkend="man.endnotes.list.heading.frag"&gt;&lt;/src:fragref&gt;
  2713. &lt;src:fragref linkend="man.font.funcprototype.frag"&gt;&lt;/src:fragref&gt;
  2714. &lt;src:fragref linkend="man.font.funcsynopsisinfo.frag"&gt;&lt;/src:fragref&gt;
  2715. &lt;src:fragref linkend="man.font.links.frag"&gt;&lt;/src:fragref&gt;
  2716. &lt;src:fragref linkend="man.font.table.headings.frag"&gt;&lt;/src:fragref&gt;
  2717. &lt;src:fragref linkend="man.font.table.title.frag"&gt;&lt;/src:fragref&gt;
  2718. &lt;src:fragref linkend="man.funcsynopsis.style.frag"&gt;&lt;/src:fragref&gt;
  2719. &lt;src:fragref linkend="man.hyphenate.computer.inlines.frag"&gt;&lt;/src:fragref&gt;
  2720. &lt;src:fragref linkend="man.hyphenate.filenames.frag"&gt;&lt;/src:fragref&gt;
  2721. &lt;src:fragref linkend="man.hyphenate.frag"&gt;&lt;/src:fragref&gt;
  2722. &lt;src:fragref linkend="man.hyphenate.urls.frag"&gt;&lt;/src:fragref&gt;
  2723. &lt;src:fragref linkend="man.indent.blurbs.frag"&gt;&lt;/src:fragref&gt;
  2724. &lt;src:fragref linkend="man.indent.lists.frag"&gt;&lt;/src:fragref&gt;
  2725. &lt;src:fragref linkend="man.indent.refsect.frag"&gt;&lt;/src:fragref&gt;
  2726. &lt;src:fragref linkend="man.indent.verbatims.frag"&gt;&lt;/src:fragref&gt;
  2727. &lt;src:fragref linkend="man.indent.width.frag"&gt;&lt;/src:fragref&gt;
  2728. &lt;src:fragref linkend="man.justify.frag"&gt;&lt;/src:fragref&gt;
  2729. &lt;src:fragref linkend="man.output.base.dir.frag"&gt;&lt;/src:fragref&gt;
  2730. &lt;src:fragref linkend="man.output.encoding.frag"&gt;&lt;/src:fragref&gt;
  2731. &lt;src:fragref linkend="man.output.in.separate.dir.frag"&gt;&lt;/src:fragref&gt;
  2732. &lt;src:fragref linkend="man.output.lang.in.name.enabled.frag"&gt;&lt;/src:fragref&gt;
  2733. &lt;src:fragref linkend="man.output.manifest.enabled.frag"&gt;&lt;/src:fragref&gt;
  2734. &lt;src:fragref linkend="man.output.manifest.filename.frag"&gt;&lt;/src:fragref&gt;
  2735. &lt;src:fragref linkend="man.output.better.ps.enabled.frag"&gt;&lt;/src:fragref&gt;
  2736. &lt;src:fragref linkend="man.output.quietly.frag"&gt;&lt;/src:fragref&gt;
  2737. &lt;src:fragref linkend="man.output.subdirs.enabled.frag"&gt;&lt;/src:fragref&gt;
  2738. &lt;src:fragref linkend="man.segtitle.suppress.frag"&gt;&lt;/src:fragref&gt;
  2739. &lt;src:fragref linkend="man.string.subst.map.frag"&gt;&lt;/src:fragref&gt;
  2740. &lt;src:fragref linkend="man.string.subst.map.local.post.frag"&gt;&lt;/src:fragref&gt;
  2741. &lt;src:fragref linkend="man.string.subst.map.local.pre.frag"&gt;&lt;/src:fragref&gt;
  2742. &lt;src:fragref linkend="man.subheading.divider.enabled.frag"&gt;&lt;/src:fragref&gt;
  2743. &lt;src:fragref linkend="man.subheading.divider.frag"&gt;&lt;/src:fragref&gt;
  2744. &lt;src:fragref linkend="man.table.footnotes.divider.frag"&gt;&lt;/src:fragref&gt;
  2745. &lt;src:fragref linkend="man.th.extra1.suppress.frag"&gt;&lt;/src:fragref&gt;
  2746. &lt;src:fragref linkend="man.th.extra2.max.length.frag"&gt;&lt;/src:fragref&gt;
  2747. &lt;src:fragref linkend="man.th.extra2.suppress.frag"&gt;&lt;/src:fragref&gt;
  2748. &lt;src:fragref linkend="man.th.extra3.max.length.frag"&gt;&lt;/src:fragref&gt;
  2749. &lt;src:fragref linkend="man.th.extra3.suppress.frag"&gt;&lt;/src:fragref&gt;
  2750. &lt;src:fragref linkend="man.th.title.max.length.frag"&gt;&lt;/src:fragref&gt;
  2751. &lt;src:fragref linkend="refentry.date.profile.enabled.frag"&gt;&lt;/src:fragref&gt;
  2752. &lt;src:fragref linkend="refentry.date.profile.frag"&gt;&lt;/src:fragref&gt;
  2753. &lt;src:fragref linkend="refentry.manual.fallback.profile.frag"&gt;&lt;/src:fragref&gt;
  2754. &lt;src:fragref linkend="refentry.manual.profile.enabled.frag"&gt;&lt;/src:fragref&gt;
  2755. &lt;src:fragref linkend="refentry.manual.profile.frag"&gt;&lt;/src:fragref&gt;
  2756. &lt;src:fragref linkend="refentry.meta.get.quietly.frag"&gt;&lt;/src:fragref&gt;
  2757. &lt;src:fragref linkend="refentry.source.fallback.profile.frag"&gt;&lt;/src:fragref&gt;
  2758. &lt;src:fragref linkend="refentry.source.name.profile.enabled.frag"&gt;&lt;/src:fragref&gt;
  2759. &lt;src:fragref linkend="refentry.source.name.profile.frag"&gt;&lt;/src:fragref&gt;
  2760. &lt;src:fragref linkend="refentry.source.name.suppress.frag"&gt;&lt;/src:fragref&gt;
  2761. &lt;src:fragref linkend="refentry.version.profile.enabled.frag"&gt;&lt;/src:fragref&gt;
  2762. &lt;src:fragref linkend="refentry.version.profile.frag"&gt;&lt;/src:fragref&gt;
  2763. &lt;src:fragref linkend="refentry.version.suppress.frag"&gt;&lt;/src:fragref&gt;
  2764. &lt;/xsl:stylesheet&gt;
  2765. </programlisting>
  2766. </appendix>
  2767. </book>