2.4 Configuring

In interactive mode, or when given the -V option (the default when running Asymptote on a single file under MSDOS), Asymptote will automatically invoke the PostScript viewer gv (under UNIX) or gsview (under MSDOS to display graphical output. These defaults may be overridden with the configuration variable psviewer. The PostScript viewer should be capable of automatically redrawing whenever the output file is updated. The default UNIX PostScript viewer gv supports this (via a SIGHUP signal). Version gv-3.6.3 or later (from http://ftp.gnu.org/gnu/gv/) is required for interactive mode to work properly. Users of ggv will need to enable Watch file under Edit/Postscript Viewer Preferences. Users of gsview will need to enable Options/Auto Redisplay (however, under MSDOS it is still necessary to click on the gsview window; under UNIX one must manually redisplay by pressing the r key).

Configuration variables are most easily set as Asymptote variables in the configuration file (by default, .asy/config.asy in the user's home directory or %USERPROFILE%\.asy\config.asy under MSDOS); see configuration file. Here are the default values of several important configuration variables under UNIX:

import settings;
psviewer="gv";
pdfviewer="acroread";
gs="gs";
python="";

The (installation-dependent) default values of these configuration variables under MSDOS are determined automatically from the Microsoft Windows registry.

For PDF format output, the gs setting specifies the location of the PostScript-to-PDF processor Ghostscript, available from http://sourceforge.net/projects/ghostscript/.

The setting pdfviewer specifies the location of the PDF viewer. On UNIX systems, to support automatic document reloading in Adobe Reader, we recommend copying the file reload.js from the Asymptote system directory (by default, /usr/local/share/asymptote under UNIX to ~/.adobe/Acrobat/x.x/JavaScripts/, where x.x represents the appropriate Adobe Reader version number. The automatic document reload feature must then be explicitly enabled by putting

import settings;
pdfreload=true;
pdfreloadOptions="-tempFile";

in the Asymptote configuration file. This reload feature is not useful under MSDOS since the document cannot be updated anyway on that operating system until it is first closed by Adobe Reader.

The graphical user interface may also require setting the variable python if Python is installed in a nonstandard location.

The configuration variable dir can be used to adjust the search path (see section Search paths).

By default, Asymptote attempts to center the figure on the page, assuming that the paper type is letter. The default paper type may be changed to a4 with the configuration variable papertype. Alignment to other paper sizes can be obtained by setting the configuration variables paperwidth and paperheight.

The following configuration variables normally do not require adjustment:

texpath
texcommand
texdvicommand
dvips
convert
display
animate
xasy

The texdvicommand is used for 3D label typesetting, which requires dvips output. An empty string indicates the default setting of latex/tex, depending on the setting of texengine.

Configuration variables may also be set or overwritten with a command-line option:

asy -psviewer=gsview -V venn

Alternatively, system environment versions of the above configuration variables may be set in the conventional way. The corresponding environment variable name is obtained by converting the configuration variable name to upper case and prepending ASYMPTOTE_: for example, to set the environment variable

ASYMPTOTE_PSVIEWER="C:\Program Files\Ghostgum\gsview\gsview32.exe";

under Microsoft Windows XP:

1. Click on the Start button;
2. Right-click on My Computer;
3. Choose Properties from the popup menu;
4. Click the Advanced tab;
5. Click the Environment Variables button.