Code Blocks

This specification has been replaced by Mallard 1.1.

Use the code element to mark up a block of text from a computer language. This will typically be used for programming languages, markup languages, and configuration files; however, you may use code for the contents of any text file.

Use the var element inside a code element to indicate text that should be replaced by the user.

Notes

The code element can contain a mixture of text and any general inline elements. Whitespace is interpreted literally.
The code 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 mime attribute takes a valid MIME type. Processing tools may adjust their behavior for particular MIME types.
The code element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
The code element may also be used in an inline context. See Code Snippets for more information.
Use the code element inside a listing element to provide a title and description for the code block. This is frequently used to provide the name of the file whose contents are being shown.

Examples

Use code to mark up a class definition:

<code mime="text/x-c++src">
class BeanStalk {
public:
  void add_bean(Bean bean);
  int count_beans();
}</code>

class BeanStalk {
public:
  void add_bean(Bean bean);
  int count_beans();
}

Processing Expectations

Code blocks are displayed verbatim, with all whitespace and line breaks reproduced in the rendered output. The only exception is a single leading line break, which is stripped by display tools if present. Display tools only strip a leading line break in an initial text node. They are not expected to strip line breaks from child elements.

Code blocks are displayed in a fixed-width font. Inline markup may cause style variations, but they do not cause a change to a variable-width font.

Comparison to Other Formats

The code element is similar to the programlisting element in DocBook. DocBook also contains numerous elements for modeling code in procedural and object-oriented programming languages. Many of these elements can be seen by browsing the content models for the classsynopsis and funcsynopsis elements. Mallard does not attempt to model any programming languages.

The code element is similar to the codeblock 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 block code element. The namespace declarations for this definition are on the page Pages.

mal_block_code = element code {
  mal_block_code_attr,
  mal_block_code_inline
}
mal_block_code_attr = (
  attribute style { xsd:NMTOKENS } ?,
  attribute mime { text } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_code_inline = mal_inline