Synopses

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the synopsis element to mark up a block that provides an overview of the material being presented. A synopsis is useful for providing a listing of functions, commands, or options in reference material, or for enumerating the items in a menu or other graphical control element.

Notes

The synopsis element contains an optional info element, an optional title element, an optional desc element, and any general block content.
The synopsis element can occur in any general block context, including inside pages, sections, and certain block elements.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The synopsis element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use synopsis to create an overview of functions:

<synopsis>
<title>Beanstalk Functions</title>
<desc>Use these methods on a <code>Beanstalk</code> object.</desc>
<code>
void add_bean    (Bean bean);
int  count_beans ();
</code>
</synopsis>

Beanstalk Functions

Use these methods on a beanstalk object.

void add_bean    (Bean bean);
int  count_beans ();

Processing Expectations

A synopsis element is rendered as a displayed block, with each of its child elements interpreted as block elements. Since a synopsis element often contains large blocks, and is generally offset from the running text, display tools may opt to render it inside a colored box, with a border, or otherwise differently from the surrounding text.

When present, the title and description should be displayed in a way that makes their respective roles clear.

The optional info element can provide metadata for the synopsis, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.

Comparison to Other Formats

The synopsis element is similar to the synopsis element in DocBook, although the DocBook element is not a formal element. DocBook also provides the cmdsynopsis and funcsynopsis elements, which attempt to model the data for command and function synopses, respectively. Mallard does not provide modeling elements. The various synopsis elements in DocBook output preformatted text, and are only useful for code. The synopsis element in Mallard allows any block content. Nest a code element for a code synopsis.

There is no direct equivalent to the synopsis element in DITA.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the synopsis element. The namespace declarations for this definition are on the page Pages.

mal_block_synopsis = element synopsis {
  mal_block_synopsis_attr,
  mal_info ?,
  mal_block_title ?,
  mal_block_desc ?,
  mal_block_synopsis_content +
}
mal_block_synopsis_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_synopsis_content = mal_block