| <?xml version="1.0"?> |
| |
| <reference xml:id="refentry"> |
| <info> |
| <title>Common » Refentry Metadata Template Reference</title> |
| <releaseinfo role="meta"> |
| $Id$ |
| </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> |
| |
