#
#   This macro dispalys the Rules for writing new ( .dgt) 
#   digitizer/mouse/trackball files.
#
more  macro  dgt_format

#   0.  All digitizer communication files using these specifications must be 
#   named with a   .dgt (or .DGT) extention.  example:  al40f82.dgt
#
#   1.  No line may exceed 95 characters in length.
#
#   2.  In a line, all characters following (& including) a pound sign (#) are
#   considered comments (ignored).  To put a pound sign into a string not to be 
#   ignored, use a  \035  .  Any ascii character can be specified in this way:
#   a backslash followed by a 3-digit (ascii decimal) number specifying the 
#   ascii decimal value of the character.
#
#   3. all other non-blank characters must be within brackets {} OR be one of 
#   the following (which are followed by brackets):
#      setup
#      start
#      stop
#      query
#      format
#   These represent the groups of information used to initiate, gather, and
#   stop input from a graphics input device (digitizer, mouse, track-ball etc.)
#   one (left or right) bracket may be on a single line, although text & 
#   brackets may share a line.
#   
#   4.  Limits:
#      a)  The file can have no more than 100 non-blank, non-comment lines.
#      b)  Other limits are listed with their data type, below.

#   5. the legal lines within brackets depend on the group to which the 
#   brackets belong.  ALL DATA LINES ARE DEPENDENT ON THE PARTICULAR DEVICE.
#   YOU MUST REFER TO THE TECHNICAL REFERENCE MANUAL FOR THE PARTICULAR DEVICE
#   (mouse /digitizer/track-ball) in order to determine which parameters and 
#   which values need to be used.  The groups (setup, start, stop, query, 
#   format) may be in any order.  Within the groups:  start, query, and stop
#   the order of command lines is important.  These are the legal line formats 
#   for each grouping:
#
#         --------------------------------
#      SETUP (this data is to setup the communication link with the digitizer 
#      and used during interpretation of the digitizer data):
#
#        (serial line characteristics)
#      a.  baud=n            This line is optional, default = 9600 if not 
#                            specified. If specified, n must be one of:  
#                            300, 600, 1200, 1800, 2400, 4800, 9600, 19200.
#      b.  parity=str        str must be 'odd', 'even', or 'none'.  This item 
#                            is optional, and defaults to none if not specified.
#      c.  data_bits=n       Then number of data bits used (does NOT include
#                            parity bits, if any).  Choices = 5,6,7,8(default)
#      d.  stop_bits=n       The number of stop bits used on the serial line.
#                            Choices are 1, or 2.  Optional, default = 1.
#
#        (data interpretation characteristics)
#      e.  digcursor=fname   This line is strongly recommended, it specifies
#                            the cursor file to be used while this digitizer 
#                            is in use.  If not used, then the digcursor file 
#                            will remain the same as it is (whatever that may 
#                            be).  The digcursor file defines which command 
#                            each digitizer button generates.
#      f.  debounce=d [r]    These values control the delay and repete rate for
#                            a digitizer/mouse button that is held down (who 
#                            says you can't keep a good button down!)  The 
#                            first value (delay) specifies the number of 
#                            continuous reports with the same button press 
#                            which must be recieved before it is taken as a 
#                            second button press.  The second value (repete 
#                            rate) (separated by a space), specifies the number
#                            of continuous reports between further reports 
#                            recieved which will be taken as subsequent button 
#                            presses.   The second value (repete rate) is 
#                            optional (default = 1/3 first value).  A 0 for 
#                            the first value indicates an infinite delay.  For 
#                            this value, only 1 key press will be taken no 
#                            matter how long a button is held down.  If no 
#                            debounce values are listed, the default of 0s will
#                            be used.
#      g.  units_per_inch=n  Helps to set sensitivity & map-inch size. 
#                            default=1000 for absolute devices, 200 for
#                            relative devices (see below).
#      h.  coordinates=str   str must be 'absolute' or 'relative', 
#                            default=absolute.  In general, mouse/track-ball 
#                            devices are relative, and digitizer coordinates 
#                            are absolute.
#      i.  sign_type = aaa   This indicates the sign type for binary formats:
#                               none          (all +)(dflt for absolute crds).
#                               0negative     (0=neg, used for some abs coords)
#                               1negative     (1=neg, used for some abs coords)
#                               2s-complement (default for relative coords).
#                            NOTE:  for binary formats the sign bit should be 
#                            coded as the highest bit number for a coordinate.
#                            NOTE:  for ascii formats, a minus (-) sign is 
#                            expected from the raw device to indicate a 
#                            negative number.
#      j   x_positive = dd   This indicates the direction of x-positive 
#                            coordiantes.  dd is a string which may have the 
#                            values:  right  left    The default is   right.
#                            All digitizers & mice have x-positive to the right
#                            as of this writting.
#      k   y_positive = dd   This indicates the direction of y-positive 
#                            coordiantes.  dd is a string which may have the 
#                            values:  up   down      The default is   up.   
#                            The microsoft mouse is a digitizing device which 
#                            has y-positive coordinates to indicate a downward 
#                            movement.
#   
#      NOTE:  Order of items is unimportant within the setup group.
#   
#   
#      example of a setup grouping:
#   
#         setup
#         {  baud = 2400
#            parity = none
#            stop_bits = 1
#            digcursor = cc9000_12
#            debounce = 12
#            sign_type = 1negative
#            units_per_inch = 1000
#            coordinates = absolute
#         }
#   
#         --------------------------------
#      START, STOP, QUERY.  All of these allow the same operations, but are 
#            used at different times when communicating with the digitizer/
#            mouse.  The START grouping is used to initialize the digitizer 
#            each time communication is switched to that device.  The QUERY 
#            grouping is used when (and if) the the digitizer is queried/
#            prompted to send data information.  The STOP grouping is used to 
#            stop digitizer output & put the digitizer to bed.  All of these 
#            groupings are optional.  If the digitizer is configured by default
#            or switch settings to output data in the desired form, then the 
#            START and STOP groups are not needed.  If the digitizer outputs 
#            data continuously, then NO QUERY GROUPING IS NEEDED.  There may be
#            no more than 40 operations within the start group or the stop 
#            group.  There may be no more than 10 operations in the query 
#            group.  The operations allowed in any of these groups are:
#   
#      a.  send=aaaa         This allows the sending of any ascii string to the
#                            digitizer (at the current buad rate and parity).
#      b.  read=n            This tells the program to read n bytes from the
#                            digitizer before trying to read again (gives up
#                            trying to read after 1 second).  This is for 
#                            reading digitizer prompts during start & stop 
#                            groups and is NOT used for querying the digitizer,
#                            unless a non-data string is to be read (like a 
#                            prompt character)
#      c.  wait=n            wait n seconds (decimal seconds allowed) before
#                            next communication with the digitizer.  Many
#                            computers are quicker than digitizers and need to
#                            allow time for the digitizer to change baud rate
#                            before resuming communication.  Maximum resolution
#                            for wait is 0.001 second.
#      d.  baud=n            This allows changing of baud rate which was set
#                            during setup and is normally not used otherwise.
#                            If only 1 baud rate is used, then it is put in the
#                            setup group only.  This is the normal case for 
#                            most digitizers.
#   
#         NOTE:  control, extention, space, and all other characters can be 
#         specified in send strings by using the backslash followed by the 
#         ascii decimal value to be sent (up to 3 digits).  Example:   
#         send=/027    (indicates the escape character).
#         NOTE:  The lines/commands communicating with the digitizer will be
#         executed in the SAME ORDER as they are in the start/stop/query 
#         grouping.  Order is very important.  Wait commands may be necessary 
#         to give the digitizer time to execute the command sent.  Wait 
#         commands may need to be added/changed when the main program is run 
#         on a faster cpu (in order to give the digitizer enough time to keep 
#         up).
#         NOTE:  A maximum of 40 non-comment lines can be in a start, stop,
#         or query group.
#         NOTE:  All characters to be sent must be specified, including 
#         carriage return (\013) and linefeed (\010).
#         NOTE:  Each time a QUERY group is executed, a 0.001 second wait is 
#         done automatically after all query group commands.  This allows time 
#         for the graphics input device to send a packet of information before 
#         the serail line is read by the program.  In general, the use of a 
#         query group will slow input & the cursor will appear to move less 
#         smoothly, but this may be necessary on some slower machines (to allow
#         the computer to keep up with a quick mouse).
#   
#      example of a start grouping:
#   
#      start
#      {  send = \027%R
#         baud = 2400
#         wait = 0.6
#         read = 3
#         wait = 0.1
#         send = \027%S
#      }
#   
#   
#      example of a query grouping:
#   
#      query
#      {  send = \027%Q
#      }
#   
#   
#      example of a stop grouping:
#   
#      stop
#      {  send = \027%K
#         wait = 0.1
#         send = \027%*
#      }
#   
#         --------------------------------
#   
#      format (this data is used each time a packet of information from the
#            digitizer is interpreted).  This group must be one of 2 types,
#            ascii or binary.  The digitizer file MUST contain a format group
#            (either ascii or binary).  Ascii format groups have only 1 line:
#   
#      a.  ascii = format_string      
#   
#            Binary format groups have one line for each byte in the form:
#   
#      b.  byteN = format_string (where N is the byte number, 1 or greater) or
#          byteNo = format_string   (similiar to above for OPTIONAL bytes).
#          NOTE:  The program assumes that opitonal bytes contain ONLY button
#          press information (no x or y information).
#          
#   
#         The legal format strings depend on the type (ascii or byteN):
#   
#      a. ASCII format strings have these characteristics:
#         1.  There are no imbeded blanks.
#         2.  Legal characters are:
#            x - denotes 1 character of the x-coordinate value (sign included).
#            y - denotes 1 character of the y-coordinate value (sign included).
#            b - denotes 1 character of button press information
#            , - denotes the comma character (used to sync data if present).
#            c - denotes a carriage return (optionally specified)
#            l - denotes a line-feed  (optionally specified)
#            ? - denotes any other character of information (including blanks).
#         NOTE:  The sign (+ or -) should be coded as part of the x or y value.
#         NOTE:  The specification of the carriage-return and linefeed are
#         totally optional.  They will be ignored wheather they are specified 
#         or not.  Their only use is to separate one ascii grouping of 
#         incomming data from another.  Any combination of carriage-returns 
#         and/or linefeeds will serve this purpose in any case of ascii format 
#         use.
#
#   
#      example of ascii format grouping:
#   
#      format
#      {  ascii = ?xxxxx,yyyyy,??bcl
#      }
#         
#   
#      b. Binary format strings have these characteristics:
#         0.  byteNo form is used only for bytes which are sometimes, but not
#             always sent by the digitizing device.  These byte(s) must be at
#             the end of the grouping/packet.  For example, the Logitech 
#             Mouseman sends an optional 4th byte only when the middle button
#             is pressed.  Very few digitizing devices use optional bytes. 
#         1.  8 bits are specified with at least 1 blank between bit groupings,
#             even if fewer bits are used (fill the left [high] bit with ? if
#             necessary).
#         2.  Legal characters are:
#            xN - denotes bit N of the x-coordinate value (low-order bit is 0,
#                 max bit allowed is 31)(include sign bit as highest bit used)
#            yN - denotes bit N of the y-coordinate value (low-order bit is 0,
#                 max bit allowed is 31)(include sign bit as highest bit used)
#            bN - denotes bit N of button press value (low-order bit is 0, 
#                 maximum bit allowed is 7).
#            0  - denotes bit is always zero (used for sync bit).
#            1  - denotes bit is always one  (used for sync bit).
#            ?  - denoted any other information (bit not used).
#         NOTE:  There cannot be more than 100 lines of byten= in the format 
#         group.
#         NOTE:  Sign bits (if any) should be coded as the highest bit number 
#         for a given coordinate.
#         NOTE:  Parity bits (if in the lowest 8 bits), and fill bits (if fewer
#         than 8 bits used) should be coded as ?.  No bits above the lowest 8 
#         should be specified at all (sometimes there is a 9th parity bit).
#         NOTE:  0s and 1s are used for syncing the input, and should all occur
#         in the same bit column OR all in the same byte row. 
#   
#      examples of a binary format grouping:
#         (example with odd or even parity and 7 data bits)
#      format
#      {  byte1 = ?  1   ?   ?   ?   ?   ?   ?
#         byte2 = ?  0   ?  b4  b3  b2  b1  b0
#         byte3 = ?  0  x5  x4  x3  x2  x1  x0
#         byte4 = ?  0 x11 x10  x9  x8  x7  x6
#         byte5 = ?  0 x16 x17 x15 x14 x13 x12
#         byte6 = ?  0  y5  y4  y3  y2  y1  y0
#         byte7 = ?  0 y11 y10  y9  y8  y7  y6
#         byte8 = ?  0 y16 y17 y15 y14 y13 y12
#      }
#   
#      or
#         (example with 8 data bits [with or without parity])
#      format
#      {  byte1 = 1   ?  b3  b2  b1  b0 x15 x14
#         byte2 = 0 x13 x12 x11 x10  x9  x8  x7
#         byte3 = 0  x6  x5  x4  x3  x2  x1  x0
#         byte4 = 0   ?   ?   ? x16 y16 y15 y14
#         byte5 = 0 y13 y12 y11 y10  y9  y8  y7
#         byte6 = 0  y6  y5  y4  y3  y2  y1  y0
#      }
#   
#   
#   
#   Example 1.  of an entire file (This is a new format for cc9000f2 [ascii])
#   (refer to the file for complete comments).:
#   
#   setup
#   {  stop_bits = 1
#      baud = 9600
#      parity = none
#      digcursor = cc9000f2_12
#      debounce = 8
#      sign_type = none
#      units_per_inch = 1000.0
#      coordinates = absolute
#   }
#   
#   start
#   {  send =\027%R
#      send =\027%W0
#      send =\027%K
#   }
#   
#   stop
#   {  send =\027%H
#   }
#   
#   format
#   {  ascii = xxxxx,yyyyy,??b
#   }
#   
#   
#   
#   
#   
#   Example 2.  of an entire file (This is a new format for al40f82 [binary])
#   (refer to the file for complete comments):
#   
#   
#   setup
#   {  baud = 9600
#      parity = none
#      stop_bits = 1
#      digcursor = al40f82_16
#      debounce= 8
#      sign_type = none
#      units_per_inch = 1000 
#      coordinates = absolute
#      sign_type = none
#   }
#   
#   start
#   {  send=S3\13
#      send=F8\13
#      send=R6\13
#   }
#   
#   
#   format
#   {  byte1 = 1   ?  b3  b2  b1  b0 x15 x14
#      byte2 = 0 x13 x12 x11 x10  x9  x8  x7
#      byte3 = 0  x6  x5  x4  x3  x2  x1  x0
#      byte4 = 0   ?   ?   ? x16 y16 y15 y14
#      byte5 = 0 y13 y12 y11 y10  y9  y8  y7
#      byte6 = 0  y6  y5  y4  y3  y2  y1  y0
#   }
