Features and Options of stic-0.7/bin/simv

This software moves and manages image files in JPEG or GIF format.
Its main purpose is to show the images and to coordinate usual file
management tasks with a picture recognition system.
A list of external helper programs is displayed as appendix to this text.

The program maintains a list of file addresses. A list index points to the
current item which can be manipulated. At start the list is empty. It is
usually filled by the program's arguments but may be extended by dialog
commands as well.

Arguments are commands which get executed before the dialog starts.
Arguments which do not begin with a '-' character get prepended by -addfile:
automatically, so they are added to the list as fileadresses.
At the beginning of the dialog, the first item of the list is made current.

If a file gets moved in or out a directory which contains a file with the
name  .imv_guarded_directory  then the picture recognition system gets
informed about the new address. Therefore all directories which contain
files known to this system should also contain a file .imv_guarded_directory

Files that are in a directory without .imv_guarded_directory  are tested
by the recognition system wether they may already be stored in a guarded
directory. If similar files are found then they are displayed with a second
viewer window.

Many commands which expect arguments like filenames or shell commands
perform parameter substition. This means that before execution certain text
parts get replaced by values known to the program. All these special
text parts begin with a $-sign. The next character decides about the kind
of substitution. See a list what is replaced by what :
 $*       the address of the current item
 $/       the directory part of $* with trailing '/'
 $&       the filename part of $*
 $#       the index number of the current item
 $.       main directory (defined by -keyset:maindir)
 $-       trash directory (defined by -keyset:trashdir)
 $~       the user's $HOME directory
 $0       the program's start directory (directory part of argv[0])
 $|       the program's process id (a number)
 $@       the program's TCP portnumber of -tcp_service:2:... (if any)
 $=       -match_par:... with current settings (or empty text if not set)
 $(text)  perform parameter substitution on text, execute the result as
          shell command and use the standard output of this command.
 $$       a single '$' character

Commands usually are not toggled in but triggered by shortcut keys or sent
by external frontend programs.
To get a command line prompt, press the '@' key.

If commands come faster than they can be processed, they get buffered and
executed as soon as possible. The ESC key discards all pending commands
and all those keystrokes and commands which follow the ESC immediately.
Please note that a lot of special keys produce sequences with ESC and
therefore cannot be used for key binding up to now.

Commands are bound to single keys by option -keyset which takes a single
keyset statement as parameter.
See below command -keyset and the sample keyset definition.

External frontend programs can connect via TCP/IP or named pipes.
They may send commands and apply for notification of any output event.
See below -pipe_service , -tcp_service, -add_view , -show_copy .
This software itself is able to act as such a frontend program via TCP/IP.
The connection may be encrypted to be secure against malicious clients
or third party interference. See below -security and -tcp_client .

Unencrypted, the input protocol simply consists of command lines separated
by CR+LF, LF or NUL bytes. Several classes of output messages may be
subscribed by -add_view .



                Command reference of application commands

-addfile:fileaddress
     Append the given file address to the list and make it the current item.

-addfile_list:fileaddress
     Read the given file and append all non-empty lines as file addresses to
     the list. The last added item becomes the current one.

-back
     Make the previous list item current.

-crc:listid:command:[arguments]
     Perform one of several actions with one of the CRC lists. There may be
     up to 16 lists simultaneously with arbitrary listid (e.g.: 1 , master).
     Each list consists of items with filename, 32-bit CRC, size (or 0)
     and a text which shows the source line from CSV file, SFV file or
     own CRC computation. Items with size 0 (i.e. from SFV file) match any
     item with the same CRC. If both sizes are larger than 0, then they
     have to be identical too.
     If given a listid that does not exist yet, the following commands
     create a new CRC list (provided there are less than 16 lists) :
                    add , add_all, copy_from , read_list , read_list_list 
     Some commands change the list ordering. Better sort before write_list .
     Commands :
       add          Determine CRC and bytecount of the given fileaddress
                    and add it to the CRC list. The fileadress is
                    expected as argument. (e.g. -crc:1:add:$* )
       add_all      Add all items in the file list to the CRC list.
                    No argument expected. (e.g. -crc:1:add_all: )
       clear        Remove the list from memory and free its slot for reuse.
                    No arguments expected (e.g.  -crc:1:clear: ).
       copy_from    Adds all items of a second CRC list to the first one.
                    The second listid is expected as argument.
       if_match     Determine CRC and bytecount of the current item and
                    execute arguments as command if the first match in the
                    CRC list also has a matching name.
       if_name_mismatch  like  if_match  but execute if the first match in
                    the CRC list has a conflicting name.
       if_no_match  like  if_match  but execute if there is no match in the
                    CRC list.
       info         Print name and number of items in the CRC list. If listid
                    is * then info about all existing CRC lists is printed.
                    No argument expected. (e.g. -crc:*:info: )
       intersect    Only keep those items which match items in a second
                    CRC list. The second listid is expected as argument.
       name_mismatching  Only keep those items which match items in a second
                    CRC list but have different names. Upercase/lowercase
                    differences are ignored. The second listid is expected
                    as argument. (e.g. -crc:1:name_mismatching:master )
       read_list    Add the data lines from a CSV or SFV file to the CRC
                    list. The name of the file is expected as argument.
       read_list_list  Add the data lines from many CSV or SFV file to the
                    CRC list. The names of these files are read line by line
                    from a plain text file and handed over to  read_list .
                    The name of the plain text file is expected as argument.
       remove_doubles  Only keep those items which do not match a previous
                    item in the same list. No arguments expected.
       rename       Rename the current item if its CRC can be found in the
                    CRC list and eventually the given bytecount matches.
                    The new name is taken from the CRC list.
                    No arguments expected (e.g.  -crc:1:rename: ).
       search       Determine CRC and bytecount of the given fileaddress
                    and try to find it in the CRC list. If a match is found
                    the line from the CSV or SFV file is printed to stdout.
                    The fileadress is expected as argument.
                    (E.g. try to verify current item : -crc:1:search:$* )
       show         Print the lines of the CRC list to standard output.
                    The number of printed lines may be limited by an optional
                    argument. (e.g. -crc:1:show:  or -crc:1:show:16 )
       sort         Sorts the CRC list according to one of the criteria :
                     name, crc, size, comment 
                    The criterium is expected as argument. Prepend a -
                    to obtain descending ordering. (e.g. -crc:1:sort:-size )
       subtract     Only keep those items which do not match items in a
                    second CRC list. Second listid is expected as argument.
       write_list   Write the CRC list to a new CSV or SFV file. Format
                    and fileaddress are expected as arguments.
                    (e.g. -crc:1:write_list:csv:/home/test/my_new.csv 
                          -crc:1:write_list:sfv:/home/test/my_new.sfv )
                    This command may not overwrite existing files.
     -crc performs parameter substition.

-doubleto:directoryaddress
     Move the first item of the displayed similar files to the given
     directory. This is mainly used to replace poor versions of an image
     by a new and better one.
     Performs parameter substition.

-for:[+|-]start_index:[+|-]end_index:command
     With each list item beginning with start_index and ending with end_index
     perform the given command. Abort loop on error. If end_index is smaller
     than start_index, then command is not performed at all. See -jump for
     an explanation of the [+|-]index format.
     The current item index is set according to the last run of command
     within the loop.

-jpgb[:interruptible|viewer_repair]
     Convert the current item to old fashioned JPEG format. A quality
     parameter can be stored in the file .imv_jpgb_quality_value but a
     reasonable value is already preset at program start.
     The original file is preserved within the trash directory so this
     command does not immediately save disk space when reducing file size.
     If ":interruptible" is appended then the conversion command is only
     performed if the input queue is empty and it is killed if input becomes
     available during its run. Thus the current item might remain unchanged.
     ":viewer_repair" includes ":interruptible" with the additional
     constraints of the internal repairer (the one controled by -repair_icv)
     It will do nothing directly after -undo or directly after an attempt
     to repair the same list item.

-jump:[+|-]index
     Make the list item current which has the given list index.
     The index may be any number larger than 0. If it is preceded by a '+'
     or '-' then the index is added resp. subtracted from the current index.
     Note: -jump:+1 may cause the program to end if -end_on:list_end is set.

-list:[+|-]start_index:[+|-]end_index[:option]
     List the indice and addresses of the files in the range from
     start_index to end_index.
     An index may be any number larger than 0. If it is preceded by a '+'
     or '-' then the index is added resp. subtracted from the current index.
     If option is "raw" then only the file addresses are listed.
     If option is "count" then also the total number of files is listed.

-mapper_args:arguments
     Predefine one or more arguments which are added to the command line of
     the picture recognition program. See -mapper_cmd below.
     This command also needs permission for service-mapper_db

-mapper_cmd:mapper_command:databaseaddress:glue_character
     Set the shell command, the database and the glue character (e.g. ':')
     for calling the picture recognition system. A call will be formed by
      <mapper_command><glue_character><databaseaddress> \
        <predefined_arguments> <option><glue_character><filename>
     Where option is in
      {-append, -refresh, -del_file, -search, -search_distance, -lookup_adr}
     This command should be used with great care, if ever. Under normal
     circumstances, -mapper_db  and -mapper_args should be sufficient for
     all purposes.
     This command also needs permission for service-mapper_db

-mapper_db:databaseaddress
     Set the database to be used by the picture recognition system.

-match_par:color_tolerance:bw_tolerance:color_ignore:bw_ignore[:method
           [:max_distance_factor[:max_result]]]
     Set an additional argument to the call of the picture recognition
     system. It describes the comparison parameters which are used for
     the decision wether two images match. See  similar -help  for more
     information about option -match_par.
     The numbers may be preceded by + or - to increment or decrement the
     current setting. If method is "unchanged" or missing, then the
     currently set method is used. Eg. -match_par:+2:+1:+0:+0:unchanged
     Unlike -mapper_args this command is secure against shell tricks since
     its parameters are checked before being added to the argument list.
     Therefore it is in class "service" and not in class "security".

-moveto:directoryaddress
     Move the current item to the given directory.
     Performs parameter substition.

-preserve
     Make a backup copy of the current item in trashdir and enable it to be
     re-installed by -undo . This is useful before -shell commands which
     may alter the content of the current item.

-replace_double
     Overwrites the first item of the displayed similar files by the current
     item. The duplicate's filename, its permissions and its linkage within
     the filesystem are preserved. Any link to the old duplicate will
     therefore point to the new data.

-search_doubles:match_parameters
     Search for duplicates of the current item using the match_parameters
     rather than the ones set with -match_par . The search is performed
     even if -search_doubles is off.
     If no parameters are given then the current setting of -match_par is
     used for the search.

-silent_about_missing:mode
     If mode is set to "on" then the -addfile* commands will not report
     missing files. The default behavior is "off".

-skip
     Make the next list item current.
     Note: -skip may cause the program to end if -end_on:list_end is set.

-undo
     Revoke the most recent operation which altered the content or the
     address of a list item. Currently operations can be undone back
     to the program's start. -undo does not revoke -addfile (i.e it does
     not remove items from the list).

-visit:fileaddress
     Append fileaddress temporarily to the file list, show the image like
     the current item is shown with -refresh, and then remove it from the
     file list.
     Note the special permission handling of -visit :
     Class is "visit" and action is the fileaddress. This address is
     checked wether it begins with the permitted action text. The remainder
     may not contain any "/" characters. If not all addresses are permitted
     then symbolic links or file objects with multiple hardlinks are denied.
     Example: -permission:all:visit:deny
              -permission:all:visit-/tmp/php:permit
              allows -visit:/tmp/phpXyZaBC but not -visit:/my/private/file

-where:criterion:regular_expression:command
     For all items in the list, test the criterion with the given regular
     expression. If it matches, execute command with that item.
     Criterion may be one of :
       "name" the last part of the current item's address
       "dir"  the other part of the current item's address
       "adr"  complete current item's address
     For a description of regular expressions see: man 1 ed , man 7 regex
     The current item index is set according to the last run of command
     within the loop.


                   Command reference of agent commands

#text or !text
     Remarks. They are ignored like empty commands.

:character
     Same as  -synthetic:-1:1:character  (see below)

-add_view:connection:subscription:representation[:encapsulation]
     Subscribe to a class of output events. This is the way how frontend
     programs get informations. There are several kinds of subscriptions:
       prompt             get notified when the server is idle and when it
                          becomes busy.
       stdout             get texts which are directed to standard output
       stderr             get texts which are directed to standard error
       current_file       get the current file (usually its name)
       double_files       get the list of possibly double files
       current_file_copy  get the copy of the current file (see -show_copy)
       double_files_copy  get the list of copies of possibly double files
       ask                get questions
       mark               get start and end of command -mark.
       reply              get start and end of command -request.
       all                subscribe to all output events
     Any time this program (the server) changes one of the subscribed states
     it sends a notification to the client using the chosen representation.
     The connection parameter may be a filename or a "-" character. A "-"
     tries to use an already established back channel to the frontend
     program. This will fail if the input connection is a pipe and no
     filename was given with a previous -add_view: from that client.
     It is ok to use a connection filename several times from within the
     same frontend program.
     The representation should be "default" up to now.
     If encapsulation is given as "encapsulated" then the view will only
     receive notifications caused by commands from the same input connection
     as this -add_view command. If encapsulation is set to "open" any
     command's output may be received. "open_and_show" does the same, but
     with subscription current_file or double_files, initial notifications
     will be sent to inform about the actual image state.
     The encapsulation mode applies to all subscriptions of the same view
     id (see below Appendix B, notification "init").
     There are two subscriptions which are served automatically together
     with any other subscription:
       init           notifies about the first subscription which is
                      assigned to a backchannel.
       end            notifies that the backchannel will be closed by the
                      server now (e.g. because it ends service).
     Also the subscriptions  mark  and  reply  are served as soon as any
     subscription is made. These notifications emerge from commands -mark
     and -request.
     The format of notification messages is described in appendix B.

-arguments_to_queue
     Only in effect for commands given as program arguments. Usually the
     arguments are interpreted before the input for dialog is started.
     This prevents unwanted outside interaction during setup.
     By -arguments_to_queue all following arguments are placed in the input
     buffer. So they get executed as user commands from internal input as
     soon as dialog service starts. (Beware of -permission restrictions)
     For automated start of -tcp_client it is desirable that all following
     arguments are sent to the server rather than waiting for the end of
     client mode. Use:  -arguments_to_queue -tcp_client:... ...

-ask_end
     Ask for Y or N . End program if answer is Y.

-bundle:mode
     After the command  -bundle:start  all following commands from the same
     input channel are buffered and their execution is delayed until the
     command  -bundle:end  or again  -bundle:start  is received.
     The execution of the buffered commands will not be mixed with commands
     from other channels. So one can rely that a combination of -jump and
     -moveto will really move the desired file even if a lot of other
     clients are using the server without any coordination.
     Be aware that the total size of buffered commands per channel is
     limited (but at least 64 KB ).
     -bundle acts along the whole client-server chain whereas enclosed
     commands might get executed locally by a client.
     -bundle may not be prepended by any other command (e.g. -mark).

-double_check:mode
     In applications which show a current image item, a picture recognition
     check may be performed to find very similar images. This command
     wether such a test shall be performed by appropriate applications.
     Mode "off" disables the check, "on" performs it with any current
     image item. Mode "auto" allows the application to check only those
     images, which are not already under the management of the recognition
     system.

-encapsulate_views:switch
     If switch is set to "on" this command excludes other views from
     being notificated about the effects of commands. Only the internal
     output channels (see -internal) and the views of the command's sender
     will get these notifications. This mode is useful if the clients of this
     program are not aware about each other and would interfere with their
     replies.
     "off" is the normal mode where all subscribers get all subscribed
     notifications.

-end
     End the run of the program.

-end_client
     Ends client mode. This mode eventually was initiated by -tcp_client .

-end_on:trigger[:option]
     Set or delete trigger for automatic end of program. The trigger is
     deleted if option is 'clear' .
     Triggers defined up to now:
        list_end     is true if the current item cannot be set because the
                     end of the file list has been reached.
        prompt       (only effective in client mode) is true if the server
                     indicates to be idle by a 'prompt' notification.
        timeout      is true after the number of seconds given by option
                     has elapsed without a new -end_on:timeout.
        idle         is true after the number of seconds given by option
                     has elapsed without receiving an input event.
     A general trigger is defined which combines all triggers.
        all          is true if any trigger is true.
     Therefore -end_on:all:clear deletes all triggers.

-end_server
     Sends an -end command to the server and ends client mode. This command
     is ignored if the program is not in client mode.

-external:channelname:switch
     Enable or disable external i/o channels. Available channel names are:
       current_file      the view subscriptions for current files
       double_files      the view subscriptions for possibly double files
       all               all of the above channels
     Switch may be either "on" or "off". Default is "all:on".

-help[_short]
     Print this text. -help_short only prints the keyset help text.
     The program ends without any dialog if -help is its last argument.

-hide
     Close internal viewers for current_file and double_files and notify
     all subscribers of these events that no files should be displayed.
     If the views are already hidden, then nothing is done.

-input_ready_fd:code
     In client mode, this command notifies that data is available from
     the server. In normal (server) mode, this command is ignored.

-input_interrupt:mode
     If an application attached interrupting input channels to the agent
     they may be enabled (mode "on") or disabled (mode "off").
     If they are disabled then the agent only listens for commands and
     notifications and the application temporarily will not see data
     pending at the interrupting input channels. As soon as the interrupt
     is enabled again, the application will notice those data.
     One should not disable for a long time because a sender may become
     impatient and close the connection.

-internal:channelname:switch
     Enable or disable internal i/o channels. Available channel names are:
       current_file      the internal viewer for current files
       double_files      the internal viewer for possibly double files
       stdout            texts directed to standard output
       stderr            texts directed to standard error
       termios           listen for single character input at start terminal
       all               all of the above channels
     Switch may be either "on" or "off". Default is "all:on".

-keyset:statement
     Manipulate the keyset mapping from single keystrokes to commands.
     A statement consists of a code word and possibly additional text.
     See also the example keyset definition below.
     Keyset statements:
       clearall             Clears the whole keyset.
       clear:keys@          Clears the mappings for one or more keys.
       clear:@#code@        Clears the mapping for a key by its decimal code.
       helpstart:text       Clears the short helptext and adds first line.
       helpmore:text        Adds another line to short help text.
       listall              Lists the whole keyset.
       list:keys@           Lists the mappings for one or more keys.
       list:@#code@         Lists the mapping for a key by its decimal code.
       maindir:address      Sets a common parent directory for file
                            addresses with 'map' and 'trashdir' which do not
                            begin with '/'.
                            Performs parameter substition.
       map:keys@command     Maps one or more single keys to a single command.
                            Use the same commands as for the command line but
                            no remarks.
       map:@#code@command   Maps a key by its decimal ASCII code to command.
       readfrom:filename    Reads keyset statements from a file one statement
                            per line. See example below.
                            Performs parameter substition.
       trashdir:address     Sets the directory which keeps old file versions
                            for the -undo command.
                            Performs parameter substition.
       #text or !text       Remarks. They are ignored like empty statements.
     '@' (ASCII 64) and ESC (ASCII 27) cannot be mapped at all.
     If a key gets more than one mapping, then all these commands get
     executed in the same sequence as they have been mapped to the key.
     So if a key is to be newly defined, "clear:" should be applied first.
     Mapping for multi character keys (like F1) is not possible yet.
     Leading blanks before the code word (e.g. 'map') are ignored.
     Blanks between @ and 'command' are ignored. All other characters up to
     the line end are significant.

-local_cmd:command
     Execute command locally even if being client and the command usually is
     performed remotely.
     Note: the command -bundle does not need -local_cmd prepended.

-loop_wait:hide_show_pause:minimum_execution_time:queue_limit
     Set the dampening parameters for the input loop. This is mainly to
     calm down the appearance of the image viewers.
     The hide_show_pause is the minimum number of microseconds between
     cancelling the previous current_file and showing the next one.
     minimum_execution_time (in microseconds) is to reduce the number of
     current_file notifications under heavy input load with fast commands.
     In this case the queue may be empty for a short time causing a prompt
     and display of the current file. Nevertheless, if new commands arrive
     frequently, only flickering windows appear and the CPU load goes up.
     If the input queue contains less than queue_limit commands, then the
     next command will be delayed until minimum_execution_time has elapsed.
     A queue_limit of 0 will apply the delay with any lenght of the queue.

-make_userkey:connectiontype:username
     Convert a file into an encrypted keyfile suitable for secure
     connections. The connectiontype may be one of:
       "tcp","file","internal","all" .
     It is used to choose the keydirectory which may be set by -security.
     There may be appended "-128" or "-256" to explicitely set key size.
     Within the keydirectory there has to be a file {username}.tnl with at
     least 64 bytes of content. The first 64 bytes are condensed and
     encrypted into a key which replaces the original file content.
     Permission to read or write the file is granted only to the owner.

-mark:id:command
     Notify the sender about start of command, execute command and notify
     about the end directly before the program checks for the next command.
     Other clients will not see the mark notifications.
     Note: the command -bundle will not work as argument of -mark.

-permission:username:class[-action]:["permit"|"deny"]
     Set a rule to permit or deny execution of particular actions by
     particular users. As soon as the dialog mode starts, the rules are
     checked with the effective username whenever a command requests a
     program action. Be careful with this command in dialog mode since you
     might exclude yourself from entering the next rule.
     The effective username is obtained from the authentication of the
     command's input connection. If no authentication by encryption has
     been enabled at that connection, the username is "external_anonymous"
     for external programs and "internal_owner" for application *rc files,
     program arguments and input at the start terminal (termios,stdin).
     Username "all" in a rule applies to any effective user.
     Any action belongs to a class (like "shell" or "move") but may
     also be addressed individually. The youngest matching rule applies.
     Example (deny shell commands for any user other than "internal_owner"
              but allow the use of a particular script with current item):
       -permission:all:shell:deny
       -permission:internal_owner:shell:permit
       -permission:all:shell-/home/scripts/infoscript $*:permit
     For a complete list of classes, see appendix agent P below

-pipe_service:type:filename
     Create filename as named pipe and listen for input. The parameter type
     determines how the input shall be used :
       1= handle single bytes as keystrokes.
       2= handle text lines as commands.
       3= send text lines to stdout
       4= send text lines to stderr
     For frontend programs only type 2 is useful. Type 1 is discouraged.
     If filename already exists and is a regular file, it gets replaced by
     the named pipe. The named pipe is removed when it is closed.
     Usually the first action of a frontend program is to send a -add_view
     command with the name of another pipe for output.
     Performs parameter substition if the application supports it.

-preserve_orphan_events:mode
     When a client connection ends, usually the server removes from the
     input queue all pending events which originate from that client.
     This is the default mode "off". If the server shall execute commands
     from clients which do not wait for completion, the mode may be set 
     to "on".
     Due to the compex handling of such orphan events, "on" is discouraged
     in high security environments.

-queue_canceled
     In client mode this causes a ESC line to be sent to the server.
     In normal (server) mode, this command is ignored.

-readfrom:fileaddress
     Read lines from file and execute each one as command.
     Performs parameter substition.

-refresh[:option]
     Redisplay the current item and eventually its lookalikes. Also print
     again the file information lines. Option "if_idle" prevents refresh
     if there is at least one input event pending (i.e the program is busy).

-remote_cmd:command
     Try to execute command remotely even if it would normally be performed
     locally in client mode. Fails if not in client mode.
     Note: the command -bundle does not need -remote_cmd prepended.

-remote_root_cmd:command
     Try to execute command remotely even if it would normally be performed
     locally in client mode. If the server is a client itself, propagate the
     command to its server and so on. Works even if not in client mode.
     Note: the command -bundle does not need -remote_root_cmd prepended.

-repair_icv:statement
     Set or delete trigger for automatic conversion of image files which
     cause the internal current view process to exit with nonzero value.
     This happens mostly if the format of the imagefile is not known to
     the viewer program.
     There are two possible statements:
        on .... if the viewer exits badly, try to repair the file via -jpgb
        off ... do not try to repair the file

-request:id:command
     Notify the sender about start of command, execute command and notify
     about the end directly after the command itself ended. Text messages to
     standard output will only be delivered to the sender of -request.
     Other clients will not see the mark notifications. This is similar
     to -mark but the end notification will be sent more early.
     Note: the command -bundle will not work as argument of -request.

-shell:shellcommand
     Execute a shell command.
     Performs parameter substition if the application supports it.

-security:connectiontype:option:value
     Add an access rule to the security list for remote connections.
     The connectiontype may be one of: "tcp","file","internal","all"
     Options may be:
       tunnel        controls encryption on server side. Possible values are
                     "require", "allow" or "refuse" encryption.
       user          controls encryption on client side. Its value sets the
                     username for encryption. Empty value disables encryption
       keydirectory  its value sets the directory with the user key files.
       controller    controls access to the -security command. Initially
                     only "internal" connections (i.e arguments and
                     start terminal input) are allowed to use this command.
                     By value "on" one may enable other connectiontypes
                     which then should have set "tunnel:require".
       clientprotocol  explicitely select an authentication protocol for
                     option "user". Valid values (protocols) are :
                      0.0    128 bit key, CRC-32 authentication (deprecated)
                      0.2    256 bit key, SHA-1 authentication (recommended)
       serverprotocol  select the authentication protocol which will be
                     accepted by a server. Valid values are :
                      0.0 , 0.2 , all   (default is "all")
                     where "all" permits any protocol known to the server.
     If more than one rule matches, the youngest one is used.

-show_copy:connection:subscription:options:target
     Subscribe to a copy-and-notification service for image files. Different
     from -add_view this subscription makes a copy of the files to be shown.
     Then it notifies its subscriber about the addresses of the copies.
     Any other subscribers of "${subscription}_copy" will get notified
     only if connection is "*". In this case -show_copy has no own back
     channel but relies on channels which have to be subscribed by -add_view.
     Other connection names are handled like in -add_view.
     Subscription may be one of :
       current_file       copy the current file
       double_files       copy the possibly double files
       all                all of the above
     Options may be a list of the following keywords and their eventual
     parameters:
      max_number=number  limits the number of copied files. This may be
                         be necessary for subscription "double_files".
      encapsulate        if this keyword is present, subscriptions are
                         encapsulated (see -add_view). Also the display of
                         copyfiles does end not before the next command from
                         the same input connection is received. Without this
                         keyword copyfiles end display as soon as the next
                         file is to be displayed.
      keep=seconds       copyfiles normally get removed when the subscribers
                         are notified about end of their display. They may
                         be kept available on the disk for the given number
                         of seconds. This is useful if serving for a web
                         server whose clients may need some time to load
                         the files.
     Target is a file address template. For an particular file it will be 
     extended by a unique counting number and the file name's dot extension.
     Example: target=/tmp/simv_current  , filename=/home/me/my_cat.jpg
              Name of copy:  /tmp/simv_current_1168105077.jpg
              This name is sent with a "current_file_copy" notification.
     Despite copyfiles get removed if all goes well, one should use a
     separate directory which is easy to clean from old remnant file copies.
     Just in case that something goes wrong.

-sidestep:command
     Execute command and afterwards restore the cursor position in the
     application's item list (if there is one and it got changed by command).

-stderr:[newlinemode:]text
     Send text to stderr and appropriate channels. If newlinemode is "nonl"
     then the output text will not be trailed by a newline character. If
     newlinemode is "nl" or if it is omitted, then a newline is appended.

-stdout:[newlinemode:]text
     Send text to stdout and appropriate channels. newlinemode: see -stderr

-synthetic:connection:type:text
     Create a synthetic input event. Useful to emulate a keystroke
     via a line oriented input connection. The value of "connection" has
     to be -1 up to now. "type" tells how to handle "text" :
         1=keystroke , 2=command line , 3 = to stdout, 4 = to stderr

-tcp_client:hostname:portnumber[:representation:[encapsulation]]
     Enter client mode. This means to connect to a peer program and to
     subscribe for all output events. Most of the input events will be
     forwarded to the peer and the incoming notifications will be
     printed and sent to the own frontend clients. The internal image
     viewers for current and double files are disabled though.
     The peer has to provide TCP/IP service by -tcp_service:hostname:...
     Commands that are handled locally:
        -add_view , -end , -end_client , -input_ready_fd , -internal
        -local_cmd , -security , -show_copy , -tcp_service
     If a username has been set by  -security:tcp:user:...  then
     this name is used for for authentication and encryption.
     (see appendix C)
     If representation is "data" then the subscriptions for image files
     will cause the server to transmit the whole file contents together
     with their addresses. All subscriptions made by -show_copy at this
     client will make their file copy from the transmitted content rather
     than trying to read the file itself. If internal file viewers are
     enabled (by -internal after -tcp_client), then they show these file
     copies rather than trying to read the file itself.
     This notification method is helpful if direct file access is not
     possible due to access restrictions or due to incompatible file
     addressing (try: -show_copy:... -tcp_client:... -internal:all:on ).
     If encapsulation is given as "encapsulated" then the client will
     only receive notifications which are caused by its own commands.
     If encapsulation is "open" or missing, any command's results may
     be received.

-tcp_service:type:hostname:portnumber:access_mask[:option]
     Offer service for frontend programs via TCP/IP. A client like telnet
     or a peer of this program itself (see -tcp_client) may connect to
     the address given by hostname and portnumber. Depending on the given
     type, input will be handeled differently:
       1= handle single bytes as keystrokes.
       2= handle text lines as commands.
       3= send text lines to stdout
       4= send text lines to stderr
     For frontend programs only type 2 is useful. Type 1 is discouraged.
     If portnumber is 0, the operating system will assign one automatically.
     The access_mask describes (in hex) which hosts other than localhost
     are allowed to connect. Connection is refused if :
       ( access_mask & foreign_address ) != ( access_mask & host_address )
     Where host_address is the address of hostname given with -tcp_service.
     Please note that this might be circumvented by IP-spoofing and that
     there is no check of user identity. Nevertheless the mask test provides
     a first defense against denial-of-service attacks.
     In hostile IT environments, use -security:tcp:tunnel:require  to demand
     user authentication and encrypted communication. See also appendix C .
     Examples: Serve at port 50000, do only accept connections from localhost
       -tcp_service:2:localhost:50000:FFFFFFFF
     Accept connections from own C-class net (assuming own hostname = ts4)
       -tcp_service:2:ts4:50000:FFFFFF00
     Accept from anywhere
       -tcp_service:2:localhost:50000:00000000
     If 'option' is given as "obstinate" the program will ignore errors
     with call bind() and try to obtain a server socket until it finally
     succeeds (or the program gets stopped).

-user:username:command
     Require permission to execute command not only for the authenticated
     user but also for the one given by username.

-viewer_cmd:shellcommand
     Set the shell command which starts an image viewing program. The program
     will be started to display one or more image files.
       ${shellcomand} -geometry [+|-]0+0 ${filename_1} ... ${filename_N}
     A geometry of +0+0 should create the image window at the upper left
     of the screen. -0+0 should do the same adjusted to the upper right.
     Tested shellcommands on Linux : xv , display


                      Appendix agent A :  Keyset Definitions

Usually a keyset definition is written to a file and read by -keyset:readfrom
There are only few sagent commands which make sense with keys, so better look
at Appendix application A for a more realistic example.

If the content of file /home/me/sagentkeys looks like that:

  # Clear old keyset
    clearall

  # Some helptext
    help: -disable_text  +enable_text  ?help  Quit
  # disable output of text
    map:-@     -internal:stdout:off
    map:-@     -internal:stderr:off
  # enable output of text
    map:+@     -internal:stdout:on
    map:+@     -internal:stderr:on
  # The help key
    map:?@     -help_short
  # Ask wether the program shall end
    map:Qq@    -ask_end

then the command
  -keyset:readfrom:/home/me/sagentkeys
activates this definition and overwrites the old one.


              Appendix agent B : Format of Notification Messages

A notification is a message consisting of a header and some fields.
It is terminated by a linefeed although it may contain 8-bit data.
  subscription number_of_fields [field[...field]]\n
A field consists of its (printable) header and a 8-bit data part :
  :name:representation:number_of_bytes:bytes
Example:
  current_file 2 :idx:data:1:5:file1:address:20:/usr/pictures/me.jpg\n
                 |first field||---------- second field ------------|

Message format of particular subscription notifications.
{#} is the number_of_bytes in decimal.
For better readability, each field is shown in a separate line.

When the server encounters the first subscription of a client :
  init 1 :id:data:{#}:{id-number}\n
This message is also generated by every single -show_copy subscription.
When the server ends service, for every "init" it issues an "end" :
  end 1 :id:data:{#}:{id-number}\n

Message to standard output resp. standard error :
  stdout 1 :text:data:{#}:{text}\n
  stderr 1 :text:data:{#}:{text}\n

When a file is added to the list
  list_change 3 :idx:data:{#}:{index}
                :action:data:6:append
                :item:data:{#}:{filename}\n
When the filename of a list item changes, "action" is set to "change"
  list_change 3 :idx:data:{#}:{index}
                :action:data:6:change
                :item:data:{#}:{filename}\n

When the current file gets displayed by the internal viewer :
  current_file 2 :idx:data:{#}:{index}
                 :file1:address:{#}:{filename}\n
or if subscribed with representation "data" :
  current_file 3 :idx:data:{#}:{index}
                 :file1:address:{#}:{filename}
                 :content1:data:{#}:{filecontent}\n
When the current file ends to be displayed :
  current_file 0 \n
If two possibly similar images were found by the recognition system :
  double_files 2 :file1:address:{#}:{name1}
                 :file2:address:{#}:{name2}\n
or (if subscribed by representation "data")
  double_files 4 :file1:address:{#}:{name1}
                 :content1:data:{#}:{content1}
                 :file2:address:{#}:{name2}
                 :content2:data:{#}:{content2}\n
When the display of these similar images ends :
  double_files 0 \n
The same formats are used for subscriptions "current_file_copy" and
"double_files_copy" (see -show_copy).

When the server becomes idle :
  prompt 2 :idx:data:{#}:{index}
           :count:data:{#}:{total_files}\n
When it gets busy :
  prompt 0 \n

When a question is asked :
  ask 4 :id:data:{#}:{question_id}
        :type:data:{#}:{type}
        :text:data:{#}:{question_text}
        :constraint:data:{#}:{rules}\n
When the question has been answered :
  ask 4 :id:data:{#}:{question_id}
        :type:data:6:cancel
        :text:data:0:
        :constraint:data:0:\n

Output is done by the particular commands as well as by the command-loop
which informs about the command before and possibly about the current item
after execution. The command -request surrounds exactly the command's
output and does not include any loop output. The command -mark surrounds
everything after "prompt 0" up to and including "prompt 2 ...".

Before a command given with -mark is executed:
  mark 2 :state:data:5:start
         :id:data:{#}:{id given with -mark}\n
Before the program checks for the next input event after -mark
  mark 2 :state:data:3:end
         :id:data:{#}:{id given with -mark}\n

Before a command given with -request is executed:
  reply 2 :state:data:5:start
          :id:data:{#}:{id given with -request}\n
After the command has been executed:
  reply 2 :state:data:3:end
          :id:data:{#}:{id given with -request}\n

One can explore the notifications by telnet. Connect to the server
(enabled by -tcp_service) and send:  -add_view:-:all:default
Then operate the server via its usual interface and watch the messages
received by telnet. One also may send command lines from telnet.
(telnet will end quickly if encryption is required by the server)


             Appendix agent C : Authentication and Encryption

Connections between the program and its frontends may be made secure by
a user-related encryption key. A user's key is stored in a file
within a keydirectory which is known to the program. The file's name is the
user's name extended by .tnl . Anybody who is able to read that file is
authorized to connect under that user identity. Therefore, restrictive
access permissions should be set for that file.

By help of command -security one can set the keydirectory, the security
requirements of a server and the username for use with -tcp_client.
The particular connection types may have separate settings.

The content of a user's keyfile is encrypted by the internal key of the
program. Since this key may vary from installation to installation, it
is better to use -make_userkey rather than creating the keyfile by other
means. Create an original 64-byte file of random bytes, transport it and
convert it locally. If you got to use old 16-byte keyfiles together with
newly created ones, make sure to create 128 keys and not the new 256 size.

If a user's keyfile has been installed at both hosts, it is sufficient to
allow encryption at the server side and to set a user for type "tcp" on
the client side. When client mode starts (by -tcp_client) the necessary
handshake is performed automatically between server and client.

Default security settings are :
   -security:all:tunnel:refuse
   -security:all:controller:off
   -security:tcp:tunnel:allow
   -security:internal:controller:on
   -security:all:keydirectory:${HOME}/tnl_keydir
Remember: the youngest matching rule wins. So encryption is only allowed for
TCP/IP connections and security controlling is only allowed for internal
input (*rc files, program arguments and termios,stdin at the start terminal).
So usually one only has to set a username before connecting to the server.
   -security:all:user:{username}
   -tcp_client:{hostname}:{portnumber}


               Appendix agent L : Legal stuff

This software is copyright 2003, Thomas Schmitt stic-source@gmx.net and
provided to you without any warranty under an open source BSD license.
(see file COPYING)


                Appendix agent P : Permission Classes

After the initial arguments of the program have been processed any further
action caused by a command is checked against rules which may have been
defined by the command -permission . A rule may address a whole class or a
single action. Depending on the command, more than one action may take place.
The application command
   -moveto:$(/home/scripts/find_target $*)
first tests for
   class="move"  , action="moveto"
and then for
   class="shell" , action="/home/scripts/find_target $*"
Nearly all commands test for their class and name, but -shell execution tests
for class "shell" and the shell command before parameter substition takes
place. The command -user tests for class "user" and the given username.

  Class       Command (resp. Action)
------------------------------------------------------------------------
  security    -security , -make_userkey , -permission, -viewer_cmd
  shell       -{shell command before parameter substitution}
  end         -ask_end , -end , -end_client , -end_on , -end_server
  peer        -local_cmd , -remote_cmd , -remote_root_cmd

  service     -double_check , -encapsulate_views , -external , -internal
              -input_interrupt , -keyset , -pipe_service
              -preserve_orphan_events , -show_copy , -tcp_client
              -tcp_service

  cancel      -queue_canceled

  user        -{username given with command -user}
  client      -add_view , -bundle , -mark , -request , -synthetic
  script      -readfrom
  navigation  -sidestep
  info        -hide , -refresh  message     -stderr , -stdout
  help        -help

For application specific commands, see the appropriate appendix P.

Special care should be taken for class "shell". If permitted, the commands
are executed under the user id which started this program. Class "security"
should be even more restricted to avoid unauthorized changes of permissions.

Note that  -permission:all:security:deny  is quite final in dialog. You
will get no chance to enter further -permission commands. So, only if given
in the program's start arguments, a set of rules may begin like that :
 -permission:all:security:deny \
 -permission:all:shell:deny \
The start terminal (via termios,stdin) gets administrator permissions :
 -permission:internal_owner:security:permit \
 -permission:internal_owner:shell:permit \

Others are allowed to perform some selected shell commands :
 -permission:all:shell-/home/scripts/infoscript $*:permit
 -permission:all:shell-/home/scripts/automatic_move_target $*:permit

For a quite mistrusted user "webserver" one may additionally define :
 -permission:webserver:all:deny
 -permission:webserver:client:permit
 -permission:webserver:navigation:permit
 -permission:webserver:help:permit
 -permission:webserver:info:permit
from class "modify" we only allow action -repair_icv:
 -permission:webserver:modify-repair_icv:permit



                      Appendix application A :  Keyset Definitions

Usually a keyset definition is written to a file and read by -keyset:readfrom
If the content of file /home/simv/anikeys looks like that:

  # Clear old keyset, set main directory and trashdirectory
    clearall
    maindir:/home/pictures
    trashdir:$./removed_pictures

  # Define three move targets with capital and small letters
    helpstart:Mice Horses Cats             (caps reform file before moving)
  # Map the capital letters MHC to a conversion to standard format
  # (they get extended below so they finally perform -jpgb before -moveto.)
    map:MHC@   -jpgb
  # Map the keys 'M' or 'm' to : -moveto /home/pictures/mice
    map:Mm@    -moveto:$./mice
  # Map the keys 'H' or 'h' to : -moveto /home/pictures/horses
    map:Hh@    -moveto:$./horses
  # Map the keys 'C' or 'c' to : -moveto /home/pictures/cats
    map:Cc@    -moveto:$./cats


  # Some general keys not specific to the file management task
    helpmore: >forward <backward -delete ~deldouble &undo !reform
  # The help key
    map:?@     -help_short
  # Navigation keys : '>' and SPACE move forward
    map:> @    -skip
  # Navigation keys : '<' and BACKSPACE move backward
    map:<@     -back
    map:@#127@ -back
  # Deletion keys for current item and its first lookalike
    map:-@     -moveto:$./removed_pictures
    map:~@     -doubleto:$./removed_pictures
  # Undo and file format normalizer
    map:&@     -undo
    map:!@     -jpgb

then the command
  -keyset:readfrom:/home/simv/anikeys
activates this definition and overwrites the old one. It does not matter
wether given as argument, in dialog or read from a file.


              Appendix application L : Legal stuff

This software is copyright 2001, Thomas Schmitt stic-source@gmx.net and
provided to you without any warranty under an open source BSD license.
(see file COPYING)


              Appendix application P : Permission Classes

This is a list of application permission classes and their commands.
see "Appendix agent P" for more information about permission classes.

  Class       Command (resp. Action)
------------------------------------------------------------------------

  security    -mapper_cmd , -mapper_args

  service     -mapper_db , -match_par

  modify      -repair_icv , -jpgb
  move        -crc , -doubleto , -moveto , -replace_double
  filelist    -addfile
  visit       -(start text of fileaddress to visit. See above: -visit)
  undo        -undo , -preserve

  navigation  -back , -skip, -jump
  info        -list, -search_doubles, -refresh
  loop        -for , -where

------------------------------------------------------------------------


----------------------------- External helper programs ------------------------

Image conversion program   :  convert -comment '' -quality 80
Picture recognition system :  similar -mapname:
Image viewer               :  display

-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
 ?help >forward <backward =isknown -delete ~deldouble &undo !reform
-------------------------------------------------------------------------------