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>
|
---|