USEPIPES information added to the abcde FAQ doc

Edits also to abcde man page and altered reference in abcde
itself.

diff --git a/FAQ b/FAQ
index 7c346bf..4b14f7f 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -387,7 +387,65 @@ A. Faac uses mp4v2 to create aac files in an m4a or mp4 container. Some
    support and then appropriately  places the audio either in .m4a or .aac. 
    Note that tagging is not possible with mpeg-2/ADTS streams in .aac.
 
-5. MISC PROBLEMS
+5. USEPIPES
+   ========
+Q. What is/are 'USEPIPES'??
+A. This is a slightly different method of ripping and encoding with abcde
+   utilising Unix pipes. Using this method a program sends as output what
+   another programs expects as input without writing the information to the
+   hard disk. For it to work with abcde, a ripper must send the data of the
+   CD tracks which are ripped to the 'standard output', while sending other
+   information and error messages to 'standard error' so that the encoder
+   does not get confused. The encoder program needs to be able to encode the
+   information send to it by reading from the standard input (which is what
+   the ripper sends to the standard output).
+   Usually Unix/Linux programs deal with the standard input/output by using
+   the special file name '-', as in the following example:
+
+   cdripper -o - | audioencoder -i - -o file.ext
+
+   The 'cdripper' program uses the flag '-o' to identify the file it will
+   output the data to. For the 'audioencoder' program to be able to read
+   the output through a Unix pipe (the '|' symbol), the output needs to be
+   sent to the standard output using the '-' special filename. Once the
+   output has been piped to 'audioencoder' we use the same special filename
+   to read the information as input with the '-i' flag and output it to
+   'file.ext' with the '-o' flag.
+
+Q. How do I use USEPIPES with abcde?
+A. You can run USEPIPES in either of two ways:
+
+     1. Add USEPIPES=y to your ~/.abcde.conf file
+     2. Use the commandline option abcde -P
+
+Q. Do all rippers and encoders work with USEPIPES?
+A. No :). Keep in mind that every ripper and encoder differs from in each
+   other in the way they interact with pipes and not all rippers and encoders
+   will use or understand the '-o' and '-' options.
+
+Q. Can I add a ripper or encoder which is not supported?
+A. Sure! If you plan to use a ripper or encoder which is not supported you
+   need to know how to use the ripper/encoder. For example, cdparanoia just
+   uses '-' as the output filename and works. The program used to decode
+   FLAC files (yes, abcde supports 'ripping' from a FLAC file :) uses '-c'.
+   To add support for a ripper called 'cdripper' which uses the '-' special
+   flag for outputting to the standard output, you need to open the config
+   file (either /etc/abcde.conf or ~/.abcde.conf) and add the line:
+
+     PIPERIPPER_cdripper="-"
+   
+   For an encoder called 'audioencoder' which uses '--stdin' to read the pipe
+  input, you need to add:
+
+     PIPE_audioencoder="--stdin"
+
+  Of course, you should try your configuration and report it to the abcde
+  devleopers so that it can be included in future versions of abcde. If
+  you are familiar with POSIX shell programing, please open "abcde" and
+  take a look at the lines below the one marked with "###USEPIPESSUPPORT###",
+  the required syntax is pretty obvious.
+
+6. MISC PROBLEMS
    =============
 
 Q. What happened with normalize?

diff --git a/USEPIPES b/USEPIPES
deleted file mode 100644 (file)
index ef2a40f..0000000
--- a/USEPIPES
+++ /dev/null
@@ -1,57 +0,0 @@
-An approach for reading and encoding taken in abcde is the use of Unix pipes.
-
-By this way, a program sends as output what another programs expects as input,
-without writing the information in the hard disk.
-
-For it to work with abcde, a ripper must send the data of the CD tracks which
-are ripped to the standard output, while sending the information and error
-messages to another "stream", so that the encoder does not get confused. This
-second stream is called "standard error".
-
-The encoder program needs to be able to encode the information send to it by
-reading from the standard input (which is what the ripper sends to the standard
-output).
-
-Usually Unix/Linux programs deal with the standard input/output by using the
-special file name "-", as in the following example:
-
-cdripper -o - | audioencoder -i - -o file.ext
-
-The "cdripper" program uses the flag "-o" to identify the file it will output
-the data to. For the "audioencoder" program to be able to read the output
-through a Unix pipe (the "|" symbol), the output needs to be sent to the
-standard output using the "-" special filename.
-
-Once the output has been pipped to "audioencoder" we use the same special
-filename to read the information as input with the "-i" flag and output it to
-"file.ext" with the "-o" flag.
-
-Keep in mind that the example above is only that, an example, and every ripper
-and encoder differs from in each other in the way they interact with pipes.
-
-For one reason, not all the rippers and encoders are supported by abcde: the
-author (or the users) have not included support for them.
-
-If you plan to use a ripper or encoder which is not supported, you need to know
-how to use the ripper/encoder. For example, cdparanoia just uses "-" as the
-output filename and works. The program used to decode FLAC files (yes, abcde
-supports "ripping" from a FLAC file :) uses "-c ".
-
-To add support for a ripper called "cdripper" which uses the "-" special flag
-for outputting to the standard output, you need to open the config file (either
-/etc/abcde.conf or ~/.abcde.conf) and add the line:
-
-PIPERIPPER_cdripper="-"
-
-For an encoder called "audioencoder" which uses "--stdin" to read the pipe
-input, you need to add:
-
-PIPE_audioencoder="--stdin"
-
-Of course, you should try your configuration and report it so that it can be
-included in future versions of abcde.
-
-If you are familiar with POSIX shell programing, please open "abcde" and take a
-look at the lines below the one marked with "###USEPIPESSUPPORT###".
-
-Thanks for your time!

diff --git a/abcde b/abcde
index 4010105..93bb93d 100755 (executable)
--- a/abcde
+++ b/abcde
@@ -4373,16 +4373,14 @@ if [ "$USEPIPES" = "y" ]; then
        if [ "$( eval echo "\$$PIPERIPPERSVARCHECK" )" = "$" ] || \
           [ "$( eval echo "\$$PIPERIPPERSVARCHECK" )" = "" ] ; then
                log error "no support for pipes with given ripper"
-               log error "read the USEPIPES file from the source tarball to get help."
-               log error "On a Debian system, it is under /usr/share/doc/abcde/USEPIPES.gz"
+               log error "read the FAQ file from the source tarball to get help."
                exit 1;
        fi
        decho "PIPEENCODERSVARCHECK: $( eval echo "\$$PIPEENCODERSVARCHECK" )"
        if [ "$( eval echo "\$$PIPEENCODERSVARCHECK" )" = "$" ] || \
           [ "$( eval echo "\$$PIPEENCODERSVARCHECK" )" = "" ] ; then
                log error "no support for pipes with given encoder"
-               log error "read the USEPIPES file from the source tarball to help"
-               log error "on a Debian system, read /usr/share/doc/abcde/USEPIPES.gz"
+               log error "read the FAQ file from the source tarball to get help"
                exit 1;
        fi
 fi

diff --git a/abcde.1 b/abcde.1
index fa270c2..cfa2923 100644 (file)
--- a/abcde.1
+++ b/abcde.1
@@ -156,8 +156,9 @@ them with a colon. The options must be escaped with double-quotes.
 Pads track numbers with 0\'s.
 .TP
 .B \-P
-Use Unix PIPES to read and encode in one step. It disables multiple encodings,
-since the WAV audio file is never stored in the disc.
+Use Unix PIPES to read and encode in one step (USEPIPES). This disables multiple
+encodings, since the WAV audio file is never stored in the disc. For more detail
+on this option see the FAQ document in the source tarball.
 .TP
 .B \-r [hosts...]
 Remote encode on this comma-delimited list of machines using \fBdistmp3\fR. See