Merge pull request #490 from baldurmen/manpages

Add man pages.

README.md

@@ -161,10 +161,11 @@ PyPI installable dependencies are listed in the [requirements.txt](https://githu
 
 ### Optional dependencies
 - [Pillow](https://pypi.org/project/Pillow/), for completely supporting the cover art feature (`embed` and `complete` option values won't work otherwise).
+- [docutils](https://pypi.org/project/docutils/), to build the man pages.
 
-This dependency isn't listed in the `requirements.txt`, to install it just issue the following command:
+These dependencies are not listed in the `requirements.txt`. To install them, just issue the following command:
 
-`pip3 install Pillow`
+`pip3 install Pillow docutils`
 
 ### Fetching the source code
 
@@ -197,6 +198,8 @@ is correct, while
 
 is not, because the `-d` argument applies to the `cd` command.
 
+A more complete set of usage instructions can be found in the `whipper` [man pages](https://github.com/whipper-team/whipper/blob/develop/man/README.md).
+
 ## Getting started
 
 The simplest way to get started making accurate rips is:

man/Makefile

@@ -0,0 +1,7 @@
+MAKEFLAGS += --silent
+
+build:
+	for manpage in *.rst; do rst2man --exit-status=2 --report=1 $${manpage} "$${manpage%%.*}".1 ; done
+
+clean:
+	rm *.1

man/README.md

@@ -0,0 +1,21 @@
+The man pages in this directory can be generated using the `rst2man` command
+line tool provided by the Python `docutils` project:
+
+    rst2man whipper.rst whipper.1
+
+Alternatively, you can also build all of the man pages in this directory at the
+same time by running (requires `make`):
+
+    make
+
+or this way (without make):
+
+   for manpage in *.rst; do rst2man --exit-status=2 --report=1 --debug ${manpage} "${manpage%%.*}".1 ; done
+
+The directory can be cleaned of generated man pages by running:
+
+    make clean
+
+or this way (without make):
+
+    rm *.1

man/whipper-accurip.rst

@@ -0,0 +1,33 @@
+===============
+whipper-accurip
+===============
+
+------------------------------
+Handle AccurateRip information
+------------------------------
+
+:Author: Louis-Philippe Véronneau
+:Date: 2020
+:Manual section: 1
+
+Synopsis
+========
+
+| whipper accurip **show** *<URL>*
+| whipper accurip **-h**
+
+Arguments
+=========
+
+| **show** *<URL>*  Show AccurateRip data for the given URL
+
+Options
+=======
+
+| **-h** | **--help**
+|     Show this help message and exit
+
+See Also
+========
+
+whipper(1)

man/whipper-cd-info.rst

@@ -0,0 +1,38 @@
+===============
+whipper-cd-info
+===============
+
+----------------------------------------------------
+Retrieve information about the currently inserted CD
+----------------------------------------------------
+
+:Author: Louis-Philippe Véronneau
+:Date: 2020
+:Manual section: 1
+
+Synopsis
+========
+
+| whipper cd info [**-R** *<RELEASE_ID>*] [**-p**] [**-c** *<COUNTRY>*]
+| whipper cd info **-h**
+
+Options
+=======
+
+| **-h** | **--help**
+|     Show this help message and exit
+
+| **-R** *<RELEASE_ID>* | **--release-id** *<RELEASE_ID>*
+|     MusicBrainz release id to match to (if there are multiple)
+
+| **-p** | **--prompt**
+|     Prompt if there are multiple matching releases
+
+| **-c** *<COUNTRY>* | **--country** *<COUNTRY>*
+|     Filter releases by country
+
+
+See Also
+========
+
+whipper(1), whipper-cd(1), whipper-cd-rip(1)

man/whipper-cd-rip.rst

@@ -0,0 +1,101 @@
+==============
+whipper-cd-rip
+==============
+
+---------
+Rips a CD
+---------
+
+:Author: Louis-Philippe Véronneau
+:Date: 2020
+:Manual section: 1
+
+Synopsis
+========
+
+| whipper cd info [**options**]
+| whipper cd info **-h**
+
+Options
+=======
+
+| **-h** | **--help**
+|     Show this help message and exit
+
+| **-R** *<RELEASE_ID>* | **--release-id** *<RELEASE_ID>*
+|     MusicBrainz release id to match to (if there are multiple)
+
+| **-p** | **--prompt**
+|     Prompt if there are multiple matching releases
+
+| **-c** *<COUNTRY>* | **--country** *<COUNTRY>*
+|     Filter releases by country
+
+| **-L** *<LOGGER<* | **--logger** *<LOGGER>*
+|     Logger to use
+
+| **-o** *<OFFSET>* | **--offset** *<OFFSET>*
+|     Sample read offset
+
+| **-x** | **--force-overread**
+|     Force overreading into the lead-out portion of the disc. Works only if
+|     the patched cdparanoia package is installed and the drive supports this
+|     feature
+
+| **-O** *<OUTPUT_DIRECTORY>* | **--output-directory** *<OUTPUT_DIRECTORY>*
+|     Output directory; will be included in file paths in log
+
+| **-W** *<WORKING_DIRECTORY>* | **--working-directory** *<WORKING_DIRECTORY>*
+|     Working directory; whipper will change to this directory and files will
+|     be created relative to it when not absolute
+
+| **--track-template** *<TRACK_TEMPLATE>*
+|     Template for track file naming
+
+| **--disc-template** *<DISC_TEMPLATE>*
+|     Template for disc file naming
+
+| **-U** | **--unknown**
+|     whether to continue ripping if the CD is unknown
+
+| **--cdr**
+|     whether to continue ripping if the disc is a CD-R
+
+Template schemes
+================
+
+| Tracks are named according to the track template, filling in the variables
+| and adding the file extension. Variables exclusive to the track template are:
+
+|
+
+| - %t: track number
+| - %a: track artist
+| - %n: track title
+| - %s: track sort name
+
+| Disc files (.cue, .log, .m3u) are named according to the disc template,
+| filling in the variables and adding the file extension. Variables for both
+| disc and track template are:
+
+|
+
+| - %A: release artist
+| - %S: release sort name
+| - %d: disc title
+| - %y: release year
+| - %r: release type, lowercase
+| - %R: release type, normal case
+| - %x: audio extension, lowercase
+| - %X: audio extension, uppercase
+
+| Paths to track files referenced in .cue and .m3u files will be made
+| relative to the directory of the disc files.
+
+| All files will be created relative to the given output directory.
+| Log files will log the path to tracks relative to this directory
+
+See Also
+========
+
+whipper(1), whipper-cd(1), whipper-cd-info(1)

man/whipper-cd.rst

@@ -0,0 +1,39 @@
+==========
+whipper-cd
+==========
+
+----------------------------------
+Display and rip CD-DA and metadata
+----------------------------------
+
+:Author: Louis-Philippe Véronneau
+:Date: 2020
+:Manual section: 1
+
+Synopsis
+========
+
+| whipper cd **-d** *<DEVICE>* [**subcommand**]
+| whipper cd **-h**
+
+Subcommands
+===========
+
+| **info**  Retrieve information about the currently inserted CD
+| **rip**   Rip the CD
+
+| For more details on these subcommands, see their respective man pages.
+
+Options
+=======
+
+| **-h** | **--help**
+|     Show this help message and exit
+
+| **-d** *<DEVICE>* | **--device** *<DEVICE>*
+|     Path to the CD-DA device
+
+See Also
+========
+
+whipper(1), whipper-cd-info(1), whipper-cd-rip(1)

man/whipper-drive-analyze.rst

@@ -0,0 +1,31 @@
+=====================
+whipper-drive-analyze
+=====================
+
+--------------------------------------------------------------------
+Determine whether cdparanoia can defeat the audio cache of the drive
+--------------------------------------------------------------------
+
+:Author: Louis-Philippe Véronneau
+:Date: 2020
+:Manual section: 1
+
+Synopsis
+========
+
+| whipper drive analyze [**-d** *<DEVICE>*]
+| whipper drive analyze **-h**
+
+Options
+=======
+
+| **-h** | **--help**
+|     Show this help message and exit
+
+| **-d** *<DEVICE>* | **--device** *<DEVICE>*
+|     Path to the CD-DA device
+
+See Also
+========
+
+whipper(1), whipper-drive(1), whipper-drive-list(1)

man/whipper-drive-list.rst

@@ -0,0 +1,27 @@
+=====================
+whipper-drive-analyze
+=====================
+
+---------------------------
+List available CD-DA drives
+---------------------------
+
+:Author: Louis-Philippe Véronneau
+:Date: 2020
+:Manual section: 1
+
+Synopsis
+========
+
+| whipper drive list [**-h**]
+
+Options
+=======
+
+| **-h** | **--help**
+|     Show this help message and exit
+
+See Also
+========
+
+whipper(1), whipper-drive(1), whipper-drive-analyze(1)

man/whipper-drive.rst

@@ -0,0 +1,36 @@
+=============
+whipper-drive
+=============
+
+---------------
+Drive utilities
+---------------
+
+:Author: Louis-Philippe Véronneau
+:Date: 2020
+:Manual section: 1
+
+Synopsis
+========
+
+| whipper drive [**subcommand**]
+| whipper drive **-h**
+
+Subcommands
+===========
+
+| **analyze**  Analyze caching behaviour of drive
+| **list**     List drives
+
+| For more details on these subcommands, see their respective man pages.
+
+Options
+=======
+
+| **-h** | **--help**
+|     Show this help message and exit
+
+See Also
+========
+
+whipper(1), whipper-drive-analyze(1), whipper-drive-list(1)

man/whipper-image-verify.rst

@@ -0,0 +1,33 @@
+====================
+whipper-image-verify
+====================
+
+-----------------------------------------------------------------------------
+Verifies the image from the given .cue files against the AccurateRip database
+-----------------------------------------------------------------------------
+
+:Author: Louis-Philippe Véronneau
+:Date: 2020
+:Manual section: 1
+
+Synopsis
+========
+
+| whipper image verify *<CUEFILE>*
+| whipper image verify **-h**
+
+Options
+=======
+
+| **-h** | **--help**
+|     Show this help message and exit
+
+Arguments
+=========
+
+| *<CUEFILE>*  CUE file to load rip image from
+
+See Also
+========
+
+whipper(1), whipper-image(1)