--- /dev/null
+<refentry id="insert.olink.page.number">
+<refmeta>
+<refentrytitle>insert.olink.page.number</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>insert.olink.page.number</refname>
+<refpurpose>Turns page numbers in olinks on and off</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='insert.olink.page.number.frag'>
+<xsl:param name="insert.olink.page.number">no</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>The value of this parameter determines if
+cross references made between documents with
+<sgmltag>olink</sgmltag> will
+include page number citations.
+In most cases this is only applicable to references in printed output.
+</para>
+<para>The parameter has three possible values.
+</para>
+<variablelist>
+<varlistentry>
+<term>no</term>
+<listitem><para>No page number references will be generated for olinks.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>yes</term>
+<listitem><para>Page number references will be generated
+for all <sgmltag>olink</sgmltag> references.
+The style of page reference may be changed
+if an <sgmltag class="attribute">xrefstyle</sgmltag>
+attribute is used.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>maybe</term>
+<listitem><para>Page number references will not be generated
+for an <sgmltag>olink</sgmltag> element unless
+it has an
+<sgmltag class="attribute">xrefstyle</sgmltag>
+attribute whose value specifies a page reference.
+</para></listitem>
+</varlistentry>
+</variablelist>
+<para>Olinks that point to targets within the same document
+are treated as <sgmltag>xref</sgmltag>s, and controlled by
+the <parameter>insert.xref.page.number</parameter> parameter.
+</para>
+
+<para>Page number references for olinks to
+external documents can only be inserted if the
+information exists in the olink database.
+This means each olink target element
+(<sgmltag>div</sgmltag> or <sgmltag>obj</sgmltag>)
+must have a <sgmltag class="attribute">page</sgmltag> attribute
+whose value is its page number in the target document.
+The XSL stylesheets are not able to extract that information
+during processing because pages have not yet been created in
+XSLT transformation. Only the XSL-FO processor knows what
+page each element is placed on.
+Therefore some postprocessing must take place to populate
+page numbers in the olink database.
+</para>
+
+
+
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="insert.olink.pdf.frag">
+<refmeta>
+<refentrytitle>insert.olink.pdf.frag</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>insert.olink.pdf.frag</refname>
+<refpurpose>Add fragment identifiers for links into PDF files</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='insert.olink.pdf.frag.frag'>
+<xsl:param name="insert.olink.pdf.frag" select="0"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>The value of this parameter determines whether
+the cross reference URIs to PDF documents made with
+<sgmltag>olink</sgmltag> will
+include fragment identifiers.
+</para>
+
+<para>When forming a URI to link to a PDF document,
+a fragment identifier (typically a '#' followed by an
+id value) appended to the PDF filename can be used by
+the PDF viewer to open
+the PDF file to a location within the document instead of
+the first page.
+However, not all PDF files have id
+values embedded in them, and not all PDF viewers can
+handle fragment identifiers.
+</para>
+
+<para>If <parameter>insert.olink.pdf.frag</parameter> is set
+to a non-zero value, then any olink targeting a
+PDF file will have the fragment identifier appended to the URI.
+The URI is formed by concatenating the value of the
+<parameter>olink.base.uri</parameter> parameter, the
+value of the <sgmltag class="attribute">baseuri</sgmltag>
+attribute from the <sgmltag class="element">document</sgmltag>
+element in the olink database with the matching
+<sgmltag class="attribute">targetdoc</sgmltag> value,
+and the value of the <sgmltag class="attribute">href</sgmltag>
+attribute for the targeted element in the olink database.
+The <sgmltag class="attribute">href</sgmltag> attribute
+contains the fragment identifier.
+</para>
+
+<para>If <parameter>insert.olink.pdf.frag</parameter> is set
+to zero (the default value), then
+the <sgmltag class="attribute">href</sgmltag> attribute
+from the olink database
+is not appended to PDF olinks, so the fragment identifier is left off.
+A PDF olink is any olink for which the
+<sgmltag class="attribute">baseuri</sgmltag> attribute
+from the matching <sgmltag class="element">document</sgmltag>
+element in the olink database ends with '.pdf'.
+Any other olinks will still have the fragment identifier added.
+</para>
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="olink.debug">
+<refmeta>
+<refentrytitle>olink.debug</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>olink.debug</refname>
+<refpurpose>Turn on debugging messages for olinks</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='olink.debug.frag'>
+<xsl:param name="olink.debug" select="0"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If non-zero, then each olink will generate several
+messages about how it is being resolved during processing.
+This is useful when an olink does not resolve properly
+and the standard error messages are not sufficient to
+find the problem.
+</para>
+
+<para>You may need to read through the olink XSL templates
+to understand the context for some of the debug messages.
+</para>
+
+</refsect1>
+</refentry>
<refentry id="olink.doctitle">
<refmeta>
<refentrytitle>olink.doctitle</refentrytitle>
-<refmiscinfo role="type">boolean</refmiscinfo>
+<refmiscinfo role="type">string</refmiscinfo>
</refmeta>
<refnamediv>
<refname>olink.doctitle</refname>
</refnamediv>
<refsynopsisdiv> <src:fragment id="olink.doctitle.frag">
-<xsl:param name="olink.doctitle" select="0"/> </src:fragment>
+<xsl:param name="olink.doctitle" select="no"/> </src:fragment>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
-<para>When olinks between documents are resolved for print output, the generated text may not make it clear that the reference is to another document. It is possible for the stylesheets to append the other document's title to external olinks. For this to happen, two parameters must be set. The <parameter>olink.doctitle</parameter> parameter should be set to nonzero to enable this
-feature. And you should set the <parameter>current.docid</parameter> parameter to the document id for the document currently
-being processed for output. If an olink's <literal>targetdoc</literal> id differs from the <literal>current.docid</literal>, then the stylesheet can append the target document's
+<para>When olinks between documents are resolved, the generated text
+may not make it clear that the reference is to another document.
+It is possible for the stylesheets to append the other document's
+title to external olinks. For this to happen, two parameters must
+be set.</para>
+<itemizedlist>
+<listitem>
+<para>This <parameter>olink.doctitle</parameter> parameter
+should be set to either <literal>yes</literal> or <literal>maybe</literal>
+to enable this feature.
+</para>
+</listitem>
+<listitem>
+<para>And you should also set the <parameter>current.docid</parameter>
+parameter to the document id for the document currently
+being processed for output.
+</para>
+</listitem>
+</itemizedlist>
+
+<para>
+Then if an olink's <literal>targetdoc</literal> id differs from
+the <literal>current.docid</literal> value, the stylesheet knows
+that it is a reference to another document and can
+append the target document's
title to the generated olink text. </para>
+
+<para>The text for the target document's title is copied from the
+olink database from the <sgmltag>ttl</sgmltag> element
+of the top-level <sgmltag>div</sgmltag> for that document.
+If that <sgmltag>ttl</sgmltag> element is missing or empty,
+no title is output.
+</para>
+
+<para>The supported values for <parameter>olink.doctitle</parameter> are:
+</para>
+<variablelist>
+<varlistentry>
+<term><literal>yes</literal></term>
+<listitem>
+<para>
+Always insert the title to the target document if it is not
+the current document.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>no</literal></term>
+<listitem>
+<para>
+Never insert the title to the target document, even if requested
+in an <sgmltag class="attribute">xrefstyle</sgmltag> attribute.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>maybe</literal></term>
+<listitem>
+<para>
+Only insert the title to the target document, if requested
+in an <sgmltag class="attribute">xrefstyle</sgmltag> attribute.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>An <sgmltag class="attribute">xrefstyle</sgmltag> attribute
+may override the global setting for individual olinks.
+The following values are supported in an
+<sgmltag class="attribute">xrefstyle</sgmltag>
+attribute using the <literal>select:</literal> syntax:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><literal>docname</literal></term>
+<listitem>
+<para>
+Insert the target document name for this olink using the
+<literal>docname</literal> gentext template, but only
+if the value of <parameter>olink.doctitle</parameter>
+is not <literal>no</literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>docnamelong</literal></term>
+<listitem>
+<para>
+Insert the target document name for this olink using the
+<literal>docnamelong</literal> gentext template, but only
+if the value of <parameter>olink.doctitle</parameter>
+is not <literal>no</literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>nodocname</literal></term>
+<listitem>
+<para>
+Omit the target document name even if
+the value of <parameter>olink.doctitle</parameter>
+is <literal>yes</literal>.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>Another way of inserting the target document name
+for a single olink is to employ an
+<sgmltag class="attribute">xrefstyle</sgmltag>
+attribute using the <literal>template:</literal> syntax.
+The <literal>%o</literal> placeholder (the letter o, not zero)
+in such a template
+will be filled in with the target document's title when it is processed.
+This will occur regardless of
+the value of <parameter>olink.doctitle</parameter>.
+</para>
+<para>Note that prior to version 1.66 of the XSL stylesheets,
+the allowed values for this parameter were 0 and 1. Those
+values are still supported and mapped to 'no' and 'yes', respectively.
+</para>
</refsect1>
</refentry>
--- /dev/null
+<refentry id="olink.lang.fallback.sequence">
+<refmeta>
+<refentrytitle>olink.lang.fallback.sequence</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>olink.lang.fallback.sequence</refname>
+<refpurpose>look up translated documents if olink not found?</refpurpose>
+
+</refnamediv>
+<refsynopsisdiv> <src:fragment id="olink.lang.fallback.sequence.frag">
+<xsl:param name="olink.lang.fallback.sequence" select="''"/> </src:fragment>
+</refsynopsisdiv>
+<refsect1>
+<title>Description</title>
+
+<para>This parameter defines a list of lang values
+to search among to resolve olinks.
+</para>
+
+<para>Normally an olink tries to resolve to a document in the same
+language as the olink itself. The language of an olink
+is determined by its nearest ancestor element with a
+<sgmltag class="attribute">lang</sgmltag> attribute, otherwise the
+value of the <parameter>l10n.gentext.default.lang</parameter>
+parameter.
+</para>
+
+<para>An olink database can contain target data for the same
+document in multiple languages. Each set of data has the
+same value for the <sgmltag>targetdoc</sgmltag> attribute in
+the <sgmltag>document</sgmltag> element in the database, but with a
+different <sgmltag>lang</sgmltag> attribute value.
+</para>
+
+<para>When an olink is being resolved, the target is first
+sought in the document with the same language as the olink.
+If no match is found there, then this parameter is consulted
+for additional languages to try.</para>
+
+<para>The <parameter>olink.lang.fallback.sequence</parameter>
+must be a whitespace separated list of lang values to
+try. The first one with a match in the olink database is used.
+The default value is empty.</para>
+
+<para>For example, a document might be written in German
+and contain an olink with
+<literal>targetdoc="adminguide"</literal>.
+When the document is processed, the processor
+first looks for a target dataset in the
+olink database starting with:</para>
+
+<literallayout><literal><document targetdoc="adminguide" lang="de"></literal>.
+</literallayout>
+
+<para>If there is no such element, then the
+<parameter>olink.lang.fallback.sequence</parameter>
+parameter is consulted.
+If its value is, for example, <quote>fr en</quote>, then the processor next
+looks for <literal>targetdoc="adminguide" lang="fr"</literal>, and
+then for <literal>targetdoc="adminguide" lang="en"</literal>.
+If there is still no match, it looks for
+<literal>targetdoc="adminguide"</literal> with no
+lang attribute.
+</para>
+
+<para>This parameter is useful when a set of documents is only
+partially translated, or is in the process of being translated.
+If a target of an olink has not yet been translated, then this
+parameter permits the processor to look for the document in
+other languages. This assumes the reader would rather have
+a link to a document in a different language than to have
+a broken link.
+</para>
+
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="olink.properties">
+<refnamediv>
+<refname>olink.properties</refname>
+<refpurpose>Properties associated with the cross-reference
+text of an olink.</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='olink.properties.frag'>
+<xsl:attribute-set name="olink.properties">
+</xsl:attribute-set>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>This attribute set is used on cross reference text
+from an olink. It is not applied to the
+optional page number or
+optional title of the external document.</para>
+
+</refsect1>
+</refentry>
--- /dev/null
+<refentry id="prefer.internal.olink">
+<refmeta>
+<refentrytitle>prefer.internal.olink</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>prefer.internal.olink</refname>
+<refpurpose>Prefer a local olink reference to an external reference</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='prefer.internal.olink.frag'>
+<xsl:param name="prefer.internal.olink" select="0"/>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If you are re-using XML content modules in multiple documents,
+you may want to redirect some of your olinks. This parameter
+permits you to redirect an olink to the current document.
+</para>
+
+<para>For example: you are writing documentation for a product,
+which includes 3 manuals: a little installation
+booklet (booklet.xml), a user
+guide (user.xml), and a reference manual (reference.xml).
+All 3 documents begin with the same introduction section (intro.xml) that
+contains a reference to the customization section (custom.xml) which is
+included in both user.xml and reference.xml documents.
+</para>
+
+<para>How do you write the link to custom.xml in intro.xml
+so that it is interpreted correctly in all 3 documents?</para>
+<itemizedlist>
+<listitem><para>If you use xref, it will fail in user.xml.</para>
+</listitem>
+<listitem><para>If you use olink (pointing to reference.xml),
+the reference in user.xml
+will point to the customization section of the reference manual, while it is
+actually available in user.xml.</para>
+</listitem>
+</itemizedlist>
+
+<para>If you set the <parameter>prefer.internal.olink</parameter>
+parameter to a non-zero value, then the processor will
+first look in the olink database
+for the olink's <sgmltag>targetptr</sgmltag> attribute value
+in document matching the <parameter>current.docid</parameter>
+parameter value. If it isn't found there, then
+it tries the document in the database
+with the <sgmltag>targetdoc</sgmltag>
+value that matches the olink's <sgmltag>targetdoc</sgmltag>
+attribute.
+</para>
+
+<para>This feature permits an olink reference to resolve to
+the current document if there is an element
+with an id matching the olink's <sgmltag>targetptr</sgmltag>
+value. The current document's olink data must be
+included in the target database for this to work.</para>
+
+<caution>
+<para>There is a potential for incorrect links if
+the same <sgmltag>id</sgmltag> attribute value is used for different
+content in different documents.
+Some of your olinks may be redirected to the current document
+when they shouldn't be. It is not possible to control
+individual olink instances.</para>
+</caution>
+
+</refsect1>
+</refentry>
projects / docbook-dsssl / commitdiff