olink.doctitle.xml 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146
  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="olink.doctitle">
  7. <refmeta>
  8. <refentrytitle>olink.doctitle</refentrytitle>
  9. <refmiscinfo class="other" otherclass="datatype">list</refmiscinfo>
  10. <refmiscinfo class="other" otherclass="value">no</refmiscinfo>
  11. <refmiscinfo class="other" otherclass="value">yes</refmiscinfo>
  12. <refmiscinfo class="other" otherclass="value">maybe</refmiscinfo>
  13. </refmeta>
  14. <refnamediv>
  15. <refname>olink.doctitle</refname>
  16. <refpurpose>show the document title for external olinks?</refpurpose>
  17. </refnamediv>
  18. <refsynopsisdiv> <src:fragment xml:id="olink.doctitle.frag">
  19. <xsl:param name="olink.doctitle">no</xsl:param>
  20. </src:fragment>
  21. </refsynopsisdiv>
  22. <refsection><info><title>Description</title></info>
  23. <para>When olinks between documents are resolved, the generated text
  24. may not make it clear that the reference is to another document.
  25. It is possible for the stylesheets to append the other document's
  26. title to external olinks. For this to happen, two parameters must
  27. be set.</para>
  28. <itemizedlist>
  29. <listitem>
  30. <para>This <parameter>olink.doctitle</parameter> parameter
  31. should be set to either <literal>yes</literal> or <literal>maybe</literal>
  32. to enable this feature.
  33. </para>
  34. </listitem>
  35. <listitem>
  36. <para>And you should also set the <parameter>current.docid</parameter>
  37. parameter to the document id for the document currently
  38. being processed for output.
  39. </para>
  40. </listitem>
  41. </itemizedlist>
  42. <para>
  43. Then if an olink's <literal>targetdoc</literal> id differs from
  44. the <literal>current.docid</literal> value, the stylesheet knows
  45. that it is a reference to another document and can
  46. append the target document's
  47. title to the generated olink text. </para>
  48. <para>The text for the target document's title is copied from the
  49. olink database from the <tag>ttl</tag> element
  50. of the top-level <tag>div</tag> for that document.
  51. If that <tag>ttl</tag> element is missing or empty,
  52. no title is output.
  53. </para>
  54. <para>The supported values for <parameter>olink.doctitle</parameter> are:
  55. </para>
  56. <variablelist>
  57. <varlistentry>
  58. <term><literal>yes</literal></term>
  59. <listitem>
  60. <para>
  61. Always insert the title to the target document if it is not
  62. the current document.
  63. </para>
  64. </listitem>
  65. </varlistentry>
  66. <varlistentry>
  67. <term><literal>no</literal></term>
  68. <listitem>
  69. <para>
  70. Never insert the title to the target document, even if requested
  71. in an <tag class="attribute">xrefstyle</tag> attribute.
  72. </para>
  73. </listitem>
  74. </varlistentry>
  75. <varlistentry>
  76. <term><literal>maybe</literal></term>
  77. <listitem>
  78. <para>
  79. Only insert the title to the target document, if requested
  80. in an <tag class="attribute">xrefstyle</tag> attribute.
  81. </para>
  82. </listitem>
  83. </varlistentry>
  84. </variablelist>
  85. <para>An <tag class="attribute">xrefstyle</tag> attribute
  86. may override the global setting for individual olinks.
  87. The following values are supported in an
  88. <tag class="attribute">xrefstyle</tag>
  89. attribute using the <literal>select:</literal> syntax:
  90. </para>
  91. <variablelist>
  92. <varlistentry>
  93. <term><literal>docname</literal></term>
  94. <listitem>
  95. <para>
  96. Insert the target document name for this olink using the
  97. <literal>docname</literal> gentext template, but only
  98. if the value of <parameter>olink.doctitle</parameter>
  99. is not <literal>no</literal>.
  100. </para>
  101. </listitem>
  102. </varlistentry>
  103. <varlistentry>
  104. <term><literal>docnamelong</literal></term>
  105. <listitem>
  106. <para>
  107. Insert the target document name for this olink using the
  108. <literal>docnamelong</literal> gentext template, but only
  109. if the value of <parameter>olink.doctitle</parameter>
  110. is not <literal>no</literal>.
  111. </para>
  112. </listitem>
  113. </varlistentry>
  114. <varlistentry>
  115. <term><literal>nodocname</literal></term>
  116. <listitem>
  117. <para>
  118. Omit the target document name even if
  119. the value of <parameter>olink.doctitle</parameter>
  120. is <literal>yes</literal>.
  121. </para>
  122. </listitem>
  123. </varlistentry>
  124. </variablelist>
  125. <para>Another way of inserting the target document name
  126. for a single olink is to employ an
  127. <tag class="attribute">xrefstyle</tag>
  128. attribute using the <literal>template:</literal> syntax.
  129. The <literal>%o</literal> placeholder (the letter o, not zero)
  130. in such a template
  131. will be filled in with the target document's title when it is processed.
  132. This will occur regardless of
  133. the value of <parameter>olink.doctitle</parameter>.
  134. </para>
  135. <para>Note that prior to version 1.66 of the XSL stylesheets,
  136. the allowed values for this parameter were 0 and 1. Those
  137. values are still supported and mapped to 'no' and 'yes', respectively.
  138. </para>
  139. </refsection>
  140. </refentry>