Update man pages

4 files changed, 238 insertions, 196 deletions

diff --git a/man/http-music-crawl-http.1 b/man/http-music-crawl-http.1
index 949d682..003e8f7 100644
--- a/man/http-music-crawl-http.1
+++ b/man/http-music-crawl-http.1
@@ -1,16 +1,13 @@
 .TH http-music-crawl-http 1
 
-
 .SH NAME
 http-music-crawl-http - create a playlist file using an HTTP-based directory listing
 
-
 .SH SYNOPSIS
 .B http-music-crawl-http
 \fIdownloadURL\fR
 [opts...]
 
-
 .SH DESCRIPTION
 \fBhttp-music-crawl-http\fR is a (convolutedly-named) command line utility used to generate playlist files for \fBhttp-music\fR by crawling the directory listing found at a given URL.
 http-music uses playlist files as its source of music; without a playlist file, the program simply does not know what to play!
@@ -44,26 +41,26 @@ http://example.com/
 .PP
 .nf
 .RS
-[
-  ['Rainbows', [
-    ['Sunlight', 'http://example.com/Rainbows/Sunlight.mp3'],
-    ['Rainbows', 'http://example.com/Rainbows/Rainbows.mp3'],
-    ['Pineapples', 'http://example.com/Rainbows/Pineapples.mp3']
-  ]],
-  ['Cool Author 72', [
-    ['Good Album', [
-      ['Hello World!', 'http://example.com/Cool%20Author%2072/Good%20Album/Hello%20World.mp3'],
-    ]]
-  ]],
-  ['Bad News', [
-    ['Bad News - Single', [
+{items: [
+  {name: 'Rainbows', items: [
+    {name: 'Sunlight', downloaderArg: 'http://example.com/Rainbows/Sunlight.mp3'},
+    {name: 'Rainbows', downloaderArg: 'http://example.com/Rainbows/Rainbows.mp3'},
+    {name: 'Pineapples', downloaderArg: 'http://example.com/Rainbows/Pineapples.mp3'}
+  ]},
+  {name: 'Cool Author 72', items: [
+    {name: 'Good Album', items: [
+      {name: 'Hello World!', downloaderArg: 'http://example.com/Cool%20Author%2072/Good%20Album/Hello%20World.mp3'},
+    ]}
+  ]},
+  {name: 'Bad News', [
+    {name: 'Bad News - Single', items: [
       ['Bad News', 'http://example.com/Bad%20News/Bad%20News%20-%20Single/Bad%20News.mp3']
-    ]],
-    ['Irony', [
+    ]},
+    {name: 'Irony', items: [
       ['Rahhhh!!', 'http://example.com/Bad%20News/Irony/Rahhhh!!.mp3']
-    ]]
-  ]]
-]
+    ]}
+  ]}
+]}
 .RE
 .fi
 
diff --git a/man/http-music-crawl-itunes.1 b/man/http-music-crawl-itunes.1
index 9d21734..e1f39d5 100644
--- a/man/http-music-crawl-itunes.1
+++ b/man/http-music-crawl-itunes.1
@@ -1,10 +1,10 @@
-.TH http-music-crawl-itunes 1
+.TH HTTP-MUSIC-CRAWL-ITUNES 1
 
 .SH NAME
 http-music-crawl-itunes - create a playlist file using an iTunes library
 
 .SH SYNOPSIS
-.B http-music-crawl-itunes
+.B http-music crawl-itunes
 [libraryPath]
 
 .SH DESCRIPTION
diff --git a/man/http-music-play.1 b/man/http-music-play.1
new file mode 100644
index 0000000..36e33fd
--- /dev/null
+++ b/man/http-music-play.1
@@ -0,0 +1,198 @@
+.TH HTTP-MUSIC-PLAY 1
+
+.SH NAME
+http-music-play - plays audio from a playlist file
+
+.SH SYNOPSIS
+.B http-music play
+[opts...]
+
+.SH DESCRIPTION
+Plays audio referenced from a playlist file.
+Tracks selected using a "picker" (see \fB--picker\fR) and retrieved using a "downloader" (see \fB--downloader\fR).
+Downloaded tracks are played with the \fBmpv\fR process.
+(As such, \fBmpv\fR is a required dependency for http-music to play anything.)
+
+
+.SH KEYBOARD CONTROLS
+.TP
+.BR <left-arrow>
+Skips backwards 5 seconds in the currently playing track; hold shift to skip by
+30 seconds.
+
+.TP
+.BR <right-arrow>
+Skips forwards 5 seconds in the currently playing track; hold shift to skip by
+30 seconds.
+
+.TP
+.BR <up-arrow>
+Turns the volume up a 10%-notch.
+Unfortunately, at present, the volume setting is NOT kept across tracks.
+You'll need to adjust your audio volume whenever a new song starts.
+(If possible, it might be better just to opt for changing the system volume.)
+
+.TP
+.BR <down-arrow>
+Turns the volume down 10%.
+
+.TP
+.BR <space>
+Pauses (or resumes) playback.
+
+.TP
+.BR i
+Shows information (title, URL/path) on the currently playing track.
+(\fBt\fR also works.)
+
+.TP
+.BR q
+Quits the http-music process and stops music currently being played.
+(\fB^C\fR and \fB^D\fR also work.)
+
+.TP
+.BR s
+Skips the currently playing track.
+
+
+.SH OPTIONS
+.TP
+.BR \-c ", " \-\-clear
+Clears the active playlist.
+This does not effect the source playlist, so specific groups can be selected using \fB\-\-keep\fR.
+
+
+.TP
+.BR \-h ", " \-? ", " \-\-help
+Presents a help message, directing the user to the \fBman\fR page.
+If this is the last option used, nothing plays (see \fB\-\-play\fR).
+
+.TP
+.BR \-k ", " \-\-keep " \fIgroupPath\fR"
+Keeps a group by adding it from the source playlist.
+This is usually useful after clearing the active playlist (\fB\-\-clear\fR); it can also be used to keep a sub-group after removing an entire parent group, e.g. \fB-r foo -k foo/baz\fR.
+
+.TP
+.BR \-l ", " \-\-list\-groups ", " \-\-list
+Lists all groups (but not tracks) in the (active) playlist.
+If this is the last option used, nothing plays (see \fB\-\-play\fR).
+
+.TP
+.BR \-L ", " \-\-list\-all ", " \-\-list\-tracks
+Lists all groups and tracks in the (active) playlist.
+If this is the last option used, nothing plays (see \fB\-\-play\fR).
+
+.TP
+.BR \-np ", " \-\-no\-play
+Forces the playlist not to play.
+See also \fB\-\-play\fR.
+
+.TP
+.BR \-o ", " \-\-open\-playlist ", " \-\-open " \fIplaylistFile\fR"
+Opens a specific file to be used as the playlist file.
+(This sets the source playlist.)
+The default playlist file used upon loading is \fBplaylist.json\fR (in the same directory as \fBhttp-music\fR is being run in).
+
+.TP
+.BR \-\-picker ", " \-\-selector " \fIpickerType\fR"
+Sets the picker type used for selecting tracks from the active playlist.
+The default is \fBshuffle\fR.
+
+.TP
+.BR \-p ", " \-\-play
+Forces the playlist to actually play, regardless of options such as \fB\-\-list\fR. See also \fB\-\-no\-play\fR.
+
+.TP
+.BR \-\-play\-opts
+Sets command line options passed to the \fBplay\fR command.
+For example, playback volume may be set to 30% by using \fB\-\-play\-opts '\-\-volume 30'\fR.
+
+.TP
+.BR \-\-print\-playlist ", " \-\-log-playlist ", " \-\-json
+Prints the JSON representation of the active playlist to the console.
+
+.TP
+.BR \-r ", " \-\-remove ", " \-x " \fIgroupPath\fR"
+Removes a group from the (active) playlist.
+
+.TP
+.BR \-w ", " \-\-write\-playlist ", " \-\-write ", " \-\-save " \fIfilePath\fR"
+Writes the active playlist to a file.
+This file can later be used with \fB\-\-open\fR; you won't need to stick in all the filtering options again.
+
+
+.SH EXAMPLES
+Basic usage:
+
+.PP
+.nf
+.RS
+$ http-music play
+.RE
+.fi
+
+.PP
+Generate a playlist from an HTTP server:
+
+.PP
+.nf
+.RS
+$ http-music crawl-http http://example.com/path > playlist.json
+.RE
+.fi
+
+.PP
+Generate a playlist from the local file system:
+
+.PP
+.nf
+.RS
+$ http-music crawl-local /example/path > playlist.json
+.RE
+.fi
+
+.PP
+Open a specific playlist file:
+
+.PP
+.nf
+.RS
+$ http-music play --open playlist2.json
+$ http-music play -o playlist2.json
+.RE
+.fi
+
+.PP
+Only play music under a specific group:
+
+.PP
+.nf
+.RS
+$ http-music play --clear --keep 'Cool Author 72'
+$ http-music play -c -k 'Cool Author 72'
+$ http-music play -c -k 'Cool Author 72/Good Album'
+.RE
+.fi
+
+.PP
+Don't play music under a specific group:
+
+.PP
+.nf
+.RS
+$ http-music play --remove 'Bad News'
+$ http-music play -r 'Bad News'
+$ http-music play -x 'Bad News'
+.RE
+.fi
+
+.PP
+Don't play music under a specific group, except for a sub-group:
+
+.PP
+.nf
+.RS
+$ http-music play --remove 'Bad News' --keep 'Bad News/Irony'
+$ http-music play -x 'Cool Author 72' -k 'Cool Author 72/Good Album'
+.RE
+.fi
diff --git a/man/http-music.1 b/man/http-music.1
index 693cb4d..12970bc 100644
--- a/man/http-music.1
+++ b/man/http-music.1
@@ -1,204 +1,51 @@
 .TH HTTP-MUSIC 1
 
-
-
 .SH NAME
-http-music - play music through the internet
-
-
+http-music - play music through the internet (and other places)
 
 .SH SYNOPSIS
 .B http-music
+<command>
 [opts...]
 
-
-
 .SH DESCRIPTION
 \fBhttp-music\fR is an easy-to-use command line music player that uses the internet as its main source.
 It features several convenient options which make it powerful while still sticking to the idea of keeping the utility as usable as possible.
+
 .PP
 \fBhttp-music\fR is portable.
 It can be used anywhere with a Node environment, requiring only two commonly installed (and otherwise easy to get) utilities (\fBmpv\fR and \fBavconv\fR, optionally \fByoutube-dl\fR).
 
+.PP
+Playlists are stored as JSON files.
+See \fBhttp-music-crawl-http\fR(1) for an example of the playlist file structure.
 
 
-.SH KEYBOARD CONTROLS
-.TP
-.BR <left-arrow>
-Skips backwards 5 seconds in the currently playing track; hold shift to skip by
-30 seconds.
-
-.TP
-.BR <right-arrow>
-Skips forwards 5 seconds in the currently playing track; hold shift to skip by
-30 seconds.
-
-.TP
-.BR <up-arrow>
-Turns the volume up a 10%-notch.
-
-.TP
-.BR <down-arrow>
-Turns the volume down 10%.
-
-.TP
-.BR <space>
-Pauses (or resumes) playback.
-
-.TP
-.BR i
-Shows information (title, URL/path) on the currently playing track.
-(\fBt\fR also works.)
-
-.TP
-.BR q
-Quits the http-music process and stops music currently being played.
-(\fB^C\fR and \fB^D\fR also work.)
-
-.TP
-.BR s
-Skips the currently playing track.
-
-
-.SH OPTIONS
-.TP
-.BR \-c ", " \-\-clear
-Clears the active playlist.
-This does not effect the source playlist, so specific groups can be selected using \fB\-\-keep\fR.
-
-
-.TP
-.BR \-h ", " \-? ", " \-\-help
-Presents a help message, directing the user to the \fBman\fR page.
-If this is the last option used, nothing plays (see \fB\-\-play\fR).
-
-.TP
-.BR \-k ", " \-\-keep " \fIgroupPath\fR"
-Keeps a group by adding it from the source playlist.
-This is usually useful after clearing the active playlist (\fB\-\-clear\fR); it can also be used to keep a sub-group after removing an entire parent group, e.g. \fB-r foo -k foo/baz\fR.
-
-.TP
-.BR \-l ", " \-\-list\-groups ", " \-\-list
-Lists all groups (but not tracks) in the (active) playlist.
-If this is the last option used, nothing plays (see \fB\-\-play\fR).
-
-.TP
-.BR \-L ", " \-\-list\-all ", " \-\-list\-tracks
-Lists all groups and tracks in the (active) playlist.
-If this is the last option used, nothing plays (see \fB\-\-play\fR).
-
-.TP
-.BR \-np ", " \-\-no\-play
-Forces the playlist not to play.
-See also \fB\-\-play\fR.
+.SH SUB-COMMANDS
+The command line utility \fBhttp-music\fR is split into various sub-commands for convenience.
+They are as listed below; each sub-command also has its own \fBman\fR page (for example, \fBcrawl-http\fR's page is \fBhttp-music-crawl-http\fR(1).)
 
 .TP
-.BR \-o ", " \-\-open\-playlist ", " \-\-open " \fIplaylistFile\fR"
-Opens a specific file to be used as the playlist file.
-(This sets the source playlist.)
-The default playlist file used upon loading is \fBplaylist.json\fR (in the same directory as \fBhttp-music\fR is being run in).
+.BR play
+Plays a playlist (from the playlist.json file, by default).
 
 .TP
-.BR \-\-picker ", " \-\-selector " \fIpickerType\fR"
-Sets the picker type used for selecting tracks from the active playlist.
-The default is \fBshuffle\fR.
+.BR crawl-http
+Creates a playlist from each music file linked to from an HTML page online.
 
 .TP
-.BR \-p ", " \-\-play
-Forces the playlist to actually play, regardless of options such as \fB\-\-list\fR. See also \fB\-\-no\-play\fR.
+.BR crawl-local
+Creates a playlist from a directory on the local machine.
 
 .TP
-.BR \-\-play\-opts
-Sets command line options passed to the \fBplay\fR command.
-For example, playback volume may be set to 30% by using \fB\-\-play\-opts '\-\-volume 30'\fR.
+.BR crawl-itunes
+Creates a playlist from the iTunes Shared Library.
 
 .TP
-.BR \-\-print\-playlist ", " \-\-log-playlist ", " \-\-json
-Prints the JSON representation of the active playlist to the console.
-
-.TP
-.BR \-r ", " \-\-remove ", " \-x " \fIgroupPath\fR"
-Removes a group from the (active) playlist.
-
-.TP
-.BR \-w ", " \-\-write\-playlist ", " \-\-write ", " \-\-save " \fIfilePath\fR"
-Writes the active playlist to a file.
-This file can later be used with \fB\-\-open\fR; you won't need to stick in all the filtering options again.
+.BR download-playlist
+Downloads each item in a playlist into a directory.
 
 
 
 .SH EXAMPLES
-Basic usage:
-
-.PP
-.nf
-.RS
-$ http-music
-.RE
-.fi
-
-.PP
-Generate a playlist from an HTTP server:
-
-.PP
-.nf
-.RS
-$ http-music-crawl-http http://example.com/path > playlist.json
-.RE
-.fi
-
-.PP
-Generate a playlist from the local file system:
-
-.PP
-.nf
-.RS
-$ http-music-crawl-local /example/path > playlist.json
-.RE
-.fi
-
-.PP
-Open a specific playlist file:
-
-.PP
-.nf
-.RS
-$ http-music --open playlist2.json
-$ http-music -o playlist2.json
-.RE
-.fi
-
-.PP
-Only play music under a specific group:
-
-.PP
-.nf
-.RS
-$ http-music --clear --keep 'Cool Author 72'
-$ http-music -c -k 'Cool Author 72'
-$ http-music -c -k 'Cool Author 72/Good Album'
-.RE
-.fi
-
-.PP
-Don't play music under a specific group:
-
-.PP
-.nf
-.RS
-$ http-music --remove 'Bad News'
-$ http-music -r 'Bad News'
-$ http-music -x 'Bad News'
-.RE
-.fi
-
-.PP
-Don't play music under a specific group, except for a sub-group:
-
-.PP
-.nf
-.RS
-$ http-music --remove 'Bad News' --keep 'Bad News/Irony'
-$ http-music -x 'Cool Author 72' -k 'Cool Author 72/Good Album'
-.RE
-.fi
+See \fBhttp-music-play\fR(1).