1SANE Backend specification files 2-------------------------------- 3 4The specification files (e.g. epson.desc) describe the capabilities of the 5backends. They provide information about the backend itself (e.g., name and 6version) and about the supported devices (e.g., manufacturer and product 7names). One file per backend should be used. Descriptions for backends 8included in the SANE distribution are located in 9`sane-backends/doc/descriptions/' while descriptions of external backends 10should be placed in `sane-backends/doc/descriptions-external/'. 11 12There is a special file `sane-backends/doc/descriptions/unsupported.desc' that 13doesn't belong to a backend but lists all (known) devices not supported by 14SANE. It may contain additional information about the device or links to 15non-SANE based programs. 16 17The specification files can be used to generate lists of backends and/or 18supported devices, hotplug/udev device lists, databases for search engines, and 19similar sources of information. Currently the creation of ASCII output and HTML 20lists is supported by `tools/sane-desc.c'. The generation of the HTML pages can 21be started by `make html-pages' in the doc/ directory. 22 23The file contents is basically emacs-lisp --- so ";" indicates comment to end 24of line. Empty lines are ignored. 25 26All syntactic elements are keyword tokens, followed by a string or keyword 27argument, as specified. All keyword tokens but ":backend" are optional. 28 29 30Backend-specific keyword tokens 31------------------------------- 32 33The keyword `:backend' must be specified exactly once. It must be the first 34keyword in each specification file. It is followed by the name of the backend. 35Example: `:backend "epson"' 36 37The following backend-specific keyword tokens are optional. If they are used, 38they shouldn't be used more than once per file. 39 40`:version' has one string argument containing the backend's version 41number. The version should match the version used in the backend source code. 42Example: `:version: "12.3.5"'. If the backend isn't maintained, the version 43should be `unmaintained' or contain this tag together with the version number. 44 45`:new' indicates that the backend is brand-new in the latest SANE release if 46the keyword argument is `:yes'. Otherwise, `:no' should be used or `:new' 47should be omitted at all. 48Example: `:new :yes' 49 50The `:manpage' keyword token has one string argument that names the manual 51page for the backend. 52Example: `:manpage "sane-epson"' 53 54 55Device-specific keyword tokens 56------------------------------ 57 58The keyword `:devicetype' starts a list of devices supported by the backend. 59It has one keyword argument. The following types are possible: `:scanner', 60`:stillcam' (still camera), `:vidcam' (video camera), `:meta' (meta backend 61like dll), `:api' (API like PINT). `:devicetype' can be used more than 62once. Each instance starts a new list of devices. 63Example: `:devicetype :scanner' 64 65`:mfg' has one string argument that defines the name of the manufacturer of 66the following devices. This keyword should be only used for hardware 67devicetypes (scanner, stillcam, vidcam). To avoid different spellings, the 68manufacturer list of the SANE standard should be used. `:mfg' can be used more 69than once. 70Example: `:mfg "Epson"'. 71 72The keyword token `:model' is used to specify the name of a hardware device in 73its string token. It must be preceded by a `:mfg' keyword. `:model' can be 74used more than once. 75Example: `:model "Perfection 636S"' 76 77`:interface' defines how the device is connected to the computer. Its string 78argument can be one or more of "SCSI", "USB", "Parport", "Serial port", 79"IEEE-1394", "JetDirect", "Ethernet", or "Proprietary". If neither one fits, 80please contact the SANE mailing list for advice. The "Parport" entries can be 81amended by "(SPP)", "(ECP)" and/or "(EPP)". The `:interface' keyword refers to 82the previous `:model', is optional and should be used only once per model. 83Example: `:interface "SCSI USB IEEE-1394"' 84 85`:usbid' defines the USB vendor and product ids of the device. It has two 86arguments which must be lower case hexadecimal (4 digits). The first one is the 87USB vendor id, the second one the USB product id. The keyword refers to the 88previous `:model', is optional, and applicable for devices with :interface "USB" 89only, and should be used only once per model. The special parameter "ignore" can 90be used if no vendor or product ids are given intentionally, e.g. for a group of 91scanners. 92Example: `:usbid "0x1234" "0x4321"' 93 94The keyword `:status' is an indication of the level of support for the model. 95It's followed by one of the following keyword arguments: `:unsupported', 96`:untested', `:minimal', `:basic', `:good', or `:complete'. The `:status' 97keyword refers to the previous `:model', is optional and should be used only 98once per model. 99`:unsupported' means the device is not supported at least by this backend. The 100keyword should only be used in the file `unsupported.desc', or to make clear 101that a specific scanner is not supported by a backend. `:untested' means the 102device may be supported but couldn't be tested. `:minimal' means that the 103device is detected and scans at least in one mode. But the quality is bad or 104important features won't work. `:basic' means it works at least in the most 105important modes but quality is not perfect. `:good' means the device is usable 106for day-to-day work. Some rather exotic features may be missing. `:complete' 107means the backends supports everything the device can do. Example: `:status 108:untested' 109 110The `:desc' keyword token is used for non-hardware devices (API and meta). Its 111string argument describes the meta backend or API. It should be used only once 112per device type. 113Example: `:desc "Scanners with the machine-independent PINT interface" 114 115 116Multi-level keyword tokens 117-------------------------- 118 119The following keyword tokens can be used after `:backend', `:mfg', `:model', 120and `:desc'. 121 122One or more `:url' keyword tokens can be used to point to more information 123about the entry the keyword refers to. The string argument contains a URL to 124e.g. a manufacturer's or backend's homepage. The most important URL should be 125listed first. 126Example: `:url "http://www.epson.com/"' 127 128`:comment' is used to add more information to one of the entries. The string 129argument can e.g. contain comments on the level of support for a model. 130Example: `:comment "US version of GT-5000"' 131