Initial import of sane-frontends version 1.0.14-9

author: Jörg Frings-Fürst <debian@jff-webhosting.net> 2014-12-02 20:17:04 +0100
committer: Jörg Frings-Fürst <debian@jff-webhosting.net> 2014-12-02 20:17:04 +0100
commit: 7d8191b83e163d76bb05e13b373638e4eeb7da95 (patch)
tree: fe29c36a3cb4ef2267b2253da4dde8ce360b3cb5 /doc
5 files changed, 611 insertions, 0 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 0000000..2212f24
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,99 @@
+SHELL = /bin/sh
+
+VPATH = @srcdir@
+srcdir = @srcdir@
+top_srcdir = @top_srcdir@
+top_builddir = ..
+
+PACKAGE = @PACKAGE@
+VERSION = @VERSION@
+distdir = $(top_srcdir)/$(PACKAGE)-$(VERSION)
+
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+bindir = @bindir@
+sbindir = @sbindir@
+libexecdir = @libexecdir@
+datadir = @datadir@
+sysconfdir = @sysconfdir@
+sharedstatedir = @sharedstatedir@
+localstatedir = @localstatedir@
+libdir = @libdir@
+infodir = @infodir@
+mandir = @mandir@
+includedir = @includedir@
+oldincludedir = /usr/include
+configdir = ${sysconfdir}/sane.d
+sanedatadir = ${datadir}/sane
+docdir=$(prefix)/doc/sane-@VERSION@
+
+MKDIR = $(top_srcdir)/mkinstalldirs
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_DATA = @INSTALL_DATA@
+LN_S = @LN_S@
+
+@SET_MAKE@
+
+SECT1	= xscanimage.1 xcam.1 scanadf.1
+MANPAGES = $(SECT1)
+LATEX	= TEXINPUTS=$(srcdir):$$TEXINPUTS latex
+DLH	= TEXINPUTS=$(srcdir):$$TEXINPUTS dlh
+MAN2HTML= nroff -man |\
+	  man2html -compress -topm 6 -botm 6 -nodepage \
+          -title $${page} -cgiurl '$$title.$$section.html'|\
+	  sed 's,<BODY>,<BODY BGCOLOR=\#FFFFFF TEXT=\#000000><H1 ALIGN=CENTER><IMG SRC="/images/sane.png" HEIGHT=117 WIDTH=346></H1>,'
+
+DISTFILES = Makefile.in sane.png xcam.man xscanimage.man scanadf.man
+
+.PHONY: all clean depend dist html html-man install ps uninstall
+
+all: $(MANPAGES)
+
+%.1: %.man
+	@sed -e 's|@DATADIR@|$(datadir)|g' \
+	    -e 's|@CONFIGDIR@|$(configdir)|g' \
+	    -e 's|@LIBDIR@|$(libdir)|g' \
+	    -e 's|@BINDIR@|$(bindir)|g' \
+	    -e 's|@SBINDIR@|$(sbindir)|g' $^ >$@
+	@echo Generating manpage $@...
+
+install: $(MANPAGES)
+	$(MKDIR) $(DESTDIR)$(mandir)/man1
+	@for page in $(SECT1); do \
+	  echo installing $${page} in $(mandir)/man1/$${page}...; \
+	  $(INSTALL_DATA) $${page} $(DESTDIR)$(mandir)/man1/$${page} \
+            || exit 1; \
+	done
+
+uninstall:
+	@for page in $(SECT1); do \
+	  echo Removing $${page} in $(mandir)/man1/$${page}...; \
+	  rm -f $(mandir)/man1/$${page} ; \
+	done
+
+html-man: $(MANPAGES)
+	@for page in $(MANPAGES); do \
+	  echo "translating $${page} to $${page}.html..."; \
+	  cat $${page} | $(MAN2HTML) > $${page}.html; \
+	done
+
+clean:
+	rm -f *.toc *.aux *.log *.cp *.fn *.tp *.vr *.pg *.ky *.blg *.idx *.cb
+	rm -f *.ilg
+
+distclean: clean
+	rm -f $(MANPAGES)
+	for manpage in $(MANPAGES) ; do \
+	  rm -f $${manpage}.html ; \
+	done
+	rm -f Makefile *~
+	rm -f *.lot *.lof *.ind
+
+depend:
+
+dist: $(DISTFILES)
+	for file in $(DISTFILES); do \
+	  ln $$file $(distdir)/doc 2> /dev/null \
+	    || cp -p $$file $(distdir)/doc ; \
+	done
diff --git a/doc/sane.png b/doc/sane.png
new file mode 100644
index 0000000..d8a9890
--- /dev/null
+++ b/doc/sane.png
diff --git a/doc/scanadf.man b/doc/scanadf.man
new file mode 100644
index 0000000..f20243e
--- /dev/null
+++ b/doc/scanadf.man
@@ -0,0 +1,268 @@
+.TH scanadf 1 "30 Oct 2004"
+.IX scanadf
+.SH NAME
+scanadf - acquire multiple images from a scanner equipped with an ADF
+.SH SYNOPSIS
+.B scanadf
+.RB [ -d | --device-name
+.IR dev ]
+.RB [ -h | --help ]
+.RB [ -L | --list-devices ]
+.RB [ -v | --verbose ]
+.RB [ -V | --version ]
+.RB [ -o | --output-file
+.IR name ]
+.RB [ -N | --no-overwrite ]
+.RB [ -S | --scan-script
+.IR name ]
+.RB [ --script-wait ] 
+.RB [ -s | --start-count
+.IR num ]
+.RB [ -e | --end-count
+.IR num ]
+.RB [ -r | --raw ]
+.RI [ device-specific-options ]
+.SH DESCRIPTION
+.B scanadf
+is a command-line interface to control image acquisition devices which
+are capable of returning a series of images (e.g. a scanner with an
+automatic document feeder (ADF)).  The device is controlled via
+command-line options.  After command-line processing,
+.B scanadf
+normally proceeds to acquire a series of images until the device returns
+the
+.B SANE_STATUS_NO_DOCS
+status code.  
+.PP
+The images are written to output files, specified by the
+.B --output-file
+option.  These files are typically written in one of the PNM (portable aNyMaP) 
+formats (PBM for black-and-white images, PGM for grayscale images, 
+and PPM for color images).  Several optional frame formats (SANE_FRAME_JPEG, 
+SANE_FRAME_G31D, SANE_FRAME_G32D, SANE_FRAME_G42D, and SANE_FRAME_TEXT)
+are supported.  In each case, the data is written out to the output file
+as-is without a header.  Unrecognized frame formats are handled in
+the same way, although a warning message is printed in verbose mode.
+.PP
+Typically, the optional frame formats are used in conjunction with a scan 
+script (specified by the 
+.B --scanscript
+option) which is invoked for each acquired image.  The script is provided
+with a series of environment variables which describe the parameters
+and format of the image file.
+
+.B scanadf
+accesses image acquisition devices through the SANE (Scanner Access
+Now Easy) interface and can thus support any device for which there
+exists a SANE backend (try "apropos sane\-" to get a list of available
+backends).
+.SH OPTIONS
+.PP
+The
+.B -d
+or
+.B --device-name
+options must be followed by a SANE device-name.  A (partial) list of
+available devices can be obtained with the
+.B --list-devices
+option (see below).  If no device-name is specified explicitly,
+.B scanadf
+will attempt to open the first available device.
+.PP
+The
+.B -h
+or
+.B --help
+options request help information.  The information is printed on
+standard output and in this case, no attempt will be made to acquire
+an image.
+.PP
+The
+.B -L
+or
+.B --list-devices
+option requests a (partial) list of devices that are available.  The
+list is not complete since some devices may be available, but are not
+listed in any of the configuration files (which are typically stored
+in directory @CONFIGDIR@).  This is particularly the case when
+accessing scanners through the network.  If a device is not listed in
+a configuration file, the only way to access it is by its full device
+name.  You may need to consult your system administrator to find out
+the names of such devices.
+.PP
+The
+.B -v
+or
+.B --verbose
+options increase the verbosity of the operation of
+.B scanadf.
+The option may be specified repeatedly, each time increasing the verbosity
+level.
+
+The
+.B -V
+or
+.B --version
+option requests that
+.B scanadf
+print the program and package name, as well as the version number of
+the SANE distribution that it came with.
+
+.PP
+The
+.B -o
+or
+.B --output-file
+option specifies a format string used to generate the name of file to 
+write the image data to.  You can use %d replacement in the output file
+name; this will be replaced with the current page number.  The default
+format string is image-%04d.
+
+.PP
+The
+.B -N
+or
+.B --no-overwrite
+option prevents
+.B scanadf 
+from overwriting existing image files. 
+
+.PP
+The
+.B -S
+or
+.B --scan-script
+option specifies the name of script to run after each scanned image
+is acquired.  The script receives the name of the image output file
+as its first and only command line argument.  Additionally the scan
+script can reference the following environment variables to get 
+information about the parameters of the image.
+
+.PP
+.RS
+.B SCAN_RES
+- the image resolution (in DPI)
+.br
+.B SCAN_WIDTH
+- the image width (in pixels) 
+.br
+.B SCAN_HEIGHT
+- the image height (in pixels)
+.br
+.B SCAN_DEPTH
+- the image bit-depth (in bits)
+.br
+.B SCAN_FORMAT
+- a string representing the image format (e.g. gray, g42d, text, etc)
+.br
+.B SCAN_FORMAT_ID
+- the numeric image format identifier
+.br
+.RE
+
+.PP
+If the
+.B --scipt-wait
+option is given, scanadf will wait until all scan-scripts have been finished before
+exiting. That will be useful if scanadf is used in conjunction with tools to modify
+the scanned images.
+
+.PP
+The
+.B -s
+or
+.B --start-count
+option specifies the page number of first scanned image.
+
+.PP
+The
+.B -e
+or
+.B --end-count
+option specifies the last page number to scan.  Using this option,
+you can request a specific number of pages to be scanned, rather than
+scanning until there are no more images available.
+
+.PP
+The
+.B -r
+or
+.B --raw
+option specifies that the raw image data be written to the output file
+as-is without interpretation.  This disables the writing of the PNM
+header for basic frame types.  This feature is usually used in 
+conjunction with the
+.B --scan-script
+option where the scan script uses the environment variables to
+understand the format and parameters of the image and converts
+the file to a more useful format.  NOTE: With support for the
+optional frame types and the default handling of unrecognized
+frametypes, this option becomes less and less useful.
+
+As you might imagine, much of the power of
+.B scanadf
+comes from the fact that it can control any SANE backend.  Thus, the
+exact set of command-line options depends on the capabilities of the
+selected device.  To see the options for a device named
+.IR dev ,
+invoke
+.B scanadf
+via a command-line of the form:
+.PP
+.RS
+scanadf --help --device
+.I dev
+.RE
+.PP
+The documentation for the device-specific options printed by
+.B --help
+is explained in the manual page for
+.B scanimage.
+
+.SH FILES
+.TP
+.I @CONFIGDIR@
+This directory holds various configuration files.  For details, please
+refer to the manual pages listed below.
+.SH "SEE ALSO"
+scanimage(1), xscanimage(1), sane(7)
+
+.SH AUTHOR
+scanadf is an adaptation by Tom Martone of scanimage by David Mosberger, 
+Andreas Beck, and Gordon Matzigkeit following closely the features of
+bnhscan by Sean Reifschneider of tummy.com, ltd.
+
+.SH BUGS
+Please send reports to 
+.IR sane\-devel@lists.alioth.debian.org .
+.PP
+This program relies on the backend to return the 
+.B SANE_STATUS_NO_DOCS
+status code when the automatic document feeder is out of paper.  Use of
+this program with backends that do not support ADFs (e.g. flatbed scanners) 
+will likely result in repeated scans of the same document.  In this
+case, it is essential to use the start-count and end-count to
+control the number of images acquired.
+
+.PP
+Only a subset of the SANE backends support feeders and return
+SANE_STATUS_NO_DOCS appropriately.  Backends which are known to
+work at this time are:
+
+.RS
+.br
+.B sane-bh
+- Bell+Howell Copiscan II series scanners.
+.br
+.B sane-hp
+- Hewlett Packard scanners.  A patch to the sane-hp backend 
+is necessary.  The --scantype=ADF option must be specified (earlier
+versions of the backend used the --scan-from-adf option, instead).
+.br
+.B sane-umax
+- UMAX scanners.  Support exists in build 12 and later.
+The --source="Automatic Document Feeder" option must be specified.
+.br
+.RE
+
+
diff --git a/doc/xcam.man b/doc/xcam.man
new file mode 100644
index 0000000..036bcb3
--- /dev/null
+++ b/doc/xcam.man
@@ -0,0 +1,79 @@
+.TH xcam 1 "11 April 2005"
+.IX xcam
+.SH NAME
+xcam - a graphical camera frontend for SANE
+.SH SYNOPSIS
+.B xcam
+.RB [ --buffer | -B  ]
+.RB [ --version | -V ]
+.RB [ --help | -h ]
+
+.SH DESCRIPTION
+.B xcam
+provides a graphical user-interface to control an image
+acquisition device such as a flatbed scanner or a camera.  It allows
+scanning invidual images and can be invoked directly from the command-line.
+
+.B xcam
+acts as a stand-alone program that saves acquired images in a suitable
+PNM format (PBM for black-and-white images, PGM for grayscale images,
+and PPM for color images).
+
+.B xcam
+accesses image acquisition devices through the SANE (Scanner Access
+Now Easy) interface.  The list of available devices depends on
+installed hardware and configuration.
+
+.B xcam
+presents a menu listing of all known and available devices.
+
+.SH OPTIONS
+.PP
+If the
+.B --Buffer (-B)
+option is given,
+.B xcam 
+will use a 1024 kByte input buffer instead of the default 32 kByte.
+.PP
+If the
+.B --version (-V)
+option is given, 
+.B xcam
+will output its version number.
+.PP
+The
+.B --help (-h)
+.B xcam
+flag prints a short summary of options.
+.PP
+.TP
+.B SANE_DEBUG_XCAM
+This environment variable controls the debug level xscanimage.  Higher
+debug levels increase the verbosity of the output.
+
+              Value  Descsription
+              0      print fatal errors
+              1      print errors
+              2      print warnings
+              3      print information messages
+              4      print everything
+
+              Example:
+              SANE_DEBUG_XCAM=3
+
+.SH FILES
+.TP
+.I $HOME/.sane/xcam/devicename.rc
+For each device, there is one rc-file that holds the saved settings
+for that particular device.  Normally, this file should not be
+manipulated directly.  Instead, the user should use the
+.B xcam
+interface to select appropriate values and then save the device
+settings using the "Preferences->Save as default settings" menubar entry.
+
+.SH "SEE ALSO"
+sane(7), xscanimage(1), scanimage(1), sane\-dll(5) and the backend manpages
+.SH AUTHOR
+David Mosberger-Tang 
+
+Gerard Klaver (2005 update)
diff --git a/doc/xscanimage.man b/doc/xscanimage.man
new file mode 100644
index 0000000..58cfe39
--- /dev/null
+++ b/doc/xscanimage.man
@@ -0,0 +1,165 @@
+.TH xscanimage 1 "1 Feb 2003"
+.IX xscanimage
+.SH NAME
+xscanimage \- scan an image
+.SH SYNOPSIS
+.B xscanimage
+.RB [ --version | -V ]
+.RB [ --help | -h ]
+.RB [ --display
+.IR d ]
+.RB [ --no-xshm ]
+.RB [ --sync ]
+.RI [ devicename ]
+.SH DESCRIPTION
+.B xscanimage
+provides a graphical user-interface to control an image
+acquisition device such as a flatbed scanner or a camera.  It allows
+previewing and scanning invidual images and can be invoked either
+directly from the command-line or through The GIMP image manipulation
+program.  In the former case,
+.B xscanimage
+acts as a stand-alone program that saves acquired images in a suitable
+PNM format (PBM for black-and-white images, PGM for grayscale images,
+and PPM for color images).  In the latter case, the images are
+directly passed to The GIMP for further processing.
+
+.B xscanimage
+accesses image acquisition devices through the SANE (Scanner Access
+Now Easy) interface.  The list of available devices depends on
+installed hardware and configuration.  When invoked without an
+explicit devicename argument,
+.B xscanimage
+presents a dialog listing of all known and available devices. If the
+environment variable SANE_DEFAULT_DEVICE is set to the devicename, the device
+is preselected in the dialog. To access an available device that is not known
+to the system, the devicename must be specified explicitly. The format of
+devicename is backendname:devicefile (e.g. umax:/dev/sga).
+.SH RUNNING UNDER THE GIMP
+To run
+.B xscanimage
+under the
+.BR gimp (1),
+simply copy it to one of the
+.BR gimp (1)
+plug-ins directories.  If you want to conserve disk-space, you can
+create a symlink instead.  For example, for gimp-1.0.x the command
+.PP
+ln -s @BINDIR@/xscanimage ~/.gimp/plug-ins/
+.PP
+and for gimp-1.2.x the command
+.PP
+ln -s @BINDIR@/xscanimage ~/.gimp-1.2/plug-ins/
+.PP
+adds a symlink for the
+.B xscanimage
+binary to the user's plug-ins directory.  After creating this symlink,
+.B xscanimage
+will be queried by
+.BR gimp (1)
+the next time it's invoked.  From then on,
+.B xscanimage
+can be invoked through "File->Acquire->Xscanimage->Device dialog..." menu entry.
+
+You'll also find that the "File->Acquire->Xscanimage" menu contains short-cuts
+to the SANE devices that were available at the time
+.B xscanimage
+was queried.  For example, the first PNM pseudo-device is typically
+available as the short-cut "File->Acquire->Xscanimage->pnm:0".
+Note that
+.BR gimp (1)
+caches these short-cuts in ~/.gimp/pluginrc.  Thus, when the list of
+available devices changes (e.g., a new scanner is installed), then it
+is typically desirable to rebuild this cache.  To do this, you can
+either
+.BR touch (1)
+the
+.B xscanimage
+binary (e.g., "touch @BINDIR@/xscanimage") or delete the plug-ins cache
+(e.g., "rm ~/.gimp/plug-ins").  Either way, invoking
+.BR gimp (1)
+afterwards will cause the pluginrc to be rebuilt.
+.SH OPTIONS
+.PP
+If the
+.B --version (-V)
+option is given, 
+.B xscanimage
+will output its version number.
+.PP
+The
+.B --help (-h)
+flag prints a short summary of options.
+.PP
+The
+.B --display
+flag selects the X11 display used to present the graphical user-interface
+(see
+.BR X (1)
+for details).
+.PP
+The
+.B --no-xshm
+flag requests not to use shared memory images.  Shared memory images
+usually enhance performance but cause problems with some buggy X11
+servers.  Unless your X11 server dies when running this program, there
+is no need or advantage to specify this flag.
+.PP
+The
+.B --sync
+flag requests a synchronous connection with the X11 server.  This is for
+debugging purposes only.
+.SH ENVIRONMENT
+.TP
+.B SANE_DEFAULT_DEVICE
+The default device-name. Example: SANE_DEFAULT_DEVICE="hp:/dev/scanner". 
+.TP
+.B SANE_DEBUG_XSCANIMAGE
+This environment variable controls the debug level xscanimage.  Higher
+debug levels increase the verbosity of the output.
+
+              Value  Descsription
+              0      print fatal errors
+              1      print errors
+              2      print warnings
+              3      print information messages
+              4      print everything
+
+              Example:
+              SANE_DEBUG_XSCANIMAGE=3
+.SH FILES
+.TP
+.I $HOME/.sane/xscanimage/xscanimage.rc
+This files holds the user preferences.  Normally, this file should not
+be manipulated directly.  Instead, the user should customize the
+program through the "Preferences" dialog.
+.TP
+.I $HOME/.sane/xscanimage/devicename.rc
+For each device, there is one rc-file that holds the saved settings
+for that particular device.  Normally, this file should not be
+manipulated directly.  Instead, the user should use the
+.B xscanimage
+interface to select appropriate values and then save the device
+settings using the "Preferences->Save Device Settings" menubar entry.
+.TP
+.I $HOME/.sane/preview-devicename.ppm
+After acquiring a preview,
+.B xscanimage
+normally saves the preview image in this device-specific file.  Thus,
+next time the program is started up, the program can present the old
+preview image.  This feature can be turned off through the
+"Preferences->Preview Options..." dialog.
+.TP
+.I @DATADIR@/sane-style.rc
+This system-wide file controls the aspects of the user-interface such
+as colors and fonts.  It is a GTK style file and provides fine control
+over the visual aspects of the user-interface.
+.TP
+.I $HOME/.sane/sane-style.rc
+This file serves the same purpose as the system-wide style file.  If
+present, it takes precedence over the system wide style file.
+.SH "SEE ALSO"
+sane(7), gimp(1), xcam(1), scanimage(1), scanadf(1), sane-scsi(5),
+sane\-dll(5), sane\-net(5), sane\-"backendname"(5)
+.SH AUTHOR
+Tristan Tarrant, Andreas Beck, David Mosberger, and Henning Meier-Geinitz
author	Jörg Frings-Fürst <debian@jff-webhosting.net>	2014-12-02 20:17:04 +0100
committer	Jörg Frings-Fürst <debian@jff-webhosting.net>	2014-12-02 20:17:04 +0100
commit	7d8191b83e163d76bb05e13b373638e4eeb7da95 (patch)
tree	fe29c36a3cb4ef2267b2253da4dde8ce360b3cb5 /doc