Previous: Comment Tips, Up: Tips
Emacs has conventions for using special comments in Lisp libraries to divide them into sections and give information such as who wrote them. Using a standard format for these items makes it easier for tools (and people) to extract the relevant information. This section explains these conventions, starting with an example:
;;; foo.el --- Support for the Foo programming language ;; Copyright (C) 2010-2019 Your Name ;; Author: Your Name <yourname@example.com> ;; Maintainer: Someone Else <someone@example.com> ;; Created: 14 Jul 2010 ;; Keywords: languages ;; Homepage: http://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/>.
The very first line should have this format:
;;; filename --- description
The description should be contained in one line. If the file needs a ‘-*-’ specification, put it after description. If this would make the first line too long, use a Local Variables section at the end of the file.
The copyright notice usually lists your name (if you wrote the file). If you have an employer who claims copyright on your work, you might need to list them instead. Do not say that the copyright holder is the Free Software Foundation (or that the file is part of GNU Emacs) unless your file has been accepted into the Emacs distribution. For more information on the form of copyright and license notices, see the guide on the GNU website.
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:
;;
and a tab or at least two spaces.
We recommend including a contact email address, of the form
‘<...>’. For example:
;; Author: Your Name <yourname@example.com> ;; Someone Else <someone@example.com> ;; Another Person <another@example.com>
If there is no maintainer line, the person(s) in the Author field
is/are presumed to be the maintainers. Some files in Emacs use
‘FSF’ for the maintainer. This means that the original author is
no longer responsible for the file, and that it is maintained as part
of Emacs.
finder-by-keyword
help command.
Please use that command to see a list of the meaningful keywords. The
command M-x checkdoc-package-keywords <RET> will find and display
any keywords that are not in finder-known-keywords
. If you set
the variable checkdoc-package-keywords-flag
non-nil
,
checkdoc commands will include the keyword verification in its checks.
This field is how people will find your package when they're looking for things by topic. To separate the keywords, you can use spaces, commas, or both.
The name of this field is unfortunate, since people often assume it is
the place to write arbitrary keywords that describe their package,
rather than just the relevant Finder keywords.
version-to-list
. See Packaging Basics.
Its format is a list of lists on a single line. The car
of
each sub-list is the name of a package, as a symbol. The cadr
of each sub-list is the minimum acceptable version number, as a string
that can be parse by version-to-list
. An entry that lacks a
version (i.e., an entry which is just a symbol, or a sub-list of one
element) is equivalent to entry with version "0". For instance:
;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2") cl-lib (seq))
The package code automatically defines a package named ‘emacs’ with the version number of the currently running Emacs. This can be used to require a minimal version of Emacs for a package.
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 from anything else by blank lines. Here is a table of them: