Revision as of 15:27, 8 August 2013

DocBook markup conventions

This page offers writing conventions for OpenStack documentation. Following conventions helps to enhance the readabilty of our docs by enabling the DocBook stylesheets to format them consistently. Please modify this page as you come across more markup you need for the docs.openstack.org site.

General authoring conventions

This section contains general guidelines for editing OpenStack documents in DocBook.

Maximum line length in verbatim text

When using verbatim elements (including literallayout, programlisting, screen, and synopsis), do not exceed a line length of 70 characters.

Boolean configuration options

When documenting boolean configuration options, explicitly include the truth value.

Correct example

force_dhcp_release=True
use_ipv6=False

Incorrect example

force_dhcp_release
nouse_ipv6

Sections

Add IDs to sections

All section tags must have an xml:id attribute. This enables unique file names for the generated HTML and human-readable page titles, plus it lets Disqus threads stay with the HTML page.

Example

<section xml:id="section-id-goes-here">
...
</section>

Keeping sections together

To keep several sections on a single HTML page, use the DocBook stop_chunking processing instruction:

Example

<section xmlns="http://docbook.org/ns/docbook"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
    xml:id="xapi-resize-setup">
<?dbhtml stop-chunking?>
<title>Dom Modifications for Resize/Migration Support</title>
 ...

euca2ools documentation

Since Nova exposes both its own API and an EC2-compatible API, many tasks can be executed using either the nova CLI or euca2ools. Documentation related to euca2ools should generally be limited to:

   * Describing euca2ools commands that don't yet have a nova CLI equivalent (e.g., euca-get-console-output)
   * Describing how to get credentials to work with euca2ools
   * Describing differences between how Amazon's EC2 endpoint behaves and how an OpenStack endpoint behaves when accessing via EC2.

Adding a line break

In verbatim elements, you explicitly control line breaks. In the output of non-verbatim block elements (such as paragraphs and table cells), lines normally break automatically, for example at a fixed page or table boundary or when the reader resizes an HTML page. Automatic line breaking can fail if the text contains long strings that contain no whitespace. When that happens, the text is clipped or overflows the page or table boundaries.

If a line fails to break normally, try adding whitespace (like spaces) in the source where you want to allow line breaks. If that method is not available, you can force a line break anywhere in text by inserting the <?sbr?> processing instruction.

Example In the first line of code, spaces around the equals signs enable the line to wrap at either location. In the second line, <?sbr?> forces a line break.

<programlisting>
compute_driver = nova.virt.baremetal.driver.BareMetalDriver
scheduler_host_manager=nova.scheduler.baremetal_host_manager.<?sbr?>BaremetalHostManager
</programlisting>

Tagging

Choosing the right tags (or at least agreeing to use the same tags) is important for using DocBook effectively. Otherwise, readers get inconsistent visual cues in the output formatting. You can check the semantic description of any tag in Oxygen. This section tries to identify circumstances where multiple tags might work or where the choice of tags is not obvious, and suggests an appropriate tagging.

Code or data (block)

Use tag: programlisting

Program source or source fragments formatted as a standalone block. (For inline source fragments use the code element). Content is displayed verbatim, so whitespace is significant, including spaces, tabs, and line breaks. Text is usually displayed in a fixed-width font.

Example

<programlisting>config-file-example=asdf
foo=bar
hello=world</programlisting>

To optimize the output of programlisting for a specific programming language, use the language attribute. Valid language values include bash, java, json, and xml.

Examples

<programlisting language="json"><xi:include href="samples/agents-put-res.json" parse="text"/></programlisting>

<programlisting language="bash" linenumbering="unnumbered">CACHES = {
  'default': {
    'BACKEND' : 'django.core.cache.backends.memcached.MemcachedCache',
    'LOCATION' : '127.0.0.1:11211'
  }
}
</programlisting>

Code or data (inline)

Use tag: literal

A fragment of code within a line of text. If you are instructing users to enter the code or data, consider userinput instead of literal.

Examples

<para>The file contains the default setting, <literal>use_syslog = True</literal>.</para>
  
<para>The owner is typically set to <literal>root:nova</literal>, and the mode set to <literal>0640</literal>.</para>

User input

Use tag: userinput

Text that you instruct or intend users to enter. Compare to code or programlisting, which simply shows an instance of code or data, without telling users to enter it.

You can insert a short userinput into a line of text (such as a para). For multiline input, embed userinput in a screen element, where you can insert line breaks to create each line.

Example

<para>Enter <userinput>admin</userinput> for the username and <userinput>secret</userinput> as the password.</para

See Computer output for a multiline example.

Computer output

Use tag: computeroutput

Text displayed in a terminal or log file as the result of a command. You can insert a short computeroutput string into a line of text. For multi-line input, embed computeroutput in a screen element, inserting line breaks to create each line.

Example

This example of an interactive session in a terminal combines a prompt, user input, and the resulting computer output in a screen:

<para>Mount the image in read-write mode by entering, as root:</para>
<screen><prompt>#</prompt> <userinput>guestfish --rw -a centos63_desktop.img</userinput>
<computeroutput>
Welcome to guestfish, the libguestfs filesystem interactive shell for
editing virtual machine filesystems.

Type: 'help' for help on commands
      'man' to read the manual
      'quit' to quit the shell

><fs></computeroutput>
</screen>

Command

Use tag: command

The name of an executable program.

Example

Use the <command>nova network-create</command> command to create the subnet that the VMs reside on.

Command line prompt

Use tag: prompt

Example

<screen><prompt>$</prompt> <userinput>sudo addgroup nova</userinput></screen>

File name or path

Use tag: filename

Any part of a path specification, including device name, directory, file name, or extension.

Examples

<para>The configuration file <filename>nova.conf</filename> is installed in <filename>/etc/nova</filename> by default.</para>

Variable text

Use tag: replaceable

Variable content that readers replace with actual instances. The text is frequently italicized in output.

Example

<para>The <filename>/etc/<replaceable>service-codename</replaceable>/policy.json</filename> controls what users are allowed to do for a given service.

Note: Don't add formatting to replaceable text, for example by surrounding it with quotes or brackets. Let the DocBook style sheets do the formatting.

System and API names

Use tag: systemitem

Refer to components in an operating system or API by name, including system services, daemons, methods, classes, and functions. To refer to the item's location rather than its name, consider using filename instead.

Example

<para>Compute uses the <systemitem>nova-scheduler</systemitem> service to determine how to dispatch compute and volume requests.</para>

General style conventions

• Use "OpenStack", not Openstack or openstack.
• Use "Compute", "Image", and "Identity" when referring to the services instead of "nova", "glance", and "keystone". Use the project names like "nova" and "keystone" when referring to the project or for CLI commands and service names.
• Wrap lines to 70 characters.

Configuration options

When documenting options in a .conf file, use the literal tag.

<literal>flat_network_bridge</literal>

Boolean configuration options

When documenting boolean configuration options, use the format that explicitly specifies the truth value:

force_dhcp_release=True
use_ipv6=False

Don't do it this way (which may not even work?)

force_dhcp_release
nouse_ipv6

Sections

All section tags must have an xml:id attribute. This enables unique file names for the generated HTML and human-readable page titles, plus it lets Disqus threads stay with the HTML page:

<section xml:id="section-id-goes-here">
...
</section>

If you want to keep several sections on a single HTML page, use a "stop chunking" processing directive:

<?dbhtml stop-chunking?>

Links

External

<link xlink:href="http://www.example.com">Linked text here</link>

Internal

<link linkend="section-name-here">Linked text here</link>

Information or configuration files that the user has to type or read

Do not indent the text (open/close tags may be indented)

    <programlisting>
config-file-example=asdf
foo=bar
hello=world
    </programlisting>

Inline configuration information (option name or value)

<literal>--use_deprecated_auth</literal>

Configuration information when part should be replaced

<literal>http://<replaceable>IP_ADDRESS</replaceable>/foo/bar</literal>

Inline mention of a specific command

<command>nova-manage</command>

Command to type into a shell

Do not indent the text (open/close tags may be indented). Use a prompt to show which user you are logged in as when entering the input. Generally on Ubuntu the docs use sudo to preface commands that must be run as a sudo user.

    <screen>
<prompt>$</prompt> <userinput>command as a regular user</userinput>
    </screen>

    <screen>
<prompt>#</prompt> <userinput>command as root</userinput>
    </screen>

    <screen>
<prompt>(mysql)</prompt> <userinput>command to type</userinput>
    </screen>

Result of the command

Do not indent the text (open/close tags may be indented)

    <screen>
<computeroutput>result output goes here</computeroutput>
    </screen>

Note that this can be combined with a prompt and input:

    <screen>
<prompt>$</prompt> <userinput>command to type</userinput>
<computeroutput>result output goes here</computeroutput>
    </screen>

File names

<filename>/my/file/is/here</filename>

File contents

The programlisting tag can do further output enhancements by using the language="langname" attribute including: bash, java, json, and xml.

<programlisting>
contents
of a
file
</programlisting>

Linux service

For example, nova-network or dnsmasq.

<systemitem class="service">nova-network</systemitem>

Procedures (where step 2 needs to be done after step 1)

<procedure><title>To do such and such</title>
       <step><para>...</para></step>
</procedure>

Note that the title must begin with the word, "To." Do not include a colon in the title.

Individual steps can also include titles. Step titles do not have to start with "To."

You can include substeps in any step, as follows:

<step><title>To configure the cloud</title>
<para>Complete the following steps:
<substeps>
<step><para>xx</para></step>
<step><para>xx</para></step>
</substeps>
</para>
</step>

Instructions to follow with no critical dependency across steps

<itemizedlist>
      <listitem><para>...</para></listitem>
</itemizedlist>

A list in key/value form

<variablelist>
  <varlistentry>
    <term>key</term>
    <listitem>value</listitem>
  </varlistentry>
  <varlistentry>
    <term>key</term>
    <listitem>value</listitem>
  </varlistentry>
</variablelist>

Notes

You can specify a Note callout box by doing:

<note><para>...</para></note>

Embedding images

In DocBook source, here is how you include images that have both a scalable-for-print-resolution in the PDF and an online-resolution for the HTML output. In this case the two types of images are SVG and PNG formats. The contentwidth="6in" attribute ensures that the image does not overlap print margins nor take up too much screen space.

<figure xml:id="CFinterfaces">
      <title>Cloud Files System Interfaces</title>
      <mediaobject>
        <imageobject>
          <imagedata contentwidth="6in" fileref="figures/CFinterfaces.svg"/>
        </imageobject>
      </mediaobject>
    </figure>

The convention is to use the /src/figures/ directory to store both the source image and any other formats of that same image. The pom.xml file copies the files in the /figures/ directory into the output directory required for HTML in the post processing section.

Also, when you add the image to the /src/figures directory, be sure to tell the source control system that you've added the image. For example, use "git add" to ensure the images get added to source control so the HTML and PDF output will be built correctly by the Jenkins continuous integration server.

For any figure you create, please also include the source files, even if the image was not created with open source tools, for maintenance purposes. While all OpenStack docs are created with open source in mind, including open-licensed fonts in the output, we are willing to allow non-open authoring or image creation tools if it's more efficient.

Tables

Use sentence capitalization for table captions and column headings.

Example:

    <table rules="all">
        <caption>Hardware recommendations </caption>
        <col width="20%"/>
        <col width="23%"/>
        <col width="57%"/>

        <thead>
            <tr>
                <td>Server</td>
                <td>Recommended hardware</td>
                <td>Notes</td>
            </tr>
        </thead>
        <tbody>
                <tr>
                        <td><para>...</para></td>
                ...
            </tr>
        </tbody>
    </table>

Force a line break

Especially handy when table cells aren't correctly wrapping or definition lists (like varlistentry) aren't wrapping well.

<?sbr?>

OS-specific (install & deploy guide)

The Install & Deploy guide has content that depends upon the operating system. Use the "os" attribute to specify a region that is operating-system specific. Valid values are:

• ubuntu
• fedora
• rhel
• centos
• deb
  

For example:

    <screen os="ubuntu"><userinput><prompt>$</prompt> sudo apt-get install -y ntp</userinput></screen>
    <screen os="rhel;fedora;centos"><prompt>$</prompt> <userinput>yum install -y ntp</userinput></screen>

Define a Hostname

Use lowercase unless legal reasons require capitalization.