lyx_mirror/lib/docbook/common/refentry.xml
2021-02-05 16:07:42 +01:00

779 lines
22 KiB
XML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8"?>
<reference xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="refentry">
<info>
<title>Common » Refentry Metadata Template Reference</title>
<releaseinfo role="meta">
</releaseinfo>
</info>
<partintro xml:id="partintro">
<title>Introduction</title>
<para>This is technical reference documentation for the “refentry
metadata” templates in the DocBook XSL Stylesheets.</para>
<para>This is not intended to be user documentation. It is provided
for developers writing customization layers for the stylesheets.</para>
<note>
<para>Currently, only the manpages stylesheets make use of these
templates. They are, however, potentially useful elsewhere.</para>
</note>
</partintro>
<refentry xml:id="template.get.refentry.metadata">
<refnamediv>
<refname>get.refentry.metadata</refname>
<refpurpose>Gathers metadata from a refentry and its ancestors</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.metadata"&gt;
&lt;xsl:param name="refname"/&gt;
&lt;xsl:param name="info"/&gt;
&lt;xsl:param name="prefs"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>Reference documentation for particular commands, functions,
etc., is sometimes viewed in isolation from its greater "context". For
example, users view Unix man pages as, well, individual pages, not as
part of a "book" of some kind. Therefore, it is sometimes necessary to
embed "context" information in output for each <tag>refentry</tag>.</para>
<para>However, one problem is that different users mark up that
context information in different ways. Often (usually), the
context information is not actually part of the content of the
<tag>refentry</tag> itself, but instead part of the content of a
parent or ancestor element to the <tag>refentry</tag>. And
even then, DocBook provides a variety of elements that users might
potentially use to mark up the same kind of information. One user
might use the <tag>productnumber</tag> element to mark up version
information about a particular product, while another might use
the <tag>releaseinfo</tag> element.</para>
<para>Taking all that in mind, the
<function>get.refentry.metadata</function> template tries to gather
metadata from a <tag>refentry</tag> element and its ancestor
elements in an intelligent and user-configurable way. The basic
mechanism used in the XPath expressions throughout this stylesheet
is to select the relevant metadata from the *info element that is
closest to the actual <tag>refentry</tag>  either on the
<tag>refentry</tag> itself, or on its nearest ancestor.</para>
<note>
<para>The <function>get.refentry.metadata</function>
template is actually just sort of a "driver" template; it
calls other templates that do the actual data collection,
then returns the data as a set.</para>
</note>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
<varlistentry>
<term>info</term>
<listitem>
<para>A set of info nodes (from a <tag>refentry</tag>
element and its ancestors)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>prefs</term>
<listitem>
<para>A node containing user preferences (from global
stylesheet parameters)</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Returns a node set with the following elements. The
descriptions are verbatim from the <literal>man(7)</literal> man
page.
<variablelist>
<varlistentry>
<term>title</term>
<listitem>
<para>the title of the man page (e.g., <literal>MAN</literal>)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>section</term>
<listitem>
<para>the section number the man page should be placed in (e.g.,
<literal>7</literal>)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>date</term>
<listitem>
<para>the date of the last revision</para>
</listitem>
</varlistentry>
<varlistentry>
<term>source</term>
<listitem>
<para>the source of the command</para>
</listitem>
</varlistentry>
<varlistentry>
<term>manual</term>
<listitem>
<para>the title of the manual (e.g., <citetitle>Linux
Programmer's Manual</citetitle>)</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1></refentry>
<refentry xml:id="template.get.refentry.title">
<refnamediv>
<refname>get.refentry.title</refname>
<refpurpose>Gets title metadata for a refentry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.title"&gt;
&lt;xsl:param name="refname"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>The <literal>man(7)</literal> man page describes this as "the
title of the man page (e.g., <literal>MAN</literal>). This differs
from <tag>refname</tag> in that, if the <tag>refentry</tag> has a
<tag>refentrytitle</tag>, we use that as the <tag>title</tag>;
otherwise, we just use first <tag>refname</tag> in the first
<tag>refnamediv</tag> in the source.</para>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Returns a <tag>title</tag> node.</para>
</refsect1></refentry>
<refentry xml:id="template.get.refentry.section">
<refnamediv>
<refname>get.refentry.section</refname>
<refpurpose>Gets section metadata for a refentry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.section"&gt;
&lt;xsl:param name="refname"/&gt;
&lt;xsl:param name="quiet" select="0"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>The <literal>man(7)</literal> man page describes this as "the
section number the man page should be placed in (e.g.,
<literal>7</literal>)". If we do not find a <tag>manvolnum</tag>
specified in the source, and we find that the <tag>refentry</tag> is
for a function, we use the section number <literal>3</literal>
["Library calls (functions within program libraries)"]; otherwise, we
default to using <literal>1</literal> ["Executable programs or shell
commands"].</para>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
<varlistentry>
<term>quiet</term>
<listitem>
<para>If non-zero, no "missing" message is emitted</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Returns a string representing a section number.</para>
</refsect1></refentry>
<refentry xml:id="template.get.refentry.date">
<refnamediv>
<refname>get.refentry.date</refname>
<refpurpose>Gets date metadata for a refentry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.date"&gt;
&lt;xsl:param name="refname"/&gt;
&lt;xsl:param name="info"/&gt;
&lt;xsl:param name="prefs"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>The <literal>man(7)</literal> man page describes this as "the
date of the last revision". If we cannot find a date in the source, we
generate one.</para>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
<varlistentry>
<term>info</term>
<listitem>
<para>A set of info nodes (from a <tag>refentry</tag>
element and its ancestors)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>prefs</term>
<listitem>
<para>A node containing users preferences (from global stylesheet parameters)</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Returns a <tag>date</tag> node.</para>
</refsect1></refentry>
<refentry xml:id="template.get.refentry.source">
<refnamediv>
<refname>get.refentry.source</refname>
<refpurpose>Gets source metadata for a refentry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.source"&gt;
&lt;xsl:param name="refname"/&gt;
&lt;xsl:param name="info"/&gt;
&lt;xsl:param name="prefs"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>The <literal>man(7)</literal> man page describes this as "the
source of the command", and provides the following examples:
<itemizedlist>
<listitem>
<para>For binaries, use something like: GNU, NET-2, SLS
Distribution, MCC Distribution.</para>
</listitem>
<listitem>
<para>For system calls, use the version of the kernel that you are
currently looking at: Linux 0.99.11.</para>
</listitem>
<listitem>
<para>For library calls, use the source of the function: GNU, BSD
4.3, Linux DLL 4.4.1.</para>
</listitem>
</itemizedlist>
</para>
<para>The <literal>solbook(5)</literal> man page describes
something very much like what <literal>man(7)</literal> calls
"source", except that <literal>solbook(5)</literal> names it
"software" and describes it like this:
<blockquote>
<para>This is the name of the software product that the topic
discussed on the reference page belongs to. For example UNIX
commands are part of the <literal>SunOS x.x</literal>
release.</para>
</blockquote>
</para>
<para>In practice, there are many pages that simply have a version
number in the "source" field. So, it looks like what we have is a
two-part field,
<replaceable>Name</replaceable> <replaceable>Version</replaceable>,
where:
<variablelist>
<varlistentry>
<term>Name</term>
<listitem>
<para>product name (e.g., BSD) or org. name (e.g., GNU)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Version</term>
<listitem>
<para>version name</para>
</listitem>
</varlistentry>
</variablelist>
Each part is optional. If the <replaceable>Name</replaceable> is a
product name, then the <replaceable>Version</replaceable> is probably
the version of the product. Or there may be no
<replaceable>Name</replaceable>, in which case, if there is a
<replaceable>Version</replaceable>, it is probably the version of the
item itself, not the product it is part of. Or, if the
<replaceable>Name</replaceable> is an organization name, then there
probably will be no <replaceable>Version</replaceable>.
</para>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
<varlistentry>
<term>info</term>
<listitem>
<para>A set of info nodes (from a <tag>refentry</tag>
element and its ancestors)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>prefs</term>
<listitem>
<para>A node containing users preferences (from global
stylesheet parameters)</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Returns a <tag>source</tag> node.</para>
</refsect1></refentry>
<refentry xml:id="template.get.refentry.source.name">
<refnamediv>
<refname>get.refentry.source.name</refname>
<refpurpose>Gets source-name metadata for a refentry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.source.name"&gt;
&lt;xsl:param name="refname"/&gt;
&lt;xsl:param name="info"/&gt;
&lt;xsl:param name="prefs"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>A "source name" is one part of a (potentially) two-part
<replaceable>Name</replaceable> <replaceable>Version</replaceable>
source field. For more details, see the documentation for the
<function>get.refentry.source</function> template.</para>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
<varlistentry>
<term>info</term>
<listitem>
<para>A set of info nodes (from a <tag>refentry</tag>
element and its ancestors)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>prefs</term>
<listitem>
<para>A node containing users preferences (from global
stylesheet parameters)</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Depending on what output method is used for the
current stylesheet, either returns a text node or possibly an element
node, containing "source name" data.</para>
</refsect1></refentry>
<refentry xml:id="template.get.refentry.version">
<refnamediv>
<refname>get.refentry.version</refname>
<refpurpose>Gets version metadata for a refentry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.version"&gt;
&lt;xsl:param name="refname"/&gt;
&lt;xsl:param name="info"/&gt;
&lt;xsl:param name="prefs"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>A "version" is one part of a (potentially) two-part
<replaceable>Name</replaceable> <replaceable>Version</replaceable>
source field. For more details, see the documentation for the
<function>get.refentry.source</function> template.</para>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
<varlistentry>
<term>info</term>
<listitem>
<para>A set of info nodes (from a <tag>refentry</tag>
element and its ancestors)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>prefs</term>
<listitem>
<para>A node containing users preferences (from global
stylesheet parameters)</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Depending on what output method is used for the
current stylesheet, either returns a text node or possibly an element
node, containing "version" data.</para>
</refsect1></refentry>
<refentry xml:id="template.get.refentry.manual">
<refnamediv>
<refname>get.refentry.manual</refname>
<refpurpose>Gets source metadata for a refentry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.manual"&gt;
&lt;xsl:param name="refname"/&gt;
&lt;xsl:param name="info"/&gt;
&lt;xsl:param name="prefs"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>The <literal>man(7)</literal> man page describes this as "the
title of the manual (e.g., <citetitle>Linux Programmer's
Manual</citetitle>)". Here are some examples from existing man pages:
<itemizedlist>
<listitem>
<para><citetitle>dpkg utilities</citetitle>
(<command>dpkg-name</command>)</para>
</listitem>
<listitem>
<para><citetitle>User Contributed Perl Documentation</citetitle>
(<command>GET</command>)</para>
</listitem>
<listitem>
<para><citetitle>GNU Development Tools</citetitle>
(<command>ld</command>)</para>
</listitem>
<listitem>
<para><citetitle>Emperor Norton Utilities</citetitle>
(<command>ddate</command>)</para>
</listitem>
<listitem>
<para><citetitle>Debian GNU/Linux manual</citetitle>
(<command>faked</command>)</para>
</listitem>
<listitem>
<para><citetitle>GIMP Manual Pages</citetitle>
(<command>gimp</command>)</para>
</listitem>
<listitem>
<para><citetitle>KDOC Documentation System</citetitle>
(<command>qt2kdoc</command>)</para>
</listitem>
</itemizedlist>
</para>
<para>The <literal>solbook(5)</literal> man page describes
something very much like what <literal>man(7)</literal> calls
"manual", except that <literal>solbook(5)</literal> names it
"sectdesc" and describes it like this:
<blockquote>
<para>This is the section title of the reference page; for
example <literal>User Commands</literal>.</para>
</blockquote>
</para>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
<varlistentry>
<term>info</term>
<listitem>
<para>A set of info nodes (from a <tag>refentry</tag>
element and its ancestors)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>prefs</term>
<listitem>
<para>A node containing users preferences (from global
stylesheet parameters)</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Returns a <tag>manual</tag> node.</para>
</refsect1></refentry>
<refentry xml:id="template.get.refentry.metadata.prefs">
<refnamediv>
<refname>get.refentry.metadata.prefs</refname>
<refpurpose>Gets user preferences for refentry metadata gathering</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="get.refentry.metadata.prefs"/&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>The DocBook XSL stylesheets include several user-configurable
global stylesheet parameters for controlling <tag>refentry</tag>
metadata gathering. Those parameters are not read directly by the
other <tag>refentry</tag> metadata-gathering
templates. Instead, they are read only by the
<function>get.refentry.metadata.prefs</function> template,
which assembles them into a structure that is then passed to
the other <tag>refentry</tag> metadata-gathering
templates.</para>
<para>So the, <function>get.refentry.metadata.prefs</function>
template is the only interface to collecting stylesheet parameters for
controlling <tag>refentry</tag> metadata gathering.</para>
</refsect1><refsect1><title>Parameters</title>
<para>There are no local parameters for this template; however, it
does rely on a number of global parameters.</para>
</refsect1><refsect1><title>Returns</title>
<para>Returns a <tag>manual</tag> node.</para>
</refsect1></refentry>
<refentry xml:id="template.set.refentry.metadata">
<refnamediv>
<refname>set.refentry.metadata</refname>
<refpurpose>Sets content of a refentry metadata item</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&lt;xsl:template name="set.refentry.metadata"&gt;
&lt;xsl:param name="refname"/&gt;
&lt;xsl:param name="info"/&gt;
&lt;xsl:param name="contents"/&gt;
&lt;xsl:param name="context"/&gt;
&lt;xsl:param name="preferred"/&gt;
...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>The <function>set.refentry.metadata</function> template is
called each time a suitable source element is found for a certain
metadata field.</para>
</refsect1><refsect1><title>Parameters</title>
<variablelist>
<varlistentry>
<term>refname</term>
<listitem>
<para>The first <tag>refname</tag> in the refentry</para>
</listitem>
</varlistentry>
<varlistentry>
<term>info</term>
<listitem>
<para>A single *info node that contains the selected source element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>contents</term>
<listitem>
<para>A node containing the selected source element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>context</term>
<listitem>
<para>A string describing the metadata context in which the
<function>set.refentry.metadata</function> template was
called: either "date", "source", "version", or "manual".</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><refsect1><title>Returns</title>
<para>Returns formatted contents of a selected source element.</para>
</refsect1></refentry>
</reference>