| DocBook: The Definitive Guide 2.0.17 (Alpha)

# reference

$Revision: 1666 $

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

reference — A collection of reference entries

## Synopsis

### Content Model

    reference ::=
    (beginpage?,referenceinfo?,
     (title,subtitle?,titleabbrev?),
     partintro?,
     (refentry)+)

### Attributes

Common attributes

Name | Type | Default
status | CDATA | None
label | CDATA | None

## Description

A `Reference` is a collection of `RefEntry`s. In a `Book`, a `Reference` can occur at either the `Part` or `Chapter` level.

Reference pages are usually bound together by topic; in traditional UNIX documentation they are most frequently bound into volumes. See `ManVolNum`.

### Processing expectations

Formatted as a displayed block. `References`s often introduce a forced page break and may start on the next recto page. Frequently, they also produce a separator page, on which may be printed the content of the `PartIntro`.

### Parents

These elements contain reference: `book`, `part`.

### Children

The following elements occur in reference: `beginpage`, `partintro`, `refentry`, `referenceinfo`, `subtitle`, `title`, `titleabbrev`.

## Attributes

label

  `Label` specifies an identifying string for presentation purposes.

  Generally, an explicit `Label` attribute is used only if the processing system is incapable of generating the label automatically. If present, the `Label` is normative; it will used even if the processing system is capable of automatic labelling.

status

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

  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

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

    <reference><title>Reference Pages</title>

    <refentry>
    <refnamediv>
    <refdescriptor>GNU as</refdescriptor>
    <refname>as</refname>
    <refpurpose>the portable GNU assembler</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>SYNOPSIS</title>
    <synopsis>...</synopsis>
    </refsynopsisdiv>
    <refsect1><title>DESCRIPTION</title>
    <para>...</para>
    </refsect1>
    </refentry>

    <refentry>
    <refnamediv>
    <refname>awk</refname>
    <refpurpose>pattern scanning and text processing language</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>SYNOPSIS</title>
    <synopsis>...</synopsis>
    </refsynopsisdiv>
    <refsect1><title>DESCRIPTION</title>
    <para>...</para>
    </refsect1>
    </refentry>

    <!-- ... -->

    </reference>

refentrytitle |  | referenceinfo

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