| DocBook: The Definitive Guide 2.0.17 (Alpha)

# refentry

$Revision: 1666 $

$Date: 2002-06-12 07:19:37 -0400 (Wed, 12 Jun 2002) $

refentry — A reference page (originally a UNIX man-style reference page)

## Synopsis

### Content Model

    refentry ::=
    (beginpage?,
     (indexterm)*,
     refentryinfo?,refmeta?,
     (remark|link|olink|ulink)*,
     refnamediv+,refsynopsisdiv?,
     (refsect1+|refsection+))

### Attributes

Common attributes

Name | Type | Default
status | CDATA | None

## Description

A `RefEntry` is a reference page. In UNIX parlance this has historically been called a “man page” (short for manual page).

`RefEntry` is an appropriate wrapper for any small unit of reference documentation describing a single topic. Canonical examples are programming language functions and user commands (one `RefEntry` per function or command).[20]

On some projects, the structure of reference pages may be rigorously defined right down to the number, order, and title of individual sections (some or all of which may be required).

### Processing expectations

Formatted as a displayed block. It is not uncommon for `RefEntry`s to introduce a forced page break in print media.

Formatting reference pages may require a fairly sophisticated processing system. Much of the meta-information about a reference page (its name, type, purpose, title, and classification) is stored in wrappers near the beginning of the `RefEntry`.

Common presentational features, such as titles and running heads, may require data from several of these wrappers plus some generated text. Other formatting often requires that these elements be reordered.

### Parents

These elements contain refentry: `appendix`, `article`, `chapter`, `part`, `partintro`, `preface`, `reference`, `sect1`, `sect2`, `sect3`, `sect4`, `sect5`, `section`.

### Children

The following elements occur in refentry: `beginpage`, `indexterm`, `link`, `olink`, `refentryinfo`, `refmeta`, `refnamediv`, `refsect1`, `refsection`, `refsynopsisdiv`, `remark`, `ulink`.

## Attributes

status

  `Status` identifies the editorial or publication status of the `RefEntry`.

  Publication status might be used to control formatting (for example, printing a “draft” watermark on drafts) or processing (perhaps a document with a status of “final” should not include any components that are not final).

## Examples

A typical reference page for a command:

    <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <refentry id="ls">

    <refmeta>
    <refentrytitle>ls</refentrytitle>
    <manvolnum>1</manvolnum>
    </refmeta>

    <refnamediv>
    <refname>ls</refname>
    <refpurpose>list contents of a directory</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
    <cmdsynopsis>
    <command>/usr/bin/ls</command>
    <arg choice="opt">
      <option>aAbcCdfFgilLmnopqrRstux1</option>
    </arg>
    <arg choice="opt" rep="repeat">file</arg>
    </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1><title>Description</title>
    <para>
    For each file that is a directory, <command>ls</command> lists the contents of
    the directory; for each file that is an ordinary file, <command>ls</command>
    repeats its name and any other information requested.
    </para>
    <para>&hellip;</para>
    </refsect1>
    </refentry>

A typical reference page for a function:

    <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <refentry id="printf">

    <refmeta>
    <refentrytitle>printf</refentrytitle>
    <manvolnum>3S</manvolnum>
    </refmeta>

    <refnamediv>
    <refname>printf</refname>
    <refname>fprintf</refname>
    <refname>sprintf</refname>
    <refpurpose>print formatted output</refpurpose>
    </refnamediv>

    <refsynopsisdiv>

    <funcsynopsis>
    <funcsynopsisinfo>
    #include &lt;stdio.h&gt;
    </funcsynopsisinfo>
    <funcprototype>
      <funcdef>int <function>printf</function></funcdef>
      <paramdef>const char *<parameter>format</parameter></paramdef>
      <paramdef>...</paramdef>
    </funcprototype>

    <funcprototype>
      <funcdef>int <function>fprintf</function></funcdef>
      <paramdef>FILE *<parameter>strm</parameter></paramdef>
      <paramdef>const char *<parameter>format</parameter></paramdef>
      <paramdef>...</paramdef>
    </funcprototype>

    <funcprototype>
      <funcdef>int <function>sprintf</function></funcdef>
      <paramdef>char *<parameter>s</parameter></paramdef>
      <paramdef>const char *<parameter>format</parameter></paramdef>
      <paramdef>...</paramdef>
    </funcprototype>
    </funcsynopsis>

    </refsynopsisdiv>

    <refsect1><title>Description</title>
    <para>
    <function>printf</function> places output on the standard
    output stream stdout.
    </para>
    <para>&hellip;</para>
    </refsect1>
    </refentry>

A reference page for a data structure:

    <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <refentry id="iovec">

    <refmeta>
    <refentrytitle>iovec</refentrytitle>
    <manvolnum>9S</manvolnum>
    </refmeta>

    <refnamediv>
    <refname>iovec</refname>
    <refpurpose>data storage structure for I/O using uio</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
    <synopsis>
    #include &lt;sys/uio.h&gt;
    </synopsis>
    </refsynopsisdiv>

    <refsect1><title>Interface Level</title>
    <para>
    Architecture independent level 1 (DDI/DKI).
    </para>
    </refsect1>

    <refsect1><title>Description</title>

    <para>
    An <structname>iovec</structname> structure describes a data
    storage area for transfer in a
    <citerefentry><refentrytitle>uio</refentrytitle>
      <manvolnum>9S</manvolnum>
    </citerefentry>
    structure. Conceptually,
    it may be thought of as a base address and length specification.
    </para>

    </refsect1>
    <refsect1><title>Structure Members</title>

    <programlisting>
         caddr_t  iov_base;  /* base address of the data storage area */
                             /* represented by the iovec structure */
         int      iov_len;   /* size of the data storage area in bytes */
    </programlisting>

    <para>&hellip;</para>
    </refsect1>
    </refentry>

For additional examples, see also `reference`.

[20] You're reading a `RefEntry` right now.

refdescriptor |  | refentryinfo

Copyright © 1999, 2000, 2001, 2002, 2003 O'Reilly & Associates, Inc. All rights reserved.