;;
;; See @link http://newlisp.org/index.cgi?Postscript http://newlisp.org/index.cgi?Postscript
;; for many examples with source code.
;;
;; Postscript files can be viewed using: 'open filename.ps' on Mac OS X
;; or using the Ghostscript program on Unix's or Win32 to convert
;; to PDF or any graphics file format. Best quality is achieved
;; on Mac OS X when using the Preview.app viewer for loading the
;; postscript files and converting to PDF or bitmapped formats like
;; JPEG, PNG, GIF by re-saving.
;;
;; If not using Mac OS X look for Ghostscript here:
;; @link http://www.ghostscript.com/ www.ghostscript.com and
;; here: @link http://www.cs.wisc.edu/~ghost/ www.cs.wisc.edu/~ghost/
;;
;; NOTE! on some Mac OS X installations it is necessary to quit out of
;; the Preview.app completely before viewing a '.ps' file for the first
;; time. Subsequent views of '.ps' documents are fine.
;;
;; On Linux/UNIX systems the following command can be used to convert
;; a '.ps' file to a '.pdf' file:
;;

;; Most functions work like in relative to the
;; current position of an imaginary drawing pen with an
;; orientation of 0 to 360 degree starting streight up: 0 and
;; moving clockwise right 90, down 180, left 270, up and 360 degrees.
;; Other functions work on absolute X,Y coordinates.
;;
;; The coordinate system starts on the bottom left with 0,0 and
;; extends on a 8 1/2 x 11 inch letter page to 'x': 612, 'y': 792,
;; 72 points for each inch. The functions 'ps:transpose' and 'ps:scale'
;; can be used to move the origin point '' or scale from points to
;; other measurements.
;;
;; Return value from 'ps:xxx' functions are not used and not mentioned in
;; the documentation.
;;
;;

Summary of functions

;;

Turtle coordinate positioning and turning

;;

;; ps:goto - move turtle to position x, y
;; ps:move - move turtle a distance s forward from the current position
;; ps:turn - turn the turtle degress dg left (negative) or right (positive)
;; ps:angle - set the turtle orientation to dg degrees
;;

;;

Line drawing

;;

;; ps:draw - draw distance s forward from current position
;; ps:drawto - draw to the absolute position x,y from the current position
;; ps:line - draw a multipart line consisting of line and bezier curve segments
;; ps:bezier - draw a Bezier curve
;;

;;

Closed shapes, filling and clipping

;;

;; ps:rectangle - draw a rectangle
;; ps:polygon - draw a polygon with radius rad and n number of sides
;; ps:circle - draw a circle
;; ps:ellipse - draw an open or closed ellipse with x-rad and y-rad radius
;; ps:pie - draw a pie piece with radius rad and width
;; ps:petal - draw a petal shape from Bezier curves
;; ps:shape - draw a shape defined by a list of line and Bezier segments
;; ps:clip - define a clipping path using line and Bezier segments
;;

Rendering and output

;; @syntax (ps:angle )
;; @param Angle degrees from 0 to 360.
;;
;; Set the turtle angle to degrees.
;; Upwards is 0, right 90, downwards 180 and left 270 degrees.
;; The turtle position is saved on the graphics state stack when using
;; '(ps:gsave)'.
;; @syntax (ps:bezier )
;; @param Bezier coordinates of relative to = 0,0
;; @param Bezier coordinates of relative to = 0,0
;; @param Bezier coordinates of relative to = 0,0
;;
;; Draw a Bezier curve.
;; The Bezier curve starts at point which is the current
;; turtle position and stops at point which is at offset
;; and relative to starting point. The turtle orientation
;; after the drawing the Bezier curve is perpendicular
;; to the Bezier curve baseline to and the position is .
;; @syntax (ps:circle [])
;; @param Radius of the circle.
;; @param Optional fill flag.
;;
;; Draw a circle with radius . The optional flag
;; with either 'true' or 'nil' (default) indicates if the circle
;; is filled with the fill color specified by 'ps:fill-color'.
;; The circle is drawn around the current turtle position.
;; The turtle position or orientation is not changed.
;; @syntax (ps:clip )
;; @param A list of turtle movements and/or Bezier curves.
;; Define a clipping path using turtle movements () and
;;
;; Bezier curves () starting from the
;; last turtle coordinates , and finishing at , .
;; All Bezier coordinates are relative to the previous turtle position and
;; orientation.
;;
;; Before redefining the clipping area '(ps:gsave)' should
;; be used to save the old graphics state parameters, after
;; clipping and drawing in the clipped area the graphics
;; state should be restored using '(ps:grestore)'.
;; The turtle position or orientation is not changed.
;; @syntax (ps:draw )
;; @param Distance to draw.
;;
;; Draw going forward distance . Moves the turtle forward by
;; the amount of points specified in and draws with the current
;; line color set by 'ps:line-color'.
;;
;; @syntax (ps:drawto )
;; @param The x coordinate to draw to.
;; @param The y coordinate to draw to.
;;
;; Draw a line to point , . Moves the turtle to point
;; , like '(ps:goto x y)', but also draws a line from
;; the old to the new position. The turtle position is changed to the
;; new point , and the orientation is changed to the orientaion of
;; the line drawn.
;; @syntax (ps:ellipse [])
;; @param The x axis radius.
;; @param The y axis radius.
;; @param The start angle in 0 to 360 degrees.
;; @param The end angle in 0 to 360 degrees.
;;
;; Draw an ellipse with optional either 'true' or 'nil' (default).
;; The ellipse is drawn around the current turtle position
;; with the Y axis oriented like the turtle.
;; For , set to 0, 360 an ellipse is drawn.
;; For a partial radius the opening is closed by a line
;; resulting in segment shape, i.e. -90, 90 would result
;; in a half circle from the left to the right of the turtle.
;; When and are of equal size a full circle
;; can be drawn. The turtle position or orientation is not changed.
;; @syntax (ps:fill-color )
;; @param The red color value.
;; @param The green color value.
;; @param The blue color value.
;;
;; Set color for shape filling.
;; Color values assume the following value:
;;

;;
;; @syntax (ps:fill-color )
;; @param A hex string specifying the line color.
;;
;; In an alternative syntax color values can be specified in a
;; hex string:
;;
;; is a hex string constant '"000000"' to '"FFFFFF"'
;; Colors are specified as usual in HTML coding.
;; Each two hex digits define a color: 'rrggbb'.
;; @syntax (ps:font )
;; @param The font name.
;; @param The size of the font in points.
;;
;; The current font is set for all subsequent text operations.
;; Depending on the version of the Postsrcipt viewer or device
;; installed different fonts are available.
;; @syntax (ps:goto )
;; @param The new x coordinate.
;; @param The new y coordinate.
;;
;; Moves to position , . On a US letter page of 612 by 792
;; point positions are defined with 72 points per inch. The turtle position
;; is saved on the graphics state stack when using '(ps:gsave)'.
;; @syntax (ps:grestore)
;;
;; Restores the graphics state from the stack.
;; @syntax (ps:gsave)
;;
;; Saves the current graphics state. The function pushes the
;; current graphics state on a special stack, from where it
;; can be resored using '(ps:grestore)'. States saved are:
;; The turtle position X, Y and orientation and transformation
;; scaling and rotation factors.
;; @syntax (ps:line )
;; @param A list of turtle movements or Bezier curves.
;;
;; Draw a multipart line. are turtle movements (),
;; or Bezier curves () starting
;; from the last turtle coordinates , and
;; finishing at , . All Bezier coordinates are
;; relative to the previous turtle position and
;; orientation.
;;
;; The turtle position and orientation are changed after
;; drawing the line.
;; @syntax (ps:line-cap )
;; @param The line termination shape mode as a string or number
;;
;; Sets the line termination shape as either a number or string:
;;

;;
;; @syntax (ps:line-color )
;; @param A hex string specifying the line color.
;;
;; In an alternative syntax color values can be specified in a
;; hex string:
;;
;; is a hex string constant '"000000"' to '"FFFFFF"'
;; Colors are specified as usual in HTML coding.
;; Each to two hex digits define a color: 'rrggbb'.
;; @syntax (ps:line-join | )
;; @param The line join mode.
;;
;; Sets the line join mode as either a number or string:
;;