Documentation/Conventions

DocBook markup conventions

This page offers conventions for DocBook markup. Please modify this page as you come across more markup you need for the docs.openstack.org site.

General style conventions

• Use "OpenStack", not Openstack or openstack.
• Wrap lines to 70 characters.

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.

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>

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)

    <screen>
<prompt>$</prompt> <userinput>command as a regular usre</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

<programlisting>
contents
of a
file
</programlisting>

Ordered procedure to follow (where step 2 needs to be done after step 1)

<orderedlist>
       <listitem><para>...</para></listitem>
</orderedlist>

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>