SANE Backend specification files -------------------------------- The specification files (e.g. epson.desc) describe the capabilities of the backends. They provide information about the backend itself (e.g., name and version) and about the supported devices (e.g., manufacturer and product names). One file per backend should be used. Descriptions for backends included in the SANE distribution are located in `sane-backends/doc/descriptions/' while descriptions of external backends should be placed in `sane-backends/doc/descriptions-external/'. There is a special file `sane-backends/doc/descriptions/unsupported.desc' that doesn't belong to a backend but lists all (known) devices not supported by SANE. It may contain additional information about the device or links to non-SANE based programs. The specification files can be used to generate lists of backends and/or supported devices, hotplug/udev device lists, databases for search engines, and similar sources of information. Currently the creation of ASCII output and HTML lists is supported by `tools/sane-desc.c'. The generation of the HTML pages can be started by `make html-pages' in the doc/ directory. The file contents is basically emacs-lisp --- so ";" indicates comment to end of line. Empty lines are ignored. All syntactic elements are keyword tokens, followed by a string or keyword argument, as specified. All keyword tokens but ":backend" are optional. Backend-specific keyword tokens ------------------------------- The keyword `:backend' must be specified exactly once. It must be the first keyword in each specification file. It is followed by the name of the backend. Example: `:backend "epson"' The following backend-specific keyword tokens are optional. If they are used, they shouldn't be used more than once per file. `:version' has one string argument containing the backend's version number. The version should match the version used in the backend source code. Example: `:version: "12.3.5"'. If the backend isn't maintained, the version should be `unmaintained' or contain this tag together with the version number. `:new' indicates that the backend is brand-new in the latest SANE release if the keyword argument is `:yes'. Otherwise, `:no' should be used or `:new' should be omitted at all. Example: `:new :yes' The `:manpage' keyword token has one string argument that names the manual page for the backend. Example: `:manpage "sane-epson"' Device-specific keyword tokens ------------------------------ The keyword `:devicetype' starts a list of devices supported by the backend. It has one keyword argument. The following types are possible: `:scanner', `:stillcam' (still camera), `:vidcam' (video camera), `:meta' (meta backend like dll), `:api' (API like PINT). `:devicetype' can be used more than once. Each instance starts a new list of devices. Example: `:devicetype :scanner' `:mfg' has one string argument that defines the name of the manufacturer of the following devices. This keyword should be only used for hardware devicetypes (scanner, stillcam, vidcam). To avoid different spellings, the manufacturer list of the SANE standard should be used. `:mfg' can be used more than once. Example: `:mfg "Epson"'. The keyword token `:model' is used to specify the name of a hardware device in its string token. It must be preceded by a `:mfg' keyword. `:model' can be used more than once. Example: `:model "Perfection 636S"' `:interface' defines how the device is connected to the computer. Its string argument can be one or more of "SCSI", "USB", "Parport", "Serial port", "IEEE-1394", "JetDirect", "Ethernet", or "Proprietary". If neither one fits, please contact the SANE mailing list for advice. The "Parport" entries can be amended by "(SPP)", "(ECP)" and/or "(EPP)". The `:interface' keyword refers to the previous `:model', is optional and should be used only once per model. Example: `:interface "SCSI USB IEEE-1394"' `:usbid' defines the USB vendor and product ids of the device. It has two arguments which must be lower case hexadecimal (4 digits). The first one is the USB vendor id, the second one the USB product id. The keyword refers to the previous `:model', is optional, and applicable for devices with :interface "USB" only, and should be used only once per model. The special parameter "ignore" can be used if no vendor or product ids are given intentionally, e.g. for a group of scanners. Example: `:usbid "0x1234" "0x4321"' The keyword `:status' is an indication of the level of support for the model. It's followed by one of the following keyword arguments: `:unsupported', `:untested', `:minimal', `:basic', `:good', or `:complete'. The `:status' keyword refers to the previous `:model', is optional and should be used only once per model. `:unsupported' means the device is not supported at least by this backend. The keyword should only be used in the file `unsupported.desc', or to make clear that a specific scanner is not supported by a backend. `:untested' means the device may be supported but couldn't be tested. `:minimal' means that the device is detected and scans at least in one mode. But the quality is bad or important features won't work. `:basic' means it works at least in the most important modes but quality is not perfect. `:good' means the device is usable for day-to-day work. Some rather exotic features may be missing. `:complete' means the backends supports everything the device can do. Example: `:status :untested' The `:desc' keyword token is used for non-hardware devices (API and meta). Its string argument describes the meta backend or API. It should be used only once per device type. Example: `:desc "Scanners with the machine-independent PINT interface" Multi-level keyword tokens -------------------------- The following keyword tokens can be used after `:backend', `:mfg', `:model', and `:desc'. One or more `:url' keyword tokens can be used to point to more information about the entry the keyword refers to. The string argument contains a URL to e.g. a manufacturer's or backend's homepage. The most important URL should be listed first. Example: `:url "http://www.epson.com/"' `:comment' is used to add more information to one of the entries. The string argument can e.g. contain comments on the level of support for a model. Example: `:comment "US version of GT-5000"'