Emacsにはセクションに分割してそれの記述者のような情報を与えるために、Lispライブラリー内で特別なコメントを使用する慣習があります。それらのアイテムにたいして標準的なフォーマットを使用すれば、ツール(や人)が関連する情報を抽出するのが簡単になります。このセクションでは以下の例を出発点にこれらの慣習を説明します。
;;; foo.el --- Support for the Foo programming language -*- lexical-binding: t; -*- ;; Copyright (C) 2010-2024 Your Name
;; Author: Your Name <yourname@example.com> ;; Maintainer: Someone Else <someone@example.com> ;; Created: 14 Jul 2010
;; Keywords: languages ;; URL: https://example.com/foo ;; This file is not part of GNU Emacs. ;; This file is free software... ... ;; along with this file. If not, see <https://www.gnu.org/licenses/>.
一番最初の行は以下のフォーマットをもつべきです:
;;; filename --- description -*- lexical-binding: t; -*-
この説明は1行に収まる必要があります。そのファイルで更に変数をセットするために‘-*-’指定が必要なら、lexical-bindingの後に配置してください。これにより最初の行が長くなりすぎるようなら、そのファイル終端でLocal
Variablesセクションを使用してください。
著作権表示には、(あなたがそのファイルを記述したなら)通常はあなたの名前をリストします。あなたの作業の著作権を主張する雇用者がいる場合には、かわりに彼らをリストする必要があるかもしれません。Emacsディストリビューション、またはGNU ELPAにあなたのファイルが受け入れられていなければ、著作権者をFree Software Foundation(またはそのファイルがGNU Emacsの一部)だと告知しないでください。著作権とライセンス通知の形式に関するより詳細な情報はthe guide on the GNU websiteを参照してください。
著作権表示の後は、それぞれが‘;; header-name:’で始まる複数のヘッダーコメント(header comment)を記述します。以下は慣習的に利用できるheader-nameのテーブルです:
このヘッダーは少なくともそのライブラリーの主要な作者の名前とemailアドレスを示す。複数の作者がいる場合には前に;;とタブか少なくとも2つのスペースがある継続行で彼らをリストする。わたしたちは‘<…>’という形式で連絡用emailアドレスを含めることを推奨する。たとえば:
;; Author: Your Name <yourname@example.com> ;; Someone Else <someone@example.com> ;; Another Person <another@example.com>
このヘッダーはAuthorヘッダーと同じフォーマット。これは現在そのファイルを保守(バグレポートへの応答等)をする人(か人々)をリストする。
MaintainerヘッダーがなければAuthorヘッダーの人(複数可)がMaintainerとみなされる。Emacs内のいくつかのファイルは、そのファイルのオリジナル作者がもはや責任をもっておらずEmacsの一部として保守されていることを意味するために、Maintainerに‘emacs-devel@gnu.org’を使用している。
このオプションの行はファイルのオリジナルの作成日付を与えるもので歴史的な興味のためだけに存在する。
個々のLispプログラムにたいしてバージョン番号を記録したいならこの行に配置する。Emacsとともに配布されたLispファイルはEmacsのバージョン番号自体が同じ役割を果たすので一般的には‘Version’ヘッダーをもたない。複数ファイルのコレクションを配布する場合には、各ファイルではなく主となるファイルにバージョンを記述することを推奨する。
この行はヘルプコマンドfinder-by-keywordでリストするキーワード。意味のあるキーワードのリストの確認にこのコマンドを使用してほしい。コマンドM-x
checkdoc-package-keywords
RETはfinder-known-keywordsにないすべてのキーワードを探して表示する。変数checkdoc-package-keywords-flagを非nilにセットすると、checkdocコマンドはチェックにキーワード検証を含める。
このフィールドはトピックでパッケージを探す人が、あなたのパッケージを見つける手段となる。キーワードを分割するにはスペースとカンマの両方を使用できる。
人はしばしばこのフィールドを単にFinder(訳注:
finder-by-keywordがオープンするバッファー)に関連したキーワードではなくパッケージを説明する任意のキーワードを記述する箇所だとみなすのは不運なことだ。
この行はライブラリーのウェブサイトを示す。
‘Version’がパッケージマネージャーによる使用に適切でなければ、パッケージは‘Package-Version’を定義でき、かわりにこれが使用される。これは‘Version’がRCSやversion-to-listでパース不能な何かであるようなら手軽である。パッケージ化の基礎を参照のこと。
これが存在する場合にはカレントパッケージが正しく動作するために依存するパッケージを示す。パッケージ化の基礎を参照のこと。これは(パッケージの完全なセットがダウンロードされることを確実にするために)ダウンロード時と、(すべての依存パッケージがあるときだけパッケージがアクティブになることを確実にするために)アクティブ化の両方でパッケージマネージャーにより使用される。
このフォーマットは単一行からなるリストのリスト。サブリストのcarはそれぞれパッケージの名前(シンボル)、cadrはversion-to-listでパース可能な許容し得る最小のバージョン番号(文字列)。バージョンが欠落したエントリー(単なるシンボルやある要素のサブリストであるようなエントリー)はバージョンが"0"のエントリーと等価。たとえば:
;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2") cl-lib (seq))
Emacs 27より古いバージョンをサポートする必要がないパッケージは、以下のように‘Package-Requires’ヘッダーを複数行に分割できる:
;; Package-Requires: ((emacs "27.1") ;; (compat "29.1.4.1"))
このフォーマットにおいても‘Package-Requires’と同じ行でリストを開始する必要があることに注意。
パッケージのコードは自動的に、実行中のEmacsのカレントのバージョン番号をもつ‘emacs’という名前のパッケージを定義する。これはパッケージが要求するEmacsの最小のバージョンに使用できる。
ほぼすべてのLispライブラリーは‘Author’と‘Keywords’のヘッダーコメント行をもつべきです。適切なら他のものを使用してください。ヘッダー行内で別のヘッダー行の名前も使用できます。これらは標準的な意味をもたないので害になることを行うことはできません。
わたしたちはライブラリーファイルのコンテンツを分割するために追加の提携コメントを使用します。これらは空行で他のものと分離されている必要があります。以下はそれらのテーブルです:
これはライブラリーが機能する方法を説明する、概論コメントを開始する。これは複製許諾の直後にあり‘Change Log’、‘History’、‘Code’のコメント行で終端されていること。このテキストはFinderパッケージで使用されるのでそのコンテキスト内で有意であること。
これは時間とともにそのファイルに加えられたオプションの変更ログを開始する。このセクションに過剰な情報を配置してはならない。(Emacsが行うように)バージョンコントロールシステムの詳細ログや個別のChangeLogファイルに留めるほうがよい。‘History’は‘Change Log’の代替え。
これはプログラムの実際のコードを開始する。
これはフッター行(footer line)。これはそのファイルの終端にある。これの目的はフッター行の欠落から、人がファイルの切り詰められたバージョンを検知することを可能にする。