Updated, mostly concerning kernel scanner driver (deprecated). Minor fixes.

ChangeLog

@@ -2,6 +2,9 @@
 
 	* doc/descriptions-external/samsung.desc: Status of Samsung
 	  SCX-4100 is "good" asit's reported to work.
+	* doc/sane-usb.man doc/sane.man: Updated, mostly concerning kernel
+	  scanner driver (deprecated). Minor fixes.
+
 
 2005-05-28  Henning Meier-Geinitz <henning@meier-geinitz.de>
 

doc/sane-usb.man

@@ -1,4 +1,4 @@
-.TH sane-usb 5 "8 Mar 2004"  "@PACKAGEVERSION@" "SANE Scanner Access Now Easy"
+.TH sane-usb 5 "29 May 2005"  "@PACKAGEVERSION@" "SANE Scanner Access Now Easy"
 .IX sane-usb
 .SH NAME
 sane-usb \- USB configuration tips for SANE
@@ -9,12 +9,10 @@ operating system kernel and using it with SANE.
 .PP
 This page applies to most backends and scanners, as they use the generic
 sanei_usb interface. However, there are some exceptions: USB Scanners
-supported by the avision and microtek2 backends need special USB kernel
+supported by the microtek2 backend need a special USB kernel
-drivers, see
+driver, see
-.BR sane-avision (5)
-and
 .BR sane-microtek2 (5)
-for details. The sm3600 backend supports only access via libusb. See the
+for details. The sm3600 backend accesses scanners over libusb dierctly. See the
 appropriate section in this manpage and
 .BR sane-sm3600 (5).
 
@@ -28,53 +26,27 @@ product ids, you are done. See section
 .B "SANE ISSUES"
 for details on how to go on.
 .PP
-Sane-find-scanner lists your scanner, but can't detect the vendor- and product
-ids? Scanning may work nevertheless, just try with section
-.BR "SANE ISSUES" .
-If it doesn't, install libusb (see section
-.BR LIBUSB )
-or, if you use Linux, upgrade your kernel (see section
-.BR "GENERIC KERNEL SCANNER DRIVER" ).
-.PP
 Sane-find-scanner doesn't list your scanner? Does it work as root? If yes,
-there is a permission issue. If sane-find-scanner lists a device name starting with 
+there is a permission issue. See the
-.IR libusb: ,
+.B LIBSUB
-read
+section for details.
-.BR LIBUSB ,
-otherwise have a look at the section
-.BR "GENERIC KERNEL SCANNER DRIVER" ).
 .PP
-Nothing is found even as root? Either install libusb (see section
+Nothing is found even as root? Check that your kernel supports USB and that
-.BR LIBUSB ),
+libusb is installed (see section
-or make sure, that the kernel scanner driver knows the ids of your scanner
+.BR LIBUSB ).
-(see section
-.BR "GENERIC KERNEL SCANNER DRIVER" ).
 
 .SH "USB ACCESS METHODS"
-Two methods for accessing USB devices are currently in use: direct access
+For accessing USB devices, the USB library libusb is used. There used to exist
-using the kernel scanner driver and access over libusb. By default, both
+another method to access USB devices: the kernel scanner driver. The kernel
-methods are tried by SANE, if they are available. Currently USB access is
+scanner driver method is deprecated and shouldn't be used anymore. It may be
-tested for Linux (kernel, libusb), FreeBSD (kernel, libsub), NetBSD (libusb),
+removed from SANE at any time. In Linux, the kernel scanner driver has been
-OpenBSD (kernel, libusb) and MacOS X (libusb). Testing on MacOS X is very
+removed in the 2.6.* kernel series. Only libusb access is documented in this
-limited and not all scanners seem to work reliably with the BSDs. For
+manual page.
-installation issues, also check the @DOCDIR@/README.platform files. The scanner
-module is on longer available on Linux 2.6 and later. Use libusb instead.
-.PP
-Generally speaking, if your scanner works with one method, there is no need to
-switch to the other one.
-.PP
-Libusb is the more general approach and is able to access any scanner. Also,
-it supports more platforms.
-.PP
-Autodetecting scanners and using USB control messages with the kernel access
-method only works with recent (>=v2.4.12) Linux kernels.  If you need one of
-these two features on a different platform, use libusb instead. Also, the
-kernel scanner driver may be removed from Linux 2.5/2.6 in future so libusb
-will be the only access method.
 
 .SH LIBUSB
 SANE can only use libusb 0.1.6 or newer. It needs to be installed at
-build-time.
+build-time. Modern Linux distributions and other operating systems come with
+libusb.
 .PP
 Libusb can only access your scanner if it's not claimed by the kernel scanner
 driver. If you want to use libusb, unload the kernel driver (e.g. rmmod
@@ -95,72 +67,21 @@ the devices are located in /proc/bus/usb/. There are directories named
 e.g. "001" (the bus name) containing files "001", "002" etc. (the device
 files). The right device files can be found out by running scanimage -L as
 root. Setting permissions with "chmod" is not permanent, however. They will be
-resetted after reboot or replugging the scanner. In Linux versions before 2.6 it
+reset after reboot or replugging the scanner.
-was also possible to mount the usbfs with the option "devmode=0666", e.g. by
-using the following line in /etc/fstab:
 .PP
-.RS
+Usually the the hotplug utilities
-none /proc/bus/usb usbfs defaults,devmode=0666  0  0
+.RI ( http://linux-hotplug.sourceforge.net/ ") are used, "
-.RE
-.PP
-.B DUE TO A KERNEL BUG THIS WON'T WORK WITH CURRENT 2.6 KERNELS. USE HOTPLUG INSTEAD
-.PP
-However, this way everyone has access to all USB devices. Another way to set
-permissions is to use the hotplug utilities
-.RI ( http://linux-hotplug.sourceforge.net/ ),
 which support dynamic setting of access permissions. SANE comes with hotplug
 scripts in the directory tools/hotplug. They can be used for setting
-permissions.  Last, the frontends can be run as root. However, that's not
+permissions.  Precompiled SANE packages may have already installed such hotplug
-recommended for security reasons.
+scrips in /etc/hotplug/.
 .PP
 For the
 .BR BSDs ,
-the device files are named 
+the device files used by libusb are named 
 .IR /dev/ugen* .
 Use chmod to apply appropriate permissions.
 
-.SH "GENERIC KERNEL SCANNER DRIVER"
-Ensure that the access permissions for the USB device are set appropriately.
-We recommend to add a group "scanner" to 
-.I /etc/group
-which contains all users that should have access to the scanner.  The
-permission of the device should then be set to allow group read and write
-access.  For example, if the scanner is at USB device
-.BR /dev/usb/scanner0 ,
-then the following two commands would set the permission correctly:
-.PP
-.RS
-$ chgrp scanner /dev/usb/scanner0
-.br
-$ chmod 660 /dev/usb/scanner0
-.RE
-.PP
-If your scanner isn't detected automatically by your operating system's
-scanner driver, you need to tell the kernel the vendor and product ids of your
-scanner. For 
-.BR Linux ,
-this can be done with modprobe parameters: First, remove the scanner module
-.RI ( "rmmod scanner" ),
-then load it again: 
-.IR "modprobe scanner vendor=0x0001 product=0x0002" .
-Use the appropriate vendor and product ids (e.g. from 
-.IR /var/log/messages ,
-.IR dmesg ,
-or
-.IR "cat /proc/bus/usb/devices" ).
-Some scanners supported by the gt68xx backend are not supported by the current
-version of the generic scanner driver. See
-.BR sane-gt68xx (5)
-for details. For these scanners, there will be a message concerning "only 2 or
-three endpoints" in syslog.
-.PP
-For OpenBSD the kernel may need to be recompiled. For details look at
-@DOCDIR@/README.openbsd. Similar approaches should be used for the other BSDs.
-.PP
-Linux kernel messages in syslog like "kernel: scanner.c: open_scanner(1):
-Unable to access minor data" can be ignored. They are generated when SANE
-scans all available USB devices for scanners.
-
 .SH "SANE ISSUES"
 .PP
 This section assumes that your scanner is detected by sane-find-scanner. It
@@ -184,11 +105,11 @@ where
 .I VENDOR
 is the USB vendor id, and
 .I PRODUCT
-is the USB product id of the scanner. Both ids are non-negative integer
+is the USB product id of the scanner. Both ids are non-negative integer numbers
-numbers in decimal or hexadecimal format. The correct values for these fields
+in decimal or hexadecimal format. The correct values for these fields can be
-can be found by looking into the syslog (e.g., /var/log/messages) or under
+found by running sane-find-scanner, looking into the syslog (e.g.,
-Linux by issuing the command "cat /proc/bus/usb/devices/".  This is an example
+/var/log/messages) or under Linux by issuing the command "cat
-of a config file line:
+/proc/bus/usb/devices/".  This is an example of a config file line:
 .PP
 .RS
 usb 0x055f 0x0006
@@ -200,18 +121,8 @@ backend.
 .PP
 If your scanner is not detected automatically, it may be necessary to edit the
 appropriate backend configuration file before using SANE for the first time.
-For most systems, the configuration file should list the name of the USB
+For a detailed description of each backend's configuration file, please refer to
-device file that the scanner is connected to (e.g., under Linux,
+the relevant backend manual page (e.g.
-.B /dev/usb/scanner0
-or
-.B /dev/usbscanner0
-is such a USB device, the device file for FreeBSD is e.g.
-.BR /dev/uscanner0 ).
-If libusb is used, the device name looks like the following example:
-.BR libusb:001:002 .
-.PP
-For a detailed description of each backend's configuration file, please refer
-to the relevant backend manual page (e.g. 
 .BR sane-mustek_usb (5)
 for Mustek USB scanners).
 .PP
@@ -238,4 +149,4 @@ libusb debugging (if available). Example: export SANE_DEBUG_SANEI_USB=4.
 .BR sane-scsi (5)
 
 .SH AUTHOR
-Henning Meier-Geinitz
+Henning Meier-Geinitz <henning@meier-geinitz.de>

doc/sane.man

@@ -1,4 +1,4 @@
-.TH sane 7 "20 Feb 2005" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy"
+.TH sane 7 "29 May 2005" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy"
 .IX sane
 
 .SH NAME
@@ -52,9 +52,9 @@ Both packages can be downloaded from the
 .B SANE
 homepage 
 .RI ( http://www.sane\-project.org/ ).
-Information about other frontends and backends can be found on the frontend
+Information about other frontends and backends can also be found on the
-page
+.B SANE
-.RI ( http://www.sane\-project.org/sane\-frontends.html ).
+homepage.
 
 .SH "GENERAL INFORMATION"
 The following sections provide short descriptions and links to more
@@ -91,11 +91,11 @@ current development version and a search engine:
 The lists are also installed on your system at @DOCDIR@/.
 .TP
 .B SANE mailing list
-There is a mailing list for the purpose of discussing the SANE standard and
+There is a mailing list for the purpose of discussing the SANE standard and its
-its implementations: sane-devel.  Despite its name, the list is not only
+implementations: sane-devel.  Despite its name, the list is not only intended
-intended for developers, but also for users. Since this is currently the only
+for developers, but also for users. There are also some more lists for special
-mailing list devoted to SANE, it's perfectly OK to ask questions that are not
+topics, however, for users, sane-devel is the right list. How to subscribe and
-strictly related to SANE development. How to subscribe and unsubscribe:
+unsubscribe:
 .IR http://www.sane\-project.org/mailing\-lists.html .
 .TP
 .B SANE IRC channel
@@ -105,7 +105,9 @@ network (irc.freenode.net). It's for discussing
 problems, talking about development and general 
 .B SANE
 related chatting. Before asking for help, please read the other documentation
-mentioned in this manual page.
+mentioned in this manual page. The channel's topic is also used for
+announcements of problems with SANE infrastructure (mailing lists, web server,
+etc.).
 .TP
 .B Compiling and installing SANE
 Look at
@@ -714,7 +716,7 @@ See also the documentation of the frontends.
 .PP
 
 .SH "HOW CAN YOU HELP SANE"
-We appreciate any help we can get. Please have alook at our web page about
+We appreciate any help we can get. Please have a look at our web page about
 contributing to 
 .BR SANE :
 .I http://www.sane\-project.org/contrib.html