Debian Codegraph @

upstream/debian-unstable/man5/sane-apple.5

raw
1 .TH sane\-apple 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy"
2 .IX sane\-apple
3 .SH NAME
4 sane\-apple \- SANE backend for Apple flatbed scanners
5 .SH DESCRIPTION
6 The
7 .B sane\-apple
8 library implements a SANE (Scanner Access Now Easy) backend that
9 provides access to Apple flatbed scanners. At present, the following
10 scanners are supported from this backend:
11 .PP
12 .br
13 .ft CR
14 .nf
15 --------------- ----- ------------------ ------
16 AppleScanner 4bit 16 Shades of Gray
17 OneScanner 8bit 256 Shades of Gray
18 ColorOneScanner 24bit RGB color 3-pass
19 .fi
20 .ft R
21
22 .PP
23 If you own a Apple scanner other than the ones listed above that
24 works with this backend, please let us know by sending the scanner's
25 model name, SCSI id, and firmware revision to
26 .IR sane\[email protected] .
27 See
28 .I http://www.sane\-project.org/mailing\-lists.html
29 for details on how to subscribe to sane\-devel.
30
31 .SH "DEVICE NAMES"
32 This backend expects device names of the form:
33 .PP
34 .RS
35 .I special
36 .RE
37 .PP
38 where
39 .I special
40 is the path-name for the special device that corresponds to a
41 SCSI scanner. For SCSI
42 scanners, the special device name must be a generic SCSI device or a
43 symlink to such a device. Under Linux, such a device name could be
44 .I /dev/sga
45 or
46 .IR /dev/sge ,
47 for example. See
48 .BR sane\-scsi (5)
49 for details.
50
51 .SH CONFIGURATION
52 The
53 .I apple.conf
54 file is a list of options and device names that correspond to Apple
55 scanners. Empty lines and lines starting with a hash mark (#) are
56 ignored. See
57 .BR sane\-scsi (5)
58 on details of what constitutes a valid device name.
59 .PP
60 Options come in two flavors: global and positional ones. Global
61 options apply to all devices managed by the backend, whereas positional
62 options apply just to the most recently mentioned device. Note that
63 this means that the order in which the options appear matters!
64
65 .SH SCSI ADAPTER TIPS
66 SCSI scanners are typically delivered with an ISA SCSI adapter.
67 Unfortunately, that adapter is not worth much since it is not
68 interrupt driven. It is sometimes possible to get the supplied card
69 to work, but without an interrupt line, scanning will put so much load on
70 the system that it becomes almost unusable for other tasks.
71 .SH FILES
72 .TP
73 .I /etc/sane.d/apple.conf
74 The backend configuration file (see also description of
75 .B SANE_CONFIG_DIR
76 below).
77 .TP
78 .I /usr/lib/x86_64-linux-gnu/sane/libsane\-apple.a
79 The static library implementing this backend.
80 .TP
81 .I /usr/lib/x86_64-linux-gnu/sane/libsane\-apple.so
82 The shared library implementing this backend (present on systems that
83 support dynamic loading).
84 .SH ENVIRONMENT
85 .TP
86 .B SANE_CONFIG_DIR
87 This environment variable is a list of directories where SANE looks
88 for the configuration file. On *NIX systems, directory names are
89 separated by a colon (`:'), under OS/2 by a semi-colon (`;').
90 If SANE_CONFIG_DIR is not set, SANE defaults to
91 searching the current working directory (".") and then
92 .IR /etc/sane.d .
93 If the value of $SANE_CONFIG_DIR ends with the separator
94 character, the default directories are searched after the directory list.
95 For example, setting
96 .B SANE_CONFIG_DIR
97 to "/tmp/config:" would result in directories
98 .IR tmp/config ,
99 .IR . ,
100 and
101 .I "/etc/sane.d"
102 being searched (in that order).
103 .TP
104 .B SANE_DEBUG_APPLE
105 Controls the debug level. A value of 255 prints
106 all debug output. Smaller values reduce verbosity. Requires a
107 library compiled with debug support.
108
109 .SH CURRENT STATUS
110 The apple backend is now in version 0.3 (Tue Jul 21 1998). Since
111 I only have the AppleScanner and not the other models (OneScanner,
112 ColorOneScanner) I can only develop/test for the AppleScanner effectively.
113 However with this release I almost completed the GUI part of all scanners.
114 Most of the functionality is there. At least OneScanner should scan
115 at the AppleScanner's compatible modes (LineArt, HalfTone, Gray16). My
116 personal belief is that with a slight touch of debugging the OneScanner
117 could be actually usable. The ColorOneScanner needs more work. AppleScanner
118 is of course almost fully supported.
119
120 .SH MISSING FUNCTIONALITY
121 Currently all three models lack upload/download support.
122 .TP
123 .B AppleScanner
124 Cannot up/download a halftone pattern.
125 .TP
126 .B OneScanner
127 Cannot up/download halftone patterns or calibration vectors.
128 .TP
129 .B ColorOneScanner
130 Cannot up/download halftone patterns, calibration vectors,
131 custom Color Correction Tables (CCT) and of course custom gamma tables.
132 .TP
133 .B Park/UnPark (OneScanner, ColorOneScanner)
134 Some capabilities are missing.
135 .PP
136 The above functionalities are missing because I don't
137 have the hardware to experiment on. Another reason is my lack
138 of understanding as to how or if the SANE API provide means
139 to describe any array type besides gamma.
140
141
142 .SH UNSUPPORTED FEATURES
143 The following "features" will never be supported, at least while I maintain
144 the sane\-apple backend.
145 .TP
146 .B NoHome (AppleScanner)
147 The scanner lamp stays on and the carriage assembly remains where it stops
148 at the end of the scan. After two minutes, if the scanner does not receive
149 another SCAN command, the lamp goes off and the carriage returns to the home
150 position.
151 .TP
152 .B Compression (AppleScanner)
153 The Scanner can compress data with CCITT Group III one dimensional algorithm
154 (fax) and the Skip White Line algorithm.
155 .TP
156 .B Multiple Windows (AppleScanner)
157 AppleScanner may support multiple windows. It would be a cool feature
158 and a challenge for me to code if it could intermix different options
159 for different windows (scan areas). This way it could scan a document
160 in LineArt mode but the figures in it in Gray and at a different resolution.
161 Unfortunately this is impossible.
162 .TP
163 .B Scan Direction (OneScanner)
164 It controls the scan direction. (?)
165 .TP
166 .B Status/Reset Button (OneScanner)
167 This option controls the status of the button on the OneScanner model. You can
168 also reset the button status by software.
169
170 .SH BUGS
171 SANE backend bugs are divided in two classes. We have
172 .B GUI
173 bugs and
174 .B scanner specific
175 bugs.
176 .PP
177 We know we have a GUI bug when a parameter is not showing up when it
178 should (active) or vice versa. Finding out which parameters are active
179 across various Apple modes and models from the documentation
180 is an interesting exercise. I may have missed some dependencies. For example
181 of the threshold parameter the Apple Scanners Programming Guide says
182 nothing. I had to assume it is valid only in LineArt mode.
183 .PP
184 Scanner specific bugs are mostly due to mandatory round-offs in order to
185 scan. In the documentation in one place states that the width of the
186 scan area should be a byte multiple. In another place it says that the
187 width of the scan area should be an even byte multiple. Go figure...
188 .PP
189 Other sources of bugs are due to scsi communication, scsi connects and
190 disconnects. However the classical bugs are still there. So you may
191 encounter buffer overruns, null pointers, memory corruption and
192 .B SANE
193 API violations.
194 .TP
195 .B SIGSEGV on SliceBars
196 When you try to modify the scan area from the slice bar you have a nice
197 little cute core dump. I don't know why. If you select the scan area from
198 the preview window or by hand typing the numbers everything is fine. The
199 SIGSEGV happens deep in gtk library (gdk). I really cannot debug it.
200 .TP
201 .B Options too much
202 It is possible, especially for the ColorOneScanner, for the backend's
203 options panel to extend beyond your screen. It happens with mine
204 and I am running my X Server at 1024x768. What can I say? Try smaller
205 fonts in the X server, or virtual screens.
206 .TP
207 .B Weird SCSI behaviour
208 I am quoting David Myers Here...
209
210 >> OS: FreeBSD 2.2.6
211 .br
212 >> CC: egcs-1.02
213 .br
214 Just wanted to follow up on this... I recently changed my SCSI card from
215 the Adaptec 2940UW to a dual-channel Symbios 786 chipset. When I started up
216 SANE with your driver, I managed to scan line art drawings okay, but Gray16
217 scans led to a stream of SCSI error messages on the console, ultimately
218 hanging with a message saying the scanner wasn't releasing the SCSI bus.
219 This may be that the Symbios is simply less tolerant of ancient
220 hardware, or may be bugs in your driver or in SANE itself...
221
222 .SH DEBUG
223 If you encounter a GUI bug please set the environmental variable
224 .B SANE_DEBUG_APPLE
225 to 255 and rerun the exact sequence of keystrokes
226 and menu selections to reproduce it. Then send me a report with the
227 log attached.
228 .PP
229 If you have an Apple Macintosh with the AppleScanners driver installed,
230 reporting to me which options are grayed out (inactive) in what modes
231 would be very helpful.
232 .PP
233 If you want to offer some help but you don't have a scanner, or you
234 don't have the model you would like to help with, or you are
235 a SANE developer and you just want to take a look at how the apple backend
236 looks like, goto to
237 .I apple.h
238 and #define the
239 .B NEUTRALIZE_BACKEND
240 macro. You can select the scanner model through the
241 .B APPLE_MODEL_SELECT
242 macro. Available options are
243 .BR APPLESCANNER ,
244 .BR ONESCANNER ,
245 and
246 .BR COLORONESCANNER .
247 .PP
248 If you encounter a SCSI bus error or trimmed and/or displaced images please
249 set the environment variable
250 .B SANE_DEBUG_SANEI_SCSI
251 to 255 before sending me
252 the report.
253
254 .SH TODO
255 .TP
256 .B Non Blocking Support
257 Make
258 .B sane\-apple
259 a non blocking backend. Properly support
260 .BR sane_set_io_mode ()
261 and
262 .BR sane_get_select_fd ().
263 .TP
264 .B Scan
265 Make scanning possible for all models in all supported modes.
266 .PP
267 Add other missing functionality.
268
269 .SH "SEE ALSO"
270 .BR sane (7),
271 .BR sane\-scsi (5)
272
273 .SH AUTHOR
274 The
275 .B sane\-apple
276 backend was written not entirely from scratch by
277 Milon Firikis. It is mostly based on the
278 .BR sane\-mustek (5)
279 backend from David Mosberger and Andreas Czechanowski.