This is a Chinese translated version of Documentation/HOWTO. Currently
Chinese involvement in Linux kernel is very low, especially comparing to
its largest population base. Language could be the main obstacle. Hope
this document will help more Chinese to contribute to Linux kernel.
Signed-off-by: Li Yang <[email protected]>
Signed-off-by: TripleX Chung <[email protected]>
Signed-off-by: Maggie Chen <[email protected]>
---
Address comments from Wang Cong.
Documentation/zh_CN/HOWTO | 536 +++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 536 insertions(+), 0 deletions(-)
create mode 100644 Documentation/zh_CN/HOWTO
diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO
new file mode 100644
index 0000000..c70debd
--- /dev/null
+++ b/Documentation/zh_CN/HOWTO
@@ -0,0 +1,536 @@
+Chinese translated version of Documentation/HOWTO
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly. However, if you have problem
+communicating in English you can also ask the Chinese maintainer for
+help. Contact the Chinese maintainer, if this translation is outdated
+or there is problem with translation.
+
+Maintainer: Greg Kroah-Hartman <[email protected]>
+Chinese maintainer: Li Yang <[email protected]>
+---------------------------------------------------------------------
+Documentation/HOWTO 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Greg Kroah-Hartman <[email protected]>
+中文版维护者： 李阳 Li Yang <[email protected]>
+中文版翻译者： 李阳 Li Yang <[email protected]>
+中文版校译者： 钟宇 TripleX Chung <[email protected]>
+ 陈琦 Maggie Chen <[email protected]>
+ 王聪 Wang Cong <[email protected]>
+
+以下为正文
+---------------------------------------------------------------------
+
+如何参与Linux内核开发
+---------------------
+
+这是一篇将如何参与Linux内核开发的相关问题一网打尽的终极秘笈。它将指导你
+成为一名Linux内核开发者，并且学会如何同Linux内核开发社区合作。它尽可能不
+包括任何关于内核编程的技术细节，但会给你指引一条获得这些知识的正确途径。
+
+如果这篇文章中的任何内容不再适用，请给文末列出的文件维护者发送补丁。
+
+
+入门
+----
+
+你想了解如何成为一名Linux内核开发者？或者老板吩咐你“给这个设备写个Linux
+驱动程序”？这篇文章的目的就是教会你达成这些目标的全部诀窍，它将描述你需
+要经过的流程以及给出如何同内核社区合作的一些提示。它还将试图解释内核社区
+为何这样运作。
+
+Linux内核大部分是由C语言写成的，一些体系结构相关的代码用到了汇编语言。要
+参与内核开发，你必须精通C语言。除非你想为某个架构开发底层代码，否则你并
+不需要了解（任何体系结构的）汇编语言。下面列举的书籍虽然不能替代扎实的C
+语言教育和多年的开发经验，但如果需要的话，做为参考还是不错的：
+ - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
+ 《C程序设计语言（第2版·新版）》（徐宝文 李志 译）[机械工业出版社]
+ - "Practical C Programming" by Steve Oualline [O'Reilly]
+ 《实用C语言编程（第三版）》（郭大海 译）[中国电力出版社]
+ - "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
+ 《C语言参考手册（原书第5版）》（邱仲潘 等译）[机械工业出版社]
+
+Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C89标准，但也用到了一些
+标准中没有定义的扩展。内核是自给自足的C环境，不依赖于标准C库的支持，所以
+并不支持C标准中的部分定义。比如long long类型的大数除法和浮点运算就不允许
+使用。有时候确实很难弄清楚内核对工具链的要求和它所使用的扩展，不幸的是目
+前还没有明确的参考资料可以解释它们。请查阅gcc信息页（使用“info gcc”命令
+显示）获得一些这方面信息。
+
+请记住你是在学习怎么和已经存在的开发社区打交道。它由一群形形色色的人组成，
+他们对代码、风格和过程有着很高的标准。这些标准是在长期实践中总结出来的，
+适应于地理上分散的大型开发团队。它们已经被很好得整理成档，建议你在开发
+之前尽可能多的学习这些标准，而不要期望别人来适应你或者你公司的行为方式。
+
+
+法律问题
+--------
+
+Linux内核源代码都是在GPL（通用公共许可证）的保护下发布的。要了解这种许可
+的细节请查看源代码主目录下的COPYING文件。如果你对它还有更深入问题请联系
+律师，而不要在Linux内核邮件组上提问。因为邮件组里的人并不是律师，不要期
+望他们的话有法律效力。
+
+对于GPL的常见问题和解答，请访问以下链接：
+ http://www.gnu.org/licenses/gpl-faq.html
+
+
+文档
+----
+
+Linux内核代码中包含有大量的文档。这些文档对于学习如何与内核社区互动有着
+不可估量的价值。当一个新的功能被加入内核，最好把解释如何使用这个功能的文
+档也放进内核。当内核的改动导致面向用户空间的接口发生变化时，最好将相关信
+息或手册页(manpages)的补丁发到[email protected]，以向手册页(manpages)
+的维护者解释这些变化。
+
+以下是内核代码中需要阅读的文档：
+ README
+ 文件简要介绍了Linux内核的背景，并且描述了如何配置和编译内核。内核的
+ 新用户应该从这里开始。
+
+ Documentation/Changes
+ 文件给出了用来编译和使用内核所需要的最小软件包列表。
+
+ Documentation/CodingStyle
+ 描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规
+ 范。大多数维护者只会接收符合规定的补丁，很多人也只会帮忙检查符合风格
+ 的代码。
+
+ Documentation/SubmittingPatches
+ Documentation/SubmittingDrivers
+ 这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)：
+ - 邮件内容
+ - 邮件格式
+ - 选择收件人
+ 遵守这些规定并不能保证提交成功（因为所有补丁需要通过严格的内容和风格
+ 审查），但是忽视他们几乎就意味着失败。
+
+ 其他关于如何正确地生成补丁的优秀文档包括：
+ "The Perfect Patch"
+ http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
+ "Linux kernel patch submission format"
+ http://linux.yyz.us/patch-format.html
+
+ Documentation/stable_api_nonsense.txt
+ 论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特
+ 性：
+ - 子系统中间层（为了兼容性？）
+ - 在不同操作系统间易于移植的驱动程序
+ - 减缓（甚至阻止）内核代码的快速变化
+ 这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系
+ 统转移到Linux的人来说也很重要。
+
+ Documentation/SecurityBugs
+ 如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来
+ 提醒其他内核开发者并帮助解决这个问题。
+
+ Documentation/ManagementStyle
+ 描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发（或者对
+ 它感到好奇）的人来说很重要，因为它解释了很多对于内核维护者独特行为的
+ 普遍误解与迷惑。
+
+ Documentation/stable_kernel_rules.txt
+ 解释了稳定版内核发布的规则，以及如何将改动放入这些版本的步骤。
+
+ Documentation/kernel-docs.txt
+ 有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找
+ 的内容，可以查看这些文档。
+
+ Documentation/applying-patches.txt
+ 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍
+
+内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何
+妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内
+核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册
+页等不同格式的文档：
+ make pdfdocs
+ make psdocs
+ make htmldocs
+ make mandocs
+
+
+如何成为内核开发者
+------------------
+如果你对Linux内核开发一无所知，你应该访问“Linux内核新手”计划：
+ http://kernelnewbies.org
+它拥有一个可以问各种最基本的内核开发问题的邮件列表（在提问之前一定要记得
+查找已往的邮件，确认是否有人已经回答过相同的问题）。它还拥有一个可以获得
+实时反馈的IRC聊天频道，以及大量对于学习Linux内核开发相当有帮助的文档。
+
+网站简要介绍了源代码组织结构、子系统划分以及目前正在进行的项目（包括内核
+中的和单独维护的）。它还提供了一些基本的帮助信息，比如如何编译内核和打补
+丁。
+
+如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问
+“Linux内核房管员”计划：
+ http://janitor.kernelnewbies.org/
+这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新
+整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁
+集成进内核的基本原理。如果还没有决定下一步要做什么的话，你还可能会得到方
+向性的指点。
+
+如果你已经有一些现成的代码想要放到内核中，但是需要一些帮助来使它们拥有正
+确的格式。请访问“内核导师”计划。这个计划就是用来帮助你完成这个目标的。它
+是一个邮件列表，地址如下：
+ http://selenic.com/mailman/listinfo/kernel-mentors
+
+在真正动手修改内核代码之前，理解要修改的代码如何运作是必需的。要达到这个
+目的，没什么办法比直接读代码更有效了（大多数花招都会有相应的注释），而且
+一些特制的工具还可以提供帮助。例如，“Linux代码交叉引用”项目就是一个值得
+特别推荐的帮助工具，它将源代码显示在有编目和索引的网页上。其中一个更新及
+时的内核源码库，可以通过以下地址访问：
+ http://sosdg.org/~coywolf/lxr/
+
+
+开发流程
+--------
+
+目前Linux内核开发流程包括几个“主内核分支”和很多子系统相关的内核分支。这
+些分支包括：
+ - 2.6.x主内核源码树
+ - 2.6.x.y -stable内核源码树
+ - 2.6.x -git内核补丁集
+ - 2.6.x -mm内核补丁集
+ - 子系统相关的内核源码树和补丁集
+
+
+2.6.x内核主源码树
+-----------------
+2.6.x内核是由Linus Torvalds（Linux的创造者）亲自维护的。你可以在
+kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循以下步
+骤：
+ - 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里
+ 维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个
+ 星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具
+ ，更多的信息可以在http://git.or.cz/获取），不过使用普通补丁也是可以
+ 的。
+ - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的
+ 新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有
+ 可能在-rc1后被接受是因为这样的修改完全独立，不会影响其他的代码，所以
+ 没有造成内核退步的风险。在-rc1以后也可以用git向Linus提交补丁，不过所
+ 有的补丁需要同时被发送到相应的公众邮件列表以征询意见。
+ - 当Linus认为当前的git源码树已经达到一个合理健全的状态足以发布供人测试
+ 时，一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。
+ - 这个过程一直持续下去直到内核被认为达到足够稳定的状态，持续时间大概是
+ 6个星期。
+
+关于内核发布，值得一提的是Andrew Morton在linux-kernel邮件列表中如是说：
+ “没有人知道新内核何时会被发布，因为发布是根据已知bug的情况来决定
+ 的，而不是根据一个事先制定好的时间表。”
+
+
+2.6.x.y -stable（稳定版）内核源码树
+-----------------------------------
+由4个数字组成的内核版本号说明此内核是-stable版本。它们包含基于2.6.x版本
+内核的相对较小且至关重要的修补，这些修补针对安全性问题或者严重的内核退步。
+
+这种版本的内核适用于那些期望获得最新的稳定版内核并且不想参与测试开发版或
+者实验版的用户。
+
+如果没有2.6.x.y版本内核存在，那么最新的2.6.x版本内核就相当于是当前的稳定
+版内核。
+
+2.6.x.y版本由“稳定版”小组（邮件地址<[email protected]>）维护，一般隔周发
+布新版本。
+
+内核源码中的Documentation/stable_kernel_rules.txt文件具体描述了可被稳定
+版内核接受的修改类型以及发布的流程。
+
+
+2.6.x -git补丁集
+----------------
+Linus的内核源码树的每日快照，这个源码树是由git工具管理的（由此得名）。这
+些补丁通常每天更新以反映Linus的源码树的最新状态。它们比-rc版本的内核源码
+树更具试验性质，因为这个补丁集是全自动生成的，没有任何人来确认其是否真正
+健全。
+
+
+2.6.x -mm补丁集
+---------------
+这是由Andrew Morton维护的试验性内核补丁集。Andrew将所有子系统的内核源码
+和补丁拼凑到一起，并且加入了大量从linux-kernel邮件列表中采集的补丁。这个
+源码树是新功能和补丁的试炼场。当补丁在-mm补丁集里证明了其价值以后Andrew
+或者相应子系统的维护者会将补丁发给Linus以便集成进主内核源码树。
+
+在将所有新补丁发给Linus以集成到主内核源码树之前，我们非常鼓励先把这些补
+丁放在-mm版内核源码树中进行测试。
+
+这些内核版本不适合在需要稳定运行的系统上运行，因为运行它们比运行任何其他
+内核分支都更具有风险。
+
+如果你想为内核开发进程提供帮助，请尝试并使用这些内核版本，并在
+linux-kernel邮件列表中提供反馈，告诉大家你遇到了问题还是一切正常。
+
+通常-mm版补丁集不光包括这些额外的试验性补丁，还包括发布时-git版主源码树
+中的改动。
+
+-mm版内核没有固定的发布周期，但是通常在每两个-rc版内核发布之间都会有若干
+个-mm版内核发布（一般是1至3个）。
+
+
+子系统相关内核源码树和补丁集
+----------------------------
+相当一部分内核子系统开发者会公开他们自己的开发源码树，以便其他人能了解内
+核的不同领域正在发生的事情。如上所述，这些源码树会被集成到-mm版本内核中。
+
+下面是目前可用的一些内核源码树的列表：
+ 通过git管理的源码树：
+ - Kbuild开发源码树， Sam Ravnborg <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git
+
+ - ACPI开发源码树, Len Brown <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git
+
+ - 块设备开发源码树, Jens Axboe <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git
+
+ - DRM开发源码树, Dave Airlie <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git
+
+ - ia64开发源码树, Tony Luck <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
+
+ - ieee1394开发源码树, Jody McIntyre <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git
+
+ - infiniband开发源码树, Roland Dreier <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git
+
+ - libata开发源码树, Jeff Garzik <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git
+
+ - 网络驱动程序开发源码树, Jeff Garzik <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git
+
+ - pcmcia开发源码树, Dominik Brodowski <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git
+
+ - SCSI开发源码树, James Bottomley <[email protected]>
+ kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git
+
+ 其他git管理的内核源码树可以在http://kernel.org/git的列表中找到
+
+ 使用quilt管理的补丁集：
+ - USB, PCI, 驱动程序核心和I2C, Greg Kroah-Hartman <[email protected]>
+ kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/
+ - x86-64, 部分i386, Andi Kleen <[email protected]>
+ ftp.firstfloor.org:/pub/ak/x86_64/quilt/
+
+
+报告bug
+-------
+
+bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。我们鼓励用
+户在这个工具中报告找到的所有bug。如何使用内核bugzilla的细节请访问：
+ http://test.kernel.org/bugzilla/faq.html
+
+内核源码主目录中的REPORTING-BUGS文件里有一个很好的模板。它指导用户如何报
+告可能的内核bug以及需要提供哪些信息来帮助内核开发者们找到问题的根源。
+
+
+利用bug报告
+-----------
+
+练习内核开发技能的最好办法就是修改其他人报告的bug。你不光可以帮助内核变
+得更加稳定，还可以学会如何解决实际问题从而提高自己的技能，并且让其他开发
+者感受到你的存在。修改bug是赢得其他开发者赞誉的最好办法，因为并不是很多
+人都喜欢浪费时间去修改别人报告的bug。
+
+要尝试修改已知的bug，请访问http://bugzilla.kernel.org网址。如果你想获得
+最新bug的通知，可以订阅bugme-new邮件列表（只有新的bug报告会被寄到这里）
+或者订阅bugme-janitor邮件列表（所有bugzilla的变动都会被寄到这里）。
+
+ http://lists.osdl.org/mailman/listinfo/bugme-new
+ http://lists.osdl.org/mailman/listinfo/bugme-janitors
+
+
+邮件列表
+--------
+
+正如上面的文档所描述，大多数的骨干内核开发者都加入了Linux Kernel邮件列
+表。如何订阅和退订列表的细节可以在这里找到：
+ http://vger.kernel.org/vger-lists.html#linux-kernel
+网上很多地方都有这个邮件列表的存档(archive)。可以使用搜索引擎来找到这些
+存档。比如：
+ http://dir.gmane.org/gmane.linux.kernel
+在发信之前，我们强烈建议你先在存档中搜索你想要讨论的问题。很多已经被详细
+讨论过的问题只在邮件列表的存档中可以找到。
+
+大多数内核子系统也有自己独立的邮件列表来协调各自的开发工作。从
+MAINTAINERS文件中可以找到不同话题对应的邮件列表。
+
+很多邮件列表架设在kernel.org服务器上。这些列表的信息可以在这里找到：
+ http://vger.kernel.org/vger-lists.html
+
+在使用这些邮件列表时，请记住保持良好的行为习惯。下面的链接提供了与这些列
+表（或任何其它邮件列表）交流的一些简单规则，虽然内容有点滥竽充数。
+ http://www.albion.com/netiquette/
+
+当有很多人回复你的邮件时，邮件的抄送列表会变得很长。请不要将任何人从抄送
+列表中删除，除非你有足够的理由这么做。也不要只回复到邮件列表。请习惯于同
+一封邮件接收两次（一封来自发送者一封来自邮件列表），而不要试图通过添加一
+些奇特的邮件头来解决这个问题，人们不会喜欢的。
+
+记住保留你所回复内容的上下文和源头。在你回复邮件的顶部保留“某某某说到……”
+这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。
+
+如果你在邮件中附带补丁，请确认它们是可以直接阅读的纯文本（如
+Documentation/SubmittingPatches文档中所述）。内核开发者们不希望遇到附件
+或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保
+你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件
+发送给自己，然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功，请
+调整或者更换你的邮件发送程序直到它正确工作为止。
+
+总而言之，请尊重其他的邮件列表订阅者。
+
+
+同内核社区合作
+----------------
+
+内核社区的目标就是提供尽善尽美的内核。所以当你提交补丁期望被接受进内核的
+时候，它的技术价值以及其他方面都将被评审。那么你可能会得到什么呢？
+ - 批评
+ - 评论
+ - 要求修改
+ - 要求证明修改的必要性
+ - 沉默
+
+要记住，这些是把补丁放进内核的正常情况。你必须学会听取对补丁的批评和评论，
+从技术层面评估它们，然后要么重写你的补丁要么简明扼要地论证修改是不必要
+的。如果你发的邮件没有得到任何回应，请过几天后再试一次，因为有时信件会湮
+没在茫茫信海中。
+
+你不应该做的事情：
+ - 期望自己的补丁不受任何质疑就直接被接受
+ - 翻脸
+ - 忽略别人的评论
+ - 没有按照别人的要求做任何修改就重新提交
+
+在一个努力追寻最好技术方案的社区里，对于一个补丁有多少好处总会有不同的见
+解。你必须要抱着合作的态度，愿意改变自己的观点来适应内核的风格。或者至少
+愿意去证明你的想法是有价值的。记住，犯错误是允许的，只要你愿意朝着正确的
+方案去努力。
+
+如果你的第一个补丁换来的是一堆修改建议，这是很正常的。这并不代表你的补丁
+不会被接受，也不意味着有人和你作对。你只需要改正所有提出的问题然后重新发
+送你的补丁。
+
+内核社区和公司文化的差异
+------------------------
+
+内核社区的工作模式同大多数传统公司开发队伍的工作模式并不相同。下面这些例
+子，可以帮助你避免某些可能发生问题：
+ 用这些话介绍你的修改提案会有好处：
+ - 它同时解决了多个问题
+ - 它删除了2000行代码
+ - 这是补丁，它已经解释了我想要说明的
+ - 我在5种不同的体系结构上测试过它……
+ - 这是一系列小补丁用来……
+ - 这个修改提高了普通机器的性能……
+
+ 应该避免如下的说法：
+ - 我们在AIX/ptx/Solaris就是这么做的，所以这么做肯定是好的……
+ - 我做这行已经20年了，所以……
+ - 为了我们公司赚钱考虑必须这么做
+ - 这是我们的企业产品线所需要的
+ - 这里是描述我观点的1000页设计文档
+ - 这是一个5000行的补丁用来……
+ - 我重写了现在乱七八糟的代码，这就是……
+ - 我被规定了最后期限，所以这个补丁需要立刻被接受
+
+另外一个内核社区与大部分传统公司的软件开发队伍不同的地方是无法面对面地交
+流。使用电子邮件和IRC聊天工具做为主要沟通工具的一个好处是性别和种族歧视
+将会更少。Linux内核的工作环境更能接受妇女和少数族群，因为每个人在别人眼
+里只是一个邮件地址。国际化也帮助了公平的实现，因为你无法通过姓名来判断人
+的性别。男人有可能叫李丽，女人也有可能叫王刚。大多数在Linux内核上工作过
+并表达过看法的女性对在linux上工作的经历都给出了正面的评价。
+
+对于一些不习惯使用英语的人来说，语言可能是一个引起问题的障碍。在邮件列表
+中要正确地表达想法必需良好地掌握语言，所以建议你在发送邮件之前最好检查一
+下英文写得是否正确。
+
+
+拆分修改
+--------
+
+Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当地介绍、讨论并且
+拆分成独立的小段。这几乎完全和公司中的习惯背道而驰。你的想法应该在开发最
+开始的阶段就让大家知道，这样你就可以及时获得对你正在进行的开发的反馈。这
+样也会让社区觉得你是在和他们协作，而不是仅仅把他们当作倾销新功能的对象。
+无论如何，你不要一次性地向邮件列表发送50封信，你的补丁序列应该永远用不到
+这么多。
+
+将补丁拆开的原因如下：
+
+1) 小的补丁更有可能被接受，因为它们不需要太多的时间和精力去验证其正确性。
+ 一个5行的补丁，可能在维护者看了一眼以后就会被接受。而500行的补丁则
+ 需要数个小时来审查其正确性（所需时间随补丁大小增加大约呈指数级增长）。
+
+ 当出了问题的时候，小的补丁也会让调试变得非常容易。一个一个补丁地回溯
+ 将会比仔细剖析一个被打上的大补丁（这个补丁破坏了其他东西）容易得多。
+
+2）不光发送小的补丁很重要，在提交之前重新编排、化简（或者仅仅重新排列）
+ 补丁也是很重要的。
+
+这里有内核开发者Al Viro打的一个比方：
+ “想象一个老师正在给学生批改数学作业。老师并不希望看到学生为了得
+ 到正确解法所进行的尝试和产生的错误。他希望看到的是最干净最优雅的
+ 解答。好学生了解这点，绝不会把最终解决之前的中间方案提交上去。”
+
+ 内核开发也是这样。维护者和评审者不希望看到一个人在解决问题时的思
+ 考过程。他们只希望看到简单和优雅的解决方案。
+
+直接给出一流的解决方案，和社区一起协作讨论尚未完成的工作，这两者之间似乎
+很难找到一个平衡点。所以最好尽早开始收集有利于你进行改进的反馈；同时也要
+保证修改分成很多小块，这样在整个项目都准备好被包含进内核之前，其中的一部
+分可能会先被接收。
+
+必须了解这样做是不可接受的：试图将未完成的工作提交进内核，然后再找时间修
+复。
+
+
+证明修改的必要性
+----------------
+除了将补丁拆成小块，很重要的一点是让Linux社区了解他们为什么需要这样修改。
+你必须证明新功能是有人需要的并且是有用的。
+
+
+记录修改
+--------
+
+当你发送补丁的时候，需要特别留意邮件正文的内容。因为这里的信息将会做为补
+丁的修改记录(ChangeLog)，会被一直保留以备大家查阅。它需要完全地描述补丁，
+包括：
+ - 为什么需要这个修改
+ - 补丁的总体设计
+ - 实现细节
+ - 测试结果
+
+想了解它具体应该看起来像什么，请查阅以下文档中的“ChangeLog”章节：
+ “The Perfect Patch”
+ http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
+
+
+这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是
+一个持续提高的过程，它需要大量的耐心和决心。只要不放弃，你一定可以做到。
+很多人已经做到了，而他们都曾经和现在的你站在同样的起点上。
+
+
+---------------
+感谢Paolo Ciarrocchi允许“开发流程”部分基于他所写的文章
+(http://linux.tar.bz/articles/2.6-development_process)，感谢Randy
+Dunlap和Gerrit Huizenga完善了应该说和不该说的列表。感谢Pat Mochel, Hanna
+Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer,
+Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian
+Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael
+Kerrisk和Alex Shepard的评审、建议和贡献。没有他们的帮助，这篇文档是不可
+能完成的。
+
+
+
+英文版维护者： Greg Kroah-Hartman <[email protected]>
--
1.5.2.GIT
On Thu, Jun 21, 2007 at 10:40:17PM +0800, Li Yang wrote:
>This is a Chinese translated version of Documentation/HOWTO. Currently
>Chinese involvement in Linux kernel is very low, especially comparing to
>its largest population base. Language could be the main obstacle. Hope
>this document will help more Chinese to contribute to Linux kernel.
>
>Signed-off-by: Li Yang <[email protected]>
>Signed-off-by: TripleX Chung <[email protected]>
>Signed-off-by: Maggie Chen <[email protected]>
Signed-off-by: WANG Cong <[email protected]>
>---
>Address comments from Wang Cong.
> Documentation/zh_CN/HOWTO | 536 +++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 536 insertions(+), 0 deletions(-)
> create mode 100644 Documentation/zh_CN/HOWTO
>
>diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO
>new file mode 100644
>index 0000000..c70debd
>--- /dev/null
>+++ b/Documentation/zh_CN/HOWTO
Thanks! Looks fine for me this time.
However, I have noticed this patch for original HOWTO:
http://lkml.org/lkml/2007/6/19/299
Maybe we can ask Greg if that patch has applied. If so, we should also change ours.
<quote sender="Li Yang">
> This is a Chinese translated version of Documentation/HOWTO. Currently
> Chinese involvement in Linux kernel is very low, especially comparing to
> its largest population base. Language could be the main obstacle. Hope
> this document will help more Chinese to contribute to Linux kernel.
>
> Signed-off-by: Li Yang <[email protected]>
> Signed-off-by: TripleX Chung <[email protected]>
> Signed-off-by: Maggie Chen <[email protected]>
> ---
> Address comments from Wang Cong.
> Documentation/zh_CN/HOWTO | 536 +++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 536 insertions(+), 0 deletions(-)
> create mode 100644 Documentation/zh_CN/HOWTO
>
> diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO
> new file mode 100644
> index 0000000..c70debd
> --- /dev/null
> +++ b/Documentation/zh_CN/HOWTO
[...]
I read through the translated HOWTO. Looks good to me.
Eugene
On Thu, 2007-06-21 at 22:40 +0800, Li Yang wrote:
> This is a Chinese translated version of Documentation/HOWTO. Currently
> Chinese involvement in Linux kernel is very low, especially comparing to
> its largest population base. Language could be the main obstacle. Hope
> this document will help more Chinese to contribute to Linux kernel.
I tried to find some bugs in this translation, but I failed, -:)).
Thanks a lot for your work, I hope I can do some help next time.
Best Regards,
- Bryan Wu
On Thursday 21 June 2007 10:40:17 Li Yang wrote:
> This is a Chinese translated version of Documentation/HOWTO. Currently
> Chinese involvement in Linux kernel is very low, especially comparing to
> its largest population base. Language could be the main obstacle. Hope
> this document will help more Chinese to contribute to Linux kernel.
I'm putting together a kernel documentation directory at http://kernel.org/doc
and I could easily add translations in there. I just don't know if this is a
good idea.
The problem is, the submission of patches happens on the various kernel.org
mailing lists, which are all in English. Kernel development is done in a
single common language: English. (If you'd like to argue for it to be done
in another language, please make the proposal in Linus's native Swedish.)
Setting aside for the moment version skew and coverage issues when translating
Documentation, which aren't really serious blocking issues, my question is
this: If developers aren't fluent enough with English to follow the
documentation, how can they follow any of the technical discussions necessary
to merge their patches back into the mainstream kernel? Doesn't this
encourage the creation of patches that can't easily be merged back into the
kernel?
It could be that the answer is "no, it's fine". I don't feel qualified to
make this decision. It's very easy for me to accept contributed translations
and put them up, but I'd like some kind of consensus from the kernel
developers that I SHOULD do this. How much use is a Chinese version of a
HOWTO that tells people how to interact with an English community?
Could somebody more qualified than me speak up on this one so I know what to
do?
Rob
P.S. I meant to comment when this topic first came up last week
[http://kerneltrap.org/node/8365] but my laptop's hard drive died and I lost
the link. (Along with any chance of this being a particularly productive
month for me...)
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
Hi,
2007/6/22, Rob Landley <[email protected]>:
> On Thursday 21 June 2007 10:40:17 Li Yang wrote:
> > This is a Chinese translated version of Documentation/HOWTO. Currently
> > Chinese involvement in Linux kernel is very low, especially comparing to
> > its largest population base. Language could be the main obstacle. Hope
> > this document will help more Chinese to contribute to Linux kernel.
>
> I'm putting together a kernel documentation directory at http://kernel.org/doc
> and I could easily add translations in there. I just don't know if this is a
> good idea.
>
I think it's not a good idea to merge translations into kernel.
> The problem is, the submission of patches happens on the various kernel.org
> mailing lists, which are all in English. Kernel development is done in a
> single common language: English. (If you'd like to argue for it to be done
> in another language, please make the proposal in Linus's native Swedish.)
>
Yes, I agree with you, and there's so many other languages, It's
better for someone to create a standalone kdoc translation project
than to merge them into kernel.
Regards
dave
> -----Original Message-----
> From: Rob Landley [mailto:[email protected]]
> Sent: Friday, June 22, 2007 10:49 AM
>
> On Thursday 21 June 2007 10:40:17 Li Yang wrote:
> > This is a Chinese translated version of Documentation/HOWTO.
Currently
> > Chinese involvement in Linux kernel is very low, especially
comparing to
> > its largest population base. Language could be the main obstacle.
Hope
> > this document will help more Chinese to contribute to Linux kernel.
>
> I'm putting together a kernel documentation directory at
http://kernel.org/doc
> and I could easily add translations in there. I just don't know if
this is a
> good idea.
>
> The problem is, the submission of patches happens on the various
kernel.org
> mailing lists, which are all in English. Kernel development is done
in a
> single common language: English. (If you'd like to argue for it to be
done
> in another language, please make the proposal in Linus's native
Swedish.)
>
> Setting aside for the moment version skew and coverage issues when
translating
> Documentation, which aren't really serious blocking issues, my
question is
> this: If developers aren't fluent enough with English to follow the
> documentation, how can they follow any of the technical discussions
necessary
> to merge their patches back into the mainstream kernel? Doesn't this
> encourage the creation of patches that can't easily be merged back
into the
> kernel?
So as I argued in a previous email, non-native English speakers tend to
be more confused by the policies and processes. I also don't think it's
necessary to translate the technical documents. To be a software
developer, one has to be educated or experienced in technical terms.
Technical discussion can be done without too much requirement to grammar
and emotional expressing. The translated document of policies and
processes will help these people to understand the process better and go
smoother in the process.
- Leo
On Fri, 2007-06-22 at 11:58 +0800, Li Yang-r58472 wrote:
> > -----Original Message-----
> > From: Rob Landley [mailto:[email protected]]
> > Sent: Friday, June 22, 2007 10:49 AM
> >
> > On Thursday 21 June 2007 10:40:17 Li Yang wrote:
> > > This is a Chinese translated version of Documentation/HOWTO.
> Currently
> > > Chinese involvement in Linux kernel is very low, especially
> comparing to
> > > its largest population base. Language could be the main obstacle.
> Hope
> > > this document will help more Chinese to contribute to Linux kernel.
> >
> > I'm putting together a kernel documentation directory at
> http://kernel.org/doc
> > and I could easily add translations in there. I just don't know if
> this is a
> > good idea.
> >
> > The problem is, the submission of patches happens on the various
> kernel.org
> > mailing lists, which are all in English. Kernel development is done
> in a
> > single common language: English. (If you'd like to argue for it to be
> done
> > in another language, please make the proposal in Linus's native
> Swedish.)
> >
> > Setting aside for the moment version skew and coverage issues when
> translating
> > Documentation, which aren't really serious blocking issues, my
> question is
> > this: If developers aren't fluent enough with English to follow the
> > documentation, how can they follow any of the technical discussions
> necessary
> > to merge their patches back into the mainstream kernel? Doesn't this
> > encourage the creation of patches that can't easily be merged back
> into the
> > kernel?
>
> So as I argued in a previous email, non-native English speakers tend to
> be more confused by the policies and processes. I also don't think it's
> necessary to translate the technical documents. To be a software
> developer, one has to be educated or experienced in technical terms.
> Technical discussion can be done without too much requirement to grammar
> and emotional expressing. The translated document of policies and
> processes will help these people to understand the process better and go
> smoother in the process.
>
> - Leo
Leo is right. Policies and processes should be clear for all developer
including non-native English speakers, while other technical documents
do not need to be translated.
After I read the translations, I also found something I missed before.
Thanks for the work
- Bryan Wu
On Fri, Jun 22, 2007 at 11:58:58AM +0800, Li Yang-r58472 wrote:
>> -----Original Message-----
>> From: Rob Landley [mailto:[email protected]]
>> Sent: Friday, June 22, 2007 10:49 AM
>>
>> On Thursday 21 June 2007 10:40:17 Li Yang wrote:
>> > This is a Chinese translated version of Documentation/HOWTO.
>Currently
>> > Chinese involvement in Linux kernel is very low, especially
>comparing to
>> > its largest population base. Language could be the main obstacle.
>Hope
>> > this document will help more Chinese to contribute to Linux kernel.
>>
>> I'm putting together a kernel documentation directory at
>http://kernel.org/doc
>> and I could easily add translations in there. I just don't know if
>this is a
>> good idea.
>>
>> The problem is, the submission of patches happens on the various
>kernel.org
>> mailing lists, which are all in English. Kernel development is done
>in a
>> single common language: English. (If you'd like to argue for it to be
>done
>> in another language, please make the proposal in Linus's native
>Swedish.)
>>
>> Setting aside for the moment version skew and coverage issues when
>translating
>> Documentation, which aren't really serious blocking issues, my
>question is
>> this: If developers aren't fluent enough with English to follow the
>> documentation, how can they follow any of the technical discussions
>necessary
>> to merge their patches back into the mainstream kernel? Doesn't this
>> encourage the creation of patches that can't easily be merged back
>into the
>> kernel?
>
>So as I argued in a previous email, non-native English speakers tend to
>be more confused by the policies and processes. I also don't think it's
>necessary to translate the technical documents. To be a software
>developer, one has to be educated or experienced in technical terms.
>Technical discussion can be done without too much requirement to grammar
>and emotional expressing. The translated document of policies and
>processes will help these people to understand the process better and go
>smoother in the process.
>
Yes, I agree.
Many people from China are trying to contribute to Linux kernel (like me),
a Chinese document which describes and explains the non-technical things
needed by Linux kernel will help them _much_ to join the development soon.
Also, IMO, a translation shows Linux kernel is friendly and open to
people from all over the world.
Regards!
WANG Cong
Dear Linus: you aren't at Transmeta anymore. Here's a second attempt to cc:
you on this because I need your opinion on a documentation issue:
On Thursday 21 June 2007 22:48:32 Rob Landley wrote:
> On Thursday 21 June 2007 10:40:17 Li Yang wrote:
> > This is a Chinese translated version of Documentation/HOWTO. Currently
> > Chinese involvement in Linux kernel is very low, especially comparing to
> > its largest population base. Language could be the main obstacle. Hope
> > this document will help more Chinese to contribute to Linux kernel.
>
> I'm putting together a kernel documentation directory at
> http://kernel.org/doc and I could easily add translations in there. I just
> don't know if this is a good idea.
>
> The problem is, the submission of patches happens on the various kernel.org
> mailing lists, which are all in English. Kernel development is done in a
> single common language: English. (If you'd like to argue for it to be done
> in another language, please make the proposal in Linus's native Swedish.)
>
> Setting aside for the moment version skew and coverage issues when
> translating Documentation, which aren't really serious blocking issues, my
> question is this: If developers aren't fluent enough with English to
> follow the documentation, how can they follow any of the technical
> discussions necessary to merge their patches back into the mainstream
> kernel? Doesn't this encourage the creation of patches that can't easily
> be merged back into the kernel?
>
> It could be that the answer is "no, it's fine". I don't feel qualified to
> make this decision. It's very easy for me to accept contributed
> translations and put them up, but I'd like some kind of consensus from the
> kernel developers that I SHOULD do this. How much use is a Chinese version
> of a HOWTO that tells people how to interact with an English community?
>
> Could somebody more qualified than me speak up on this one so I know what
> to do?
>
> Rob
>
> P.S. I meant to comment when this topic first came up last week
> [http://kerneltrap.org/node/8365] but my laptop's hard drive died and I
> lost the link. (Along with any chance of this being a particularly
> productive month for me...)
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On Thursday 21 June 2007 23:23:54 dave young wrote:
> Hi,
>
> 2007/6/22, Rob Landley <[email protected]>:
> > On Thursday 21 June 2007 10:40:17 Li Yang wrote:
> > > This is a Chinese translated version of Documentation/HOWTO. Currently
> > > Chinese involvement in Linux kernel is very low, especially comparing
> > > to its largest population base. Language could be the main obstacle.
> > > Hope this document will help more Chinese to contribute to Linux
> > > kernel.
> >
> > I'm putting together a kernel documentation directory at
> > http://kernel.org/doc and I could easily add translations in there. I
> > just don't know if this is a good idea.
>
> I think it's not a good idea to merge translations into kernel.
>
> > The problem is, the submission of patches happens on the various
> > kernel.org mailing lists, which are all in English. Kernel development
> > is done in a single common language: English. (If you'd like to argue
> > for it to be done in another language, please make the proposal in
> > Linus's native Swedish.)
>
> Yes, I agree with you, and there's so many other languages, It's
> better for someone to create a standalone kdoc translation project
> than to merge them into kernel.
I wasn't suggesting merging them into the kernel.
I'm doing a web page to put together html versions of lots of kernel
documentation in a place Google can find it. Peter Anvin was kind enough to
give me http://kernel.org/doc for this. It would not be technically
difficult for this web page to host translated versions of this
documentation.
The question is, do the kernel developers want to encourage people who don't
speak English to mess with the kernel, any more than they want to encourage
kernel developers who don't know C? Is kernel documentation in Chinese a
better idea than a repository of kernel patches in C++? (Either way, work
resulting from this is much less likely than normal to be merged into the
kernel.)
I don't know if this is a valid concern or not. That's why I'm asking.
Rob
P.S. The hardest part of putting together a kernel documentation web page is
actually indexing it coherently. It's not very useful to just dump together
huge amounts of stuff from Documentation and make htmldocs and linux weekly
news' kernel index and kerneltrap and kernel traffic and the kernelnewbies
wiki and kernelplanet and man-pages-2.57 coverted to html with doclifter...
Ahem. I finally figured out how I wanted it indexed, made a skeleton to hang
stuff on, and my laptop blew up. Grrr. Mostly recovered, but now OLS is
bearing down on me and I still haven't got a new laptop...
Don't mind me, I'll catch up.
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
Hi,
2007/6/22, Rob Landley <[email protected]>:
> On Thursday 21 June 2007 23:23:54 dave young wrote:
> > Hi,
> >
> > 2007/6/22, Rob Landley <[email protected]>:
> > > On Thursday 21 June 2007 10:40:17 Li Yang wrote:
> > > > This is a Chinese translated version of Documentation/HOWTO. Currently
> > > > Chinese involvement in Linux kernel is very low, especially comparing
> > > > to its largest population base. Language could be the main obstacle.
> > > > Hope this document will help more Chinese to contribute to Linux
> > > > kernel.
> > >
> > > I'm putting together a kernel documentation directory at
> > > http://kernel.org/doc and I could easily add translations in there. I
> > > just don't know if this is a good idea.
> >
> > I think it's not a good idea to merge translations into kernel.
> >
> > > The problem is, the submission of patches happens on the various
> > > kernel.org mailing lists, which are all in English. Kernel development
> > > is done in a single common language: English. (If you'd like to argue
> > > for it to be done in another language, please make the proposal in
> > > Linus's native Swedish.)
> >
> > Yes, I agree with you, and there's so many other languages, It's
> > better for someone to create a standalone kdoc translation project
> > than to merge them into kernel.
>
> I wasn't suggesting merging them into the kernel.
I'm misunderstanded.
I means:
Yes, I agree with you.
There's so many other languages, It's better for someone to create a
standalone kdoc translation project than to merge them into kernel.
> I'm doing a web page to put together html versions of lots of kernel
> documentation in a place Google can find it. Peter Anvin was kind enough to
> give me http://kernel.org/doc for this. It would not be technically
> difficult for this web page to host translated versions of this
> documentation.
>
> The question is, do the kernel developers want to encourage people who don't
> speak English to mess with the kernel, any more than they want to encourage
> kernel developers who don't know C? Is kernel documentation in Chinese a
> better idea than a repository of kernel patches in C++? (Either way, work
> resulting from this is much less likely than normal to be merged into the
> kernel.)
>
It's another issue.
Someone don't speak english , but it don't means they haven't
programming skilles. As long as one can help to promote the kernel
development he is welcomed.
> I don't know if this is a valid concern or not. That's why I'm asking.
>
> Rob
>
> P.S. The hardest part of putting together a kernel documentation web page is
> actually indexing it coherently. It's not very useful to just dump together
> huge amounts of stuff from Documentation and make htmldocs and linux weekly
> news' kernel index and kerneltrap and kernel traffic and the kernelnewbies
> wiki and kernelplanet and man-pages-2.57 coverted to html with doclifter...
> Ahem. I finally figured out how I wanted it indexed, made a skeleton to hang
> stuff on, and my laptop blew up. Grrr. Mostly recovered, but now OLS is
> bearing down on me and I still haven't got a new laptop...
>
> Don't mind me, I'll catch up.
> --
> "One of my most productive days was throwing away 1000 lines of code."
> - Ken Thompson.
>
Regards
dave
> -----Original Message-----
> From: Rob Landley [mailto:[email protected]]
> Sent: Friday, June 22, 2007 1:33 PM
> To: dave young
> Cc: Li Yang-r58472; [email protected]; [email protected];
> [email protected]; [email protected]; TripleX Chung; Maggie
Chen;
> [email protected]
> Subject: Re: [PATCH] Chinese translation of Documentation/HOWTO
>
> On Thursday 21 June 2007 23:23:54 dave young wrote:
> > Hi,
> >
> > 2007/6/22, Rob Landley <[email protected]>:
> > > On Thursday 21 June 2007 10:40:17 Li Yang wrote:
> > > > This is a Chinese translated version of Documentation/HOWTO.
Currently
> > > > Chinese involvement in Linux kernel is very low, especially
comparing
> > > > to its largest population base. Language could be the main
obstacle.
> > > > Hope this document will help more Chinese to contribute to Linux
> > > > kernel.
> > >
> > > I'm putting together a kernel documentation directory at
> > > http://kernel.org/doc and I could easily add translations in
there. I
> > > just don't know if this is a good idea.
> >
> > I think it's not a good idea to merge translations into kernel.
> >
> > > The problem is, the submission of patches happens on the various
> > > kernel.org mailing lists, which are all in English. Kernel
development
> > > is done in a single common language: English. (If you'd like to
argue
> > > for it to be done in another language, please make the proposal in
> > > Linus's native Swedish.)
> >
> > Yes, I agree with you, and there's so many other languages, It's
> > better for someone to create a standalone kdoc translation project
> > than to merge them into kernel.
>
> I wasn't suggesting merging them into the kernel.
>
> I'm doing a web page to put together html versions of lots of kernel
> documentation in a place Google can find it. Peter Anvin was kind
enough to
> give me http://kernel.org/doc for this. It would not be technically
> difficult for this web page to host translated versions of this
> documentation.
>
> The question is, do the kernel developers want to encourage people who
don't
> speak English to mess with the kernel, any more than they want to
encourage
> kernel developers who don't know C? Is kernel documentation in
Chinese a
> better idea than a repository of kernel patches in C++? (Either way,
work
> resulting from this is much less likely than normal to be merged into
the
> kernel.)
IMHO, the ultimate language for the Linux kernel is C language rather
than English. Nothing prevents one with poor English to write good C
code except for the comment part. However if the code is really good to
be understood on its own, the problem is not that important then.
Moreover, the case here is not about people who can't read/write in
English completely. It is to help and to encourage people who have some
difficulty to deal with the community but has the basic English skill to
deal with technical discussion. That's like why we have disability
services for special people who can do things actually.
- Leo
> The question is, do the kernel developers want to encourage people who don't
> speak English to mess with the kernel, any more than they want to encourage
> kernel developers who don't know C? Is kernel documentation in Chinese a
The majority of the world population do not speak English. There are
existing contributors do not speak English (and I'm not being funny about
the USSA here) - you don't notice because they have a team member who
speaks passable English.
There are also entire non-English sites around things like Linux that
monoglot English speakers generally don't notice exist.
> P.S. The hardest part of putting together a kernel documentation web page is
> actually indexing it coherently. It's not very useful to just dump together
For the kernel I would follow the kernel tree so that its always
/[languagecode]/Documentation/...
that works fairly well although their are political fights you can get
into over China/Taiwan and over Burmese.
Alan
On Fri, 22 Jun 2007, Li Yang-r58472 wrote:
>
> So as I argued in a previous email, non-native English speakers tend to
> be more confused by the policies and processes. I also don't think it's
> necessary to translate the technical documents. To be a software
> developer, one has to be educated or experienced in technical terms.
> Technical discussion can be done without too much requirement to grammar
> and emotional expressing. The translated document of policies and
> processes will help these people to understand the process better and go
> smoother in the process.
I do agree.
I think that the policies and processes parts of the documentation are
things that make total sense to encourage translation of, because it's
entirely possible that those are interesting and valid even to the people
who aren't necessarily directly involved in the actual coding, and may
well be relevant to managers etc who may not be _directly_ involed with
the rest of the kernel developers.
In fact, I suspect pretty much any documentation (whether technical or
about processes and/or style) makes sense to have translated if the energy
and ability to do that exists. I suspect the "policies and processes"
kinds of docs make _more_ sense to translate initially, simply because
they are approachable on their own - but I certainly would never
discourage anybody from translating anything at all.
That said, I don't think that merging the result into the standard kernel
makes sense - like it or not, right now English ends up being required
to be part of actually getting things into the "standard" kernel, and as
such, at _some_ point there has to be a connection point that switches
over to English, and trying to make the translations be an in-kernel thing
is thus kind of pointless.
But as part of some "documentation site", it makes 100% sense.
And sometimes maybe the issue isn't even just about straight translations,
but also perhaps about explaining cultural differences that aren't
mentioned at all in the documentation, just because people in the west end
up taking certain things for granted and it doesn't "need" documenting..
Linus
A little issue about "when is translation good"
I usually tell people to use vimtutor's example to set up syntax
highlighting in vim. I usually only install OSs in english because
translations tend to be poor and hard to comprehend.
Now, I'm from argentina, and I live with a ling?ist. He doesn't handle
english very well, and he wanted to get rid of Windows, so we
installed ubuntu, Locale:SP_ARG.
vim is in spanish, and so is vimtutor. vimtutor's spanish translation
doesn't have anything on syntax highlighting: the translation is poor.
my point: IMHO it's better to have no translation than a poor one
T
--
|_|0|_|
|_|_|0|
|0|0|0|
Linus Torvalds wrote:
> On Fri, 22 Jun 2007, Li Yang-r58472 wrote:
>
>> So as I argued in a previous email, non-native English speakers tend to
>> be more confused by the policies and processes. I also don't think it's
>> necessary to translate the technical documents. To be a software
>> developer, one has to be educated or experienced in technical terms.
>> Technical discussion can be done without too much requirement to grammar
>> and emotional expressing. The translated document of policies and
>> processes will help these people to understand the process better and go
>> smoother in the process.
>>
>
> I do agree.
>
> I think that the policies and processes parts of the documentation are
> things that make total sense to encourage translation of, because it's
> entirely possible that those are interesting and valid even to the people
> who aren't necessarily directly involved in the actual coding, and may
> well be relevant to managers etc who may not be _directly_ involed with
> the rest of the kernel developers.
>
> In fact, I suspect pretty much any documentation (whether technical or
> about processes and/or style) makes sense to have translated if the energy
> and ability to do that exists. I suspect the "policies and processes"
> kinds of docs make _more_ sense to translate initially, simply because
> they are approachable on their own - but I certainly would never
> discourage anybody from translating anything at all.
>
> That said, I don't think that merging the result into the standard kernel
> makes sense - like it or not, right now English ends up being required
> to be part of actually getting things into the "standard" kernel, and as
> such, at _some_ point there has to be a connection point that switches
> over to English, and trying to make the translations be an in-kernel thing
> is thus kind of pointless.
>
> But as part of some "documentation site", it makes 100% sense.
>
> And sometimes maybe the issue isn't even just about straight translations,
> but also perhaps about explaining cultural differences that aren't
> mentioned at all in the documentation, just because people in the west end
> up taking certain things for granted and it doesn't "need" documenting..
>
>
As I know, there are a lot of standalone kernel developer in China. They
write device drivers for their chips or iptables modules for their
linux based network devices. They send source files to their customers
or publish them on web but seldom do anything to make the codes into
kernel source tree. The usual reason is they do not know how to
communicate and work with the Linux kernel development community. People
will have more chance to read these documentation if we merge them to
the kernel source tree.
TripleX
On Friday 22 June 2007 02:07:57 dave young wrote:
> > > Yes, I agree with you, and there's so many other languages, It's
> > > better for someone to create a standalone kdoc translation project
> > > than to merge them into kernel.
> >
> > I wasn't suggesting merging them into the kernel.
>
> I'm misunderstanded.
>
> I means:
> Yes, I agree with you.
> There's so many other languages, It's better for someone to create a
> standalone kdoc translation project than to merge them into kernel.
I agree, but this is just an opinion. (I see where Greg KH wants to merge it
into the kernel.)
> > The question is, do the kernel developers want to encourage people who
> > don't speak English to mess with the kernel, any more than they want to
> > encourage kernel developers who don't know C? Is kernel documentation in
> > Chinese a better idea than a repository of kernel patches in C++?
> > (Either way, work resulting from this is much less likely than normal to
> > be merged into the kernel.)
>
> It's another issue.
>
> Someone don't speak english , but it don't means they haven't
> programming skilles. As long as one can help to promote the kernel
> development he is welcomed.
I agree that programming talent can exist without the ability to speak
English. But will the resulting patches get merged if the developer can't
communicate with the Linux development community?
I dealt with a programmer on the BusyBox project who only speaks Russian, and
uses a babelfish variant to translate everything. This was incredibly
frustrating: he regularly misunderstood what we were saying, we regularly had
no idea what he was saying, his attempts at commenting the code were often
worse than not commeting it at all, and after three years his ability to
communicate hadn't improved in the slightest.
Possibly we'd need some volunteer translators just for the purpose of merging
code in languages we'd translated the documentation into? A "chinese patch
maintainer" or some such?
Rob
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On Friday 22 June 2007 05:21:23 Alan Cox wrote:
> > The question is, do the kernel developers want to encourage people who
> > don't speak English to mess with the kernel, any more than they want to
> > encourage kernel developers who don't know C? Is kernel documentation in
> > Chinese a
>
> The majority of the world population do not speak English. There are
> existing contributors do not speak English (and I'm not being funny about
> the USSA here) - you don't notice because they have a team member who
> speaks passable English.
Ok. Cool. If this is not a problem, that's good to know.
> There are also entire non-English sites around things like Linux that
> monoglot English speakers generally don't notice exist.
I'm aware of this.
> > P.S. The hardest part of putting together a kernel documentation web
> > page is actually indexing it coherently. It's not very useful to just
> > dump together
>
> For the kernel I would follow the kernel tree so that its always
>
> /[languagecode]/Documentation/...
That PS was about putting up a kernel doc web page, not about the existing
kernel Documentation tree.
The existing Documentation tree has, at the top level, coding style
guidelines, files documenting the kernel community, a file documenting the
Amiga "zorro" bus, a half-dozen files about old multiport serial cards,
documentation about several different types of locking, a penguin graphic
from 1996, your documentation on the tty layer, a document on how to
configure BINFMT_MISC to autorun .NET files with mono, and zillions of other
random unrelated topics that are sorted based on where random passerby put
things down last.
I sent a couple patches to shuffle stuff around in there but it got lost on
the noise. More to the point, an HTML index can hotlink but text files have
a harder time doing that, so if I'm making an HTML index it's probably best
to link to the text files but not attempt to navigate with them.
Rob
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
> As I know, there are a lot of standalone kernel developer in China. They
> write device drivers for their chips or iptables modules for their
> linux based network devices. They send source files to their customers
> or publish them on web but seldom do anything to make the codes into
> kernel source tree. The usual reason is they do not know how to
> communicate and work with the Linux kernel development community. People
> will have more chance to read these documentation if we merge them to
> the kernel source tree.
>
> TripleX
>
Well, not necessarily they'll need to go to the source tree. Having a
website or something like that would just be fine IMO.
tong
On Friday 22 June 2007 13:02:26 Linus Torvalds wrote:
> In fact, I suspect pretty much any documentation (whether technical or
> about processes and/or style) makes sense to have translated if the energy
> and ability to do that exists. I suspect the "policies and processes"
> kinds of docs make _more_ sense to translate initially, simply because
> they are approachable on their own - but I certainly would never
> discourage anybody from translating anything at all.
>
> That said, I don't think that merging the result into the standard kernel
> makes sense - like it or not, right now English ends up being required
> to be part of actually getting things into the "standard" kernel, and as
> such, at _some_ point there has to be a connection point that switches
> over to English, and trying to make the translations be an in-kernel thing
> is thus kind of pointless.
>
> But as part of some "documentation site", it makes 100% sense.
Ok, I've got some documentation site, specifically http://kernel.org/doc (and
I'll be completely redoing it as soon as I've recovered from my recent laptop
crash and OLS).
Send me translations (preferably in HTML format), and I'll put 'em up. (I've
already got the one that started this thread.)
Thanks,
Rob
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On Friday 22 June 2007 14:39:36 TripleX wrote:
> As I know, there are a lot of standalone kernel developer in China. They
> write device drivers for their chips or iptables modules for their
> linux based network devices. They send source files to their customers
> or publish them on web but seldom do anything to make the codes into
> kernel source tree. The usual reason is they do not know how to
> communicate and work with the Linux kernel development community. People
> will have more chance to read these documentation if we merge them to
> the kernel source tree.
There are two distinct problems here:
1) Documentation so developers who know C but not English have an easier time
working with the kernel. (Again, if you translate it, send it to me and I'll
put it on the web. After OLS, though. :)
2) Some kind of "language X patch maintainer", a bilingual person who can
accept patches from people who don't speak English, submit them to the
mailing list, and pass comments back and forth until issues with the patch
are resolved. So there could be a chinese patch maintainer, a spanish patch
maintainer, etc.
> TripleX
Rob
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On Fri, Jun 22, 2007 at 03:11:45PM -0400, Rob Landley wrote:
>On Friday 22 June 2007 13:02:26 Linus Torvalds wrote:
>> In fact, I suspect pretty much any documentation (whether technical or
>> about processes and/or style) makes sense to have translated if the energy
>> and ability to do that exists. I suspect the "policies and processes"
>> kinds of docs make _more_ sense to translate initially, simply because
>> they are approachable on their own - but I certainly would never
>> discourage anybody from translating anything at all.
>>
>> That said, I don't think that merging the result into the standard kernel
>> makes sense - like it or not, right now English ends up being required
>> to be part of actually getting things into the "standard" kernel, and as
>> such, at _some_ point there has to be a connection point that switches
>> over to English, and trying to make the translations be an in-kernel thing
>> is thus kind of pointless.
>>
>> But as part of some "documentation site", it makes 100% sense.
>
>Ok, I've got some documentation site, specifically http://kernel.org/doc (and
>I'll be completely redoing it as soon as I've recovered from my recent laptop
>crash and OLS).
>
>Send me translations (preferably in HTML format), and I'll put 'em up. (I've
>already got the one that started this thread.)
>
>Thanks,
>
Please also send a copy of HTML format to me, I will put them to
http://www.kerneltravel.net (A Chinese website about Linux kernel).
Thanks!
WANG Cong
Hi!
> And sometimes maybe the issue isn't even just about straight translations,
> but also perhaps about explaining cultural differences that aren't
> mentioned at all in the documentation, just because people in the west end
> up taking certain things for granted and it doesn't "need" documenting..
Actually docs of cultural differences would be useful even for western
people.
--
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
On Thursday 28 June 2007 13:53:17 Pavel Machek wrote:
> Hi!
>
> > And sometimes maybe the issue isn't even just about straight
> > translations, but also perhaps about explaining cultural differences that
> > aren't mentioned at all in the documentation, just because people in the
> > west end up taking certain things for granted and it doesn't "need"
> > documenting..
>
> Actually docs of cultural differences would be useful even for western
> people.
I'm working on it. After OLS...
Rob
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.