跳转到： 导航, 搜索

文档/Markup 约定

OpenStack 文档
文档规范
Warning icon.svg 警告

此页面已弃用。此处保留供参考。

此页面提供 DocBook 格式化语法的写作约定。

有关 RST 约定，请参阅 文档贡献者指南。此页面上的 RST 约定已被该指南取代。


通用写作约定

本节包含使用 DocBook 格式编辑 OpenStack 文档的通用指南。

注意：有关 RST 约定，请参阅 文档贡献者指南。

避免过长行

包装源代码行，以确保没有超过 79 个字符的行，这与 Python 的 pep8 标准相符，并有助于在评审时进行并排差异比较。对于包含标记的 programlistings/screens，存在例外情况。

Verbatim 文本中的最大行长度

在使用 verbatim 元素（包括 literallayout、programlisting、screen 和 synopsis）时，不要超过 79 个打印字符的行长度。

章节、段落等

使用 ID (仅 DocBook)

所有章节、段落和附录标签都必须具有 xml:id 属性。这可以为生成的 HTML 和人类可读的页面标题启用唯一的名称，此外，它还可以让 Disqus 线程与 HTML 页面保持一致。

示例 

<section xml:id="section-id-goes-here">
...
</section>

对于 xml:id 创建，请遵循以下准则

  • xml:id 必须在构建的交付成果中是唯一的，否则会发生构建错误
  • xml:id 创建 HTML 文件名，因此应该易于阅读，而不是像文件名那样进行编码
  • xml:id 应该紧密遵循文本中的实际标题，使用破折号代替空格
  • xml:id 创建应考虑搜索和查找能力以及人类可读性

将段落组合在一起 (仅 DocBook)

要将多个段落放在单个 HTML 页面上，请使用 DocBook stop_chunking 处理指令

示例 

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

添加换行符

verbatim 元素（如 screen 和 programlisting）的输出保留了你在源代码中输入的空格，包括换行符。

在非 verbatim 元素（如段落和表格单元格）的输出中，行通常会自动换行，例如在固定的页面或表格边界处，或者当读者调整 HTML 页面的大小时。如果文本包含没有空格的长字符串，则自动换行可能会失败。当发生这种情况时，文本会被截断或溢出页面或表格边界。

如果一行在输出中无法正常换行，请尝试在源代码中添加空格（如空格）在你希望允许换行的地方。如果无法使用该方法，则可以通过插入 <?sbr?> 处理指令在文本中的任何位置强制换行。

示例

在第一行代码中，等号周围的空格使该行可以在任一位置换行。在第二行中，<?sbr?> 强制换行。

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

空白字符

不要在代码中使用制表符，始终使用空格。为了保持一致性，我们不喜欢在文件中留下额外的空格，因此不要在以下位置放置空格

  • 行尾 (尾随空格)
  • 在 listitem、para、td、th、command、literal、title、caption、filename、userinput、programlisting 等元素的开头或关闭标记之后

你可以使用 tox -e checkniceness 在 openstack-manuals 中测试空格。

实体 (仅 DocBook)

常用的实体定义在 doc/common/entities/openstack.ent 文件中。在使用常用实体之前，请包含此文件并根据需要进行增强。有关其用法的示例，请参阅 数字和单位 部分。

数字和单位

用不间断空格分隔数字及其单位。包含定义了它的常用实体文件。

示例 

<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
...
1&nbsp;TB, is 1024&nbsp;GB.

长破折号

不要在长破折号前后放置空格。如果使用长破折号，请使用 &mdash; 实体。

示例 

<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
...
OpenStack dashboard&mdash;Project tab

标签

对于文档，我们使用语义标记并让工具链以一致且适当的方式格式化文本。因此，每个术语（如变量）都应使用相同的标记。写作应该清晰且标记一致，以便读者可以轻松了解为什么某个术语使用特定的标记，如粗体或斜体。显式使用粗体或斜体通常是错误的。

选择正确的标签（或至少同意使用相同的标签）对于有效使用 DocBook 非常重要。否则，读者会在输出格式中获得不一致的视觉提示。你可以在 Oxygen 中检查任何标签的语义描述。本节试图识别多个标签可能有效或标签选择不明显的情况，并提出适当的标记建议。

注意：有关 RST 约定，请参阅 文档贡献者指南。

块级元素

标题

注意：除了 Operations Guide 之外，请对标题使用句子风格的 capitalization，Operations Guide 遵循 O'Reilly 标题 capitalization 风格。

例如

错误：打开文件

正确：打开一个文件

对于任务主题，避免使用动名词 (_ING_ 动词)。

错误：安装和配置软件

正确：安装并配置软件

不要组织你的内容，使标题“堆叠”在一起——这意味着，在引入第二个标题的原因之后，有两个标题直接相连。

DocBook 使用标签：section 或 chapter 中的 title

笔记

一条从主文本中分离出来的简短消息。对于通用消息，使用 note；其他消息具有更具体的语义含义，如其名称所示。

DocBook：使用标签：note、caution、important、tip 或 warning

默认情况下，这些元素会自动生成标题（注意、警告等）。你可以通过显式添加 title 元素来自定义标题。

示例

此示例中的标题元素覆盖了默认标题，注意

<note><title>Upcoming changes</title>
    <para>Future versions of this feature may not be backward compatible. Consider implementing the revised interface now.
  </para>
</note>

过程

一个正式的（带标题的）步骤序列。通常，步骤在输出中呈现为编号列表。标题应以“To”开头，不应以冒号结尾。各个步骤不需要标题，并且步骤标题不必以“To”开头。

DocBook：要使用的标签：procedure

为了减少步骤数量并使长过程更易于遵循，请考虑将步骤分解为逻辑子步骤组。

示例 

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

要指示步骤选择，请使用 stepalternative。替代步骤在输出中呈现为项目符号列表。

要指示可选步骤，请使用 <step> (可选) </step>，而不是 DocBook 性能属性。

示例

感谢 Bob Stayton 的清晰说明 

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

将概念信息提取到过程之前的概述中。使过程中的步骤简洁。每个步骤都以动词开头。如果该步骤包含命令示例，则在介绍句的末尾加上冒号 (:)。

示例 

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

列表

选择适当的列表类型来呈现一系列条目。你可以嵌套列表，包括不同类型的列表。注意：对于正式任务中的步骤，请使用 procedure。

有序列表

DocBook：使用标签：orderedlist

一系列条目，其顺序很重要。

示例 

<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>
无序列表

一系列条目，可以以任何顺序发生，或者其顺序并不重要。

DocBook：使用标签：itemizedlist

示例 

<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>
术语/描述或键/值对

一个无序列表，其中每个条目都有一个简短的术语（如键或选项）或短语，后跟一个描述它的块。variablelist 通常在 HTML 输出中呈现为 dl 定义列表，术语突出显示。

考虑使用变量列表

  • 而不是项目符号列表，当你的列表具有一致的键/值或术语/定义对模式时。
  • 而不是两列表格，其中第一列列出一致类型的条目，如键、选项或短语，第二列描述这些条目。请考虑，列表通常比表格更易于屏幕阅读器用户访问。

DocBook：使用标签 variablelist

示例

此示例包含嵌套的变量列表。嵌套不同类型的列表是分解信息为不同的视觉和逻辑块的一种方式

<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 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.
简单、无装饰的条目列表 (仅 DocBook)

使用标签：simplelist

呈现一系列单词或短语，而无需编号或项目符号列表的装饰。simplelist 提供了各种风格。

示例（默认垂直列表）

<para>Valid formats include:</para>
  <simplelist>
    <member>PNG</member>
    <member>JPG</member>
    <member>GIF</member>
    <member>SVG</member>
  </simplelist>

默认情况下，此示例呈现为独立的无装饰条目块，如下所示

Valid formats include:
PNG
JPG
GIF
SVG

示例（内联列表）

你可以通过添加 type="inline" 属性在段落中呈现逗号分隔的列表

<para>Valid formats include 
  <simplelist type='inline'>
    <member>PNG</member>
    <member>JPG</member>
    <member>GIF</member>
    <member>SVG</member>
  </simplelist>
</para>

输出如下所示

Valid formats include PNG, JPG, GIF, SVG.

Image

DocBook：mediaobject

使用 mediaobject 表示块级图像。对于正式的（带标题的）图像，将 mediaobject 嵌入到 figure 中。

注意：inlinemediaobject 在文本块中插入图像，例如段落。对于我们的文档，mediaobject 通常是更好的选择：inlinemediaobject 通常用于小的内联图形（如图标）或实现浮动效果，需要小心使用。

在 DocBook 源代码中，以下是如何包含同时具有可用于 PDF 的可缩放打印分辨率和 HTML 输出的在线分辨率的图像。在这种情况下，两种类型的图像是 SVG 和 PNG 格式。contentwidth="6in" 属性可确保图像不会重叠打印边距，也不会占用过多的屏幕空间。

<figure xml:id="CFinterfaces">
  <title>Cloud Files System Interfaces</title>
  <mediaobject>
    <imageobject>
      <imagedata contentwidth="6in" fileref="figures/CFinterfaces.svg"/>
    </imageobject>
  </mediaobject>
</figure>

注意：contentwidth="6in" 用于所有指南，除了培训指南。培训指南使用 contentwidth="7in"，因为 PDF 是横向的。

约定是使用 /src/figures/ 目录来存储源图像及其任何其他格式的图像。pom.xml 文件将 /figures/ 目录中的文件复制到 HTML 所需的输出目录中，在后处理部分。

此外，当你将图像添加到 /src/figures 目录时，请务必告诉源代码控制系统你已添加了该图像。例如，使用 git add 确保图像被添加到源代码控制中，以便 Jenkins 持续集成服务器可以正确构建 HTML 和 PDF 输出。

对于你创建的任何图形，请也包含源文件，即使该图像不是使用开源工具创建的，也是为了维护目的。虽然所有 OpenStack 文档都是以开源为导向创建的，包括在输出中使用开源字体，但如果使用开源或图像创建工具更有效，我们愿意允许使用非开源的创作或图像创建工具。

对于许多网络图，例如管理指南中的那些，作为 docbook 中的注释，存在指向 Google Drawing 图像的链接，这些图像是共享的，以便任何拥有链接的人都可以编辑它们，然后导出为 PNG。

对于操作指南，源文件是 .ai 格式，因此我们没有包含它们，因为它们不是使用开源工具编辑的。但是，如果您发现错误，我们可以获取这些图像的副本，以及在 O'Reilly 工作之前的原始 SVG 文件，因为它们仍然可用。

表格

使用标签：table、informaltable。一般来说，我们不使用 CALS 表格，而是使用 <tr> <td> 标记。

对于正式（带标题）的表格使用 table，对于没有标题的表格使用 informaltable。

使用句子首字母大写来编写表格标题和列标题。

对于标题（包括列标题和行标题）使用 th。在标题中使用 td 也可以，但推荐使用 th。

示例 

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

代码或数据（块和内联）

代码或数据（块）

以独立块的形式格式化的程序源代码或源代码片段。（对于内联源代码片段，请参阅 代码或数据（内联）。源代码中的空格，包括空格、制表符和换行符，将在输出中保留。文本通常以等宽字体显示。

DocBook：使用标签： programlisting

示例 

<programlisting>config-file-example = asdf
foo = bar
hello = world</programlisting>

为了优化 programlisting 的输出，以适应特定的编程语言，请使用 language 属性。有效的语言值包括 bash、ini、java、javascript、json、python 和 xml。

示例 

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

注意：由于 programlisting 保留换行符，因此请始终将源代码的初始行/末尾行与标签一起添加，否则将插入一个空行

不要使用 

<programlisting>
LINE 1
LINE 2
</programlisting>

而是使用 

<programlisting>LINE 1
LINE 2</programlisting>

选项和值

对于配置文件中的选项及其值，始终在 "=" 符号周围添加空格

<programlisting>option = value</programlisting>

布尔型配置选项

在记录布尔型配置选项时，明确包含真值。

正确示例 

force_dhcp_release = True
use_ipv6 = False

错误示例 

force_dhcp_release
nouse_ipv6

避免在屏幕和程序列表中出现空行

由于 screen 和 programlisting 保留您输入的换行符，如果您没有在代码的第一行/最后一行添加标签，则可能会在文本的开头/结尾处获得空行。

不要使用 

<programlisting>
LINE 1
LINE 2
</programlisting>

而是使用 

<programlisting>LINE 1
LINE 2</programlisting>

代码或数据（内联）

行内文本中的代码片段。

DocBook：使用标签：literal 或 code

如果您正在告知或期望用户输入代码或数据，请使用 userinput。

示例 

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

用户输入

使用标签：userinput

您指示或打算用户输入文本。与 code 或 programlisting 相比，后者只是显示代码或数据的实例，而不会告知用户输入它。

您可以将一个短的 userinput 插入到一行文本中（例如，一个段落）。对于多行输入，将 userinput 嵌入到 screen 元素中，您可以在其中插入换行符以创建每一行。

示例 

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

如果您的命令太长，请将其换行并添加斜杠，以便用户可以复制和粘贴该行。此外，用几个（通常是三个）空格缩进下一行

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

请参阅 计算机输出 以获取另一个多行示例。

计算机输出

使用标签：computeroutput

作为命令结果在终端或日志文件中显示的文本。您可以将一个短的 computeroutput 字符串插入到一行文本中。对于多行输入，将 computeroutput 嵌入到 screen 元素中，插入换行符以创建每一行。

示例

此交互式终端会话组合了提示符、用户输入和生成的计算机输出，位于 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

>&lt;fs></computeroutput></screen>

命令、参数和变量

用于内联命令。示例是 OpenStack nova、swift 或 neutron 命令行界面 (CLI) 的内联子命令以及内联 Linux 命令。

对于变量，使用大写字母，例如 <replaceable>VARIABLE</replaceable>。有关更多信息，请参阅 变量。

注意：您不必标记 OpenStack CLI 名称，例如 nova。使用 command 标签标记客户端子命令。

DocBook：使用标签：command、parameter 和 replaceable

示例 

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

命令行提示符

使用标签：prompt

示例 

<screen><prompt>#</prompt> <userinput>addgroup nova</userinput></screen>
<screen><prompt>$</prompt> <userinput>glance image-list</userinput></screen>

注意在关闭 prompt 和打开 userinput 之间有一个空格。

如果命令需要 root 权限才能运行，请始终使用 # 提示符。不要使用 sudo。

否则使用 $ 提示符。

配置选项（内联）

使用标签：option

描述配置文件选项。对于这些选项使用“option”一词（而不是“key”）。

示例 

<para>Set the <option>backend</option> option in the <filename>nova.conf</filename> configuration file.</para>

内联元素

应用程序（内联）

使用标签： application

描述软件应用程序。

示例 

<para>You must configure the <application>RabbitMQ</application>.</para>

文件名或路径

路径规范的任何部分，包括设备名称、目录、文件名或扩展名。

DocBook：使用标签：filename

示例 

<para>By default, the <filename>nova.conf</filename> file is installed in the <filename>/etc/nova</filename> directory.</para>

软件包（内联）

使用标签： package

描述软件软件包。

示例 

<para>You must install the <package>libvirt</package> package.</para>

变量文本

使用标签：replaceable

读者用实际实例替换的可变内容。输出中该文本通常以斜体显示。

对于变量，使用大写字母，例如 <replaceable>VARIABLE</replaceable>。

示例 

<para>The <filename>/etc/<replaceable>SERVICE-CODENAME</replaceable>/policy.json</filename> controls what users are allowed to do for a given service.

还可用于那些可以按原样使用但可以更改的值。例如，控制器节点通常称为 controller，但有些人会更改它。或者像 storage_type=ephemeral 这样的选项 - 其中 ephemeral 是您可以选择的几个有效类型之一。

示例 

rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable>
storage_type= <replaceable>ephemeral</replaceable>

注意：不要对可替换文本添加格式，例如用引号或方括号将其括起来。让 DocBook 样式表执行格式化。

系统和 API 名称

使用标签：systemitem

您按名称引用的操作系统或 API 组件，包括系统服务、守护程序、方法、类和函数。要引用项目的路径而不是名称，请使用 filename。您可以使用 class="service" 来进一步描述名称。

示例

<para>Compute uses the <systemitem class="service">nova-scheduler</systemitem> service to determine how to dispatch compute and volume requests.</para>

链接

链接到具有标题的内部目标

DocBook：使用标签：xref

交叉引用同一文档中的元素，该元素可以自动提供链接文本。“热”链接文本在处理期间从目标对象自动生成到输出中。因此，xref 通常指向具有标题或关联标签（例如过程中的编号步骤）的目标。

与使用 link 进行交叉引用进行比较，在使用 link 时，您自己指定链接文本。使用 xref 的优点是链接文本不是静态的：如果目标标题发生更改，您的链接文本将在下一次构建中自动更新。

请注意，xref linkend 属性指向目标元素的 xml:id，而不是其标题。

示例

此 xref 指向后面的图形。在输出中，目标标题 OpenStack 服务 将自动用作交叉引用的链接文本

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

如果此示例中的目标是 informalfigure，它没有标题，则输出将显示“？？？”作为链接文本，这可能不是您想要的。（有关此限制的解决方法，请参阅 DocBook xref 参考。）

链接到内部目标或外部资源

使用标签：link

交叉引用同一文档中的另一个元素（可能没有标题），或链接到外部资源，例如 HTML 页面或 PDF 文档。在 link 的内容中，指定您希望出现在输出中的“热”文本。

  • 要交叉引用内部目标，请在 linkend 属性中指定目标元素的 xml:id。
  • 要交叉引用外部目标，请在 xlink:href 属性中指定指向目标的 URI。

示例

此交叉引用指向外部资源并显示链接文本 Nova

<link xlink:href="http://nova.openstack.org">Nova</link>

此交叉引用指向同一文档中的非正式表格，并指定链接文本 OpenStack 服务

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

作为经验法则，如果 DocBook 处理不能自动生成链接文本（例如，没有标题的元素），请使用 link 代替 xref 进行交叉引用。相反，如果您正在交叉引用具有标题或标签的内部目标，请考虑使用 xref 代替硬编码链接文本link。

未链接的 URI

从技术上讲，我们应该使用以下所示的 uri 元素，但我们工具链当前会创建一个活动链接，因此请谨慎使用 uri。错误已记录在 https://bugs.launchpad.net/openstack-manuals/+bug/1221225。

使用标签：uri

仅提供 URI 的文本，没有活动链接。

示例 

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

菜单序列

使用标签：menuchoice

示例:

表示导航菜单以选择向下多级菜单项的操作。输出会自动在项目之间包含 → 分隔符。

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

输出如下所示

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

键盘组合键

使用标签：keycombo

两个或多个击键或鼠标操作的序列。输出会自动在项目之间包含 + 分隔符。

示例 

<para>Click <guibutton>Search</guibutton> or press 
<keycombo>
  <keycap>Ctrl</keycap>
  <keycap>F1</keycap>
</keycombo>
.</para>

输出如下所示

Click Search or press Ctrl+F1.

GUI 按钮

Docbook：使用标签：guibutton

窗口中的一个项目，您可以选择或单击它。

示例 

<para>In the TryStack dashboard, click <guibutton>Login</guibutton>.</para>

词表条目

DocBook：使用标签：glossterm

这会将一个术语标记为出现在词表中。如果文本和词表中的术语拼写不同，请使用 baseform 属性。

请注意，并非所有指南都包含词表，目前操作指南、安全指南、安装指南、架构设计指南和网络指南都具有词表。在用 glossterm 标记一个术语之前，请检查它是否已出现在共享词表中，该词表可在 在线 和作为文件 glossary/glossary-terms.xml 在 openstack-manuals 存储库中。请不要使用术语 firstterm。

示例 

Several <glossterm baseform="user">users</glossterm> might be part of a single <glossterm>tenant</glossterm>

您可以在一个指南中使用 glossterm 几次。目前的目标是将条目添加到词表附录中。一个好的做法是在术语首次出现时添加标记，尤其是在术语被引入或定义时。

分析（条件内容）

使用标签：任何元素，带有 os 属性、audience 属性等。有关所有分析属性，请参阅 DocBook：第 26 章。分析（条件文本）。

安装和部署指南 具有依赖于操作系统的内容。使用 os 属性指定特定于操作系统的元素。有效值是

  • ubuntu
  • fedora
  • rhel
  • centos
  • deb

示例 

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

资源

DocBook：第 26 章。分析（条件文本）

API 编写指南

参考文献

从 "https://wiki.openstack.org/w/index.php?title=Documentation/Markup_conventions&oldid=160512" 检索