Provided by: texlive-pictures_2019.20200218-1_all bug

NAME

       mathsPIC

AUTHORS

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

       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_

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

       -o defines the output file name

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 var command as shown below.  Macros  are  deleted  using  the  %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)

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

        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.

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

       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)

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

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

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

       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)

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

       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}

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

       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}

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

       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)

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

       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:
        drawExcircle(ABC, BC)

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

       DrawIncircle
        This command draws the incircle of a triangle.

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

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

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

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

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

       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 arrowhead 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 command 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
       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)

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

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

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

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

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

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

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

       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)

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

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

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

       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

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

       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}

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

       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)

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

SEE ALSO

       The mathsPIC package manual and examples

BUGS

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