パッケージ開発と英語

Debian Project に提供するパッケージを作成する際、避けて通れないのが英語です。パッケージ作成の際、パッケージメンテナは最低限、以下の部分で英語を書くことが必要となります。

• パッケージ説明文 (Description:) (短い説明)
• パッケージ説明文 (Description:) (詳しい説明)
• 更新 (debian/changelog) ファイル

このうち、パッケージ説明文については、ユーザの目に触れるものであるため、 ある程度きちんとした英語を書く必要があります。以下に示すガイドラインを 参考にしてください。

英語に対して苦手意識を持つ人は多いですが、恐れる必要はありません。 そのうち慣れてくるものです。 もしわからないことがあれば、 Debian JP Developers メーリングリストなどで気軽に質問してください。

パッケージ説明文 (短い説明)

Debian パッケージの debian/control ファイルの Description: の行に続けて 1 行で書く説明のことです。この記述は、dpkg、dselect、 apt などのツールで使われるほか、 Web 上での検索や表示にも使われます。

パッケージの短い説明については、Branden Robinson さんが、 簡単なガイドラインを示しています。 以下に、その和訳を示します。

パッケージの短い記述は、以下のことを守るべきです。

• control ファイルが 80 文字の行に収まるようにする。 (パッケージ名と短い説明とが合計で 80 文字に達しないように)。
• 通常は、以下の文の ... 部分にあてはまるように書く。
  「<foo> is a package which provides (a/an) ...」 (訳注: 要するに、文ではなく名詞句を書いてくださいということです)。
• もし文字数が許し、説明に役立つなら、 パッケージ名に使った略称のフルネームを書く。
• そのパッケージをインストールしたいと思う人ならすでに知っていると 思われることは書かない (たとえば、python や perl パッケージを 何らかの形で扱おうと思っている人は普通、それがスクリプト言語である ということを知っているはずです。その事実を繰り返す必要はありません)。

パッケージの短い説明は、以下のことをするべきではありません。

1. パッケージの名前を繰り返すこと。 パッケージ名を示さずに説明だけが示されることはあり得ません。
2. 正式名称ではない名称で、ほかのパッケージ・プロトコル・標準などの 名前を書くこと。 (訳注: 原文は逆になっていますが、原文が誤りです)。 たとえば、
   • "X Window System", "X11", "X" を使い、"X Windows", "X-Windows", "X Window" を使わない。特に "X Window" は最悪です。
   • "GTK+" を使う。"GTK" や "gtk" はだめ。
   • "GNOME" と書く。"Gnome" はだめ。
   • "PostScript" と書く。"Postscript" や "postscript" はだめ。
3. どうしても必要だということがない場所で不定冠詞の "a" や "an" を使うこと。
4. 大文字やピリオドを含むこと。ただし 2. で必要とされる場合を除く。
5. これが Debian パッケージであるという情報を入れること (わかりきった情報です)。
6. "&"、"misc."、"etc." などの略称を使うこと。

パッケージの短い説明は、以下のことをしてはいけません。

• ほかのパッケージの短い説明と同一になること。
• 80 文字以上になること。

良い例

Description: simple configuration tool for Japanese environment

短くて、優しくて、余分な冠詞や記号がありません。

Description: Vi IMproved - enhanced vi editor

パッケージ名の "vim" の説明になっていて、 よく知られた実在するソフトウェアの名前を使って説明しています。

Description: reasonably versatile X-based image editing tool

"X-Windows-based" と書かないほうがよいことがこれでわかります。

Description: Debian Packaging Manual

Description: Perl extensions for writing pRPC servers and clients

「Perl」は「perl」と書くよりも正統でしょうか?

Description: an oscilloscope on acid

この説明は明らかに冗談めかして書かれているので、上記のルール (訳注: 冠詞を付けないこと) は適用されません (原注: 私は、プログラム自体が冗談で書かれていると思います :) )。 (訳注: acid には LSD という意味があり、上記説明文は 「(幻覚剤を服用して) ラリっているオシロスコープ」 というくらいの意味になります。)

あまり良くない例

Description: The Japanese version of chess.

必要ないのに文の形になっています。 "The" とピリオドを除くと良くなります。
改良案: Japanese version of chess

Description: Emacs-lisp python-mode for the scripting language Python.

Python の表記が不統一です。"lisp" は正統でしょうか。私は "LISP" が正しいと思っていました (ただし、これは Emacs Lisp という別の言語のときには問題にならないかもしれません)。 ピリオドで終わっているという別の問題もあります。
改良案: Emacs LISP major mode for the Python scripting language
あるいは Emacs major mode for Python

Description: The GNU wdiff utility. Compares two files word by word.

不要な大文字、冠詞、ピリオドがあります。
改良案: GNU "word-diff" utility for comparing files word by word

Description: A compression module for Python using zlib.

改良案: zlib compression module for Python

Description: The telnet client.

改良案: telnet client

Description: Frontends to DNS search.

最初の大文字と、ピリオド。情報が十分ではありません。
改良案: programs to perform lookups on DNS servers