ドキュメント開発のTips & Tricks

1.  Webサイトにあるファイルをチェックアウトする

anonymous CVSを使う

翻訳作業に参加する方はanonymous CVS サーバーを使ってください。Gentoo開発者が使うオフィシャルなCVSと同じファイルが格納されています。anonymous CVS リポジトリは１時間毎に更新されます。

ドキュメント開発のためだけに、専用のディレクトリを作成してください。そしてWebサイトのファイルをチェックアウトしてください。

$ cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml

リポジトリのコピーを更新するためには gentoo/xmlディレクトリでcvs update -dP を実行してください。

Gentoo 開発者向けの活動用リポジトリ

もし、まだgentooモジュールをチェックアウトしていなければ、チェックアウトしてください:

$ export CVSROOT=<your nick>@cvs.gentoo.org:/var/cvsroot
$ cvs co gentoo/xml

リポジトリのコピーを更新するのは、gentoo/xml ディレクトリでcvs update -dPを実行してください。

オンラインCVSリポジトリ

個別のバージョン間の違い提供するために私たちのオンライン CVS リポジトリを利用することができます。中心的な英語版リポジトリは、すべて利用可能です。. オンラインCVSは一時間毎に更新されます。

2.  ローカル環境をセットアップする

gorgのインストール

私たちの GuideXML ドキュメントはwww-servers/gorgパッケージによりHTMLに変換されます。これをインストールしてください。

gorgのホームページにしたがって、設定してください。CVSリポジトリをチェックアウトしたディレクトリ(.../gentoo/xml/htdocs)をWebルートとして設定する必要がありますその他のパラメーターは www.gentoo.org のローカルコピーを提供したい場合に有効です。

XML環境をセットアップする

私たちのドキュメントが使うDTDがどこで見つけられるのかシステムが知らなくてはなりません。rootになり/etc/xml/catalog に次の行を追加してください:

<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

もし/etc/xml/catalogが空か何もエントリーがない状態であれば、 <rewriteURI>エレメントを<catalog>の内側に 挿入する必要があります:

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
</catalog>

さらにいくつかのファイルではhttp://www.gentoo.org/dtd/guide.dtdというurlのようにオンラインDTDを指定してもかまいません。これらの参照を書き換えてバリデーション中のネット越しのアクセス速度低下を避けることもできます:

<rewriteURI uriStartString="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Gentooガイドのテスト

Gentooガイドをテストするために、まず正しい(valid)XMLを使用しているかどうかチェックするためにxmllint (dev-libs/libxml2にある)を使いましょう:

$ xmllint --valid --noout alsa-guide.xml

xmllintが目に見える形で何も返さない場合、そのファイルの構造は正当(valid)です。次にHTMLに変換する必要があります:

$ gorg < alsa-guide.xml > alsa-guide.html

もし何もエラーがなければ、ブラウザでalsa-guide.htmlを開き、変換結果のドキュメントをみてみましょう。エラーがあれば、動作するまでガイドを修正しましょう。

Gentoo のWebサイトのローカルコピーをブラウズする

GentooのWebサイトをCVSからチェックアウトしているので、ローカルコピーをブラウズするためにgorgを使うこともできます。もしGentooと同じフロントページにしたい場合は、gorgのホームページで説明されているとおりにニュースインデックスをダウンロードしているかどうか確認してください。

3.  よくある質問

ファイルをUTF-8に変換するにはどうしたらいいですか？

あなたの助けとなるツールは数多くあります。有名なものにはapp-text/recodeがあります。他にもsys-libs/glibcの一部分であるiconvといったものもあります。

Recodeの使い方はとても簡単です。ドキュメントに使われている現在の文字コードと、ドキュメントの文字コードをどれに変換するかをRecodeに伝えます。

例えば、ISO-8859-15(Latin-9としても知られています)からUTF-8へ変換するためには、次のように使います:

(l9 = ISO-8859-15, u8 = UTF-8)
$ recode l9..u8 file.xml

4.  ドキュメント提出に関するTips

<guide> タグが正しいことを確認する

<guide link> 属性がガイドの正しい場所を指しているか確認してください。大抵は/doc/${LANG}/filename.xmlです。もし、翻訳ドキュメントの場合は、常にドキュメントへの絶対パス(たとえば/doc/${LANG}/)を指定してください。もし、guide や book DTDを使うようなドキュメントを書いた場合、/doc/${LANG}/filename.xml や filename.xmlが使えるかもしれません。大抵の場合、GDPは前者の指定を推奨します。

リンクを確認する

かならず ドキュメントのすべてのハイパーリンクを確認してください。翻訳ドキュメントの場合、他の翻訳ドキュメントへのリンクはどれも存在するファイルを指していることを確認してください。

タブのチェック

GuideXMLではタブは必要がある場合(たとえばドキュメントがユーザーにタブを使うよう指示している場合)を除いて絶対に禁止です。タブに関してドキュメントをチェックするには、grep "CTRL+V<TAB>" file.xmlを実行してください。grepの出力結果はすべて修正してください。

Bugzilla

一旦ドキュメントの作成を終えたら、Bugzillaを使ってドキュメントチームへドキュメントを提出してください。プラットフォームやemerge infoの出力、arch、再現手順などの情報については気にする必要はありません。もし、ドキュメントを翻訳した場合は、 ドキュメント翻訳 コンポーネントをバグ情報のなかで選んでください。また、翻訳についてなんらか助けになるサマリーを次のような好ましい形で含めてください: "[fr] New translation: /doc/fr/gnupg-user.xml"。[fr] の部分を翻訳言語に合わせた2文字で置き換えてください。

デフォルトではdocs-team@gentoo.org がバグをアサインしますので、任命者欄を変更する必要はありません。

バグには"プレーンテキスト(text/plain)"でファイルやパッチを添付してください。たとえ.xmlを提出する場合でも、"XMLソース(application/xml)"をえらばないでください。 パッチの場合は"Patch"オプションをチェックしてくださいtarballでのドキュメント提出はしないでください。それぞれのドキュメントやパッチを個別に添付してください。

5.  一般的または危険な間違い

Gentooハンドブックがすべてのアーキテクチャに対応する点を忘れている

[gentoo]/xml/htdocs/doc/en/handbook 内のファイルで名前の末尾が"-<arch>.xml"でないものは、すべてのハンドブックで読み込まれます。 つまりこの場合、ファイルに記載されている内容はすべてアーキテクチャに共通でなければいけません。

もし、アーキテクチャ固有な点について修正する必要がある場合や、そういった事柄をフ文書内に書き留めておく必要があると感じた場合、これを解決するには、まずgentoo-doc@gentoo.orgに問い合わせるとよいでしょう。他のアーキテクチャのユーザーに手間をとらせずに済む方法があるかもしれません。

バージョンや日付を進めない、もしくは間違った方法で進めている

ポリシーに従って、(ほぼ実質的に)何らか変更があったときにはバージョンや日付を進めなければいけません。バージョンはさほど重要ではありませんが(ただ、忘れた場合にはSwifTにこっぴどく怒られるでしょうね)、日付によりユーザーはドキュメントが最後に変更された時間を知ります。

もし内容(指示やコード例など)の変更した場合は、バージョンをあげなくてはいけません。 内容に関連しない(打ち間違いやGuideXMLの修正など)の変更では、ふつうバージョンは上げる必要はありません。

ハンドブックを更新した場合は、変更したファイルの日付とバージョンだけを更新してください。handbook-ARCH.xmlの内容を実質的に変更しない限り、このファイルの更新をしないでください。

他によくある間違いは、十進数であるかのようにバージョン番号を更新してしまうことです。これは違います。3.9の次は3.10にしなければいけません。4.0でも 3.91でもありません。

このドキュメントの内容は、他のものが明示されない限りは、 CC-BY-SA-2.5ライセンスです。 Gentoo Name and Logo Usage Guidelines (日本語訳)が適用されます。