|
|
(244 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.
| |
− | * 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 HTML plus human-readable page titles, plus it lets Disqus threads stay with the HTML page:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <section xml:id="section-id-goes-here">
| |
− | ...
| |
− | </section>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == 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>
| |
− | <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 ==
| |
− | | |
− | Do not indent the text (open/close tags may be indented)
| |
− | | |
− | | |
− | <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 ==
| |
− | | |
− | Do not indent the text (open/close tags may be indented)
| |
− | | |
− | | |
− | <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><para>...</para></listitem>
| |
− | </orderedlist>
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == Instructions to follow with no critical dependency across steps ==
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | <itemizedlist>
| |
− | <listitem><para>...</para></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>
| |