Augmented Devices
From Open Watcom
Contents |
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". Only the device and driver files using the :ABSOLUTEADDRESS block, the :HLINE block, the :VLINE block, and the :DBOX block was used because the actual PostScript driver and device provide these blocks. The extension for the output file was "ps2".
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". A diff program was then used to see what happened.
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 three categories:
- Those involving the available fonts.
- 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.
The next sections discuss these results.
The Available Fonts
The PS :DEVICE block uses a font name ('courier') with the :BOX block. Normally, this would result in an available font being generated for the 'courier' font and the :FONTVALUE blocks in the :INIT blocks would be interpreted for this generated available font.
This, however, does not happen. The reason is probably because such a font would never be used: the PSDRV :DRIVER block defines the :HLINE block, the :VLINE block, and the :DBOX block, so the :BOX block is never used.
When the test driver is used, an available font is generated if the :UNDERSCORE block uses a non-empty font name. Since all versions of the PSDRV :DRIVER block define the macros @uline and @euline and use them instead of device functions %ulineon() and %ulineoff(), this is surprising since it is clearly never needed either.
This can be implemented very easily: simply do not create any additional available fonts based on the :BOX block or the :UNDERLINE block if the PS device is being used.
Output Record Flushing
In this category, the only observed change was that output records were terminated 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. The space itself, however, is skipped. If followed by more than one space, the first space is skipped and the remaining spaces are placed in the output buffer, until it is full; any remaining spaces appear at the start of the next output record.
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 (the space between them does not appear in either 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 appear at the end of the same output record as "Font ", no matter how many spaces it is followed with.
Although unlikely to occur in practice, testing shows that, if the output buffer is so small that an entire word cannot be inserted, wgml 4.0 emits this error message:
IO--011: Output file's record size is too small for
the device 'pstest'
and exits.
Outputting Document Text
This is what is done for characters (spaces, text, or both) which are to appear in the final document:
- They are enclosed in parentheses.
- They are followed by either " shwd " or " sd ", which is inserted by wgml 4.0, as discussed further below.
- The PS driver (but not the test driver), with the value of "no" for the :LAYOUT block :DEFAULT block attribute justify, prints the text out line-by-line, using "\" as a line continuation character.
- The sequence "() shwd " is inserted before the :ABSOLUTEADDRESS block in these contexts:
- subsequent paragraph lines (left margin "6");
- text used with or generated by a :FIG tag (left margin "8");
- text used with the :BACKM tag (left margin "9");
- the title-line "Index" (left margin "21");
- the letters used to organize the Index (left margin "8");
- the Index entries (left margin "6" or "7", depending on level);
- the Table of Contents entries (left margin "6");
- the List of Figures entries (left margin "6");
- The sequence "() shwd " is not inserted before the :ABSOLUTEADDRESS block in these contexts:
- the first line of a paragraph (left margin "6", total "9");
- the title-line "Table of Contents" (left margin "6", total "15");
- the title-line "List of Figures" (left margin "6", total "16");
Notes:
- This will continue to be examined when the text-output is implemented. The issue is, of course, whether or not a particular "augmentation" is done in the document layout or in the text output/output buffer code.
- Verification that PS output is per-line only when justification is off will be needed.
- The sequence "() shwd " represents no output at all; as such, it is invisible in non-PS devices but may still be occurring. In other words, some occurrrences may be part of text output in general, not PS-specific.
- The sequence "() shwd " sometimes appears in other contexts than proximity to the :ABSOLUTEADDRESS block.
- The sequence "() shwd " does not appear in a simple PS file; however, it does not appear in a simple test device file either, so that may not mean much. A more complicated PS file will need to be examined.
- Testing shows that the "(" is not subject to output translation and, given that the ") sd " or ") shwd " are part of the instructions to the PS interpreter, they will be treated as not subject to output translation either. The net effect is to treat these elements as if output by %image() statements.
The " shwd " and " sd " appear to refer to items defined in the actual PS :DRIVER block in psdrv.pcd:
%image('/sd { exch currentpoint exch pop moveto shwd } def')
%image('/shwd {show} def')
This means that the PS augmentation and the PS driver are closely connected.
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, a stack used by the PostScript interpreter.
It is worth emphasizing that, in the test device, "sd" and "shwd" were not defined but were nonetheless inserted by wgml 4.0.
