Linuxカーネルは、これまでで最もダイナミックで複雑な大規模なオープンソースプロジェクトです。 彼のドキュメントはどうですか？ 直接的なリンクがあります。プロジェクトのドキュメントにアクセスしやすくなるほど、部外者がケースの基本を学び、快適になり、完全なメンバーになることが容易になります。
Kernel Recipiesワークショップで、 LinuxドキュメントカーネルメンテナのJonathan Corbetが、ドキュメントの現在の状態と、無秩序から秩序への移行がどのように行われるかについて話しました。 この努力の最初の成功はすでにそこにあります。 最近、Python Sphinxを使用して一部のドキュメントがReStructuredText
変換されました。 内部でどのように伝えられたかについて。
Documentationフォルダーには何が含まれていますか？
Documentation
は大文字のディレクトリで始まる唯一のLinuxディレクトリです。これはその特別な役割と位置を強調していますが、気の毒な脚の中では壊れます。
- 2264ファイル
- 228ディレクトリ
-
Documentation/devicetree
を含まない23 MBのドキュメンテーション
ドキュメンテーション/ *は巨大な混乱であり、現在、ランダムな通行人が物事を最後に置く場所に基づいて編成されています。
-ロブ・ランドリー、2007年7月。
これはすべて、2つの方法で存在します。通常のtxtファイルとDocBookテンプレートです。 単純なtxtファイルは相互に接続されておらず、さまざまな人によってさまざまな時点で書き込まれ、すべてが同じように役立つわけではありません。 それらのいくつかは、すべてのカーネル開発者に知られています。 これらは、LinusまたはCodingStyle
によって作成されたManagementStyle
、すべてのボランティアが開始します。 これらのドキュメントは、すべての開発者、Linuxoid、およびシンパサイザーに読まれるべきだと思います。
ところで、「カーネルマネージャー」について話すとき、それはすべて、企業内で従来の管理を行う人ではなく、技術的なリーダーです。 発注書に署名するか、グループの予算について何か手掛かりを持っている場合、あなたはほぼ確実にカーネルマネージャーではありません。 これらの提案は、お客様に適用される場合と適用されない場合があります。
経費請求書に署名し、予算編成を理解している場合、あなたは間違いなく上級カーネル開発者ではありません。
外向きに紛失したドックは、明らかに他のドックと違いはありません。 たとえば、 Documentation/applying-patches.txt
は、 ftp
を介してパッチをダウンロードし、 patch
コマンドを使用して適用する方法を指示します。 今日、誰もそれをしていないことは明らかです。
# moving from 2.6.11 to 2.6.12 $ cd ~/linux-2.6.11 # change to kernel source dir $ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch $ cd .. $ mv linux-2.6.11 linux-2.6.12 # rename source dir # moving from 2.6.11.1 to 2.6.12 $ cd ~/linux-2.6.11.1 # change to kernel source dir $ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch # source dir is now 2.6.11 $ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch $ cd .. $ mv linux-2.6.11.1 linux-2.6.12 # rename source dir
発掘調査により、驚くべき結果が得られることがあります。 1996年以来、Linuxはクリンゴン語の記述をサポートしていることがわかりました 。 Documentation/unicode.txt
ます。
U+F8D0 KLINGON LETTER A U+F8D1 KLINGON LETTER B U+F8D2 KLINGON LETTER CH U+F8D3 KLINGON LETTER D U+F8D4 KLINGON LETTER E U+F8D5 KLINGON LETTER GH U+F8D6 KLINGON LETTER H U+F8D7 KLINGON LETTER I U+F8D8 KLINGON LETTER J U+F8D9 KLINGON LETTER L U+F8DA KLINGON LETTER M U+F8DB KLINGON LETTER N U+F8DC KLINGON LETTER NG U+F8DD KLINGON LETTER O U+F8DE KLINGON LETTER P U+F8DF KLINGON LETTER Q
Documentation/zorro.txt
は、Amiga PC用のプログラミングドライバーの秘密が含まれています。 2003年にドックが最後に統治されたのは驚くことではありません。
一部のテキストは非常に激怒しているため、ほとんどの人は理解できません。 これらには、Jonathan Documentation/memory-barriers.txt
含まれていました。 彼によると、そこで議論されていることを理解した人は、彼や他の多くの人よりもよく考える。
下位レベルのカタログにも多くのジャンクがあります。このドキュメントはおそらく最も密度の高いものの1つです。 面白いことです。100年前にusa.netにもメールがありましたが、DotCom市場でのクラッシュの後、有料になり、Yahooに移りました。
(5:521)$ less Documentation/sound/oss/MultiSound #! /bin/sh # # Turtle Beach MultiSound Driver Notes # -- Andrew Veliath <andrewtv@usa.net> # # Last update: September 10, 1998 # Corresponding msnd driver: 0.8.3
カーネルからのサウンドサブシステムOSSがほぼ完全に切り取られていることは注目に値しますが、ドキュメントはまだそこにあります。
次に、プレーンテキストファイルの純粋な無秩序から、カーネルドキュメントのより複雑な2番目の混乱へと移りましょう。
DocBookとみんな
すべての処理インフラストラクチャを備えたこれらの34のXMLテンプレートはDocBookです。 プレーンテキストとは異なり、DocBookフォーマットでは、API、関数の説明を構造化し、クロスリンクでリンクされたhtml、pdf、またはmanページを取得できます。
(5:522)$ ll Documentation/DocBook/*.tmpl |wc -l 34
ソースコードには、特別なkerneldoc comments
- kerneldoc comments
が含まれていkerneldoc comments
。 コードには、55,000以上のそのような挿入があります。
/** * list_add - add a new entry * @new: new entry to be added * @head: list head to add it after * * Insert a new entry after the specified head. * This is good for implementing stacks. */
DocBookテンプレートには、ソースからドキュメントをダウンロードする方法に関する指示が含まれています 。
/* * Parse file, calling action specific functions for: * 1) Lines containing !E * 2) Lines containing !I * 3) Lines containing !D * 4) Lines containing !F * 5) Lines containing !P * 6) Lines containing !C * 7) Default lines - lines not matching the above */
Documentation/DocBook/networking.tmpl
。
<sect1><title>Socket Buffer Functions</title> !Iinclude/linux/skbuff.h !Iinclude/net/sock.h !Enet/socket.c !Enet/core/skbuff.c !Enet/core/sock.c !Enet/core/datagram.c !Enet/core/stream.c </sect1>
ユーザーがmake htmldocs
、 scripts/docproc
がテンプレート内のドキュメントエクスポート命令を解析し、各命令に対して次のアクションを実行します。
- 指定されたファイル内の
EXPORT_SYMBOL()
命令を見つけて解析し、エクスポートされたシンボルのリストに関数名を追加します。 - Perlスクリプト
scripts/kernel-doc
呼び出します。これは、必要な定義を取得するために、Cコードで見つかった関数、構造、その他すべてを実行します。 - 2回目のラウンドで
scripts/kernel-doc
、同じファイルを再度読み取りますが、今回はそれらの関数のドキュメントを作成し、結果をDocBookスニペットにパックします。
次に、 docproc
は、作成されたファイルをDocBookフォーマットでテンプレートにプッシュします。 HTMLの場合、 scripts/kernel-doc-xml-ref
スクリプトが呼び出されます。これは相互参照を作成しますが、個別のテンプレートに対してのみです。 最後に、 xmlto
は指定された形式でドキュメントを作成しますが、 Makefile
代替プログラムを指定できます。
スクリプト、退屈なXMLテンプレート、地獄の常連のこのミックス [1]信頼性が低く、抑制されていた [2] 、そして最も重要なこと-目を楽しませ、首尾一貫した文書を作成しませんでした。
マークダウン、アシドイド、スフィンクス
この状況が誰にも適していないことは明らかであり、ジョナサンと彼の同僚は状況から抜け出す方法を探していました。 いくつかのオプションを調べて試した結果、最終的にReStructuredTtext
とSphinx
束に落ち着きました。
最初に、原則が策定されました。 新しい文書システムは要件を満たしている必要があります。
- 混乱を排除します。
- フォーマットと可読性を改善します。
- 平文。
- 合理的に編成されたツール。
軽量マークアップ言語の使用は自明であり、最初の試みはMarkdown
でした。 これにより、複数の問題を一度に解決することができました。 まず 、プログラム自体に書かれたコメントが更新されます。 楽観的ではありますが、全体としての考えは真実です。 第二に 、テキストベースのMarkDown
はDocBook-XML
よりもはるかに低い入力しきい値を持っているため、簡単に作成できるドキュメントは記述される可能性が高くなりDocBook-XML
。
しかしすぐに、 MarkDown
は単独では使用できず、現在のプログラムセットのアドオンとしてのみ使用できることが明らかになりました。 kernel-doc
MarkDown
のコレクションにMarkDown
のサポートを追加する必要がありました。これには、追加のpandoc
変換pandoc
（およびasciidoc
）の使用が必要でした。 資金は明らかに対立しており、マークアップは変動し、デバッグは複雑でした。 より多くのブレーキがあり、ツールはさらに不機嫌になりました。
それからジョナサンは、状況から抜け出す方法を探さなければならないことに気づき、反対方向に動いた。 フォーマットと相互変換のチェーンを複雑にする代わりに、そこから余分なものを取り出して捨てるべきです。 DocBookと彼の周りのすべてが不要であることが判明しました。 すべてをAsciiDoc
転送し、DocBookインフラストラクチャをバイパスして、そこから必要なhtml、pdf、およびmanページを直接作成するとどうなりますか？
言うのは簡単、実装は難しい。 AsciiDoc
はRubyの依存関係を引き出し、 xmlto
とのリンクがxmlto
、とにかくDocBookを置き換えるよりも補足し、ドキュメントのリンクはまだ一緒に成長しませんでした。 それにもかかわらず、不可解な理由を待つのではなく、前進することが決定されました。 最後の瞬間、Jonathanは短いタイムアウトを取り、 長所と短所を比較検討し、軽量のRestructuredText
マークアップに基づいたSphinx pythonドキュメンテーションシステムの採用を提案しました 。
なぜスフィンクスなのか？
- ソフトウェアを文書化するように設計されています。 たとえば、関数とは何かを知っています。
- 多くのファイルに散らばる大きなドキュメントに適しています。
- よく使用され、良好なサポートがあります。 [3] 。
- ドキュメントは最終的に接続されます。
- ツールチェーンが簡素化され、アセンブリが高速化されました。
同僚を説得するために、ジョナサンは曲がった概念実証を膝の上に書き、それからジャニ・ニクラはそれを磨き、それを思い起こさせた。 ドキュメンタリーの間では、この問題についてコンセンサスが急速に生じ、すべてが始まりました。 ところで、 PoCトリックは、 mm
カーネルブランチのメンテナーであるAndrew Mortonによれば常に機能します。 これがLinuxの誕生方法であり、ひどい解決策を理想的でない解決策に置き換える必要がある場合、多くの場合、論争のある問題は解決されます。
何が行われ、何が行われるべきか
変更はすでに部分的に表示され、 Sphinxの設定はDocumentation/Makefile.sphinx
およびDocumentation/conf.py
保存されています。 インデックスファイルindex.rst
とkernel-documentation.rst
。 gpu
とmedia
開発者は他の先を行っており、すべてのDocumentation/gpu/
documentationをすでにSphinxに翻訳しています。
Sphinxに切り替えるプロセスは、ショック療法なしで行われます。つまり、プレーンテキストファイルとDocBookテンプレートは、他のメンテナーと合意して、徐々に新しい形式に変換されます。 そのため、DocBookの間はどこにもdocproc
ませんが、新しい最初のドキュメントにdocproc
必要docproc
ません。
バージョン4.8は、新しいドキュメントシステムを備えた最初の安定したLinuxカーネルです。 Linusはこれらの変更について手紙でコメントし、パッチの20％がドキュメントであると驚いた。
パッチ自体はいくぶん変わっているように見えますが、マージウィンドウはかなり正常です。パッチの20％以上は、docbookからSphinx doc形式へのdrmおよびメディアドキュメントの変換によるドキュメントの更新です。
Linux Torvalds（4.8-rc1リリース）
良い例は、HSIドキュメントです。 これまで、プレーンテキストとDocBookの2つの形で存在していました。 ドキュメントは相互に接続されていません。
-
Documentation/hsi.txt
-
Documentation/DocBook/device-drivers.tmpl
Linux 4.9以降、これは1つのDocumentation/drivers-api/hsi.rst
。 そして、これは長い旅の始まりに過ぎません！
多くの作業が先にあります。 長期的な目標は、DocBookと20年前のPerl kernel-doc
マジックを完全に取り除くことです。 カーネルソースのスペースと同じ順序になるように、2,000を超えるテキストファイルをReStructuredText
に変換し、 Documentation
でファイルシステムの厳密でわかりやすい階層を設定する必要があります。
参加したい場合 オージェan舎の清掃 Linuxカーネルのドキュメントの改革、それのために行く;ドメインの知識は、もちろん、余分なものではありませんが、これには特別な知識は必要ありません。 新しいことを学び、すべての利害関係者と対話し、健全な保守主義と漸進主義の原則を順守することも同様に重要です。