[bongo-patches] Miscellaneous changes to the manual draft

[Daniel Brockman]

Miscellaneous changes to the manual draft.

diff -rN -u old-bongo/bongo.texinfo new-bongo/bongo.texinfo
--- old-bongo/bongo.texinfo     2007-05-24 13:29:47.000000000 +0200
+++ new-bongo/bongo.texinfo     2007-05-24 13:29:47.000000000 +0200
@@ -4,7 +4,7 @@
 @settitle Bongo Manual
 @c %**end of header
 
address@hidden LAST-UPDATED  May 8, 2007
address@hidden LAST-UPDATED  May 15, 2007
 
 @copying
 Copyright @copyright{} 2007  Daniel Brockman
@@ -85,11 +85,12 @@
 Playback
 
 * Pausing::             Temporarily stopping playback.
+* Stopping::            Permanently stopping playback.
 * Seeking::             Rewinding or fast-forwarding tracks.
+* Volume::              Changing the volume of your sound card.
+* Switching Tracks::    Playing the next or previous track.
 * Playback Modes::      Choosing the order in which tracks are played.
 * Sprinkle Mode::       Keeping playlists populated with random tracks.
-* Volume Control::      Controlling the volume of your sound card.
-* Last.fm::             Submitting song information to Last.fm.
 @end detailmenu
 @end menu
 
@@ -240,7 +241,7 @@
 Insert an action track (@code{bongo-insert-action}).
 
 This command prompts for an Emacs Lisp form to be evaluated when the
-action track is played.  @ref{Top, Emacs Lisp Reference, , elisp, GNU
+action track is played.  @ref{Top, Emacs Lisp Reference,, elisp, GNU
 Emacs Lisp Reference Manual}
 
 @item I cd @key{RET}
@@ -249,7 +250,7 @@
 insert a single track representing the entire disc.
 
 The customization group @code{bongo-audio-cd} covers this feature.
address@hidden Customization, , , emacs, GNU Emacs Manual}
address@hidden Customization,,, emacs, GNU Emacs Manual}
 
 @item I uri @key{RET}
 Insert a URI track (@code{bongo-insert-uri}).
@@ -280,15 +281,9 @@
 @node Playing Tracks
 @chapter Playing Tracks
 
-To start playing some particular track, move point to that track line
-and hit @key{RET} (@code{bongo-dwim}).  This does not work for playing
-sections, as @key{RET} on a section header just collapses the section.
-To play the thing at point, whether a track or a section, use @kbd{g}
-(@code{bongo-play}).
-
-Since library buffers are not meant to play tracks, in library buffers,
-the @key{RET} and @kbd{g} commands enqueue into the nearest playlist and
-play there instead.
+To play some particular track, move point to it and hit @key{RET} (or
+click on it).  Doing that on a section header will just collapse the
+section; to play a section, use @kbd{g} (@code{bongo-play}).
 
 @table @asis
 @item @key{RET}
@@ -306,144 +301,66 @@
 or marking.
 @end table
 
-It is often useful to temporarily pause playback without killing the
-backend player.  This is supported for all backends (@pxref{Pausing}).
-
address@hidden @asis
address@hidden @key{SPC}
-Pause or resume playback (@code{bongo-pause/resume}).
address@hidden table
-
-Some backends support fast-forwarding and rewinding the currently
-playing track.  @ref{Seeking} for details.
-
address@hidden @asis
address@hidden @kbd{f}, @kbd{F}, @kbd{M-F}, @kbd{C-M-F}
-Fast-forward the currently playing track (@code{bongo-seek-forward}).
address@hidden @kbd{b}, @kbd{B}, @kbd{M-B}, @kbd{C-M-B}
-Rewind the currently playing track (@code{bongo-seek-backward}).
address@hidden @kbd{s}
-Go into a special mode where @kbd{M-f}, @kbd{M-b}, @kbd{C-M-f},
address@hidden and the arrow keys do fast-forwarding and rewinding
-(@code{bongo-seek}).  Use @key{RET} or @kbd{C-g} to exit this mode.
address@hidden table
-
-The @kbd{C-c C-s} (@code{bongo-start/stop}) command stops playback and
-kills the backend player process if something is being played.
-If nothing is being played, then @kbd{C-c C-s} starts playing the
-first track (or the last track, in regressive playback mode).
-
address@hidden @asis
address@hidden @kbd{C-c C-s}
-Start or stop playback.
address@hidden @kbd{C-u C-c C-s}
-Switch to start/stop playback mode, in which playback stops whenever any
-track finishes playing (@pxref{Playback Modes}).
address@hidden @kbd{1 C-c C-s}
-Insert a stopping action track immediately after the current track
-(@pxref{Action Tracks}).  (``Stop after playing this one track.'')
address@hidden @kbd{5 C-c C-s}
-Insert a stopping action track five tracks below the current track.
-(``Stop after playing these five tracks.'')
address@hidden @kbd{C-u C-u C-c C-s}
-Insert a stopping action track at point.
address@hidden table
-
-The @kbd{C-c C-n} (@code{bongo-play-next}), @kbd{C-c C-p}
-(@code{bongo-play-previous}) and @kbd{C-c C-r}
-(@code{bongo-play-random}) commands are used to start playing another
-track, stopping any currently playing track first.
-
address@hidden @asis
address@hidden @kbd{C-c C-n}
-Play the next track.
address@hidden @kbd{5 C-c C-n}
-Skip four tracks downwards and play the one after that.
address@hidden @kbd{C-u C-c C-n}
-Switch to progressive playback mode (the default).
address@hidden @kbd{C-c C-p}
-Play the previous track.
address@hidden @kbd{5 C-c C-p}
-Skip four tracks upwards and play the one before that.
address@hidden @kbd{C-u C-c C-p}
-Switch to regressive playback mode, in which tracks are played in
-reverse order.
address@hidden @kbd{C-c C-r}
-Play a random track.
address@hidden @kbd{C-u C-c C-r}
-Switch to random playback mode.
address@hidden table
-
-Though @kbd{0 C-c C-n} may be used to play the current track again, it
-is easier to use the @kbd{C-c C-a}
-(@code{bongo-replay-current}) command.
-
address@hidden @asis
address@hidden @kbd{C-c C-a}
-Play the current track again.
address@hidden @kbd{C-u C-c C-a}
-Switch to repeating playback mode.
address@hidden table
-
-Just as @kbd{C-a} has a counterpart @kbd{C-e} in Emacs, so @kbd{C-c C-a}
-has a counterpart @kbd{C-c C-e} (@code{bongo-skip-current}) in Bongo.
-
address@hidden @asis
address@hidden @kbd{C-c C-e}
-Skip the current track and move on according to the current playback
-mode (@pxref{Playback Modes}).
address@hidden table
+Since libraries are not meant to play tracks, the @key{RET} and @kbd{g}
+commands enqueue into the nearest playlist and play there instead when
+used in a library buffer.
 
 @menu
 * Pausing::             Temporarily stopping playback.
+* Stopping::            Permanently stopping playback.
 * Seeking::             Rewinding or fast-forwarding tracks.
+* Volume::              Changing the volume of your sound card.
+* Switching Tracks::    Playing the next or previous track.
 * Playback Modes::      Choosing the order in which tracks are played.
 * Sprinkle Mode::       Keeping playlists populated with random tracks.
-* Volume Control::      Controlling the volume of your sound card.
-* Last.fm::             Submitting song information to Last.fm.
 @end menu
 
 @node Pausing
address@hidden Pausing
address@hidden Pausing Playback
 
 @cindex @key{SPC}
 @findex bongo-pause/resume
-The command @key{SPC} (@code{bongo-pause/resume}) toggles the paused
-state of the currently playing track.
+It is often useful to temporarily pause playback without killing the
+backend process.  The @key{SPC} command toggles the paused state of the
+currently playing track.
+
address@hidden @asis
address@hidden @key{SPC}
+Pause or resume playback (@code{bongo-pause/resume}).
address@hidden table
 
 @cindex signals
 Some backends (e.g., VLC and @samp{mpg123}) support pausing by talking
-to the player process through a pipe.  For backends where this is not
+to the backend process through a pipe.  For backends where this is not
 possible (due to lack of any such remote control facility), pausing is
 implemented using @samp{SIGTSTP} (or @samp{SIGSTOP}) and @samp{SIGCONT},
 which forces the entire process to stop (just as @samp{C-z} would in a
 job control shell).
 
 @node Seeking
address@hidden Seeking
address@hidden Fast-forwarding and Rewinding
 @cindex fast-forwarding
 @cindex rewinding
 
-Fast-forwarding and rewinding, usually referred to as @dfn{seeking}
-forward or backward, is how you skip around inside the currently
-playing track.
+Some backends support fast-forwarding and rewinding --- often referred
+to as @dfn{seeking} forward or backward.  This allows you to skip over
+some part of a track or go back and play some part of it again.
 
 @table @asis
address@hidden @kbd{b}, @kbd{f}
-Seek 1 second (or @var{n} seconds, given a prefix argument @var{n})
-backward (@code{bongo-seek-backward}) or forward
-(@code{bongo-seek-forward}) in the currently playing track.
-
address@hidden @kbd{B}, @kbd{F}
-Seek 3 seconds.
-
address@hidden @kbd{M-B}, @kbd{M-F}
-Seek 10 seconds.
-
address@hidden @kbd{C-M-B}, @kbd{C-M-F}
-Seek 60 seconds @footnote{Since the keys @kbd{C-M-B} and @kbd{C-M-F}
-cannot be typed in all terminals, the following commands may be used as
-substitutes:
address@hidden @kbd{f}, @kbd{b}
+Fast-forward or rewind the current track 1 second (or @var{n} seconds,
+given a prefix argument @var{n}).
+
address@hidden @kbd{F}, @kbd{B}, @address@hidden, @address@hidden
+Fast-forward or rewind 3 seconds (or 3 @var{n} seconds).
+
address@hidden @kbd{M-F}, @kbd{M-B}, @address@hidden, @address@hidden
+Fast-forward or rewind 10 seconds (or 10 @var{n} seconds).
+
address@hidden @kbd{C-M-F}, @kbd{C-M-B}, @address@hidden, @address@hidden
+Fast-forward or rewind 60 seconds (or @var{n} minutes) @footnote{While
address@hidden and @kbd{C-M-F} cannot be typed in all terminals, you may
+use the following commands as substitutes:
 
 @table @asis
 @item @kbd{60 b}, @kbd{60 f}
@@ -454,42 +371,39 @@
 @end table}.
 @end table
 
-By default, on graphical terminals, the mode line will contain buttons
-that let you seek using the mouse.  (To add or remove Bongo mode line
-buttons, customize @code{bongo-mode-line-indicator-format}.)
-
 To seek a specific number of seconds, give a numeric prefix argument to
 @kbd{f} or @kbd{b}.  (For example, @kbd{27 f} would seek 27
 seconds forward.)
 
-To seek to a specific position, use the command @kbd{s}
-(@code{bongo-seek}) with a numeric prefix argument.  (For example,
address@hidden s} would jump directly to 1 minute and 20 seconds from the
-beginning of the track.)  Giving just @kbd{C-u} as the prefix argument
-to @kbd{s} will prompt for the position to seek to, letting you say
-things like ``1:20''.
-
-Another way to seek is to type just @kbd{s} without any prefix argument.
-This takes you into a special mode, called Bongo Seek mode, which is
-dedicated to seeking @footnote{By default, Bongo Seek mode is
-``electric'', meaning that it assumes control over the entire keyboard.
-To turn this behavior off, customize the variable
address@hidden  When non-electric, Bongo Seek mode
-uses a regular window instead of the echo area.}.  Playback status is
-shown continuously in the echo area, and apart from the usual bindings
-for seeking (see above), the following extra key bindings are available:
+To seek to a specific position, use the @kbd{s} (@code{bongo-seek})
+command with a numeric prefix argument.  (For example, @kbd{80 s} would
+jump directly to 1 minute and 20 seconds from the beginning of the
+track.)  Giving just @kbd{C-u} as the prefix argument to @kbd{s} will
+prompt for the position to seek to and allows you to say things like
+``1:20''.
 
address@hidden @asis
address@hidden @key{LEFT}, @key{RIGHT}
-Seek 3 seconds.
+Unfortunately, not all backends support seeking.  Among the ones in the
+Bongo distribution, VLC and @samp{mpg123} do support it, whereas
address@hidden, @samp{speexdec}, TiMidity and MikMod do not.
 
address@hidden @kbd{M-b}, @kbd{M-f}, @address@hidden, @address@hidden, 
@key{DOWN}, @key{UP}
-Seek 10 seconds.
address@hidden Seek Mode
 
address@hidden @kbd{C-M-b}, @kbd{C-M-f}, @address@hidden, @address@hidden, 
@address@hidden, @address@hidden
-Seek 60 seconds.
+Typing @kbd{s} (@code{bongo-seek}) without any prefix argument takes you
+into a special mode dedicated to seeking.  In this mode, all the seeking
+commands work as usual, but you can drop most of the @kbd{S-} modifiers.
+For example, @address@hidden still works, but @key{left} does the
+same thing.
 
address@hidden @kbd{a}, @kbd{e}, @key{HOME}, @key{END}
address@hidden @asis
address@hidden @kbd{s}
+Enter seek mode.  Use @key{RET} or @kbd{C-g} to exit.
address@hidden table
+
+In seek mode, playback status is shown continuously in the echo area,
+and the following extra key bindings are available:
+
address@hidden @asis
address@hidden @kbd{a}, @kbd{e}, @key{home}, @key{end}
 These are shortcuts for @kbd{C-c C-a} (@code{bongo-replay-current}) and
 @kbd{C-c C-e} (@code{bongo-skip-current}).
 
@@ -497,26 +411,83 @@
 These are shortcuts for @kbd{C-c C-p} (@code{bongo-play-previous}),
 @kbd{C-c C-n} (@code{bongo-play-next}), and @kbd{C-c C-r}
 (@code{bongo-play-random}).
address@hidden table
 
address@hidden @key{RET}, @kbd{C-g}, @kbd{s}
-Quit Bongo Seek mode.
+Seek mode uses its own command loop, so you cannot do anything other
+than seeking (and a handful of other things) until you quit seek mode.
+If you don't like this, set @code{bongo-seek-electric-mode} to
address@hidden
+
address@hidden Stopping
address@hidden Stopping Playback
+
+The @kbd{C-c C-s} command stops playback and kills the backend process.
+However, if nothing is being played, then @kbd{C-c C-s} instead
address@hidden playing the first track.
+
address@hidden @asis
address@hidden @kbd{C-c C-s}
+Start or stop playback (@code{bongo-start/stop}).
address@hidden @kbd{C-u C-c C-s}
+Switch to start/stop playback mode, in which playback stops whenever any
+track finishes playing (@pxref{Playback Modes}).
address@hidden @kbd{1 C-c C-s}
+Insert a stopping action track (@pxref{Action Tracks}) immediately after
+the current track.  (``Stop after playing this track.'')
address@hidden @kbd{5 C-c C-s}
+Insert a stopping action track five tracks below the current track.
+(``Stop after playing these five tracks.'')
address@hidden @kbd{C-u C-u C-c C-s}
+Insert a stopping action track at point.
 @end table
 
-Unfortunately, not all backends support seeking.  Among the ones in the
-Bongo distribution, VLC and @samp{mpg123} do support it, whereas
address@hidden, @samp{speexdec}, TiMidity and MikMod do not.
address@hidden Switching Tracks
address@hidden Switching Tracks
+
+The @kbd{C-c C-n}, @kbd{C-c C-p} and @kbd{C-c C-r} commands are used to
+start playing another track (stopping any currently playing track first).
+
address@hidden @asis
address@hidden @kbd{C-c C-n}
+Play the next track (@code{bongo-play-next}).
address@hidden @kbd{C-c C-p}
+Play the previous track (@code{bongo-play-previous}).
address@hidden @kbd{C-c C-r}
+Play a random track (@code{bongo-play-random}).
address@hidden @kbd{5 C-c C-n}
+Skip four tracks downwards and play the one after that.
address@hidden @kbd{5 C-c C-p}
+Skip four tracks upwards and play the one before that.
address@hidden table
+
+Though @kbd{0 C-c C-n} may be used to play the current track again, it
+is easier to use the @kbd{C-c C-a} command.
+
address@hidden @asis
address@hidden @kbd{C-c C-a}
+Play the current track again (@code{bongo-replay-current}).
address@hidden table
+
+Just as the regular @kbd{C-a} command in Emacs has a counterpart
address@hidden, so @kbd{C-c C-a} has a counterpart @kbd{C-c C-e}.
+
address@hidden @asis
address@hidden @kbd{C-c C-e}
+Skip the current track (@code{bongo-skip-current}).  Proceed according
+to the current playback mode (@pxref{Playback Modes}).
address@hidden table
 
 @node Playback Modes
 @section Playback Modes
 
 Whenever a track finishes playing (or is skipped using @kbd{C-c C-e}),
-normally, the next track in the playlist will be played --- this is the
+normally, the next track in the playlist will be played.  This is the
 default behavior, but it can be changed.  The way Bongo chooses which
 track to play next is called the @dfn{playback mode}.
 
 There are five built-in playback modes.  Switching to one of them is
 easily done by giving a @kbd{C-u} prefix argument to the corresponding
-playback command (@pxref{Playing Tracks}):
+playback command:
 
 @table @kbd
 @item C-u C-c C-n
@@ -565,18 +536,14 @@
 
 
 
address@hidden Volume Control
address@hidden Volume Control
address@hidden Volume
address@hidden Volume
 
 The volume control facility is provided by the @samp{volume} library
 @footnote{http://www.brockman.se/software/volume-el/}.
 
 The @kbd{v} (@code{volume}) command
 
address@hidden Last.fm
address@hidden Last.fm
-
-
 @node Enqueuing Tracks
 @chapter Enqueuing Tracks
 

-- 
Daniel Brockman <address@hidden>