Shaun McCance
shaunm@gnome.org 2008-2009
Mark up code from a programming, markup, or other machine-readable format.

# Code Snippets

    mal_inline_code = element code {
      mal_attr_link ?,
      attribute style { xsd:NMTOKENS } ?,
      attribute mime { text } ?,
      attribute * - (mal:* | local:*) { text } *,

      mal_inline
    }

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.

# Notas

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

The `code` element may also be used in a block context. See for more information.

# Ejemplos

Use `code` to mark up the name of a function, struct, or other constuct 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 discernable 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.

# Comparison to Other Formats

The `code` element is similar to the `code` element in DocBook. Since Mallard does not attempt to model programming languages, `code` may be used in place of numerous DocBook elements, including `classname`, `constant`, `function`, `interfacename`, `methodname`, `parameter`, `structfield`, `structname`, 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 `sgmltag`.