Gentoo Logo

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

目次:

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

anonymous CVSを使う

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

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

コード表示 1.1: Webサイトのファイルをチェックアウトする

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

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

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

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

コード表示 1.2: 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-0.6.3以上をインストールしてください。使っているアーキテクチャによってはkeywordが必要かもしれません。

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

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

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

コード表示 2.1: /etc/xml/catalog 追加行

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

注意: CVSからチェックアウトしたDTDへのパスへ書き換えてもかまいません。

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

コード表示 2.2: 最低限の/etc/xml/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を指定してもかまいません。これらの参照を書き換えてバリデーション中のネット越しのアクセス速度低下を避けることもできます:

コード表示 2.3: その他の /etc/xml/catalog への追加行

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

Gentooガイドのテスト

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

コード表示 2.4: GuideXMLの正当性確認(validation)のためxmllintを使う

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

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

コード表示 2.5: HTMLへの変換

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

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

注意: ハンドブックの章では、他の章へのリンクは生成されないかもしれません。 なぜならオンラインでのハンドブックアクセスはマスターファイルを経由しておこなわれ、chappartパラメーターによるからです。

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へ変換するためには、次のように使います:

コード表示 3.1: ファイルを再変換する

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

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

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

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



印刷

ページの更新日 2007年 3月 8日

このドキュメントのオリジナルバージョン の更新日は2010年 12月 6日

要約: Gentooドキュメント開発者の開発時間を短縮するtips & tricksです。

Xavier Neys
Author

Sven Vermeulen
Author

池田 健吾
翻訳

シンドウナオアキ
翻訳

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.