  Document  : CDD.DOC
  DOC-INFO  : Calamus Printer Driver Descriptor Definition
  Author/(c): A. Wagner
  Up to v#  : 2.08 of DTD Definition Rules (same as CDTG v#)
  Last CHNG : 11-9-93
  State     : Public
  


                     Make-up of the .CDD File
                     ========================

  The .CDD (Calamus DruckertreiberDeskriptor = printer driver descriptor) 
  file serves for preparing a printer driver for Calamus. It contains 
  data about the resolution, the number of printable page formats, the 
  minimum margins, the paper feed arrangements, the control codes etc. It 
  is built up in a similar way to the Calamus Setup file: Each command 
  starts with a hash character ('#'), each comment line with a '|'; 
  comments can also be included in the active lines following a 'REM'. 
  Both of these continue automatically to the end of the line.

  Make-up of the code lines:
  ==========================

  Code lines follow the CDD commands PRINIT, PREXIT, NEWLINE, PLANESET,
  CURHOR, CURVER, WIDTH, HEIGHT, COPIES, REVERSE, SETFEED as well as 
  GRAPHMODE and are made up of bytes that are to be sent to the printer.
  Both decimal and hexadecimal numbers as well as strings can be used for 
  this. All bytes are separated by a comma, only the characters in a 
  string can follow each other. Decimal numbers have no prefix, while 
  hexadecimal numbers are prefixed with a '$'; characters and character 
  strings are enclosed in single quotation marks ('). The byte Escape 
  (27, $1B) can also be represented by CTRL-E (ASCII 5, which is an 
  X-crossed black square in the Atari system font and a hollow square 
  with the Monaco font). Examples of code sequences can be taken from 
  the CDD files included.

  Commands:
  =========

  #PRNAME           This command is followed by the printer name. It may 
                    have a length of up to 31 characters.
  
  #EDITION          Gives the number of the editions of the CDD file. 
                    Each time it is saved anew, EDITION is incremented by 
                    one.

  #TYPE             This command specifies the prototype with which the 
                    printer is to be driven. Here is the name of the 
                    prototype as it was selected in the converter.

  #AUTHOR           The character string following this command will be 
                    entered in the 'Author :' field of the converter.

  #TITLE            Represents the top line of the Comment page of the 
                    converter.

  #REM              This command may be present up to 5 times and 
                    represents the five comment lines in the Comment 
                    page. Normally this contains information about 
                    compatibility, departures from standard code 
                    definitions or additional information about the 
                    prototype used.

  #TIMEOUT          This command sepcifies the time in seconds the 
                    printer driver waits before Calamus signals "Your 
                    printer is either off line or disconnected" (max 99 
                    seconds). The time applies to the output of ONE byte.
                    If the byte is accepted by the printer within the 
                    specified time, then the same timeout applies for the 
                    next byte.

  #MEASUREMENT      This command may appear as often as you like and 
                    switches between different types of measurement. If 
                    a 'cm' follows, then all following page dimensions 
                    up to the next MEASUREMENT command will be 
                    interpreted as centimeters with a maximum of two 
                    decimal places; if on the other hand 'x/n inch' 
                    follows ('n' can be anything, but is usually the 
                    smallest dot size the printer can print or quoted 
                    dpi), then all following measurements will be taken  
                    as fractions of an inch.
                    The first MEASUREMENT command in the CDD file 
                    determines the measurement unit set in the generator 
                    after loading in the file.

  #PAGE             Specifies the available page formats. The following 
                    are possible: A3, A4, A5, B5, LETTER, LEGAL, DOUBLE, 
                    HALF, OWN. With OWN you also have to specify the name 
                    of the format (up to 10 characters) as well as the 
                    page height and width in the current MEASUREMENT 
                    units.
                    Up to 11 page formats are permitted.
                    After this you can optionally enter the margins for 
                    the format. When programming a printer driver it's 
                    best to omit these parameters at first and print out 
                    a complete page from Calamus with the printer driver; 
                    the page should be filled completely with a grey 
                    raster. After that measure the resulting margins, 
                    enter them with this command into the .CDD file 
                    subsequently and let the CDT generator translate the 
                    file anew.
                    The margins (in the order left, right, top, bottom) 
                    are to be specified in the current MEASUREMENT units.

  #FEED             FEED specifies the paper supply source and type. FEED 
                    is followed by a descriptive name of the feed source 
                    (max. 25 characters), followed by an '=' and the 
                    mode. If this = 0, then this is an automatic paper 
                    feed, if it = 1 then this is manual feed, with 2 
                    we are dealing with a timed feed.

  General notes about printer codes:
  Deviations from the definitions as far as individual codes go are 
  possible due to the very different printer families, as well as for 
  special functions and different operation of some printers. Read more 
  about this in the .TXT files in this directory as well as comments for  
  individual codes and the REMs of the CDDs.

  #PRINIT           The codes that are sent before printing a page to the 
                    printer. With the PRINIT code, in contrast to all 
                    other codes, macros are permitted that allow the 
                    insertion of the line-feed distance, the number of 
                    copies and the (optional) switch-over to reverse 
                    (more correctly inverse) printing. Usually the 
                    printer is brought with the PRINIT code to a defined 
                    starting condition (initialisation code) and if 
                    appropriate switched to unidirectional printing etc.. 
                    Up to three macros can be inserted at any position in 
                    the code, whose place will then be taken during 
                    output to the printer by the #COPIES code, the 
                    #REVERSE code and/or the #SETFEED code. For the 
                    #COPIES code one should enter a 'C' in the #PRINIT 
                    code, for the #REVERSE code an 'R' and for the 
                    #SETFEED code an 'F'. The copy code can be switched 
                    off by the #COPYMODE OFF command, in which case the 
                    driver can not output any copies; the reverse code is 
                    switched on and off by its mere presence. If inverse 
                    printing is NOT switched on in the Calamus Print 
                    dialog, then the corresponding #REVERSE code will not 
                    be output ('R' will be suppressed).

  #NEWLINE          The codes that are sent before each line to the 
                    printer. We are dealing here with an escape sequence,
                    i.e. with an Escape byte (27 or $1B) followed by the 
                    codes for initialisation of a graphic mode. The codes 
                    that switch on the selected graphic mode are entered 
                    here. In this sequence an 'n1' and 'n2' have to be 
                    specified so that the driver knows at which position 
                    it has to begin outputting the set of data to be 
                    transmitted. The numbers are separated by commas. 
                    Hexadecimal numbers are identified by a preceding 
                    '$' character.
                    Usually the sequence can be typed in from the printer 
                    manual, where it is present under the following 
                    names:
                    240*216 and 240*180 dpi   : Quadruple-density graphics
                    180*180 dpi, 24 LOW       : Triple-density graphics
                    360*360 dpi, 24 HIGH      : Sextuple-density, 24 pins
                    360*360 dpi, 48           : Sextuple-density, 48 pins
                    See also the CDDs.

  #PREXIT           The codes that are sent after a page has been 
                    printed. Usually this is an escape sequence that 
                    switches back to the normal line-feed distance 
                    (1/6th of an inch as a rule), and a FORM FEED (12) 
                    which ejects the printed sheet.

  #COPIES           If the printer (e.g. a laser) can itself create 
                    copies, then there will be an escape sequence here to 
                    make this possible. This sequence will be inserted in 
                    the PRINIT code at that position where a 'C' is 
                    placed. The number of copies is identified with 'n1', 
                    as the printer driver will itself later enter the 
                    desired number of copies here. Whether the number of 
                    copies or of specimens as such will be inserted 
                    here is determined by #COPYMODE.

  #REVERSE          If the printer is able to print inverse (white on 
                    black) in the graphics mode, then the code for this 
                    will be specified here. In contrast to the Copies 
                    code this sequence is only sent to the printer if 
                    inverse printing is to be switched on; as a result 
                    this code contains no variables. The position of the 
                    inverse (reverse) command in the PRINIT sequence is 
                    marked in that with an 'R'.

  #PLANESET         This is used with colour printers that output one 
                    plane (or colour layer) after another to switch 
                    between planes. The 'n1' parameter then contains the 
                    command to switch between red, green and blue planes 
                    in RGB, or between yellow, magenta, cyan (and black) 
                    in three- (or four-)colour printing. The assignment 
                    of 'n1' to the colour planes is documented in the CDDs.

  #CURHOR           This usually finds application with laser printers 
                    for a RELATIVE horizontal move of the graphics cursor 
                    to the right. In the code there is usually a '+' in 
                    front of the parameter.
  #CURVER           As #CURHOR, only the graphics cursor movement is a 
                    RELATIVE move downwards.
                    
  #WIDTH            and #HEIGHT serve with a page-oriented (colour) 
  #HEIGHT           printer to specify the width and height of the 
                    (partial) page to be output. 'n1' represents the 
                    size in the horizontal or vertical direction 
                    respectively.

  #SETFEED          This tells a matrix printer how large the following 
                    line-feeds should be. With an NEC P6 for instance one 
                    sets 'n1/360' line-feed, where 'n1' is set in turn by 
                    the driver during output. In general, the denominator 
                    of the line-feed is identical with the vertical 
                    resolution in dpi, so for instance:
                    240*216 dpi             : n1/216 inch
                    240*180 and 180*180     : n1/180 inch
                    360*360, 24 and 48 pins : n1/360 inch

  #GRAPHMODE        This switches a page-oriented printer into the 
                    graphics mode. The order of the codes output will 
                    have first PRINIT with the optionally included COPIES 
                    and REVERSE codes, then WIDTH and HEIGHT before or 
                    after GRAPHMODE.

  #EOL              With this command you can specify the end-of-line 
                    code. As parameters you can have alternatively 'CR', 
                    'CRLF', 'CRCR' and 'LF' (CR = Carriage Return, LF = 
                    Line Feed).

  #RESOLUTION       With drivers that support more than one resolution, 
                    it is possible that several resolutions can be 
                    switched off; the resolutions that are to be switched 
                    on follow RESOLUTION. A command is required for each 
                    resolution.

  The .CDD file will be translated by the program 'CDTG.PRG' into a 
  working .CDT  priner driver for Calamus.

