Jump to: navigation, search

Difference between revisions of "Documentation/Conventions"

(Force a line break)
 
(210 intermediate revisions by 14 users not shown)
Line 1: Line 1:
= DocBook markup conventions =
+
{{Warning|header=Warning|body=This page is deprecated. It is left here for reference.}}
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 ==
+
Read the new content in [http://docs.openstack.org/contributor-guide/writing-style/general-writing-guidelines.html the Documentation Contributor Guide].
* 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 ==
+
{{OpenStack_Documentation_Navbar}}
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:
+
{{OpenStack_Conventions_Navbar}}
 
 
* 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.
 
 
 
<pre><nowiki>
 
<literal>flat_network_bridge</literal>
 
</nowiki></pre>
 
 
 
 
 
=== Boolean configuration options ===
 
When documenting boolean configuration options, use the format that explicitly specifies the truth value:
 
 
 
<pre><nowiki>
 
force_dhcp_release=True
 
use_ipv6=False
 
</nowiki></pre>
 
 
 
Don't do it this way (which may not even work?)
 
 
 
<pre><nowiki>
 
force_dhcp_release
 
nouse_ipv6
 
</nowiki></pre>
 
 
 
== 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>
 
 
 
If you want to keep several sections on a single HTML page, use a "stop chunking" processing directive:
 
 
 
<pre><nowiki>
 
<?dbhtml stop-chunking?>
 
</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 user</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 ==
 
The programlisting tag can do further output enhancements by using the language="langname" attribute including: bash, java, json, and xml.
 
 
 
<pre><nowiki>
 
<programlisting>
 
contents
 
of a
 
file
 
</programlisting>
 
</nowiki></pre>
 
 
 
== Linux service ==
 
For example, nova-network or dnsmasq.
 
 
 
<pre><nowiki>
 
<systemitem class="service">nova-network</systemitem>
 
</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 ==
 
In DocBook source, here is how you include images that have both a scalable-for-print-resolution in the PDF and an online-resolution for the HTML output. In this case the two types of images are SVG and PNG formats. The scale="60" attribute ensures that the image does not overlap print margins nor take up too much screen space.
 
 
 
<pre><nowiki>
 
<figure xml:id="CFinterfaces">
 
      <title>Cloud Files System Interfaces</title>
 
      <mediaobject>
 
        <imageobject role="fo">
 
          <imagedata scale="60" fileref="figures/CFinterfaces.svg"/>
 
        </imageobject>
 
        <imageobject role="html">
 
          <imagedata scale="60" fileref="figures/CFinterfaces.png"/>
 
        </imageobject>
 
      </mediaobject>
 
    </figure>
 
</nowiki></pre>
 
 
 
The convention is to use the /src/figures/ directory to store both the source image and any other formats of that same image. The pom.xml file copies the files in the /figures/ directory into the output directory required for HTML in the post processing section.
 
 
 
Also, when you add the image to the /src/figures directory, be sure to tell the source control system that you've added the image. For example, use "git add" to ensure the images get added to source control so the HTML and PDF output will be built correctly by the Jenkins continuous integration server.
 
 
 
For any figure you create, please also include the source files, even if the image was not created with open source tools, for maintenance purposes. While all OpenStack docs are created with open source in mind, including open-licensed fonts in the output, we are willing to allow non-open authoring or image creation tools if it's more efficient.
 
 
 
== 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>
 
 
 
== Force a line break ==
 
Especially handy when table cells aren't correctly wrapping or definition lists (like varlistentry) aren't wrapping well.
 
 
 
<pre><nowiki>
 
<?sbr?>
 
</nowiki></pre>
 
 
 
== OS-specific (install & deploy guide) ==
 
The Install & Deploy guide has content that depends upon the operating system. Use the "os" attribute to specify a region that is operating-system specific. Valid values are:
 
 
 
* ubuntu
 
* fedora
 
* rhel
 
* centos
 
* deb
 
 
 
For example:
 
 
 
 
 
<pre><nowiki>
 
    <screen os="ubuntu"><userinput><prompt>$</prompt> sudo apt-get install -y ntp</userinput></screen>
 
    <screen os="rhel;fedora;centos"><prompt>$</prompt> <userinput>sudo yum install -y ntp</userinput></screen>
 
</nowiki></pre>
 
 
 
 
 
== Define an Hostname ==
 
You should prefer lowercase nearly all the time unless legal reasons indicate capitalizing.
 

Latest revision as of 13:47, 27 March 2018

Warning icon.svg Warning

This page is deprecated. It is left here for reference.

Read the new content in the Documentation Contributor Guide.