From db76ba2c86f217e74c00a7bc31be8c8ab07c0b77 Mon Sep 17 00:00:00 2001 From: Henning Geinitz Date: Sun, 11 Jul 2004 13:02:50 +0000 Subject: [PATCH] New files. Added separate SANE2 page. Added TODO page based on sane2-api-todo.txt. --- sane2/index.html | 79 ++++++ sane2/sane2-todo.html | 541 ++++++++++++++++++++++++++++++++++++++++++ sane2/todo.css | 15 ++ 3 files changed, 635 insertions(+) create mode 100644 sane2/index.html create mode 100644 sane2/sane2-todo.html create mode 100644 sane2/todo.css diff --git a/sane2/index.html b/sane2/index.html new file mode 100644 index 00000000..0a154996 --- /dev/null +++ b/sane2/index.html @@ -0,0 +1,79 @@ + + + + + SANE - Standard Version 2 + + + + + + + + + + +
+ SANE +
+ +
+

SANE - Standard Version 2

+
+ +

+ The SANE standard version 2 is currently under development. It shouldn't be + used yet for production software because some important parts are still + missing. Most of the work to update the standard has been done by + Andreas Beck and Oliver Rauch. The discussion takes place on the sane-standard mailing list. The standard is + in CVS, see CVS page. The SANE2 standard is in + branch DEVEL_2_0_BRANCH-1. Use the following command to get this branch: +

+ 
+  export CVS_RSH=ssh 
+  cvs -z3 -d:ext:developername@cvs.alioth.debian.org:/cvsroot/sane co -d sane2 -r DEVEL_2_0_BRANCH-1 sane-backends
+
+ +

+ There is a TODO list and some snapshots of + the standard are available in several formats: +

+ + + + +
+ +

+ Documentation page
+ SANE homepage +

+

+ $Date$ $Author$ +

+ + + diff --git a/sane2/sane2-todo.html b/sane2/sane2-todo.html new file mode 100644 index 00000000..79134968 --- /dev/null +++ b/sane2/sane2-todo.html @@ -0,0 +1,541 @@ + + + + + SANE - TODO List for Standard Version 2 + + + + + + + + + + + +
+ SANE +
+ +
+

SANE - TODO list for standard version 2

+
+ +

+ This list intends to show the items which need to be finished before the + SANE2 standard can be published. It's based on Oliver Rauch's + sane2-api-todo.txt document. The headlines show the status of the change + as shown below. Keep in mind that this status is just the opinion of the + author of this page (hmg). If you think that anything is wrong or missing, + contact sane-standard. +

+

Accepted: The change is in the latest standard

+

Further discussion: The change is in the standard but + there are still problems

+

Rejected: the change won't be included in the + standard

+

(no status): neither included nor rejected yet

+ +

Naming and versioning

+

Archive/CVS name

+

+ "sane-backends2" (-->sane-backends2-2.x.y) or sane2-backends + (-->sane2backends-2.x.y)? +

+

Header file

+

+ "sane/sane2.h", "sane/sane-2.h", "sane2/sane.h" or "sane/sane."? +

+

Libraries

+

+ "libsane2-dll.so" or "libsane-dll2.so"? +

+

Standard

+

+ Use 3 versions for the standard (major, minor, revision)? The major number + would be 2 and means "binary incompatible changes". The minor number + means: additions to the standard (e.g. using of reserved values). The + revision is for changes that don't change the interface at all + (clarifications, more return values for a function). +

+

Config file names

+

+ "/etc/sane2.d/dll.conf"? "/etc/sane.d/dll2.conf" doesn't work because + there are already backends with numbers (microtek2.conf). +

+

SANE data types

+

SANE_Char

+

UTF-8 format

+

+ All texts and translations: UTF-8 format (this is used in KDE and + gtk+-2.x) may be UTF-8 should be forced as SANE_Char format. Currently + ISO-8859-1 is used as encoding. +

+ +

SANE_Parameters

+

Move SANE_Parameters to data type section

+

+ I don't see any reason to keep SANE_Parameters in the "Operations" section + as all the other data types are in "Data Types". +

+

Changes to frames (SANE_Parameters.format) (accepted)

+

+ Use SANE_FRAME_RAW, formatdesc="red:8,green:8,blue:8" instead of old + SANE_FRAME_* types. Add SANE_FRAME_MIME, formatdesc=MIME-descriptor, only + one frame/image, arbitrary data. This allows transmission of e.g. jpeg, + tiff and any other data format. SANE_FRAME_GRAY/RGB/RED/GREEN/BLUE are + obsolete. +

+

define bit order of 1 bit modes (accepted)

+

+ Lineart: 1 = black, other modes: 0 = black. Reason: History. +

+

Remove multi-frame paradigm at all

+

+ More than one frame is used e.g. for 3-pass scanners. Maybe also film + scanners use a separate frame for IR data? +

+

Remove multi-channel 1 bit mode (accepted)

+

+ Some old Mustek scanners support this mode (color 1 bit). But it's not + really useful. So 1 bit color is not allowed anymore. +

+

Add flags to SANE_Parameters.flags (accepted)

+

+ Make it compatible to SANE 1. Adds more_images, new_page, front/backside + info, 28 more flags available. +

+

More informational values (accepted)

+

+ Add dpi_x, dpi_y, proposed_filename, formatdesc, channels_per_image. +

+

32 bytes for future extension (set to 0) (further discussion)

+

+ Check how to do this without creating portability nightmares. The current + implementation just won't work as sizeof(SANE_Int) = 4 is not true + everywhere. Keep in mind that the size of SANE_Int is unknown, same is + true for SANE_String and even char. maybe just use SANE_Int reserved[10]? +

+ +

SANE_Device

+

Add informational and reserved members (accepted)

+

+ These members have been added: +

+ + +

Next pointer (rejected)

+

+ Add a pointer "next" to the device handle to make linked lists instead of + arrays. Is this incompatible change really useful? +

+ +

SANE_Status

+

Add more errors

+

E.g. out of memory in scanner, file not found, firmware not found, some + kind of error concerning options, power failure of scanner,...

+

Change SANE_Status to (also) contain textual error messages

+

+ The fixed error messages are sometimes not enough to find out what's wrong + exactly. E.g. which file is not found exactly or which option can't be + set? +

+ +

+ One proposal is: +

+ 
+typedef struct {
+  int code;
+  char *msg;
+} SANE_Status;
+
+

+ SANE_Status.code is always a standard SANE status code. If SANE_Status.msg + is NULL, then the standard SANE status message is printed, end of the + story. Otherwise, the custom SANE_Status.msg is printed, and the caller + must free SANE_Status.msg. +

+

+ The good thing about that proposal is that the error message comes with + the error code. That way we don't need a new API function to get the + verbose error message. The bad thing is that the caller has to care about + freeing msg. Also check if this works with saned. +

+

+ Another proposal: Slightly redefine SANE_Status, as a 32bit integer where + the 2 MSB are a backend-specific error code and the 2 LSB are a standard + SANE status code. +

+

+ The 2 LSB will always correspond to a SANE status. +

+

+ If the 2 MSB are non-zero, they are passed to a sane_backend_status() + routine inside the backend that returns a proper status message that is + then echoed to the user. (depending on what we want to achieve, we'd + require the caller to free the message after use, think sprintf(), + etc...). Otherwise, the standard SANE status message is echoed. +

+

+ Problems with this proposal: How does the dll backend know which backend + to ask for the error code? The usual problems: thread safety, who frees + the message. +

+ + +

SANE_Option_Descriptor

+

SANE_CAP_ADVANCED for a group (accepted)

+

SANE_CAP_ALWAYS_SETTABLE (accepted)

+

SANE_CAP_HIDDEN (accepted)

+

SANE_CAP_AUTO_POLL

+

+ One of the problems with the options system in SANE is that a backend + can't tell the frontend that something has changed. Such a feature would + be useful if a button is pressed on the scanner or some other status in + the scanner changes. As callbacks are not available over the network, + polling of options can be used a a workaround. An option with the + capability SANE_CAP_AUTO_POLL should be read by the frontend each + [interval] milliseconds. The interval should be defined. (e.g. min 100 + msecs, max 1 sec?) +

+ +

SANE API functions

+

sane_open

+

New parameter: sane_device (accepted)

+

+ sane_open does return sane_device: A frontend may decide not to call + sane_get_devices because it already knows which device shall be opened. In + this case it does not get any information about the device (vendor, model, + ...). So it makes sense to return the SANE_Device in sane_open. +

+ +

sane_get_parameters

+

Define error codes for sane_get_parameters

+

+ Currently there are no error codes. +

+

Move SANE_Parameters to data type section

+

+ All the other structs are defined in the data type sections. I don't see + any reason to not move SANE_Parameters to that section. +

+ +

sane_init

+

Define return value of sane_init

+ +

sane_get_select_fd

+

Implementation note for select_fd

+

+ If the select_fd is a pipe, it's not enough to close "the other side" of + that pipe. The select_fd must be closed itself. The frontend shouldn't + assume that the fd is a pipe. +

+ +

sane_control_option

+

Which parts of an option descriptor can be changed at + run-time?

+

+ Define what parts in a option_descriptor may be changed after it has been + set up and passed to the frontend. +

+

More members of option descriptor that should be changeable

+

+ Maybe add size to list of members that can be changed? +

+ +

SANE_INFO_INVALIDATE_PREVIEW (accepted)

+

+ When an option is set with sane_control_option that changes the image + significantly (e.g. exposure) invalidate the preview by setting + SANE_INFO_INVALIDATE_PREVIEW. +

+ +

sane_strstatus

+

Remove "const" (accepted)

+ +

New SANE API functions

+ +

sane_verbose_error

+

+ Add SANE_String sane_verbose_error(Sane_Handle h), to show + backend-specific error messages. The error string always refers to the + last error reported by the backend. So the frontend would call this when + a SANE API call returned with an error status. E.g. out-of-memory in + scanner hardware or "Couldn't open file foo". Check for thread-safety + problems. If the handle parameter is used, no errors can be printed + before sane_open has succeeded. +

+

+ If we use SANE_String sane_verbose_error() (no handle parameter), we could + ask for error messages even in sane_open. However, SANE allows to open + several scanners at the same time so this could lead to confusion. Also, + how does the dll backend know which backend to ask for the error message + if no handle is given? +

+

+ How to translate individual error messages? +

+

+ See also SANE_Status. +

+ +

sane_download_translation, sane_download_backend_file

+

+ The idea of using a SANE API function to download backend translations and + backend documentation is that the frontend doesn't need to care about + paths to these files. Also it works over the network. So the client only + has the net backend (and no documentation/translation for other backends) + and all the data is on the server. On the other hand the current + implementation works quite well (translations are installed by + sane-backends). 95 % of the backends don't have HTML documentation so we + had to move from man page to HTML if we wanted to use that approach. +

+

+ My proposal is to keep the current situation concerning translations (and + only define formats and filenames in the standard). Concerning + documentation, maybe just add a member "doc_path" to SANE_Device so the + frontend can use any browser it likes? However, this means that we have to place + the docs and translations on the client as it's the case now. +

+

+ In the following paragraphs some other approaches to download + translations/documentation are explained. +

+

+ Download backend translation and documentation: The Download function does + not care about the file format, this probably also has to be defined in + the sane standard. E.g.: sane_download_backend_file(filename). The backend + has to load the file from a fixed directory. The path to the directory has + to contain the backend name, e.g: /usr/local/share/sane/sane-umax/ The + frontend can not change the directory due to security! That may cause + trouble with network scanning! +

+

+ Rethink the whole idea of downloading. Maybe there should just be a + function to get the .gmo file for a specific language. E.g. sane_read_gmo + (SANE_String language, SANE_Byte * buffer, SANE_Int * size) or even + SANE_Byte * sane_get_translation (SANE_String language). Does the latter + work over the net (local copy needed)? +

+

+ Or use a more general approach: SANE_Status sane_get_aux_info (SANE_String + * aux_info, SANE_String_Const lang, SANE_Int info_type). info_type defines + if a translation or backend documentation is selected. Format for + documentation is HTML without images? However, this way only one html file + per backend can be transmitted. +

+

sane_get_device_info (rejected)

+

+ Add sane_get_device_info function that allows the frontend to ask for + information about all involved backends and meta backends that are used. + Is this still needed with version_code in sane_device and the new + parameter in sane_open? +

+ +

sane_extended_call / sane_extended_callback + (rejected)

+

+ I don`t like this because it makes it too simple to add proprietary + functions that are not defined in the sane standard. +

+ +

Split sane_cancel and add sane_end

+

+ Currently sane_cancel has two meanings: "The scan is now finished" and + "Stop the scan immediately". It would be much cleaner if these functions + were separate. +

+ +

Well-known options

+

resolution, x-resolution, y-resolution (accepted)

+

preview, new frame types (accepted)

+

geometry, temporarily wrong (accepted)

+

new: depth (accepted)

+

new: mode (accepted)

+

new: source (accepted)

+

new: threshold (accepted)

+

new: gamma-table (accepted)

+

new: analog-gamma (accepted)

+

new: shadow (accepted)

+

new: highlight (accepted)

+

new: lamp-on, lamp-off (accepted)

+

new: scanner-buttons-* (further discussion)

+

new: batch-scan (further discussion)

+

+ Option "batch-scan" should be of type SANE_Int. Define SANE_BATCH_* values + in sane_opt.h: 0 = no batch, 1 = ... . Strings shouldn't be used for such + switches. +

+

focus-position-x, -y

+

+ Set focus position. I don't know what's meant by this. Details please! +

+ +

Manual focussing

+

+ An option to use manual focus on film scanners was proposed. Details? +

+ +

multi-pass

+

+ Multi pass for film scanners. number of passes (either native or + EMULATED) SANE_TYPE_INT, word_list or range. +

+ +

image-number

+

+ Direct selection of image number, e.g. for film scanners -> SANE_TYPE_INT +

+ +

total-images

+

+ Number of images to be scanned, e.g. for film scanners. Read-only? Do we + need this option with SANE_PFLAG_MORE_IMAGES? +

+ +

exposure-time

+ +

Image type/compression type

+

+ Many scanners are able to generate scan data in different formats, + e.g. raw and jpeg. There should be a well-known option to select which + kind of image data is used. E.g. a string list with well known values for + "Raw", "JPEG", "TIFF", whatever. +

+ +

Miscellaneous

+ Message callbacks +

+ Let backend display a frontend-info or -selection (ok/cancel) dialog-box + (e.g. "Calibration in progress: wait 10/9/8/... seconds") this has to be + done with a callback, e.g.: sane_frontend_dialog_display(**window, text, + ok_text, cancel_text, backend_dialog_callback_function) + sane_frontend_dialog_close(window) the frontend function has to be + implemented in a way that the backend can change the text. A good place + to define the callback functions could be sane_init, where already the + authorization_callback is defined. +

+

+ Callbacks don't work with the SANE network protocol. At least you can't + call the callback if no SANE function is currently running. An exception + is the authorization callback as that's only needed before calling some + specific functions. So those functions return "authorization needed" over + the net. It's not clear yet if it's possible to implement message + callbacks over the net at all. Even if it is, the code will be complicated + and bloated because we need to return an error for the RPC and then + restart the currently running code at the same position where the callback + occurred. +

+ +

Flag to reload options after scan (rejected)

+

+ Give backend the chance to tell the frontend while/after scan that the + options have changed (e.g. film scanner reduces number of available + images): may be a flag (comparable to int *i in sane_control_option). +

+

+ If such a feature is really necessary and SANE_CAP_AUTO_POLL is not + enough, we could force the frontend to reload the descriptors after every + scan. Otherwise we had to add a flag to sane_cancel which I think is + really unclean. +

+

Implementation notes

+

+ The idea is to add a section with implementation notes like the text that + is currently in backend-writing.txt. My personal view is that everything a + backend programmer needs to know should go into the standard. Everything + that concerns the sane-backends distribution, coding style, general coding + tips etc. should go int backend-writing.txt. +

+ +

Internationalization/documentation

+

Marking of translatable texts (further + discussion)

+

+ See section 4.2.10 ff for details. I don't think that the details of the + marking should be mentioned in the standard as they are backend-dependant + and not part of the API. Only mention that options are in English and that + option names must not be translated. +

+

Recommended file formats for internationalization + (further discussion)

+

+ In sane_i18n definition files: *.po, default translation tables: *.(g)mo. + (section 4.2.10.3). It's ok to define the formats but the way how to use + these files needn't be defined (maybe a gettext to something else + converter is used). +

+ +

Network protocol

+

Update from API changes

+

+ The network protocol must be updated to reflect the changes to the SANE + standard. +

+

Use UDP instead of TCP?

+

port number selection

+

+ Let the server define a port number for the data port to avoid firewall + problems? +

+

Avoid data port

+

+ Maybe it's possible to avoid the data port at all? +

+

Document RPCs

+

+ Add the numbers of the RPCs to the standard, Maybe the standard needs some + more details of the network interface, too. +

+

Callbacks

+

+ Check if the callbacks are implemented according to the standard. +

+ +

Lamp shut off (rejected)

+

+ Saned or a stand alone "turn lamp off daemon" should get an internal timer + to turn off the lamp of some scanners. This has to be defined closer. + May be it is necessary to find out how long a scanner has not been + used. For this saned needs a function like sane_get_offline_time()... +

+

+ This should be done in the backend. +

+ +

Grammar/spelling/formalities

+

Update contact information

+

Add clear preliminary marker

+

Set change markers of INVALIDATE_PREVIEW

+

Check grammar & spelling

+

Check too long lines

+

Check defective references

+

Update index

+

Check that all headlines are in capital letters

+ + + +
+ +

+ SANE 2 standard page
+ Documentation page
+ SANE homepage +

+

+ $Date$ $Author$ +

+ + + diff --git a/sane2/todo.css b/sane2/todo.css new file mode 100644 index 00000000..2b2fe8a9 --- /dev/null +++ b/sane2/todo.css @@ -0,0 +1,15 @@ +body {color:black; background-color:white; + font-family:helvetica,arial,sans-serif;} + +p {margin-left:2%;} +pre {margin-left:2%;} + +h2 { margin-left:0%; } +h3 { margin-left:1%; } +h4 { margin-left:2%; } + +p.noindent { margin-left:0;} + +h4.accepted { color:green; } +h4.discussed { color:#FFBB00; } +h4.rejected { color:red; }