Inside Pstricks
Total Page:16
File Type:pdf, Size:1020Kb
Inside PSTricks Timothy Van Zandt Department of Economics, Princeton University, Princeton, New Jersey USA [email protected] Denis Girou Institut du D´eveloppement et des Ressources en Informatique Scientifique Centre National de la Recherche Scientifique, Orsay, France [email protected] Abstract The macro-commands of the PSTricks package offer impressive additional ca- pabilities to (LA)TEX users, by giving them direct access to much of the power of PostScript, including full support for color. The purpose of this article is to outline the implementation of a few of the features of PSTricks (version 0.94). Introduction 2. Other drawing tools, such as a picture environ- ment, various commands for positioning text, When a PostScript output device and a dvi-to-ps and macros for grids and axes. driver are used to print or display TEX files, TEX and PostScript work together, as a preprocessor and 3. Commands for rotating, scaling and tilting text, a postprocessor, respectively. The role of PostScript and 3-D projections. may simply be to render TEX’s dvi typesetting in- 4. Text framing and clipping commands. structions. However, the full power of PostScript 5. Nodes and node connection and label com- can be accessed through \special’s and through mands, which are useful for trees, graphs, and features, such as font handling, built into the dvi- commutative diagrams, among other applica- to-ps driver. tions. One can divide the PostScript enhancements to 6. Overlays, for making slides. TEX into roughly four categories: 7. Commands for typesetting text along a path. 1. The use of PostScript fonts. 8. Commands for stroking and filling character 2. The inclusion of PostScript graphics files. outlines. 9. Plotting macros. 3. The coloring of text and rules. For information on PSTricks from the user’s 4. Everything else. point of view, consult the PSTricks User’s Guide Most TEX-PS users are familiar with the first three (Van Zandt, 1994) and the article by Denis Girou categories. The PSTricks macro package, by Timo- (Girou, 1994) in Cahiers GUTenberg, the review of thy Van Zandt, attempts to cover the fourth cate- the French TEX users’ group. The latter article is gory.1 useful even to those who do not read French, because The PSTricks package started as an implemen- it consists predominantly of examples. Several of tation of some special features in the Seminar doc- these examples appear in this paper, courtesy of ument style/class, which is for making slides with Cahiers GUTenberg. LAT X2 . However, it has grown into much more. E ε Who can use PSTricks? Below are some of its current features: A goal of PSTricks is to be compatible with any T X 1. Graphics objects (analogous to LATEX picture E commands such as \line and \frame), in- format and any dvi-to-ps driver. Compatibility with cluding lines, polygons, circles, ellipses, curves, the various TEX formats is not difficult to achieve, springs and zigzags. because PSTricks does not deal with page layout, floats or sectioning commands. 1 PSTricks is available by anonymous ftp from However, compatibility with all dvi-to-ps drivers Princeton.EDU:/pub/tvz and the CTAN archives. is an unattainable goal because some drivers do TUGboat, Volume 15 (1994), No. 3 — Proceedings of the 1994 Annual Meeting 239 Timothy Van Zandt and Denis Girou not provide the basic \special facilities required One can also use the source file directly, in by PSTricks. The requirements are discussed in which case no header is used. This is convenient subsequent sections. All of PSTricks’ features work when developing the macros, because TEXandPost- with the most popular driver, Rokicki’s dvips,and Script macros can be written together, in the same most features work with most other drivers. file, and it is not necessary to make stripped input Two dvi-to-ps drivers that support the same and header files each time one is testing new code. \special facility may have different methods for The use of header files in PostScript documents invoking the facility. Therefore, PSTricks reads a reduces the size of the documents and makes the configuration file that tells PSTricks how to use the code more readable. However, the real benefit of us- driver’s \special’s. ing header files with PSTricks is that it substantially improves TEX’s performance. It reduces memory Header files requirements because, for example, the definition of A PostScript header (prologue) file is analogous to \tx@Atan takes up less memory and, more impor- aTEX macro file. It comes towards the beginning tantly, \tx@Atan takes up less string space each time of the PostScript output, and contains definitions it is usedin a \special. It reduces run time because of PostScript procedures that can be subsequently the writing of \special strings to dvi output is very used in the document. slow. A file that makes intensive use of PSTricks can It is always possible to add a header file to a run 3 to 4 times slower without header files! PostScript file with a text editor, but this is very Parameters and Lengths tedious. Most drivers support a \special or a command-line option for giving the name of a header To give the user flexible control over the macros, file to be included in the PostScript output. For without having cumbersome optional arguments example, the \special whose syntax is difficult to remember, PSTricks uses 2 \special{header=pstricks.pro} a key=value system for setting parameters. For example, tells dvips to include pstricks.pro. However, a few drivers, such as Textures (up \pscoil[coilarm=0.5,linewidth=1mm, through v1.6.2, but this may change) do not have coilwidth=0.5]{|->}(5,-1) this feature. Therefore, PSTricks can also be used without header files. From a single source file, one can generate a header file, an input file for use with headers, and an input file for use without headers. For example, the main PSTricks source file, The coilarm parameter in this example is the pstricks.doc, contains the line: length of the segments at the ends of the coil. \pst@def{Atan}<% Note that coilarm was set to 0.5, without units. /atan load stopped{pop pop 0}if> Whenever a length is given as a parameter value When generating the header file pstricks.pro,the or argument of a PSTricks macro, the unit is op- line tional. If omitted, the value of \psunit is used. /Atan {/atan load stopped{pop pop 0}if}def In the previous example, the value of \psunit was 1cm. Therefore, coilarm=0.5cm would have is written to pstricks.pro. When generating the given the same result. Omitting the unit saves key input file pstricks.tex for use with pstricks.pro, strokes and makes graphics scalable by resetting the the line value of \psunit. This is why the arguments to \def\tx@Atan{Atan } LATEX’s picture environment macros do not have A is written to the input file. The input file for use units. However, unlike LTEX’s picture macros, without pstricks.pro contains instead the line with PSTricks the unit can be given explicitly when convenient, such as linewidth=1mm in the previous \def\tx@Atan{% example. /atan load stopped{pop pop 0}if } The implementation of this feature is simple. Other macros can use \tx@Atan in the PostScript \pssetlength is analogous to \LaTeX’s \setlength code, without having to know whether it expands command, but the unit is optional: to a name of a procedure (defined in a header file) 2 PSTricks has recently adopted David Carlisle’s improved or to the code for the procedure (when there is no implementation of the parsing, contained in the keyval pack- header file). age. 240 TUGboat, Volume 15 (1994), No. 3 — Proceedings of the 1994 Annual Meeting Inside PSTricks \def\pssetlength#1#2{% Arithmetic \let\@psunit\psunit \afterassignment\pstunit@off One of the limitations of TEXisitslackoffast, #1=#2\@psunit} floating-point arithmetic. It is possible to write \def\pstunit@off{% routines for calculating, for examples, sines and \let\@psunit\ignorespaces\ignorespaces} cosines using TEX’s integer arithmetic, but these are One advantage of the key=value system is that notoriously slow. Therefore, PSTricks offloads such PSTricks has control over the internal storage of val- arithmetic to PostScript, whenever possible. ues. For example, PSTricks stores most dimensions Such offloading is not always possible because as strings in ordinary command sequences, rather PostScript cannot send information to TEX. If TEX than in dimension registers. It uses only 13 of the needs to know the result of some calculation, it must scarce dimension registers, whereas, for example, do the calculation itself. For example, suppose that P CT X uses over 120. When PSTricks processes one wants a macro that puts a triangle around a I E A the parameter setting coilarm=0.5, it executes: TEX box, analogous to LTEX’s \fbox command. The macro can measure the T X box, and pass \pssetlength\pst@dimg{0.5} E \edef\psk@coilarm{\pst@number\pst@dimg} these dimensions to a PostScript procedure via a \special. PostScript can then use its trigonometric \pst@dimg is a register. \pst@number\pst@dimg functions to calculate the coordinates of the vertices expands to the value of \pst@dimg,inpt units, but of the triangle, and then draw the triangle. However, without the pt. Hence, \psk@coilarm is ready to it may be important for T X to know the bounding be inserted as PostScript code. E box of the triangle that is drawn, so that the triangle Color does not overlap surrounding text. In this case, TEX must do (slowly) the trigonometric calculations To declare a new color, the user can type: itself.