diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 99 | ||||
| -rw-r--r-- | doc/sane.png | bin | 0 -> 10753 bytes | |||
| -rw-r--r-- | doc/scanadf.man | 268 | ||||
| -rw-r--r-- | doc/xcam.man | 79 | ||||
| -rw-r--r-- | doc/xscanimage.man | 165 |
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 Binary files differnew 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 |
