X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/793149f04ce52bf75dc4efb7b83a3f8ed30d1fff..35ec793690104efdd610964d255302a0310a2daf:/doc/xslt/common/refentry.xml diff --git a/doc/xslt/common/refentry.xml b/doc/xslt/common/refentry.xml deleted file mode 100644 index 4741ce0d..00000000 --- a/doc/xslt/common/refentry.xml +++ /dev/null @@ -1,781 +0,0 @@ - - - - - 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. - - -