doc/xslt/params/olink.doctitle.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="olink.doctitle">
   7 <refmeta>
   8 <refentrytitle>olink.doctitle</refentrytitle>
   9 <refmiscinfo class="other" otherclass="datatype">list</refmiscinfo>
  10 <refmiscinfo class="other" otherclass="value">no</refmiscinfo>
  11 <refmiscinfo class="other" otherclass="value">yes</refmiscinfo>
  12 <refmiscinfo class="other" otherclass="value">maybe</refmiscinfo>
  13 </refmeta>
  14 <refnamediv>
  15 <refname>olink.doctitle</refname>
  16 <refpurpose>show the document title for external olinks?</refpurpose>
  17
  18 </refnamediv>
  19 <refsynopsisdiv> <src:fragment xml:id="olink.doctitle.frag">
  20 <xsl:param name="olink.doctitle">no</xsl:param>
  21 </src:fragment>
  22 </refsynopsisdiv>
  23 <refsection><info><title>Description</title></info>
  24
  25 <para>When olinks between documents are resolved, the generated text
  26 may not make it clear that the reference is to another document.
  27 It is possible for the stylesheets to append the other document's
  28 title to external olinks. For this to happen, two parameters must
  29 be set.</para>
  30 <itemizedlist>
  31 <listitem>
  32 <para>This <parameter>olink.doctitle</parameter> parameter
  33 should be set to either <literal>yes</literal> or <literal>maybe</literal>
  34 to enable this feature.
  35 </para>
  36 </listitem>
  37 <listitem>
  38 <para>And you should also set the <parameter>current.docid</parameter>
  39 parameter to the document id for the  document currently
  40 being processed for output.
  41 </para>
  42 </listitem>
  43 </itemizedlist>
  44
  45 <para>
  46 Then if an olink's  <literal>targetdoc</literal> id differs from
  47 the <literal>current.docid</literal> value, the stylesheet knows
  48 that it is a reference to another document and can
  49 append the target document's
  50 title to the generated olink text. </para>
  51
  52 <para>The text for the target document's title is copied from the
  53 olink database from the <tag>ttl</tag> element
  54 of the top-level <tag>div</tag> for that document.
  55 If that <tag>ttl</tag> element is missing or empty,
  56 no title is output.
  57 </para>
  58
  59 <para>The supported values for <parameter>olink.doctitle</parameter> are:
  60 </para>
  61 <variablelist>
  62 <varlistentry>
  63 <term><literal>yes</literal></term>
  64 <listitem>
  65 <para>
  66 Always insert the title to the target document if it is not
  67 the current document.
  68 </para>
  69 </listitem>
  70 </varlistentry>
  71 <varlistentry>
  72 <term><literal>no</literal></term>
  73 <listitem>
  74 <para>
  75 Never insert the title to the target document, even if requested
  76 in an <tag class="attribute">xrefstyle</tag> attribute.
  77 </para>
  78 </listitem>
  79 </varlistentry>
  80 <varlistentry>
  81 <term><literal>maybe</literal></term>
  82 <listitem>
  83 <para>
  84 Only insert the title to the target document, if requested
  85 in an <tag class="attribute">xrefstyle</tag> attribute.
  86 </para>
  87 </listitem>
  88 </varlistentry>
  89 </variablelist>
  90 <para>An <tag class="attribute">xrefstyle</tag> attribute
  91 may override the global setting for individual olinks.
  92 The following values are supported in an
  93 <tag class="attribute">xrefstyle</tag>
  94 attribute using the <literal>select:</literal> syntax:
  95 </para>
  96
  97 <variablelist>
  98 <varlistentry>
  99 <term><literal>docname</literal></term>
 100 <listitem>
 101 <para>
 102 Insert the target document name for this olink using the
 103 <literal>docname</literal> gentext template, but only
 104 if the value of <parameter>olink.doctitle</parameter>
 105 is not <literal>no</literal>.
 106 </para>
 107 </listitem>
 108 </varlistentry>
 109 <varlistentry>
 110 <term><literal>docnamelong</literal></term>
 111 <listitem>
 112 <para>
 113 Insert the target document name for this olink using the
 114 <literal>docnamelong</literal> gentext template, but only
 115 if the value of <parameter>olink.doctitle</parameter>
 116 is not <literal>no</literal>.
 117 </para>
 118 </listitem>
 119 </varlistentry>
 120 <varlistentry>
 121 <term><literal>nodocname</literal></term>
 122 <listitem>
 123 <para>
 124 Omit the target document name even if
 125 the value of <parameter>olink.doctitle</parameter>
 126 is <literal>yes</literal>.
 127 </para>
 128 </listitem>
 129 </varlistentry>
 130 </variablelist>
 131 <para>Another way of inserting the target document name
 132 for a single olink is to employ an
 133 <tag class="attribute">xrefstyle</tag>
 134 attribute using the <literal>template:</literal> syntax.
 135 The <literal>%o</literal> placeholder (the letter o, not zero)
 136 in such a template
 137 will be filled in with the target document's title when it is processed.
 138 This will occur regardless of
 139 the value of <parameter>olink.doctitle</parameter>.
 140 </para>
 141 <para>Note that prior to version 1.66 of the XSL stylesheets,
 142 the allowed values for this parameter were 0 and 1.  Those
 143 values are still supported and mapped to 'no' and 'yes', respectively.
 144 </para>
 145 </refsection>
 146 </refentry>