From 924d927aed2a3f96f63c7a7fe3fd82e82693f7d2 Mon Sep 17 00:00:00 2001 From: Yuan Yijun Date: Sat, 17 Dec 2005 13:28:38 +0000 Subject: update build part --- acknowledgments-zh_CN.xml | 1 + docs-emacs-zh_CN.xml | 2 +- docs-getting-files-zh_CN.xml | 308 +++++++++++++++++++++++++++++++++++++----- docs-intro-zh_CN.xml | 2 +- docs-rh-guidelines-zh_CN.xml | 2 +- docs-tutorial-zh_CN.xml | 2 +- docs-vim-zh_CN.xml | 2 +- docs-xml-tags-zh_CN.xml | 4 +- documentation-guide-zh_CN.xml | 6 +- 9 files changed, 283 insertions(+), 46 deletions(-) diff --git a/acknowledgments-zh_CN.xml b/acknowledgments-zh_CN.xml index db0c7bc..11770bd 100644 --- a/acknowledgments-zh_CN.xml +++ b/acknowledgments-zh_CN.xml @@ -7,4 +7,5 @@ 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 标记集合添加更多解释。 + 合并了 Tommy Reynolds (Tommy.Reynolds at MegaCoder.com) 的补丁，详细解释文档构建系统。 diff --git a/docs-emacs-zh_CN.xml b/docs-emacs-zh_CN.xml index 3320e48..67886e2 100644 --- a/docs-emacs-zh_CN.xml +++ b/docs-emacs-zh_CN.xml @@ -1,5 +1,5 @@ - + Emacs 与 PSGML 模式 PSGML diff --git a/docs-getting-files-zh_CN.xml b/docs-getting-files-zh_CN.xml index 8f2823e..7b0304f 100644 --- a/docs-getting-files-zh_CN.xml +++ b/docs-getting-files-zh_CN.xml @@ -1,46 +1,286 @@ - 下载文件 - 要开始为 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 + 先决要求 + 在操作 &FED; 文档之前，您必须安装合适的工具和软件包。下面的步骤将帮您配置系统。 +
+ 系统软件包 + 要开始为 Docs Project 贡献力量，您需要适当的 DocBook XML 文件，样式表以及一些脚本。需要安装下列软件包： + + + + xmlto — 生成 HTML 和 PDF 输出。 + + + + docbook-style-xsl — 我们构建时默认的 XSLT 样式单。 + + + + docbook-dtds — DocBook DTD 针对 XML 的版本 + + + 您可以这样检查系统中的软件包，运行命令： + + +rpm -q xmlto +rpm -q docbook-style-xsl +rpm -q docbook-dtds + + + 如果缺少什么软件包，就用 yum(8) 来安装： + + +su -c 'yum install xmlto' +su -c 'yum install docbook-style-xsl' +su -c 'yum install docbook-dtds' + + +
+
+ Fedora 文档工具 + 您只需执行这些步骤一次。这些文件对所有 &FDPX; 文档都是一致的。 + 常用的脚本和样式表都存放在 cvs.fedora.redhat.com CVS 服务器的仓库中。您需要将它们以及已有文档的 DocBook XML 文件检出。 + 当您看到密码提示时，按下 Enter 键。在下面的例子中，我们演示了如何获取一份已有的 &FDPX; 文档的复本。 + + mkdir my-fedora-docs-sandbox +cd my-fedora-docs-sandbox 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 文件。 + +
+
+ 文件名约定 + &FDPX; 提供了工具、脚本和样式单来将您的 XML 文档转换为 HTML 和 PDF 输出格式。另外，您的文档还可以被自动构建为 RPM 软件包。 + 要利用这些服务，您应当遵循为文件命名的规范。无论选择什么名字，采用我们的建议将使事情简单许多。当然，如果您将自己的文档导入我们的构建系统，修改数以百计的文件名字也许过于繁杂；请放松，只要稍作修改就可以满足要求了。请继续阅读。 +
+ 文档文件名 + 每个文档有单独的目录，与先前从 &FED; 文档中检出的 docs-common 目录并列。将您的文档目录命名为与内容相关的名字，避免使用已有的名称。前面提到的 cvs co -c 命令可以显示已有的名称。 +
+
+ 与 I18N 国际化翻译组合作 + &FDPX; 包括一支活跃的翻译团队。项目文档被译为多种语言。根据约定，译文与原始文档处于同一目录；文件名必须唯一。 + &FDPX; 文件名的扩展名前面，必须是一个连字符加上 ISO 语言名称。例如，如果文件内容是 US(美国英语)，可以命名为 mydoc-en.xml；而它的简体中文译文将命名为 mydoc-zh_CN.xml，以此类推。 + 为了促进这种努力，文档构建系统假定每个文件都包含了 I18N 国际化语言环境标记。我们的文件名约定在 中讲述 + + &FDPX; 文件名约定 + + + + + + + 组件 + + + 描述 + + + + + + + + 除连字符外的其他字符 + + + + 文件名的第一部分可以是各种字符，只要不使用连字符(dash)。 + + + + + + - + + + + 连字符 (-) 用来引入 ${LANG} 文件名组件。 + + + + + + ${LANG} + + + + + ${LANG} 组件区分了文件内容的 locale(语言环境)。 + 除了根据语言区分文件外，我们还用 ${LANG} 的值作为输出文档时的 UTF-8 语言环境。例如，文档 mydoc-it.xml 在渲染时会使用 it.UTF-8 作为语言环境。 + 有关更多 I18N 本地化的信息请访问 网站。 + + + + +
+ + 文档文件名是特别的 + 文档的主控文件 必须 依据文件命名约定，否则构建系统无法找到它。 + +
+
+
+ 文档构建系统 + 一般的工作，类似将文档渲染为 HTML 或 PDF 可以很容易地用文档构建系统实现。 + 构建系统依赖于 make(1) 工具和 shell 脚本的强大功能，来自动完成这些工作。但是，作为作者，无须 有使用 shell 脚本或 Makefile 的经验。尽管每篇文档都拥有自己的 Makefile，它通常只有几行的长度，非常简单。文件 Makefile 的内容被设计为可以拷贝 'n 粘贴。 + 例如， 显示了一个简单文档(只有一个文件，且只有一种语言)的完整 Makefile。 + + 示例文档 Makefile(编译控制文件) + +DOCBASE = mydoc +LANGUAGES = en +XMLEXTRAFILES-en= +include ../docs-common/Makefile.common + + + 我们的主控 XML 文件是 mydoc-en.xml；尚未添加翻译。 + + LANGUAGES 定义列出了英语的语言环境 en；如果出现了其他翻译，只要将它们的语言环境追加在这个定义中。 + 这份文档只包括主控文件 mydoc-en.xml，但是其他文档也许被划分为多个文件。 XMLEXTRAFILES-en 定义可以记录附加文件，这样在文件被改动时，构建系统就会注意到，并且在需要的时候重新构建文档。这个定义只是简单的文件列表。 + 最后一行，以 include(包含)开始，引用了主控的构建系统的 Makefile。Makefile.common 文件包含了所有 make(1) 目标以及规则，用来实际地构建文档以及各种文件。 + 添加新的文档翻译： + + + 将已翻译的文件添加到文档目录。一定要用正确的 ${LANG} 文件名组件，使文件名相似而唯一。 + + + 编辑 Makefile，追加新的 ${LANG} 到 LANGUAGES 定义中。 + + + 创建新的 XMLEXTRAFILES-${LANG} 定义，以引用除了主控文件之外的所有其他受影响的文档文件。 + + +
+ 构建系统动作 + 要将 XML 文旦渲染为 HTML 或 PDF，运行命令： make html, make html-nochunk, 或 make pdf。 + + 列出了已定义的构建系统目标。 + + 文档构建目标 + + + + + + + 目标 + + + 描述 + + + + + + + + all + + + + 构建 HTML, 和 PDF 格式的文档，包括所有的译本。 + 同时构建打包，包括 tar(1) 和 rpm(8)。 + + + + + + tarball + + + + 只构建 tar(1) 打包，针对所有文档语言。 + + + + + + pdf + + + + 只构建 PDF 文档，针对所有文档语言。 + 当前，PDF 生成还有问题，可能无法使用。 + + + + + + html + + + + 只构建 HTML 文档，针对每种翻译。输出被放在单独的目录中：${DOCBASE}-${LANG}/；每一节在那个目录中都有对应的文件。 + + + + + + html-nochunks + + + + 只构建 HTML 文档，针对每种翻译。输出是一个单独的文件：${DOCBASE}-${LANG}.html；不会创建其他文件。 + + + + + + clean + + + + 删除所有临时文件和生成的文件。不会 删除任何 HTML, PDF, 或文件打包。 + + + + + + distclean + + + + 删除所有 HTML, PDF, 和文件打包。同时自动执行 clean 目标。 + + + + +
+ 您可以添加自己特定的目标和规则，只要将它们添加在文件 Makefile 的最后，在 include 一行的下面。 + 在您的目标定义后面一定要用双冒号，不能只用一个。这样，您就可以为已定义的目标添加步骤了。 +
+
+ 使用文档图象文件 + 图象文件，例如 .PNG，通常会在文档中用到。尽管文档可以存放在任何地方，我们建议您将图象文件存放在文档目录的 figs/ 子目录中。换句话说，图象 picture.png 应该是 mydoc/figs/picture.png 文件。 + + 使用 PNG 图象，不要用 JPG + 根据输出媒介不同，有时图象会被缩放，拉伸或压缩。为了减少变形，我们建议您只使用 PNG 图象，避免 JPG 文件。 + 您会发现 convert(1) 程序，来自 ImageMagickRPM 软件包，提供了转换已有的 JPG 文件的好办法。 + + 您可以将图象文件组织为 figs/ 目录下的子目录。文档构建系统会在输出文档中复制图象子目录的结构。 + 另外，我们建议您遵循文件名命名的约定。例如，一幅图象经常会包含标题或其他文本。这些文本应当像文档内容一样被翻译，因此区分 words-en.png 与 words-ru.png 是个好主意。不包含文本的图象文件可以简单地命名为 picture.png 之类。 + 有时，文档需要使用不遵循命名约定的图象。您可以在文档构建系统中使用这些图象，但是您必须创建一个文本文件，列出要使用的图象文件名。这个文件必须命名为 figs/Manifest-${LANG}，这样构建系统就可以在搜索图象文件名时找到它。 + 创建 figs/Manifest-${LANG} 文件的简单办法是 。 + + 构建一份清单(Manifest) + +rm -f figs/Manifest-en +find figs -print >/tmp/manifest +mv /tmp/manifest figs/Manifest-en +vi figs/Manifest-en + + +
+
diff --git a/docs-intro-zh_CN.xml b/docs-intro-zh_CN.xml index 792f8a5..01733e7 100644 --- a/docs-intro-zh_CN.xml +++ b/docs-intro-zh_CN.xml @@ -1,5 +1,5 @@ - + 介绍 Docs Project 的目标是为 &FC; 用户和开发者创建易于维护，基于任务的文档。除了 &IG; 之外，所有文档必须是 DocBook XML article 格式，每个主题一篇文章。这样，作者就可以专注于撰写一个主题，不必考虑它如何排版为一个手册，或如何与其他主题协调。 要用到的工具： diff --git a/docs-rh-guidelines-zh_CN.xml b/docs-rh-guidelines-zh_CN.xml index 0ead30c..7615ed2 100644 --- a/docs-rh-guidelines-zh_CN.xml +++ b/docs-rh-guidelines-zh_CN.xml @@ -181,7 +181,7 @@ 它被提交到 CVS 中时 (在每次提交时)，这一行都会自动更新，以包含关于文件的信息。例如： -<!-- $Id: docs-rh-guidelines-zh_CN.xml,v 1.1 2005/12/09 15:28:54 bbbush Exp $ --> +<!-- $Id: --> diff --git a/docs-tutorial-zh_CN.xml b/docs-tutorial-zh_CN.xml index 28af5dd..6a7e494 100644 --- a/docs-tutorial-zh_CN.xml +++ b/docs-tutorial-zh_CN.xml @@ -1,5 +1,5 @@ - + 文档的布局 在本章您将看到 &PROJECT; 文档中，主控文件的示例。这个示例与 Docs Project 处理 DocBook XML 的方式相关。主控文件包含文档的主要结构，以及到定义公共实体的文件的链接，还包括定义文档版本和日期的实体。 diff --git a/docs-vim-zh_CN.xml b/docs-vim-zh_CN.xml index aea10db..a33623f 100644 --- a/docs-vim-zh_CN.xml +++ b/docs-vim-zh_CN.xml @@ -1,5 +1,5 @@ - + VIM 与 DocBook VIM diff --git a/docs-xml-tags-zh_CN.xml b/docs-xml-tags-zh_CN.xml index 7cc752d..f8029f8 100644 --- a/docs-xml-tags-zh_CN.xml +++ b/docs-xml-tags-zh_CN.xml @@ -1,5 +1,5 @@ - + DocBook XML 标记 XML @@ -119,8 +119,6 @@ 一篇 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> diff --git a/documentation-guide-zh_CN.xml b/documentation-guide-zh_CN.xml index aea70d3..1a29334 100644 --- a/documentation-guide-zh_CN.xml +++ b/documentation-guide-zh_CN.xml @@ -1,9 +1,8 @@ - + %FEDORA-ENTITIES-EN; - @@ -14,7 +13,6 @@ - @@ -43,4 +41,4 @@ Moore Sandra - &LEGALNOTICE; &INTRODUCTION; &GETTINGFILES; &GUIDELINES; &EMACS; &EMACS-NXML; &VIM; &TAGS; &TUTORIAL; &STYLE; &CONVERTING; &CVS; &ACKNOWLEDGMENTS; + &LEGALNOTICE; &INTRODUCTION; &GETTINGFILES; &GUIDELINES; &EMACS; &EMACS-NXML; &VIM; &TAGS; &TUTORIAL; &STYLE; &CVS; &ACKNOWLEDGMENTS; -- cgit