Skip to content

3.1 内核文档翻译指南

Jump to bottom
TurtleRuss edited this page Sep 29, 2024 · 3 revisions

建议大家基于 lwn.git 的 docs-next 分支开展补丁编写工作。

首先请阅读中文排版指北，内核的翻译要求的基础是建立在这上面的，这很重要！！！。

  1. 内核文档通常对中文翻译有如下要求：
    • 中文文档要求每行长度不超过40个中文字符，或者不超过80个英文字符，其中一个中文字符的长度=两个英文字符的长度，无论具体是多长，请尽量保持每行长度一样，要整整齐齐。

对于RST的标题来说，下划线的个数与标题长度也有一定的关系，比如一个标题用上面的长度转换规则转换后的英文字符长度为10，则下划线的个数也为10。如：

Debug 文件系统接口
~~~~~~~~~~~~~~~~~~
  • 在译文的开头记得声明证书以及包含中文免责声明，如下
.. SPDX-License-Identifier: GPL-2.0

.. include:: ../disclaimer-zh_CN.rst

  • 在进行长度上限导致的换行时，如下的情况不能进行换行

    • 字符截断在代码段中，比如下面这种情况

      接口的细粒度允许高效的创建测试进程。即，一个父进程打开了
``/sys/kernel/debug/kcov``

      单看长度上限不应该这样换行，但是由于/sys/kernel/debug/kcov/是一个完整的代码字符串，所以应当提前换行。

    • 完整的英文名词，比如下面这种情况

      "Kernel hacking" 中的
CONFIG_DEBUG_KMEMLEAK 必须被启用。

      但看长度上限不应该这样换行，但是由于 CONFIG_DEBUG_KMEMLEAK 是一个完整的英文名词，所以不应该被截断，所以应当提前换行。

  • 英文字符替换为中文字符，比如半角符号替换为全角符号。

  1. 请查阅 Documentation/doc-guide/sphinx.rst 来熟悉文档子系统的构建流程。

    运行如下命令，根据提示安装就行。

    ./scripts/sphinx-pre-install

  2. 发送补丁前，至少要做到解决所有的 error 和 warning，当前的文档主要以 html 渲染为主，请执行：

make cleandocs
# 如果可以确定之前的编译产生的 error 和 warning 与自己的文档无关，则可以不进行 clean，节省一些时间
make htmldocs

  1. 渲染后的文件在 Documentation/output，请用浏览器打开进行中英文排版比对，解决不一致的地方。

  2. 使用 ./scripts/checkpatch.pl *.patch 检查生成的补丁，同样解决掉报错。

  3. 检查完补丁并且消除错误后，使用如下命令先提交给[email protected]。

git send-email --to="[email protected]" /path/to/your/patch

待团队内部人员初审后，可以将修改后的 PATCH 发送给内核。

如果在内部审核中产生多个版本的 PATCH，向内核提交时需采用最终版并消除 PATCH前缀。

使用如下命令发送 PATCH 至内核：

git send-email \
   --to-cmd="$(pwd)/scripts/get_maintainer.pl --nogit --nogit-fallback --norolestats --nol" \
   --cc-cmd="$(pwd)/scripts/get_maintainer.pl --nogit --nogit-fallback --norolestats --nom" \
   --cc="[email protected]" \
   /path/to/your/patch

也可以使用我们的脚本submit2kernel.sh一键提交。

cd /path/to/your/translate_project
submit2kernel.sh /path/to/your/patch
Clone this wiki locally