[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
devel/website/working.wml
いまいです。
debian-www@org で話題に出て、見ると devel/website/ ではこれだけ残って
いたので訳してみました。チェックをお願いします。
ところどころ #nov 〜として疑問点を書いています。レビューの参考になれば。
原文:
http://cvs.debian.org/webwml/english/devel/website/working.wml?rev=1.32&cvsroot=webwml&content-type=text/vnd.viewcvs-markup
--
Nobuhiro IMAI <nov@xxxxxxxxxxxx>
Key fingerprint = F39E D552 545D 7C64 D690 F644 5A15 746C BD8E 7106
#use wml::debian::template title="Debian ウェブページの作業をするには" BARETITLE=true
#use wml::debian::toc
#use wml::debian::translation-check translation="1.32"
<toc-display/>
<hrline>
<toc-add-entry name="general">一般的な情報</toc-add-entry>
<h3>必要なリソース</h3>
<p>我々のウェブサイトについて作業をしたいなら、少なくともディスクに 60 MB
の空き容量を用意してください。これは現在のソースアーカイブのサイズに左右されます。
もし (偶然にも) 全ページを再構築することになったら、
少なくとも倍の容量が必要になるでしょう。部分的にしかチェックアウトしないなら、
もっと少ない容量で済みます。例えば、english/ ディレクトリは 18 MB あります。</p>
<h3>部分的なチェックアウト</h3>
<p>多くの人は <code>webwml</code> CVS ツリー全体をチェックアウトしないと思いますが、
重要なファイルが追加された後でそのディレクトリで完全な <kbd>cvs update</kbd>
を実行しなかった場合など、ファイルを失ったり不完全なビルドを招いたりすることがあります。
文句を言う前に (.wmlrc などの) 必要なファイルがあるかどうか確かめるのを忘れないでください。
</p>
<h3>「"#" で始まる行はなんですか?」</h3>
<p>WML では、"#" で始まる行はコメントです。
最終的なページに表示されないようにするには、通常の HTML
のコメントの方がよいでしょう。</p>
<p>WML についての詳しい情報は、<a href="using_wml">WML
の利用方法</a>のページを読んでください。</p>
<toc-add-entry name="etiquette">編集者のエチケット</toc-add-entry>
<h3>「このページを変更してもいいですか?」</h3>
<p>場合によります。typo などのちょっとした間違いなら、修正してください。</p>
<p>情報が少し足りないと気づいた場合も、気にせずに修正してください。</p>
<p>書き直しが必要なほどひどいと感じた場合は、議論のために debian-www
に問題を出してください。たぶん賛成できると思います。</p>
<p>テンプレート (つまり webwml/english/template/debian ディレクトリにあるファイル)
に問題があると思ったら、コミットする前に変更点についてよく考えてください。
テンプレートの変更は、時としてサイトの大部分を再構築することになりますから。</p>
<h3>ディレクトリを追加したら、Makefile も追加してください!</h3>
<p>CVS に新しいディレクトリを追加するときは、ちょっと注意してください。
カレントディレクトリが ../Makefile に記載されている場合、Makefile
を作成しなければ<b>いけません</b> — さもないと、<tt>make</tt>
がエラーメッセージを出します。</p>
<h3>明解で分かり易い英語を使ってください</h3>
<p>Debian のウェブページは英語がネイティブではない人々が読んで他の言語に翻訳するので、
明解で分かり易い英語で書き、スラングや分かりにくいイディオム、
古い英語などを使わないのがベストです。</p>
<p>これらを使いたい場合には、その意味を説明するコメントを追記してください。</p>
<h3>README を読んでください</h3>
<p>そのディレクトリがどのように構成されているか理解するのを助けるために、README
ファイルが置かれているディレクトリもあります。この領域で作業するのに必要な、
特別な情報が書かれているばずです。</p>
<h3>内容の変更とフォーマットの変更は分けてください</h3>
<p>パッチやコミットにおいては、常に内容の変更とフォーマットの変更を分けてください。
これらが混ざってしまうと、翻訳者が差分を見つけるのに苦労します。<kbd>cvs diff</kbd>
を実行してみると、そのような変更が混乱のもとになるのがよく分かるはずです。</p>
<p>一般的に、成り行き任せのフォーマット変更は避けてください。
ある修正をコミットする際に、古い部分への XHTML/XML 対応を同時にすべきではありません。
(もちろん、新しいページでは最初から正しくなっているばずです。)</p>
<h3>可能なら翻訳版も更新してください</h3>
<p>URL や組込み Perl コードの変更のように、WML
で使われている言語には依存しない変更もあります。翻訳中には大抵無視してしまうので、
typo の修正もこの範疇に入ります。このような言語非依存の変更をする際には、
他の言語を実際には知らなくてもすべての翻訳ファイルを同様に変更し、
安全に translation-check ヘッダのバージョンを上げられると思います。</p>
<p>翻訳者が自分で同様の作業をするのはそんなに大変なことではないですし、
英語を話す編集者が処理のためにすべてをチェックアウトするのは厄介なことです。
しかし、一人でさっさと出来ることに 2 ダースもの人々の手を煩わせるのを避けるためにも、
この作業を推奨します。</p>
<p>付け加えると、このような変更を簡単に適用するには、webwml CVS
モジュールのトップディレクトリにある <code>smart_change.pl</code>
スクリプトを使うとよいでしょう。</p>
<h4>smart_change.pl の使い方</h4>
<pre>smart_change.pl [options] origfile</pre>
<p>現在のところ、<code>/english/</code> 以下にあるファイルだけが <var>origfile</var>
として認められています。<code>smart_change.pl</code> は次のような引数を取ります:</p>
<dl>
<dt><code>-s, --substitute=<var>REGEXP</var></code></dt>
<dd>ソースファイルに適用する Perl
の正規表現を指定します (複数回指定することになるでしょう)。例えば:
<pre>
$> ./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
</pre>
最初のコマンドで変更を加え、次のコマンドで英語のオリジナルファイルと
各翻訳ファイルを確認しています。コミットする前にこうして実際の変更点を
確認してください。すべてが期待どおりなら、最後のコマンドで変更をコミットします。
</dd>
<dt><code>-l, --lang=<var>STRING</var></code></dt>
<dd>この言語を処理します (複数回指定することになるでしょう)。
言語が指定されなかった場合、存在するすべてのものを処理します。</dd>
<dt><code>-n, --no-bump</code></dt>
<dd>translation-check ヘッダのバージョンを上げません。
通常、各 translation-check ヘッダは、
翻訳済のファイルが最新の状態になれば一つ増やされ、
古いままならそのままにされます。このオプションが指定されると、
translation-check ヘッダは一切変更されません。
「ウェブサイトの翻訳を最新に保つ」ために <a href="uptodate">\
translation-check の説明</a>を見てください。
</dd>
#nov リンクを張るなら「ウェブサイトの翻訳を最新に保つ」の方では？
<dt><code>-p, --previous</code></dt>
<dd>CVS の前のリビジョンを表示します。これは主に、
すでに英語版がコミットされていて、前のバージョンに対して translation-check
ヘッダを確認したい場合に便利です。</dd>
<dt><code>-h, --help</code></dt>
<dd>簡単な使い方を表示します。</dd>
<dt><code>-v, --verbose</code></dt>
<dd>実行中に冗長なメッセージを表示します。</dd>
</dl>
<toc-add-entry name="links">リンク</toc-add-entry>
<h3>「このリンクは正しくなさそうです。変更すべきですか?」</h3>
<p>ウェブサーバは (<a href="content_negotiation">内容交渉</a> を使って)
設定されているので、内部のリンクを変更する必要は一切ないはずです。
実際にも変更しないことを勧めます。リンクがおかしいと思ったら、
変更する前に debian-www に知らせてください。</p>
#nov 一文目は () を外すと意味が分からない…
<h3>リンクの修正</h3>
<p>外部のウェブサイトへのリンクがリダイレクト (301、302、<meta>
タグによるリダイレクト、「このページは移動しました」と書かれている)
される場合は、そのことを debian-www に知らせてください。</p>
<p>リンク切れ (404、403、リンクとは違うページが表示される) を発見したら、
修正した上で debian-www に知らせてください。そうすれば、翻訳者も気づきます。
さらによいのは、他の翻訳すべてにおいてもリンクを修正し、
可能なら translation-check ヘッダを更新してください :-)。</p>
<toc-add-entry name="special">データとテキストの分離</toc-add-entry>
<h3>「foo.def とか foo.data というファイルはなんですか?」</h3>
<p>翻訳を最新の状態に保つのを容易にするために、テキスト部分 (text)
から共通部分 (data) を分離しているページがあります。
翻訳者はテキスト部分だけをコピーして翻訳すればよく、共通部分は自動的に付加されます。
</p>
<p>例を挙げると分かり易いでしょう。<code>CD/vendors</code>
にあるベンダーリストのページを生成するには、いくつものファイルを使います:</p>
<dl compact>
<dt><code>index.wml</code>:
<dd>ベンダーページの先頭のテキストは、このファイルにあります。
翻訳したものを各言語のディレクトリに配置します。
<dt><code>vendors.CD.def</code>:
<dd>このファイルには、各ベンダーのエントリに必要なテキスト片が含まれています。
訳は <code><<var>language</var>>/po/vendors.<var>xy</var>.po</code>
に追加します。
<dt><code>vendors.CD</code>:
<dd>このファイルには、言語に依存しない実際のベンダーエントリが含まれています。
翻訳者はこのファイルに触る必要はありません。
</dl>
<p><email "cdvendors@debian.org"> のうちの誰かが新規のベンダーを追加するときは、
まず <code>debiancd.db</code> にエントリを追加して、(<code>getvendors.pl</code>
を使って) WML フォーマットの <code>vendors.CD</code> に変換します。そして、
WML と Makefile を使って魔法をかけます。
すべての翻訳は既存の翻訳済テキストを使って再構築されますが、
ベンダーのデータは新しいものになっています。
(An updated translation for free! :-)</p>
#nov これ↑はどう訳せば？
<toc-add-entry name="newpage">新しいページを追加する</toc-add-entry>
<p>Debian に新しいページを追加するのはとても簡単です。
ヘッダとフッタは WML が正しく作成してくれます。
新しいファイルの先頭に次のような行を入れて、:</p>
<pre><protect>
#use wml::debian::template title="TITLE OF PAGE"
</protect></pre>
<p>本文を続けるだけです。News や security の記事など、
そのセクション用に特別に作成されたものを使わないかぎり、
すべてのページで <code>wml::debian::template</code> テンプレートを使うべきです。</p>
<p>このテンプレートでは、作成されるページに影響する特定の変数を宣言できます。
これにより、それぞれの場所で様々なテンプレートを作成することを避け、
簡単に実装を改良できるようになります。現在利用可能な変数とその意味は:</p>
<dl>
<dt>BARETITLE="true"
<dd>通常ならすべての <title> タグに表示される "Debian GNU/Linux --"
の部分を削除します。
<dt>NOHEADER="true"
<dd>ページからヘッダ部分を削除します。当然ながら、
本文にカスタムのヘッダを追加できます。
<dt>NOMIRRORS="true"
<dd>ページからミラーサイトのドロップダウンリストを削除します。
少数のページを除いて、これを利用すべきではありません。
<dt>NOHOMELINK="true"
<dd>通常ならページの下部に追加される、Debian
のメインページに戻るリンクを削除します。
<dt>NOLANGUAGES="true"
<dd>通常ならページの下部に追加される、他の言語版へのリンクを削除します。
<dt>GEN_TIME="true"
<dd>ソースファイルのタイムスタンプではなく、
生成されたファイルのタイムスタンプを日付として設定します。
<dt>NOCOPYRIGHT="true"
<dd>ページ下部の著作権表示を削除します。
</dl>
<p>これらの変数に使う値は、"true" でも "yes" でも "foo" でも、
文字列なら何でも構いません。</p>
<p>独自のヘッダを持った移植のページに、利用例があります。
<code>ports/arm/index.wml</code> では以下のようなヘッダが使われています。</p>
<pre><protect>
#use wml::debian::template title="ARM Port" NOHEADER="yes"
</protect></pre>
<p>既存のテンプレートでは実現できないことをしたい場合には、
まずそれらの拡張を考えてください。互換性を保ったまま拡張するのが無理なら、
既存のもののスーパーセットとなるような新しいテンプレートを作るようにしてください。
そうすれば、次回のメジャーアップグレード時にそのテンプレートを使うよう、
ページを変換できます (できれば早くても半年に一度ぐらいであって欲しいですが)。</p>
#nov ここも最後の () 内がよく分かってません。
<p>スクリプトによって生成されるページや、
ちょっとした散文的な文章のページを作成するときは、
翻訳を最新に保つ作業を簡単にするために <gettext> タグの利用を考慮してください。
#nov 「ちょっとした散文的な文章のページ」？
</p>
# think of a good example for <gettext> in new pages
<toc-add-entry name="newdir">新しいディレクトリを追加する</toc-add-entry>
<p>注意: <code>install</code>
という名前のディレクトリは<strong>作らないでください</strong>。
これは make を混乱させ、そのディレクトリの中のページが自動更新されなくなります。</p>
<p>以下はウェブサイトに新しいディレクトリを追加する注釈付きの例です。</p>
#nov annotated って「親ディレクトリ〜」のこと？
<pre>
mkdir foo
cvs add foo
cd foo
cp ../intro/Makefile .
cvs add Makefile
</pre>
<p>親ディレクトリの Makefile を編集して、<code>SUBS</code>
変数に作成したディレクトリを加えてください。これにより、make
時に構築すべきディレクトリとして追加されます。</p>
<p>最後に、以下のコマンドですべての変更点をリポジトリにコミットします。</p>
<pre>
cvs commit Makefile foo
</pre>
#nov この前に cd .. が必要では？