Page Descriptions

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

Use the desc element to provide a short description for a page or section. This description is generally not shown on the page itself, but it is used in automatic links to the page or section. It may also be used for various other purposes by different tools.

Notes

The desc element can contain a mixture of text and any general inline elements.
The desc element can occur in any info element.
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 desc element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
The desc element can also be used in a block context. See Block Descriptions for more information.

Examples

Create a page with a title and description:

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="mal_info_desc">
<info>
  <desc>Provide a short description of a page or section.</desc>
</info>
<title>Page Descriptions</title>
</page>

Processing Expectations

The desc element is not necessarily displayed on the page in which it appears. It is, however, used for automatic links, which often display a link block showing the title and description of the linked-to page or section. When it is displayed, its contents are treated as inline content.

Comparison to Other Formats

There is no direct equivalent to the informational desc element in DocBook. When used in an info element, the abstract element may be used for a similar purpose, although it is a formal element without the same processing expectations.

There is no direct equivalent to the informational desc element in DITA. The shortdesc element may contain similar text, but it is always part of the main body of a topic, rather than part of the metadata.

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 informational desc element. The namespace declarations for this definition are on the page Pages.

mal_info_desc = element desc {
  mal_info_desc_attr,
  mal_info_desc_inline
}
mal_info_desc_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_info_desc_inline = mal_inline