follow header conventions

[tarsius]

I maintain the Emacsmirror a mirror of Emacs packages here at github.

Eventually I want to provide a package manager which uses this mirror. This package manager is far from ready but it can already display a list of available packages and details about a package; similar to package-list-packages and describe-package from the official (as of the to be released Emacs-24) package.el package manager.

Since I mirror more than 3000 packages I can not maintain the package metadata manually like the maintainers of package.el and el-get.el do. Instead I extract it using the builtin library lisp-mnt.el and some custom tools.

Unfortunately many maintainers do not follow these conventions at all or not close enough for these extraction tools to work properly.

I mirror about 800 packages from github among which 120 do not follow the most important convention: how the summary line has to be formatted.

;;; foo.el --- Do foo with bar

For these 120 packages I am currently creating patches and submitting pull requests like this one.

In some cases I also corrected some other problems concerning the library header and/or deleted trailing whitespace. If I did not fix anything but the summary line please don't assume that the rest of the header is 100% correct; you might still want to improve it.

Also note that if you maintain additional packages I might not have created such a pull request for them even when they fail to follow the header conventions closely enough. I do so only (at this point) if the summary line can not be parsed. So please fix the headers of other libraries yourself.

Please read the official Header Conventions. Note that while creating this patch I tried to preserve your personal header style while following these conventions as closely as required by the extraction tools. You might want to further improve the header.

Here are some additional notes.

(To save some time I created this generic pull request message which mentions some common problems which might not all apply to this package. So please forgive me if some of this is not relevant to you.)

Summary Line

;;; foo.el --- Do foo with bar

This has to be on the first line, there are three semicolons and three dashes. The library name has to match the filename (therefor it ends with .el) and the provided feature (which obviously doesn't end with .el tough).

If you also define local variables using -*- ... -*- then that has to be done on the next line or at the end of the first line.

;;; foo.el --- Do foo with bar -*- baz: t -*-

or

;;; foo.el --- Do foo with bar
;; -*- baz: t -*-

There is not reason for -*- mode: emacs-lisp -*-. Really Emacs detects that on it's own... Also it is usually not necessary to specify the coding-system.

If the summary is rather long do not split it into two lines, the extraction tools fail to parse that. Instead make them shorter, which is also useful when the summary is displayed when listing packages or elsewhere.

Don't worry if the summary line is longer than 74 or 80 characters; what matters is the length of the summary sans the leading filename. It's probably a good idea for the summary to be no longer than ~30-40 characters (or even less) - but again if you can't make it this short without losing essential information don't worry to much.

However this:

;;; foo.el --- Foo is a global minor mode to do foo repeatedly while also going to the local bar based on baz

can probably be abbreviated as:

;;; foo.el --- Do foo with bar

Move the longer description to the Commentary section.

Also please make the summary useful to people who don't have the necessary domain knowledge. E.g. they should be able to tell from the summary that the package implements a major mode for some obscure programming language they have never heard of before and therefor is not of interest to them.

Commentary Section

;;; Commentary:

This begins with three dashes and ends with a colon.

The first sentence or paragraph should repeat the information from the summary line. Try to be brief but use whole sentences - this isn't the summary line, we have enough room.

If you feel the need to provide installation instructions preferably do so toward the end of the commentary section.

You might even want to create a separate section for the installation instructions. This breaks with the header conventions (or at least isn't mentioned there) but has the advantage that tools that extract the commentary won't include the installation instructions. And that is useful because these tools are commonly used to extract information for the benefit of a package manager, so the generic instructions would actually be incorrect because installation happens with something like M-x pm-install-package.

;;; Commentary:

;; This package...

;;; Installation:

;; Put `foo.el' in the `load-path' and add
;;
;;   (foo-mode)
;;
;; to your init file.

In any case do not only provide the installation instructions. At the very least duplicate the summary line at the beginning of the commentary section.

Also if your installation instructions are as generic as in the example above consider dropping them completely. This is common knowledge and for a complete beginner who never installed a package before yours (how likely is that?) this isn't enough information anyway (what is that load-path, where is my init file?). Don't duplicate the generic installation instructions from the Emacs info page in an incomplete way - just inform about additional things to consider.

Code Section

Put ;;; Code: after the commentary section and before the first require form. This might be kind of pointless but not following this convention just because is also rather pointless. (By the way lm-commentary will fail without this but my variant of that function does not.)

;;; Commentary:

;; This package...

;;; Code:

(require 'bar)
...

Maintainer and Author Header Lines

The convention requests both to be specified. In my opinion you can omit Maintainer if it is equal to Author.

;; Author: Jonas Bernoulli <jonas@bernoul.li>
;; Maintainer: Jonas Bernoulli <jonas@bernoul.li>

Multiple authors can be specified but only one maintainer. Note that you can't use Authors (plural) when there are multiple authors - lm-authors won't detect it (though my variant does).

;; Author: Jonas Bernoulli <jonas@bernoul.li>
;;      Linus Bernoulli <linus@bernoulli.cc>
  [^tab] (only one tab, nothing else)

Please consider not obfuscation the email address and wrap it with <...> even if you do obfuscate it.

Footer Line

(provide 'foo)
;;; foo.el ends here

Don't forget to provide the appropriate feature. The ;;; foo.el ends here? Omit it if you want I don't care. I think this is rather pointless in the age of distributed version control, then again not everybody has arrived there yet. I don't omit it in my libraries - that would weaken my position when telling people that following the conventions is important :-)