.\" @(#)manual	1.3 12/6/91
.H1 "VEM (version 8.1)"
.pp
.EQ
delim off
.EN
VEM 
is an interactive graphics shell/editor for designs represented in
the
.BO Oct
CAD/VLSI data representation system.
The primary purpose of
VEM
is to provide a means of looking at the graphics representation of
.BO Oct
views and invoking various CAD tools on these views.
\*(PT is such a CAD tool, invoked via a program called \fIpigiRpc\fR.
.IE "pigiRpc"
.IE Oct
VEM
was originally intended for IC design.  As such
VEM
provides standard graphics editing capabilities for physical (mask-level),
symbolic, and schematic designs.  \*(PT uses schematic
.IE "physical mode"
.IE "schematic mode"
.IE "symbolic mode"
capabilities for applications and physical capabilities
for icons.  Some understanding
of the terminology of the
.BO Oct
data manager is required to use
VEM.  This terminology is explained in the pigi section of the Almagest.
.pp
VEM
is a multi-window
application designed to run on bitmap based graphics workstations.
VEM
will run on any such system that has a reasonably complete implementation
of the
.I X
Window System version 11 release 4 or later.
.IE "X Window system"
Currently,  there are 
.I X 
implementations for a wide range of desktop workstations
including all DEC and Sun Microsystems computers
as well as some HP, Apollo, and Masscomp computers.
Currently,
\*(PT has only been tested on DEC and Sun Miscrosystems computers.
.pp
VEM
may be started by simply typing
"vem", but this will not start \*(PT.
To start the \*(PT interactive graphical interface, simply execute the
command pigi in ~ptolemy/bin.
This invokes a shell script that starts VEM and the
associated pigiRpc process.
VEM is started in general with the following command line options:
.(c
vem [-F cell[:view[:facet]]] [-G WxH+X+Y] [-R [host,]path] \\\\
	[-display host:display] [name=value ...]
.)c
.IE "VEM command line"
As an example, the main part of the pigi script reads:
.(c
if (!($?PIGIRPC)) then
	setenv PIGIRPC ~ptolemy/bin.$ARCH/pigiRpc
endif
xrdb -m ~ptolemy/lib/pigiXRes8
vem -G 600x150+0+0 -F init.pal:schematic \\\\
	-G 600x300+0+170 -R $PIGIRPC
.)c
The first three lines set the PIGIRPC environment variable to point
to the correct executable.  The next line merges the X Windows
resources defined in ~ptolemy/lib/pigiXRes8.
The last line starts VEM.
.pp
VEM
looks at the value of the DISPLAY environment variable to determine
what host and display to use for output.
VEM and pigi
may be run in the background without affecting the program operation.
.pp
The 
.BO -F, 
.BO -G,
and 
.BO -R
command line options allow a user to specify a certain
startup window configuration for VEM.
These three options are considered triplets that specify the initial cell, 
position and size, and remote application respectively for a window.
There is no limit to the number of triplets that may be specified.
The 
.BO -F
flag marks the start of each new triplet.  The corresponding
.BO -G 
and 
.BO -R 
flags after the 
.BO -F 
flag are optional.  If the 
.BO -G 
flag is omitted,
VEM will not specify a location for the window and most window
managers will interactively prompt for the window location.
If the 
.BO -R 
flag
is omitted,  no remote application will be started in the window.
The 
.BO -F 
flag can be omitted from the first triplet.  In this case, the
.BO -G 
and 
.BO -R 
flags apply to the console window.
For example,  the pigi script above starts VEM with its console window
at (0,0) with a size of 600 by 150,  and one window looking at
the cell "init.pal:schematic" at (0,170) with a size of 600 by 300, running
the "pigiRpc" remote application.
.pp
VEM is a highly customizable editor.  Nearly all of the colors, font
styles and fill patterns VEM uses can be changed by the user.
Normally, these parameters are read from the user's X resources
(usually kept in the files ~/.Xdefaults or ~/.Xresources).  However,
one can set certain parameters on the command line using the = (equal)
command line option.
A list of all configurable parameters can be found in the section
"Customizing VEM".
.pp
If no location for the console window is provided on the command line,
VEM will not specify a location for the console window and most window
managers will interactively prompt for a console window location.
This window echoes user input and outputs various help and status messages.  
After starting,  the
console will display a prompt and wait for input.
.pp
If the init.pal facet does not exist in the directory in which pigi is
started, then it will be created.  A blank cell will appear.
Convention in \*(PT dictates that this facet should be used to store
icons representing complete applications, or universes, that are defined
in the directory.
If such icons already exist in the init.pal facet, the applications can
be examined using the pigi "look-inside" command.
.pp
New windows can be
created using
.I open-facet
command (see the pigi command reference).  
Note that these windows will be connected to the pigiRpc process.
It is also possible to open a window from the VEM console using
the
.I open-window
command, but this new window will not be attached to pigiRpc
(see the command reference below).
Each window has exactly
one associated cell.  
Mouse action with the cursor positioned inside
a window cause operations to occur to the window's associated cell.
Any number of windows can be created with the same or different
associated cells.  
More than one window may have the same associated
cell.
In this case,  all of the windows are attached to the
.I same
cell.  
Thus,  a change to one of the windows may cause updates
to other windows which look at the same cell.
.pp
VEM assumes the presence of a three-button mouse.  
The left button is used for entry of graphics information.  
The middle button is used for the primary menu of commands.  
The right button is used to modify graphics information entered using
the left button.
.pp
Commands to VEM are specified in post-fix form.  
The user
builds an argument list first and then selects a command.  
Commands can be selected in four ways:  pop-up menus,  single
keystrokes,  using the last command button, or by typing in the command name.
Pressing and releasing the middle button in a graphics window causes
a VEM menu to appear.  
The user can use the mouse to riffle through
the options until the desired choice is highlighted.  
Pressing and releasing the mouse button activates the selected command.  
Pressing and releasing the mouse outside the menu cancels the selection.  
Normally,  pressing and releasing the middle button causes a VEM
menu to appear.  
Holding the shift key and clicking the middle button causes the
pigi menu to appear.  Both menus are useful.
.IE menus
.pp
A number of common commands
can be selected via a single keystroke.  
Key bindings for various commands are 
shown next to the corresponding entry in the VEM menu,
are listed in the command reference below,
and can be queried interactively using the
.I bindings
command.
Finally,  typing a colon (:) allows
the user to type in the command name (or a user defined alias).  
The standard line editing keys can be used while typing the command name.
.pp
The interface supports automatic command completion.  
.IE "command completion"
Typing a
tab will complete the command if it is unique or offer a list of
alternatives if it is not unique.  
The command is selected by
typing a carriage return.
.pp
There are five types of input to VEM:  points, boxes, lines, text,
and objects.  
.IE "VEM arguments"
Points are entered by pressing and releasing the left
button of the mouse.  
Boxes are entered by pressing, dragging, and
releasing the left button.  
Lines are entered by pressing, dragging
and releasing the left button over a previously created point or
line.  
Text is entered by typing the text enclosed in double 
quotes.
If entering a filename,  typing a TAB character will cause VEM
to try to complete the name if it is unique or offer a list of
alternatives if it is not unique.
Objects are entered using the 
.I select-objects 
and 
.I unselect-objects 
commands.
The last item on an argument list can be deleted using the standard
character for delete.  The last group of items can be deleted using
the word erase character control-W.  The entire argument list can be
deleted using the standard kill-line character (usually control-X or 
control-U).
.pp
Once entered, graphics arguments (points, boxes, and lines) can be 
modified in various ways.  
For all arguments,  a point can be moved
by moving the cursor over the point
and pressing, dragging, and releasing the right mouse button.
New points can be added to a group of lines by moving over a point
in the segment,
depressing, dragging, and releasing the left mouse button.  
This will
insert a new point after the point.
It is also possible to interactively move, rotate, and mirror objects 
arguments (selected items).  
See the description of the
.I transform
command in the command reference below.
.pp
This version of VEM supports three basic editing styles:  
physical, symbolic, and schematic.
Physical editing involves the entry and editing of basic geometry
and the creation of interface terminals.  
This style is used in pigi to
build icons.
Symbolic editing involves the placement of
instances of leaf cells and the interconnection of these instances.  
Pigi does not use symbolic editing.
Schematic editing is an extension of symbolic where the primitive
cells are schematic symbols and wire width is insignificant.
Schematic cells use used by pigi to represent block diagrams.
.pp
When VEM opens a new cell,  a dialog will appear asking for
three property values:  TECHNOLOGY, VIEWTYPE, and EDITSTYLE.
The TECHNOLOGY and VIEWTYPE properties determine the location
of the technology facet (see tap(3)).  
A standard technology facet has been designed for \*(PT, so the
defaults that appear are almost always acceptable.
Layer display and design
rule information is read from this facet.  
The EDITSTYLE property is used by VEM to determine the set of
commands available for editing the cell.  
Currently,  the
legal editing styles are PHYSICAL, SYMBOLIC, or SCHEMATIC.
.H2 "Using Dialog Boxes"
.pp
Some commands require information that cannot be expressed easily
using post-fix notation.  Examples include destructive commands
that require an explicit confirmation and commands that require complex
non-graphic information.  VEM uses
.I dialog boxes
to handle these situations.  
Dialog boxes are windows that resemble business forms.
These windows contain labeled fields for entering text, changing
numerical values, and selecting options.
This section describes how to use dialog boxes.
.pp
All dialog boxes in VEM have the same form.  
At the top of all dialogs is a one line title indicating the purpose
for the dialog.
The middle of the dialog (known as the body) contains fields for
displaying and editing information of various kinds.
At the bottom of the dialog are a number of
.I control buttons.
Each control button represents a command.
The arguments to the command are the values of the fields displayed in
the body.
Thus, operating a dialog consists of editing or changing fields in the
body and then selecting a command by activating a control button.
Six kinds of fields may appear in the body of a VEM dialog: editable
text, non-editable text, enumerated value, numerical value, exclusive
lists, and non-exclusive lists.
A description of each field type is given in the paragraphs that follow.
.pp
Editable text fields are used to enter and edit text.  
Visually, an edit text field consists of a box containing a caret
cursor, an optional scrollbar, and a label to the left of the box
indicating the purpose for the field.
Only one editable text field is active in any one dialog.
The active editable text field has a dark border.
Typing text with the mouse positioned anywhere in the dialog inserts
text into the active editable text field.
Most of the basic emacs editing commands can be used to modify the
text in the field:
.TS
box, center;
cb cb | cb cb
c l | c l.
Key	Action	Key	Action
=
Ctrl-A	Beginning of Line	Ctrl-E	End of Line
_
Ctrl-B	Backward character	Ctrl-F	Forward character
_
Ctrl-N	Next line	Ctrl-P	Previous line
_
Ctrl-V	Next page	Meta-V	Previous page
_
Ctrl-D	Delete next character	Meta-D	Delete next word
_
Ctrl-K	Delete to end of line	Ctrl-S	Search forward
_
Ctrl-Y	Yank deleted text	Meta-I	Include file
.TE
The insert position in the field may also be changed by pressing the
left mouse button when the mouse cursor is over the desired position.
Any editable text field can be made active by clicking the left mouse
button inside the editable area.
Alternatively, one can use the <Tab> key to make the next text field
active and <Meta-Tab> to make the previous field active.
Editable text fields that display large amounts of text have a
scrollbar to the left of the text area.  
Pressing the left and right
mouse buttons when the mouse cursor is in a scrollbar will scroll the
text down and up respectively in proportion to the distance between
the mouse cursor and the top of the scrollbar.
As an example, pressing the left mouse button near the bottom of the
scrollbar will scroll down the text almost one screen.
Pressing and releasing the middle mouse button scrolls the text to
a relative position based on how far the mouse cursor is from the top
of the scrollbar.
Holding down the middle mouse button will interactively scroll through
the text.
.pp
Non-editable text fields are used to display text messages.
They consist of a box containing text and an optional scrollbar.
The scrollbar operates just like those used in editable text fields.
.pp
Enumerated value fields are used to specify one value out of a small
list of values.
They consist of a value displayed
inside a box and a descriptive label to the left of the value.
The border of the value highlights as the mouse cursor moves over it.
Depressing and holding the left mouse button inside the value box
causes a menu to appear that displays all possible values.
The choices will highlight as the mouse cursor moves over them.
To select a new value, release the mouse button when the desired
choice is highlighted.  The new value will appear in the value box.
One can leave the value unchanged by releasing the mouse button
outside the menu boundary.
.pp
The numerical value field is used to specify a magnitude between a
predetermined minimum and maximum.
Visually, it consists of a box containing a numerical value, a
horizontal scrollbar to the right of the box for changing the value,
and a label to the left describing the value.
The magnitude of the value is changed by operating the scrollbar.
Pressing the left and right buttons in the scrollbar decrement and
increment the value by one unit.
Pressing the middle button changes the value based on the distance
between the mouse cursor and the left edge of the scroll bar.
The middle button may be pressed and held to interactively modify the
value. 
Most people use the middle button to set the value roughly then use
the left and right buttons to make the value precise.
.pp
Exclusive lists are used to choose one possible value out of a
(possibly quite large) list of values.
These values are displayed in a box with a scrollbar on the left edge
of the box.
Each value consists of a button box on the left and a descriptive label
to the right.
As the mouse moves over a button box, it will highlight to indicate it
can be activated.
The button box of the selected item will appear dark while all others
will remain light.
If there are too many values to display in the box at one time, the
scrollbar can be used to scroll through the possible values.
The scrollbar operates in the same way as described for editable text
fields.
.pp
Non-exclusive lists are used to choose zero or more possible values
from a (possibly quite large) list of values.
A non-exclusive list resembles an exclusive list both in appearance
and operation.
However, unlike an exclusive list, one can choose any number of items
in a non-exclusive list.
Visually, the two lists are distinguished by the appearance of the
button boxes.
Exclusive button boxes resemble radio buttons.  Non-exclusive button
boxes resemble check marks.
Pressing the left button in a non-exclusive button box causes the
value to toggle (i.e., if it was selected it becomes unselected, if it
was unselected it becomes selected).
.pp
Control buttons cause the dialog to carry out some operation.
They consist of a text label surrounded by a box.
Control buttons are activated in one of two ways:
pressing and releasing the left mouse button when the mouse cursor is
positioned inside the button boundary, and through keystrokes.
Not all control buttons can be activated using keystrokes.
Those that can be activated in this fashion display the key in
parentheses under the button label.
Although there are exceptions, most dialogs support the following
keyboard accelerators:
.TS
box, center;
cb cb
c l.
Keys	Action
=
<Ret>,<Meta-Ret>,<F1>	Ok
_
<Del>,<Meta-Del>,<F2>	Cancel
_
<Help>,<F3>	Help
_
<F4>	All
_
<F5>	Clear
.TE
.pp
Dialogs may be both
.I moded
and
.I unmoded.
Moded dialogs are those requiring a response before processing can
proceed.
VEM uses these kinds of dialogs to ask for confirmation before
proceeding.
On the other hand, unmoded dialogs remain active until explicitly
dismissed by the user.
Other commands may be invoked freely while unmoded dialogs are
visible.
Most non-confirmation dialogs in VEM are unmoded.
.H2 "General Commands"
.pp
Below is a reference for all VEM commands.  
The first section outlines
general commands available for editing all types of cells.  
The next section describes the general selection mechanism.  
The third section describes property and bag editing features.
The next three sections describe editing commands for physical, symbolic,
and schematic cells respectively.
The summary includes the
name of the command as it appears on a menu, if it appears in the menu.
The command name can be typed in as well.  Place the mouse in the window
where you wish to execute the command, enter the command arguments
(points, objects, etc.), type a colon ``:'', and type
the command name.
The TAB character will automatically complete command names.
The phrase <no-name> implies it has no default menu or command name binding,
.pp
The list below also shows the
default keyboard
binding for each command, if it has one,
and the syntax of the argument list passed to it.
The symbol <*> implies the command has no default key binding.
In general,  the commands
used most often have key and menu bindings.  
Less often used commands may have
only command name bindings.
.pp
Some VEM commands are not documented here because they are dangerous
or conflict with the objectives of pigi.  Those commands will not appear
in the VEM menu, and have no key binding,
although all are still available by typing them in.
Adventurous users may wish to consult the standard
Octtools documentation before using them.
.pp
.TS
lw(20)b lw(10)b lb.
<no-name>	<del>,^H	Any Argument List
.TE
.in +0.5i
This command deletes the last item of the last argument on the
argument list.  Thus,  if the last argument is 10 boxes,  it
will delete the last box entered and the argument list will be
modified to contain 9 boxes.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
<no-name>	^W	Any Argument List
.TE
.in +0.5i
This command is similar to the one above, but deletes the entire last argument
on the argument list.   Thus,  if the last argument is 5 lines,
it will delete all 5 lines and leave the remaining arguments
unchanged.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
<no-name>	^X or ^U	Any Argument List
.TE
.in +0.5i
This command erases the entire argument list allowing the user
to start over.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
bindings	b	Saves Arguments
.TE
.IE "bindings, VEM"
.in +0.5i
This command asks the user for a command and displays all of its
current key, menu, and alias bindings.  The command will display
a prompt (vem bindings> ) and the user can specify a command using
any of the four means of normally specifying commands (via menu,
single keystroke, type-in, or last command).
The command also outputs a one line description of the command
for help purposes.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
close-window	^D	No Arguments
.TE
.IE "close-window, VEM"
.in +0.5i
The 
.I close-window
command closes the window the cursor was in when the command
was invoked.  This DOES NOT flush the contents of the window to disk.
Even after all windows looking at a facet are closed,  the contents
are not saved on disk.  This must be done using the 
.I save-window
or 
.I save-all
commands.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
deep-reread	<*>	[objs]
.TE
.IE "deep-reread, VEM"
.in +0.5i
The
.I deep-reread
command is a specialized form of the re-read command.  With no arguments,
it re-reads a facet and all of master facets of its subcells (instances).
Both the contents and interface facets of the instances are re-read.
If a set of objects is specified,  the command re-reads the master
cells of the instances in the object set.  Only the master cells of
the instances are re-read;  cells are not re-read recursively when
using this form.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
interrupt	^C	No arguments
.TE
.IE "interrupt, VEM"
.in +0.5i
This routine interrupts (deactivates) the window containing the cursor.
No drawing will be done in the window until a full redraw requested
by the user (using pan, zoom, or redraw-window) is done.  
The key binding for this command
can also be used while a window is drawing to immediately
stop drawing in that window.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
kill-buffer	<*>	"cell view {facet} {version}"
.TE
.IE "kill-buffer, VEM"
.in +0.5i
The
.I kill-buffer
command flushes a facet out of memory
.I without
saving its contents.  
If the string specification of the facet is missing,  the facet
is determined by the window containing the cursor.
.I All
windows looking at this facet are destroyed.  There are no
key or menu bindings for the command and it will ask the user
for confirmation before carrying out the command.
.in -0.5i
.TS
lw(20)b lw(10)b lb.
log-bindings	<*>	Saves arguments
.TE
.IE "log-bindings, VEM"
.in +0.5i
The
.I log-bindings
command writes out a description of all type-in, menu, and key bindings for all
commands in the editing style of the window containing the cursor.
This description is written to the log file for the session.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
open-window	o	[box] or "cell:{view:{facet:{version}}}"
.TE
.IE "open-window, VEM"
.in +0.5i
The 
.I open-window
command is primary way to create new graphics windows in VEM.
It takes a string specifying the cell to open.  
When specifying the cell portion of the name,  typing a TAB
will attempt to complete the string as a file or offer alternatives
if the name is not unique.
If this string is
absent,  it will duplicate the window containing the cursor.  
Normally,  the extent of the duplicated window is the same as
the parent window.  However, if
the user specifies a box,  the duplicated window will be zoomed
to that extent (see zoom-in).
The string specifying the cell contains four fields.  The last three
are optional and default to "physical", "contents", 
and the null string respectively.
It is possible to specify your own defaults for these fields.  See
the customization document for details.
Newly created windows are always zoomed to contain all geometry in the cell.
If the cell does not exist,  it will be created.
When creating new cells,  VEM prompts the user for required cell
properties.  See the introduction for details.  Most of the time, the
defaults presented in this dialog are acceptable and activating the
.I Ok
button is sufficient to proceed.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
palette	P	{"palette-name"}
.TE
.IE "palette, VEM"
.in +0.5i
The
.I palette
command opens a new window onto a previously created facet which contains
standard layers or instances for a given technology.  This window can
be used to select layers for creating geometry or instances for
instantiation.
The command takes one argument:  the name
of the palette.  If omitted,  it defaults to "layer".
.sp 0.5
Palette cells are found using the function tapGetPalette (see
tap(3)).  For all standard technologies and viewtypes,  there is
a "layer" palette.  In the symbolic editing style,  there are
also "mosfet" and "connector" palettes which
display mosfets and connectors respectively.  In the schematic
editing style,  there are "device" and "gate"
palettes which contain device level and gate level schematic
primitives.  New palettes can be added easily.  See ``Customizing VEM''
for details.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
pan	p	[any arguments] [pnt]
.TE
.IE "pan, VEM"
.in +0.5i
The
.I pan
command centers the window containing the cursor around the last point
on the argument list.  The window will be redrawn so that the argument
list point is now the center of the window.  The point need not be
in the same window as the cursor.  Thus,  a user can point in a window
showing a large portion of a cell and invoke the command in
a more detailed window for a magnifying glass effect.  If the point
is omitted,  the command assumes the cursor position is also the
desired center point.  This is the fast way to pan in a single
window.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
pop-context	)	No Arguments
.TE
.IE "pop-context, VEM"
.in +0.5i
This command pops off an input context from the context stack
and replaces the current context with that context.  See the
.I push-context
command for details.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
push-context	(	No arguments
.TE
.IE "push-context, VEM"
.in +0.5i
This command pushes the current argument list context onto the context
stack and gives the user a new context.  This can be used to do other
commands while preserving entered arguments.  Note that the current
arguments remain displayed.  The old context can be restored using the
.I pop-context
command.
Four context levels are supported in the current version of VEM.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
push-master	<*>	{"facet"}
.TE
.IE "push-master, VEM"
.in +0.5i
The
.I push-master
command opens a new window on the master of the instance under the
mouse cursor.
This command can be used all editing styles.
If a facet name is supplied,  the command will use that facet
name instead of "contents".
In \*(PT, this command is rarely needed.  The \fIedit-icon\fR
command accomplishes the same objective.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
recover-facet	<*>	No Arguments
.TE
.IE "recover-facet, VEM"
.in +0.5i
Unless directed otherwise,
VEM saves all cells occasionally in case of a system crash or some
other unforseen disaster.
Whenever a new cell is opened, VEM checks to see if the last
automatically saved version is more recent than the user saved
version.
If the automatically saved version is more recent, a warning is
produced and the user version is loaded.
One can use the
.I recover-facet
command to replace the cell with the more recent automatically saved
version.
The command displays a dialog containing a list of all of the saved
versions.
Generally, there are two possible alternative versions for a cell.
The
.I autosave
version is written by vem automatically after a certain number of
changes to the cell.
The
.I crashsave
version is written when VEM detects a serious error.
Note that the crashsave version may itself be corrupt since a serious
error occurred just before it was written.
This command is destructive: it replaces the cell with the selected
alternate.
One can use the
.I Cancel
button to abort the recovery.
Before using the
.I recover-facet
command, it is often useful to view the alternate cells.
This can be done by specifying the version (either "autosave" or
"crashsave" as the last field in the cell specification to
.I open-window.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
re-read	<*>	No Arguments
.TE
.IE "re-read, VEM"
.in +0.5i
The
.I re-read
command flushes the facet associated with the window containing the
cursor out of memory and reads it back in from the disk.  This
can be used to see changes to a cell that were done outside VEM
or to revert back to the cell before changes were made.  This
is a dangerous command and VEM asks for confirmation before
proceeding.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
redraw-window	^L	[box]
.TE
.IE "redraw-window, VEM"
.in +0.5i
This command redraws the contents of the window containing the cursor.
It does not effect the argument list (i.e. it can be done regardless
of the argument list contents).  If a box is provided,  only the
portion of the window in the box is redrawn.  If the window is interrupted,
this command will reactivate it.  However,  if the box form is used,
VEM will only draw the specified area and leave the window deactivated.
This can be used to selectively draw portions of a deactivated window.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
same-scale	= 	[any arguments] [pnt]
.TE
.IE "same-scale, VEM"
.in +0.5i
This command changes the scale of the window containing the mouse to
the same scale as the window containing the last point on the argument
list.  It is commonly used to compare the sizes of two facets.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
save-window	S	[any arguments]
.TE
.IE "save-window, VEM"
.in +0.5i
This command saves the contents of the facet associated with the
window where the command was invoked.  It asks for confirmation
and does not effect the argument list.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
set-path-width	w	[box] [line] [point] or ["size string"]
.TE
.IE "set-path-width, VEM"
.in +0.5i
This command sets the current path width for a given layer on a
window-by-window basis.
It takes one argument which may be points, lines, boxes,
or text.  For points and lines,  the argument length must
be two.  The path width is set to the maximum manhattan
distance between the points.  For boxes,  only one box
is allowed at the new width is the larger of the two
dimensions.  For text, the string should contain the path
width in lambda.
If no width is specified,  the path width will be set to
the minimum layer width as specified in the technology.
.sp 0.5
The layer for the path width command is determined by looking
at the object under the cursor.
If there are objects on more than one layer under the cursor,
a dialog will be presented and the user should choose one
of the listed layers and press "OK" to continue.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
show-all	f	No Arguments
.TE
.IE "show-all, VEM"
.in +0.5i
The 
.I show-all
command causes VEM to zoom the window containing the cursor
so that all of the cell is displayed in the window.  The
key binding is an abbreviation for "full".  It does not effect
the argument list.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
switch-facet	<*>	["cell view {facet {version}}"] or [pnt]
.TE
.IE "switch-facet, VEM"
.in +0.5i
This command replaces the facet in the window containing the mouse
with a different facet.  The first form replaces the window's facet
with the named facet.  The second form replaces the window's facet
with the facet of the window containing the point.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
toggle-grid	g	No Arguments
.TE
.IE "toggle-grid, VEM"
.in +0.5i
The 
.I toggle-grid
command toggles the visibility of the grid in the window containing
the cursor.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
version	V	No arguments
.TE
.IE "version, VEM"
.in +0.5i
This command outputs the current version of Pigi
to the console window.  
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
where	?	No arguments
.TE
.IE "where, VEM"
.in +0.5i
The 
.I where 
command can be used to find out the position of the cursor
in terms of 
.BO Oct
units.  It also displays a textual representation
of the objects under the cursor.  The command can be issued while building an
argument list without effecting the list.
Alternatively,  if the argument list includes an object set,  the
where command will print textual descriptions of the selected items.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
write-window	W	"cell:view" [any arguments]
.TE
.IE "write-window, VEM"
.in +0.5i
The 
.I write-window
command saves the contents of the cell associated with the window where
the command was invoked under another name.
This alternate name is specified by the "cell:view" argument.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
zoom-in	z	[any arguments] [box]
.TE
.IE "zoom-in, VEM"
.in +0.5i
The 
.I zoom-in 
command zooms the window containing the mouse to the extent
indicated by the last box on the argument list.  The box
and the zoom window must be in the same facet.  
However,  the extent may be in a different window from the mouse
which can be used to achieve a magnifying glass effect.
If the box is not provided,  it zooms the window containing
the mouse in by a factor of two.  If provided,  the command removes the box
from the argument list but leaves other arguments untouched.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
zoom-out	Z	[any arguments] [box]
.TE
.IE "zoom-out, VEM"
.in +0.5i
The 
.I zoom-out 
command is the opposite of zoom-in.  This command zooms
the window containing the mouse out far enough so that the OLD
contents of the window are contained in the extent of the box
provided on the argument list.  Thus,  smaller boxes zoom out
farther than larger ones.  If the box is omitted,  the window
containing the mouse is zoomed out by a factor of two.
.in -0.5i
.H2 "Options"
.pp
The options commands below all post form windows which allow a user
to change display parameters interactively.  The default values
for these parameters can be changed in your ~/.Xdefaults file.
See "Customizing VEM" for details.
.pp
All of the options dialogs below are
.I unmoded.
This means that the user can do other things while the dialog is
posted.  They will not go away until explicitly closed by the user.
Details on the operation of dialog boxes can be found in the section
.I Using Dialog Boxes
at the start of the manual.
.TS
lw(20)b lw(10)b lb.
window-options	<*>	No arguments
.TE
.IE "window-options, VEM"
.in +0.5i
This command posts a dialog which presents a number of window related
options each of which can be modified by the user on a window-by-window
basis.  Two kinds of options are presented in this dialog: flag options
and value options.  Flag options have a check box on the left of
the option and can be either on or off.  Pressing the left mouse button
in the check box toggles the value of the option.
Value options display a numerical value in a box with a descriptive
label to the left and a scrollbar to the right for changing the value.
At the bottom of the dialog are four control buttons: 
.I OK,
.I Dismiss,
.I Apply,
and
.I Help.
Pressing the left mouse button inside the
.I OK
button saves any options you may have changed and closes the window.
The
.I Dismiss
button does not save any options and closes the window.
The
.I Apply
button saves any changed options but does not close the window.
The
.I Help
button will open a window containing a brief description
of the dialog.
.sp 0.5
Each of the options and their meanings are given below:
.IP "Visible Grid"
If set, a grid will be shown in the window.
.IP "Dotted Grid"
If the grid is visible and this option is set,
the grid will be drawn as dots rather than
lines.
.IP "Manhattan Argument Entry"
If this option is set, entering line arguments and dragging
option sets will be restricted to manhattan angles.  This
option is set by default in the symbolic and schematic
editing styles.
.IP "Argument Gravity"
If set,  all lines entered using the left button whose endpoints
are near an actual terminal will be snapped to that terminal.
This is especially useful when editing
schematic diagrams (VEM automatically turns this option on
when the edit style is set to schematic).
The .Xdefault parameter
.I vem.gravity
specifies the maximum distance 
between line endpoints and terminals
for gravity to have an effect (by default, 10 pixels).
.IP "Show Instance Bounding Boxes"
If this option is set,  VEM will display bounding boxes
around all instances.
The instance name will be displayed in the center of
these bounding boxes.
.IP "Show Actual Terminals"
When viewing very large designs, drawing the highlighting around actual terminals
can be expensive.  If this option is turned off,  VEM
will not draw highlighting around actual terminals.
.IP "Expand Instances"
If on,  the contents facet of instance masters will be displayed.
Otherwise,  the interface facet will be displayed.  This has
the same effect as the
.I toggle-expansion
command.
.IP "Visible Title Bar"
If this option is set,  VEM will display its own title bar above each
graphics window.  If the option is turned off,  the title bar will
be turned off.
.IP "Oct units per Lambda"
This parameter specifies the number of 
.BO Oct 
units per lambda.  The
output of the where command and the coordinate displays in the title
bar are displayed according to the value of this parameter.  By default,
VEM uses 20 
.BO Oct 
units per lambda.
.IP "Snap"
All graphic input into the window will be snapped to multiples of
this parameter (given in 
.BO Oct
units).  By default,  VEM snaps to
one lambda (20 
.BO Oct
unit) intervals.
.IP "Major Grid Spacing"
This parameter specifies the grid spacing of major grid lines
in 
.BO Oct 
units.  If logarithmic grids are turned on,  it specifies
a multiplying factor for major grid line spacing (see Base below).
.IP "Minor Grid Spacing"
This parameter specifies the grid spacing of minor grid lines
in 
.BO Oct 
units.  If logarithmic grids are turned on,  it specifies
a multiplying factor for minor grid line spacing (see Base below).
.IP "Minimum Grid Threshold"
This parameter specifies the smallest allowable space (in pixels) 
between grid lines before VEM stops drawing them.
.IP "Log Grid Base"
If non-zero,  this option selects a logarithmic grid.  Normally,
there are two grids drawn at a fixed number of 
.BO Oct 
units (major
and minor grid lines).  In a logarithmic grid,  grids are drawn at
some constant (specified by the Major Grid and Minor Grid parameters
above) times the nearest integral power of the grid base.  For
example,  if the constant is two and the base 10,  grids will be
drawn at 2, 20, 200, etc.
.IP "Log Grid Minimum Base"
This parameter specifies the smallest base to be used for drawing
logarithmic grids (see above).
.IP "Solid Fill Threshold"
This parameter specifies the size (in pixels) before a shape is
drawn using solid fill rather than stipple fill.
A large number specifies all geometry should be drawn solid
regardless of its size.
.IP "BB Name Threshold"
Label text drawn in bounding boxes (e.g. instances or terminals)
may or may not be drawn depending on the size of the bounding box.
This parameter specifies how many times wider the text may be than the
box before the label is not drawn.
.IP "BB Abstraction Threshold"
This parameter specifies the maximum size of a bounding box (in pixels)
where it is acceptable to draw a filled box rather than an outline
to speed the drawing process.
.IP "Contact Abstraction Threshold"
This parameter specifies the maximum size of a contact (connector)
where it is acceptable to draw an abstraction of the contact
rather than its full definition.
This can be used to tell VEM to draw contacts quickly.
.IP "Interface Facet"
This string parameter specifies the name of the displayed
interface facet.
This facet will be used to draw instances in unexpanded mode.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
layer-display	<*>	No Arguments
.TE
.IE "layer-display, VEM"
.in +0.5i
This command posts a dialog which can be used to selectively turn on or
off the display of geometry on any layer.
At the bottom of the dialog are six control buttons.
The
.I Ok,
.I Dismiss,
.I Apply,
and
.I Help
buttons work in the same way as described for
.I window-options.
The
.I All
button automatically selects all of the layers displayed in the body
of the dialog.
The
.I Clear
button automatically unselects all of the layers displayed in the body
of the dialog.
Above the control buttons there is a list of all layers displayed
in the window.  
The layers currently shown in the window have
buttons to the left of the layer name
that have check marks.
Those that are not shown have buttons to the left of
the layer name that appear empty.  The state of a layer
can be changed by moving the cursor over the corresponding button 
and depressing the left mouse button.
Note that no window update will occur until either
.I Ok
or
.I Apply
are pressed.
.in -0.5i
.H2 "Selection"
.pp
.IE "selection, VEM"
The selection commands described below are used to manipulate
object arguments on the argument list.
.TS
lw(20)b lw(10)b lb.
select-layer	.	[objs] [pnts] [lines] [boxes] "layer"
.TE
.in +0.5i
The
.I select-layer
command is similar to the
.I select-objects
command but allows the user to select only the geometries
on a particular layer.  This layer can be specified in two
ways:  the layer name can be typed in as the last argument
or the command will try to determine the layer by looking
at the geometry under the cursor when the command is invoked.
If the spot for the layer is ambiguous,  VEM will post a dialog
presenting a choice between the layers.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
select-objects	s	[objs] [pnts] [lines] [boxes] "layer"
.TE
.IE "select-objects, VEM"
.in +0.5i
The 
.I select-objects
command is used for placing collections of objects on
the argument list for further processing by other commands.
It takes as arguments any number of points,  lines,  or boxes.
Points select items under the point,  lines select objects which
cross the line,  and boxes select objects inside the box.  
If
.I select-objects
is not given any point, line, or box arguments,  it will try
to select items under the cursor where the command was invoked.
These semantics are described in detail below.
.sp 0.5
For each
point,  the command adds zero or more of the objects under the
point to the list.  
If there is more than one object under the point,
a dialog will be posted with buttons representing each of the objects
under the point.  Clicking the mouse in one of the buttons highlights
the object.  Once the user has clicked on the desired objects,  the 
"ok" button is used to actually select the items.
.sp 0.5
For each line argument,  the command adds all objects which intersect
the line.  This is useful for schematic drawings where paths (wires)
are zero width.
Selection using lines works best if the entered lines are manhattan.
Non-manhattan lines may select more objects than intended.
.sp 0.5
For each box,  the command adds all objects completely contained
in the box to the list.
Note that an object is considered contained if and only if its
.I "bounding box"
is
.I "completely inside"
the given box.
The 
.I select-objects
command is incremental;  i.e. it may be called many
times,  each time adding to the selected set.  All items selected
are highlighted in the VEM highlight color.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
select-terms	^T	[objs][pnts][lines][boxes]
.TE
.IE "select-terms, VEM"
.in +0.5i
This command selects all terminals (both actual and formal) whose
implementations intersect the objects found by examining the argument
list.  The semantics for specifying the objects is identical to
that described for
.I select-objects.
The items on the argument list will be replaced with the
set of terminals found by examining the items.
This command is useful for deleting formal terminals, specifying
actual terminals for use by 
.I edit-property
or
.I select-bag,
or creating new symbolic formal terminals using
.I promote.
As such, \fIit is extremely dangerous in \*(PT\fR.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
transform	t	[objs]
.TE
.IE "transform, VEM"
.in +0.5i
This command takes a selected set of objects built by selection
commands and transforms them.  The objects remain on the selected
set.  It is important to note that the actual objects in the database
are not affected by this command.  The transformation is associated
with the object set not with the objects themselves.
.sp 0.5
The command takes (up to) three arguments:  a set of objects to
work on,  a text rotation specification,  and two points indicating
a relative translation.  The object set must be supplied.
The rotation specification is a list of keywords separated by
colons:
.IP mx
Mirror around the Y axis.
.IP my
Mirror around the X axis
.IP 90
Rotate counter-clockwise 90 degrees.
.IP 180
Rotate counter-clockwise 180 degrees.
.IP 270
Rotate counter-clockwise 270 degrees.
.sp 0.5
If both a rotation and a translation are given,  the rotation specification
should come first.  If no rotation and translation are given,  the
command rotates the items 90 degrees counter-clockwise.
.sp 0.5
The
.I transform
command is incremental.
This means it can be applied many times with each command having a
relative effect on the current selected set.
For example,  invoking 
.I transform
without arguments twice is the same as invoking it once and specifying
the rotation string "180".
.sp 0.5
Once the command completes,  the highlighted form of the objects
will reflect the specified transformation.  This can be used as
a reference for further rotations or translations.
.sp 0.5
Translations are specified by two points.  A relative translation
is applied to the current transformation based on the vector formed
by the two points.
It is also possible to interactively specify the translation of
a selected set.
This is done by moving the cursor to a reference point and
pressing, dragging, and releasing the right mouse
button.  While the right button is depressed,  the selected objects
will track the cursor motion.
This can be used to drag items around interactively.
.sp 0.5
After completing a transformation with transform,  the objects
are not actually changed until a command that manipulates objects
is invoked (e.g. move-objects, copy-objects, etc).
See the
.I move-objects
and
.I copy-objects
commands below for more information.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
unselect-objects	u	[objs] [pnts] [lines] [boxes]
.TE
.IE "unselect-objects, VEM"
.in +0.5i
The 
.I unselect-objects
command is used to remove items from a previously created
object argument (select-objects operation).  
Any number of points, lines, and boxes may be
specified.  
The semantics for mapping these arguments to objects is the same as
.I select-objects.
For each point,  zero or more items beneath the point that are
part of the selected set are removed.  For each line,  all
items in the selected set intersecting the line are removed 
from the set.  For each box,  all items
completely contained in the box that are part of the selected
set are removed from the set.  
.sp 0.5
It is important to note that this command is intended to
be used to unselect small sets of already selected objects.
To unselect all items on the argument list,  use control-W
or control-U.
.H2 "Property and Bag editing"
.pp
The
.BO Oct
Data Manager supports two kinds of annotation: properties and bags.
Properties are named objects which may have an arbitrary value and
can be attached to any other
.BO Oct
object.
Properties are used by pigi to store parameters.
Bags are named objects which can contain any number of other
.BO Oct
objects, and are not used by pigi.
Bags are used to represent common collections of objects (instances
for example) that can be accessed efficiently.
There are a number of VEM commands used to create, edit, and delete properties
and bags.
However, since only one of these is useful in pigi, only one is documented
here.
.TS
lw(20)b lw(10)b lb.
show-property	^P	[objs]
.TE
.IE "show-property, VEM"
.in +0.5i
The 
.I show-property
command produces a list of all the properties associated
with the object under the cursor when the command was invoked
(or all objects in the selected set).  
If there are many objects under the cursor,  the command will
present a dialog which lists each object.  The user can select
one by clicking the mouse in the check box next to the object name.
The object will be highlighted.  When the right object is found,
the user can click "ok" to show the properties attached to the
object.
If the cursor is not over an object and nothing is in the
selected set, the properties attached to
the facet are shown.
The
properties are shown in the form:  xid: name (type) = value.  
The
.I xid
is the external identifier for the property and can be
used in evaluated labels.
The command also echos the type of the object each property is connected to.
.in -0.5i
.H2 "Physical editing commands"
.pp
The physical editing style in VEM is used by pigi for editing icons.
The commands described below are available in addition to the
common commands described in the previous section.
.pp
.TS
lw(20)b lw(10)b lb.
alter-geometry	a	[box] [lines] or [points]
.TE
.IE "alter-geometry, VEM"
.in +0.5i
This command replaces the box, path, or polygon under the cursor 
with the new specification supplied on the argument list.
This can be used to "stretch" geometry or change their composition.
For example,  to make a box slightly larger,  enter the slightly
larger box onto the argument list,  move the mouse over the old
box,  and invoke 
.I alter-geometry.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
change-layer	l	[objs] or [pnts][lines][boxes]"layer"
.TE
.IE "change-layer, VEM"
.in +0.5i
The 
.I change-layer
command detaches geometry from its current layer and attaches it
to a different layer.
The geometry can be specified either as an object set constructed
by the selection commands,  or directly by drawing points on them,
drawing lines through them,  or drawing boxes around them.
Normally,  the target layer is determined by looking at the geometry 
under the cursor when the command was invoked.
However,  if the last argument to the command is text,  it
is interpreted as the name of the target layer.
.in -0.5i
.TS
lw(20)b lw(10)b lb.
copy-objects	x	[objs] {pnt pnt}
.TE
.IE "copy-objects, VEM"
.in +0.5i
The 
.I copy-objects
command copies a set of objects from one place to another.
The command takes an object argument that should contain a list
of objects to be moved (this is built with 
.I select-objects
and 
.I unselect-objects ).
The command assumes the object set has been transformed using the
.I transform
command or interactively dragged to a new location with the right
mouse button.  The command makes a copy of the objects where are transformed
according to this translation.  For example,  to copy objects from
one location to another,  the user first selects the objects using
.I select-objects,
then interactively drags the objects using the right button (transformation),
then invokes the
.I copy-objects
command to make a copy at the new location.
Since the items remain selected, new copies can be made without reselecting
the objects.
.pp
The optional second argument should be two points which specify the source
and destination points of the copy.  This alternative can be used if
the object set is too large for interactive dragging or one wishes to
copy objects from one facet into another.  If the copy is from one
facet to another facet,  terminals will not be copied and
the objects will be copied in a manner
that preserves the position of the objects relative
to the source point.
The default key binding for this command is short for
"xerox".
.in -0.5i
.pp
.TS
lw(20)b cw(10) lb.
create-circle	C	[line] [pnts] "layer"
.TE
.IE "create-circle, VEM"
.in +0.5i
Since VEM does not have a circle argument type,  a special circle
drawing command has been added.  For most types of geometry,  the
user should use
.I create-geometry.
Circles are specified in one of two ways.  The first is a line
followed by up to two points.  The line specifies a filled circle
with the first point being the center and the second its
outer radius.  If the first point is supplied,  an arc is assumed
with an angle formed by the second point of the line,  the center
point and the newly specified point.  The angle is measured counter-clockwise.
If the last point is supplied,  it specifies the inner radius of the circle
(otherwise the inner radius is zero).
The second form takes two points and an optional point.  It specifies
a circle where the inner and outer radius are the same.  If the last
point is supplied,  an arc with the same semantics as the first form
is assumed.  Finally,  the layer of the circle is determined from
the cursor position or by a final text argument specifying the layer
directly.
.in -0.5i
.pp
.TS
lw(20)b cw(10) lb.
create-geometry	c	[pnts] [lines] [boxes] [text] "layer"
.TE
.IE "create-geometry, VEM"
.in +0.5i
The 
.I create-geometry
command creates new geometry.  It takes any number of
points, lines, boxes, or text and a layer specification.  A points argument
creates a closed polygon.  A line argument creates a multi-point
path.  Box arguments create boxes.  Finally,  text arguments
create labels.  When creating labels,  the point set after the
label is interpreted as the target points for the label.
All the geometry is created
on the same layer.  This layer may be specified as the final text
argument to the command or by invoking the command over an object
attached to a layer.  If the layer is ambiguous,  the command will
present a choice of layers in a dialog box.  The palette
command can be used to create a window which offers all possible
layers for creating geometry.
.in -0.5i
.pp
.TS
lw(20)b cw(10)b lb.
create-instance	<*>	[pnt] {"master:view name"}
.TE
.in +0.5i
In most cases,  the leaf cells designed with the physical editing
style are not hierarchical.
Instead,  instances of the low-level cells are connected together
using the symbolic editing style.
However,  those who would like to use VEM as a purely physical
design editor require instances in physical cells.
This command places instances in the physical editing style.
.sp 0.5
The instance is placed relative to the point supplied to the command.
The master of the instance can be specified in two ways.
In the first form,  the user supplies a text argument which contains
the cell, view, and instance names separated by spaces.  The instance
name is optional.
The second form determines the master of the instance by looking at
the instance under the cursor when the command is invoked.
This instance can be in the same cell or in another cell.
A common practice is to build a cell of primitives and use this
cell as a menu for placing physical instances (see the
.I palette
command).
.in -0.5i
.pp
.TS
lw(20)b cw(10)b lb.
create-terminal	<*>	["term name"]
.TE
.in +0.5i
This command creates a new formal terminal named "term name".  The
implementation of the terminal is determined by constructing
a list of all geometries under the spot where the command was
invoked and choosing the smallest coincident boxes from this
list.
\fIThis command is dangerous in pigi.\fR
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
delete-objects	D	[objs] or [pnts] [boxes] "layer"
.TE
.IE "delete-objects, VEM"
.in +0.5i
The delete command removes objects from a cell.  The command
has two forms.  The first takes an object argument constructed
using selection commands and deletes all of the items in this
set.
The second takes any number of point, line, and box arguments and
a layer specification.  This form deletes all objects under
the points,  all objects which intersect the lines, and all 
objects completely contained in the boxes
that are attached to the specified layer.  The layer may also
be specified by placing the cursor over some other object attached
to a layer when the command is invoked.  If no layer is specified,
all of the geometry is deleted.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
edit-label	E	[pnt] { "LAYER" } or [objs]
.TE
.IE "edit-label, VEM"
.in +0.5i
The
.I edit-label
command creates and edits labels.
The command has two forms.  The first form creates a new label at the
specified point on the given layer.  If the layer is not specified,
it will be determined by looking at the object under the cursor.
The second form edits labels selected using the
.I select
command.
.sp 0.5
Labels in Oct are represented as a box where the text is drawn
entirely inside the box subject to justification and text
height parameters.
The edit-label command builds the box automatically by examining
the text height and text itself.
Thus, the user can control the justification, text height,
and the label text.
These parameters are set using the edit-label dialog box.
This is a modeless dialog box that is posted when the
user invokes the edit-label command.
.sp 0.5
The edit-label dialog box consists of three check-box areas for
adjusting the label justification, and two type-in fields
for adjusting the text height and the text itself.
The justifications are computed in relation to the point
the user specified when the label was first created.
Thus,  the horizontal justification specifies whether the
point should be to the left, center, or right of the text.
Similarly,  the vertical justification specifies whether
the point should be on the bottom, center, or top of the
text.
Finally, the line justification specifies how the lines
should be justified within the text block when there is
more than one line.
The text height of the text is given in Oct units.
Note that the X window system does not directly support
fully scalable fonts.
Thus,  VEM uses a strategy where it will pick the closest
font from a set of fonts that can be specified as a startup
parameter (see the document "Customizing VEM" for details).
Finally,  the last type in field can be used to enter
the text for the label.  The label can have as many lines
as necessary.
.sp 0.5
At the bottom of the dialog are four control buttons:
.I Ok,
.I Apply,
.I Dismiss,
and
.I Help.
The
.I Ok
button updates the value of the label and causes the dialog
to close.  The
.I Apply
button updates the value of the label (showing the effects
in the graphics window) but does not close the dialog.
This allows the user to adjust the label several times
if necessary.
The
.I Dismiss
button closes the dialog without updating the value of the label.
Finally, the
.I Help
button displays some help about how to use the dialog.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
move-objects	m	[objs] {pnt pnt}
.TE
.IE "move-objects, VEM"
.in +0.5i
The 
.I move-objects
command moves a set of objects from one place to another.
The command takes an object argument that should contain a list
of objects to be moved (this is built with 
.I select-objects and 
.I unselect-objects ).
The command assumes the object set has been transformed using the
.I transform
command or interactively dragged to a new location using the right
mouse button.  The command moves the objects to a new location based on
this transformation.  For example,  to move objects from
one location to another,  the user first selects the objects using
.I select-objects,
then interactively drags the objects using the right button (transformation),
then invokes the
.I move-objects
command to actually move the items to the new location.  The items remain
selected for further moves if necessary.
.pp
The optional second argument should be two points which specify the source
and destination points of the move.  This alternative can be used if
the object set is too large for interactive dragging.  Unlike the
.I copy-objects
command,  objects cannot be moved from one facet to another.
.in -0.5i
.H2 "Symbolic editing commands"
.pp
The symbolic editing commands in VEM allow the user to edit
.BO Oct
symbolic views.
Symbolic views are used to represent layout in a form
suitable for compaction and simulation.
Since they are not used by pigi, they are not documented here.
.H2 "Schematic editing commands"
.pp
The schematic editing style is an extension of symbolic.
In addition to the general, selection, and options
editing commands,  the following commands are specific to
the schematic editing style:
.pp
.TS
lw(20)b cw(10)b lb.
delete-objects	D	[objs] or [pnts, lines, boxes] ["layer"]
.TE
.IE "delete-objects, VEM"
.in +0.5i
This command takes either an object list created with
the 
.I select-objects
and
.I unselect-objects
commands, or points, lines, and boxes with an optional layer-name.
The resulting objects are deleted from the cell.
.in -0.5i
.pp
.TS
lw(20)b cw(10)b lb.
select-major-net	^N	pnts, lines, or boxes ["net name"]
.TE
.IE "select-major-net, VEM"
.in +0.5i
This command finds the net associated with the object under
the points, intersecting the lines, or inside the boxes
and highlights all objects on that net.
If no points, boxes, or lines are specified,  the object
under the cursor will be examined.
Alternatively,  if a net name is provided,  objects on
the named net are highlighted.
This command can be used to check the connectivity of
a symbolic cell.
The command is incremental (i.e. multiple nets can be
selected).
.in -0.5i
.pp
.TS
lw(20)b cw(10)b lb.
move-objects	m	[objs] {pnt pnt}
.TE
.IE "move-objects, VEM"
.in +0.5i
The
.I move-objects
command moves a set of objects from one place to another.
The command takes a set of objects (specified using select-objects)
and a transformation.
This transformation can be specified in two ways: as two points
specifying a relative translation or using the transform command.
The transform command allows general mirroring and rotation
to be specified in addition to a translation.
It is also possible to specify the translation of an object
set by interactively moving the set using the right mouse
button (see the transform command).
After a move operation,  the objects remain on the argument list for
further move or copy operations.
.sp 0.5
For example,  a set of objects can be moved using the following
sequence:  select the objects using the select-objects command.
Move the cursor over a reference point.  Depress and hold the
right mouse button and drag the items to a new location.
Use the transform command to rotate or mirror the object
set.  Once everything is correct,  invoke the move-objects
command to actually move the objects.
.sp 0.5
The connectivity of the items moved by this command is not changed.
This means an instance moved using this command also causes the
segments attached to its terminals to move as well.  Moving
objects between facets is not supported.
.in -0.5i
.pp
.TS
lw(20)b cw(10)b lb.
copy-objects	x	(See Below)
.TE
.IE "copy-objects, VEM"
.in +0.5i
The
.I copy-objects
command copies a set of objects from one place to another.
This command has the same form as 
.I move-objects 
(see above) except that
the objects are copied not moved.
Like 
.I move-objects,  
the objects copied remain on the argument
list for further move and copy operations.
However, unlike
.I move-objects,
the connections to the objects in the selected set are not copied.
Instead, the connectivity between the selected items is copied
along with the objects.
.in -0.5i
.pp
.TS
lw(20)b cw(10)b lb.
create	c	(See Below)
.TE
.IE "create, VEM"
.in +0.5i
The 
.I create
command allows the user to add new objects to a schematic cell.
Different arguments given to 
.I create
will produce different objects.
.sp 0.5
.BO "Formal Terminals -"
\fB"terminal-name [type] [direction]"\fP
.BO " : create"
.sp 0.5
When 
.I create
is given a single argument string, the name of a new formal terminal,
a formal terminal is created.  
The implementation of the formal terminal is taken to be the actual
terminal currently under the mouse (note: a connector terminal can also be used
for this purpose).
Since terminals in schematic may be quite small,  this routine
will try to find nearby terminals if it doesn't find a terminal
directly beneath the cursor.
.sp 0.5
Formal terminal names must be unique within the cell.
If a formal terminal of the given name already exists,
VEM will display a dialog box asking whether or not you
wish to replace the old terminal.
.sp 0.5
Two optional pieces of annotation can be placed on the terminal:
type and direction.
The type can be one of SIGNAL, CLOCK, GROUND, SUPPLY, or TRISTATE.
If not provided,  SIGNAL will be assumed.
The direction can be one of IN, OUT, or INOUT.  If not specified,
INOUT will be assumed.
If either of these values are not provided in the terminal
name specification, VEM will post a dialog box containing fields
for entering both the terminal type and direction.  Pressing the left
mouse button in the value area for these fields will cause a menu
of the possible choices to appear.  New values can be selected
by releasing the mouse button over the desired value.  Once
appropriate values are selected, activating the
.I Ok
button at the bottom of the dialog will save the annotations.
Activating the
.I Dismiss
option will leave the annotations unspecified.
These annotations can be edited later using the edit-property command.
.sp 0.5
.BO "Instances - points ["\fB"[master:view] [instance-name]"\fB
.BO "] : create"
.sp 0.5
If the arguments to 
.I create
are a number of points followed by an optional string, instances will
be created with their origins at those points.
If the name of the master is not specified textually,
it will be inferred from the instance under the mouse.
.sp 0.5
The string argument has two parts: the instance specification and name.
Both of these fields are optional.  Specifying a null string is considered
to be the same as no string at all.  The instance specification is a
master-view pair, such as "amp:schematic".  If this field is left
out, 
the master is inferred from the instance under the mouse.  
Otherwise, an attempt
is made to locate the instance by the master-view pair.  If the
name field is given, the instance will be given the specified name.
.sp 0.5
NOTES: Newly created instances whose actual terminals intersect actual terminals
of other instances will be automatically connected.
In this case,  no path is required between the terminals.
Rotated and mirrored forms of instances can be created by instantiating
a new instance and using the transform and move-objects or transform
and copy-objects commands.
.sp 0.5
.BO "Paths - lines" : create
.sp 0.5
This command creates new segments for connecting together instance
actual terminals.
A new series of segments will be created on a predefined layer
(WIRING).
Connector instances will be placed automatically at all
jog points.
The width of the new path is always zero.
.sp 0.5
Normally,  the schematic editing style has a feature turned on
called "gravity".
When you draw segments with gravity turned on,  VEM will try
to connect the segments to a nearby terminal if you miss
a terminal by a small amount.
This is useful when editing a large cell.
.in -0.5i
.pp
.TS
lw(20)b lw(10)b lb.
edit-label	E	[pnt] { "LAYER" } or [objs]
.TE
.IE "edit-label, VEM"
.in +0.5i
The
.I edit-label
command creates and edits labels.
The command has two forms.  The first form creates a new label at the
specified point on the given layer.  If the layer is not specified,
it will be determined by looking at the object under the cursor.
The second form edits labels selected using the
.I select
command.
.sp 0.5
Labels in Oct are represented as a box where the text is drawn
entirely inside the box subject to justification and text
height parameters.
The edit-label command builds the box automatically by examining
the text height and text itself.
Thus, the user can control the justification, text height,
and the label text.
These parameters are set using the edit-label dialog box.
This is a modeless dialog box that is posted when the
user invokes the edit-label command.
.sp 0.5
The edit-label dialog box consists of three check-box areas for
adjusting the label justification, and two type-in fields
for adjusting the text height and the text itself.
The justifications are computed in relation to the point
the user specified when the label was first created.
Thus,  the horizontal justification specifies whether the
point should be to the left, center, or right of the text.
Similarly,  the vertical justification specifies whether
the point should be on the bottom, center, or top of the
text.
Finally, the line justification specifies how the lines
should be justified within the text block when there is
more than one line.
The text height of the text is given in Oct units.
Note that the X window system does not directly support
fully scalable fonts.
Thus,  VEM uses a strategy where it will pick the closest
font from a set of fonts that can be specified as a startup
parameter (see the document "Customizing VEM" for details).
Finally,  the last type in field can be used to enter
the text for the label.  The label can have as many lines
as necessary.
.sp 0.5
At the bottom of the dialog are four control buttons:
.I Ok,
.I Apply,
.I Dismiss,
and
.I Help.
The
.I Ok
button updates the value of the label and causes the dialog
to close.  The
.I Apply
button updates the value of the label (showing the effects
in the graphics window) but does not close the dialog.
This allows the user to adjust the label several times
if necessary.
The
.I Dismiss
button closes the dialog without updating the value of the label.
Finally, the
.I Help
button displays some help about how to use the dialog.
.in -0.5i
.H2 "Remote application commands"
.pp
The following commands apply only if a remote application, like
pigiRpc, is running.
.pp
.TS
lw(20)b lw(10)b lb.
kill-application	<*>	No Arguments
.TE
.IE "kill-application, VEM"
.in +0.5i
The
.I kill-application
command kills the remote application which has control of the
window where the command was invoked.  This can be used to
terminate runaway remote applications.  Note it has no
standard menu or key bindings;  it is a type-in command only.
This command may not work on all machines.
.in 0.5i
.pp
.TS
lw(20)b lw(10)b lb.
rpc-any	r	"host pathname"
.TE
.IE "rpc-any, VEM"
.in +0.5i
This command starts up a remote application which is not on
the standard list of applications in the VEM menu.  "host"
specifies the network location for the application and
"path" specifies the path to the executable on "host".
If the host specification is omitted,  the local machine
is assumed.
.in -0.5i
.TS
lw(20)b lw(10)b lb.
rpc-reset	^R	No Arguments
.TE
.in +0.5i
If an application terminates abnormally,  VEM may not recognize
that the window no longer has an application running in it.
This command forces VEM to reset the state of the window
so that new applications can be run in it.
.H2 "Customization"
.pp
VEM is a highly customizable editor.  Nearly all of the colors,  font
styles,  and fill patterns it uses can be configured to a user's
taste.  See "Customizing VEM" for more details.
.pp
Furthermore,  VEM is meant to be an extensible program.
New commands can be written that are either tightly bound to
the editor or that run in a separate process space.  There
are documents describing both tightly bound and remotely
bound extensions to VEM.  See the complete octtools distribution
documentation for details.
.H2 "Bugs"
.lp
Opening a facet that is inconsistent (either out of date or one
with conflicting terminals) isn't handled very gracefully.
You can open an inconsistent facet by opening it again.
.sp 0.5
Bounding boxes may not be drawn if there is no geometry in the cell.
.sp 0.5
The set path width command doesn't work if you use a palette
to specify the layer.
.sp 0.5
Editing the master of an instance displayed in some other window
sometimes causes the instance to disappear.  Re-reading the
cell with the instance gets around the problem.
.sp 1
Send bug reports to vem@eros.Berkeley.EDU
.EQ
delim $$
.EN
