[Emms-patches] [COMMIT] Document emms-lastfm-client.el

[Yoni Rabkin]

---
 doc/emms.texinfo           |  197 +++++++++++++------------------------------
 lisp/emms-lastfm-client.el |   46 +----------
 2 files changed, 63 insertions(+), 180 deletions(-)

diff --git a/doc/emms.texinfo b/doc/emms.texinfo
index 1fca86c..c34f7d7 100644
--- a/doc/emms.texinfo
+++ b/doc/emms.texinfo
@@ -81,7 +81,7 @@ Modules and Extensions
 * Streaming Audio::      Interface to streaming audio.
 * Lyrics::               Displaying lyrics synchronously.
 * Volume::               Changing the volume.
-* Last.fm::              Interact with http://www.last.fm's services.
+* Last.fm::              Interact with the Last.fm service.
 * APE / FLAC Commands::  How to play next or previous track in these files.  
 * Extending Emms::       How to define new players and modules.
 
@@ -115,8 +115,8 @@ 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.
+* Last.fm Setup::            Configuring Emms to use Last.fm.
+* Last.fm Radio::            Listening to music through Last.fm.
 
 Extending Emms
 * New Player::               How to define a new player.
@@ -2212,160 +2212,83 @@ by six steps of @code{emms-volume-change-amount}, you 
would simply type
 
 @cindex last.fm
 
-Currently the `emms-lastfm' package provided by the file
address@hidden offers the two most important last.fm services.
+Last.fm is a popular commercial music streaming service. Last.fm
+allows a subscriber to listen to streaming music. Last.fm can also
+accept data as to what music is played locally. This information can
+be used by the Last.fm service. As usual the responsibility is on the
+user to decide how much information to share with third-parties.
 
address@hidden
address@hidden
-It can submit informations of tracks (artist, title, album) you listen
-to to last.fm to enhance your music profile.
-
address@hidden
-You can listen to the Last.fm radio. Those are the streams beginning
-with lastfm://.
address@hidden enumerate
-
-For both services you need a last.fm account and you have to set up
-two variables.
-
address@hidden emms-lastfm-username
-Your last.fm username.
address@hidden defopt
-
address@hidden emms-lastfm-password
-Your last.fm password.
address@hidden defopt
-
-To set them in your @file{.emacs} add something like this.
-
address@hidden
-(setq emms-lastfm-username "my-user-name"
-      emms-lastfm-password "very-secret!")
address@hidden lisp
+The emms-lastfm-client package, provided the file
address@hidden provides native Last.fm support from
+within Emms.
 
-You can edit them with the `customize' interface, too.
+Emms does not provide a subscription to the Last.fm service, nor is it
+affiliated with the service in any way. There are restrictions on the
+use of this service. Quoting from @uref{http://www.last.fm/api/radio}:
+``Who can I stream radio to? Any API account can only stream radio to
+Last.fm's paid subscribers''.
 
 @menu
-* Submitting track informations:: How to submit track information to last.fm.
-* Last.fm radio::                 How to listen to last.fm radio.
+* Last.fm Setup::            Configuring Emms to use Last.fm.
+* Last.fm Radio::            Listening to music through Last.fm
 @end menu
 
address@hidden Submitting track informations
address@hidden Submitting track informations
-
-These functions enable/disable submission of track informations to
-last.fm.
-
address@hidden emms-lastfm-enable
-Start submitting to last.fm. Note that submission will start with the
-next track, not the current one.
address@hidden defun
-
address@hidden emms-lastfm-disable
-Stop submission of track informations.
address@hidden defun
-
-If you want to enable submission of tracks by default, put this into
-your @file{.emacs}.
-
address@hidden
-(emms-lastfm-activate)
address@hidden lisp
-
address@hidden Last.fm radio
address@hidden 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.
-
address@hidden 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.
address@hidden 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.
-
address@hidden
-(add-to-list 'emms-player-list 'emms-player-lastfm-radio)
address@hidden lisp
-
-To add a Last.fm stream into the current playlist, do the following:
address@hidden 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
address@hidden To add a last.fm stream to the playlist buffer that's
-currently browsed (which might not be the ``current'' playlist), use
address@hidden 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.
-
address@hidden emms-play-lastfm-similar-artists artist
-Starts playing the similar artist radio of @var{artist}. When run
-interactively you will be prompted for an artist name.
address@hidden defun
-
address@hidden emms-play-lastfm-global-tag tag
-Starts playing the global tag radio of @var{tag}. When run interactively
-you will be prompted for a tag name.
address@hidden defun
-
address@hidden emms-play-lastfm-artist-fan artist
-Starts playing the artist fan radio of @var{artist}. When run
-interactively you will be prompted for an artist name.
address@hidden defun
address@hidden Last.fm Setup
address@hidden Last.fm Setup
 
-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:
+We've spoken to representatives from Last.fm and arrived at the
+following agreement: In order to be able to use the service while
+preserving the essential freedoms of the GPL each client must apply
+for their own API key from Last.fm.
 
address@hidden 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.
+Here are the steps for getting authorization from Last.fm to stream
+music. Thankfully this only needs to be done once:
 
-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.)
address@hidden defopt
address@hidden
 
-Even if you set this variable to nil (no polling) you can fetch the
-meta-informations with one of the following functions.
address@hidden
+Complete steps 1 and 2 from
address@hidden://www.last.fm/api/authentication} to get an API key and a
+secret key. Set the variables @var{emms-lastfm-client-api-key} and
address@hidden respectively.
 
address@hidden 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.
address@hidden defun
address@hidden
+Invoke @kbd{M-x emms-lastfm-client-user-authorization}. On successful
+completion a browser window will open asking for confirmation to allow
+this application access to your Last.fm account. Confirm and close the
+browser.
 
address@hidden emms-lastfm-np
-Show the currently-playing lastfm radio tune.
address@hidden
+Invoke @kbd{M-x emms-lastfm-client-get-session}. On successful
+completion your permanent session key will be stored in
address@hidden As long as this value is
+accessible the authentication process need not be repeated.
 
-If you prefixed the command with @kbd{C-u}, the current song information
-is inserted at point.
address@hidden enumerate
 
-Otherwise, display a message with the current song information.
address@hidden defun
+After successfully completing the above Emms should be authorized to
+access your Last.fm account.
 
-When you listen to last.fm radio you can rate or skip the current song.
address@hidden Last.fm Radio
address@hidden Last.fm Radio
 
address@hidden emms-lastfm-radio-love
-Inform Last.fm that you love the currently playing song.
address@hidden defun
+Currently the only music streaming service provided by
+emms-lastfm-client is Last.fm's "play similar artists". More services
+will be implemented Real Soon Now.
 
address@hidden emms-lastfm-radio-skip
-Inform Last.fm that you want to skip the currently playing song.
address@hidden defun
+Note that Last.fm streams cannot be paused or replayed. Doing so may
+cause Last.fm to suspend your account.
 
address@hidden emms-lastfm-radio-ban
-Inform Last.fm that you want to ban the currently playing song.
address@hidden defun
+To play the Similar-Artists stream invoke @kbd{M-x
+emms-lastfm-client-play-similar-artists}. Then enter the name of the
+artist. The input will auto-complete from the Emms cache. If an artist
+is not in the Emms cache and has a name with spaces, use @kbd{C-q
+Space} to enter literal spaces.
 
-Ok, that's all.
+To show information about the currently playing track invoke @kbd{M-x
+emms-lastfm-client-show}.
 
+To skip a track invoke @kbd{M-x emms-lastfm-client-track-advance}.
 
 @node Streaming Audio
 @chapter Streaming Audio
diff --git a/lisp/emms-lastfm-client.el b/lisp/emms-lastfm-client.el
index 20ec018..0ad8451 100644
--- a/lisp/emms-lastfm-client.el
+++ b/lisp/emms-lastfm-client.el
@@ -24,49 +24,9 @@
 
 ;;; Commentary:
 ;;
-;; There are restrictions on the use of this service. Quoting from
-;; [http://www.last.fm/api/radio]: "Who can I stream radio to? Any API
-;; account can only stream radio to Last.fm's paid subscribers".
-;;
-;; We've spoken to representatives from Last.fm and arrived at the
-;; following agreement: In order to be able to use the service while
-;; preserving the essential freedoms of the GPL each client must apply
-;; for their own API key from Last.fm.
-
-;;; Installation:
-;;
-;; Here is how to get authorization from Last.fm to stream
-;; music. Thankfully this only needs to be done _once_:
-;;
-;; 1. Complete steps 1 and 2 from
-;;    [http://www.last.fm/api/authentication] to get an API key and a
-;;    secret key. Set `emms-lastfm-client-api-key' and
-;;    `emms-lastfm-client-api-secret-key' accordingly.
-;;
-;; 2. M-x emms-lastfm-client-user-authorization
-;;
-;;    If this completes successfully a browser window will open asking
-;;    for confirmation to allow this application to access the Last.fm
-;;    account. Confirm and close the browser.
-;;
-;; 3. M-x emms-lastfm-client-get-session
-;;
-;;    After this last step the permanent session key will be stored in
-;;    `emms-lastfm-client-session-key-file'. As long as this key value
-;;    is accessible the authentication process need never be repeated.
-
-;;; Use:
-;;
-;; M-x emms-lastfm-client-play-similar-artists
-;;
-;; Call the ...-play- family of interactive functions, such the above,
-;; to start streaming music.
-;;
-;; To show the currently playing track: M-x emms-lastfm-client-show
-;;
-;; To skip to the next track: M-x emms-lastfm-client-track-advance
-;;
-;; ...more Last.fm functionality to come, so stay tuned.
+;; Definitive information on how to setup and use this package is
+;; provided in the wonderful Emms manual, in the /doc directory of the
+;; Emms distribution.
 
 ;;; Code:
 
-- 
debian.1.5.6.1.19.ge6b2