documentation-guide acknowledgments-zh_CN.xml, NONE, 1.1 docs-converting-zh_CN.xml, NONE, 1.1 docs-emacs-nxml-zh_CN.xml, NONE, 1.1 docs-emacs-zh_CN.xml, NONE, 1.1 docs-getting-files-zh_CN.xml, NONE, 1.1 docs-intro-zh_CN.xml, NONE, 1.1 docs-rh-guidelines-zh_CN.xml, NONE, 1.1 docs-style-zh_CN.xml, NONE, 1.1 docs-tutorial-zh_CN.xml, NONE, 1.1 docs-vim-zh_CN.xml, NONE, 1.1 docs-xml-tags-zh_CN.xml, NONE, 1.1 documentation-guide-zh_CN.xml, NONE, 1.1

Yuan Yijun (bbbush) fedora-docs-commits at redhat.com
Fri Dec 9 15:29:03 UTC 2005 

Author: bbbush

Update of /cvs/docs/documentation-guide
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv24110

Added Files:
	acknowledgments-zh_CN.xml docs-converting-zh_CN.xml 
	docs-emacs-nxml-zh_CN.xml docs-emacs-zh_CN.xml 
	docs-getting-files-zh_CN.xml docs-intro-zh_CN.xml 
	docs-rh-guidelines-zh_CN.xml docs-style-zh_CN.xml 
	docs-tutorial-zh_CN.xml docs-vim-zh_CN.xml 
	docs-xml-tags-zh_CN.xml documentation-guide-zh_CN.xml 
Log Message:



--- NEW FILE acknowledgments-zh_CN.xml ---
<?xml version="1.0" encoding="utf-8"?>
<chapter id="acknowledgments">
  <title>致谢</title>
  <para>本文档基于 Tammy Fox (tfox at redhat.com) 起草的一篇文档，并得到了 Sandra Moore (smoore at redhat.com) 和 Johnray Fuller (jrfuller at redhat.com) 的协助。</para>
  <para>Roozbeh Pournader (roozbeh at sharif.edu) 的补丁已被合并，修正了一些拼写错误，解释了匿名 CVS 访问时禁止提交的情况。</para>
  <para>Gavin Henry (ghenry at suretecsystems.com) 的补丁已被合并，向 <filename>docs-xml-tags.xml</filename> 中的 <command>figure</command> 标记范例添加尾部斜线，以及添加 <xref linkend="ch-emacs-nxml"/>。</para>
  <para>Joshua Daniel Franklin (joshuadfranklin at yahoo.com) 的补丁已被合并，添加 <xref linkend="ch-vim"/>。</para>
  <para>Karsten Wade (kwade at redhat.com) 的补丁已被合并，添加 <xref linkend="s1-screenshots"/>。它为 Paul W. Frields (stickstr5 at hotmail.com) 编辑。</para>
  <para>Paul W. Frields (stickstr5 at hotmail.com) 的补丁已被合并，向 <xref linkend="s1-xml-tags-screen"/> 中的 <command>screen</command> 标记集合添加更多解释。</para>
</chapter>


***** Error reading new file: [Errno 2] No such file or directory: 'docs-converting-zh_CN.xml'

--- NEW FILE docs-emacs-nxml-zh_CN.xml ---
<?xml version="1.0" encoding="utf-8"?>
<chapter id="ch-emacs-nxml">
  <title>Emacs 与 nXML 模式</title>
  <indexterm>
    <primary>nXML</primary>
  </indexterm>
  <indexterm>
    <primary>Emacs</primary>
  </indexterm>
  <indexterm>
    <primary>Emacs</primary>
    <secondary>nXML 模式</secondary>
  </indexterm>
  <para>您可以使用 <application>Emacs</application> 的 nXML 模式，使撰写 DocBook XML 格式更加简单。nXML 模式提供了上下文敏感的编辑模式，包括补全、实时的有效性检测、语法高亮和缩进。为此您只要安装一个 RPM 软件包！</para>
  <note>
    <title>开发早期</title>
    <para>需要注意的是，<application>Emacs</application> 的 nXML 模式尚不完善，因此在编辑一些文档时，高级用户可能会注意到一些问题。如果您略微关注一下邮件列表，就可以获得相关信息，也可以问问题。请参考 <xref linkend="s1-emacs-nxml-readme"/>。</para>
  </note>
  <sect1 id="s1-nxml-rpm">
    <title>下载 nXML RPM</title>
    <indexterm>
      <primary>nXML</primary>
      <secondary>RPM</secondary>
    </indexterm>
    <indexterm>
      <primary>nXML RPM</primary>
    </indexterm>
    <para>要在 emacs 中使用 nXML 模式，您需要安装 <ulink url="http://people.redhat.com/twaugh/ftp/docbook/nxml-modee/"> Tim Waugh <ulink> 网站上的 nXML RPM，或者下载 <ulink url="http://www.thaiopensource.com/download/">http://www.thaiopensource.com/download/</ulink> 的源代码。源代码需要花工夫来配置，因此这里只考虑 RPM 版本。</ulink></ulink></para>
    <para>关于下载源代码请参考 <xref linkend="s1-emacs-additional-resources"/>。</para>
  </sect1>
  <sect1 id="s1-nxml-examples">
    <title>范例</title>
    <para>与 PSGML 模式相比，您只需有数几个命令。这样使用 <application>Emacs</application> 编辑就快捷多了，您可以更多地关注文章的内容。</para>
    <sect2 id="s2-nxml-commands">
      <title>命令</title>
      <para>要创建一个标记，输入 <userinput><</userinput> 然后输入关键字。要完成这个关键字，按下 <command>Ctrl-Ret</command>，然后添加随后的 <userinput>></userinput>。要关闭一个标记，输入 <userinput></</userinput>。</para>
      <important>
        <title>注意</title>
        <para>当您打开不包含首部 DOCTYPE 声明的文件时，将看到如下信息，标记补全也无法实现，因为 nXML 不知道您在编辑的文件格式。</para>
      </important>
      <para>要加载 schema，按下 <command>Ctrl-c</command>，然后按 <command>Ctrl-s</command> 然后浏览 <filename>/usr/share/emacs/site-lisp/nxml-mode/schema/</filename> 并加载 <filename>docbook.rnc</filename>。<application>Emacs</application> 将提示您将它保存到工作目录。</para>
      <tip>
        <title>技巧</title>
        <para>已描述过的命令只是 <application>Emacs</application> PSGML 模式与 <application>Emacs</application> nXML 模式的不同之处。您仍然需要使用 <xref linkend="s1-emacs-basic-commands"/> 中描述的命令。</para>
      </tip>
    </sect2>
  </sect1>
  <sect1 id="s1-emacs-nxml-additional-resources">
    <title>其他资源</title>
    <para>其他的 Emacs 与 nXML 帮助可以在下列位置找到：</para>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="http://www.thaiopensource.com/download/">http://www.thaiopensource.com/download/</ulink> — <citetitle>Author's download area</citetitle></para>
      </listitem>
      <listitem>
        <para>
          <ulink url="http://wks.uts.ohio-state.edu/unix_course/intro-135.html">http://wks.uts.ohio-state.edu/unix_course/intro-135.html</ulink> — <citetitle>Emacs Quick Reference Guide</citetitle></para>
      </listitem>
      <listitem>
        <para>
          <filename>emacs</filename> 软件包附带了 Emacs 参考卡片。您可以打印一份，作为参考。— <filename>/usr/share/emacs/<replaceable><version></replaceable>/etc/refcard.ps</filename></para>
      </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="s1-emacs-nxml-readme">
    <title>nXML README 文件</title>
    <note>
      <title>注意</title>
      <para>这个文件可以在您解压的源代码中找到，如果安装了 RPM，它的位置是 <filename>/usr/share/doc/nxml-mode-<replaceable><version></replaceable>/</filename>。</para>
    </note>
    <para>README 文件：</para>
    <para>这是 GNU Emacs 的一种新的主模式。它支持格式良好的 XML 文档，也为采用 RELAX NG Compact Syntax 的 XML 文档提供了 schema-sensitive 编辑模式。</para>
    <para>要使用它，您需要 GNU Emacs 21.x 版本，推荐 21.3。GNU Emacs 20 版本中无法正常运作，XEmacs 也不行。要开始编辑，输入命令：</para>
    <screen>
      <command>M-x load-file RET rng-auto.el RET</command>
    </screen>
    <para>这样定义了必需的 autoloads。然后，打开一个包含 XML 文档的文件，执行命令：</para>
    <screen>
      <command>M-x nxml-mode</command>
    </screen>
    <para>然后执行</para>
    <screen>
      <command>C-h m</command>
    </screen>
    <para>来查看 nXML 模式的使用帮助。手册的起始页在 nxml-mode.info 中，可以这样阅读它：</para>
    <screen>
      <command>C-u M-x info RET nxml-mode.info RET</command>
    </screen>
    <para>它也在顶层 info 目录最后添加了自己的一项，因此您可以和平常一样，用 <command>C-h i</command> 开始阅读。</para>
    <para>您可以用 <filename>test.valid.xml</filename> 和 <filename>test.invalid.xml</filename> 作为正确和不正确的 XML 文档范例。</para>
    <para>要在 Emacs 启动时自动加载这些，将下列内容加入您的 <filename>.emacs</filename>：</para>
    <screen>
      <computeroutput>
(load "~/nxml-mode-200YMMDD/rng-auto.el")
</computeroutput>
    </screen>
    <para>这里 <computeroutput>~/nxml-mode-200YMMDD</computeroutput> 是包含 <filename>.elc</filename> 文件的目录。注意 <filename>rng-auto.el</filename> 不会加载所有 nXML 模式的代码；它仅仅设置环境，使得 nXML 模式的所有特性得以正确地自动加载。您不应尝试自动加载 <filename>rng-auto.el</filename> 本身。</para>
    <para>要在加载扩展名是 <filename>xml</filename>, <filename>xsl</filename>, <filename>rng</filename> 或 <filename>xhtml</filename> 的文件时自动切换到 nXML 模式，将下列内容加入您的 <filename>.emacs</filename>：</para>
    <screen>
      <computeroutput>
(setq auto-mode-alist
        (cons '("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode)
	      auto-mode-alist))
</computeroutput>
    </screen>
    <para>如果您编辑 iso-8859-N 编码的 XML，而不是 iso-8859-1，并且您运行的是 Emacs 21.3 或更新版本，那么最好打开 unify-8859-on-decoding-mode，将下列内容加入您的 <filename>.emacs</filename>：</para>
    <screen>
      <computeroutput>(unify-8859-on-decoding-mode)</computeroutput>
    </screen>
    <para>要使用验证以及 schema-sensitive 编辑模式，您需要文档的 RELAX NG Compact Syntax (RNC) schema 文件。schema 目录包含了常用文档类型的 schema。</para>
    <para>关于 RELAX NG 请参考 <ulink url="http://relaxng.org/">http://relaxng.org/</ulink>。</para>
    <para>关于 RELAX NG Compact NG 的教程请参考 <ulink url="http://relaxng.org/compact-tutorial.html">http://relaxng.org/compact-tutorial.html</ulink></para>
    <para>关于自动创建 RNC schema，推荐使用 Trang 程序：<ulink url="http://www.thaiopensource.com/relaxng/trang.html">http://eee.thaiopensource.com/relaxng/trang.html"</ulink></para>
    <para>您可以使用它来 <itemizedlist><listitem><para>从已有文档得出 RNC schema</para></listitem><listitem><para>将 DTD 转换为 RNC schema</para></listitem><listitem><para>将 RELAX NG XML syntax schema 转换为 RNC schema</para></listitem></itemizedlist></para>
    <para>要将 RELAX NG XML syntax (.rng) schema 转换为 RNC schema，您也可以使用 <ulink url="http://www.pantor.com/download.html">http://www.pantor.com/download.html"</ulink> 的 XSLT 样式表。</para>
    <para>要将 W3C XML Schema 转换为 RNC schema，您需要首先将它转换为 RELAX NG XML syntax，使用 Sun 的 RELAX NG 转换工具 rngconv (基于 MSV)。请参考 <ulink url="https://msv.dev.java.net/">https://www.dev.java.net/</ulink>。</para>
    <para>文件 <filename>NEWS</filename> 描述了最近的更改。</para>
    <para>请访问邮件列表 <ulink url="http://groups.yahoo.com/group/emacs-nxml-mode/">http://groups.yahoo.com/group/emacs-nxml-mode</ulink> 来提交 bug 和参与讨论。我将在那里发布新版本。</para>
    <para>James Clark</para>
    <para>jjc at thaiopensource.com</para>
  </sect1>
</chapter>


***** Error reading new file: [Errno 2] No such file or directory: 'docs-emacs-zh_CN.xml'

--- NEW FILE docs-getting-files-zh_CN.xml ---
<?xml version="1.0" encoding="utf-8"?>
<!-- $Id: --><!--
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

 <!ENTITY BOILERPLATE "This header makes editing XML easier" >

]>
--><chapter id="ch-getting-files">
  <title>下载文件</title>
  <para>要开始为 Docs Project 贡献力量，您需要适当的 DocBook XML 文件，样式表以及一些脚本。需要安装下列软件包：</para>
  <itemizedlist>
    <listitem>
      <para>
        <filename>xmlto</filename> — 生成 HTML å’Œ PDF 版本的输出</para>
    </listitem>
    <listitem>
      <para>
        <filename>docbook-style-xsl</filename> — 我们默认使用的 XSLT 样式表</para>
    </listitem>
    <listitem>
      <para>
        <filename>docbook-dtds</filename> — DocBook DTD 针对 XML 的版本</para>
    </listitem>
  </itemizedlist>
  <para>常用的脚本和样式表都存放在 <computeroutput>cvs.fedora.redhat.com</computeroutput> CVS 服务器的仓库中。您需要将它们以及已有文档的 DocBook XML 文件检出。</para>
  <para>您应当只在第一次从 docs CVS 检出时，做这些动作。当您看到密码提示时，按下 <keycap>Enter</keycap>。</para>
  <screen>
    <userinput>mkdir my-fedora-docs
cd my-fedora-docs
export CVSROOT=:pserver:anonymous at cvs.fedora.redhat.com:/cvs/docs
cvs login
cvs co docs-common
cvs co example-tutorial</userinput>
  </screen>
  <para>当您进行匿名 CVS 检出时，您可以检视文件并获取更新的版本。您不可以添加或提交更新到服务器中。要提交修改，必须有 <abbrev>CVS</abbrev> 写权限。关于获取 <abbrev>CVS</abbrev> 写权限请参考 <ulink url="http://fedoraproject.org/wiki/DocsProject/NewWriters"/>。</para>
  <para>要查看已有文档的列表：</para>
  <screen>
    <userinput>cvs co -c</userinput>
  </screen>
  <para>选择您感兴趣的文档，然后下载到工作目录：</para>
  <screen>
    <userinput>cvs co example-tutorial</userinput>
  </screen>
  <para>除了 <citetitle>&IG;</citetitle> 之外，CVS 中所有文档必须是 DocBook XML article 格式，使用 <filename>example-tutorial</filename> 目录中的模板。每个文档 <emphasis>必须</emphasis> 有自己的目录。根目录中不允许有 XML 文件。</para>
</chapter>


***** Error reading new file: [Errno 2] No such file or directory: 'docs-intro-zh_CN.xml'

***** Error reading new file: [Errno 2] No such file or directory: 'docs-rh-guidelines-zh_CN.xml'

--- NEW FILE docs-style-zh_CN.xml ---
<?xml version="1.0" encoding="utf-8"?>
<!-- $Id: --><chapter id="ch-style">
  <title>写作风格</title>
  <para>撰写完善的技术文档不仅仅指展示命令行和指令集。好文档应当容易阅读、理解、翻译，表达准确的概念间的逻辑关系。好文档也可以用 <emphasis>不应当做的</emphasis> 事情来定义。您的文档应当避免：</para>
  <itemizedlist>
    <listitem>
      <para>冗长</para>
    </listitem>
    <listitem>
      <para>多余的，不加解释的行话</para>
    </listitem>
    <listitem>
      <para>语法或拼写错误</para>
    </listitem>
    <listitem>
      <para>对个人经历的引证</para>
    </listitem>
    <listitem>
      <para>可能触犯或迷惑用户的评论</para>
    </listitem>
  </itemizedlist>
  <para>这一章包含了 &FED; 文档写作风格的规则和准则。准则与规则不同，即使违反了准则，如果您的文章更加易于理解，那么没有关系。尽量遵循准则，总是遵循规则。如果没有明确表明，一个建议就是一个准则。</para>
  <section id="sn-intro-to-style">
    <title>为何写作风格很重要</title>
    <para>优秀的写作不是天生的。它是一种技术，即使专业的作者，甚至有名的作家，也必须时常练习。 <firstterm>写作风格</firstterm><indexterm><primary>style</primary></indexterm> 是将优秀的作品与平直的描述区分开的特性。</para>
    <para>优秀的作品有多种形式。对于诗歌和散文，优秀的作品不会遵循一定的语法、句法或拼写规则。一个著名的例子是 James Joyce 的小说 <citetitle>Ulysses</citetitle> 中的 Episode 18, "Penelope," <footnote id="fn-ulysses"><para><ulink url="http://www.online-literature.com/james_joyce/ulysses/18/">http://www.online-literature.com/james_joyce/ulysses/18/</ulink>。请注意这个例子包含一些成人内容，因此不适于所有用户。</para></footnote>。那里，Joyce 使用长串的词汇，不加标点，来摹拟角色的内心意识。虽然违反了语法和句法的基本规则，Joyce 描绘了叙述者无组织却又松散联系的思考方式。</para>
    <para>技术文档却必须遵循这些规则。文档与标准语法偏差越大，读者就会觉得越难理解。例如，读者也许并不以文档语言为母语，或者正在阅读译本。这时，如果作者使用方言、习语或者行话，读者和译者会很容易被迷惑。下面的例子比较了表达同样含义的不同做法：</para>
    <example>
      <title>不正确的风格</title>
      <!-- I prefer "incorrect," because I think terms such as
	"problematic" are mealy-mouthed.  They remind me of the late
	1980's English textbook trend toward the politically correct yet
	wholly unhelpful "standard/nonstandard."  But then, I tend to be
	dogmatic; it's probably my Catholic upbringing. [PWF] -->
      <para>So you made the changes I showed you in the last section. What's the next thing you should do? Just pop your thumb drive onto your system and read the <filename>messages</filename> log. When you see "USB device found," then Bob's your uncle.</para>
    </example>
    <example>
      <title>正确的风格</title>
      <!-- I prefer "correct." See above. [PWF] -->
      <para>After you complete the configuration changes above, attach the USB removable media to your system. Use the <command>dmesg</command> command to examine the kernel message log. The message <computeroutput>USB device
	  found</computeroutput> indicates that your device was installed successfully.</para>
    </example>
    <para>第一个例子是更口语化的英语，它不适于正式的文档。第二个例子更加正式，但是无论是对英语用户还是译者，它都更容易理解。</para>
    <para>遵守写作风格规则和准则，可以使读者阅读大量文档时更轻松。一致的风格有助于增强文档的专业性和价值认同。另一方面，忽略标点或语法错误将使读者对文档产生抵触。读者会认为基本正确的一篇文档不够权威，因为它写得很差。读者不必为理解作者的语言而头疼时才会放松下来。</para>
    <para>这一章不可能包含足够的内容，使每个读过的人变成一个好作者。一些专门讲述写作风格的手册可能会有几百页。这一章为中级作者理解技术文档的写作风格提供了足够的准则。</para>
    <para>如果您不是有经验的作者，无论技术文档还是其他，您还可以从其他资源中学到很多。下面的列表仍不够完善，但是提供了一个起点：</para>
    <itemizedlist>
      <listitem>
        <para>
          <citetitle>The Elements of Style</citetitle>, 作者 William Strunk. 在线阅读: <ulink url="http://bartleby.com/141/">http://bartleby.com/141/</ulink></para>
      </listitem>
      <!-- placeholder for when it's ready
        <para>
          <citetitle>The Elements of Style</citetitle>, by William
          Strunk.  Fedora Docs Project version: <ulink
            url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>
        </para>
-->
      <listitem>
        <para>
          <citetitle>The Chicago Manual of Style</citetitle>, 作者 the University of Chicago Press. 在线阅读: <ulink url="http://www.chicagomanualofstyle.org/">http://www.chicagomanualofstyle.org/</ulink></para>
      </listitem>
      <listitem>
        <para>
          <citetitle>Paradigm Online Writing Assistant</citetitle>, 维护者 Chuck Guilford, Ph.D. 在线阅读: <ulink url="http://www.powa.org/">http://www.powa.org/</ulink></para>
      </listitem>
    </itemizedlist>
    <para>很多自由软件的文档计划有自己的文档风格准则。实际上，这一章很多内容来自 <citetitle>GNOME Documentation Style Guidelines</citetitle> (<firstterm>GDSG</firstterm>)。您可以看到本来的 <citetitle>GDSG</citetitle>，位置是 <ulink url="http://developer.gnome.org/documents/style-guide/">http://developer.gnome.org/documents/style-guide/</ulink>。</para>
  </section>
  <section id="sn-tech-docs-fundamentals">
    <title>技术文档的基本概念</title>
    <note>
      <title>参考书目信息</title>
      <para>这一节来自 <citetitle>GDSG</citetitle>。</para>
    </note>
    <!-- This section will reproduce mostly what is in Chapter 1 of
      the GDSG.  There may be minor changes.  FIXME: Make sure the
      appropriate front matter of the Documentation Guide includes
      attribution as required by the GNU FDL. -->
    <para>这一章提供了写作技术文档的简要介绍。</para>
    <section id="sn-fundamentals-1">
      <title>写作风格一般要求</title>
      <para>&FP; 技术文档写作在一般要求的基础上，有特殊的约束。好的 &FED; 技术文档应当有下列特点：</para>
      <variablelist>
        <varlistentry>
          <term>完备</term>
          <listitem>
            <para>描述一个产品的全部功能。不可忽略个人认为对用户没有用处的功能。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>一致</term>
          <!-- I'm having issues with the
          sketchy definition of this non-dictionary word and the
          associated text.  Not wrong, per se, just wishing for
          something better.  This note shall remind us! - kwade -->
	  <!-- Hopefully this change helps.  Makes sense according to the
          gdict tool in Core, at least.  - PWF -->
          <listitem>
            <para>描述看到的内容。不要描述想要看到的内容。将信息以用户切身经历的顺序表达出来。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>清楚</term>
          <listitem>
            <para>阅读 <citetitle>The Elements of Style</citetitle> (<ulink url="http://www.bartleby.com/141/">http://www.bartleby.com/141/</ulink>) 来撰写清楚的文档。</para>
          
<!-- placeholder for when this is published:
            <para>
              Read <citetitle>The Elements of Style</citetitle>
                &FED;-version (<ulink
                url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>)
              to help make your writing clear.
            </para>
-->
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>è¿žè´¯</term>
          <listitem>
            <para>在文档中使用约定俗成的词汇。如果其他作者在撰写相关的文档，那么使用相同的词汇。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>简明</term>
          <listitem>
            <para>写作时多检视作品，问问自己哪些可以删减。请参考 <xref linkend="sn-fundamentals-2"/>。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section id="sn-fundamentals-2">
      <title>原则</title>
      <para>这一节包含了一些基本的风格准则。本章的后续小节将展开详述这些准则。</para>
      <variablelist>
        <varlistentry>
          <term>原则一：简短</term>
          <listitem>
            <itemizedlist>
              <listitem>
                <para>将每句话限制到 25 个词以下。</para>
              </listitem>
              <listitem>
                <para>将每步过程限制到 23 个词以下。</para>
              </listitem>
            </itemizedlist>
            <example id="ex-golden-rule-1-wrong">
              <title>不正确：过长</title>
              <para>Under normal operating conditions, the kernel does not always immediately write file data to the disks, storing it in a memory buffer and then periodically writing to the disks to speed up operations.</para>
            </example>
            <example id="ex-golden-rule-1-right">
              <title>正确：短句</title>
              <para>Normally, the kernel stores the data in memory prior to periodically writing the data to the disk.</para>
            </example>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>原则二：有条理</term>
          <listitem>
            <itemizedlist>
              <listitem>
                <para>每段讲述一个主题。</para>
              </listitem>
              <listitem>
                <para>每句话表达一个意思。</para>
              </listitem>
              <listitem>
                <para>每步操作只包含一个动作。</para>
              </listitem>
            </itemizedlist>
            <example id="ex-golden-rule-2-wrong">
              <title>不正确：没有条理</title>
              <para>The <application>Workspace Switcher</application> applet helps you navigate all of the virtual desktops available on your system. The X Window system, working in hand with a piece of software called a <emphasis>window manager</emphasis>, allows you to create more than one virtual desktop, known as <emphasis>workspaces</emphasis>, to organize your work, with different applications running in each workspace. The <application>Workspace Switcher</application> applet is a navigational tool to get around the various workspaces, providing a miniature road map in the GNOME panel showing all your workspaces and allowing you to switch easily between them.</para>
            </example>
            <example id="ex-golden-rule-2-right">
              <title>正确：有条理</title>
              <para>Use the <application>Workspace Switcher</application> to add new <emphasis>workspaces</emphasis> to the GNOME Desktop. You can run different applications in each workspace. The <application>Workspace Switcher</application> applet provides a miniature map that shows all of your workspaces. You can use the <application>Workspace Switcher</application> applet to switch between workspaces.</para>
            </example>
            <tip>
              <para>在撰写前规划段落的顺序。决定在每段应当涵盖的主题。</para>
            </tip>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>原则三：使用指示</term>
          <listitem>
            <para>使用例子来演示如何操作。提供指示，而不是描述。</para>
            <example id="ex-golden-rule-3-wrong">
              <title>不正确：描述而不指示</title>
              <para>There is a text box that you can use to find out the definition of a word.</para>
            </example>
            <example id="ex-golden-rule-3-right">
              <title>正确：指示用法</title>
              <para>To request a definition of a word, type the word in the text box, then select <guilabel>Lookup</guilabel>.</para>
            </example>
            <tip>
              <para>不要过于教条。有时您需要解释，以说明那些范例。</para>
            </tip>
          </listitem>
        </varlistentry>
        <varlistentry id="vle-golden-rule-4">
          <term>原则四：客观</term>
          <listitem>
            <para>以中立的语气写作。</para>
            <example id="ex-golden-rule-4-wrong">
              <title>不正确：偏倚一方</title>
              <para>The applet is a handy little screen grabber.</para>
            </example>
            <example id="ex-golden-rule-4-right">
              <title>正确：客观陈述</title>
              <para>Use the applet to take screenshots.</para>
            </example>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section id="sn-fundamentals-3">
      <title>语气</title>
      <para>不合适的语气会妨碍读者获取信息。中立的，不带个人好恶选择的语气可以促进读者的理解。中立的语气使较大的文档项目中的作者可以并行写作。另外，新的作者可以随时加入。中立的语气可以在系列文档之间实现一致，便于用户获得信息。要达到共同的中立的语气，最好的办法是采用下列原则：</para>
      <variablelist>
        <varlistentry>
          <term>避免幽默</term>
          <listitem>
            <para>幽默使注意力从您的信息中移开。幽默也使文档难以翻译。保持直白。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>避免个人好恶选择</term>
          <listitem>
            <para>无论您认为某个功能是否好坏都不重要。将功能展示给用户，包含如何使用这些功能的指示。保持准确。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>避免口语</term>
          <listitem>
            <para>口语难以翻译，通常是与文化相关的。保持中立。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>避免一时的论断</term>
          <listitem>
            <para>一个论断在今天被认同，在明天就可能被推翻。保持技术化。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>避免展望将来</term>
          <listitem>
            <para>关于某个产品的将来，这不属于技术文档。只撰写您现在看到的东西。要实际。</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section id="sn-fundamentals-4">
      <title>面向正确的用户</title>
      <para>您对文档的结构和内容的定夺应当基于对读者的理解。考虑读者如何获取文档，需要哪些信息，曾经的经验等等。通常，您需要创建适合不同群体的文档。下面几节包含了您需要考虑的与读者相关的主题。</para>
    </section>
    <section id="sn-fundamentals-6">
      <title>用户的动机</title>
      <para>不要浪费想在文档中获取信息的读者的时间。用户阅读技术文档不是为了取乐。用户通常带有特定的问题。您需要对这些问题作出明确的回答。</para>
    </section>
    <section id="sn-fundamentals-7">
      <title>新用户</title>
      <para>&FC; 的新用户遇到不熟悉的应用程序或功能时，通常会查阅在线教程。每个教程应当包含足够的介绍信息，告诉新用户如何使用相关的功能。每个教程还应当包含足够的使用说明，告诉用户他们可以用这个命令或功能作出的种种动作。使这些说明面向任务。在教程中不要描述 GUI 屏幕、对话框和对话框元素，除非某个特性影响了您的说明。</para>
    </section>
    <section id="sn-fundamentals-8">
      <title>有经验的用户</title>
      <para>有经验的用户通常将文档作为参考。文档需要完备，组织合理，如果是打印的方式，还需要索引。</para>
    </section>
    <section id="sn-fundamentals-9">
      <title>不要触犯读者</title>
      <para>为避免触犯读者，文档应遵循下列准则：</para>
      <variablelist>
        <varlistentry>
          <term>避免内部用语</term>
          <listitem>
            <para>内部用语包括行话和计算机社群中常见的缩写风气。例如，使用<literal>docs</literal> 而不是 <literal>documentation</literal>。一个词如果满足下面的条件，就是一句行话：</para>
            <itemizedlist>
              <listitem>
                <para>这个词没有包含在 <citetitle>&FED; Jargon Buster</citetitle> (<ulink url="http://fedora.redhat.com/docs/jargon-buster/">http://fedora.redhat.com/docs/jargon-buster/</ulink>) 中。</para>
              </listitem>
              <listitem>
                <para>这个词没有包含在 <citetitle>American Heritage Dictionary</citetitle> (<ulink url="http://www.bartleby.com/61/">http://www.bartleby.com/61/ </ulink>) 中。</para>
              </listitem>
              <listitem>
                <para>这个词没有出现在您撰写的文档的词汇表中。</para>
              </listitem>
              <listitem>
                <para>这个词也没有在您撰写的文档中定义。</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>避免性别相关的语言</term>
          <listitem>
            <para>不要出现代词 <literal>他的/她的</literal> 或 <literal>他/她</literal>。在指令中不必区分性别。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>避免特定文化的语言</term>
          <listitem>
            <para>如果您的范例只能让您周围方圆百里的人看懂，那么它没有意义。</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>不要用高人一等的口气</term>
          <listitem>
            <para>如果文档中说，一个动作很容易或很快，而实际上用户无法完成，那没有比这更能让读者郁闷的了。不要评价和判断动作。</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>准则的其他部分是对可能造成触犯的语气和语言用法的详细说明。</para>
    </section>
  </section>
  <section id="sn-grammar-and-usage">
    <title>语法和用法准则</title>
    <note>
      <title>参考书目信息</title>
      <para>这一节部分来自 <citetitle>GDSG</citetitle>，部分来自 <citetitle>The Elements of Style</citetitle>，为二十一世纪的技术文档作者进行了更新。</para>
    </note>
    <!-- FIXME: Again, check attribution viz.  GNU FDL.  This will be more work
      than the previous section. -->
    <para>这一节包含了字母序排列的语法和用法准则，用于 &FED; 文档。很多准则只适用于英语，请参考 <citetitle>American Heritage Dictionary</citetitle> (<ulink url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) 和 <citetitle>Chicago Manual of Style</citetitle> (<ulink url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>)。</para>
    <variablelist>
      <varlistentry>
        <term>缩写</term>
        <listitem>
          <para>词或短语的简写形式，可以代替原来的词使用，例如 <literal>Dr.</literal>, <literal>a.m.</literal>, <literal>p.m.</literal> 等等。在使用缩写时，遵循下列规则：</para>
          <itemizedlist>
            <listitem>
              <para>避免创造新的缩写。不熟悉的缩写造成混淆，无法表明一个概念。</para>
            </listitem>
            <listitem>
              <para>不要解释或展开众所周知的缩写。</para>
            </listitem>
            <listitem>
              <para>不要在文档的词汇表中包含众所周知的缩写。</para>
            </listitem>
          </itemizedlist>
          <para>对于短语的缩写，例如 <literal>i.e.</literal> ("in other words", 换句话说) 和 <literal>e.g.</literal> ("for example", 例如)，不要使用缩写。拼写出整个短语。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>形容词</term>
        <listitem>
          <para>小心使用形容词。在必须使用形容词来区分对象时再用。无论合适，检查是否可以把形容词去掉。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>首字母组合词</term>
        <listitem>
          <para>用来表达一个由多个词组成的概念。通常，首字母组合词是这样构造的：</para>
          <itemizedlist>
            <listitem>
              <para>From the first letters of each word in a compound term, for example Table of Contents (TOC).</para>
            </listitem>
            <listitem>
              <para>From recognizable parts of a compound term, such as GNU Object Model Environment (GNOME).</para>
            </listitem>
          </itemizedlist>
          <para>在使用首字母组合词的时候，遵循下列规则：</para>
          <itemizedlist>
            <listitem>
              <para>在第一次使用时，拼写完整的名称，在括号中包含组合词。</para>
            </listitem>
            <listitem>
              <para>不要拼写出众所周知的首字母组合，除非您认为这对读者有用。</para>
            </listitem>
            <listitem>
              <para>不要创建新的首字母组合。不熟悉的组合将造成混淆，无法表达清楚。</para>
            </listitem>
            <listitem>
              <para>用大写表示，除非必须用小写。</para>
            </listitem>
            <listitem>
              <para>在文档的词汇表中包含首字母组合和全称。</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>副词</term>
        <listitem>
          <para>小心使用副词。在必须用副词修饰组件的功能时再用。无论合适，检测是否可以去掉副词。经典的冗余副词包括 <literal>容易地</literal>，<literal>简单地</literal> 和 <literal>迅速地</literal>。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>拟人</term>
        <listitem>
          <itemizedlist>
            <listitem>
              <para>不要让应用程序软件充满情绪、欲望或意见。</para>
            </listitem>
            <listitem>
              <para>不要让应用程序软件产生位置、维度的感觉。用户不会 "处在" 一个文本编辑器里。</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>冠词</term>
        <listitem>
          <para>不要在下列对象前面使用定冠词 <literal>the</literal>：</para>
          <itemizedlist>
            <listitem>
              <para>文章标题</para>
            </listitem>
            <listitem>
              <para>段的标题</para>
            </listitem>
            <listitem>
              <para>标题</para>
            </listitem>
            <listitem>
              <para>图象说明</para>
            </listitem>
            <listitem>
              <para>表格说明</para>
            </listitem>
            <listitem>
              <para>列表</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>撇号</term>
        <listitem>
          <para>尽可能不要使用撇号</para>
          <itemizedlist>
            <listitem>
              <para>不要用撇号来表达从属和拥有的关系</para>
            </listitem>
            <listitem>
              <para>不要用撇号来表达缩写</para>
            </listitem>
            <listitem>
              <para>不要用撇号来表达复数</para>
            </listitem>
          </itemizedlist>
          <example id="ex-apostrophe-wrong">
            <title>不正确的撇号</title>
            <itemizedlist>
              <listitem>
                <para>the <guimenu>Main Menu's</guimenu><guimenuitem>Help</guimenuitem> option</para>
              </listitem>
              <listitem>
                <para>don't use the default option</para>
              </listitem>
              <listitem>
                <para>several SCSI disk's</para>
              </listitem>
            </itemizedlist>
          </example>
          <example id="ex-apostrophe-right">
            <title>正确：不使用撇号</title>
            <itemizedlist>
              <listitem>
                <para>the <guimenuitem>Help</guimenuitem> option on the <guimenu>Main Menu</guimenu></para>
              </listitem>
              <listitem>
                <para>do not use the default option</para>
              </listitem>
              <listitem>
                <para>several SCSI disks</para>
              </listitem>
            </itemizedlist>
          </example>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>方括号</term>
        <listitem>
          <itemizedlist>
            <listitem>
              <para>不要使用方括号 [就像这样] 替换圆括号 (就像这样)</para>
            </listitem>
            <listitem>
              <para>使用方括号表达可选的命令行参数</para>
            </listitem>
            <listitem>
              <para>不要使用尖括号表达文本中的变量，应使用 <sgmltag class="starttag">replaceable</sgmltag> 标记。标记用法请参考 <xref linkend="s1-xml-tags-replaceable"/>。</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>大写</term>
        <listitem>
          <para>下列情况下大写：</para>
          <itemizedlist>
            <listitem>
              <para>首字母缩写中的所有字母，除非是众所周知的特例</para>
            </listitem>
            <listitem>
              <para>列表中第一个词的第一个字母</para>
            </listitem>
            <listitem>
              <para>顺序列表中第一个词的第一个字母</para>
            </listitem>
            <listitem>
              <para>按键名称的第一个字母，例如 <keycap>Shift</keycap></para>
            </listitem>
            <listitem>
              <para>句子的第一个字母</para>
              <note>
                <title>命令名</title>
                <para>避免在句首使用命令名或应用程序名称，如果它们的首字母是小写的话。</para>
              </note>
            </listitem>
            <listitem>
              <para>冒号后面完整句子的首字母</para>
            </listitem>
          </itemizedlist>
          <para>下列情况下不要大写：</para>
          <itemizedlist>
            <listitem>
              <para>组合的名词，后面是缩写或首字母组合</para>
            </listitem>
            <listitem>
              <para>如果要强调一些内容</para>
            </listitem>
            <listitem>
              <para>变量名</para>
            </listitem>
            <listitem>
              <para>冒号后面，不完整句子的首字母</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>标题</term>
        <listitem>
          <para>对于标题，以及图象和表格的说明，使用相同的规则。不要在标题最后加上句号。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>冒号</term>
        <listitem>
          <para>在下列情况下，使用冒号：</para>
          <itemizedlist>
            <listitem>
              <para>引入列表</para>
            </listitem>
            <listitem>
              <para>在解释的前面</para>
            </listitem>
            <listitem>
              <para>在介绍之后</para>
            </listitem>
          </itemizedlist>
          <para>下列情况下，不要使用冒号：</para>
          <itemizedlist>
            <listitem>
              <para>要引入图象或表格</para>
            </listitem>
            <listitem>
              <para>介绍标题</para>
            </listitem>
            <listitem>
              <para>介绍一个过程之后</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>表栏标题</term>
        <listitem>
          <para>使用与标题相同的规则</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>逗号</term>
        <listitem>
          <para>下列情况下，使用逗号：</para>
          <itemizedlist>
            <listitem>
              <para>区分系列中的对象</para>
            </listitem>
            <listitem>
              <para>区分句子的部分</para>
            </listitem>
            <listitem>
              <para>区分非限制性的短语</para>
            </listitem>
            <listitem>
              <para>与破折号类似，表达同位语</para>
            </listitem>
            <listitem>
              <para>在 <emphasis>例如，</emphasis> 和类似的表达中</para>
            </listitem>
          </itemizedlist>
          <para>下列情况下，不要使用逗号：</para>
          <itemizedlist>
            <listitem>
              <para>一系列形容词修饰一个对象时</para>
            </listitem>
            <listitem>
              <para>两个短的独立子句间</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>命令</term>
        <listitem>
          <para>不要将命令作为动词。</para>
        </listitem>
      </varlistentry>
      <varlistentry id="vle-contractions">
        <term>缩写</term>
        <listitem>
          <para>不要使用缩写，类似 <emphasis>can't</emphasis>, <emphasis>don't</emphasis>, 或 <emphasis>isn't</emphasis>。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>破折号</term>
        <listitem>
          <para>不要使用破折号或连接号。使用分段或冒号，如果是介绍性文字的话。如果有很多内容要介绍，那么使用一个列表。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>省略号</term>
        <listitem>
          <para>下列情况下，使用省略号：</para>
          <itemizedlist>
            <listitem>
              <para>要表示忽略了句子的一部分</para>
            </listitem>
            <listitem>
              <para>要表示引用文本的间断</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>分数</term>
        <listitem>
          <para>使用分数时，遵循这些规则：</para>
          <itemizedlist>
            <listitem>
              <para>在表格中，以及度量单位中，使用分数的数字形式，在正文中使用文本形式。</para>
            </listitem>
            <listitem>
              <para>数字和相连的分数间添加空格，以防混淆。例如：1 1/2 而不是 11/2。</para>
            </listitem>
            <listitem>
              <para>如果分数用作复合的修饰，在分数和度量单位间添加连字符。</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>性别</term>
        <listitem>
          <para>请参考 <xref linkend="sn-fundamentals-9"/>。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>语法</term>
        <listitem>
          <para>标准的英语语法规则，请参考 <citetitle>Chicago Manual of Style</citetitle> (<ulink url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>)。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>标题</term>
        <listitem>
          <para>在标题中使用下面的大写规则：</para>
          <itemizedlist>
            <listitem>
              <para>第一个词的首字母大写</para>
            </listitem>
            <listitem>
              <para>名词，形容词和动词的首字母大写</para>
            </listitem>
            <listitem>
              <para>连词，冠词和少于四个字母的介词都应小写</para>
            </listitem>
            <listitem>
              <para>四个字母的介词或更多时首字母大写</para>
            </listitem>
            <listitem>
              <para>四个字母的连词或更多时大写</para>
            </listitem>
          </itemizedlist>
        
	    <!-- <para> See <xref linkend="infodesign-2"/> for more
	    information about headings. </para> -->
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>连字符</term>
        <listitem>
          <para>下列情况下，使用连字符：</para>
          <itemizedlist>
            <listitem>
              <para>组合修饰中的数字</para>
            </listitem>
            <listitem>
              <para>避免混淆</para>
            </listitem>
            <listitem>
              <para>在标准的前缀和后缀中。请参考 <citetitle>American Heritage Dictionary</citetitle> (<ulink url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>)。</para>
            </listitem>
            <listitem>
              <para>在拼写的分数中</para>
            </listitem>
            <listitem>
              <para>在由两个或多个单词构成的变量名中，类似 <replaceable>directory-name</replaceable>。注意： <replaceable>filename</replaceable> 是特例。</para>
            </listitem>
          </itemizedlist>
          <para>下列情况下，不要使用连字符：</para>
          <itemizedlist>
            <listitem>
              <para>对于行话</para>
            </listitem>
            <listitem>
              <para>对于动词</para>
            </listitem>
            <listitem>
              <para>以 <emphasis>ly</emphasis> 结尾的副词</para>
            </listitem>
            <listitem>
              <para>数字作为单一修饰时</para>
            </listitem>
            <listitem>
              <para>
                <citetitle>American Heritage Dictionary</citetitle> (<ulink url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) 列为不需连字符的单词，以及有共同前缀的词</para>
            </listitem>
            <listitem>
              <para>商标</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>拉丁文名称</term>
        <listitem>
          <para>不要使用拉丁文名称。使用相应的英文名称。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>像</term>
        <listitem>
          <para>不要使用 <emphasis>像</emphasis> 来表达等价或相似。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>列表</term>
        <listitem>
          <para>使用以冒号结尾的完整的句子引入列表。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>æ•°å­—</term>
        <listitem>
          <para>下列情况下，拼写出数字：</para>
          <itemizedlist>
            <listitem>
              <para>从 0 到 9 的数字，除非数字是测度的一部分</para>
            </listitem>
            <listitem>
              <para>估计</para>
            </listitem>
            <listitem>
              <para>极端情况，类似 <emphasis>百万</emphasis>，但要在前面加上一个数字。</para>
            </listitem>
            <listitem>
              <para>出现在句子开头的数字</para>
            </listitem>
            <listitem>
              <para>后面紧接一个数的数字。例如：<literal>两个 10 MB 的文件</literal></para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>数字形式</term>
        <listitem>
          <para>下列情况下，使用数字：</para>
          <itemizedlist>
            <listitem>
              <para>数字 10 或更大</para>
            </listitem>
            <listitem>
              <para>è´Ÿæ•°</para>
            </listitem>
            <listitem>
              <para>大多数分数</para>
            </listitem>
            <listitem>
              <para>百分数</para>
            </listitem>
            <listitem>
              <para>小数</para>
            </listitem>
            <listitem>
              <para>测度</para>
            </listitem>
            <listitem>
              <para>小于一秒的时间单位</para>
            </listitem>
            <listitem>
              <para>对位和字节的引用</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>圆括号</term>
        <listitem>
          <para>下列情况下，使用圆括号：</para>
          <itemizedlist>
            <listitem>
              <para>要包含第一次出现的名称的缩写</para>
            </listitem>
            <listitem>
              <para>在手册页的引用中，指明章节号</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>句点</term>
        <listitem>
          <para>下列情况下，使用句号：</para>
          <itemizedlist>
            <listitem>
              <para>结束句子</para>
            </listitem>
            <listitem>
              <para>文件和目录名中</para>
            </listitem>
            <listitem>
              <para>可能被误认为单词的缩写中，类似 a.m. 和 U.S.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>标点</term>
        <listitem>
          <para>使用标准的英语标点规则。请参考 <citetitle>Chicago Manual of Style</citetitle> (<ulink url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>)。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>数字中的标点</term>
        <listitem>
          <para>不要在四位的数字中使用逗号。如果超过四位，那么使用逗号。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>引号</term>
        <listitem>
          <para>使用引号来表示内容是不变地从其他来源复制的。不要使用引号来区分不合适的用词。如果用词不合适，换一个别的。如果必须用这个词，就在词汇表中解释它，使这种用法变得合理。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>See v. Refer to</term>
        <listitem>
          <para>向用户提供参考资源时，使用 "refer to" 而不是 "see"，使用 "refer also to" 而不是 "see also"。这样可以与索引用到的 <sgmltag class="starttag">see</sgmltag> 和 <sgmltag class="starttag">seealso</sgmltag> 标记区分开。 这些标记用于在索引中创建特殊的链接。为了在文档中保持一致，我们保留关键字 "see" 和 "see also" 用作超链接的索引引用，使用 "refer to" 和 "refer also to" 表达非超链接的，非索引的引用。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>分号</term>
        <listitem>
          <para>不要使用分号。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>斜线</term>
        <listitem>
          <para>除了用作文件名的一部分之外，不要使用斜线 "/"。不能包含 <literal>and/or</literal> 这样的内容，应该换成其中任何一个。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>拼写</term>
        <listitem>
          <para>使用标准的英语拼写规则，请参考 <citetitle>American Heritage Dictionary</citetitle> (<ulink url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>)。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>书名</term>
        <listitem>
          <para>对于文档的名称，使用与标题相同的规则。</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>单位</term>
        <listitem>
          <para>使用单位时，遵循下列规则：</para>
          <itemizedlist>
            <listitem>
              <para>使用标准的单位缩写，不要自行创造缩写。</para>
            </listitem>
            <listitem>
              <para>请参考 <citetitle>IEEE Standard Dictionary of Electrical and Electronics Terms</citetitle>。</para>
            </listitem>
            <listitem>
              <para>在缩写的可能被误解为单词的单位中使用句点。</para>
            </listitem>
            <listitem>
              <para>大多数标准的缩写单位都同时适于单数和复数。</para>
            </listitem>
            <listitem>
              <para>在数字和单位之间加上空格。</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>
  <section id="sn-composition-tips">
    <title>行文技巧</title>
    <!--

    This section will collect miscellanea and advice for specific
    situations that the FDP editors encounter.  I hope they will feel
    free to e-mail me sticky situations or particularly interesting
    examples of work they've beautified.  Hopefully not too much will be
    drawn from my own work! - PWF.

-->
    <para>本节包含了一些技巧提示，来自 &FDP; 作者们曾遇到的情况。您应理解运用它们，来改善自己的文档。&FDP; 作者乐于接受新的范例。</para>
    <section id="sn-misc-active-voice">
      <title>主动语态</title>
      <para>总是使用主动语态，除非这样很别扭。文档告诉用户如何完成一项任务，应当给出清楚简明的指令。避免使用"必须", "需要"之类的词。这些词在文档中是多余的，因为读者期望看到您给出必要的步骤来完成任务。同样，避免使用"可能," "也许"等等，表示您对问题不很确定的词。您的文档应当权威地描述一个主题。读者不应担心按照文档做会有莫名奇妙的效果。</para>
      <example id="ex-misc-passive-voice">
        <title>不正确：被动语态</title>
        <para>命令 <command>yum update</command> 必须被运行。</para>
        <para>您也许想运行 <command>yum update</command> 命令。</para>
      </example>
      <example id="ex-misc-active-voice">
        <title>正确：主动语态</title>
        <para>运行 <command>yum update</command> 命令。</para>
      </example>
    </section>
    <section id="sn-present-tense">
      <title>一般现在时态</title>
      <para>以一般现在时态写作。最好的经验，是不需用 "将要" 来描述用户将要做或看到的内容。它们没有意义，并可能混淆翻译者。它们也通常与被动语态有关，请参考 <xref linkend="sn-misc-active-voice"/>。</para>
      <example id="ex-misc-future-tense">
        <title>不正确：将来时态</title>
        <para>应用程序将要显示目标文件的列表。</para>
        <para>目标文件的列表将要被应用程序显示出来。</para>
      </example>
      <example id="ex-misc-present-tense">
        <title>正确：一般现在时态</title>
        <para>应用程序显示目标文件的列表。</para>
      </example>
    </section>
    <section id="sn-narrative-voice">
      <title>叙述的语气</title>
      <para>不要用第一人称"我" "我们" 来引用作者自己 (无论是否包含读者)，&FDP;，&FED; 社群或任何群体。不要用第三人称指代用户 ("他" "她" 或 "他或她") 或者 "某人"。使用第二人称 "您" 来指代读者是可以的。</para>
      <example id="ex-misc-wrong-person">
        <title>不正确：第一或第三人称</title>
        <para>正如上文所述，我通常在配置 Samba 服务器之前运行 <command>up2date</command>。</para>
        <para>如果用户需要备份他的或她的文件，他或她应当使用 <command>tar</command> 或 <command>cpio</command> 命令。</para>
      </example>
      <example id="ex-misc-correct-person">
        <title>正确：第二人称，或不使用代词</title>
        <para>配置 Samba 服务器之前，请参考关于 <command>up2date</command> 的小节。</para>
        <para>如果需要，用户可以使用 <command>tar</command> 或 <command>cpio</command> 命令来备份文件。</para>
      </example>
    </section>
    <section id="sn-misc-negative">
      <title>否定的用词</title>
      <para>避免说不，因为它使教程显得武断。可以使用"避免"来代替。注意否定的词通常使用缩写，例如 <emphasis>don't</emphasis> 或 <emphasis>can't</emphasis>。请参考 <xref linkend="vle-contractions"/>。</para>
    </section>
    <section id="sn-misc-uncertainty">
      <title>不确定</title>
      <para>避免过度使用 "典型的"，"通常地"，"大多数时候"，"许多"等诸如此类的词。</para>
    </section>
    <section id="sn-misc-offtopic">
      <title>多余的内容</title>
      <para>避免涉及多余的内容，例如如何更新 &FC; 系统。这些关键的主题在其他教程中已有讲述。作者们经常违反这个准则，因为觉得自己的教程不够长。但是，不要偏离您的主题。如果其他教程可以完整的覆盖那些主题，那么指引读者阅读那些文档。</para>
    </section>
    <section id="sn-misc-importance">
      <title>自行评估价值</title>
      <para>避免类似 "最重要的是应该做 <replaceable>XYZ</replaceable>" 的表述。如果这个过程很重要，读者一定希望在您的文档中看到。反过来说，如果您的文档中出现了某个过程，作者一定会觉得那很重要，尤其是当这个过程占用了整整一节的时候。其实只要说 "做 <replaceable>XYZ</replaceable>"，然后详细说明就可以了。如果整整一节都是对如何做 <replaceable>XYZ</replaceable> 的说明，就干脆不要说这句话。请参考 <xref linkend="vle-golden-rule-4"/>。</para>
    </section>
    <section id="sn-misc-precision">
      <title>明确的语言</title>
      <para>对于用户应当做出的动作，使用明确的词汇。不要让读者 "去" 选择，或者让读者在菜单里 "找"。</para>
      <example id="ex-precision-wrong">
        <title>不正确：不明确的用词</title>
        <itemizedlist>
          <listitem>
            <para>转到 <guimenu>Main Menu</guimenu> -> <guimenuitem>Foobar</guimenuitem></para>
          </listitem>
          <listitem>
            <para>找到标记 <guilabel>Search</guilabel> 的选项</para>
          </listitem>
        </itemizedlist>
      </example>
      <example id="ex-precision-right">
        <title>正确：明确的用词</title>
        <itemizedlist>
          <listitem>
            <para>在 <guimenu>Main Menu</guimenu> 菜单中，选择 <guimenuitem>Foobar</guimenuitem></para>
          </listitem>
          <listitem>
            <para>选择 <guilabel>Search</guilabel> 选项。</para>
          </listitem>
        </itemizedlist>
      </example>
      <important>
        <title>不要区别对待非图形界面用户</title>
        <para>如果您的文档是关于纯图形界面程序的，那么可以随意使用 "点击"。如果应用程序有字符界面，那么可以使用 "选择"，像上面那样。</para>
      </important>
    </section>
    <section id="sn-misc-docbook-tips">
      <title>DocBook 技巧</title>
      <para>这一节包含关于如何在文档中更有效地使用 DocBook 标记的技巧。</para>
      <section id="sn-misc-admonitions">
        <title>创建提示</title>
        <para>避免过分使用提示。在提示中只包含最重要的内容，使提示尽可能短。将用来解释的背景说明移到提示之外。使用简短的描述性的标题。标题的大小写规则与正文标题一致。</para>
        <example id="ex-misc-ineffective-admonition">
          <title>不正确：过长的提示</title>
          <para>
            <warning>
              <title>使用 <command>sfdisk</command> 检测输入</title>
              <para>
                <command>sfdisk</command> 命令接受一个脚本文件作为标准输入，来设置硬盘的分区。<command>sfdisk</command> 有些情况下拒绝一个有错的输入文件。在另一些情况下，它将无保留的执行输入，在硬盘上写入错误的分区。在写入磁盘前，总是用 <command>sfdisk -n</command> 命令检测输入文件。</para>
            </warning>
          </para>
        </example>
        <example id="ex-misc-good-admonition">
          <title>正确：简短的提示</title>
          <para>
            <command>sfdisk</command> 命令接受一个脚本文件作为标准输入，来设置硬盘的分区。<command>sfdisk</command> 有些情况下拒绝一个有错的输入文件。在另一些情况下，它将无保留的执行输入，在硬盘上写入错误的分区。<warning><title>检测输入</title><para>在写入磁盘前，总是用 <command>sfdisk -n</command> 命令检测输入文件。</para></warning></para>
        </example>
        <para>避免在章节或提示的标题中使用标点，除非必须使用逗号。在标题中包含与提示相关的内容，例如 "需要重启"，而不是简单地使用提示类型作为标题 ("警告")。</para>
        <para>提示的标题应使用与正文标题相同的大小写规则。</para>
      </section>
      <section id="sn-misc-replaceable">
        <title>
          <sgmltag class="starttag">replaceable</sgmltag> 标记</title>
        <para>如果您的文档表述了作为约定的一个特定的值，那么不要在文中或示例中使用 <sgmltag class="starttag">replaceable</sgmltag> 标记。</para>
      </section>
      <section id="sn-misc-entities">
        <title>XML 实体</title>
        <para>使用 &FDP; 提供的实体。这些实体可以在 <filename>fedora-docs</filename> 的 <filename>common/</filename> 目录找到。(请参考 <xref linkend="ch-getting-files"/>。) 例如，不要使用缩写 "FC2"，应当使用预定义的实体 "&FC; &FCVER;"，这样将生成文本 "&FC; &FCVER;"。</para>
      </section>
    </section>
  </section>
</chapter>


***** Error reading new file: [Errno 2] No such file or directory: 'docs-tutorial-zh_CN.xml'

***** Error reading new file: [Errno 2] No such file or directory: 'docs-vim-zh_CN.xml'

***** Error reading new file: [Errno 2] No such file or directory: 'docs-xml-tags-zh_CN.xml'

--- NEW FILE documentation-guide-zh_CN.xml ---
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../docs-common/common/fedora-entities-en.ent">
%FEDORA-ENTITIES-EN;

<!ENTITY VERSION "0.2.6.3">
<!ENTITY BOOKID "documentation-guide-&VERSION; (2005-09-18)">
<!ENTITY INTRODUCTION SYSTEM "docs-intro-zh_CN.xml" >
<!ENTITY GETTINGFILES SYSTEM "docs-getting-files-zh_CN.xml" >
<!ENTITY GUIDELINES SYSTEM "docs-rh-guidelines-zh_CN.xml" >
<!ENTITY EMACS SYSTEM "docs-emacs-zh_CN.xml" >
<!ENTITY EMACS-NXML SYSTEM "docs-emacs-nxml-zh_CN.xml" >
<!ENTITY VIM SYSTEM "docs-vim-zh_CN.xml" >
<!ENTITY TAGS SYSTEM "docs-xml-tags-zh_CN.xml" >
<!ENTITY TUTORIAL SYSTEM "docs-tutorial-zh_CN.xml" >
<!ENTITY CONVERTING SYSTEM "docs-converting-zh_CN.xml" >
<!ENTITY CVS SYSTEM "../docs-common/common/cvs-zh_CN.xml" >
<!ENTITY ACKNOWLEDGMENTS SYSTEM "acknowledgments-zh_CN.xml" >
<!ENTITY STYLE SYSTEM "docs-style-zh_CN.xml" >
]>
<book id="documentation-guide" lang="zh_CN">
  <bookinfo>
    <title>&FP; 文档撰写准则</title>
    <subtitle>版本 &VERSION;</subtitle>
    <copyright>
      <year>2003,2004,2005</year>
      <holder>&FORMAL-RHI;</holder>
      <holder>Tammy Fox</holder>
      <holder>Johnray Fuller</holder>
      <holder>Sandra Moore</holder>
    </copyright>
    <authorgroup>
      <author>
        <surname>Fox</surname>
        <firstname>Tammy</firstname>
      </author>
      <author>
        <surname>Fuller</surname>
        <firstname>Johnray</firstname>
      </author>
      <author>
        <surname>Moore</surname>
        <firstname>Sandra</firstname>
      </author>
    </authorgroup> &LEGALNOTICE;</bookinfo> &INTRODUCTION; &GETTINGFILES; &GUIDELINES; &EMACS; &EMACS-NXML; &VIM; &TAGS; &TUTORIAL; &STYLE; &CONVERTING; &CVS; &ACKNOWLEDGMENTS; <index id="generated-index"/></book>

More information about the Fedora-docs-commits mailing list