From 52c6a7f13d82d14545d721f342b5a0e01ad73235 Mon Sep 17 00:00:00 2001 From: Henning Geinitz Date: Wed, 2 Apr 2003 11:59:31 +0000 Subject: [PATCH] Reorganization. Updated DEVELOPER'S DOCUMENTATION. Rewrote PROBLEMS in a more user-centric way. Added "HOW CAN YOU HELP" section. Added paragraph about SANE device lists. Updated CONTACT section. Minor additions to the gt68xx and plustek entries. Minor spelling fixes. --- ChangeLog | 5 + doc/sane.man | 411 ++++++++++++++++++++++++++++++++------------------- 2 files changed, 262 insertions(+), 154 deletions(-) diff --git a/ChangeLog b/ChangeLog index 441d70328..8208dfbc6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,11 @@ 2003-04-02 Henning Meier-Geinitz * doc/sane-as6e.man: Added info about $PATH. Minor formatting fixes. + * doc/sane.man: Reorganization. Updated DEVELOPER'S DOCUMENTATION. + Rewrote PROBLEMS in a more user-centric way. Added "HOW CAN YOU + HELP" section. Added paragraph about SANE device lists. Updated + CONTACT section. Minor additions to the gt68xx and plustek + entries. Minor spelling fixes. 2003-03-31 Henning Meier-Geinitz diff --git a/doc/sane.man b/doc/sane.man index d7c1db368..e163b50df 100644 --- a/doc/sane.man +++ b/doc/sane.man @@ -1,4 +1,4 @@ -.TH sane 7 "Feb 24th, 2003" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy" +.TH sane 7 "April 2nd, 2003" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy" .IX sane .SH NAME @@ -19,6 +19,8 @@ operating system. .PP This manual page provides a summary of the information available about .BR SANE . +.PP +If you have trouble getting your scanner detected, read the PROBLEMS section. .SH TERMINOLOGY @@ -34,42 +36,6 @@ A .B meta backend provides some means to manage one or more other backends. -.SH "SANE STANDARD AND WRITING BACKENDS" -The -.B SANE -standard defines the application programming interface (API) that is used to -communicate between frontends and backends. It can be found at -.I @DOCDIR@/sane.ps -(if latex is installed on your system) and on the -.B SANE -website: -.I http://www.mostang.com/sane/html/ -(HTML), or -.I http://www.mostang.com/sane/sane.ps -(Postscript). -.PP -There is some more information for programmers in -.IR @DOCDIR@/backend-writing.txt . -Most of the internal -.B SANE -routines -.RB ( sanei ) -are documented using doxygen: -.IR http://sanei.meier-geinitz.de/ . -Before a new backend or frontend project is started, have a look at -.I @DOCDIR@/PROJECTS -for projects that are planned or not yet included into the -.B SANE -distribution. -.PP -Your help is always appreciated. Look at -.I @DOCDIR@/TODO -for things that should be done. Not only programmers are needed, but also -reading and fixing the documentation and reporting bugs would be nice. Further -more, translations of the backend options are needed. Contact the -.B SANE -mailing list for details and tell us, when you start working on a project, so -no work id duplicated. .SH "SOFTWARE PACKAGES" The package @@ -112,6 +78,17 @@ Information on all aspects of SANE including a tutorial and a link to the SANE F can be found on the SANE homepage: .IR http://www.mostang.com/sane/ . .TP +.B SANE device lists +The +.B SANE +device lists contain information about the status of +.B SANE +support for a specific device. If your scanner is not listed there (either +supported or unsupported), please contact us. See section HOW CAN YOU HELP +SANE for details. There are lists for specific releases of SANE, for the +current develoment version and a search engine: +.IR http://www.mostang.com/sane/sane-supported-devices.html . +.TP .B SANE mailing list There is a mailing list for the purpose of discussing the SANE standard and its implementations: sane-devel. Despite its name, the list is not only @@ -148,7 +125,7 @@ available on the local host. See .BR saned (1). .TP .B sane-find-scanner -Ccommand-line tool to find SCSI and USB scanners and determine their Unix +Command-line tool to find SCSI and USB scanners and determine their Unix device files. See .BR sane-find-scanner (1). .PP @@ -201,7 +178,7 @@ for details. .B avision This backend supports several Avision based scanners. This includes the original Avision scanners (like AV 630, AV 620, ...) as well as the HP -ScanJet 53xx and 74xx series, Fujitsu ScanPartnerm, some Mitsubishi and +ScanJet 53xx and 74xx series, Fujitsu ScanPartner, some Mitsubishi and Minolta film-scanners. See .BR sane-avision (5) @@ -256,9 +233,10 @@ fi-4340 SCSI scanners. See for details. .TP .B gt68xx -The gt68xx backend provides support for scanners based on the Grandtech GT-6801 -and GT-6816 chips like the Artec Ultima 2000 and several Mustek BearPaw CU and -TA models. See +The gt68xx backend provides support for scanners based on the Grandtech +GT-6801 and GT-6816 chips like the Artec Ultima 2000 and several Mustek +BearPaw CU and TA models. Some Genius, Lexmark, Medion, Packard Bell, Plustek, +and Trust scanners are also supported. See .BR sane-gt68xx (5) for details. .TP @@ -333,7 +311,8 @@ for details. .TP .B plustek The SANE plustek backend supports Plustek parallel port and LM983[1/2/3] based -USB flatbed scanners. See +USB flatbed scanners. Scanners using the LM983x chips include some models from +Plustek, KYE/Genius, Hewlett-Packard, Mustek, Umax, Epson, and Canon. See .BR sane-plustek (5) for details. .TP @@ -505,121 +484,68 @@ Also, have a look at the backend information page at and the list of projects in .IR @DOCDIR@/PROJECTS . -.SH PROBLEMS -Please note that the default configuration uses +.SH "CHANGING THE TOP-LEVEL BACKEND" +By default, all +.B SANE +backends (drivers) are loaded dynamically by the .B sane-dll -as the top-level backend. Hence it is probably a good idea to start with -reading +meta backend. If you have any questions about the dynamic loading, +read .BR sane-dll (5). -The top-level backend can be changed by copying or linking a backend to +.B SANE +frontend can also be linked to other backends directly by copying or linking a +backend to .B libsane.so in .IR @LIBDIR@ . .PP -If you encounter any problems with getting your device(s) recognized, try -setting the various environment variables that are available to assist in -debugging such problems. The environment variables are documented in the -relevant manual pages. For example, to get the maximum amount of debug -information when testing a Mustek SCSI scanner, set environment variables -.BR SANE_DEBUG_DLL ", " SANE_DEBUG_MUSTEK ", and " SANE_DEBUG_SANEI_SCSI -to 128 and then invoke -.B scanimage -or whatever program you're trying to debug. For a Mustek scanner at -.IR /dev/scanner, -you might want to invoke -.B scanimage -as follows: -.IP -.B scanimage \-d -.I mustek:/dev/scanner -.B \-h -.TP -If this works, you could try to acquire an image with: -.IP -.B scanimage \-d -.IR mustek:/dev/scanner " >t.pnm" -.PP -To check that the -.B SANE -libraries are installed correctly you can use the test backend, even if you -don't have a scanner or other -.B SANE -device: -.IP -.B scanimage \-d -.I test -.B \-T -.TP -You should get a list of PASSed tests. -.PP -If you are not sure what generic SCSI or USB device your scanner is connected -to, try the command -.BR sane-find-scanner . -Usually, It's sufficient to invoke the program without any arguments. -Invoking this command should produce output similar to this (informational -messages are ommitted): -.IP -found SCSI scanner "SCANNER 2.01" at /dev/sg1 -.br -found USB scanner (vendor=0x05d8, product=0x4002) at libusb:001:012 -.PP -Note that sane-find-scanner will find any scanner that is connected to a SCSI -or USB bus. It will even find scanners that are not supported at all by -.BR SANE . -.PP -There may be several causes for the following messages from the frontends: -"scanimage: no SANE devices found" or "xscanimage: no devices available.". -.TP 2 -* -Your scanner is not recognized by any backend. It is not supported. You may -ask the maintainer of your backend (see -.IR @DOCDIR@/AUTHORS ) -or the -.B SANE -mailing list (see above) if support is planned. -.TP -* -.B SANE -can't access the device files (e.g -.IR /dev/sg0 ). -Check the permissions. -.TP -* -Your backend is not listed in -.I @CONFIGDIR@/dll.conf -(or commented out). -.TP -* -There are older installations of -.B SANE -on your system. If you installed the -.B SANE -libraries in -.I /usr/local/lib -(default) you should check if there are older -.B SANE -libraries at -.IR /usr/lib . -Remove them using your distribution's package manager or manually -.RB ( "rm \-r" -.IR "/usr/lib/libsane* /usr/lib/sane" ). -.TP -* -If you can use -.B SANE -with -.B scanimage -but not with other (graphical) frontends, check that -.I /etc/ld.so.conf -contains -.I /usr/local/lib -and does -.B not -contain -.IR /usr/local/lib/sane . -See also the documentation of the frontends. -.SH FILES +.SH "DEVELOPER'S DOCUMENTATION" +It's not hard to write a +.B SANE +backend. It can take some time, however. You should have basic knowledege of C +and enough patience to work through the documentation and find out how your +scanner works. Appended is a list of some documents that help to write backends +and frontends. +.PP +The +.B SANE +standard defines the application programming interface (API) that is used to +communicate between frontends and backends. It can be found at +.I @DOCDIR@/sane.ps +(if latex is installed on your system) and on the +.B SANE +website: +.I http://www.mostang.com/sane/html/ +(HTML), or +.I http://www.mostang.com/sane/sane.ps +(Postscript). +.PP +There is some more information for programmers in +.IR @DOCDIR@/backend-writing.txt . +Most of the internal +.B SANE +routines +.RB ( sanei ) +are documented using doxygen: +.IR http://sanei.meier-geinitz.de/ . +Before a new backend or frontend project is started, have a look at +.I @DOCDIR@/PROJECTS +for projects that are planned or not yet included into the +.B SANE +distribution and at the todo list: +.IR @DOCDIR@/TODO . +.PP +There are some links on how to find out about the protocol of a scanner: +.IR http://www.meier-geinitz.de/sane/misc/develop.html . + +.PP +If you start writing a backend or frontend or any other part of +.BR SANE, +please contact the sane-devel mailing list for coordination so the same work +isn't done twice. + +.SH "FILES" .TP .I @CONFIGDIR@/*.conf The backend configuration files. @@ -635,9 +561,186 @@ support dynamic loading). .B SANE documentation: The standard, READMEs, text files for backends etc. -.SH "REPORTING BUGS" -If you think you found a bug in a backend, contact the author of your -backend. Usually the email address can be found in the +.SH "PROBLEMS" +If your device isn't found but you know that it is supported, make +sure that it is detected by your operating system. For SCSI and USB scanners, +use the +.B sane-find-scanner +tool (see +.BR sane-find-scanner (1) +for details). It prints one line for each scanner it has detected and some +comments (#). If +.B sane-find-scanner +finds your scanner only as root but not as normal user, the permissions for +the device files are not adjusted correctly. If the scanner isn't found at all, +the operating system hasn't detected it and may need some help. Depending on +the type of your scanner, read +.BR sane-usb (5) +or +.BR sane-scsi (5). +If your scanner (or other device) is not connected over the SCSI bus or USB, +read the backend's manual page for details on how to set it up. +.PP + +Now your scanner is detected by the operating system but not by +.BR SANE ? +Try +.BR "scanimage -L" . +If the scanner is not found, check that the backend's name is mentioned in +.IR @CONFIGDIR@/dll.conf . +Some backends are commented out by default. Remove the comment sign for your +backend in this case. Also some backends aren't compiled at all if one of their +prerequisites are missing. Examples include dc210, dc240, canon_pp, hpsj5s, +gphoto2, pint, qcam, v4l, net, sm3600, snapscan, pnm. If you need one of these +backends and they aren't available, read the build instructions in the +.B README +file and the individual manual pages of the backends. +.PP + +Another reason for not beeing detected by +.B scanimage -L +may be a missing or wrong configuration in the backend's configuration +file. While +.B SANE +tries to automatically find most scanners, some can't be setup correctly +without the intervention of the administrator. Also on some operating systems +auto-detection may not work. Check the backend's manual page for details. +.PP +If your scanner is still not found, try +setting the various environment variables that are available to assist in +debugging. The environment variables are documented in the +relevant manual pages. For example, to get the maximum amount of debug +information when testing a Mustek SCSI scanner, set environment variables +.BR SANE_DEBUG_DLL ", " SANE_DEBUG_MUSTEK ", and " SANE_DEBUG_SANEI_SCSI +to 128 and then invoke +.B scanimage +.B -L . +The debug messages for the dll backend tell if the mustek backend was found +and loaded at all. The mustek messages explain what the mustek backend is +doing while the SCSI debugging shows the low level handling. If you can't find +out what's going on by checking the messages carefully, contact the sane-devel +mailing list for help (see REPORTING BUGS below). +.PP +Now that your scanner is found by +.BR "scanimage -L" , +try to do a scan: +.BR "scanimage >image.pnm" . +This command starts a scan for the default scanner with default settings. All +the available options are listed by running +.BR "scanimage --help" . +If scanning aborts with an error message, turn on debugging as mentioned +above. Maybe the configuration file needs some tuning, e.g. to setup the path +to a firmware that is needed by some scanners. See the backend's maunal page +for details. If you can't find out what's wrong, contact sane-devel. +.PP +To check that the +.B SANE +libraries are installed correctly you can use the test backend, even if you +don't have a scanner or other +.B SANE +device: +.IP +.B scanimage \-d +.I test +.B \-T +.PP +You should get a list of PASSed tests. You can do the same with your backend +by changing "test" to your backend's name. +.PP +So now scanning with +.B scanimage +works and you want to use one of the graphical frontends like +.BR xsane , +.BR xscanimage ", or" +.B quiteinsane +but those frontends don't detect your scanner? One reason may be that you +installed two versions of +.BR SANE . +E.g. the version that was installed by your distribution in +.I /usr +and one you installed from source in +.IR /usr/local/ . +Make sure that only one version is installed. Another possible reason is, that +your system's dynamic loader can't find the +.B SANE +libraries. For Linux, make sure that +.I /etc/ld.so.conf +contains +.I /usr/local/lib +and does +.B not +contain +.IR /usr/local/lib/sane . +See also the documentation of the frontends. +.PP + +.SH "HOW CAN YOU HELP SANE" +We appreciate any help we can get. Here are some topics on which you can work: +.TP +.B Writing backends +Without a backend, a scanner doesn't work. So it's crucial we have backends +for as much devices as possible. It's not necessary to be an experienced +programmer to start writing a backend. If you have an unsupported scanner, +writing a backend yourself is probably the only way to get it supported. See +DEVELOPER'S DOCUMENTATION for details. But first make sure that you get any +information about your scanner that is available (see below), and check if +your scanner can be supported by an already existing backend with only small +modifications. +.TP +.B Writing frontends +There are already some very capable frontends. So helping with improving the +existing frontends may make more sense than to write yet another one. On the +other hand there may be reasons to start writing a completely new frontend, +like support for a specific widget set, a programming language or a special +type of devices (e.g. cameras, slide scanners). In any case, keep the +sane-devel mailinglist informed of your plans. +.TP +.B Reporting unsupported scanners +Even if you can't write a backend for your unsupported scanner, please send us +all the information you have about it. We need the make and the model name of +your scanner. Also provide an output of +.BR "sane-find-scanner -v -v" . +For Linux: If it's a SCSI scanner, show us the output of +.BR "cat /proc/scsi/scsi" , +for a USB scanner: +.B "cat /proc/bus/usb/devices" +(if the file is not there, do +.BR "mount -t usbdevfs /proc/bus/usb /proc/bus/usb" ). +See CONTACT section. +.TP +.B Reporting bugs and missing features +If you think something in +.B SANE +isn't working as it should, please don't hesiate to contact us (see COTACT +scetion). Please provide as many details as possible. Describe which software +you are using (operating system + version, distribution, version of +sane-backends and of the frontend you use). Explain exactly what doesn't work, +is wrong or missing. +.TP +.B Adding and fixing documentation +If you found a bug in any documentation (man pages, web site, READMEs), please +contact us (see CONTACT section). Also write us if you think some +documentation is missing. Please include a patch in this case, if +possible. Don't hesitate to send spelling and grammar mistakes. +.TP +.B Translations +The options of the backends can be translated. For some languages, the +translations are almost complete, but some are lacking a lot of words and for +most languages there is no translation at all. If you want to help to +translate the options to your native language (or a language you speak +fluently), contact the sane-devel mailing list and have a look at the +.I po/ +directory in the source code. +.TP +.B Success reports +If you had success using +.B SANE +we want to know about that, too. Especially if your scanner is not in the +lists yet or is marked "untested". + +.SH "CONTACT" +If you want to comment on a backend-specific problem, contact the author of +your backend. Usually the email address can be found in the .I @DOCDIR@/AUTHORS file or the backend's manpage. If the author isn't marked as `active maintainer' or doesn't answer, you can also contact the