Code Snippets

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 portion of text from a computer language. This includes programming languages, markup languages, and the contents of any type of file with a structured syntax. For commands which are run in an interactive shell, however, you should use the cmd element, even though they may include snippets of shell programming.

You can use the code element to mark up any portion of code, including comments or textual content that doesn't strictly follow any syntax.

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.
The code element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The code element can link to other pages or documents. See Ubiquitous Linking for more information.
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 a block context. See Code Blocks for more information.

Examples

Use code to mark up the name of a function, struct, or other construct in a programming language:

Use <code>gtk_container_add</code> to add a child widget to a
<code>GtkButton</code>.

Use gtk_container_add to add a child widget to a GtkButton.

Use code with var to mark up code with a placeholder for an argument the user should supply:

To create a new button with a label, use
<code>gtk_button_new_with_label(<var>label</var>)</code>,
replacing <var>label</var> with the text of the label.

To create a new button with a label, use gtk_button_new_with_label(label), replacing label with the text of the label.

Link to a web page directly with a code element:

Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark
up code with a placeholder for an argument the user should supply.

Use code with var to mark up code with a placeholder for an argument the user should supply.

Processing Expectations

Code snippets are displayed in a fixed-width font. This mimics the look of a typical environment where code is typed. More importantly, fixed-width fonts tend to have more distinction between visually similar characters. This is particularly important in code, since letters often appear without the context of a known word that helps make them discernible in normal prose.

For particularly long code snippets, display tools may use a background color or border to make the beginning and end clear, although authors should prefer code blocks for long code snippets.

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 code element in DocBook. Since Mallard does not attempt to model programming languages, the code element may be used in place of numerous DocBook elements, including classname, constant, function, interfacename, methodname, parameter, and varname. Additionally, since Mallard does not provide separate elements for marking portions of markup languages, the code element should be used in place of the DocBook elements markup and tag.

The code element is similar to the codeph element in DITA. Since Mallard does not contain specializations for different types of code, the code element may be used in place of DITA elements like apiname.

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

mal_inline_code = element code {
  mal_inline_code_attr,
  mal_inline_code_inline
}
mal_inline_code_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  attribute type { xsd:NMTOKENS } ?,
  attribute mime { text } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_code_inline = mal_inline