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="prefer.internal.olink">
|
---|
7 | <refmeta>
|
---|
8 | <refentrytitle>prefer.internal.olink</refentrytitle>
|
---|
9 | <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
|
---|
10 | </refmeta>
|
---|
11 | <refnamediv>
|
---|
12 | <refname>prefer.internal.olink</refname>
|
---|
13 | <refpurpose>Prefer a local olink reference to an external reference</refpurpose>
|
---|
14 | </refnamediv>
|
---|
15 |
|
---|
16 | <refsynopsisdiv>
|
---|
17 | <src:fragment xml:id="prefer.internal.olink.frag">
|
---|
18 | <xsl:param name="prefer.internal.olink" select="0"/>
|
---|
19 | </src:fragment>
|
---|
20 | </refsynopsisdiv>
|
---|
21 |
|
---|
22 | <refsection><info><title>Description</title></info>
|
---|
23 |
|
---|
24 | <para>If you are re-using XML content modules in multiple documents,
|
---|
25 | you may want to redirect some of your olinks. This parameter
|
---|
26 | permits you to redirect an olink to the current document.
|
---|
27 | </para>
|
---|
28 |
|
---|
29 | <para>For example: you are writing documentation for a product,
|
---|
30 | which includes 3 manuals: a little installation
|
---|
31 | booklet (booklet.xml), a user
|
---|
32 | guide (user.xml), and a reference manual (reference.xml).
|
---|
33 | All 3 documents begin with the same introduction section (intro.xml) that
|
---|
34 | contains a reference to the customization section (custom.xml) which is
|
---|
35 | included in both user.xml and reference.xml documents.
|
---|
36 | </para>
|
---|
37 |
|
---|
38 | <para>How do you write the link to custom.xml in intro.xml
|
---|
39 | so that it is interpreted correctly in all 3 documents?</para>
|
---|
40 | <itemizedlist>
|
---|
41 | <listitem><para>If you use xref, it will fail in user.xml.</para>
|
---|
42 | </listitem>
|
---|
43 | <listitem><para>If you use olink (pointing to reference.xml),
|
---|
44 | the reference in user.xml
|
---|
45 | will point to the customization section of the reference manual, while it is
|
---|
46 | actually available in user.xml.</para>
|
---|
47 | </listitem>
|
---|
48 | </itemizedlist>
|
---|
49 |
|
---|
50 | <para>If you set the <parameter>prefer.internal.olink</parameter>
|
---|
51 | parameter to a non-zero value, then the processor will
|
---|
52 | first look in the olink database
|
---|
53 | for the olink's <tag>targetptr</tag> attribute value
|
---|
54 | in document matching the <parameter>current.docid</parameter>
|
---|
55 | parameter value. If it isn't found there, then
|
---|
56 | it tries the document in the database
|
---|
57 | with the <tag>targetdoc</tag>
|
---|
58 | value that matches the olink's <tag>targetdoc</tag>
|
---|
59 | attribute.
|
---|
60 | </para>
|
---|
61 |
|
---|
62 | <para>This feature permits an olink reference to resolve to
|
---|
63 | the current document if there is an element
|
---|
64 | with an id matching the olink's <tag>targetptr</tag>
|
---|
65 | value. The current document's olink data must be
|
---|
66 | included in the target database for this to work.</para>
|
---|
67 |
|
---|
68 | <caution>
|
---|
69 | <para>There is a potential for incorrect links if
|
---|
70 | the same <tag>id</tag> attribute value is used for different
|
---|
71 | content in different documents.
|
---|
72 | Some of your olinks may be redirected to the current document
|
---|
73 | when they shouldn't be. It is not possible to control
|
---|
74 | individual olink instances.</para>
|
---|
75 | </caution>
|
---|
76 |
|
---|
77 | </refsection>
|
---|
78 | </refentry>
|
---|