X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/0c9c28efcd43f53ac54aa60b2dfefa69c70dbadf..6b6d9b29e9e9e91f79507a8bf193fb30de311dcc:/doc/help/xslt/common/refentry.xml diff --git a/doc/help/xslt/common/refentry.xml b/doc/help/xslt/common/refentry.xml new file mode 100644 index 00000000..4741ce0d --- /dev/null +++ b/doc/help/xslt/common/refentry.xml @@ -0,0 +1,781 @@ + + + + + Common » Refentry Metadata Template Reference + + $Id: refentry.xsl 7867 2008-03-07 09:54:25Z xmldoc $ + + + + + Introduction + +This is technical reference documentation for the “refentry + metadata” templates in the DocBook XSL Stylesheets. + + +This is not intended to be user documentation. It is provided + for developers writing customization layers for the stylesheets. + + + +Currently, only the manpages stylesheets make use of these + templates. They are, however, potentially useful elsewhere. + + + + + + +get.refentry.metadata +Gathers metadata from a refentry and its ancestors + + +<xsl:template name="get.refentry.metadata"> +<xsl:param name="refname"/> +<xsl:param name="info"/> +<xsl:param name="prefs"/> + ... +</xsl:template> + +Description + +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 refentry. + + + +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 + refentry itself, but instead part of the content of a + parent or ancestor element to the refentry. 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 productnumber element to mark up version + information about a particular product, while another might use + the releaseinfo element. + + + +Taking all that in mind, the + get.refentry.metadata template tries to gather + metadata from a refentry 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 refentry – either on the + refentry itself, or on its nearest ancestor. + + + + +The get.refentry.metadata + 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. + + + + Parameters + + + + refname + + +The first refname in the refentry + + + + + info + + +A set of info nodes (from a refentry + element and its ancestors) + + + + + prefs + + +A node containing user preferences (from global + stylesheet parameters) + + + + + + Returns + +Returns a node set with the following elements. The + descriptions are verbatim from the man(7) man + page. + + + + title + + +the title of the man page (e.g., MAN) + + + + + section + + +the section number the man page should be placed in (e.g., + 7) + + + + + date + + +the date of the last revision + + + + + source + + +the source of the command + + + + + manual + + +the title of the manual (e.g., Linux + Programmer's Manual) + + + + + + + + + + + +get.refentry.title +Gets title metadata for a refentry + + +<xsl:template name="get.refentry.title"> +<xsl:param name="refname"/> + ... +</xsl:template> + +Description + +The man(7) man page describes this as "the + title of the man page (e.g., MAN). This differs + from refname in that, if the refentry has a + refentrytitle, we use that as the title; + otherwise, we just use first refname in the first + refnamediv in the source. + + Parameters + + + + refname + + +The first refname in the refentry + + + + + + Returns + +Returns a title node. + + + + +get.refentry.section +Gets section metadata for a refentry + + +<xsl:template name="get.refentry.section"> +<xsl:param name="refname"/> +<xsl:param name="quiet" select="0"/> + ... +</xsl:template> + +Description + +The man(7) man page describes this as "the + section number the man page should be placed in (e.g., + 7)". If we do not find a manvolnum + specified in the source, and we find that the refentry is + for a function, we use the section number 3 + ["Library calls (functions within program libraries)"]; otherwise, we + default to using 1 ["Executable programs or shell + commands"]. + + Parameters + + + + refname + + +The first refname in the refentry + + + + + quiet + + +If non-zero, no "missing" message is emitted + + + + + + Returns + +Returns a string representing a section number. + + + + +get.refentry.date +Gets date metadata for a refentry + + +<xsl:template name="get.refentry.date"> +<xsl:param name="refname"/> +<xsl:param name="info"/> +<xsl:param name="prefs"/> + ... +</xsl:template> + +Description + +The man(7) man page describes this as "the + date of the last revision". If we cannot find a date in the source, we + generate one. + + Parameters + + + + refname + + +The first refname in the refentry + + + + + info + + +A set of info nodes (from a refentry + element and its ancestors) + + + + + prefs + + +A node containing users preferences (from global stylesheet parameters) + + + + + + Returns + +Returns a date node. + + + + + +get.refentry.source +Gets source metadata for a refentry + + +<xsl:template name="get.refentry.source"> +<xsl:param name="refname"/> +<xsl:param name="info"/> +<xsl:param name="prefs"/> + ... +</xsl:template> + +Description + +The man(7) man page describes this as "the + source of the command", and provides the following examples: + + + + +For binaries, use something like: GNU, NET-2, SLS + Distribution, MCC Distribution. + + + + +For system calls, use the version of the kernel that you are + currently looking at: Linux 0.99.11. + + + + +For library calls, use the source of the function: GNU, BSD + 4.3, Linux DLL 4.4.1. + + + + + + + + +The solbook(5) man page describes + something very much like what man(7) calls + "source", except that solbook(5) names it + "software" and describes it like this: +
+ +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 SunOS x.x + release. + +
+ + + + +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, + Name Version, + where: + + + + Name + + +product name (e.g., BSD) or org. name (e.g., GNU) + + + + + Version + + +version name + + + + + + Each part is optional. If the Name is a + product name, then the Version is probably + the version of the product. Or there may be no + Name, in which case, if there is a + Version, it is probably the version of the + item itself, not the product it is part of. Or, if the + Name is an organization name, then there + probably will be no Version. + + + Parameters + + + + refname + + +The first refname in the refentry + + + + + info + + +A set of info nodes (from a refentry + element and its ancestors) + + + + + prefs + + +A node containing users preferences (from global + stylesheet parameters) + + + + + + Returns + +Returns a source node. + + + + + +get.refentry.source.name +Gets source-name metadata for a refentry + + +<xsl:template name="get.refentry.source.name"> +<xsl:param name="refname"/> +<xsl:param name="info"/> +<xsl:param name="prefs"/> + ... +</xsl:template> + +Description + +A "source name" is one part of a (potentially) two-part + Name Version + source field. For more details, see the documentation for the + get.refentry.source template. + + Parameters + + + + refname + + +The first refname in the refentry + + + + + info + + +A set of info nodes (from a refentry + element and its ancestors) + + + + + prefs + + +A node containing users preferences (from global + stylesheet parameters) + + + + + + Returns + +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. + + + + + +get.refentry.version +Gets version metadata for a refentry + + +<xsl:template name="get.refentry.version"> +<xsl:param name="refname"/> +<xsl:param name="info"/> +<xsl:param name="prefs"/> + ... +</xsl:template> + +Description + +A "version" is one part of a (potentially) two-part + Name Version + source field. For more details, see the documentation for the + get.refentry.source template. + + Parameters + + + + refname + + +The first refname in the refentry + + + + + info + + +A set of info nodes (from a refentry + element and its ancestors) + + + + + prefs + + +A node containing users preferences (from global + stylesheet parameters) + + + + + + Returns + +Depending on what output method is used for the + current stylesheet, either returns a text node or possibly an element + node, containing "version" data. + + + + + +get.refentry.manual +Gets source metadata for a refentry + + +<xsl:template name="get.refentry.manual"> +<xsl:param name="refname"/> +<xsl:param name="info"/> +<xsl:param name="prefs"/> + ... +</xsl:template> + +Description + +The man(7) man page describes this as "the + title of the manual (e.g., Linux Programmer's + Manual)". Here are some examples from existing man pages: + + + + +dpkg utilities + (dpkg-name) + + + + +User Contributed Perl Documentation + (GET) + + + + +GNU Development Tools + (ld) + + + + +Emperor Norton Utilities + (ddate) + + + + +Debian GNU/Linux manual + (faked) + + + + +GIMP Manual Pages + (gimp) + + + + +KDOC Documentation System + (qt2kdoc) + + + + + + + + +The solbook(5) man page describes + something very much like what man(7) calls + "manual", except that solbook(5) names it + "sectdesc" and describes it like this: +
+ +This is the section title of the reference page; for + example User Commands. + +
+ + + + Parameters + + + + refname + + +The first refname in the refentry + + + + + info + + +A set of info nodes (from a refentry + element and its ancestors) + + + + + prefs + + +A node containing users preferences (from global + stylesheet parameters) + + + + + + Returns + +Returns a manual node. + + + + + +get.refentry.metadata.prefs +Gets user preferences for refentry metadata gathering + + +<xsl:template name="get.refentry.metadata.prefs"/> + +Description + +The DocBook XSL stylesheets include several user-configurable + global stylesheet parameters for controlling refentry + metadata gathering. Those parameters are not read directly by the + other refentry metadata-gathering + templates. Instead, they are read only by the + get.refentry.metadata.prefs template, + which assembles them into a structure that is then passed to + the other refentry metadata-gathering + templates. + + + +So the, get.refentry.metadata.prefs + template is the only interface to collecting stylesheet parameters for + controlling refentry metadata gathering. + + Parameters + +There are no local parameters for this template; however, it + does rely on a number of global parameters. + + Returns + +Returns a manual node. + + + + + +set.refentry.metadata +Sets content of a refentry metadata item + + +<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> + +Description + +The set.refentry.metadata template is + called each time a suitable source element is found for a certain + metadata field. + + Parameters + + + + refname + + +The first refname in the refentry + + + + + info + + +A single *info node that contains the selected source element. + + + + + contents + + +A node containing the selected source element. + + + + + context + + +A string describing the metadata context in which the + set.refentry.metadata template was + called: either "date", "source", "version", or "manual". + + + + + + Returns + +Returns formatted contents of a selected source element. + + +