A.5 Emacsライブラリのヘッダの慣習

Emacsには、コメントをいくつかの部分に分けて作者などの情報を与えるために、 Lispライブラリの特別なコメントに対する慣習があります。 本節ではそれらの慣習について述べます。 まず、例を示します。

     ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
     
     ;; Copyright (C) 1992 Free Software Foundation, Inc.
     
     ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
     ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
     ;; Created: 14 Jul 1992
     ;; Version: 1.2
     ;; Keywords: docs
     
     ;; This file is part of GNU Emacs.
     ...
     ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     ;; Boston, MA 02111-1307, USA.

最初の行はつぎの形式であるべきです。

     ;;; filename --- description

この記述は1行で完全になるようにします。

著作権表示のあとには、`;; header-name:'で始まる いくつかのヘッダコメント（header comment）行が続きます。 header-nameに使う可能性のある慣習の一覧を以下に示します。

`Author'

この行では、少なくともライブラリの主作者の 氏名とネットワークアドレスを明記する。

複数の作者がいる場合には、以下のように、 ;;とタブ文字で始めた継続行に その人達を列挙する。

          ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
          ;;      Dave Sill <de5@ornl.gov>
          ;;      Dave Brennan <brennan@hal.com>
          ;;      Eric Raymond <esr@snark.thyrsus.com>
     

`Maintainer'

この行には、作者行（`Author'）のように1人の氏名とアドレス、 アドレスのみ、文字列`FSF'のいずれかを書く。 保守者行（`Maintainer'）がない場合には、 作者行の人達が保守していると仮定する。 上の例は、保守者行が冗長であり、少々いんちきである。

作者行（`Author'）と保守者行（`Maintainer'）の考えは、 手作業で名前を探さずに『保守者にメイルを送る』ようなLisp関数を 作れるようにするためである。

ネットワークアドレスに加えて人の氏名も書く場合には、 ネットワークアドレスを`<...>'で必ず囲むこと。

`Created'

この行は省略できるが、ファイルの作成日時を書く。 歴史的な意味だけである。

`Version'

各Lispプログラムの版番号を記録しておきたい場合に、 この行に版番号を書く。

`Adapted-By'

このヘッダ行では、（たとえば、スタイルの慣習に適合するように変更したなどの） インストールのためにライブラリを受理した人の名前を書く。

`Keywords'

この行には、ヘルプコマンドfinder-by-keyword向けの キーワードを書く。 意味のあるキーワードを理解するためにこのコマンドを試してほしい。

この部分は重要である。 人々が特定の話題で探して読者のパッケージをみつけるであろう。 キーワードは空白やカンマで区切る。

ほとんどのLispライブラリには、 `Author'と`Keywords'のヘッダコメント行が必要です。 残りのものは必要に応じて使います。 別の名前のヘッダ行があってもかまいません。 それらには標準的な意味はありませんが、害になることもありません。

ライブラリファイルの内容を分割するために形式を定めたコメントも使います。 それらを以下に示します。

`;;; Commentary:'

ライブラリの動作を説明する入門的なコメントを始める。 著作権表示の直後にきて、 `Change Log'、`History'、`Code'のいずれかのコメント行で終る。 このテキストはパッケージfinderが使うので、 その文脈で意味があるようにすること。

`;;; Documentation'

`;;; Commentary:'のかわりに使っているファイルもあるが、 `;;; Commentary:'のほうが好ましい。

`;;; Change Log:'

（変更履歴をライブラリに収める場合の） ライブラリファイルに収めた変更記録情報を始める。 Emacsで配布されるほとんどのLispファイルでは、 変更履歴はファイルChangeLogに収めてあり、 ソースファイルには収めない。 それらのファイルには`;;; Change Log:'行はない。

`;;; Code:'

プログラムの実際のコードを始める。

`;;; filename ends here'

これは最終行（footer line）であり、ファイルの末尾に現れる。 その目的は、最終行が欠如していることでファイルが切り詰められていることが わかるようにするのである。