add the RST source for the man/html pages

1 files changed, 113 insertions, 0 deletions

diff --git a/miragextract.rst b/miragextract.rst
new file mode 100644
index 0000000..5a097f8
--- /dev/null
+++ b/miragextract.rst
@@ -0,0 +1,113 @@
+.. RST source for miragextract(1) man page. Convert with:
+..   rst2man.py miragextract.rst > miragextract.1
+.. rst2man.py comes from the SBo development/docutils package.
+
+.. note to self: don't forget to check the generated man and html pages
+.. into git since we don't want to require our users to have rst2man.py.
+
+.. |version| replace:: 0.0.1
+.. |date| date::
+
+============
+miragextract
+============
+
+--------------------------------------------
+extract audio and data tracks from CD images
+--------------------------------------------
+
+:Manual section: 1
+:Manual group: Urchlay
+:Date: |date|
+:Version: |version|
+
+SYNOPSIS
+========
+
+miragextract [**-l**] [**-s**] [**-t** track] [**-b** base] [**-f** fmt] [**-q** quality ] **image-file**
+
+DESCRIPTION
+===========
+
+Extracts data and audio tracks from any CD image supported by libmirage.
+Data tracks are written as-is, and audio tracks can be written as-is or
+converted to wav, flac, or ogg/vorbis (via libsndfile).
+
+OPTIONS
+=======
+
+--help
+            Print short usage string.
+
+-l     Lists the tracks in the image without extracting them.
+
+-s     Swaps bytes in audio tracks. Use this if your audio files sound
+       like white noise or gibberish.
+
+-t     Takes a track number (1-99), and extracts only that one track.
+       Default behaviour is to extract all tracks.
+
+-b     Sets the base filename for the output files. Default is 'track'.
+
+-f     Sets the format and filename extension for the output files.
+       Choices are 'wav', 'ogg', 'flac', 'cdda' (raw CD audio). Default is 'wav'.
+
+-q     Quality setting for .ogg and .flac output files. Integer from 0
+       to 10. Default is 7.
+
+NOTES
+=====
+
+Image-file is e.g. a .cue, .ccd, .nrg, .mds, or anything else supported
+by libmirage. See the README for your version of libmirage for details.
+
+Output audio files are named track01.wav, track02.wav, etc by default. The
+'track' part of the name can be set with -b, and the extension will
+match the encoding set with -f. Note that mp3 is NOT a valid -f option.
+If you need mp3, extract to .wav and then use a tool like lame or ffmpeg
+to convert to mp3.
+
+Output data tracks will be named to end in '.iso', which is usually
+correct. Future versions of this program might be smart enough to
+detect e.g. Macintosh DMG files and name them appropriately (for now,
+just rename them if you need to).
+
+Images with multiple sessions should be supported, but have not been
+tested. Track numbering just continues, so a disc with 2 sessions of
+8 files each will have tracks numbered 1 to 16 as far as the -t option
+and the output filenames are concerned.
+
+When extracting raw CD audio tracks, you can test them by listening to
+them with the *play* command from *sox*. Try::
+
+  play -x -t cdda track01.cdda
+
+...possibly without the -x option if you're on a big-endian platform.
+
+.. other sections we might want, uncomment as needed.
+
+.. FILES
+.. =====
+
+.. ENVIRONMENT
+.. ===========
+
+.. EXIT STATUS
+.. ===========
+
+.. BUGS
+.. ====
+
+.. EXAMPLES
+.. ========
+
+AUTHORS
+=======
+
+miragextract was written by B. Watson <yalhcru@gmail.com> and
+released under the WTFPL: Do WTF you want with this.
+
+SEE ALSO
+========
+
+TODO: fill in