more manual re-writing

darcs-hash:20050930212451-be80e-f339987613f6eb5668f180268b1a32d080ac654b.gz

1 files changed, 47 insertions, 20 deletions

diff --git a/emms.texinfo b/emms.texinfo
index 297babc..381697f 100644
--- a/emms.texinfo
+++ b/emms.texinfo
@@ -4,8 +4,8 @@
 @settitle The Emms Manual
 @c %**end of header
 
-@c Maintainer comments:
-@c There is always work to do in a manual.
+@c Maintainer comments: As of Oct 2005 the manual is being re-written
+@c for Emms2.
 
 @dircategory Emacs
 @direntry
@@ -61,6 +61,7 @@ Emms basics
 * 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
 * Info Tags::           More narrative track descriptions.
@@ -186,7 +187,6 @@ just need the following line,
 @lisp
 (require 'emms)
 @end lisp
-@noindent
 
 which installs the core of Emms.
 
@@ -202,15 +202,20 @@ interface. Here's an example:
 @end lisp
 
 Here is a list of the interface complexity options:
+
 @table @samp
 @item minimalistic
 Define the players and play directory but nothing more.
-@item tiny
+@item standard
 Features the above plus the playlist buffer mode. Use this for a
 minimalistic installation plus a user interface to the playlists.
-@item default
+@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
 
 Now your configuration is done.
@@ -348,8 +353,6 @@ function uses @var{emms-show-format} to format the current track.
 
 @node The Core File
 @chapter The Core File
-@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.
 
@@ -423,7 +426,6 @@ Hook run when a player is paused or resumed. Use
 @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.
 
@@ -506,12 +508,6 @@ Seek ten seconds forward.
 @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}.
@@ -600,6 +596,36 @@ the specified PARAMS.
 Sentinel for determining the end of process
 @end defun
 
+@c FIXME finish writing this
+@node Playlists
+@chapter Playlists
+
+@cindex organizing tracks and media
+
+Emms uses an Emacs buffer to store a list of media tracks to be
+played. We call it a ``playlist buffer'' or an ``Emms playlist
+buffer''. Emms then proceeds to play the media tracks from top to
+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}.
+
+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
+
+The current Emms playlist buffer is stored in the variable
+@var{emms-playlist-buffer}.
+
 @node Info Tags
 @chapter Info Tags
 
@@ -609,8 +635,8 @@ The file @file{emms-info.el} provides an interface for different
 methods of reading info about the files that Emms is playing, and
 displaying it.
 
-To create a method for retrieving info about a file, you create an
-object like this:
+To create a method for retrieving (or setting) info about a file, you
+create an object like this:
 
 @lisp
 (define-emms-info-method emms-info-mp3info
@@ -754,12 +780,13 @@ return an emms-info structure representing it.
 * Playlist Buffer::     Browsing buffer known by other players
 @end menu
 
-@node Playlist Buffer
-@section Playlist buffer
+@node Playlist Buffers
+@section Playlist buffers
+
+@findex emms-playlist-mode-go
+@cindex playlist buffers
 
 @table @code
-@findex emms-pbi
-@item emms-pbi
 Switch to playlist buffer
 
 The playlist-buffer *Playlist* will be created and put into