[b1a51ac1] | 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>
|
---|