From: Michael Smith Date: Mon, 4 Jul 2005 23:51:51 +0000 (+0000) Subject: Initial add. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=39dc5056f06c5b3481cd386638d4b3b404801055;p=docbook-dsssl Initial add. This file provides templates for gathering refentry metadata. The templates are currently only called by the manpages stylesheets, but they are designed to be generally useful. --- diff --git a/xsl/common/refentry.xsl b/xsl/common/refentry.xsl new file mode 100644 index 000000000..e23e70953 --- /dev/null +++ b/xsl/common/refentry.xsl @@ -0,0 +1,929 @@ + + + + + + + + + $Id$ + + The DocBook Project + 2005 + The DocBook Project + + + Refentry Metadata Gathering + + +
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 parent + + + 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 mark up that context information in + different ways. Often (usually), it is not actually part fo the + content of the refentry itself, but instead part of its + parent element's content. 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.info function tries to gather data + from a refentry element and its parent element in an + intelligent and user-configurable way. + + + The get.refentry.info is actually just + sort of a "driver" function; it calls other function that do that + actual data collection, the returns the data as a set. + + + The manpages stylesheets are an application of these APIs. + + + + + + refname + + The first refname in the refentry + + + + info + + An info node (from a refentry element) + + + + parentinfo + + An info node (from a parent of a refentry + element) + + + + prefs + + A node containing users 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"]. + + + [none] + + + Returns a section node. + + + + + + + 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. + + + + + + info + + An info node (from a refentry element) + + + + parentinfo + + An info node (from a parent of a refentry element) + + + + prefs + + A node containing users preferences (from global stylesheet parameters) + + + + + + Returns a date node. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + 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. + + + + + + + info + + An info node (from a refentry element) + + + + parentinfo + + An info node (from a parent of a refentry element) + + + + prefs + + A node containing users preferences (from global + stylesheet parameters) + + + + + + Returns a source node. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + info + + An info node (from a refentry element) + + + + parentinfo + + An info node (from a parent of a refentry element) + + + + 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. + + + + + + + + + + + using source.name profile + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + info + + An info node (from a refentry element) + + + + parentinfo + + An info node (from a parent of a refentry element) + + + + 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. + + + + + + + + + + + using version profile + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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) + + + + + + + + + info + + An info node (from a refentry element) + + + + parentinfo + + An info node (from a parent of a refentry element) + + + + prefs + + A node containing users preferences (from global + stylesheet parameters) + + + + + + Returns a manual node. + + + + + + + + + + + using manual profile + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 functions. Instead, they + are read only by the get.refentry.metadata.prefs + function, which assembles them into a structure that is then passed to + the other refentry metadata-gathering functions. + + So the, get.refentry.metadata.prefs + function is the only interface to collecting stylesheet parameters for + controlling refentry metadata gathering. + + + + There are no local parameters for this function; however, it + does rely on a number of global parameters. + + + Returns a manual node. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +