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