diff options
Diffstat (limited to 'kdoctools/docbook/xsl/params/olink.doctitle.xml')
-rw-r--r-- | kdoctools/docbook/xsl/params/olink.doctitle.xml | 137 |
1 files changed, 137 insertions, 0 deletions
diff --git a/kdoctools/docbook/xsl/params/olink.doctitle.xml b/kdoctools/docbook/xsl/params/olink.doctitle.xml new file mode 100644 index 000000000..9493fb671 --- /dev/null +++ b/kdoctools/docbook/xsl/params/olink.doctitle.xml @@ -0,0 +1,137 @@ +<refentry id="olink.doctitle"> +<refmeta> +<refentrytitle>olink.doctitle</refentrytitle> +<refmiscinfo role="type">string</refmiscinfo> +</refmeta> +<refnamediv> +<refname>olink.doctitle</refname> +<refpurpose>show the document title for external olinks?</refpurpose> + +</refnamediv> +<refsynopsisdiv> <src:fragment id="olink.doctitle.frag"> +<xsl:param name="olink.doctitle" select="no"/> </src:fragment> +</refsynopsisdiv> +<refsect1> +<title>Description</title> +<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> |