Debian Codegraph @

texmf-dist/doc/support/texdraw/texdraw.texi

raw
1 % -*-texinfo-*-
2
3 % $Id: texdraw.texi 2.11 2019/04/18 TeXdraw-v2r3 $
4
5 % To produce a TeX version of this manual, you must have the following
6 % files accessible to TeX.
7 % texdraw.texi - this file, the TeXdraw manual, part of the TeXdraw
8 % distribution
9 % texdraw.tex - the TeXdraw macros, part of the TeXdraw distribution
10 % txdtools.tex - extra macros for TeXdraw, part of the TeXdraw
11 % distribution
12 % texinfo.tex - texinfo manual macros (distributed by FSF, for instance
13 % with the GNUemacs editor). This version of the manual has
14 % been tested with version 2.145 of texinfo.tex. The file
15 % texinfo.tex is available by anonymous ftp as
16 % pub/gnu/texinfo-3.6.tar.Z on prep.ai.mit.edu.
17 %
18 \input texdraw % bring in TeXdraw before texinfo changes "\" to "@"
19 \input txdtools
20
21 \input texinfo @c -*-texinfo-*-
22 @comment %**start of header
23 @setfilename texdraw.info
24 @settitle @TeX{}draw
25 @comment %**end of header
26
27 @copying
28 This manual (edition 2.3) documents @TeX{}draw, a system for
29 producing PostScript drawings from @TeX{}.
30
31 Copyright @copyright{} 1993--2019 Peter Kabal
32
33 This work is licensed under the Creative Commons Attribution (CC-BY)
34 License, any version. To view the licenses, visit
35 @w{@url{creativecommons.org/licenses/by}} or send a letter to
36 Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
37 @end copying
38
39 @dircategory TeX
40 @direntry
41 * TeXdraw: (texdraw). Drawing PostScript diagrams within TeX.
42 @end direntry
43
44
45 @titlepage
46 @title @TeX{}draw
47 @subtitle PostScript Drawings from @TeX{}
48 @subtitle Edition 2.3
49 @subtitle April 2019
50 @author Peter Kabal
51
52 @page
53 @vskip 0pt plus 1filll
54 @insertcopying
55
56 Peter Kabal @*
57 Department of Electrical @& Computer Engineering @*
58 McGill University @*
59
60 @code{peter dot kabal at mcgill dot ca} @*
61 @code{http://www-mmsp.ece.mcgill.ca/MMSP/Documents/Software/}
62 @end titlepage
63
64 @contents
65
66 @ifnottex
67 @node Top, Introduction, (dir), (dir)
68 @top TeXdraw
69
70 @TeX{}draw is a collection of macros that allow drawings to be created
71 from @emph{within} @TeX{}.
72
73 This is edition 2.3 of the @TeX{}draw documentation.
74 @end ifnottex
75
76 @menu
77 * Introduction::
78 * TeXdraw Commands::
79 * Drawing Segments and Scaling::
80 * Using TeXdraw with LaTeX::
81 * More Details::
82 * PostScript Commands::
83 * TeXdraw Toolbox::
84 * Examples::
85 * Command Listing::
86
87 Indices
88 * Concept Index::
89 * Command Index::
90
91 --- The Detailed Node Listing ---
92
93 Introduction
94
95 * Distribution::
96
97 TeXdraw Commands
98
99 * Accessing TeXdraw::
100 * Command syntax::
101 * TeXdraw coordinates::
102 * Coordinate specification::
103 * Line vectors::
104 * TeX text::
105 * Circles and arcs::
106 * Bezier curves::
107 * Fill commands::
108
109 Drawing Segments and Scaling
110
111 * Drawing segments::
112 * Drawing paths::
113 * Saving positions::
114 * Scaling coordinates::
115 * Drawing size::
116 * Initial current position::
117
118 Using TeXdraw with LaTeX
119
120 * PostScript printer drivers::
121
122 More Details
123
124 * Errors while using TeXdraw::
125 * Extending TeXdraw::
126 * How TeXdraw merges graphics and text::
127
128 Extending TeXdraw
129
130 * Scaling::
131 * Resolution::
132 * Text placement::
133 * Intermediate PostScript file::
134
135 PostScript Commands
136
137 TeXdraw Toolbox
138
139 * Coordinate parsing::
140 * Real arithmetic::
141 * Arrow curve::
142
143 Examples
144
145 * Block diagram::
146 * Filter response graph::
147 * Geometric construction::
148
149 Command Listing
150
151 Command Index
152
153 Concept Index
154 @end menu
155
156
157 @node Introduction, TeXdraw Commands, Top, Top
158 @chapter Introduction
159
160 @TeX{} is a powerful typesetting program which allows for complex text
161 layouts but by itself lacks a general graphics capability. However,
162 when coupled with an appropriate printer driver program, external
163 graphics files can be inserted into the printed document. In this mode,
164 @TeX{} is instructed to leave space for a drawing. The drawing is
165 inserted by the printer driver program. The @TeX{}draw macros described
166 here generate the external graphics file from within @TeX{} and generate
167 the instructions to the the print driver program to position the
168 graphics at the appropriate position on the page.
169
170 @TeX{}draw consists of a set of @TeX{} macros that create line drawings
171 and other figures. The drawing primitives include solid lines,
172 patterned lines, Bezier curves, circles and arrows. Other commands
173 allow for the filling of a region with a gray level. The drawing
174 commands generate PostScript code. This limits @TeX{}draw to systems
175 which use PostScript printers. @TeX{}draw also provides commands to
176 position @TeX{} text, including mathematics, on the drawing. The final
177 drawing, with text and graphics, can be positioned on the page like any
178 other @TeX{} box.
179
180 @cindex @code{dvips} printer driver
181 @cindex La@TeX{}
182 @cindex @code{graphics} package
183 The basic @TeX{}draw macros for @TeX{} use the @code{\special} syntax
184 recognized by the printer driver program @code{dvips}. However, when
185 invoked as a La@TeX{}2e package, the @TeX{}draw macros can be used with
186 any of the PostScript printer driver programs supported by the standard
187 @code{graphics} package for La@TeX{}2e.
188
189 The basic @TeX{}draw macros provide only simple drawing commands.
190 However, @TeX{}draw provides a drawing segment environment which allows
191 parameter changes and coordinate scaling changes to be kept local to the
192 drawing segment. This facility, together with @TeX{}'s macro
193 capabilities allows one to modularize drawing units and extend
194 @TeX{}draw by building more complex graphics entities from simpler
195 elements.
196
197 @menu
198 * Distribution::
199 @end menu
200
201 @node Distribution, , , Introduction
202 @section Distribution information
203 @cindex distribution
204
205 The entire @TeX{}draw package, both code and documentation, is
206 released under Creative Commons Attribution (CC-BY) license, any
207 version.
208
209
210 @node TeXdraw Commands, Drawing Segments and Scaling, Introduction, Top
211 @chapter Using the @TeX{}draw Commands
212
213 The main @TeX{}draw macros (commands) are defined in the file
214 @file{texdraw.tex}. These macros may be used directly in @TeX{}. The
215 file @file{texdraw.sty} provides an interface for use with La@TeX{}2e.
216 The following sections describe the basic commands for @TeX{}draw.
217
218 @menu
219 * Accessing TeXdraw::
220 * Command syntax::
221 * TeXdraw coordinates::
222 * Coordinate specification::
223 * Line vectors::
224 * TeX text::
225 * Circles and arcs::
226 * Bezier curves::
227 * Fill commands::
228 @end menu
229
230 @node Accessing TeXdraw, Command syntax, , TeXdraw Commands
231 @section Accessing @TeX{}draw
232 @cindex accessing @TeX{}draw
233 @cindex invoking @TeX{}draw
234
235 @cindex plain @TeX{}
236 @cindex La@TeX{}
237 The form of the user command to run the @TeX{} program depends on which
238 version of @TeX{} is being used, and which other macro packages are
239 preloaded as format files. Typically, installations have at least two
240 versions of @TeX{} --- plain @TeX{} which includes basic typesetting
241 macros (usually invoked as @file{tex}) and La@TeX{}2e which includes the
242 La@TeX{}2e typesetting macros (usually invoked as @file{latex}). An
243 older version of La@TeX{}, version 2.09, may also be available. The
244 @TeX{}draw macros can be used with plain @TeX{} and with either version
245 of La@TeX{}.
246
247 For use with plain @TeX{}, the user must read in the @TeX{}draw macros
248 from the file @file{texdraw.tex}.
249 @example
250 @group
251 \input texdraw % Read in the TeXdraw macros
252 ...
253 \btexdraw
254 ... % TeXdraw commands to generate a drawing
255 \etexdraw
256 @end group
257 @end example
258
259 For use with La@TeX{} version 2.09, the user reads in the @TeX{}draw
260 macros from the file @file{texdraw.tex} and optionally defines the
261 @code{\begin@{texdraw@}} / @code{\end@{texdraw@}} environment.
262 @example
263 @group
264 \documentstyle[11pt]@{article@} % Article style at 11pt size
265 ...
266 \input texdraw % Read in the TeXdraw macros
267 \newenvironment@{texdraw@}@{\leavevmode\btexdraw@}@{\etexdraw@}
268 ...
269 \begin@{texdraw@}
270 ... % TeXdraw commands to generate a drawing
271 \end@{texdraw@}
272 ...
273 \end@{document@}
274 @end group
275 @end example
276
277 @cindex @code{texdraw} package
278 @cindex @code{graphics} package
279 For use with La@TeX{}2e, the user must load the @code{texdraw} package
280 (file @file{texdraw.sty}). This package file defines the
281 @code{\begin@{texdraw@}} / @code{\end@{texdraw@}} environment, brings in
282 the standard @code{graphics} package and reads in the file
283 @file{texdraw.tex} containing the definitions of the @TeX{}draw macros.
284 @example
285 @group
286 \documentclass[11pt]@{article@} % Article class at 11pt size
287 \usepackage@{texdraw@} % TeXdraw commands
288
289 \begin@{document@}
290 ...
291 \begin@{texdraw@}
292 ... % TeXdraw commands to generate a drawing
293 \end@{texdraw@}
294 ...
295 \end@{document@}
296 @end group
297 @end example
298
299 As the @TeX{}draw commands are processed by @TeX{}, an intermediate
300 PostScript file is generated. The intermediate PostScript has a name of
301 the form @file{@var{name}.ps1}. The name part is derived from the name
302 of the main @TeX{} file being processed. If more than one drawing is
303 produced, the digit in the file name extension is
304 incremented.@footnote{After the ninth PostScript file, the name of the
305 intermediate PostScript file takes the form @file{@var{name}.p10}, with
306 the number increasing from 10 with each file.}
307
308 The @TeX{}draw commands to produce a drawing are inserted between
309 @code{\btexdraw} and @code{\etexdraw} commands, or for La@TeX{}, between
310 @code{\begin@{texdraw@}} and @code{\end@{texdraw@}} commands. This
311 results in a @TeX{} box of appropriate size containing the drawing
312 generated by the @TeX{}draw commands. The @TeX{}draw box can be
313 positioned in a document like any other @TeX{} box.
314
315 The @code{\centertexdraw@{...@}} macro centers the box generated by
316 @TeX{}draw. The vertical space taken up is equal to the vertical size
317 of the drawing. The @code{\centertexdraw} macro is normally used in
318 vertical mode (between paragraphs). A @code{\par} command (a blank line
319 will do also) before a @code{\centertexdraw} command will terminate
320 horizontal mode and return to vertical mode. For La@TeX{}, a structured
321 equivalent to the @code{\centertexdraw@{...@}} command is shown below.
322 @example
323 @group
324 \begin@{center@}
325 \begin@{texdraw@}
326 ...
327 \end@{texdraw@}
328 \end@{center@}
329 @end group
330 @end example
331
332 The @code{\everytexdraw} command can be used to define a set of
333 @TeX{}draw commands that will be executed at the beginning of every
334 @TeX{}draw drawing. It is invoked as @code{\everytexdraw@{ ...@}},
335 with the desired @TeX{}draw commands as arguments.
336
337 @table @code
338 @findex \btexdraw
339 @item \btexdraw
340 Start a @TeX{}draw drawing. The drawing is terminated with an
341 @code{\etexdraw} command.
342 @findex \etexdraw
343 @item \etexdraw
344 End a @TeX{}draw drawing started with a @code{\btexdraw} command. The
345 resulting @TeX{}draw drawing is placed in a box with height equal to the
346 height of the drawing and width equal to the width of the drawing. The
347 depth of the box is zero.
348 @findex \begin@{texdraw@}
349 @item \begin@{texdraw@}
350 Start a @TeX{}draw drawing. The drawing is terminated with an
351 @code{\end@{texdraw@}} command. This command is for use with La@TeX{}.
352 @findex \end@{texdraw@}
353 @item \end@{texdraw@}
354 End a @TeX{}draw drawing started with a @code{\begin@{texdraw@}}
355 command. The resulting @TeX{}draw drawing is placed in a box with
356 height equal to the height of the drawing and width equal to the width
357 of the drawing. The depth of the box is zero. This command is for use
358 with La@TeX{}.
359 @findex \centertexdraw
360 @item \centertexdraw@{ ... @}
361 Center a @TeX{}draw box horizontally. The argument contains @TeX{}draw
362 commands. The resulting box has the horizontal size @code{\hsize} and
363 height equal to the height of the drawing.
364 @findex \everytexdraw
365 @item \everytexdraw@{ ... @}
366 Specify @TeX{}draw commands to be executed at the beginning of every
367 @TeX{}draw drawing.
368 @end table
369
370 @node Command syntax, TeXdraw coordinates, Accessing TeXdraw, TeXdraw Commands
371 @section Command syntax
372 @cindex command syntax
373 @cindex syntax of commands
374
375 Generally @TeX{}draw commands that take a single argument need a
376 terminating blank or newline after the argument. Arguments that are
377 self-delimiting, such as coordinates within parentheses and text within
378 braces, do not need the terminating blank. However, even when not
379 needed by the defining syntax of the command, blanks following command
380 arguments are allowed and ignored within the @TeX{}draw environment.
381
382 On entering the @TeX{}draw environment, @TeX{} is in internal vertical
383 mode (vertical mode inside a @code{\vbox}). In this mode, spaces can be
384 placed freely between commands. However, any other extraneous input
385 that generates output that is not part of the @TeX{}draw environment is
386 disallowed.
387
388 Blank lines are interpreted as paragraph breaks, equivalent to a
389 @code{\par} command. The @TeX{}draw macro @code{\centertexdraw} is
390 defined with the @code{\long} attribute to allow @code{\par} commands
391 and blank lines to be interspersed between @TeX{}draw commands. The
392 @code{\btexdraw} and @code{\etexdraw} commands also allow @code{\par}
393 command and blank lines to be included.
394
395 @node TeXdraw coordinates, Coordinate specification, Command syntax, TeXdraw Commands
396 @section @TeX{}draw coordinates
397 @cindex coordinates
398
399 The @TeX{}draw coordinate system has increasing @var{x} to the right and
400 increasing @var{y} upward. The coordinates (without the unit) are
401 floating point numbers. Integer values can be written without a decimal
402 point. The size of the drawing is determined by the maximum excursions
403 of the coordinates specified in @TeX{}draw commands.
404 @tex
405 \bigskip
406 \centertexdraw{
407 \avec (0 0.8) \textref h:C v:B \htext (0 0.9){\sl y}
408 \move (0 0) \avec (0.8 0) \textref h:L v:C \htext(0.9 0){\sl x}
409 \move (0 1.0)}
410 @end tex
411
412 Consider the following example of @TeX{}draw commands to draw a simple
413 figure.
414 @example
415 @group
416 \centertexdraw@{
417 \drawdim cm \linewd 0.02
418 \move(2 2) \lvec(3 3) \lvec(2 4) \lvec(1 3) \lvec(2 2)
419 \textref h:C v:C \htext(2 3)@{$\sum \rho_n$@}
420 @}
421 @end group
422 @end example
423 @tex
424 \bigskip
425 \centertexdraw{
426 \drawdim{cm} \linewd 0.02
427 \move(2 2) \lvec(3 3) \lvec(2 4) \lvec(1 3) \lvec(2 2)
428 \textref h:C v:C \htext(2 3){$\sum \rho_n$}
429 }
430 @end tex
431 This drawing uses units of centimetres, with a line width of 0.02 cm.
432 The @var{x} coordinate ranges between 1 and 3 while the @var{y}
433 coordinate ranges between 2 and 4. When included into a document, the
434 size of the drawing is 2 cm by 2 cm. The drawing is placed in a @TeX{}
435 box, with the lower lefthand corner of the box corresponding to
436 @TeX{}draw coordinate @code{(1 2)} and the upper righthand corner at
437 @code{(3 4)}. The @code{\centertexdraw} command centers the drawing
438 horizontally. The @code{\textref} command controls the centering of the
439 text. The text in this drawing is centered (both horizontally and
440 vertically) at the coordinate @code{(2 3)}.
441
442 @node Coordinate specification, Line vectors, TeXdraw coordinates, TeXdraw Commands
443 @section Coordinate specification
444 @cindex coordinate specification
445 @cindex position specification
446
447 Coordinates are specified within parentheses, with blanks (but no comma)
448 between the values. Leading blanks and trailing blanks are permitted
449 within the parentheses. The coordinates refer to units, which are
450 specified by the @code{\drawdim} command. The default is inches, but
451 any valid @TeX{} dimension unit can be specified. Symbolic
452 specification of saved coordinate values will be discused later
453 (@pxref{Saving positions}).
454
455 @table @code
456 @findex \drawdim
457 @item \drawdim @var{dim}
458 Set the units to @var{dim}. The argument @var{dim} can be any valid
459 @TeX{} dimension unit. The units are used to interpret coordinate
460 values. Examples of valid units: @code{cm}, @code{mm}, @code{in},
461 @code{pt}, and @code{bp}.
462 @end table
463
464 Examples of coordinate and scaling specifications:
465 @table @code
466 @item \drawdim @{cm@} \move(2 2)
467 Set the units to centimetres, move to a position 2 cm to the right and 2
468 cm up from the origin of the drawing coordinate system.
469 @item \drawdim bp
470 Set the units to big points.
471 @item \lvec ( 2.2 +5.5) \lvec(2.3 -2) \lvec(2.2 5.4 )
472 Examples of acceptable coordinate specifications.
473 @end table
474
475 @node Line vectors, TeX text, Coordinate specification, TeXdraw Commands
476 @section Line vectors
477 @cindex lines
478 @cindex vectors
479 @cindex arrows
480 @cindex moves
481 @cindex current position
482
483 @TeX{}draw implements moves, line vectors and arrow vectors. There are
484 both absolute and relative motion versions of these vector commands.
485 @TeX{}draw maintains a current position. Lines are drawn from the
486 current position to a new coordinate, with the new coordinate becoming
487 the new current position. An explicit move can be used to establish a
488 new current position. The position @code{(0 0)} is used if there is no
489 move to an initial current position.
490
491 The @code{\move} and @code{\rmove} commands establish a new current
492 position without drawing a line. The @code{\lvec} and @code{\rlvec}
493 commands draw a line from the current position to a new position, which
494 then becomes the new current position. The @code{\avec} and
495 @code{\ravec} commands draw a line with an arrowhead from the current
496 position to a new coordinate, which then becomes the new current
497 position. The tip of the arrow is at the new current position. The
498 direction of the arrow follows the direction of the line. Since this
499 direction is undefined for zero length vectors, these are not allowed
500 for @code{\avec} or @code{\ravec}. Zero length arrow vectors will
501 generate a PostScript print error: @code{undefinedresult}. For any
502 non-zero length vector, the full size arrowhead is drawn, even if that
503 arrowhead is longer than the line length.
504
505 The absolute motion versions of these commands specify the coordinate of
506 the final position.
507
508 @table @code
509 @findex \move
510 @item \move (@var{x} @var{y})
511 Move to coordinate @code{(@var{x} @var{y})}. The new current position
512 is @code{(@var{x} @var{y})}.
513 @findex \lvec
514 @item \lvec (@var{x} @var{y})
515 Draw a line from the current position to coordinate @code{(@var{x}
516 @var{y})}. The new current position is @code{(@var{x} @var{y})}.
517 @findex \avec
518 @item \avec (@var{x} @var{y})
519 Draw a line with an arrowhead from the current position to
520 @code{(@var{x} @var{y})}. The new current position is @code{(@var{x}
521 @var{y})}. The arrowhead is aligned with the line, with the tip at
522 @code{(@var{x} @var{y})}.
523 @end table
524
525 @cindex relative positioning
526 The relative motion versions of these commands interpret the coordinates
527 as displacements relative to the current position. Given the
528 displacements @code{(@var{dx} @var{dy})} as a parameter, each of the
529 relative motion commands moves @var{dx} units in the @var{x} direction
530 and @var{dy} units in the @var{y} direction.
531
532 @table @code
533 @findex \rmove
534 @item \rmove (@var{dx} @var{dy})
535 Move from the current position, @var{dx} units in the @var{x} direction
536 and @var{dy} units in the @var{y} direction. The final position becomes
537 the new current position.
538 @findex \rlvec
539 @item \rlvec (@var{dx} @var{dy})
540 Draw a line from the current position, @var{dx} units in the @var{x}
541 direction and @var{dy} units in the @var{y} direction. The final
542 position becomes the new current position.
543 @findex \ravec
544 @item \ravec (@var{dx} @var{dy})
545 Draw a line with an arrowhead from the current position, @var{dx} units
546 in the @var{x} direction and @var{y} units in the @var{y} direction.
547 The final position becomes the new current position. The arrowhead is
548 aligned with the line, with the tip at the new current position.
549 @end table
550
551 Lines can be customized with commands to change the line width, line
552 pattern and line gray level rendition. In addition, commands for
553 changing the type and size of the arrowhead are available.
554
555 @cindex line width
556 @cindex width of lines
557 @cindex dashed lines
558 @cindex dotted lines
559 @cindex gray levels for lines
560 @cindex arrowhead parameters
561 @table @code
562 @findex \linewd
563 @item \linewd @var{width}
564 Set the line width to @var{width} units. Initially @var{width} is 0.01
565 inches (corresponding to 3 pixels at 300 pixels to the inch).
566 @item \lpatt (@var{pattern})
567 Set lines to have the pattern @code{(@var{pattern})}. A pattern is a
568 sequence of on/off lengths separated by blanks and enclosed in parentheses.
569 The lengths alternately specify the length of a dash and the length of a
570 gap between dashes. Each length is interpreted using the current
571 scaling and drawing units. The pattern is used cyclically. The empty
572 pattern signifies a solid line. The initial line pattern is a solid
573 line, corresponding to the empty pattern @code{\lpatt ()}.
574 @findex \setgray
575 @item \setgray @var{level}
576 Set the gray level of lines. Gray levels are real values from 0 (black)
577 through intermediate values (gray) to 1 (white). The initial gray level
578 is 0 corresponding to black.
579 @findex \arrowheadtype
580 @item \arrowheadtype t:@var{type}
581 Set the arrowhead type to @var{type}, where @var{type} is one of
582 @code{F}, @code{T}, @code{W}, @code{V}, or @code{H}. There are two
583 kinds of arrowheads. The first kind is a triangle. There are 3
584 variants: type @code{T} is an empty triangle, type @code{F} is a filled
585 triangle (using the current gray level for lines), type @code{W} is a
586 triangle filled with white. The second kind of arrowhead is an open
587 ended Vee. There are 2 variants: type @code{V} has the stem continue to
588 the tip, type @code{H} has the stem stop at the base of the arrowhead.
589 The initial arrowhead type is @code{T}.
590 @findex \arrowheadsize
591 @item \arrowheadsize l:@var{length} w:@var{width}
592 Set the arrowhead size to be @var{length} units long and @var{width}
593 units wide. The width is measured across the ``base'' of the arrowhead.
594 The initial arrowhead size has a @var{length} of 0.16 inches and a
595 @var{width} of 0.08 inches.
596 @end table
597
598 Note that the lines which outline the arrowhead will be drawn with the
599 same line pattern used for the stem. Normally, arrow vectors are drawn
600 with the line pattern set for a solid line. Note that the fill level
601 used for the @code{F} variant of the arrowhead uses the same gray level
602 as used for lines. The difference between the @code{T} variant and the
603 @code{W} variant only shows up if the arrowhead is placed over non-white
604 areas of the drawing. The @code{W} variant obliterates the area under
605 the arrowhead.
606
607 Examples of line parameter and arrowhead settings are shown in the
608 following code.
609 @example
610 @group
611 \centertexdraw@{
612 \drawdim in
613 \linewd 0.03 \setgray 0.6 \arrowheadtype t:F \avec(0 0.5)
614 \linewd 0.01 \setgray 0 \arrowheadtype t:V \avec(0.5 0.5)
615 \linewd 0.015 \lpatt(0.067 0.1) \lvec (1 0)
616 \linewd 0.02 \lpatt() \arrowheadtype t:T \avec(1.5 0.5)
617 \arrowheadtype t:H \avec(2.0 0.5)
618 \setgray 0.4 \arrowheadtype t:W \avec(3.0 0)
619 @}
620 @end group
621 @end example
622 @tex
623 \bigskip
624 \centertexdraw{
625 \drawdim in
626 \linewd 0.03 \setgray 0.6 \arrowheadtype t:F \avec(0.5 0.5)
627 \linewd 0.01 \setgray 0 \arrowheadtype t:V \avec(1.0 0.5)
628 \linewd 0.015 \lpatt(0.067 0.1) \lvec (1.5 0)
629 \linewd 0.02 \lpatt() \arrowheadtype t:T \avec(2.0 0.5)
630 \arrowheadtype t:H \avec(2.5 0.5)
631 \setgray 0.4 \arrowheadtype t:W \avec(3.0 0)
632 \textref h:R v:T \htext (0.35 0.50){\tt t:F}
633 \textref h:R v:T \htext (1.0 0.43){\tt t:V}
634 \textref h:R v:T \htext (1.82 0.50){\tt t:T}
635 \textref h:R v:T \htext (2.5 0.43){\tt t:H}
636 \textref h:R v:B \htext (2.8 0){\tt t:W}
637 }
638 @end tex
639
640 @node TeX text, Circles and arcs, Line vectors, TeXdraw Commands
641 @section @TeX{} text
642 @cindex text commands
643
644 Text may be superimposed on the drawing. The text argument of the
645 @code{\htext} command is in horizontal mode. This text can be ordinary
646 text, math mode expressions, or even more complicated boxes consisting
647 of tables and the like. The resulting @TeX{} text is placed in a box.
648 The reference point of the box can be chosen to be one of nine
649 locations: horizontally left, center or right; vertically top, center or
650 bottom. The @code{\htext} command takes one of two forms.
651
652 @table @code
653 @findex \htext
654 @item \htext (@var{x} @var{y})@{@var{text}@}
655 @itemx \htext @{@var{text}@}
656 The first form of this command places the @TeX{} text @var{text}
657 horizontally with the text reference point at the coordinate
658 @code{(@var{x} @var{y})}. The new current position is @code{(@var{x}
659 @var{y})}. The second form of this command places the @TeX{} text
660 @var{text} horizontally with the text reference point at the current
661 position. The text reference point is set with the @code{\textref}
662 command.
663 @end table
664
665 @cindex vertical text
666 @cindex rotated text
667 @cindex text rotation
668 Text can be placed vertically using the @code{\vtext} command. The text
669 argument is in horizontal mode. The @TeX{} text is placed in a box and
670 then rotated counterclockwise. The reference point is the point in the
671 box, @emph{before} rotation of the text. Not all PostScript printer
672 drivers support vertical text.
673
674 @table @code
675 @findex \vtext
676 @item \vtext (x y)@{@var{text}@}
677 @itemx \vtext @{@var{text}@}
678 The first form of this command places the @TeX{} text @var{text}
679 vertically with the text reference point at the coordinate
680 @code{(@var{x} @var{y})}. The new current position is @code{(@var{x}
681 @var{y})}. The second form of this command places the @TeX{} text
682 @var{text} vertically with the text reference point at the current
683 position. In both cases, the @TeX{} text is placed in a box and the box
684 is rotated counterclockwise by 90 degrees about the text reference
685 point. The text reference point is set with the @code{\textref}
686 command.
687 @end table
688
689 @cindex rotated text
690 @cindex text rotation
691 Text can be placed at an arbitrary angle using the @code{\rtext}
692 command. The text argument is in horizontal mode. The @TeX{} text is
693 placed in a box and then rotated counterclockwise. The reference point
694 is the point in the box, @emph{before} rotation of the text. Not all
695 PostScript printer drivers support rotated text.
696
697 @table @code
698 @findex \rtext
699 @item \rtext td:@var{angle} (x y)@{@var{text}@}
700 @itemx \rtext td:@var{angle} @{@var{text}@}
701 The first form of this command places the @TeX{} text @var{text} at an
702 angle with the text reference point at the coordinate @code{(@var{x}
703 @var{y})}. The new current position is @code{(@var{x} @var{y})}. The
704 second form of this command places the @TeX{} text @var{text} at an
705 angle with the text reference point at the current position. In both
706 cases, the @TeX{} text is placed in a box and the box is rotated
707 counterclockwise by @var{angle} degrees about the text reference point.
708 The text reference point is set with the @code{\textref} command.
709 @end table
710
711 The reference point for subsequent @TeX{} text in a @code{\htext},
712 @code{\vtext} or @code{\rtext} command is set with the @code{\textref}
713 command.
714
715 @table @code
716 @findex \textref
717 @item \textref h:@var{h-ref} v:@var{v-ref}
718 Set the text reference point for subsequent text commands. The
719 horizontal reference point @var{h-ref} is one of @code{L}, @code{C} or
720 @code{R} (left, center or right). The vertical reference point
721 @var{v-ref} is one of @code{T}, @code{C} or @code{B} (top, center or
722 bottom). For rotated text, the reference point is determined before
723 rotation. The initial text reference point corresponds to
724 @code{\textref h:L v:B}.
725 @end table
726 @noindent
727
728 @tex
729 \centertexdraw{
730 \def\bdot {\bsegment
731 \fcir f:0 r:0.02
732 \esegment}
733 \def\Ttext #1{\bsegment
734 \textref h:C v:B \htext (0 +0.06){#1}
735 \esegment}
736 \def\Btext #1{\bsegment
737 \textref h:C v:T \htext (0 -0.06){#1}
738 \esegment}
739 \def\Ltext #1{\bsegment
740 \textref h:R v:C \htext (-0.08 0){#1}
741 \esegment}
742 \def\Rtext #1{\bsegment
743 \textref h:L v:C \htext (+0.08 0){#1}
744 \esegment}
745 \move (-1.5 0)
746 \bsegment
747 \move (+1.55 +0.45) \move (-1.55 -0.45) \move (0 0)
748 \Ttext{Horizontal Text}
749 \bdot \Btext{\tt h:C v:C}
750 \move (-0.9 0) \bdot \Ltext{\tt h:L v:C}
751 \move (+0.9 0) \bdot \Rtext{\tt h:R v:C}
752 \move (0 +0.3) \bdot \Ttext{\tt h:C v:T}
753 \move (0 -0.3) \bdot \Btext{\tt h:C v:B}
754 \move (-0.9 -0.3) \bdot \Ltext{\tt h:L v:B}
755 \lvec (-0.9 +0.3) \bdot \Ltext{\tt h:L v:T}
756 \lvec (+0.9 +0.3) \bdot \Rtext{\tt h:R v:T}
757 \lvec (+0.9 -0.3) \bdot \Rtext{\tt h:R v:B}
758 \lvec (-0.9 -0.3)
759 \esegment
760 \def\atext {\rtext td:45 }
761 \def\ATtext #1{\bsegment
762 \setsegscale 0.707
763 \textref h:C v:B \atext (-0.06 +0.06){#1}
764 \esegment}
765 \def\ABtext #1{\bsegment
766 \setsegscale 0.707
767 \textref h:C v:T \atext (+0.060 -0.06){#1}
768 \esegment}
769 \def\ALtext #1{\bsegment
770 \setsegscale 0.707
771 \textref h:R v:C \atext (-0.08 -0.08){#1}
772 \esegment}
773 \def\ARtext #1{\bsegment
774 \setsegscale 0.707
775 \textref h:L v:C \atext (+0.08 +0.08){#1}
776 \esegment}
777 \move (+1.5 0)
778 \bsegment
779 \move (+1.33 +1.33) \move (-1.33 -1.33) \move (0 0)
780 \setsegscale 0.707
781 \ATtext{Rotated Text}
782 \bdot \ABtext{\tt h:C v:C}
783 \move (-0.9 -0.9) \bdot \ALtext{\tt h:L v:C}
784 \move (+0.9 +0.9) \bdot \ARtext{\tt h:R v:C}
785 \move (-0.3 +0.3) \bdot \ATtext{\tt h:C v:T}
786 \move (+0.3 -0.3) \bdot \ABtext{\tt h:C v:B}
787 \move (-0.6 -1.2) \bdot \ALtext{\tt h:L v:B}
788 \lvec (-1.2 -0.6) \bdot \ALtext{\tt h:L v:T}
789 \lvec (+0.6 +1.2) \bdot \ARtext{\tt h:R v:T}
790 \lvec (+1.2 +0.6) \bdot \ARtext{\tt h:R v:B}
791 \lvec (-0.6 -1.2)
792 \esegment
793 }
794 @end tex
795
796 The font used to render the text is determined as for any other @TeX{}
797 text. Normally the font used outside of @TeX{}draw is in effect. If
798 desired, other fonts can be specified as part of the text. Any font
799 changes within a @TeX{}draw text command remain local to that command.
800
801 Only the coordinate of the text reference point in a @code{\htext},
802 @code{\vtext} or @code{\rtext} command is used in calculating the size
803 of the drawing. This means that text itself can spill outside of the
804 drawing area determined by @TeX{}draw. The area of the drawing can be
805 increased to include the text by issuing additional @code{\move}
806 commands.
807
808 @example
809 @group
810 \centertexdraw@{
811 \avec(-0.75 -0.25) \textref h:R v:C \htext@{H-text@}
812 \move(0 0) \avec(-0.75 +0.25) \textref h:R v:B \htext@{H-text@}
813 \move(0 0) \avec(0 +0.5) \textref h:L v:T \vtext@{V-text@}
814 \move(0 0) \avec(+0.75 +0.25) \textref h:L v:B \htext@{H-text@}
815 \move(0 0) \avec(+0.75 -0.25) \textref h:L v:C \htext@{H-text@}
816 @}
817 @end group
818 @end example
819 @iftex
820 Superimposed on this example is a shaded region showing the limits of
821 the @TeX{}draw box as determined by the coordinates specified.
822 @tex
823 \bigskip
824 \centertexdraw{
825 \move(-0.75 -0.25) \lvec (-0.75 +0.5) \lvec (+0.75 +0.5)
826 \lvec(+0.75 -0.25) \ifill f:0.9 % fill the region
827 \move(0 0)
828 \avec(-0.75 -0.25) \textref h:R v:C \htext{H-text}
829 \move(0 0) \avec(-0.75 +0.25) \textref h:R v:B \htext{H-text}
830 \move(0 0) \avec(0 +0.5) \textref h:L v:T \vtext{V-text}
831 \move(0 0) \avec(+0.75 +0.25) \textref h:L v:B \htext{H-text}
832 \move(0 0) \avec(+0.75 -0.25) \textref h:L v:C \htext{H-text}
833 \move (-1.15 -0.3) \move (+1.15 +0.92) % increase the size of the drawing
834 }
835 @end tex
836 @end iftex
837
838 @node Circles and arcs, Bezier curves, TeX text, TeXdraw Commands
839 @section Circles, ellipses and arcs
840 @cindex circles
841 @cindex filled circles
842 @cindex ellipses
843 @cindex arcs
844
845 @TeX{}draw supplies commands to generate circles, ellipses and arcs.
846 There are two forms of the circle command. The @code{\lcir} command
847 draws a circle of given radius. The @code{\fcir} command draws a filled
848 circle. In the latter case, the circle is filled by a specified gray
849 level. For the filled circle, the line defining the circumference of
850 the circle is not drawn. Note that the gray level area filled in by the
851 @code{\fcir} command is opaque, even if the fill is chosen to be white.
852 For either form of the circle command, the drawing size is increased if
853 necessary to contain the circle.
854
855 The @code{\lellip} command generates an ellipse specified by the radius
856 of the ellipse in the @var{x} direction and the radius of the ellipse in
857 the @var{y} direction. The ellipse is symmetrical about horizontal and
858 vertical lines drawn through the current point. The @code{\fellip}
859 command draws a filled ellipse. In the latter case, the ellipse is
860 filled by a specified gray level. For the filled ellipse, the line
861 defining the boundary of the ellipse is not drawn. For either form of
862 the ellipse command, the drawing size is increased if necessary to
863 contain the ellipse.
864
865
866 The @code{\larc} command generates a counterclockwise arc specified by a
867 start angle in degrees and an end angle in degrees. The center of the
868 arc is the current position. Only the arc is drawn, not the line
869 joining the center to the beginning of the arc. Note that the
870 @code{\larc} command does not affect the size of the drawing.
871
872 @table @code
873 @findex \lcir
874 @item \lcir r:@var{radius}
875 Draw a circle with center at the current position. The radius is
876 specified by @var{radius}. This command draws a line along the
877 circumference of the circle. The drawing size is increased if necessary
878 to contain the circle.
879 @findex \fcir
880 @item \fcir f:@var{level} r:@var{radius}
881 Draw a filled circle with center at the current position. The radius is
882 specified by @var{radius}. The circle is painted with the gray level
883 specified by @var{level}. A gray level of 1 corresponds to white, with
884 decreasing values getting darker. The level 0 is full black. This
885 command does not draw a line along the circumference. The drawing size
886 is increased if necessary to contain the circle.
887 @findex \lellip
888 @item \lellip rx:@var{x-radius} ry:@var{y-radius}
889 Draw an ellipse with center at the current position. The radius in the
890 @var{x} direction is specified by @var{x-radius}. The radius in the
891 @var{y} direction is specified by @var{y-radius}. The drawing size is
892 increased if necessary to contain the ellipse.
893 @findex \fellip
894 @item \fellip f:@var{level} rx:@var{x-radius} ry:@var{y-radius}
895 Draw a filled ellipse with center at the current position. The radius
896 in the @var{x} direction is specified by @var{x-radius}. The radius in
897 the @var{y} direction is specified by @var{y-radius}. The ellipse is
898 painted with the gray level specified by @var{level}. A gray level of 1
899 corresponds to white, with decreasing values getting darker. The level
900 0 is full black. This command does not draw a line along the boundary
901 of the ellipse. The drawing size is increased if necessary to contain
902 the ellipse.
903 @findex \arc
904 @item \larc r:@var{radius} sd:@var{start-angle} ed:@var{end-angle}
905 Draw a counterclockwise arc. The center of the arc is at the current
906 position. The radius is specified by @var{radius}. The start and end
907 angles (in degrees) are specified by @var{start-angle} and
908 @var{end-angle}. This command does not affect the limits (size) of the
909 drawing.
910 @end table
911
912 As an example, the following commands draw a filled circle, and
913 superimpose an arc.
914 @example
915 @group
916 \centertexdraw@{
917 \linewd 0.02
918 \fcir f:0.7 r:1
919 \larc r:1 sd:45 ed:135
920 \lvec (+0.707 +0.707) \move (0 0) \lvec (-0.707 +0.707)
921 @}
922 @end group
923 @end example
924 @tex
925 \bigskip
926 \centertexdraw{
927 \linewd 0.02
928 \fcir f:0.7 r:1
929 \larc r:1 sd:45 ed:135
930 \lvec ( 0.707 0.707) \move (0 0) \lvec (-0.707 +0.707)
931 }
932 @end tex
933
934 Note that for the arc command, the resulting figure can spill outside of
935 the @TeX{}draw box as determined by the maximum excursions of the
936 coordinates. Extra moves can be used to compensate for the size of the
937 arc.
938
939 @node Bezier curves, Fill commands, Circles and arcs, TeXdraw Commands
940 @section Bezier curves
941 @cindex Bezier curves
942 @cindex curves
943
944 Bezier curves in @TeX{}draw use 4 reference coordinates, two as the end
945 points and two others to control the shape of the curve. Let the 4
946 points be @code{(@var{x0} @var{y0})}, @code{(@var{x1} @var{y1})},
947 @code{(@var{x2} @var{y2})} and @code{(@var{x3} @var{y3})}. The curve
948 starts out tangent to the line joining the first two points and ends up
949 tangent to the line joining the second two points. The control points
950 ``pull'' at the curve to control the curvature. The amount of pull
951 increases with the distance of the control point from the endpoint.
952
953 @tex
954 As the parameter $\mu$ varies from 0 to 1, the coordinates of the Bezier
955 curve are given by a pair of parametric cubic equations,
956 $$
957 \def\x #1{\hbox{\sl x#1}}
958 \def\y #1{\hbox{\sl y#1}}
959 \eqalign{
960 \x{}(\mu) &= (1-\mu)^3 \x0 + 3\mu(1-\mu)^2 \x1 + 3\mu^2(1-\mu) \x2 + \mu^3 \x3 \cr
961 \y{}(\mu) &= (1-\mu)^3 \y0 + 3\mu(1-\mu)^2 \y1 + 3\mu^2(1-\mu) \y2 + \mu^3 \y3\ . \cr}
962 $$
963 @end tex
964 @ifinfo
965 As the parameter u varies from 0 to 1, the coordinates of the Bezier
966 curve are given by a pair of parametric cubic equations,
967
968 @noindent
969 x(u) = (1-u)^3 x0 + 3u (1-u)^2 x1 + 3u^2 (1-u) x2 + u^3 x3
970 @noindent
971 y(u) = (1-u)^3 y0 + 3u (1-u)^2 y1 + 3u^2 (1-u) y2 + u^3 y3 .
972
973 @end ifinfo
974
975
976 @table @code
977 @findex \clvec
978 @item \clvec (@var{x1} @var{y1})(@var{x2} @var{y2})(@var{x3} @var{y3})
979 Draw a Bezier curve from the current position to the coordinate
980 @code{(@var{x3} @var{y3})} which becomes the new current position. The
981 coordinates @code{(@var{x1} @var{y1})} and @code{(@var{x2} @var{y2})}
982 serve as control points for the curve. Only the last coordinate given
983 is used to update the size of the drawing.
984 @end table
985 @noindent
986 Note that only 3 coordinate pairs are specified. The other point is the
987 current position before the @code{\clvec} command is executed. Only the
988 last coordinate specified in the @code{\clvec} command is used to
989 determine the extent of the drawing. While the Bezier curve passes
990 through the old current position and the new current position, in
991 general the curve will not reach the intermediate control points. The
992 curve is always entirely enclosed by the convex quadrilateral defined by
993 the two end points and the two control points. Note that the curve may
994 pass outside the limits of the drawing as determined by the end point of
995 the curve.
996
997 A simple Bezier curve is produced by the following example.
998 @example
999 @group
1000 \btexdraw
1001 \move (0 0)
1002 \clvec (0 1)(1 0)(1 1)
1003 \etexdraw
1004 @end group
1005 @end example
1006
1007 @iftex
1008 This example is the rightmost of the following Bezier curves. The
1009 drawings also show the end points and the control points for each curve.
1010 @tex
1011 \bigskip
1012 \centertexdraw{
1013 \def\Ltext #1{\bsegment
1014 \textref h:R v:C \htext (-0.08 0){#1}
1015 \esegment}
1016 \def\Rtext #1{\bsegment
1017 \textref h:L v:C \htext (+0.08 0){#1}
1018 \esegment}
1019 \def\bdot {\fcir f:0 r:0.02 }
1020 \def\Ldot #1{\bdot \Ltext{#1}}
1021 \def\Rdot #1{\bdot \Rtext{#1}}
1022 \move (-2 0)
1023 \bsegment
1024 \lpatt (0.033)
1025 \move (0 0) \Ldot{0} \lvec (0 1) \Ldot{1}
1026 \lvec (1 1) \Rdot{2} \lvec (1 0) \Rdot{3}
1027 \lpatt ()
1028 \move (0 0) \clvec (0 1)(1 1)(1 0)
1029 \esegment
1030 \move (0 0)
1031 \bsegment
1032 \lpatt (0.033)
1033 \move (0 0) \Ldot{0} \lvec (0.5 0.8) \Ldot{1}
1034 \lvec (1.5 0.8) \Rdot{2} \lvec (1 0) \Rdot{3}
1035 \lpatt ()
1036 \move (0 0) \clvec (0.5 1)(1.5 1)(1 0)
1037 \esegment
1038 \move ( 2 0)
1039 \bsegment
1040 \lpatt (0.033)
1041 \move (0 0) \Ldot{0} \lvec (0 1) \Ldot{1}
1042 \lvec (1 0) \Rdot{2} \lvec (1 1) \Rdot{3}
1043 \lpatt ()
1044 \move (0 0) \clvec (0 1)(1 0)(1 1)
1045 \esegment
1046 }
1047 @end tex
1048 @end iftex
1049
1050 @node Fill commands, , Bezier curves, TeXdraw Commands
1051 @section Fill commands
1052 @cindex filling regions
1053 @cindex painting regions
1054 @cindex paths
1055
1056 PostScript deals with paths consisting of line segments. The paths can
1057 be closed and the interior of the closed region filled. From
1058 @TeX{}draw, paths start with a @code{\move} or @code{\rmove} command and
1059 continue with @code{\lvec}, @code{\rlvec} or @code{\clvec} commands.
1060 The @TeX{}draw fill commands close the path and fill the interior of the
1061 closed region. Closing the path means that effectively another
1062 @code{\lvec} line is drawn from the last point specified to the initial
1063 point. @TeX{}draw provides two forms of the fill command. The
1064 @code{\ifill} fills the interior of the region with the given gray
1065 level. The lines defining the path are not drawn. The @code{\lfill}
1066 command fills the region defined by the closed path and draws a line
1067 along the enclosing path. Note for both forms of the fill command, the
1068 gray level used for filling is opaque, even if the gray level is chosen
1069 to be white.
1070
1071 @table @code
1072 @findex \lfill
1073 @item \lfill f:@var{level}
1074 Close the current path, draw the line around the path using the current
1075 grey level for lines and paint the interior of the region with specified
1076 gray level @var{level}. Gray levels are real values from 0 (black)
1077 through intermediate values (grays) to 1 (white).
1078 @findex \ifill
1079 @item \ifill f:@var{level}
1080 Close the current path and paint the interior of the region with gray
1081 level @var{level}. The line around the path is not drawn. Gray levels
1082 are real values from 0 (black) through intermediate values (grays) to 1
1083 (white).
1084 @end table
1085
1086 The following example draws a ``flag'' with the interior filled in. The
1087 path around the boundary is given in a clockwise order to define a
1088 closed path. We could take advantage of the fact that the fill command
1089 will close an open path to eliminate one of the @code{\lvec} commands.
1090 @example
1091 @group
1092 \centertexdraw@{
1093 \move (0.5 0)
1094 \lvec (0 0.5) \clvec (0.5 0.85)(1 0.65)(1.5 1)
1095 \lvec (2 0.5) \clvec (1.5 0.15)(1 0.35)(0.5 0)
1096 \lfill f:0.8
1097 @}
1098 @end group
1099 @end example
1100 @tex
1101 \bigskip
1102 \centertexdraw{
1103 \move (0.5 0)
1104 \lvec (0 0.5) \clvec (0.5 0.85)(1 0.65)(1.5 1)
1105 \lvec (2 0.5) \clvec (1.5 0.15)(1 0.35)(0.5 0)
1106 \lfill f:0.8
1107 }
1108 @end tex
1109
1110 In @TeX{}draw, the @code{\move} command always terminates any previous
1111 paths and starts a new path. Commands that change line parameters
1112 (e.g@. @code{\setgray} or @code{\lpatt}) also terminate paths and start
1113 new paths. The circle, ellipse and arc commands do not affect the
1114 definition of the current path. The @code{\avec} command is not
1115 appropriate for defining a path to be filled. It ends a subpath at its
1116 tail and begins a new subpath at its tip. Filling a region defined by a
1117 path with subpaths is more complicated in that each subpath is closed
1118 before filling.
1119
1120
1121 @node Drawing Segments and Scaling, Using TeXdraw with LaTeX, TeXdraw Commands, Top
1122 @chapter Drawing Segments and Scaling
1123
1124 @TeX{}draw provides individually scaled segments which can be used to
1125 create relocatable drawing modules.
1126
1127 @menu
1128 * Drawing segments::
1129 * Drawing paths::
1130 * Saving positions::
1131 * Scaling coordinates::
1132 * Drawing size::
1133 * Initial current position::
1134 @end menu
1135
1136 @node Drawing segments, Drawing paths, , Drawing Segments and Scaling
1137 @section Drawing segments
1138 @cindex segments
1139 @cindex drawing segments
1140
1141 A @TeX{}draw drawing segment allows for local modifications of
1142 parameters and relative positioning. A @TeX{}draw segment is delimited
1143 by a @code{\bsegment} command and an @code{\esegment} command. Inside
1144 the segment, the initial current position is @code{(0 0)}. Any changes
1145 to parameters such as the gray level and the line width, remain local to
1146 the segment. Segments are implemented in @TeX{} using a
1147 @code{\begingroup} and @code{\endgroup}. Segments can be nested.
1148
1149 @table @code
1150 @findex \bsegment
1151 @item \bsegment
1152 Start a drawing segment. The coordinate system is shifted such that the
1153 current position corresponds to the coordinate @code{(0 0)}. Changes to
1154 scaling, position and line parameters stay local to the drawing segment.
1155 @findex \esegment
1156 @item \esegment
1157 End a drawing segment. The current position in effect before the
1158 corresponding @code{\bsegment} command is restored. The scaling and
1159 line parameter values revert to those in effect before the corresponding
1160 @code{\bsegment} command was invoked.
1161 @end table
1162
1163 @node Drawing paths, Saving positions, Drawing segments, Drawing Segments and Scaling
1164 @section Drawing paths
1165 @cindex fill operations, interaction with drawing segments
1166 @cindex paths
1167 @cindex stroking lines
1168 Certain subtle interactions occur between drawing segments and fill
1169 operations. In PostScript, lines are drawn by first defining a path,
1170 then later stroking the path to draw the line. In @TeX{}draw, this
1171 stroking occurs when the line is terminated, say by a @code{\move}
1172 command. PostScript paths are interrupted by, but continue after a
1173 drawing segment. This means that a path started before a segment may
1174 not be stroked (drawn) until after the segment ends. Consider the
1175 following example.
1176 @example
1177 @group
1178 \move (0 0)
1179 \lvec (1 1)
1180 \bsegment
1181 \move (-0.25 -0.25)
1182 \fcir f:0.8 r:0.5
1183 \esegment
1184 \move (0 0)
1185 @end group
1186 @end example
1187 A PostScript path is started at @code{(0 0)} and continues with a line
1188 to @code{(1 1)}. This path is interrupted by the segment. The filled
1189 circle is drawn next. After the segment, the path continues and is not
1190 stroked until the @code{\move (0 0)} command after the end of the
1191 segment. This means that the line appears on top of the filled region.
1192
1193 If the fill operation is to cover the line, the path must be stroked
1194 before the fill operation. From @TeX{}draw, the move commands
1195 @code{\move} and @code{\rmove}, and the end @TeX{}draw command
1196 @code{\etexdraw} terminate a path and cause it to be stroked. Within a
1197 segment, the end segment command @code{\esegment} also terminates and
1198 strokes a path. In the example above, the line can be stroked by
1199 inserting a move command (such as a @code{\rmove (0 0)} which does not
1200 affect the position), before the start of the segment.
1201
1202 @node Saving positions, Scaling coordinates, Drawing paths, Drawing Segments and Scaling
1203 @section Saving positions
1204 @cindex saving positions
1205 @cindex positions, saving
1206 @cindex coordinate, symbolic
1207 @cindex symbolic coordinate
1208
1209 The @code{\savecurrpos} command saves the current position. The saved
1210 position is an absolute position, not one relative to a segment. The
1211 position saving mechanism is global; the position can be saved within a
1212 nested segment and then used outside of the segment. The @var{x} and
1213 @var{y} coordinates of the position are saved separately as named
1214 coordinates. The names are of the form @code{*@var{name}}, with the
1215 leading @code{*} being obligatory. A companion command,
1216 @code{\savepos}, saves a given coordinate (relative to the current
1217 segment) as an absolute symbolic position.
1218
1219 @table @code
1220 @findex \savecurrpos
1221 @item \savecurrpos (*@var{px} *@var{py})
1222 Save the current position as the absolute position referenced by
1223 @code{(*@var{px} *@var{py})}.
1224 @findex \savepos
1225 @item \savepos (@var{x} @var{y})(*@var{px} *@var{py})
1226 Save the coordinate position @code{(@var{x} @var{y})} as the absolute
1227 position referenced by @code{(*@var{px} *@var{py})}. The coordinate
1228 @code{(@var{x} @var{y})} is interpreted in the normal fashion as a
1229 coordinate relative to the current segment, using the current scaling
1230 factors and drawing unit.
1231 @end table
1232
1233 The symbolic names used to specify a saved position can consist of any
1234 characters that are not special to @TeX{}, but must start with a
1235 @code{*} character. The symbolic names can be used as the @var{x}
1236 and/or @var{y} coordinate in any command that needs a coordinate.
1237 Symbolic coordinates are not normally used with relative motion commands
1238 such as @code{\rlvec} or @code{\rmove}. If used with relative motion,
1239 the corresponding displacement is equal to the symbolic coordinate
1240 value.
1241
1242 On exit from a segment, the position and graphics state on entry is
1243 restored. Any changes to line types, scaling and position are
1244 discarded. However, it is sometimes useful alter the position on exit
1245 from a segment. The @code{\savepos} command allows for the saving of a
1246 position within the segment. This position can be restored after the
1247 @code{\esegment} with a @code{\move} command using the saved symbolic
1248 position. This approach can be used to build modules which operate in a
1249 manner analogous to the basic relative motion line vector commands.
1250
1251 The following example defines a macro which draws a box 0.75 inches wide
1252 by 0.5 inches high containing centered text. On leaving the macro the
1253 position will be set at a point on the righthand side of the box.
1254 @example
1255 @group
1256 \def\tbox #1@{\bsegment
1257 \lvec (0 +0.25) \lvec (0.75 +0.25)
1258 \lvec (0.75 -0.25) \lvec (0 -0.25) \lvec (0 0)
1259 \textref h:C v:C \htext (0.375 0)@{#1@}
1260 \savepos (0.75 0)(*ex *ey)
1261 \esegment
1262 \move (*ex *ey)@}
1263 @end group
1264 @end example
1265 With this definition, we can treat @code{\tbox} in the same way as the
1266 basic vector commands, stringing them together to form a block diagram
1267 as in this example.
1268 @example
1269 @group
1270 \centertexdraw@{
1271 \ravec (1 0) \tbox@{$H(z)$@} \ravec (1 0)
1272 @}
1273 @end group
1274 @end example
1275 @tex
1276 \def\tbox #1{\bsegment
1277 \lvec (0 +0.25) \lvec (0.75 +0.25)
1278 \lvec (0.75 -0.25) \lvec (0 -0.25) \lvec (0 0)
1279 \textref h:C v:C \htext (0.375 0){#1}
1280 \savepos (0.75 0)(*ex *ey)
1281 \esegment
1282 \move (*ex *ey)}
1283 \bigskip
1284 \centertexdraw{
1285 \ravec (1 0) \tbox{$H(z)$} \ravec (1 0)
1286 }
1287 @end tex
1288
1289 @node Scaling coordinates, Drawing size, Saving positions, Drawing Segments and Scaling
1290 @section Scaling coordinates
1291 @cindex scaling coordinates
1292 @cindex relative scaling
1293 @cindex segment scale
1294 @cindex unit scale
1295
1296 There are two scale factors available, the unit scale factor and the
1297 segment scale factor. The overall scale factor is the product of these
1298 two. There are absolute and relative versions of commands to change
1299 these scale factors.
1300
1301 The unit scale factor is normally used to affect global scale changes.
1302 Changes to the unit scale factor remains local to a segment, but
1303 propagate to inferior segments. The default value is unity.
1304
1305 The segment scale factor is used for local scale changes. It remains
1306 local to a segment. The segment scale factor is reset to unity on entry
1307 into each segment. This means that changes to the segment scale factor
1308 do not propagate to inferior segments.
1309
1310 @table @code
1311 @findex \setunitscale
1312 @item \setunitscale @var{scale}
1313 Set the unit scaling to @var{scale}. The argument @var{scale} is a real
1314 number which is used to scale coordinate values. The overall scaling
1315 factor is the product of the unit scale factor and the segment scale
1316 factor.
1317 @findex \relunitscale
1318 @item \relunitscale @var{value}
1319 Adjust the unit scale factor by multiplying by @var{value}. This has
1320 the effect of multiplying the overall scale factor by the same factor.
1321 The overall scaling factor is the product of the unit scale factor and
1322 the segment scale factor.
1323 @findex \setsegscale
1324 @item \setsegscale @var{scale}
1325 Set the segment scale factor. The argument @var{scale} is a real number
1326 which is used to scale coordinate values. The overall scale factor is
1327 the product of the unit scale factor and the segment scale factor.
1328 @findex \relsegscale
1329 @item \relsegscale @var{value}
1330 Adjust the segment scale factor by multiplying by @var{value}. This has
1331 the effect of multiplying the current overall scale factor by the same
1332 factor. The overall scaling factor is the product of the unit scale
1333 factor and the segment scale factor.
1334 @end table
1335
1336 In addition to the unit scale factor and the segment scale factor, the
1337 scaling can be controlled by the choice of drawing units with the
1338 command @code{\drawdim} (@pxref{Coordinate specification}).
1339
1340 @table @code
1341 @item \drawdim cm \setunitscale 2.54
1342 Set the units to centimetres scaled by 2.54. Together these commands
1343 are effectively the same as @code{\drawdim in}.
1344 @end table
1345
1346 The segment scale can be used to allow scale changes in segments so that
1347 values are in more convenient units. For example suppose dimensions in
1348 a segment are multiples of one third of an inch. The segment scale can
1349 be set once to make 1 drawing unit equal 0.3333 inches. From that point
1350 on, coordinates can be specified with integer values.
1351
1352 The following example defines a macro to draw a rectangular box which is
1353 twice as wide as it is high. The width is specified as an argument.
1354 @example
1355 @group
1356 \def\mybox #1@{\bsegment
1357 \setsegscale #1
1358 \lvec (0 +0.25) \lvec (1 +0.25) \lvec (1 -0.25)
1359 \lvec (0 -0.25) \lvec (0 0)
1360 \esegment@}
1361 @end group
1362 @end example
1363
1364 @node Drawing size, Initial current position, Scaling coordinates, Drawing Segments and Scaling
1365 @section Drawing size
1366 @cindex size of the drawing
1367
1368 The effective size of the drawing is determined by the maximum
1369 excursions of the coordinates supplied to @TeX{}draw commands. The
1370 minimum and maximum scaled @var{x} and @var{y} coordinates are tallied.
1371 Note that @code{\move} commands contribute to the determination of the
1372 calculated size of the drawing, even though they do not generate visible
1373 lines. The circle and ellipse commands add a compensation for the radii
1374 of circles and ellipses. The final @TeX{}draw drawing is placed in a
1375 @TeX{} box with lower lefthand corner corresponding to
1376 @code{(}@var{x}-min @var{y}-min@code{)} and upper righthand corner at
1377 @code{(}@var{x}-max @var{y}-max@code{)}.
1378
1379 Text generated by @code{\htext}, @code{\vtext} or @code{\rtext} can
1380 spill outside the box as determined above. Only the text reference
1381 point is guaranteed to be in the drawing box. Arcs can also spill
1382 outside the drawing box. Note also that the widths of lines, and the
1383 sizes of arrowheads do not affect the size of the drawing. The
1384 calculated size of the drawing will never be larger than the actual size
1385 of the drawing. In extreme cases in which text or lines extend far
1386 outside the drawing, extra @code{\move} commands should be used to
1387 establish the size of the drawing so that the @TeX{}draw box includes
1388 all of the drawing.
1389
1390 @TeX{}draw provides the @code{\drawbb} command to draw a box which
1391 indicates the effective size of the drawing. Whenever @code{\drawbb} is
1392 invoked, a ruled box is drawn around the drawing as it has been sized up
1393 to that point. Normally @code{\drawbb} is invoked just before the end
1394 of a drawing to indicate the effective size of the final drawing.
1395
1396 @table @code
1397 @findex \drawbb
1398 @item \drawbb
1399 Draw a ruled box around the effective size of a drawing produced by
1400 @TeX{}draw commands.
1401 @end table
1402
1403 @node Initial current position, , Drawing size, Drawing Segments and Scaling
1404 @section Initial current position
1405 @cindex current position
1406 @cindex initial current position
1407
1408 The first operation in a drawing should be a move to establish the
1409 current position. The current position can be established explicitly
1410 through a @code{\move} command or a text positioning command such as
1411 @code{\htext} with a coordinate. However, if an attempt is made to use
1412 a drawing command which needs a current position and none has been
1413 established, @TeX{}draw implicitly sets the initial current position to
1414 @code{(0 0)}. The size of the @TeX{}draw figure is normally determined
1415 from the sequence of coordinates specified, but will include the
1416 implicit initial position in case another initial position has not been
1417 explicitly specified.
1418
1419 @node Using TeXdraw with LaTeX, More Details, Drawing Segments and Scaling, Top
1420 @chapter Using @TeX{}draw with La@TeX{}
1421 @cindex accessing @TeX{}draw
1422 @cindex invoking @TeX{}draw
1423 @cindex La@TeX{}
1424 @cindex @code{texdraw} package
1425
1426 The La@TeX{} typesetting system uses a structured approach to declaring
1427 typesetting environments. For La@TeX{}2e, the @code{texdraw} package
1428 defines the @code{texdraw} environment. The @TeX{}draw environment is
1429 started with a @code{\begin@{texdraw@}} command and terminated with an
1430 @code{\end@{texdraw@}} command. All of the basic @TeX{}draw commands
1431 can be used within the @code{texdraw} environment.
1432
1433 As an example, a La@TeX{}2e variant of an earlier example can be
1434 constructed as follows.
1435 @example
1436 @group
1437 \documentclass@{article@}
1438 \usepackage@{texdraw@}
1439 ...
1440 \begin@{document@}
1441 ...
1442 \newcommand@{\tbox@}[1]@{%
1443 \bsegment
1444 \lvec (0 +0.25) \lvec (0.75 +0.25)
1445 \lvec (0.75 -0.25) \lvec (0 -0.25) \lvec (0 0)
1446 \textref h:C v:C \htext (0.375 0)@{#1@}
1447 \savepos (0.75 0)(*ex *ey)
1448 \esegment
1449 \move (*ex *ey)@}
1450 \begin@{center@}
1451 \begin@{texdraw@}
1452 \ravec (1 0) \tbox@{$H(z)$@} \ravec (1 0)
1453 \end@{texdraw@}
1454 \end@{center@}
1455 ...
1456 \end@{document@}
1457 @end group
1458 @end example
1459
1460 This example illustrates the use of the La@TeX{} command
1461 @code{\newcommand} as an alternative to the plain @TeX{} command
1462 @code{\def}. Instead of the basic @TeX{}draw command
1463 @code{\centertexdraw}, a nested combination of the La@TeX{} centering
1464 environment and the @TeX{}draw environment is used.
1465
1466 @menu
1467 * PostScript printer drivers::
1468 @end menu
1469
1470 @node PostScript printer drivers, , , Using TeXdraw with LaTeX
1471 @section PostScript printer drivers
1472 @cindex printer drivers
1473 @cindex PostScript printer drivers
1474
1475 @cindex @code{graphics} package
1476 The @code{texdraw} package uses the printer driver interface provided by
1477 the standard La@TeX{}2e @code{graphics} package. Any options to the
1478 @code{texdraw} package are passed to the @code{graphics} package.
1479 Specifically, the name of the PostScript driver to be used can be
1480 specified as an option to the @code{texdraw} package. With no explicit
1481 printer driver option, the default printer driver associated with the
1482 @code{graphics} package is used.
1483
1484 @cindex @code{dvips} printer driver
1485 @cindex @code{xdvi} driver
1486 @cindex @code{dvi2ps} printer driver
1487 @cindex @code{dvialw} printer driver
1488 @cindex @code{dvilaser} printer driver
1489 @cindex @code{dvipsone} printer driver
1490 @cindex @code{dviwindo} printer driver
1491 @cindex @code{dvitops} printer driver
1492 @cindex @code{oztex} printer driver
1493 @cindex @code{psprint} driver
1494 @cindex @code{textures} printer driver
1495 @cindex @code{pctexps} printer driver
1496 @cindex @code{pctexwin} printer driver
1497 @cindex rotated text
1498 @cindex text rotation
1499 The @code{texdraw} package can be used with any of the printer drivers
1500 supported by the @code{graphics} package that allow for the importation
1501 of PostScript graphics files, viz., @code{dvips}, @code{xdvi},
1502 @code{dvi2ps}, @code{dvialw}, @code{dvilaser}, @code{dvipsone},
1503 @code{dviwindo}, @code{dvitops}, @code{oztex}, @code{psprint},
1504 @code{textures}, @code{pctexps}, and @code{pctexwin}. Not all of these
1505 drivers support the text rotation needed for the @TeX{}draw commands
1506 @code{\vtext} and @code{\rtext}. Of the drivers listed above, only the
1507 following support support text rotation: @code{dvips}, @code{xdvi},
1508 @code{dvi2ps}, @code{dvitops}, @code{textures}, and @code{pctexps}.
1509
1510
1511 @node More Details, PostScript Commands, Using TeXdraw with LaTeX, Top
1512 @chapter More Details
1513
1514 The first part of this chapter offers some suggestions for strategies to
1515 isolate errors in @TeX{} and @TeX{}draw input. The second part of this
1516 chapter discusses implementational issues. An awareness of these issues
1517 is useful if @TeX{}draw is to be extended.
1518
1519 @menu
1520 * Errors while using TeXdraw::
1521 * Extending TeXdraw::
1522 * How TeXdraw merges graphics and text::
1523 @end menu
1524
1525 @node Errors while using TeXdraw, Extending TeXdraw, , More Details
1526 @section Errors while using @TeX{}draw
1527 @cindex problems while using @TeX{}draw
1528 @cindex errors while using @TeX{}draw
1529
1530 @TeX{} input is notoriously difficult to debug. If @TeX{} reports
1531 errors, so much the better. If the cause is not immediately obvious,
1532 consider using a binary search strategy, removing sections of code with
1533 the premature insertion of the @code{\bye} (or @code{\end@{document@}}
1534 for La@TeX{}) command (with the appropriate closing of any open groups
1535 and the like). Other strategies include the insertion of
1536 @code{\message@{I am here@}} at appropriate places. Try using
1537 @code{\tracingmacros=1}. Many problems turn out to be due to an
1538 incorrect number of macro arguments or incorrectly delimited macro
1539 arguments. The @code{\tracingmacros=1} option writes the macro
1540 arguments and macro expansions to the @TeX{} log file.
1541
1542 Certain errors may not manifest themselves until well after the
1543 offending command. For instance, if a closing parenthesis is missing
1544 from a @TeX{}draw coordinate, @TeX{} continues searching for the
1545 parenthesis. If one is found, perhaps many lines later, the @TeX{}draw
1546 error message @code{invalid coordinate} will be printed at this later
1547 point.
1548
1549 All input in the @TeX{}draw environment should be intended for
1550 interpretation by @TeX{}draw commands. @TeX{}draw places text inside a
1551 zero size box (the text itself extends outside the box). Extraneous
1552 input manifests itself as a non-zero size @TeX{}draw text box. This
1553 causes the @TeX{}draw text and the PostScript graphics to be displaced
1554 from one another. An error message is issued if a non-zero width
1555 @TeX{}draw text box is detected. If this error message appears, look
1556 for unintended character sequences amongst the commands to @TeX{}draw.
1557
1558 Several @TeX{}draw commands pass their arguments ``raw'' to the
1559 PostScript file. That means that invalid arguments can generate
1560 PostScript errors when the document is printed. For instance the
1561 argument of the @code{\setgray} command is passed straight through to
1562 the PostScript file. If this argument is non-numeric, a PostScript
1563 error results. Not all PostScript printers report errors back to the
1564 user. The print may just stop prematurely. One approach to debugging
1565 is to use a PostScript previewer on a workstation. That way, one can
1566 determine at which point in the drawing the PostScript error occurs.
1567
1568 @node Extending TeXdraw, How TeXdraw merges graphics and text, Errors while using TeXdraw, More Details
1569 @section Extending @TeX{}draw
1570 @cindex implementation
1571
1572 @TeX{}draw is implemented using a combination of @TeX{} commands and
1573 PostScript code. This section discusses some of the implementational
1574 issues as they relate to extending @TeX{}draw.
1575
1576 @TeX{}draw as implemented, offers a basic set of drawing features.
1577 These are adequate for certain tasks such as producing block diagrams.
1578 There are different approaches to extending @TeX{}draw to include other
1579 functions. In some cases, the desired functionality can be achieved by
1580 writing a @TeX{} macro which builds on top of the existing @TeX{}draw
1581 commands. As these extensions become more complex, the limitations of
1582 @TeX{} for computations become increasingly evident. In other cases,
1583 access to different features of PostScript is desired. The appropriate
1584 approach would be to write new PostScript procedures which can be
1585 accessed by @TeX{} macros.
1586
1587 Included with @TeX{}draw is a set of macros for directly accessing
1588 PostScript functions. These are described in an appendix
1589 (@pxref{PostScript Commands}).
1590
1591 @TeX{}draw also comes with a toolbox of routines for handling much of
1592 the user interface, converting between different coordinate
1593 representations and the like. The macros for coordinate decoding and
1594 for computations involving coordinates are described in an appendix
1595 (@pxref{TeXdraw Toolbox, , @TeX{}draw Toolbox}).
1596
1597 @menu
1598 * Scaling::
1599 * Resolution::
1600 * Text placement::
1601 * Intermediate PostScript file::
1602 @end menu
1603
1604 @node Scaling, Resolution, , Extending TeXdraw
1605 @subsection Scaling
1606 @cindex scaling
1607
1608 The scaling commands provided in @TeX{}draw are designed to affect only
1609 the coordinate values specified in commands. For instance, changing the
1610 @code{\setunitscale} value changes the interpretation of the coordinate
1611 in an @code{\avec (@var{x} @var{y})} command, but does not change the
1612 line width or arrowhead sizes in effect. None of the @TeX{}draw scaling
1613 commands affect the size of @TeX{} text produced by, for instance, the
1614 @code{\htext} command. Scale changes will however affect the
1615 positioning of text for subsequent commands.
1616
1617 The line parameters are changed only if the corresponding commands to
1618 change them are issued. If the @code{\linewd} command is given, the
1619 current coordinate scaling is used to determine the line width. To
1620 achieve a behaviour more like a global scaling, whenever the scale
1621 factor is changed, the line parameters should be set again.
1622
1623 @node Resolution, Text placement, Scaling, Extending TeXdraw
1624 @subsection Resolution
1625 @cindex resolution
1626
1627 @TeX{}draw scales coordinates before passing them to PostScript.
1628 Keeping track of the coordinate scaling is necessary, in any event, to
1629 allow @TeX{}draw to compute the maximum excursions of the coordinates.
1630 @TeX{}draw uses pixel units in its PostScript code. One pixel unit is
1631 equal to 1/300 of an inch. @TeX{}draw issues PostScript commands with
1632 integer valued pixel coordinates. This sets the positioning resolution
1633 for @TeX{}draw. The passing of integer valued coordinates which
1634 correspond to the device resolution keeps lines aligned with the device
1635 grid; parallel lines of the same width will be rendered with the same
1636 width.
1637
1638 The position saving mechanism in @TeX{}draw (@pxref{Saving positions})
1639 associates the pixel coordinates of a position with the specified name.
1640
1641 @TeX{}draw uses the limited real number representation provided by
1642 @TeX{}. These operations are based on the representation of dimensions
1643 as real-valued numbers of points. Internally in @TeX{}, dimensions are
1644 stored 32-bit values, normalized so that 1 pt corresponds to the scaled
1645 point (sp) value of 65536. Dimensions with magnitudes between 0.000015
1646 pt and 32767 pt can be represented. This is also the dynamic range of
1647 the @TeX{}draw pixel coordinates passed to PostScript. @TeX{}draw must
1648 convert from user supplied coordinates using the scaling factor (which
1649 itself consists of two components, the unit scale and the segment scale)
1650 and a pixel conversion factor. The use of limited precision real
1651 numbers in these computations can cause accumulation of error when
1652 relative scaling is used repeatedly.
1653
1654 @node Text placement, Intermediate PostScript file, Resolution, Extending TeXdraw
1655 @subsection Text placement
1656
1657 While in the @TeX{}draw environment, @TeX{} text is placed in a @TeX{}
1658 box while PostScript code is written to the intermediate file. At the
1659 end of the @TeX{}draw environment, the size of the drawing is
1660 determined. A @TeX{} box of this size is created. The @TeX{}
1661 @code{\special} mechanism is used to instruct the PostScript driver
1662 program to position the PostScript drawing from the intermediate file in
1663 this area. Next, the text generated by @TeX{}draw is positioned and
1664 placed in the box. Note that when the document is printed, the
1665 PostScript drawing is placed on the page before the @TeX{} text; @TeX{}
1666 text will appear on top of graphics.
1667
1668 @cindex rotated text
1669 @cindex text rotation
1670 The rotation of text is carried out with in-line PostScript code which
1671 does not appear in the intermediate PostScript file. This code is sent
1672 to the PostScript driver with a @code{\special} command. This
1673 PostScript code is embedded in the dvi (device independent) file that
1674 @TeX{} produces.
1675
1676 @node Intermediate PostScript file, , Text placement, Extending TeXdraw
1677 @subsection The intermediate PostScript file
1678 @cindex Encapsulated PostScript File
1679
1680 The intermediate PostScript file consists of a header, a body and a
1681 trailer following Encapsulated PostScript File (EPSF) standards. The
1682 header sets up PostScript definitions and default parameter values. The
1683 trailer includes the @code{BoundingBox} information which gives the
1684 coordinates in default PostScript units (72 per inch) for the lower
1685 lefthand corner and the upper righthand corner of the drawing. The body
1686 of the intermediate PostScript file contains the PostScript commands
1687 generated by @TeX{}draw.
1688
1689 Many moves in @TeX{}draw serve only to position text or to reset saved
1690 positions. @TeX{}draw buffers move commands in order to be able to
1691 collapse runs of moves. Only the last move of a run of moves is
1692 actually written to the PostScript file. However the intermediate moves
1693 still affect the size of the drawing. The expunging of moves means that
1694 the PostScript file @code{BoundingBox} information may indicate a drawing size
1695 larger than the PostScript commands themselves would warrant.
1696
1697 Drawing segments in @TeX{}draw show up in the PostScript file as saves
1698 and restores of the PostScript graphics state. Segment starts are
1699 buffered and only written out if necessary. This way ``empty'' segments
1700 do not generate output to the PostScript file. These empty segments
1701 arise if a segment contains only moves and text commands. The moves
1702 inside the segment are not needed since they are local to the segment,
1703 and the text commands do not generate output to the PostScript file.
1704
1705 If @TeX{}draw is used only for moves and text, no intermediate
1706 PostScript file will be created.
1707
1708 @node How TeXdraw merges graphics and text, , Extending TeXdraw, More Details
1709 @section How @TeX{}draw merges graphics and text
1710 @cindex graphics placement
1711 @cindex text placement
1712 @cindex placement of graphics and text
1713
1714 @TeX{}draw creates a box which is the same size as the graphic. The
1715 printer driver will place the PostScript graphic into this space. Any
1716 @TeX{} text generated by the @TeX{}draw commands will be superimposed on
1717 this graphic.
1718
1719 @cindex @code{texdraw} package
1720 @cindex @code{graphics} package
1721 The La@TeX{}2e front-end for @TeX{}draw is enabled by including the
1722 @code{texdraw} package. The @code{texdraw} package automatically
1723 invokes the standard @code{graphics} package distributed with
1724 La@TeX{}2e. The @code{graphics} package has support for a number of
1725 different printer drivers, including a number for PostScript printers.
1726 Any options to the @code{texdraw} package are passed on to the
1727 @code{graphics} package. Such an option can be used to select a driver
1728 other than the default one.
1729
1730 @cindex PostScript printer drivers
1731 @cindex printer drivers
1732 @cindex @code{dvips} printer driver
1733 @cindex rotated text
1734 @cindex text rotation
1735 Within the @code{graphics} package, the driver option is used to select
1736 definitions for the low-level macros which generate the @code{\special}
1737 commands needed to request insertion of a graphics file and to rotate
1738 text.@footnote{Not all PostScript drivers support text rotation.}
1739 @TeX{}draw uses the user-level macros defined by the @code{graphics}
1740 package (@pxref{PostScript printer drivers}). When not used with the
1741 La@TeX{}2e front-end, @TeX{}draw defines versions of these macros that
1742 are suitable for use with the @code{dvips} printer driver.
1743
1744 @node PostScript Commands, TeXdraw Toolbox, More Details, Top
1745 @appendix PostScript Commands
1746 @cindex PostScript commands
1747
1748 This appendix describes a set of macros for accessing some of the
1749 PostScript builtin functions. Each of these macros issues a single
1750 PostScript command. The extra services provided by @TeX{}draw are the
1751 interpretation of coordinates in user units relative to the current
1752 drawing segment and the writing of a pending @TeX{}draw move to the
1753 PostScript file. This last operation establishes the current point in
1754 PostScript. The user of these commands should be familiar with the
1755 concepts of path construction and filling in PostScript. Further
1756 details on the PostScript functions used can found in the
1757 @cite{PostScript Language Reference Manual, Second Edition}, Adobe
1758 Systems, Addison-Wesley, 1990.
1759
1760 These macros are distributed in file @file{txdps.tex}.
1761
1762 The @code{\PSsetlinecap} and @code{\PSsetlinejoin} commands control the
1763 way line ends and line joins are rendered. The default values set by
1764 @TeX{}draw (round caps and round join) are appropriate for most
1765 drawings. Changes to these parameters apply to the current and
1766 subsequent paths.
1767
1768 @cindex line cap
1769 @cindex line join
1770 @table @code
1771 @findex setlinecap
1772 @findex \PSsetlinecap
1773 @item \PSsetlinecap @var{type}
1774 Set the line cap parameter. The value @code{0} gives a butt cap;
1775 @code{1} gives a round cap; and @code{2} gives a projecting square cap.
1776 The initial value is corresponds to a round cap.
1777 @findex setlinejoin
1778 @findex \PSsetlinejoin
1779 @item \PSsetlinejoin @var{type}
1780 Set the line join parameter. The value @code{0} gives a miter join;
1781 @code{1} gives a round join; and @code{2} gives a bevel join. The
1782 initial value corresponds to a round join.
1783 @end table
1784
1785 @cindex stroking lines
1786 @cindex filling regions
1787 @cindex paths
1788 @cindex current position in PostScript
1789 PostScript paths and fill operations can be controlled by a number of
1790 functions. By design, @TeX{}draw always maintains a defined PostScript
1791 current point. Some of the following macros cause the PostScript
1792 current point to become undefined. The PostScript current point must be
1793 set again (say with a @code{\PSmoveto} command) before invoking basic
1794 @TeX{}draw commands.
1795 @table @code
1796 @findex stroke
1797 @findex \PSstroke
1798 @item \PSstroke
1799 Stroke a PostScript path. The current path is stroked with the current
1800 gray level (set with @code{\setgray}) and the current line pattern (set
1801 with @code{\lpatt}). The PostScript current point becomes undefined.
1802 @findex newpath
1803 @findex \PSnewpath
1804 @item \PSnewpath
1805 Establish a new path. The PostScript current point becomes undefined.
1806 @findex closepath
1807 @findex \PSclosepath
1808 @item \PSclosepath
1809 Close a subpath. A new subpath is started.
1810 @findex fill
1811 @findex \PSfill
1812 @item \PSfill
1813 Fill a region defined by a path. Each subpath is closed and the
1814 enclosed regions painted with the current gray level. The PostScript
1815 current point becomes undefined. The gray level can be set with the
1816 @TeX{}draw command @code{\setgray}.
1817 @end table
1818
1819 The following line commands interpret coordinates relative to the
1820 current @TeX{}draw scaling and drawing segment. The specified
1821 coordinate affects the drawing size as determined by @TeX{}draw.
1822 @cindex lines
1823 @cindex moves
1824 @table @code
1825 @findex lineto
1826 @findex \PSlineto
1827 @item \PSlineto (@var{x} @var{y})
1828 Add a line segment to the current path. This command is identical to
1829 the @TeX{}draw command @code{\lvec}. The PostScript current point must
1830 be defined before this command is issued.
1831 @findex moveto
1832 @findex \PSmoveto
1833 @item \PSmoveto (@var{x} @var{y})
1834 Move to the coordinate specified by @code{(@var{x} @var{y})}. The
1835 PostScript current point becomes defined.
1836 @end table
1837
1838 The following macros provide access to the general arc commands in
1839 PostScript. The coordinates are interpreted relative to the current
1840 @TeX{}draw scaling and drawing segment. The specified coordinate
1841 affects the drawing size as determined by @TeX{}draw.
1842 @cindex arcs
1843 @table @code
1844 @findex arc
1845 @findex \PSarc
1846 @item \PSarc r:@var{radius} sd:@var{start-angle} ed:@var{end-angle} (@var{x} @var{y})
1847 Draw a counterclockwise arc. The center of the arc is at the given
1848 position. The radius is specified by @var{radius}. The start and end
1849 angles (in degrees) are specified by @var{start-angle} and
1850 @var{end-angle}. If the PostScript current point is defined, this
1851 command also draws the line from the current point to the beginning of
1852 the arc. The line and arc become part of the current path. The current
1853 point becomes defined.
1854 @findex arcn
1855 @findex \PSarcn
1856 @item \PSarcn r:@var{radius} sd:@var{start-angle} ed:@var{end-angle} (@var{x} @var{y})
1857 Draw a clockwise arc. The center of the arc is at the given position.
1858 The radius is specified by @var{radius}. The start and end angles (in
1859 degrees) are specified by @var{start-angle} and @var{end-angle}. If the
1860 PostScript current point is defined, this command also draws the line
1861 from the current point to the beginning of the arc. The line and arc
1862 become part of the current path. The current point becomes defined.
1863 @end table
1864
1865 The macro @code{\writeps} provides the general facility to write
1866 arbitrary PostScript commands to the PostScript file. This macro is
1867 used by the preceding commands and by the @TeX{}draw commands
1868 themselves. This facility has to be used with care since changes in
1869 position or scaling resulting from the PostScript commands are not known
1870 to @TeX{}draw.
1871 @table @code
1872 @findex \writeps
1873 @item \writeps @{@var{<ps-commands>}@}
1874 Write PostScript commands to the intermediate PostScript file. Before
1875 the commands are inserted, any pending @TeX{}draw move is written to the
1876 PostScript file. The PostScript scaling gives 300 units/inch.
1877 @end table
1878
1879
1880 @node TeXdraw Toolbox, Examples, PostScript Commands, Top
1881 @appendix @TeX{}draw Toolbox
1882
1883 This appendix describes some of the macros supplied with @TeX{}draw
1884 which can be used to define additional commands for creating drawings.
1885 The macros described here work in the user specified coordinate system.
1886 Some of these toolbox macros are used by the @TeX{}draw commands
1887 themselves, others are supplied in an auxiliary file
1888 @file{txdtools.tex}.
1889
1890 @menu
1891 * Coordinate parsing::
1892 * Real arithmetic::
1893 * Arrow curve::
1894 @end menu
1895
1896 @node Coordinate parsing, Real arithmetic, , TeXdraw Toolbox
1897 @appendixsec Coordinate parsing
1898
1899 The coordinate parsing macro @code{\getpos} is useful for creating new
1900 commands. This macro takes care of stripping leading and trailing
1901 blanks from coordinates specified between parentheses. In addition,
1902 symbolic coordinates are translated to the corresponding relative
1903 coordinate using the segment offset and scaling in effect.
1904
1905 The macro @code{\currentpos} returns the relative coordinates of the
1906 current position. The returned values are relative to the current
1907 segment and the current scaling. The macro @code{\cossin} returns the
1908 real-valued cosine and sine of the direction of the line joining two
1909 points. The macro @code{\vectlen} returns the length of a vector. The
1910 results appear as the value of user supplied macro names.
1911
1912 @cindex coordinate parsing
1913 @cindex current position
1914 @cindex angle of a vector
1915 @cindex direction of a line
1916 @cindex cosine of a vector direction
1917 @cindex sine of a vector direction
1918 @cindex length of a vector
1919 @table @code
1920 @findex \getpos
1921 @item \getpos (@var{x} @var{y})\@var{mx}\@var{my}
1922 Decode coordinate values. The coordinates specified by @code{(@var{x}
1923 @var{y})} are decoded. Symbolic coordinates are translated to the
1924 corresponding relative coordinate using the current segment offset and
1925 scaling. The resulting character strings representing the real-valued
1926 coordinates are assigned to the macros specified by @code{\@var{mx}} and
1927 @code{\@var{my}}.
1928 @findex \currentpos
1929 @item \currentpos \@var{mx}\@var{my}
1930 Return the coordinates of the current position. The coordinates are
1931 relative to the current segment offset and scaling. The resulting
1932 character strings representing the real-valued coordinates are assigned
1933 to the macros specified by @code{\@var{mx}} and @code{\@var{my}}.
1934 @findex \cossin
1935 @item \cossin (@var{x1} @var{y1})(@var{x2} @var{y2})\@var{cosa}\@var{sina}
1936 Return the cosine and sine of the direction of a vector joining two
1937 points. The cosine and sine of the angle of the vector which goes from
1938 @code{(@var{x1} @var{y1})} to @code{(@var{x2} @var{y2})}. The character
1939 strings representing these real-valued quantities are assigned to the
1940 macros specified by @code{\@var{cosa}} and @code{\@var{sina}}.
1941 @findex \vectlen
1942 @item \vectlen (@var{x1} @var{y1})(@var{x2} @var{y2})\@var{len}
1943 Return the length of a vector joining two points. The length of the
1944 vector is relative to the current scaling. The character string
1945 representing the real-valued length is assigned to the macro specified
1946 by @code{\@var{len}}.
1947 @end table
1948
1949 @node Real arithmetic, Arrow curve, Coordinate parsing, TeXdraw Toolbox
1950 @appendixsec Real arithmetic
1951
1952 The @TeX{}draw toolbox supplies macros to perform real arithmetic on
1953 coordinate values. The result appears as the value of a user supplied
1954 macro name.
1955 @table @code
1956 @findex \realadd
1957 @item \realadd @{@var{value1}@} @{@var{value2}@} \@var{sum}
1958 Add two real quantities, assigning the resultant character string
1959 representing the sum to the macro @code{\@var{sum}}.
1960 @findex \realmult
1961 @item \realmult @{@var{value1}@} @{@var{value2}@} \@var{prod}
1962 Multiply two real quantities, assigning the resultant character string
1963 representing the product to the macro @code{\@var{prod}}.
1964 @findex \realdiv
1965 @item \realdiv @{@var{value1}@} @{@var{value2}@} \@var{result}
1966 Divide two real quantities, assigning the resultant character string
1967 representing the result of @var{value1}/@var{value2} to the macro
1968 @code{\@var{result}}.
1969 @end table
1970
1971 @node Arrow curve, , Real arithmetic, TeXdraw Toolbox
1972 @appendixsec Arrow curve
1973 @cindex example, arrow curve
1974
1975 This example illustrates the use of the @TeX{}draw toolbox routines to
1976 do computations with the coordinates. The problem will be tackled in
1977 two parts. First, we will produce a macro to place an arrowhead on a
1978 Bezier curve. Then given this macro, we will produce a macro which can
1979 draw a ``wiggly'' line from the current position to a given coordinate.
1980
1981 @tex
1982 \bigskip
1983 \def\cavec (#1 #2)(#3 #4)(#5 #6){
1984 \clvec (#1 #2)(#3 #4)(#5 #6)
1985 \cossin (#3 #4)(#5 #6)\cosa\sina
1986 \rmove (0 0) % stroke the Bezier curve
1987 \bsegment
1988 \drawdim in \setsegscale 0.05
1989 \move ({-\cosa} -\sina) \avec (0 0)
1990 \esegment}
1991
1992 \def\caw (#1 #2){
1993 \currentpos \xa\ya
1994 \cossin ({\xa} \ya)(#1 #2)\cosa\sina
1995
1996 % The nominal wiggly curve is (0 0) (1+dx dy) (-dx -dy) (1 0)
1997 % Find the rotated offset (dx dy) -> (du dv)
1998 \rotatecoord (0.4 0.1)\cosa\sina \du\dv
1999
2000 % calculate the length of the vector
2001 \vectlen ({\xa} \ya)(#1 #2)\len
2002
2003 % draw the curve in normalized units
2004 \bsegment
2005 \setsegscale {\len}
2006 \realadd \cosa \du \tmpa \realadd \sina \dv \tmpb
2007 \cavec ({\tmpa} \tmpb)({-\du} -\dv)({\cosa} \sina)
2008 \esegment
2009
2010 \move (#1 #2)}
2011
2012 % rotate a coordinate (x y)
2013 % arguments: (x y) cosa sina x' y'
2014 % x' = cosa * x - sina * y; y' = sina * x + cosa * y
2015 \def\rotatecoord (#1 #2)#3#4#5#6{
2016 \getpos (#1 #2)\xarg\yarg
2017 \realmult \xarg {#3} \tmpa \realmult \yarg {#4} \tmpb
2018 \realadd \tmpa {-\tmpb} #5
2019 \realmult \xarg {#4} \tmpa \realmult \yarg {#3} \tmpb
2020 \realadd \tmpa \tmpb #6}
2021
2022 \centertexdraw{
2023 \arrowheadtype t:W
2024 \move (0 0)
2025 \cavec (1.4 0.1)(-0.4 -0.1)(1 0)
2026 \move (1 0) \caw (1 1) \htext{tip at \tt (1 1)}
2027 \move (1 0) \caw (2 1) \htext{tip at \tt (2 1)}
2028 \move (1 0) \caw (2 0) \htext{tip at \tt (2 0)}
2029 \move (0 1.13) \move (0 -0.04)
2030 }
2031 @end tex
2032
2033 The first macro, @code{\cavec}, uses the @code{\cossin} command to
2034 determine the the cosine and sine of the angle of the line joining the
2035 second control point to the end point of the Bezier curve. Recall that
2036 the Bezier curve is tangent to this line at the end point. After
2037 drawing the Bezier curve, the scaling is set locally to absolute units
2038 of 0.05 inches. We go back down the line from the end point by 0.05
2039 inches and draw an arrow vector to the end point from there. This arrow
2040 vector is mostly arrowhead, with little or no tail.
2041
2042 @example
2043 @group
2044 \def\cavec (#1 #2)(#3 #4)(#5 #6)@{
2045 \clvec (#1 #2)(#3 #4)(#5 #6)
2046 \cossin (#3 #4)(#5 #6)\cosa\sina
2047 \rmove (0 0)
2048 \bsegment
2049 \drawdim in \setsegscale 0.05
2050 \move (@{-\cosa@} -\sina) \avec (0 0)
2051 \esegment@}
2052 @end group
2053 @end example
2054
2055 Note the use of macros as arguments to a @code{\move} command. Minus
2056 signs are put in front of the macros. However, the value of the macro
2057 @code{\cosa} or @code{\sina} could be negative. Fortunately, @TeX{}
2058 accepts two minus signs in a row and interprets the result as positive.
2059 Note that the @code{\rmove (0 0)} command before the beginning of the
2060 segment ensures that the Bezier curve is stroked before the arrowhead is
2061 drawn.
2062
2063 The second macro @code{\caw} builds on @code{\cavec}. The goal is to
2064 produce a wiggly vector that can be used as a pointer in a drawing.
2065 Consider the following symmetrical normalized Bezier curve.
2066 @example
2067 \centertexdraw@{ \move (0 0) \cavec (1.4 0.1)(-0.4 -0.1)(1 0) @}
2068 @end example
2069
2070 This curve has the appropriate wiggle. Now we want to be able to draw
2071 this curve, appropriately scaled and rotated. The macro @code{\caw}
2072 needs to do computations on the coordinates. First, @code{\caw} uses
2073 the macros @code{\getpos} and @code{\currentpos} to get the positions of
2074 the end and start of the curve. Next, the length of the vector is
2075 calculated using the macro @code{\vectlen}. A local macro
2076 @code{\rotatecoord} is used to rotate a coordinate pair about the
2077 origin, using the cosine and sine of the rotation angle. The vector
2078 length is used to scale the normalized curve. The remaining code draws
2079 the rotated, normalized curve.
2080
2081 @example
2082 \def\caw (#1 #2)@{
2083 \currentpos \xa\ya
2084 \cossin (@{\xa@} \ya)(#1 #2)\cosa\sina
2085
2086 % The nominal wiggly curve is (0 0) (1+dx dy) (-dx -dy) (1 0)
2087 % Find the rotated offset (dx dy) -> (du dv)
2088 \rotatecoord (0.4 0.1)\cosa\sina \du\dv
2089
2090 % calculate the length of the vector
2091 \vectlen (@{\xa@} \ya)(#1 #2)\len
2092
2093 % draw the curve in normalized units
2094 \bsegment
2095 \setsegscale @{\len@}
2096 \realadd \cosa \du \tmpa \realadd \sina \dv \tmpb
2097 \cavec (@{\tmpa@} \tmpb)(@{-\du@} -\dv)(@{\cosa@} \sina)
2098 \esegment
2099 \move (#1 #2)@}
2100
2101 % rotate a coordinate (x y)
2102 % arguments: (x y) cosa sina x' y'
2103 % x' = cosa * x - sina * y; y' = sina * x + cosa * y
2104 \def\rotatecoord (#1 #2)#3#4#5#6@{
2105 \getpos (#1 #2)\xarg\yarg
2106 \realmult \xarg @{#3@} \tmpa \realmult \yarg @{#4@} \tmpb
2107 \realadd \tmpa @{-\tmpb@} #5
2108 \realmult \xarg @{#4@} \tmpa \realmult \yarg @{#3@} \tmpb
2109 \realadd \tmpa \tmpb #6@}
2110 @end example
2111
2112 Finally, the new macro can be used as follows.
2113 @example
2114 \centertexdraw@{
2115 \arrowheadtype t:W
2116 \move (0 0)
2117 \cavec (1.4 0.1)(-0.4 -0.1)(1 0)
2118 \move (1 0) \caw (1 1) \htext@{tip at \tt (1 1)@}
2119 \move (1 0) \caw (2 1) \htext@{tip at \tt (2 1)@}
2120 \move (1 0) \caw (2 0) \htext@{tip at \tt (2 0)@}
2121
2122 @}
2123 @end example
2124
2125 Note that the Bezier curve in the macro @code{\cavec} lies below the
2126 arrowhead. The example then draws an arrowhead of type @code{W} to
2127 erase the part of the line below the arrowhead.
2128
2129 @node Examples, Command Listing, TeXdraw Toolbox, Top
2130 @appendix Examples
2131 @cindex example, block diagram
2132
2133 This appendix shows examples of the use of @TeX{}draw.
2134
2135 @menu
2136 * Block diagram::
2137 * Filter response graph::
2138 * Geometric construction::
2139 @end menu
2140
2141 @node Block diagram, Filter response graph, , Examples
2142 @appendixsec Block diagram of a lattice filter
2143
2144 The block diagram of a lattice filter uses a library of extended
2145 commands built from the basic @TeX{}draw commands.
2146
2147 @tex
2148 \bigskip
2149 \bigskip
2150 \def\delay {\bsegment
2151 \setsegscale 0.3
2152 \lvec (0 +0.5) \lvec (1 +0.5) \lvec (1 -0.5)
2153 \lvec (0 -0.5) \lvec (0 0)
2154 \textref h:C v:C \htext (0.5 0){$z^{-1}$}
2155 \savepos (1 0)(*ex *ey)
2156 \esegment
2157 \move (*ex *ey)}
2158 \def\bdot {\fcir f:0 r:0.02 }
2159 \def\Ttext #1{\bsegment
2160 \textref h:C v:B \htext (0 +0.06){#1}
2161 \esegment}
2162 \def\Btext #1{\bsegment
2163 \textref h:C v:T \htext (0 -0.06){#1}
2164 \esegment}
2165 \def\Ltext #1{\bsegment
2166 \textref h:R v:C \htext (-0.06 0){#1}
2167 \esegment}
2168 \def\Rtext #1{\bsegment
2169 \textref h:L v:C \htext (+0.06 0){#1}
2170 \esegment}
2171 \def\cradius {0.08}
2172 \def\pluss {\bsegment
2173 \setsegscale {\cradius}
2174 \move (-0.5 0) \lvec (+0.5 0)
2175 \move (0 -0.5) \lvec (0 +0.5)
2176 \esegment}
2177 \def\pcir {\lcir r:{\cradius} \pluss}
2178 \def\puttext (#1 #2)#3{\bsegment
2179 \setsegscale {\cradius}
2180 \textref h:C v:C \htext (#1 #2){#3}
2181 \esegment}
2182 \def\putwnw #1{\puttext (-1.7 +1.2){#1}}
2183 \def\putwsw #1{\puttext (-1.7 -1.2){#1}}
2184 \def\putn #1{\puttext ( 0 +2 ){#1}}
2185 \def\puts #1{\puttext ( 0 -2 ){#1}}
2186 \def\avectoc (#1 #2){\currentpos \xa\ya
2187 \cossin ({\xa} \ya)(#1 #2)\cosa\sina
2188 \savepos (#1 #2)(*tx *ty)
2189 \bsegment
2190 \move (*tx *ty)
2191 \setsegscale {\cradius}
2192 \rmove ({-\cosa} -\sina)
2193 \savecurrpos (*ex *ey)
2194 \esegment
2195 \avec (*ex *ey)
2196 \move (#1 #2)}
2197 \def\avecfrc (#1 #2){\currentpos \xa\ya
2198 \cossin ({\xa} \ya)(#1 #2)\cosa\sina
2199 \bsegment
2200 \setsegscale {\cradius}
2201 \move ({\cosa} \sina)
2202 \savecurrpos (*ex *ey)
2203 \esegment
2204 \move (*ex *ey)
2205 \avec (#1 #2)}
2206
2207 \centertexdraw{
2208 \drawdim in
2209 \arrowheadtype t:F \arrowheadsize l:0.08 w:0.04
2210 \def\pl {$\scriptscriptstyle +$} \def\mn {$\scriptscriptstyle -$}
2211
2212 \move (0 +0.63) \move (0 -0.60) % compensate for the text size
2213 \move (0 0)
2214
2215 % Input to the first stage
2216 \bsegment
2217 \Ltext{$x(n)$}
2218 \lvec (0.3 0) \bdot \lvec (0.3 +0.4)
2219 \move (0.3 0) \lvec (0.3 -0.4)
2220 \savepos (0.3 0)(*ex *ey)
2221 \esegment
2222 \move (*ex *ey)
2223
2224 % first lattice stage
2225 \bsegment
2226 \move (0 +0.4) \avectoc (1.7 +0.4)
2227 \pcir \putwnw{\pl} \puts{\mn}
2228 \avecfrc (2.1 +0.4)
2229 \move (0 -0.4) \avec (0.4 -0.4) \delay \avectoc (1.7 -0.4)
2230 \pcir \putwsw{\pl} \putn{\mn}
2231 \avecfrc (2.1 -0.4)
2232 \move (0.9 +0.4) \bdot \avectoc (1.7 -0.4)
2233 \move (0.9 -0.4) \bdot \avectoc (1.7 +0.4)
2234 \move (0.1 +0.42) \Ttext {$f_0(n)$}
2235 \move (2.0 +0.42) \Ttext {$f_1(n)$}
2236 \move (0.1 -0.4) \Btext {$b_0(n)$}
2237 \move (2.0 -0.4) \Btext {$b_1(n)$}
2238 \textref h:L v:B \htext (1.15 +0.2){$K_1$}
2239 \textref h:L v:T \htext (1.15 -0.2){$K_1$}
2240 \savepos (2.1 0)(*ex *ey)
2241 \esegment
2242 \move (*ex *ey)
2243
2244 % center section
2245 \bsegment
2246 \textref h:C v:C
2247 \htext (0.3 +0.4){$\cdots$}
2248 \htext (0.3 -0.4){$\cdots$}
2249 \savepos (0.6 0)(*ex *ey)
2250 \esegment
2251 \move (*ex *ey)
2252
2253 % last lattice stage
2254 \bsegment
2255 \move (0 +0.4) \avectoc (1.7 +0.4)
2256 \pcir \putwnw{\pl} \puts{\mn}
2257 \avecfrc (2.3 +0.4) \Rtext{$e(n)$}
2258 \move (0 -0.4) \avec (0.4 -0.4) \delay \avectoc (1.7 -0.4)
2259 \pcir \putwsw{\pl} \putn{\mn}
2260 \avecfrc (2.1 -0.4)
2261 \move (0.9 +0.4) \bdot \avectoc (1.7 -0.4)
2262 \move (0.9 -0.4) \bdot \avectoc (1.7 +0.4)
2263 \move (0.1 +0.42) \Ttext {$f_{P-1}(n)$}
2264 \move (2.0 +0.42) \Ttext {$f_P(n)$}
2265 \move (0.1 -0.4) \Btext {$b_{P-1}(n)$}
2266 \move (2.0 -0.4) \Btext {$b_P(n)$}
2267 \textref h:L v:B \htext (1.15 +0.2){$K_P$}
2268 \textref h:L v:T \htext (1.15 -0.2){$K_P$}
2269 \esegment
2270 }
2271 \bigskip
2272 @end tex
2273
2274 The block diagram uses a ``delay'' block. This is defined as a segment
2275 which leaves the current position at the end of this block. A second
2276 macro, @code{\bdot}, draws a ``big'' dot which is used to mark junctions
2277 of lines. The @code{\Ttext} command centers text above a given point.
2278 The offset to position the text is local to a segment, resulting in no
2279 change to the current point. Similar macros to position text below a
2280 point (@code{\Btext}), to the left of a point (@code{\Ltext}) and to the
2281 right of a point (@code{\Rtext}) are used in the final drawing.
2282 @example
2283 \def\delay @{\bsegment
2284 \setsegscale 0.3
2285 \lvec (0 +0.5) \lvec (1 +0.5) \lvec (1 -0.5)
2286 \lvec (0 -0.5) \lvec (0 0)
2287 \textref h:C v:C \htext (0.5 0)@{$z^@{-1@}$@}
2288 \savepos (1 0)(*ex *ey)
2289 \esegment
2290 \move (*ex *ey)@}
2291 \def\bdot @{\fcir f:0 r:0.02 @}
2292 \def\Ttext #1@{\bsegment
2293 \textref h:C v:B \htext (0 +0.06)@{#1@}
2294 \esegment@}
2295 @end example
2296
2297 Several of the block diagram elements scale with the size of the summing
2298 nodes. The radius of the circles for the summing nodes is defined as
2299 the macro @code{\cradius}. The summing nodes will have enclosed plus
2300 signs, appropriately scaled. The plus sign is drawn by the macro
2301 @code{\pluss}. The macro @code{\pcir} draws both the circle and the
2302 plus sign. The incoming lines to a summing node will be labelled with
2303 plus or minus signs (characters this time), placed at the appropriate
2304 position with respect to the center of the summing node. These
2305 positions are given in terms of compass directions. The macro
2306 @code{\putwnw} places text west by north-west relative to the center of
2307 the summing node.
2308 @example
2309 \def\cradius @{0.08@}
2310 \def\pluss @{\bsegment
2311 \setsegscale @{\cradius@}
2312 \move (-0.5 0) \lvec (+0.5 0)
2313 \move (0 -0.5) \lvec (0 +0.5)
2314 \esegment@}
2315 \def\pcir @{\lcir r:@{\cradius@} \pluss@}
2316 \def\puttext (#1 #2)#3@{\bsegment
2317 \setsegscale @{\cradius@}
2318 \textref h:C v:C \htext (#1 #2)@{#3@}
2319 \esegment@}
2320 \def\putwnw #1@{\puttext (-1.7 +1.2)@{#1@}@}
2321 @end example
2322
2323 The block diagram has vectors arriving and departing from the summing
2324 nodes (circles). One could calculate the points of intersection of the
2325 lines with the circles, and then enter the values into the @TeX{}draw
2326 code. However, in this example, we implement an automated procedure.
2327 Two macros are needed, an arrow vector to a circle (@code{\avectoc}) and
2328 an arrow vector leaving from a circle (@code{\avecfrc}). The macros
2329 will calculate the point of intersection with the circle and start or
2330 end the vector at the intersection point.
2331
2332 The arrow macros use scaling and relative positioning inside of a
2333 drawing segment. In the case of the macro @code{\avectoc}, a move is
2334 made to the final point (center of the circle), then within a drawing
2335 segment, a scaled move is made back towards the initial point to
2336 determine the intersection point with the circle.
2337
2338 @example
2339 \def\avectoc (#1 #2)@{\currentpos \xa\ya
2340 \cossin (@{\xa@} \ya)(#1 #2)\cosa\sina
2341 \savepos (#1 #2)(*tx *ty)
2342 \bsegment
2343 \move (*tx *ty)
2344 \setsegscale @{\cradius@}
2345 \rmove (@{-\cosa@} -\sina)
2346 \savecurrpos (*ex *ey)
2347 \esegment
2348 \avec (*ex *ey)
2349 \move (#1 #2)@}
2350 \def\avecfrc (#1 #2)@{\currentpos \xa\ya
2351 \cossin (@{\xa@} \ya)(#1 #2)\cosa\sina
2352 \bsegment
2353 \setsegscale @{\cradius@}
2354 \move (@{\cosa@} \sina)
2355 \savecurrpos (*ex *ey)
2356 \esegment
2357 \move (*ex *ey)
2358 \avec (#1 #2)@}
2359 @end example
2360
2361 Having defined these macros, we are ready to draw the block diagram.
2362 The first and last sections of the lattice filter are very similar,
2363 differing mainly in the text labels. With more effort, code could be
2364 shared between the commands used to draw these blocks.
2365 @example
2366 \centertexdraw@{
2367 \drawdim in
2368 \arrowheadtype t:F \arrowheadsize l:0.08 w:0.04
2369 \def\pl @{$\scriptscriptstyle +$@} \def\mn @{$\scriptscriptstyle -$@}
2370
2371 \move (0 +0.63) \move (0 -0.60) % compensate for the text size
2372 \move (0 0)
2373
2374 % Input to the first stage
2375 \bsegment
2376 \Ltext@{$x(n)$@}
2377 \lvec (0.3 0) \bdot \lvec (0.3 +0.4) \move (0.3 0) \lvec (0.3 -0.4)
2378 \savepos (0.3 0)(*ex *ey)
2379 \esegment
2380 \move (*ex *ey)
2381
2382 % first lattice stage
2383 \bsegment
2384 \move (0 +0.4) \avectoc (1.7 +0.4)
2385 \pcir \putwnw@{\pl@} \puts@{\mn@}
2386 \avecfrc (2.1 +0.4)
2387 \move (0 -0.4) \avec (0.4 -0.4) \delay \avectoc (1.7 -0.4)
2388 \pcir \putwsw@{\pl@} \putn@{\mn@}
2389 \avecfrc (2.1 -0.4)
2390 \move (0.9 +0.4) \bdot \avectoc (1.7 -0.4)
2391 \move (0.9 -0.4) \bdot \avectoc (1.7 +0.4)
2392 \move (0.1 +0.42) \Ttext @{$f_0(n)$@}
2393 \move (2.0 +0.42) \Ttext @{$f_1(n)$@}
2394 \move (0.1 -0.4) \Btext @{$b_0(n)$@}
2395 \move (2.0 -0.4) \Btext @{$b_1(n)$@}
2396 \textref h:L v:B \htext (1.15 +0.2)@{$K_1$@}
2397 \textref h:L v:T \htext (1.15 -0.2)@{$K_1$@}
2398 \savepos (2.1 0)(*ex *ey)
2399 \esegment
2400 \move (*ex *ey)
2401
2402 % center section
2403 \bsegment
2404 \textref h:C v:C \htext (0.3 +0.4)@{$\cdots$@}
2405 \htext (0.3 -0.4)@{$\cdots$@}
2406 \savepos (0.6 0)(*ex *ey)
2407 \esegment
2408 \move (*ex *ey)
2409
2410 % last lattice stage
2411 \bsegment
2412 \move (0 +0.4) \avectoc (1.7 +0.4)
2413 \pcir \putwnw@{\pl@} \puts@{\mn@}
2414 \avecfrc (2.3 +0.4) \Rtext@{$e(n)$@}
2415 \move (0 -0.4) \avec (0.4 -0.4) \delay \avectoc (1.7 -0.4)
2416 \pcir \putwsw@{\pl@} \putn@{\mn@}
2417 \avecfrc (2.1 -0.4)
2418 \move (0.9 +0.4) \bdot \avectoc (1.7 -0.4)
2419 \move (0.9 -0.4) \bdot \avectoc (1.7 +0.4)
2420 \move (0.1 +0.42) \Ttext @{$f_@{P-1@}(n)$@}
2421 \move (2.0 +0.42) \Ttext @{$f_P(n)$@}
2422 \move (0.1 -0.4) \Btext @{$b_@{P-1@}(n)$@}
2423 \move (2.0 -0.4) \Btext @{$b_P(n)$@}
2424 \textref h:L v:B \htext (1.15 +0.2)@{$K_P$@}
2425 \textref h:L v:T \htext (1.15 -0.2)@{$K_P$@}
2426 \esegment
2427 @}
2428 @end example
2429
2430 The macros used in this example are similar to the block diagram macros
2431 defined in the file @file{blockdiagram.tex}.
2432
2433 @node Filter response graph, Geometric construction, Block diagram, Examples
2434 @appendixsec Filter response graph
2435 @cindex example, graph
2436
2437 This example shows the response of a canonical filter. @TeX{}draw is
2438 not well suited for general purpose graphing --- it has no coordinate
2439 translation facility nor does it have separate @var{x} and @var{y}
2440 scaling. Nonetheless, for certain simple graphs, @TeX{}draw is
2441 adequate.
2442
2443 @tex
2444 \bigskip
2445 \centertexdraw{
2446 \arrowheadtype t:F \arrowheadsize l:0.08 w:0.04
2447 \def\ds {\displaystyle}
2448 \def\ticklab (#1 #2)#3{\move(#1 #2)
2449 \bsegment
2450 \lvec (0 0.05)
2451 \textref h:C v:T \htext (0 -0.05){#3}
2452 \esegment}
2453 \def\Rtext #1{\bsegment
2454 \textref h:L v:C \htext ( 0.08 0){#1}
2455 \esegment}
2456
2457 \move (2.4 -0.32) % move to set the size
2458
2459 \move (0 0)
2460 % Axes
2461 \avec (0 1.4)
2462 \move (0 0) \avec (2.2 0) \Rtext{$\omega$}
2463 \ticklab (0 0) {0}
2464 \ticklab (0.8 0) {$\ds {\pi \over 2N} $}
2465 \ticklab (1.2 0) {$\omega_s$}
2466 \ticklab (1.6 0) {$\ds {\pi \over N} $}
2467
2468 \linewd 0.025
2469 \move (0 1)
2470 \lvec (0.4 1)
2471 \lvec (0.44 0.998)
2472 \lvec (0.48 0.988)
2473 \lvec (0.52 0.973)
2474 \lvec (0.56 0.951)
2475 \lvec (0.60 0.923)
2476 \lvec (0.64 0.891)
2477 \lvec (0.68 0.852)
2478 \lvec (0.72 0.809)
2479 \lvec (0.76 0.760)
2480 \lvec (0.80 0.707)
2481 \lvec (0.84 0.649)
2482 \lvec (0.88 0.587)
2483 \lvec (0.92 0.522)
2484 \lvec (0.96 0.454)
2485 \lvec (1.00 0.382)
2486 \lvec (1.04 0.309)
2487 \lvec (1.08 0.233)
2488 \lvec (1.12 0.156)
2489 \lvec (1.16 0.078)
2490 \lvec (1.20 0)
2491 \lvec (1.9 0)
2492 }
2493 \bigskip
2494 @end tex
2495
2496 In this example, macro @code{\ticklab} places a labelled axis tick at a
2497 given position. The data is specified in a straightforward manner,
2498 having been scaled beforehand to give the desired aspect ratio for the
2499 graph.
2500
2501 @example
2502 \centertexdraw@{
2503 \arrowheadtype t:F \arrowheadsize l:0.08 w:0.04
2504 \def\ds @{\displaystyle@}
2505 \def\ticklab (#1 #2)#3@{\move(#1 #2)
2506 \bsegment
2507 \lvec (0 0.05)
2508 \textref h:C v:T \htext (0 -0.05)@{#3@}
2509 \esegment@}
2510 \def\Rtext #1@{\bsegment
2511 \textref h:L v:C \htext (+0.08 0)@{#1@}
2512 \esegment@}
2513
2514 \move (2.4 -0.3) % move to set the size
2515
2516 \move (0 0)
2517 % Axes
2518 \avec (0 +1.4)
2519 \move (0 0) \avec (2.2 0) \Rtext@{$\omega$@}
2520 \ticklab (0 0) @{0@}
2521 \ticklab (0.8 0) @{$\ds @{\pi \over 2N@} $@}
2522 \ticklab (1.2 0) @{$\omega_s$@}
2523 \ticklab (1.6 0) @{$\ds @{\pi \over N@} $@}
2524
2525 \linewd 0.025
2526 \move (0 1)
2527 \lvec (0.4 1)
2528 \lvec (0.44 0.998)
2529 \lvec (0.48 0.988)
2530 \lvec (0.52 0.973)
2531 \lvec (0.56 0.951)
2532 ...
2533 \lvec (1.08 0.233)
2534 \lvec (1.12 0.156)
2535 \lvec (1.16 0.078)
2536 \lvec (1.20 0)
2537 \lvec (1.9 0)
2538 @}
2539 @end example
2540
2541 @node Geometric construction, , Filter response graph, Examples
2542 @appendixsec Geometric construction
2543 @cindex example, circle and ellipse
2544
2545 This example shows a geometric construction which places an ellipse
2546 tangent to an enclosing circle. The size of the ellipse is determined
2547 from geometric considerations. Macros are used to modularize the code.
2548 The example alters the unit scale factor. This allows the drawing to be
2549 carried out in units normalized to the radius of the circle.
2550
2551 @tex
2552 \bigskip
2553 \centertexdraw{
2554 \arrowheadtype t:V \arrowheadsize l:0.08 w:0.04
2555 \linewd 0.01
2556 \setunitscale 1.5 % circle will have radius 1.5 inches
2557
2558 \def\Btext #1{\bsegment
2559 \textref h:C v:T \htext (0 -0.04){#1}
2560 \esegment}
2561 \def\Ttext #1{\bsegment
2562 \textref h:C v:B \htext (0 0.04){#1}
2563 \esegment}
2564 \def\Ltext #1{\bsegment
2565 \textref h:R v:C \htext (-0.04 0){#1}
2566 \esegment}
2567 \def\bdot {\fcir f:0 r:0.0133 }
2568 \def\vtick {\bsegment
2569 \move (0 -0.05) \lvec (0 0.05)
2570 \esegment}
2571 \def\htick {\bsegment
2572 \move (-0.05 0) \lvec ( 0.05 0)
2573 \esegment}
2574 \def\Hlen #1#2{\bsegment
2575 \vtick \avec ({#1} 0) \vtick \avec (0 0)
2576 \relsegscale 0.5
2577 \move ({#1} 0) \Ttext {#2}
2578 \esegment}
2579 \def\Vlen #1#2{\bsegment
2580 \htick \avec (0 {#1}) \htick \avec (0 0)
2581 \relsegscale 0.5
2582 \move (0 {#1}) \Ltext {#2}
2583 \esegment}
2584
2585 \lcir r:1 % circle
2586 \move (-1.05 0) \lvec ( 1.05 0) % axes
2587 \move (0 -1.05) \lvec (0 1.05)
2588
2589 \move (0 0) \lvec (0.707 0.707) \bdot
2590 \rmove (0.02 0.02) \textref h:L v:B \htext {X}
2591 \move (0.707 -0.707) \bdot
2592 \textref h:R v:T \htext(-0.02 -0.02){O}
2593
2594 \move (0.5 0) % center of ellipse
2595 \bsegment
2596 \lellip rx:0.435 ry:0.804
2597 \bdot \Btext {$\beta_2$}
2598 \move (0 0.15) \Hlen {0.435}{$|\beta_1{+}\beta_3|$}
2599 \move (-0.7 0) \Vlen {0.804}{$|\beta_1{-}\beta_3|$}
2600 \esegment
2601 }
2602 \bigskip
2603 @end tex
2604 @example
2605 \centertexdraw@{
2606 \arrowheadtype t:V \arrowheadsize l:0.08 w:0.04
2607 \linewd 0.01
2608 \setunitscale 1.5 % circle will have radius 1.5 inches
2609
2610 \def\Btext #1@{\bsegment
2611 \textref h:C v:T \htext (0 -0.04)@{#1@}
2612 \esegment@}
2613 \def\Ttext #1@{\bsegment
2614 \textref h:C v:B \htext (0 +0.04)@{#1@}
2615 \esegment@}
2616 \def\Ltext #1@{\bsegment
2617 \textref h:R v:C \htext (-0.04 0)@{#1@}
2618 \esegment@}
2619 \def\bdot @{\fcir f:0 r:0.0133 @}
2620 \def\vtick @{\bsegment
2621 \move (0 -0.05) \lvec (0 +0.05)
2622 \esegment@}
2623 \def\htick @{\bsegment
2624 \move (-0.05 0) \lvec (+0.05 0)
2625 \esegment@}
2626 \def\Hlen #1#2@{\bsegment
2627 \vtick \avec (@{#1@} 0) \vtick \avec (0 0)
2628 \relsegscale 0.5
2629 \move (@{#1@} 0) \Ttext @{#2@}
2630 \esegment@}
2631 \def\Vlen #1#2@{\bsegment
2632 \htick \avec (0 @{#1@}) \htick \avec (0 0)
2633 \relsegscale 0.5
2634 \move (0 @{#1@}) \Ltext @{#2@}
2635 \esegment@}
2636
2637 \lcir r:1 % circle
2638 \move (-1.05 0) \lvec ( 1.05 0) % axes
2639 \move (0 -1.05) \lvec (0 1.05)
2640
2641 \move (0 0) \lvec (0.707 0.707) \bdot
2642 \rmove (0.02 0.02) \textref h:L v:B \htext @{X@}
2643 \move (0.707 -0.707) \bdot
2644 \textref h:R v:T \htext(-0.02 -0.02)@{O@}
2645
2646 \move (0.5 0) % center of ellipse
2647 \bsegment
2648 \lellip rx:0.435 ry:0.804
2649 \bdot \Btext @{$\beta_2$@}
2650 \move (0 0.15) \Hlen @{0.435@}@{$|\beta_1@{+@}\beta_3|$@}
2651 \move (-0.7 0) \Vlen @{0.804@}@{$|\beta_1@{-@}\beta_3|$@}
2652 \esegment
2653 @}
2654 @end example
2655
2656
2657 @node Command Listing, Command Index, Examples, Top
2658 @appendix Alphabetic listing of commands
2659 @cindex listing of commands
2660
2661 @table @code
2662
2663 @item \arrowheadsize l:@var{length} w:@var{width}
2664 Set the arrowhead size to be @var{length} units long and @var{width}
2665 units wide. The width is measured across the ``base'' of the arrowhead.
2666 The initial arrowhead size has a @var{length} of 0.16 inches and a
2667 @var{width} of 0.08 inches.
2668
2669 @item \arrowheadtype t:@var{type}
2670 Set the arrowhead type to @var{type}, where @var{type} is one of
2671 @code{F}, @code{T}, @code{W}, @code{V}, or @code{H}. There are two
2672 kinds of arrowheads. The first kind is a triangle. There are 3
2673 variants: type @code{T} is an empty triangle, type @code{F} is a filled
2674 triangle (using the current gray level for lines), type @code{W} is a
2675 triangle filled with white. The second kind of arrowhead is an open
2676 ended Vee. There are 2 variants: type @code{V} has the stem continue to
2677 the tip, type @code{H} has the stem stop at the base of the arrowhead.
2678 The initial arrowhead type is @code{T}.
2679
2680 @item \avec (@var{x} @var{y})
2681 Draw a line with an arrowhead from the current position to
2682 @code{(@var{x} @var{y})}. The new current position is @code{(@var{x}
2683 @var{y})}. The arrowhead is aligned with the line, with the tip at
2684 @code{(@var{x} @var{y})}.
2685
2686 @item \begin@{texdraw@}
2687 Start a @TeX{}draw drawing. The drawing is terminated with an
2688 @code{\end@{texdraw@}} command. This command is for use with La@TeX{}.
2689
2690 @item \bsegment
2691 Start a drawing segment. The coordinate system is shifted such that the
2692 current position corresponds to the coordinate @code{(0 0)}. Changes to
2693 scaling, position and line parameters stay local to the drawing segment.
2694
2695 @item \btexdraw
2696 Start a @TeX{}draw drawing. The drawing is terminated with an
2697 @code{\etexdraw} command.
2698
2699 @item \centertexdraw @{ ... @}
2700 Center a @TeX{}draw box. The argument contains @TeX{}draw commands.
2701 The resulting box has the horizontal size @code{\hsize} and height equal
2702 to the height of the drawing.
2703
2704 @item \clvec (@var{x1} @var{y1})(@var{x2} @var{y2})(@var{x3} @var{y3})
2705 Draw a Bezier curve from the current position to the coordinate
2706 @code{(@var{x3} @var{y3})} which becomes the new current position. The
2707 coordinates @code{(@var{x1} @var{y1})} and @code{(@var{x2} @var{y2})}
2708 serve as control points for the curve. Only the last coordinate given
2709 is used to update the size of the drawing.
2710
2711 @item \drawbb
2712 Draw a ruled box around the effective size of a drawing produced by
2713 @TeX{}draw commands.
2714
2715 @item \drawdim @var{dim}
2716 Set the units to @var{dim}. The argument @var{dim} can be any valid
2717 @TeX{} dimension unit. The units are used to interpret coordinate
2718 values. Examples of valid units: @code{cm}, @code{mm}, @code{in},
2719 @code{pt}, and @code{bp}.
2720
2721 @item \end@{texdraw@}
2722 End a @TeX{}draw drawing started with a @code{\begin@{texdraw@}}
2723 command. The resulting @TeX{}draw drawing is placed in a box with
2724 height equal to the height of the drawing and width equal to the width
2725 of the drawing. The depth of the box is zero. This command is for use
2726 with La@TeX{}.
2727
2728 @item \esegment
2729 End a drawing segment. The current position in effect before the
2730 corresponding @code{\bsegment} command is restored. The scaling and
2731 line parameter values revert to those in effect before the corresponding
2732 @code{\bsegment} was invoked.
2733
2734 @item \etexdraw
2735 End a @TeX{}draw drawing started with a @code{\btexdraw} command. The
2736 resulting @TeX{}draw drawing is placed in a box with height equal to the
2737 height of the drawing and width equal to the width of the drawing. The
2738 depth of the box is zero.
2739
2740 @item \everytexdraw @{ ... @}
2741 Specify @TeX{}draw commands to be executed at the beginning of every
2742 @TeX{}draw drawing.
2743
2744 @item \fcir f:@var{level} r:@var{radius}
2745 Draw a filled circle with center at the current position. The radius is
2746 specified by @var{radius}. The circle is painted with the gray level
2747 specified by @var{level}. A gray level of 1 corresponds to white, with
2748 decreasing values getting darker. The level 0 is full black. This
2749 command does not draw a line along the circumference. The drawing size
2750 is increased if necessary to contain the circle.
2751
2752 @item \fellip f:@var{level} rx:@var{x-radius} ry:@var{y-radius}
2753 Draw a filled ellipse with center at the current position. The radius
2754 in the @var{x} direction is specified by @var{x-radius}. The radius in
2755 the @var{y} direction is specified by @var{y-radius}. The ellipse is
2756 painted with the gray level specified by @var{level}. A gray level of 1
2757 corresponds to white, with decreasing values getting darker. The level
2758 0 is full black. This command does not draw a line along the boundary
2759 of the ellipse. The drawing size is increased if necessary to contain
2760 the ellipse.
2761
2762 @item \htext (@var{x} @var{y})@{@var{text}@}
2763 @itemx \htext @{@var{text}@}
2764 The first form of this command places the @TeX{} text @var{text}
2765 horizontally with the text reference point at the coordinate
2766 @code{(@var{x} @var{y})}. The new current position is @code{(@var{x}
2767 @var{y})}. The second form of this command places the @TeX{} text
2768 @var{text} horizontally with the text reference point at the current
2769 position. The text reference point is set with the @code{\textref}
2770 command.
2771
2772 @item \ifill f:@var{level}
2773 Close the current path and paint the interior of the region with gray
2774 level @var{level}. The line around the path is not drawn. Gray levels
2775 are real values from 0 (black) through intermediate values (grays) to 1
2776 (white).
2777
2778 @item \larc r:@var{radius} sd:@var{start-angle} ed:@var{end-angle}
2779 Draw a counterclockwise arc. The center of the arc is at the current
2780 position. The radius is specified by @var{radius}. The start and end
2781 angles (in degrees) are specified by @var{start-angle} and
2782 @var{end-angle}. This command does not affect the limits (size) of the
2783 drawing.
2784
2785 @item \lcir r:@var{radius}
2786 Draw a circle with center at the current position. The radius is
2787 specified by @var{radius}. This command draws a line along the
2788 circumference of the circle. The drawing size is increased if necessary
2789 to contain the circle.
2790
2791 @item \lellip rx:@var{x-radius} ry:@var{y-radius}
2792 Draw an ellipse with center at the current position. The radius in the
2793 @var{x} direction is specified by @var{x-radius}. The radius in the
2794 @var{y} direction is specified by @var{y-radius}. The drawing size is
2795 increased if necessary to contain the ellipse.
2796
2797 @item \lfill f:@var{level}
2798
2799 Close the current path, draw the line around the path using the current
2800 grey level for lines and paint the interior of the region with specified
2801 gray level @var{level}. Gray levels are real values from 0 (black)
2802 through intermediate values (grays) to 1 (white).
2803
2804 @item \linewd @var{width}
2805 Set the line width to @var{width} units. Initially @var{width} is 0.01
2806 inches (corresponding to 3 pixels at 300 pixels to the inch).
2807
2808 @item \lpatt (@var{pattern})
2809 Set lines to have the pattern @code{(@var{pattern})}. A pattern is a
2810 sequence of on/off lengths separated by blanks and enclosed in parentheses.
2811 The lengths alternately specify the length of a dash and the length of a
2812 gap between dashes. Each length is interpreted using the current
2813 scaling and drawing units. The pattern is used cyclically. The empty
2814 pattern signifies a solid line. The initial line pattern is a solid
2815 line, corresponding to the empty pattern @code{\lpatt ()}.
2816
2817 @item \lvec (@var{x} @var{y})
2818 Draw a line from the current position to coordinate @code{(@var{x}
2819 @var{y})}. The new current position is @code{(@var{x} @var{y})}.
2820
2821 @item \move (@var{x} @var{y})
2822 Move to coordinate @code{(@var{x} @var{y})}. The new current position
2823 is @code{(@var{x} @var{y})}.
2824
2825 @item \ravec (@var{dx} @var{dy})
2826 Draw a line with an arrowhead from the current position, @var{dx} units
2827 in the @var{x} direction and @var{y} units in the @var{y} direction.
2828 The final position becomes the new current position. The arrowhead is
2829 aligned with the line, with the tip at the new current position.
2830
2831 @item \relsegscale @var{value}
2832 Adjust the segment scale factor by multiplying by @var{value}. This has
2833 the effect of multiplying the current overall scale factor by the same
2834 factor. The overall scaling factor is the product of the unit scale
2835 factor and the segment scale factor.
2836
2837 @item \relunitscale @var{value}
2838 Adjust the unit scale factor by multiplying by @var{value}. This has
2839 the effect of multiplying the overall scale factor by the same factor.
2840 The overall scaling factor is the product of the unit scale factor and
2841 the segment scale factor.
2842
2843 @item \rlvec (@var{dx} @var{dy})
2844 Draw a line from the current position, @var{dx} units in the @var{x}
2845 direction and @var{dy} units in the @var{y} direction. The final
2846 position becomes the new current position.
2847
2848 @item \rmove (@var{dx} @var{dy})
2849 Move from the current position, @var{dx} units in the @var{x} direction
2850 and @var{dy} units in the @var{y} direction. The final position becomes
2851 the new current position.
2852
2853 @item \rtext td:@var{angle} (x y)@{@var{text}@}
2854 @itemx \rtext td:@var{angle} @{@var{text}@}
2855 The first form of this command places the @TeX{} text @var{text} at an
2856 angle with the text reference point at the coordinate @code{(@var{x}
2857 @var{y})}. The new current position is @code{(@var{x} @var{y})}. The
2858 second form of this command places the @TeX{} text @var{text} at an
2859 angle with the text reference point at the current position. In both
2860 cases, the @TeX{} text is placed in a box and the box is rotated
2861 counterclockwise by @var{angle} degrees about the text reference point.
2862 The text reference point is set with the @code{\textref} command.
2863
2864 @item \savecurrpos (*@var{px} *@var{py})
2865 Save the current position as the absolute position referenced by
2866 @code{(*@var{px} *@var{py})}.
2867
2868 @item \savepos (@var{x} @var{y})(*@var{px} *@var{py})
2869 Save the coordinate position @code{(@var{x} @var{y})} as the absolute
2870 position referenced by @code{(*@var{px} *@var{py})}. The coordinate
2871 @code{(@var{x} @var{y})} is interpreted in the normal fashion as a
2872 coordinate relative to the current segment, using the current scaling
2873 factors and drawing unit.
2874
2875 @item \setgray @var{level}
2876 Set the gray level of lines. Gray levels are real values from 0 (black)
2877 through intermediate values (gray) to 1 (white). The initial gray level
2878 is 0 corresponding to black.
2879
2880 @item \setsegscale @var{scale}
2881 Set the segment scale factor. The argument @var{scale} is a real number
2882 which is used to scale coordinate values. The overall scale factor is
2883 the product of the unit scale factor and the segment scale factor.
2884
2885 @item \setunitscale @var{scale}
2886 Set the unit scaling to @var{scale}. The argument @var{scale} is a real
2887 number which is used to scale coordinate values. The overall scaling
2888 factor is the product of the unit scale factor and the segment scale
2889 factor.
2890
2891 @item \textref h:@var{h-ref} v:@var{v-ref}
2892 Set the text reference point for subsequent text commands. The
2893 horizontal reference point @var{h-ref} is one of @code{L}, @code{C} or
2894 @code{R} (left, center or right). The vertical reference point
2895 @var{v-ref} is one of @code{T}, @code{C} or @code{B} (top, center or
2896 bottom). For rotated text, the reference point is determined before
2897 rotation. The initial text reference point corresponds to
2898 @code{\textref h:L v:B}.
2899
2900 @item \vtext (x y)@{@var{text}@}
2901 @itemx \vtext @{@var{text}@}
2902 The first form of this command places the @TeX{} text @var{text}
2903 vertically with the text reference point at the coordinate
2904 @code{(@var{x} @var{y})}. The new current position is @code{(@var{x}
2905 @var{y})}. The second form of this command places the @TeX{} text
2906 @var{text} vertically with the text reference point at the current
2907 position. In both cases, the @TeX{} text is placed in a box and the box
2908 is rotated counterclockwise by 90 degrees about the text reference
2909 point. The text reference point is set with the @code{\textref}
2910 command.
2911
2912 @end table
2913
2914 @node Command Index, Concept Index, Command Listing, Top
2915 @unnumbered Command Index
2916 @printindex fn
2917
2918 @node Concept Index, , Command Index, Top
2919 @unnumbered Concept Index
2920 @printindex cp
2921
2922 @bye