[sane-devel] Proposal: Definition of the format for backend specification files (.desc)

[Henning Meier-Geinitz]

Hi,

This is the first draft of a definition of the backend specification
files. It's the result of the discussion about the SANE2-standard and
mostly based on the existing template file (doc/descriptions/template.desc.)
and current usage.

The only thing I changed was to remove :new from the :status keyword.
Instead, I added an additional keyword: ":new" (surprise!). The reason
is, that even for new backends the user is interested in the level of
stability of the backend.

Please comment on contents, language, spelling etc. The idea is to add
this file as sane-backends/doc/descriptions.txt to SANE CVS.

Bye,
  Henning
  
SANE Backend specification files
--------------------------------

The specification files (e.g. epson.desc) describe the capabilities of the
backends. They provide information about the backend itsself (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/'.

The specification files can be used to generate lists of backends and/or
supported devices, databases and similar sources of information.  Currently
the creation of two HTML lists is supported by `tools/sane-desc.el' and
`tools/sane-desc-external.el'.  The generation of the HTML pages can be
started by `make sane-backends.html' and `make sane-backends-external.html' 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"'

The keyword `:status' is an indication of the stability of the backend.  It's
followed by one of the following keyword arguments: `:alpha', `:beta', or
`:stable'.
Example: `:status :stable'

`: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", 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"'

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"'