+++ /dev/null
-<?xml version="1.0"?>
-
-<reference xml:id="refentry">
- <info>
- <title>Common » Refentry Metadata Template Reference</title>
- <releaseinfo role="meta">
- $Id: refentry.xsl 7867 2008-03-07 09:54:25Z xmldoc $
- </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 xmlns:xlink="http://www.w3.org/1999/xlink" 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><xsl:template name="get.refentry.metadata">
-<xsl:param name="refname"/>
-<xsl:param name="info"/>
-<xsl:param name="prefs"/>
- ...
-</xsl:template></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 xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.title">
-<refnamediv>
-<refname>get.refentry.title</refname>
-<refpurpose>Gets title metadata for a refentry</refpurpose>
-</refnamediv>
-<refsynopsisdiv>
-<synopsis><xsl:template name="get.refentry.title">
-<xsl:param name="refname"/>
- ...
-</xsl:template></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 xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.section">
-<refnamediv>
-<refname>get.refentry.section</refname>
-<refpurpose>Gets section metadata for a refentry</refpurpose>
-</refnamediv>
-<refsynopsisdiv>
-<synopsis><xsl:template name="get.refentry.section">
-<xsl:param name="refname"/>
-<xsl:param name="quiet" select="0"/>
- ...
-</xsl:template></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 xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.date">
-<refnamediv>
-<refname>get.refentry.date</refname>
-<refpurpose>Gets date metadata for a refentry</refpurpose>
-</refnamediv>
-<refsynopsisdiv>
-<synopsis><xsl:template name="get.refentry.date">
-<xsl:param name="refname"/>
-<xsl:param name="info"/>
-<xsl:param name="prefs"/>
- ...
-</xsl:template></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 xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.source">
-<refnamediv>
-<refname>get.refentry.source</refname>
-<refpurpose>Gets source metadata for a refentry</refpurpose>
-</refnamediv>
-<refsynopsisdiv>
-<synopsis><xsl:template name="get.refentry.source">
-<xsl:param name="refname"/>
-<xsl:param name="info"/>
-<xsl:param name="prefs"/>
- ...
-</xsl:template></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 xmlns:xlink="http://www.w3.org/1999/xlink" 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><xsl:template name="get.refentry.source.name">
-<xsl:param name="refname"/>
-<xsl:param name="info"/>
-<xsl:param name="prefs"/>
- ...
-</xsl:template></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 xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.version">
-<refnamediv>
-<refname>get.refentry.version</refname>
-<refpurpose>Gets version metadata for a refentry</refpurpose>
-</refnamediv>
-<refsynopsisdiv>
-<synopsis><xsl:template name="get.refentry.version">
-<xsl:param name="refname"/>
-<xsl:param name="info"/>
-<xsl:param name="prefs"/>
- ...
-</xsl:template></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 xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.manual">
-<refnamediv>
-<refname>get.refentry.manual</refname>
-<refpurpose>Gets source metadata for a refentry</refpurpose>
-</refnamediv>
-<refsynopsisdiv>
-<synopsis><xsl:template name="get.refentry.manual">
-<xsl:param name="refname"/>
-<xsl:param name="info"/>
-<xsl:param name="prefs"/>
- ...
-</xsl:template></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 xmlns:xlink="http://www.w3.org/1999/xlink" 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><xsl:template name="get.refentry.metadata.prefs"/></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 xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.set.refentry.metadata">
-<refnamediv>
-<refname>set.refentry.metadata</refname>
-<refpurpose>Sets content of a refentry metadata item</refpurpose>
-</refnamediv>
-<refsynopsisdiv>
-<synopsis><xsl:template name="set.refentry.metadata">
-<xsl:param name="refname"/>
-<xsl:param name="info"/>
-<xsl:param name="contents"/>
-<xsl:param name="context"/>
-<xsl:param name="preferred"/>
- ...
-</xsl:template></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>
-
git.stg.codes / stg.git / blobdiff