GNU Emacs Lisp Reference Manual

36.5: Conventional Headers for Emacs Libraries

Emacs 19 has conventions for using special comments in Lisp libraries to divide them into sections and give information such as who wrote them. This section explains these conventions. First, an example:

;;; 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.
copying permissions...

The very first line should have this format:

;;; filename --- description

The description should be complete in one line.

After the copyright notice come several header comment lines, each beginning with ;; header-name:. Here is a table of the conventional possibilities for header-name:

Author

This line states the name and net address of at least the principal author of the library.

If there are multiple authors, you can list them on continuation lines led by ;; and a tab character, like this:

;; 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

This line should contain a single name/address as in the Author line, or an address only, or the string FSF. If there is no maintainer line, the person(s) in the Author field are presumed to be the maintainers. The example above is mildly bogus because the maintainer line is redundant.

The idea behind the Author and Maintainer lines is to make possible a Lisp function to ``send mail to the maintainer'' without having to mine the name out by hand.

Be sure to surround the network address with <...> if you include the person's full name as well as the network address.

Created

This optional line gives the original creation date of the file. For historical interest only.

Version

If you wish to record version numbers for the individual Lisp program, put them in this line.

Adapted-By

In this header line, place the name of the person who adapted the library for installation (to make it fit the style conventions, for example).

Keywords

This line lists keywords for the finder-by-keyword help command. This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both.

Just about every Lisp library ought to have the Author and Keywords header comment lines. Use the others if they are appropriate. You can also put in header lines with other header names---they have no standard meanings, so they can't do any harm.

We use additional stylized comments to subdivide the contents of the library file. Here is a table of them:

;;; Commentary:

This begins introductory comments that explain how the library works. It should come right after the copying permissions.

;;; Change log:

This begins change log information stored in the library file (if you store the change history there). For most of the Lisp files distributed with Emacs, the change history is kept in the file ChangeLog and not in the source file at all; these files do not have a ;;; Change log: line.

;;; Code:

This begins the actual code of the program.

;;; filename ends here

This is the footer line; it appears at the very end of the file. Its purpose is to enable people to detect truncated versions of the file from the lack of a footer line.