emacs-aurel/README.md

About

This is an Emacs package for searching, getting information and downloading AUR (Arch User Repository) packages. Its functionality is very similar to the one provided by cower, but instead of the command-line interface you use Emacs interface.

Also you can use it to (un)vote for packages and to (un)subscribe for package comments (see AUR account actions), i.e. it may be a substitution for aurvote and aurnotify.

This package uses AurJson RPC interface to get information about AUR packages.

You may look at the screenshot below or at this gif demonstration made by Ivaylo Kuzev to get an idea how aurel looks like (this demo is a bit outdated as it was made for version 0.1, the interface has changed since then).

(alect-light theme from alect-themes is used in this screenshot)

Installation

MELPA

The package can be installed from MELPA (with M-x package-install or M-x list-packages).

Manual

Add the following lines to your .emacs.

• Add a directory with this package to the load-path:

  (add-to-list 'load-path "/path/to/aurel-dir")

• Add autoloads for the interactive functions:

  (autoload 'aurel-package-info "aurel" nil t)
  (autoload 'aurel-package-search "aurel" nil t)
  (autoload 'aurel-package-search-by-name "aurel" nil t)
  (autoload 'aurel-maintainer-search "aurel" nil t)
  (autoload 'aurel-installed-packages "aurel" nil t)

• Set a directory where the packages will be downloaded:

  (setq aurel-download-directory "~/abs")

Usage

• Search for packages by name or description:

M-x aurel-package-search

Searching for multiple words (separated with spaces) is supported. If you want to search for a string containing spaces, quote it with double quotes ("..."). Examples of searching:

• ttf
• strategy game
• "python library" xml

• light weight "programming language"

• Search for packages only by name (i.e., only packages with names that contain a searched string will be displayed):

M-x aurel-package-search-by-name

• Search for packages by maintainer:

M-x aurel-maintainer-search

• Get an information about a package by exact name:

M-x aurel-package-info

• Display information about installed AUR packages:

M-x aurel-installed-packages

A particular filter (see Filtering) is useful here: press fv to hide the packages with the same installed and current AUR versions (i.e. to see the potential candidates for updating).

There are 2 kinds of buffers (major modes) for representing an information about packages:

• aurel-list-mode

Display packages in a form similar to a list of Emacs packages (M-x list-packages). Press RET to get more information about the current package or the marked packages (you can mark several packages with m/M and unmark with u/U/DEL).

• aurel-info-mode

Display more information about package(s) in a buffer with self-descriptive buttons. This buffer is similar to an Emacs customization buffer.

In both modes you can press d to download the package, but don't forget to set aurel-download-directory before.

Each aurel buffer has its own history similar to the history of the Emacs help or Info modes. You can move backward/forward by the history with l/r and refresh information with g.

Press h to see a hint (a summary of the available key bindings).

AUR account actions

If you have an AUR account, you can use aurel to vote for packages, to subscribe for new comments and to show additional information (whether a package is voted/subscribed by you or not).

The following keys are available in a buffer with package info by default:

• v to vote (C-u v to unvote)
• s to subscribe (C-u s to unsubscribe)

To enable receiving additional AUR user specific information (Voted and Subscribed lines should appear in the info buffer), use the following:

(setq aurel-aur-user-package-info-check t)

The first time aurel needs the above information, you will be prompted for your AUR account (you may set aurel-aur-user-name variable for convenience) and a password. The password is not saved anywhere, but a login cookie is saved (emacs saves cookies in ~/.emacs.d/url/cookies by default). The cookie is valid for about a month, so if you don't want to be prompted for the credentials every month, you may add the following line to your ~/.authinfo (or ~/.authinfo.gpg) file (see auth manual for details):

machine aur.archlinux.org login <user> password <password>

(Substitute <user> and <password> with your credentials)

Configuration

User options can be explored with M-x customize-group RET aurel.

Anything you see in info/list buffers is configurable using aurel-info-format and aurel-list-format variables.

If you want to change column titles (displayed in list buffer) and descriptions of package parameters (displayed in info buffer), there are aurel-list-titles/aurel-info-titles and aurel-titles (general for both buffer types) variables.

If you don't like the names of info and list buffers, you can change them like this:

(setq aurel-list-buffer-name "*aur-list*"
      aurel-info-buffer-name "*aur-info*")

By default, after receiving information about the packages from AUR server, pacman is called to get additional information about installed packages. If you want to disable that (to make the process a bit faster, for example), use the following:

(setq aurel-installed-packages-check nil)

Filtering

You can hide some of the displayed packages using filters. Press fC-h to see all available filter bindings. The most useful ones are:

• ff to select and enable a filter;
• fd to disable all filters;

A new filter will be added to the enabled ones, so for example you can hide unmaintained and outdated packages by pressing fm and fo. If you want to make a filter the only active, press C-u before a filter command.

Downloading a package

You can change the default behavior of a "downloading action" with aurel-info-download-function, aurel-list-download-function and aurel-list-multi-download-function (you can mark several packages for downloading with m/M and unmark with u/U/DEL) variables. Currently the following functions are available:

• aurel-download
• aurel-download-unpack (default in a list buffer)
• aurel-download-unpack-dired (default in an info buffer)
• aurel-download-unpack-pkgbuild
• aurel-download-unpack-eshell

Acknowledgements

The following people helped to improve this package:

• Andrea De Michele: fixed the pacman localization issue.