Many bug fixes went into this update:
[abcde.git] / abcde.1
diff --git a/abcde.1 b/abcde.1
index 634e914..61b88b3 100644 (file)
--- a/abcde.1
+++ b/abcde.1
@@ -1,6 +1,6 @@
 .TH ABCDE 1
 .SH NAME
-abcde \- Grab an entire CD and compress it to Ogg/Vorbis, MP3, FLAC or Ogg/Speex format.
+abcde \- Grab an entire CD and compress it to Ogg/Vorbis, MP3, FLAC, Ogg/Speex and/or MPP/MP+(Musepack) format.
 .SH SYNOPSIS
 .B abcde
 .I [options] [tracks]
@@ -10,7 +10,7 @@ tagging or commenting it, is very involved.
 .BR abcde
 is designed to automate this. It will take an entire CD and convert it into
 a compressed audio format - Ogg/Vorbis, MPEG Audio Layer III, Free Lossless
-Audio Codec (FLAC) or Ogg/Speex. With one command, it will:
+Audio Codec (FLAC), Ogg/Speex or MPP/MP+(Musepack). With one command, it will:
 .TP
 .B *
 Do a CDDB query over the Internet to look up your CD or use a locally stored CDDB entry
@@ -19,7 +19,7 @@ Do a CDDB query over the Internet to look up your CD or use a locally stored CDD
 Grab a track from your CD
 .TP
 .B *
-Compress it to Ogg/Vorbis, MP3, FLAC and/or Ogg/Speex format
+Compress it to Ogg/Vorbis, MP3, FLAC, Ogg/Speex and/or MPP/MP+(Musepack) format
 .TP
 .B *
 Comment or ID3 tag it
@@ -92,7 +92,7 @@ Create DOS-style playlists, modifying the resulting one by adding CRLF line
 endings. Some hardware players insist on having those to work.
 .TP
 .B \-o [filetype]
-Select output type. Can be "ogg", "mp3", "flac" or "spx". Specify a 
+Select output type. Can be "ogg", "mp3", "flac", "spx" or "mpc". Specify a 
 comma-delimited list of output types to obtain all specified types. See 
 the OUTPUTTYPE configuration variable.
 .TP
@@ -103,6 +103,10 @@ Pads track numbers with 0\'s.
 Remote encode on this comma-delimited list of machines using distmp3. See
 the REMOTEHOSTS configuration variable.
 .TP
+.B \-s [number]
+Start the numbering of the tracks at a given number. It only affects the
+filenames and the playlist. Internal (tag) numbering remains the same.
+.TP
 .B \-S [speed]
 Set the speed of the CD drive. Needs CDSPEED and CDSPEEDOPTS set properly
 and both the program and device must support the capability.
@@ -127,11 +131,10 @@ will process the entire CD. Accepts ranges of track numbers -
 "abcde 1-5 7 9" will process tracks 1, 2, 3, 4, 5, 7, and 9.
 .SH OUTPUT
 Each track is, by default, placed in a separate file named after the track
-in a subdirectory named after the artist under the current directory. Each
-file is given an extension identifying its compression format, '.ogg',
-\'.mp3', '.flac', or '.spx'.
+in a subdirectory named after the artist under the current directory. 
 This can be modified using the OUTPUTFORMAT and VAOUTPUTFORMAT
-variables in your abcde.conf.
+variables in your abcde.conf. Each file is given an extension identifying 
+its compression format, '.ogg', '.mp3', '.flac', '.spx', or '.mpc'.
 .SH CONFIGURATION
 abcde sources two configuration files on startup - /etc/abcde.conf and
 $HOME/.abcde.conf, in that order. 
@@ -139,7 +142,6 @@ $HOME/.abcde.conf, in that order.
 The configuration variables have to be set as follows:
 .TP
 .B VARIABLE=value
-.TP
 Except when "value" needs to be quoted or otherwise interpreted. If other 
 variables within "value" are to be expanded upon reading the configuration 
 file, then double quotes should be used. If they are only supposed to be 
@@ -172,6 +174,10 @@ Specifies the style of encoder to use for the FLAC encoder. At this point only
 Specifies the style of encoder to use for Speex encoder. At this point only
 \'speexenc\' is available for Ogg/Speex encoding.
 .TP
+.B MPPENCODERSYNTAX
+Specifies the style of encoder to use for MPP/MP+ (Musepack) encoder. At this
+point we only have \'mppenc\' available, from corecodecs.org.
+.TP
 .B NORMALIZERSYNTAX
 Specifies the style of normalizer to use.  Valid options are \'default\'
 and \'normalize'\ (and both run \'normalize\'), since we only support it, ATM.
@@ -204,25 +210,27 @@ to 700MB of temporary space for each session (although it is rare to use
 over 100MB for a machine that can encode music as fast as it can read it).
 .TP
 .B OUTPUTFORMAT
-Specifies the format for completed Ogg/Vorbis, MP3, FLAC or Ogg/Speex filenames.
+Specifies the format for completed Ogg/Vorbis, MP3, FLAC, Ogg/Speex or MPP/MP+ 
+(Musepack) filenames.
 Variables are included
 using standard shell syntax. Allowed variables are GENRE, ALBUMFILE, ARTISTFILE,
-TRACKFILE, and TRACKNUM. Default is
-\'${ARTISTFILE}/${TRACKFILE}.${OUTPUTTYPE}\'.
+TRACKFILE, TRACKNUM, and YEAR. Default is
+\'${ARTISTFILE}-${ALBUMFILE}/${TRACKNUM}-${TRACKFILE}\'.
 Make sure to use single quotes around this variable. TRACKNUM is
-automatically zero-padded.
+automatically zero-padded, when the number of encoded tracks is higher than
+9. When lower, you can force with '-p' in the command line.
 .TP
 .B OUTPUTTYPE
 Specifies the encoding format to output, as well as the default extension and
 encoder. Defaults to "ogg". Valid settings are "ogg" (Ogg/Vorbis), "mp3"
-(MPEG-1 Audio Layer 3), "flac" (Free Lossless Audio Codec) and "spx" 
-(Ogg/Speex). Values like "ogg,mp3" encode the tracks in both Ogg/Vorbis and MP3
-formats.
+(MPEG-1 Audio Layer III), "flac" (Free Lossless Audio Codec), "spx" (Ogg/Speex)
+and "mpc" (MPP/MP+ (Musepack)). Values like "ogg,mp3" encode the tracks in 
+both Ogg/Vorbis and MP3 formats.
 .P
 For each value in OUTPUTTYPE, abcde expands a different process for encoding,
 tagging and moving, so you can use the format placeholder, OUTPUT, to create 
 different subdirectories to hold the different types. The variable OUTPUT will
-be 'ogg', 'mp3', 'flac' and/or 'spx', depending on the OUTPUTTYPE you define.
+be 'ogg', 'mp3', 'flac', 'spx' and/or 'mpc', depending on the OUTPUTTYPE you define.
 For example
 .P
 OUTPUTFORMAT='${OUTPUT}/${ARTISTFILE}/${ALBUMFILE}/${TRACKNUM}._${TRACKFILE}'
@@ -234,16 +242,17 @@ OUTPUTFORMAT is set to.
 .B PATHNAMES
 The following configuration file options specify the pathnames of their
 respective utilities: LAME, GOGO, BLADEENC, L3ENC, XINGMP3ENC, MP3ENC,
-VORBIZE, OGGENC, FLAC, SPEECENC, ID3, ID3V2, CDPARANOIA, CDDA2WAV, HTTPGET,
-CDDISCID, CDDBTOOL, EJECT, NORMALIZE, DISTMP3, VORBISCOMMENT, and CDSPEED.
+VORBIZE, OGGENC, FLAC, SPEECENC, MPPENC, ID3, ID3V2, CDPARANOIA, CDDA2WAV, 
+HTTPGET, CDDISCID, CDDBTOOL, EJECT, NORMALIZE, DISTMP3, VORBISCOMMENT, and 
+CDSPEED.
 .TP
 .B COMMAND-LINE OPTIONS
 If you wish to specify command-line options to any of the programs abcde
 uses, set the following configuration file options: LAMEOPTS, GOGOOPTS,
 BLADEENCOPTS, L3ENCOPTS, XINGMP3ENCOPTS, MP3ENCOPTS, VORBIZEOPTS,
-OGGENCOPTS, FLACOPTS, SPEEXOPTS, ID3OPTS, ID3V2OPTS, CDPARANOIAOPTS, 
-CDDA2WAVOPTS, HTTPGETOPTS, CDDBTOOLOPTS, EJECTOPTS, DISTMP3OPTS,
-NORMALIZEOPTS, CDSPEEDOPTS, and CDSPEEDVALUE.
+OGGENCOPTS, FLACOPTS, SPEEXENCOPTS, MPPENCOPTS, ID3OPTS, ID3V2OPTS, 
+CDPARANOIAOPTS, CDDA2WAVOPTS, HTTPGETOPTS, CDDBTOOLOPTS, EJECTOPTS, 
+DISTMP3OPTS, NORMALIZEOPTS, CDSPEEDOPTS, and CDSPEEDVALUE.
 .TP
 .B CDROM
 If set, it points to the CD-Rom device which has to be used for audio
@@ -287,6 +296,10 @@ Make sure to use single quotes around this variable.
 Specifies a prefix for filenames within a playlist. Useful for http
 playlists, etc.
 .TP
+.B DOSPLAYLIST
+If set, the resulting playlist will have CR-LF line endings, needed by some
+hardware-based players.
+.TP
 .B COMMENT
 Specifies a comment to embed in the ID3 or Ogg comment field of each
 finished track. Can be up to 28 characters long. Supports the same
@@ -315,7 +328,7 @@ after all tracks have been read.
 abcde requires the following backend tools to work:
 .TP
 .B *
-An Ogg/Vorbis, MP3, FLAC or Ogg/Speex encoder (oggenc, vorbize, lame, gogo, bladeenc, l3enc, mp3enc, flac, speexenc)
+An Ogg/Vorbis, MP3, FLAC, Ogg/Speex or MPP/MP+(Musepack) encoder (oggenc, vorbize, lame, gogo, bladeenc, l3enc, mp3enc, flac, speexenc, mppenc)
 .TP
 .B *
 An audio CD reading utility (cdparanoia, cdda2wav, dagrab)
@@ -343,6 +356,7 @@ An HTTP retrieval program: wget, fetch (FreeBSD) or curl (Mac OS X, among others
 .BR vorbize (1),
 .BR flac (1),
 .BR speexenc(1),
+.BR mppenc(1),
 .BR id3 (1),
 .BR wget (1),
 .BR fetch (1),
@@ -350,6 +364,6 @@ An HTTP retrieval program: wget, fetch (FreeBSD) or curl (Mac OS X, among others
 .BR distmp3 (1),
 .BR distmp3host (1),
 .BR curl(1)
-.SH AUTHOR
+.SH AUTHORS
 Robert Woodcock <rcw@debian.org>
 Jesus Climent <jesus.climent@hispalinux.es>