translating_rule

翻译的注意点

1. 原文中的tag需要保留
   比如:

    <structfield>bgw_extra</structfield> can contain extra data to be passed
    to the background worker. ...
   

   应该翻译为:

    <structfield>bgw_extra</structfield>包含传递到后台工作者的额外数据。
   

   下面这样是不对的(少了<structfield>)

    bgw_extra包含传递到后台工作者的额外数据。
   

2. sgml文件中不要输入tab键，要用空格代替。

   在Linux下编译sgml时，如果有tab键会产生编译错误(Windows下的编译不会出错)。 很多文本编辑器支持自动将输入的tab变换成4个空格，建议设置一下。

3. 翻译后的sgml文件将英文原文作为注释保留，以便校对。 英文原文注释可通过自动注释添加工具添加和删除。

注释自动添加工具

添加注释

添加注释的用法如下，支持单个sgml文件注释添加和目录递归的批量注释添加

python3 tools\pgdoc_add_commet.py <输入sgml> <注释源sgml> <输出sgml>

为单个文件添加注释：

python3 tools\pgdoc_add_commet.py postgresql\doc\src\sgml\acronyms.sgml ..\postgresql-9.6.0\doc\src\sgml\acronyms.sgml ..\sgml_out\acronyms.sgml

为批量文件添加注释:

python3 tools\pgdoc_add_commet.py postgresql\doc\src\sgml ..\postgresql-9.6.0\doc\src\sgml ..\sgml_out

删除注释

删除注释的用法类似

python3 tools\pgdoc_del_commet.py <输入sgml> <输出sgml>

注释规则

注释自动添加工具遵照以下注释规则

1. 对sgml文件的以下tag整体添加注释

   • title
   • para
   • simpara
   • indexterm
   • term
   • titleabbrev
   • row
   • bookinfo
   • remark
   • programlisting
   • screen
   • literallayout
   • refmeta
   • refnamediv
   • indexentry
   • biblioentry
   • cmdsynopsis
   • synopsis

   以上tag如果出现了嵌套，只处理层级最高的tag

2. 将被注释的内容中--全部替换成-−

示例

添加注释后的示例如下:

<!--==========================orignal english content==========================
   <para>
    This part describes the use of the <acronym>SQL</acronym> language
    in <productname>PostgreSQL</productname>.  We start with
    describing the general syntax of <acronym>SQL</acronym>, then
    explain how to create the structures to hold data, how to populate
    the database, and how to query it.  The middle part lists the
    available data types and functions for use in
    <acronym>SQL</acronym> commands.  The rest treats several
    aspects that are important for tuning a database for optimal
    performance.
   </para>
____________________________________________________________________________-->
   <para>
    这部份描述在<productname>PostgreSQL</productname>中<acronym>SQL</acronym>语言的使用。
    我们从描述<acronym>SQL</acronym>的一般语法开始，然后解释如何创建保存数据的结构、
    如何填充数据库以及如何查询它。中间的部分列出了在<acronym>SQL</acronym>命令中可用的数据类型和函数。
    剩余的部分则留给对于调优数据性能的重要方面。
   </para>

TAG不匹配的处理

添加注释时，如果目标sgml和原始sgml的tag不匹配，pgdoc_add_commet.py会报错,比如:

[pgdoc@nodex ~]$ python3 ./gitrep/pgdoc-cn/tools/pgdoc_add_commet.py configxx.sgml /tmp/config.sgml config.sgml_new
config.sgml: skip for error:source sgml "config.sgml" and comment sgml "/tmp/config.sgml" does not match

可以通过比较目标和源的tag文件可以找到不匹配的tag

[pgdoc@i-yh5e8qjy ~]$ diff config.sgml.srctags config.sgml.commenttags
727c727
<                 varlistentry id="guc-min-parallel-table_scan-size" xreflabel="min_parallel_table_scan_size"
---
>                 varlistentry id="guc-min-parallel-table-scan-size" xreflabel="min_parallel_table_scan_size"

config.sgml.srctags中内容是sgml文件的tag结构，如果查看每个tag对应的行号可以参考config.sgml.srctags_detail