Initial import of sane-backends version 1.0.24-1.2

1 files changed, 324 insertions, 0 deletions

diff --git a/doc/sane-test.man b/doc/sane-test.man
new file mode 100644
index 0000000..41b9aa4
--- /dev/null
+++ b/doc/sane-test.man
@@ -0,0 +1,324 @@
+.TH sane\-test 5 "14 Jul 2008" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy"
+.IX sane\-test
+.SH NAME
+sane\-test \- SANE backend for testing frontends
+.SH DESCRIPTION
+The
+.B sane\-test
+library implements a SANE (Scanner Access Now Easy) backend that allows
+testing the SANE installation and SANE frontends.  It provides access to a
+(nearly) unlimited number of virtual devices.  There is no support for real
+scanners or cameras.  However, the backend simulates scanning and setting
+options.
+.PP
+The idea is not only to find bugs in frontends but also to show all
+capabilities of SANE.  Therefore
+.B sane\-test
+implements functions and options that are not (or seldom) found in other
+backends. 
+.PP
+The backend is commented out in @CONFIGDIR@/dll.conf, so either the comment
+character must be removed or the backend must be called explicitly.  E.g. 
+`scanimage \-d test' or `xscanimage test'.
+
+.SH SCAN MODE OPTIONS
+Option
+.B mode
+selects the scan mode (Gray or Color).
+.PP
+Option
+.B depth
+determines the number of bits per sample (1. 8, or 16).  Keep in mind, that
+this value refers to the sample, not the pixel.  So depth=16 results in 48
+bits per pixel in color mode. The most usual combinations are mode=Gray,
+depth=1 for lineart, mode=Gray, depth=8 for gray and mode=Color, depth=8 for
+color mode.  The combination of color and 1-bit mode is quite obscure (8
+colors) but allowed in the SANE standard. However, the meaning of bits is not
+defined. Currently 1 = high intensity and 0 = low intensity is used.
+.PP
+Setting option
+.B hand\-scanner
+results in the test-backend behaving like a hand-scanner.  Hand-scanners do
+not know the image height a priori.  Instead, they return a height of \-1.
+Setting this option allows to test whether a frontend can handle this
+correctly.  This option also enables a fixed width of 11 cm.
+.PP
+Setting option
+.B three\-pass
+simulates a three-pass scanner.  Older color scanners needed to scan the image
+once per color (reg/green/blue) to get the full image.  Therefore, in this mode
+three single frames are transmitted in color mode.
+.PP
+Option
+.B three\-pass\-order
+provides support for changing the order of the three frames (see option
+three-pass above).  A frontend should support all orders.
+.PP
+Option
+.B resolution
+sets the resolution of the image in dots per inch.
+.PP
+.PP
+Option
+.B source
+can be used to simulate an Automatic Document Feeder (ADF). After 10 scans, the
+ADF will be "empty".
+.PP
+
+.SH SPECIAL OPTIONS
+Option
+.B test\-picture
+allows to set the image that's returned to the frontend.  While "Solid white"
+and "Solid black" are quite obvious, the other options need some more
+explanation.  Color patterns are used to determine if all modes and their
+colors are represented correctly by the frontend.  The grid should look like the
+same in every mode and resolution.  A table of all the test pictures can be
+found at: http://www.meier\-geinitz.de/sane/test\-backend/test\-pictures.html.
+.PP
+If option
+.B invert\-endianess
+is set, the upper and lower bytes of image data in 16 bit modes are exchanged.
+This option can be used to test the 16 bit modes of frontends, e.g. if the
+frontend uses the correct endianess.
+.PP
+If option
+.B read\-limit
+is set, the maximum amount of data transferred with each call to sane_read() is
+limited.
+.PP
+Option 
+.B read\-limit\-size
+sets the limit for option read-limit.  A low limit slows down scanning.  It
+can be used to detect errors in frontend that occur because of wrong
+assumptions on the size of the buffer or timing problems.
+.PP
+Option
+.B read\-delay
+enables delaying data to the frontend.
+.PP
+Option
+.B read\-delay\-duration
+selects the number of microseconds the backends waits after each transfer of a
+buffer.  This option is useful to find timing-related bugs, especially if
+used over the network.
+.PP
+If option
+.B read\-return\-value
+is different from "Default", the selected status will be returned by every
+call to sane_read().  This is useful to test the frontend's handling of the
+SANE statuses.
+.PP
+If option
+.B ppl\-loss
+is different from 0, it determines the number of pixels that are "lost" at the
+end of each line.  That means, lines are padded with unused data.
+.PP
+Option
+.B fuzzy\-parameters
+selects that fuzzy (inexact) parameters are returned as long as the scan
+hasn't been started.  This option can be used to test if the frontend uses the
+parameters it got before the start of the scan (which it shouldn't).
+.PP
+Option
+.B non\-blocking
+determines if non-blocking IO for sane_read() should be used if supported by
+the frontend.
+.PP
+If option
+.B select\-fd
+is set, the backend offers a select filedescriptor for detecting if
+sane_read() will return data.
+.PP
+If option
+.B enable\-test\-options
+is set, a fairly big list of options for testing the various SANE option
+types is enabled.
+.PP
+Option
+.B print\-options
+can be used to print a list of all options to standard error.
+.PP
+
+.SH GEOMETRY OPTIONS
+Option
+.B tl\-x
+determines the top-left x position of the scan area.
+.PP
+Option
+.B tl\-y
+determines the top-left y position of the scan area.
+.PP
+Option
+.B br\-x
+determines the bottom-right x position of the scan area.
+.PP
+Option
+.B br\-y
+determines the bottom-right y position of the scan area.
+.PP
+
+.SH BOOL TEST OPTIONS
+There are 6 bool test options in total.  Each option is numbered.  (3/6)
+means: this is option 3 of 6.  The numbering scheme is intended for easier
+detection of options not displayed by the frontend (because of missing support
+or bugs).
+.PP
+Option
+.B bool\-soft\-select\-soft\-detect
+(1/6) is a bool test option that has soft select and soft detect (and
+advanced) capabilities.  That's just a normal bool option.
+.PP
+Option
+.B bool\-hard\-select\-soft\-detect
+(2/6) is a bool test option that has hard select and soft detect (and
+advanced) capabilities.  That means the option can't be set by the frontend
+but by the user (e.g. by pressing a button at the device).
+.PP
+Option
+.B bool\-hard\-select
+(3/6) is a bool test option that has hard select (and advanced) capabilities.
+That means the option can't be set by the frontend but by the user (e.g. by
+pressing a button at the device) and can't be read by the frontend.
+.PP
+Option
+.B bool\-soft\-detect
+(4/6) is a bool test option that has soft detect (and advanced)
+capabilities.  That means the option is read-only.
+.PP
+Option
+.B bool\-soft\-select\-soft\-detect\-emulated
+(5/6) is a Bool test option that has soft select, soft detect, and emulated
+(and advanced) capabilities.
+.PP
+Option
+.B bool\-soft\-select\-soft\-detect\-auto
+(6/6) is a Bool test option that has soft select, soft detect, and automatic
+(and advanced) capabilities.  This option can be automatically set by the
+backend.
+.PP
+
+.SH INT TEST OPTIONS
+There are 6 int test options in total. 
+.PP
+Option
+.B int
+(1/6) is an int test option with no unit and no constraint set.
+.PP
+Option
+.B int\-constraint\-range
+(2/6) is an int test option with unit pixel and constraint range set.  Minimum
+is 4, maximum 192, and quant is 2.
+.PP
+Option
+.B int\-constraint\-word\-list
+(3/6) is an int test option with unit bits and constraint word list set.
+.PP
+Option
+.B int\-constraint\-array
+(4/6) is an int test option with unit mm and using an array without
+constraints.
+.PP
+Option
+.B int\-constraint\-array\-constraint\-range
+(5/6) is an int test option with unit mm and using an array with a range
+constraint.  Minimum is 4, maximum 192, and quant is 2.
+.PP
+Option
+.B int\-constraint\-array\-constraint\-word\-list
+(6/6) is an int test option with unit percent and using an array a word list
+constraint.
+
+.SH FIXED TEST OPTIONS
+There are 3 fixed test options in total. 
+.PP
+Option
+.B fixed
+(1/3) is a fixed test option with no unit and no constraint set.
+.PP
+Option
+.B fixed\-constraint\-range
+(2/3) is a fixed test option with unit microsecond and constraint range
+set. Minimum is \-42.17, maximum 32767.9999, and quant is 2.0.
+.PP
+Option
+.B fixed\-constraint\-word\-list
+(3/3) is a Fixed test option with no unit and constraint word list set.
+.PP
+
+.SH STRING TEST OPTIONS
+There are 3 string test options in total. 
+.PP
+Option
+.B string
+(1/3) is a string test option without constraint.
+.PP
+Option
+.B string\-constraint\-string\-list
+(2/3) is a string test option with string list constraint.
+.PP
+Option
+.B string\-constraint\-long\-string\-list
+(3/3) is a string test option with string list constraint. Contains some more
+entries...
+.PP
+
+.SH BUTTON TEST OPTION
+Option
+.B button
+(1/1) is a Button test option. Prints some text...
+.PP
+
+.SH FILES
+.TP
+.I @CONFIGDIR@/test.conf
+The backend configuration file (see also description of
+.B SANE_CONFIG_DIR
+below). The initial values of most of the basic SANE options can be configured
+in this file. A template containing all the default values is provided
+together with this backend. One of the more interesting values may be
+.BR number_of_devices . 
+It can be used to check the frontend's ability to show a long list of devices.
+The config values concerning resolution and geometry can be useful to test
+the handling of big file sizes.
+
+.TP
+.I @LIBDIR@/libsane\-test.a
+The static library implementing this backend.
+.TP
+.I @LIBDIR@/libsane\-test.so
+The shared library implementing this backend (present on systems that
+support dynamic loading).
+.SH ENVIRONMENT
+.TP
+.B SANE_CONFIG_DIR
+This environment variable specifies the list of directories that may
+contain the configuration file.  Under UNIX, the directories are
+separated by a colon (`:'), under OS/2, they are separated by a
+semi-colon (`;').  If this variable is not set, the configuration file
+is searched in two default directories: first, the current working
+directory (".") and then in @CONFIGDIR@.  If the value of the
+environment variable ends with the directory separator character, then
+the default directories are searched after the explicitly specified
+directories.  For example, setting
+.B SANE_CONFIG_DIR
+to "/tmp/config:" would result in directories "tmp/config", ".", and
+"@CONFIGDIR@" being searched (in this order).
+.TP
+.B SANE_DEBUG_TEST
+If the library was compiled with debug support enabled, this
+environment variable controls the debug level for this backend.  Higher
+debug levels increase the verbosity of the output. 
+
+Example: 
+export SANE_DEBUG_TEST=4
+
+.SH "SEE ALSO"
+sane(7), 
+.IR http://www.meier\-geinitz.de/sane/test\-backend/
+
+
+.SH AUTHOR
+Henning Meier-Geinitz <henning@meier\-geinitz.de>
+
+.SH BUGS
+\- config file values aren't tested for correctness