|
|
| (234 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.
| |
| − | * 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.
| |
| − | | |
| − | == 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:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | <section xml:id="section-id-goes-here">
| |
| − | ...
| |
| − | </section>
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | == Links ==
| |
| − | | |
| − | === External ===
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | <link xlink:href="http://www.example.com">Linked text here</link>
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | === Internal ===
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | <link linkend="section-name-here">Linked text here</link>
| |
| − | </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>
| |
| − | | |
| − | | |
| − | == Notes ==
| |
| − | | |
| − | You can specify a Note callout box by doing:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | <note><para>...</para></note>
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | == Embedding images ==
| |
| − | | |
| − | Example:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | <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>
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | == Tables ==
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | <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>
| |
| − | </nowiki></pre>
| |
Warning
