14.1 Common Item Keywords

以降のセクションで説明するカスタマイズ宣言(customization declaration) — defcustom、defgroupなどはすべて、さまざまな情報を指定するためのキーワード引数(Constant Variablesを参照してください)を受け取ります。このセクションでは、カスタマイズ宣言のすべての種類に適用されるキーワードを説明します。

:tag以外のすべてのキーワードは、与えられたアイテムにたいして複数回使用できます。キーワードの使用はそれぞれ独立した効果をもちます。:tagは例外で、これはすべての与えられたアイテムは1つの名前だけを表示できるからです。

:tag label

labelを使用すると、カスタマイズメニュー(customization menu)およびカスタマイズバッファー(customization buffer)のアイテムのラベルづけに、そのアイテムの名前のかわりに指定された文字列を使用します。混乱を招くので、そのアイテムの実際の名前と、大きく異なる名前は使用しないでください。

:group group

このカスタマイズアイテムを、グループgroupに配します。defgroup内で:groupを使用した場合、そのアイテムは新しいグループ(:groupのサブグループ)になります。

このキーワードを複数回使用した場合、1つのアイテムを複数のグループに配すことができます。これらのグループのどれかを表示すると、このアイテムが表示されます。煩わしくなるので、多用しないでください。

:link link-data

このアイテムのドキュメント文字列の後に外部リンクを含めます。これは他のドキュメントを参照する、センテンスを含むボタンです。

link-dataに使用できる複数の候補があります:

(custom-manual info-node)

infoノードへのリンクです。info-nodeは、"(emacs)Top"のような、ノード名を示す文字列です。このリンクはカスタマイズバッファーの‘[Manual]’に表示され、info-nodeにたいしてビルトインのinfoリーダーを起動します。

(info-link info-node)

custom-manualと同様ですが、カスタマイズバッファーには、そのinfoノード名が表示されます。

(url-link url)

ウェブページヘのリンクです。urlはURLを指定する文字列です。カスタマイズバッファーに表示されるリンクは、browse-url-browser-functionで指定されたWWWブラウザーを呼び出します。

(emacs-commentary-link library)

ライブラリーのコメントセクション(commentary section)へのリンクです。libraryはライブラリー名を指定する文字列です。Library Headersを参照してください。

(emacs-library-link library)

Emacs Lispライブラリーファイルへのリンクです。libraryはライブラリー名を指定する文字列です。

(file-link file)

ファイルへのリンクです。fileは、ユーザーがこのリンクを呼び出したときにfind-fileでvisitするファイルの名前を指定する文字列です。

(function-link function)

関数のドキュメントへのリンクです。functionは、ユーザーがこのリンクを呼び出したときにdescribe-functionで説明を表示する関数の名前を指定する文字列です。

(variable-link variable)

変数のドキュメントへのリンクです。variableは、ユーザーがこのリンクを呼び出したときにdescribe-variableで説明を表示する変数の名前を指定する文字列です。

(custom-group-link group)

他のカスタマイズグループへのリンクです。このリンクを呼び出すことにより、groupにたいする新たなカスタマイズバッファーが作成されます。

link-dataの1つ目の要素の後に:tag nameを追加することにより、カスタマイズバッファーで使用するテキストを指定できます。たとえば(info-link :tag "foo" "(emacs)Top")は、そのバッファーで‘foo’と表示されるEmacs manualへのリンクを作成します。

複数のリンクを追加するために、このキーワードを複数回使用することができます。

:load file

このカスタマイズアイテムを表示する前に、ファイルfileをロードします(Loadingを参照してください)。ロードはloadにより行われ、そのファイルがまだロードされていないときだけロードします。

:require feature

保存したカスタマイズが、このアイテム値をセットするとき、(require 'feature)が実行されます。featureはシンボルです。

:requireを使用するもっとも一般的な理由は、ある変数がマイナーモードのような機能を有効にするとき、そのモードを実装するコードがロードされていない場合には、変数をセットするだけでは効果がないからです。

:version version

このキーワードは、そのアイテムが最初に導入されたEmacsバージョンversion、またはそのアイテムのデフォルト値がそのバージョンで変更されたことを指定します。値versionは文字列でなければなりません。

:package-version '(package . version)

このキーワードは、そのアイテムが最初に導入されたpackageのバージョンversionまたはアイテムの意味(またはデフォルト値)が変更されたバージョンを指定します。このキーワードは:versionより優先されます。

packageにはそのパッケージの公式名をシンボルとして指定します(たとえばMH-E)。versionには文字列を指定します。パッケージpackageがEmacsの一部としてリリースされた場合、packageとversionの値は、customize-package-emacs-version-alistの値に表示されるべきです。

Emacsの一部として配布された:package-versionキーワードを使用するパッケージは、customize-package-emacs-version-alist変数も更新しなければなりません。

Variable: customize-package-emacs-version-alist

このalistは、Emacsのバージョンにたいして、:package-versionキーワード内でリストされたパッケージのバージョンへのマッピングを提供します:

(package (pversion . eversion)…)

package(シンボル)それぞれにたいして、パッケージバージョンpversionを含む1つ以上の要素と、それに関連づけられるEmacsバージョンeversionが存在します。これらのバージョンは文字列です。たとえばMH-Eパッケージは、以下でalistを更新します:

(add-to-list 'customize-package-emacs-version-alist
             '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
                    ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
                    ("7.4" . "22.1") ("8.0" . "22.1")))

packageの値は一意である必要があり、また:package-versionキーワード内に現れるpackageの値とマッチする必要があります。おそらくユーザーはエラーメッセージからこの値を見るので、MH-EやGnusのようなパッケージの公式名を選択するのがよいでしょう。