Open
Description
问题
个别sgml注释和译文离得很远,比如client-auth.sgml中下面的这段：
client-auth.sgml(当前):
<!--==========================orignal english content==========================
<para>
A record can have one of the seven formats
...(这里省掉几百行)
<varlistentry>
<term><replaceable>auth-options</replaceable></term>
<listitem>
<para>
After the <replaceable>auth-method</replaceable> field, there can be field(s) of
the form <replaceable>name</replaceable><literal>=</literal><replaceable>value</replaceable> that
specify options for the authentication method. Details about which
options are available for which authentication methods appear below.
</para>
<para>
In addition to the method-specific options listed below, there is one
method-independent authentication option <literal>clientcert</literal>, which
can be specified in any <literal>hostssl</literal> record. When set
to <literal>1</literal>, this option requires the client to present a valid
(trusted) SSL certificate, in addition to the other requirements of the
authentication method.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
____________________________________________________________________________-->
<para>
记录可以是下面七种格式之一：
...(这里省掉几百行)
<varlistentry>
<term><replaceable>auth-options</replaceable></term>
<listitem>
<para>
在<replaceable>auth-method</replaceable>域的后面，可以是形如<replaceable>name</replaceable><literal>=</literal><replaceable>value</replaceable>的域，它们指定认证方法的选项。关于哪些认证方法可以用哪些选项的细节请见下文。
</para>
<para>
除了下文列出的与方法相关的选项之外，还有一个与方法无关的认证选项<literal>clientcert</literal>，它可以在任何<literal>hostssl</literal>记录中指定。当被设置为<literal>1</literal>时，这个选项要求客户端在认证方法的其他要求之外出示一个有效的（可信的）SSL 证书。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
这不方便人工对比译文和原始译文。下面的形式更符合我们的预期
client-auth.sgml(期望):
<!--==========================orignal english content==========================
<para>
A record can have one of the seven formats
____________________________________________________________________________-->
<para>
记录可以是下面七种格式之一：
...
<varlistentry>
<term><replaceable>auth-options</replaceable></term>
<listitem>
<!--==========================orignal english content==========================
<para>
After the <replaceable>auth-method</replaceable> field, there can be field(s) of
the form <replaceable>name</replaceable><literal>=</literal><replaceable>value</replaceable> that
specify options for the authentication method. Details about which
options are available for which authentication methods appear below.
</para>
____________________________________________________________________________-->
<para>
在<replaceable>auth-method</replaceable>域的后面，可以是形如<replaceable>name</replaceable><literal>=</literal><replaceable>value</replaceable>的域，它们指定认证方法的选项。关于哪些认证方法可以用哪些选项的细节请见下文。
</para>
<!--==========================orignal english content==========================
<para>
In addition to the method-specific options listed below, there is one
method-independent authentication option <literal>clientcert</literal>, which
can be specified in any <literal>hostssl</literal> record. When set
to <literal>1</literal>, this option requires the client to present a valid
(trusted) SSL certificate, in addition to the other requirements of the
authentication method.
</para>
____________________________________________________________________________-->
<para>
除了下文列出的与方法相关的选项之外，还有一个与方法无关的认证选项<literal>clientcert</literal>，它可以在任何<literal>hostssl</literal>记录中指定。当被设置为<literal>1</literal>时，这个选项要求客户端在认证方法的其他要求之外出示一个有效的（可信的）SSL 证书。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
原因
目前很多英文原文注释是通过脚本自动加入的。脚本加注释有一个重要的原则，只对完整的tag加注释。client-auth.sgml之所以被这样加，是因为这个sgml里出现了嵌套的para，所以脚本只在最外层的para上加注释，只能怪这个最外层的para太长了，有200多行，所以看上去有点奇怪。
<para>
xxxx
<para>yyyy</para>
</para>
注释脚本处理规则请参考
https://github.com/postgres-cn/pgdoc-cn/wiki/translating_rule
处理建议
可以人工进行调整。但是不建议这么做，因为以后注释可能会被自动脚本重新覆盖掉。文档发布前计划用注释工具做一次全文档的注释删除再添加，目的主要是检查中文文档和英文原始文档在段落上是否一致，另外也可以避免人工添加的注释有遗漏。
另外一种解决办法是优化注释脚本，但是这个问题确实难以处理。而且，毕竟这种情况只是少数，所以暂时保留当前自动化注释脚本的风格。
Metadata
Metadata
Assignees
Labels
No labels