Documentation to the Harlekin Printer Driver Files

Harlekin: The Program of Possibilities

This text is copyrighted Mermaid Group 1989 and may not be 
reproduced in any form without written permission.

Harlekin is produced by:
Mermaid Group
Krabbesholmsalle 2
DK-8000 Źrhus C

Harlekin is distributed by:
MAXON Scandinavia
Montanagade 29e
DK-8000 Źrhus C
Tel. +45 86 20 13 88
FAX  +45 86 20 12 04

Documentation written by Tassilo Nitz
English translation by Andreas Ramos

Documentation to the Printer Driver HEX files.

This is a syntax description of the HEX file. The Harlekin 
configuration program will convert the HEX file into a printer 
driver file (with the extender PRT).

All characters must be written in HEX values. Comments may be 
added to the text at any point. At the beginning of a line, a 
comment should start with an asterisk (star, or *). Everything 
else on that line after the asterisk will be ignored when the 
file is converted into a PRT file.

If there are lines which repeat themselves, then this will be 
noted in the following documentation as two periods on separate 
lines.

Structure of a Harlekin HEX file:
***************************************************
<NAME OF DRIVER>
ESCDEFINITON
<ESC-CHARACTER>, <GROUP>, <INFORMATION VALUE>
.
.
FSDEFINITION
<FS-CHARACTER>, <GROUP>, <INFORMATION VALUE>
.
.
EXCEPTIONS
/ <EXCEPTION-NUMBER>, <NUMBER OF PRINTER COMMANDS> \
| <CHARACTER>, .., <GROUP>, <INFORMATION VALUE>    |
| .	                     |
\ .	                     /
.
.
TRANSLATION
<ORIGINAL CHARACTER>, <TRANSLATION>, ..
.
.
PRINTERCOMMANDS
/ <BUTTON TEXT>
\ <PRINTER COMMAND>
.
.
END
*******************************
Documentation now follows.

NAME OF DRIVER: A Name for the driver. This is only for you. The 
name will appear in the Harlekin printer filter box. Maximum 
number of characters: 30 characters.

ESCDEFINITION & FSDEFINITION: This allows the Harlekin printer 
driver to suppress any translation of characters during graphic 
printing or during printer commands.

A character string which is sent to the printer and which starts 
with either ESC (Dez:27 Hex:1B) or FS (Dez:28 Hex:1C) is called 
an "escape sequence." An escape sequence is used to start a 
printer command, such as style (bold, italic, etc), line feed, 
or paper length. The characters following an ESC or FS will not 
be printed. These characters are however part of the command.

ESC-CHARACTER AND FS-CHARACTERS: The individual lines tell you 
the number of characters which belong to each command which your 
printer knows. It is important that the printer driver does not 
translate these command characters. A printer command is 
normally determined by the characters which follow ESC or FS. In 
the following, this will be called an "ESC CHARACTER" or "FS 
CHARACTER".

Commands with a constant lenght (group 1): Most printer commands 
have a constant lenght. Here, the printer driver can decide 
which characters should be translated or not simply by counting 
the number of characters which follow an ESC character. The 
"information value" must note the number of characters which 
follow the ESC character.

Command with a closing byte (group 2): These commands may have a 
varying number of characters. The end is noted by a specific 
value. The information value contains the value of the closing 
byte. In most commands, theis is 0 (zero).

Commands for Single Pin Graphic (group 3): It is important that 
the printer driver should not translate graphic information. By 
dot matrix printers, there is a command which notifies the 
printer that the following specific number of characters will be 
graphics characters and therefore should not be translated. The 
binary value of bytes (the bit pattern) will then determine 
which pins in the printer head will be used. Such a command has 
place holders for two values which are called n1 and n2. The 
number of the point columns which will be printed is calculated 
by n1 + (256 X n2).

Depending on the number of points in a column, one needs 
different numbers of bytes. For defining the column, an 8 pin 
printer needs one byte per point column; a 24 pin printer needs 
three bytes.

A command for dot matrix printers must be noted with a group 
three command. The information value must be a two place 
number.The first number notes the nubmer of bytes per point 
column. The second number notes the number of bytes which must 
pass until the n1 n2 command is received. Enter here the number 
of bytes between "ESC (Esc character)" and "n1 n2". For most 
printers, this value is 0 or 1.

Command Exceptions (Group 4): In some cases, a command sequence 
can't be clearly defined by ESC characters.
In the ESCDEFINITION or FSDEFINITION, these commands should be 
described as group four. The information value must be a value 
between 1 and 10. Under this number, the command can be 
described in more detail in the exception table.

EXCEPTION Table: Those printer commands which don't fit into the 
first three groups can be described here.
This table can be best explained by an example.

Let's look at the command: ESC "*" m n1 n2

Many 24 pin printers use this command to print graphics in 
different modes. The graphic mode is determined by the value 
"m". If "m" = 0,1,2,3,4 or 6, the printer uses 8 pin graphics; 
if "m" = 32,33,38,39 or 40, a 24 pin graphic is used. For 8 pin 
mode, the command could be: 2a, 3, 11. (2a = ASCII value of "*" 
in hexadecimal notation.
3 means that a single pin graphic is being used.
1 (the first digit in 11) shows that a single point column is 
defined by one byte.
1 (the second digit in 11) shows that it is exactly a byte 
between "ESC 2a" and "n1 n2".

For 24 pin mode, the command must be written as: 2a, 3, 31, 
because three bytes are needed for each point column.

In the ESCDEFINITION, this command must be defined as an 
exception through: 2a, 4, 1. In the EXCEPTION table, the command 
would be written as follows:

1, B      * EXCEPTION NUMBER 1, 11 (SUB-)COMMAND
0, 3, 10  * HEX Value of m, 3 = Graphic, 1 = "1 Byte per column"
1, 3, 10
2, 3, 10
3, 3, 10
4, 3, 10
6, 3, 10
20,3, 30  * 3 = "3 Bytes per column
21,3, 30
26,3, 30
27,3, 30
28,3, 30

Note that the second digit of the INFORMATION VALUE is a 0 
(zero). Both of the values "n1 n2" directly follow "m."

TRANSLATION Table: The actual translation of characters is done 
in this table.

The <ORIGINAL CHARACTER> is related to the ASCII value of the 
character which will be translated.
"<TRANSLATION>, .." is a character or series of characters into 
which the character must be translated.
Recursive tranlation is not possible. The maximum lenght of a 
translation is 250 characters. The syntax of the translation 
table is similar to the WORDPLUS translation table. If you are 
using Wordplus, you can simply copy this block of material (up 
to the concluding Null byte!)

PRINTERCOMMANDS: In this table, you can place up to eight 
commands. Later, in Harlekin's printer filter window, you can 
click on the buttons and activate the commands. For example, you 
can reset the printer, change to another font, change the 
margin, etc.

<BUTTON TEXT> is the name of the command. This text appears in 
the printer filter button. The maximun number of characters is 
15.

<PRINTER COMMAND>: This is the command which is activated by 
clicking on the button. This is written in HEX characters.

The end of the HEX file is noted with the word "END".

                            