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.

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. When pasting, make sure the first line on the page starts 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.”

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:

(global-set-key (kbd "C-z") 'eshell)
(global-set-key (kbd "C-x 4 C-z") 'eshell-other-window)
(defun eshell-other-window (&optional arg)
  (interactive "P")
  (if (one-window-p)
      (split-window)
    (other-window 1))
  (eshell arg))

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:

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: 305%

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.