summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/mathspic/mathspic.1
blob: 9ffa4b6c6c503eafcfb0db47887541bc548349a1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
.\" copyright (c) 2010 A Syropoulos and RWD Nickalls
.\" mathspic.1
.\" place this file in: /usr/share/man/man1/
..
.TH mathsPIC 1 "April 26, 2010"  "mathsPIC perl version"
.SH NAME
.B mathsPIC
.SH AUTHORS
A. Syropoulos and R.W.D. Nickalls (April 26, 2010)

 asyropoulos[at]<yahoo><com> 
 dick[at]<nickalls><org>

.SH DESCRIPTION
.B 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
.PP
CTAN: tex-archive/graphics/pictex/mathspic/perl
.PP
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).
.PP
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.

Trigonometric: sin(), cos(), tan(), asin(), acos(), atan()

Remainder: rem(); eg var  r=12 rem(5)

Integer: int(); eg var  r= int(3.87) --> 3

Sign (returns -1, 0, +1): sgn(); eg var  s=sgn(-3.27) --> -1

Square root: sqrt(); eg var s = sqrt(14)

Exponentiation: **; eg var j = r**2

Pi constant (3.14159...):  _Pi_  and  _pi_

e constant (2.71828...):  _E_  and  _e_

Linethickness:  _linethickness_  ; eg  var t = _linethickness_

.SH COMMAND-LINE USE
perl mathspic.pl [-b] [-c] [-h] [-o  <outfile>]  <infile>

.B -b
enables beep if mathsPIC detects an error

.B -c
disables the writing of comments to output file

.B -h
displays the help file

.B -o
defines the output file name
.SH MACRO COMMANDS
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
.B var
command as shown below. Macros are deleted using the
.B %undef
command.

 -----syntax:
 %def MACRONAME(parameters)<macrodefinition>
 %undef MACRONAME(parameters)

 -----notes:
 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.

 -----examples:
 %def d2r()_pi_/180%              % degrees2radians
 %def AreaOfRectangle(x,y)x*y%    % width x, length y
 %undef d2r()                     % delete the macro

 -----use:
 var j2= 6*(&d2r(45) + 23)
 var a3 = 3*&AreaOfRectangle(5,7)
.SH GENERAL COMMANDS

.P
.B NUMERICAL EXPRESSIONS
 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.

 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.

 -----examples:
 ArrowShape(3mm, 20,40)
 var h=4
 ArrowShape(h mm, 20, 40)
 ArrowShape((2*h)mm,20,40)

.P
.B BACKSLASH
\\
 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.

.P
.B USING THE COLOR PACKAGE
 The standard COLOR package can be used with mathsPIC, but note that it is important to load the COLOR package  after the mathsPIC package.

  It is best to place a comment symbol % at the end of LaTeX and TeX commands to limit white space at the end.

 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.

==============================

.B ARROWSHAPE
 This command defines the shape of an arrowhead, and allows
different arrowheads to be customised.

The default arrow shape is equivalent to the Arrowshape(2mm,30,40) command.
This default arrowhead shape can be reset using the Arrowshape(default) command, as shown in the following example.

 -----syntax:
 arrowshape(<length>[units], <angledeg>, <angledeg>)

 -----examples:
 Arrowshape(4mm,30,60)
 drawArrow(AB)
 Arrowshape(default)

==============================

.B beginLOOP...endLOOP
 This is an environment which cycles a block of code a specified number of times.

 -----syntax:
 beginLoop <expr>
 ...
 endLoop

 -----notes:
 The block of code which lies within the environment is input <expr> times.

 -----example:
 beginLoop 5
 ...
 endLoop


==============================

.B beginSKIP...endSKIP
 This is an `environment' within which commands are not actioned. It is useful in development for testing isolated commands and excluding other commands. 

==============================

.B CONST
 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.

 -----syntax:
 const name = <expr>

 -----examples:
 const r = 20, r4 = r3*tan(0.3)

==============================

.B DashArray
 The dasharray command takes an arbitrary number of paired arguments that are used to specify a dash pattern.

 -----syntax
 dasharray(d1 , g1 , d2 , g2 , ... )

 -----notes
 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.

 -----example
 dasharray(6pt, 2pt, 1pt, 2pt)
 var d=2
 dasharray(6pt, 2pt, 1pt, d pt)
 dasharray(6pt, 2pt, 1pt, (d)pt)
 dasharray(6pt, 2pt, 1pt, (3*d)pt)

==============================

.B DrawAngleArc
 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.
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.

 -----syntax:
 DrawAngleArc{angle(), radius(), external, clockwise}

 -----example:
 DrawAngleArc{angle(ABC), radius(3), external, clockwise}
 var r=3
 DrawAngleArc{angle(ABC), radius(r), external, clockwise}

==============================

.B DrawAngleArrow
 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.
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.

 -----syntax:
 DrawAngleArrow{angle(), radius(), external, clockwise}

 -----example:
 DrawAngleArrow{angle(ABC), radius(3), external, clockwise}
 var r=3
 DrawAngleArrow{angle(ABC), radius(r), external, clockwise}

==============================

.B DrawArrow
 This command draws an arrow(s) joining two points. The direction of the arrow is in the point order specified.

 -----syntax:
 drawArrow(<line> [,<line>] ... )

 -----notes:
 The length option can only refer to one arrow

 -----example:
 drawArrow(AB)
 drawArrow(FG, HJ)

==============================

.B DrawCircle
 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.

 -----syntax:
 DrawCircle(<center>, <radius>)

 -----examples:
 drawCircle(C2,5)
 drawCircle(C2,r2)
 drawCircle(C2,r2/tan(1.3))
 drawCircle(C2,AB)

==============================

.B DrawCircumcircle
 This command draws the circumcircle of a triangle.

 -----syntax:
 DrawCircumcircle(<triangle>)

 -----example:
 drawCircumcircle(ABC)

==============================

.B DrawCurve
 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.

 -----syntax:
 DrawCurve(<point><point><point>)

 -----example:
 drawCurve(ABC)

==============================

.B DrawExcircle
 This command draws the excircle touching one side of a triangle.

 -----syntax:
 DrawExcircle(<triangle>, <side>)

 -----example:
 drawExcircle(ABC, BC)

==============================

.B DrawIncircle
 This command draws the incircle of a triangle.

 -----syntax:
 DrawIncircle(<triangle>)

 -----example:
 drawIncircle(ABC)

==============================

.B DrawLine
 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.

 -----syntax:
 DrawLine( <points> [, <points>] )

 -----notes:
 <points> is any sequence of two or more point names.
 <expr> is any numerical expression.
 Lines are drawn in the order specified.
 Lines are separated by a comma.

 -----examples:
 drawline(AB)
 drawline(BCDE)
 drawline(FG, HJK, PQRST)

==============================

.B DrawPerpendicular
 This command draws the perpendicular from a point to a line.

 -----syntax:
 DrawPerpendicular(<point>, <line)

 -----example:
 drawPerpendicular(P,AB)

==============================

.B DrawPoint
 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.

 -----syntax:
 DrawPoint(<point> [<point> ..])

 -----examples:
 drawpoint(T4)
 drawpoint(ABCDEF)
 drawpoint(P1 P2 P3 P4)

==============================

.B DrawRightangle
 This command draws the standard right-angle symbol in the internal angle specified at the size specified by <expr>.

 -----syntax:
 DrawRightangle(<angle>, <expr>)

 -----notes:
 The <expr> can be any numerical expression.

 -----example:
 drawRightangle(ABC,3)
 drawRightangle(ABC,PQ)
 var d=5
 drawRightangle(ABC,d)

==============================

.B DrawSquare
 This command draws a square defined by its side and the point-name of its centre. The <sidelength> can be any numerical expression.

 -----syntax:
 DrawSquare(<centerpoint>, <sidelength>)

 -----examples:
 drawSquare(P,5)
 var s2=3, j=2
 drawSquare(P,s2)
 drawSquare(P, s2*4/(3*j))
 drawSquare(P,AB)

==============================

.B DrawThickArrow
 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.

 -----syntax:
 drawThickArrow(<line> [,<line>,...])

 -----examples:
 drawThickarrow(BC)
 drawThickarrow(PQ, RS)

==============================

.B DrawThickLine
 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.

 -----syntax:
 drawThickLine(<line> [,<line>,...])

 -----examples:
 drawThickline(BC)
 drawThickline(PQ, RS)

==============================

.B InputFile
 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.

 -----syntax:
 inputFile[*](<filename>)[<loopnumber>]

 -----notes:
 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.

 -----examples:
 inputFile(myfile.dat)[4]
 inputFile*(mycurvedata.dat)

==============================

.B LineThickness
 This command sets a particular linethickness. The command linethickness(default) restores the working linethickness to the default value of 0.4pt.
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) .

 -----syntax:
 LineThickness(<expr><units>)
 LineThickness(default)
 var t = _linethickness_

 -----notes:
 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.

 -----examples:
 linethickness(2pt)
 var t=3
 linethickness((t)pt)
 lineThickness((2*t)pt)
 linethickness(default)
 var t = _linethickness_

 -----caution:
 Note that there is a similar PiCTeX  command  with the same name (but with a different syntax).

==============================

.B PAPER
 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.

 -----examples:
 paper{units(1cm),xrange(0,10),yrange(0,10)}
 paper{units(2cm,1cm),xrange(0,10),yrange(0,10),axes(LB)}
 paper{units(1mm),xrange(0,100),yrange(0,100),axes(XY)}
 paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRTBXY),ticks(1,1)}
 paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRT*B*)}

==============================

.B POINT
 Defines a new point by allocating coordinates to a new point name. The * option re-allocates coordinates to an existing point name.

 -----syntax:
 POINT[*](<name>){<point>}[symbol=<chars>, radius=<expr>]
 POINT[*](<name>){<location>}[symbol=<chars>, radius=<expr>]

 -----notes:
 <name> one leading letter plus maximum of three trailing digits
 <chars> any TeX string allowed in an \\hbox{}
 <expr> any numerical expression
 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.

 -----examples:
 point(A){5,5}
 point(B2){22,46}[symbol=$\\odot$]
 point(B2){22,46}[symbol=circle(2),radius=5]
 var r=3
 point(B2){22,46}[symbol=square(3),radius=r]
 point(B123){22,46}[radius=5]
 point(D2){B2, shift(5,5)}
 var s = 3
 point(D2){B2, shift(2*s,4*s)}
 point(D3){D2, polar(6,32 deg)}
 point(D4){D2, polar(6,1.2 rad)}
 point(D4){D2, polar(6, direction(AB))}      %% radians by default
 point(D4){D2, polar(6, directiondeg(AB) deg)}
 point(G2){Q, rotate(P, 23 deg)}
 point(G2){Q, vector(AB)}
 point(D2){intersection(AB,CD)}
 point(F){PointOnLine(AB,5.3)}
 point(G){perpendicular(P,AB)}
 point(H){circumcircleCenter(ABC)}
 point(J){incircleCenter(ABC)}
 point(K){excircleCenter(ABC,BC)}
 point*(A){6,3}
 point*(P){Q}
 point*(B){B, shift(5,0)}
 point*(P){xcoord(J),ycoord(K)}

==============================

.B PointSymbol
 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).

 -----syntax:
 PointSymbol(<symbol>, <line-free-radius>)
 PointSymbol(default)

 -----notes:
 The PointSymbol command only influences subsequent point commands.
 The optional square bracket of the point command overrides the PointSymbol command.

 -----examples:
 PointSymbol($\\odot$, 0.7)
 PointSymbol(default)

==============================

.B SYSTEM
 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.

 -----syntax:
 System("<command>")

 -----notes:
 The <command> string must be in inverted commas.

 -----example:
 system("dir > mydir-listing.txt")
 system("perl myperlprogram.pl")

==============================

.B SHOW....
 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.

 -----syntax:
 showLength(AB)
 showAngle(ABC)       % returns angle in radians
 showAngledeg(ABC)    % returns angle in degrees
 showArea(ABC)
 showPoints
 showVariables

==============================

.B TEXT
 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.

 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

 -----syntax:
 text(<string>){<location>}[<position options>]
 text(<string>){<pointname>, shift(<x>,<y>)}[]
 text(<string>){<pointname>, polar(<r>,<angle>[rad])}[]

 -----examples:
 text(A){5,6}
 text($A_1$){A1, shift(2, 2)}
 text(Z2){Z2, shift(5, -5)}[tr]
 text(Z3){Z2, polar(5, 20 deg)}[Br]
 text(Z4){Z2, polar(5, 1.34 rad)}
 text(\\framebox{Z5}){Z5}

==============================

.B VAR
 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).

  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.

 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).

 -----syntax:
 var  <name> = <expr>

 -----notes:
 In addition to the mathematical functions mathsPIC functions which can be used with the var command are:

 angle(<three-points>)          % returns angle in radians
 angledeg(<three-points>)       % returns angle in degrees
 area(<three-points>)
 xcoord(<point>)
 ycoord(<point>)
 direction(<two-points>)     % returns angular direction in radians
 directiondeg(<two-points>)  % returns angular direction in degrees

 -----examples:
 var r = 20, r4 = r3*tan(0.3), j = (r*2e3)**2,  r5 = AB
 var e = _e_, p1 = _Pi_
 var t = _linethickness_  % returns linethickness in current units
 var g137 = angle(ABC)    %(default: returns in radians)
 var g = angledeg(ABC)    % angle in degrees
 var h = area(ABC)
 var x2 = xcoord(A), y2 = ycoord(A)
 var m5 = 12 rem 3     % remainder after dividing by 3
 var r1 = direction(PQ)   % in radians
 var d1 = directiondeg(PQ)

==============================
.SH SEE ALSO
The mathsPIC package manual and examples
.SH BUGS
Please report bugs to Dick Nickalls (dick [AT] nickalls [dot] org) or to Apostolos Syropoulos