Code Blocks

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

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 type attribute takes a space-separated list of tokens indicating the content type. Processing tools may adjust their behavior based on any of the tokens.
The mime attribute is deprecated and replaced by the type attribute. It 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 type="cpp">
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.

The type and mime attributes may be used for syntax highlighting or other type-specific formatting. The mime attribute is deprecated in favor of the type attribute. The mime attribute takes a MIME type. The type attribute takes a space-separated list of tokens indicating the content type. Processing tools should select the most specific token that they can work with.

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 type { xsd:NMTOKENS } ?,
  attribute mime { text } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_code_inline = mal_inline