Update upstream source from tag 'upstream/1.1.1'

Update to upstream version '1.1.1'
with Debian dir 4cb81ae9eaa2503b9c320ac1e8125f9df6e7f7b3

1 files changed, 161 insertions, 155 deletions

diff --git a/doc/scanimage.man b/doc/scanimage.man
index 7d48389..a86fe2a 100644
--- a/doc/scanimage.man
+++ b/doc/scanimage.man
@@ -14,7 +14,7 @@ scanimage \- scan an image
 .RB [ \-f | \-\-formatted\-device\-list
 .IR format ]
 .RB [ \-b | \-\-batch
-.RI [= format ]]
+.RI [ format ]]
 .RB [ \-\-batch\-start
 .IR start ]
 .RB [ \-\-batch\-count
@@ -24,7 +24,8 @@ scanimage \- scan an image
 .RB [ \-\-batch\-double ]
 .RB [ \-\-accept\-md5\-only ]
 .RB [ \-p | \-\-progress ]
-.RB [ \-o | \-\-output-file ]
+.RB [ \-o | \-\-output-file
+.IR path ]
 .RB [ \-n | \-\-dont\-scan ]
 .RB [ \-T | \-\-test ]
 .RB [ \-A | \-\-all-options ]
@@ -75,17 +76,33 @@ To print all available options:
   scanimage \-h
 
 .SH OPTIONS
+There are two sets of options available when running
+.BR scanimage .
+.PP
+The options that are provided by
+.B scanimage
+itself are listed below. In addition, each backend offers its own set of options and these
+can also be specified. Note that the options available from the backend may vary depending on the
+scanning device that is selected.
+.PP
+Often options that are similar in function may be implemented
+differently across backends. An example of this difference is
+.I \-\-mode Gray
+and
+.IR "\-\-mode Grayscale" .
+This may be due to differing backend author preferences.
+At other times, options are defined by the scanning device itself and therefore out of the
+control of the backend code.
+
+.PP
 Parameters are separated by a blank from single-character options (e.g.
-.BR "\-d epson" )
+.BI "\-d " epson )
 and by a "=" from multi-character options (e.g.
-.BR \-\-device\-name=epson ).
+.BR \-\-device\-name =\fIepson\FR ).
 
-.PP
-The
-.B \-d
-or
-.B \-\-device\-name
-options must be followed by a SANE device-name like
+.TP
+.BR \-d "\fI dev\fR, " \-\-device\-name =\fIdev\fR
+specifies the device to access and must be followed by a SANE device-name like
 .RI ` epson:/dev/sg0 '
 or
 .RI ` hp:/dev/usbscanner0 '.
@@ -98,11 +115,10 @@ reads a device-name from the environment variable
 If this variable is not set,
 .B scanimage
 will attempt to open the first available device.
-.PP
-The
-.B \-\-format
-.I format
-option selects how image data is written to standard output or the file specified by
+
+.TP
+.BR \-\-format =\fIformat\fR
+selects how image data is written to standard output or the file specified by
 the
 .B \-\-output\-file
 option.
@@ -116,19 +132,15 @@ or
 If
 .B \-\-format
 is not specified, PNM is written by default.
-.PP
-The
-.B \-i
-or
-.B \-\-icc\-profile
-option is used to include an ICC profile into a TIFF file.
-.PP
-The
-.B \-L
-or
-.B \-\-list\-devices
-option requests a (partial) list of devices that are available.  The
-list is not complete since some devices may be available, but are not
+
+.TP
+.BR \-i "\fI profile\fR, " \-\-icc\-profile =\fIprofile\fR
+is used to include an ICC profile into a TIFF file.
+
+.TP
+.BR \-L ", " \-\-list\-devices
+requests a (partial) list of devices that are available.  The
+list may not be complete since some devices may be available, but are not
 listed in any of the configuration files (which are typically stored
 in directory
 .IR @CONFIGDIR@ ).
@@ -136,12 +148,10 @@ This is particularly the case when accessing scanners through the network.  If
 a device is not listed in a configuration file, the only way to access it is
 by its full device name.  You may need to consult your system administrator to
 find out the names of such devices.
-.PP
-The
-.B \-f
-or
-.B \-\-formatted\-device\-list
-option works similar to
+
+.TP
+.BR \-f "\fI format\fR, " \-\-formatted\-device\-list =\fIformat\fR
+works similar to
 .BR \-\-list\-devices ,
 but requires a format string.
 .B scanimage
@@ -149,25 +159,30 @@ replaces the placeholders
 .B %d %v %m %t %i %n
 with the device name, vendor name, model name, scanner type, an index
 number and newline respectively. The command
-.PP
+.LP
 .RS
 .B scanimage \-f
 .I \*(lq scanner number %i device %d is a %t, model %m, produced by %v \*(rq
-.PP
-.RE
+.LP
+
 will produce something like:
 .PP
 .RS
 scanner number 0  device sharp:/dev/sg1 is  a  flatbed scanner, model JX250
 SCSI, produced by SHARP
 .RE
+.RE
+
 .PP
 The
 .B \-\-batch*
-options provide the features for scanning documents using document
+options provide features for scanning documents using document
 feeders.
-.BR \-\-batch
-.RI [ format ]
+
+.RS
+
+.TP
+.BR \-b " [\fIformat\fR], " \-\-batch =[\fIformat\fR]
 is used to specify the format of the filename that each page will be written
 to.  Each page is written out to a single file.  If
 .I format
@@ -190,129 +205,126 @@ This option is incompatible with the
 option.
 .I format
 is given as a printf style string with one integer parameter.
-.B \-\-batch\-start
-.I start
+
+
+.TP
+.BR \-\-batch\-start =\fIstart\fR
 selects the page number to start naming files with. If this option is not
 given, the counter will start at 1.
-.B \-\-batch\-count
-.I count
+
+.TP
+.BR \-\-batch\-count =\fIcount\fR
 specifies the number of pages to attempt to scan.  If not given,
-scanimage will continue scanning until the scanner returns a state
+.B scanimage
+will continue scanning until the scanner returns a state
 other than OK.  Not all scanners with document feeders signal when the
-ADF is empty, use this command to work around them.
-With
-.B \-\-batch\-increment
-.I increment
-you can change the amount that the number in the filename is incremented
+ADF is empty. Use this option to work around them.
+
+.TP
+.BR \-\-batch\-increment =\fIincrement\fR
+sets the amount that the number in the filename is incremented
 by.  Generally this is used when you are scanning double-sided documents
-on a single-sided document feeder.  A specific command is provided to
-aid this:
+on a single-sided document feeder.
+.B \-\-batch\-double
+is a specific command provided to aid this.
+
+.TP
 .B \-\-batch\-double
 will automatically set the increment to 2.
+Equivalent to
+.BR \-\-batch\-increment =2
+
+.TP
 .B \-\-batch\-prompt
 will ask for pressing RETURN before scanning a page. This can be used for
 scanning multiple pages without an automatic document feeder.
-.PP
-The
+.RE
+
+.TP
 .B \-\-accept\-md5\-only
-option only accepts user authorization requests that support MD5 security. The
+only accepts user authorization requests that support MD5 security. The
 .B SANE
 network daemon
-.RB ( saned )
-is capable of doing such requests. See
-.BR saned (8).
-.PP
-The
-.B \-p
-or
-.B \-\-progress
-option requests that
+.BR saned (8)
+is capable of doing such requests.
+
+.TP
+.BR \-p ", " \-\-progress
+requests that
 .B scanimage
 prints a progress counter. It shows how much image data of the current image has
-already been received by
-.B scanimage
-(in percent).
-.PP
-The
-.B \-o
-or
-.B \-\-output\-file
-option requests that
+already been received (in percent).
+
+.TP
+.BR \-o "\fI path\fR, " \-\-output\-file =\fIpath\fR
+requests that
 .B scanimage
-saves the scanning output to the given path. This option is incompatible with the
-\-\-batch option. The program will try to guess
+saves the scanning output to the given
+.IR path .
+This option is incompatible with the
+.B \-\-batch
+option. The program will try to guess
 .B \-\-format
 from the file name. If that is not possible, it will print an error message and exit.
-.PP
-The
-.B \-n
-or
-.B \-\-dont\-scan
-option requests that
+
+.TP
+.BR \-n ", " \-\-dont\-scan
+requests that
 .B scanimage
 only sets the options provided by the user but doesn't actually perform a
 scan. This option can be used to e.g. turn off the scanner's lamp (if
 supported by the backend).
-.PP
-The
-.B \-T
-or
-.B \-\-test
-option requests that
+
+.TP
+.BR \-T ", " \-\-test
+requests that
 .B scanimage
 performs a few simple sanity tests to make sure the backend works as
 defined by the
 .B SANE
-API (in particular the
+API. In particular the
 .BR sane_read ()
-function is exercised by this test).
-.PP
-The
-.B \-A
-or
-.B \-\-all-options
-option requests that
+function is exercised by this test.
+
+.TP
+.BR \-A ", " \-\-all\-options
+requests that
 .B scanimage
-lists all available options exposed the backend, including button options.
-The information is printed on standard output and no scan will be done.
-.PP
-The
-.B \-h
-or
-.B \-\-help
-options request help information.  The information is printed on
-standard output and in this case, no attempt will be made to acquire
-an image.
-.PP
-The
-.B \-v
-or
-.B \-\-verbose
-options increase the verbosity of the operation of
+lists all available options exposed by the backend, including button options.
+The information is printed on standard output and no scan will be performed.
+
+.TP
+.BR \-h ", " \-\-help
+requests help information.  The information is printed on
+standard output and no scan will be performed.
+
+.TP
+.BR \-v ", " \-\-verbose
+increases the verbosity of the output of
 .B scanimage.
 The option may be specified repeatedly, each time increasing the verbosity
 level.
-.PP
-The
-.B \-B
-option without argument changes the input buffer size from the default 32KB to 1MB.  For finer grained control, use
-.B \-\-buffer-size=
-followed by the number of KB.
-.PP
-The
-.B \-V
-or
-.B \-\-version
-option requests that
+
+.TP
+.BR \-B " [\fIsize\fR], " \-\-buffer\-size =[\fIsize\fR]
+changes input buffer size from the default of 32KB to
+.I size
+KB. If
+.I size
+is not specified then the buffer is set to 1 MB.
+
+.TP
+.BR \-V ", " \-\-version
+requests that
 .B scanimage
 prints the program and package name, the version number of
 the
 .B SANE
 distribution that it came with and the version of the backend that it
-loads. Usually that's the dll backend. If more information about the version
+loads. If more information about the version
 numbers of the backends are necessary, the
 .B DEBUG
-variable for the dll backend can be used. Example:
+variable for the dll layer can be used. Example:
 .I "SANE_DEBUG_DLL=3 scanimage \-L" .
 .PP
 As you might imagine, much of the power of
@@ -336,24 +348,26 @@ The documentation for the device-specific options printed by
 is best explained with a few examples:
 
 .B \-l 0..218mm [0]
-.br
-    Top-left x position of scan area.
-.PP
 .RS
+Top-left x position of scan area.
+.PP
 The description above shows that option
 .B \-l
 expects an option value in the range from 0 to 218 mm.  The
 value in square brackets indicates that the current option value is 0
-mm. Most backends provide similar geometry options for top-left y position (\-t),
-width (\-x) and height of scan-area (\-y).
+mm. Most backends provide similar geometry options for top-left y position
+.RB ( \-t ),
+width
+.RB ( \-x )
+and height of scan-area
+.RB (\-y ).
 .RE
 
 
 .B \-\-brightness \-100..100% [0]
-.br
-    Controls the brightness of the acquired image.
-.PP
 .RS
+Controls the brightness of the acquired image.
+.PP
 The description above shows that option
 .B \-\-brightness
 expects an option value in the range from \-100 to 100 percent.  The
@@ -362,10 +376,9 @@ percent.
 .RE
 
 .B \-\-default\-enhancements
-.br
-    Set default values for enhancement controls.
-.PP
 .RS
+Set default values for enhancement controls.
+.PP
 The description above shows that option
 .B \-\-default\-enhancements
 has no option value.  It should be thought of as having an immediate
@@ -378,10 +391,9 @@ would effectively be a no-op.
 .RE
 
 .B \-\-mode Lineart|Gray|Color [Gray]
-.br
-    Selects the scan mode (e.g., lineart or color).
-.PP
 .RS
+Selects the scan mode (e.g., lineart or color).
+.PP
 The description above shows that option
 .B \-\-mode
 accepts an argument that must be one of the strings
@@ -401,10 +413,9 @@ is identical to
 .RE
 
 .B \-\-custom\-gamma[=(yes|no)] [inactive]
-.br
-    Determines whether a builtin or a custom gamma-table should be used.
-.PP
 .RS
+Determines whether a builtin or a custom gamma-table should be used.
+.PP
 The description above shows that option
 .B \-\-custom\-gamma
 expects either no option value, a "yes" string, or a "no" string.
@@ -434,14 +445,11 @@ is selected.
 .RE
 
 .B \-\-gamma\-table 0..255,...
-.br
-    Gamma-correction table.  In color mode this option
-.br
-    equally affects the red, green, and blue channels
-.br
-    simultaneously (i.e., it is an intensity gamma table).
-.PP
 .RS
+Gamma-correction table.  In color mode this option
+equally affects the red, green, and blue channels
+simultaneously (i.e., it is an intensity gamma table).
+.PP
 The description above shows that option
 .B \-\-gamma\-table
 expects zero or more values in the range 0 to 255.  For example, a
@@ -459,12 +467,10 @@ can be used to generate such gamma tables (see
 for details).
 .RE
 
-.br
 .B \-\-filename <string> [/tmp/input.ppm]
-.br
-    The filename of the image to be loaded.
-.PP
 .RS
+The filename of the image to be loaded.
+.PP
 The description above is an example of an option that takes an
 arbitrary string value (which happens to be a filename).  Again,
 the value in brackets show that the option is current set to the
@@ -501,8 +507,8 @@ to 127 characters.
 .BR sane (7),
 .BR gamma4scanimage (1),
 .BR xscanimage (1),
-.BR xcam(1) ,
-.BR xsane(1) ,
+.BR xcam (1) ,
+.BR xsane (1) ,
 .BR scanadf (1),
 .BR sane\-dll (5),
 .BR sane\-net (5),