Documentation/Conventions/DocBook

= 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,  ,  , and  ), do not exceed a line length of 70 characters.

Boolean configuration options
When documenting boolean configuration options, explicitly include the truth value.

Correct example force_dhcp_release=True use_ipv6=False Incorrect example force_dhcp_release nouse_ipv6

Add IDs to sections
All section tags must have an  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

 ...

Keeping sections together
To keep several sections on a single HTML page, use the DocBook  processing instruction:

Example

 <?dbhtml stop-chunking?> Dom Modifications for Resize/Migration Support ...

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 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  and   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  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,  forces a line break.

compute_driver = nova.virt.baremetal.driver.BareMetalDriver scheduler_host_manager=nova.scheduler.baremetal_host_manager.<?sbr?>BaremetalHostManager

Avoiding empty lines in screen and programlistings
Since  and   preserve line breaks that you enter, you might get empty lines at the beginning/end of a text if you do not add the tags on the first/last line of the code.

Do not use LINE 1 LINE 2

Use instead LINE 1 LINE 2

Whitespace
Do not use tab characters in the code, always use spaces. For consistency, we like to have no extra whitespaces in the files, so do not place whitespaces at the following locations:
 * End of line (trailing whitespace)
 * after the opening or before the closing tag of elements listitem, para, td, th, command, literal, title, caption, filename, userinput, programlisting

You can test for whitespace in openstack-manuals with tools/validate.py.

Tags
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.

Applications (inline)
Use tag:

Describes software applications.

Example

You must configure the RabbitMQ.

Code or data (block)
Use tag:

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

config-file-example=asdf foo=bar hello=world

To optimize the output of  for a specific programming language, use the language attribute. Valid language values include,  ,  ,  ,  ,  , and.

Examples



CACHES = { 'default': { 'BACKEND' : 'django.core.cache.backends.memcached.MemcachedCache', 'LOCATION' : '127.0.0.1:11211' } }

Note: Since  preserves line breaks, add the initial/last line of source code always together with the tag, otherwise an empty line will be inserted:

Do not use LINE 1 LINE 2

Use instead LINE 1 LINE 2

Code or data (inline)
Use tag:  or

A fragment of code within a line of text. If you are telling or expecting users to enter the code or data, use  instead.

Examples

The file contains the default setting, use_syslog = True. The owner is typically set to root:nova, and the mode set to 0640.

To set the environment variable, run

Text that you instruct or intend users to enter. Compare to  or , which simply shows an instance of code or data, without telling users to enter it.

You can insert a short  into a line of text (such as a para). For multiline input, embed  in a   element, where you can insert line breaks to create each line.

Example

Enter admin for the username and secret as the password.</para

See Computer output for a multiline example.

Computer output
Use tag:

Text displayed in a terminal or log file as the result of a command. You can insert a short  string into a line of text. For multi-line input, embed  in a   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 :

Mount the image in read-write mode by entering, as root: # guestfish --rw -a centos63_desktop.img 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

>&amp;lt;fs>

Commands, parameters, and variables
Use tags:  and   and

Use for inline commands. Examples are inline sub-commands for the OpenStack nova, swift, or neutron command-line interfaces (CLIs) and inline Linux commands.

Note: You do not have to tag the OpenStack CLI name, such as nova. Use the  tag to tag the client sub-commands.

Examples

To launch a virtual machine, use the nova boot command. Use the --flavor FLAVOR and --image  IMAGE parameters to specify the IDs or names of the flavor and image to use for the image.

Command line prompt
Use tag:

Example $ sudo addgroup nova

Note there's a single space between the closing  and the opening.

Configuration options (inline)
Use tag:

Describes configuration file options. Example

Set the backend option in the nova.conf configuration file.

File name or path
Use tag:

Any part of a path specification, including device name, directory, file name, or extension. Example

By default, the nova.conf configuration file is installed in the /etc/nova folder.

Packages (inline)
Use tag:

Describes software packages.

Example

You must install the libvirt package.

Variable text
Use tag:

Variable content that readers replace with actual instances. The text is frequently italicized in output.

Example

The /etc/ service-codename /policy.json controls what users are allowed to do for a given service.

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:

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   instead. You can use class="service" to further describe the name.

Example Compute uses the nova-scheduler service to determine how to dispatch compute and volume requests.

Link to an internal target that has a title
Use tag:

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,  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, where you specify the link text yourself. The advantage of using  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  attribute points to the   of the target element, not its title.

Example

The  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:

The Image Service is central to the overall IaaS picture, as shown in . ...  OpenStack Services  If the target in this example were an, 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  reference.)

Link to an internal target or external resource
Use tag:

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  specify the "hot" text that you want to appear in the output.


 * To cross-reference an internal target, in the  attribute specify the target element's.


 * To cross-reference an external target, in the  attribute specify a URI that points to the target.

Examples

This cross-reference points to an external resource and displays the link text, Nova

Nova

This cross-reference points to an informal table in the same document, and specifies the link text, OpenStack Services:

The Image Service is central to the overall IaaS picture, as shown in OpenStack Services. ...  

As a rule of thumb, use  instead of   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  instead of hard-coding the link text.

Unlinked URI
Technically, we should use the uri element as shown below, but our tool chain currently makes a live link, so use   sparingly if at all. Bug logged at https://bugs.launchpad.net/openstack-manuals/+bug/1221225.

Use tag:

Provide only the text of a URI, without a live link.

Example

In your Web brower, log in to the Dashboard at http://192.168.206.130.

Procedure
Tag to use:

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

To install the software Download the package. Go to the download page. Choose the package for your environment and click Download. Unpack the downloaded file. To indicate a choice of steps, use. The alternative steps are rendered as a bulleted list in the output.

Example

Thanks to Bob Stayton for this clear illustration:

Do part A    Do one of these: Do part B        If you can't do part B, do part C

To indicate an optional step, use (Optional) rather than the DocBook performance attribute.

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  instead.

Ordered list
Use tag:

A sequence of items whose order matters.

Example

During the migration process: The target host ensures that live migration is enabled. The target host installs the base VHD if it is not already present. The source host ensures that live migration is enabled. The source host initiates the migration. The source host notifies the manager of the outcome of the operation.

Unordered list
Use tag:

A sequence of items that can happen in any order or whose order doesn't matter.

Example

OpenStack with XenAPI supports the following virtual machine image formats: Raw VHD (in a gzipped tarball)

Term/description or key/value pairs
Use tag:

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. is typically rendered as a  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: 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.

The example output looks something like this: * 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.

A simple, undecorated list of items
Use tag:

Present a sequence of words or short phrases without the decorations of a numbered or bulleted list. offers a variety of flavors.

Example (default vertical list)

Valid formats include: PNG JPG GIF SVG

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  attribute:

Valid formats include  PNG JPG GIF SVG

The output looks like this:

Valid formats include PNG, JPG, GIF, SVG.

Headings
Use tag:  in a   or

Use  for a heading.

Note: Use sentence-style capitalization for headings except for the Operations Guide, which follows O'Reilly heading capitalization style.

For example:

Incorrect: Open a File

Correct: Open a file

For task topics, avoid gerunds (_ING_ verbs).

Incorrect: Installing and Configuring Software

Correct: Install and configure software

Image
Use tag:

Use  for a block image. For a formal (titled) image, embed a  in a.

Note:  inserts an image in a text block, such as a paragraph. For our docs,  is usually the better choice:   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.

 Cloud Files System Interfaces 

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:,. Generally speaking we don't use CALS tables, using markup.

Use  for a formal (titled) table,   for a table with no title.

Use sentence capitalization for table captions and column headings.

Example

Profiling (conditional content)
Use tag: any element, with  attribute,   attribute, and so on. For all profiling attributes, see [http://www.sagehill.net/docbookxsl/Profiling.html DocBook: Chapter 26. Profiling (conditional text)].

The Install & Deploy Guide has content that depends upon the operating system. Use the  attribute to specify an element that is operating-system specific. Valid values are:


 * ubuntu
 * fedora
 * rhel
 * centos
 * deb

Examples

$ sudo apt-get install ntp

 $ yum install ntp

Resources

[http://www.sagehill.net/docbookxsl/Profiling.html DocBook: Chapter 26. Profiling (conditional text)]

API Writers Guide

Menu sequence
Use tag:

Example:

Represents the action of navigating a menu to choose an item one or more levels down. Output automatically includes a → separator between items.

To download an openrc file in the Dashboard, click Settings Project Settings Download RC File .

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:

A sequence of two or more keystrokes or mouse actions. Output automatically includes a + separator between items.

Example

Click Search or press Ctrl F1.

The output looks like this: Click Search or press Ctrl+F1.

GUI button
Use tag:

An item in a window that you select or click.

Example

In the TryStack dashboard, click Login.

Glossary
Use tag:

This marks a term as appearing in the glossary. Use the  attribute if the spelling of the term in the text and the glossary is different.

Note that not all guides include a glossary, currently the Operations Guide, the Security Guide and the Install Guides have a glossary. Before you mark a term with, check that it appears already in the shared glossary which is available online and as file glossary/glossary-terms.xml in the openstack-manuals repository. Please do not use the term.

Example

Several users might be part of a single tenant

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

"local-hostname": "test.novalocal"

Service and project names
When referring to the services, use "Compute," "Image Service" and "Identity Service" instead of "nova," "glance," and "keystone." Use the project names like "nova" and "keystone" when you refer to the project or the command-line interfaces (CLIs) and service names.

Here's the list of project names and their official names and capitalization:
 * Ceilometer: Telemetry or Telemetry module
 * Cinder: OpenStack Block Storage
 * Glance: OpenStack Image Service
 * Heat: Orchestration or Orchestration module
 * Horizon: OpenStack dashboard
 * Keystone: OpenStack Identity Service
 * Neutron: OpenStack Networking
 * Nova: OpenStack Compute
 * Swift: OpenStack Object Storage

Generally the capitalization of the project team names like swift is lowercase. When used as a command-line-client name, lowercase is best. When used for the team or project name, typically it's not necessary to capitalize.

Release names
Release Names should follow the wiki page. Particularly, the 9th release should be written Icehouse - a single word with only initial capital.

Guide Conventions
The following lists conventions used for writing specific guides. In general we want to be consistent between guides, especially since some guides include the same files.

General
TBD

Install Guide

 * Use  instead of the IP address 192.168.0.10
 * Use  instead of IP address for compute (Nova) nodes. Replace X with a number starting from 1. The external IP address of the first compute node is 10.0.0.11, the second is 10.0.0.12, and so on.
 * Use  instead of IP address for block storage (Cinder) nodes. Replace X with a number starting from 1.
 * Database passwords are written as, e.g.
 * Keystone passwords are written as, e.g.
 * is