| DocBook: The Definitive Guide Version 2.0.8 (Alpha)

# example

$Revision: 1.3 $

$Date: 2002/06/12 11:18:10 $

example — A formal example, with a title

## Synopsis

### Content Model

    example ::=
    (blockinfo?,
     (title,titleabbrev?),
     (calloutlist|glosslist|itemizedlist|orderedlist|segmentedlist|
      simplelist|variablelist|literallayout|programlisting|
      programlistingco|screen|screenco|screenshot|synopsis|
      cmdsynopsis|funcsynopsis|classsynopsis|fieldsynopsis|
      constructorsynopsis|destructorsynopsis|methodsynopsis|
      formalpara|para|simpara|address|blockquote|graphic|graphicco|
      mediaobject|mediaobjectco|informalequation|informalexample|
      informalfigure|informaltable|indexterm|beginpage)+)

### Attributes

Common attributes

Name | Type | Default
width | CDATA | None
label | CDATA | None

## Description

`Example` is a formal example with a title. Examples often contain `ProgramListing`s or other large, block elements. Frequently they are given IDs and referenced from the text with `XRef` or `Link`.

### Processing expectations

Formatted as a displayed block. DocBook does not specify the location of the example within the final displayed flow of text; it may float or remain where it is located.

A list of examples may be generated at the beginning of a document.

### Parents

These elements contain example: `answer`, `appendix`, `article`, `bibliodiv`, `bibliography`, `blockquote`, `callout`, `caution`, `chapter`, `constraintdef`, `glossary`, `glossdef`, `glossdiv`, `important`, `index`, `listitem`, `msgexplan`, `msgtext`, `note`, `para`, `partintro`, `preface`, `procedure`, `qandadiv`, `qandaset`, `question`, `refsect1`, `refsect2`, `refsect3`, `refsection`, `refsynopsisdiv`, `revdescription`, `sect1`, `sect2`, `sect3`, `sect4`, `sect5`, `section`, `setindex`, `sidebar`, `simplesect`, `step`, `tip`, `warning`.

### Children

The following elements occur in example: `address`, `beginpage`, `blockinfo`, `blockquote`, `calloutlist`, `classsynopsis`, `cmdsynopsis`, `constructorsynopsis`, `destructorsynopsis`, `fieldsynopsis`, `formalpara`, `funcsynopsis`, `glosslist`, `graphic`, `graphicco`, `indexterm`, `informalequation`, `informalexample`, `informalfigure`, `informaltable`, `itemizedlist`, `literallayout`, `mediaobject`, `mediaobjectco`, `methodsynopsis`, `orderedlist`, `para`, `programlisting`, `programlistingco`, `screen`, `screenco`, `screenshot`, `segmentedlist`, `simpara`, `simplelist`, `synopsis`, `title`, `titleabbrev`, `variablelist`.

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

width

  `Width` specifies the width (in characters) of the longest line in this `Example` (formatters may use this value to determine scaling or rotation).

## See Also

`equation`, `figure`, `informalequation`, `informalexample`, `informalfigure`, `informaltable`, `table`.

## Examples

    <!DOCTYPE example PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <example><title>A DSSSL Function</title>
    <programlisting>
    (define (node-list-filter-by-gi nodelist gilist)
      ;; Returns the node-list that contains every element of the original
      ;; nodelist whose gi is in gilist
      (let loop ((result (empty-node-list)) (nl nodelist))
        (if (node-list-empty? nl)
        result
        (if (member (gi (node-list-first nl)) gilist)
            (loop (node-list result (node-list-first nl))
              (node-list-rest nl))
            (loop result (node-list-rest nl))))))
    </programlisting>
    </example>

Example 31. A DSSSL Function

    (define (node-list-filter-by-gi nodelist gilist)
      ;; Returns the node-list that contains every element of the original
      ;; nodelist whose gi is in gilist
      (let loop ((result (empty-node-list)) (nl nodelist))
        (if (node-list-empty? nl)
        result
        (if (member (gi (node-list-first nl)) gilist)
            (loop (node-list result (node-list-first nl))
              (node-list-rest nl))
            (loop result (node-list-rest nl))))))

For additional examples, see also `remark`.

errortype |  | exceptionname

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