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