DocBook Website: The Definitive Guide  (Version 0.9.1 for DocBook Website 5.1)

example

example — A formal example, with a title.

Synopsis

example ::= [-]

Attributes

Common attributes and common linking attributes.

Additional attributes:

  • floatstyle
  • label
  • At most one of:
    • width (nonNegativeInteger)
    • pgwide (enumeration)
      • “0”
      • “1”

Additional Constraints

  • example must not occur among the children or descendants of example
  • figure must not occur among the children or descendants of example
  • table must not occur among the children or descendants of example

Description

An example is a formal example with a title. Examples often contain programlistings or other large block elements. Frequently, they are given xml: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.

If a label is specified, that label will be used for identifying the example and in generated cross-references. If unspecified, examples are often, but not always, numbered.

If a width is specified, formatters may use this value to determine scaling or rotation.

Attributes

Common attributes and common linking attributes.

floatstyle

Specifies style information to be used when rendering the float

label

Specifies an identifying string for presentation purposes

pgwide

Indicates if the element is rendered across the column or the page

Enumerated values:
“0”

The element should be rendered in the current text flow (with the flow column width).

“1”

The element should be rendered across the full text page.

width

Specifies the width (in characters) of the element

Children

The following elements occur in example: blockquote, caption (db.caption), epigraph, example, figure, html:form, info (db.titleforbidden.info), info (db.titleonlyreq.info), informaltable (db.cals.informaltable), informaltable (db.html.informaltable), itemizedlist, literallayout, mediaobject, note, orderedlist, para, programlisting, revhistory, sidebar, table (db.cals.table), table (db.html.table), title, titleabbrev, variablelist, webtoc.

Examples

<article xmlns='http://docbook.org/ns/docbook'>
<title>Example example</title>

<example xml:id="ex.dssslfunction">
<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>

</article>
Example 1. 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))))))