para
Prev | DocBook Element Reference | Next

This is an alpha version of this book.

# para

## Name

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|link|olink|ulink|action|
     application|classname|methodname|interfacename|exceptionname|
     ooclass|oointerface|ooexception|command|computeroutput|database|
     email|envar|errorcode|errorname|errortype|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

### Parameter Entities

The following parameter entities contain para:

Parameter Entities
`%admon.mix;` | `%bookcomponent.content;` | `%component.mix;`
`%divcomponent.mix;` | `%example.mix;` | `%footnote.mix;`
`%glossdef.mix;` | `%highlights.mix;` | `%indexdivcomponent.mix;`
`%legalnotice.mix;` | `%para.class;` | `%qandaset.mix;`
`%refcomponent.mix;` | `%revdescription.mix;` | `%sidebar.mix;`
`%tabentry.mix;` | `%tbl.entry.mdl;` | `%textobject.mix;`

## 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`, `legalnotice`, `listitem`, `msgexplan`, `msgtext`, `note`, `partintro`, `preface`, `printhistory`, `procedure`, `qandadiv`, `qandaset`, `question`, `refsect1`, `refsect2`, `refsect3`, `refsynopsisdiv`, `revdescription`, `sect1`, `sect2`, `sect3`, `sect4`, `sect5`, `section`, `setindex`, `sidebar`, `simplesect`, `step`, `textobject`, `tip`, `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`, `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`, `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.