From 770e67eac5f36ae100306a21672c8c9ed90b2681 Mon Sep 17 00:00:00 2001 From: Yuan Yijun Date: Fri, 9 Dec 2005 15:28:54 +0000 Subject: *** empty log message *** --- acknowledgments-zh_CN.xml | 10 + docs-converting-zh_CN.xml | 9 + docs-emacs-nxml-zh_CN.xml | 123 ++++ docs-emacs-zh_CN.xml | 533 ++++++++++++++ docs-getting-files-zh_CN.xml | 46 ++ docs-intro-zh_CN.xml | 24 + docs-rh-guidelines-zh_CN.xml | 415 +++++++++++ docs-style-zh_CN.xml | 1047 ++++++++++++++++++++++++++ docs-tutorial-zh_CN.xml | 72 ++ docs-vim-zh_CN.xml | 87 +++ docs-xml-tags-zh_CN.xml | 1615 +++++++++++++++++++++++++++++++++++++++++ documentation-guide-zh_CN.xml | 46 ++ 12 files changed, 4027 insertions(+) create mode 100644 acknowledgments-zh_CN.xml create mode 100644 docs-converting-zh_CN.xml create mode 100644 docs-emacs-nxml-zh_CN.xml create mode 100644 docs-emacs-zh_CN.xml create mode 100644 docs-getting-files-zh_CN.xml create mode 100644 docs-intro-zh_CN.xml create mode 100644 docs-rh-guidelines-zh_CN.xml create mode 100644 docs-style-zh_CN.xml create mode 100644 docs-tutorial-zh_CN.xml create mode 100644 docs-vim-zh_CN.xml create mode 100644 docs-xml-tags-zh_CN.xml create mode 100644 documentation-guide-zh_CN.xml diff --git a/acknowledgments-zh_CN.xml b/acknowledgments-zh_CN.xml new file mode 100644 index 0000000..db0c7bc --- /dev/null +++ b/acknowledgments-zh_CN.xml @@ -0,0 +1,10 @@ + + + 致谢 + 本文档基于 Tammy Fox (tfox at redhat.com) 起草的一篇文档，并得到了 Sandra Moore (smoore at redhat.com) 和 Johnray Fuller (jrfuller at redhat.com) 的协助。 + Roozbeh Pournader (roozbeh at sharif.edu) 的补丁已被合并，修正了一些拼写错误，解释了匿名 CVS 访问时禁止提交的情况。 + Gavin Henry (ghenry at suretecsystems.com) 的补丁已被合并，向 docs-xml-tags.xml 中的 figure 标记范例添加尾部斜线，以及添加 。 + Joshua Daniel Franklin (joshuadfranklin at yahoo.com) 的补丁已被合并，添加 。 + Karsten Wade (kwade at redhat.com) 的补丁已被合并，添加 。它为 Paul W. Frields (stickstr5 at hotmail.com) 编辑。 + Paul W. Frields (stickstr5 at hotmail.com) 的补丁已被合并，向 中的 screen 标记集合添加更多解释。 + diff --git a/docs-converting-zh_CN.xml b/docs-converting-zh_CN.xml new file mode 100644 index 0000000..dc06576 --- /dev/null +++ b/docs-converting-zh_CN.xml @@ -0,0 +1,9 @@ + + + 生成 HTML 及 PDF + 每个包含文档的目录都有一个 Makefile。在这个目录下，运行命令 make html 来生成 HTML 版本，运行 make pdf 来生成 PDF 版本。 + + 警告 + PDF 的生成仍然不完善，可能无法工作。 + + diff --git a/docs-emacs-nxml-zh_CN.xml b/docs-emacs-nxml-zh_CN.xml new file mode 100644 index 0000000..071201b --- /dev/null +++ b/docs-emacs-nxml-zh_CN.xml @@ -0,0 +1,123 @@ + + + Emacs 与 nXML 模式 + + nXML + + + Emacs + + + Emacs + nXML 模式 + + 您可以使用 Emacs 的 nXML 模式，使撰写 DocBook XML 格式更加简单。nXML 模式提供了上下文敏感的编辑模式，包括补全、实时的有效性检测、语法高亮和缩进。为此您只要安装一个 RPM 软件包！ + + 开发早期 + 需要注意的是，Emacs 的 nXML 模式尚不完善，因此在编辑一些文档时，高级用户可能会注意到一些问题。如果您略微关注一下邮件列表，就可以获得相关信息，也可以问问题。请参考 。 + + + 下载 nXML RPM + + nXML + RPM + + + nXML RPM + + 要在 emacs 中使用 nXML 模式，您需要安装 Tim Waugh 网站上的 nXML RPM，或者下载 http://www.thaiopensource.com/download/ 的源代码。源代码需要花工夫来配置，因此这里只考虑 RPM 版本。 + 关于下载源代码请参考 。 + + + 范例 + 与 PSGML 模式相比，您只需有数几个命令。这样使用 Emacs 编辑就快捷多了，您可以更多地关注文章的内容。 + + 命令 + 要创建一个标记，输入 < 然后输入关键字。要完成这个关键字，按下 Ctrl-Ret，然后添加随后的 >。要关闭一个标记，输入 </。 + + 注意 + 当您打开不包含首部 DOCTYPE 声明的文件时，将看到如下信息，标记补全也无法实现，因为 nXML 不知道您在编辑的文件格式。 + + 要加载 schema，按下 Ctrl-c，然后按 Ctrl-s 然后浏览 /usr/share/emacs/site-lisp/nxml-mode/schema/ 并加载 docbook.rnc。Emacs 将提示您将它保存到工作目录。 + + 技巧 + 已描述过的命令只是 Emacs PSGML 模式与 Emacs nXML 模式的不同之处。您仍然需要使用 中描述的命令。 + + + + + 其他资源 + 其他的 Emacs 与 nXML 帮助可以在下列位置找到： + + + + http://www.thaiopensource.com/download/ — Author's download area + + + + http://wks.uts.ohio-state.edu/unix_course/intro-135.html — Emacs Quick Reference Guide + + + + emacs 软件包附带了 Emacs 参考卡片。您可以打印一份，作为参考。— /usr/share/emacs/<version>/etc/refcard.ps + + + + + nXML README 文件 + + 注意 + 这个文件可以在您解压的源代码中找到，如果安装了 RPM，它的位置是 /usr/share/doc/nxml-mode-<version>/。 + + README 文件： + 这是 GNU Emacs 的一种新的主模式。它支持格式良好的 XML 文档，也为采用 RELAX NG Compact Syntax 的 XML 文档提供了 schema-sensitive 编辑模式。 + 要使用它，您需要 GNU Emacs 21.x 版本，推荐 21.3。GNU Emacs 20 版本中无法正常运作，XEmacs 也不行。要开始编辑，输入命令： + + M-x load-file RET rng-auto.el RET + + 这样定义了必需的 autoloads。然后，打开一个包含 XML 文档的文件，执行命令： + + M-x nxml-mode + + 然后执行 + + C-h m + + 来查看 nXML 模式的使用帮助。手册的起始页在 nxml-mode.info 中，可以这样阅读它： + + C-u M-x info RET nxml-mode.info RET + + 它也在顶层 info 目录最后添加了自己的一项，因此您可以和平常一样，用 C-h i 开始阅读。 + 您可以用 test.valid.xml 和 test.invalid.xml 作为正确和不正确的 XML 文档范例。 + 要在 Emacs 启动时自动加载这些，将下列内容加入您的 .emacs： + + +(load "~/nxml-mode-200YMMDD/rng-auto.el") + + + 这里 ~/nxml-mode-200YMMDD 是包含 .elc 文件的目录。注意 rng-auto.el 不会加载所有 nXML 模式的代码；它仅仅设置环境，使得 nXML 模式的所有特性得以正确地自动加载。您不应尝试自动加载 rng-auto.el 本身。 + 要在加载扩展名是 xml, xsl, rng 或 xhtml 的文件时自动切换到 nXML 模式，将下列内容加入您的 .emacs： + + +(setq auto-mode-alist + (cons '("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode) + auto-mode-alist)) + + + 如果您编辑 iso-8859-N 编码的 XML，而不是 iso-8859-1，并且您运行的是 Emacs 21.3 或更新版本，那么最好打开 unify-8859-on-decoding-mode，将下列内容加入您的 .emacs： + + (unify-8859-on-decoding-mode) + + 要使用验证以及 schema-sensitive 编辑模式，您需要文档的 RELAX NG Compact Syntax (RNC) schema 文件。schema 目录包含了常用文档类型的 schema。 + 关于 RELAX NG 请参考 http://relaxng.org/。 + 关于 RELAX NG Compact NG 的教程请参考 http://relaxng.org/compact-tutorial.html + 关于自动创建 RNC schema，推荐使用 Trang 程序：http://eee.thaiopensource.com/relaxng/trang.html" + 您可以使用它来 从已有文档得出 RNC schema将 DTD 转换为 RNC schema将 RELAX NG XML syntax schema 转换为 RNC schema + 要将 RELAX NG XML syntax (.rng) schema 转换为 RNC schema，您也可以使用 http://www.pantor.com/download.html" 的 XSLT 样式表。 + 要将 W3C XML Schema 转换为 RNC schema，您需要首先将它转换为 RELAX NG XML syntax，使用 Sun 的 RELAX NG 转换工具 rngconv (基于 MSV)。请参考 https://www.dev.java.net/。 + 文件 NEWS 描述了最近的更改。 + 请访问邮件列表 http://groups.yahoo.com/group/emacs-nxml-mode 来提交 bug 和参与讨论。我将在那里发布新版本。 + James Clark + jjc@thaiopensource.com + + diff --git a/docs-emacs-zh_CN.xml b/docs-emacs-zh_CN.xml new file mode 100644 index 0000000..3320e48 --- /dev/null +++ b/docs-emacs-zh_CN.xml @@ -0,0 +1,533 @@ + + + Emacs 与 PSGML 模式 + + PSGML + + + Emacs + + + Emacs + PSGML 模式 + + 您可以利用 Emacs 的 PSGML 模式以使编辑 XML 格式更容易。PSGML 模式提供了语法高亮，标记补全等功能。 + + 设置您的 <filename>.emacs</filename> + + Emacs + 配置文件 + + + + .emacs + + + 为使 Emacs 可以正确解析您的 DocBook 文档，您必须定制一个 .emacs 文件。将下列内容复制并粘贴到您已有的 .emacs 文件中，或者创建一个包含下列内容的新文件： +;; turn on auto-fill in `text-mode' and derived modes +;;(mail, news, etc) +(add-hook 'text-mode-hook 'turn-on-auto-fill) + +;; +;;MODES +;; + +(setq auto-mode-alist (cons '("\\.sgml$" . sgml-mode) auto-mode-alist)) +(setq auto-mode-alist (cons '("\\.sgm$" . sgml-mode) auto-mode-alist)) + +;; +;;XML!! +;; +;;############################################################# + +;; +;;PSGML mode stuff +;; + +(autoload 'sgml-mode "psgml" "My Most Major Mode" t) + +(setq sgml-mode-hook '(lambda () "Defaults for XML mode." (turn-on-auto-fill) +(setq fill-column 80))) + +(defun My-XML-keymap () + (local-set-key [(alt i)] + '(lambda () + (interactive) + (sgml-indent-line) + (sgml-insert-element 'item) + (sgml-indent-line))) + (local-set-key [(alt l)] + '(lambda () + (interactive) + (sgml-insert-element 'list) + (sgml-insert-element 'item) + (sgml-indent-line))) + (local-set-key [(alt p)] + '(lambda () + (interactive) + (sgml-indent-line) + (sgml-insert-element 'para) + (sgml-indent-line))) + (local-set-key [(alt -)] + '(lambda () + (interactive) + (insert "—")))) + +(add-hook 'sgml-mode-hook 'My-XML-keymap) + +;; +;; Fix up indentation of data... +;; + +(setq-default sgml-indent-data t) + +;; +;; XML markup faces. +;; + +(setq-default sgml-set-face t) + + +(make-face 'sgml-comment-face) +(make-face 'sgml-doctype-face) +(make-face 'sgml-end-tag-face) +(make-face 'sgml-entity-face) +(make-face 'sgml-ignored-face) +(make-face 'sgml-ms-end-face) +(make-face 'sgml-ms-start-face) +(make-face 'sgml-pi-face) +(make-face 'sgml-sgml-face) +(make-face 'sgml-short-ref-face) +(make-face 'sgml-start-tag-face) + +(set-face-foreground 'sgml-comment-face "maroon") +(set-face-foreground 'sgml-doctype-face "dark green") +(set-face-foreground 'sgml-end-tag-face "blue2") +(set-face-foreground 'sgml-entity-face "red2") +(set-face-foreground 'sgml-ignored-face "maroon") +(set-face-background 'sgml-ignored-face "gray90") +(set-face-foreground 'sgml-ms-end-face "maroon") +(set-face-foreground 'sgml-ms-start-face "maroon") +(set-face-foreground 'sgml-pi-face "maroon") +(set-face-foreground 'sgml-sgml-face "maroon") +(set-face-foreground 'sgml-short-ref-face "goldenrod") +(set-face-foreground 'sgml-start-tag-face "blue2") + +(setq-default sgml-markup-faces + '((comment . sgml-comment-face) + (doctype . sgml-doctype-face) + (end-tag . sgml-end-tag-face) + (entity . sgml-entity-face) + (ignored . sgml-ignored-face) + (ms-end . sgml-ms-end-face) + (ms-start . sgml-ms-start-face) + (pi . sgml-pi-face) + (sgml . sgml-sgml-face) + (short-ref . sgml-short-ref-face) + (start-tag . sgml-start-tag-face))) + + +(defun docbook-mode () + (sgml-mode) + ) + + + +;; +;;END XML STUFF +;; +;;################################################################## + +;PO mode stuff + +(setq auto-mode-alist + (cons '("\\.pox?\\'" . po-mode) auto-mode-alist)) +(autoload 'po-mode "po-mode") + + + (global-set-key [(f1)] (lambda () (interactive) (manual- + entry (current-word)))) + + + 您是否有一个滚轮鼠标？如果是，那么可以将下列内容加入您的 .emacs，这样您的滚轮将可以用在 Emacs 中 (适于 Emacs 版本 21)： + + +;; Enable wheelmouse support by default for emacs 21 +(cond (window-system +(mwheel-install) +)) + + + 如果您使用旧的 20 版本，应添加下列内容： + + +;; Enable wheelmouse support by default +(require 'mwheel) + + + + + + + + + 定制 Emacs + + Emacs + 定制 + + + + .Xresources + + + + Emacs + colors + + + Emacs + font + + + Emacs + geometry + + 在您的 ~/.Xresources 中配置 Emacs 的颜色，字体和默认窗口大小。设置的格式是 emacs.keyword:value + 下面是一个 ~/.Xresources 文件范例。 + + 注意 + 如果您的 ~/.Xresources 中包含其他设置，就将下列内容添加到文件结尾。 + + + +emacs.background: light gray +emacs.foreground: black +emacs.pointerColor: blue +emacs.cursorColor: blue +emacs.bitmapIcon: on +emacs.font: fixed +emacs.geometry: 90x25 + + + 修改文件后，您必须执行命令 + + xrdb -merge ~/.Xresources + + 并且重新运行 Emacs 以使改变生效。 + + + 创建重编译的 DTD 子集 + 如果给出了正确的文档类型声明 (DTD) 文件，Emacs 可以对 DocBook XML 文件进行正确的语法高亮和缩进。这些特性将使您的 XML 文件易于阅读，帮助您发现错误。 + 要创建一个可加载的已解析的 DTD 文件：找到一组 DocBook 文件的主控文件。您可以通过头部是否包含 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" 来找到它。最简单的办法，是运行命令 grep DocBook *.xml。找到主控文件后，在 Emacs 中打开它，命令是 emacs <parentfile>.xml (这里 <parentfile>.xml 是你找到的主控文件)。在下拉菜单中选择 DTD -> Parse DTD。当您看到屏幕下方的 Fontifying...done 信息时，解析就完成了。将已解析的 DTD 保存为文件，方法是在下拉菜单中选择 DTD -> Save Parsed DTD。按下 Enter 来保存为默认文件名，或者修改文件名，但应保留 .ced 扩展名。可以将它命名为 docbook.ced 这样很通用的名字，这样您在打开所有 DocBook 文件的时候都可以引用它。这个文件也可以复制到要加载的目录中。 + + 技巧 + 您也可以使用 Emacs 命令 Meta-x sgml-parse-prolog 来解析这个文件，然后用命令 Meta-x sgml-save-dtd 来保存已解析的 DTD 到 .ced 文件中。 + + + + 加载已解析的 DTD + 现在您已保存了 DTD 设置，您可以加载这个 .ced 文件，看看 .sgml 文件语法高亮的效果。 + 要加载已解析的 DTD 文件：在 Emacs 中打开 XML 文件在下拉菜单中选择 DTD -> Load DTD 然后选择您在上一步保存的文件。例如，选择 docbook.ced。当您看到屏幕下方的 Fontifying...done 信息时，就加载完毕了。加载已解析的 DTD 可能需要很久。您可以在加载完毕前就开始编辑。 + + 技巧 + 您也可以使用 Emacs 命令 Meta-x sgml-load-dtd 来加载已翻译的 DTD。 + + + + 基本的 Emacs 命令 + + Meta 键通常指的是 Alt 键。 + + Emacs 命令 + + + + + + 快捷方式 + 描述 + + + + + + + Meta + x + sgml-parse-prolog, Enter + 解析 DTD + + + + + Meta + x + sgml-save-dtd, Enter + 保存已解析的 DTD + + + + + Meta + x + sgml-load-dtd, Enter + 加载 DTD + + + + + Ctrl + c + , Shift, Tab + 显示有效标记的列表 + + + + + Ctrl + c + , Shift, type beginning of tag, Tab + 补全标记 + + + + + Ctrl g + + 取消 minibuffer 中的命令 + + + + + Ctrl + c + , / + 关闭标记 + + + + + Ctrl a + + 将光标移动到行首 + + + + + Ctrl + e + + + 将光标移动到行尾 + + + + + Ctrl + Home + + + 将光标移动到文件开始 + + + + + Ctrl + End + + + 将光标移动到文件结束 + + + + + Ctrl + k + + + 剪切一行 + + + + + Ctrl y + + 粘贴一行 + + + + + Ctrl s + + 在文件中向前搜索 + + + + + Ctrl + r + + + 在文件中向后搜索 + + + + + Meta + $ + + + 检查当前单词的拼写 + + + + + Meta + x + ispell-word, Enter + 检查当前单词的拼写 + + + + + Meta + x + ispell-buffer, Enter + 检测当前 buffer 的拼写 + + + + + Ctrl + x + , Ctrlf + 打开文件 + + + + + Ctrl + x + , Ctrls + 保存文件 + + + + + Ctrl + x + , Ctrlc + 退出 Emacs，在需要时提示保存文件 + + + + + Meta q + + 段落重排 + + + + + Ctrl + c + , Ctrla + 编辑标记的属性 (例如，您可以编辑 ulink 标记的 url 属性) + + + + + Ctrl + c + , Ctrlc + 结束编辑属性 + + + +
+ + + 范例 + Emacs 和 PSGML 的命令表 (参考卡片) 对于新手来说有些难。本节有一些例子，讲解如何使用它们。 + + 标记补全 + + 注意 + 本节假设您已经加载了 DTD 文件 (.ced)。 + + 需要插入标记时，不要输入它。按下组合键 Ctrl-c, 然后按下 <。在 Emacs 窗口的下方，您将看到： + + Tag: < + + 要查看所有标记的列表，按下 Tab 或 ?。如果您知道标记的首字母，可以按下它们，然后按 Tab，就可以看到有同样首字母的所有标记的列表。 + 尝试这样：按下 Ctrl-c 然后按 <，然后按下字母 k，然后按 Tab。为了得到完整的列表，您可能需要多次按下 Tab。 + 输出应当与下面类似： + + +Click mouse-2 on a completion to select it. +In this buffer, type RET to select the completion near point. + +Possible completions are: +<keycap> <keycode> +<keycombo> <keysym> + + + + + 标记关闭 + 当您开始了一个标记后，您必须关闭它。按下组合键 Ctrl-c，然后按 /。这样将关闭最近一个开放的标记。 + + + 其他 Emacs 任务 + + 恢复单个窗口: 有时 Emacs 窗口被划分 (下方的窗口有标记补全等内容)。要恢复到只有您的 XML 文本全屏显示的状态，最简单的办法是按下 Ctrl-x，然后按 1。 + + 保存作品: 要保存编辑结果，按下 Ctrl-x 然后按 Ctrl-s。 + + "清除/返回"命令:有时，在标记补全中玩得太多，需要直接返回编辑时，按下 Ctrl-g。这个命令将放弃当前动作，而不会关闭文件本身。 + + 打开文件: 要打开一个新文件，按下 Ctrl-x 然后按 Ctrl-f。在窗口下方，可以输入要打开文件名 (这里也可以使用 Tab 补全)。 + + 关闭 emacs: 要关闭 emacs，按下 Ctrl-x 然后按 Ctrl-c。如果您尚未保存，它将提示，否则它会简单地退出。 + + + + 其他资源 + 其他 Emacs 和 PSGML 参考可以在这里找到： + + + + http://wks.uts.ohio-state.edu/unix_course/intro-135.html — Emacs Quick Reference Guide + + emacs 软件包附带了 Emacs 参考卡片。您可以打印一份，作为参考。— /usr/share/emacs/<version>/etc/refcard.ps + + + /usr/share/doc/psgml-<version>/psgml.ps 中的 Editing XML with Emacs and PSGML。 + + + + http://www.snee.com/bob/sgmlfree/psgmqref.html — Emacs/PSGML Quick Reference 是一个 Emacs PSGML 模式的索引表。 + + + + http://www.snee.com/bob/sgmlfree/emcspsgm.html — PSGML Tricks + + + + diff --git a/docs-getting-files-zh_CN.xml b/docs-getting-files-zh_CN.xml new file mode 100644 index 0000000..8f2823e --- /dev/null +++ b/docs-getting-files-zh_CN.xml @@ -0,0 +1,46 @@ + + + 下载文件 + 要开始为 Docs Project 贡献力量，您需要适当的 DocBook XML 文件，样式表以及一些脚本。需要安装下列软件包： + + + + xmlto — 生成 HTML 和 PDF 版本的输出 + + + + docbook-style-xsl — 我们默认使用的 XSLT 样式表 + + + + docbook-dtds — DocBook DTD 针对 XML 的版本 + + + 常用的脚本和样式表都存放在 cvs.fedora.redhat.com CVS 服务器的仓库中。您需要将它们以及已有文档的 DocBook XML 文件检出。 + 您应当只在第一次从 docs CVS 检出时，做这些动作。当您看到密码提示时，按下 Enter。 + + mkdir my-fedora-docs +cd my-fedora-docs +export CVSROOT=:pserver:anonymous@cvs.fedora.redhat.com:/cvs/docs +cvs login +cvs co docs-common +cvs co example-tutorial + + 当您进行匿名 CVS 检出时，您可以检视文件并获取更新的版本。您不可以添加或提交更新到服务器中。要提交修改，必须有 CVS 写权限。关于获取 CVS 写权限请参考 。 + 要查看已有文档的列表： + + cvs co -c + + 选择您感兴趣的文档，然后下载到工作目录： + + cvs co example-tutorial + + 除了 &IG; 之外，CVS 中所有文档必须是 DocBook XML article 格式，使用 example-tutorial 目录中的模板。每个文档 必须 有自己的目录。根目录中不允许有 XML 文件。 + diff --git a/docs-intro-zh_CN.xml b/docs-intro-zh_CN.xml new file mode 100644 index 0000000..792f8a5 --- /dev/null +++ b/docs-intro-zh_CN.xml @@ -0,0 +1,24 @@ + + + 介绍 + Docs Project 的目标是为 &FC; 用户和开发者创建易于维护，基于任务的文档。除了 &IG; 之外，所有文档必须是 DocBook XML article 格式，每个主题一篇文章。这样，作者就可以专注于撰写一个主题，不必考虑它如何排版为一个手册，或如何与其他主题协调。 + 要用到的工具： + + + DocBook XML v4.1 + + + 自定义的打印版本和 HTML 版本的 XSLT 样式表 + + + 自定义的脚本，以生成 PDF 版本和 HTML 版本的输出 (使用 xmlto) + + + Emacs PSGML 模式 (可选，推荐使用) + + + Emacs nXML 模式 (可选，同样推荐使用) + + + 本文档的目的是解释 Docs Project 使用的工具，同时提供写作约定和标记约定，使文档一致且易于维护。 + diff --git a/docs-rh-guidelines-zh_CN.xml b/docs-rh-guidelines-zh_CN.xml new file mode 100644 index 0000000..0ead30c --- /dev/null +++ b/docs-rh-guidelines-zh_CN.xml @@ -0,0 +1,415 @@ + + + &RH; 文档撰写约定 + + recursion + recursion + + + RTFM + read the f*'ing manual + humor + + + humor + RTFM + + 请仔细阅读本章。本章描述了必须遵循的约定，例如命名约定。 + + ID 命名约定 + + XML 标记 + 命名约定 + + + 命名约定 + + 后面您将看到这样的 ID 命名。它们有助于理解这些命名的含义。例如： + + +<chapter id="ch-uniquename"> + +<sect3="s3-install-make-disks"> + +<figure id="fig-redhat-config-kickstart-basic"> + + + ID 是独一无二的标识符，使得 DocBook XML 得知如何交叉参考章、节等等。 + 定义 ID 的一般规则如下： + + XML 标记 + 定义 ID 的规则 + + + 命名约定 + 定义 ID 的规则 + + + + 至多使用 32 个字母 (这里指的是引号中所有内容) + + + 尽量短小而简单 + + + 确保命名与内容相关 (使它可辨识) + + + 例如，"ch-uniquename" (有 13 个字母) 以及 "s3-install-make-disks" (有 21 个字母)。 + 特定一章中的小节应当在 ID 中包含这一章的名称 (这一章的 ID 去掉 "ch-")。例如，您在撰写 "ch-intro" 一章，需要将有关磁盘分区的内容作为第一节时，小节 ID 将类似于 "s1-intro-partition"，它包含了小节编号，这一章的 ID 以及这一节的独一无二的 ID。 + + 命名约定 + + + + + + 标记 + 前缀 + + + + + + 前言 + + + pr- + + + + + chapter + + + ch- + + + + + 节 + + + sn- + + + + + 第一节 + + + s1- + + + + + 第二节 + + + s2- + + + + + 第三节 + + + s3- + + + + + 第四节 + + + s4- + + + + + figure + + + fig- + + + + + table + + + tb- + + + + + 附录 + + + ap- + + + + + part + + + pt- + + + + + example + + + ex- + + + + +
+ + + 文件头 + 所有文件必须包含 CVS Id 头部。 + 如果您创建了一个新文件，第一行必须是： + + +<!-- $Id: --> + + + 它被提交到 CVS 中时 (在每次提交时)，这一行都会自动更新，以包含关于文件的信息。例如： + + +<!-- $Id: docs-rh-guidelines-zh_CN.xml,v 1.1 2005/12/09 15:28:54 bbbush Exp $ --> + + + + + 创建提示 + + 提示 + + + XML 标记 + 警告 + + + XML 标记 + 技巧 + + + XML 标记 + 注意 + + + XML 标记 + 小心 + + + XML 标记 + 重要 + + + XML 标记 + 提示 + 警告 + + + XML 标记 + 提示 + 技巧 + + + XML 标记 + 提示 + 注意 + + + XML 标记 + 提示 + 小心 + + + XML 标记 + 提示 + 重要 + + DocBook 中有五种提示类型：小心，重要，注意，技巧和警告。 + 所有提示都有类似的结构：可选的标题，随后是段落级的元素。DocBook DTD 没有定义每种提示的特殊语义。例如，DocBook 并未规定警告必须用于可能造成重大损失的情况。 + + 创建技巧，注意，小心，重要和警告提示 + + XML 标记 + 注意 + + + XML 标记 + 技巧 + + + XML 标记 + 小心 + + + XML 标记 + 重要 + + + XML 标记 + 警告 + + 有很多方法来使文档中的文本引人注意。Note 用于显示附加信息。Tip 用于显示完成任务的其他方法。Caution 用于告诫用户在尝试某一步时必须小心。Important 用于提醒用户不可忽视的信息，尽管用户动作不受影响，但是必须提醒用户信息的重要性。Warning 用于提醒读者，他们的设置将被修改或变动，例如文件将被删除，如果他们在意这一后果，就不应继续动作。 + 下列代码将展示上面每种情况的写法，同时也展示了 HTML 显示效果。 + + +<note> +<title>注意</title> +<para>文本内容</para> +</note> + + + + 注意 文本内容 + + +<tip> +<title>技巧</title> +<para>文本内容</para> +</tip> + + + + 技巧 + 文本内容 + + + +<caution> +<title>小心</title> +<para>文本内容</para> +</caution> + + + + 小心 文本内容 + + +<important> +<title>重要</title> +<para>文本内容</para> +</important> + + + + 注意 + 文本内容 + + + +<warning> +<title>警告</title> +<para>文本内容</para> +</warning> + + + + 警告 文本内容 + + + + 屏幕截图 + + 屏幕截图 + 如何截取 + + + 屏幕快照 + 屏幕截图 + + + 屏幕抓图 + 屏幕截图 + + 有两种类型的屏幕截图：图象和文本。选择它们的原则是 尽量使用文本截图。这意味着，如果您可以用文本而不是图象来表达，那么就用文本。GUI 的图象截图可以首先引入一些对象，然后用文字加以描述，但是您不会总是为每一步都创建一副截图。 + 这样选择的主要目的是文本块通常比占据相同空间的图象包含更多信息。这和具体图象有关，某个场景的准确的截图也许抵得上一千字的效果。GUI 的截图通常有很大空白，只包含很少元素，这样便于描述或列举。 + 截取图象的步骤本身表明了，使用文字来描述一个过程比起一系列的屏幕截图要精确许多。 + + + 图象截图 + + + + 设置主题为默认主题。这样读者会熟悉这一外观，也使得 &FDP; 文档显得一致。从菜单中，选择 Preferences, Theme 然后选 Bluecurve (&FC; 4 不再使用 Bluecurve)。 + + + 设置字体为默认值。从菜单中，选择 Preferences, Fonts. 然后设置 Application font 和 Desktop font 为 Sans Regular 10。设置 Window Title font 为 Sans Bold 10。设置 Terminal font 为 Monospace Regular 10。 + + + 在截图之前，试着将目标 GUI 元素调整到尽可能小。您的目标应当是 500 像素或更小。如果您需要截取超过一个 GUI 元素，可以按照下面的步骤来缩放图象。 + + + 要截取图象，使用鼠标选择 GUI 元素，将它放到最前，或者调整元素排列。按下 AltPrint Screen 来截取单个 GUI 窗口。要抓去整个桌面，按下 Print Screen。如果您要截取包含很多元素的图象，并已将它们靠近，那么还可以在 The GIMP 中裁减结果图象到适当大小。截取的图象将是 PNG 格式。 + + + 如果需要，您可以使用 The GIMP 缩放图象。打开图象，在图象上点击右键，选择 Image -> Scale Image...。保持长宽比不变，设置 New Width 为 500 px，然后点击 OK。记住在转换为 EPS 之前按下 Ctrls 保存图象。 + + + 仍使用 The GIMP 编辑图象，在图象上点击右键，选择 File -> Save As...。在 Determine File Type: 列表中，选择 PostScript，然后点击 OK。点击 Export，允许平整图象。 + 在 Save as PostScript 窗口，选择 Encapsulated PostScript，然后点击 OK。 + + + 关于如何在 XML 中调用图象，请参考 。 + + + + 文本截图 + + 文本的屏幕信息对读者也很有用。如果您可以同时用图象和文本截图描述某个功能，就不要同时包含它们，除非忽略任何一个都将使描述不清楚。您应当使得信息更加通用。忽略用户名和主机名信息，区分用户的输入与示例的输出。在 screen 标记中，用户输入应当包含在 userinput 标记内，而用户看到的输出应当包含在 computeroutput 标记内。例如， 的用法应该改为这样 + + 不正确的文本截图 + + ps ax | grep ssh + + 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 + + + + + 正确的文本截图 + 要显示所有当前活动的 ssh 会话，执行下列命令： + + ps ax | grep ssh + + 输出将类似于： + + + 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 + + + + 关于 screen 标记，请参考 。 + + + + + + 图表和图象 + + images + + + 图表 + 创建 + + 待编辑 + + diff --git a/docs-style-zh_CN.xml b/docs-style-zh_CN.xml new file mode 100644 index 0000000..14e7228 --- /dev/null +++ b/docs-style-zh_CN.xml @@ -0,0 +1,1047 @@ + + + 写作风格 + 撰写完善的技术文档不仅仅指展示命令行和指令集。好文档应当容易阅读、理解、翻译，表达准确的概念间的逻辑关系。好文档也可以用 不应当做的 事情来定义。您的文档应当避免： + + + 冗长 + + + 多余的，不加解释的行话 + + + 语法或拼写错误 + + + 对个人经历的引证 + + + 可能触犯或迷惑用户的评论 + + + 这一章包含了 &FED; 文档写作风格的规则和准则。准则与规则不同，即使违反了准则，如果您的文章更加易于理解，那么没有关系。尽量遵循准则，总是遵循规则。如果没有明确表明，一个建议就是一个准则。 +
+ 为何写作风格很重要 + 优秀的写作不是天生的。它是一种技术，即使专业的作者，甚至有名的作家，也必须时常练习。 写作风格style 是将优秀的作品与平直的描述区分开的特性。 + 优秀的作品有多种形式。对于诗歌和散文，优秀的作品不会遵循一定的语法、句法或拼写规则。一个著名的例子是 James Joyce 的小说 Ulysses 中的 Episode 18, "Penelope," http://www.online-literature.com/james_joyce/ulysses/18/。请注意这个例子包含一些成人内容，因此不适于所有用户。。那里，Joyce 使用长串的词汇，不加标点，来摹拟角色的内心意识。虽然违反了语法和句法的基本规则，Joyce 描绘了叙述者无组织却又松散联系的思考方式。 + 技术文档却必须遵循这些规则。文档与标准语法偏差越大，读者就会觉得越难理解。例如，读者也许并不以文档语言为母语，或者正在阅读译本。这时，如果作者使用方言、习语或者行话，读者和译者会很容易被迷惑。下面的例子比较了表达同样含义的不同做法： + + 不正确的风格 + + 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 messages log. When you see "USB device found," then Bob's your uncle. + + + 正确的风格 + + After you complete the configuration changes above, attach the USB removable media to your system. Use the dmesg command to examine the kernel message log. The message USB device + found indicates that your device was installed successfully. + + 第一个例子是更口语化的英语，它不适于正式的文档。第二个例子更加正式，但是无论是对英语用户还是译者，它都更容易理解。 + 遵守写作风格规则和准则，可以使读者阅读大量文档时更轻松。一致的风格有助于增强文档的专业性和价值认同。另一方面，忽略标点或语法错误将使读者对文档产生抵触。读者会认为基本正确的一篇文档不够权威，因为它写得很差。读者不必为理解作者的语言而头疼时才会放松下来。 + 这一章不可能包含足够的内容，使每个读过的人变成一个好作者。一些专门讲述写作风格的手册可能会有几百页。这一章为中级作者理解技术文档的写作风格提供了足够的准则。 + 如果您不是有经验的作者，无论技术文档还是其他，您还可以从其他资源中学到很多。下面的列表仍不够完善，但是提供了一个起点： + + + + The Elements of Style, 作者 William Strunk. 在线阅读: http://bartleby.com/141/ + + + + + The Chicago Manual of Style, 作者 the University of Chicago Press. 在线阅读: http://www.chicagomanualofstyle.org/ + + + + Paradigm Online Writing Assistant, 维护者 Chuck Guilford, Ph.D. 在线阅读: http://www.powa.org/ + + + 很多自由软件的文档计划有自己的文档风格准则。实际上，这一章很多内容来自 GNOME Documentation Style Guidelines (GDSG)。您可以看到本来的 GDSG，位置是 http://developer.gnome.org/documents/style-guide/。 +
+
+ 技术文档的基本概念 + + 参考书目信息 + 这一节来自 GDSG。 + + + 这一章提供了写作技术文档的简要介绍。 +
+ 写作风格一般要求 + &FP; 技术文档写作在一般要求的基础上，有特殊的约束。好的 &FED; 技术文档应当有下列特点： + + + 完备 + + 描述一个产品的全部功能。不可忽略个人认为对用户没有用处的功能。 + + + + 一致 + + + + 描述看到的内容。不要描述想要看到的内容。将信息以用户切身经历的顺序表达出来。 + + + + 清楚 + + 阅读 The Elements of Style (http://www.bartleby.com/141/) 来撰写清楚的文档。 + + + + + + 连贯 + + 在文档中使用约定俗成的词汇。如果其他作者在撰写相关的文档，那么使用相同的词汇。 + + + + 简明 + + 写作时多检视作品，问问自己哪些可以删减。请参考 。 + + + +
+
+ 原则 + 这一节包含了一些基本的风格准则。本章的后续小节将展开详述这些准则。 + + + 原则一：简短 + + + + 将每句话限制到 25 个词以下。 + + + 将每步过程限制到 23 个词以下。 + + + + 不正确：过长 + 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. + + + 正确：短句 + Normally, the kernel stores the data in memory prior to periodically writing the data to the disk. + + + + + 原则二：有条理 + + + + 每段讲述一个主题。 + + + 每句话表达一个意思。 + + + 每步操作只包含一个动作。 + + + + 不正确：没有条理 + The Workspace Switcher 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 window manager, allows you to create more than one virtual desktop, known as workspaces, to organize your work, with different applications running in each workspace. The Workspace Switcher 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. + + + 正确：有条理 + Use the Workspace Switcher to add new workspaces to the GNOME Desktop. You can run different applications in each workspace. The Workspace Switcher applet provides a miniature map that shows all of your workspaces. You can use the Workspace Switcher applet to switch between workspaces. + + + 在撰写前规划段落的顺序。决定在每段应当涵盖的主题。 + + + + + 原则三：使用指示 + + 使用例子来演示如何操作。提供指示，而不是描述。 + + 不正确：描述而不指示 + There is a text box that you can use to find out the definition of a word. + + + 正确：指示用法 + To request a definition of a word, type the word in the text box, then select Lookup. + + + 不要过于教条。有时您需要解释，以说明那些范例。 + + + + + 原则四：客观 + + 以中立的语气写作。 + + 不正确：偏倚一方 + The applet is a handy little screen grabber. + + + 正确：客观陈述 + Use the applet to take screenshots. + + + + +
+
+ 语气 + 不合适的语气会妨碍读者获取信息。中立的，不带个人好恶选择的语气可以促进读者的理解。中立的语气使较大的文档项目中的作者可以并行写作。另外，新的作者可以随时加入。中立的语气可以在系列文档之间实现一致，便于用户获得信息。要达到共同的中立的语气，最好的办法是采用下列原则： + + + 避免幽默 + + 幽默使注意力从您的信息中移开。幽默也使文档难以翻译。保持直白。 + + + + 避免个人好恶选择 + + 无论您认为某个功能是否好坏都不重要。将功能展示给用户，包含如何使用这些功能的指示。保持准确。 + + + + 避免口语 + + 口语难以翻译，通常是与文化相关的。保持中立。 + + + + 避免一时的论断 + + 一个论断在今天被认同，在明天就可能被推翻。保持技术化。 + + + + 避免展望将来 + + 关于某个产品的将来，这不属于技术文档。只撰写您现在看到的东西。要实际。 + + + +
+
+ 面向正确的用户 + 您对文档的结构和内容的定夺应当基于对读者的理解。考虑读者如何获取文档，需要哪些信息，曾经的经验等等。通常，您需要创建适合不同群体的文档。下面几节包含了您需要考虑的与读者相关的主题。 +
+
+ 用户的动机 + 不要浪费想在文档中获取信息的读者的时间。用户阅读技术文档不是为了取乐。用户通常带有特定的问题。您需要对这些问题作出明确的回答。 +
+
+ 新用户 + &FC; 的新用户遇到不熟悉的应用程序或功能时，通常会查阅在线教程。每个教程应当包含足够的介绍信息，告诉新用户如何使用相关的功能。每个教程还应当包含足够的使用说明，告诉用户他们可以用这个命令或功能作出的种种动作。使这些说明面向任务。在教程中不要描述 GUI 屏幕、对话框和对话框元素，除非某个特性影响了您的说明。 +
+
+ 有经验的用户 + 有经验的用户通常将文档作为参考。文档需要完备，组织合理，如果是打印的方式，还需要索引。 +
+
+ 不要触犯读者 + 为避免触犯读者，文档应遵循下列准则： + + + 避免内部用语 + + 内部用语包括行话和计算机社群中常见的缩写风气。例如，使用docs 而不是 documentation。一个词如果满足下面的条件，就是一句行话： + + + 这个词没有包含在 &FED; Jargon Buster (http://fedora.redhat.com/docs/jargon-buster/) 中。 + + + 这个词没有包含在 American Heritage Dictionary (http://www.bartleby.com/61/ ) 中。 + + + 这个词没有出现在您撰写的文档的词汇表中。 + + + 这个词也没有在您撰写的文档中定义。 + + + + + + 避免性别相关的语言 + + 不要出现代词 他的/她的 或 他/她。在指令中不必区分性别。 + + + + 避免特定文化的语言 + + 如果您的范例只能让您周围方圆百里的人看懂，那么它没有意义。 + + + + 不要用高人一等的口气 + + 如果文档中说，一个动作很容易或很快，而实际上用户无法完成，那没有比这更能让读者郁闷的了。不要评价和判断动作。 + + + + 准则的其他部分是对可能造成触犯的语气和语言用法的详细说明。 +
+
+
+ 语法和用法准则 + + 参考书目信息 + 这一节部分来自 GDSG，部分来自 The Elements of Style，为二十一世纪的技术文档作者进行了更新。 + + + 这一节包含了字母序排列的语法和用法准则，用于 &FED; 文档。很多准则只适用于英语，请参考 American Heritage Dictionary (http://www.bartleby.com/61/) 和 Chicago Manual of Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html)。 + + + 缩写 + + 词或短语的简写形式，可以代替原来的词使用，例如 Dr., a.m., p.m. 等等。在使用缩写时，遵循下列规则： + + + 避免创造新的缩写。不熟悉的缩写造成混淆，无法表明一个概念。 + + + 不要解释或展开众所周知的缩写。 + + + 不要在文档的词汇表中包含众所周知的缩写。 + + + 对于短语的缩写，例如 i.e. ("in other words", 换句话说) 和 e.g. ("for example", 例如)，不要使用缩写。拼写出整个短语。 + + + + 形容词 + + 小心使用形容词。在必须使用形容词来区分对象时再用。无论合适，检查是否可以把形容词去掉。 + + + + 首字母组合词 + + 用来表达一个由多个词组成的概念。通常，首字母组合词是这样构造的： + + + From the first letters of each word in a compound term, for example Table of Contents (TOC). + + + From recognizable parts of a compound term, such as GNU Object Model Environment (GNOME). + + + 在使用首字母组合词的时候，遵循下列规则： + + + 在第一次使用时，拼写完整的名称，在括号中包含组合词。 + + + 不要拼写出众所周知的首字母组合，除非您认为这对读者有用。 + + + 不要创建新的首字母组合。不熟悉的组合将造成混淆，无法表达清楚。 + + + 用大写表示，除非必须用小写。 + + + 在文档的词汇表中包含首字母组合和全称。 + + + + + + 副词 + + 小心使用副词。在必须用副词修饰组件的功能时再用。无论合适，检测是否可以去掉副词。经典的冗余副词包括 容易地，简单地 和 迅速地。 + + + + 拟人 + + + + 不要让应用程序软件充满情绪、欲望或意见。 + + + 不要让应用程序软件产生位置、维度的感觉。用户不会 "处在" 一个文本编辑器里。 + + + + + + 冠词 + + 不要在下列对象前面使用定冠词 the： + + + 文章标题 + + + 段的标题 + + + 标题 + + + 图象说明 + + + 表格说明 + + + 列表 + + + + + + 撇号 + + 尽可能不要使用撇号 + + + 不要用撇号来表达从属和拥有的关系 + + + 不要用撇号来表达缩写 + + + 不要用撇号来表达复数 + + + + 不正确的撇号 + + + the Main Menu'sHelp option + + + don't use the default option + + + several SCSI disk's + + + + + 正确：不使用撇号 + + + the Help option on the Main Menu + + + do not use the default option + + + several SCSI disks + + + + + + + 方括号 + + + + 不要使用方括号 [就像这样] 替换圆括号 (就像这样) + + + 使用方括号表达可选的命令行参数 + + + 不要使用尖括号表达文本中的变量，应使用 replaceable 标记。标记用法请参考 。 + + + + + + 大写 + + 下列情况下大写： + + + 首字母缩写中的所有字母，除非是众所周知的特例 + + + 列表中第一个词的第一个字母 + + + 顺序列表中第一个词的第一个字母 + + + 按键名称的第一个字母，例如 Shift + + + 句子的第一个字母 + + 命令名 + 避免在句首使用命令名或应用程序名称，如果它们的首字母是小写的话。 + + + + 冒号后面完整句子的首字母 + + + 下列情况下不要大写： + + + 组合的名词，后面是缩写或首字母组合 + + + 如果要强调一些内容 + + + 变量名 + + + 冒号后面，不完整句子的首字母 + + + + + + 标题 + + 对于标题，以及图象和表格的说明，使用相同的规则。不要在标题最后加上句号。 + + + + 冒号 + + 在下列情况下，使用冒号： + + + 引入列表 + + + 在解释的前面 + + + 在介绍之后 + + + 下列情况下，不要使用冒号： + + + 要引入图象或表格 + + + 介绍标题 + + + 介绍一个过程之后 + + + + + + 表栏标题 + + 使用与标题相同的规则 + + + + 逗号 + + 下列情况下，使用逗号： + + + 区分系列中的对象 + + + 区分句子的部分 + + + 区分非限制性的短语 + + + 与破折号类似，表达同位语 + + + 在 例如， 和类似的表达中 + + + 下列情况下，不要使用逗号： + + + 一系列形容词修饰一个对象时 + + + 两个短的独立子句间 + + + + + + 命令 + + 不要将命令作为动词。 + + + + 缩写 + + 不要使用缩写，类似 can't, don't, 或 isn't。 + + + + 破折号 + + 不要使用破折号或连接号。使用分段或冒号，如果是介绍性文字的话。如果有很多内容要介绍，那么使用一个列表。 + + + + 省略号 + + 下列情况下，使用省略号： + + + 要表示忽略了句子的一部分 + + + 要表示引用文本的间断 + + + + + + 分数 + + 使用分数时，遵循这些规则： + + + 在表格中，以及度量单位中，使用分数的数字形式，在正文中使用文本形式。 + + + 数字和相连的分数间添加空格，以防混淆。例如：1 1/2 而不是 11/2。 + + + 如果分数用作复合的修饰，在分数和度量单位间添加连字符。 + + + + + + 性别 + + 请参考 。 + + + + 语法 + + 标准的英语语法规则，请参考 Chicago Manual of Style ( http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html)。 + + + + 标题 + + 在标题中使用下面的大写规则： + + + 第一个词的首字母大写 + + + 名词，形容词和动词的首字母大写 + + + 连词，冠词和少于四个字母的介词都应小写 + + + 四个字母的介词或更多时首字母大写 + + + 四个字母的连词或更多时大写 + + + + + + + + 连字符 + + 下列情况下，使用连字符： + + + 组合修饰中的数字 + + + 避免混淆 + + + 在标准的前缀和后缀中。请参考 American Heritage Dictionary (http://www.bartleby.com/61/)。 + + + 在拼写的分数中 + + + 在由两个或多个单词构成的变量名中，类似 directory-name。注意： filename 是特例。 + + + 下列情况下，不要使用连字符： + + + 对于行话 + + + 对于动词 + + + 以 ly 结尾的副词 + + + 数字作为单一修饰时 + + + + American Heritage Dictionary (http://www.bartleby.com/61/) 列为不需连字符的单词，以及有共同前缀的词 + + + 商标 + + + + + + 拉丁文名称 + + 不要使用拉丁文名称。使用相应的英文名称。 + + + + 像 + + 不要使用 像 来表达等价或相似。 + + + + 列表 + + 使用以冒号结尾的完整的句子引入列表。 + + + + 数字 + + 下列情况下，拼写出数字： + + + 从 0 到 9 的数字，除非数字是测度的一部分 + + + 估计 + + + 极端情况，类似 百万，但要在前面加上一个数字。 + + + 出现在句子开头的数字 + + + 后面紧接一个数的数字。例如：两个 10 MB 的文件 + + + + + + 数字形式 + + 下列情况下，使用数字： + + + 数字 10 或更大 + + + 负数 + + + 大多数分数 + + + 百分数 + + + 小数 + + + 测度 + + + 小于一秒的时间单位 + + + 对位和字节的引用 + + + + + + 圆括号 + + 下列情况下，使用圆括号： + + + 要包含第一次出现的名称的缩写 + + + 在手册页的引用中，指明章节号 + + + + + + 句点 + + 下列情况下，使用句号： + + + 结束句子 + + + 文件和目录名中 + + + 可能被误认为单词的缩写中，类似 a.m. 和 U.S. + + + + + + 标点 + + 使用标准的英语标点规则。请参考 Chicago Manual of Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html)。 + + + + 数字中的标点 + + 不要在四位的数字中使用逗号。如果超过四位，那么使用逗号。 + + + + 引号 + + 使用引号来表示内容是不变地从其他来源复制的。不要使用引号来区分不合适的用词。如果用词不合适，换一个别的。如果必须用这个词，就在词汇表中解释它，使这种用法变得合理。 + + + + See v. Refer to + + 向用户提供参考资源时，使用 "refer to" 而不是 "see"，使用 "refer also to" 而不是 "see also"。这样可以与索引用到的 see 和 seealso 标记区分开。 这些标记用于在索引中创建特殊的链接。为了在文档中保持一致，我们保留关键字 "see" 和 "see also" 用作超链接的索引引用，使用 "refer to" 和 "refer also to" 表达非超链接的，非索引的引用。 + + + + 分号 + + 不要使用分号。 + + + + 斜线 + + 除了用作文件名的一部分之外，不要使用斜线 "/"。不能包含 and/or 这样的内容，应该换成其中任何一个。 + + + + 拼写 + + 使用标准的英语拼写规则，请参考 American Heritage Dictionary (http://www.bartleby.com/61/)。 + + + + 书名 + + 对于文档的名称，使用与标题相同的规则。 + + + + 单位 + + 使用单位时，遵循下列规则： + + + 使用标准的单位缩写，不要自行创造缩写。 + + + 请参考 IEEE Standard Dictionary of Electrical and Electronics Terms。 + + + 在缩写的可能被误解为单词的单位中使用句点。 + + + 大多数标准的缩写单位都同时适于单数和复数。 + + + 在数字和单位之间加上空格。 + + + + + +
+
+ 行文技巧 + + 本节包含了一些技巧提示，来自 &FDP; 作者们曾遇到的情况。您应理解运用它们，来改善自己的文档。&FDP; 作者乐于接受新的范例。 +
+ 主动语态 + 总是使用主动语态，除非这样很别扭。文档告诉用户如何完成一项任务，应当给出清楚简明的指令。避免使用"必须", "需要"之类的词。这些词在文档中是多余的，因为读者期望看到您给出必要的步骤来完成任务。同样，避免使用"可能," "也许"等等，表示您对问题不很确定的词。您的文档应当权威地描述一个主题。读者不应担心按照文档做会有莫名奇妙的效果。 + + 不正确：被动语态 + 命令 yum update 必须被运行。 + 您也许想运行 yum update 命令。 + + + 正确：主动语态 + 运行 yum update 命令。 + +
+
+ 一般现在时态 + 以一般现在时态写作。最好的经验，是不需用 "将要" 来描述用户将要做或看到的内容。它们没有意义，并可能混淆翻译者。它们也通常与被动语态有关，请参考 。 + + 不正确：将来时态 + 应用程序将要显示目标文件的列表。 + 目标文件的列表将要被应用程序显示出来。 + + + 正确：一般现在时态 + 应用程序显示目标文件的列表。 + +
+
+ 叙述的语气 + 不要用第一人称"我" "我们" 来引用作者自己 (无论是否包含读者)，&FDP;，&FED; 社群或任何群体。不要用第三人称指代用户 ("他" "她" 或 "他或她") 或者 "某人"。使用第二人称 "您" 来指代读者是可以的。 + + 不正确：第一或第三人称 + 正如上文所述，我通常在配置 Samba 服务器之前运行 up2date。 + 如果用户需要备份他的或她的文件，他或她应当使用 tar 或 cpio 命令。 + + + 正确：第二人称，或不使用代词 + 配置 Samba 服务器之前，请参考关于 up2date 的小节。 + 如果需要，用户可以使用 tar 或 cpio 命令来备份文件。 + +
+
+ 否定的用词 + 避免说不，因为它使教程显得武断。可以使用"避免"来代替。注意否定的词通常使用缩写，例如 don't 或 can't。请参考 。 +
+
+ 不确定 + 避免过度使用 "典型的"，"通常地"，"大多数时候"，"许多"等诸如此类的词。 +
+
+ 多余的内容 + 避免涉及多余的内容，例如如何更新 &FC; 系统。这些关键的主题在其他教程中已有讲述。作者们经常违反这个准则，因为觉得自己的教程不够长。但是，不要偏离您的主题。如果其他教程可以完整的覆盖那些主题，那么指引读者阅读那些文档。 +
+
+ 自行评估价值 + 避免类似 "最重要的是应该做 XYZ" 的表述。如果这个过程很重要，读者一定希望在您的文档中看到。反过来说，如果您的文档中出现了某个过程，作者一定会觉得那很重要，尤其是当这个过程占用了整整一节的时候。其实只要说 "做 XYZ"，然后详细说明就可以了。如果整整一节都是对如何做 XYZ 的说明，就干脆不要说这句话。请参考 。 +
+
+ 明确的语言 + 对于用户应当做出的动作，使用明确的词汇。不要让读者 "去" 选择，或者让读者在菜单里 "找"。 + + 不正确：不明确的用词 + + + 转到 Main Menu -> Foobar + + + 找到标记 Search 的选项 + + + + + 正确：明确的用词 + + + 在 Main Menu 菜单中，选择 Foobar + + + 选择 Search 选项。 + + + + + 不要区别对待非图形界面用户 + 如果您的文档是关于纯图形界面程序的，那么可以随意使用 "点击"。如果应用程序有字符界面，那么可以使用 "选择"，像上面那样。 + +
+
+ DocBook 技巧 + 这一节包含关于如何在文档中更有效地使用 DocBook 标记的技巧。 +
+ 创建提示 + 避免过分使用提示。在提示中只包含最重要的内容，使提示尽可能短。将用来解释的背景说明移到提示之外。使用简短的描述性的标题。标题的大小写规则与正文标题一致。 + + 不正确：过长的提示 + + + 使用 <command>sfdisk</command> 检测输入 + + sfdisk 命令接受一个脚本文件作为标准输入，来设置硬盘的分区。sfdisk 有些情况下拒绝一个有错的输入文件。在另一些情况下，它将无保留的执行输入，在硬盘上写入错误的分区。在写入磁盘前，总是用 sfdisk -n 命令检测输入文件。 + + + + + 正确：简短的提示 + + sfdisk 命令接受一个脚本文件作为标准输入，来设置硬盘的分区。sfdisk 有些情况下拒绝一个有错的输入文件。在另一些情况下，它将无保留的执行输入，在硬盘上写入错误的分区。检测输入在写入磁盘前，总是用 sfdisk -n 命令检测输入文件。 + + 避免在章节或提示的标题中使用标点，除非必须使用逗号。在标题中包含与提示相关的内容，例如 "需要重启"，而不是简单地使用提示类型作为标题 ("警告")。 + 提示的标题应使用与正文标题相同的大小写规则。 +
+
+ + <sgmltag class="starttag">replaceable</sgmltag> 标记 + 如果您的文档表述了作为约定的一个特定的值，那么不要在文中或示例中使用 replaceable 标记。 +
+
+ XML 实体 + 使用 &FDP; 提供的实体。这些实体可以在 fedora-docs 的 common/ 目录找到。(请参考 。) 例如，不要使用缩写 "FC2"，应当使用预定义的实体 "&FC; &FCVER;"，这样将生成文本 "&FC; &FCVER;"。 +
+
+
+ diff --git a/docs-tutorial-zh_CN.xml b/docs-tutorial-zh_CN.xml new file mode 100644 index 0000000..28af5dd --- /dev/null +++ b/docs-tutorial-zh_CN.xml @@ -0,0 +1,72 @@ + + + 文档的布局 + 在本章您将看到 &PROJECT; 文档中，主控文件的示例。这个示例与 Docs Project 处理 DocBook XML 的方式相关。主控文件包含文档的主要结构，以及到定义公共实体的文件的链接，还包括定义文档版本和日期的实体。 + + 主控文件 + 下面是一个简单的主控文件 + + +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../common/fedora-entities-en.xml"> +%FEDORA-ENTITIES-EN; + +<!ENTITY VERSION "0.1"> <!-- change version of tutorial here --> + +<!ENTITY BOOKID "example-tutorial-&VERSION; (2003-07-07)"> <!-- change last modified date here --> + +<!ENTITY LEGALNOTICE SYSTEM "../common/legalnotice-en.xml"> + + +]> + +<article id="example-tutorial" lang="en"> + <articleinfo> + <title>Example Tutorial</title> + <copyright> + <year>2003</year> + <holder>&FORMAL-RHI;</holder> + <holder>Tammy Fox</holder> + </copyright> + <authorgroup> + <author> + <surname>Fox</surname> + <firstname>Tammy</firstname> + </author> + </authorgroup> + &LEGALNOTICE; + </articleinfo> + + <section id="some-section"> + <title>Some Section</title> + + <para> + This is an example section. You can also use sect1, sect2, etc. + </para> + + <warning> + <title>Warning</title> + <para> + Example of an admonition. + </para> + </warning> + + </section> + +<index id="generated-index"></index> +</article> + + + + + 包含许可信息 + + 文档版式 + 许可 + + 所有 &PROJECT; 手册 必须 包含文件 legalnotice.xml。这个文件包含了 GNU Free Documentation License (FDL) 的文本。 + 示例主控文件显示了如何包含它们。 + + diff --git a/docs-vim-zh_CN.xml b/docs-vim-zh_CN.xml new file mode 100644 index 0000000..aea10db --- /dev/null +++ b/docs-vim-zh_CN.xml @@ -0,0 +1,87 @@ + + + VIM 与 DocBook + + VIM + + VIM 有很多特性，有助于撰写类似 DocBook 的 XML 文档，包括语法高亮和可定制的按键绑定。另外，还可以用外部程序辅助 VIM 完成拼写检查等操作。本章假定您已知悉 VIM 一般用法；如果您要学习一般用法，执行 vimtutor 或在 VIM 中执行 :help tutor。 + + 设置 <filename>.vimrc</filename> 文件 + + VIM + 配置文件 + + 下面是一个示例 .vimrc 文件，打开了一些 VIM 特性，便于编辑类似 DocBook 的 SGML 或 XML 文档： +" 关闭 vi 兼容特性，类似有限的撤销 +set nocompatible +" 基于文件扩展名的语法高亮 +syntax on +" 在 80 个字符后面自动插入新行 +set textwidth=80 +" 自动缩进 +set autoindent +" 使用 % 匹配 SGML 标记 +source $VIMRUNTIME/macros/matchit.vim + + + 一些特性需要安装 vim-enhanced。如果您使用的是 vim-minimal，或者是旧版本的 VIM，可能不包含 $VIMRUNTIME/macros/matchit.vim 文件，那么可以在 Vim.org 下载 matchit.zip 并加载。 + + + + VIM 中的按键映射 + VIM 可以使创建 DocBook 文档更加快捷，只要将经常使用的标记 (或任何词汇短语) 定义为快捷键。默认情况下，键盘映射以反斜线 (\) 开始，但是也可以用命令定义，类似 let mapleader = + ","。有两种方式来使用下面的例子；您可以将它写在 .vimrc 文件中，或者将它保存为单独的文件，并在 .vimrc 文件中以 source 命令加载。e />:nohlsearcha + +" common tags that start a new text block +imappa O +imaps1 joO +imappl O0i +imapcp O0i + +" common tags that are placed inline +" use F>a +imapen F>a +imapfi F>a +imaplt F>a +imapre F>a +imapui F>a +imapul F>a +imapsi F>a +imapus F>a +imapsy F>a +imapcm F>a +" entities +imap > > +imap < < +]]> + 不幸的是，这不是所有 DocBook 命令的完整集合，因此您需要自行定义，或定制 范例中的定义。 + + + 其他 VIM 资源 + 其他 VIM 相关的资源可以在这里找到： + + + + 示例 sgml-vimrc，来自 Beginner's guide to Vi Improved (VIM) + + + + VIM Quick Reference Card + + + + + Vim 作为 XML 编辑器 + + + + + VIM REFERENCE MANUAL，包含在 vim-common 软件包中 — /usr/share/vim/<version>/doc/intro.txt，可以在 VIM 中执行 :help intro 查看。 + + + + diff --git a/docs-xml-tags-zh_CN.xml b/docs-xml-tags-zh_CN.xml new file mode 100644 index 0000000..7cc752d --- /dev/null +++ b/docs-xml-tags-zh_CN.xml @@ -0,0 +1,1615 @@ + + + DocBook XML 标记 + + XML + 标记 + XML 标记 + + 请仔细阅读这一章。这一章描述了 Docs Project 使用的标记。一些规则是 Docs Project 特定的。 + 如果这些标记运用合适，搜索文档时可以得到有意义的结果。这些标记帮助搜索引擎确认与搜索条件相关的信息。另一个好处是使 &PROJECT; 文档拥有相同的外观。(不过，由于输出格式不同，外观仍然会有一些区别。) + + XML + 标记概要 + + XML 中所有标记必须有开标记和闭标记。另外，按照惯例，章、节、图象、表格等必须有唯一的标识符，这样可以被正确标识，需要的话也可以交叉引用。 + 尽管 XML 可以处理很多文档形式，这里介绍的只是 article 一种。 + 本章只介绍 &PROJECT; 文档使用的标记，并不是所有可用的 DocBook XML 标记。完整的列表请参考： + + + http://www.docbook.org/tdg/en/html/docbook.html + + + + 标记和实体警告 + + xml 标记 + 警告 + + 应当牢记本节的警告。它们比有效的 DocBook XML 更加严格，这些规则的存在，是为了使 HTML 和 PDF 输出看起来更合适。 + + + 不要使用商标实体 + + 不要使用商标实体 &trade;, &copy;, 或 &reg; 因为它们无法为所有字符集产生 HTML 输出。这些实体产生的 HTML 输出定义在 DTD 中，无法通过样式表改变。 + 应当使用 trademark 标记以及相关类别，如下所示： + + + <trademark>其后是商标符号</trademark> + + + <trademark class="registered">其后是注册商标符号</trademark> + + + <trademark class="copyright">其后是版权符号</trademark> + + + + + + + para 标记中的内容 + + 除非是文本段落，否则不要使用 para。这个标记在 PDF 中，会使其间的文本包含多余的空白。 + 特别的，在下列标记之外不要使用 para (换句话说，不要把下列标记包含在 para 中)： + + + <screen> + + + <itemizedlist> + + + <orderedlist> + + + <variablelist> + + + <table> + + + + + + 包含在 para 标记中的 listitem + + 包含在 para 中的 listitem 标记 必须 紧挨 <para> 的开始标记，以避免 PDF 中的多余空白。 + + + + 包含在 screen 标记中的内容 + + XML 文件中，screen 标记 (<screen> 和 </screen>) 必须 靠左对齐，screen 包含的内容必须同样靠左对齐，除非有意留出空白。否则，多余的空白将出现在 HTML 中。 + + + + + + + <command>application</command> + + + XML 标记 + application + + application 是图形界面应用程序的名字。command 是一个可执行的程序，或者运行应用程序的命令。 + + <application> 和 </application> 标记使您可以引用应用程序。例如，下面的 XML： + + +要在 Linux 中访问 Web，您可以使用 +<application>Mozilla</application> 或 +<application>lynx</application>，如果您只需要字符界面的话。 + + + 产生如下输出： + 要在 Linux 中访问 Web，您可以使用 +Mozilla 或 +lynx，如果您只需要字符界面的话。 + + + + <command>chapter</command> + + + XML 标记 + chapter + + 一篇 DocBook 文档可以划分为多章，类似： + + +<!--$Id: docs-xml-tags-zh_CN.xml,v 1.1 2005/12/09 15:28:54 bbbush Exp $ --> + + <chapter id="ch-sample"> + <title>示例章</title> + + <para>这是示例章，显示了用于创建章、节和小节的 XML 标记。</para> + + </chapter> + + + chapter 还可以进一步划分为节 (sect1, sect2, sect3 等等)。请参考 。 + + + + <command>citetitle</command> + + + XML 标记 + citetitle + + + <citetitle>标记用来格式化一个特别的引用 (引用标题可以自行输入，也可以使用实体实体是引用其他手册或教程的快捷方式。它可以在主控文档中定义，对于特定的文档集合，也可以在 DTD 引用的文件中定义。，如果在文档中已经定义的话)。 + 例如： + + +<citetitle>IG;</citetitle>. + + + 输出类似于 &IG;，因为 &IG; 是已定义的实体。 + + + + <command>command</command> + + + XML 标记 + command + + application 是图形界面应用程序的名字。command 是一个可执行的程序，或者运行应用程序的命令。任何命令行程序，或是只有字符界面的工具都应以 command 标记。 + 如果某些文本是一个命令，那就用 <command> 和 </command> 标记： + + +要在安装后改变键盘设置，切换为 root 并使用 <command>redhat-config-keyboard</command> 命令，或者在 root 提示符下输入 <command>setup</command>。 + + + 输出： + 要在安装后改变键盘设置，切换为 root 并使用 redhat-config-keyboard 命令，或者在 root 提示符下输入 setup。 + 另一个例子： + + +<command>MAILNOVIOLATIONS</command> — 如果设置为 <command>true</command>，这个选项使得 Tripwire 定时发送邮件报告，无论是否出现了越权操作。默认值是 <command>true</command>。 + + + 输出： + + MAILNOVIOLATIONS — 如果设置为 true，这个选项使得 Tripwire 定时发送邮件报告，无论是否出现了越权操作。默认值是 true。 + + 注意 本例中，选项值 (true) 被标记为 <command>。由于选项是出现在配置文件中的，(命令行选项应当使用 <option> 标记，)并且由于没有为配置文件选项定义什么标记，我们约定使用 <command> 标记配置文件中的选项。 + 名词也标记为 command，因为没有其他合适的标记： + + + 配置文件中的选项，类似 Apache 指令 + + + 守护进程名称 + + + + + + <command>computeroutput</command> + + + XML 标记 + computeroutput + + 要显示屏幕输出，使用这个标记： + + +<computeroutput>您是否要删除文件? y n</computeroutput> + + + 输出： + + 您是否要删除文件? y n + + + + + <command>emphasis</command> + + + XML 标记 + emphasis + + 要强调的内容，使用 <emphasis> 和 </emphasis> 标记。例如： + + +安装过程将 <emphasis>删除所有</emphasis> 硬盘上的 <emphasis>所有</emphasis> 已有 Linux 分区，非 Linux 分区不会被删除。 + + + 输出： + 安装过程将 删除所有 硬盘上的 所有 已有 Linux 分区，非 Linux 分区不会被删除。 + + + + <command>example</command> + + + XML 标记 + example + + + <example> 和 </example> 标记用来格式化某个文档中的文本，适于显示代码示例等。 + + <example> 标记应当有一个 ID 和标题： + + <example id="static-ip"> + <title>使用 DHCP 的静态 IP 地址</title> + +<screen width=60> +<computeroutput> +host apex { + option host-name "apex.example.com"; + hardware ethernet 00:A0:78:8E:9E:AA; + fixed-address 192.168.1.4; +} +<computeroutput> +</screen> + + </example> + + 输出： + + 使用 DHCP 的静态 IP 地址 + + +host apex { + option host-name "apex.example.com"; + hardware ethernet 00:A0:78:8E:9E:AA; + fixed-address 192.168.1.4; +} + + + + + + + <command>filename</command> + + + XML 标记 + filename + + + <filename> 和 </filename> 标记定义文件名和路径。由于目录是特殊的文件，因此也使用 filename 标记。例如： + +编辑 <filename>/home/smoore/sam.xml</filename> 文件，修改它或加注释。 + + 输出： + 编辑 /home/smoore/sam.xml 文件，修改它或加注释。 + 它们也用来标记 RPM 软件包名称。例如： + +要使用 <application>Keyboard Configuration Tool</application>，必须安装 <filename>system-config-keyboard</filename> 软件包。 + + 输出： + 要使用 Keyboard Configuration Tool，必须安装 redhat-config-keyboard 软件包。 + + 注意 + 目录名必须以斜线 (/) 结尾，以与文件名区分。 + + + + + <command>firstterm</command> + + + XML 标记 + firstterm + + + <firstterm> 和 </firstterm> 标记用来定义一个用户不熟悉，但将频繁出现的词。例如： + + +几乎所有现代操作系统都使用 <firstterm>disk +partitions</firstterm>(磁盘分区)，&FC; 也不例外。 + + + 输出： + 几乎所有现代操作系统都使用 disk partitions(磁盘分区)，&FC; 也不例外。 + + + + <command>footnote</command> + + + XML 标记 + footnote + + 如果您需要添加脚注，可以这样： + + +如果您想进行服务器级 +<footnote> +<para> +服务器级安装用于安装典型的服务器环境。注意，服务器级安装不会安装图形界面。 +</para> +</footnote> 安装，请参考 <citetitle>Installation Guide</citetitle>。 + + + 输出： + 如果您想进行服务器级 服务器级安装用于安装典型的服务器环境。注意，服务器级安装不会安装图形界面。 安装，请参考 Installation Guide。 + + + + <command>figure</command> + + + XML 标记 + figure + + + 注意 + 顺序很重要！EPS 文件 必须 首先声明。 + + 示例图象声明： + + +<figure id="fig-ksconfig-basic"> + <title>基本设置</title> + <mediaobject> + <imageobject> + <imagedata fileref="./figs/ksconfig/ksconfig-basic.eps" + format="EPS"/> + </imageobject> + <imageobject> + <imagedata fileref="./figs/ksconfig/ksconfig-basic.png" + format="PNG"/> + </imageobject> + <textobject> + <phrase> + 一些关于图象的文本描述 + </phrase> + </textobject> + </mediaobject> +</figure> + + + 下面列出了需要修改的内容： + +<figure id="fig-ksconfig-basic"> ==> id="" 可以修改 + +<title>基本设置</title> ==> 标题可以修改 + +fileref="./figs/ksconfig/ksconfig-basics.eps"> ==> .eps 位置可以修改 + +fileref="./figs/ksconfig/ksconfig-basics.png"> ==> .png 位置可以修改 + +<phrase>一些关于图象的文本描述</phrase> ==> "一些关于..." 可以修改 + 关于获取屏幕截图，请参考 。 + + + 图形用户界面标记 + + XML 标记 + GUI 标记 + + + + <command>guilabel</command> + + + XML 标记 + GUI 标记 + guilabel + + + XML 标记 + guilabel + + 使用 <guilabel> 和 </guilabel> 作为描述 GUI 时的默认标记，类似窗体名称或窗体标题。例如： + + +<guilabel>Authentication Configuration</guilabel> 屏幕指引您如何配置更安全的系统。 + + + 输出： + + Authentication Configuration 屏幕指引您如何配置更安全的系统。 + + + + <command>guibutton</command> + + + XML 标记 + GUI 标记 + guibutton + + + XML 标记 + guibutton + + 使用 <guibutton> 和 </guibutton> 标记表示屏幕或菜单中的按钮。例如： + + +选择 <guibutton>Activate on boot</guibutton> 按钮，配置 X 窗口系统自动启动。 + + + 输出： + 选择 Activate on boot 按钮，配置 X 窗口系统自动启动。 + + + + <command>guiicon</command> + + + XML 标记 + GUI 标记 + guiicon + + + XML 标记 + guiicon + + + <guiicon> 和 </guiicon> 标记用来表示面板或桌面图标。例如： + + +双击桌面上的 <guiicon>Start Here</guiicon> 图标。 + + + 输出： + 双击桌面上的 Start Here 图标。 + + + + <command>guimenu</command> 和 <command>guimenuitem</command> + + XML 标记 + GUI 标记 + guimenu + + + XML 标记 + guimenu + + + XML 标记 + GUI 标记 + guimenuitem + + + XML 标记 + guimenuitem + + 要表示一个菜单 (安装程序或控制面板中的菜单)，使用 <guimenu> 和 </guimenu> 标记。 + 要表示子菜单，使用 <guimenuitem> 和 </guimenuitem> 标记。(请注意示例中为了输出需要，插入了一些换行。)例如： + + +选择 <guimenu>Main Menu</guimenu> => + <guimenuitem>Programming</guimenuitem> => <guimenuitem>Emacs</guimenuitem> 来启动 +<application>Emacs</application> 编辑器。 + + + 输出： + 选择 Main Menu => Programming => Emacs 来启动 Emacs 编辑器。 + + + + + <command>keycap</command> + + + XML 标记 + keycap + + 要表示某个按键，应当使用 <keycap> 和 </keycap> 标记。按键会自动加上尖括号，因此不要在 XML 代码中再加一次。例如： + + +要作出选择，按下 <keycap>Enter</keycap> 键。 + + + 输出： + 要作出选择，按下 Enter 键。 + + + <command>menuchoice</command> + + + XML 标记 + menuchoice + + 通常，使用鼠标对于频繁的操作过于繁琐。因此，程序员在程序中设置了快捷键来简化使用。应当使用 shortcut 标记包含 keycap 标记，然后再整个包含在 menuchoice 标记中，来表示快捷键。例如： + + +打开菜单并选择： + <menuchoice> + <shortcut> + <keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo> + </shortcut> + <guimenu><accel>F</accel>ile</guimenu> + <guimenuitem><accel>S</accel>ave</guimenuitem> + </menuchoice>. + + + 输出： + 打开菜单并选择：CtrlsFileSave. + + + + <command>keycombo</command> + + + XML 标记 + keycombo + + 要描述按键组合，使用 <keycombo> 和 </keycombo>, <keycap> 和 </keycap> 标记。例如： + + +要重启系统，按下 <keycombo> +<keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap> +</keycombo>. + + + 输出： + 要重启系统，按下 CtrlAltDel. + + + + 列表 + + 列表 + 创建 + + 您可以用 XML 创建多种列表。您可以创建无序的枚举，有序的编号列表，或是变量表 (先是一个词，然后是单独的一段话)。 + 还有一种列表适于表格，最后一种是用于定义词汇解释的列表。 + 下面各节描述了各种列表，以及如何创建。 + + + <command>itemizedlist</command> + + + XML 标记 + + itemizedlist + + + + XML 标记 + 列表 + itemizedlist + + + 列表 + + itemizedlist + + + + itemizedlist 适于向读者呈现重要的信息，而信息是无序的。它比 variablelist 更短，也简单一点。 + 要创建 itemizedlist (也称为枚举列表)，可以这样： + + 注意 下面列表中的文本是直接包含在 para 标记中的。如果您使用列表，不要用这个标记，否则列表中会包含多余空白，无法对齐。如果多个列表项是多行文本，空白会更加明显。HTML 版本不会像 PDF 版本那样明显。 + + +<itemizedlist> + <listitem> + <para>熟悉安装程序的界面</para> + </listitem> + + <listitem> + <para>开始安装程序</para> + </listitem> + + <listitem> + <para>选择安装方法</para> + </listitem> +</itemizedlist> + + + 输出： + + + 熟悉安装程序的界面 + + + 开始安装程序 + + + 选择安装方法 + + + + + + <command>orderedlist</command> + + + XML 标记 + + orderedlist + + + + 列表 + + orderedlist + + + + XML 标记 + 列表 + orderedlist + + + orderedlist 适于向读者显示必须以一定顺序出现的信息。orderedlist 用来向读者描述一步一步的场景转换很不错。 + 要创建 orderedlist (有序列表) 可以这样： + + 注意 下面列表中的文本是直接包含在 para 标记中的。如果您使用列表，不要用这个标记，否则列表中会包含多余空白，无法对齐。如果多个列表项是多行文本，空白会更加明显。HTML 版本不会像 PDF 版本那样明显。 + + +<orderedlist> + <listitem> + <para>在线 &mdash; http://www.redhat.com/support/errata; 提供 + 可以在线阅读的更正，您也可以下载光盘镜像。 + </para> + </listitem> + + <listitem> + <para>电子邮件 &mdash; 发送空白邮件到 errata@redhat.com, + 您将收到完整的包含安装程序和相关软件 (如果有的话) 的更正说明。 + 同时还包括软件更新以及光盘镜像的 URL。通过这些 URL 来下载 + 镜像。请注意：下载时使用二进制模式。</para> + </listitem> +</orderedlist> + + + 输出： + + + 在线 — http://www.redhat.com/support/errata; 提供可以在线阅读的更正，您也可以下载光盘镜像。 + + + 电子邮件 — 发送空白邮件到 errata@redhat.com, 您将收到完整的包含安装程序和相关软件 (如果有的话) 的更正说明。同时还包括软件更新以及的光盘镜像的 URL。通过这些 URL 来下载镜像。请注意：下载时使用二进制模式。 + + + + + + <command>variablelist</command> + + + XML 标记 + + variablelist + + + + XML 标记 + 列表 + variablelist + + + 列表 + + variablelist + + + + variablelist 适于表现一个词以及相关的解释和描述。 + 要创建 variablelist 可以这样： + + 注意 下面列表中的文本是直接包含在 para 标记中的。如果您使用列表，不要用这个标记，否则列表中会包含多余空白，无法对齐。如果多个列表项是多行文本，空白会更加明显。HTML 版本不会像 PDF 版本那样明显。 + + +<variablelist> + <varlistentry> + <term> 新的多介质安装过程 </term> + <listitem> + <para>由于安装程序越来越大，RedHat 开发了 + 可以处理多张 CD-ROM 介质的安装程序。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>XFree 4.0 </term> + <listitem> + <para>X 窗口系统的配置从来没有如此简单。 + 从选择显示器及其设置，到显卡探测，以及测试您期望的 X 窗口设置， + Xconfigurator 可以搞定一切。</para> + </listitem> + </varlistentry> +</variablelist> + + + 输出： + + + 新的多介质安装过程 由于安装程序越来越大，RedHat 开发了可以处理多张 CD-ROM 介质的安装程序。 + + XFree 4.0 + + X 窗口系统的配置从来没有如此简单。从选择显示器及其设置，到显卡探测，以及测试您期望的 X 窗口设置，Xconfigurator 可以搞定一切。 + + + + + 警告 + + 不要 设置表格的 frame 属性，否则 PDF 生成会失败。 + + + + 在表格中创建列表，使用 <command>simplelist</command> + + XML 标记 + + simplelist + + + + XML 标记 + 列表 + simplelist + + + 列表 + + simplelist + + + + 表格 + 在表格中创建列表 + + simplelist + + + + simplelist 是无修饰的列表。simplelist 可以内联或按列对齐。 + 使用 simplelist 在表格内添加分离的文本段落。通常的列表，例如 itemizedlist，不能嵌入在表格内。 + XML 代码如下： + + + <table id="tb-hwinfo-hostbus"> + <title>主机总线适配器特性及配置要求</title> + + <tgroup cols="3"> + <colspec colnum="1" colname="HostBus" colwidth="33"/> + <colspec colnum="2" colname="Features" colwidth="34"/> + <colspec colnum="3" colname="Single" colwidth="33"/> + + <thead> + <row> + <entry>主机总线适配器</entry> + <entry>特性</entry> + <entry>Single-Initiator 配置</entry> + </row> + </thead> + + <tbody> + + <row> + <entry>Adaptec 2940U2W</entry> + + <entry><simplelist> + <member>Ultra2, wide, LVD.</member> + <member>HD68 external connector.</member> + <member>One channel, with two bus segments.</member> + <member>Set the onboard termination by using the BIOS + utility.</member> + <member>Onboard termination is disabled when the power is + off.</member> + </simplelist></entry> + + <entry><simplelist> + <member>Set the onboard termination to automatic (the + default).</member> + <member>Use the internal SCSI connector for private + (non-cluster) storage.</member> + </simplelist></entry> + </row> + + <row> + <entry>Qlogic QLA1080</entry> + + <entry><simplelist> + <member>Ultra2, wide, LVD</member> + <member>VHDCI external connector</member> + <member>One channel</member> + <member>Set the onboard termination by using the BIOS + utility.</member> + <member>Onboard termination is disabled when the power is off, + unless jumpers are used to enforce termination.</member> + </simplelist></entry> + + + <entry><simplelist> + <member>Set the onboard termination to + automatic (the default).</member> + <member>Use the internal SCSI connector for private + (non-cluster) storage.</member> + </simplelist></entry> + </row> + + </tbody> + </tgroup> + </table> + + + 输出： + + 主机总线适配器特性及配置要求 + + + + + + + 主机总线适配器 + 特性 + Single-Initiator 配置 + + + + + Adaptec 2940U2W + + + Ultra2, wide, LVD. + HD68 external connector. + One channel, with two bus segments. + Set the onboard termination by using the BIOS utility. + Onboard termination is disabled when the power is off. + + + + + Set the onboard termination to automatic (the default). + Use the internal SCSI connector for private (non-cluster) storage. + + + + + Qlogic QLA1080 + + + Ultra2, wide, LVD + VHDCI external connector + One channel + Set the onboard termination by using the BIOS utility. + Onboard termination is disabled when the power is off, unless jumpers are used to enforce termination. + + + + + Set the onboard termination to automatic (the default). + Use the internal SCSI connector for private (non-cluster) storage. + + + + + +
+ + 注意 + 注意 simplelist 标记的用法。<entry> 和 <simplelist> 标记必须靠紧，否则将产生解析错误。 + + 每个要加入 simplelist 的段落或列表项应当包含在 <member> 标记中。 + + + + <command>glosslist</command> + + + XML 标记 + + glosslist + + + + XML 标记 + 列表 + glosslist + + + 列表 + + glosslist + + + 使用 glosslist 来创建词汇表和解释。 + XML 代码如下： + + + <glosslist> + <glossentry> + <glossterm>applet</glossterm> + <glossdef> + <para>一个小程序，通常是实用工具或简单程序。</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>architecture</glossterm> + <glossdef> + <para>计算机或计算机系统中， + 组件的组织和整合的设计。</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>archive</glossterm> + <glossdef> + <para>将文件传送到存储设备，以节省空间和/或 + 加以组织。</para> + </glossdef> + </glossentry> + </glosslist> + + + 输出： + + + applet + + 一个小程序，通常是实用工具或简单程序。 + + + + architecture + + 计算机或计算机系统中，组件的组织和整合的设计。 + + + + archive + + 将文件传送到存储设备，以节省空间和/或加以组织。 + + + + + + + + <command>option</command> + + + XML 标记 + option + + 如果您的命令需要选项或设置标志，使用 <option> 和 </option> 标记。 + + 注意 + <option> 标记只用于命令行选项，不用于配置文件。 + + 指定选项的 XML 代码如下： + + +例如，运行命令 <command>ls</command> 时可以指定选项 <option>-la</option>。 + + + 输出： + 例如，运行命令 ls 时可以指定选项 。 + + + 索引节点 + + 创建索引 + + + XML 标记 + 创建索引 + + 下面的命令序列展示了如何向文档中添加一个索引项的代码： + + +<indexterm> <-- 这是要在索引中添加的词汇 +<primary>foo</primary> <-- 表示 "foo" 是首要条目 +<secondary>bar</secondary> <-- "bar" 将列在 "foo" 条目之下 +</indexterm> <-- 关闭索引项 + + + + foo + bar + + + <seealso> 标记允许您引用另一个索引项或其他手册。应确保您指向的 <seealso> 引用有自己的节点。例如： + + 创建索引 + seealso 标记 + + + +<indexterm> +<primary>SWAK</primary> +<seealso>salutations</seealso> +</indexterm> + + +<indexterm> +<primary>salutations</primary> +</indexterm> + + + + SWAK + Salutations + + + Salutations + + + <see> 标记允许您引用一个完整的索引节点。例如： + + 创建索引 + see 标记 + + + +<indexterm> +<primary>Guinness</primary> +<see>beer</see> <-- "beer" 将被列在 "Guinness" 条目下，但是应确保所引用的 "beer" 有自己的索引节点。 +</indexterm> + +<indexterm> +<primary>beer</primary> +</indexterm> + + + + Guinness + Beer + + + Beer + + 要查看这里的索引节点的 HTML 输出，请参考文档最后的 generated-index.html 文件。 + 索引是如何生成的? 如果文档中包含 indexterm，并且开标记和闭标记出现在文档或文章的结束标记之前，就创建索引，因为样式表参数 generate.index 的默认值是真。 + + + + <command>para</command> + + + XML 标记 + para + + 对于任意一段，<para> 和 </para> 标记必须作为这一段的开始和结束。 + 不要在除了简单段落之外使用 para 标记。否则，文本内部会产生多余的空白。 + 在下列标记周围不要使用 <para> (换句话说，不要把下列标记放在 <para> 标记中)： + + + + <screen> + + + + + <itemizedlist> + + + + + <orderedlist> + + + + + <variablelist> + + + + + <table> + + + + + + + <command>part</command> + + + parts + + + XML 标记 + part + + 在主控文件中，可以将章划分为部，以表示逻辑分组。例如，在主控文件中，以 part 标签包含章的实体： + + +<part id="pt-foo"> + <partintro> + <para>一些文本，对这一部分的介绍</para> + &CHAPTER; + + &ANOTHER-CHAPTER; +</part> + + + 如果您创建了一个 part，应当对内容作一些介绍。例如： + + + <part id="pt-setup"> + <title>设置环境</title> + <partintro> + <para>本节讲述当您刚加入 Docs Group 时需要的信息。 + 您也许会再参考本节中，有关安装 &FC; 的信息。</para> + </partintro> + + + 在 HTML 输出中，会生成单独的 HTML 页面，包含这一部的编号、标题、介绍和目录。在 PDF 输出中，这些信息会出现在单独的一页上。 + + + + <command>prompt</command> + + + XML 标记 + prompt + + 要显示提示符，类似 root 提示符或 DOS 提示符，使用 <prompt> 和 </prompt> 标记。例如： + + +在 <prompt>LILO:</prompt> 启动提示符下，输入 linux 来启动到 Linux 分区。 + +在 <prompt>C:\></prompt> 提示符下，输入... + + + 输出： + 在 LILO: 启动提示符下，输入 linux 来启动到 Linux 分区。 + 在 C:\> 提示符下，输入... + + 注意 + 在显示计算机输出的范例时 (通常是在 screen 标记中)，不要包含提示符或命令 (除非命令或提示符是您意图显示的计算机输出)。 + + + + + <command>replaceable</command> + + + XML 标记 + replaceable + + 要创建可替换的文本，使用 <replaceable> 和 </replaceable> 标记包围您用作可变值的文本。 + 这个例子演示了在引用 RPM 文件时如何使用 replaceable 标记。 + +foo-<replaceable>version-number</replaceable>.<replaceable>arch</replaceable>.rpm + + 输出： + +foo-version-number.arch.rpm + + + + + <command>screen</command> + + + XML 标记 + screen + + + <screen> 标记用来格式化文档中的文本，适于用来添加代码示例，计算机输出等等。在 HTML 中，使用 Fedora CSS 文件，可以显示为灰色背景的方框。需要这种效果时，只要将开标记 <screen> 和闭标记 </screen> 包围在需要强调的文本前后。 + + 注意 + 使用 <screen> 标记时，必须设置所包含的所有内容，包括 <screen> 标记本身为左对齐。这样，在转化为 HTML 时，在灰色背景内部文字之前不会出现多余的空白。 + + + <screen> 标记可能包含其他内联标记，类似 <computeroutput>, <userinput>, 或 <replaceable> 等等。其他内联标记未作要求。<screen> 标记本身可以提供足够的上下文，尤其对于简单的范例或列举文件而言。考虑范例的上下文，如果内联标记有助于阅读，那么就使用它。 + 如果您使用内联标记，牢记 <screen> 标记中的换行会在任何输出中生成换行。将标记与内容 放在同一行。不要在 <screen> 的内容中过分使用标记。 + + <screen> 示例如下： + + <screen> +这是 screen 的示例。其中无须使用 &lt;para&gt; 标记。 +</screen> + + 输出： + +这是 screen 的示例。其中无须使用 <para> 标记。 + + + 在 <command>screen</command> 中使用内联标记 + 如果您在 <screen> 中使用内联标记，遵循下列准则以保持一致。如果 screen 的内容是配置文件的清单或程序的输出，使用 <computeroutput> 标记包含整个输出。如果用户应当在命令行照范例输入，或是配置文件，使用 <userinput> 标记。用简短的叙述性的话来区分输入和输出，如下所示： + + <para> + 输入下面的命令： + </para><screen><userinput>command -sw file1</userinput></screen><para> + 可以看到下列输出： + </para><screen><computeroutput>Completed, time = 0.12 sec</computeroutput></screen> + 输出： + 输入下面的命令： + + command -sw file1 + + 可以看到下列输出： + + Completed, time = 0.12 sec + + + 注意 + 在 screen 标记中显示一条命令或命令序列时，不要显示提示符。 + + 如果 <screen> 向读者显示如何修改文本的 一部分，可以将修改部分以内联的 <userinput> 标记。您可以在大块内联的 <computeroutput> 文本中使用 <userinput>。这时不要包含更多上下文，除非必须这么做。下面的示例演示了这些准则： + + <para> + 编辑 <filename>/etc/sysconfig/init</filename> 文件，如下所示： + </para><screen> +GRAPHICAL=<userinput>yes</userinput></screen> + 输出： + 编辑 /etc/sysconfig/init 文件，如下所示： + +GRAPHICAL=yes + 对于如何在 screen 标记中使用 replaceable 标记，请参考 。 + + + + section + + XML 标记 + 节 + + + 节 + + 在文章中 (或者在 chapter 中，如果是 DocBook XML book 样式的话，类似 &IG;)，可以细分为节和小节。<sect1> 总是最顶层的节。如果两个 section 级别相同，那么一个不能包含另一个 (section 2 可以包含在 section 1 里面，但是如果再创建新的 section 1，必须先关闭当前的 section 1)。大致的布局如下： + + +<sect1 id="s1-uniquename"> + <title>插入标题</title> + <para> + 内容文本。 + </para> + + + <sect2 id="s2-uniquename"> + <title>插入标题</title> + <para> + 内容文本。 + </para> + + <sect3 id="s3-uniquename"> + <title>插入标题</title> + <para> + 内容文本。 + </para> + + </sect3> + + </sect2> + +</sect1> + + + 在 DocBook article 样式中，如果您只需要一级 section，可以使用 section 标记。例如： + + +<section id="sn-uniquename"> + <title>插入标题</title> + <para> + 内容文本。 + </para> +</section> +<section id="sn-anothername"> + <title>插入标题</title> + <para> + 内容文本。 + </para> +</section> + + + + + + <command>table</command> + + + XML 标记 + table + + 下面是创建表格的范例。 + +<table id="tb-mockup-before-begin"> + 这在 XML 中声明了一个表格，ID 是 "tb-mockup-before-begin"。 + +<title>Available Features of GNOME and KDE</title> + +<tgroup cols="3"> + 这在 XML 中声明了一个表格，包含三列。 + +<colspec colnum="1" colname="Features" colwidth="3"/> + colspec 表示您向 XML 声明的表格列信息。 colnum="1" 表示您对第一列的设定。colname="Features" 表示本列的标题是 "Features"。colwidth="3" 指定列宽。这里有些机关：如果两列的列宽分别是 1 和 2，那么 1 占据的页宽就是 2 的一半。但是，如果您需要让第一列比第二列的一半稍微宽一点，那么就用一个更大的数值，例如指定列宽分别为 10 和 20，然后把 10 增加到 11 或 12，这样就比第二列的 20 的一半大一点了。如果没有给定任何值，默认就是 1。 + +<colspec colnum="2" colname="GNOME" colwidth="2"/> +<colspec colnum="3" colname="KDE" colwidth="2"/> + +<thead> + 包含一个或多个表格行。 + +<row> + 包含一个或多个表格单元。 + +<entry>Features</entry> + 表格单元元素，一列表格单元中的一个，定义了行内的列。 + +<entry>GNOME</entry> +<entry>KDE</entry> +</row> +</thead> + +<tbody> + 包含一个或多个表格行，作为表格的主体。 + +<row> +<entry>高度可定制</entry> +<entry>yes</entry> +<entry>yes</entry> +</row> +<row> +<entry>多种窗口管理器</entry> +<entry>yes</entry> +<entry>yes</entry> +</row> +<row> +<entry>互联网程序</entry> +<entry>yes </entry> +<entry>yes </entry> +</row> +</tbody> +</tgroup> +</table> + + + Available Features of GNOME and KDE + + + + + + + 特性 + GNOME + KDE + + + + + 高度可定制 + yes + yes + + + 多种窗口管理器 + yes + yes + + + 互联网程序 + yes + yes + + + +
+ + 在表格中创建列表 + + XML 标记 + table + 表格中的列表 + + 在表格中创建列表比较困难，它要求严格的格式化以及一些 Emacs 无法完成的命令补全。 + 需要使用的标记是 <simplelist> 和 <member>。 + 下面是在表格中创建列表的例子。 + + +<table id="tb-hardware-powerswitch"> + <title>不间断电源硬件</title> + <tgroup cols="4"> + <colspec colnum="1" colname="Hardware" colwidth="2"/> + <colspec colnum="2" colname="Quantity" colwidth="2"/> + <colspec colnum="3" colname="Description" colwidth="6"/> + <colspec colnum="4" colname="Required" colwidth="2"/> + + <thead> + <row> + <entry>Hardware</entry> + <entry>Quantity</entry> + <entry>Description</entry> + <entry>Required</entry> + </row> + </thead> + + <tbody> + + <row> + <entry>Serial power switches</entry> + + <entry>Two</entry> + + <entry><simplelist> <member>Power switches enable each cluster system + to power-cycle the other cluster system. Note that clusters are + configured with either serial or network attached power switches and + not both.</member> + + <member>The following serial attached power switch has been + fully tested:</member> + + <member>RPS-10 (model M/HD in the US, and model M/EC in + Europe) </member> + + <member>Latent support is provided for the following serial + attached power switch. This switch has not yet been fully + tested:</member> + + <member>APC Serial On/Off Switch (partAP9211), <ulink + url="http://www.apc.com/">http://www.apc.com/</ulink></member> + </simplelist></entry> + + <entry>Strongly recommended for data integrity under all failure + conditions</entry> + + </row> + </tbody> + </tgroup> +</table> + + + + <simplelist> 标记必须紧挨 <entry> 标记。如果不这样，就无法成功解析。 + 上面的示例看起来象这样： + + 不间断电源硬件 + + + + + + + + Hardware + Quantity + 描述 + Required + + + + + Serial power switches + Two + + Power switches enable each cluster system to power-cycle the other cluster system. Note that clusters are configured with either serial or network attached power switches and not both.The following serial attached power switch has been fully tested:RPS-10 (model M/HD in the US, and model M/EC in Europe)Latent support is provided for the following serial attached power switch. This switch has not yet been fully tested:APC Serial On/Off Switch (partAP9211), http://www.apc.com/ + + Strongly recommended for data integrity under all failure conditions + + + +
+ + + + + <command>trademark</command> + + + XML 标记 + + trademark + + + 不要使用商标实体 &trade;, &copy;, 或 &reg; 因为它们无法为所有字符集产生 HTML 输出。这些实体产生的 HTML 输出定义在 DTD 中，无法通过样式表改变。 + 应当使用 trademark 标记以及相关类别，如下所示： + + +<trademark>其后是商标符号</trademark> +<trademark class="registered">其后是注册商标符号</trademark> +<trademark class="copyright">其后是版权符号</trademark> + + + + + + <command>userinput</command> + + + XML 标记 + + userinput + + + 要显示用户将输入的内容，使用 userinput 标记。例如： + + +在提示符下，输入： + +<userinput>dd if=boot.img of=/dev/fd0 bs=1440k</userinput> + + + 输出： + 在提示符下，输入： + + dd if=boot.img of=/dev/fd0 bs=1440k + + + + + + <command>ulink</command> + + + XML 标记 + ulink + + 要在文本中创建 URL，如下： + + +在线 &mdash; <ulink url="http://www.redhat.com/support/errata/"> +http://www.redhat.com/support/errata/</ulink>; 提供可以在线阅读的更正，您也可以下载光盘镜像。 + + + 输出： + 在线 — http://www.redhat.com/support/errata/; 提供可以在线阅读的更正，您也可以下载光盘镜像。 + + 注意 + 如果 URL 不是以文件名结尾，必须以斜线结束 (/)，才是格式正确的 URL，例如 http://www.redhat.com/。 + + + + + <command>wordasword</command> + + + XML 标记 + wordasword + + <wordasword> 标记用来定义一个词只作为语法单位，不代表其他含义。 + 许多技术文档使用了有丰富意义的词汇。有时又需要用到不带技术意味的这个词。<wordasword> 标记这样的词，指示这个词应当简单地理解为一个词而不是其他东西。 + 使用这个标记不会帮助读者理解其中的意义差别；好文档应当做到这一点。实际上 <wordasword> 的价值在于全文搜索和索引工具可以用它来减少虚假结果。 + 例如： + + 要使用 <command>grep</command> 搜索单词 +<wordasword>linux</wordasword>，使用命令 +<command>grep linux</command>。 + + 输出： + 要使用 grep 搜索单词 linux，使用命令 grep linux。 + 这个例子中，"linux" 仅仅是一个单词。文档不是以 Linux 为主题，这个词也不为内容添加任何相关含义，可以替换为其他任何词。 + + + + <command>xref</command> + + + XML 标记 + xref + + 要引用手册中其他章节，使用 <xref> 标记。 + 它的输出是您向读者指引的章节的标题。例如： + + +关于主控文件，请参考 +<xref linkend="ch-tutorial"></xref> 和 <xref linkend="s1-tutorial-parent"></xref> + + + 输出： + 关于主控文件，请参考 和 。 + + diff --git a/documentation-guide-zh_CN.xml b/documentation-guide-zh_CN.xml new file mode 100644 index 0000000..aea70d3 --- /dev/null +++ b/documentation-guide-zh_CN.xml @@ -0,0 +1,46 @@ + + + +%FEDORA-ENTITIES-EN; + + + + + + + + + + + + + + + +]> + + + &FP; 文档撰写准则 + 版本 &VERSION; + + 2003,2004,2005 + &FORMAL-RHI; + Tammy Fox + Johnray Fuller + Sandra Moore + + + + Fox + Tammy + + + Fuller + Johnray + + + Moore + Sandra + + &LEGALNOTICE; &INTRODUCTION; &GETTINGFILES; &GUIDELINES; &EMACS; &EMACS-NXML; &VIM; &TAGS; &TUTORIAL; &STYLE; &CONVERTING; &CVS; &ACKNOWLEDGMENTS; -- cgit