Work on documentation. cd-paranoia name is now properly substituted.

Offset option described better.
2005-01-16 13:08:25 +00:00
parent 526748e809
commit 45500e1e73
6 changed files with 109 additions and 60 deletions
--- a/configure.ac
+++ b/configure.ac
@@ -19,7 +19,7 @@ define(RELEASE_NUM, 72)
 define(CDIO_VERSION_STR, 0.$1cvs)

 AC_PREREQ(2.52)
-AC_REVISION([$Id: configure.ac,v 1.127 2005/01/11 04:00:26 rocky Exp $])dnl
+AC_REVISION([$Id: configure.ac,v 1.128 2005/01/16 13:08:25 rocky Exp $])dnl
 AC_INIT(libcdio, CDIO_VERSION_STR(RELEASE_NUM))
 AC_CONFIG_SRCDIR(src/cd-info.c)
 AM_INIT_AUTOMAKE
@@ -534,6 +534,8 @@ AC_CONFIG_FILES([ \
       lib/paranoia/Makefile \
       src/cd-paranoia/Makefile \
       src/cd-paranoia/usage.txt \
+       src/cd-paranoia/doc/cd-paranoia.1 \
+       src/cd-paranoia/doc/cd-paranoia.1.jp \
       src/Makefile \
       test/check_nrg.sh \
       test/check_cue.sh \
--- a/src/cd-paranoia/Makefile.am
+++ b/src/cd-paranoia/Makefile.am
@@ -1,4 +1,4 @@
-#   $Id: Makefile.am,v 1.11 2005/01/16 11:47:45 rocky Exp $
+#   $Id: Makefile.am,v 1.12 2005/01/16 13:08:25 rocky Exp $
 #
 #    Copyright (C) 2004, 2005 Rocky Bernstein <rocky@panix.com>
 #    Copyright (C) 1998 Monty xiphmont@mit.edu
@@ -27,8 +27,10 @@ endif
 man_MANS = doc/cd-paranoia.1 doc/cd-paranoia.1.jp

 EXTRA_DIST = $(man_MANS) getopt.c getopt1.c \
-	      usage.txt.in pod2c.pl \
-	      doc/FAQ.txt doc/overlapdef.txt
+	     usage.txt.in pod2c.pl \
+             doc/FAQ.txt doc/overlapdef.txt \
+             doc/cd-paranoia.1.in doc/cd-paranoia.1.jp.in
+

 noinst_HEADERS = getopt.h header.h report.h 

--- a/src/cd-paranoia/cd-paranoia.c
+++ b/src/cd-paranoia/cd-paranoia.c
@@ -20,7 +20,6 @@
 * See ChangeLog for recent changes.
 *
 * last changes:
- *   09.04.04 - conversion to use libcdio. 
 *   22.01.98 - first version
 *   15.02.98 - alpha 2: juggled two includes from interface/low_interface.h
 *                       that move contents in Linux 2.1
@@ -44,6 +43,9 @@
 *                       AIFF support (in addition to AIFC)
 *                       Path parsing fixes
 *   Changes are becoming TNTC. Will resume the log at beta.
+ *
+ *   09.04.04 - conversion to use libcdio. See top-level Changelog for
+ *              libcdio history.
 */

 #ifdef HAVE_CONFIG_H
@@ -867,10 +869,23 @@ main(int argc,char *argv[])

  if (query_only) exit(0);

-  /* bias the disc.  A hack.  Of course. */
-  /* we may need to read before or past user area; this is never
-     default, and we do it because the [allegedly informed] user told
-     us to */
+  /* bias the disc.  A hack.  Of course. this is never the default. */
+  /* 
+     Some CD-ROM/CD-R drives will add an offset to the position on
+     reading audio data. This is usually around 500-700 audio samples
+     (ca. 1/75 second) on reading. So when this program queries a
+     specific sector, it might not receive exactly that sector, but
+     shifted by some amount.
+
+     Note that if ripping includes the end of the CD, this will this
+     cause this program to attempt to read partial sectors before or
+     past the known user data area of the disc, probably causing read
+     errors on most drives and possibly even hard lockups on some
+     buggy hardware. 
+
+     [Note to libcdio driver hackers: make sure all CD-drivers don't
+     try to read outside of the stated disc boundaries.]
+  */
  if(sample_offset){
    toc_offset+=sample_offset/588;
    sample_offset%=588;
--- a/src/cd-paranoia/doc/cd-paranoia.1.in
+++ b/src/cd-paranoia/doc/cd-paranoia.1.in
@@ -1,22 +1,22 @@
-.TH CD-PARANOIA 1 "version III release alpha 9.8 libcdio"
+.TH @CDPARANOIA_NAME@ 1 "version III release alpha 9.8 libcdio"
 .SH NAME
-cdparanoia 9.8 (Paranoia release III) \- an audio CD reading utility which includes extra data verification features
+cdparanoia 9.8 (Paranoia release III libcdio) \- an audio CD reading utility which includes extra data verification features
 .SH SYNOPSIS
 .B cdparanoia
 .RB [ options ]
 .B span 
 .RB [ outfile ]
 .SH DESCRIPTION
-.B cd-paranoia
+.B @CDPARANOIA_NAME@
 retrieves audio tracks from CDDA capable CDROM drives.  The data can
 be saved to a file or directed to standard output in WAV, AIFF, AIFF-C
 or raw format.  Most ATAPI, SCSI and several proprietary CDROM drive
 makes are supported;
-.B cd-paranoia
+.B @CDPARANOIA_NAME@
 can determine if the target drive is CDDA capable.
 .P
 In addition to simple reading, 
-.B cd-paranoia
+.B @CDPARANOIA_NAME@
 adds extra-robust data verification, synchronization, error handling
 and scratch reconstruction capability.
 .SH OPTIONS
@@ -50,7 +50,7 @@ Forces a complete search for a cdrom drive, even if the /dev/cdrom link exists.
 .TP
 .B \-h --help
 Print a brief synopsis of 
-.B cd-paranoia 
+.B @CDPARANOIA_NAME@ 
 usage and options.

 .TP
@@ -87,20 +87,20 @@ always in MSB first byte order).
 .TP
 .BI "\-B --batch "

-Cdda2wav-style batch output flag; cd-paranoia will split the output
+Cdda2wav-style batch output flag; @CDPARANOIA_NAME@ will split the output
 into multiple files at track boundaries.  Output file names are
 prepended with 'track#.'

 .TP
 .B \-c --force-cdrom-little-endian
 Some CDROM drives misreport their endianness (or do not report it at
-all); it's possible that cd-paranoia will guess wrong.  Use
+all); it's possible that @CDPARANOIA_NAME@ will guess wrong.  Use
 .B \-c
-to force cd-paranoia to treat the drive as a little endian device.
+to force @CDPARANOIA_NAME@ to treat the drive as a little endian device.

 .TP
 .B \-C --force-cdrom-big-endian
-As above but force cd-paranoia to treat the drive as a big endian device.
+As above but force @CDPARANOIA_NAME@ to treat the drive as a big endian device.

 .TP
 .BI "\-n --force-default-sectors " n
@@ -149,27 +149,33 @@ beginning offset values in the TOC, but then treat the beginning of
 track 1 index 1 as sector 0 for all read operations.  This results in
 every track seeming to start too late (losing a bit of the beginning
 and catching a bit of the next track).
-.B \-T
-accounts for this behavior.  Note that this option will cause
-cd-paranoia to attempt to read sectors before or past the known user
+\-T accounts for this behavior.  Note that this option will cause
+@CDPARANOIA_NAME@ to attempt to read sectors before or past the known user
 data area of the disc, resulting in read errors at disc edges on most
 drives and possibly even hard lockups on some buggy hardware.

 .TP
 .BI "\-O --sample-offset " number
+Some CD-ROM/CD-R drives will add an offset to the position on reading
+audio data. This is usually around 500-700 audio samples (ca. 1/75
+second) on reading. So when @CDPARANOIA_NAME@ queries a specific
+sector, it might not receive exactly that sector, but shifted by some
+amount.
+.P
 Use this option to force the entire disc to shift sample position
 output by the given amount; This can be used to shift track boundaries
-for the whole disc manually on sample granularity. Note that this will
-cause cd-paranoia to attempt to read partial sectors before or past the
-known user data area of the disc, probably causing read errors on most
-drives and possibly even hard lockups on some buggy hardware.
-
+for the whole disc manually on sample granularity. Note that if you
+are ripping something including the ending of the CD (e.g. the entire
+disk), this option will cause @CDPARANOIA_NAME@ to attempt to read
+partial sectors before or past the known user data area, probably
+causing read errors on most drives and possibly even hard lockups on
+some buggy hardware.

 .TP
 .B \-Z --disable-paranoia
 Disable 
 .B all
-data verification and correction features.  When using -Z, cd-paranoia
+data verification and correction features.  When using -Z, @CDPARANOIA_NAME@
 reads data exactly as would cdda2wav with an overlap setting of zero.
 This option implies that 
 .B \-Y
@@ -190,6 +196,18 @@ boundaries is performed. It can wedge if errors occur in the attempted overlap a
 .B \-X --abort-on-skip
 If the read skips due to imperfect data, a scratch, whatever, abort reading this track.  If output is to a file, delete the partially completed file.

+.TP
+.B \-x --test-flags mask
+Simulate CD-reading errors. This is used in regression testing, but
+other uses might be to see how well a CD-ROM performs under
+(simulated) CD degradation. mask specifies the artificial kinds of
+errors to introduced; "or"-ing values from the selection below will
+simulate the kind of specified failure.
+.P
+     0x10  - Simulate under-run reading
+.TP
+
+
 .SH OUTPUT SMILIES
 .TP
 .B
@@ -249,7 +267,7 @@ Unreported loss of streaming/other error in read
 .B
   !  
 Errors found after stage 1 correction; the drive is making the
-same error through multiple re-reads, and cd-paranoia is having trouble
+same error through multiple re-reads, and @CDPARANOIA_NAME@ is having trouble
 detecting them.
 .TP
 .B
@@ -311,25 +329,25 @@ A few examples, protected from the shell:
 .TP
 Query only with exhaustive search for a drive and full reporting of autosense:
 .P
-       cd-paranoia -vsQ
+       @CDPARANOIA_NAME@ -vsQ
 .TP
 Extract an entire disc, putting each track in a seperate file:
 .P
-       cd-paranoia -B 
+       @CDPARANOIA_NAME@ -B 
 .TP
 Extract from track 1, time 0:30.12 to 1:10.00:
 .P
-       cd-paranoia "1[:30.12]-1[1:10]"
+       @CDPARANOIA_NAME@ "1[:30.12]-1[1:10]"
 .TP
 Extract from the beginning of the disc up to track 3:
 .P
-       cd-paranoia -- "-3"
+       @CDPARANOIA_NAME@ -- "-3"
 .TP
 The "--" above is to distinguish "-3" from an option flag.
 .SH OUTPUT

 The output file argument is optional; if it is not specified,
-cd-paranoia will output samples to one of
+@CDPARANOIA_NAME@ will output samples to one of
 .BR cdda.wav ", " cdda.aifc ", or " cdda.raw
 depending on whether 
 .BR \-w ", " \-a ", " \-r " or " \-R " is used (" \-w 
@@ -338,9 +356,9 @@ is the implicit default).  The output file argument of
 specifies standard output; all data formats may be piped. 

 .SH ACKNOWLEDGEMENTS
-Cd-Paranoia sprang from and once drew heavily from the interface of
+@CDPARANOIA_NAME@ sprang from and once drew heavily from the interface of
 Heiko Eissfeldt's (heiko@colossus.escape.de) 'cdda2wav'
-package. Cd-Paranoia would not have happened without it.
+package. @CDPARANOIA_NAME@ would not have happened without it.
 .P
 Joerg Schilling has also contributed SCSI expertise through his
 generic SCSI transport library.
@@ -348,5 +366,10 @@ generic SCSI transport library.
 .SH AUTHOR
 Monty <monty@xiph.org>
 .P
-Cd-Paranoia's homepage may be found at:
+Cdparanoia's homepage may be found at:
 http://www.xiph.org/paranoia/
+.P
+Revised for use with libcdio by Rocky <rocky@panix.com>
+.P
+The libcdio homepage may be found at:
+http://www.gnu.org/software/libcdio
--- a/src/cd-paranoia/doc/cd-paranoia.1.jp.in
+++ b/src/cd-paranoia/doc/cd-paranoia.1.jp.in
@@ -1,26 +1,26 @@
-.TH CDPARANOIA 1
+.TH @CDPARANOIA_NAME@ 1
 .\" Translated Sun Aug 22 18:02:41 JST 1999
 .\"         by FUJIWARA Teruyoshi <fujiwara@linux.or.jp>
 .SH 名前
-cdparanoia (Paranoia release III) \- オーディオ CD 読み取りユーティリティ。特別なデータ照合機能を持つ。
+@CDPARANOIA_NAME@ (Paranoia release III libcdio) \- オーディオ CD 読み取りユーティリティ。特別なデータ照合機能を持つ。
 .SH 日付
 バージョンIII リリースα9.6 (17 Aug 1999)
 .SH 書式
-.B cdparanoia
+.B @CDPARANOIA_NAME@
 .RB [ options ]
 .B span 
 .RB [ outfile ]
 .SH 説明
-.B cdparanoia
+.B @CDPARANOIA_NAME@
 は CD-DA 機能を持つ CD-ROM ドライブからオーディオトラックを取り出しま
 す。このデータは WAV, AIFF, AIFF-C, raw 形式でファイルにセーブすること
 や、標準出力に送ることができます。ほとんどの ATAPI, SCSI, メーカー独自
 の CD-ROM ドライブがサポートされています。
-.B cdparanoia
+.B @CDPARANOIA_NAME@
 は対象のドライブが CD-DA 機能を持っているかどうかを判別できます。
 .P
 単純な読み取りだけでなく、
-.B cdparanoia
+.B @CDPARANOIA_NAME@
 は特別に頑健なデータ照合機能、同期機能、エラー処理機能、破損データの再
 構成機能を持っています。
 .SH オプション
@@ -54,7 +54,7 @@ CD-ROM

 .TP
 .B \-h --help
-.B cdparanoia 
+.B @CDPARANOIA_NAME@ 
 の使い方とオプションを簡単な説明を出力します。

 .TP
@@ -95,23 +95,23 @@ MSB first

 .TP
 .BI "\-B --batch "
-cdda2wav 形式のバッチ出力を行います。cdparanoia は出力をトラック境界で
+cdda2wav 形式のバッチ出力を行います。@CDPARANOIA_NAME@ は出力をトラック境界で
 複数ファイルに分割します。出力ファイルのファイル名の先頭部分は、'track(番号)' 
 となります。

 .TP
 .B \-c --force-cdrom-little-endian
 一部の CD-ROM は間違ったエンディアンを報告します(あるいはエンディアン
-に関する情報を全く報告しません)。そのため、cdparanoia がエンディアンを
+に関する情報を全く報告しません)。そのため、@CDPARANOIA_NAME@ がエンディアンを
 間違えることがあります。ドライブをリトルエンディアンのデバイスとして
-cdparanoia に扱わせるには、
+@CDPARANOIA_NAME@ に扱わせるには、
 .B \-c
 オプションを使います。

 .TP
 .B \-C --force-cdrom-big-endian
 前のオプションの逆で、デバイスをビッグエンディアンのデバイスとして
-cdparanoia に扱わせます。
+@CDPARANOIA_NAME@ に扱わせます。

 .TP
 .BI "\-n --force-default-sectors " n
@@ -119,7 +119,7 @@ cdparanoia
 1 回の読み取りごとに
 .B n
 セクタとします。この数は問題を起こすおそれがあります。カーネルは多くの
-場合、読み取り要求を最小単位の読み取り(cdparanoia による自動処理はこれ
+場合、読み取り要求を最小単位の読み取り(@CDPARANOIA_NAME@ による自動処理はこれ
 に対応しています)複数個に分割するか、制限された大きさの範囲でしか
 読み取りを許可しません。
 .B 普通はこのオプションを使うべきではありません。
@@ -152,7 +152,7 @@ CD
 .B \-Z --disable-paranoia
 データ照合と訂正機能を
 .b 全て
-無効にします。-Z オプションを用いると、cdparanoia は
+無効にします。-Z オプションを用いると、@CDPARANOIA_NAME@ は
 オーバーラップの設定が 0 である cdda2wav と全く同じようにデータの
 読み取りを行います。
 このオプションを指定すると
@@ -179,7 +179,7 @@ CD
 .B \-X --disable-scratch-detection
 照合の途中では傷の探査も行わず、傷に対して頑健な同期処理も行いません。
 .B \-X
-オプションを指定した場合、傷ついた CD を与えると cdparanoia は読み取り
+オプションを指定した場合、傷ついた CD を与えると @CDPARANOIA_NAME@ は読み取り
 の失敗を起こします。

 .TP
@@ -245,7 +245,7 @@ SCSI/ATAPI
 .B
   !  
 ステージ 1 訂正の後にエラーが見つかった。読み取りを複数回繰り返しても
-同じエラーが発生し、cdparanoia はそのエラーをうまく検出できない。
+同じエラーが発生し、@CDPARANOIA_NAME@ はそのエラーをうまく検出できない。
 .TP
 .B
   e    
@@ -307,24 +307,24 @@ span
 .TP
 ドライブの調査だけを徹底的に行い、自動検出の結果を全て報告します:
 .P
-       cdparanoia -vsQ
+       @CDPARANOIA_NAME@ -vsQ
 .TP
 ディスク全体を吸い出します。それぞれのトラックは別々のファイルにします:
 .P
-       cdparanoia -B "1-"
+       @CDPARANOIA_NAME@ -B "1-"
 .TP
 トラック 1 の時刻 0:30.12 から時刻 1:10.00 までを吸い出します:
 .P
-       cdparanoia "1[:30.12]-1[1:10]"
+       @CDPARANOIA_NAME@ "1[:30.12]-1[1:10]"
 .TP
 トラック 1 の時刻 0:30.12 から 1 分間のデータを吸い出します:
 .P
-       cdparanoia "1[:30.12]-[1:00]"
+       @CDPARANOIA_NAME@ "1[:30.12]-[1:00]"

 .SH 出力

 出力ファイルを指定する引き数は省略可能です。指定されていなければ、
-cdparanoia はサンプル音声を
+@CDPARANOIA_NAME@ はサンプル音声を
 .BR cdda.wav ", " cdda.aifc ", " cdda.raw
 のいずれかに出力します。どのファイルに出力されるのかは、オプション
 .BR \-w ", " \-a ", " \-r "," \-R
@@ -336,10 +336,10 @@ cdparanoia
 ることができます。

 .SH 謝辞
-cdparanoia の基となったのは Heiko Eissfeldt さん
+@CDPARANOIA_NAME@ の基となったのは Heiko Eissfeldt さん
 (heiko@colossus.escape.de)が作成した 'cdda2wav' パッケージであり、
-以前は cdparanoia のインタフェースの大部分は cdda2wav からもらってきた
-ものでした。cdda2wav がなければ、cdparanoia が作られることはなかったで
+以前は @CDPARANOIA_NAME@ のインタフェースの大部分は cdda2wav からもらってきた
+ものでした。cdda2wav がなければ、@CDPARANOIA_NAME@ が作られることはなかったで
 しょう。
 .P
 Joerg Schilling さんが作成した汎用 SCSI データ転送ライブラリから、SCSI 
@@ -352,3 +352,8 @@ cdparanoia
 .P
 .ce 
 http://www.xiph.org/paranoia/
+.P
+libcdio のホームページは以下の場所にあります:
+.P
+.ce 
+http://www.gnu.org/libcdio/
--- a/src/cd-paranoia/usage.txt.in
+++ b/src/cd-paranoia/usage.txt.in
@@ -47,6 +47,8 @@ OPTIONS:
  -Z --disable-paranoia           : disable all paranoia checking
  -Y --disable-extra-paranoia     : only do cdda2wav-style overlap checking
  -X --abort-on-skip              : abort on imperfect reads/skips
+  -x --test-flags=mask            : simulate CD-reading errors of ilk-mask n
+                                    mask & 0x10  - simulate underrun errors

 OUTPUT SMILIES:
  :-)   Normal operation, low/no jitter