# Refentry Metadata-Gathering Template Reference

###

$Id: refentry.xsl,v 1.4 2005/07/08 08:41:01 xmldoc Exp $

Copyright © 2005 by The DocBook Project. No Warranty.

## 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.

### Note

Currently, only the manpages stylesheets make use of these templates. They are, however, potentially useful elsewhere.

## Name

get.refentry.metadata — Gathers metadata from a refentry and its parent

## Synopsis

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

### Note

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.

Parameters

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

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)

## Name

get.refentry.title — Gets title metadata for a refentry

## Synopsis

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

Parameters

refname

  The first `refname` in the refentry

Returns

Returns a `title` node.

## Name

get.refentry.section — Gets section metadata for a refentry

## Synopsis

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

Parameters

[none]

Returns

Returns a `section` node.

## Name

get.refentry.date — Gets date metadata for a refentry

## Synopsis

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

Parameters

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

Returns a `date` node.

## Name

get.refentry.source — Gets source metadata for a refentry

## Synopsis

    <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:

- 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`.

Parameters

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

Returns a `source` node.

## Name

get.refentry.source.name — Gets source-name metadata for a refentry

## Synopsis

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

Parameters

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

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.

## Name

get.refentry.version — Gets version metadata for a refentry

## Synopsis

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

Parameters

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

Depending on what output method is used for the current stylesheet, either returns a text node or possibly an element node, containing "version" data.

## Name

get.refentry.manual — Gets source metadata for a refentry

## Synopsis

    <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:

- 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)

Parameters

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

Returns a `manual` node.

## Name

get.refentry.metadata.prefs — Gets user preferences for refentry metadata gathering

## Synopsis

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

Parameters

There are no local parameters for this function; however, it does rely on a number of global parameters.

Returns

Returns a `manual` node.