Drawing Boxes
From Open Watcom
Contents |
Introduction
This page explores the box-drawing behavior of wgml 4.0. It includes the device library blocks that are used in the actual drawing as well as the control words and layout/document tags that are used to cause boxes to be drawn.
This initial version records what is known so far. Additional work is needed and will eventually be done.
The Required :BOX Block
The :BOX block, which is a required part of the :DEVICE block, defines the line-drawing characters and the font they are to be taken from.
The :ABSOLUTEADDRESS, :HLINE, :VLINE, and :DBOX Blocks
These blocks are all optional, but that does not mean that they can be used arbitrarily.
While attempting to get wgml 4.0 to interpret the :VLINE block, I discovered that :DRIVER block without an :ABSOLUTEADDRESS block but with the :HLINE, :VLINE, and :DBOX blocks would produce an "Abnormal program termination" -- but only when used to process a document specification which caused :VLINE to be interpreted.
This table shows every occurrence in the source files available to me:
Source File :ABSOLUTEADDRESS :HLINE :VLINE :DBOX hpldrv.pcd Yes hplpdrv.pcd Yes Yes Yes hplpldrv.pcd Yes Yes Yes mltdrv.pcd Yes Yes Yes psdrv.pcd Yes Yes Yes Yes x2700drv.pcd Yes Yes Yes
No other source file available to me has any of these blocks in it.
Two obvious deductions can be drawn:
- An :ABSOLUTEADDRESS block is a prerequisite the other three blocks.
- The :HLINE and :VLINE blocks always appear together.
Section "15.9.15 VLINE Block" of the WGML Reference describes the intended context of :VLINE in this way:
The special symbols %y_size and %thickness are defined prior to processing the vline block. The symbol %y_size is set to the height of the vertical line, from the top edge to the bottom edge. The symbol %thickness is set to the value specified by the vline blocks thickness attribute. WATCOM Script/GML positions to the bottom left corner of the line before creating the rule line, and assumes the current point of the device is set to the top left corner of the line when finished.
In other words, a :VLINE block is expected to draw the line in an upward direction. Since a device that does not define :ABSOLUTEADDRESS has no ability to move the print position upwards (negative values of the attribute skip of the :NEWLINE block are not allowed, see the discussion here), it is not surprising that attempting to use :VLINE without :ABSOLUTEADDRESS causes a problem.
An :HLINE block, in contrast, is expected to draw the line from left to right, and so does not require :ABSOLUTEADDRESS -- provided wgml 4.0 always starts it on the correct line and does not attempt to go back up to print out text.
The :DBOX block starts at the bottom left corner and so would, in practice, have to go back up to draw the top and sides of the box, although it does not produce an "Abnormal program termination" in the absense of an :ABSOLUTEADDRESS block.
Clearly, which blocks are present depends on the characteristics of the device. Many devices have none of them, presumably because they produce their output one line at a time.
The .bx Control Word
This is a Script control word, and wgml 4.0 will ignore it entirely unless "script" is placed on the command line (or in an option file, such as default.opt).
If the first example given in the document Waterloo SCRIPT for the control word ".bx":
.in 4 .bx 1 70 .sk;.la ONE;.ce TWO;.ra THREE .sk;.bx This is a continued box showing formatted text in a box. .bx off
when used with my test device, this produced the message:
SC--062: Invalid box position
which was fixed by rewriting
.bx 1 70
to
.bx 10 20
after which the control word ".ra THREE" produced this error message:
SC--006: Unrecognized control word
together with the line number and the offending control word itself. From this, it appears that, if we ever want to, we can determine which of the known wgml 4.0 by simply having it process a list of them.
This allowed wgml 4.0 to complete document processing. For further testing, this sequence was used:
.in 4 .bx 10 20 40 .bx char This is a box showing formatted text in a box. .bx off
In this case, the :VLINE block was not used, only :HLINE.
Experimentation showed, some of the time, that inserting such control words as
.bx char .bx 2 70
into the file resulted in the :VLINE block being interpreted. But only some of the time, and other sequences appeared, some of the time, to work just as well. On the other hand, a PostScript version showed all three vertical lines. Taken together with the problem with ".bx 1 70", it is possible that something else entirely is affecting how .bx is treated by wgml 4.0.
The observed behavior (so far, with limited testing) of .bx is:
- If :HLINE and :VLINE are present, they are used (well, :HLINE is used; use of :VLINE is harder to control).
- If :HLINE and :VLINE are not present, then the characters specified by :BOX are used.
The Layout/Document Tags
There are three tags which can cause wgml to draw boxes if a particular attribute is given the value "box":
Tag Type Attribute :FIG Document frame :FIG Layout default_frame :IXHEAD Layout frame
The :FIG tags pertain to figures; the :IXHEAD tag pertains to index headings.
The observed behavior (so far, with limited testing) is:
- If :DBOX is present, then it is used.
- If :DBOX is not present, but :HLINE and :VLINE are present, then :HLINE and :VLINE are used to draw the box for figures but not for index headings (no box appears at all around the index headings in this case). Note that :VLINE, in the limited testing performed, was only used here when it was used with .bx.
- If neither :DBOX nor :HLINE/:VLINE are present, then the characters specified by :BOX are used for both figures and index headings.
It is surprising that :IXHEAD behaves differently from :FIG when :DBOX is not provided but :HLINE and :VLINE are.
Implementation Notes
Our wgml is intended to be a drop-in replacement for wgml 4.0 in the Open Watcom document build system. As such, it will be used with two devices (PS and WHELP). One of these devices (PS) provides all four of the :ABSOLUTEADDRSS, :HLINE, :VLINE and :DBOX blocks, and so boxes requested by tags :IXHEAD and :FIG appear and are drawn by wgml 4.0 using :DBOX. The other device (WHELP) provides none of them, and so boxes requested by tags :IXHEAD and :FIG appear and are drawn by wgml 4.0 using the characters and font prescribed by the :BOX block (at least, they do in the output file; what whlpcvt.exe does with them is not part of implementing wgml/gendev).
This means that the situation where :ABSOLUTEADDRESS, :HLINE and :VLINE are provided but :DBOX is not does not occur in the Open Watcom document build system. Since section "15.9.16 DBOX Block" of the WGML Reference states:
If this block is not specified, rule lines will be created with the hline and vline block definitions.
it would seem reasonable to implement box drawing so that :HLINE and :VLINE are used when they are provided but :DBOX is not, even when drawing boxes for :IXHEAD, unless some reason for not using them with :IXHEAD becomes apparent during the implementation of our wgml.
The control word .bx is used in the Open Watcom document specifications, and so will have to be implemented. Since it is documented in Waterloo SCRIPT with this statement:
BOX generates the horizontal lines and initiates the vertical lines of a box.
and since none of the examples shows a box without sides, there is no reason to believe that .bx was ever intended to not generate the sides of a box. So, unless some reason for not doing so becames apparent during the implementation of our wgml, .bx should always generate the sides of the box (plus any internal vertical lines).
This produces a unified view of box-drawing in our wgml:
- For the tags, if :DBOX is defined, then use :DBOX.
- If :HLINE and :VLINE are defined (and, for the tags, if :DBOX is not), then :HLINE and :VLINE should be used. :VLINE should be used whenever :HLINE is used to draw a box.
- Otherwise, the characters provided by :BOX should be used.
It should be pointed out that drawing with :DBOX, with :HLINE and :VLINE, and with the :BOX block characters are quite different operations. Thus, informal observations show that :DBOX is invoked after the text has been displayed, while :HLINE is usually invoked before, during, and after the text is displayed, depending on how the result is intended to look, followed by the :VLINE invocations. When characters are used, then the horizontal lines appear in order before, during, or after the text but the vertical characters appear as part of each line of text. This implies that our wgml will need to know whether :DBOX is defined and, if it is not, whether :HLINE and :VLINE are defined, so that it may select the correct method to use to draw the box.
This should simplify the implementation of this small part of our wgml. There are two situations which might require that behavior closer to that of wgml 4.0 will need to be implemented:
- Since our wgml is to be a drop-in replacement for wgml 4.0 in the OW document build system, it is possible that, during testing, it will turn out that always using :VLINE results in our wgml producing a different result than wgml 4.0 does.
- If our wgml is released more widely, then it is possible that those with existing wgml installations may report that they need the wgml 4.0 behavior implemented more exactly.
However, for the devices used by Open Watcom, the simplified form should work.
Future Directions
This are easily-seen topics for future exploration:
- Verification of how .bx works in wgml 4.0 (it has several operands).
- Determining whether or not .bx and the GML tags use a common context for box-drawing.
