Document new v7/v8 features; .doc = .txt
git-svn-id: svn+ssh://svn.code.sf.net/p/libjpeg-turbo/code/trunk@252 632fc199-4ca6-4c93-a231-07263d6284db
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 @@
.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 @@
.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 @@
.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