refinements-and-docs-for-emms-history.dpatch

This path makes some refinements in emms-history.el:

  - Start playback after `emms-history-load' only if
    `emms-history-start-playing' is non-nil.
  - Added customization group emms-history
  - defvar -> defcustom
  - better docstrings and commentary
  - Added Info docs. (Node "Persistent Playlists")

darcs-hash:20070815080114-c06f4-fbe6c254a5dade4d6a99130fb2cc43c277ef6311.gz

2 files changed, 83 insertions, 20 deletions

diff --git a/emms-history.el b/emms-history.el
index b3b9f0c..153e43a 100644
--- a/emms-history.el
+++ b/emms-history.el
@@ -1,4 +1,4 @@
-;;; emms-history.el -- save playlist when exit emacs
+;;; emms-history.el -- save all playlists when exiting emacs
 
 ;; Copyright (C) 2006, 2007 Free Software Foundation, Inc.
 ;;
@@ -22,25 +22,42 @@
 
 ;;; Commentary:
 
-;; Save playlists when exit emacs.
-;; Next time use M-x emms-history-load to load saved playlist
+;; Saves all playlists when you close emacs.  When you start it up again use
+;; M-x emms-history-load to restore all saved playlists.
 
-;; Put this file into your load-path and the following into your ~/.emacs:
+;; To use it put the following into your ~/.emacs:
+;;
 ;;   (require 'emms-history)
+;;
+;; If all playlists should be restored on startup add this, too:
+;;
+;;   (emms-history-load)
 
 ;;; Code:
 
-(provide 'emms-history)
 (require 'emms)
 (eval-when-compile
   (require 'cl))
 
-(defvar emms-history-file "~/.emacs.d/.emms-history"
-  "File to save playlists")
+(defgroup emms-history nil
+  "Saving and restoring all playlists when closing/restarting
+Emacs."
+  :prefix "emms-history-"
+  :group 'emms)
+
+(defcustom emms-history-file "~/.emacs.d/emms-history"
+  "The file to save playlists in."
+  :type   'string
+  :group  'emms-history)
+
+(defcustom emms-history-start-playing nil
+  "If non-nil emms starts playing the current track after
+`emms-history-load' was invoked."
+  :type   'boolean
+  :group  'emms-history)
 
 (defun emms-history-save ()
-  "Save all playlists that open in this emacs session when exit. Use
-`emms-history-load' to load saved playlists."
+  "Save all playlists that are open in this Emacs session."
   (interactive)
   (when (stringp emms-history-file)
     (let ((oldbuf emms-playlist-buffer)
@@ -80,6 +97,7 @@
 (add-hook 'kill-emacs-hook 'emms-history-save)
 
 (defun emms-history-load ()
+  "Restore all playlists in `emms-history-file'."
   (interactive)
   (when (and (stringp emms-history-file)
              (file-exists-p emms-history-file))
@@ -100,6 +118,8 @@
         (dolist (method (nth 2 history))
           (set (car method) (cdr method)))
         (ignore-errors
-          (emms-start))))))
+          (when emms-history-start-playing
+            (emms-start)))))))
 
+(provide 'emms-history)
 ;;; emms-history.el ends here
diff --git a/emms.texinfo b/emms.texinfo
index d15b36d..4c03120 100644
--- a/emms.texinfo
+++ b/emms.texinfo
@@ -68,16 +68,17 @@ Advanced Features
 * Markable Playlists::       Allow tracks to be marked.
 
 Modules and Extensions
-* The Browser::         Advanced metadata browsing.
-* Sorting Playlists::   Sorting the order of the tracks.
-* Editing Tracks::      Editing track information from within Emms.
-* Emms Mode Line::      Emms information on the mode line.
-* Music Player Daemon:: Interface to Music Player Daemon.
-* Streaming Audio::     Interface to streaming audio.
-* Lyrics::              Displaying lyrics synchronously.
-* Volume::              Changing the volume.
-* Last.fm::             Interact with http://www.last.fm's services.
-* Extending Emms::      How to define new players and modules.
+* The Browser::          Advanced metadata browsing.
+* Sorting Playlists::    Sorting the order of the tracks.
+* Persistent Playlists:: Restoring playlists on emacs startup.
+* Editing Tracks::       Editing track information from within Emms.
+* Emms Mode Line::       Emms information on the mode line.
+* Music Player Daemon::  Interface to Music Player Daemon.
+* Streaming Audio::      Interface to streaming audio.
+* Lyrics::               Displaying lyrics synchronously.
+* Volume::               Changing the volume.
+* Last.fm::              Interact with http://www.last.fm's services.
+* Extending Emms::       How to define new players and modules.
 
 Copying and license
 * Copying::             The GNU General Public License gives you permission to
@@ -1699,6 +1700,48 @@ Sort playlist by notes in ascending order.
 Sort emms playlist by score in descending order.
 @end defun
 
+@node Persistent Playlists
+@chapter Persistent Playlists
+
+The Emms module @file{emms-history.el} makes playlists persistent over
+emacs sessions.  To make use of this feature put this into your
+~/.emacs.
+
+@lisp
+(require 'emms-history)
+@end lisp
+
+When you kill emacs all playlists will be saved in the file given by the
+variable:
+
+@defopt emms-history-file
+The file to save playlists in.  It defaults to
+"~/.emacs.d/emms-history".
+@end defopt
+
+After you started up emacs again, you can restore all saved playlists
+with this function.
+
+@defun emms-history-load
+Restore all playlists in `emms-history-file'.
+@end defun
+
+If that should be done automatically on each startup, put these lines
+into your ~/.emacs.
+
+@lisp
+(require 'emms-history)
+(emms-history-load)
+@end lisp
+
+Normally @code{emms-history} only restores playlists.  If you want it to
+start playback afterwards, you can tweak this variable.
+
+@defopt emms-history-start-playing
+If non-nil emms starts playing the current track after
+`emms-history-load' was invoked.  The default value is nil.
+@end defopt
+
 @node Editing Tracks
 @chapter Editing Tracks