doc/xslt/params/man.base.url.for.relative.links.xml

   1 <refentry xmlns="http://docbook.org/ns/docbook"
   2           xmlns:xlink="http://www.w3.org/1999/xlink"
   3           xmlns:xi="http://www.w3.org/2001/XInclude"
   4           xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
   5           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   6           version="5.0" xml:id="man.base.url.for.relative.links">
   7   <refmeta>
   8     <refentrytitle>man.base.url.for.relative.links</refentrytitle>
   9     <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
  10   </refmeta>
  11   <refnamediv>
  12     <refname>man.base.url.for.relative.links</refname>
  13     <refpurpose>Specifies a base URL for relative links</refpurpose>
  14   </refnamediv>
  15
  16   <refsynopsisdiv>
  17     <src:fragment xml:id="man.base.url.for.relative.links.frag"><xsl:param name="man.base.url.for.relative.links">[set $man.base.url.for.relative.links]/</xsl:param></src:fragment>
  18   </refsynopsisdiv>
  19
  20   <refsection><info><title>Description</title></info>
  21
  22     <para>For any “notesource” listed in the auto-generated
  23       “NOTES” section of output man pages (which is generated when
  24       the value of the
  25       <parameter>man.endnotes.list.enabled</parameter> parameter
  26       is non-zero), if the notesource is a link source with a
  27       relative URI, the URI is displayed in output with the value
  28       of the
  29       <parameter>man.base.url.for.relative.links</parameter>
  30       parameter prepended to the value of the link URI.</para>
  31
  32     <note>
  33       <para>A link source is an notesource that references an
  34         external resource:
  35         <itemizedlist>
  36           <listitem>
  37             <para>a <tag>ulink</tag> element with a <tag
  38                 class="attribute">url</tag> attribute</para>
  39           </listitem>
  40           <listitem>
  41             <para>any element with an <tag
  42                 class="attribute">xlink:href</tag> attribute</para>
  43           </listitem>
  44           <listitem>
  45             <para>an <tag>imagedata</tag>, <tag>audiodata</tag>, or
  46               <tag>videodata</tag> element</para>
  47           </listitem>
  48         </itemizedlist>
  49       </para>
  50     </note>
  51
  52     <para>If you use relative URIs in link sources in your DocBook
  53       <tag>refentry</tag> source, and you leave
  54       <parameter>man.base.url.for.relative.links</parameter>
  55       unset, the relative links will appear “as is” in the “Notes”
  56       section of any man-page output generated from your source.
  57       That’s probably not what you want, because such relative
  58       links are only usable in the context of HTML output. So, to
  59       make the links meaningful and usable in the context of
  60       man-page output, set a value for
  61       <parameter>man.base.url.for.relative.links</parameter> that
  62       points to the online version of HTML output generated from
  63       your DocBook <tag>refentry</tag> source. For
  64       example:
  65       <programlisting
  66         >&lt;xsl:param name="man.base.url.for.relative.links"
  67         >http://www.kernel.org/pub/software/scm/git/docs/&lt;/xsl:param></programlisting>
  68     </para>
  69
  70   </refsection>
  71
  72   <refsection><info><title>Related Parameters</title></info>
  73     <para><parameter>man.endnotes.list.enabled</parameter></para>
  74   </refsection>
  75
  76 </refentry>