[PATCH 2/2] zh_CN/coding-style: Add coding-style into docs build system
From: Andy Deng
Date: Tue Jan 24 2017 - 18:55:02 EST
Tested by the command:
make htmldocs
During the compiling process, some rendering issues were found and
fixed, most of which were due to Chinese characters leading to a syntax
failure, such as `` ``, ** **.
I have not tested to generate pdf format, but html documents have been
checked.
Signed-off-by: Andy Deng <theandy.deng@xxxxxxxxx>
---
Documentation/index.rst | 10 ++-
.../zh_CN/{CodingStyle => coding-style.rst} | 84 +++++++++++-----------
Documentation/translations/zh_CN/index.rst | 12 ++++
3 files changed, 64 insertions(+), 42 deletions(-)
rename Documentation/translations/zh_CN/{CodingStyle => coding-style.rst} (91%)
create mode 100644 Documentation/translations/zh_CN/index.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index cb5d776..f6e641a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -47,7 +47,7 @@ These books get into the details of how specific kernel subsystems work
from the point of view of a kernel developer. Much of the information here
is taken directly from the kernel source, with supplemental material added
as needed (or at least as we managed to add it — probably *not* all that is
-needed).
+needed).
.. toctree::
:maxdepth: 2
@@ -68,6 +68,14 @@ Korean translations
translations/ko_KR/index
+Chinese translations
+--------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ translations/zh_CN/index
+
Indices and tables
==================
diff --git a/Documentation/translations/zh_CN/CodingStyle b/Documentation/translations/zh_CN/coding-style.rst
similarity index 91%
rename from Documentation/translations/zh_CN/CodingStyle
rename to Documentation/translations/zh_CN/coding-style.rst
index 8e7ae2d..1466aa6 100644
--- a/Documentation/translations/zh_CN/CodingStyle
+++ b/Documentation/translations/zh_CN/coding-style.rst
@@ -8,6 +8,7 @@ translation is outdated or there is problem with translation.
Chinese maintainer: Zhang Le <r0bertz@xxxxxxxxxx>
---------------------------------------------------------------------
+
Documentation/process/coding-style.rst 的中文翻译
如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，
@@ -21,6 +22,7 @@ Documentation/process/coding-style.rst 的中文翻译
管旭东 Xudong Guan <xudong.guan@xxxxxxxxx>
Li Zefan <lizf@xxxxxxxxxxxxxx>
Wang Chen <wangchen@xxxxxxxxxxxxxx>
+
以下为正文
---------------------------------------------------------------------
@@ -221,13 +223,13 @@ Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关
s = sizeof(struct file);
-不要在小括号里的表达式两侧加空格。这是一个**反例**：
+不要在小括号里的表达式两侧加空格。这是一个 **反例** ：
.. code-block:: c
s = sizeof( struct file );
-当声明指针类型或者返回指针类型的函数时，``*`` 的首选使用方式是使之靠近变量名
+当声明指针类型或者返回指针类型的函数时， ``*`` 的首选使用方式是使之靠近变量名
或者函数名，而不是靠近类型名。例子：
.. code-block:: c
@@ -269,22 +271,22 @@ Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关
C 是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同，
C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会
-称那个变量为 ``tmp``，这样写起来会更容易，而且至少不会令其难于理解。
+称那个变量为 ``tmp`` ，这样写起来会更容易，而且至少不会令其难于理解。
不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的
名字。称一个全局函数为 ``foo`` 是一个难以饶恕的错误。
-全局变量 (只有当你**真正**需要它们的时候再用它) 需要有一个具描述性的名字，就
+全局变量 (只有当你 **真正** 需要它们的时候再用它) 需要有一个具描述性的名字，就
像全局函数。如果你有一个可以计算活动用户数量的函数，你应该叫它
-``count_active_users()`` 或者类似的名字，你不应该叫它 ``cntuser()``。
+``count_active_users()`` 或者类似的名字，你不应该叫它 ``cntuser()`` 。
在函数名中包含函数类型 (所谓的匈牙利命名法) 是脑子出了问题——编译器知道那些类
型而且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题
的程序。
本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计
-数器，它应该被称为 ``i``。叫它 ``loop_counter`` 并无益处，如果它没有被误解的
-可能的话。类似的，``tmp`` 可以用来称呼任意类型的临时变量。
+数器，它应该被称为 ``i`` 。叫它 ``loop_counter`` 并无益处，如果它没有被误解的
+可能的话。类似的， ``tmp`` 可以用来称呼任意类型的临时变量。
如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综
合症。请看第六章 (函数)。
@@ -295,7 +297,7 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字
不要使用类似 ``vps_t`` 之类的东西。
-对结构体和指针使用 typedef 是一个**错误**。当你在代码里看到：
+对结构体和指针使用 typedef 是一个 **错误** 。当你在代码里看到：
.. code-block:: c
@@ -311,34 +313,34 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字
你就知道 ``a`` 是什么了。
-很多人认为 typedef ``能提高可读性``。实际不是这样的。它们只在下列情况下有用：
+很多人认为 typedef ``能提高可读性`` 。实际不是这样的。它们只在下列情况下有用：
- (a) 完全不透明的对象 (这种情况下要主动使用 typedef 来**隐藏**这个对象实际上
+ (a) 完全不透明的对象 (这种情况下要主动使用 typedef 来 **隐藏** 这个对象实际上
是什么)。
- 例如：``pte_t`` 等不透明对象，你只能用合适的访问函数来访问它们。
+ 例如： ``pte_t`` 等不透明对象，你只能用合适的访问函数来访问它们。
- .. 注意::
+ .. note::
不透明性和 "访问函数" 本身是不好的。我们使用 pte_t 等类型的原因在于真
的是完全没有任何共用的可访问信息。
- (b) 清楚的整数类型，如此，这层抽象就可以**帮助**消除到底是 ``int`` 还是
+ (b) 清楚的整数类型，如此，这层抽象就可以 **帮助** 消除到底是 ``int`` 还是
``long`` 的混淆。
u8/u16/u32 是完全没有问题的 typedef，不过它们更符合类别 (d) 而不是这里。
- .. 再次注意::
+ .. note::
- 要这样做，必须事出有因。如果某个变量是 ``unsigned long``，那么没有必要
+ 要这样做，必须事出有因。如果某个变量是 ``unsigned long`` ，那么没有必要
typedef unsigned long myflags_t;
不过如果有一个明确的原因，比如它在某种情况下可能会是一个 ``unsigned int``
- 而在其他情况下可能为 ``unsigned long``，那么就不要犹豫，请务必使用
+ 而在其他情况下可能为 ``unsigned long`` ，那么就不要犹豫，请务必使用
typedef。
- (c) 当你使用 sparse 按字面的创建一个**新**类型来做类型检查的时候。
+ (c) 当你使用 sparse 按字面的创建一个 **新** 类型来做类型检查的时候。
(d) 和标准 C99 类型相同的类型，在某些例外的情况下。
@@ -357,8 +359,8 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字
``u32`` 类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似
的类型。
-可能还有其他的情况，不过基本的规则是**永远不要**使用 typedef，除非你可以明确
-的应用上述某个规则中的一个。
+可能还有其他的情况，不过基本的规则是 **永远不要** 使用 typedef，除非你可以明
+确的应用上述某个规则中的一个。
总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们
就不应该是一个 typedef。
@@ -409,7 +411,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
便了。如果并不需要清理操作，那么直接 return 即可。
选择一个能够说明 goto 行为或它为何存在的标签名。如果 goto 要释放 ``buffer``,
-一个不错的名字可以是 ``out_free_buffer:``。别去使用像 ``err1:`` 和 ``err2:``
+一个不错的名字可以是 ``out_free_buffer:`` 。别去使用像 ``err1:`` 和 ``err2:``
这样的GW_BASIC 名称，因为一旦你添加或删除了 (函数的) 退出路径，你就必须对它们
重新编号，这样会难以去检验正确性。
@@ -444,7 +446,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
return result;
}
-一个需要注意的常见错误是 ``一个 err 错误``，就像这样：
+一个需要注意的常见错误是 ``一个 err 错误`` ，就像这样：
.. code-block:: c
@@ -557,16 +559,16 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。
这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。
不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可
-以用 ``indent``。
+以用 ``indent`` 。
不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选
项。不过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性
(GNU 的人并不是坏人，他们只是在这个问题上被严重的误导了)，所以你只要给 indent
-指定选项 ``-kr -i8`` (代表 ``K&R，8 字符缩进``)，或使用 ``scripts/Lindent``，
+指定选项 ``-kr -i8`` (代表 ``K&R，8 字符缩进``)，或使用 ``scripts/Lindent``
这样就可以以最时髦的方式缩进源代码。
``indent`` 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册。
-不过记住：``indent`` 不能修正坏的编程习惯。
+不过记住： ``indent`` 不能修正坏的编程习惯。
10) Kconfig 配置文件
@@ -607,14 +609,14 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。
担心这个数据结构仅仅因为暂时不被使用就消失了，那些用户可能不过是沉睡了一阵或
者做了一些其他事情而已。
-注意上锁**不能**取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一
+注意上锁 **不能** 取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一
个内存管理技巧。通常二者都需要，不要把两个搞混了。
很多数据结构实际上有 2 级引用计数，它们通常有不同 ``类`` 的用户。子类计数器统
计子类用户的数量，每当子类计数器减至零时，全局计数器减一。
-这种 ``多级引用计数`` 的例子可以在内存管理 (``struct mm_struct``：mm_users 和
-mm_count)，和文件系统 (``struct super_block``：s_count 和 s_active) 中找到。
+这种 ``多级引用计数`` 的例子可以在内存管理 (``struct mm_struct``: mm_users 和
+mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中找到。
记住：如果另一个执行线索可以找到你的数据结构，但这个数据结构没有引用计数器，
这里几乎肯定是一个 bug。
@@ -657,8 +659,8 @@ mm_count)，和文件系统 (``struct super_block``：s_count 和 s_active) 中
return -EBUGGERED; \
} while (0)
- **非常**不好。它看起来像一个函数，不过却能导致 ``调用`` 它的函数退出；不要
- 打乱读者大脑里的语法分析器。
+**非常** 不好。它看起来像一个函数，不过却能导致 ``调用`` 它的函数退出；不要打
+乱读者大脑里的语法分析器。
2) 依赖于一个固定名字的本地变量的宏：
@@ -666,8 +668,8 @@ mm_count)，和文件系统 (``struct super_block``：s_count 和 s_active) 中
#define FOO(val) bar(index, val)
- 可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致
- 看起来不相关的改动带来错误。
+可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起
+来不相关的改动带来错误。
3) 作为左值的带参数的宏： FOO(x) = y；如果有人把 FOO 变成一个内联函数的话，这
种用法就会出错了。
@@ -691,7 +693,7 @@ mm_count)，和文件系统 (``struct super_block``：s_count 和 s_active) 中
(ret); \
})
- ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。
+ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。
cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL，内核里的汇编语
言经常用到它。
@@ -701,7 +703,7 @@ cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL
------------------------------
内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。
-不要用不规范的单词比如 ``dont``，而要用 ``do not`` 或者 ``don't``。保证这些信
+不要用不规范的单词比如 ``dont``，而要用 ``do not`` 或者 ``don't`` 。保证这些信
息简单明了,无歧义。
内核信息不必以英文句号结束。
@@ -762,9 +764,9 @@ kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。
15) 内联弊病
------------------------------
-有一个常见的误解是``内联``是 gcc 提供的可以让代码运行更快的一个选项。虽然使用
-内联函数有时候是恰当的 (比如作为一种替代宏的方式，请看第十二章)，不过很多情况
-下不是这样。inline 关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。
+有一个常见的误解是 ``内联`` 是 gcc 提供的可以让代码运行更快的一个选项。虽然使
+用内联函数有时候是恰当的 (比如作为一种替代宏的方式，请看第十二章)，不过很多情
+况下不是这样。inline 的过度使用会使内核变大，从而使整个系统运行速度变慢。
因为体积大内核会占用更多的指令高速缓存，而且会导致 pagecache 的可用内存减少。
想象一下，一次 pagecache 未命中就会导致一次磁盘寻址，将耗时 5 毫秒。5 毫秒的
时间内 CPU 能执行很多很多指令。
@@ -783,8 +785,8 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除
16) 函数返回值及命名
------------------------------
-函数可以返回很多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。
-这样的一个值可以表示为一个错误代码整数 (-Exxx＝失败，0＝成功) 或者一个``成功``
+函数可以返回多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样
+的一个值可以表示为一个错误代码整数 (-Exxx＝失败，0＝成功) 或者一个 ``成功``
布尔值 (0＝失败，非0＝成功)。
混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和
@@ -794,7 +796,7 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除
如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代
码整数。如果是一个判断，那么函数应该返回一个 "成功" 布尔值。
-比如，``add work`` 是一个命令，所以 add_work() 在成功时返回 0，在失败时返回
+比如， ``add work`` 是一个命令，所以 add_work() 在成功时返回 0，在失败时返回
-EBUSY。类似的，因为 ``PCI device present`` 是一个判断，所以 pci_dev_present()
在成功找到一个匹配的设备时应该返回 1，如果找不到时应该返回 0。
@@ -828,7 +830,7 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除
18) 编辑器模式行和其他需要罗嗦的事情
-------------------------------
+--------------------------------------------------
有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs
能够解释被标记成这样的行：
@@ -869,7 +871,7 @@ Vim 能够解释这样的标记：
地写下只有细微差异内联汇编。记住内联汇编可以使用 C 参数。
大型，有一定复杂度的汇编函数应该放在 .S 文件内，用相应的 C 原型定义在 C 头文
-件中。汇编函数的 C 原型应该使用 ``asmlinkage``。
+件中。汇编函数的 C 原型应该使用 ``asmlinkage`` 。
你可能需要把汇编语句标记为 volatile，用来阻止 GCC 在没发现任何副作用后就把它
移除了。你不必总是这样做，尽管，这不必要的举动会限制优化。
diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
new file mode 100644
index 0000000..75956d6
--- /dev/null
+++ b/Documentation/translations/zh_CN/index.rst
@@ -0,0 +1,12 @@
+.. raw:: latex
+
+ \renewcommand\thesection*
+ \renewcommand\thesubsection*
+
+Chinese translations
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ coding-style
--
2.9.3