Difference between revisions of "Documentation/Conventions"
(adding a table of contents for easy jump-to-section) |
|||
Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
+ | <<[[TableOfContents]]()>> | ||
= [[DocBook]] markup 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. | |
− | 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 == | == General style conventions == | ||
− | |||
* Use "OpenStack", not Openstack or openstack. | * 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. | + | * 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. | * Wrap lines to 70 characters. | ||
== euca2ools documentation == | == 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: | 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: | ||
Line 19: | Line 17: | ||
== Configuration options == | == Configuration options == | ||
− | + | When documenting options in a .conf file, use the literal tag. | |
− | When documenting options in a .conf file, use the literal tag. | ||
Line 26: | Line 23: | ||
<literal>flat_network_bridge</literal> | <literal>flat_network_bridge</literal> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
=== Boolean configuration options === | === Boolean configuration options === | ||
− | |||
When documenting boolean configuration options, use the format that explicitly specifies the truth value: | When documenting boolean configuration options, use the format that explicitly specifies the truth value: | ||
Line 37: | Line 32: | ||
use_ipv6=False | use_ipv6=False | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Don't do it this way (which may not even work?) | Don't do it this way (which may not even work?) | ||
Line 46: | Line 40: | ||
nouse_ipv6 | nouse_ipv6 | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Sections == | == 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: | 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: | ||
Line 58: | Line 50: | ||
</section> | </section> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
If you want to keep several sections on a single HTML page, use a "stop chunking" processing directive: | If you want to keep several sections on a single HTML page, use a "stop chunking" processing directive: | ||
Line 66: | Line 57: | ||
<?dbhtml stop-chunking?> | <?dbhtml stop-chunking?> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Links == | == Links == | ||
− | |||
=== External === | === External === | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
<link xlink:href="http://www.example.com">Linked text here</link> | <link xlink:href="http://www.example.com">Linked text here</link> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
=== Internal === | === Internal === | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
<link linkend="section-name-here">Linked text here</link> | <link linkend="section-name-here">Linked text here</link> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== 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) | Do not indent the text (open/close tags may be indented) | ||
Line 98: | Line 82: | ||
</programlisting> | </programlisting> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Inline configuration information (option name or value) == | == Inline configuration information (option name or value) == | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
<literal>--use_deprecated_auth</literal> | <literal>--use_deprecated_auth</literal> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Configuration information when part should be replaced == | == Configuration information when part should be replaced == | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
<literal>http://<replaceable>IP_ADDRESS</replaceable>/foo/bar</literal> | <literal>http://<replaceable>IP_ADDRESS</replaceable>/foo/bar</literal> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Inline mention of a specific command == | == Inline mention of a specific command == | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
<command>nova-manage</command> | <command>nova-manage</command> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Command to type into a shell == | == Command to type into a shell == | ||
− | |||
Do not indent the text (open/close tags may be indented) | Do not indent the text (open/close tags may be indented) | ||
Line 134: | Line 110: | ||
</screen> | </screen> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Line 142: | Line 117: | ||
</screen> | </screen> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Line 150: | Line 124: | ||
</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) | Do not indent the text (open/close tags may be indented) | ||
Line 162: | Line 134: | ||
</screen> | </screen> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Note that this can be combined with a prompt and input: | Note that this can be combined with a prompt and input: | ||
Line 173: | Line 144: | ||
</screen> | </screen> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== File names == | == File names == | ||
Line 180: | Line 150: | ||
<filename>/my/file/is/here</filename> | <filename>/my/file/is/here</filename> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== File contents == | == File contents == | ||
Line 193: | Line 162: | ||
</programlisting> | </programlisting> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Linux service == | == Linux service == | ||
+ | For example, nova-network or dnsmasq. | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
<systemitem class="service">nova-network</systemitem> | <systemitem class="service">nova-network</systemitem> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Ordered procedure to follow (where step 2 needs to be done after step 1) == | == Ordered procedure to follow (where step 2 needs to be done after step 1) == | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
Line 212: | Line 178: | ||
</orderedlist> | </orderedlist> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Instructions to follow with no critical dependency across steps == | == Instructions to follow with no critical dependency across steps == | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
Line 222: | Line 186: | ||
</itemizedlist> | </itemizedlist> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== A list in key/value form == | == A list in key/value form == | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
Line 239: | Line 201: | ||
</variablelist> | </variablelist> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Notes == | == Notes == | ||
− | |||
You can specify a Note callout box by doing: | You can specify a Note callout box by doing: | ||
Line 249: | Line 209: | ||
<note><para>...</para></note> | <note><para>...</para></note> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Embedding images == | == Embedding images == | ||
− | |||
Example: | Example: | ||
Line 268: | Line 226: | ||
</mediaobject> | </mediaobject> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Tables == | == Tables == | ||
+ | Example: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
Line 280: | Line 237: | ||
<col width="23%"/> | <col width="23%"/> | ||
<col width="57%"/> | <col width="57%"/> | ||
− | + | ||
<thead> | <thead> | ||
<tr> | <tr> | ||
Line 289: | Line 246: | ||
</thead> | </thead> | ||
<tbody> | <tbody> | ||
− | + | <tr> | |
− | + | <td><para>...</para></td> | |
− | + | ... | |
</tr> | </tr> | ||
</tbody> | </tbody> | ||
</table> | </table> | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Force a line break == | == Force a line break == | ||
− | |||
Especially handy when table cells aren't correctly wrapping or definition lists (like varlistentry) aren't wrapping well. | Especially handy when table cells aren't correctly wrapping or definition lists (like varlistentry) aren't wrapping well. | ||
Revision as of 03:17, 17 June 2012
<<TableOfContents()>>
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.
- 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.
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.
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)
<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
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>
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>
Notes
You can specify a Note callout box by doing:
<note><para>...</para></note>
Embedding images
Example:
<mediaobject> <imageobject role="fo"> <imagedata fileref="figures/dashboard-overview.png" format="PNG" scale="60"/> </imageobject> <imageobject role="html"> <imagedata fileref="figures/dashboard-overview.png" format="PNG" /> </imageobject> </mediaobject>
Tables
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?>