Emms directory structure change/cleanup

I've been thinking about moving some parts of Emms to their own
directories in order to tidy up the distribution. Attached is a patch
which does this for the documentation. What do you people think?

>From 61459ce16456b31b119faefc6333007a023436d5 Mon Sep 17 00:00:00 2001
From: Yoni Rabkin <yonirabkin@member.fsf.org>
Date: Thu, 8 May 2008 23:58:07 +0300
Subject: [PATCH] Moved Emms documentation to a newly created doc directory.

As a first step in cleaning up the Emms distribution directory
structure, I've moved all the documentation to its own
directory. Makefiles have been created/updated accordingly.

Signed-off-by: Yoni Rabkin <yonirabkin@member.fsf.org>

4 files changed, 3605 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..cccdff3
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,10 @@
+# Don't delete if make is interrupted
+.PRECIOUS: %.info %.html
+
+all: emms.info
+
+%.info: %.texinfo
+	makeinfo --no-split $<
+
+%.html: %.texinfo
+	makeinfo --html --no-split $<
diff --git a/doc/emms.texinfo b/doc/emms.texinfo
new file mode 100644
index 0000000..5c9b5b0
--- /dev/null
+++ b/doc/emms.texinfo
@@ -0,0 +1,2419 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename emms.info
+@settitle The Emms Manual
+@c %**end of header
+
+@c History: The Emms manual was almost entirely rewritten for the
+@c release of Emms version 2.
+
+@c As a rule, modules which are stable enough to be included into the
+@c `emms-all' setup level should be documented. That is, any feature
+@c which is considered stable should be included.
+
+@dircategory Emacs
+@direntry
+* Emms: (emms).           The Emacs Multimedia System
+@end direntry
+
+@copying
+ @copyright{} 2004, 2005, 2006, 2007
+   Free Software Foundation, Inc.
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
+copy of the license is included in the section entitled "GNU Free
+Documentation License".
+@end quotation
+@end copying
+
+@c For printed material
+@titlepage
+@title The Emms Manual
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+@c END For printed material
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Emms Manual
+
+This is the Manual for the Emacs Multimedia System
+@menu
+Starting out
+* Introduction::        Introduction to Emms.
+* Installation::        How to install Emms on your System.
+* Simple Setup::        Quick, basic default Emms setup.
+* Configuration::       More detailed setup and configuration.
+* Quickstart Guide::    First steps with EMMS for new users.
+* Getting Help::        Where to get help with Emms and make suggestions.
+
+Emms basics
+* Basic Commands::      How to control Emms with ease.
+* The Core File::       The inner core of Emms.
+* Sources::             Sources for playlists-creation.
+* Simple Players::      Some simple players.
+* Playlists::           How Emms organizes media.
+
+Advanced Features
+* Track Information::        More narrative track descriptions.
+* Interactive Playlists::    Interactive Playlists.
+* Markable Playlists::       Allow tracks to be marked.
+
+Modules and Extensions
+* The Browser::          Advanced metadata browsing.
+* Sorting Playlists::    Sorting the order of the tracks.
+* Persistent Playlists:: Restoring playlists on emacs startup.
+* Editing Tracks::       Editing track information from within Emms.
+* Emms Mode Line::       Emms information on the mode line.
+* Music Player Daemon::  Interface to Music Player Daemon.
+* Streaming Audio::      Interface to streaming audio.
+* Lyrics::               Displaying lyrics synchronously.
+* Volume::               Changing the volume.
+* Last.fm::              Interact with http://www.last.fm's services.
+* Extending Emms::       How to define new players and modules.
+
+Copying and license
+* Copying::             The GNU General Public License gives you permission to
+                            redistribute Emms on certain terms; it also explains
+                            that there is no warranty.
+* The GNU FDL::         The license for this documentation.
+
+Indices
+* Concept Index::
+* Function Index::
+* Variable Index::
+* Keybinding Index::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Here are some other nodes which are really inferiors of the ones
+already listed, mentioned here so you can get to them in one step:
+
+Installation
+* Compiling Emms::      Compiling Emms into Byte-Code.
+
+The Core File
+* User Variables::     Variables for the user to tweak.
+* Hooks::              Hooks for important Emms functions.
+* Core Functions::     Providing the basic functionality of Emms.
+
+Track Information
+* Defining Info Methods::    Defining new info methods.
+
+Last.fm
+* Submitting track informations:: How to submit track information to last.fm.
+* Last.fm radio::                 How to listen to last.fm radio.
+
+Extending Emms
+* New Player::               How to define a new player.
+* Simple Player for `play':: Example player using @command{play}.
+* More Complex Player::      Example of a complex player using @command{mpg321}.
+@end detailmenu
+@end menu
+
+@end ifnottex
+
+
+@node Introduction
+@chapter Introduction
+
+@cindex introduction
+
+Emms is the Emacs Multi-Media System. It tries to be a clean and small
+application to play multimedia files from Emacs using external
+players. Many of its ideas are derived from
+@uref{http://www.nongnu.org/mp3player, MpthreePlayer}, but it tries to
+be more general and more clean.
+
+This manual tries to be the definitive source of information about
+Emms, an online version of the manual is available at:
+@uref{http://www.gnu.org/software/emms/manual/}.
+
+The basic functionality of Emms consists of three parts: The core, the
+sources, and the players.
+
+The core resides in @file{emms.el}, and provides a simple playlist and the
+basic functionality to use all the other features of Emms. It provides
+the common user commands and interfaces for other parts. It thinks in
+tracks, where a track is the combination of a type and a name - e.g.
+the track type 'file has a name that is the file name. Other track
+types are possible.
+
+To get to tracks, the core needs sources. The file @file{emms-source-file.el}
+provides simple sources to interact with the file system.
+
+When Emms finally has the sources in the playlist, it needs a player
+to play them. @file{emms-player-simple.el} defines a few useful players, and
+allows you to define your own in a very simple way.
+
+The way Emms works is easy to customize with your own code or by using
+`M-x customize'.
+
+@node Installation
+@chapter Installation
+
+@cindex installation
+
+You need to put all the .el files of emms in a directory in your
+load-path. For example, if you put all those files into ~/elisp/emms/,
+then in your ~/.emacs, you should do:
+
+@lisp
+(add-to-list 'load-path "~/elisp/emms/")
+@end lisp
+@noindent
+
+@menu
+* Compiling Emms::      Compiling Emms into Byte-Code.
+@end menu
+
+@node Compiling Emms
+@section Compiling Emms
+
+@cindex compiling
+
+If you are using XEmacs, you will need to edit @file{Makefile} as
+follows before continuing.
+
+@example
+EMACS=xemacs
+SITEFLAG=-no-site-file
+@end example
+
+You can byte-compile Emms by first entering the directory containing the
+Emms source code, followed by invoking:
+
+@command{make}
+
+Which will byte compile Emms. You can then invoke:
+
+@command{make install}
+
+Which will install Emms into your Emacs directories (provided you have
+the appropriate permissions to do so on your system).
+
+Note that Emms is a light-weight and agile program, you can therefore
+run Emms just fine without byte compiling it.
+
+@node Simple Setup
+@chapter Simple Setup
+
+@cindex simple setup
+@cindex setting up Emms
+@cindex quick setup
+
+After adding the location of the Emms code to the @var{load-path}
+variable, see @xref{Installation}. We invoke the following using the
+`emms-setup' feature which allows for quick and simple Emms setup.
+
+@lisp
+(require 'emms-setup)
+(emms-standard)
+(emms-default-players)
+@end lisp
+
+After which Emms is set-up and ready to go!
+
+The above will setup Emms with standard features (interactive
+playlists, audio track tag reading etc.) and a default list of players
+(ogg, mp3, mplayer etc.).
+
+The `emms-setup' feature is provided by the file
+@file{emms-setup.el}. It is essentially a collection of shortcuts for
+setting up Emms quickly and simply. Everything you can do with
+`emms-setup' can also be done manually.
+
+We use `emms-setup' by calling one of the setup functions. Each of the
+functions sets up Emms to include a number of features.
+
+@defun emms-minimalistic
+An Emms setup script.
+Invisible playlists and all the basics for playing media.
+@end defun
+
+@defun emms-standard
+An Emms setup script.
+Everything included in the @code{emms-minimalistic} setup, the Emms
+interactive playlist mode and reading information from tagged
+audio files.
+@end defun
+
+@defun emms-all
+An Emms setup script.
+Everything included in the @code{emms-standard} setup and adds all the
+stable features which come with the Emms distribution.
+@end defun
+
+@defun emms-devel
+An Emms setup script.
+Everything included in the @code{emms-all} setup and adds all of the
+features which come with the Emms distribution regardless of if they
+are considered stable or not.  Use this if you like living on the
+edge.
+@end defun
+
+`emms-setup' also comes with a convenience function to set a default
+list of media players.
+
+@defun emms-default-players
+Set @var{emms-player-list} to @var{emms-setup-default-player-list}.
+@end defun
+
+It is also worth noting that you can write your own Emms setup
+functions like the above by looking at the existing function
+definitions in @file{emms-setup.el}.
+
+@node Configuration
+@chapter Configuration
+
+@cindex Configuration
+
+This chapter discusses the configuration of Emms in more detail.
+
+The following code fragment provides a minimal Emms setup without
+using the layer of `emms-setup'. It can maybe be used to better
+understand the internals of Emms. You can see how Emms needs to know
+about players (these are defined in `emms-player-simple') and about
+sources for tracks (trivial file system based sources, such as this
+`emms-directory-tree', are defined in `emms-source-file').
+
+@lisp
+(require 'emms-player-simple)
+(require 'emms-source-file)
+(require 'emms-source-playlist)
+(setq emms-player-list '(emms-player-mpg321
+                         emms-player-ogg123
+                         emms-player-mplayer))
+@end lisp
+
+For a discussion on how to define additional players, see @xref{Simple
+Players}.
+
+Much of the behaviour of Emms can be changed by setting
+variables. For example:
+
+@lisp
+(setq emms-info-asynchronously nil)
+(setq emms-playlist-buffer-name "*Music*")
+@end lisp
+
+The first @code{setq} turns off the asynchronous updating of info tags. The
+second sets the default name of the Emms playlist buffer.
+
+Another way to change Emms variables is to use the M-x
+@command{customize} mechanism provided by Emacs.
+
+@menu
+* Finding files and speed::     Finding files quickly or portably.
+@end menu
+
+@node Finding files and speed
+@section Finding files and speed
+
+@cindex files
+@cindex speed
+
+Emms needs to traverse directories in order to find playable
+media. The default method Emms uses to achive this is
+@code{emms-source-file-directory-tree-internal} as defined in
+@file{emms-source-file.el}.  The above method is written portably and
+will always work, but might be too slow if we want to load several
+hundred tracks (or more).
+
+@file{emms-source-file.el} defines another method for finding files,
+@code{emms-source-file-directory-tree-find} which uses
+GNU/find. @code{emms-source-file-directory-tree-find} is usually an
+order of magnitude faster, but of course will not work if you do not
+have GNU/find installed.
+
+The method Emms will use is defined in the customisable variable
+@var{emms-source-file-directory-tree-function}.
+
+@node Quickstart Guide
+@chapter Quickstart Guide
+
+This chapter demonstrates how to setup EMMS so that you can start
+listening to your music without having to read all of the documentation
+first.
+
+The first thing you have to do is telling Emacs where the sources of
+EMMS are located. Let's say you have them in @file{~/elisp/emms/}. So
+add this line to your @file{.emacs}.
+
+@lisp
+(add-to-list 'load-path "~/elisp/emms")
+@end lisp
+
+Further informations about installing EMMS can be found in the
+installation chapter, @xref{Installation}.
+
+Let's say you want to enable all features which are considered stable by
+the EMMS developers. To achieve this you invoke the @code{emms-all}
+setup function by adding the following three lines to your @file{.emacs}.
+
+@lisp
+(require 'emms-setup)
+(emms-all)
+(emms-default-players)
+@end lisp
+
+The function @code{emms-default-players} in the last line sets up the
+list of default players. The list contains lightweight specialized
+players like ogg123 or mpg321 and we-play-everything-players like
+mplayer or xine. To be sure that emms can play all your music you should
+check that the needed players are installed.
+
+Further informations about the several setup scripts can be found in the
+simple setup chapter, @xref{Simple Setup}.
+
+Of course EMMS tries to display the tags of the music files you listen
+to. For this to work you have to make sure that the appropriate programs
+are installed. For mp3 files you need `mp3info', and for ogg files you
+need `ogginfo'.
+
+The last thing to do is to tell EMMS the root directory of our music
+collection. Let's say all your music is in @file{~/Music} or in
+subdirectories thereof.
+
+@lisp
+(setq emms-source-file-default-directory "~/Music/")
+@end lisp
+
+OK, now we've set up EMMS. Reload your @file{.emacs} or restart Emacs to
+let the changes have an effect.
+
+Now we will add all our music to a playlist by invoking @kbd{M-x
+emms-add-directory-tree RET ~/Music/ RET}. We do this because then EMMS
+will read the tags of all your music files and cache them. This is
+required for the browser, @xref{The Browser}.
+
+To switch to the playlist buffer, invoke @kbd{M-x emms-playlist-mode-go}
+or simply @kbd{M-x emms}. You can see that most tracks are displayed
+with their file name, but track by track the filename gets replaced with
+the artist and track name of the file's tag.
+
+Hit @kbd{RET} on a track to start playback.
+
+Now you can start exploring EMMS. It's probably best to begin with the
+basic commands (@pxref{Basic Commands}), the interactive playlists
+(@pxref{Interactive Playlists}), and the browser (@pxref{The Browser}).
+
+@node Getting Help
+@chapter Getting Help
+
+@cindex mailing list
+@cindex website
+
+If you have a bug to report, need help, or wish to suggest a feature,
+please feel free to use the Emms mailing list.  The address of the list
+is emms-help@@gnu.org.  To subscribe to it, visit
+@url{http://lists.gnu.org/mailman/listinfo/emms-help}.
+
+If you are familiar with the Gmane service, there is a Gmane newsgroup
+which mirrors this mailing address at gmane.emacs.emms.user.
+
+Emms also has a website at @url{http://www.gnu.org/software/emms/}.
+
+@node Basic Commands
+@chapter Basic Commands
+
+@cindex basic commands
+@cindex commands, basic
+
+Before you can use the interface commands, you need a playlist to
+start with. The following commands allow you to add to the current
+playlist from different sources:
+
+Note that the commands with the ``emms-add-'' prefix add the source to
+the playlist but do not start playing it immediately. Conversely, the
+commands with the ``emms-play-'' prefix begin playing the track
+immediately.
+
+@defun emms-play-file file
+A source for a single file - either @var{file}, or queried from the
+user. If called with a prefix the file will be added like
+@command{emms-add-file}.
+@end defun
+@defun emms-add-file file
+A source for a single file - either @var{file}, or queried from
+the user. If called with a prefix the file will be played like
+@command{emms-play-file}.
+@end defun
+@defun emms-play-directory dir
+A source for a whole directory tree - either @var{dir}, or queried
+from the user.
+@end defun
+@defun emms-add-directory dir
+A source for a whole directory tree - either @var{dir}, or queried
+from the user.
+@end defun
+@defun emms-play-directory-tree dir
+A source for multiple directory trees - either @var{dir}, or the
+value of @var{emms-source-file-default-directory}.
+@end defun
+@defun emms-add-directory-tree dir
+A source for multiple directory trees - either @var{dir}, or the
+value of @var{emms-source-file-default-directory}.
+@end defun
+@defun emms-play-url url
+A source for an @var{url} - for example, for streaming.
+@end defun
+@defun emms-add-url url
+A source for an @var{url} - for example, for streaming.
+@end defun
+@defun emms-play-playlist playlist
+A source for the M3u or PLS playlist format from the file @var{playlist}.
+@end defun
+@defun emms-add-playlist playlist
+A source for the M3u or PLS playlist format from the file @var{playlist}.
+@end defun
+@defun emms-play-find dir regexp
+A source that will find files in @var{dir} or
+@var{emms-source-file-default-directory} which match @var{regexp}.
+@end defun
+@defun emms-add-find dir regexp
+A source that will find files in @var{dir} or
+@var{emms-source-file-default-directory} which match @var{regexp}.
+@end defun
+
+The basic functionality of Emms is just to play music without being
+noticed. It provides a few commands to skip the current track and
+such, but other than that it doesn't show up. Emms provides the
+following basic user commands (which you might want to bind to
+keystrokes):
+
+@defun emms-start
+Start playing the current playlist
+@end defun
+@defun emms-stop
+Stop playing
+@end defun
+@defun emms-next
+Start playing the next track in the playlist
+@end defun
+@defun emms-previous
+Start playing previous track in the playlist
+@end defun
+@defun emms-shuffle
+Shuffle the current playlist. This uses
+@var{emms-playlist-shuffle-function}.
+@end defun
+@defun emms-sort
+Sort the current playlist. This uses
+@var{emms-playlist-sort-function}.
+@end defun
+@defun emms-show &optional insertp
+Describe the current Emms track in the minibuffer. If @var{insertp} is
+non-nil, insert the description into the current buffer instead. This
+function uses @var{emms-show-format} to format the current track.
+@end defun
+
+@node The Core File
+@chapter The Core File
+
+@cindex core file
+@cindex heart of Emms
+@cindex primitive functions
+
+The core file @file{emms.el} provides the all basic functions for
+playing music, generating playlists and defining players.
+
+@menu
+* User Variables::     Variables for the user to tweak.
+* Hooks::              Hooks for important Emms functions.
+* Core Functions::     Providing the basic functionality of Emms.
+@end menu
+
+@node User Variables
+@section User Variables
+
+@cindex user variables
+@cindex options
+
+The core file defines a number of user variables.
+
+@defopt emms-player-list
+A list of players Emms can use. You need to set this in order to use
+Emms to play media.
+@end defopt
+@defopt emms-show-format
+The format to use for @command{emms-show}. Any "%s" is replaced by
+what @var{emms-track-description-function} returns for the currently
+playing track.
+@end defopt
+@defopt emms-repeat-playlist
+Non-nil if the Emms playlist should automatically repeat the playlist.
+If nil, playback will stop when the last track finishes playing.
+@end defopt
+@defopt emms-track-description-function
+Function for describing an Emms track in a user-friendly way.
+@end defopt
+@defopt emms-sort-lessp-function
+A function that compares two tracks, and returns non-nil if the first
+track should be sorted before the second (see also @code{sort}).
+@end defopt
+
+@node Hooks
+@section Hooks
+
+@cindex hooks
+@cindex adding functionality
+
+The core file provides hook variables for the basic functionality of
+Emms.
+
+@defopt emms-player-started-hook
+A hook run when an Emms player started playing.
+@end defopt
+@defopt emms-player-stopped-hook
+A hook run when an Emms player stopped playing. See also
+@var{emms-player-finished-hook}.
+@end defopt
+@defopt emms-playlist-source-inserted-hook
+Hook run when a source got inserted into the playlist. The buffer is
+narrowed to the new tracks.
+@end defopt
+@defopt emms-playlist-selection-changed-hook
+Hook run after another track is selected in the Emms playlist.
+@end defopt
+@defopt emms-playlist-cleared-hook
+Hook run after the current Emms playlist is cleared. This happens both
+when the playlist is cleared and when a new buffer is created for it.
+@end defopt
+@defopt emms-player-finished-hook
+Hook run when an Emms player finishes playing a track. Please pay
+attention to the differences between @var{emms-player-finished-hook}
+and @var{emms-player-stopped-hook}. The former is called only when the
+player is stopped interactively; the latter, only when the player
+actually finishes playing a track.
+@end defopt
+@defopt emms-player-paused-hook
+Hook run when a player is paused or resumed. Use
+@var{emms-player-paused-p} to find the current state.
+@end defopt
+
+@node Core Functions
+@section Core Functions
+
+@cindex core functions
+@cindex basic functions
+
+The core file also defines all the functions important to the basic
+use of Emms.
+
+There are functions which deal with movement in the playlist.
+
+@defun emms-next-noerror
+Start playing the next track in the Emms playlist. Unlike
+@code{emms-next}, this function doesn't signal an error when called at
+the end of the playlist. This function should only be called when no
+player is playing. This is a good function to put in
+@code{emms-player-finished-hook}.
+@end defun
+@defun emms-playlist-next
+Move to the previous track in the current buffer.
+@end defun
+@defun emms-playlist-previous
+Move to the previous track in the current buffer.
+@end defun
+@defun emms-random
+Jump to a random track.
+@end defun
+@defun emms-toggle-repeat-playlist
+Toggle whether emms repeats the playlist after it is done. See
+@var{emms-repeat-playlist}.
+@end defun
+@defun emms-toggle-repeat-track
+Toggle whether emms repeats the current track. See
+@var{emms-repeat-track}.
+@end defun
+
+Some functions deal with the getting and setting track information.
+
+@defun emms-track type name
+Create a track with type @var{type} and name @var{name}.
+@end defun
+@defun emms-track-type track
+Return the type of @var{track}.
+@end defun
+@defun emms-track-name track
+Return the name of @var{track}.
+@end defun
+@defun emms-track-get name track &optional inexistent
+Return the value of @var{name} for @var{track}. If there is no value,
+return @var{default} (or nil, if not given).
+@end defun
+@defun emms-track-set track name value
+Set the value of @var{name} for @var{track} to @var{value}.
+@end defun
+@defun emms-track-description track
+Return a description of @var{track}. This function uses
+@var{emms-track-description-function}.
+@end defun
+@defun emms-player-for track
+Return an Emms player capable of playing @var{track}. This will be the
+first player whose PLAYABLEP function returns non-nil, or nil if no
+such player exists.
+@end defun
+@defun emms-playlist-current-selected-track
+Return the currently selected track in the current playlist.
+@end defun
+
+There are also functions which deal with the playing itself.
+
+@defun emms-player-start track
+Start playing @var{track}.
+@end defun
+@defun emms-player-stop
+Stop the currently playing player.
+@end defun
+@defun emms-player-stopped
+Declare that the current Emms player is finished.
+This should only be done by the current player itself.
+@end defun
+@defun emms-seek seconds
+Seek the current player @var{seconds} seconds. This can be a floating
+point number for sub-second fractions. It can also be negative to
+seek backwards.
+@end defun
+@defun emms-seek-forward
+Seek ten seconds forward.
+@end defun
+@defun emms-seek-backward
+Seek ten seconds backward.
+@end defun
+
+For more basic commands defined in the core file see @xref{Basic
+Commands}.
+
+@node Sources
+@chapter Sources
+
+@cindex Sources
+
+Sources allow Emms to add and play tracks. Emms comes with a number of
+sources of its own. Sources are designed so that creating new ones
+will be easy.
+
+For examples of Emms sources for files and directories see
+@file{emms-source-file.el}.
+
+@defopt emms-source-file-default-directory
+The default directory to look for media files.
+@end defopt
+@defun emms-play-find
+Play all files in @var{emms-source-file-default-directory} that match
+a specific regular expression.
+@end defun
+@defun emms-source-file &optional file
+An Emms source for a single file - either @var{file}, or queried from the
+user.
+@end defun
+@defun emms-source-files files
+An Emms source for a list of @var{files}.
+@end defun
+@defun emms-source-directory &optional dir
+An Emms source for a whole directory tree - either @var{dir}, or queried
+from the user
+@end defun
+@defun emms-source-directory-tree & optional dir
+An Emms source for multiple directory trees - either @var{dir}, or the
+value of @var{emms-source-file-default-directory}.
+@end defun
+@defun emms-source-playlist file
+An EMMS source for playlists.  See `emms-source-playlist-formats' for
+a list of supported formats.
+@end defun
+@defun emms-source-playlist-native file
+An EMMS source for a native EMMS playlist file.
+@end defun
+@defun emms-source-playlist-m3u file
+An EMMS source for an m3u playlist file.
+@end defun
+@defun emms-source-playlist-pls file
+An EMMS source for a pls playlist file.
+@end defun
+@defun emms-source-find &optional dir regex
+An Emms source that will find files in @var{dir} or
+@var{emms-source-file-default-directory} that match @var{regexp}.
+@end defun
+@defun emms-source-file-directory-tree &optional dir
+Return a list of all files under @var{dir} which match @var{regex}.
+@end defun
+@defun emms-source-dired
+Play all marked files of a dired buffer
+@end defun
+@defun emms-source-file-regex
+Return a regexp that matches everything any player (that supports
+files) can play.
+@end defun
+@defun emms-locate regexp
+Search for @var{regexp} and display the results in a locate buffer
+@end defun
+
+@node Simple Players
+@chapter Simple Players
+
+@cindex players, simple
+
+@defmac define-emms-simple-player name types regex command &rest args
+Define a simple player with the use of `emms-define-player'.
+@var{name} is used to construct the name of the function like
+emms-player-@var{name}. @var{types} is a list of track types
+understood by this player. @var{regex} must be a regexp that matches
+the filenames the player can play. @var{command} specifies the command
+line argument to call the player and @var{args} are the command line
+arguments.
+@end defmac
+
+For a discussion on how to define new players see @xref{New Player}.
+
+@defun emms-player-simple-stop
+Stop the currently playing process, if indeed there is one.
+@end defun
+@defun emms-player-simple-start filename cmdname params
+Starts a process playing @var{filename} using the specified @var{cmdname} with
+the specified @var{params}.
+@end defun
+@defun emms-player-simple-sentinel proc str
+Sentinel for determining the end of process for the process @var{proc}
+and the sentinel string @var{str}.
+@end defun
+
+@node Playlists
+@chapter Playlists
+
+@cindex organizing tracks and media
+
+Emms uses Emacs buffers to store the media tracks for playing. We call
+one such buffer a ``playlist buffer'' or an ``Emms playlist
+buffer''. Emms then proceeds to play the media tracks in the buffer
+from top to bottom until the end of the playlist.
+
+The name of the playlist buffer is defined in the variable
+@var{emms-playlist-buffer-name} and is set to be an invisible Emacs
+buffer by default. You can change to any name you want. For an example
+configuration see @xref{Configuration}.
+
+You can create any number of playlist buffers you wish. At any time
+Emms has a single ``current'' buffer through which it proceeds track
+by track.
+
+@defun emms-playlist-new &optional name
+Create a new playlist buffer.
+The buffer is named @var{name}, but made unique. @var{name} defaults
+to `emms-playlist-buffer-name'. If called interactively, the new
+buffer is also selected.
+@end defun
+
+@defun emms-playlist-save &optional format file
+Store the current playlist to FILE as the type FORMAT.  The default
+format is specified by `emms-source-playlist-default-format'.
+@end defun
+
+The current Emms playlist buffer is stored in the variable
+@var{emms-playlist-buffer}.
+
+@node Track Information
+@chapter Track Information
+
+@cindex track information
+@cindex info tags
+
+Emms is distributed with two predefined methods for retrieving info,
+provided by @file{emms-info-mp3info.el} and
+@file{emms-info-ogginfo.el}. Both packages are front-ends for
+command-line tools. Ogg track information is retrieved using the
+@uref{http://directory.fsf.org/audio/ogg/vorbistools.html, ogginfo}
+software. Likewise, mp3 track information is available using
+@uref{http://www.ibiblio.org/mp3info/, mp3info}.
+
+Automatic track information retrieval is enabled by default in the
+`emms-standard', `emms-all' and `emms-devel' setup levels provided by
+@file{emms-setup.el}. For more information about @file{emms-setup.el}
+see @xref{Simple Setup}.
+
+If you would like to know how Emms track retreival works and how we
+can define new methods for track retrieval see @xref{Defining Info
+Methods}.
+
+There are a number of user variables which control the behaviour of
+`emms-info'.
+
+@defopt emms-info-auto-update
+Non-nil when Emms should update track information if the file changes.
+This will cause hard drive activity on track loading. If this is too
+annoying for you, set this variable to nil.
+@end defopt
+@defopt emms-info-asynchronously
+Non-nil when track information should be loaded asynchronously. This
+requires the feature `later-do' which is provided by the file
+@file{later-do.el}, which should come with Emms.
+@end defopt
+@defopt emms-info-functions
+Functions which add information to tracks.  Each is called with a
+track as argument.
+@end defopt
+
+@menu
+* Defining Info Methods::    Defining new info methods.
+@end menu
+
+@node Defining Info Methods
+@section Defining Info Methods
+
+@cindex defining info methods
+
+An info method essentially consists of a function which given an Emms
+track returns the appropriate info for that track.
+
+We can for example look at the predefined method for retrieving
+information about audio tracks in the Ogg format.
+
+The function @command{emms-info-ogginfo} provided by
+@file{emms-info-ogginfo.el} accepts an Emms track as a single
+argument and returns the appropriate information string.
+
+We then register our info function with Emms by adding it to the
+@var{emms-info-functions} list. The function will then be called at
+the right time to provide track info.
+
+@lisp
+(add-to-list 'emms-info-functions 'emms-info-ogginfo)
+@end lisp
+
+@node Interactive Playlists
+@chapter Interactive Playlists
+
+@cindex Interactive Playlists
+
+Emms provides a visual, interactive playlist mode as well as the
+ability to use playlists without ever looking at then. This visual,
+interactive mode is called the `emms-playlist-mode' and is defined in
+@file{emms-playlist-mode.el}.
+
+The interactive playlist mode is enabled by default in the
+`emms-standard', `emms-all' and `emms-devel' setup levels. For more
+information about Emms setup levels see @xref{Simple Setup}.
+
+@defun emms-playlist-mode-go
+Switch to the current emms-playlist buffer and use emms-playlist-mode.
+@end defun
+
+If you wish to make this the default EMMS playlist mode, add the
+following to your @file{.emacs}.
+
+@lisp
+(setq emms-playlist-default-major-mode 'emms-playlist-mode)
+@end lisp
+
+The interactive playlist buffer shows the tracks in the current Emms
+playlist in the order in which they will be played. The current track
+will be highlighted.
+
+When in the interactive playlist mode we can perform different actions
+on the current playlist.
+
+@table @kbd
+@item a
+@findex emms-playlist-mode-add-contents
+Add files in the playlist at point to the current playlist buffer.
+If we are in the current playlist, make a new playlist buffer and
+set it as current.
+@item b
+@findex emms-playlist-set-playlist-buffer
+Set the current playlist buffer.
+@item n
+@findex emms-next
+Start playing the next track in the playlist.
+@item p
+@findex emms-next
+Start playing the previous track in the playlist.
+@item s
+@findex emms-stop
+Stop playing.
+@item P
+@findex emms-pause
+Pause.
+@item >
+@findex emms-seek-forward
+Seek ten seconds forward.
+@item <
+@findex emms-seek-backward
+Seek ten seconds backward.
+@item f
+@findex emms-show
+Describe the currently playing track in the minibuffer.
+@item c
+@findex emms-playlist-mode-center-current
+Display the current track in the center of the screen.
+@item RET
+@findex emms-playlist-mode-play-current-track
+Start playing the track under point. Note that this is also available
+with @kbd{<mouse-2>}.
+@item SPC
+@findex scroll-up
+Scroll up a near full page.
+@item M-<
+@findex emms-playlist-mode-first
+Go to the first track in the playlist. @kbd{M->} completes this
+command by going to the last track in the playlist using
+@command{emms-playlist-mode-last}.
+@item r
+@findex emms-random
+Go to a randomly selected track in the playlist.
+@item q
+@findex bury-buffer
+Put the interactive playlist buffer at the end of the list of all
+buffers.
+@item C-x C-s
+@findex emms-playlist-save
+Save the current playlist buffer to a file.
+@item ?
+@findex describe-mode
+Describe the mode.
+@end table
+
+We can also edit the playlist using familiar GNU/Emacs commands:
+
+@table @kbd
+@item C-k
+@findex emms-playlist-mode-kill-track
+Remove the track under point from the playlist buffer. Also available
+using the @kbd{d} key.
+@item C-y
+@findex emms-playlist-mode-yank
+See the command @command{yank}
+@item C-w
+@findex emms-playlist-mode-kill
+See the command @command{kill-region}
+@item M-y
+@findex emms-playlist-mode-yank-pop
+See the command @command{yank-pop}.
+@item C-j
+@findex emms-playlist-mode-insert-newline
+Insert a newline at point.
+@end table
+
+We can use the regular GNU/Emacs killing and yanking commands to move
+and copy tracks in between playlist buffers. We can use the same
+commands to insert arbitrary text into the playlist buffers together
+with the playlist tracks. Text which is not a track is ignored by the
+program and can therefore be used to include titles and annotations
+within the playlist.
+
+@node Markable Playlists
+@chapter Markable Playlists
+
+@cindex Markable Playlists
+
+The Markable Playlists provided by the file @file{emms-mark.el} are an
+alternative to the default interactive playlists, @xref{Interactive
+Playlists}. They allow marking tracks with keybindings familiar to users
+of dired.
+
+To enable the Markable Playlists you have to add
+
+@lisp
+(require 'emms-mark)
+@end lisp
+
+to your @file{.emacs}. Then you can activate @command{emms-mark-mode} by
+executing @command{M-x emms-mark-mode} in a playlist buffer. You can
+return to the default interactive playlist mode with @command{M-x
+emms-mark-mode-disable}.
+
+If you wish to make this the default EMMS playlist mode, add the
+following to your @file{.emacs}.
+
+@lisp
+(setq emms-playlist-default-major-mode 'emms-mark-mode)
+@end lisp
+
+@table @kbd
+@item m
+@findex emms-mark-forward
+Marks the current track and sets point one line forward. If a prefix
+argument ARG is given, it will mark the next ARG tracks and set point
+accordingly. A negative argument marks backward.
+@item U
+@findex emms-mark-unmark-all
+Unmarks all tracks in the playlist.
+@item t
+@findex emms-mark-toggle
+Toggles mark on the current track.
+@item u
+@findex emms-mark-unmark-forward
+Unmarks same way as @command{emms-mark-forward} marks.
+@item % m
+@findex emms-mark-regexp
+Marks all tracks in the playlist matching the given regular
+expression. A prefix argument means to unmark them instead.
+@end table
+
+When tracks are marked you can operate on them:
+
+@table @kbd
+@item D
+@findex emms-mark-delete-marked-tracks
+Deletes the marked tracks from the playlist.
+@item K
+@findex  emms-mark-kill-marked-tracks
+Deletes the marked tracks from the playlist and places them in the
+kill-ring, so that you can @command{yank} in into another playlist.
+@item W
+@findex emms-mark-copy-marked-tracks
+Adds the marked tracks to the kill-ring, so that you can @command{yank}
+them into another playlist.
+@end table
+
+emms-mark is also intent to provide a way for user to select tracks
+for other command to operate on them. Currently,
+@file{emms-tag-editor.el} used the emms-mark to edit tags of selected
+tracks. Two function is useful for elisp programer to handle marked
+tracks.
+
+@defun emms-mark-do-with-marked-track
+This function take a function to perform on all marked tracks. A
+optional argument `move-flag' to tell the function to move forward
+line after calling given function. If the given function didn't change
+position, the second argument should set to non-nil.
+@end defun
+
+@defun emms-mark-mapcar-marked-track
+This function is very similar to `emms-mark-do-with-marked-track'
+except it collects result of given function (that's why named with
+`mapcar').
+@end defun
+
+@node Extending Emms
+@chapter Extending Emms
+
+@cindex new players
+@cindex defining players
+@cindex new players, defining
+
+Emms introduces a high abstraction layer for playing music so you can
+customise it to your needs.
+
+@menu
+* New Player::               How to define a new player.
+* Simple Player for `play':: An example player using @command{play}.
+* More Complex Player::      Example of a complex player using @command{mpg321}.
+@end menu
+
+@node New Player
+@section New Player
+
+@cindex new player
+@cindex defining new players
+
+The file @file{emms-player-simple.el} defines some easy players to
+start with, but it shouldn't be hard to provide a function for your
+favourite player. We will start with an easy example that shows how
+we can use the @command{play} command under Unix to play our WAV files.
+
+@node Simple Player for `play'
+@section Simple Player for `play'
+
+@cindex simple player
+@cindex primitive player
+@cindex basic player
+
+Play is a very easy command line player for various format. If you
+want your emms to play WAV files just put the following lines in you
+@file{.emacs}:
+
+@lisp
+(require 'emms-player-simple)
+(define-emms-simple-player play '(file) "\\.wav$" "play")
+@end lisp
+@noindent
+
+Huh! Wasn't that easy?
+
+The macro function @command{define-emms-simple-player} takes a minimum
+of three arguments. The first argument (@emph{play} in our example)
+defines the name of the player. It's used to name the player
+functions. The second is a regexp, that defines which files to play
+with our player. @emph{\\.wav$} matches any filename ending with a dot
+and the string wav. The last argument is the actual command line
+command we use to play our files. You can also add the path but we
+just assume that the command is in your path. All arguments you add to
+these three are optional. They define the command line arguments you
+want to add to your argument. If you want to hear the wav file of your
+favourite artist in the most possible volume use the following line:
+
+@lisp
+(require 'emms-player-simple)
+
+(define-emms-simple-player play
+                           '(file)
+                           "\\artist-*.wav$"
+                           "play"
+                           "--volume=100")
+@end lisp
+@noindent
+
+Please notice that you have to add the arguments as strings!
+
+The command line tool you use for @command{define-emms-simple-player}
+has to take one song as argument and stop after playing that
+particular song. For any other concept you will need to customise
+emms a bit more...
+
+@node More Complex Player
+@section More Complex Player
+
+@cindex complex player
+@cindex advanced player
+
+The most players you use will be simple players so you don't need to
+read this chapter. But if you are curious how you can use (almost) every
+player in emms read further...
+
+In this chapter we will use mpg321 to construct a player that
+actually can pause a track, restart it and show rest time. We won't
+implement all of that, but after that chapter you will know how to
+define it.
+
+The command @command{define-emms-simple-player} is just a abstraction
+layer for @command{define-emms-player}, which is a little bit more
+complicated but much more powerful!
+
+@lisp
+(define-emms-player "emms-mpg321-remote"
+  :start 'emms-mpg321-remote-start
+  :stop 'emms-mpg321-remote-stop
+  :playablep 'emms-mpg321-remote-playable-p)
+@end lisp
+@noindent
+
+So, that is almost all! @command{define-emms-player} takes a minimum
+of three arguments. The first is the name of the player. The rest are
+methods with functions to call. Three methods are required: start,
+stop and playable. Start says Emms how to start a track (sic!), stop
+how to stop a player and playablep should return non-nil if the player
+can play the track.
+
+So we just need these three functions to get our mpg321-remote:
+
+First we code the start function. We will check if there's a open
+process and start one otherwise. Then we send a string to the process
+with the filename and set a filter.
+
+@lisp
+(defun emms-mpg321-remote-start ()
+  (unless (get-process ``mpg321-remote'')
+    (setq emms-mpg321-remote-process
+	  (start-process "mpg321-remote-process"
+			 "*mpg321*" "mpg321" "-R" "abc"))
+  (process-send-string "mpg321-remote-process"
+		       (concat "l " (emms-track-name track)))
+  (set-process-filter emms-mpg321-remote-process 'emms-mpg321-remote-filter)))
+@end lisp
+@noindent
+
+We need the filter, as mpg321-remote won't quit after playing the
+track as the simple player do. We wait until the process sends the
+output ``(at-sign)P 0'' (the signal of mpg321 that the song ended) to the
+filter and call emms-mpg321-remote-stop.
+
+@lisp
+(defun emms-mpg321-remote-filter (process output)
+  (when (string-match "(at-sign)P 0" output)
+    (emms-mpg321-remote-stop)))
+@end lisp
+@noindent
+
+@command{emms-mpg321-remote-stop} won't do anything interesting. It
+just test if there are other files to play and close the process otherwise.
+
+@lisp
+(defun emms-mpg321-remote-stop ()
+  (unless emms-playlist
+    (process-send-string "mpg321-remote-process" "Q\n"))
+@end lisp
+@noindent
+
+And to make that a playable example I also added
+@command{emms-mpg321-remote-playablep}, which I really just steal
+from @file{emms-player-simple.el}
+
+@lisp
+(defun emms-mpg321-remote-playablep (track)
+       "Return non-nil when we can play this track."
+       (and (eq 'file (emms-track-type track))
+@end lisp
+@noindent
+
+Now we have a ready player and we could add commands like
+@command{emms-mpg321-remote-pause} for example.
+
+@node The Browser
+@chapter The Browser
+
+The Browser allows you to browse the metadata cache and add tracks to
+your playlist. It includes a powerful interactive mode.
+
+The Browser is defined in @file{emms-browser.el} and is included in
+the @command{emms-all} setup level. For more information about Emms
+setup levels see @xref{Simple Setup}.
+
+You can also manually add the Browser to your Emms setup by loading it
+explicitly with:
+
+@lisp
+(require 'emms-browser)
+@end lisp
+
+To be properly useful, you should do M-x
+@command{emms-add-directory-tree} to all the files you own at least
+once so that the cache is fully populated.
+
+@menu
+* Browser Interface::     The interactive browser interface.
+* Filtering Tracks::      Displaying a subset of the tracks.
+* Displaying Covers::     Displaying album covers in the browser interface.
+* Changing Looks::        Changing the tree structure, display format and faces.
+@end menu
+
+@node Browser Interface
+@section Browser Interface
+
+The browser interface allows you to display and interact with your
+tracks in many different ways. There are a number of ways to start the
+browser.
+
+@defun emms-smart-browse
+Display browser and playlist. Toggle between selecting browser,
+playlist or hiding both. Tries to behave sanely if the user has
+manually changed the window configuration.
+@end defun
+
+@defun emms-browse-by-artist
+Display the browser and order the tracks by artist.
+@end defun
+
+@defun emms-browse-by-album
+Display the browser and order the tracks by album.
+@end defun
+
+@defun emms-browse-by-genre
+Display the browser and order the tracks by genre.
+@end defun
+
+@defun emms-browse-by-year
+Display the browser and order the tracks by year.
+@end defun
+
+Once the Browser is displayed you can use it to managed your track
+collection and playlists. The Browser is interactive and has its own
+keybindings.
+
+@table @kbd
+
+@item C-j
+@kindex C-j (emms-browser)
+@findex emms-browser-add-tracks-and-play
+Add all tracks at point, and play the first added track.
+
+@item RET
+@kindex RET (emms-browser)
+@findex emms-browser-add-tracks
+Add all tracks at point.
+
+@item SPC
+@kindex SPC (emms-browser)
+@findex emms-browser-toggle-subitems
+Show or hide (kill) subitems under the current line.
+
+@item 1
+@kindex 1 (emms-browser)
+@findex emms-browser-collapse-all
+Collapse everything.
+
+@item 2
+@kindex 2 (emms-browser)
+@findex emms-browser-expand-to-level-2
+Expand all top level items one level.
+
+@item 3
+@kindex 3 (emms-browser)
+@findex emms-browser-expand-to-level-3
+Expand all top level items two levels.
+
+@item 4
+@kindex 4 (emms-browser)
+@findex emms-browser-expand-to-level-4
+Expand all top level items three levels.
+
+@item C
+@kindex C (emms-browser)
+@findex emms-browser-clear-playlist
+Clear the playlist.
+
+@item E
+@kindex E (emms-browser)
+@findex emms-browser-expand-all
+Expand everything.
+
+@item d
+@kindex d (emms-browser)
+@findex emms-browser-view-in-dired
+View the current directory in dired.
+
+@item q
+@kindex q (emms-browser)
+@findex emms-browser-bury-buffer
+Bury the browser buffer.
+
+@item r
+@kindex r (emms-browser)
+@findex emms-browser-goto-random
+Jump to a random track.
+
+@item /
+@kindex / (emms-browser)
+@findex emms-isearch-buffer
+Isearch through the buffer.
+
+@item <
+@kindex < (emms-browser)
+@findex emms-browser-previous-filter
+Redisplay with the previous filter.
+
+@item >
+@kindex > (emms-browser)
+@findex emms-browser-next-filter
+Redisplay with the next filter.
+
+@item ?
+@kindex ? (emms-browser)
+@findex describe-mode
+See the Emacs documentation for the function.
+
+@item C-/
+@kindex C-/ (emms-browser)
+@findex emms-playlist-mode-undo
+Undo the previous playlist action.
+
+@item <C-return>
+@kindex <C-return> (emms-browser)
+@findex emms-browser-add-tracks-and-play
+Add all tracks at point, and play the first added track.
+
+@item <backtab>
+@kindex <backtab> (emms-browser)
+@findex emms-browser-prev-non-track
+Jump to the previous non-track element.
+
+@item <tab>
+@kindex <tab> (emms-browser)
+@findex emms-browser-next-non-track
+Jump to the next non-track element.
+
+@item s A
+@kindex s A (emms-browser)
+@findex emms-browser-search-by-album
+Search the collection by album.
+
+@item s a
+@kindex s a (emms-browser)
+@findex emms-browser-search-by-artist
+Search the collection by artist.
+
+@item s s
+@kindex s s (emms-browser)
+@findex emms-browser-search-by-names
+Search the collection by names.
+
+@item s t
+@kindex s t (emms-browser)
+@findex emms-browser-search-by-title
+Search the collection by title.
+
+@item b 1
+@kindex b 1 (emms-browser)
+@findex emms-browse-by-artist
+Browse the collection by artist.
+
+@item b 2
+@kindex b 2 (emms-browser)
+@findex emms-browse-by-album
+Browse the collection by album.
+
+@item b 3
+@kindex b 3 (emms-browser)
+@findex emms-browse-by-genre
+Browse the collection by genre.
+
+@item b 4
+@kindex b 4 (emms-browser)
+@findex emms-browse-by-year
+Browse the collection by year.
+
+@item W a p
+@kindex W a p (emms-browser)
+@findex emms-browser-lookup-album-on-pitchfork
+Lookup the album using Pitchfork.
+
+@item W a w
+@kindex W a w (emms-browser)
+@findex emms-browser-lookup-album-on-wikipedia
+Lookup the album using Wikipedia.
+@end table
+
+@node Filtering Tracks
+@section Filtering Tracks
+
+If you want to display a subset of your collection (such as a
+directory of 80s music, only avi files, etc.) then you can extend the
+Browser by defining ``filters''.
+
+Show everything:
+
+@lisp
+(emms-browser-make-filter "all" 'ignore)
+@end lisp
+
+Set "all" as the default filter:
+
+@lisp
+(emms-browser-set-filter (assoc "all" emms-browser-filters))
+@end lisp
+
+Show all files (no streamlists, etc):
+
+@lisp
+(emms-browser-make-filter
+ "all-files" (emms-browser-filter-only-type 'file))
+@end lisp
+
+Show only tracks in one folder:
+
+@lisp
+(emms-browser-make-filter
+ "80s" (emms-browser-filter-only-dir "~/Mp3s/80s"))
+@end lisp
+
+Show all tracks played in the last month:
+
+@lisp
+(emms-browser-make-filter
+ "last-month" (emms-browser-filter-only-recent 30))
+@end lisp
+
+After executing the above commands, you can use M-x
+emms-browser-show-all, emms-browser-show-80s, etc to toggle between
+different collections. Alternatively you can use '<' and '>' to cycle
+through the available filters.
+
+The second argument to make-filter is a function which returns t if a
+single track should be filtered. You can write your own filter
+functions to check the type of a file, etc.
+
+Show only tracks not played in the last year:
+
+@lisp
+(emms-browser-make-filter "not-played"
+ (lambda (track)
+  (not (funcall (emms-browser-filter-only-recent 365) track))))
+@end lisp
+
+Show all files that are not in the pending directory:
+
+@lisp
+(emms-browser-make-filter
+ "all"
+ (lambda (track)
+   (or
+    (funcall (emms-browser-filter-only-type 'file) track)
+    (not (funcall
+          (emms-browser-filter-only-dir "~/Media/pending") track)))))
+@end lisp
+
+@node Displaying Covers
+@section Displaying Covers
+
+The browser will attempt to display cover images if they're
+available. By default it looks for images cover_small.jpg,
+cover_med.jpg, etc. Customize @var{emms-browser-covers} to use your
+own covers. Note that you'll probably want to resize your existing
+covers to particular sizes. Suggested sizes are 100x100 for small, and
+200x200 for medium.
+
+Also, Emacs by default will jump around a lot when scrolling a buffer
+with images. In order to prevent that, you can set
+@var{scroll-up-aggressively} and @var{scroll-down-aggressively} to the
+number ``0.0''.
+
+To show a 'no cover' image for albums which don't have a cover, add
+the following code to your .emacs:
+
+@lisp
+(setq emms-browser-default-covers
+  (list "/path/to/cover_small.jpg" nil nil)
+@end lisp
+
+The medium and large images can be set as well.
+
+You can download an example @uref{http://repose.cx/cover_small.jpg,
+`no cover' image}.
+
+@node Changing Looks
+@section Changing Looks
+
+The Browser's look can be customised. You can change the way the tree
+structure looks, the display format and display faces.
+
+@subheading Changing Tree Structure
+
+You can change the way the tree is displayed by modifying the function
+@command{emms-browser-next-mapping-type}.
+
+The following code displays artist->track instead of
+artist->album->track when you switch to the 'singles' filter:
+
+@lisp
+(defadvice emms-browser-next-mapping-type
+                                (after no-album (current-mapping))
+  (when (eq ad-return-value 'info-album)
+    (setq ad-return-value 'info-title)))
+@end lisp
+
+@lisp
+(defun toggle-album-display ()
+  (if (string= emms-browser-current-filter-name "singles")
+      (ad-activate 'emms-browser-next-mapping-type)
+    (ad-deactivate 'emms-browser-next-mapping-type)))
+
+(add-hook 'emms-browser-filter-changed-hook 'toggle-album-display)
+@end lisp
+
+@subheading Changing Display Format
+
+Format strings govern the way items are displayed in the browser and
+playlist. You can customize these if you wish.
+
+@var{emms-browser-default-format} controls the format to use when no
+other format has been explicitly defined. By default, only track and
+albums deviate from the default.
+
+To customise the format of a particular type, find the name of the
+field you want to use (eg `info-artist', `info-title', etc), and
+insert that into emms-browser-<type>-format or
+emms-browser-playlist-<type>-format. For example, if you wanted to
+remove track numbers from tracks in both the browser and playlist, you
+could do:
+
+@lisp
+(defvar emms-browser-info-title-format "%i%n")
+(defvar emms-browser-playlist-info-title-format
+  emms-browser-info-title-format)
+@end lisp
+
+The format specifiers available include:
+
+@itemize @w
+@item
+%i    indent relative to the current level
+@item
+%n    the value of the item - eg -info-artist might be ``pink floyd''
+@item
+%y    the album year
+@item
+%A    the album name
+@item
+%a    the artist name of the track
+@item
+%t    the title of the track
+@item
+%T    the track number
+@item
+%cS   a small album cover
+@item
+%cM   a medium album cover
+@item
+%cL   a big album cover
+@end itemize
+
+Note that if you use track-related items like %t, it will take the
+data from the first track.
+
+@subheading Changing Display Faces
+
+The faces used to display the various fields are also customizable.
+They are in the format emms-browser-<type>-face, where type is one of
+"year/genre", "artist", "album" or "track". Note that faces lack the
+initial "info-" part. For example, to change the artist face, type M-x
+@command{customize-face} @command{emms-browser-artist-face}.
+
+@node Sorting Playlists
+@chapter Sorting Playlists
+
+@cindex sort
+@cindex track order
+
+The `emms-playlist-sort' module, defined in the
+@file{emms-playlist-sort.el} package provides functions for sorting
+Emms playlists. `emms-playlist-sort' can be loaded by invoking:
+
+@lisp
+(require 'emms-playlist-sort)
+@end lisp
+
+@defun emms-playlist-sort-by-name
+Sort playlist by name in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-artist
+Sort playlist by artist in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-title
+Sort playlist by title in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-album
+Sort playlist by album in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-year
+Sort playlist by year in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-note
+Sort playlist by notes in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-score
+Sort emms playlist by score in descending order.
+@end defun
+
+@node Persistent Playlists
+@chapter Persistent Playlists
+
+The Emms module @file{emms-history.el} makes playlists persistent over
+emacs sessions.  To make use of this feature put this into your
+~/.emacs.
+
+@lisp
+(require 'emms-history)
+@end lisp
+
+When you kill emacs all playlists will be saved in the file given by the
+variable:
+
+@defopt emms-history-file
+The file to save playlists in.  It defaults to
+"~/.emacs.d/emms-history".
+@end defopt
+
+After you started up emacs again, you can restore all saved playlists
+with this function.
+
+@defun emms-history-load
+Restore all playlists in `emms-history-file'.
+@end defun
+
+If that should be done automatically on each startup, put these lines
+into your ~/.emacs.
+
+@lisp
+(require 'emms-history)
+(emms-history-load)
+@end lisp
+
+Normally @code{emms-history} only restores playlists.  If you want it to
+start playback afterwards, you can tweak this variable.
+
+@defopt emms-history-start-playing
+If non-nil emms starts playing the current track after
+`emms-history-load' was invoked.  The default value is nil.
+@end defopt
+
+@node Editing Tracks
+@chapter Editing Tracks
+
+@cindex track editor
+
+Using @file{emms-tag-editor.el}, emms can set tag informations of tracks
+and write them back to the file with the help of external programs, such
+as `mp3info', `vorbiscomment'.
+
+Use the keybinding @kbd{E} to edit the tags of track under point in the
+playlist or all marked tracks (@pxref{Markable Playlists} for how to
+mark tracks).  The track's tag informations are listed in a special
+buffer `*EMMS-TAGS*' in text format.  Field names are marked in bold
+face and are not editable.  Any tag information is placed behind an
+equal sign and is changable.  A special field `name' is the track's file
+name.  If any change is made in this field, the track's file will be
+renamed to the new name.  When you finished editing the tag infos use
+@kbd{C-c C-c} (which calls @code{emms-tag-editor-submit-and-exit}) to
+submit the changes and close the `*EMMS-TAGS*' buffer.
+
+There are a few commands to perform changes on all tracks.
+
+@defun emms-tag-editor-set-all tag value
+Set TAG to VALUE in all tracks.
+
+If transient-mark-mode is turned on, you can apply the command to a
+selected region.
+
+If `transient-mark-mode' is on and the mark is active, the changes will
+only take effect on the tracks in the region.
+@end defun
+
+@defun emms-tag-editor-replace-in-tag tag from to
+Query and replace text in selected TAG.
+
+For example, if the info-title tag is selected, then only perform
+replacement in title tags.
+
+If `transient-mark-mode' is on and the mark is active, the changes will
+only take effect on the tracks in the region.
+@end defun
+
+@defun emms-tag-editor-transpose-tag tag1 tag2
+Transpose value of TAG1 and TAG2.
+
+If `transient-mark-mode' is on and the mark is active, the changes will
+only take effect on the tracks in the region.
+@end defun
+
+@defun emms-tag-editor-submit arg
+Make modified tags take affect.
+
+With prefix argument, bury the tag edit buffer.
+@end defun
+
+If you want to extend the tag editor to work with file formats other
+than `mp3' and `ogg', have a look at these variables.
+
+@defvr {Variable} emms-tag-editor-formats
+This variable determine how to insert track fields to
+`emms-tag-editor-edit-buffer'.  Emms tag info editable fields is usually
+determined by the extension of track name.  The variable
+`emms-tag-editor-tags' contains all tags that emms track may have.  A
+single charactar is assigned to the tag to make the
+`emms-tag-editor-formats' easier to generate.
+@end defvr
+
+@defvr {Variable} emms-tag-editor-tagfile-functions
+To write tags to track file, an extern program should specified in this
+variable.
+
+If the external program has an interface like `mp3info', you don't have
+to write a function.  Take `mp3' and `ogg' as example.
+@end defvr
+
+@heading Renaming Files
+
+The tag editor is also capable to rename the file of the track at point
+or all files of the marked tracks according to the value this variable.
+
+@defopt emms-tag-editor-rename-format
+When `emms-tag-editor-rename' is invoked the track's file will be
+renamed according this format specification.  The file extension will be
+added automatically.
+
+It uses the format specs defined in @code{emms-tag-editor-tags}.
+
+The default value is "%a - %l - %n - %t", so that files are named
+
+  <Artist> - <Album> - <Tracknumber> - <Title>.<extension>
+
+after renaming.
+@end defopt
+
+To perform the renaming put point on the track you want to rename or
+mark some tracks.  Then hit @kbd{R} which calls this function:
+
+@defun emms-tag-editor-rename
+Rename the file corresponding to track at point or all marked tracks
+according to the value of @code{emms-tag-editor-rename-format}.
+@end defun
+
+@node Emms Mode Line
+@chapter Emms Mode Line
+
+@cindex mode line
+@cindex display emms information
+
+We can display information about the currenty playing track on the
+Emacs mode line using the package `emms-mode-line' which is provided
+by the file @file{emms-mode-line.el}.
+
+To activate this feature invoke:
+
+@lisp
+(require 'emms-mode-line)
+(emms-mode-line 1)
+@end lisp
+
+It is also possible to display the amount of time a track has been
+playing. This feature is defined in the `emms-playing-time' package
+which is provided by the file @file{emms-playing-time.el}.
+
+To use this feature invoke:
+
+@lisp
+(require 'emms-playing-time)
+(emms-playing-time 1)
+@end lisp
+
+Note: `(emms-playing-time -1)' will disable emms-playing-time module
+completely, and is not recommended. (since some other emms modules may
+rely on it, such as `emms-lastfm.el')
+
+Instead, to toggle displaying playing time on mode line, one could call
+`emms-playing-time-enable-display' and
+`emms-playing-time-disable-display'."
+
+@defun emms-playing-time-enable-display
+Display playing time on mode line.
+@end defun
+
+@defun emms-playing-time-disable-display
+Remove playing time from mode line.
+@end defun
+
+@node Music Player Daemon
+@chapter Music Player Daemon
+
+@cindex music player daemon
+@cindex remote interface
+@cindex mpd
+
+Emms provides an interface to the @uref{http://www.musicpd.org/, Music
+Player Daemon}(MusicPD) software. The package is called `emms-player-mpd' and
+is provided by the file @file{emms-player-mpd.el}.
+
+The advantages of using MusicPD as an EMMS backend include the
+following.
+
+@itemize @bullet
+@item minimal CPU usage
+@item fast access of track information
+@item optional crossfade
+@end itemize
+
+@subheading Setup
+
+To load `emms-player-mpd' invoke:
+
+@lisp
+(require 'emms-player-mpd)
+@end lisp
+
+Set the variables @var{emms-player-mpd-server-name} and
+@var{emms-player-mpd-server-port} to the location and port
+(respectively) of your MusicPD server. For example:
+
+@lisp
+(setq emms-player-mpd-server-name "localhost")
+(setq emms-player-mpd-server-port "6600")
+@end lisp
+
+If your MusicPD setup requires a password, you will to set
+@var{emms-player-mpd-server-password} as follows.
+
+@lisp
+(setq emms-player-mpd-server-password "mypassword")
+@end lisp
+
+To get track information from MusicPD, invoke the following:
+
+@lisp
+(add-to-list 'emms-info-functions 'emms-info-mpd)
+@end lisp
+
+Adding `emms-player-mpd' to your Emms player list is accomplished by
+invoking:
+
+@lisp
+(add-to-list 'emms-player-list 'emms-player-mpd)
+@end lisp
+
+If you use absolute file names in your m3u playlists (which is most
+likely), make sure you set @var{emms-player-mpd-music-directory} to
+the value of "music_directory" from your MusicPD config.  There are
+additional options available as well, but the defaults should be
+sufficient for most uses.
+
+You can set @var{emms-player-mpd-sync-playlist} to nil if your master
+EMMS playlist contains only stored playlists.
+
+@subheading Commands provided
+
+@defun emms-player-mpd-connect
+Connect to MusicPD and retrieve its current playlist. Afterward, the
+status of MusicPD will be tracked.
+@end defun
+
+@defun emms-player-mpd-disconnect
+Terminate the MusicPD client process and disconnect from MusicPD.
+@end defun
+
+@defun emms-player-mpd-show &optional insertp
+Describe the current EMMS track in the minibuffer. If INSERTP is
+non-nil, insert the description into the current buffer instead. This
+function uses @var{emms-show-format} to format the current track. It
+differs from @command{emms-show} in that it asks MusicPD for the
+current track, rather than Emms.
+@end defun
+
+@subsubheading Updating the MusicPD database
+
+@defun emms-player-mpd-update-directory dir
+Cause the tracks in DIR to be updated in the MusicPD database.
+@end defun
+
+@defun emms-player-mpd-update-all
+Cause all tracks in the MusicPD music directory to be updated in
+the MusicPD database.
+@end defun
+
+@subsubheading emms-cache.el integration
+
+@defun emms-cache-set-from-mpd-directory dir
+Dump all MusicPD data from DIR into the EMMS cache.
+This is useful to do when you have recently acquired new music.
+@end defun
+
+@defun emms-cache-set-from-mpd-all
+Dump all MusicPD data into the EMMS cache.
+This is useful to do once, just before using emms-browser.el, in
+order to prime the cache.
+@end defun
+
+@subsubheading emms-volume.el integration
+
+To activate this, add the following to your .emacs.
+
+@lisp
+(require 'emms-volume)
+(setq emms-volume-change-function 'emms-volume-mpd-change)
+@end lisp
+
+@node Lyrics
+@chapter Lyrics
+
+@cindex lyrics
+
+We can display the lyrics of a song in time with the music using the
+`emms-lyrics' package provided by the file @file{emms-lyrics.el}.
+
+The lyrics files should have the extention ``.lrc'', and can be placed
+under either the same directory as the music files or
+@var{emms-lyrics-dir}.
+
+To add this feature we invoke:
+
+@lisp
+(require 'emms-lyrics)
+(emms-lyrics 1)
+@end lisp
+
+There are a number of variables we can set to define the way that
+`emms-lyrics' behaves, we can set these directly or by using the
+Customize feature in Emacs.
+
+@defvr {User Option} emms-lyrics-display-on-minibuffer
+If non-nil, display lyrics on minibuffer.
+@end defvr
+
+@defvr {User Option} emms-lyrics-display-on-modeline
+If non-nil, display lyrics on modeline.
+@end defvr
+
+@defvr {User Option} emms-lyrics-dir
+Local lyrics repository.
+@command{emms-lyrics-find-lyric} will look for lyrics in current
+directory(i.e., same as the music file) and this directory.
+@end defvr
+
+@defvr {User Option} emms-lyrics-display-format
+Format for displaying lyrics. "%s" will be replaced by the lyrics
+string.
+@end defvr
+
+@defvr {User Option} emms-lyrics-coding-system
+Coding system used in the output of lyrics.
+@end defvr
+
+@defvr {User Option} emms-lyrics-scroll-p
+Non-nil value will enable lyrics scrolling.
+@end defvr
+
+@defvr {User Option} emms-lyrics-scroll-timer-interval
+Interval between scroller timers. The shorter, the faster.
+@end defvr
+
+We can control `emms-lyrics' with the help of the following functions:
+
+@defun emms-lyrics-start
+Start displaying lyrics.
+@end defun
+
+@defun emms-lyrics-stop
+Stop displaying lyrics.
+@end defun
+
+@defun emms-lyrics-toggle-display-on-minibuffer
+Toggle display lyrics on minibufer.
+@end defun
+
+@defun emms-lyrics-toggle-display-on-modeline
+Toggle display lyrics on mode line.
+@end defun
+
+@defun emms-lyrics-enable
+Enable displaying Emms lyrics.
+@end defun
+
+@defun emms-lyrics-disable
+Disable displaying Emms lyrics.
+@end defun
+
+@defun emms-lyrics-toggle
+Toggle displaying Emms lyrics.
+@end defun
+
+@node Volume
+@chapter Volume
+
+@cindex volume
+
+We can use the `emms-volume' package, as provided by the
+@file{emms-volume.el} file, to manipulate the volume.
+
+@defopt emms-volume-change-amount
+The amount to use when raising or lowering the volume using the
+emms-volume interface.
+
+This should be a positive integer.
+@end defopt
+
+@defun emms-volume-raise
+Increase the volume.
+@end defun
+
+@defun emms-volume-lower
+Decrease the volume.
+@end defun
+
+If you feel like binding those two functions to global keys --- don't do
+it or you'll miss the convenience of `emms-volume-minor-mode'. Instead,
+bind the following two commands to some keys that you like.
+
+@defun emms-volume-mode-plus
+Raise volume and enable or extend the `emms-volume-minor-mode' timeout.
+@end defun
+
+@defun emms-volume-mode-minus
+Lower volume and enable or extend the `emms-volume-minor-mode' timeout.
+@end defun
+
+Example:
+
+@lisp
+(global-set-key (kbd "C-c +") 'emms-volume-mode-plus)
+(global-set-key (kbd "C-c -") 'emms-volume-mode-minus)
+@end lisp
+
+Whenever you use one of these keys or call these functions with
+@kbd{M-x}, Emms will be put into `emms-volume-minor-mode' for a short
+period defined by `emms-volume-mode-timeout'.
+
+@defopt emms-volume-mode-timeout
+The timeout in amount of seconds used by `emms-volume-minor-mode'.
+@end defopt
+
+In this interval you can raise/lower the volume simply by pressing
+@kbd{+} or @kbd{-}, which will also reset the timer to its initial
+value. So instead of pressing @kbd{C-c +} six times to increase volume
+by six steps of @code{emms-volume-change-amount}, you would simply type
+@kbd{C-c + + + + + +}.
+
+
+@node Last.fm
+@chapter Last.fm
+
+@cindex last.fm
+
+Currently the `emms-lastfm' package provided by the file
+@file{emms-lastfm.el} offers the two most important last.fm services.
+
+@enumerate
+@item
+It can submit informations of tracks (artist, title, album) you listen
+to to last.fm to enhance your music profile.
+
+@item
+You can listen to the Last.fm radio. Those are the streams beginning
+with lastfm://.
+@end enumerate
+
+For both services you need a last.fm account and you have to set up
+two variables.
+
+@defopt emms-lastfm-username
+Your last.fm username.
+@end defopt
+
+@defopt emms-lastfm-password
+Your last.fm password.
+@end defopt
+
+To set them in your @file{.emacs} add something like this.
+
+@lisp
+(setq emms-lastfm-username "my-user-name"
+      emms-lastfm-password "very-secret!")
+@end lisp
+
+You can edit them with the `customize' interface, too.
+
+@menu
+* Submitting track informations:: How to submit track information to last.fm.
+* Last.fm radio::                 How to listen to last.fm radio.
+@end menu
+
+@node Submitting track informations
+@section Submitting track informations
+
+These functions enable/disable submission of track informations to
+last.fm.
+
+@defun emms-lastfm-enable
+Start submitting to last.fm. Note that submission will start with the
+next track, not the current one.
+@end defun
+
+@defun emms-lastfm-disable
+Stop submission of track informations.
+@end defun
+
+If you want to enable submission of tracks by default, put this into
+your @file{.emacs}.
+
+@lisp
+(emms-lastfm-activate)
+@end lisp
+
+@node Last.fm radio
+@section Last.fm radio
+
+On http://www.last.fm you'll find lots of links referencing last.fm
+radio stations like lastfm://artist/Metallica/fans. You can listen to
+them using these functions.
+
+@defun emms-lastfm-radio lastfm-url
+Starts playing the stream referenced by @var{lastfm-url}. When run
+interactively you will be prompted for a last.fm URL.
+@end defun
+
+You can also insert Last.fm streams into playlists (or use
+emms-streams.el to listen to them) by activating the player as follows.
+
+@lisp
+(add-to-list 'emms-player-list 'emms-player-lastfm-radio)
+@end lisp
+
+To add a Last.fm stream into the current playlist, do the following:
+@kbd{M-x emms-add-lastfm RET lastfm://rest-of-url RET}. To directly
+start playing use @command{emms-play-lastfm}.
+
+To read more about the concept of the ``current'' playlist
+@xref{Playlists}. To add a last.fm stream to the playlist buffer that's
+currently browsed (which might not be the ``current'' playlist), use
+@command{emms-insert-lastfm} instead.
+
+For your convenience there are some functions which let you choose a
+common radio station without having to remember or type its last.fm URL.
+
+@defun emms-lastfm-radio-similar-artists artist
+Starts playing the similar artist radio of @var{artist}. When run
+interactively you will be prompted for an artist name.
+@end defun
+
+@defun emms-lastfm-radio-global-tag tag
+Starts playing the global tag radio of @var{tag}. When run interactively
+you will be prompted for a tag name.
+@end defun
+
+@defun emms-lastfm-radio-artist-fan artist
+Starts playing the artist fan radio of @var{artist}. When run
+interactively you will be prompted for an artist name.
+@end defun
+
+While listening to a last.fm radio station `emms-lastfm' will try to
+fetch some meta-informations (artist and title) of the currently playing
+song. That's controlled by the following variable:
+
+@defopt emms-lastfm-radio-metadata-period
+When listening to Last.fm Radio every how many seconds should
+emms-lastfm poll for metadata? If set to nil, there won't be any
+polling at all.
+
+The default is 15: That means that the mode line will display the
+wrong (last) track's data for a maximum of 15 seconds. If your
+network connection has a big latency this value may be too
+high. (But then streaming a 128KHz mp3 won't be fun anyway.)
+@end defopt
+
+Even if you set this variable to nil (no polling) you can fetch the
+meta-informations with one of the following functions.
+
+@defun emms-lastfm-radio-request-metadata
+Request the metadata of the current song and display it in the
+mode-line if the `emms-mode-line' package is enabled.
+@end defun
+
+@defun emms-lastfm-np
+Show the currently-playing lastfm radio tune.
+
+If you prefixed the command with @kbd{C-u}, the current song information
+is inserted at point.
+
+Otherwise, display a message with the current song information.
+@end defun
+
+When you listen to last.fm radio you can rate or skip the current song.
+
+@defun emms-lastfm-radio-love
+Inform Last.fm that you love the currently playing song.
+@end defun
+
+@defun emms-lastfm-radio-skip
+Inform Last.fm that you want to skip the currently playing song.
+@end defun
+
+@defun emms-lastfm-radio-ban
+Inform Last.fm that you want to ban the currently playing song.
+@end defun
+
+Ok, that's all.
+
+
+@node Streaming Audio
+@chapter Streaming Audio
+
+@cindex streaming audio
+@cindex internet radio
+
+Emms provides a friendly interface for managing and playing streaming
+audio in addition to the Emms playlist interface. The interface is
+defined in the @file{emms-streams.el} package and can be loaded by
+invoking:
+
+@lisp
+(require 'emms-streams)
+@end lisp
+
+The Emms interface for streaming audio is enabled by default in the
+`emms-all' and `emms-devel' setup levels. For more information about
+Emms setup levels see @xref{Simple Setup}.
+
+Enter the emms-streams interface by invoking @kbd{M-x}
+@command{emms-streams}. The emms-streams interface comes with a
+built-in, eclectic list of streaming audio channels from throughout the
+Web. Emms can of-course play other streams than the ones listed by
+default, you are free to remove any or all of them and add your
+own.@footnote{If you enjoy a particular streaming audio station on the
+Web and think that it belongs in the default list, please send us a
+link and we will gladly add it!}
+
+If you want to play Last.fm streams, invoke the following and use the
+``lastfm'' type when adding a bookmark to a Last.fm stream.
+
+@lisp
+(require 'emms-lastfm)
+@end lisp
+
+The following is a list of the key-bindings for the emms-streams
+interface:
+
+@table @kbd
+@item RET
+@kindex RET (emms-streams)
+@vindex emms-stream-default-action
+Perform the default action when you press RET in the Emms Stream
+interface. Can be either ``add'' or ``play''. The default is ``add'',
+which adds the station under point to the Emms playlist. When
+@var{emms-stream-default-action} is ``play'' then Emms will play the
+streaming audio channel under point.
+@item q
+@kindex q (emms-streams)
+@findex emms-stream-quit
+Quit the emms-streams interface.
+@item a
+@kindex a (emms-streams)
+@findex emms-stream-add-bookmark
+Add a bookmark to a streaming audio URL to the list.
+@item d
+@kindex d (emms-streams)
+@findex emms-stream-delete-bookmark
+Remove a bookmark to a streaming audio URL from the list.
+@item e
+@kindex e (emms-streams)
+@findex emms-stream-edit-bookmark
+Edit the details of the bookmark under point.
+@item h
+@kindex h (emms-streams)
+@findex describe-mode
+Describe the emms-streams mode.
+@item n
+@kindex n (emms-streams)
+@findex emms-stream-next-line
+Move to the next line in the emms-streams buffer (same as C-n).
+@item p
+@kindex p (emms-streams)
+@findex emms-stream-previous-line
+Move to the previous line in the emms-streams buffer (same as C-p).
+@item s
+@kindex s (emms-streams)
+@findex emms-stream-save-bookmarks-file
+Save the bookmarks in the emms-streams interface to disk. The
+bookmarks will be to the location designated in the variable
+@var{emms-stream-bookmarks-file}.
+@item i
+@kindex i (emms-streams)
+@findex emms-stream-info-bookmark
+Return information about the streaming audio at the URL of the
+bookmark under point. Note that this will only work if the
+`emms-stream-info' has already been loaded.
+@end table
+
+@c including the relevant licenses
+@include gpl.texi
+@include fdl.texi
+
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
+@node Function Index
+@unnumbered Function Index
+@printindex fn
+
+@node Variable Index
+@unnumbered Variable Index
+@printindex vr
+
+@node Keybinding Index
+@unnumbered Keybinding Index
+@printindex ky
+
+@bye
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644
index 0000000..1276677
--- /dev/null
+++ b/doc/fdl.texi
@@ -0,0 +1,451 @@
+@node The GNU FDL, Concept Index, Copying, Top
+@chapter GNU Free Documentation License
+
+@cindex FDL, GNU Free Documentation License
+@center Version 1.2, November 2002
+
+@display
+Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
+51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The ``Document'', below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as ``you''.  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject.  (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification.  Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
+@acronym{JPG}.  Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
+@acronym{XML} for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''.  You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License.  Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License.  However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+@end enumerate
+
+@page
+@section ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.2
+  or any later version published by the Free Software Foundation;
+  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with...Texts.'' line with this:
+
+@smallexample
+@group
+    with the Invariant Sections being @var{list their titles}, with
+    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+    being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
diff --git a/doc/gpl.texi b/doc/gpl.texi
new file mode 100644
index 0000000..9223243
--- /dev/null
+++ b/doc/gpl.texi
@@ -0,0 +1,725 @@
+@node Copying, The GNU FDL, Extending Emms, Top
+
+@unnumbered GNU General Public License
+@center Version 3, 29 June 2007
+
+@c This file is intended to be included in another file.
+
+@display
+Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+@end display
+
+@unnumberedsec Preamble
+
+The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom
+to share and change all versions of a program--to make sure it remains
+free software for all its users.  We, the Free Software Foundation,
+use the GNU General Public License for most of our software; it
+applies also to any other work released this way by its authors.  You
+can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you
+have certain responsibilities if you distribute copies of the
+software, or if you modify it: responsibilities to respect the freedom
+of others.
+
+For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too,
+receive or can get the source code.  And you must show them these
+terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the
+manufacturer can do so.  This is fundamentally incompatible with the
+aim of protecting users' freedom to change the software.  The
+systematic pattern of such abuse occurs in the area of products for
+individuals to use, which is precisely where it is most unacceptable.
+Therefore, we have designed this version of the GPL to prohibit the
+practice for those products.  If such problems arise substantially in
+other domains, we stand ready to extend this provision to those
+domains in future versions of the GPL, as needed to protect the
+freedom of users.
+
+Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish
+to avoid the special danger that patents applied to a free program
+could make it effectively proprietary.  To prevent this, the GPL
+assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@unnumberedsec TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS
+@end ifinfo
+
+@enumerate 0
+@item Definitions.
+
+``This License'' refers to version 3 of the GNU General Public License.
+
+``Copyright'' also means copyright-like laws that apply to other kinds
+of works, such as semiconductor masks.
+
+``The Program'' refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as ``you''.  ``Licensees'' and
+``recipients'' may be individuals or organizations.
+
+To ``modify'' a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of
+an exact copy.  The resulting work is called a ``modified version'' of
+the earlier work or a work ``based on'' the earlier work.
+
+A ``covered work'' means either the unmodified Program or a work based
+on the Program.
+
+To ``propagate'' a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To ``convey'' a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user
+through a computer network, with no transfer of a copy, is not
+conveying.
+
+An interactive user interface displays ``Appropriate Legal Notices'' to
+the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+@item Source Code.
+
+The ``source code'' for a work means the preferred form of the work for
+making modifications to it.  ``Object code'' means any non-source form
+of a work.
+
+A ``Standard Interface'' means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+The ``System Libraries'' of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+``Major Component'', in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+The ``Corresponding Source'' for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can
+regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same
+work.
+
+@item Basic Permissions.
+
+All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey,
+without conditions so long as your license otherwise remains in force.
+You may convey covered works to others for the sole purpose of having
+them make modifications exclusively for you, or provide you with
+facilities for running those works, provided that you comply with the
+terms of this License in conveying all material for which you do not
+control copyright.  Those thus making or running the covered works for
+you must do so exclusively on your behalf, under your direction and
+control, on terms that prohibit them from making any copies of your
+copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the
+conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+@item Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such
+circumvention is effected by exercising rights under this License with
+respect to the covered work, and you disclaim any intention to limit
+operation or modification of the work as a means of enforcing, against
+the work's users, your or third parties' legal rights to forbid
+circumvention of technological measures.
+
+@item Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+@item Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these
+conditions:
+
+@enumerate a
+@item 
+The work must carry prominent notices stating that you modified it,
+and giving a relevant date.
+
+@item
+The work must carry prominent notices stating that it is released
+under this License and any conditions added under section 7.  This
+requirement modifies the requirement in section 4 to ``keep intact all
+notices''.
+
+@item
+You must license the entire work, as a whole, under this License to
+anyone who comes into possession of a copy.  This License will
+therefore apply, along with any applicable section 7 additional terms,
+to the whole of the work, and all its parts, regardless of how they
+are packaged.  This License gives no permission to license the work in
+any other way, but it does not invalidate such permission if you have
+separately received it.
+
+@item
+If the work has interactive user interfaces, each must display
+Appropriate Legal Notices; however, if the Program has interactive
+interfaces that do not display Appropriate Legal Notices, your work
+need not make them do so.
+@end enumerate
+
+A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+``aggregate'' if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+@item  Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of
+sections 4 and 5, provided that you also convey the machine-readable
+Corresponding Source under the terms of this License, in one of these
+ways:
+
+@enumerate a
+@item
+Convey the object code in, or embodied in, a physical product
+(including a physical distribution medium), accompanied by the
+Corresponding Source fixed on a durable physical medium customarily
+used for software interchange.
+
+@item
+Convey the object code in, or embodied in, a physical product
+(including a physical distribution medium), accompanied by a written
+offer, valid for at least three years and valid for as long as you
+offer spare parts or customer support for that product model, to give
+anyone who possesses the object code either (1) a copy of the
+Corresponding Source for all the software in the product that is
+covered by this License, on a durable physical medium customarily used
+for software interchange, for a price no more than your reasonable
+cost of physically performing this conveying of source, or (2) access
+to copy the Corresponding Source from a network server at no charge.
+
+@item
+Convey individual copies of the object code with a copy of the written
+offer to provide the Corresponding Source.  This alternative is
+allowed only occasionally and noncommercially, and only if you
+received the object code with such an offer, in accord with subsection
+6b.
+
+@item
+Convey the object code by offering access from a designated place
+(gratis or for a charge), and offer equivalent access to the
+Corresponding Source in the same way through the same place at no
+further charge.  You need not require recipients to copy the
+Corresponding Source along with the object code.  If the place to copy
+the object code is a network server, the Corresponding Source may be
+on a different server (operated by you or a third party) that supports
+equivalent copying facilities, provided you maintain clear directions
+next to the object code saying where to find the Corresponding Source.
+Regardless of what server hosts the Corresponding Source, you remain
+obligated to ensure that it is available for as long as needed to
+satisfy these requirements.
+
+@item
+Convey the object code using peer-to-peer transmission, provided you
+inform other peers where the object code and Corresponding Source of
+the work are being offered to the general public at no charge under
+subsection 6d.
+
+@end enumerate
+
+A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+A ``User Product'' is either (1) a ``consumer product'', which means any
+tangible personal property which is normally used for personal,
+family, or household purposes, or (2) anything designed or sold for
+incorporation into a dwelling.  In determining whether a product is a
+consumer product, doubtful cases shall be resolved in favor of
+coverage.  For a particular product received by a particular user,
+``normally used'' refers to a typical or common use of that class of
+product, regardless of the status of the particular user or of the way
+in which the particular user actually uses, or expects or is expected
+to use, the product.  A product is a consumer product regardless of
+whether the product has substantial commercial, industrial or
+non-consumer uses, unless such uses represent the only significant
+mode of use of the product.
+
+``Installation Information'' for a User Product means any methods,
+procedures, authorization keys, or other information required to
+install and execute modified versions of a covered work in that User
+Product from a modified version of its Corresponding Source.  The
+information must suffice to ensure that the continued functioning of
+the modified object code is in no case prevented or interfered with
+solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or
+updates for a work that has been modified or installed by the
+recipient, or for the User Product in which it has been modified or
+installed.  Access to a network may be denied when the modification
+itself materially and adversely affects the operation of the network
+or violates the rules and protocols for communication across the
+network.
+
+Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+@item Additional Terms.
+
+``Additional permissions'' are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders
+of that material) supplement the terms of this License with terms:
+
+@enumerate a
+@item
+Disclaiming warranty or limiting liability differently from the terms
+of sections 15 and 16 of this License; or
+
+@item
+Requiring preservation of specified reasonable legal notices or author
+attributions in that material or in the Appropriate Legal Notices
+displayed by works containing it; or
+
+@item
+Prohibiting misrepresentation of the origin of that material, or
+requiring that modified versions of such material be marked in
+reasonable ways as different from the original version; or
+
+@item
+Limiting the use for publicity purposes of names of licensors or
+authors of the material; or
+
+@item
+Declining to grant rights under trademark law for use of some trade
+names, trademarks, or service marks; or
+
+@item
+Requiring indemnification of licensors and authors of that material by
+anyone who conveys the material (or modified versions of it) with
+contractual assumptions of liability to the recipient, for any
+liability that these contractual assumptions directly impose on those
+licensors and authors.
+@end enumerate
+
+All other non-permissive additional terms are considered ``further
+restrictions'' within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions; the
+above requirements apply either way.
+
+@item Termination.
+
+You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+@item Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run
+a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+@item Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+An ``entity transaction'' is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+@item Patents.
+
+A ``contributor'' is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's ``contributor version''.
+
+A contributor's ``essential patent claims'' are all patent claims owned
+or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, ``control'' includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+In the following three paragraphs, a ``patent license'' is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To ``grant'' such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  ``Knowingly relying'' means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+A patent license is ``discriminatory'' if it does not include within the
+scope of its coverage, prohibits the exercise of, or is conditioned on
+the non-exercise of one or more of the rights that are specifically
+granted under this License.  You may not convey a covered work if you
+are a party to an arrangement with a third party that is in the
+business of distributing software, under which you make payment to the
+third party based on the extent of your activity of conveying the
+work, and under which the third party grants, to any of the parties
+who would receive the covered work from you, a discriminatory patent
+license (a) in connection with copies of the covered work conveyed by
+you (or copies made from those copies), or (b) primarily for and in
+connection with specific products or compilations that contain the
+covered work, unless you entered into that arrangement, or that patent
+license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+@item No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey
+a covered work so as to satisfy simultaneously your obligations under
+this License and any other pertinent obligations, then as a
+consequence you may not convey it at all.  For example, if you agree
+to terms that obligate you to collect a royalty for further conveying
+from those to whom you convey the Program, the only way you could
+satisfy both those terms and this License would be to refrain entirely
+from conveying the Program.
+
+@item Use with the GNU Affero General Public License.
+
+Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+@item Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU General Public License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies that a certain numbered version of the GNU General Public
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that numbered version or
+of any later version published by the Free Software Foundation.  If
+the Program does not specify a version number of the GNU General
+Public License, you may choose any version ever published by the Free
+Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions
+of the GNU General Public License can be used, that proxy's public
+statement of acceptance of a version permanently authorizes you to
+choose that version for the Program.
+
+Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+@item Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
+CORRECTION.
+
+@item Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
+CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
+NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
+LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
+PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+@item Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+@unnumberedsec How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+@smallexample
+@var{one line to give the program's name and a brief idea of what it does.}  
+Copyright (C) @var{year} @var{name of author}
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or (at
+your option) any later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see @url{http://www.gnu.org/licenses/}.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+@smallexample
+@var{program} Copyright (C) @var{year} @var{name of author} 
+This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
+This is free software, and you are welcome to redistribute it under certain conditions; type @samp{show c} for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License.  Of course, your
+program's commands might be different; for a GUI interface, you would
+use an ``about box''.
+
+You should also get your employer (if you work as a programmer) or school,
+if any, to sign a ``copyright disclaimer'' for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+@url{http://www.gnu.org/licenses/}.
+
+The GNU General Public License does not permit incorporating your
+program into proprietary programs.  If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library.  If this is what you want to do, use
+the GNU Lesser General Public License instead of this License.  But
+first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}.
+
+@end enumerate