diff options
Diffstat (limited to 'stylesheets/lfs-xsl/docbook-xsl-1.78.1/common/refentry.xml')
| -rw-r--r-- | stylesheets/lfs-xsl/docbook-xsl-1.78.1/common/refentry.xml | 781 |
1 files changed, 0 insertions, 781 deletions
diff --git a/stylesheets/lfs-xsl/docbook-xsl-1.78.1/common/refentry.xml b/stylesheets/lfs-xsl/docbook-xsl-1.78.1/common/refentry.xml deleted file mode 100644 index 4741ce0da..000000000 --- a/stylesheets/lfs-xsl/docbook-xsl-1.78.1/common/refentry.xml +++ /dev/null @@ -1,781 +0,0 @@ -<?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> - |