mathspic

       A. Syropoulos and R.W.D. Nickalls (April 26, 2010)

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

DESCRIPTION
       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

       CTAN: tex-archive/graphics/pictex/mathspic/perl

       Commands  which  can be used in the mathsPIC script file fall into four
       main groups (a) mathsPIC macro commands (prefixed with %def), (b) regu-
       lar  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).

       The  following  mathematics functions can used (note that decimal frac-
       tions 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_

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

       -b enables beep if mathsPIC detects an error

       -c disables the writing of comments to output file

       -h displays the help file

        -----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 %  sym-
       bol 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)

GENERAL COMMANDS
       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)

       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 back-
       slash followed by one or more spaces makes mathsPIC copy the whole line
       verbatim into the output file but without the backslash.

       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.

       mand.  This default arrowhead shape  can  be  reset  using  the  Arrow-
       shape(default) command, as shown in the following example.

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

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

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

       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

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

       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.

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

       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  lower-
       case  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>

        -----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  sepa-
       rated  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)

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

       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 con-
       sistent. The option order angle/radius/internal  or  external/clockwise
       or anticlockwise is important. The <radius> parameter can be any numer-
       ical 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}

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

       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 cor-
       respond 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}

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

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

       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)

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

       DrawCircumcircle
        This command draws the circumcircle of a triangle.

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

        -----example:
        drawCircumcircle(ABC)

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

       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)

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

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

        -----syntax:
        DrawExcircle(<triangle>, <side>)
        -----example:
        drawIncircle(ABC)

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

       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  com-
       mand 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)

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

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

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

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

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

       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)

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

        drawRightangle(ABC,PQ)
        var d=5
        drawRightangle(ABC,d)

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

       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)

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

       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 arrow-
       head is controlled by the ArrowShape command.

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

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

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

       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 com-
       mand to vary thickness of a line.

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

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

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

       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 numeri-
       requires a ODD number of points.

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

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

       LineThickness
        This  command  sets a particular linethickness. The command linethick-
       ness(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).

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

       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,  Bot-
       tom,  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)}

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

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

       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 \bul-
       let  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.
        -----syntax:
        System("<command>")

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

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

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

       SHOW....
        This command makes mathsPIC return the value of a calculation or spec-
       ified 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

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

       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 appro-
       priate 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}

       ture,  and a variable can have the same name as a point (and so we sug-
       gest points have uppercase letters and  variables  and  constants  have
       lowercase  letters).  New  values can be re-allocated to existing vari-
       able-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 acciden-
       tally 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)

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

SEE ALSO
       The mathsPIC package manual and examples

BUGS
       Please  report  bugs to Dick Nickalls (dick [AT] nickalls [dot] org) or
       to Apostolos Syropoulos

mathsPIC perl version           April 26, 2010                     mathsPIC(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2019 Hurricane Electric. All Rights Reserved.