$Id$ The DocBook Project 2005-2007 The DocBook Project Refentry Metadata-Gathering Template Reference Introduction This is technical reference documentation for the "refentry metadata gathering" 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. Gathers metadata from a refentry and its ancestors 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 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. 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 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) <xsl:call-template name="get.refentry.title"> <xsl:with-param name="refname" select="$refname"/> </xsl:call-template>
Gets title metadata for a refentry 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. refname The first refname in the refentry Returns a title node. Gets section metadata for a refentry 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"]. refname The first refname in the refentry quiet If non-zero, no "missing" message is emitted Returns a string representing a section number. Note meta manvol no refentry/refmeta/manvolnum Note meta manvol see http://docbook.sf.net/el/manvolnum Note meta manvol Setting man section to 3 3 1 Gets date metadata for a refentry 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. 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 a date node. Note meta date no date; using generated date Note meta date see http://docbook.sf.net/el/date Gets source metadata for a refentry 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. 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 a source node. Warn meta source no valid fallback for source; leaving empty Warn meta source no source fallback specified; leaving empty Gets source-name metadata for a refentry 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. 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) 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. source source productname source productname source productname source productname source productname Note meta source no *info/productname or alternative Note meta source see http://docbook.sf.net/el/productname Note meta source no refentry/refmeta/refmiscinfo@class=source Note meta source see http://docbook.sf.net/el/refmiscinfo Gets version metadata for a refentry 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. 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) Depending on what output method is used for the current stylesheet, either returns a text node or possibly an element node, containing "version" data. version version productnumber version productnumber Note meta version no *info/productnumber or alternative Note meta version see http://docbook.sf.net/el/productnumber Note meta version no refentry/refmeta/refmiscinfo@class=version Note meta version see http://docbook.sf.net/el/refmiscinfo Gets source metadata for a refentry 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.
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 a manual node. manual manual Note meta manual no titled ancestor of refentry Note meta manual no refentry/refmeta/refmiscinfo@class=manual Note meta manual see http://docbook.sf.net/el/refmiscinfo Warn meta manual no valid fallback for manual; leaving empty Warn meta manual no manual fallback specified; leaving empty Gets user preferences for refentry metadata gathering 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. There are no local parameters for this template; however, it does rely on a number of global parameters. Returns a manual node. Sets content of a refentry metadata item The set.refentry.metadata template is called each time a suitable source element is found for a certain metadata field. 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 formatted contents of a selected source element. Note Note no refentry/refmeta/refmiscinfo@class= Note