|
|
| (239 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 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>
| |
Warning
