From 5e9eb077a9acdd12ec028e6eee394926780c285f Mon Sep 17 00:00:00 2001
From: Damyan Ivanov <dmn@debian.org>
Date: Thu, 2 Dec 2021 17:33:01 +0000
Subject: [PATCH] more docs

---
 bin/mpd-feeder | 140 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 131 insertions(+), 9 deletions(-)

diff --git a/bin/mpd-feeder b/bin/mpd-feeder
index 99453c3..15520e7 100755
--- a/bin/mpd-feeder
+++ b/bin/mpd-feeder
@@ -39,7 +39,7 @@ Engage daemon mode, keeping the MPD playlist full:
 
     mpd-feeder [I<option>...]
 
-Perform a single command and return:
+Perform a single command and return to the OS:
 
     mpd-feeder [I<option>...] I<command>
 
@@ -58,12 +58,12 @@ The timespans for "recent" queueing are configurable.
 =head1 COMMANDS
 
 In daemon mode (with no command given), C<mpd-feeder> connects to MPD, updates
-its local copy of the song database and makes sure that the playlist never has
-fewer songs than the configured minimum. Playlist changes are detected when
-they happen.
+its local copy of the song database (but see C<--skip-db-update> option below)
+and makes sure that the playlist is never left with fewer songs than the
+configured minimum. Playlist changes are detected when they happen.
 
-When a command is given, C<mpd-feeder> does not engage in daemon mode, but returns
-to the OS after execution.
+When a command is given, C<mpd-feeder> does not engage in daemon mode, but
+returns to the OS after execution.
 
 =head2 dump-config
 
@@ -90,8 +90,9 @@ Prints the contents of the unwanted artist list, one per line.
 
 =head2 list-unwanted-albums
 
-Manupulate the list of unwanted albums. Useful when there is an album you don't
-want to listen to, but you still want to hear other albums by the same artist.
+Manupulate the list of unwanted albums. Useful when there is a specific album
+you don't want to listen to, but you don't mind other albums by the same
+artist.
 
 =head2 one-shot
 
@@ -100,12 +101,20 @@ songs.
 
 =head2 single
 
-Adds one song to the playlist. Ignores the configured minimum.
+Adds one song to the playlist. Ignores the configured minimum playlist length.
 
 =head1 OPTIONS
 
 =over
 
+=item B<--config> I<file>
+
+=item B<--cfg> I<file>
+
+The configuration file to read at startup.
+
+B<Default>: C</etc/mpd-feeder/mpd-feeder.conf>.
+
 =item B<--log-level> I<trace|debug|info|notice|warning|error|critical|alert|emergency>
 
 Set log verbosity. C<trace> is most talkative, including all exchanges with MPD.
@@ -147,6 +156,119 @@ I<duration> is a text duration, recognised by L<Time::Duration::Parse>.
 
 =head1 CONFIGURATION FILE
 
+Configuration file is an C<.ini> file with the following sections. You can get
+a skeleton configuration by executing C<mpd-feeder dump-config>. That will
+produce a configuration file filled with the default values.
+
+=head2 [mpd-feeder]
+
+=over
+
+=item B<log_level> = I<level>
+
+Determines the verboseness of the logging. See L</--log-level> option above.
+
+B<Default>: C<warn>.
+
+=back
+
+=head2 [mpd]
+
+=over
+
+=item B<host> = I<hostname>
+
+The host where MPD is running.
+
+B<Default>: none. However, L<Net::Async::MPD> defaults to the value of the
+C<MPD_HOST> environment variable, and if that is empty - C<localhost>.
+
+=item B<port> = I<number>
+
+The port number where MPD is listening.
+
+B<Default>: none. However, L<Net::Async::MPD> defaults to the value of the
+C<MPD_PORT> environment variable, and if that is empty - C<6600>.
+
+=item B<initial-reconnect-delay> = I<duration>
+
+=item B<max-reconnect-delay> = I<duration>
+
+When the connection to MPD is lost, a delay is inserted before a re-connection
+attempt is made. The duration of the delay is controlled with these two
+options. Each delay is a bit longer than the last, starting with the value of
+<initial-reconnect-delay>, and topped at the value of C<max-reconnect-delay>.
+
+When a connection is made, the delay before the next re-connection is reset to
+C<initial-reconnect-delay>.
+
+B<Default>: C<3 seconds> for C<initial-reconnect-delay> and C<2 minutes> for
+C<max-reconnect-delay>.
+
+=back
+
+=head2 [queue]
+
+=over
+
+=item B<target-length> = I<number>
+
+The number of songs to always have in the MPD's playlist.
+
+B<Default>: C<10>.
+
+=item B<min-song-interval> = I<duration>
+
+The minimum amount of time after a song is added to the playlist by
+B<mpd-feeder>, before it is considered again.
+
+B<Default>: C<13 days>
+
+=item B<min-album-interval> = I<duration>
+
+The minimum amount of time after a song is added to the playlist by
+B<mpd-feeder> before songs from the same album are considered for addition to
+the playlist.
+
+B<Default>: C<5 hours>.
+
+=item B<min-artist-interval> = I<duration>
+
+The minimum amount of time after a song is added to the playlist by
+B<mpd-feeder> before songs by the same artist are consideret for addition to
+the playlist.
+
+B<Default>: C<1 hour and 15 minutes>.
+
+=back
+
+=head2 [db]
+
+=over
+
+=item B<path> = I<DSN>
+
+PostgresQL database name to use for local storage.
+
+B<Default>: C<mpd-feeder>
+
+=item B<user> = I<name>
+
+PostgreSQL user name to connect as.
+
+B<Default>: none.
+
+=item B<password> = I<secret>
+
+Password to use when connecting to PostgreSQL.
+
+B<Default>: none.
+
+=back
+
+See F<init.sql> file in the distribution for commands to initializa the
+database.
+
 =head1 COPYRIGHT & LICENSE
 
 Copyright © 2021 Damyan Ivanov L<dam+mpdfeeder@ktnx.net>
-- 
2.39.2