|
|
| (179 intermediate revisions by 12 users not shown) |
| Line 1: |
Line 1: |
| − | = Writing style = | + | {{Warning|header=Warning|body=This page is deprecated. It is left here for reference.}} |
| | | | |
| − | == Use active voice ==
| + | Read the new content in [http://docs.openstack.org/contributor-guide/writing-style/general-writing-guidelines.html the Documentation Contributor Guide]. |
| | | | |
| − | In general, write in active voice rather than passive voice.
| + | {{OpenStack_Documentation_Navbar}} |
| − | | + | {{OpenStack_Conventions_Navbar}} |
| − | * Active voice identifies the agent of action as the subject of the verb—usually the user.
| |
| − | * Passive voice identifies the recipient (not the source) of the action as the subject of the verb.<br />
| |
| − | | |
| − | Active-voice sentences clarify the performer of an action and are easier to understand than passive-voice sentences. Passive voice is usually less engaging and more complicated than active voice. When you use passive voice, the actions and responses of the software can be difficult to distinguish from those of the user. In addition, passive voice usually requires more words than active voice.
| |
| − | | |
| − | === Correct usage ===
| |
| − |
| |
| − | After you install the software, start the computer.<br />
| |
| − | Click OK to save the configuration.<br />
| |
| − | Create a server.
| |
| − |
| |
| − | === Incorrect usage ===
| |
| − | After the software has been installed, the computer can be started.<br />
| |
| − | The configuration is saved when the OK button is clicked.<br />
| |
| − | A server is created by you.<br />
| |
| − | | |
| − | | |
| − | However, passive voice is acceptable in the following situations:
| |
| − | | |
| − | * Using active voice sounds like you are blaming the user. For example, you can use passive voice in an error message or troubleshooting content when the active subject is the user.
| |
| − | * The agent of action is unknown, or you want to de-emphasize the agent of action and emphasize the object on which the action is performed.
| |
| − | * Recasting the sentence in active voice is wordy or awkward.
| |
| − | | |
| − | === Correct usage ===
| |
| − | If the build fails, the flavor might have been omitted.<br />
| |
| − | A flag was set incorrectly.<br />
| |
| − | (The messages can be generated by the product, the OS, or the database, and the source of the messages is not important to the user.)<br />
| |
| − | The product, OS, or database returns the messages.
| |
| − | | |
| − | === Incorrect usage ===
| |
| − | | |
| − | If the build fails, you probably omitted the flavor.<br />
| |
| − | You set the flag incorrectly.<br />
| |
| − | The messages are returned.
| |
| − | | |
| − | == Use present tense ==
| |
| − | | |
| − | Users read documentation to perform tasks or gather information. For users, these activities take place in their present, so the present tense is appropriate in most cases. Additionally, present tense is easier to read than past or future tense.
| |
| − | | |
| − | Use future tense only when you need to emphasize that something will occur later (from the users' perspective).
| |
| − | | |
| − | === Correct usage ===
| |
| − |
| |
| − | The product prompts you to verify the deletion.<br />
| |
| − | After you log in, your account begins the verification process.<br />
| |
| − |
| |
| − | === Incorrect usage ===
| |
| − | The product will prompt you to verify the deletion.<br />
| |
| − | After you log in, your account will then begin the verification process.
| |
| − | | |
| − | == Write to you (the user) ==
| |
| − | | |
| − | Users are more engaged with documentation when you use second person (that is, you address the user as you). Second person promotes a friendly tone by addressing users directly. Using second person with the imperative mood (in which the subject you is understood) and active voice helps to eliminate wordiness and confusion about who or what initiates an action, especially in procedural steps.
| |
| − | | |
| − | Using second person also avoids the use of gender-specific, third-person pronouns such as he, she, his, and hers. If you must use third person, use the pronouns they and their, but ensure that the pronoun matches the referenced noun in number.
| |
| − | | |
| − | Use first person plural pronouns (we, our) judiciously. These pronouns emphasize the writer or OpenStack rather than the user, so before you use them, consider whether second person or imperative mood is more "user friendly." However, use we recommend rather than it is recommended or OpenStack recommends . Also, you can use we in the place of OpenStack if necessary.
| |
| − | | |
| − | Do not use first person to avoid naming the product or to avoid using passive voice. If the product is performing the action, use third person (the product as actor). If you want to de-emphasize the agent of action and emphasize the object on which the action is performed, use passive voice.
| |
| − | | |
| − | The first-person singular pronoun I is acceptable in the question part of FAQs and when authors of blogs or signed articles are describing their own actions or opinions.
| |
| − | | |
| − | Do not switch person (point of view) in the same document.
| |
| − | | |
| − | === Correct usage ===
| |
| − | To create a server, you specify a name, flavor, and image.<br />
| |
| − | To create a server, specify a name, flavor, and image. (imperative mood)<br />
| |
| − | | |
| − | === Incorrect usage ===
| |
| − | Creating a server involves specifying a name, flavor, and image.<br />
| |
| − | To create a server, the user specifies and name, flavor, and image.<br />
| |
| − | | |
| − | == Avoid obscure non-English words and abbreviations ==
| |
| − | | |
| − | Some non-English words and abbreviations are difficult to translate, and some users might be unfamiliar with them. Some Latin abbreviations, like i.e., e.g., and etc., are unnecessarily vague. The following table lists terms and abbreviations to avoid, and their preferred alternatives.
| |
| − | | |
| − | Avoid e.g. ''Create a server by using a Linux distribution, e.g. Fedora or Ubuntu.''<br />
| |
| − | Use instead: For example or such as.
| |
| − |
| |
| − | * Create a server by using a Linux distribution. For example, use Fedora or Ubuntu.
| |
| − | * Create a server by using a Linux distribution, such as Fedora or Ubuntu.
| |
| − | | |
| − | = DocBook markup conventions =
| |
| − | This page offers writing conventions for OpenStack documentation. Following conventions helps to enhance the readabilty of our docs by enabling the DocBook stylesheets to format them consistently. Please modify this page as you come across more markup you need for the docs.openstack.org site.
| |
| − | | |
| − | == General authoring conventions ==
| |
| − | This section contains general guidelines for editing OpenStack documents in DocBook.
| |
| − | | |
| − | === Maximum line length in verbatim text ===
| |
| − | When using verbatim elements (including <code>literallayout</code>, <code>programlisting</code>, <code>screen</code>, and <code>synopsis</code>), do not exceed a line length of 70 characters.
| |
| − | | |
| − | === Boolean configuration options ===
| |
| − | When documenting boolean configuration options, explicitly include the truth value.
| |
| − | | |
| − | '''Correct example'''
| |
| − | <pre><nowiki>force_dhcp_release=True
| |
| − | use_ipv6=False</nowiki></pre>
| |
| − |
| |
| − | '''Incorrect example'''
| |
| − | <pre><nowiki>force_dhcp_release
| |
| − | nouse_ipv6</nowiki></pre>
| |
| − | | |
| − | === Sections ===
| |
| − | ==== Add IDs to sections ====
| |
| − | All section tags must have an <code>xml:id</code> 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.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><section xml:id="section-id-goes-here">
| |
| − | ...
| |
| − | </section></pre>
| |
| − | | |
| − | ==== Keeping sections together ====
| |
| − | To keep several sections on a single HTML page, use the DocBook <code>stop_chunking</code> processing instruction:
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><section xmlns="http://docbook.org/ns/docbook"
| |
| − | xmlns:xi="http://www.w3.org/2001/XInclude"
| |
| − | xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
| |
| − | xml:id="xapi-resize-setup">
| |
| − | <?dbhtml stop-chunking?>
| |
| − | <title>Dom Modifications for Resize/Migration Support</title>
| |
| − | ...</pre>
| |
| − | | |
| − | === 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.
| |
| − | | |
| − | === Adding a line break ===
| |
| − | The output of verbatim elements like <code>screen</code> and <code>programlisting</code> preserves the whitespace that you enter in the source, including line breaks.
| |
| − | | |
| − | In the output of non-verbatim elements (such as paragraphs and table cells), lines normally break automatically, for example at a fixed page or table boundary or when the reader resizes an HTML page. Automatic line breaking can fail if the text contains long strings that contain no whitespace. When that happens, the text is clipped or overflows the page or table boundaries.
| |
| − | | |
| − | If a line fails to break normally in output, try adding whitespace (like spaces) in the source where you want to allow line breaks. If that method is not available, you can force a line break anywhere in text by inserting the <code><?sbr?></code> processing instruction.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | In the first line of code, spaces around the equals signs enable the line to wrap at either location. In the second line, <code><?sbr?></code> forces a line break.
| |
| − | | |
| − | <pre><nowiki><programlisting>
| |
| − | compute_driver = nova.virt.baremetal.driver.BareMetalDriver
| |
| − | scheduler_host_manager=nova.scheduler.baremetal_host_manager.<?sbr?>BaremetalHostManager
| |
| − | </programlisting></nowiki></pre>
| |
| − | | |
| − | == Tagging ==
| |
| − | Choosing the right tags (or at least agreeing to use the same tags) is important for using DocBook effectively. Otherwise, readers get inconsistent visual cues in the output formatting. You can check the semantic description of any tag in Oxygen. This section tries to identify circumstances where multiple tags might work or where the choice of tags is not obvious, and suggests an appropriate tagging.
| |
| − | | |
| − | === Code or data (block) ===
| |
| − | | |
| − | '''Use tag:''' <code>programlisting</code>
| |
| − | | |
| − | Program source or source fragments formatted as a standalone block. (For inline source fragments see [[Code or data (inline)]].
| |
| − | Whitespace in the source, including spaces, tabs, and line breaks, is preserved in the output. Text is usually displayed in a fixed-width font.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><programlisting>config-file-example=asdf
| |
| − | foo=bar
| |
| − | hello=world</programlisting></nowiki></pre>
| |
| − | | |
| − | To optimize the output of <code>programlisting</code> for a specific programming language, use the language attribute. Valid language values include <code>bash</code>, <code>ini</code>, <code>java</code>, <code>javascript</code>, <code>json</code>, <code>python</code>, and <code>xml</code>.
| |
| − | | |
| − | '''Examples'''
| |
| − | | |
| − | <pre><nowiki><programlisting language="json"><xi:include href="samples/agents-put-res.json" parse="text"/></programlisting>
| |
| − | | |
| − | <programlisting language="bash" linenumbering="unnumbered">CACHES = {
| |
| − | 'default': {
| |
| − | 'BACKEND' : 'django.core.cache.backends.memcached.MemcachedCache',
| |
| − | 'LOCATION' : '127.0.0.1:11211'
| |
| − | }
| |
| − | } | |
| − | </programlisting></nowiki></pre>
| |
| − | | |
| − | === Code or data (inline) ===
| |
| − | | |
| − | '''Use tag''': <code>literal</code>
| |
| − | | |
| − | A fragment of code within a line of text. If you are telling or expecting users to enter the code or data, use <code>userinput</code> instead.
| |
| − | | |
| − | '''Examples'''
| |
| − | | |
| − | <pre><nowiki><para>The file contains the default setting, <literal>use_syslog = True</literal>.</para>
| |
| − |
| |
| − | <para>The owner is typically set to <literal>root:nova</literal>, and the mode set to
| |
| − | <literal>0640</literal>.</para></nowiki></pre>
| |
| − | | |
| − | === User input ===
| |
| − | | |
| − | '''Use tag''': <code>userinput</code>
| |
| − | | |
| − | Text that you instruct or intend users to enter. Compare to <code>code</code> or <code>programlisting</code>, which simply shows an instance of code or data, without telling users to enter it.
| |
| − | | |
| − | You can insert a short <code>userinput</code> into a line of text (such as a para). For multiline input, embed <code>userinput</code> in a <code>screen</code> element, where you can insert line breaks to create each line.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><para>Enter <userinput>admin</userinput> for the username and <userinput>secret</userinput> as the password.</para</nowiki></pre>
| |
| − | | |
| − | See [[Computer output]] for a multiline example.
| |
| − | | |
| − | === Computer output ===
| |
| − | '''Use tag''': <code>computeroutput</code>
| |
| − | | |
| − | Text displayed in a terminal or log file as the result of a command. You can insert a short <code>computeroutput</code> string into a line of text. For multi-line input, embed <code>computeroutput</code> in a <code>screen</code> element, inserting line breaks to create each line.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | This interactive terminal session combines a prompt, user input, and the resulting computer output in a <code>screen</code>:
| |
| − | | |
| − | <pre><nowiki><para>Mount the image in read-write mode by entering, as root:</para>
| |
| − | <screen><prompt>#</prompt> <userinput>guestfish --rw -a centos63_desktop.img</userinput>
| |
| − | <computeroutput>
| |
| − | Welcome to guestfish, the libguestfs filesystem interactive shell for
| |
| − | editing virtual machine filesystems.
| |
| − | | |
| − | Type: 'help' for help on commands
| |
| − | 'man' to read the manual
| |
| − | 'quit' to quit the shell
| |
| − | | |
| − | >&lt;fs></computeroutput>
| |
| − | </screen></nowiki></pre>
| |
| − | | |
| − | === Command ===
| |
| − | '''Use tag''': <code>command</code>
| |
| − | | |
| − | The name of an executable program.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><para>Use the <command>nova network-create</command> command to create the subnet that the VMs reside on.</para></nowiki></pre>
| |
| − | | |
| − | === Command line prompt ===
| |
| − | '''Use tag''': <code>prompt</code>
| |
| − | | |
| − | '''Example'''
| |
| − |
| |
| − | <pre><nowiki><screen><prompt>$ </prompt><userinput>sudo addgroup nova</userinput></screen></nowiki></pre>
| |
| − | | |
| − | === File name or path ===
| |
| − | '''Use tag''': <code>filename</code>
| |
| − | | |
| − | Any part of a path specification, including device name, directory, file name, or extension.
| |
| − |
| |
| − | '''Examples'''
| |
| − | | |
| − | <pre><nowiki><para>The configuration file <filename>nova.conf</filename> is installed in <filename>/etc/nova</filename> by default.</para></nowiki></pre>
| |
| − | | |
| − | === Variable text ===
| |
| − | '''Use tag''': <code>replaceable</code>
| |
| − | | |
| − | Variable content that readers replace with actual instances. The text is frequently italicized in output.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><para>The <filename>/etc/<replaceable>service-codename</replaceable>/policy.json</filename> controls what users are allowed to do for a given service.</nowiki></pre>
| |
| − | | |
| − | '''Note''': Don't add formatting to replaceable text, for example by surrounding it with quotes or brackets. Let the DocBook style sheets do the formatting.
| |
| − | | |
| − | === System and API names ===
| |
| − | '''Use tag''': <code>systemitem</code>
| |
| − | | |
| − | Operating system or API components that you refer to by name, including system services, daemons, methods, classes, and functions. To refer to an item's location rather than its name, use <code>filename</code> instead.
| |
| − | | |
| − | Example
| |
| − | <pre><nowiki><para>Compute uses the <systemitem>nova-scheduler</systemitem> service to determine how to dispatch compute and volume requests.</para></nowiki></pre>
| |
| − | | |
| − | === Linking ===
| |
| − |
| |
| − | ==== Link to an internal target that has a title ====
| |
| − | | |
| − | '''Use tag''': <code>xref</code>
| |
| − | | |
| − | Cross-reference an element, in the same document, that can automatically provide the link text. The "hot" link text that appears in the output is generated automatically from the target object during processing. For this reason, <code>xref</code> usually point to targets that have a title or a associated label (such as a numbered step in a procedure).
| |
| − | | |
| − | Compare this to a cross reference using <code>link</code>, where you specify the link text yourself. The advantage of using <code>xref</code> is that the link text is not static: if the title of the target changes, your link text is automatically updated in the next build.
| |
| − | | |
| − | Note that the <code>xref linkend</code> attribute points to the <code>xml:id</code> of the target element, not its title.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | The <code>xref</code> in this example points to the figure that follows. In the output, the target title, '''OpenStack Services''', is automatically used as the link text of the cross-reference:
| |
| − | | |
| − | <pre><nowiki><para>The Image Service is central to the overall IaaS picture, as shown in <xref linkend="concept_arch"/>.</para>
| |
| − | ...
| |
| − | <figure xml:id="concept_arch">
| |
| − | <title>OpenStack Services</title>
| |
| − | <mediaobject>
| |
| − | <imageobject>
| |
| − | <imagedata
| |
| − | fileref="figures/openstack-arch-grizzly-v1-conceptual.jpg"
| |
| − | contentwidth="6in"/>
| |
| − | </imageobject>
| |
| − | </mediaobject>
| |
| − | </figure></nowiki></pre>
| |
| − |
| |
| − | If the target in this example were an <code>informalfigure</code>, which has no title, the output would show "???" as the link text. which is probably not what you want. (For workarounds to this limitation, see the DocBook <code>xref</code> reference.)
| |
| − | | |
| − | | |
| − | ==== Link to an internal target or external resource ====
| |
| − | | |
| − | '''Use tag''': <code>link</code>
| |
| − | | |
| − | Cross-reference another element (which may or may not have a title) in the same document, or link to an external resource like an HTML page or PDF document. In the content of the <code>link</code> specify the "hot" text that you want to appear in the output.
| |
| − | | |
| − | * To cross-reference an internal target, in the <code>linkend</code> attribute specify the target element's <code>xml:id</code>.
| |
| − | | |
| − | * To cross-reference an external target, in the <code>xlink:href</code> attribute specify a URI that points to the target.
| |
| − | | |
| − | '''Examples'''
| |
| − | | |
| − | This cross-reference points to an external resource and displays the link text, '''Nova'''
| |
| − | | |
| − | <pre><nowiki><link xlink:href="http://nova.openstack.org">Nova</link></nowiki></pre>
| |
| − | | |
| − | This cross-reference points to an informal table in the same document, and specifies the link text, '''OpenStack Services''':
| |
| − | | |
| − | <pre><nowiki><para>The Image Service is central to the overall IaaS picture, as shown in <link linkend="concept_arch2">OpenStack Services</link>.</para>
| |
| − | ...
| |
| − | <informalfigure xml:id="concept_arch2">
| |
| − | <mediaobject>
| |
| − | <imageobject>
| |
| − | <imagedata
| |
| − | fileref="figures/openstack-arch-grizzly-v1-conceptual.jpg"
| |
| − | contentwidth="6in"/>
| |
| − | </imageobject>
| |
| − | </mediaobject>
| |
| − | </informalfigure></nowiki></pre>
| |
| − | | |
| − | As a rule of thumb, use <code>link</code> instead of <code>xref</code> to cross-reference internal targets for which DocBook processing does not automatically generate link text (for example elements without titles). Conversely, if you're cross-referencing an internal target that has a title or label, consider using <code>xref</code> instead of hard-coding the link text<code>link</code>.
| |
| − | | |
| − | === Unlinked URI ===
| |
| − | '''Use tag''': <code>uri</code>
| |
| − | | |
| − | Provide only the text of a URI, without a live link.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><para>In your Web brower, log in to the Dashboard at <uri>http://192.168.206.130</uri>. </para></nowiki></pre>
| |
| − | | |
| − | === Procedure ===
| |
| − | Tag to use: <code>procedure</code>
| |
| − | | |
| − | A formal (titled) sequence of steps. Normally, the steps are rendered as a numbered list in the output.
| |
| − | | |
| − | Begin the title with the word, "To", and do not end the title with a colon. Individual steps don't require titles, and step titles do not have to start with "To."
| |
| − | | |
| − | To reduce the number of steps and make long procedures easier to follow, consider breaking steps up into logical groups of substeps.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><procedure>
| |
| − | <title>To install the software</title>
| |
| − | <step><para>Download the package.</para>
| |
| − | <substeps>
| |
| − | <step><para>Go to the download page.</para></step>
| |
| − | <step><para>Choose the package for your environment and click <guibutton>Download</guibutton>.</para></step>
| |
| − | </substeps>
| |
| − | </step>
| |
| − | <step><para>Unpack the downloaded file.</para></step>
| |
| − | </procedure></nowiki></pre>
| |
| − |
| |
| − | To indicate a choice of steps, use <code>stepalternative</code>. The alternative steps are rendered as a bulleted list in the output.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | ''Thanks to Bob Stayton for this clear illustration:''
| |
| − | | |
| − | <pre><nowiki><procedure>
| |
| − | <step><para>Do part A</para></step>
| |
| − | <step><para>Do one of these:</para>
| |
| − | <stepalternatives>
| |
| − | <step><para>Do part B</para></step>
| |
| − | <step><para>If you can't do part B, do part C</para></step>
| |
| − | </stepalternatives>
| |
| − | </step>
| |
| − | </procedure> </nowiki></pre>
| |
| − | | |
| − | === Lists ===
| |
| − | Choose the appropriate list type to presenting a sequence of items. You can nest lists, including lists of different types. '''Note''': to present steps in a formal task, use <code>procedure</code> instead.
| |
| − | | |
| − | ==== Ordered list ====
| |
| − | '''Use tag''': <code>orderedlist</code>
| |
| − | | |
| − | A sequence of items whose order matters.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><para>During the migration process:</para>
| |
| − | <orderedlist>
| |
| − | <listitem><para>The target host ensures that live migration is enabled.</para></listitem>
| |
| − | <listitem><para>The target host installs the base VHD if it is not already present.</para></listitem>
| |
| − | <listitem><para>The source host ensures that live migration is enabled.</para></listitem>
| |
| − | <listitem><para>The source host initiates the migration.</para></listitem>
| |
| − | <listitem><para>The source host notifies the manager of the outcome of the operation.</para></listitem>
| |
| − | </orderedlist></nowiki></pre>
| |
| − | | |
| − | ==== Unordered list ====
| |
| − | '''Use tag''': <code>itemizedlist</code>
| |
| − | | |
| − | A sequence of items that can happen in any order or whose order doesn't matter.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><para>OpenStack with XenAPI supports the following virtual machine image formats:</para>
| |
| − | <itemizedlist>
| |
| − | <listitem><para>Raw</para></listitem>
| |
| − | <listitem><para>VHD (in a gzipped tarball)</para></listitem>
| |
| − | </itemizedlist></nowiki></pre>
| |
| − | | |
| − | ==== Term/description or key/value pairs ====
| |
| − | '''Use tag''': <code>variablelist</code>
| |
| − | | |
| − | An unordered list in which each item has a short term (such as a key or option) or phrase, followed by a block that describes it. <code>variablelist</code> is typically rendered as a <code>dl</code> definition list in HTML output, with the term highlighted.
| |
| − | | |
| − | Consider using a variable list:
| |
| − | * Instead of an itemized list when your list has a regular pattern of key/value or term/definition pairs.
| |
| − | | |
| − | * Instead of a two column table where the first column lists items of a consistent type, such as keys, options, or short terms, and the second column describes the items. Consider that lists are generally more accessible than tables for screen reader users.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | This example includes a nested variable list. Nesting lists of different kinds is a way of breaking up information into distinct visual and logical chunks:
| |
| − | <pre><nowiki><itemizedlist>
| |
| − | <listitem>
| |
| − | <para>The system exposes these components to users:</para>
| |
| − | <variablelist>
| |
| − | <varlistentry><term>Component A</term>
| |
| − | <listitem><para>Description of A.</para></listitem>
| |
| − | </varlistentry>
| |
| − | <varlistentry><term>Component B</term>
| |
| − | <listitem><para>Description of B.</para></listitem>
| |
| − | </varlistentry>
| |
| − | <varlistentry><term>Component C</term>
| |
| − | <listitem><para>Description of C. Note: C is available only for these OS's:</para>
| |
| − | <itemizedlist>
| |
| − | <listitem><para>Linux</para></listitem>
| |
| − | <listitem><para>Mac OS X</para></listitem>
| |
| − | </itemizedlist>
| |
| − | </listitem>
| |
| − | </varlistentry>
| |
| − | </variablelist>
| |
| − | </listitem>
| |
| − | <listitem><para>API libraries are also available.</para></listitem>
| |
| − | </itemizedlist></nowiki></pre>
| |
| − | | |
| − | The example output looks something like this:
| |
| − | <pre><nowiki>* The system exposes these components to users:
| |
| − | | |
| − | Component A
| |
| − | Description of A.
| |
| − | | |
| − | Component B
| |
| − | Description of B.
| |
| − | | |
| − | Component C
| |
| − | Description of C. Note: C is available only for these OS's:
| |
| − | * Linux
| |
| − | * Mac OS X
| |
| − | | |
| − | *API libraries are also available.</nowiki></pre>
| |
| − | | |
| − | ==== A simple, undecorated list of items ====
| |
| − | | |
| − | '''Use tag''': <code>simplelist</code>
| |
| − | | |
| − | Present a sequence of words or short phrases without the decorations of a numbered or bulleted list. <code>simplelist</code> offers a variety of flavors.
| |
| − | | |
| − | '''Example''' (default vertical list)
| |
| − | | |
| − | <pre><nowiki><para>Valid formats include:</para>
| |
| − | <simplelist>
| |
| − | <member>PNG</member>
| |
| − | <member>JPG</member>
| |
| − | <member>GIF</member>
| |
| − | <member>SVG</member>
| |
| − | </simplelist></nowiki></pre>
| |
| − | | |
| − | By default, this example is rendered as a standalone block of undecorated items, like this:
| |
| − | | |
| − | Valid formats include:
| |
| − | PNG
| |
| − | JPG
| |
| − | GIF
| |
| − | SVG
| |
| − | '''Example''' (inline list)
| |
| − | | |
| − | You can also render a comma-separated list in a paragraph, by adding the <code>type="inline"</code> attribute:
| |
| − | | |
| − | <pre><nowiki><para>Valid formats include
| |
| − | <simplelist type='inline'>
| |
| − | <member>PNG</member>
| |
| − | <member>JPG</member>
| |
| − | <member>GIF</member>
| |
| − | <member>SVG</member>
| |
| − | </simplelist>
| |
| − | </para></nowiki></pre>
| |
| − | | |
| − | The output looks like this:
| |
| − | | |
| − | Valid formats include PNG, JPG, GIF, SVG.
| |
| − | | |
| − | === Notes ===
| |
| − | | |
| − | '''Use tag''': <code>note</code>, <code>caution</code>, <code>important</code>, <code>tip</code>, or <code>warning</code>
| |
| − | | |
| − | A brief message that is set off from the main text. Use <code>note</code> for generic messages; the others have more specific semantic meanings, as their names indicate. By default, these elements automatically generate a title ('''Note''', '''Caution''', and so on.) You can customize the title by explicitly adding a <code>title</code> element.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | The title element in this example overrides the default title, '''Note''':
| |
| − | | |
| − | <pre><nowiki><note><title>Upcoming Changes</title>
| |
| − | <para>Future versions of this feature may not be backward compatible. Consider implementing the revised interface now.
| |
| − | </para>
| |
| − | </note></nowiki></pre>
| |
| − | === Image ===
| |
| − | | |
| − | '''Use tag''': <code>mediaobject</code>
| |
| − | | |
| − | Use <code>mediaobject</code> for a block image. For a formal (titled) image, embed a <code>mediaobject</code> in a <code>figure</code>.
| |
| − | | |
| − | '''Note''': <code>inlinemediaobject</code> inserts an image in a text block, such as a paragraph. For our docs, <code>mediaobject</code> is usually the better choice: <code>inlinemediaobject</code> is typically used for small inline graphics (like icons) or to achieve floating effects, and requires some care to use correctly.
| |
| − | | |
| − | | |
| − | 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 contentwidth="6in" 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>
| |
| − | <imagedata contentwidth="6in" fileref="figures/CFinterfaces.svg"/>
| |
| − | </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 ===
| |
| − | | |
| − | '''Use tag''': <code>table</code>, <code>informaltable</code>. Generally speaking we don't use CALS tables, using <tr> <td> markup.
| |
| − | | |
| − | Use <code>table</code> for a formal (titled) table, <code>informaltable</code> for a table with no title.
| |
| − | | |
| − | Use sentence capitalization for table captions and column headings.
| |
| − | | |
| − | '''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>
| |
| − | | |
| − | === Conditionalizing ===
| |
| − | '''Use tag''': any element, with <code>os</code> attribute
| |
| − | | |
| − | The ''Install & Deploy Guide'' has content that depends upon the operating system. Use the <code>os</code> attribute to specify an element that is operating-system specific. Valid values are:
| |
| − | | |
| − | * ubuntu
| |
| − | * fedora
| |
| − | * rhel
| |
| − | * centos
| |
| − | * deb
| |
| − | | |
| − | '''Examples'''
| |
| − | | |
| − | <pre><nowiki><screen os="ubuntu"><prompt>$</prompt> <userinput>sudo apt-get install -y ntp</userinput></screen>
| |
| − | | |
| − | <screen os="rhel;fedora;centos"><prompt>$</prompt> <userinput>yum install -y ntp</userinput></screen></nowiki></pre>
| |
| − | | |
| − | === Menu sequence ===
| |
| − | '''Use tag''': <code>menuchoice</code>
| |
| − | | |
| − | '''Example''':
| |
| − | | |
| − | Represents the action of navigating a menu to choose an item one or more levels down. Output automatically includes a '''→''' separator between items.
| |
| − | | |
| − | <pre><nowiki><para>To download an openrc file in the Dashboard, click
| |
| − | <menuchoice>
| |
| − | <guimenu>Settings</guimenu>
| |
| − | <guimenuitem>Project Settings</guimenuitem>
| |
| − | <guimenuitem>Download RC File</guimenuitem>
| |
| − | </menuchoice>
| |
| − | .</para></nowiki></pre>
| |
| − | | |
| − | The output looks like this:
| |
| − | To download an openrc file in the Dashboard, click Settings → Project Settings → Download RC File.
| |
| − | | |
| − | === Keyboard key combination ===
| |
| − | '''Use tag''': <code>keycombo</code>
| |
| − | | |
| − | A sequence of two or more keystrokes or mouse actions. Output automatically includes a '''+''' separator between items.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><para>Click <guibutton>Search</guibutton> or press
| |
| − | <keycombo>
| |
| − | <keycap>Ctrl</keycap>
| |
| − | <keycap>F1</keycap>
| |
| − | </keycombo>
| |
| − | .</para></nowiki></pre>
| |
| − | | |
| − | The output looks like this:
| |
| − | Click Search or press '''Ctrl+F1'''.
| |
| − | === GUI button ===
| |
| − | '''Use tag''': <code>guibutton</code>
| |
| − | | |
| − | An item in a window that you select or click.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki><para>In the TryStack dashboard, click <guibutton>Login</guibutton>.</para></nowiki></pre>
| |
| − | | |
| − | == Terms and usage ==
| |
| − | This section offers conventions around general English usage and terms that are not covered in the glossary.
| |
| − | | |
| − | | |
| − | === hostname ===
| |
| − | Use lowercase unless legal considerations require capitalizing.
| |
| − | | |
| − | '''Example'''
| |
| − | | |
| − | <pre><nowiki>"local-hostname": "test.novalocal"</nowiki></pre>
| |
| − | | |
| − | === OpenStack, not Openstack or openstack ===
| |
| − | | |
| − | === Service and project names ===
| |
| − | When referring to the services, use "Compute", "Image", and "Identity" 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.
| |
Warning
