Difference between revisions of "Documentation/Conventions"
| Line 12: | Line 12: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | < | + | <programlisting> |
| − | + | config-file-example=asdf | |
| − | </ | + | foo=bar |
| + | hello=world | ||
| + | </programlisting> | ||
| + | </nowiki></pre> | ||
| − | < | + | |
| − | + | == Inline configuration information (option name or value) == | |
| − | </ | + | |
| + | |||
| + | <pre><nowiki> | ||
| + | <literal>--use_deprecated_auth</literal> | ||
| + | </nowiki></pre> | ||
| + | |||
| + | |||
| + | == Configuration information when part should be replaced == | ||
| + | |||
| + | |||
| + | <pre><nowiki> | ||
| + | <literal>http://<replaceable>IP_ADDRESS</replaceable>/foo/bar</literal> | ||
</nowiki></pre> | </nowiki></pre> | ||
| − | == Inline | + | == Inline mention of a specific command == |
<pre><nowiki> | <pre><nowiki> | ||
| − | < | + | <command>nova-manage</command> |
| − | |||
| − | - | ||
| − | |||
| − | </ | ||
</nowiki></pre> | </nowiki></pre> | ||
| − | == Command to type into a | + | == Command to type into a shell == |
<pre><nowiki> | <pre><nowiki> | ||
| − | < | + | <screen> |
| − | + | <prompt>$</prompt> <userinput>command as a regular usre</userinput> | |
| − | </ | + | </screen> |
</nowiki></pre> | </nowiki></pre> | ||
| Line 46: | Line 56: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | < | + | <screen> |
| − | (mysql) | + | <prompt>#</prompt> <userinput>command as root</userinput> |
| − | </ | + | </screen> |
| + | </nowiki></pre> | ||
| + | |||
| + | |||
| + | |||
| + | <pre><nowiki> | ||
| + | <screen> | ||
| + | <prompt>(mysql)</prompt> <userinput>command to type</userinput> | ||
| + | </screen> | ||
</nowiki></pre> | </nowiki></pre> | ||
| Line 56: | Line 74: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | < | + | <screen> |
| − | + | <computeroutput>result output goes here</computeroutput> | |
| − | + | </screen> | |
| − | </ | + | </nowiki></pre> |
| + | |||
| + | |||
| + | Note that this can be combined with a prompt and input: | ||
| + | |||
| + | |||
| + | <pre><nowiki> | ||
| + | <screen> | ||
| + | <prompt>$</prompt> <userinput>command to type</userinput> | ||
| + | <computeroutput>result output goes here</computeroutput> | ||
| + | </screen> | ||
</nowiki></pre> | </nowiki></pre> | ||
| Line 66: | Line 94: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | < | + | <filename>/my/file/is/here</filename> |
</nowiki></pre> | </nowiki></pre> | ||
| Line 75: | Line 103: | ||
<pre><nowiki> | <pre><nowiki> | ||
<programlisting> | <programlisting> | ||
| − | + | contents | |
| − | + | of a | |
| + | file | ||
</programlisting> | </programlisting> | ||
</nowiki></pre> | </nowiki></pre> | ||
Revision as of 21:53, 4 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.
Information or configuration files that the user has to type or read
<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
<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
<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>
