Refentry Metadata-Gathering Template Reference

<xsl:template name="get.refentry.metadata">
<xsl:param name="refname"/>
<xsl:param name="info"/>
<xsl:param name="parentinfo"/>
<xsl:param name="prefs"/>
  ...
</xsl:template>

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 manpages stylesheets are an application of these APIs.

<xsl:template name="get.refentry.title">
<xsl:param name="refname"/>
  ...
</xsl:template>

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.

<xsl:template name="get.refentry.section"/>

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"].

<xsl:template name="get.refentry.date">
<xsl:param name="info"/>
<xsl:param name="parentinfo"/>
<xsl:param name="prefs"/>
  ...
</xsl:template>

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.

<xsl:template name="get.refentry.source">
<xsl:param name="info"/>
<xsl:param name="parentinfo"/>
<xsl:param name="prefs"/>
  ...
</xsl:template>

The man(7) man page describes this as "the source of the command", and provides the following examples:

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:

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.

<xsl:template name="get.refentry.source.name">
<xsl:param name="info"/>
<xsl:param name="parentinfo"/>
<xsl:param name="prefs"/>
  ...
</xsl:template>

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.

<xsl:template name="get.refentry.version">
<xsl:param name="info"/>
<xsl:param name="parentinfo"/>
<xsl:param name="prefs"/>
  ...
</xsl:template>

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.

<xsl:template name="get.refentry.manual">
<xsl:param name="info"/>
<xsl:param name="parentinfo"/>
<xsl:param name="prefs"/>
  ...
</xsl:template>

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:

<xsl:template name="get.refentry.metadata.prefs"/>

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.