Jump to: navigation, search

Difference between revisions of "Documentation/Conventions"

(Fixed bullet formatting.)
(Indent comments)
Line 10: Line 10:
  
 
== Information or configuration files that the user has to type or read ==
 
== Information or configuration files that the user has to type or read ==
 +
 +
Do not indent the text (open/close tags may be indented)
  
  
 
<pre><nowiki>
 
<pre><nowiki>
<programlisting>
+
    <programlisting>
 
config-file-example=asdf
 
config-file-example=asdf
 
foo=bar
 
foo=bar
 
hello=world
 
hello=world
</programlisting>
+
    </programlisting>
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 46: Line 48:
  
 
== Command to type into a shell ==
 
== Command to type into a shell ==
 +
 +
Do not indent the text (open/close tags may be indented)
  
  
 
<pre><nowiki>
 
<pre><nowiki>
<screen>
+
    <screen>
 
<prompt>$</prompt> <userinput>command as a regular usre</userinput>
 
<prompt>$</prompt> <userinput>command as a regular usre</userinput>
</screen>
+
    </screen>
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 57: Line 61:
  
 
<pre><nowiki>
 
<pre><nowiki>
<screen>
+
    <screen>
 
<prompt>#</prompt> <userinput>command as root</userinput>
 
<prompt>#</prompt> <userinput>command as root</userinput>
</screen>
+
    </screen>
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 65: Line 69:
  
 
<pre><nowiki>
 
<pre><nowiki>
<screen>
+
    <screen>
 
<prompt>(mysql)</prompt> <userinput>command to type</userinput>
 
<prompt>(mysql)</prompt> <userinput>command to type</userinput>
</screen>
+
    </screen>
 
</nowiki></pre>
 
</nowiki></pre>
  
  
 
== Result of the command ==
 
== Result of the command ==
 +
 +
Do not indent the text (open/close tags may be indented)
  
  
 
<pre><nowiki>
 
<pre><nowiki>
<screen>
+
    <screen>
 
<computeroutput>result output goes here</computeroutput>
 
<computeroutput>result output goes here</computeroutput>
</screen>
+
    </screen>
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 85: Line 91:
  
 
<pre><nowiki>
 
<pre><nowiki>
<screen>
+
    <screen>
 
<prompt>$</prompt> <userinput>command to type</userinput>
 
<prompt>$</prompt> <userinput>command to type</userinput>
 
<computeroutput>result output goes here</computeroutput>
 
<computeroutput>result output goes here</computeroutput>
</screen>
+
    </screen>
 
</nowiki></pre>
 
</nowiki></pre>
  

Revision as of 19:43, 30 March 2012

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.

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></listitem>
</orderedlist>


Instructions to follow with no critical dependency across steps

<itemizedlist>
      <listitem></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>