ElispArea

This is the EmacsWiki elisp area where we collect EmacsLisp files. No login required, no version control required, no ftp required, no password required. It’s as simple as the wiki itself. That also means that anybody can place malicious code in these EmacsLisp files. If in doubt, don’t use them.

Downloading

Links to EmacsLisp libraries hosted on the EmacsWiki come in two different forms.

Links to the plain text library look like Download:foo.el. To view the linked file just follow the link. After that you can use your browser’s save dialog to download the file.

Links that look like Lisp:foo.el take you to a wiki page which is an HTML file. Click on the Download link on that page to view or download the plain text file.

If you accidentally download and then try to load an HTML file in Emacs you will get an error like: “Loading library.el (source)… File mode specification error: (void-variable <!--)”.

Sometimes you will encounter links to libraries with neither the Lisp: nor Download: prefix. If they link to libraries on the Emacswiki they will never-the-less take you to either the plain text or html version of the library. Otherwise they link to files outside the Emacswiki in which case anything can happen.

Besides downloading individual libraries, you can also use Wget, Rsync or a version control system to download the files. See WikiDownload.

• Alphabetical list of all Elisp libraries on this Wiki
• Chronological list of all Elisp libraries on this Wiki (last seven days)
• By Category – Most of the links off of SiteMap are to categories pages, which link to relevant user-contributed libraries

For help installing a library, see InstallingPackages.

Uploading

Small files up to maybe 200k can be pasted into ordinary pages. Basic instructions follow but please also read and wherever possible follow the ElispAreaConventions.

First, create a page on the wiki explaining what the file does. See CreateNewPages for how to do this. On that page, create a link to the file itself using the Lisp prefix:

Example:

     Lisp:foo.el

Result:

Lisp:foo.el

This kind of link makes it easier for visitors to download the file, and to find references to the file.

Now follow the link, edit the page, and paste the file.

The file must start with three semicolons: ;;;.

When posting a link to the elisp file on other pages, a common practice is to also provide a link to the Wiki page(s) that describe the library, perhaps in parentheses. See TextFormattingRules for information about how to create link to wiki page.

Example:

     Lisp:color-moccur.el (OccurBuffer)

Result:

Lisp:color-moccur.el (OccurBuffer)

Uploading large files

Gzip files and upload them. Create a page to hold your file. Use the filename as pagename, eg. color-theme.el.gz. Edit the page, and click on the link below the save button that says to replace the text with a file.

Version Control

“Instead of hosting their projects in version control (say GitHub) they develop stuff locally, upload them to the wiki and say that this is the canonical way to obtain their software. Needless to say - this is a horrible, horrible practice.” – Die EmacsWiki, Die!, by BozhidarBatsov

Use Savannah, “the software forge for people committed to free software.”

Use Gists: “Gist is a simple way to share snippets and pastes with others. All gists are git repositories, so they are automatically versioned, forkable and usable as a git repository.”

…or use Fossil for all of those mini-projects and sync them via vc-fossil. Wiki, bug-tracker etc. included by default, easily clone- and forkable.

Code snippets

For a small set of functions or code snippets, just put them on the wiki pages directly, or add them to the ElispCookbook. If you do, make sure you use the <pre> and </pre> or the {{{ and }}} tags to protect the code from formatting.

Or use Gists: snippets of code hosted on github.

Or use Lisppaste:

<include lisppaste "http://paste.lisp.org/display/132682">

Result:

Conventions

The wiki is for free software only. Please make sure your files contain an appropriate blurb that says so. Code snippets are covered by the license in the footer of every page.

Please describe the EmacsLisp libraries you add to the Wiki. CreateNewPages to do that, or add the descriptions to existing pages.

Proposed guidelines for Emacs Lisp files on Emacs Wiki are in ElispAreaConventions.

If a file has been uploaded to the wiki, we consider it an implicit invitation to collaborative improve it. If you are the maintainer of code that has been changed on the site, you have several options:

1. treat it is a fork and ignore it
2. review the change and reject it – roll back the change and revert to an earlier version
3. agree to the change and merge it with your working copy if you use a version control system
4. agree to the change and do nothing if the copy on the wiki is the only official location

Other people fixing what they consider to be bugs and adding features they are missing seems to be the workflow that emerges naturally from the wiki nature of this site. If you disagree, see Version Control, above.

Alternatives

Here are some other places to download and distribute elisp code:

• ELPA – packages included in ELPA can be installed using the package.el package manager. The number of packages is limited but the ones that are included are of good quality; Marmalade and MELPA are both supplementary or alternative ELPA archives.
• el-get – gives apt-get user experience to emacs, includes support for emacswiki elisp files
• DELPS – packages which are made available in DELPS format, called epackages, can be installed using the reference implementation epackage.el package manager. This a modern implementation of ELPA: from centralized package repository to individually maintained distributed Git repositories with Debian style of packaging.
• Emacsmirror – a huge collection of packages which are distributed in form of Git repositories. Includes mirroring most of the packages found here: at EmacsWiki’s ElispArea. No support for package.el yet.
• WikifiedEmacsLispList – pointers to various files on authors’ own sites. Unfortunatly many links are dead (those that were not are also included in the Emacsmirror).
• Many pages on the EmacsWiki link to external sites with elisp libraries
• Various package hosting solutions (with version control). Some of the more popular ones are (links to Emacs specific pages for your searching pleasure):
  • Using Git -- repo.or.cz, gitlab, github (more)
  • Using Bazaar -- launchpad
  • Using Mercurial -- bitbucket (more)
  • Various vcs -- savannah, savannah nongnu, sourceforge

Tips

Additional tips can be found on Comments on ElispArea.

Tip: Version keyword

If you put a percent sign (%), then “Id:” (the colon is necessary), then another %, in a page of elisp code, it will end up being expanded into a revision number and look like this:

%Id: 309%

So you can have lisp files on the wiki be version-numbered automatically instead of manually.

Name conflicts

If you find libraries that duplicate existing Emacs libraries, consider why the code has been posted on the wiki.

1. A mistake – delete the page
2. A library that was hosted on the wiki before it got integrated into Emacs – in this case, it depends: Sometimes these copies are the last revision to actually work on older emacsen.
3. A patched copy – the page should probably be renamed.

Encoding

When pasting code on a page, make sure the code is UTF-8 encoded. (ASCII encoding is automatically valid UTF-8!) The wiki serves pages using a HTTP header telling browsers that the page will be UTF-8 encoded. If your code contains Latin-1 or other encodings, this will result in garbage: Invalid UTF-8.

This usually happens when code contains string literals. Consider using octal escapes instead:

  (replace-string "\221" "`" nil (point-min) (point-max))  ; opening single quote
  (replace-string "\222" "'" nil (point-min) (point-max))  ; closing single quote

To convince yourself that octal escapes really work, consider (length "\221") → 1.