GNU Info

(elisp)Library Headers

---

Prev: Comment Tips Up: Tips

---

Enter node , (file) or (file)node

Conventional Headers for Emacs Libraries
========================================

   Emacs 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.

   We'll start with an example, a package that is included in the Emacs
distribution.

   Parts of this example reflect its status as part of Emacs; for
example, the copyright notice lists the Free Software Foundation as the
copyright holder, and the copying permission says the file is part of
Emacs.  When you write a package and post it, the copyright holder would
be you (unless your employer claims to own it instead), and you should
get the suggested copying permission from the end of the GNU General
Public License itself.  Don't say your file is part of Emacs if we
haven't installed it in Emacs yet!

   With that warning out of the way, on to the 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.
     ...
     ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     ;; Boston, MA 02111-1307, USA.

   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.
     Please use that command to see a list of the meaningful keywords.

     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.  These should be separated by blank lines from anything
else.  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,
     terminated by a `Change Log', `History' or `Code' comment line.
     This text is used by the Finder package, so it should make sense
     in that context.

`;;; Documentation'
     This has been used in some files in place of `;;; Commentary:',
     but `;;; Commentary:' is preferred.

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

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