Another installment of manual changes

darcs-hash:20050928071321-be80e-d6ffd8ab5ab0ab84074951d1c869903d2f096dcb.gz

1 files changed, 142 insertions, 120 deletions

diff --git a/emms.texinfo b/emms.texinfo
index 118dda5..613ab5c 100644
--- a/emms.texinfo
+++ b/emms.texinfo
@@ -51,22 +51,22 @@ This is the Manual for the Emacs Multimedia System
 * The GNU FDL::         The license for this documentation.
 
 Starting out
-* Introduction::        Introduction to Emms
-* Installation::        How to install Emms on your System
-* Quick Setup::         Quick start in Emms
-* Configuration Example::     Bare bones configuration
+* Introduction::        Introduction to Emms.
+* Installation::        How to install Emms on your System.
+* Quick Setup::         Quick start in Emms.
+* Configuration Example::     Bare bones configuration.
 
 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
+* 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.
 
 Advanced Features
-* Info Tags::           More narrative track descriptions
-* The Playlist Buffer:: Interactive Playlist
-* Extending Emms::           How to define new players and modules
-* Streaming Audio::          Interface to streaming audio
+* Info Tags::           More narrative track descriptions.
+* The Playlist Buffer:: Interactive Playlist.
+* Extending Emms::           How to define new players and modules.
+* Streaming Audio::          Interface to streaming audio.
 
 Indices
 * Concept Index::
@@ -74,6 +74,8 @@ Indices
 * Variable Index::
 * Keybinding Index::
 
+@c FIXME: the detailed listing needs to be re-generated after the
+@c above is finished.
 @detailmenu
 --- The Detailed Node Listing ---
 
@@ -189,7 +191,7 @@ just need the following line,
 which installs the core of Emms.
 
 Now we need to do some configuration.
-
+@c FIXME: Renaming of emms-default? New user levels?
 The Emms module `emms-default' provides the function `emms-setup',
 which is a way to quickly configure your Emms. You can add any number
 of directories which contain media. The first argument is the
@@ -201,7 +203,6 @@ complexity level of the user interface. Here's an example:
 @end lisp
 
 Here is a list of the interface complexity options:
-@c FIXME: what is actually included with emms-defaults for each level?
 @table @samp
 @item minimalistic
 Define the players and play directory but nothing more.
@@ -211,10 +212,6 @@ minimalistic installation plus a user interface to the playlists.
 @item default
 Features the above plus the reading the info from tagged Mp3 and Ogg
 files.
-@item advanced
-@c FIXME: see above
-@item cvs
-@c FIXME: see above
 @end table
 
 Now your configuration is done.
@@ -227,9 +224,9 @@ The (optional) directory is used for
 
 @cindex Configuration Example
 
-The following code fragment provides a minimal EMMS setup without
+The following code fragment provides a minimal Emms setup without
 using the layer of `emms-default'. It can maybe be used to better
-understand the internals of EMMS. You can see how EMMS needs to know
+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').
@@ -346,60 +343,118 @@ Sort the current playlist. This uses
 @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.
+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
-@c FIXME: go over all these first, then add new ones
-The file @file{emms.el} provides all basic functions for playing
-music, generating a playlist and defining players.
+@c FIXME: go over all these first, then add new ones. Also divide
+@c these into subsections to keep the overall size down.
+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
+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 play
-files. Unless you use @file{emms-player-simple} you have to define a
-player with @command{emms-define-player} first.
+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}. The only argument %s is the
-string returned by @command{emms-track-description}
+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 for repeating the playlist after playing the last track.
+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
-A function to be called to give a nice, user-friendly description of
-the track passed to it as an argument.
+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 `sort').
-@end defopt
-@defopt emms-playlist-changed-hook
-A hook run when the playlist of Emms has changed.
-@end defopt
-@defopt emms-playlist-current-changed-hook
-A hook run when the current track in the playlist of Emms has
-changed.
+track should be sorted before the second (see also @code{sort}).
 @end defopt
+
+@node Hooks
+@section Hooks
+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.
+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
+The core file also defines all the functions important to the basic
+use of Emms.
+@c FIXME: sort these so that they make sense
+
+There are functions which deal with movement in the playlist.
 
 @defun emms-next-noerror
-Play the next track in the playlist, but don't signal an error when
-we're at the end. This should be called when no player is playing.
-This is a suitable function to put in @var{emms-player-stopped-hook}.
+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-sort
-Sort the playlist.
+@defun emms-playlist-next
+Move to the previous track in the current buffer.
 @end defun
-@defun emms-sort-track-name-less-p a b
-Return non-nil if the track name of @var{a} is before @var{b}.
+@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
@@ -410,80 +465,27 @@ Return the type of @var{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{inexistent} (or nil if not given).
+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
-A simple function to give a user-readable description of @var{track}.
-If it's a file track, it's just the filename.
-Else it's the type and the name with a colon in between.
-@end defun
-@defun emms-playlist-current
-Return a description of the currently playing track.
-This uses @var{emms-track-description-function}.
-@end defun
-@defun emms-playlist-current-track
-Return the currently playing track.
-@end defun
-@defun emms-playlist-get n
-Return a description of the @var{n}th entry of the current playlist.
-This uses `emms-track-description-function'
-@end defun
-@defun emms-playlist-get-track n
-Return the @var{n}th track of the current playlist.
-@end defun
-@defun emms-playlist-set-playlist new
-Set the playlist to @var{new}.
-This runs `emms-playlist-changed-hook'.
-@end defun
-@defun emms-playlist-get-playlist
-Return the current playlist.
-@end defun
-@defun emms-playlist-set-current n
-Set the current track in the playlist to @var{n} (a number).
-This runs `emms-playlist-current-changed-hook'.
-@end defun
-@defun emms-playlist-get-current
-Return the number of the current track, or nil if the playlist is
-empty.
-@end defun
-@defun emms-playlist-next
-Advance the current track to the next entry in the playlist and
-return non-nil. Return nil if there is no next track.
-@end defun
-@defun emms-playlist-previous
-Set the current track to the previous entry in the playlist and
-return non-nil. Return nil if there is no previous track.
-@end defun
-@defun emms-playlist-add seq &optional idx
-Add each track of the sequence @var{seq} to the current playlist.
-Insert at @var{idx}, which defaults to the end.
-@end defun
-@defun emms-playlist-remove idx
-Remove track at @var{idx} from playlist.
-@end defun
-@defun emms-playlist-shuffle
-Shuffle the current playlist.
-@end defun
-@defun emms-playlist-sort
-Sort the current playlist according to `emms-sort-lessp-function'
-@end defun
-@defun emms-playlist-shuffle-vector vector
-Shuffle @var{vector}.
-@end defun
-@defun emms-playlist-sort-vector vector
-Sort @var{vector} according to `emms-sort-lessp-function'.
-@end defun
-@defun emms-source-play lis
-Play the tracks returned by @var{lis}.
+Return a description of @var{track}. This function uses
+@var{emms-track-description-function}.
 @end defun
 @defun emms-player-for track
-Return the player which is responsible for @var{track}, or nil if
-there is none.
+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
@@ -491,9 +493,29 @@ Start playing @var{track}.
 Stop the currently playing player.
 @end defun
 @defun emms-player-stopped
-Declare that the current player has finished playing.
-This should only be called by a player.
+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
+@defun emms-sort-track-name-less-p a b
+Return non-nil if the track name of @var{A} sorts before @var{B}.
+@end defun
+@defun emms-ensure-player-playing-p
+Raise an error if no player is playing right now.
+@end defun
+
+For more basic commands defined in the core file see @xref{Basic
+Commands}.
 
 @node Sources
 @chapter Sources
@@ -547,7 +569,7 @@ Return a regexp that matches everything any player (that supports
 files) can play.
 @end defun
 @defun emms-save-playlist filename
-Export the current playlist as to @var{filename}.  See also
+Export the current playlist as to @var{filename}. See also
 @command{emms-source-playlist-file}.
 @end defun
 @defun emms-locate
@@ -876,7 +898,7 @@ should return the text to be inserted in the playlist.
 @end defopt
 @defopt emms-pbi-playlist-entry-max-length
 The maximum length of an entry in the playlist. If this is nil, the
-entire string provided by `emms-track-description-function'.  will be
+entire string provided by `emms-track-description-function'. will be
 used. Beware, the output of that function is cut off to fit the
 max-length before running `emms-pbi-playlist-entry-generate-function'.
 @end defopt
@@ -1181,8 +1203,8 @@ interface:
 @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'',
+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.