警告! この翻訳は古過ぎるため、原文を御覧ください。

Debian ウェブページの作業をするには

一般的な情報
編集者のエチケット
リンク
データとテキストの分離
新しいページを追加する
他のファイルを含める
新しいディレクトリを追加する

一般的な情報

必要なリソース

我々のウェブサイトについて作業をしたいなら、少なくともディスクに 250 MB の空き容量を用意してください。これは現在のソースアーカイブのサイズに左右されます。もし (偶然にも) 全ページを再構築することになったら、少なくとも倍の容量が必要になるでしょう。部分的にしかチェックアウトしないなら、もっと少ない容量で済みます。例えば、english/ ディレクトリは 50 MB あります。

部分的なチェックアウト

多くの人は webwml CVS ツリー全体をチェックアウトしないと思いますが、重要なファイルが追加された後でそのディレクトリで完全な cvs update を実行しなかった場合など、ファイルを失ったり不完全なビルドを招いたりすることがあります。文句を言う前に (.wmlrc などの) 必要なファイルがあるかどうか確かめるのを忘れないでください。

"#" で始まる行はなんですか?

WML では、"#" で始まる行はコメントです。最終的なページに表示されないようにするには、通常の HTML のコメントの方がよいでしょう。

WML についての詳しい情報は、WML の利用方法のページを読んでください。

編集者のエチケット

このページを変更してもいいですか?

場合によります。typo などのちょっとした間違いなら、修正してください。

情報が少し足りないと気づいた場合も、気にせずに修正してください。

書き直しが必要なほどひどいと感じた場合は、議論のために debian-www に問題を出してください。たぶん賛成できると思います。

テンプレート (つまり webwml/english/template/debian ディレクトリにあるファイル) に問題があると思ったら、コミットする前に変更点についてよく考えてください。テンプレートの変更は、時としてサイトの大部分を再構築することになりますから。

ディレクトリを追加したら、Makefile も追加してください!

CVS に新しいディレクトリを追加するときは、ちょっと注意してください。カレントディレクトリが ../Makefile に記載されている場合、カレントディレクトリにも Makefile を作成しなければいけません — さもないと、make がエラーメッセージを出します。

明解で分かり易い英語を使ってください

Debian のウェブページは英語がネイティブではない人々が読んで他の言語に翻訳するので、明解で分かり易い英語で書き、スラングや絵文字、分かりにくいイディオムなどの使用は避けるのがベストです。

これらを使いたい場合には、その意味を説明するコメントを追記してください。

疑問がある、提案の校正が欲しいといった場合は、英語地域化チームと連絡を取ってください。

README を読んでください

そのディレクトリがどのように構成されているか理解するのを助けるために、README ファイルが置かれているディレクトリもあります。この領域で作業するのに必要な、特別な情報が書かれているはずです。

内容の変更とフォーマットの変更は分けてください

パッチやコミットにおいては、常に内容の変更とフォーマットの変更を分けてください。これらが混ざってしまうと、翻訳者が差分を見つけるのに苦労します。cvs diff を実行してみると、そのような変更が混乱のもとになるのがよく分かるはずです。

一般的に、成り行き任せのフォーマット変更は避けてください。ある修正をコミットする際に、修正箇所以外の XHTML/XML 対応を同時にすべきではありません。 (もちろん、最近のページでは最初から XHTML/XML に対応できているはずです。)

可能なら翻訳版も更新してください

URL や組込み Perl コードの変更のように、訳されている言語には依存しない変更もあります。翻訳中には大抵無視してしまうので、typo の修正もこの範疇に入ります。このような言語非依存の変更をする際には、他の言語を実際には知らなくてもすべての翻訳ファイルを同様に変更し、安全に translation-check ヘッダのバージョンを上げられると思います。

何十人もの翻訳者がそれぞれ同様の作業をするのはとんでもなく大変なことではないですし、英語を話す編集者が処理のためにすべてをチェックアウトするのは厄介なことです。しかし、一人でさっさと出来ることに 2 ダースもの人々の手を煩わせるのを避けるためにも、この作業を推奨します。

付け加えると、このような変更を簡単に適用するには、webwml CVS モジュールのトップディレクトリにある smart_change.pl スクリプトを使うとよいでしょう。

smart_change.pl の使い方

smart_change.pl [options] origfile

現在のところ、/english/ 以下にあるファイルだけが origfile として認められています。smart_change.pl は次のような引数を取ります:

-s, --substitute=REGEXP

ソースファイルに適用する Perl の正規表現を指定します (複数回指定することになるでしょう)。例えば:

   $> ./smart_change.pl -s "s,http://oldurl/,http://newurl/,g" english/devel/index.wml
   $> cvs diff -u */devel/index.wml | less
   $> cvs ci -m "1.23: Updated oldurl to current location" */devel/index.wml

最初のコマンドで変更を加え、次のコマンドで英語のオリジナルファイルと各翻訳ファイルを確認しています。コミットする前にこうして実際の変更点を確認してください。すべてが期待どおりなら、最後のコマンドで変更をコミットします。

-l, --lang=STRING

この言語を処理します (複数回指定することになるでしょう)。言語が指定されなかった場合、存在するすべてのものを処理します。

-n, --no-bump

translation-check ヘッダのバージョンを上げません。通常、各 translation-check ヘッダは、翻訳済のファイルが最新の状態になれば一つ増やされ、古いままならそのままにされます。このオプションが指定されると、 translation-check ヘッダは一切変更されません。ウェブサイトの翻訳を最新に保つために translation-check の説明を見てください。

-p, --previous

CVS の前のリビジョンを表示します。これは主に、すでに英語版がコミットされていて、前のバージョンに対して translation-check ヘッダを確認したい場合に便利です。

-h, --help

簡単な使い方を表示します。

-v, --verbose

実行中に冗長なメッセージを表示します。

リンク

このリンクは正しくなさそうです。変更すべきですか?

ウェブサーバは (内容交渉を使って) 設定されているので、内部のリンクを変更する必要は一切ないはずです。実際にも変更しないことを勧めます。リンクがおかしいと思ったら、変更する前に debian-www に知らせてください。

リンクの修正

外部のウェブサイトへのリンクがリダイレクト (301、302、<meta> タグによるリダイレクト、このページは移動しました。と書かれている) される場合は、そのことを debian-www に知らせてください。

リンク切れ (404、403、リンクとは違うページが表示される) を発見したら、修正した上で debian-www に知らせてください。そうすれば、翻訳者も気づきます。さらによいのは、他の翻訳すべてにおいてもリンクを修正し、可能なら translation-check ヘッダを更新してください。

データとテキストの分離

foo.def とか foo.data というファイルはなんですか?

翻訳を最新の状態に保つのを容易にするために、テキスト部分 (text) から共通部分 (data) を分離しているページがあります。翻訳者はテキスト部分だけをコピーして翻訳すればよく、共通部分は自動的に付加されます。

例を挙げると分かり易いでしょう。CD/vendors にあるベンダーリストのページを生成するには、いくつものファイルを使います:

index.wml:: ベンダーページの先頭のテキストは、このファイルにあります。翻訳したものを各言語のディレクトリに配置します。
vendors.CD.def:: このファイルには、各ベンダーのエントリに必要なテキスト片が含まれています。訳は <language>/po/vendors.xy.po に追加します。
vendors.CD:: このファイルには、言語に依存しない実際のベンダーエントリが含まれています。翻訳者はこのファイルに触る必要はありません。

[email protected] のうちの誰かが新規のベンダーを追加するときは、まず debiancd.db にエントリを追加して、(getvendors.pl を使って) WML フォーマットの vendors.CD に変換します。そして、 WML と Makefile を使って魔法をかけます。すべての翻訳は既存の翻訳済テキストを使って再構築されますが、ベンダーのデータは新しいものになっています。 (無料で翻訳版もアップデート!)

新しいページを追加する

Debian に新しいページを追加するのはとても簡単です。ヘッダとフッタは WML が正しく作成してくれます。あなたがすべきことは、新しいファイルの先頭に次のような行を入れ、:

#use wml::debian::template title="TITLE OF PAGE"

本文を続けるだけです。News や security の記事など、そのセクション用に特別に作成されたものを使わないかぎり、すべてのページで wml::debian::template テンプレートを使うべきです。

このテンプレートでは、作成されるページに影響する特定の変数を宣言できます。これにより、それぞれの場所で様々なテンプレートを作成することを避け、簡単に実装を改良できるようになります。現在利用可能な変数とその意味は:

BARETITLE="true": 通常ならすべての <title> タグに表示される "Debian --" の部分を削除します。
NOHEADER="true": ページからヘッダ部分を削除します。当然ながら、本文にカスタムのヘッダを追加できます。
NOMIRRORS="true": ページからミラーサイトのドロップダウンリストを削除します。少数のページを除いて、これを利用すべきではありません。
NOHOMELINK="true": 通常ならページの下部に追加される、Debian のメインページに戻るリンクを削除します。
NOLANGUAGES="true": 通常ならページの下部に追加される、他の言語版へのリンクを削除します。
GEN_TIME="true": ソースファイルのタイムスタンプではなく、生成されたファイルのタイムスタンプを日付として設定します。
NOCOPYRIGHT="true": ページ下部の著作権表示を削除します。

これらの変数に使う値は、trueでもyesでもfooでも、文字列なら何でも構いません。

独自のヘッダを持った移植のページに、利用例があります。 ports/arm/index.wml では以下のようなヘッダが使われています。

#use wml::debian::template title="ARM Port" NOHEADER="yes"

既存のテンプレートでは実現できないことをしたい場合には、まずそれらの拡張を考えてください。互換性を保ったまま拡張するのが無理なら、既存のもののスーパーセットとなるような新しいテンプレートを作るようにしてください。そうすれば、次回のメジャーアップグレード時にそのテンプレートを使うよう、ページを変換できます (できればメジャーアップグレードは早くても半年に一度ぐらいであって欲しいですが)。

スクリプトによって生成されるページや、短かく無味乾燥な文章のページを作成するときは、翻訳を最新に保つ作業を簡単にするために <gettext> タグの利用を考慮してください。

他のファイルを含める

ページの一部を (メインのファイルに取り込まれる) 別個のファイルに分離したい場合、そのファイルの内容が翻訳されるべきであれば拡張子に .src を使用してください。そうすると普通の .wml ファイルと同様に変更が追跡されます。.inc のように他の拡張子を使うと、翻訳者が更新に気付かず、別の言語では内容が異なってしまうかもしれません。

新しいディレクトリを追加する

注意: install という名前のディレクトリは作らないでください。これは make を混乱させ、そのディレクトリの中のページが自動更新されなくなります。

以下はウェブサイトに新しいディレクトリを追加する例です。

   mkdir foo
   cvs add foo
   cd foo
   cp ../intro/Makefile .
   cvs add Makefile

親ディレクトリの Makefile を編集して、SUBS 変数に作成したディレクトリを加えてください。これにより、make 時に構築すべきディレクトリとして追加されます。

最後に、以下のコマンドですべての変更点をリポジトリにコミットします。

   cvs commit Makefile foo