Augmented Devices

From Open Watcom

Introduction

The WGML Reference in 15.3 Augmented Device Definitions states:

Certain device operations are not selectable through the device and 
driver definitions. WATCOM Script/GML augments some device 
definitions by directly supporting these operations.

The augmented device definitions are recognized by the starting 
characters of the driver name. For example, HPLDRV is recognized as 
the name of a driver definition for the HP LaserJet printer.

Name Prefix    Augmented Device
HPL            HP LaserJet
HPLP           HP LaserJet Plus
MLT            Multiwriter V (emulation mode)
MLTE           Multiwriter V (express mode)
PCG            IBM PC Graphics
PS             PostScript

If the driver definition name begins with HPL (but not HPLP), the 
value returned by the %X_ADDRESS and %TABWIDTH device functions is 
in terms of decipoints instead of dots.

Exactly what functionality is provided is not otherwise specified. Since the PostScript device is part of the Open Watcom document system, it will be investigated and implemented. The other devices can wait until needed.

Device PS

This section reports the preliminary investigation, using the test document. When the actual Open Watcom documents are processed, additional augmentations may, or may not, be found.

The test device and driver source files were copied and renamed to start with "ps". The extension for the output file was also to "ps1" (for output files using :NEWLINE and the :BOX characters) or "ps2" (for output files using :ABSOLUTEADDRESS and :HLINE, :VLINE, and :DBOX). A diff program was then used to see what happened; it is important to understand that the device definitions were otherwise identical, so any difference could only have resulted from the appearance of the prefix "ps". Testing showed that only the value of attribute defined_name for the :DRIVER block must start with "ps" for the effect to be seen. Neither the defined name of the :DEVICE block nor either member (file) name needs to start with "ps".

The results fall into two categories:

• Those affecting the output from the various function blocks which is not intended to appear in the final document and which, in an actual driver, would implement the action desired for that block.
• Those affecting the output which is intended to appear in the final document, including whitespace.

In the first category, an obvious augmentation was that output records were terminated prematurely at the end of a word. As discussed here, wgml 4.0 normally flushes the output buffer when it has exactly the number of characters specified by the file specification, although it will do so earlier if device function %recordbreak() is encountered.

What happens when a "ps" prefix is found is that, when the last word in the text would normally not fit into the output buffer, then the output buffer is flushed before the last word in inserted (the "last word", of course, becomes the first word of the next record.

Interestingly, if the word is followed by a space, that space must also fit into the output buffer. If followed by more than one space, the result is the same as if it were followed by only one space.

To illustrate this, consider this device function invocation:

%image("Font Number: ")

this inserts the character string shown into the output buffer. When the output record ends with Numb", then, for the pstest device but not the normal test device, the output record ends with "Font" and "Number: " appears at the start of the next output record. However, "Number: " will also appear at the start of the next output record even when "Number:" would fit on the end of the preceding output record. Altering the string shows that "Nmber: " will also appear at the end of the same output record as "Font ", no matter how many spaces it is followed with.

This is what is done for characters (spaces, text, or both) which are to appear in the final document:

• They are surrounded by parentheses.
• They are usually followed by "|shwd|", which is inserted by wgml 4.0.
• They are sometimes followed by "|sd|", which is inserted by wgml 4.0.

When they consist entirely of spaces with no record break separating the spaces from the output of the next function block, then that function block is included in the parentheses, up to the next device function %recordbreak() -- record breaks caused by the record length being exceeded do not have this effect.

The actual PS :DRIVER block, as defined in psdrv.pcd has these two lines:

%image('/sd { exch currentpoint exch pop moveto shwd } def')
%image('/shwd {show} def')

which appear to define "sd" and "shwd".

Further research shows that the usage of these items is related to how the horizontal positioning is done:

• If the horizontal position at which the current text is to begin was established by the :HTAB block, then "|sd|" is used.
• If the horizontal position at which the current text (including any preceding spaces) is to begin was established by either the :ABSOLUTEADDRESS block or the emission of characters (including space characters), then "|shwd|" is used.

The definition of "sd" presumably is intended to work with the definition of :HTAB:

:HTAB.
   :value.
      %image(%decimal(%x_address()))
      %image( ' ' )
   :evalue.
:eHTAB.

and so to depend on the value of %x_address() being available on, presumably, the stack.

It is worth emphasizing that, in the test devices, "sd" and "shwd" were not defined but were nonetheless inserted by wgml 4.0. Thus, the initial requirements for producing the PS augmentation are clear. Whether or not more is needed can only be determined when the actual Open Watcom documents can be tested. The test document does not include every possible feature of wgml!