如何在DocBook的<term>中用<cmdsynopsis>风格描述配置选项？

核心原因 #

DocBook 4.5的内容模型限制了<term>标签仅能包含内联级元素（如<option>、<literal>、<emphasis>等），而<cmdsynopsis>、<arg>、<group>属于命令概要专用的块级/结构化元素，不能直接嵌套在<term>中。

可行解决方案 #

方案1：用内联元素模拟选项结构 #

利用<choice>内联元素（专门用于表示互斥选项）结合<emphasis>标记默认值，既保持结构化又符合<term>的内容规则：

<variablelist>
  <varlistentry>
    <term>
      <option>foo=</option>
      <choice>
        <option>yes</option>
        <option><emphasis role="bold">NO</emphasis></option>
      </choice>
    </term>
    <listitem>
      <para>选项<option>foo</option>可取<option>yes</option>和<option>NO</option>值，默认值为<emphasis role="bold">NO</emphasis>。</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <option>bar=</option>
      <choice>
        <option>easy</option>
        <option><emphasis role="bold">HARD</emphasis></option>
      </choice>
    </term>
    <listitem>
      <para>选项<option>bar</option>可取<option>easy</option>和<option>HARD</option>值，默认值为<emphasis role="bold">HARD</emphasis>。</para>
    </listitem>
  </varlistentry>
</variablelist>

方案2：将<cmdsynopsis>移至<listitem>中 #

如果必须保留<cmdsynopsis>的风格，可以在<term>中使用简化的选项标识，把完整的结构化概要放在<listitem>内：

<variablelist>
  <varlistentry>
    <term>
      <option>foo=yes|NO</option>
    </term>
    <listitem>
      <para>选项<option>foo</option>的取值说明：</para>
      <cmdsynopsis>
        <option>foo=</option>
        <group choice="plain">
          <arg choice="plain">yes</arg>
          <arg choice="plain">NO</arg>
        </group>
      </cmdsynopsis>
      <para>默认值为<emphasis role="bold">NO</emphasis>。</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <option>bar=easy|HARD</option>
    </term>
    <listitem>
      <para>选项<option>bar</option>的取值说明：</para>
      <cmdsynopsis>
        <option>bar=</option>
        <group choice="plain">
          <arg choice="plain">easy</arg>
          <arg choice="plain">HARD</arg>
        </group>
      </cmdsynopsis>
      <para>默认值为<emphasis role="bold">HARD</emphasis>。</para>
    </listitem>
  </varlistentry>
</variablelist>

方案3：用<literal>+<replaceable>简化标记 #

如果不需要强结构化，仅需清晰区分选项和取值，可使用基础内联元素组合：

<term>
  <literal>foo=</literal><replaceable>yes</replaceable>| <emphasis role="bold">NO</emphasis>
</term>

内容的提问来源于stack exchange，提问作者cagney