Docs and whatnot

3 files changed, 178 insertions, 0 deletions

diff --git a/man/README.md b/man/README.md
new file mode 100644
index 0000000..b16e522
--- /dev/null
+++ b/man/README.md
@@ -0,0 +1,7 @@
+The beginning of an incomplete and potentially abandoned guide can be found
+here: https://gist.github.com/liam4/12d2881811b9adbc01ecc50a0da495c1
+
+It was never added to the man page because of its inconvenience; though it is
+possibly a useful guide for new (and clueless) users, its length and nature of
+a walkthrough instead of as examples simply made it not be fitting for a man
+page.
diff --git a/man/http-music.1 b/man/http-music.1
new file mode 100644
index 0000000..4a7e824
--- /dev/null
+++ b/man/http-music.1
@@ -0,0 +1,170 @@
+.TH HTTP-MUSIC 1
+
+
+
+.SH NAME
+http-music - play music through the internet
+
+
+
+.SH SYNOPSIS
+.B http-music
+[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 (\fBplay\fR (SoX) and \fBavconv\fR).
+
+
+
+.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 \-\-downloader " \fIdownloaderType\fR"
+Sets the downloader type used for actually retrieving track files.
+The default is \fBhttp\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 " \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 playlist.json (in the same directory as \fBhttp-music\fR is being run in).
+
+.TP
+.BR \-\-picker " \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 '\-v 0.3'\fR.
+
+.TP
+.BR \-r ", " \-\-remove ", " \-x " \fIgroupPath\fR"
+Removes a group from the (active) playlist.
+
+.TP
+.BR \-\-debug\-list
+Prints the JSON representation of the (active) playlist.
+
+
+
+.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
+Play music from a playlist generated from local file system:
+
+.PP
+.nf
+.RS
+$ http-music --downloader local
+.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
diff --git a/package.json b/package.json
index e0f2cae..4ed3f41 100644
--- a/package.json
+++ b/package.json
@@ -12,6 +12,7 @@
     "http-music-crawl-http": "./src/crawl-http.js",
     "http-music-crawl-local": "./src/crawl-local.js"
   },
+  "man": "./man/http-music.1",
   "dependencies": {
     "cheerio": "^1.0.0-rc.1",
     "node-fetch": "^1.7.0",