README for the Umax scanner driver version 0.5.6
================================================

GENERAL INFORMATIONS:
=====================
  The umax scanner driver is still in alpha state, a lot of bugs are already
  removed, but there are still some known and I think a lot of unknown bugs.

          **************************************************
          *                                                *
          *   In any case, proceed at your own risk. !!!   *
          *                                                *
          **************************************************

  The SCSI-adapter that are shipped with some UMAX-scanner are not supported
  by Linux, you have to buy a supported SCSI-adapter.

  Linux 2.0 works better with UMAX scanners than previous versions, because
  SCSI error handling has been improved, and UMAX scanners more or less
  assume that they are the only active device on the SCSI bus and like to
  reset it on a regular basis.  You will probably find that things work
  best if you have a separate SCSI adapter for the scanner.
  (But I (Oliver Rauch) connected my harddisc and my scanner to the same
  SCSI adapter and don't have any problems, so it may work!)


DOCUMENTATIONS:
===============
  Please read the documentations with thorrowness. There are
  the following files wich contain important informations:
  ============================================================================
   README               this file, general and compile informations
   README.SANE          how to install new version of sane-backend in SANE
   BUGS                 known bugs, PLEASE READ IT !!!
   FEEDBACK-FORM.CLI    Please read this, fill it out and send it back
   FEEDBACK-FORM.SANE   if you use sane, please send this back, too
   SUPPORTED_SCANNERS   a list of supported scanners
   CHANGES.CLI          changes that have been done for UMAX-CLI
   CHANGES.SANE         changes that have been done for the SANE-backend
   CHANGES.LOWLEVEL     changes on parts that are used in SANE and UMAX-CLI
   TODO.CLI             things that should be done with umax-cli
   TODO.SANE            things that should be done with SANE-backend
   TODO.LOWLEVEL        things that should be done with the lowleve-parts
   DEVELOPPERS          short developpers information
   DEBUG_LEVEL.TXT      a list of the debug-levels for UMAX-CLI and SANE_UMAX
  ============================================================================


COMPILING AND INSTALLING UMAX-CLI:
==================================
  If you are still interested, you should build the driver with the command
    make

  Copy the binary and the manpage somewhere useful, or do
    make install
  or
    make install-german
  as root and the files umax-cli and umaX-scan will be copied to /usr/local/bin
  and the english or german manpage will be copied to /usr/local/man/man1.


BEFORE YOU DO ANYTHNIG ELSE:
============================
  Run the umax driver (umax-cli) as a user who is able to read and write the
  /dev/sg? device the scanner is mounted on.  

  If you aren't sure to which device the scanner is mounted,
  you can run umax-cli as root and let it find the scanner:
  umax-cli -v 4 -I 2>&1 | head -1
  will tell you where it finds the scanner, or if it doesn't
  find the scanner.

  I suggest to set a symbolic link /dev/scanner that points to
  the device, on which the scanner is mounted, do as root
  (with "?" replaced by the right number or letter):
  ln -s /dev/sg? /dev/scanner


  If the driver complains about unsupported scanner, have a look
  at the option --continue.


umax-cli/umaX-scan:
==================
  umax-cli is a shell-interface for the umax-driver.

  In order to get a scan, you have to choose the scan mode:
  lineart (1-bit), dithered (1-bit), greyscale (8-bit) or rgb color (24-bit).
  Even with the Windows drivers for this scanner, the 8-bit color scans are
  done as 24-bit scans and dithered to 8 bits; use the pnmquant program to do
  this for you if you need it done. The command line options are -l for
  lineart, -d for dithered, -g for greyscale, and -r for rgb.

  In order to get help, read the man-page (man umax-cli) or do
    umax-cli -H

  To get a first scan, do
    umax-cli -R100 -w200 -h200 -g >first_scan.pgm

  The output is pnm: Portable aNyMap. That is, lineart and
  halftone scans are output as pbm (Portable BitMap), greyscale
  scans are output as pgm (Portable GreyMap), and color scans
  are output as ppm (Portable PixMap).

  We recommend the pbm tools (either the netpbm or pbmplus versions) and
  possibly an image manipulation toolset such as ImageMagick or The GIMP for
  doing image manipulation when you are done scanning.

  umaX-scan is a simple graphical-user-interface (tk/tcl-script) and uses
  umax-cli to do the scan.


SANE:
=====
  SANE (Scanner Acces Now Easy) is a try to generate a common interface
  between scanner-drivers and scanner-software (Frontends). You can compare
  it a bit to TWAIN in the Windows-World. If you are intersited in it, have
  a look at

           http://www.azstarnet.com/~axplinux/sane/

  If the scanner-name is not listed as supported scanner, you will not be able
  to use SANE. Please try the shell-interface "umax-cli" with option --continue
  (see docs) and if that works, contact me so that I can add your scanner to
  the list.


IF YOU HAVE PROBLEMS:
=====================
  At first read the documentations, the solution of the most (known) problems
  are described in this text or in the man-page.

  Report any problems to
    Oliver Rauch <Oliver.Rauch@Wolfsburg.DE>.

  In order to print the version number, use umax-cli -V
  Please say, which driver-version you are using.

  It would be nice, if you would send the output of the follwing command to
  Oliver Rauch <Oliver.Rauch@Wolfsburg.DE>:
    umax-cli -I 2>scanner_inquiry.txt
  or if the scanner is unknown:
    umax-cli -I --continue 2>scanner_inquiry.txt
  and say if it works or not and - if there is no UMAX-label at the scanner -
  mention the name of the scanner.


Missing /usr/include/scsi on Linux systems:
===========================================
  Older Linux distributions are missing the /usr/include/scsi directory. In
  such a case, it is necessary to set a link to the relevant directory of the
  kernel distribution. Normally, the command:

    ln -s /usr/src/linux/include/scsi /usr/include/scsi

  should fix this problem.


INCREASING SCSI-BUFFER-SIZE:
============================
  On Linux-systems, the SCSI-buffer is only 32KB. That slows down the scanning
  speed and sometimes forces problems while scanning large images, so I suggest
  to increase the size to 127.5KB. For that you have to edit
    /usr/include/scsi/sg.h
  and change 
    #define SG_BIG_BUFF 32768 
  to
    #define SG_BIG_BUFF 130560
  then you have to recompile and install the kernel/modules, reboot and
  (re)compile the umax-driver.


OTHER THINGS:
=============
  Have a look at the directory ohter-things. There is an example for a program
  that adds and removes a umax-scanner from the SCSI-device-list, so you
  (possibly) don't have to switched the scanner on while booting linux.


Developper Information
======================
  I hope there will be no reason for you to add support to a new UMAX scanner,
  because the driver should do it by itself (--continue). But there are some
  scan-options that do not work with all scanners. If you like to support the
  umax-driver have a look at the DEVELOPPERS file or contact me.



PROGRAMMERS :
=============
  The author of the umax-driver originally is
    Michael K. Johnson <johnsonm@redhat.com>
  He programmed the driver until version 0.5. In future he may be the author
  of following versions too.

  I (Oliver Rauch) wrote the versions 0.5.1 to 0.5.6



         THANKS FOR READING THIS FILE!

   Oliver Rauch <Oliver.Rauch@Wolfsburg.DE>.
