gitback/el-get
1
0
Fork 0
mirror of https://github.com/dimitri/el-get.git synced 2024-09-29 13:08:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updated Home (markdown)

dabrahams 2011-05-29 04:58:42 -07:00
parent f3ecaf0317
commit cd7b2e95f7
1 changed files with 12 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
Home.md

@ -6,9 +6,16 @@ The mailing list archive is at [gmane.emacs.el-get.devel](http://blog.gmane.org/
# Guidelines for Recipe Authors # Guidelines for Recipe Authors
An el-get recipe should make code available on the local machine as though it were packaged with emacs. This means: An el-get recipe should make code available on the local machine as though it were packaged with Emacs. With very few exceptions, Emacs' own packages:
1. Don't turn on global-minor-modes; 1. Are loaded only *on-demand* via [`autoload`](http://www.gnu.org/software/emacs/elisp/html_node/Autoload.html)
1. Major modes for files can be added to `auto-mode-alist` for commonly-used unambigous file patterns. But in general this should be discouraged; try to get it fixed upstream instead; 1. *Do not* make features (such as minor mode and color theme) *globally active*;
1. `:feature` and `:load` are discouraged, even for "global" settings like color themes: what you have installed should not necessarily dictate your preferred environment. and only used if there's no way to make an autoload work, or if the package provides its own autoload file (e.g. nognus' `gnus-load.el`). In such cases, prefer `:feature` to `:load`, as the former will pick up the compiled version of the file, if any; 1. *Do* make features *globally available* (e.g. via autoloads);
1. If the upstream package doesn't mark its primary functions with a [autoload cookies](http://www.gnu.org/software/emacs/elisp/html_node/Autoload.html) or provide its own autoload file, it's acceptable to add a :pre-init or :post-init that calls `(autoload ...)` "manually". *Please*, however, try to get the package maintainer to add autoload cookies before you submit a recipe containing an manual autoload invocation 1. *Do* make features *selectively active* (e.g., activating a major mode based on filename) when that reflects popular practice.
If a package does not follow these principles "by itself", **please try to get the package maintainer to fix that before submitting a recipe that attempts to compensate**. If you can't get the package maintainer to make adjustments in a timely fashion, the following compensations in recipes are allowed and encouraged:
1. Major modes can be added to `auto-mode-alist` for *commonly-used, unambigous* file patterns.
1. A `:pre-init` or `:post-init` may call `(autoload ...)` "manually"
By default, el-get automatically compiles autoloads for any package written with [autoload cookies](http://www.gnu.org/software/emacs/elisp/html_node/Autoload.html) into a file that's loaded at startup. However, recipes for packages that generate their own autoload files at installation time should disable automatic autoloads and eagerly load that file instead. For example, the nognus recipe contains `:autoloads nil` and `:features gnus-load`. Aside from cases like this, there should almost never be a reason to use `:features` (or, as a last resort, `:load`).