asymptote 1.83

git-svn-id: svn://tug.org/texlive/trunk@14696 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 95 insertions, 87 deletions

diff --git a/Build/source/utils/asymptote/doc/asymptote.texi b/Build/source/utils/asymptote/doc/asymptote.texi
index db56898ee9c..736ac00dfa1 100644
--- a/Build/source/utils/asymptote/doc/asymptote.texi
+++ b/Build/source/utils/asymptote/doc/asymptote.texi
@@ -361,11 +361,12 @@ You will also need to install @code{GPL Ghostscript} from
 To view the default @code{PostScript} output, you can install the
 program @code{gsview} available from 
 @url{http://www.cs.wisc.edu/~ghost/gsview/}.
+@cindex @code{psview}
 @anchor{psview}
 A better (and free) @code{PostScript} viewer available at
 @url{http://psview.sourceforge.net/} (which in particular works properly
 in interactive mode) unfortunately currently requires some manual
-configuration. Specifically, if version @code{x.xx} of psview is
+configuration. Specifically, if version @code{x.xx} of @code{psview} is
 extracted to the directory @code{c:\Program Files} one needs to put
 @verbatim
 import settings;
@@ -415,17 +416,15 @@ Users of @code{gsview} will need to enable @code{Options/Auto Redisplay}
 (however, under @code{MSDOS} it is still necessary to click on the
 @code{gsview} window; under @code{UNIX} one must manually redisplay by
 pressing the @code{r} key). A better (and free) multiplatform
-alternative to @code{gsview} is psview (@pxref{psview}).
+alternative to @code{gsview} is @code{psview} (@pxref{psview}).
 
 @cindex @code{settings}
 @cindex configuration file
 Configuration variables are most easily set as @code{Asymptote}
-variables in an optional configuration file (by default,
-@code{.asy/config.asy} in the user's home directory,
-@code{$TEXMFCONFIG/asymptote} under @code{TeXLive}, and
-@code{%USERPROFILE%\.asy\config.asy} under @code{MSDOS};
-@pxref{configuration file}). Here are the default values
-of several important configuration variables under @code{UNIX}:
+variables in an optional configuration file @code{config.asy}
+@pxref{configuration file}).
+Here are the default values of several important configuration
+variables under @code{UNIX}:
 
 @noindent
 @verbatim
@@ -506,7 +505,8 @@ warn(string s);
 nowarn(string s);
 @end verbatim
 @noindent
-or by directly modifying the string array @code{warnings}.
+or by directly modifying the string array @code{settings.suppress}, which lists
+all disabled warnings.
 
 @cindex command-line options
 Configuration variables may also be set or overwritten with a
@@ -550,8 +550,10 @@ variable @code{dir} (separated by @code{:} under UNIX and
 @code{;} under @code{MSDOS});
 @item
 @cindex @code{.asy}
-The directory @code{.asy} in the user's home directory 
-(@code{%USERPROFILE%\.asy} under @code{MSDOS});
+The directory specified by the environment variable
+@code{ASYMPTOTE_HOME}; if this variable is not set,
+the directory @code{.asy} in the user's home directory
+(@code{%USERPROFILE%\.asy} under @code{MSDOS}) is used;
 @item
 The @code{Asymptote} system directory (by default,
 @code{@value{Datadir}/asymptote} under @code{UNIX} and
@@ -898,6 +900,7 @@ interconnected with
 @cindex @code{..}
 @code{--}, which denotes a straight line segment, or @code{..}, which
 denotes a cubic spline.
+@cindex @code{unitcircle}
 @anchor{unitcircle}
 @cindex @code{unitcircle}
 Specifying a final node @code{cycle} creates a cyclic path that
@@ -907,6 +910,7 @@ connects smoothly back to the initial node, as in this approximation
 path unitcircle=E..N..W..S..cycle;
 @end verbatim
 
+@cindex Bezier
 @anchor{Bezier}
 @cindex direction specifier
 Each interior node of a cubic spline may be given a
@@ -1127,6 +1131,7 @@ ends of the path). Each of these bar specifiers (except for
 length of the bar in @code{PostScript} coordinates. The default
 bar length is @code{barsize(pen)}.
 
+@cindex arrows
 @anchor{arrows}
 @cindex @code{None}
 @cindex @code{Blank}
@@ -1161,10 +1166,10 @@ the predefined arrowhead styles @code{DefaultHead}, @code{SimpleHead},
 real @code{size} (arrowhead size in @code{PostScript} coordinates),
 real @code{angle} (arrowhead angle
 in degrees), filltype @code{filltype} (one of @code{FillDraw}, @code{Fill},
-@code{NoFill}, @code{UnFill}, @code{Draw}) 
-and (except for @code{MidArrow} and @code{Arrows}) a
-relative real @code{position} along the path (an @code{arctime}) where
-the tip of the arrow should be placed. The default arrowhead size when drawn
+@code{NoFill}, @code{UnFill}, @code{Draw}) and (except for
+@code{MidArrow} and @code{Arrows}) a real @code{position} (in the
+sense of @code{point(path p, real t)}) along the path where the tip of
+the arrow should be placed. The default arrowhead size when drawn
 with a pen @code{p} is @code{arrowsize(p)}. There are also arrow versions with
 slightly modified default values of @code{size} and @code{angle} suitable for
 curved arrows: @code{BeginArcArrow}, @code{EndArcArrow} (or equivalently
@@ -1478,6 +1483,7 @@ bottom-left corner of the label at @code{position}.
 @cindex @code{nullpen}
 If @code{p} is @code{nullpen}, the pen specified within the
 Label, which defaults to @code{currentpen}, will be used.
+@cindex @code{Label}
 @anchor{Label}
 The Label @code{L} can either be a string or the structure obtained by calling
 one of the functions
@@ -1529,11 +1535,11 @@ void label(picture pic=currentpicture, Label L, path g, align align=NoAlign,
 @end verbatim
 @cindex @code{Relative}
 By default the label will be positioned at the midpoint of the path.
-An alternative label location (an @code{arctime} value between 0 and
-@code{length(g)} @pxref{arctime}) may be specified as real value for
-@code{position} in constructing the Label. The position
-@code{Relative(real)} specifies a location relative to the total
-arclength of the path. These convenient abbreviations are predefined:
+An alternative label position (in the sense of @code{point(path p, real t)})
+may be specified as a real value for @code{position} in constructing
+the Label. The position @code{Relative(real)} specifies a location
+relative to the total arclength of the path. These convenient
+abbreviations are predefined:
 @cindex @code{BeginPoint}
 @cindex @code{MidPoint}
 @cindex @code{EndPoint}
@@ -2199,8 +2205,8 @@ path Arc(pair c, explicit pair z1, explicit pair z2,
 @end verbatim
 
 An ellipse can be drawn with the routine
-@verbatim
 @cindex @code{ellipse}
+@verbatim
 path ellipse(pair c, real a, real b)
 {
   return shift(c)*scale(a,b)*unitcircle;
@@ -2761,7 +2767,14 @@ pen Dotted(pen p=currentpen) {return dotted+2*linewidth(p);}
 @cindex @code{defaultpen}
 The default line type is @code{solid}; this may be changed with
 @code{defaultpen(pen)}.
-The line type of a pen is returned by @code{int linetype(pen p=currentpen)}.
+@cindex @code{linetype}
+@cindex @code{offset}
+@cindex @code{scale}
+@cindex @code{adjust}
+The line type of a pen can be determined with the functions
+@code{string linetype(pen p=currentpen)}, 
+@code{real offset(pen p)}, @code{bool scale(pen p)}, and
+@code{bool adjust(pen p)}.
 
 @cindex @code{linewidth}
 @cindex @code{defaultpen}
@@ -3259,7 +3272,7 @@ void shipout(string prefix=defaultfilename, picture pic=currentpicture,
              orientation orientation=orientation,
              string format="", bool wait=false, bool view=true,
              string options="", string script="",
-             projection P=currentprojection);
+             light light=currentlight, projection P=currentprojection)
 @end verbatim
 @noindent
 The default output format, @code{PostScript}, may be changed
@@ -3381,8 +3394,8 @@ margin and output the resulting frame, use the command:
 @verbatim
 shipout(bbox(0.25cm));
 @end verbatim
-A @code{picture} may be fit to a frame with the background color of
-pen @code{p} with the function @code{bbox(p,Fill)}. 
+A @code{picture} may be fit to a frame with the background color
+pen @code{p}, using the function @code{bbox(p,Fill)}. 
 
 The functions 
 @verbatim
@@ -3656,9 +3669,11 @@ write(fout,"List: ",1,2,3);     // Writes "List: 1     2     3"
 @cindex @code{xoutput}
 @cindex @code{binput}
 @cindex @code{boutput}
-@cindex @code{single}
+@cindex single precision
 @cindex double precision
-@cindex @code{signed}
+@cindex @code{singlereal}
+@cindex @code{singleint}
+@cindex @code{signedint}
 A file may also be opened with @code{xinput} or @code{xoutput}, instead of
 @code{input} or @code{output}, to read or write
 double precision (64-bit) reals and single precision (32-bit)
@@ -3668,23 +3683,21 @@ Data Representation) portable binary format (available on all
 Alternatively, a file may also be opened with @code{binput} or
 @code{boutput} to read or write double precision reals and single
 precision integers in the native (nonportable) machine binary format.
-The function
-@code{file single(file f, bool real=true, bool int=true)} may
+The virtual member functions
+@code{file singlereal(bool b=false)} and @code{file singleint(bool b=true)}
 be used to change the precision of real and integer I/O
 operations, respectively, for an @acronym{XDR} or binary file @code{f}.  
-Similarly, the function @code{file signed(file f, bool b=true)}
+Similarly, the function @code{file signedint(bool b=true)}
 can be used to modify the signedness of integer reads and writes for
 an @acronym{XDR} or binary file @code{f}.
-Note that @code{single}, and @code{signed} modify and return their
-file arguments (to facilitate nested function calls).
 
 @cindex @code{name}
 @cindex @code{mode}
 @cindex @code{singlereal}
 @cindex @code{singleint}
-@cindex @code{signed}
+@cindex @code{signedint}
 The virtual members @code{name}, @code{mode}, @code{singlereal},
-@code{singleint}, and @code{signed} may be used to query the
+@code{singleint}, and @code{signedint} may be used to query the
 respective parameters for a given file.
 
 @cindex @code{eof}
@@ -4467,6 +4480,7 @@ as variables, but allows overloading by distinguishing variables
 based on their signatures.  
 
 @cindex @code{libsigsegv}
+@cindex stack overflow
 @anchor{stack overflow}
 @cindex recursion
 @cindex stack overflow
@@ -4906,7 +4920,6 @@ The @code{copy} function listed below provides a deep copy of an array.
 
 @cindex @code{length}
 @cindex @code{cyclic}
-@cindex @code{cyclicflag}
 @cindex @code{keys}
 @cindex @code{push}
 @cindex @code{append}
@@ -4917,8 +4930,7 @@ The @code{copy} function listed below provides a deep copy of an array.
 Every array @code{A} of type @code{T[]} has the virtual members
 @itemize
 @item   @code{int length},
-@item   @code{void cyclic(bool b)},
-@item   @code{bool cyclicflag},
+@item   @code{int cyclic},
 @item   @code{int[] keys},
 @item   @code{T push(T x)},
 @item   @code{void append(T[] a)},
@@ -4930,10 +4942,9 @@ Every array @code{A} of type @code{T[]} has the virtual members
 @end itemize
 
 The member @code{A.length} evaluates to the length of the array.
-Setting @code{A.cyclic(true)} signifies that array indices should be reduced
+Setting @code{A.cyclic=true} signifies that array indices should be reduced
 modulo the current array length. Reading from or writing to a nonempty
-cyclic array never leads to out-of-bounds errors or array resizing. The member
-@code{A.cyclicflag} returns the current setting of the @code{cyclic} flag.
+cyclic array never leads to out-of-bounds errors or array resizing.
 
 The member @code{A.keys} evaluates to an array of integers containing the
 indices of initialized entries in the array in ascending order.  Hence, for an
@@ -4952,7 +4963,7 @@ elements down. If no arguments are given, @code{A.delete()} provides a
 convenient way of deleting all elements of @code{A}. The routine
 @code{A.initialized(int n)} can be used to examine whether the element
 at index @code{n} is initialized. Like all @code{Asymptote} functions,
-@code{cyclic}, @code{push}, @code{append}, @code{pop}, @code{insert},
+@code{push}, @code{append}, @code{pop}, @code{insert},
 @code{delete}, and @code{initialized} can be "pulled off" of the array
 and used on their own. For example,
 @verbatim
@@ -5214,7 +5225,6 @@ If the matrix @code{a} is tridiagonal, the routine @code{tridiagonal} provides
 a more efficient algorithm (@pxref{tridiagonal}). 
 
 @anchor{solve}
-
 @cindex @code{solve}
 @item real[][] solve(real[][] a, real[][] b, bool warn=true)
 Solve the linear equation @math{@code{a}x=@code{b}} and return the
@@ -5286,12 +5296,16 @@ real[] A=fin;
 @cindex line mode
 @noindent
 reads real values into @code{A} until the end-of-file is reached (or an
-I/O error occurs). If line mode is set with @code{line(file)}, then
+I/O error occurs). 
+
+The virtual members @code{dimension}, @code{line}, @code{csv},
+@code{word}, and @code{read} of a file are useful for reading arrays.
+@cindex @code{line}
+For example, if line mode is set with @code{file line(bool b=true)}, then
 reading will stop once the end of the line is reached instead
-(line mode may be cleared with @code{line(file,false)}):
 @verbatim
 file fin=input("test.txt");
-real[] A=line(fin);
+real[] A=fin.line();
 @end verbatim
 
 @cindex reading string arrays
@@ -5299,27 +5313,25 @@ real[] A=line(fin);
 @cindex white-space string delimiter mode
 Since string reads by default read up to the end of line anyway, line mode
 normally has no effect on string array reads.
-However, there is a white-space delimiter mode for reading strings, set with
-@code{word(file)} and cleared with @code{word(file,false)}, which causes
-string reads to respect white-space delimiters, instead of the default
-end-of-line delimiter:
+However, there is a white-space delimiter mode for reading strings,
+@code{file word(bool b=true)}, which causes string reads to respect
+white-space delimiters, instead of the default end-of-line delimiter:
 @verbatim
-file fin=word(line(input("test.txt")));
+file fin=input("test.txt").line().word();
 real[] A=fin;
 @end verbatim
 
 @cindex @code{csv}
 @cindex comma-separated-value mode
-Another useful mode is comma-separated-value mode, set with @code{csv(file)}
-and cleared with @code{csv(file,false)}, which causes reads to respect
-comma delimiters:
+Another useful mode is comma-separated-value mode,
+@code{file csv(bool b=true)}, which causes reads to respect comma delimiters:
 @verbatim
 file fin=csv(input("test.txt"));
 real[] A=fin;
 @end verbatim
 
 @cindex @code{dimension}
-To restrict the number of values read, use the @code{dimension(file,int)}
+To restrict the number of values read, use the @code{file dimension(int)}
 function: 
 @verbatim
 file fin=input("test.txt");
@@ -5336,23 +5348,22 @@ Two- and three-dimensional arrays of the basic data types can be read
 in like this:
 @verbatim
 file fin=input("test.txt");
-real[][] A=dimension(fin,2,3);
-real[][][] B=dimension(fin,2,3,4);
+real[][] A=fin.dimension(2,3);
+real[][][] B=fin.dimension(2,3,4);
 @end verbatim
 @noindent
 Again, an integer limit of zero means no restriction.
 
-@cindex @code{read1}
-@cindex @code{read2}
-@cindex @code{read3}
+@cindex @code{read}
 Sometimes the array dimensions are stored with the data as integer
-fields at the beginning of an array. Such arrays can be read in with the
-functions @code{read1}, @code{read2}, and @code{read3}, respectively:
+fields at the beginning of an array. Such 1, 2, or 3 dimensional
+arrays can be read in with the virtual member functions
+@code{read(1)}, @code{read(2)}, or @code{read(3)}, respectively:
 @verbatim
 file fin=input("test.txt");
-real[] A=read1(fin);
-real[][] B=read2(fin);
-real[][][] C=read3(fin);
+real[] A=fin.read(1);
+real[][] B=fin.read(2);
+real[][][] C=fin.read(3);
 @end verbatim
 
 @cindex @code{write}
@@ -5360,18 +5371,6 @@ One, two, and three-dimensional arrays of the basic data types can be
 output with the functions @code{write(file,T[])},
 @code{write(file,T[][])}, @code{write(file,T[][][])}, respectively.
 
-@cindex @code{dimension}
-@cindex @code{line}
-@cindex @code{csv}
-@cindex @code{word}
-@cindex @code{single}
-@cindex @code{signed}
-Note that @code{dimension}, @code{line}, @code{csv},
-@code{word}, @code{single}, and @code{signed} modify and return their
-file arguments (to facilitate nested function calls).
-The virtual members @code{dimension}, @code{line}, @code{csv}, and
-@code{word} may be used to query the respective parameters for a given file.
-
 @node Slices
 @subsection Slices
 @cindex slices
@@ -5410,7 +5409,7 @@ simply wrap around.  For example:
 
 @verbatim
 int[] x={0,1,2,3,4,5,6,7,8,9};
-x.cyclic(true);
+x.cyclic=true;
 int[] y=x[8:15];  // y={8,9,0,1,2,3,4}.
 int[] z=x[-5:5];  // z={5,6,7,8,9,0,1,2,3,4}
 int[] w=x[-3:17]; // w={7,8,9,0,1,2,3,4,5,6,7,8,9,0,1,2,3,4,5,6}
@@ -5907,7 +5906,7 @@ need to remove the files @code{latexusage-*}, @code{latexusage_.pre}, and
 One can specify @code{width}, @code{height},
 @code{viewportwidth}, @code{viewportheight}, and @code{attach}
 @code{keyval}-style options to the @code{asy} environment.
-The current version (1.07) of @code{asymptote.sty} supports the
+The current version (1.09) of @code{asymptote.sty} supports the
 embedding of 3D @acronym{PRC} files, either inline or, using the
 @code{attach} option with the @code{attachfile2} (or older
 @code{attachfile}) @code{LaTeX} package,
@@ -6015,7 +6014,7 @@ sizing of pictures.
 @section @code{math}
 @cindex @code{math}
 This package extends @code{Asymptote}'s mathematical capabilities with
-intersection algorithms and matrix arithmetic:
+matrix arithmetic and intersection algorithms:
 
 @table @code
 
@@ -6195,7 +6194,6 @@ sharp corners of paths, as illustrated in the example file @code{roundpath.asy}.
 @node animation
 @section @code{animation}
 @cindex @code{animation}
-@cindex @code{merge}
 @cindex @code{convert}
 @cindex animation
 @cindex @code{ImageMagick}
@@ -6203,7 +6201,7 @@ This module allows one to generate animations, as illustrated by the
 files @code{wheel.asy}, @code{wavelet.asy}, and @code{cube.asy} in
 the @code{animations} subdirectory of the examples directory. These
 animations use the @code{ImageMagick} @code{convert} program to
-@code{merge} multiple images into a @acronym{GIF} or @acronym{MPEG}
+merge multiple images into a @acronym{GIF} or @acronym{MPEG}
 movie.
 
 @cindex @code{animate}
@@ -6450,7 +6448,7 @@ bool3 function @code{cond} on [@code{a},@code{b}]. If @code{cond} is:
 @item @code{default}, the point is added to a new guide;
 @item @code{false}, the point is omitted and a new guide is begun.
 @end itemize
-Th points are connected using the interpolation specified by @code{join}:
+The points are connected using the interpolation specified by @code{join}:
 @itemize @bullet 
 
 @cindex @code{operator --}
@@ -6925,6 +6923,7 @@ the tick labels on the @math{y} axis.
 @cindex @code{marknodes}
 @cindex @code{markuniform}
 @cindex @code{mark}
+@cindex path markers
 @anchor{pathmarkers}
 @item The next example draws two graphs of an array of coordinate pairs,
 using frame alignment and data markers. In the left-hand graph, the
@@ -6991,6 +6990,7 @@ absolute values of the elements of the pair array @code{dp} and the
 optional pair array @code{dm}. If @code{dm} is not specified, the
 positive and negative extents of the error are assumed to be equal.
 @anchor{errorbars}
+@cindex error bars
 @verbatiminclude errorbars.asy
 @sp 1
 @center @image{errorbars}
@@ -7042,6 +7042,7 @@ factor.
 @center @image{scaledgraph}
 
 @anchor{automatic scaling}
+@cindex automatic scaling
 @cindex @code{scale}
 @cindex @code{Linear}
 @cindex @code{Log}
@@ -7201,6 +7202,7 @@ data in @code{diatom.csv} and @code{westnile.csv}.
 @node palette
 @section @code{palette}
 @anchor{images}
+@cindex images
 @code{Asymptote} can also generate color density images
 and palettes. The following palettes are predefined in
 @code{palette.asy}: 
@@ -7484,17 +7486,17 @@ Arbitrary thick three-dimensional curves and line caps (which the
 @code{OpenGL} standard does not require implementations to provide) are
 constructed with
 @verbatim
-tube tube(path3 g, real width, real granularity=tubegranularity);
+tube tube(path3 p, real width, real granularity=tubegranularity);
 @end verbatim
 @noindent
 this returns a tube structure representing a tube of diameter @code{width} 
 centered approximately on @code{g}. The tube structure consists of a
 surface @code{s} and the actual tube center, path3 @code{center}.
-This can make files slow to render,
+Drawing thick lines as tubes can be slow to render,
 especially with the @code{Adobe Reader} renderer. The setting
 @code{thick=false} can be used to disable this feature and force all
 lines to be drawn with @code{linewidth(0)} (one pixel wide, regardless
-of the resolution). By default mesh and contour lines in three-dimensions
+of the resolution). By default, mesh and contour lines in three-dimensions
 are always drawn thin, unless an explicit line width is given in the pen
 parameter or the setting @code{thin} is set to @code{false}. The pens
 @code{thin()} and @code{thick()} defined in plain_pens.asy can also be used
@@ -8040,6 +8042,7 @@ Further three-dimensional examples are provided in the files
 subdirectory) @code{cube.asy}.
 
 @anchor{PostScript3D}
+@cindex 3D @code{PostScript}
 Limited support for projected vector graphics (effectively three-dimensional
 nonrendered @code{PostScript}) is available with the setting
 @code{render=0}. This currently only works for piecewise planar
@@ -8181,6 +8184,9 @@ surface surface(real f(pair z), pair a, pair b, int nx=nmesh, int ny=nx,
 surface surface(real f(pair z), pair a, pair b, int nx=nmesh, int ny=nx,
                 splinetype xsplinetype, splinetype ysplinetype=xsplinetype,
                 bool cond(pair z)=null);
+surface surface(triple f(pair z), real[] u, real[] v,
+                splinetype[] usplinetype, splinetype[] vsplinetype=Spline,
+                bool cond(pair z)=null);
 surface surface(triple f(pair z), pair a, pair b, int nu=nmesh, int nv=nu,
                 bool cond(pair z)=null);
 surface surface(triple f(pair z), pair a, pair b, int nu=nmesh, int nv=nu,
@@ -8621,6 +8627,7 @@ automatically imported for each run as the final step in loading module
 @code{plain}.
 
 @anchor{configuration file}
+@cindex configuration file
 @cindex @code{ASYMPTOTE_CONFIG}
 @cindex @code{config}
 @cindex @code{settings}
@@ -8628,8 +8635,8 @@ automatically imported for each run as the final step in loading module
 Default option values may be entered as @code{Asymptote} code in a
 configuration file named @code{config.asy} (or the file specified by
 the environment variable @code{ASYMPTOTE_CONFIG} or @code{-config} option).
-@code{Asymptote} will look for this file in its usual search path.
-Typically the configuration file is placed in the
+@code{Asymptote} will look for this file in its usual search path
+(@pxref{Search paths}). Typically the configuration file is placed in the
 @code{.asy} directory in the user's home directory
 (@code{%USERPROFILE%\.asy} under @code{MSDOS}).
 Configuration variables are accessed using the long form of the option names:
@@ -8804,6 +8811,7 @@ A trailing semi-colon followed by optional @code{Asymptote} commands may
 be entered on the same line.
 @cindex @code{quit}
 @cindex @code{exit}
+@cindex @code{history}
 @anchor{history}
 @item quit
 exit interactive mode (@code{exit} is a synonym; the abbreviation