path: root/docs-rh-guidelines-zh_CN.xml

<?xml version="1.0" encoding="utf-8"?>
<chapter id="ch-rh-guidelines">
  <title>&RH; 文档撰写约定</title>
  <indexterm>
    <primary>recursion</primary>
    <see>recursion</see>
  </indexterm>
  <indexterm>
    <primary>RTFM</primary>
    <secondary>read the f*'ing manual</secondary>
    <seealso>humor</seealso>
  </indexterm>
  <indexterm>
    <primary>humor</primary>
    <secondary>RTFM</secondary>
  </indexterm>
  <para>请仔细阅读本章。本章描述了必须遵循的约定，例如命名约定。</para>
  <sect1 id="s1-xml-guidelines-naming">
    <title>ID 命名约定</title>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>命名约定</secondary>
    </indexterm>
    <indexterm>
      <primary>命名约定</primary>
    </indexterm>
    <para>后面您将看到这样的 ID 命名。它们有助于理解这些命名的含义。例如：</para>
    <screen>
      <computeroutput>
&lt;chapter id="ch-uniquename"&gt;

&lt;sect3="s3-install-make-disks"&gt;

&lt;figure id="fig-redhat-config-kickstart-basic"&gt;
</computeroutput>
    </screen>
    <para>ID 是独一无二的标识符，使得 DocBook XML 得知如何交叉参考章、节等等。</para>
    <para>定义 ID 的一般规则如下：</para>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>定义 ID 的规则</secondary>
    </indexterm>
    <indexterm>
      <primary>命名约定</primary>
      <secondary>定义 ID 的规则</secondary>
    </indexterm>
    <itemizedlist>
      <listitem>
        <para>至多使用 32 个字母 (这里指的是引号中所有内容)</para>
      </listitem>
      <listitem>
        <para>尽量短小而简单</para>
      </listitem>
      <listitem>
        <para>确保命名与内容相关 (使它可辨识)</para>
      </listitem>
    </itemizedlist>
    <para>例如，<command>"ch-uniquename"</command> (有 13 个字母) 以及 <command>"s3-install-make-disks"</command> (有 21 个字母)。</para>
    <para>特定一章中的小节应当在 ID 中包含这一章的名称 (这一章的 ID 去掉 <command>"ch-"</command>)。例如，您在撰写 <command>"ch-intro"</command> 一章，需要将有关磁盘分区的内容作为第一节时，小节 ID 将类似于 <command>"s1-intro-partition"</command>，它包含了小节编号，这一章的 ID 以及这一节的独一无二的 ID。</para>
    <table id="tb-xml-namingconventions">
      <title>命名约定</title>
      <tgroup cols="2">
        <colspec colname="tag" colnum="1" colwidth="100"/>
        <colspec colname="prefix" colnum="2" colwidth="100"/>
        <thead>
          <row>
            <entry>标记</entry>
            <entry>前缀</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>
              <command>前言</command>
            </entry>
            <entry>
              <computeroutput>pr-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>chapter</command>
            </entry>
            <entry>
              <computeroutput>ch-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>节</command>
            </entry>
            <entry>
              <computeroutput>sn-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>第一节</command>
            </entry>
            <entry>
              <computeroutput>s1-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>第二节</command>
            </entry>
            <entry>
              <computeroutput>s2-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>第三节</command>
            </entry>
            <entry>
              <computeroutput>s3-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>第四节</command>
            </entry>
            <entry>
              <computeroutput>s4-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>figure</command>
            </entry>
            <entry>
              <computeroutput>fig-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>table</command>
            </entry>
            <entry>
              <computeroutput>tb-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>附录</command>
            </entry>
            <entry>
              <computeroutput>ap-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>part</command>
            </entry>
            <entry>
              <computeroutput>pt-</computeroutput>
            </entry>
          </row>
          <row>
            <entry>
              <command>example</command>
            </entry>
            <entry>
              <computeroutput>ex-</computeroutput>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </sect1>
  <sect1 id="s1-xml-guidelines-header">
    <title>文件头</title>
    <para>所有文件必须包含 CVS Id 头部。</para>
    <para>如果您创建了一个新文件，第一行必须是：</para>
    <screen>
      <computeroutput>
&lt;!-- $Id: --&gt;
</computeroutput>
    </screen>
    <para>它被提交到 CVS 中时 (在每次提交时)，这一行都会自动更新，以包含关于文件的信息。例如：</para>
    <screen>
      <computeroutput>
&lt;!-- $Id: --&gt;
</computeroutput>
    </screen>
  </sect1>
  <sect1 id="s1-xml-admon">
    <title>创建提示</title>
    <indexterm>
      <primary>提示</primary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>警告</secondary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>技巧</secondary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>注意</secondary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>小心</secondary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>重要</secondary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>提示</secondary>
      <tertiary>警告</tertiary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>提示</secondary>
      <tertiary>技巧</tertiary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>提示</secondary>
      <tertiary>注意</tertiary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>提示</secondary>
      <tertiary>小心</tertiary>
    </indexterm>
    <indexterm>
      <primary>XML 标记</primary>
      <secondary>提示</secondary>
      <tertiary>重要</tertiary>
    </indexterm>
    <para>DocBook 中有五种提示类型：小心，重要，注意，技巧和警告。</para>
    <para>所有提示都有类似的结构：可选的标题，随后是段落级的元素。DocBook DTD 没有定义每种提示的特殊语义。例如，DocBook 并未规定警告必须用于可能造成重大损失的情况。</para>
    <sect2 id="s2-xml-notesetc">
      <title>创建技巧，注意，小心，重要和警告提示</title>
      <indexterm>
        <primary>XML 标记</primary>
        <secondary>注意</secondary>
      </indexterm>
      <indexterm>
        <primary>XML 标记</primary>
        <secondary>技巧</secondary>
      </indexterm>
      <indexterm>
        <primary>XML 标记</primary>
        <secondary>小心</secondary>
      </indexterm>
      <indexterm>
        <primary>XML 标记</primary>
        <secondary>重要</secondary>
      </indexterm>
      <indexterm>
        <primary>XML 标记</primary>
        <secondary>警告</secondary>
      </indexterm>
      <para>有很多方法来使文档中的文本引人注意。<emphasis>Note</emphasis> 用于显示附加信息。<emphasis>Tip</emphasis> 用于显示完成任务的其他方法。<emphasis>Caution</emphasis> 用于告诫用户在尝试某一步时必须小心。<emphasis>Important</emphasis> 用于提醒用户不可忽视的信息，尽管用户动作不受影响，但是必须提醒用户信息的重要性。<emphasis>Warning</emphasis> 用于提醒读者，他们的设置将被修改或变动，例如文件将被删除，如果他们在意这一后果，就不应继续动作。</para>
      <para>下列代码将展示上面每种情况的写法，同时也展示了 HTML 显示效果。</para>
      <screen>
        <computeroutput>
&lt;note&gt;
&lt;title&gt;注意&lt;/title&gt;
&lt;para&gt;文本内容&lt;/para&gt;
&lt;/note&gt;
</computeroutput>
      </screen>
      <note>
        <title>注意</title> <para>文本内容</para></note>
      <screen>
        <computeroutput>
&lt;tip&gt;
&lt;title&gt;技巧&lt;/title&gt;
&lt;para&gt;文本内容&lt;/para&gt;
&lt;/tip&gt;
</computeroutput>
      </screen>
      <tip>
        <title>技巧</title>
        <para>文本内容</para>
      </tip>
      <screen>
        <computeroutput>
&lt;caution&gt;
&lt;title&gt;小心&lt;/title&gt;
&lt;para&gt;文本内容&lt;/para&gt;
&lt;/caution&gt;
</computeroutput>
      </screen>
      <caution>
        <title>小心</title> <para>文本内容</para></caution>
      <screen>
        <computeroutput>
&lt;important&gt;
&lt;title&gt;重要&lt;/title&gt;
&lt;para&gt;文本内容&lt;/para&gt;
&lt;/important&gt;
</computeroutput>
      </screen>
      <important>
        <title>注意</title>
        <para>文本内容</para>
      </important>
      <screen>
        <computeroutput>
&lt;warning&gt;
&lt;title&gt;警告&lt;/title&gt;
&lt;para&gt;文本内容&lt;/para&gt;
&lt;/warning&gt;
</computeroutput>
      </screen>
      <warning>
        <title>警告</title> <para>文本内容</para></warning>
    </sect2>
  </sect1>
  <sect1 id="s1-screenshots">
    <title>屏幕截图</title>
    <indexterm>
      <primary>屏幕截图</primary>
      <secondary>如何截取</secondary>
    </indexterm>
    <indexterm>
      <primary>屏幕快照</primary>
      <see>屏幕截图</see>
    </indexterm>
    <indexterm>
      <primary>屏幕抓图</primary>
      <see>屏幕截图</see>
    </indexterm>
    <para>有两种类型的屏幕截图：图象和文本。选择它们的原则是 <firstterm>尽量使用文本截图</firstterm>。这意味着，如果您可以用文本而不是图象来表达，那么就用文本。GUI 的图象截图可以首先引入一些对象，然后用文字加以描述，但是您不会总是为每一步都创建一副截图。</para>
    <para>这样选择的主要目的是文本块通常比占据相同空间的图象包含更多信息。这和具体图象有关，某个场景的准确的截图也许抵得上一千字的效果。GUI 的截图通常有很大空白，只包含很少元素，这样便于描述或列举。</para>
    <para>截取图象的步骤本身表明了，使用文字来描述一个过程比起一系列的屏幕截图要精确许多。</para>
    <variablelist>
      <varlistentry>
        <term>图象截图</term>
        <listitem>
          <procedure>
            <step>
              <para>设置主题为默认主题。这样读者会熟悉这一外观，也使得 &FDP; 文档显得一致。从菜单中，选择 <guimenu>Preferences</guimenu>, <guimenuitem>Theme</guimenuitem> 然后选 <guimenuitem>Bluecurve</guimenuitem> (&FC; 4 不再使用 Bluecurve)。</para>
            </step>
            <step>
              <para>设置字体为默认值。从菜单中，选择 <guimenu>Preferences</guimenu>, <guimenuitem>Fonts</guimenuitem>. 然后设置 <guilabel>Application font</guilabel> 和 <guilabel>Desktop font</guilabel> 为 Sans Regular 10。设置 <guilabel>Window Title font</guilabel> 为 Sans Bold 10。设置 <guilabel>Terminal font</guilabel> 为 Monospace Regular 10。</para>
            </step>
            <step>
              <para>在截图之前，试着将目标 GUI 元素调整到尽可能小。您的目标应当是 500 像素或更小。如果您需要截取超过一个 GUI 元素，可以按照下面的步骤来缩放图象。</para>
            </step>
            <step>
              <para>要截取图象，使用鼠标选择 GUI 元素，将它放到最前，或者调整元素排列。按下 <keycombo><keycap>Alt</keycap><keycap>Print Screen</keycap></keycombo> 来截取单个 GUI 窗口。要抓去整个桌面，按下 <keycap>Print Screen</keycap>。如果您要截取包含很多元素的图象，并已将它们靠近，那么还可以在 <application>The GIMP</application> 中裁减结果图象到适当大小。截取的图象将是 PNG 格式。</para>
            </step>
            <step>
              <para>如果需要，您可以使用 <application>The GIMP</application> 缩放图象。打开图象，在图象上点击右键，选择 <guimenu>Image</guimenu> -&gt; <guimenuitem>Scale Image...</guimenuitem>。保持长宽比不变，设置 <guilabel>New Width</guilabel> 为 <guilabel>500 px</guilabel>，然后点击 <guibutton>OK</guibutton>。记住在转换为 EPS 之前按下 <keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo> 保存图象。</para>
            </step>
            <step>
              <para>仍使用 <application>The GIMP</application> 编辑图象，在图象上点击右键，选择 <guimenu>File</guimenu> -&gt; <guimenuitem>Save As...</guimenuitem>。在 <guimenu>Determine File Type:</guimenu> 列表中，选择 <guimenuitem>PostScript</guimenuitem>，然后点击 <guibutton>OK</guibutton>。点击 <guibutton>Export</guibutton>，允许平整图象。</para>
              <para>在 <guilabel>Save as PostScript</guilabel> 窗口，选择 <guilabel>Encapsulated PostScript</guilabel>，然后点击 <guibutton>OK</guibutton>。</para>
            </step>
          </procedure>
          <para>关于如何在 XML 中调用图象，请参考 <xref linkend="s1-xml-tags-figure"/>。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>文本截图</term>
        <listitem>
          <para>文本的屏幕信息对读者也很有用。如果您可以同时用图象和文本截图描述某个功能，就不要同时包含它们，除非忽略任何一个都将使描述不清楚。您应当使得信息更加通用。忽略用户名和主机名信息，区分用户的输入与示例的输出。在 <command>screen</command> 标记中，用户输入应当包含在 <command>userinput</command> 标记内，而用户看到的输出应当包含在 <command>computeroutput</command> 标记内。例如，<xref linkend="ex-text-screenshot-bad"/> 的用法应该改为这样 <xref linkend="ex-text-screenshot-good"/></para>
          <example id="ex-text-screenshot-bad">
            <title>不正确的文本截图</title>
            <screen>
              <userinput>ps ax | grep ssh</userinput>
              <computeroutput>
 2564 ?        S      0:23 /usr/sbin/sshd
 3092 ?        S      0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
 8235 ?        S      0:00 ssh -Nf rocky@philadelphia.net -L 6667:localhost
17223 pts/0    S      0:00 ssh rbalboa@core-router7
17227 pts/2    S      0:10 ssh rbalboa@smbshare2
21113 pts/7    S      1:19 ssh rocky@xxx.private
</computeroutput>
            </screen>
          </example>
          <example id="ex-text-screenshot-good">
            <title>正确的文本截图</title>
            <para>要显示所有当前活动的 ssh 会话，执行下列命令：</para>
            <screen>
              <command>ps ax | grep ssh</command>
            </screen>
            <para>输出将类似于：</para>
            <screen>
              <computeroutput>
 2564 ?        S      0:23 /usr/sbin/sshd
 3092 ?        S      0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
 8032 pts/0    S      0:00 ssh user@host.example.com
 8032 pts/1    S      0:00 ssh root@backup.example.com
</computeroutput>
            </screen>
          </example>
          <para>关于 screen 标记，请参考 <xref linkend="s1-xml-tags-screen"/>。</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>
  <sect1 id="s1-diagrams-images">
    <title>图表和图象</title>
    <indexterm>
      <primary>images</primary>
    </indexterm>
    <indexterm>
      <primary>图表</primary>
      <secondary>创建</secondary>
    </indexterm>
    <para>待编辑</para>
  </sect1>
</chapter>