summaryrefslogtreecommitdiff
path: root/Build/source/utils/asymptote/doc/asymptote.texi
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-08-15 23:57:48 +0000
committerKarl Berry <karl@freefriends.org>2009-08-15 23:57:48 +0000
commit16d128e5e10d541a78654b86409d5a3539f07708 (patch)
tree66de0af63c3811bb3040c16e9b52c11985f70811 /Build/source/utils/asymptote/doc/asymptote.texi
parentb20f78c549859ec0e8610bdd3ad904245e86b489 (diff)
asymptote 1.83
git-svn-id: svn://tug.org/texlive/trunk@14696 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/utils/asymptote/doc/asymptote.texi')
-rw-r--r--Build/source/utils/asymptote/doc/asymptote.texi182
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