Yet Another Installment of the manual re-write

darcs-hash:20051004134932-be80e-4b875ae487827f1507f8f7dd0f13a37023894976.gz

2 files changed, 83 insertions, 238 deletions

diff --git a/emms-setup.el b/emms-setup.el
index 8a99ccc..55df85e 100644
--- a/emms-setup.el
+++ b/emms-setup.el
@@ -41,7 +41,7 @@
 
 (defun emms-minimalistic ()
   "An Emms setup script.
-Invisible playlist and all the basics for playing media."
+Invisible playlists and all the basics for playing media."
   (require 'emms)
   (require 'emms-source-file)
   (require 'emms-player-simple)
@@ -49,8 +49,9 @@ Invisible playlist and all the basics for playing media."
 
 (defun emms-standard ()
   "An Emms setup script.
-Everything included in the `emms-minimalistic' setup and adds the
-Emms playlist mode."
+Everything included in the `emms-minimalistic' setup, the Emms
+interactive playlist mode and reading information from tagged
+audio files."
   ;; include
   (emms-minimalistic)
   ;; define
@@ -68,7 +69,7 @@ Emms playlist mode."
 (defun emms-all ()
   "An Emms setup script.
 Everything included in the `emms-standard' setup and adds all the
-stable add-ons which come with the Emms distribution."
+stable features which come with the Emms distribution."
   ;; include
   (emms-standard)
   ;; define
@@ -82,9 +83,9 @@ stable add-ons which come with the Emms distribution."
 (defun emms-devel ()
   "An Emms setup script.
 Everything included in the `emms-all' setup and adds all the
-add-ons which come with the Emms distribution regardless if they
-are considered stable or not.  Use this if you like living on the
-edge."
+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."
   ;; include
   (emms-all)
   ;; define
diff --git a/emms.texinfo b/emms.texinfo
index 4d7791e..e76a580 100644
--- a/emms.texinfo
+++ b/emms.texinfo
@@ -13,6 +13,8 @@
 @c FIXME: Stuff slated for addition to the manual:
 @c emms-mode-line, emms-metaplaylist-mode.
 
+@c FIXME: Add concept indices to all the new chapters.
+
 @dircategory Emacs
 @direntry
 * Emms: (emms).           The Emacs Multimedia System
@@ -59,8 +61,8 @@ This is the Manual for the Emacs Multimedia System
 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.
+* Simple Setup::        Quick, basic default Emms setup.
+* Configuration::       More detailed setup and configuration.
 
 Emms basics
 * Basic Commands::      How to control Emms with ease.
@@ -71,9 +73,9 @@ Emms basics
 
 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.
+* Interactive Playlists::    Interactive Playlists.
+* Extending Emms::      How to define new players and modules.
+* Streaming Audio::     Interface to streaming audio.
 
 Indices
 * Concept Index::
@@ -97,9 +99,6 @@ Info Tags
 * MP3 Info::    Reading mp3 info tags
 @end detailmenu
 
-The Playlist Buffer
-* Playlist Buffer::     Browsing buffer known by other players
-
 Extending Emms
 * New Player::  How to define a new player
 
@@ -143,8 +142,7 @@ 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'. It is possible to extend Emms with the extra modules
-shipped with Emms. @xref{Extending Emms}.
+`M-x customize'.
 
 @node Installation
 @chapter Installation
@@ -184,56 +182,76 @@ 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 Quick Setup
-@chapter Quick setup
+@node Simple Setup
+@chapter Simple Setup
 
-Emms is quite simple to set up. For the most basic needs, you will
-just need the following line,
+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)
+(require 'emms-setup)
+(emms-standard)
+(emms-default-players)
 @end lisp
 
-which installs the core of Emms.
+After which Emms is set-up and ready to go!
 
-@c FIXME: update this for new version of emms-setup.
-Now we need to do some configuration. The Emms module `emms-setup'
-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 complexity level of the user
-interface. Here's an example:
+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.).
 
-@lisp
-(require 'emms-setup)
-(emms-setup 'tiny "directory")
-@end lisp
+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.
 
-Here is a list of the interface complexity options:
+We use `emms-setup' by calling one of the setup functions. Each of the
+functions sets up Emms to include a number of features.
 
-@table @samp
-@item minimalistic
-Define the players and play directory but nothing more.
-@item standard
-Features the above plus the playlist buffer mode. Use this for a
-minimalistic installation plus a user interface to the playlists.
-@item all
-Features the above plus the reading the info from tagged Mp3 and Ogg
-files.
-@item devel
-Featuers all the above plus all the other modules shipped with Emms
-regardless if their stability. Use this only if yuo enjoy living on
-the edge.
-@end table
+@defun emms-minimalistic
+An Emms setup script.
+Invisible playlists and all the basics for playing media.
+@end defun
 
-Now your configuration is done.
+@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 convinience 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
 
-The (optional) directory is used for
-`emms-source-file-default-directory', in case you were wondering.
+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 Example
-@chapter Configuration Example
+@node Configuration
+@chapter Configuration
 
-@cindex Configuration Example
+@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
@@ -254,15 +272,16 @@ 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. Here is an example. The first `setq' turns off the
-asynchronous updating of info tags. The second sets the default name
-of the Emms playlist buffer.
+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.
 
@@ -524,6 +543,8 @@ Commands}.
 
 @cindex sources
 
+@c FIXME: This is rather bare, add some explanatory text.
+
 @defopt emms-source-file-default-directory
 The default directory to look for media files.
 @end defopt
@@ -617,7 +638,7 @@ bottom until it reaches the end of the playlist buffer.
 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 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
@@ -777,189 +798,12 @@ return an emms-info structure representing it.
 *The name/path of the mp3info-program.
 @end defopt
 
-@node The Playlist Buffer
-@chapter The Playlist Buffer
-@cindex playlist buffer
+@node Interactive Playlists
+@chapter Interactive Playlists
+@cindex Interactive Playlists
 
 @c FIXME: Completely rewrite the playlist buffer thus introducing the
 @c concept of multiple playlists to the people.
-@menu
-* Playlist Buffer::     Browsing buffer known by other players
-@end menu
-
-@node Playlist Buffers
-@section Playlist buffers
-
-@findex emms-playlist-mode-go
-@cindex playlist buffers
-
-@table @code
-Switch to playlist buffer
-
-The playlist-buffer *Playlist* will be created and put into
-emms-pbi-mode, which give you some usefull keybinings
-@end table
-
-@c New keymaps all around
-@table @kbd
-@item ?
-@kindex ? (Emms-pbi)
-@findex describe-mode
-Describe the keybindings
-@item <mouse-2>
-@kindex <mouse-2> (Emms-pbi)
-@findex emms-pbi-play-current-line
-Play the current line
-@item RET
-@kindex RET (Emms-pbi)
-@findex emms-pbi-play-current-line
-Play the current line
-@item q
-@kindex q
-@findex bury-buffer
-@item Q
-@kindex Q
-@findex emms-pbi-quit
-Stops emms and kill the playlist buffer
-@item f
-@kindex f
-@findex emms-pbi-show-current-line
-Show the trackname on current line
-@item s
-@kindex s
-@findex emms-stop
-Stop Emms
-@item C-y
-@kindex C-y
-@findex emms-pbi-yank
-Yank a filename from @var{emms-kill-ring} into the playlist.
-@item C-k
-@kindex C-k
-@findex emms-pbi-kill-line
-Kill the current line from the playlist.
-
-Send the filename to the @var{emms-kill-ring}. Make sure hooks that regenerate
-the entire playlist aren't run.
-@item c
-@kindex c
-@findex emms-pbi-recenter
-Center on current playing track
-@item p
-@kindex p
-@findex emms-previous
-Play the previous track in the playlist.
-@item n
-@kindex n
-@findex emms-next
-Play the next track in the playlist.
-This might behave funny in @var{emms-player-stopped-hook}, use
-@var{emms-next-noerror} instead for that.
-@item C-x C-s
-@kindex C-x C-s
-@findex emms-pbi-export-playlist
-Export the current playlist as to FILENAME. See also:
-@var{emms-pbi-import-playlist}.
-@end table
-
-@c FIXME: update these as well.
-@defun emms-pbi
-Turn on emms-playlist if prefix argument ARG is a positive integer,
-off otherwise.
-@end defun
-@defun emms-pbi-shorten-entry-to-max-length
-Cut off an entry-text to make sure it's no longer than
-`emms-pbi-playlist-entry-max-length' characters long.
-@end defun
-@defun emms-pbi-entry-info-updated
-Update the track-entry based on the info
-@end defun
-@defun emms-pbi-rebuild-playlist-buffer
-This function rebuilds the playlist-buffer if necessary.
-@end defun
-@defun emms-pbi-build-playlist-buffer
-Build a playlist-buffer based on the current playlist.
-@end defun
-@defun emms-pbi-insert-tag
-Insert the TRACK tag at point.
-The tag is automatically shortened by
-@command{emms-pbi-shorten-entry-to-max-length'}.
-@end defun
-@defun emms-pbi-insert-entry
-Insert an entry in the playlist
-@end defun
-@defun emms-pbi-async-alternative-text filename
-Generates a single replacement-text for @var{filename}, to be
-displayed in the playlist while the info is being loaded.
-@end defun
-@defun emms-pbi-update-current-face
-Updates the file line with the current-face
-@end defun
-@defun emms-pbi-add-properties-current-line
-Adds the correct faces and other properties to the current line
-@end defun
-@defun emms-pbi-play-current-line
-Play the current line
-@end defun
-@defun emms-pbi-show-current-line
-Show filename and info for track on current line.
-@end defun
-@defun emms-pbi-export-playlist filename
-Export the current playlist as to @var{filename}.
-@end defun
-@defun emms-pbi-quit
-Stops emms and kill the playlist buffer
-@end defun
-@defun emms-pbi-kill-line
-Kill the current line from the playlist.
-
-Send the filename to @var{emms-kill-ring}. Make sure hooks that
-regenerate the entire playlist aren't run.
-@end defun
-@defun emms-pbi-yank
-Yank a filename from `kill-ring' into the playlist.
-@end defun
-@defun emms-pbi-return-current-line-index
-Return the index position in the playlist of the current line.
-@end defun
-@defun emms-pbi-recenter
-Center on current playing track
-@end defun
-
-@defopt emms-pbi-playlist-entry-generate-function
-The function to call for generating a single item of the
-playlist. This will be called with a string argument FILENAME, and
-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
-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
-@defopt emms-pbi-async-alternative-text-function
-The function to call for generating the replacement-text for a
-playlist-item, while the info is lazy-loading. This will be called
-with a string argument FILENAME, and should return the text to be
-processed by emms-pbi-playlist-entry-generate-function.
-@end defopt
-@defopt emms-pbi-playlist-buffer-name
-Name of the buffer to use as a playlist-buffer
-@end defopt
-@defopt emms-pbi-load-info-async
-Whether or not to use emms-info.el's features for async loading
-info. Defaults to t when emms-info is available, and nil otherwise.
-@end defopt
-@defopt emms-pbi-after-build-hook
-Hook that is run after the playlist buffer is built.
-That might be usefull to change the playlist buffer before the
-buffer is set read-only.
-@end defopt
-@defopt emms-pbi-current-line-face-changed-hook
-Hook that is called when the face of the current line changes.
-@end defopt
-@defopt emms-pbi-manually-change-song-hook
-Hook that is called when the song is manually changed.
-@end defopt
 
 @node Extending Emms
 @chapter Extending Emms