diff options
Diffstat (limited to 'doc/scanimage.man')
| -rw-r--r-- | doc/scanimage.man | 316 |
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), |