Debian Codegraph @

texmf-dist/doc/man/man1/mathspic.1

raw
1 .\" copyright (c) 2010 A Syropoulos and RWD Nickalls
2 .\" mathspic.1
3 .\" place this file in: /usr/share/man/man1/
4 ..
5 .TH mathsPIC 1 "April 26, 2010" "mathsPIC perl version"
6 .SH NAME
7 .B mathsPIC
8 .SH AUTHORS
9 A. Syropoulos and R.W.D. Nickalls (April 26, 2010)
10
11 asyropoulos[at]<yahoo><com>
12 dick[at]<nickalls><org>
13
14 .SH DESCRIPTION
15 .B mathsPIC
16 is a Perl filter program for PiCTeX. mathsPIC has its own macro and macro library capability, and allows use of mathsPIC, PiCTeX, TeX and LaTeX commands. A significant feature of mathsPIC is that it allows access to the command-line, and so allows the user to extend mathsPIC commands by calling Perl and other programs written to perform particular drawing actions. See the package manual for full details and examples. The latest version can be downloaded from
17 .PP
18 CTAN: tex-archive/graphics/pictex/mathspic/perl
19 .PP
20 Commands which can be used in the mathsPIC script file fall into four main groups (a) mathsPIC macro commands (prefixed with %def), (b) regular mathsPIC commands (do not have a backslash), (c) regular PiCTeX commands (all have a backslash), and (d) regular TeX and LaTeX commands (all have a backslash).
21 .PP
22 The following mathematics functions can used (note that decimal fractions having an absolute value less than 1 must have a leading zero). Note also that all the trignometric functions require their argument in radians.
23
24 Trigonometric: sin(), cos(), tan(), asin(), acos(), atan()
25
26 Remainder: rem(); eg var r=12 rem(5)
27
28 Integer: int(); eg var r= int(3.87) --> 3
29
30 Sign (returns -1, 0, +1): sgn(); eg var s=sgn(-3.27) --> -1
31
32 Square root: sqrt(); eg var s = sqrt(14)
33
34 Exponentiation: **; eg var j = r**2
35
36 Pi constant (3.14159...): _Pi_ and _pi_
37
38 e constant (2.71828...): _E_ and _e_
39
40 Linethickness: _linethickness_ ; eg var t = _linethickness_
41
42 .SH COMMAND-LINE USE
43 perl mathspic.pl [-b] [-c] [-h] [-o <outfile>] <infile>
44
45 .B -b
46 enables beep if mathsPIC detects an error
47
48 .B -c
49 disables the writing of comments to output file
50
51 .B -h
52 displays the help file
53
54 .B -o
55 defines the output file name
56 .SH MACRO COMMANDS
57 macro definition commands are prefixed with %def and can take either 0, 1, or more parameters. Macros will generally be used as part of a
58 .B var
59 command as shown below. Macros are deleted using the
60 .B %undef
61 command.
62
63 -----syntax:
64 %def MACRONAME(parameters)<macrodefinition>
65 %undef MACRONAME(parameters)
66
67 -----notes:
68 Notes: (a) the () must be used in the definition even if no parameters are used, (b) the name can be any combination of upper and lower case characters and numbers, (c) when the macro is used in a command it is prefixed by a & symbol, (d) it is a good idea to always place a % symbol at the end of the definition, (e) comments (prefixed by a % symbol) can be placed after the macro definition just as in TeX or LaTeX.
69
70 -----examples:
71 %def d2r()_pi_/180% % degrees2radians
72 %def AreaOfRectangle(x,y)x*y% % width x, length y
73 %undef d2r() % delete the macro
74
75 -----use:
76 var j2= 6*(&d2r(45) + 23)
77 var a3 = 3*&AreaOfRectangle(5,7)
78 .SH GENERAL COMMANDS
79
80 .P
81 .B NUMERICAL EXPRESSIONS
82 When dealing with commands we will refer frequently to the term `numerical expression' by which is meant either (a) a number (integer or decimal), (b) a numeric variable or constant (defined using the var or const command), (c) any mathsPIC function, macro, or mathematical expression which evaluates to a number, or (d) a pair of point names (e.g. AB) representing the Pythagorean distance between the two points. A leading zero must be used with decimal fractions less than one.
83
84 In general, if a command's argument accepts a number then it will also accept a `numerical expression' (<expr>) as defined above. Sometimes a following <unit> is associated with the number or numerical expression, in which case the number or numerical expression can be delimited by a round bracket (or separated from the unit by a <space>), as shown in the following examples.
85
86 -----examples:
87 ArrowShape(3mm, 20,40)
88 var h=4
89 ArrowShape(h mm, 20, 40)
90 ArrowShape((2*h)mm,20,40)
91
92 .P
93 .B BACKSLASH
94 \\
95 A leading backslash without a following space indicates that it is part of a PiCTeX, TeX or LaTeX command, in which case mathsPIC simply copies the whole line verbatim into the output file. A leading backslash followed by one or more spaces makes mathsPIC copy the whole line verbatim into the output file but without the backslash.
96
97 .P
98 .B USING THE COLOR PACKAGE
99 The standard COLOR package can be used with mathsPIC, but note that it is important to load the COLOR package after the mathsPIC package.
100
101 It is best to place a comment symbol % at the end of LaTeX and TeX commands to limit white space at the end.
102
103 In the event of any colour-spill from a diagram into any following text (this used to be a problem in early TeX implementations) consider using the \\normalcolor command as a delimiter within the \\beginpicture...\\endpicture environment.
104
105 ==============================
106
107 .B ARROWSHAPE
108 This command defines the shape of an arrowhead, and allows
109 different arrowheads to be customised.
110
111 The default arrow shape is equivalent to the Arrowshape(2mm,30,40) command.
112 This default arrowhead shape can be reset using the Arrowshape(default) command, as shown in the following example.
113
114 -----syntax:
115 arrowshape(<length>[units], <angledeg>, <angledeg>)
116
117 -----examples:
118 Arrowshape(4mm,30,60)
119 drawArrow(AB)
120 Arrowshape(default)
121
122 ==============================
123
124 .B beginLOOP...endLOOP
125 This is an environment which cycles a block of code a specified number of times.
126
127 -----syntax:
128 beginLoop <expr>
129 ...
130 endLoop
131
132 -----notes:
133 The block of code which lies within the environment is input <expr> times.
134
135 -----example:
136 beginLoop 5
137 ...
138 endLoop
139
140
141 ==============================
142
143 .B beginSKIP...endSKIP
144 This is an `environment' within which commands are not actioned. It is useful in development for testing isolated commands and excluding other commands.
145
146 ==============================
147
148 .B CONST
149 The const command is used to define scalar constants. Note that a constant-name must begin with a single letter (either upper or lower case), and may have up to a maximum of three following digits. Note that constants, variables and points have the same name structure, and a constant could have the same name as a point (and so we suggest points have uppercase letters and variables and constants have lowercase letters). The scalar argument can be any numeric expression. New values cannot be re-allocated to existing constant-names. If this occurs mathsPIC will issue an error message.
150
151 -----syntax:
152 const name = <expr>
153
154 -----examples:
155 const r = 20, r4 = r3*tan(0.3)
156
157 ==============================
158
159 .B DashArray
160 The dasharray command takes an arbitrary number of paired arguments that are used to specify a dash pattern.
161
162 -----syntax
163 dasharray(d1 , g1 , d2 , g2 , ... )
164
165 -----notes
166 The ds denotes the length of a dash and the gs denotes the length of the gap between two consecutive dashes. There must be an even number of arguments. If a variable or expression is used then it should be separated from the unit either by a <space> or with round brackets ( ) as shown below.
167
168 -----example
169 dasharray(6pt, 2pt, 1pt, 2pt)
170 var d=2
171 dasharray(6pt, 2pt, 1pt, d pt)
172 dasharray(6pt, 2pt, 1pt, (d)pt)
173 dasharray(6pt, 2pt, 1pt, (3*d)pt)
174
175 ==============================
176
177 .B DrawAngleArc
178 This command draws an arc in the specified angle, a distance <radius> from the angle. The angle is either <internal> (less than 180 deg) or <external> (greater than 180 deg). The direction of the arc is either <clockwise> or <anticlockwise>, and this direction must correspond with the letter sequence specified for the angle.
179 Strange and unexpected results will be produced if the four parameters are not internally consistent. The option order angle/radius/internal or external/clockwise or anticlockwise is important. The <radius> parameter can be any numerical expression.
180
181 -----syntax:
182 DrawAngleArc{angle(), radius(), external, clockwise}
183
184 -----example:
185 DrawAngleArc{angle(ABC), radius(3), external, clockwise}
186 var r=3
187 DrawAngleArc{angle(ABC), radius(r), external, clockwise}
188
189 ==============================
190
191 .B DrawAngleArrow
192 This command draws a curved arrow in the specified angle, a distance <radius> from the angle. The angle is either <internal> (less than 180 deg) or <external> (greater than 180 deg). The direction of the arrow is either <clockwise> or <anticlockwise>, and this direction must correspond with the letter sequence specified for the angle.
193 Strange and unexpected results will be produced if the four parameters are not internally consistent. The option order angle/radius/internal/clockwise is important. The <radius> parameter can be any numerical expression.
194
195 -----syntax:
196 DrawAngleArrow{angle(), radius(), external, clockwise}
197
198 -----example:
199 DrawAngleArrow{angle(ABC), radius(3), external, clockwise}
200 var r=3
201 DrawAngleArrow{angle(ABC), radius(r), external, clockwise}
202
203 ==============================
204
205 .B DrawArrow
206 This command draws an arrow(s) joining two points. The direction of the arrow is in the point order specified.
207
208 -----syntax:
209 drawArrow(<line> [,<line>] ... )
210
211 -----notes:
212 The length option can only refer to one arrow
213
214 -----example:
215 drawArrow(AB)
216 drawArrow(FG, HJ)
217
218 ==============================
219
220 .B DrawCircle
221 This command draws a circle defined by its radius and the point-name of its centre. The <radius> can be any numerical expression. If the units of the X and Y axes are different, circles may be drawn strangely, and mathsPIC therefore generates a warning message to this effect.
222
223 -----syntax:
224 DrawCircle(<center>, <radius>)
225
226 -----examples:
227 drawCircle(C2,5)
228 drawCircle(C2,r2)
229 drawCircle(C2,r2/tan(1.3))
230 drawCircle(C2,AB)
231
232 ==============================
233
234 .B DrawCircumcircle
235 This command draws the circumcircle of a triangle.
236
237 -----syntax:
238 DrawCircumcircle(<triangle>)
239
240 -----example:
241 drawCircumcircle(ABC)
242
243 ==============================
244
245 .B DrawCurve
246 This command draws a smooth quadratic curve through three points in the point order specified. Note that curves drawn using this command do not break to avoid line-free zones associated with the points.
247
248 -----syntax:
249 DrawCurve(<point><point><point>)
250
251 -----example:
252 drawCurve(ABC)
253
254 ==============================
255
256 .B DrawExcircle
257 This command draws the excircle touching one side of a triangle.
258
259 -----syntax:
260 DrawExcircle(<triangle>, <side>)
261
262 -----example:
263 drawExcircle(ABC, BC)
264
265 ==============================
266
267 .B DrawIncircle
268 This command draws the incircle of a triangle.
269
270 -----syntax:
271 DrawIncircle(<triangle>)
272
273 -----example:
274 drawIncircle(ABC)
275
276 ==============================
277
278 .B DrawLine
279 This command draws a line joining two or more points. Use the Linethickness command to vary thickness. This command uses the PiCTeX \\putrule command for horizontal and vertical lines, and the \\plot command for all other orientations.
280
281 -----syntax:
282 DrawLine( <points> [, <points>] )
283
284 -----notes:
285 <points> is any sequence of two or more point names.
286 <expr> is any numerical expression.
287 Lines are drawn in the order specified.
288 Lines are separated by a comma.
289
290 -----examples:
291 drawline(AB)
292 drawline(BCDE)
293 drawline(FG, HJK, PQRST)
294
295 ==============================
296
297 .B DrawPerpendicular
298 This command draws the perpendicular from a point to a line.
299
300 -----syntax:
301 DrawPerpendicular(<point>, <line)
302
303 -----example:
304 drawPerpendicular(P,AB)
305
306 ==============================
307
308 .B DrawPoint
309 This command draws the point-symbol at the point-location. Commas must not be used to separate point names. The default point-symbol is \$\\bullet\$, unless an optional point-symbol (or string of characters) is specified in the associated point command.
310
311 -----syntax:
312 DrawPoint(<point> [<point> ..])
313
314 -----examples:
315 drawpoint(T4)
316 drawpoint(ABCDEF)
317 drawpoint(P1 P2 P3 P4)
318
319 ==============================
320
321 .B DrawRightangle
322 This command draws the standard right-angle symbol in the internal angle specified at the size specified by <expr>.
323
324 -----syntax:
325 DrawRightangle(<angle>, <expr>)
326
327 -----notes:
328 The <expr> can be any numerical expression.
329
330 -----example:
331 drawRightangle(ABC,3)
332 drawRightangle(ABC,PQ)
333 var d=5
334 drawRightangle(ABC,d)
335
336 ==============================
337
338 .B DrawSquare
339 This command draws a square defined by its side and the point-name of its centre. The <sidelength> can be any numerical expression.
340
341 -----syntax:
342 DrawSquare(<centerpoint>, <sidelength>)
343
344 -----examples:
345 drawSquare(P,5)
346 var s2=3, j=2
347 drawSquare(P,s2)
348 drawSquare(P, s2*4/(3*j))
349 drawSquare(P,AB)
350
351 ==============================
352
353 .B DrawThickArrow
354 This command draws a thick arrow(s) joining two points. The direction of the arrow is in the point order specified. The shape of the arrowhead is controlled by the ArrowShape command.
355
356 -----syntax:
357 drawThickArrow(<line> [,<line>,...])
358
359 -----examples:
360 drawThickarrow(BC)
361 drawThickarrow(PQ, RS)
362
363 ==============================
364
365 .B DrawThickLine
366 This command draws a thick line(s) joining two points. The direction of the line is in the point order specified. Use the Linethickness command to vary thickness of a line.
367
368 -----syntax:
369 drawThickLine(<line> [,<line>,...])
370
371 -----examples:
372 drawThickline(BC)
373 drawThickline(PQ, RS)
374
375 ==============================
376
377 .B InputFile
378 This command inputs a plain text file containing mathsPIC commands. Optionally, the file can be input several times, in which case this command functions like a DO--LOOP.
379 The <loopnumber> can be any numerical expression. If the <loopnumber> is not an integer then mathsPIC will round the value down to the nearest integer. See also the beginLOOP ... endLOOP commands.
380
381 -----syntax:
382 inputFile[*](<filename>)[<loopnumber>]
383
384 -----notes:
385 The inputfile* command is used to input a file in verbatim, i.e. a file with no mathsPIC commands, for example, a file containing only PiCTeX commands or data-points
386 for plotting etc. Note that the inputfile* command has no <loopnumber> option. Note also that PiCTeX requires a ODD number of points.
387
388 -----examples:
389 inputFile(myfile.dat)[4]
390 inputFile*(mycurvedata.dat)
391
392 ==============================
393
394 .B LineThickness
395 This command sets a particular linethickness. The command linethickness(default) restores the working linethickness to the default value of 0.4pt.
396 The current value of the linethickness (in current units) can be accessed using the var command (this can be useful when drawing figures using thick lines) .
397
398 -----syntax:
399 LineThickness(<expr><units>)
400 LineThickness(default)
401 var t = _linethickness_
402
403 -----notes:
404 This command also sets the font to cmr and plotsymbol to \\CM . and also sets the rule thickness for drawing horizontal and vertical lines. It is important to include a leading zero with decimal fractions less than one.
405
406 -----examples:
407 linethickness(2pt)
408 var t=3
409 linethickness((t)pt)
410 lineThickness((2*t)pt)
411 linethickness(default)
412 var t = _linethickness_
413
414 -----caution:
415 Note that there is a similar PiCTeX command with the same name (but with a different syntax).
416
417 ==============================
418
419 .B PAPER
420 Defines the plotting area in terms of the options units(), xrange(), yrange(), axes(), and ticks(). The units() argument must contain a numeric value and a valid TeX length unit mm, cm, pt, pc(pica), in(inch), bp(big point), dd(didot), cc(cicero), sp(scaled point). The X and Y axes can have different units (see second example below). The axes() arguments XYTBLR refer to the X and Y axes, and the Top, Bottom, Left and Right axes. A * following one of the axes disables ticks on that axis. The X and Y axes pass through the zeros.
421
422 -----examples:
423 paper{units(1cm),xrange(0,10),yrange(0,10)}
424 paper{units(2cm,1cm),xrange(0,10),yrange(0,10),axes(LB)}
425 paper{units(1mm),xrange(0,100),yrange(0,100),axes(XY)}
426 paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRTBXY),ticks(1,1)}
427 paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRT*B*)}
428
429 ==============================
430
431 .B POINT
432 Defines a new point by allocating coordinates to a new point name. The * option re-allocates coordinates to an existing point name.
433
434 -----syntax:
435 POINT[*](<name>){<point>}[symbol=<chars>, radius=<expr>]
436 POINT[*](<name>){<location>}[symbol=<chars>, radius=<expr>]
437
438 -----notes:
439 <name> one leading letter plus maximum of three trailing digits
440 <chars> any TeX string allowed in an \\hbox{}
441 <expr> any numerical expression
442 The polar(r,theta) option defaults to radians for the angle theta. To work in degrees then must append <deg> eg: polar(r,theta deg). Can use <direction()> and <directiondeg()> to replace theta. Note that the term vector(AB) means use same (r, theta) as AB.
443
444 -----examples:
445 point(A){5,5}
446 point(B2){22,46}[symbol=$\\odot$]
447 point(B2){22,46}[symbol=circle(2),radius=5]
448 var r=3
449 point(B2){22,46}[symbol=square(3),radius=r]
450 point(B123){22,46}[radius=5]
451 point(D2){B2, shift(5,5)}
452 var s = 3
453 point(D2){B2, shift(2*s,4*s)}
454 point(D3){D2, polar(6,32 deg)}
455 point(D4){D2, polar(6,1.2 rad)}
456 point(D4){D2, polar(6, direction(AB))} %% radians by default
457 point(D4){D2, polar(6, directiondeg(AB) deg)}
458 point(G2){Q, rotate(P, 23 deg)}
459 point(G2){Q, vector(AB)}
460 point(D2){intersection(AB,CD)}
461 point(F){PointOnLine(AB,5.3)}
462 point(G){perpendicular(P,AB)}
463 point(H){circumcircleCenter(ABC)}
464 point(J){incircleCenter(ABC)}
465 point(K){excircleCenter(ABC,BC)}
466 point*(A){6,3}
467 point*(P){Q}
468 point*(B){B, shift(5,0)}
469 point*(P){xcoord(J),ycoord(K)}
470
471 ==============================
472
473 .B PointSymbol
474 This command allows the default point-symbol \\bullet (with zero line-free radius) to be changed. The PointSymbol command is particularly useful where a set of points uses the same point-symbol, for example, when drawing graphs. The point-symbol can be reset to the default \\bullet using the command PointSymbol(default).
475
476 -----syntax:
477 PointSymbol(<symbol>, <line-free-radius>)
478 PointSymbol(default)
479
480 -----notes:
481 The PointSymbol command only influences subsequent point commands.
482 The optional square bracket of the point command overrides the PointSymbol command.
483
484 -----examples:
485 PointSymbol($\\odot$, 0.7)
486 PointSymbol(default)
487
488 ==============================
489
490 .B SYSTEM
491 This command allows the user to access the command line and execute standard Linux commands. A important use for this command is to run a Perl program.
492
493 -----syntax:
494 System("<command>")
495
496 -----notes:
497 The <command> string must be in inverted commas.
498
499 -----example:
500 system("dir > mydir-listing.txt")
501 system("perl myperlprogram.pl")
502
503 ==============================
504
505 .B SHOW....
506 This command makes mathsPIC return the value of a calculation or specified parameter; for example, the value of a particular angle, or the length of a line. The result is shown in the output-file as a commented line. This allows mathsPIC commands to be adjusted in the light of calculations. There are currently five such commands as follows.
507
508 -----syntax:
509 showLength(AB)
510 showAngle(ABC) % returns angle in radians
511 showAngledeg(ABC) % returns angle in degrees
512 showArea(ABC)
513 showPoints
514 showVariables
515
516 ==============================
517
518 .B TEXT
519 This command places a text-string at a specific location. By default the text is centered vertically and horizontally at the specified point. Optionally, text can be placed relative to a point using appropriate combinations of the PiCTeX `position' options l t r B b to align the (l)eft edge, (r)ight edge, (t)op edge, (B)aseline, (b)ottom edge respectively of the text box with the point-location.
520
521 Remember that the default units for the angle argument of the polar() expression is radians; hence you MUST append `deg' if you want to work in degrees
522
523 -----syntax:
524 text(<string>){<location>}[<position options>]
525 text(<string>){<pointname>, shift(<x>,<y>)}[]
526 text(<string>){<pointname>, polar(<r>,<angle>[rad])}[]
527
528 -----examples:
529 text(A){5,6}
530 text($A_1$){A1, shift(2, 2)}
531 text(Z2){Z2, shift(5, -5)}[tr]
532 text(Z3){Z2, polar(5, 20 deg)}[Br]
533 text(Z4){Z2, polar(5, 1.34 rad)}
534 text(\\framebox{Z5}){Z5}
535
536 ==============================
537
538 .B VAR
539 The var command is used to define scalar variables. It can be any numerical expression. A variable-name must begin with a single letter (either upper or lower case), and may have up to a maximum of four following digits. If a more detailed variable name is required, then a simple alternative is to use a mathsPIC macro---as any string can be allocated via macros (see the beginning of this chapter for details on macros).
540
541 Note that variables, constants and points have the same name structure, and a variable can have the same name as a point (and so we suggest points have uppercase letters and variables and constants have lowercase letters). New values can be re-allocated to existing variable-names; however, when this occurs then mathsPIC does not issue a warning message to hightlight this fact.
542
543 If it is important to be warned if a potential variable is accidentally reallocated then one should consider using the const command instead (since mathsPIC does generate an error message if a constant is reallocated).
544
545 -----syntax:
546 var <name> = <expr>
547
548 -----notes:
549 In addition to the mathematical functions mathsPIC functions which can be used with the var command are:
550
551 angle(<three-points>) % returns angle in radians
552 angledeg(<three-points>) % returns angle in degrees
553 area(<three-points>)
554 xcoord(<point>)
555 ycoord(<point>)
556 direction(<two-points>) % returns angular direction in radians
557 directiondeg(<two-points>) % returns angular direction in degrees
558
559 -----examples:
560 var r = 20, r4 = r3*tan(0.3), j = (r*2e3)**2, r5 = AB
561 var e = _e_, p1 = _Pi_
562 var t = _linethickness_ % returns linethickness in current units
563 var g137 = angle(ABC) %(default: returns in radians)
564 var g = angledeg(ABC) % angle in degrees
565 var h = area(ABC)
566 var x2 = xcoord(A), y2 = ycoord(A)
567 var m5 = 12 rem 3 % remainder after dividing by 3
568 var r1 = direction(PQ) % in radians
569 var d1 = directiondeg(PQ)
570
571 ==============================
572 .SH SEE ALSO
573 The mathsPIC package manual and examples
574 .SH BUGS
575 Please report bugs to Dick Nickalls (dick [AT] nickalls [dot] org) or to Apostolos Syropoulos
576