para
Prev | DocBook Element Reference | Next

This is an alpha version of this book.

# para

para — A paragraph

## Synopsis

### Mixed Content Model

    para ::=
    (#PCDATA|footnoteref|xref|abbrev|acronym|citation|citerefentry|
     citetitle|emphasis|firstterm|foreignphrase|glossterm|footnote|
     phrase|quote|trademark|wordasword|personname|link|olink|ulink|
     action|application|classname|methodname|interfacename|
     exceptionname|ooclass|oointerface|ooexception|command|
     computeroutput|database|email|envar|errorcode|errorname|
     errortype|errortext|filename|function|guibutton|guiicon|guilabel|
     guimenu|guimenuitem|guisubmenu|hardware|interface|keycap|keycode|
     keycombo|keysym|literal|constant|markup|medialabel|menuchoice|
     mousebutton|option|optional|parameter|prompt|property|
     replaceable|returnvalue|sgmltag|structfield|structname|symbol|
     systemitem|token|type|userinput|varname|nonterminal|anchor|
     author|authorinitials|corpauthor|modespec|othercredit|
     productname|productnumber|revhistory|remark|subscript|
     superscript|inlinegraphic|inlinemediaobject|inlineequation|
     synopsis|cmdsynopsis|funcsynopsis|classsynopsis|fieldsynopsis|
     constructorsynopsis|destructorsynopsis|methodsynopsis|indexterm|
     beginpage|calloutlist|glosslist|itemizedlist|orderedlist|
     segmentedlist|simplelist|variablelist|caution|important|note|tip|
     warning|literallayout|programlisting|programlistingco|screen|
     screenco|screenshot|address|blockquote|graphic|graphicco|
     mediaobject|mediaobjectco|informalequation|informalexample|
     informalfigure|informaltable|equation|example|figure|table)*

### Attributes

Common attributes

## Description

A `Para` is a paragraph. Paragraphs in DocBook may contain almost all inlines and most block elements. Sectioning and higher-level structural elements are excluded. DocBook offers two variants of paragraph: `SimPara`, which cannot contain block elements, and `FormalPara`, which has a title.

Some processing systems may find the presence of block elements in a paragraph difficult to handle. On the other hand, it is frequently most logical, from a structural point of view, to include block elements, especially informal block elements, in the paragraphs that describe their content. There is no easy answer to this problem.

### Processing expectations

Formatted as a displayed block.

### Future Changes

The `InterfaceDefinition` element will be discarded in DocBook V4.0. It will no longer be available in the content model of this element.

### Parents

These elements contain para: `abstract`, `answer`, `appendix`, `article`, `authorblurb`, `bibliodiv`, `bibliography`, `blockquote`, `callout`, `caption`, `caution`, `chapter`, `colophon`, `constraintdef`, `dedication`, `entry`, `epigraph`, `example`, `footnote`, `formalpara`, `glossary`, `glossdef`, `glossdiv`, `highlights`, `important`, `index`, `indexdiv`, `informalexample`, `itemizedlist`, `legalnotice`, `listitem`, `msgexplan`, `msgtext`, `note`, `orderedlist`, `partintro`, `personblurb`, `preface`, `printhistory`, `procedure`, `qandadiv`, `qandaset`, `question`, `refsect1`, `refsect2`, `refsect3`, `refsection`, `refsynopsisdiv`, `revdescription`, `sect1`, `sect2`, `sect3`, `sect4`, `sect5`, `section`, `setindex`, `sidebar`, `simplesect`, `step`, `textobject`, `tip`, `variablelist`, `warning`.

### Children

The following elements occur in para: `abbrev`, `acronym`, `action`, `address`, `anchor`, `application`, `author`, `authorinitials`, `beginpage`, `blockquote`, `calloutlist`, `caution`, `citation`, `citerefentry`, `citetitle`, `classname`, `classsynopsis`, `cmdsynopsis`, `command`, `computeroutput`, `constant`, `constructorsynopsis`, `corpauthor`, `database`, `destructorsynopsis`, `email`, `emphasis`, `envar`, `equation`, `errorcode`, `errorname`, `errortext`, `errortype`, `example`, `exceptionname`, `fieldsynopsis`, `figure`, `filename`, `firstterm`, `footnote`, `footnoteref`, `foreignphrase`, `funcsynopsis`, `function`, `glosslist`, `glossterm`, `graphic`, `graphicco`, `guibutton`, `guiicon`, `guilabel`, `guimenu`, `guimenuitem`, `guisubmenu`, `hardware`, `important`, `indexterm`, `informalequation`, `informalexample`, `informalfigure`, `informaltable`, `inlineequation`, `inlinegraphic`, `inlinemediaobject`, `interface`, `interfacename`, `itemizedlist`, `keycap`, `keycode`, `keycombo`, `keysym`, `link`, `literal`, `literallayout`, `markup`, `medialabel`, `mediaobject`, `mediaobjectco`, `menuchoice`, `methodname`, `methodsynopsis`, `modespec`, `mousebutton`, `nonterminal`, `note`, `olink`, `ooclass`, `ooexception`, `oointerface`, `option`, `optional`, `orderedlist`, `othercredit`, `parameter`, `personname`, `phrase`, `productname`, `productnumber`, `programlisting`, `programlistingco`, `prompt`, `property`, `quote`, `remark`, `replaceable`, `returnvalue`, `revhistory`, `screen`, `screenco`, `screenshot`, `segmentedlist`, `sgmltag`, `simplelist`, `structfield`, `structname`, `subscript`, `superscript`, `symbol`, `synopsis`, `systemitem`, `table`, `tip`, `token`, `trademark`, `type`, `ulink`, `userinput`, `variablelist`, `varname`, `warning`, `wordasword`, `xref`.

## See Also

`formalpara`, `simpara`.

## Examples

Ordinary paragraphs can contain most block elements:

    <!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <para>
    The component suffered from three failings:
    <itemizedlist>
    <listitem><para>It was slow</para></listitem>
    <listitem><para>It ran hot</para></listitem>
    <listitem><para>It didn't actually work</para></listitem>
    </itemizedlist>
    Of these three, the last was probably the most important.
    </para>

The component suffered from three failings:

- It was slow

- It ran hot

- It didn't actually work

Of these three, the last was probably the most important.

Formal paragraphs include a title:

    <!DOCTYPE formalpara PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <formalpara><title>A Test</title>
    <para>
    This is a test.  This is only a test.  Had this been a real
    example, it would have made more sense.
    </para>
    </formalpara>

A Test.

This is a test. This is only a test. Had this been a real example, it would have made more sense.

Simple paragraphs may not contain block elements:

    <!DOCTYPE simpara PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <simpara>
    Just the text, ma'am.
    </simpara>

Just the text, ma'am.

Prev | Home | Next
pagenums | Up | paramdef

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