Merge pull request #11 from rocky/force-overread

Adds --force-overread

doc/en/cd-paranoia.1.in

@@ -4,7 +4,7 @@
 .SH SYNOPSIS
 .B @CDPARANOIA_NAME@
 .RB [ options ]
-.B span 
+.B span
 .RB [ outfile ]
 .SH DESCRIPTION
 .B @CDPARANOIA_NAME@
@@ -15,7 +15,7 @@ makes are supported;
 .B @CDPARANOIA_NAME@
 can determine if the target drive is CDDA capable.
 .P
-In addition to simple reading, 
+In addition to simple reading,
 .B @CDPARANOIA_NAME@
 adds extra-robust data verification, synchronization, error handling
 and scratch reconstruction capability.
@@ -25,7 +25,7 @@ drive. The jitter and error correction however are the same as used in
 Xiph's cdparanoia.
 .SH OPTIONS
 
-.TP 
+.TP
 .B \-A --analyze-drive
 Run and log a complete analysis of drive caching, timing and reading behavior;
 verifies that cdparanoia is correctly modelling a sprcific drive's cache and
@@ -55,23 +55,23 @@ contents, then quit.
 
 .TP
 .B \-h --help
-Print a brief synopsis of 
-.B @CDPARANOIA_NAME@ 
+Print a brief synopsis of
+.B @CDPARANOIA_NAME@
 usage and options.
 
 .TP
-.BI "\-l --log-summary " file 
+.BI "\-l --log-summary " file
 Save result summary to file.
 
 .TP
-.BI "\-L --log-debug " file 
+.BI "\-L --log-debug " file
 Save detailed device autosense and debugging output to a file.
 
 .TP
 .B \-p --output-raw
-Output headerless data as raw 16 bit PCM data with interleaved samples in host byte order.  To force little or big endian byte order, use 
-.B \-r 
-or 
+Output headerless data as raw 16 bit PCM data with interleaved samples in host byte order.  To force little or big endian byte order, use
+.B \-r
+or
 .B \-R
 as described below.
 
@@ -118,12 +118,12 @@ As above but force @CDPARANOIA_NAME@ to treat the drive as a big endian device.
 
 .TP
 .BI "\-n --force-default-sectors " n
-Force the interface backend to do atomic reads of 
+Force the interface backend to do atomic reads of
 .B n
 sectors per read.  This number can be misleading; the kernel will often
 split read requests into multiple atomic reads (the automated Paranoia
 code is aware of this) or allow reads only wihin a restricted size
-range. 
+range.
 .B This option should generally not be used.
 
 .TP
@@ -183,13 +183,19 @@ 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
+.BI \-E --force-overread
+Force overreading into the lead-out portion of the disc. This option is only applicable when using the
++.B -O
++option with a positive sample offset value. Many drives are not capable of reading into this portion of the disc and attempting to do so on those drives will produce read errors and possibly hard lockups.
+
 .TP
 .B \-Z --disable-paranoia
-Disable 
+Disable
 .B all
 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 
+This option implies that
 .B \-Y
 is active.
 
@@ -223,85 +229,85 @@ simulate the kind of specified failure.
 .SH OUTPUT SMILIES
 .TP
 .B
-  :-)   
+  :-)
 Normal operation, low/no jitter
 .TP
 .B
-  :-|   
+  :-|
 Normal operation, considerable jitter
 .TP
 .B
-  :-/   
+  :-/
 Read drift
 .TP
 .B
-  :-P   
+  :-P
 Unreported loss of streaming in atomic read operation
 .TP
 .B
-  8-|   
+  8-|
 Finding read problems at same point during reread; hard to correct
 .TP
 .B
-  :-0   
+  :-0
 SCSI/ATAPI transport error
 .TP
 .B
-  :-(   
+  :-(
 Scratch detected
 .TP
 .B
-  ;-(   
+  ;-(
 Gave up trying to perform a correction
 .TP
 .B
   8-X
 Aborted read due to known, uncorrectable error
 .TP
 .B
-  :^D   
+  :^D
 Finished extracting
 
 .SH PROGRESS BAR SYMBOLS
 .TP
 .B
-<space> 
+<space>
 No corrections needed
 .TP
 .B
-   -    
+   -
 Jitter correction required
 .TP
 .B
-   +    
+   +
 Unreported loss of streaming/other error in read
 .TP
 .B
-   !  
+   !
 Errors found after stage 1 correction; the drive is making the
 same error through multiple re-reads, and @CDPARANOIA_NAME@ is having trouble
 detecting them.
 .TP
 .B
-   e    
+   e
 SCSI/ATAPI transport error (corrected)
 .TP
 .B
-   V    
+   V
 Uncorrected error/skip
 
 .SH SPAN ARGUMENT
 
 The span argument specifies which track, tracks or subsections of
-tracks to read.  This argument is required. 
+tracks to read.  This argument is required.
 .B NOTE:
 Unless the span is a simple number, it's generally a good idea to
 quote the span argument to protect it from the shell.
 .P
 The span argument may be a simple track number or an offset/span
 specification.  The syntax of an offset/span takes the rough form:
 .P
-1[ww:xx:yy.zz]-2[aa:bb:cc.dd] 
+1[ww:xx:yy.zz]-2[aa:bb:cc.dd]
 .P
 Here, 1 and 2 are track numbers; the numbers in brackets provide a
 finer grained offset within a particular track. [aa:bb:cc.dd] is in
@@ -316,20 +322,20 @@ offset is preceeded or followed by a hyphen, the implicit missing
 offset is taken to be the start or end of the disc, respectively. Thus:
 
 .TP
-.B  1:[20.35]    
+.B  1:[20.35]
 Specifies ripping from track 1, second 20, sector 35 to the end of
 track 1.
 .TP
-.B 1:[20.35]-   
+.B 1:[20.35]-
 Specifies ripping from 1[20.35] to the end of the disc
 .TP
-.B \-2           
+.B \-2
 Specifies ripping from the beginning of the disc up to (and including) track 2
 .TP
-.B \-2:[30.35]   
+.B \-2:[30.35]
 Specifies ripping from the beginning of the disc up to 2:[30.35]
 .TP
-.B 2-4          
+.B 2-4
 Specifies ripping from the beginning of track 2 to the end of track 4.
 .P
 Again, don't forget to protect square brackets and preceeding hyphens from
@@ -345,7 +351,7 @@ Query only with exhaustive search for a drive and full reporting of autosense:
 .TP
 Extract an entire disc, putting each track in a seperate file:
 .P
-       @CDPARANOIA_NAME@ -B 
+       @CDPARANOIA_NAME@ -B
 .TP
 Extract from track 1, time 0:30.12 to 1:10.00:
 .P
@@ -361,11 +367,11 @@ The "--" above is to distinguish "-3" from an option flag.
 The output file argument is optional; if it is not specified,
 @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 
-is the implicit default).  The output file argument of 
+depending on whether
+.BR \-w ", " \-a ", " \-r " or " \-R " is used (" \-w
+is the implicit default).  The output file argument of
 .B \-
-specifies standard output; all data formats may be piped. 
+specifies standard output; all data formats may be piped.
 
 .SH ACKNOWLEDGEMENTS
 @CDPARANOIA_NAME@ sprang from and once drew heavily from the interface of