Documentation/Markup conventions
This page provides writing conventions for the DocBook formatting syntax.
For RST conventions, see the Documentation Contributors Guide. The RST conventions on this page are replaced by the guide.
Contents
- 1 General authoring conventions
- 2 Tags
- 2.1 Block elements
- 2.2 Code or data (block and inline)
- 2.2.1 Code or data (block)
- 2.2.2 Options and values
- 2.2.3 Boolean configuration options
- 2.2.4 Avoiding empty lines in screen and programlistings
- 2.2.5 Code or data (inline)
- 2.2.6 User input
- 2.2.7 Computer output
- 2.2.8 Commands, parameters, and variables
- 2.2.9 Command line prompt
- 2.2.10 Configuration options (inline)
- 2.3 Inline elements
- 2.4 Profiling (conditional content)
- 3 References
General authoring conventions
This section contains general guidelines for editing OpenStack documents in DocBook.
Note: For RST conventions, see the Documentation Contributors Guide.
Avoid long lines
Wrap source lines so that you do not have lines longer than 79 characters, which matches pep8 standards (from Python) and helps with side-by-side diffs for reviews. There are exceptions for programlistings/screens that contain markup.
Maximum line length in verbatim text
When using verbatim elements (including literallayout
, programlisting
, screen
, and synopsis
), do not exceed a line length of 79 characters of printed characters.
Chapters, sections and so on
Using IDs (DocBook only)
All chapter, section and appendix 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.
Example
<section xml:id="section-id-goes-here"> ... </section>
For xml:id creation, follow these guidelines:
- xml:id must be unique across a built deliverable, otherwise you get build errors
- xml:id creates the HTML file name so it should be human-readable, not codified like the file name
- xml:id should closely follow the actual title in the text, using dashes for spaces
- xml:id creation should consider search and find-ability as well as human-readability
Keeping sections together (DocBook only)
To keep several sections on a single HTML page, use the DocBook stop_chunking
processing instruction:
Example
<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 and migration support</title> ...
Adding a line break
The output of verbatim elements like screen
and programlisting
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 <?sbr?>
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, <?sbr?>
forces a line break.
<td>compute_driver = nova.virt.baremetal.driver.BareMetalDriver</td> <td>scheduler_host_manager=nova.scheduler.baremetal_host_manager.<?sbr?>BaremetalHostManager</td>
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 tox -e checkniceness
.
Entities (DocBook only)
The common used entities are defined in the file doc/common/entities/openstack.ent. Include this file before using common entities and enhance it as needed. For examples of its usage, see the section Numbers and units.
Numbers and units
Separate numbers and their units by a non-breaking space. Include the common entitites file with the definition of it.
Example
<!DOCTYPE section [ <!ENTITY % openstack SYSTEM "../common/entities/openstack.ent"> %openstack; ]> ... 1 TB, is 1024 GB.
Emdashes
Do not place spaces before and after emdashes. If you use emdashes, use the —
entitity.
Example
<!DOCTYPE section [ <!ENTITY % openstack SYSTEM "../common/entities/openstack.ent"> %openstack; ]> ... OpenStack dashboard—Project tab
Tags
For documentation, we use semantic markup and let the toolchain format the text in a consistent and appropriate way. Thus, every occurrence of a term, like a variable, should use the same markup. The writing should be clear and markup consistent and thus a reader should easily know why a certain term is using a specific markup like boldface or italics. Explicit use of bold or italics is in general wrong.
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.
Block elements
Headings
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
Do not organize your content so that headings are "stacked" -- meaning, there are two titles directly after each other with no text to introduce the reason for the second title.
DocBook use tag: title
in a section
or chapter
Notes
A brief message that is set off from the main text. Use note
for generic messages; the others have more specific semantic meanings, as their names indicate.
DocBook: use tag: note
, caution
, important
, tip
, or warning
By default, these elements automatically generate a title (Note, Caution, and so on.) You can customize the title by explicitly adding a title
element.
Example
The title element in this example overrides the default title, Note:
<note><title>Upcoming changes</title> <para>Future versions of this feature may not be backward compatible. Consider implementing the revised interface now. </para> </note>
Procedure
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."
DocBook: Tag to use: procedure
To reduce the number of steps and make long procedures easier to follow, consider breaking steps up into logical groups of substeps.
Example
<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>
To indicate a choice of steps, use stepalternative
. The alternative steps are rendered as a bulleted list in the output.
To indicate an optional step, use <step> (Optional) </step> rather than the DocBook performance attribute.
Example
Thanks to Bob Stayton for this clear illustration:
<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> <step><para>Do part D.</para></step> <step><para>(Optional) Do part E.</para></step> </procedure>
Pull conceptual information into an overview before the procedure. Make the steps in the procedure concise. Start each step with a verb. If the step includes a command example, end the introductory sentence with a colon (:).
Example
<section xml:id="xxx"><title>Edit a file</title> <para>Place concepts in an introductory paragraph before the procedure.</para> <para>If you want, describe the overall flow in a couple of sentences.</para> <procedure> <step> <para>Navigate to the directory that contains the file.</para> </step> <step> <para>Open the file, where <replaceable>MY_FILE</replaceable> is the name of your file:</para> <screen><prompt>$</prompt> <userinput>open-file <replaceable>MY_FILE</replaceable></userinput></screen> </step> <step> <para>Edit the file.</para> </step> <step> <para>Make global changes:</para> <screen><prompt>$</prompt> <userinput>change-file xyz zyx</userinput></screen> </step> </procedure>
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 procedure
instead.
Ordered list
DocBoook: Use tag: orderedlist
A sequence of items whose order matters.
Example
<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>
Unordered list
A sequence of items that can happen in any order or whose order doesn't matter.
DocBook: Use tag: itemizedlist
Example
<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>
Term/description or key/value pairs
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. variablelist
is typically rendered as a dl
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.
DocBook: Use tag variablelist
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:
<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>
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 (DocBook only)
Use tag: simplelist
Present a sequence of words or short phrases without the decorations of a numbered or bulleted list. simplelist
offers a variety of flavors.
Example (default vertical list)
<para>Valid formats include:</para> <simplelist> <member>PNG</member> <member>JPG</member> <member>GIF</member> <member>SVG</member> </simplelist>
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 type="inline"
attribute:
<para>Valid formats include <simplelist type='inline'> <member>PNG</member> <member>JPG</member> <member>GIF</member> <member>SVG</member> </simplelist> </para>
The output looks like this:
Valid formats include PNG, JPG, GIF, SVG.
Image
DocBook: mediaobject
Use mediaobject
for a block image. For a formal (titled) image, embed a mediaobject
in a figure
.
Note: inlinemediaobject
inserts an image in a text block, such as a paragraph. For our docs, mediaobject
is usually the better choice: inlinemediaobject
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.
<figure xml:id="CFinterfaces"> <title>Cloud Files System Interfaces</title> <mediaobject> <imageobject> <imagedata contentwidth="6in" fileref="figures/CFinterfaces.svg"/> </imageobject> </mediaobject> </figure>
Note: the contentwidth="6in"
is used for all guides with the exception of the Training Guides. The Training Guides use contentwidth="7in"
since the PDFs is in landscape.
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.
For many networking diagrams such as those in the admin guide, as a comment in the docbook there are links to Google Drawing images that are shared so that they can be edited by anyone with the link, then exported to PNG.
For the Operations Guide, the source files are .ai so we have not included them as they are not edited with open source tools. However, if you find an error we can get a copy of those images, and the original SVGs prior to the O'Reilly work, as they are still available.
Tables
Use tag: table
, informaltable
. Generally speaking we don't use CALS tables, using <tr> <td> markup.
Use table
for a formal (titled) table, informaltable
for a table with no title.
Use sentence capitalization for table captions and column headings.
Use th
for headers - both column and row headers. Using td
in headers works as well but th
is preferred.
Example
<table rules="all"> <caption>Hardware recommendations </caption> <col width="20%"/> <col width="23%"/> <col width="57%"/> <thead> <tr> <th>Server</th> <th>Recommended hardware</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td><para>...</para></td> ... </tr> </tbody> </table>
Code or data (block and inline)
Code or data (block)
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.
DocBook: Use tag: programlisting
Example
<programlisting>config-file-example = asdf foo = bar hello = world</programlisting>
To optimize the output of programlisting
for a specific programming language, use the language attribute. Valid language values include bash
, ini
, java
, javascript
, json
, python
, and xml
.
Examples
<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>
Note: Since programlisting
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
<programlisting> LINE 1 LINE 2 </programlisting>
Use instead
<programlisting>LINE 1 LINE 2</programlisting>
Options and values
For options and their values in configuration files, always add a space around the "=" sign:
<programlisting>option = value</programlisting>
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
Avoiding empty lines in screen and programlistings
Since screen
and programlisting
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
<programlisting> LINE 1 LINE 2 </programlisting>
Use instead
<programlisting>LINE 1 LINE 2</programlisting>
Code or data (inline)
A fragment of code within a line of text.
DocBook: Use tag: literal
or code
If you are telling or expecting users to enter the code or data, use userinput
instead.
Examples
<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> <para>To set the environment variable, run <code>export token="token"</code.</para>
User input
Use tag: userinput
Text that you instruct or intend users to enter. Compare to code
or programlisting
, which simply shows an instance of code or data, without telling users to enter it.
You can insert a short userinput
into a line of text (such as a para). For multiline input, embed userinput
in a screen
element, where you can insert line breaks to create each line.
Example
<para>Enter <userinput>admin</userinput> for the username and <userinput>secret</userinput> as the password.</para>
If your command is too long, wrap it and add slashes so that users can copy and paste the line. Also, intent the following line with just a few, usually three, spaces:
<screen><prompt>$</prompt> <userinput>glance image-create --name ubuntu.iso \ --is-public=True --container-format=bare \ --disk-format=iso < ubuntu-13.04-server-amd64.iso</userinput></screen>
See Computer output for another multiline example.
Computer output
Use tag: computeroutput
Text displayed in a terminal or log file as the result of a command. You can insert a short computeroutput
string into a line of text. For multi-line input, embed computeroutput
in a screen
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 screen
:
<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 ><fs></computeroutput></screen>
Commands, parameters, and variables
Use for inline commands. Examples are inline sub-commands for the OpenStack nova, swift, or neutron command-line interfaces (CLIs) and inline Linux commands.
For variables, use all caps like <replaceable>VARIABLE</replaceable>
. There is more information on variables here.
Note: You do not have to tag the OpenStack CLI name, such as nova. Use the command
tag to tag the client sub-commands.
DocBook': Use tags: command
and parameter
and replaceable
Examples
<para>To launch a virtual machine, use the nova <command>boot</command> command. Use the <parameter>--flavor</parameter> <replaceable>FLAVOR</replaceable> and <parameter>--image</parameter> <replaceable>IMAGE</replaceable> parameters to specify the IDs or names of the flavor and image to use for the image.</para>
Command line prompt
Use tag: prompt
Example
<screen><prompt>#</prompt> <userinput>addgroup nova</userinput></screen> <screen><prompt>$</prompt> <userinput>glance image-list</userinput></screen>
Note there's a single space between the closing prompt
and the opening userinput
.
Always use the #
prompt if the command needs root privileges to run. Don't use sudo
.
Use the $
prompt otherwise.
Configuration options (inline)
Use tag: option
Describes configuration file options. Use the word "option" (not "key") for these.
Example
<para>Set the <option>backend</option> option in the <filename>nova.conf</filename> configuration file.</para>
Inline elements
Applications (inline)
Use tag: application
Describes software applications.
Example
<para>You must configure the <application>RabbitMQ</application>.</para>
File name or path
Any part of a path specification, including device name, directory, file name, or extension.
DocBook: Use tag: filename
Example
<para>By default, the <filename>nova.conf</filename> file is installed in the <filename>/etc/nova</filename> directory.</para>
Packages (inline)
Use tag: package
Describes software packages.
Example
<para>You must install the <package>libvirt</package> package.</para>
Variable text
Use tag: replaceable
Variable content that readers replace with actual instances. The text is frequently italicized in output.
For variables, use all caps like <replaceable>VARIABLE</replaceable>
.
Example
<para>The <filename>/etc/<replaceable>SERVICE-CODENAME</replaceable>/policy.json</filename> controls what users are allowed to do for a given service.
Use replaceable
also for values that are useable as-is but can be changed. For example the controller node is often called controller but some change it. Or an option like storage_type=ephemeral
- where ephemeral
is one of several valid types that you can choose.
Example
rabbit_host = <replaceable>controller</replaceable> rabbit_password = <replaceable>RABBIT_PASS</replaceable> storage_type= <replaceable>ephemeral</replaceable>
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: systemitem
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 filename
instead. You can use class="service" to further describe the name.
Example
<para>Compute uses the <systemitem class="service">nova-scheduler</systemitem> service to determine how to dispatch compute and volume requests.</para>
Linking
Link to an internal target that has a title
DocBook: Use tag: xref
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, xref
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 link
, where you specify the link text yourself. The advantage of using xref
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 xref linkend
attribute points to the xml:id
of the target element, not its title.
Example
The xref
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:
<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>
If the target in this example were an informalfigure
, 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 xref
reference.)
Link to an internal target or external resource
Use tag: link
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 link
specify the "hot" text that you want to appear in the output.
- To cross-reference an internal target, in the
linkend
attribute specify the target element'sxml:id
.
- To cross-reference an external target, in the
xlink:href
attribute specify a URI that points to the target.
Examples
This cross-reference points to an external resource and displays the link text, Nova
<link xlink:href="http://nova.openstack.org">Nova</link>
This cross-reference points to an informal table in the same document, and specifies the link text, OpenStack Services:
<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>
As a rule of thumb, use link
instead of xref
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 xref
instead of hard-coding the link textlink
.
Unlinked URI
Technically, we should use the uri element as shown below, but our tool chain currently makes a live link, so use uri
sparingly if at all. Bug logged at https://bugs.launchpad.net/openstack-manuals/+bug/1221225.
Use tag: uri
Provide only the text of a URI, without a live link.
Example
<para>In your Web brower, log in to the Dashboard at <uri>http://192.168.206.130</uri>. </para>
Menu sequence
Use tag: menuchoice
Example:
Represents the action of navigating a menu to choose an item one or more levels down. Output automatically includes a → separator between items.
<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>
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: keycombo
A sequence of two or more keystrokes or mouse actions. Output automatically includes a + separator between items.
Example
<para>Click <guibutton>Search</guibutton> or press <keycombo> <keycap>Ctrl</keycap> <keycap>F1</keycap> </keycombo> .</para>
The output looks like this:
Click Search or press Ctrl+F1.
GUI button
Docbook: Use tag: guibutton
An item in a window that you select or click.
Example
<para>In the TryStack dashboard, click <guibutton>Login</guibutton>.</para>
Glossary entry
DocBook: Use tag: glossterm
This marks a term as appearing in the glossary. Use the baseform
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, the Install Guides, the Architecture Design Guide and the Networking Guide have a glossary. Before you mark a term with glossterm
, 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 firstterm
.
Example
Several <glossterm baseform="user">users</glossterm> might be part of a single <glossterm>tenant</glossterm>
You can use glossterm
several times in a guide. Right now the goal is to get entries into the glossary appendix. A good practice is to add the markup at the first mention of a term, especially when a term gets introduced or defined.
Profiling (conditional content)
Use tag: any element, with os
attribute, audience
attribute, and so on. For all profiling attributes, see DocBook: Chapter 26. Profiling (conditional text).
The Install & Deploy Guide has content that depends upon the operating system. Use the os
attribute to specify an element that is operating-system specific. Valid values are:
- ubuntu
- fedora
- rhel
- centos
- deb
Examples
<screen os="ubuntu"><prompt>$</prompt> <userinput>sudo apt-get install ntp</userinput></screen> <screen os="rhel;fedora;centos"><prompt>$</prompt> <userinput>yum install ntp</userinput></screen>
Resources
DocBook: Chapter 26. Profiling (conditional text)
References
- DocBook 5: The Definitive Guide
- Rackspace API Writers Guide
- DocBook XSL: The Complete Guide
- Sphinx RST documentation