diff options
Diffstat (limited to 'Build/source/utils/asymptote/doc/asymptote.texi')
-rw-r--r-- | Build/source/utils/asymptote/doc/asymptote.texi | 109 |
1 files changed, 87 insertions, 22 deletions
diff --git a/Build/source/utils/asymptote/doc/asymptote.texi b/Build/source/utils/asymptote/doc/asymptote.texi index 6fd28e78456..9a2d6baa88b 100644 --- a/Build/source/utils/asymptote/doc/asymptote.texi +++ b/Build/source/utils/asymptote/doc/asymptote.texi @@ -382,8 +382,8 @@ The @code{ImageMagick} package from @url{http://www.imagemagick.org/script/binary-releases.php} @noindent -is required to support output formats other than @acronym{EPS} and -@acronym{PDF} (@pxref{convert}). +is required to support output formats other than @acronym{EPS}, +@acronym{PDF}, @acronym{SVG}, and @acronym{PNG} (@pxref{convert}). The @code{Python} interpreter from @url{http://www.python.org} is only required if you wish to try out the graphical user interface (@pxref{GUI}). @@ -532,7 +532,7 @@ under @code{Microsoft Windows XP}: @enumerate @item Click on the @code{Start} button; @item Right-click on @code{My Computer}; -@item Choose @code{Properties} from the popup menu; +@item Choose @code{View system information}; @item Click the @code{Advanced} tab; @item Click the @code{Environment Variables} button. @end enumerate @@ -788,14 +788,19 @@ application for the extension @code{asy}). @noindent @cindex @code{-V} This method, known as @emph{batch mode}, outputs a @code{PostScript} -file @code{test.eps}. The @code{-V} option opens up a @code{PostScript} -viewer window so you can immediately view the result: +file @code{test.eps}. If you prefer @acronym{PDF} output, use +the command line +@verbatim +asy -V -f pdf test +@end verbatim +In either case, the @code{-V} option opens up a viewer window so you +can immediately view the result: @sp 1 @center @image{diagonal} @cindex @code{bp} @noindent -The @code{--} connector joins the two points @code{(0,0)} and -@code{(100,100)} with a line segment. +Here, the @code{--} connector joins the two points @code{(0,0)} and +@code{(100,100)} with a line segment. @section Drawing in interactive mode Another method is @emph{interactive mode}, where @code{Asymptote} reads @@ -3260,12 +3265,14 @@ If exactly one of @code{x} or @code{y} is 0, no size restriction is imposed in that direction; it will be scaled the same as the other direction. +@cindex @code{keepAspect} @cindex @code{Aspect} If @code{keepAspect} is set to @code{Aspect} or @code{true}, the picture will be scaled with its aspect ratio preserved such that the final width is no more than @code{x} and the final height is no more than @code{y}. +@cindex @code{keepAspect} @cindex @code{IgnoreAspect} If @code{keepAspect} is set to @code{IgnoreAspect} or @code{false}, the picture will be scaled in both directions so that the final width @@ -3668,6 +3675,10 @@ will be set to the end-of-file, and both reading and writing operations will be enabled. For security reasons, writing to files in directories other than the current directory is allowed only if the @code{-globalwrite} (or @code{-nosafe}) command-line option is specified. +@cindex @code{mktemp} +The function @code{string mktemp(string s)} may be used to create and +return the name of a unique temporary file in the current directory +based on the string @code{s}. @cindex @code{stdin} @cindex @code{stdout} @@ -3691,6 +3702,8 @@ write(file file, suffix suffix=none); @cindex @code{flush} @cindex @code{endl} @cindex @code{newl} +@cindex @code{DOSendl} +@cindex @code{DOSnewl} @cindex @code{tab} @cindex @code{comma} If @code{file} is not specified, @code{stdout} is used and @@ -3701,6 +3714,8 @@ or one-dimensional arrays. The @code{suffix} may be one of the following: @code{none} (do nothing), @code{flush} (output buffered data), @code{endl} (terminate with a newline and flush), @code{newl} (terminate with a newline), +@code{DOSendl} (terminate with a DOS newline and flush), +@code{DOSnewl} (terminate with a DOS newline), @code{tab} (terminate with a tab), or @code{comma} (terminate with a comma). Here are some simple examples of data output: @verbatim @@ -4631,6 +4646,16 @@ write(f(4,3)); @noindent and outputs 43. +@cindex @code{keyword} +@cindex keyword-only +Parameters can be specified as ``keyword-only'' by putting @code{keyword} +immediately before the parameter name, as in @code{int f(int keyword x)} or +@code{int f(int keyword x=77)}. This forces the caller of the function to use +a named argument to give a value for this parameter. That is, @code{f(x=42)} +is legal, but @code{f(25)} is not. Keyword-only parameters must be listed +after normal parameters in a function definition. + + As a technical detail, we point out that, since variables of the same name but different signatures are allowed in the same scope, the code @verbatim @@ -4715,6 +4740,17 @@ If no arguments are packed, then a zero-length array (as opposed to arguments are ignored for rest formals and the rest argument is not bound to a keyword. +In some cases, keyword-only parameters are helpful to avoid arguments intended +for the rest parameter to be assigned to other parameters. For example, here +the use of @code{keyword} is to avoid @code{pnorm(1.0,2.0,0.3)} matching +@code{1.0} to @code{p}. +@verbatim +real pnorm(real keyword p=2.0 ... real[] v) +{ + return sum(v^p)^(1/p); +} +@end verbatim + The overloading resolution in @code{Asymptote} is similar to the function matching rules used in C++. Every argument match is given a score. Exact matches score better than matches with casting, and @@ -5081,9 +5117,10 @@ themselves (in which case they are each initialized to empty arrays). @cindex @code{array} @item T[] array(int n, T value, int depth=intMax) -returns an array consisting of @code{n} deep copies of a 0, 1, or 2 -dimensional array @code{T value}. If @code{depth} is specified, this -deep copying recurses to no more than the number of levels specified. +returns an array consisting of @code{n} copies of @code{value}. +If @code{value} is itself an array, a deep copy of @code{value} is made +for each entry. If @code{depth} is specified, this deep copying only +recurses to the specified number of levels. @cindex @code{sequence} @item int[] sequence(int n) @@ -5931,7 +5968,7 @@ to the type. This is regardless of what fields the variable actually possesses. @cindex @code{asymptote.sty} @code{Asymptote} comes with a convenient @code{LaTeX} style file -@code{asymptote.sty} (version 1.15 or later) that makes @code{LaTeX} +@code{asymptote.sty} that makes @code{LaTeX} @code{Asymptote}-aware. Entering @code{Asymptote} code directly into the @code{LaTeX} source file, at the point where it is needed, keeps figures organized and avoids the need to invent new file @@ -5940,8 +5977,7 @@ names for each figure. Simply add the line and enclose your @code{Asymptote} code within a @code{\begin@{asy@}...\end@{asy@}} environment. As with the @code{LaTeX} @code{comment} environment, the @code{\end@{asy@}} command -must appear on a line by itself, with no leading spaces or trailing -commands/comments. +must appear on a line by itself, with no trailing commands/comments. The sample @code{LaTeX} file below, named @code{latexusage.tex}, can be run as follows: @@ -5959,11 +5995,11 @@ asy latexusage-*.asy pdflatex latexusage @end verbatim @noindent -To switch between using @code{latex} and @code{pdflatex} you may first -need to remove the files @code{latexusage-*}, @code{latexusage.pre}, and -@code{latexusage.aux}. +To switch between using inline Asymptote code with @code{latex} and +@code{pdflatex} you may first need to remove the files @code{latexusage-*.tex}. @cindex @code{latexmk} +@cindex @code{perl} An even better method for processing a @code{LaTeX} file with embedded @code{Asymptote} code is to use the @code{latexmk} utility from @quotation @@ -5981,16 +6017,26 @@ latexmk -pdf latexusage will then call @code{Asymptote} automatically, recompiling only the figures that have changed. Since each figure is compiled in a separate system process, this method also tends to use less memory. +External @code{Asymptote} code in @code{filename.asy} should be included with +@cindex @code{asyinclude} +@verbatim +\asyinclude[<options>]{<filename.asy>} +@end verbatim +@noindent +so that @code{latexmk} will recognize when the code is changed. Note that +@code{latemk} requires @code{perl}, available from @url{http://www.perl.org/}. @cindex @code{width} @cindex @code{height} +@cindex @code{keepAspect} @cindex @code{viewportwidth} @cindex @code{viewportheight} @cindex @code{attach} @cindex @code{inline} -One can specify @code{width}, @code{height}, +One can specify @code{width}, @code{height}, @code{keepAspect}, @code{viewportwidth}, @code{viewportheight}, @code{attach}, and @code{inline}. -@code{keyval}-style options to the @code{asy} environment. +@code{keyval}-style options to the @code{asy} and @code{asyinclude} +environments. Three-dimensional @acronym{PRC} files may either be embedded within the page (the default) or attached as annotated (but printable) attachments, using the @code{attach} option and the @code{attachfile2} @@ -7493,21 +7539,29 @@ Here is an example that uses logarithmic scaling of the function values: @sp 1 @center @image{logimage} -One can also draw an image directly from a two-dimensional pen array: +One can also draw an image directly from a two-dimensional pen array +or a function @code{pen f(int, int)}: @verbatim void image(picture pic=currentpicture, pen[][] data, pair initial, pair final, bool transpose=(initial.x < final.x && initial.y < final.y), bool copy=true, bool antialias=false); +void image(picture pic=currentpicture, pen f(int, int), int width, int height, + pair initial, pair final, bool antialias=false); @end verbatim @noindent -as illustrated in the following example: +as illustrated in the following examples: @anchor{penimage} @verbatiminclude penimage.asy @sp 1 @center @image{penimage} +@anchor{penfunctionimage} +@verbatiminclude penfunctionimage.asy +@sp 1 +@center @image{penfunctionimage} + For convenience, the module @code{palette} also defines functions that may be used to construct a pen array from a given function and palette: @verbatim @@ -8273,6 +8327,16 @@ Module @code{three} also defines the three-dimensional margins @code{BeginDotMargin3}, @code{EndDotMargin3}, @code{DotMargin3}, @code{DotMargins3}, @code{Margin3}, and @code{TrueMargin3}. +@cindex @code{pixel} +The routine +@verbatim +void pixel(picture pic=currentpicture, triple v, pen p=currentpen, + real width=1); +@end verbatim +@noindent +can be used to draw on picture @code{pic} a pixel of width @code{width} at +position @code{v} using pen @code{p}. + Further three-dimensional examples are provided in the files @code{near_earth.asy}, @code{conicurv.asy}, and (in the @code{animations} subdirectory) @code{cube.asy}. @@ -9568,11 +9632,12 @@ Mark Henning, Steve Melenchuk, Martin Wiebusch, and Stefan Knorr. @c LocalWords: vectorfieldsphere RightView FrontView BackView BottomView CTZ @c LocalWords: addViews outprefix addAllViews xsplinetype ysplinetype rotateX @c LocalWords: usplinetype vsplinetype leftbutton middlebutton rightbutton -@c LocalWords: rotateY rotateZ wheelup zoomin wheeldown zoomout TeXLive +@c LocalWords: rotateY rotateZ wheelup zoomin wheeldown zoomout TeXLive pnorm @c LocalWords: viewportshift signedint signedness psview multiplatform nowarn @c LocalWords: singlereal singleint writeoverloaded dvisvg reddash lexorder @c LocalWords: bigdiagonal autobillboard dvisvgm maxtiles hyperrefOptions @c LocalWords: setpagesize pdfborder controlsystem OmitTickInterval SixViews @c LocalWords: OmitTickIntervals tickmodifiers autorotated SixViewsUS latexmk @c LocalWords: ThreeViewsUS ThreeViewsFR SixViewsFR ThreeViews partialsum -@c LocalWords: defaultrender Vidiassov latexmkrc +@c LocalWords: defaultrender Vidiassov latexmkrc mktemp DOSendl DOSnewl perl +@c LocalWords: filename asyinclude latemk penfunctionimage |