* doc/emms.texinfo: update manual

2 files changed, 137 insertions, 79 deletions

diff --git a/doc/emms.texinfo b/doc/emms.texinfo
index 063cb75..43c5fc3 100644
--- a/doc/emms.texinfo
+++ b/doc/emms.texinfo
@@ -407,11 +407,11 @@ The method Emms will use is defined in the customisable variable
 @cindex configuration
 
 What follow are samples from real-world Emms configurations which show
-the variety and breadth of modifications people make to the default
-Emms setup.
+some of the variety and breadth of modifications people make to the
+default Emms setup.
 
-This excerpt includes dbus integration, defining a "recent" filter for
-the @xref{The Browser}, persistent playlist via
+The following excerpt includes dbus integration, defining a "recent"
+filter for the @xref{The Browser}, persistent playlist via
 @file{emms-history.el}, and enabling sending track information with
 @file{emms-librefm-stream.el}:
 
@@ -437,7 +437,10 @@ the @xref{The Browser}, persistent playlist via
   (emms-librefm-scrobbler-enable)
 @end lisp
 
-...
+
+In the following it is possible to see how some of defaults are set
+regarding saving playlists, playlist interaction, as well as adding
+special arguments to a specific player backend.
 
 @lisp
   (setq-default
@@ -446,12 +449,11 @@ the @xref{The Browser}, persistent playlist via
    emms-source-playlist-default-format 'm3u
    emms-playlist-mode-center-when-go t
    emms-playlist-default-major-mode 'emms-playlist-mode
+   emms-show-format "NP: %s"
 
    emms-player-list '(emms-player-mpv)
    emms-player-mpv-environment '("PULSE_PROP_media.role=music")
-   emms-player-mpv-parameters '("--quiet" "--really-quiet" "--no-audio-display" "--force-window=no" "--vo=null")
-
-   emms-show-format "NP: %s")
+   emms-player-mpv-parameters '("--quiet" "--really-quiet" "--no-audio-display" "--force-window=no" "--vo=null"))
 @end lisp
 
 
diff --git a/emms.info b/emms.info
index fc1ecfe..d18b9a7 100644
--- a/emms.info
+++ b/emms.info
@@ -123,7 +123,7 @@ Emms, an online version of the manual is available at:
    The basic functionality of Emms consists of three parts: The core,
 the sources, and the players.
 
-   The core resides in 'emms.el', and provides a simple playlist and the
+   The core resides in 'emms.el', provides a simple playlist, and the
 basic functionality to use all the other features of Emms.  It provides
 the common user commands and interfaces for other parts.  It thinks in
 tracks, where a track is the combination of a type and a name - e.g.
@@ -135,11 +135,11 @@ types are possible.
 system.
 
    When Emms finally has the sources in the playlist, it needs a player
-to play them.  'emms-player-simple.el' defines a few useful players, and
-allows you to define your own in a very simple way.
+to play them.  'emms-player-simple.el' defines a few useful players and
+provides a straightforward way of providing your own.
 
-   The Emms core comes with many additional features to extend its
-functionality.
+   The Emms comes with many additional features to extend the
+functionality beyond the core.
 
    The way Emms works is easy to customize with your own code or by
 using 'M-x customize' or by changing the variables directly.
@@ -154,9 +154,10 @@ This chapter demonstrates how to setup Emms so that you can start
 listening to your music without having to read all of the documentation
 first.  This is the tl;dr version of the manual.
 
-   The first thing you have to do is telling Emacs where Emms is
-located.  Let's say you have it in '~/elisp/emms/'.  So add this line to
-your '.emacs':
+   The first thing you do is to load Emms via GNU ELPA. But if you are
+installing manually, then start by telling Emacs where Emms is located.
+Let's say you have it in '~/elisp/emms/'.  So add this line to your
+'.emacs':
 
      (add-to-list 'load-path "~/elisp/emms/lisp/")
 
@@ -165,7 +166,7 @@ installation chapter, *Note Installation::.
 
    You'll then want to load Emms into Emacs.  To achieve this you invoke
 the 'emms-all' setup function by adding the following three lines to
-your '.emacs'.
+your Emacs initialization file.
 
      (require 'emms-setup)
      (emms-all)
@@ -185,14 +186,14 @@ the name of the file) of the music you listen to.  Emms can use a number
 of pieces of software and libraries as sources for track info, see *Note
 Track Information:: for more.
 
-   The last thing to do is to tell Emms where your music is; the root
+   The last thing to do is to tell Emms where is your music; the root
 directory of our music collection.  Let's say all your music is in
-'~/Music' or in subdirectories thereof.
+'~/Music' or in subdirectories thereof:
 
      (setq emms-source-file-default-directory "~/Music/")
 
-   OK, now we've set up Emms.  Reload your '.emacs' or restart Emacs to
-let the changes have an effect.
+   OK, now we've set up Emms.  Reload your Emacs initialization file or
+restart Emacs to let the changes have an effect.
 
    Now we will add all our music to a playlist by invoking 'M-x
 emms-add-directory-tree RET ~/Music/ RET'.  We do this because then Emms
@@ -201,9 +202,9 @@ required for the Emms browser, *Note The Browser::.)
 
    To switch to the playlist buffer, invoke 'M-x emms-playlist-mode-go'
 or simply 'M-x emms'.  You may see that some tracks are displayed with
-their file name, but as Emms populates its tag cache, track by track,
-the filenames get replaced with the artist and track name of the file's
-tag.
+their file name, but as Emms asynchronously populates its tag cache,
+track by track, the filenames get replaced with the artist and track
+name of the file's tag.
 
    Go ahead and navigate to a track and hit 'RET' on it to start
 playback.
@@ -329,9 +330,10 @@ mechanism provided by Emacs.
 * Menu:
 
 * Finding files and speed::     Finding files quickly or portably.
+* Setup Examples::              Examples of ways to setup Emms.
 
 
-File: emms.info,  Node: Finding files and speed,  Up: Configuration
+File: emms.info,  Node: Finding files and speed,  Next: Setup Examples,  Up: Configuration
 
 5.1 Finding files and speed
 ===========================
@@ -353,6 +355,57 @@ installed.
 EMMS-SOURCE-FILE-DIRECTORY-TREE-FUNCTION.
 
 
+File: emms.info,  Node: Setup Examples,  Prev: Finding files and speed,  Up: Configuration
+
+5.2 Setup Examples
+==================
+
+What follow are samples from real-world Emms configurations which show
+some of the variety and breadth of modifications people make to the
+default Emms setup.
+
+   The following excerpt includes dbus integration, defining a "recent"
+filter for the *Note The Browser::, persistent playlist via
+'emms-history.el', and enabling sending track information with
+'emms-librefm-stream.el':
+
+       ;; notifications
+       (require 'emms-dbus)
+       (emms-dbus-enable)
+       ;; covers
+       (setq emms-browser-covers #'emms-browser-cache-thumbnail-async)
+       (setq emms-browser-thumbnail-small-size 64)
+       (setq emms-browser-thumbnail-medium-size 128)
+       ;; filters
+       (emms-browser-make-filter "all" #'ignore)
+       (emms-browser-make-filter "recent"
+          (lambda (track) (< 30
+             (time-to-number-of-days
+       (time-subtract (current-time)
+             (emms-info-track-file-mtime track))))))
+       (emms-browser-set-filter (assoc "all" emms-browser-filters))
+       ;; history
+       (emms-history-load)
+       ;; libre-fm
+       (emms-librefm-scrobbler-enable)
+
+   In the following it is possible to see how some of defaults are set
+regarding saving playlists, playlist interaction, as well as adding
+special arguments to a specific player backend.
+
+       (setq-default
+        emms-source-file-default-directory "/mnt/db/mediaCore/sound_music/"
+
+        emms-source-playlist-default-format 'm3u
+        emms-playlist-mode-center-when-go t
+        emms-playlist-default-major-mode 'emms-playlist-mode
+        emms-show-format "NP: %s"
+
+        emms-player-list '(emms-player-mpv)
+        emms-player-mpv-environment '("PULSE_PROP_media.role=music")
+        emms-player-mpv-parameters '("--quiet" "--really-quiet" "--no-audio-display" "--force-window=no" "--vo=null"))
+
+
 File: emms.info,  Node: Getting Help,  Next: Formats and Freedom,  Prev: Configuration,  Up: Top
 
 6 Getting Help
@@ -3370,12 +3423,14 @@ Concept Index
 * compiling:                             Compiling Emms.        (line 6)
 * complex player:                        More Complex Player.   (line 6)
 * Configuration:                         Configuration.         (line 6)
+* configuration:                         Setup Examples.        (line 6)
 * core file:                             The Core File.         (line 6)
 * core functions:                        Core Functions.        (line 6)
 * defining info methods:                 Defining Info Methods. (line 6)
 * defining new players:                  New Player.            (line 6)
 * defining players:                      Extending Emms.        (line 6)
 * display emms information:              Emms Mode Line.        (line 6)
+* example:                               Setup Examples.        (line 6)
 * FDL, GNU Free Documentation License:   The GNU FDL.           (line 6)
 * files:                                 Finding files and speed.
                                                                 (line 6)
@@ -3757,59 +3812,60 @@ Keybinding Index
 Tag Table:
 Node: Top695
 Node: Introduction4442
-Node: Quickstart Guide5901
-Node: Installation8652
-Node: Compiling Emms9201
-Node: Setup9889
-Node: Configuration10875
-Node: Finding files and speed12286
-Node: Getting Help13132
-Node: Formats and Freedom13710
-Node: Basic Commands14915
-Node: The Core File18296
-Node: User Variables18730
-Node: Hooks19706
-Node: Core Functions21132
-Node: Sources24132
-Node: Simple Players26265
-Node: Playlists27322
-Node: Track Information28603
-Node: Using tinytag31490
-Node: Using exiftool31919
-Node: Using TagLib32291
-Node: Defining Info Methods33400
-Node: Interactive Playlists34182
-Node: Markable Playlists37224
-Node: Extending Emms39695
-Node: New Player40131
-Node: Simple Player for `play'40520
-Node: More Complex Player42248
-Node: The Browser45255
-Node: Browser Interface46231
-Node: Filtering Tracks48645
-Node: Displaying Covers50423
-Node: Changing Looks52437
-Node: Sorting Playlists55415
-Node: Persistent Playlists56884
-Node: Editing Tracks58043
-Node: Emms Mode Line61717
-Node: Limiting62885
-Node: Music Player Daemon65224
-Node: Lyrics68737
-Node: Volume70785
-Node: Streaming Audio72573
-Ref: Streaming Audio-Footnote-173165
-Node: APE / FLAC Commands73516
-Node: Bookmarks74223
-Node: Managing Playlists74934
-Node: GNU FM75957
-Node: Uploading Track Information77311
-Node: GNU FM Streaming78193
-Node: Copying78693
-Node: The GNU FDL116210
-Node: Concept Index138598
-Node: Function Index143529
-Node: Variable Index159221
-Node: Keybinding Index161564
+Node: Quickstart Guide5910
+Node: Installation8778
+Node: Compiling Emms9327
+Node: Setup10015
+Node: Configuration11001
+Node: Finding files and speed12476
+Node: Setup Examples13345
+Node: Getting Help15278
+Node: Formats and Freedom15856
+Node: Basic Commands17061
+Node: The Core File20442
+Node: User Variables20876
+Node: Hooks21852
+Node: Core Functions23278
+Node: Sources26278
+Node: Simple Players28411
+Node: Playlists29468
+Node: Track Information30749
+Node: Using tinytag33636
+Node: Using exiftool34065
+Node: Using TagLib34437
+Node: Defining Info Methods35546
+Node: Interactive Playlists36328
+Node: Markable Playlists39370
+Node: Extending Emms41841
+Node: New Player42277
+Node: Simple Player for `play'42666
+Node: More Complex Player44394
+Node: The Browser47401
+Node: Browser Interface48377
+Node: Filtering Tracks50791
+Node: Displaying Covers52569
+Node: Changing Looks54583
+Node: Sorting Playlists57561
+Node: Persistent Playlists59030
+Node: Editing Tracks60189
+Node: Emms Mode Line63863
+Node: Limiting65031
+Node: Music Player Daemon67370
+Node: Lyrics70883
+Node: Volume72931
+Node: Streaming Audio74719
+Ref: Streaming Audio-Footnote-175311
+Node: APE / FLAC Commands75662
+Node: Bookmarks76369
+Node: Managing Playlists77080
+Node: GNU FM78103
+Node: Uploading Track Information79457
+Node: GNU FM Streaming80339
+Node: Copying80839
+Node: The GNU FDL118356
+Node: Concept Index140744
+Node: Function Index145821
+Node: Variable Index161513
+Node: Keybinding Index163856
 
 End Tag Table