Linux: Translating Kernel Documentation

on June 11, 2007 - 3:36am

From: Tsugikazu Shibata [email blocked]
To:  linux-kernel
Subject: [RFD] Documentation/HOWTO translated into Japanese
Date:	Sun, 10 Jun 2007 20:48:45 +0900 (JST)
 (葵)

Hi all,

I am posting Documentation/HOWTO which is translated into Japanese at
bottom of this email.
This document had been reviewed by JF project which has long history
to translate documents into Japanese. (not only kernel but also FAQs).
For JF, please see : http://www.linux.or.jp/JF/index.html
Please also note that the page is written in Japanese, but you can see
a lot of results there.

Actually, this is my first trial to post Japanese translated document
and here are some points I decided ;

- Character encoding is ISO-2022-JP, which is normally used for email
  using Japanese.
- Added "Singed-off-by" line
- Left the JF header strings which include translator/reviewer's name
- Non-patch format, simple text

I would be happy if I could get your comments and suggestions.
Though I know there are several issues to merge it, I want to have 
discussions with you to accomplish it.

This email comes from strong recommendation from Greg K-H when he came
to Tokyo two weeks ago. Thanks >Greg

[Editor's note: Those that don't read Japanese can click here
to skip down to where the discussion continues in English]

----- Below lines are Japanese Translation of "HOWTO" -----

Signed-off-by: Tsugikazu Shibata [email blocked]
---
==================================
これは、
linux-2.6.21/Documentation/HOWTO
の和訳です。

翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日： 2007/06/04
翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com>
校正者： 松倉さん <nbh--mats at nifty dot com>
         小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp>
         武井伸光さん、<takei at webmasters dot gr dot jp>
         かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp>
         野口さん (Kenji Noguchi) <tokyo246 at gmail dot com>
         河内さん (Takayoshi Kochi) <t-kochi at bq dot jp dot nec dot com>
         岩本さん (iwamoto) <iwamoto.kn at ncos dot nec dot co dot jp>
==================================

Linux カーネル開発のやり方
-------------------------------

これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した
ドキュメントです。ここには Linux カーネル開発者になるための方法と
Linux カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれて
います。カーネルプログラミングに関する技術的な項目に関することは何も含
めないようにしていますが、カーネル開発者となるための正しい方向に向かう
手助けになります。

もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン
トの最後にリストしたメンテナーにパッチを送ってください。

はじめに
---------

あなたは　Linux カーネルの開発者になる方法を学びたいのでしょうか？　そ
れともあなたは上司から「このデバイスの Linux ドライバを書くように」と
言われているのでしょうか？　
この文書の目的は、あなたが踏むべき手順と、コミュニティと一緒にうまく働
くヒントを書き下すことで、あなたが知るべき全てのことを教えることです。
また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も
説明しようと試みています。

カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている
以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー
ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの
でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり
ません。以下の本は、C 言語の十分な知識や何年もの経験に取って代わるもの
ではありませんが、少なくともリファレンスとしてはいい本です。
 - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
 -『プログラミング言語Ｃ第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
 - "Practical C Programming" by Steve Oualline [O'Reilly]
 - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン]
 - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
 - 『新・詳説 C 言語 H&S リファレンス』
       (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]

カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル
は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って
います。カーネルは標準 C ライブラリとは関係がないといった、C 言語フリー
スタンディング環境です。そのため、C の標準で使えないものもあります。任
意の long long の除算や浮動小数点は使えません。
ときどき、カーネルがツールチェインや C 言語拡張に置いている前提がどう
なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ
レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を
みてください。

あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ
とに留意してください。そのコミュニティは、コーディング、スタイル、
開発手順について高度な標準を持つ、多様な人の集まりです。
地理的に分散した大規模なチームに対してもっともうまくいくとわかったこと
をベースにしながら、これらの標準は長い時間をかけて築かれてきました。
これらはきちんと文書化されていますから、事前にこれらの標準についてでき
るだけたくさん学んでください。また皆があなたやあなたの会社のやり方に合わ
せてくれると思わないでください。

法的問題
------------

Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま
す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在
する、COPYING のファイルをみてください。もしライセンスについてさらに質
問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ
法律家に相談してください。メーリングリストの人達は法律家ではなく、法的
問題については彼らの声明はあてにするべきではありません。

GPL に関する共通の質問や回答については、以下を参照してください。
	http://www.gnu.org/licenses/gpl-faq.html

ドキュメント
------------

Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ
らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。
新しい機能がカーネルに追加される場合、その機能の使い方について説明した
新しいドキュメントファイルも追加することを勧めます。
カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
をマニュアルページのメンテナ [email blocked] に送ることを勧めます。

以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で
す-

  README
    このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注
    configure )し、生成(訳注 build )するために必要なことは何かが書かれ
    ています。カーネルに関して初めての人はここからスタートするとよいで
    しょう。

  Documentation/Changes
     このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
     小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
     ます。

  Documentation/CodingStyle
    これは Linux カーネルのコーディングスタイルと背景にある理由を記述
    しています。全ての新しいコードはこのドキュメントにあるガイドライン
    に従っていることを期待されています。大部分のメンテナーはこれらのルー
    ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
    だけをレビューします。

  Documentation/SubmittingPatches
  Documentation/SubmittingDrivers
     これらのファイルには、どうやってうまくパッチを作って投稿するかに
     ついて非常に詳しく書かれており、以下を含みます(これだけに限らない
     けれども)
        - Email に含むこと
        - Email の形式
        - だれに送るか
     これらのルールに従えばうまくいくことを保証することではありません
     が (すべてのパッチは内容とスタイルについて精査を受けるので)、
     ルールに従わなければ間違いなくうまくいかないでしょう。
     この他にパッチを作る方法についてのよくできた記述は-

	"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 開発の思想を理解するのに非常に重要です。
     そして、他のOSでの開発者が Linux に移る時にとても重要です。

  Documentation/SecurityBugs
    もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
    のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
    支援してください。

  Documentation/ManagementStyle
    このドキュメントは Linux カーネルのメンテナー達がどう行動するか、
    彼らの手法の背景にある共有されている精神について記述しています。こ
    れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも）
    重要です。なぜならこのドキュメントは、カーネルメンテナー達の独特な
    行動についての多くの誤解や混乱を解消するからです。

  Documentation/stable_kernel_rules.txt
    このファイルはどのように stable カーネルのリリースが行われるかのルー
    ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
    り入れてもらいたい場合に何をすればいいかが示されています。

  Documentation/kernel-docs.txt
　　カーネル開発に付随する外部ドキュメントのリストです。もしあなたが
    探しているものがカーネル内のドキュメントでみつからなかった場合、
    このリストをあたってみてください。

  Documentation/applying-patches.txt
    パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
    適用するのかについて正確に記述した良い入門書です。

カーネルはソースコードから自動的に生成可能な多数のドキュメントを自分自
身でもっています。これにはカーネル内 API のすべての記述や、どう正しく
ロックをかけるかの規則が含まれます。このドキュメントは
Documentation/DocBook/ ディレクトリに作られ、以下のように
	make pdfdocs
	make psdocs
	make htmldocs
	make mandocs
コマンドを実行するとメインカーネルのソースディレクトリから
それぞれ、PDF, Postscript, HTML, man page の形式で生成されます。

カーネル開発者になるには
---------------------------

もしあなたが、Linux カーネル開発について何も知らないならば、
KernelNewbies プロジェクトを見るべきです
	http://kernelnewbies.org

このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関
するほとんどどんな種類の質問もできます (既に回答されているようなことを
聞く前にまずはアーカイブを調べてください)。
またここには、リアルタイムで質問を聞くことができる IRC チャネルや、Linux
カーネルの開発に関して学ぶのに便利なたくさんの役に立つドキュメントがあ
ります。

web サイトには、コードの構成、サブシステム、現在存在するプロジェクト(ツ
リーにあるもの無いものの両方)の基本的な管理情報があります。
ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接
的な基本情報も記述されています。

あなたがどこからスタートしてよいかわからないが、Linux カーネル開発コミュ
ニティに参加して何かすることをさがしている場合には、Linux kernel
Janitor's プロジェクトにいけばよいでしょう -
	http://janitor.kernelnewbies.org/
ここはそのようなスタートをするのにうってつけの場所です。ここには、
Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな
らない、単純な問題のリストが記述されています。このプロジェクトに関わる
開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入
れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ
ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。

もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入
れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネル
メンターズプロジェクトはそのような皆さんを助けるためにできました。
ここにはメーリングリストがあり、以下から参照できます
	http://selenic.com/mailman/listinfo/kernel-mentors

実際に Linux カーネルのコードについて修正を加える前に、どうやってその
コードが動作するのかを理解することが必要です。そのためには、特別なツー
ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど
のトリッキーな部分は十分にコメントしてありますから)。そういうツールで
特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、
自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
ます-
	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 によってメンテナンスされ、kernel.org
の pub/linux/kernel/v2.6/ ディレクトリに存在します。この開発プロセスは
以下のとおり-

  - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、
    この期間中に、メンテナー達は Linus に大きな差分を送ることができま
    す。このような差分は通常 -mm カーネルに数週間含まれてきたパッチで
    す。 大きな変更は git(カーネルのソース管理ツール、詳細は
    http://git.or.cz/  参照) を使って送るのが好ましいやり方ですが、パッ
    チファイルの形式のまま送るのでも十分です。

  - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定
    性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと
    はできません。新しいドライバ(もしくはファイルシステム)のパッチは
    -rc1 の後で受け付けられることもあることを覚えておいてください。な
    ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え
    ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、
    Linus へパッチを送付するのに git を使うこともできますが、パッチは
    レビューのために、パブリックなメーリングリストへも同時に送る必要が
    あります。

  - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分
    に安定した状態にあると判断したときにリリースされます。目標は毎週新
    しい -rc カーネルをリリースすることです。

  - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま
    す。このプロセスはだいたい 6週間継続します。

Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ
て書いたことをここで言っておくことは価値があります-
  「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現
  実に認識されたバグの状況によりリリースされるのであり、前もって決めら
  れた計画によってリリースされるものではないからです。」

2.6.x.y -stable カーネルツリー
---------------------------

バージョンに4つ目の数字がついたカーネルは -stable カーネルです。これに
は、2.6.x カーネルで見つかったセキュリティ問題や重大な後戻りに対する比
較的小さい重要な修正が含まれます。

これは、開発/実験的バージョンのテストに協力することに興味が無く、
最新の安定したカーネルを使いたいユーザに推奨するブランチです。

もし、2.6.x.y カーネルが存在しない場合には、番号が一番大きい 2.6.x
が最新の安定版カーネルです。

2.6.x.y は "stable" チーム [email blocked] でメンテされており、だ
いたい隔週でリリースされています。

カーネルツリーに入っている、Documentation/stable_kernel_rules.txt ファ
イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ
リースプロセスがどう動くかが記述されています。

2.6.x -git パッチ
------------------

git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ
ショットがあります。(だから -git という名前がついています)。これらのパッ
チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ
れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的
に生成されるので、より実験的です。

2.6.x -mm カーネルパッチ
------------------------

Andrew Morton によってリリースされる実験的なカーネルパッチ群です。
Andrew は個別のサブシステムカーネルツリーとパッチを全て集めてきて
linux-kernel メーリングリストで収集された多数のパッチと同時に一つにま
とめます。
このツリーは新機能とパッチが検証される場となります。ある期間の間パッチ
が -mm に入って価値を証明されたら、Andrew やサブシステムメンテナが、メ
インラインへ入れるように Linus にプッシュします。

メインカーネルツリーに含めるために Linus に送る前に、すべての新しいパッ
チが -mm ツリーでテストされることが強く推奨されます。

これらのカーネルは安定して動作すべきシステムとして使うのには適切ではあ
りませんし、カーネルブランチの中でももっとも動作にリスクが高いものです。

もしあなたが、カーネル開発プロセスの支援をしたいと思っているのであれば、
どうぞこれらのカーネルリリースをテストに使ってみて、そしてもし問題があ
れば、またもし全てが正しく動作したとしても、linux-kernel メーリングリ
ストにフィードバックを提供してください。

すべての他の実験的パッチに加えて、これらのカーネルは通常リリース時点で
メインラインの -git カーネルに含まれる全ての変更も含んでいます。

-mm カーネルは決まったスケジュールではリリースされません、しかし通常幾
つかの -mm カーネル (1 から 3 が普通）が各-rc カーネルの間にリリースさ
れます。

サブシステム毎のカーネルツリーとパッチ
-------------------------------------------

カーネルの様々な領域で何が起きているかを見られるようにするため、多くの
カーネルサブシステム開発者は彼らの開発ツリーを公開しています。これらの
ツリーは説明したように -mm カーネルリリースに入れ込まれます。

以下はさまざまなカーネルツリーの中のいくつかのリスト-

  git ツリー-
    - Kbuild の開発ツリー、Sam Ravnborg [email blocked]
	kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git

    - ACPI の開発ツリー、 Len Brown <len.brown@intel.com>
	kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git

    - Block の開発ツリー、Jens Axboe [email blocked]
	kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git

    - DRM の開発ツリー、Dave Airlie [email blocked]
	kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git

    - ia64 の開発ツリー、Tony Luck <tony.luck@intel.com>
	kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git

    - ieee1394 の開発ツリー、Jody McIntyre [email blocked]
	kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git

    - infiniband, Roland Dreier [email blocked]
	kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git

    - libata, Jeff Garzik [email blocked]
	kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git

    - ネットワークドライバ, Jeff Garzik [email blocked]
	kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git

    - pcmcia, Dominik Brodowski [email blocked]
	kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git

    - SCSI, James Bottomley <James.Bottomley@SteelEye.com>
	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 blocked]
	kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/

バグレポート
-------------

bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する
場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。
どう kernel bugzilla を使うかの詳細は、以下を参照してください-
	http://test.kernel.org/bugzilla/faq.html

メインカーネルソースディレクトリにあるファイル REPORTING-BUGS はカーネ
ルバグらしいものについてどうレポートするかの良いテンプレートであり、問
題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳
細が書かれています。

メーリングリスト
-------------

上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分
は Linux kernel メーリングリストに参加しています。このリストの登録/脱
退の方法については以下を参照してください-
	http://vger.kernel.org/vger-lists.html#linux-kernel

このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ
れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば-
	http://dir.gmane.org/gmane.linux.kernel

リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索
することを是非やってください。多数の事がすでに詳細に渡って議論されて
おり、アーカイブにのみ記録されています。

大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス
トを持っています。個々のグループがどんなリストを持っているかは、
MAINTAINERS ファイルにリストがありますので参照してください。

多くのリストは kernel.org でホストされています。これらの情報は以下にあ
ります-
	http://vger.kernel.org/vger-lists.html

メーリングリストを使う場合、良い行動習慣に従うようにしましょう。
少し安っぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合の
シンプルなガイドラインを示しています-
	http://www.albion.com/netiquette/

もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは
だいぶ多くなるでしょう。良い理由がない場合、CC: リストから誰かを削除を
しないように、また、メーリングリストのアドレスだけにリプライすることの
ないようにしましょう。1つは送信者から、もう1つはリストからのように、メー
ルを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追加し
てこの状態を変えようとしないように。人々はそのようなことは好みません。

今までのメールでのやりとりとその間のあなたの発言はそのまま残し、
"John Kernlehacker wrote ...:" の行をあなたのリプライの先頭行にして、
メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
す。

もしパッチをメールに付ける場合は、Documentaion/SubmittingPatches に提
示されているように、それは プレーンな可読テキストにすることを忘れない
ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま
せん-
彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす
るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう
に確認した方がいいです。最初の良いテストとしては、自分にメールを送って
みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな
ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ
きです。

とりわけ、他の登録者に対する尊敬を表すようにすることを覚えておいてくだ
さい。

コミュニティと共に働くこと
--------------------------

カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること
です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術
的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ
うか?
  - 批判
  - コメント
  - 変更の要求
  - パッチの正当性の証明要求
  - 沈黙

思い出してください、ここはあなたのパッチをカーネルに入れる話です。あ
なたは、あなたのパッチに対する批判とコメントを受け入れるべきで、それら
を技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべ
きでないかを明確で簡潔な理由の説明を提供してください。
もし、あなたのパッチに何も反応がない場合、たまにはメールの山に埋もれて
見逃され、あなたの投稿が忘れられてしまうこともあるので、数日待って再度
投稿してください。

あなたがやるべきでないものは?
  - 質問なしにあなたのパッチが受け入れられると想像すること
  - 守りに入ること
  - コメントを無視すること
  - 要求された変更を何もしないでパッチを出し直すこと

可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく
らい有益なのかについては常に異なる意見があります。あなたは協調的である
べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ
うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ
だけの価値があるとすすんで証明するようにしなければなりません。
正しい解決に向かって進もうという意志がある限り、間違うことがあっても許
容されることを忘れないでください。

あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ
とも普通のことです。これはあなたのパッチが受け入れられないということで
は *ありません*、そしてあなた自身に反対することを意味するのでも *ありま
せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば
いいのです。

カーネルコミュニティと企業組織のちがい
-----------------------------------------------------------------

カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で
動いています。以下は問題を避けるためにできるとよいことののリストです-

  あなたの提案する変更について言うときのうまい言い方：

    - "これは複数の問題を解決します"
    - "これは2000行のコードを削除します"
    - "以下のパッチは、私が言おうとしていることを説明するものです"
    - "私はこれを5つの異なるアーキテクチャでテストしたのですが..."
    - "以下は一連の小さなパッチ群ですが..."
    - "これは典型的なマシンでの性能を向上させます.."

  やめた方がいい悪い言い方：

    - このやり方で AIX/ptx/Solaris ではできたので、できるはずだ
    - 私はこれを20年もの間やってきた、だから
    - これは、私の会社が金儲けをするために必要だ
    - これは我々のエンタープライズ向け商品ラインのためである
    - これは 私が自分のアイディアを記述した、1000ページの設計資料である
    - 私はこれについて、6ケ月作業している。
    - 以下は ... に関する5000行のパッチです
    - 私は現在のぐちゃぐちゃを全部書き直した、それが以下です...
    - 私は〆切がある、そのためこのパッチは今すぐ適用される必要がある

カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労
働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。
email と irc を第一のコミュニケーションの形とする一つの利点は、性別や
民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受
容します。なぜなら、email アドレスによってのみあなたが認識されるからで
す。
国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた
は人の名前で性別を想像できないからです。ある男性が アンドレアという名
前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、
それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は
Patricia (主に女性名)や Patrick (主に男性名)の略称)。
Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前
向きな経験をもっています。

言葉の壁は英語が得意でない一部の人には問題になります。
メーリングリストの中できちんとアイディアを交換するには、相当うまく英語
を操れる必要があることもあります。そのため、あなたは自分のメール
を送る前に英語で意味が通じているかをチェックすることをお薦めします。

変更を分割する
---------------------

Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ
とはありません。変更は正確に説明される必要があり、議論され、小さい、個
別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて
きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと
ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい
ることにフィードバックを得られます。これは、コミュニティからみれば、あ
なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の
ゴミ捨て場として使っているのではない、と感じられるでしょう。
しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは
やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ
くなければなりません。

パッチを分割する理由は以下です-

1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー
   ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか
   らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。し
   かし、500行のパッチは、正しいことをレビューするのに数時間かかるかも
   しれません(時間はパッチのサイズなどにより指数関数に比例してかかりま
   す)
   小さいパッチは何かあったときにデバッグもとても簡単になります。パッ
   チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお
   かしくなった後で)解剖するのに比べればとても簡単です。

2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす
   る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。

以下はカーネル開発者の Al Viro のたとえ話しです：

        "生徒の数学の宿題を採点する先生のことを考えてみてください、先
        生は生徒が解に到達するまでの試行錯誤をみたいとは思わないでしょ
        う。先生は簡潔な最高の解をみたいのです。良い生徒はこれを知って
        おり、そして最終解の前の中間作業を提出することは決してないので
        す"
        カーネル開発でもこれは同じです。メンテナー達とレビューア達は、
        問題を解決する解の背後になる思考プロセスをみたいとは思いません。
        彼らは単純であざやかな解決方法をみたいのです。

あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を
議論することのバランスをキープするのは難しいかもしれません。
ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ
うにするのもいいですが、変更点を小さい部分に分割して全体ではまだ完成し
ていない仕事を(部分的に)取り込んでもらえるようにすることもいいことです。

また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め
てもらうように送っても、それは受け付けられないことを理解してください。

あなたの変更を正当化する
-------------------

あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな
いかを Linux コミュニティに知らせることはとても重要です。新機能は必要
性と有用性で正当化されなければなりません。

あなたの変更の説明
--------------------

あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ
いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ
れ、いつも皆がみられるように保管されます。これは次のような項目を含め、
パッチを完全に記述するべきです-

  - なぜ変更が必要か
  - パッチ全体の設計アプローチ
  - 実装の詳細
  - テスト結果

これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ
ントの ChangeLog セクションをみてください-
  "The Perfect Patch"
      http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

これらのどれもが、時にはとても困難です。これらの慣例を完璧に実施するに
は数年かかるかもしれません。これは継続的な改善のプロセスであり、そのた
めには多数の忍耐と決意を必要とするものです。でも、諦めないで、これは可
能なことです。多数の人がすでにできていますし、彼らも皆最初はあなたと同
じところからスタートしたのですから。

Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process"
(http://linux.tar.bz/articles/2.6-development_process)セクショ
ンをこのテキストの原型にすることを許可してくれました。
Rundy 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
彼らの支援なしでは、このドキュメントはできなかったでしょう。

Maintainer: Greg Kroah-Hartman [email blocked]

From: IKEDA Munehiro [email blocked]
Subject: [RFD] Documentation/stable_api_nonsense.txt translated into Japanese
Date:	Sun, 10 Jun 2007 21:03:15 +0900

This is Japanese translation of "stable_api_nonsense.txt",
which is based on the same motivation of Tsugikazu Shibata.

-----------------------------------------------------------------
Below lines are Japanese Translation of "stable_api_nonsense.txt"
-----------------------------------------------------------------

Signed-off-by: IKEDA, Munehiro [email blocked]
---
==================================
これは、
linux-2.6.19/Documentation/stable_api_nonsense.txt の和訳
です。
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日 ： 2006/12/3
原著作者: Greg Kroah-Hartman < greg at kroah dot com >
翻訳者 ： 池田 宗広 < m-ikeda at ds dot jp dot nec dot com >
校正者 ： Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp >
          Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp >
==================================

Linux カーネルのドライバインターフェース
（あなたの質問すべてに対する回答とその他諸々）

Greg Kroah-Hartman <greg at kroah dot com>

この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義
されていないのか、またはなぜ不変のカーネルインターフェースを持たな
いのか、ということを説明するために書かれた。ここでの話題は「カーネ
ル内部の」インターフェースについてであり、ユーザー空間とのインター
フェースではないことを理解してほしい。カーネルとユーザー空間とのイ
ンターフェースとはアプリケーションプログラムが使用するものであり、
つまりシステムコールのインターフェースがこれに当たる。これは今まで
長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か
より前のカーネルを使ってビルドした古いプログラムを持っているが、そ
れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン
ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼
してよいものの一つである。

要旨
----

あなたは不変のカーネルインターフェースが必要だと考えているかもしれ
ないが、実際のところはそうではない。あなたは必要としているものが分
かっていない。あなたが必要としているものは安定して動作するドライバ
であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得
ることができる。ドライバがメインのカーネルツリーに含まれていると、
他にも多くの良いことがある。それは、Linux をより強固で、安定な、成
熟したオペレーティングシステムにすることができるということだ。これ
こそ、そもそもあなたが Linux を使う理由のはずだ。

はじめに
--------

カーネル内部のインターフェース変更を心配しなければならないドライバ
を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、
そのようなドライバがどんなインターフェースを使っているかなど知らな
いし、そんなドライバのことなど全く気にもかけていない。

まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの
みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ
コードでそれを読み込むためのラッパー部分のみソースコードが公開され
ているとか、その他用語は何であれ GPL の下にソースコードがリリース
されていないカーネルドライバに関する法的な問題について、私は「いか
なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ
である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問
題について述べることにする。（法的な問題を軽視しているわけではない。
それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が
ある）

訳注(1)
「使い物にならない代物」の原文は "blob"

さてここでは、バイナリカーネルインターフェースについてと、ソースレ
ベルでのインターフェースの不変性について、という二つの話題を取り上
げる。この二つは互いに依存する関係にあるが、まずはバイナリインター
フェースについて議論を行いやっつけてしまおう。

バイナリカーネルインターフェース
--------------------------------

もしソースレベルでのインターフェースが不変ならば、バイナリインター
フェースも当然のように不変である、というのは正しいだろうか？正しく
ない。Linux カーネルに関する以下の事実を考えてみてほしい。
  - あなたが使用するＣコンパイラのバージョンによって、カーネル内部
    の構造体の配置構造は異なったものになる。また、関数は異なった方
    法でカーネルに含まれることになるかもしれない（例えばインライン
    関数として扱われたり、扱われなかったりする）。個々の関数がどの
    ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ
    ィングが異なるというのは非常に重要である。
  - あなたがカーネルのビルドオプションをどのように設定するかによっ
    て、カーネルには広い範囲で異なった事態が起こり得る。
      - データ構造は異なるデータフィールドを持つかもしれない
      - いくつかの関数は全く実装されていない状態になり得る
        （例：SMP向けではないビルドでは、いくつかのロックは中身が
          カラにコンパイルされる）
      - 関数から関数への引数の受け渡しは、異なる方法で行われる可能
        性がある（CONFIG_REGPARM オプションがこれを制御している）
      - カーネル内のメモリは、異なった方法で配置され得る。これはビ
        ルドオプションに依存している。
  - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。
    あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで
    正常に動作させる方法はない。

ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ
Ｃコンパイラを使用して単にカーネルモジュールをコンパイルするだけで
も、あなたはこれらいくつもの問題に直面することになる。ある特定の
Linux ディストリビューションの、ある特定のリリースバージョン用にモ
ジュールを提供しようと思っただけでも、これらの問題を引き起こすには
十分である。にも関わらず Linux ディストリビューションの数と、サ
ポートするディストリビューションのリリース数を掛け算し、それら一つ
一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ
ションの違いという悪夢にすぐさま悩まされることになる。また、ディス
トリビューションの各リリースバージョンには、異なるハードウェア（プ
ロセッサタイプや種々のオプション）に対応するため、何種類かのカーネ
ルが含まれているということも理解して欲しい。従って、ある一つのリ
リースバージョンだけのためにモジュールを作成する場合でも、あなたは
何バージョンものモジュールを用意しなければならない。

信じて欲しい。このような方法でサポートを続けようとするなら、あなた
はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身
をもって学んだのだ・・・

不変のカーネルソースレベルインターフェース
------------------------------------------

メインカーネルツリーに含まれていない Linux カーネルドライバを継続
してサポートしていこうとしている人たちとの議論においては、これは極
めて「引火性の高い」話題である。[訳注(2)]

訳注(2)
「引火性の高い」の原文は "valatile"。
valatile には「揮発性の」「爆発しやすい」という意味の他、「変わり
やすい」「移り気な」という意味がある。
「（この話題は）爆発的に激しい論争を巻き起こしかねない」ということ
を、「（カーネルのソースレベルインターフェースは）移ろい行くもので
ある」ということを連想させる "valatile" という単語で表現している。

Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め
ることがない。その中でカーネル開発者達は、現状のインターフェースに
あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン
ターフェースがより正しく動作するように修正を行う。その過程で関数の
名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし
れず、関数の引数は検討しなおされるかもしれない。そのような場合、引
き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー
スを使用している個所も全て同時に修正される。

具体的な例として、カーネル内の USB インターフェースを挙げる。USB
サブシステムはこれまでに少なくとも３回の書き直しが行われ、その結果
インターフェースが変更された。これらの書き直しはいくつかの異なった
問題を修正するために行われた。
  - 同期的データストリームが非同期に変更された。これにより多数のド
    ライバを単純化でき、全てのドライバのスループットが向上した。今
    やほとんど全ての USB デバイスは、考えられる最高の速度で動作し
    ている。
  - USB ドライバが USB サブシステムのコアから行う、データパケット
    用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ
    れたデッドロック条件を回避するため、全ての USB ドライバはより
    多くの情報を USB コアに提供しなければならないようになっている。

このできごとは、数多く存在するクローズソースのオペレーティングシス
テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース
をメンテナンスしなければならない。古いインターフェースが残ることで、
新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発
を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ
らされることになる。

上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で
あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ
ベルでインターフェースの不変性を保証しなければならないとしたら、新
しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ
ンテナンスするという余計な仕事を USB の開発者にさせなければならな
い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ
て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。

セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ
ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正
される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ
ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ
れたインターフェースを使用する全てのドライバもまた変更された。これ
により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ
れる。もし内部インターフェースの変更が許されないとしたら、このよう
にセキュリティ問題を修正し、将来再発しないことを保証することなど不
可能なのだ。

カーネルのインターフェースは時が経つにつれクリーンナップを受ける。
誰も使っていないインターフェースは削除される。これにより、可能な限
りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り
テストされることを保証しているのだ。（使われていないインターフェー
スの妥当性をテストすることは不可能と言っていいだろう）

これから何をすべきか
-----------------------

では、もしメインのカーネルツリーに含まれない Linux カーネルドライ
バがあったとして、あなたは、つまり開発者は何をするべきだろうか？全
てのディストリビューションの全てのカーネルバージョン向けにバイナリ
のドライバを供給することは悪夢であり、カーネルインターフェースの変
更を追いかけ続けることもまた過酷な仕事だ。

答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ
い。（ここで言及しているのは、GPL に従って公開されるドライバのこと
だということに注意してほしい。あなたのコードがそれに該当しないなら
ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew
と Linus からのコメント＜Andrew と Linus のコメントへのリンクをこ
こに置く＞をどうぞ）ドライバがメインツリーに入れば、カーネルのイン
ターフェースが変更された場合、変更を行った開発者によってドライバも
修正されることになるだろう。あなたはほとんど労力を払うことなしに、
常にビルド可能できちんと動作するドライバを手に入れることができる。

ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効
果がある。
  - ドライバの品質が向上する一方で、（元の開発者にとっての）メンテ
    ナンスコストは下がる。
  - あなたのドライバに他の開発者が機能を追加してくれる。
  - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。
  - 誰かがあなたのドライバにある改善点を見つけてくれる。
  - 外部インターフェースが変更されドライバの更新が必要になった場合、
    誰かがあなたの代わりに更新してくれる。
  - ドライバを入れてくれとディストロに頼まなくても、そのドライバは
    全ての Linux ディストリビューションに自動的に含まれてリリース
    される。

Linux では、他のどのオペレーティングシステムよりも数多くのデバイス
が「そのまま」使用できるようになった。また Linux は、どのオペレー
ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの
デバイスを使用することができるようにもなった。このように、Linux の
開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい
くだろう。:)

------

この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David
Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読
と助言を頂きました。感謝申し上げます。

From: Jesper Juhl [email blocked]
Subject: Re: [RFD] Documentation/HOWTO translated into Japanese
Date:	Sun, 10 Jun 2007 14:24:51 +0200

On 10/06/07, Tsugikazu Shibata [email blocked] wrote:
> Hi all,
>
> I am posting Documentation/HOWTO which is translated into Japanese at
> bottom of this email.

Good job. I'm sure a lot of japanese people will appreciate that.

> This document had been reviewed by JF project which has long history
> to translate documents into Japanese. (not only kernel but also FAQs).
> For JF, please see : http://www.linux.or.jp/JF/index.html
> Please also note that the page is written in Japanese, but you can see
> a lot of results there.
>
> Actually, this is my first trial to post Japanese translated document
> and here are some points I decided ;
>
> - Character encoding is ISO-2022-JP, which is normally used for email
>   using Japanese.

I think there's consensus that documents in the kernel source should
be either plain ASCII or UTF-8 (doesn't UTF-8 work for japanese?).

> - Added "Singed-off-by" line
> - Left the JF header strings which include translator/reviewer's name
> - Non-patch format, simple text
>
> I would be happy if I could get your comments and suggestions.
> Though I know there are several issues to merge it, I want to have
> discussions with you to accomplish it.
>
> This email comes from strong recommendation from Greg K-H when he came
> to Tokyo two weeks ago. Thanks >Greg
>
> ----- Below lines are Japanese Translation of "HOWTO" -----
>
> Signed-off-by: Tsugikazu Shibata [email blocked]
> ---

Unfortunately I don't speak japanese so I can't say anything about the
translation at all, but I do have some other comments/questions.

If we start adding translated versions of documentation to the kernel
source how should we organize the documents? Should each language get
a sepperate directory in Documentation/ - like Documentation/JP/,
Documentation/EN/, Documentation/DA/ etc?

With multiple translated versions of the documentation in the tree,
don't we run the risk that the translations will quickly become
outdated since most people updating the documentation won't be able to
update the translations?

Since the common language of most kernel contributors is english I
personally feel that we should stick to just that one language in the
tree and then perhaps keep translations on a website somewhere. So the
authoritative docs stay in the tree, in english, so that as many
contributors as possible can read and update them. It would then be a
seperate project to generate translations and keep them updated
according to what's in the tree.  Perhaps we could get the kernel.org
people to create an official space for that and then place a pointer
to that site in Documentation/ somewhere.

-- 
Jesper Juhl [email blocked]
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html

From: IKEDA Munehiro [email blocked]
Subject: Re: [RFD] Documentation/HOWTO translated into Japanese
Date:	Sun, 10 Jun 2007 23:25:09 +0900

Jesper Juhl wrote:
>> - Character encoding is ISO-2022-JP, which is normally used for email
>>   using Japanese.
> 
> 
> I think there's consensus that documents in the kernel source should
> be either plain ASCII or UTF-8 (doesn't UTF-8 work for japanese?).

Oh really?
UTF-8 works even for Japanese.  Thank you and Jan for the suggestion.

> If we start adding translated versions of documentation to the kernel
> source how should we organize the documents? Should each language get
> a sepperate directory in Documentation/ - like Documentation/JP/,
> Documentation/EN/, Documentation/DA/ etc?
> 
> With multiple translated versions of the documentation in the tree,
> don't we run the risk that the translations will quickly become
> outdated since most people updating the documentation won't be able to
> update the translations?
> 
> Since the common language of most kernel contributors is english I
> personally feel that we should stick to just that one language in the
> tree and then perhaps keep translations on a website somewhere. So the
> authoritative docs stay in the tree, in english, so that as many
> contributors as possible can read and update them. It would then be a
> seperate project to generate translations and keep them updated
> according to what's in the tree.  Perhaps we could get the kernel.org
> people to create an official space for that and then place a pointer
> to that site in Documentation/ somewhere.

Yes, that's the point.

At least for Japanese, there is a great activity "JF" as Tsugikazu 
Shibata mentioned.  It is a separate project from the tree, and it often 
happens that some documentations are outdated.  If we could merge them, 
they could be kept up-to-date IMHO.
But, on the other hand, it is fact that kernel tar ball would bloat.

Your opinion above as "creating official space in kernel.org and putting 
pointer in Documentation" seems good for me.

Hmm...

--
IKEDA, Munehiro

From: Greg KH [email blocked]
Subject: Re: [RFD] Documentation/HOWTO translated into Japanese
Date:	Sun, 10 Jun 2007 09:22:21 -0700

On Sun, Jun 10, 2007 at 02:24:51PM +0200, Jesper Juhl wrote:
>  On 10/06/07, Tsugikazu Shibata [email blocked] wrote:
> > Hi all,
> >
> > I am posting Documentation/HOWTO which is translated into Japanese at
> > bottom of this email.

Great, thanks for posting this and doing the work.

> > This document had been reviewed by JF project which has long history
> > to translate documents into Japanese. (not only kernel but also FAQs).
> > For JF, please see : http://www.linux.or.jp/JF/index.html
> > Please also note that the page is written in Japanese, but you can see
> > a lot of results there.
> >
> > Actually, this is my first trial to post Japanese translated document
> > and here are some points I decided ;
> >
> > - Character encoding is ISO-2022-JP, which is normally used for email
> >   using Japanese.
> 
>  I think there's consensus that documents in the kernel source should
>  be either plain ASCII or UTF-8 (doesn't UTF-8 work for japanese?).

Is it hard to convert it to UTF-8?

> > - Added "Singed-off-by" line
> > - Left the JF header strings which include translator/reviewer's name
> > - Non-patch format, simple text
> >
> > I would be happy if I could get your comments and suggestions.
> > Though I know there are several issues to merge it, I want to have
> > discussions with you to accomplish it.
> >
> > This email comes from strong recommendation from Greg K-H when he came
> > to Tokyo two weeks ago. Thanks >Greg
> >
> > ----- Below lines are Japanese Translation of "HOWTO" -----
> >
> > Signed-off-by: Tsugikazu Shibata [email blocked]
> > ---
> 
>  Unfortunately I don't speak japanese so I can't say anything about the
>  translation at all, but I do have some other comments/questions.
> 
>  If we start adding translated versions of documentation to the kernel
>  source how should we organize the documents? Should each language get
>  a sepperate directory in Documentation/ - like Documentation/JP/,
>  Documentation/EN/, Documentation/DA/ etc?
> 
>  With multiple translated versions of the documentation in the tree,
>  don't we run the risk that the translations will quickly become
>  outdated since most people updating the documentation won't be able to
>  update the translations?

That's up to the people maintaining the translations to do.

>  Since the common language of most kernel contributors is english I
>  personally feel that we should stick to just that one language in the
>  tree and then perhaps keep translations on a website somewhere. So the
>  authoritative docs stay in the tree, in english, so that as many
>  contributors as possible can read and update them. It would then be a
>  seperate project to generate translations and keep them updated
>  according to what's in the tree.  Perhaps we could get the kernel.org
>  people to create an official space for that and then place a pointer
>  to that site in Documentation/ somewhere.

No, I think the translated files should be in the tree proper, we have
the space :)

thanks,

greg k-h

From: Matthias Schniedermeyer [email blocked]
Subject: Re: [RFD] Documentation/HOWTO translated into Japanese
Date:	Sun, 10 Jun 2007 19:56:52 +0200

Greg KH wrote:
> On Sun, Jun 10, 2007 at 02:24:51PM +0200, Jesper Juhl wrote:
>>  Since the common language of most kernel contributors is english I
>>  personally feel that we should stick to just that one language in the
>>  tree and then perhaps keep translations on a website somewhere. So the
>>  authoritative docs stay in the tree, in english, so that as many
>>  contributors as possible can read and update them. It would then be a
>>  seperate project to generate translations and keep them updated
>>  according to what's in the tree.  Perhaps we could get the kernel.org
>>  people to create an official space for that and then place a pointer
>>  to that site in Documentation/ somewhere.
> 
> No, I think the translated files should be in the tree proper, we have
> the space :)

Frankly i don't see the difference between this and the annual reoccurring 
"why can't the kernel messages be localized" discussion.
(Which is a little overdue, but maybe this replaces it this time.)

I could see the point in ONE "HOWTO" file per language to get people started, 
but everything else is a pointless exercise. A developer/bug-reporter has to 
be able to express him-/herself in English and understand English, otherwise 
you can not accomplish very much.

All the points of the localized-messages discussion:
- You have to have a common language, otherwise you can't communicate.
- The translation will per definition be out of sync
- Translations tend to introduce (translation-)errors
- ...
also apply here.

A little anecdote:
Very Long ago (last millennium i think) SuSE defaulted to a german 
translated kernel for one release of their distribution. (And optionally 
for a few more) But even though i'm german i couldn't understand a single word.

And here is the FAQ-Entry about the annually reoccurring discussion:
http://www.tux.org/lkml/#s9-16

Bis denn

-- 
Real Programmers consider "what you see is what you get" to be just as
bad a concept in Text Editors as it is in women. No, the Real Programmer
wants a "you asked for it, you got it" text editor -- complicated,
cryptic, powerful, unforgiving, dangerous.

From: Greg KH [email blocked]
Subject: Re: [RFD] Documentation/HOWTO translated into Japanese
Date:	Sun, 10 Jun 2007 23:07:59 -0700

On Sun, Jun 10, 2007 at 07:56:52PM +0200, Matthias Schniedermeyer wrote:
>  Greg KH wrote:
> > On Sun, Jun 10, 2007 at 02:24:51PM +0200, Jesper Juhl wrote:
> >>  Since the common language of most kernel contributors is english I
> >>  personally feel that we should stick to just that one language in the
> >>  tree and then perhaps keep translations on a website somewhere. So the
> >>  authoritative docs stay in the tree, in english, so that as many
> >>  contributors as possible can read and update them. It would then be a
> >>  seperate project to generate translations and keep them updated
> >>  according to what's in the tree.  Perhaps we could get the kernel.org
> >>  people to create an official space for that and then place a pointer
> >>  to that site in Documentation/ somewhere.
> > No, I think the translated files should be in the tree proper, we have
> > the space :)
> 
>  Frankly i don't see the difference between this and the annual reoccurring 
>  "why can't the kernel messages be localized" discussion.
>  (Which is a little overdue, but maybe this replaces it this time.)

It is _vastly_ different.

>  I could see the point in ONE "HOWTO" file per language to get people 
>  started, but everything else is a pointless exercise.
>  A developer/bug-reporter has to be able to express him-/herself in English 
>  and understand English, otherwise you can not accomplish very much.

Yes, but this file, and the stable-api-nonsense.txt files are there to
help people understand both the kernel's philosophy, as well as
encourage them to help contribute.

That is totally different from internationalizing the internal kernel
messages (which, btw, some people are working on...)  That I would not
agree to as it's just too hard to keep up with and would be pointless in
a way.

So I really do want to see a translated copy of the HOWTO,
stable-api-nonsense.txt, and possibly a few other files in the main
kernel tree (SubmittingPatches, CodingStyle, and SubmittingDrivers might
all be good canidates for this.)  These files change relativly
infrequently (the HOWTO file has had only 7 changes in 1 and 1/2 years,
and they were very minor ones) and should be easy for the translators to
keep up with.

So, Tsugikazu, care to resend this file as a patch that I can apply to
the Documentation directory of the kernel tree?  I think it would be
good to have there.

thanks,

greg k-h

From: KAMEZAWA Hiroyuki [email blocked]
Subject: Re: [RFD] Documentation/HOWTO translated into Japanese
Date:	Mon, 11 Jun 2007 11:55:57 +0900

Hi, thank you for your work. I was impressed.

BTW, how about adding following lines (both in Japanese and English) ?
==
This is translated "HOWTO" documentation. Original "HOWTO" is maintaind by 
Greg Kroah-Hartman [email blocked] and linux kernal mailing list.
And this one is maintained by Tsugikazu Shibata <tsugikazu.shibata@jp.nec.com>
and JF Projet <www.linux.or.jp/JF>. Because original HOWTO documentation itself
is being updated day and night, this file may contain old sentences. Please contact
JF project if you find problems in translation.

It is guaranteed that this file is just a translation and doesn't contains any
additional information, sentences. If you want to update "HOWTO", please update
English version first. Don't fork from original if you update this file.

Last Updated: 2007/06/04  Version: 2.6.21
==

not worth writing ?

-Kame

From: Greg KH [email blocked]
Subject: Re: [RFD] Documentation/HOWTO translated into Japanese
Date:	Sun, 10 Jun 2007 23:09:06 -0700

On Mon, Jun 11, 2007 at 11:55:57AM +0900, KAMEZAWA Hiroyuki wrote:
> 
> Hi, thank you for your work. I was impressed.
> 
> BTW, how about adding following lines (both in Japanese and English) ?
> ==
> This is translated "HOWTO" documentation. Original "HOWTO" is maintaind by 
> Greg Kroah-Hartman [email blocked] and linux kernal mailing list.
> And this one is maintained by Tsugikazu Shibata <tsugikazu.shibata@jp.nec.com>
> and JF Projet <www.linux.or.jp/JF>. Because original HOWTO documentation itself
> is being updated day and night, this file may contain old sentences. Please contact
> JF project if you find problems in translation.
> 
> It is guaranteed that this file is just a translation and doesn't contains any
> additional information, sentences. If you want to update "HOWTO", please update
> English version first. Don't fork from original if you update this file.
> 
> Last Updated: 2007/06/04  Version: 2.6.21
> ==
> 
> not worth writing ?

That sounds fine with me, and would be good to have.  I also have no
problem also CC:ing anyone who wants to translate this file with patches
that happen to modify the originals.  That way they can easily keep up
with the minor number of changes that happen over time.

thanks,

greg k-h

From: Hiro Yoshioka [email blocked]
Subject: Re: [RFD] Documentation/HOWTO translated into Japanese
Date:	Mon, 11 Jun 2007 17:45:27 +0900

Hi,

Shibata san's contribution was really great. I was impressed too.

I think the important point is that Shibata san let the
linux kernel community knows the translation work has been done
and ask the feedback.

I think this two way communication is very important.

On 6/11/07, Greg KH [email blocked] wrote:
> On Mon, Jun 11, 2007 at 11:55:57AM +0900, KAMEZAWA Hiroyuki wrote:
> >
> > Hi, thank you for your work. I was impressed.
> >
> > BTW, how about adding following lines (both in Japanese and English) ?
> > ==
> > This is translated "HOWTO" documentation. Original "HOWTO" is maintaind by
> > Greg Kroah-Hartman [email blocked] and linux kernal mailing list.
> > And this one is maintained by Tsugikazu Shibata <tsugikazu.shibata@jp.nec.com>
> > and JF Projet <www.linux.or.jp/JF>. Because original HOWTO documentation itself
> > is being updated day and night, this file may contain old sentences. Please contact
> > JF project if you find problems in translation.
> >
> > It is guaranteed that this file is just a translation and doesn't contains any
> > additional information, sentences. If you want to update "HOWTO", please update
> > English version first. Don't fork from original if you update this file.
> >
> > Last Updated: 2007/06/04  Version: 2.6.21
> > ==
> >
> > not worth writing ?
>
> That sounds fine with me, and would be good to have.  I also have no
> problem also CC:ing anyone who wants to translate this file with patches
> that happen to modify the originals.  That way they can easily keep up
> with the minor number of changes that happen over time.

I think that some members of YLUG (Yokohama Linux Users Group)
may help to review the translations. :-)

Regards,
  Hiro
-- 
Hiro Yoshioka
mailto:hyoshiok at miraclelinux.com

From: Sam Ravnborg [email blocked]
Subject: kconfig .po files in kernel tree? [Was: Documentation/HOWTO translated into Japanese]
Date:	Sun, 10 Jun 2007 19:52:28 +0200

On Sun, Jun 10, 2007 at 09:22:21AM -0700, Greg KH wrote:
> >  Since the common language of most kernel contributors is english I
> >  personally feel that we should stick to just that one language in the
> >  tree and then perhaps keep translations on a website somewhere. So the
> >  authoritative docs stay in the tree, in english, so that as many
> >  contributors as possible can read and update them. It would then be a
> >  seperate project to generate translations and keep them updated
> >  according to what's in the tree.  Perhaps we could get the kernel.org
> >  people to create an official space for that and then place a pointer
> >  to that site in Documentation/ somewhere.
> 
> No, I think the translated files should be in the tree proper, we have
> the space :)

We once discussed about .po files for kconfig and back then
the conclusion was not to keep them in the kernel tree.

I advocated that they should stay out back then.
But on the other hand I do not see it causing much troubles
having scripts/kconfig/po/da.po etc araound.

Any opinion about the .po files?

	Sam

From: Jan Engelhardt [email blocked]
Subject: Re: kconfig .po files in kernel tree? [Was: Documentation/HOWTO translated into Japanese]
Date:	Sun, 10 Jun 2007 20:35:03 +0200 (CEST)

On Jun 10 2007 19:52, Sam Ravnborg wrote:
>> >  Since the common language of most kernel contributors is english I
>> >  personally feel that we should stick to just that one language in the
>> >  tree and then perhaps keep translations on a website somewhere. So the
>> >  authoritative docs stay in the tree, in english, so that as many
>> >  contributors as possible can read and update them. It would then be a
>> >  seperate project to generate translations and keep them updated
>> >  according to what's in the tree.  Perhaps we could get the kernel.org
>> >  people to create an official space for that and then place a pointer
>> >  to that site in Documentation/ somewhere.
>> 
>> No, I think the translated files should be in the tree proper, we have
>> the space :)
>
>We once discussed about .po files for kconfig and back then
>the conclusion was not to keep them in the kernel tree.
>
>I advocated that they should stay out back then.
>But on the other hand I do not see it causing much troubles
>having scripts/kconfig/po/da.po etc araound.
>
>Any opinion about the .po files?

Like with translated doc, they might get out of date easily.

	Jan

From: Denis Vlasenko <vda.linux@googlemail.com>
Subject: Re: kconfig .po files in kernel tree? [Was: Documentation/HOWTO translated into Japanese]
Date:	Mon, 11 Jun 2007 01:59:00 +0200

On Sunday 10 June 2007 20:58, Rene Herman wrote:
> All that stuff only serves to multiply the speed at which a fixed percentage 
> of content obsoletes itself. When it's still new and shiny, sure, stuff will 
> get translated but in no time at all it'll become a fragmented mess which 
> nobody ever feels right about removing because that would be anti-social to 
> all those poor non-english speaking kernel hackers out there.

I agree. i18n efforts won't help one iota because people just have
to know English in order to participate in l-k development.
They should be able to read _and_ reply_ to lkml posts,
and read and understnd code _and_ comments_.

Those who cannot participate in development because they don't
know English, won't get much help from some bits of semi-obsolete
Documentation/* being available. Ok, they will read it, then what?
How they are supposed to read the code? Write email? etc...

There is only one practical solution: learn the language.

It's not about *English* per se. It just happened so historically
that CS has originated in English speaking countries.

BTW, I learned it by reading sci-fi (Asimov's Foundation was the first thing),
and then lkml. :)
--
vda

From: Paul Mundt [email blocked]
Subject: Re: kconfig .po files in kernel tree? [Was: Documentation/HOWTO translated into Japanese]
Date:	Mon, 11 Jun 2007 09:56:13 +0900

On Mon, Jun 11, 2007 at 01:59:00AM +0200, Denis Vlasenko wrote:
> On Sunday 10 June 2007 20:58, Rene Herman wrote:
> > All that stuff only serves to multiply the speed at which a fixed
> > percentage of content obsoletes itself. When it's still new and
> > shiny, sure, stuff will get translated but in no time at all it'll
> > become a fragmented mess which nobody ever feels right about removing
> > because that would be anti-social to all those poor non-english
> > speaking kernel hackers out there.
> 
> I agree. i18n efforts won't help one iota because people just have
> to know English in order to participate in l-k development.

That's a ridiculous statement. Non-native language abilities and
technical competence have very little to do with each other. People have
to understand the code and figure out what it is that they want to
change. As long as this is done cleanly and the intent is obvious,
language doesn't even factor in beyond the Signed-off-by tag. Explanation
is necessary from time to time, but it really depends on the area in
which someone is working. If it's a complicated and involved change, then
of course it takes a bit more effort on both sides, but that doesn't
invalidate the importance or necessity of the work.

> They should be able to read _and_ reply_ to lkml posts,
> and read and understnd code _and_ comments_.
> 
> Those who cannot participate in development because they don't
> know English, won't get much help from some bits of semi-obsolete
> Documentation/* being available. Ok, they will read it, then what?
> How they are supposed to read the code? Write email? etc...
> 
It's arguable whether those that know English well derive any benefit
from semi-obsolete Documentation/* files either. One could speculate that
not being able to read semi-obsolete documentation and being forced to
read the code is actually more productive ;-)

Besides, Kconfig localization is more for the end users than the
developers anyways. I certainly don't see any problem with this, the more
people eyeballing the documentation, the easier it is to find out areas
where we're lacking or that are simply wrong.

> There is only one practical solution: learn the language.
> 
I suggest you step outside of your box and spend more time working with
people who speak little to none of the languages you understand.

From: Denis Vlasenko <vda.linux@googlemail.com>
Subject: Re: kconfig .po files in kernel tree? [Was: Documentation/HOWTO translated into Japanese]
Date:	Mon, 11 Jun 2007 09:46:11 +0200

On Monday 11 June 2007 02:56, Paul Mundt wrote:
> On Mon, Jun 11, 2007 at 01:59:00AM +0200, Denis Vlasenko wrote:
> > On Sunday 10 June 2007 20:58, Rene Herman wrote:
> > > All that stuff only serves to multiply the speed at which a fixed
> > > percentage of content obsoletes itself. When it's still new and
> > > shiny, sure, stuff will get translated but in no time at all it'll
> > > become a fragmented mess which nobody ever feels right about removing
> > > because that would be anti-social to all those poor non-english
> > > speaking kernel hackers out there.
> > 
> > I agree. i18n efforts won't help one iota because people just have
> > to know English in order to participate in l-k development.
> 
> That's a ridiculous statement. Non-native language abilities and
> technical competence have very little to do with each other. People have
> to understand the code and figure out what it is that they want to
> change. As long as this is done cleanly and the intent is obvious,
> language doesn't even factor in beyond the Signed-off-by tag. Explanation
> is necessary from time to time, but it really depends on the area in
> which someone is working. If it's a complicated and involved change, then
> of course it takes a bit more effort on both sides, but that doesn't
> invalidate the importance or necessity of the work.

Point me to one person who doesn't know English at all
and who has successfully participated in l-k devel.

I'm not saying that non-English should banned or something.
In Kconfig it can even make sense. A section on kernel.org
where people can put translations is also a good idea.
I can still think that it is almost useless activity,
but who knows, maybe I'm wrong.

Just not Documentation/<lang>/* thing and no i18n of printks.
--
vda

From: Paul Mundt [email blocked]
Subject: Re: kconfig .po files in kernel tree? [Was: Documentation/HOWTO translated into Japanese]
Date:	Mon, 11 Jun 2007 17:34:29 +0900

On Mon, Jun 11, 2007 at 09:46:11AM +0200, Denis Vlasenko wrote:
> On Monday 11 June 2007 02:56, Paul Mundt wrote:
> > That's a ridiculous statement. Non-native language abilities and
> > technical competence have very little to do with each other. People have
> > to understand the code and figure out what it is that they want to
> > change. As long as this is done cleanly and the intent is obvious,
> > language doesn't even factor in beyond the Signed-off-by tag. Explanation
> > is necessary from time to time, but it really depends on the area in
> > which someone is working. If it's a complicated and involved change, then
> > of course it takes a bit more effort on both sides, but that doesn't
> > invalidate the importance or necessity of the work.
> 
> Point me to one person who doesn't know English at all
> and who has successfully participated in l-k devel.
> 
There are entire architectures that have been merged and maintained by
folks who speak little to no english, for example. I'll let you figure
out which ones. Many drivers and such, too. Perhaps you've simply never
noticed since these folks tend not to be terribly vocal.

This is not to say that there aren't communication barriers, but things
do gradually get done in any case.

> I'm not saying that non-English should banned or something.
> In Kconfig it can even make sense. A section on kernel.org
> where people can put translations is also a good idea.
> I can still think that it is almost useless activity,
> but who knows, maybe I'm wrong.
> 
> Just not Documentation/<lang>/* thing and no i18n of printks.

Documentation/* is in enough disarray as it is, I think it's worth having
more people looking at it and verifying that things are up to date and
accurate, regardless of what language they happen to be working in.

Kconfig localization (is is that time of year already?) is another
problem entirely, and one that doesn't have a lot of chance of being kept
up to date. Documentation/* on the other hand isn't terribly prone to
heavy modification, I'd wager most people would rather be lining up to
voluntarily rewrite the floppy driver than even accidentally cd in to
Documentation/. In any event, the rate of change is far lower, and people
at least have a chance of keeping translations updated.

Documentation is one area where we simply suck, the more people working
on it, the better.

From: Greg KH [email blocked]
Subject: Re: kconfig .po files in kernel tree? [Was: Documentation/HOWTO translated into Japanese]
Date:	Sun, 10 Jun 2007 23:02:59 -0700

On Sun, Jun 10, 2007 at 07:52:28PM +0200, Sam Ravnborg wrote:
> On Sun, Jun 10, 2007 at 09:22:21AM -0700, Greg KH wrote:
> > >  Since the common language of most kernel contributors is english I
> > >  personally feel that we should stick to just that one language in the
> > >  tree and then perhaps keep translations on a website somewhere. So the
> > >  authoritative docs stay in the tree, in english, so that as many
> > >  contributors as possible can read and update them. It would then be a
> > >  seperate project to generate translations and keep them updated
> > >  according to what's in the tree.  Perhaps we could get the kernel.org
> > >  people to create an official space for that and then place a pointer
> > >  to that site in Documentation/ somewhere.
> > 
> > No, I think the translated files should be in the tree proper, we have
> > the space :)
> 
> We once discussed about .po files for kconfig and back then
> the conclusion was not to keep them in the kernel tree.
> 
> I advocated that they should stay out back then.
> But on the other hand I do not see it causing much troubles
> having scripts/kconfig/po/da.po etc araound.
> 
> Any opinion about the .po files?

I have no objection for them to be around in the tree, it might help out
some users who want to build their own kernels, and allow the -stable
kernels to catch up on the translations.

So I would encourage their addition, if possible.

thanks,

greg 'not everyone speaks english' k-h

Linux: Translating Kernel Documentation

[RFD] Documentation/HOWTO translated into Japanese

Kconfig translations

Comment viewing options