APPLICATION NOTE #189 USING POSTSCRIPT TO ADD LINES AND BORDERS Rev. 01 PostScript is a page description programming language produced by Adobe Systems, Inc., that is used to drive certain printers and typesetters. You can use the PostScript language to add graphic elements--from boxes and rules to more elaborate images--to your documents. This application note shows you how to use very basic PostScript line and box drawing programs with XyWrite, and gives you samples which you can apply to your own documents. SOME BASICS OF POSTSCRIPT PostScript is a powerful programming language that is most often used by application software to control the printing of text and graphics. It is designed to be read by an interpreter which converts the code to a device-specific format. With a little knowledge of this language, you can send your own instructions to the printer, whether you want to draw a simple line or a more elaborate image. The following paragraphs introduce some basic PostScript commands and concepts. These paragraphs do not constitute a comprehensive description, but provide some information on the commands that are used in our examples. For a broader understanding of what PostScript can do, we recommend that you read the PostScript Language series of manuals published by Adobe Systems, Inc. and Addison-Wesley Publishing Company, Inc. The PostScript Page PostScript programs do not follow the page formatting that you established in your document with XyWrite commands. You must tell the printer exactly where on the page to position your graphic. PostScript looks at the page as a grid, with the lower left corner having the value of 0,0. You can identify any point on the page by its x and y coordinates, where x is the distance along the bottom of the page and y is the distance up the side. For example, to move 72 points to the right and 144 points up the page, the position is "72 144." (See Note #1.) Note #1 Units of Measure. PostScript's standard unit of measure is points (72 points = 1 inch). You can use other units of measure if you define those units in your program (see "Dictionaries"). If you are specifying a position in units other than points, you must identify that unit after each number (e.g., 1 inch 2 inch). Otherwise, PostScript assumes the number is in points. Operands and Operators Each step of your PostScript program uses values called operands and commands called operators. The operand is a value that will be used by the following operator. For example, in the statement "1 setlinewidth," 1 is an operand representing the value of 1 point, and setlinewidth is the operator which specifies the line width. You separate operands and operators with space(s), tab(s), or return(s). To PostScript, one or several spaces, tabs, and returns serve the same purpose. The only exception is that you cannot use returns when typing in PostScript mode (see Note #3). Graphic State Each PostScript program must start with a closed parenthesis and end with an open parenthesis. This convention notifies the printer that you are suspending the printing of your text to run a PostScript program. When you suspend the current printing of your document, you must issue the show operator. Show instructs the printer to print all the text prior to the closed parenthesis. XyWrite's PostScript printer files define "s" to be the show operator. Next, you must save the graphic state, which is the set of data that controls all graphic parameters of your document, such as the current path, font, position, line width, and more. The gsave operator saves all these parameters, and the grestore operator restores them. Start each program with s and gsave, and end it with grestore. Paths PostScript follows a path to draw text, lines, shapes, and other graphics. When you suspend the printing of text to run your program, you must state whether you want the printer to start a new path or stay on the current path. You use the newpath and currentpoint operators to indicate your choice. The path of your drawing is defined by x and y coordinates. You mark the starting coordinate with the moveto operator, and the subsequent line drawing coordinates with the lineto operator. For example, "36 756 lineto" defines a line that runs from the previous point in the path to the point where x=36 points and y=756 points. When you have marked all the points, the closepath operator sets a line which returns to the point of origin (the point defined by the last moveto operator). Dictionaries PostScript allows you to define terms that you will use later in your programs. As mentioned previously, you can define an inch as a unit of measure. This is done with the following statement: /inch {72 mul} def The slash (/) before "inch" denotes that the following term is a literal name to be defined for the dictionary. The curly braces are used to encompass the operands and operators that define an inch. In this case, the definition means multiply the previous number by 72 to convert it to points (mul means multiply). The def operator executes the function of defining the term and storing it in the dictionary. Drawing Operators Once you have marked the coordinates of your graphic, you have to tell the printer what to do with them. You must first establish the weight of the line with the setlinewidth command. To draw a line through each of your coordinates, use the stroke operator. If you want to shade the area you have marked off, use the fill operator. This operator puts a solid color within the perimeter of your coordinates. You can use the setgray operator to screen (lighten) the color. In the example below, we are drawing two 1-point lines as a border around the entire page. The first line will be inset from the edge of the page by .5", and the second is inset by an additional .05". Note that the operands and operators that mark the coordinates are separated by a tab. The first column shows the x coordinates, and the second shows the y coordinates. ) s gsave /inch {72 mul} def newpath .5 inch .5 inch moveto .5 inch 10.5 inch lineto 8 inch 10.5 inch lineto 8 inch .5 inch lineto closepath .55 inch .55 inch moveto .55 inch 10.45 inch lineto 7.95 inch 10.45 inch lineto 7.95 inch .55 inch lineto closepath 1 setlinewidth stroke grestore ( This program tells the printer to start a new path, and then gives the coordinates for the lines. First, the printer must "moveto" the position .5 inch, .5 inch. Then it marks the coordinates that you will use to draw the borders. Once the coordinates have all been marked, then the line width of the borders is set to 1 point and the printer is instructed to "stroke" the lines. Relative Operators You can use the relative move and line operators, rmoveto and rlineto, when you want to describe coordinates in relation to their starting point. For example, if you want to put a border around a paragraph which immediately follows in the text, your drawing operators can mark the coordinates relative to that paragraph. As long as the program is adjacent to the affected paragraph, you can move the paragraph without having to change the coordinates of the border. Each rlineto operator moves to a point relative to the last point marked. USING THE INCLUDE COMMAND WITH POSTSCRIPT The IN (Include) command allows you to have the contents of any printer-ready file incorporated in your document. You can write a PostScript program in a separate file within XyWrite and use the IN command to send it to the printer as part of your document. At the point which the printer sees the IN command, it executes the graphic routine specified in the program. 1. Create your PostScript program file with the NEW command: Type: F5new border 2. Type the PostScript code into the file. Do not use any embedded formatting commands in your program file, because they interfere with the PostScript coding. For example: )s gsave newpath .5 inch .5 inch moveto .5 inch 10.5 inch lineto 8 inch 10.5 inch lineto 8 inch .5 inch lineto closepath 1 setlinewidth stroke grestore ( 3. Store the file. 4. Call your document. 5. Move the cursor to the page on which you want to execute the PostScript program. 6. Insert the IN (Include) command at the point you want the program to take effect. For this example, you should insert it at the top of the page. Type: F5in border 7. Send the document to the printer. Type: F5ty Note #2 File End Markers & IN Command. In XyWrite III Plus for Networks, any document that is printed at COMn or LPTn printer ports will be sent using the TYF (Type to File) command (n is any number). The TYF command inserts a file end marker at the end of every XyWrite file, including those which are sent using the IN command. The file end marker causes the printer to stop when it reaches the end of the included file. In these instances, your network administrator may be able to redirect the output or you can write the programs using the PostScript font. WRITING PROGRAMS IN POSTSCRIPT MODE Every PostScript printer file for XyWrite III Plus (3POSTPLS.PRN, 3POST.PRN, 3LAND.PRN, and 3LANDPLS.PRN) contains a PostScript font. This font allows you to type PostScript code directly into your document without using the IN command. You can then edit the programs and affected text at the same time. The PostScript font (shown below) begins with the show (represented by "s") and gsave operators, and ends with the grestore operator to save and restore the graphic state of your document. The characters of your PostScript program will not print, nor will they affect vertical or horizontal spacing. FO:postscript FO< ) s gsave FO> grestore ( vl=0 UW:postscript ET To use PostScript mode: 1. Assign it to a non-standard mode in your PT tables. In the example below, the PostScript font was assigned to MD 70. MD 70+POSTSCRIPT 2. Store and load the printer file. 3. Call the file you want to modify. 4. Move the cursor to where you want the program to take effect. 5. Enter PostScript mode. Type: F5_md 70_ 6. Type in the program. Do not type any carriage returns (see Note #3). For example, to draw a box relative to the current point in the file: 0 -58 rlineto 238 0 rlineto 0 58 rlineto closepath .5 setlinewidth stroke 7. Return to normal mode and enter a carriage return. Type: F5md nm Press: 8. Print your file. Result: The example above starts from the current point and moves down the page 61 points, moves to the right 238 points, and so on until the border is closed. Then it sets the line width at .5 point and strokes the line. A negative number for x instructs the printer to move down the page, and a negative number for y means move to the left. Note that all measurements are in points. Note #3 Carriage Returns. You cannot enter a carriage return when you type in PostScript mode. That's because XyWrite returns to normal mode when it sees a carriage return, which disrupts the PostScript coding. If you want to execute two drawing functions after you have marked the coordinates of the box (e.g., draw a border and then fill it with a gray screen), you can use the define operator to store the coordinates in a PostScript dictionary. In the example below, we define BOX1 to have the same coordinates as the previous example. The definition is followed by the two drawing functions that will affect BOX1. This program will stroke a line that is 1 point wide and fill the area with a gray screen. The fill operator alone would make BOX1 entirely black. The setgray operator screens the black so that the fill will appear gray. Setgray has two extreme values: 1 for white and 0 for black. A decimal value between 0 and 1 sets gray screens of varying density. currentpoint currentpoint /BOX1 {moveto 0 -61 rlineto 238 0 rlineto 0 61 rlineto -238 0 rlineto} def BOX1 1 setlinewidth stroke BOX1 .95 setgray fill Note that the currentpoint operator is listed twice. Since two functions are being executed on the BOX1 coordinates, you need to set the current point twice for the moveto operator to pick up the correct point on the first and second pass. If you were going to execute a third function, another currentpoint operator would have to be included in the program. Note #4 Returning to Current Point. When you enter a PostScript routine, PostScript remembers its current position when you issue the gsave operator, and it returns to that spot when the grestore operator is executed. That means that you can be in the middle of the page when you enter PostScript commands that draw a box around the entire page. After the drawing is done, the printer returns to the middle of the page, exactly where it encountered the PostScript program. Note #5 Using Error Messages. Many PostScript printers come with a software file called ERHANDLR.COM. If you copy this file to your PostScript printer, it will print error messages at the point they occur in your document. The error messages will help you understand and correct any mistakes in your PostScript program. ###