DocBook documentation stub added

[stg.git] / doc / help / xslt / params / man.font.links.xml

diff --git a/doc/help/xslt/params/man.font.links.xml b/doc/help/xslt/params/man.font.links.xml
new file mode 100644 (file)
index 0000000..0f8a1e0
--- /dev/null
+++ b/doc/help/xslt/params/man.font.links.xml
@@ -0,0 +1,64 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+          version="5.0" xml:id="man.font.links">
+<refmeta>
+<refentrytitle>man.font.links</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.font.links</refname>
+<refpurpose>Specifies font for links</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.font.links.frag">
+<xsl:param name="man.font.links">B</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<para>The <parameter>man.font.links</parameter> parameter
+specifies the font for output of links (<tag>ulink</tag> instances
+and any instances of any element with an <tag
+  class="attribute">xlink:href</tag> attribute).</para>
+
+<para>The value of <parameter>man.font.links</parameter> must be
+  either <literal>B</literal> or <literal>I</literal>, or empty. If
+the value is empty, no font formatting is applied to links.</para>
+
+<para>If you set <parameter>man.endnotes.are.numbered</parameter> and/or
+<parameter>man.endnotes.list.enabled</parameter> to zero (disabled), then
+you should probably also set an empty value for
+<parameter>man.font.links</parameter>. But if
+<parameter>man.endnotes.are.numbered</parameter> is non-zero (enabled),
+you should probably keep
+<parameter>man.font.links</parameter> set to
+<literal>B</literal> or <literal>I</literal><footnote><para>The
+    main purpose of applying a font format to links in most output
+formats it to indicate that the formatted text is
+“clickable”; given that links rendered in man pages are
+not “real” hyperlinks that users can click on, it might
+seem like there is never a good reason to have font formatting for
+link contents in man output.</para>
+<para>In fact, if you suppress the
+display of inline link references (by setting
+<parameter>man.endnotes.are.numbered</parameter> to zero), there is no
+good reason to apply font formatting to links. However, if
+<parameter>man.endnotes.are.numbered</parameter> is non-zero, having
+font formatting for links (arguably) serves a purpose: It provides
+“context” information about exactly what part of the text
+is being “annotated” by the link. Depending on how you
+mark up your content, that context information may or may not
+have value.</para></footnote>.</para>
+</refsection>
+
+<refsection><info><title>Related Parameters</title></info>
+  <para><parameter>man.endnotes.list.enabled</parameter>,
+    <parameter>man.endnotes.are.numbered</parameter></para>
+</refsection>
+
+</refentry>