Proposed DVI \special command standard

Don Hosek Harvey Mudd College^{∗} Claremont, CA

August 6, 1987

The information in this report includes some ideas based on responses to an article sent to the TEXhax mailing list and printed in the TEXMAG electronic “magazine”. Among those people who sent me suggestions were Neta Amit, Stephan Bechtolsheim, Peter Breitenlohner, ‘dorab’, John Gourlay, Jean-Francois Lamy, Kevin LaRue, William LeFebvre, and Thomas J. Reid. Also, Dean Guenther invited me to send my suggestions for the TUG meeting. I apologize if I left anyone out of this list.

1 Introduction

It is becoming clear that some sort of standard on the syntax and effect of \special commands is necessary. In my original report to TEXhax and TEX-MAG [4], I outlined some of the issues to be confronted in the development of a \special standard. These included device dependency, naming conventions and syntax, graphics, and scope (see also [2]).

Dean Guenther informs me that he hopes to see some definite standards for \special commands set after this year’s TUG meeting, and Stephan Bechtolsheim (dvi2ps) is holding off on writing the \special handling code for his latest version of the driver until the \special command issue is resolved. The suggestions in this paper are just that, suggestions; the specifications of this proposed standard are open to change. The final standard that comes out of this meeting should be specific enough that all implementations of it can generate identical results, but also open to extension to reflect changes and innovations in printing technology.

∗BITNET: DHOSEK@HMCVAX. Phone: (714) 621-8000. Postal address: Platt Campus Center, Harvey Mudd College, Claremont, CA 91711

2 Syntax

The general syntax for a \special command is: optional environment setting commands followed by the special command with multiple special commands separated by semicolons. A Backus-Naur Form^{1} syntax for \special commands follows:

special command → spec cmd ; special command | spec cmd
spec cmd → environment setting cmds cmd
| ϵ
environment setting cmds → env cmd environment setting cmds
| ϵ

Most possible cmd or env cmd values accept options that have the syntax described below:

options → required space opt options | ϵ
required space → ␣ optional space
optional space → required space | ϵ
opt → angle | position | scaling | tag | length | color

| cap shape | file name

angle → " real | / real , real
position → ( dimen , dimen ) | + ( dimen , dimen )
scaling → < opt real , opt real > | [ dimen , dimen ]
tag → chars :
length → req dimen

        color → black | white
             | red | blue | yellow
             | violet | green | orange
             | brown

| color & color

    cap shape → butt | round | square | bar

file name → opt area name opt ext
real → digit digit string

| digit digit string . digit string

opt real → real | ϵ
digit → 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
digit string → digit digit string | ϵ
dimen → opt real unit
req dimen → real unit
unit → scaled unit | true scaled unit | ϵ
scaled unit → pt | pc | in | bp | cm | mm | dd | cc | sp
chars → chr chars | ϵ
chr → letter | digit
letter → A —Z | a —z

1See [1] for additional information on BNF

opt area → < name > | name : | ϵ
opt ext → . name | ϵ

Details of the semantics of the various possiblities for env cmd or cmd are given in sections 3 and 4. However, a brief overview of the various env cmd and cmd values will be given, followed by an explanation of the various option values.

2.1 Overview of env cmd

An environment command or commands affect only the first cmd following it. Since cmd is never empty, this means that an environment setting command can not affect a cmd that is in a different \special than the one in which the env cmd appeared.

The following is a list of possible env cmd values with option list and a brief description. A detailed explanation will be deferred until Section 3. black color Set the color to be used as black. linecap cap shape Set the shape of line ends. linewidth length Set the width of lines. offset position Change the location of the output from cmd. turn angle Rotate the command. scale scaling Scale the command. white color Set the color to be used as white.

2.2 Overview of cmd

arc length angle angle Draw an arc. beginbar tag Begin a vertical bar at the current DVI h, v coordinates. circle length Draw a circle. disk length Draw a filled-in circle. endbar tag End a vertical bar at the current DVI v coordinate. include tag file name Include the graphics image of the type tag contained in

file name. landscape Orient the page in the landscape position. line length angle Draw a line. message Send option to the terminal.

newsheet Force a new sheet.

pie length angle angle Draw a filled-in arc.

portrait Orient the page in the portrait position.

rotate angle Rotate the page about the center of the real page.

spline position position position Draw a Bézier cubic.

textcolor color Set the current text color.

2.3 Overview of opt

The order in which the opt values appear in options is not important unless more than one opt of a given type appears in the paramter list.

2.3.1 Angles

An angle may be specified in two manners. It may be given as " followed by a real number (let us call it n). The angle θ represented, is then considered to be (in degrees) n mod 360 if n mod 360 ≤ 180, and 360−(n mod 360) otherwise. It may also be given as / followed by two reals separated with a comma (let us call them m and n). If n > 0 and m ≥ 0 then θ = arctan |m/n|; if n > 0 and m < 0 then θ = 180 − arctan |m/n|; if n < 0 and m ≥ 0 then θ = −180 + arctan |m/n|; if n < 0 and m < 0 then θ = − arctan |m/n|; if n = 0 and m < 0 then θ = 180; and if n = 0 and m > 0 then θ = 0. If m = 0 and n = 0 then the command should be flushed. All angles are considered to be counterclockwise measured from “up” on the current page orientation, unless specified otherwise.

If an angle must be rounded,^{2} it should be rounded as follows:

1. Assuming that the available angles of rotation are in the array p, scan through p from 1 to last in increasing order. Continue to scan until p_{i} ≥ θ.

2. If p_{i} − θ ≤ θ − p_{i−1} then round θ to p_{i}, otherwise, round θ to p_{i−1} (p_{0} should be set ridiculously low, to make sure that θ is rounded to p_{1} if θ < p_{1}).

2This generally only applies to rotation of figures or pages where the array of available rotations would tend to be relatively small, such as [-180, -90, 0, 90].

2.3.2 Dimensions

Dimensions are specified in essentially the same format as TEX uses (see [7, Chapter 10] for details on the meanings of the units used). One extension to this format is that integer values shall be assumed to be in terms of DVI units (as defined in [6, §13–20]). In the case of TEX82, DVI units are always scaled points (2^{−16} points) so a construction such as \number\mydimen will yield a valid dimension for a \special command. This could be used by macros that generate \special commands rather than \the\mydimen to keep computations by the postprocesor down.

Dimensions should be rounded to pixel dimensions using the algorithim of rule pixels [6, §76].

2.3.3 Positions

An offset may be described in two manners. An absolute offset is given as (x, y) where x and y are optional dimensions. If the dimension is omitted, the current h or v is substituted for it. The standard DVI coordinate system is used (see [6, §14]).

A relative offset is specified as +(x, y) where x and y are optional dimensions. If a dimension is omitted, it is treated as zero. x is added to the current h, and y is added to the current v to get the position for the output of the \special command.

2.3.4 Scaling

Scaling may be described in two manners. Absolute scaling is given as [x, y] where x and y are optional dimensions. If a dimension is omitted, the natural width of the \special’s output is substituted for it. When given, x or y cause the width or height of the \special’s output to be scaled to match the given dimension.

Relative scaling is specified as <x, y> where x and y are optional reals. If x or y are omitted, then they are treated as 1. Scaling is performed by multiplying the natural width of the special by x and the natural height by y.

2.3.5 Tags

A tag is used to indicate the nature of external information to be included. Their interpretation is given under the description of each command that uses them in section 4. Tags may be of any length.

2.3.6 Lengths

A length is given as a dimension. It may not be omitted.

2.3.7 Colors

A color may be one of the names from the definition of color or some combination of them. A color not in the list of names may be obtained by “mixing” colors (e.g. pink may be specified as red&white). If two graphic objects overlap that are of different colors, then the object whose definition occurs later in the page should take precedence.

2.3.8 Line Cap Shapes

The shape of the end of a line may be one of three forms:^{3}

butt The line is squared off at its endpoint.

round A semicircle with radius equal to half of the line width is drawn at the end of the line.

square The line is extended one half of the line width past its endpoint and squared off.

bar If the line is vertical at its endpoint, this is treated as a butt cap. Otherwise, a vertical line is drawn through the endpoint, and the edges of the lines are extended or retracted to meet the vertical line drawn.^{4}

2.3.9 File Names

File names are specified in the same manner as used by TEX and (see [8, Part 29] for details and WEB code). The default directory specification is left up to the DVI driver designer, although it is suggested that there be some standard directory defined for commonly used included images (such as a letterhead). Default file extensions are dependent on the context of file name.

3 Environment setting commands

The commands described here are used to set certain parameters on graphics, etc., \special commands. They only affect the cmd following them. For example, In the following series of \special commands, the color special will only affect the line command, not the arc.

\special{color red line "0 1in; arc "-10 "10 1in}
\special{color red line "0 1in}
\special{arc "-10 "10 1in}

The individual commands are described below, organized by their effects.

3[5, p. 217] contains illustrations of three of the line caps described

4This is primarily intended for musical typesetting. See [3] and [10] for more information on the subject.

3.1 Color setting commands

The black and white commands set colors to be used by graphics commands.

black color Set the color to be used for “black”. i.e., the color that lines and curves of graphics primitives are to be drawn in and the color to be used for pixels to be colored in an included graphic image. The default black

     is black.

white color Set the color to be used for “white”. i.e., the color that will be used for pixels that are set off in an included graphic image. The default white is white.

3.2 Line and curve parameter commands

These commands are intended to affect the shapes of lines and curves drawn by graphics primitives.

linecap cap shape Set the shape of the ends of lines. See the description of cap shape above for details on that parameter. The default line cap is

     butt.

linewidth length Set the width of lines and curves to be drawn by graphics primitives. The edges of the line will be half the line width from the zero-width path of the curve or line. The default line width is 0.38889pt.

3.3 Translation and rotation

Graphic output is normally placed at the current DVI h, v coordinates. These commands alter the placement and sizing of graphic output from a \special command.

offset position Move the output of the \special command by/to position. The default is to print it where it appears.

turn angle Rotate the output of the \special command about the position where it appears. The default is to leave it unrotated.

scale scaling Scale the output of the \special command by the amount specified by scaling. The default is to print the output at the natural size.

4 Proposed commands

No cmd may affect any page other than the one upon which it appears. A cmd also may not change the positioning of text. The commands proposed are listed below, organized by type.

4.1 Duplex printing

Duplex printing (i.e., printing on both sides of a sheet of paper, is a feature available with some output devices. Duplex printing can only be selected on a global basis (generally through a command-line option), but a new sheet may be forced if necessary (for example, for a table of contents page that is output at the end of the document). This is accomplished with the newsheet command.

newsheet Force a new sheet on output. If newsheet appears on a page that would normally be printed on the back of a sheet of paper than that page will be printed on a new sheet of paper. If the \special appears on the front of a sheet of paper (this is always the case in simplex printing) then newsheet has no effect.

4.2 Page orientation

Most output devices have the ability to print output rotated by 90^{∘} and sometimes other values. This can be globally specified only by the user interface to the DVI-driver. Changes on a single page basis may be made through \special commands listed below (These commands will generally be issued inside of a

command pair such as \pageinsert ... \endinsert).

rotate angle The page that rotate appears upon will be printed rotated n^{∘} counterclockwise from the vertical position on the actual sheet. If necessary, the angle should be rounded as outlined in section 2.3.1. If more than one rotate occurs on a given page, the one occurring later takes precedence.

landscape A specialized case of rotate. angle is set to 90^{∘}.^{5}

portrait A specialized case of rotate. angle is set to 0^{∘}. This is likely to only be of use in a document with a global orientation other than 0^{∘}.

4.3 Graphics Inclusion

To maintain a reasonable degree of compatibility between device drivers for graphics inclusion, a graphics inclusion facility must know something about the nature of the graphics file. This may be either the intended destination of the graphics file (for example, a file may be composed of Hewlett-Packard LaserJet Plus control codes) or the source of the file (MacPaint, for example can generate PostScript output; however, it contains additional header information which must be stripped off of the file before it can be included in a PostScript file generated by some DVI-to-PS program).

A DVI driver should insure that the current real values of h and v are not changed by any included graphics. If the device allows absolute positioning on the page, then the simplest approach is to simply reset the position on the page; otherwise the driver must keep track of position changes in the included file and compensate appropriately afterwards.

5Or −90^{∘} if 90^{∘} is not available and the former is.

include tag file name Include the graphics file in file name of type tag.

tag indicates the nature of the graphics file. Intelligent drivers should be able to interpret “foreign” graphics formats. Possible values for tag are: (this is not a full list; other values may be added as necessary to reflect new printers or graphics software)

BITMAP: The file is a bitmap of an image with the first fullword indicating the width of the bitmap (in pixels), the second fullword indicating the height of the bitmap, and third fullword indicating the intended resolution (in dpi). The data following this is the binary data for the bitmap scanning from left to right horizontally and top to bottom vertically. If rows will not align on fullwords, then they will be padded on the right with 0 bits.

EPIC: The file is composed of EPIC graphics commands.

HALFTONE: The file contains a halftone graphics image. Format is similar to that for BITMAP: except that the first byte contains a value indicating how many bits each pixel requires to store its gray-scale value.

IMP: The file is composed of IMPRESS commands.

INTER: The file is composed of Xerox Interpress commands.

MAC: The file is a PostScript file created by a MacIntosh graphics program such as MacPaint.

PCL: The file is composed of PCL instructions.

PS: The file is composed of PostScript commands.

QUIC: The file is composed of QUIC control sequences.

TEK: The file is composed of Tektronics plot commands.

The file name is as described above in section 2.3.9. The default filetype is tag (less the colon).

4.4 Graphics primitives

The ability to generate simple figures using graphics primitives has been used in the program DVIIMP [11] and a few versions of other DVI-drivers. There is also a Unix utility called tpic which uses pic commands to generate \special commands for TEX. The philosophy of these graphics primitives could also be applied to the LaTEX picture environment (see [9]) to allow more freedom in the choice of graphic objects.

All graphics primitives ignore white. The following graphics primitives are provided:

arc length angle angle Draw an arc centered at the current position with radius length from the first angle counterclockwise to the second angle.

circle length Draw a circle with radius length centered at the current position.

disk length Draw a filled circle with radius length centered at the current position.

line length angle Draw a line of length length at an angle of angle from the current point.

pie length angle angle Draw two lines of length length at the two angles specified, and an arc with the length and angles above, and fill the figure in with the current black color.

Line joins are mitred. The outer edges of the two lines are extended until they meet. If the difference between the two angles is less than 10^{∘} then the join is drawn as if the two lines each had round line caps and no special joining was done.

The linecap setting is ignored.

spline position position position A Bézier cubic is drawn from from the current position to the last position in options using the second and third positions as control points.

4.5 Miscellaneous \special commands

The following miscellaneous commands should also be provided.

beginbar tag Begin a vertical line at the current DVI h, v coordinates. The line continues until the v coordinate of the matching endbar on the page. If there is no matching endbar, then no line is drawn.

endbar tag End a vertical line at the current v coordinate (see beginbar).

message option Output option to the terminal. If the DVI-driver does not output page numbers as it processes the file, it should print the TEX page number (from the bop command see [6]) before printing message text.

textcolor color All text from the first DVI push to its matching pop are to be typeset in color.

References

[1] Alfred V. Aho, Ravi Sethi, and Jeffrey D. Ullman. Compilers: Principles, Techniques, and Tools. Addison-Wesley, Reading, Massachussetts, 1986.

[2] Jim Fox. Change bars. TUGboat, 7(3), 1986. Appeared in “Queries” section.

[3] John S. Gourlay, Allen Parrish, Dean K. Roush, F. Javier Sola, and Yiling Tien. Computer formatting of music. Technical Report OSU-CISRC-2/87-TR3, Ohio State University, 1986.

[4] Don Hosek. Call for standardization of dvi specials. TEXMAG, 1(5), 1987.

[5] Adobe Systems Incorporated. PostScript language reference manual. Addison-Wesley, Reading, Massachussetts, 1985.

[6] Donald E. Knuth. The dvitype processor. WEB program, Stanford University, August 1984.

[7] Donald E. Knuth. The TEXbook. Addison Wesley, Reading, Massachusetts, 1986.

[8] Donald E. Knuth. TEX: The Program. Addison Wesley, Reading, Massachusetts, 1986.

[9] Leslie Lamport. LaTEX: A Document Preparation System. Addison Wesley, Reading, Massachusetts, 1986.

[10] John S. Renner. TEXtyl: a line-drawing interface for TEX. Technical Report OSU-CISRC-4/87-TR9, Ohio State University, March 1987.

[11] Arthur L. Samuel. The dviimp processor. WEB program, Stanford University, July 1985.