doc/xslt/params/prefer.internal.olink.xml

   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>