Debian Codegraph @

texmf-dist/doc/latex/mathspic/HELP.txt

raw
1
2
3 HELP.txt
4
5 A .txt version of the Linux manpage (for use with MS-Windows)
6
7 copyright (c) 2010 A Syropoulos and RWD Nickalls
8 mathsPIC 1.13 April 26, 2010 mathsPIC perl version
9
10 NAME: mathsPIC
11
12 AUTHORS: A. Syropoulos and R.W.D. Nickalls (April 26, 2010)
13
14 asyropoulos[at]<yahoo><com>
15 dick[at]<nickalls><org>
16
17 DESCRIPTION
18 -----------
19 mathsPIC 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
20
21 CTAN: tex-archive/graphics/pictex/mathspic/perl
22
23 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).
24
25
26 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.
27
28 Trigonometric: sin(), cos(), tan(), asin(), acos(), atan()
29 Remainder: rem(); eg var r=12 rem(5)
30 Integer: int(); eg var r= int(3.87) --> 3
31 Sign (returns -1, 0, +1): sgn(); eg var s=sgn(-3.27) --> -1
32 Square root: sqrt(); eg var s = sqrt(14)
33 Exponentiation: **; eg var j = r**2
34 Pi constant (3.14159...): _Pi_ and _pi_
35 e constant (2.71828...): _E_ and _e_
36 Linethickness: _linethickness_ ; eg var t = _linethickness_
37
38 COMMAND-LINE USE
39 -----------------
40
41 perl mathspic.pl [-b] [-c] [-h] [-o <outfile>] <infile>
42 -b enables beep if mathsPIC detects an error
43 -c disables the writing of comments to output file
44 -h displays the help file
45 -o defines the output file name
46
47
48 MACRO COMMANDS
49 --------------
50 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 var command as shown below. Macros are deleted using the %undef command.
51
52 -----syntax:
53 %def MACRONAME(parameters)<macrodefinition>
54 %undef MACRONAME(parameters)
55
56 -----notes:
57 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.
58
59 -----examples:
60 %def d2r()_pi_/180% % degrees2radians
61 %def AreaOfRectangle(x,y)x*y% % width x, length y
62 %undef d2r() % delete the macro
63
64 -----use:
65 var j2= 6*(&d2r(45) + 23)
66 var a3 = 3*&AreaOfRectangle(5,7)
67
68 GENERAL COMMANDS
69 ----------------
70
71 NUMERICAL EXPRESSIONS
72 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.
73
74 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.
75
76 -----examples:
77 ArrowShape(3mm, 20,40)
78 var h=4
79 ArrowShape(h mm, 20, 40)
80 ArrowShape((2*h)mm,20,40)
81
82 =============================
83
84 BACKSLASH \
85
86 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.
87
88 =============================
89
90 USING THE COLOR PACKAGE
91
92 The standard COLOR package can be used with mathsPIC, but note that it is important to load the COLOR package after the mathsPIC package.
93
94 It is best to place a comment symbol % at the end of LaTeX and TeX commands to limit white space at the end.
95
96 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.
97
98 ==============================
99
100 ARROWSHAPE
101
102 This command defines the shape of an arrowhead, and allows
103 different arrowheads to be customised.
104
105 The default arrow shape is equivalent to the Arrowshape(2mm,30,40) command.
106 This default arrowhead shape can be reset using the Arrowshape(default) command, as shown in the following example.
107
108 -----syntax:
109 arrowshape(<length>[units], <angledeg>, <angledeg>)
110
111 -----examples:
112 Arrowshape(4mm,30,60)
113 drawArrow(AB)
114 Arrowshape(default)
115
116 ==============================
117
118 beginLOOP...endLOOP
119
120 This is an environment which cycles a block of code a specified number of times.
121
122 -----syntax:
123 beginLoop <expr>
124 ...
125 endLoop
126
127 -----notes:
128 The block of code which lies within the environment is input <expr> times.
129
130 -----example:
131 beginLoop 5
132 ...
133 endLoop
134
135
136 ==============================
137
138 beginSKIP...endSKIP
139
140 This is an `environment' within which commands are not actioned. It is useful in development for testing isolated commands and excluding other commands.
141
142 ==============================
143
144 CONST
145
146 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.
147
148 -----syntax:
149 const name = <expr>
150
151 -----examples:
152 const r = 20, r4 = r3*tan(0.3)
153
154 ==============================
155
156 DashArray
157
158 The dasharray command takes an arbitrary number of paired arguments that are used to specify a dash pattern.
159
160 -----syntax
161 dasharray(d1 , g1 , d2 , g2 , ... )
162
163 -----notes
164 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.
165
166 -----example
167 dasharray(6pt, 2pt, 1pt, 2pt)
168 var d=2
169 dasharray(6pt, 2pt, 1pt, d pt)
170 dasharray(6pt, 2pt, 1pt, (d)pt)
171 dasharray(6pt, 2pt, 1pt, (3*d)pt)
172
173 ==============================
174
175 DrawAngleArc
176
177 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.
178 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.
179
180 -----syntax:
181 DrawAngleArc{angle(), radius(), external, clockwise}
182
183 -----example:
184 DrawAngleArc{angle(ABC), radius(3), external, clockwise}
185 var r=3
186 DrawAngleArc{angle(ABC), radius(r), external, clockwise}
187
188 ==============================
189
190 DrawAngleArrow
191
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 DrawArrow
206
207 This command draws an arrow(s) joining two points. The direction of the arrow is in the point order specified.
208
209 -----syntax:
210 drawArrow(<line> [,<line>] ... )
211
212 -----notes:
213 The length option can only refer to one arrow
214
215 -----example:
216 drawArrow(AB)
217 drawArrow(FG, HJ)
218
219 ==============================
220
221 DrawCircle
222
223 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.
224
225 -----syntax:
226 DrawCircle(<center>, <radius>)
227
228 -----examples:
229 drawCircle(C2,5)
230 drawCircle(C2,r2)
231 drawCircle(C2,r2/tan(1.3))
232 drawCircle(C2,AB)
233
234 ==============================
235
236 DrawCircumcircle
237
238 This command draws the circumcircle of a triangle.
239
240 -----syntax:
241 DrawCircumcircle(<triangle>)
242
243 -----example:
244 drawCircumcircle(ABC)
245
246 ==============================
247
248 DrawCurve
249
250 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.
251
252 -----syntax:
253 DrawCurve(<point><point><point>)
254
255 -----example:
256 drawCurve(ABC)
257
258 ==============================
259
260 DrawExcircle
261
262 This command draws the excircle touching one side of a triangle.
263
264 -----syntax:
265 DrawExcircle(<triangle>, <side>)
266
267 -----example:
268 drawExcircle(ABC, BC)
269
270 ==============================
271
272 DrawIncircle
273
274 This command draws the incircle of a triangle.
275
276 -----syntax:
277 DrawIncircle(<triangle>)
278
279 -----example:
280 drawIncircle(ABC)
281
282 ==============================
283
284 DrawLine
285
286 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.
287
288 -----syntax:
289 DrawLine( <points> [, <points>] )
290
291 -----notes:
292 <points> is any sequence of two or more point names.
293 <expr> is any numerical expression.
294 Lines are drawn in the order specified.
295 Lines are separated by a comma.
296
297 -----examples:
298 drawline(AB)
299 drawline(BCDE)
300 drawline(FG, HJK, PQRST)
301
302 ==============================
303
304 DrawPerpendicular
305
306 This command draws the perpendicular from a point to a line.
307
308 -----syntax:
309 DrawPerpendicular(<point>, <line)
310
311 -----example:
312 drawPerpendicular(P,AB)
313
314 ==============================
315
316 DrawPoint
317
318 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.
319
320 -----syntax:
321 DrawPoint(<point> [<point> ..])
322
323 -----examples:
324 drawpoint(T4)
325 drawpoint(ABCDEF)
326 drawpoint(P1 P2 P3 P4)
327
328 ==============================
329
330 DrawRightangle
331
332 This command draws the standard right-angle symbol in the internal angle specified at the size specified by <expr>.
333
334 -----syntax:
335 DrawRightangle(<angle>, <expr>)
336
337 -----notes:
338 The <expr> can be any numerical expression.
339
340 -----example:
341 drawRightangle(ABC,3)
342 drawRightangle(ABC,PQ)
343 var d=5
344 drawRightangle(ABC,d)
345
346 ==============================
347
348 DrawSquare
349
350 This command draws a square defined by its side and the point-name of its centre. The <sidelength> can be any numerical expression.
351
352 -----syntax:
353 DrawSquare(<centerpoint>, <sidelength>)
354
355 -----examples:
356 drawSquare(P,5)
357 var s2=3, j=2
358 drawSquare(P,s2)
359 drawSquare(P, s2*4/(3*j))
360 drawSquare(P,AB)
361
362 ==============================
363
364 DrawThickArrow
365
366 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.
367
368 -----syntax:
369 drawThickArrow(<line> [,<line>,...])
370
371 -----examples:
372 drawThickarrow(BC)
373 drawThickarrow(PQ, RS)
374
375 ==============================
376
377 DrawThickLine
378
379 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.
380
381 -----syntax:
382 drawThickLine(<line> [,<line>,...])
383
384 -----examples:
385 drawThickline(BC)
386 drawThickline(PQ, RS)
387
388 ==============================
389
390 InputFile
391
392 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. 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.
393
394 -----syntax:
395 inputFile[*](<filename>)[<loopnumber>]
396
397 -----notes:
398 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 for plotting etc. Note that the inputfile* command has no <loopnumber> option. Note also that PiCTeX requires a ODD number of points.
399
400 -----examples:
401 inputFile(myfile.dat)[4]
402 inputFile*(mycurvedata.dat)
403
404 ==============================
405
406 LineThickness
407
408 This command sets a particular linethickness. The command linethickness(default) restores the working linethickness to the default value of 0.4pt.
409 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) .
410
411 -----syntax:
412 LineThickness(<expr><units>)
413 LineThickness(default)
414 var t = _linethickness_
415
416 -----notes:
417 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.
418
419 -----examples:
420 linethickness(2pt)
421 var t=3
422 linethickness((t)pt)
423 lineThickness((2*t)pt)
424 linethickness(default)
425 var t = _linethickness_
426
427 -----caution:
428 Note that there is a similar PiCTeX command with the same name (but with a different syntax).
429
430 ==============================
431
432 PAPER
433
434 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.
435
436 -----examples:
437 paper{units(1cm),xrange(0,10),yrange(0,10)}
438 paper{units(2cm,1cm),xrange(0,10),yrange(0,10),axes(LB)}
439 paper{units(1mm),xrange(0,100),yrange(0,100),axes(XY)}
440 paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRTBXY),ticks(1,1)}
441 paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRT*B*)}
442
443 ==============================
444
445 POINT
446
447 Defines a new point by allocating coordinates to a new point name. The * option re-allocates coordinates to an existing point name.
448
449 -----syntax:
450 POINT[*](<name>){<point>}[symbol=<chars>, radius=<expr>]
451 POINT[*](<name>){<location>}[symbol=<chars>, radius=<expr>]
452
453 -----notes:
454 <name> one leading letter plus maximum of four trailing digits
455 <chars> any TeX string allowed in an \hbox{}
456 <expr> any numerical expression
457 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.
458
459 -----examples:
460 point(A){5,5}
461 point(B2){22,46}[symbol=$\odot$]
462 point(B2){22,46}[symbol=circle(2),radius=5]
463 var r=3
464 point(B2){22,46}[symbol=square(3),radius=r]
465 point(B123){22,46}[radius=5]
466 point(D2){B2, shift(5,5)}
467 var s = 3
468 point(D2){B2, shift(2*s,4*s)}
469 point(D3){D2, polar(6,32 deg)}
470 point(D4){D2, polar(6,1.2 rad)}
471 point(D4){D2, polar(6, direction(AB))} %% radians by default
472 point(D4){D2, polar(6, directiondeg(AB) deg)}
473 point(G2){Q, rotate(P, 23 deg)}
474 point(G2){Q, vector(AB)}
475 point(D2){intersection(AB,CD)}
476 point(F){PointOnLine(AB,5.3)}
477 point(G){perpendicular(P,AB)}
478 point(H){circumcircleCenter(ABC)}
479 point(J){incircleCenter(ABC)}
480 point(K){excircleCenter(ABC,BC)}
481 point*(A){6,3}
482 point*(P){Q}
483 point*(B){B, shift(5,0)}
484 point*(P){xcoord(J),ycoord(K)}
485
486 ==============================
487
488 PointSymbol
489
490 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).
491
492 -----syntax:
493 PointSymbol(<symbol>, <line-free-radius>)
494 PointSymbol(default)
495
496 -----notes:
497 The PointSymbol command only influences subsequent point commands.
498 The optional square bracket of the point command overrides the PointSymbol command.
499
500 -----examples:
501 PointSymbol($\odot$, 0.7)
502 PointSymbol(default)
503
504 ==============================
505
506 SYSTEM
507
508 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.
509
510 -----syntax:
511 System("<command>")
512
513 -----notes:
514 The <command> string must be in inverted commas.
515
516 -----example:
517 system("dir > mydir-listing.txt")
518 system("perl myperlprogram.pl")
519
520 ==============================
521
522 SHOW....
523
524 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.
525
526 -----syntax:
527 showLength(AB)
528 showAngle(ABC) % returns angle in radians
529 showAngledeg(ABC) % returns angle in degrees
530 showArea(ABC)
531 showPoints
532 showVariables
533
534 ==============================
535
536 TEXT
537
538 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.
539
540 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
541
542 -----syntax:
543 text(<string>){<location>}[<position options>]
544 text(<string>){<pointname>, shift(<x>,<y>)}[]
545 text(<string>){<pointname>, polar(<r>,<angle>[rad])}[]
546
547 -----examples:
548 text(A){5,6}
549 text($A_1$){A1, shift(2, 2)}
550 text(Z2){Z2, shift(5, -5)}[tr]
551 text(Z3){Z2, polar(5, 20 deg)}[Br]
552 text(Z4){Z2, polar(5, 1.34 rad)}
553 text(\framebox{Z5}){Z5}
554
555 ==============================
556
557 VAR
558
559 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).
560
561 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.
562
563 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).
564
565 -----syntax:
566 var <name> = <expr>
567
568 -----notes:
569 In addition to the mathematical functions mathsPIC functions which can be used with the var command are:
570
571 angle(<three-points>) % returns angle in radians
572 angledeg(<three-points>) % returns angle in degrees
573 area(<three-points>)
574 xcoord(<point>)
575 ycoord(<point>)
576 direction(<two-points>) % returns angular direction in radians
577 directiondeg(<two-points>) % returns angular direction in degrees
578
579 -----examples:
580 var r = 20, r4 = r3*tan(0.3), j = (r*2e3)**2, r5 = AB
581 var e = _e_, p1 = _Pi_
582 var t = _linethickness_ % returns linethickness in current units
583 var g137 = angle(ABC) %(default: returns in radians)
584 var g = angledeg(ABC) % angle in degrees
585 var h = area(ABC)
586 var x2 = xcoord(A), y2 = ycoord(A)
587 var m5 = 12 rem 3 % remainder after dividing by 3
588 var r1 = direction(PQ) % in radians
589 var d1 = directiondeg(PQ)
590
591 ==============================
592 SEE ALSO
593 The mathsPIC package manual and examples
594
595 BUGS
596 Please report bugs to Dick Nickalls (dick [AT] nickalls [dot] org) or to Apostolos Syropoulos
597
598 ================END=================