Document new v7/v8 features; .doc = .txt

git-svn-id: svn://svn.code.sf.net/p/libjpeg-turbo/code/trunk@252 632fc199-4ca6-4c93-a231-07263d6284db

1 files changed, 35 insertions, 31 deletions

diff --git a/cjpeg.1 b/cjpeg.1
index 3aee807..63a4e39 100644
--- a/cjpeg.1
+++ b/cjpeg.1
@@ -1,4 +1,4 @@
-.TH CJPEG 1 "30 December 2009"
+.TH CJPEG 1 "11 October 2010"
 .SH NAME
 cjpeg \- compress an image file to a JPEG file
 .SH SYNOPSIS
@@ -108,33 +108,35 @@ other JPEG programs may be unable to decode the resulting file.  Use
 .B \-baseline
 if you need to ensure compatibility at low quality values.)
 .PP
-The
-.B \-quality
-option has been extended in IJG version 7 for support of separate quality
-settings for luminance and chrominance (or in general, for every provided
-quantization table slot).  This feature is useful for high-quality
-applications which cannot accept the damage of color data by coarse
-subsampling settings.  You can now easily reduce the color data amount more
-smoothly with finer control without separate subsampling.  The resulting file
-is fully compliant with standard JPEG decoders.
-Note that the
-.B \-quality
-ratings refer to the quantization table slots, and that the last value is
-replicated if there are more q-table slots than parameters.  The default
-q-table slots are 0 for luminance and 1 for chrominance with default tables as
-given in the JPEG standard.  This is compatible with the old behaviour in case
-that only one parameter is given, which is then used for both luminance and
-chrominance (slots 0 and 1).  More or custom quantization tables can be set
-with
-.B \-qtables
-and assigned to components with
-.B \-qslots
-parameter (see the "wizard" switches below).
-.B Caution:
-You must explicitly add
-.BI \-sample " 1x1"
-for efficient separate color
-quality selection, since the default value used by library is 2x2!
+The \fB-quality\fR option has been extended in this version of \fBcjpeg\fR to
+support separate quality settings for luminance and chrominance (or, in
+general, separate settings for every quantization table slot.)  The principle
+is the same as chrominance subsampling:  since the human eye is more sensitive
+to spatial changes in brightness than spatial changes in color, the chrominance
+components can be quantized more than the luminance components without
+incurring any visible image quality loss.  However, unlike subsampling, this
+feature reduces data in the frequency domain instead of the spatial domain,
+which allows for more fine-grained control.  This option is useful in
+quality-sensitive applications, for which the artifacts generated by
+subsampling may be unacceptable.
+.PP
+The \fB-quality\fR option accepts a comma-separated list of parameters, which
+respectively refer to the quality levels which should be assigned to the
+quantization table slots.  If there are more q-table slots than parameters,
+then the last parameter is replicated.  Thus, if only one quality parameter is
+given, this is used for both luminance and chrominance (slots 0 and 1,
+respectively), preserving the legacy behavior of cjpeg v6b and prior.
+More (or customized) quantization tables can be set with the \fB-qtables\fR
+option and assigned to components with the \fB-qslots\fR option (see the
+"wizard" switches below.)
+.PP
+JPEG files generated with separate luminance and chrominance quality are fully
+compliant with standard JPEG decoders.
+.PP
+.BR CAUTION:
+For this setting to be useful, be sure to pass an argument of \fB-sample 1x1\fR
+to \fBcjpeg\fR to disable chrominance subsampling.  Otherwise, the default
+subsampling level (2x2, AKA "4:2:0") will be used.
 .PP
 The
 .B \-progressive
@@ -236,7 +238,7 @@ Use the scan script given in the specified text file.
 .PP
 The "wizard" switches are intended for experimentation with JPEG.  If you
 don't know what you are doing, \fBdon't use them\fR.  These switches are
-documented further in the file wizard.doc.
+documented further in the file wizard.txt.
 .SH EXAMPLES
 .LP
 This example compresses the PPM file foo.ppm with a quality factor of
@@ -303,8 +305,10 @@ Independent JPEG Group
 .SH BUGS
 Arithmetic coding is not supported for legal reasons.
 .PP
-GIF input files are no longer supported, to avoid the Unisys LZW patent.
-(Conversion of GIF files to JPEG is usually a bad idea anyway.)
+Support for GIF input files was removed in cjpeg v6b due to concerns over
+the Unisys LZW patent.  Although this patent expired in 2006, cjpeg still
+lacks GIF support, for these historical reasons.  (Conversion of GIF files to
+JPEG is usually a bad idea anyway.)
 .PP
 Not all variants of BMP and Targa file formats are supported.
 .PP