Code and Commands

You can use the code element inside a paragraph to mark up a snippet of code. You will typically use code as an inline element to refer to something short like a function name or variable.

<p>Call the <code>bean_grow</code> function to grow your magic beans.</p>

You can use the code element for more than programming languages. Use the code element to mark up the name of an XML element, a key in a configuration file, or anything else you might find in a file you would edit in a text editor.

<p>Use the <code>code</code> element to mark up the name of an XML element.</p>

<p>Set the <code>Name</code> key to the name of your application.</p>

Use the cmd element to provide a command for a user to run in a command-line environment.

<p>Use <cmd>yelp-tool</cmd> to create HTML from your Mallard document.</p>

Sometimes you need to refer to options or arguments to commands. In Mallard, you mark up command arguments with the cmd element as well.

<p>Use the <cmd>-o</cmd> option to specify an output directory.</p>

Sometimes you need to provide multiple lines of code or file contents, or you may want to put a long line of code on its own line to make it easier to read. You can use the code element outside of a paragraph to create a code block.

<code>
if (bean_is_magic(bean)) {
  bean_grow(bean);
}
</code>

if (bean_is_magic(bean)) {
  bean_grow(bean);
}

The contents of your code block might contain special XML characters like <. You can write these with standard XML escape sequences like &lt;, but that can become cumbersome, especially when writing the contents of an XML file. Fortunately, XML provides a special syntax called CDATA to escape large amounts of text.

<code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="guide" id="index">
  <info>
    <!-- Page information goes here -->
  </info>
  <!-- Page contents go here -->
</page>
]]></code>

<page xmlns="http://projectmallard.org/1.0/"
      type="guide" id="index">
  <info>
    <!-- Page information goes here -->
  </info>
  <!-- Page contents go here -->
</page>

You can use the CDATA syntax anywhere you need to escape a lot of special characters. It is a standard XML feature, not specific to Mallard or code blocks.

If you need to provide a long command to your readers, you may want to show the command in its own block. Long commands can be difficult to read when embedded inline in a paragraph. You can use the screen element to show a command in a block.

<screen>
xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
  `pkg-config --variable mal2html.xsl yelp-xsl` \
  index.page
</screen>

xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
  `pkg-config --variable mal2html.xsl yelp-xsl` \
  index.page

You can also use the screen element to show commands along with their output. To mark up the input and output, use the input and output elements.

<screen>
<input>ls *.page</input>
<output>index.page  planting.page  uses.page</output>
</screen>

ls *.page
index.page  planting.page  uses.page

If you want to provide more complicated command-line sessions, you can use the style attribute on the output element to mark up prompts and error output.

<screen>
<output style="prompt">$ </output><input>ls *.page</input>
<output>index.page  planting.page  uses.page</output>
<output style="prompt">$ </output><input>rm uses.page</input>
<output style="prompt">$ </output><input>ls *.page</input>
<output>index.page  planting.page</output>
<output style="prompt">$ </output><input>rm uses.page</input>
<output style="error">rm: cannot remove `uses.page': No such file or directory</output>
</screen>

$ ls *.page
index.page  planting.page  uses.page
$ rm uses.page
$ ls *.page
index.page  planting.page
$ rm uses.page
rm: cannot remove `uses.page': No such file or directory

When you use code blocks to show the contents of a file, you often want to provide a name or title for the file. You can do this in introductory text in a paragraph before the code block, but displaying the title with the code block makes it more clear to the reader.

The code element takes inline content and treats all its contents as part of the code block, so you can't place a title inside the code element. Mallard provides the listing element to allow you to specify a title for code blocks and similiar content.

<listing>
<title><file>index.page</file></title>
<code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/
      type="guide" id="index">
  <info>
    <!-- Page information goes here -->
  </info>
  <!-- Page contents go here -->
</page>
]]></code>
</listing>

<page xmlns="http://projectmallard.org/1.0/
      type="guide" id="index">
  <info>
    <!-- Page information goes here -->
  </info>
  <!-- Page contents go here -->
</page>

The title is supplied by the title element. This example also uses the file element, an inline element that allows you to provide a file name.

You can also use the listing element around any other type of block content. For example, you can use the listing element to provide a title for a command inside a screen element.

<listing>
<title>Process a Mallard Document</title>
<screen>
xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
  `pkg-config --variable mal2html.xsl yelp-xsl` \
  index.page
</screen>
</listing>

xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
  `pkg-config --variable mal2html.xsl yelp-xsl` \
  index.page

Finally, you can also supply a short description for a listing using the desc element.

<listing>
<title>Process a Mallard Document</title>
<desc>Note that the <cmd>pkg-config</cmd> command is surrounded by backticks.</desc>
<screen>
xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
  `pkg-config --variable mal2html.xsl yelp-xsl` \
  index.page
</screen>
</listing>

xsltproc -o index.html --xinclude --stringparam mal.cache.file index.cache \
  `pkg-config --variable mal2html.xsl yelp-xsl` \
  index.page