Gentoo Linux Documentation Developer Policy（ドラフト）

1. 概要

イントロダクション 

このガイドを読んでいるならば、あなたは新しいドキュメント作成者かプロジェクトに貢献したいと思っているかのどちらかでしょう。まず、Gentoo Linux プロジェクトへの貢献に感謝したいと思います。私たちの目的のなかには、誰にとってもよい資料をつくるということがあります。私たちのフォーマットは簡単に学べるので、XML 言語と格闘することはないでしょう。私たちの XML フォーマットに関するより多くの情報はこちら（日本語訳）を見てください。

ガイドの対象範囲 

このガイドは次の項目を対象にします：

• 作成者の責任
• フォーマットの約束
• ドキュメントのエンコーディング
• xmllint と xsltproc チュートリアル
• Gentoo.org ウェブサイト概要
• CVS コミット
• コンタクトリスト（問い合わせ先）

2. 作成者の責任

責任と倫理 

たとえあなたが作成者でなくても、これらのガイドラインは、やはり適用されます。もしあなたが作成者であれば、これらのガイドラインは必ずやあなたの Gentoo バイブルとなるでしょう。多くの検討がこのポリシーに加えられました。あなたはこれらに従うよう強く要請されます、そしてもし必要ならば異議を唱えてください。

まずはじめに、全ての作成者がOfficial Gentoo Linux Policy（日本語訳）を読まなくてはいけません。このドキュメントはすべての作成者の共同作業であり、そしていくつか非常に重要な情報があります。

ドキュメント作成者としてあなたは gentoo-doc メーリングリストに入会しなくてはいけません。ここではこのリストに含まれる多くの情報があり、起こっている事を更新しつづける良いアイデアです。

あなたが CVS になにかをコミットするとき、コミットするものが十分に役に立ち、校正されたものであることが 非常に重要です。私はあなたのドキュメントがさまざまな面から正しいということがどれほど重要かを強調することはできません。もしあなたが自分のドキュメントの校正をしなかったり、壊れた XML をコミットし続けたりした場合は、CVS アクセスの取り消しといった形での反響があるかもしれません。

バグリストに載っているあなたのバグをチェックしきちんと対応することは作成者としてのあなたの義務です。Gentoo プロジェクトではみな自分の責任を果たします。もし、疑問があれば別の作成者に質問してください。たいていは大いに喜んで助けてくれるでしょう。あなたのバグに言及しないことは重大な違反であり、作成者の地位を取り消されることにもなり得ます。

最も重要なのは、他の作成者たちを尊敬することです。

3. 書式規約

書式 

多くの優れたプログラムのように、Gentoo Linux ドキュメンテーションのなかである書式が守られることが非常に重要です。まず、ドキュメントの最初の部分からいきましょう。 Gentoo Linux プロジェクトに対して書かれたドキュメントは全て次のヘッダーを最上部に持ちます。

<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
	

最初のラインは、インタープリターがどの XML のバージョンを解釈すべきか何の文字エンコーディングを使うべきなのかを認識する、ということを保証します。私はこのガイドのあと文字エンコーディングについて議論しましたが、2002年11月に すべての Gentoo Linux 付属ドキュメントが UTF-8(Unicode) エンコーディングを採用することになりました。

二番目のラインは DTD ファイルのパスを指定します。DTD の定義の説明はこのドキュメントの範囲外ですが、もしお知りなりたいのであれば、いくつか 調査 、その結果を私たちにフィードバックしてください。

つぎのラインは非常に大事です。これはドキュメントの場所を設定します。かならずセットしてください。

x をあなたのドキュメント名で置き換えてください。
<guide link = "/doc/your_country_code/x.html">
        

すべての "<pre>" タグには内容の十分な記述をつけてください。

<pre caption = "This is what my pre contains">

よく書かれたプログラミングコードのように、ドキュメント執筆者はタグとともに XML コードを適切にインデントすることが望まれます。このことは、これまであまり多く行われてきませんでした、しかし今後はなされる必要があります。これは可読性の向上と Just Good Programming (tm) の練習です。

あなたがもし、多くの変更をドキュメントに加えた場合は、あなたの名前をドキュメントに加えなければいけません。"<author>"; タグは次のようなときに使ってください。

あなたのドキュメントをまとめてください。あなたのメインの要点とサブの要点をうまく組み合わせてください。Gentoo の文書はプロがしたようにレイアウトされていくでしょう(訳注：guide.html を使うためです)。これは見た目の良さだけでなく、全体的な読みやすさもよくなります。Chapter/Section もうまく使ってください。これにより、ドロップダウンボックスによるナビゲーションが簡単にとてもできます。

適切なキャピタライゼーション(大文字化)を意味が分かるように使ってください。すなわち、gentoo linux == Gentoo Linux, kde == KDE, gnome == GNOME などです。

もっとも大事なのはGentoo XML Guide（日本語訳）を読むことです。多くの重要な情報が含まれており、Gentoo Linux の文書を書く人は だれでも読まなくてはいけません。

4. ドキュメントエンコーディング

Unicode(UTF-8) 

2002年の11月半ばに、新しい Gentoo Linux のドキュメント類はすべて UTF-8 にてエンコーディングされました。私は文字エンコーディングの素晴らしい世界に参加はしないでしょうが、しかし UTF-8 は国際標準であり、あらゆる優れたブラウザから認識されています。私たちは古いドキュメントを UTF-8 にする作業をしており、できれば、次の年(2003)のある時点で、すべてのドキュメントが UTF-8 準拠にしたいです。

5. XMLLINT と XSLTPROC 簡単なチュートリアル

XMLLINT と XSLTPROC の使い方 

ドキュメントとして扱うものをコミットする前には、かならずドキュメントを xmllint と xsltproc でチェック/妥当性の検証をしなくてはいけません。xmllint はいわゆる文法チェッカーで xsltcproc は本格的な xml --> html 変換エンジンです。

xmllint の使い方はシンプルです：

# xmllint doc.html --format スイッチを使うのが良いかもしれません。そうすると、出力結果がより良くなるでしょう。 

基本的に、もしあなたのドキュメント内にエラーがあれば、xmllint はエラーを検知し報告するでしょう。

xsltproc を使うのは(xmllint に比べて）ちょっと難しいですが、しかしそれほど難しくはありません。xsltproc は次のように使用します：

# xsltproc /path/to/the/xsl/guide/guide.xsl your_doc.html > output.html 

もちろん、どちらのツールにもより多くのオプションがあります。これらを調べることをお勧めします。私が紹介した例はドキュメントをチェックする基本的なものです。

6. The Gentoo.org Website

Overview 

Gentoo.org は常に(活)動的で発展しているウェブページです。私たちのウェブサイトは XML/XSL 変換システムに基づいています。もしあなたが知らないとするとチョット驚きですが、私たちのウェブサイト全体は XML で書かれています。私たちの XML コードは Axkit と呼ばれる素晴らしいサーバーサイドキットにて変換されて運用されています。言い換えれば、XML ドキュメントがリクエストされたときに、HTML に変換されるということです。これでドキュメントの正確さが非常に重要な理由が分かっていただけたと思います。もし、XML エラーページがあれば、それは単純に表示されません。繰り返しですが、絶対あなたの XML に間違いのないようにしてください。

組織 

Gentoo.org のウェブサイトはgentoo-xml ブランチのしたにあるgentoo-srcツリーにて見つけることができます。ドキュメントの登録(コミット)は全て gentoo-xml/doc/your_lang/(訳注:日本語の場合は your_lang は ja です。)にて行われます。ディレクトリにあるファイル名の慣例を守るようにしてください。私たちにまだなかった新しい言語で、登録を行うときは、シニアデベロッパーに連絡をとってください。そうすれば、彼らはセットアップを手伝ってくれます。

7. Bugzilla Commits (Non-CVS)

Commiting Documents via Bugzilla 

もし、あなたが CVS アクセスができないならば、あなたのドキュメントはBugzillaを使って登録してください。バグを新たに登録し、[email protected]にアサインしてください。(そのとき)XML でのあなたのガイドを添付してください。

8. CVS コミット

CVS でのドキュメントの登録 

私たちのドキュメント登録には、簡易な古い cvs commit を使っています。適切なコミットコメントをつける必要があります。私たちはドキュメントの changelog を保存していません（今後は変わるかもしれませんが）、よって CVS のコミットコメントに頼っているわけです。あなたが CVS コミットをするものに対して責任があることをわすれないでください。言い換えれば、こわれた XML はコミット（登録）しないでください！ Seemant と私自身（ドキュメントチームの残りのメンバーについてではありません）の怒りを買うことになります。

CVS になにか疑問があれば、CVS Tutorial（日本語訳）を参考にしてください。

9. ドキュメントコンタクトリスト

コンタクトリスト（連絡先） 

もし、何か疑問があれば、次の方に相談してみてください。

もし、どなたか忘れていたら本当にごめんなさい。今の時点で主要な開発者全員を載せました。何か質問があれば遠慮せずに連絡をください。