Shaun McCance
shaunm@gnome.org 2008-2009
Create an overview of concepts.

# Synopses

    mal_block_synopsis = element synopsis {
      attribute style { xsd:NMTOKENS } ?,
      attribute * - (mal:* | local:*) { text } *,

      mal_block_title ?,
      mal_block_desc ?,
      mal_block +
    }

The `synopsis` element allows you to mark up a block as providing an overview of the material being presented. It 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.

Shaun McCance

Add explanation, examples

# Notas

The `synopsis` element contains 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 for more information on external-namespace attributes.

# Ejemplos

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.

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