|
|
(250 intermediate revisions by 20 users not shown) |
Line 1: |
Line 1: |
− | __NOTOC__
| + | {{Warning|header=Warning|body=This page is deprecated. It is left here for reference.}} |
− | = [[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.
| + | Read the new content in [http://docs.openstack.org/contributor-guide/writing-style/general-writing-guidelines.html the Documentation Contributor Guide]. |
| | | |
− | == General style conventions ==
| + | {{OpenStack_Documentation_Navbar}} |
− | | + | {{OpenStack_Conventions_Navbar}} |
− | Use "OpenStack", not Openstack or openstack.
| |
− | | |
− | == Information or configuration files that the user has to type or read ==
| |
− | | |
− | | |
− | <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>
| |
− | | |
− | | |
− | == Inline mention of a specific command ==
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <command>nova-manage</command>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == Command to type into a shell ==
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <screen>
| |
− | <prompt>$</prompt> <userinput>command as a regular usre</userinput>
| |
− | </screen>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <screen>
| |
− | <prompt>#</prompt> <userinput>command as root</userinput>
| |
− | </screen>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <screen>
| |
− | <prompt>(mysql)</prompt> <userinput>command to type</userinput>
| |
− | </screen>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == Result of the command ==
| |
− | | |
− | | |
− | <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>
| |
− | | |
− | | |
− | == File names ==
| |
− | | |
− | <pre><nowiki>
| |
− | <filename>/my/file/is/here</filename>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == File contents ==
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <programlisting>
| |
− | contents
| |
− | of a
| |
− | file
| |
− | </programlisting>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == Ordered procedure to follow (where step 2 needs to be done after step 1) ==
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <orderedlist>
| |
− | <listitem></listitem>
| |
− | </orderedlist>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == Instructions to follow with no critical dependency across steps ==
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <itemizedlist>
| |
− | <listitem></listitem>
| |
− | </itemizedlist>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == A list in key/value form ==
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <variablelist>
| |
− | <varlistentry>
| |
− | <term>key</term>
| |
− | <listitem>value</listitem>
| |
− | </varlistentry>
| |
− | <varlistentry>
| |
− | <term>key</term>
| |
− | <listitem>value</listitem>
| |
− | </varlistentry>
| |
− | </variablelist>
| |
− | </nowiki></pre>
| |