Provided by: xcircuit_3.7.26.dfsg-1_amd64 bug

NAME

       xcircuit  -  Draw  circuit  schematics  or  almost  anything;  make  circuit netlists from
       schematics.

SYNOPSIS

       xcircuit [filename[,...]]

DESCRIPTION

       The program  xcircuit  is  a  generic  drawing  program  tailored  especially  for  making
       publication-quality  renderings  of circuit diagrams (hence the name).  The output is pure
       PostScript, and the graphical interface  attempts  to  maintain  as  much  consistency  as
       possible between the X11 window rendering and the final printer output.

       xcircuit  is  mouse,  menu,  and  keyboard-driven,  with  the emphasis on single-character
       keyboard macros.

OPTIONS

       filename[,...]
               Begin running xcircuit by loading in the PostScript file  filename.   If  filename
               does not have a .ps extension, xcircuit will attempt to look for both the filename
               as entered and, upon failure, with  the  .ps  extension.   The  file  must  be  in
               xcircuit format.  filename may also be a comma-separated list of files.

BASIC ELEMENTS

       There are five drawing elements.  These are as follows:

       a) polygon (multiple lines which may or may not be closed and filled)

       b) arc (ellipse segment which may be closed and/or filled as above)

       c) label (any text)

       d) curve (based on the PostScript "curveto" algorithm)

       e) object instance (see below)

       There are two composite elements, which are:

       f) path (a connected series of polygons, arcs, and curves)

       g) object  (something  containing  polygons, arcs, labels, curves, paths, and instances of
          other objects)

MOUSE BUTTONS

       The mouse button system, the object library, and the paged buffer system are loosely based
       on the Caltech circuit-simulation program "log" (either "analog" or "diglog").

       The  general  idea is to make the most commonly-used functions the easiest to perform, and
       (to the extent possible) to scale (inversely) the complexity of performing a function with
       the frequency of that task.  Because this program is tailored to circuit drawing, the most
       common functions are drawing lines and moving object  instances.   The  next  most  common
       function is selection of elements singly or in groups.

       Mouse  button 1 can be tapped to start a connected chain of lines, the most common drawing
       function.  In addition, button 1 has a function called  "grab",  which  occurs  after  the
       button has been continually pressed for a short length of time (about 1/5 second).  As the
       name implies, "grab" grabs hold of an element which can then be moved around the screen.

       Button 2 can be used to select an item if tapped, and if pressed and held down, a box will
       be  drawn  and  everything  inside  that box selected when the button is released.  In all
       other cases, button 2 will complete a command.  For users who have only two mouse  buttons
       and  do  not  emulate the middle mouse button with the combination of buttons 1 and 3, use
       the combination of the Shift key and mouse button 1 to emulate mouse button 2.

       Button 3 will normally abort a command.  During editing of an  arc,  spline,  or  polygon,
       button  3  will  revert  back to the previous form, or abort if there is no remaining edit
       history.

       All other commands are available from the pulldown menus and/or from  the  keyboard  using
       single-key macros (with easy-to-remember mnemonics).  Keyboard commands are quicker, since
       they act on the present cursor position, whereas menu commands require an extra step.

BUILT-IN LIBRARY

       The library is intended to provide a convenient way to store and retrieve  elements  of  a
       picture  which  will  be  used  more than once.  For the application of circuit drawing, a
       built-in library provides  basic  objects  such  as  transistors,  amplifiers,  resistors,
       capacitors,  arrows,  circles,  power  and  ground  symbols, and the like.  This file is a
       composite  of  several  library  files  (such   as   "builtins.lps",   "analog.lps",   and
       "digital.lps")  which are called by the startup script ("xcstartup.tcl") The program first
       looks for the startup script in the current directory, and then searches in the  directory
       given  by  the  environment  variable  "XCIRCUIT_LIB_DIR",  and finally, in the hard-coded
       global directory (/usr/lib) if it could not find it elsewhere.  Thus each user can add  to
       or  modify  the  file  of builtins to reflect personal taste.  Since the PostScript output
       contains all object definitions, these changes to the built-in  functions  are  inherently
       transferrable.   Xcircuit  will automatically resolve conflicts between objects having the
       same name but different contents.

       The library is accesible from the pull-down menu or with the  "l"  keyboard  macro.   When
       inside  the  library, clicking the first mouse button on an object "grabs" that object and
       returns the graphics state immediately to the page being edited, so that the  object  will
       be placed when the mouse button is released.

ZOOMING

       Xcircuit  has  unconstrained  zooming  and snap-to positioning.  Objects scale completely:
       line widths and text sizes will increase/decrease proportionally with the zoom, as well as
       dot/dash  spacing  and  all  other features.  Xcircuit does have a minimum integer grid in
       coordinate space, which translates to 0.005 inches at an output scale of 1.   The  maximum
       zoom  scale  gives a screen size translating to about 100 by 100 inches at an output scale
       of 1.  The effective scale can be varied by changing the output scale  (reached  from  the
       "File/Write"  menu selection) in order to fit a drawing to a page or to get a grid matched
       to a specific dimension.  A separate scale parameter changes the  scale  of  the  reported
       position relative to the output scale (as it will appear on a printed page).

SNAP-TO GRID

       The  snap-to  grid is an all-important feature for circuit drawing, wherein it is critical
       that elements line up properly with one another.  In xcircuit, there is no way to get  off
       the  snap-to  grid except by turning the snap function off and physically pushing elements
       off the grid.  Generally, it is most convenient to leave the snap functon on and  use  key
       macros  "+"  and  "-" to double/halve it as necessary.  In any case, objects can always be
       returned to the snap grid with the "snap" function (key macro "S").

SELECTION MECHANISM

       Objects are selected using a variety of search methods.  The select box (formed by holding
       down  mouse  button  2  and  dragging the pointer) uses the simplest method, searching for
       curve/polygon segment endpoints, arc centers, and label and object bounding boxes  falling
       within  the  select  box  frame.  General object selection is more complicated.  Polygons,
       Arcs, and Curves are selected by their outer edges, not the interiors.  Currently this  is
       also  true for filled instances of those types.  A line is selected if the pointer is in a
       region describing a box around it, which is adusted according to the scale (zoom  factor).
       Every  object has an associated bounding box, which is rectangular but may be rotated with
       respect to the top level window.  An object instance is  selected  if  the  pointer  falls
       within its bounding box.  Each label also has a bounding box carefully calculated from the
       width of the text string.

       Often the selection mechanism will find multiple elements in range  of  the  pointer.   In
       this  case,  each  object  in  turn  will  be presented, colored in blue (or the specified
       "querycolor" in the defaults  file),  and  the  user  has  the  option  of  accepting  the
       highlighted  element  for  selection  using the mouse button 1, or rejecting it with mouse
       button 3.  When all the elements under consideration have been accepted or  rejected,  the
       program  proceeds  to  execute  whatever  function was in progress.  This selection method
       takes a little while to get used to, but is sensible and seems to work well.

COLOR

       Color in xcircuit is implemented with the idea of "color inheritance".  Every page  has  a
       "default  color" of black.  All elements which have color value "Inherit" will inherit the
       default color, black.   If  an  object  instance  is  painted  blue  (for  instance),  all
       components  in  that object which have color value "Inherit" will inherit its color, blue.
       The reason for this is that it allows different object instances to be  painted  different
       colors  (such  as  if  one part of a circuit is highlighted for emphasis), while making it
       possible for object instances to be multicolored, if necessary.  Changing the color of  an
       object instance will have no observable effect on the drawing if none of the components of
       the object inherit that color.  An object may have both normally  colored  components  and
       components  which  inherit  their  color,  in  which  case  only those components with the
       "Inherit" value will change color when the color of the object instance is changed.

SCHEMATIC CAPTURE

       XCircuit implements a sophisticated schematic capture.   Unlike  virtually  all  schematic
       capture  software currently available, xcircuit allows the designer to draw the circuit in
       a "natural" way, making use both of schematic hierarchies and simple  hierarchies  created
       simply  by grouping elements together.  If the chosen netlist format is hierarchical (like
       SPICE), both hierarchical forms will be retained in the  output.   For  element  grouping,
       input/output  ports  connecting  into  to the group will be determined automatically, from
       context.  A schematic capture tutorial is available from the xcircuit website,
       http://opencircuitdesign.com/xcircuit/tutorial/tutorial2.html.

       Netlist types currently available are "SPICE", "sim", and "PCB".

KEYBOARD COMMANDS

       Basic keyboard commands:

       Z           Zoom in by a factor of 3/2.  If this key is pressed while a selection  box  is
                   active  (created  with  the  middle  mouse  button),  then  acts like Zoom Box
                   function.

       z           Zoom out by a factor of 3/2.

       p           Pan the screen so that the point under the mouse is brought to the  center  of
                   the  program  window.   This  function  can  also be conveniently performed by
                   clicking on the scrollbars.  The scrollbars cannot be moved  continuously  due
                   to the slow time for screen refresh.

       cursors     The  arrow  keys perform a pan of one-half window size in the direction of the
                   arrow pressed.

       l           Go to the Library of built-in objects.  From the library, use mouse button1 to
                   grab  an  object  and  bring  it back to the edit screen, or button3 to return
                   without selecting an object instance.  While in the library screen,  the  zoom
                   and pan functions can be used to move around.

       >           Push into an on-screen object in order to edit that object

       <           Return  from  editing  an  object.   Object  pushes  and  pops  can be stacked
                   indefinitely.

       space       Refresh the screen.

       digits 0-9  Switch to one of the first ten editing pages.  Pages greater than  10  can  be
                   reached from the "Window/Goto Page" menu selection.

       + and -     Change snap-to grid spacing by a factor of two up or down.

       | : and _   (Bar,  colon,  and underline) Change style on the currently selected object to
                   dashed, dotted, and solid, respectively.

       h or ?      Print a help page summary of commands

       Commands to create elements:

       a   Arc.  Center is fixed at the initial position  of  the  cursor.   The  mouse  position
           changes  the  radius of the circle.  In snap-to mode the arc boundry will pass through
           the snap point closest to the cursor.  Mouse button  1  cycles  from  controlling  the
           radius to controlling the starting point, the ending point, and separately controlling
           the minor axis to create ellipse.  Mouse button 2 completes the arc.

       b   Box.  This is a convenience  function  for  generating  rectangular  closed  polygons.
           Creates  a  rectangle with one corner fixed at the position of the cursor.  Subsequent
           movement of the cursor defines the point diametrically opposed.  Mouse buttons 1 or  2
           complete the box.

       s   Spline  curve.   The  first endpoint is defined by the initial cursor position.  Mouse
           position adjusts the other  endpoint  of  the  curve.   Mouse  button  1  cycles  from
           controlling  position  of  the  endpoint to controlling positions of the curve control
           points and the curve starting point.  Mouse button 2 completes the curve.

       t   Text.  Text starts out justified according to the styles chosen in the pull-down menu.
           Text  can be rejustified using the menu or by typing the numbers on the keypad (shift-
           keypad-1 through shift-keypad-9).  The position of the keys on the keypad matches  the
           justification.    Subscripts,   superscripts,   font   changes,   text  size  changes,
           underlining, and overlining are all available from the pull-down menu.  Text edit mode
           recognizes  Home  and  End  keys  to  move  to  the  beginning  and end of the string,
           respectively.  If  the  X11  environment  maps  control  key  sequences  to  character
           encodings  (such  as ISO-Latin1), these may be used to insert non-ASCII text.  Another
           method of inserting non-ASCII characters is the use of the backslash character,  which
           duplicates the action of the Text/Insert/Character menu button.

       M, m
           Make  object.   Takes  all  the  elements currently selected and compiles them into an
           object.  The object is then placed in the user library.  The  elements  just  selected
           are  deleted  from the screen and replaced by the new object.  The center point of the
           resulting object is chosen as the closest snap-to point to the center of the  object's
           bounding  box;   if another center is desired, then the object can be edited using the
           ">" command and its contents moved with respect to its origin.  Note:  Objects  cannot
           have the same name as PostScript commands or have the same name as any other object in
           memory.  If such a name is found, an underscore ("_") will be prepended to the name as
           many times as is necessary to differentiate it from all other known objects.  The name
           also cannot contain special PostScript characters such as slash; any  such  characters
           found will be replaced with underscores.

       Major editing commands:

       d   Delete.  Select the nearest element or elements and delete it/them.

       u   Undelete.   Xcircuit  saves up to 10 delete events to be recovered.  Delete events are
           stored in order of occurrence, and the most recent delete event is  the  first  to  be
           recovered.   When  multiple  elements  are  deleted  at the same time, all of them are
           stored as one delete event, and restored together.

       x   Deselect. Elements which have been selected can be deselected on a per-item basis.  In
           order  not  to  be  too confusing, deselect does not query if multiple items are found
           under the cursor; it just deselects them all.

       c   Copy.  Make a copy of the object(s)  nearest  the  cursor.   Object  is  automatically
           grabbed  for  moving  to a new position.  The next button1 or button2 press will place
           the element.  Button2 will end the copy, and button1 will continue the copy function.

       e   Edit.  The action of Edit is dependent on the type of  element  selected.   These  are
           detailed below:

       Label       Returns  to  text  editing  mode,  starting  with the cursor at the end of the
                   string.  Mode is like regular text entry except that Button 3 returns text  to
                   its original string.

       Polygon     Grabs  one  point  of  a  polygon  for repositioning.  Button 1 cycles between
                   points, button 2 accepts the new polygon, and button 3 returns to the previous
                   state,  unless there is no remaining edit history, in which case it aborts the
                   command.  Key macros available during polygon edit are:

                   "x"---Breaks the polygon at the given point.

                   "e"---Moves edit position to the next point.

                   "i" or "Insert"---Inserts a new point at the position.

                   "d" or "Delete"---Deletes the current edit point.

                   There are four modes for polygon editing; see the "Polygon Edit" section below
                   for details.

       Arc         Allows  resizing  of  the  radius.   Mouse  button 1 or the "e" key will cycle
                   between control of the radius, the endpoint  angles,  and  the  ellipse  minor
                   axis.   Mouse  button 2 accepts the new arc.  Button 3 returns to the previous
                   editing state, unless there is no remaining edit history,  in  which  case  it
                   aborts the command.

       Curve       Allows  repositioning of one end of the curve.  Originally, the starting angle
                   of the curve is kept fixed.  Mouse button 1 or the "e" key cycles between  the
                   four control points of the curve, allowing control over the angle of the curve
                   at its endpoint and the shape of the curve.  Mouse button 2  accepts  the  new
                   curve.   Button  3  reverts back to the previous edit state unless there is no
                   remaining edit history, in which case it terminates the command.

       Object instance
                   Object instances have no properties to change except scale, and do not respond
                   to    the    "edit"    command.    Scale   can   be   changed   by   selecting
                   "Options/Other/Object Size" from the menu.

       Minor editing commands:

       R   Rotate the selected element(s) or element under  the  cursor  counterclockwise  in  15
           degree intervals.

       r   Rotate  the  selected  element(s)  or  element under the cursor clockwise in 15 degree
           intervals.

       O   Rotate the selected element(s) or element  under  the  cursor  counterclockwise  by  5
           degree  intervals.   This  is  currently  the  smallest  angle resolution available to
           xcircuit.

       o   Rotate the selected element(s) or element under  the  cursor  clockwise  by  5  degree
           intervals.

       f   Flip  an  element  around  a vertical axis defined by an object's origin for an object
           instance, or across an axis defined by the pointer position for  arcs,  polygons,  and
           curves.

       F   Flip an element around a horizontal axis defined similarly to the "f" command.

       X   If  two  elements are selected, their order is exchanged (this is only relevant if one
           element occludes another).  If one element is selected, it is raised  up  one  in  the
           stack, and if it is already on top of the stack, it is shuffled to the bottom.

       S   Snap the nearest object to the snap-to grid.  For curves the control and endpoints are
           snapped; for polygons, each point is snapped; for arcs, the  centerpoint  is  snapped;
           for labels and object instances, the designated point of origin is snapped.

       j   Join  polygons  together.   This  only  makes sense if it is possible to make a single
           continuous (open or closed) polygon from the selected parts.  Otherwise a warning will
           be posted and the parts will remain separate.

       A   Attach an element to a polygon, arc, or curve.  The element to be attached must be the
           one currently grabbed (either by a "drag", copy command, or edit command).   Until  it
           is  released,  it will be forced to align its center (object, arc), endpoint (polygon,
           curve), or position (label) with the closest polygon, arc, or curve.  Note  that  this
           is  a  very  powerful  tool  for generating, for example, lines tangent to a curve, or
           objects arranged in a circle or along a line.

       Library editing commands:

       D   Delete.  The selected objects will be deleted from the library  unless  other  library
           objects  or  pages  contain  references  to that object.  Note: Unlike deleting object
           instances with the "d" command, this command deletes the actual  object  and  releases
           all memory associated with that object, so the object cannot be undeleted.

       C   Copy.   Makes  a copy of an object from either library page and places the new copy in
           the user library.  The new object will be renamed to avoid naming conflicts.

       M   Move.  If one object has been selected, it is moved to the position of the cursor.  If
           two objects have been selected, their positions in the library are exchanged.

       E   Edit label.  Edit the object name whose label is under the cursor.  After editing, the
           object name will be checked for conflicts with other  object  names,  and  altered  if
           necessary.

       H   Hide  object.   If the object is a sub-instance of another object, but is not meant to
           be used by itself, it can be "hidden" so that it will not  appear  by  itself  on  the
           library page.

MENU COMMANDS

       Write Postscript (W)
           This  command  brings  up  a popup menu with a number of options.  First, it gives the
           name of the file if one exists, or else it  gives  the  default  name  of  the  buffer
           (usually  Page  n,  where n is the number of the buffer).  Next, it gives a preview of
           the picture scale and output styles, which include Landscape/Portrait orientation  and
           Encapulated/Unencapsulated (full page) PostScript modes.  The former allows adjustment
           of the nominal size of the picture when drawn in PostScript.   The  default  scale  is
           1.00,  which  makes the text scale of 1.0 about 14 points on the PostScript page.  The
           width and height of the resulting picture are also given, in inches, and  any  of  the
           three values can be changed.  The values of the other two will be updated accordingly.
           Pages which have the same name will be grouped together into a single  file,  allowing
           multiple  pages  to  be  stored in the same PostScript file.  However, as Encapsulated
           PostScript does not make sense for this kind of file, it is not an option.

           The Write File button writes the current page to an output file.  If the  page  has  a
           name  other  than  the  default, the file will automatically be saved under that name.
           Otherwise, it is necessary to change the name of the buffer.  If a file of  that  name
           already exists on the disk, the button will read Overwrite File.

       Read PostScript
           Reads in a file of Xcircuit format.  The file name is requested by a popup prompt, and
           an extension of ".ps" will be added if necessary.  The file is read into  the  current
           page,  which  is  cleared  first if anything is in it.  If the file is a multiple-page
           file, the current page will be overwritten with the first  page  from  the  file,  but
           other  pages  will  be loaded into empty buffers.  Xcircuit can also read "lgf"-format
           files from the Chipmunk CAD tools programs "analog" and "diglog".

       Import PostScript
           Acts like "Read PostScript" except that the page is not reset first, so  graphics  are
           added on top of existing graphics on the page.

       Clear Page
           Clears  the  current page of all elements and resets the name.  The contents cannot be
           recovered.

       Alt Color
           Switches between the two xcircuit color schemes.  The color schemes can  be  redefined
           through  XDefaults  (see  below).   The  default  color schemes are black-on-white and
           white-on-black.  The latter is less straining to the eyes, but the former matches  the
           black  ink  on  white  paper PostScript output.  Any color scheme other than black-on-
           white is not recommended for drawings with color, as the actual output does not  match
           the observed xcircuit screen.

       Grid
           Turns the grid lines on and off.

       Axes
           Turns  the axis lines on and off.  The axes mark the origin (0,0) of the page.  On the
           top level (TopObject), the origin has  no  particular  relevance,  since  encapsulated
           output  will  define its own boundaries, and full-page (unencapsulated) output will be
           centered on the output page, not according to the Xcircuit coordinate system.

       Grid spacing
           Changes the spacing of the grid lines.  Default spacing is 1/6 inch,  which  is  about
           the width of the letter 'W' in default text scale.

       Grid type/display
           This  is  a  submenu  allowing  the coordinates and coordinate grid to be specified in
           alternate units.  Listing  of  coordinates  in  the  top  window  can  be  in  default
           fractional  inches,  decimal inches, or centimeters.  Default spacing of grid lines is
           either one-quarter inch or one-half centimeter.  Selecting an A:B  scale  With  option
           "Drawing  Scale"  causes  all listed coordinates to be multiplied by the scale.  Note:
           Xcircuit will make an attempt to keep objects on the snap/grid spacing when  switching
           between  inch  and  centimeter scales.  In order to do this, it will change the output
           scale by the ratio of 2.54 to 2.5, thus keeping a closer correspondence between inches
           and  centimeters.   To get true centimeters on the output page, the output scale (from
           the "File/Write Xcircuit PS") can be reset to 1.0 at the expense of having all objects
           intended for the inch grid displaced off of the snap grid.

       Snap-to
           Turns  the  snap-to  grid  on and off.  When the grid is on, movement and placement of
           elements is restricted to points on the snap-to grid.

       Snap spacing
           Determines the spacing of the points in the snap-to grid.  Default is 1/12 inch, which
           is half the grid line spacing.

       Linewidth
           Controls the default linewidth against which all linewidths in the drawing are scaled.

       Polygon Edit
           The  options  in  this  submenu  control how the position of lines are affected when a
           point in a polygon is selected for editing.  "Rhomboid-X" mode moves adjoining  points
           as necessary to keep all horizontal lines horizontal; "Rhomboid-Y" mode acts similarly
           to keep all vertical lines vertical.  "Rhomboid-A" is similar to  Manhattan  mode  but
           also tracks non-Manhattan lines.  The default mode is "Manhattan Box Edit", which is a
           combination of Rhomboid-X and Rhomboid-Y.  In "Normal"  mode,  only  the  point  being
           edited can be moved.

       Arc/Box/Curve Border
           The  options under this menu determine the border style of arcs, polygons, and curves.
           If an element is selected,  it  will  be  modified;   otherwise,  if  no  objects  are
           selected,  the  style  chosen  is  made default for all subsequent arcs, polygons, and
           curves.  Elements may be drawn with or without borders (but for obvious reasons cannot
           be  made  both  borderless  and unfilled, which would be invisible) The borders may be
           closed or unclosed.  For an arc, closed means that a chord is drawn connecting the two
           endpoints,  if the beginning and ending angles do not complete a full circle.  Borders
           may be solid, dashed, dotted, and of varying width.

       Arc/Box/Curve Fill
           The options under this menu determine the fill style of arcs,  polygons,  and  curves.
           Fill  style  may  be  solid, empty, or one of 7 stipple patterns varying from light to
           dark, which are drawn both in xcircuit and PostScript as stipple  patterns.   Stipples
           can  be  transparent  or  opaque.   Warning:  Transparent stipples are NOT inherent to
           PostScript and the hacks necessary to implement them cause slow rendering on a printer
           or PostScript previewer.  Due to the device-dependent nature of the routines, patterns
           will look abnormally large on PostScript previewers.  This  transparancy  feature  has
           been  added  with  the  expectation that most circuit schematics will not rely heavily
           upon halftoning.  Complicated color patterns can be created using transparent colored,
           stippled  elements  on  top  of  solid-color  elements.  Note: Ordering of elements is
           according to order created.  A different  ordering  can  be  achieved  using  the  "X"
           (exchange)  command.   This  method is not especially easy to work with, and hopefully
           something better will be implemented in the future.

       Arc/Box/Curve Color
           See the COLOR section above for a discussion of color inheritance.   This  menu  shows
           all the colors available to xcircuit with the option of adding more colors.  Currently
           the entry style for colors is by name or by RGB content in the X11  style  of  #rrggbb
           where  rr,  gg,  and  bb  are hex values ranging from 00 to FF.  The only limit to the
           number of colors is the X Server's colormap depth.  If the colormap is full,  xcircuit
           attempts to allocate the closest possible color to the one requested.

       Zoom Box
           This zoom feature requests the user to create a box (using either mouse button 1 or 2,
           expanding the box while holding down the button).  When the button  is  released,  the
           view will zoom to the area of that box.

       Full View
           This  zoom  feature  calculates the bounding box of the entire picture and adjusts the
           scale to make it fit comfortably inside the program window.

TEXT FEATURES

       Xcircuit's ability to handle text is arguably the most complicated part  of  the  program,
       and  also  of the PostScript output.  Careful attention to text justification and style is
       the key to a good drawing.

       Text Size
           Alters the size of the labels.  The value is a scale, with  a  default  of  1.0  which
           translates to 14 points on the PostScript page if the default page scale of 1 is used.
           If a label is selected, only that label is affected.  If  a  label  is  being  edited,
           scale  changes  starting at the edit position.  Otherwise, it becomes the default size
           for all subsequent labels.  Size affects the entire text string.   Text  size  can  be
           changed  anywhere  inside  of  a  string.  However, text sizes inside a string are all
           given relative to the label size, not as an absolute point size.  Sizes of  subscripts
           and  superscripts  are  given  relative  to  the  natural  size  of  the  subscript or
           superscript (2/3 the size of the text for which it is a modifier).

       Text Font
           Standard printer fonts  Times-Roman,  Helvetica,  Courier,  and  Symbol,  are  readily
           available.   "User-defined"  fonts  can  also  be added; however, support is currently
           limited, and requires a font object (.lps) file and encoding (.xfe) file, examples  of
           which are found in the fonts subdirectory of the xcircuit library directory.

       Text Style
           Four   standard  font  styles  are  available,  matching  the  standard  printer  font
           variations:  Normal, Italic (or oblique), Bold,  and  BoldItalic.   PostScript  matrix
           manipulation  allows  slanted  versions of any font, such as Symbol, for which none is
           otherwise available.

       Text Insert
           The Insert menu allows  insertion  of  special  characters  which  are  otherwise  not
           (necessarily)  allowed  from  the keyboard.  These include tab-stop, tab-forward, tab-
           backward, kern, half-space, quarter-space, and "Character".  The latter option  brings
           up  a page showing the 256-character encoding vector for the font, allowing point-and-
           click entry of any character in the font.  "Kern" instructions allow characters to  be
           offset vertically or horizontally relative to the rest of the text.

       Text Encoding
           Two  standard  font encodings are available by default, Standard (Adobe) Encoding, and
           ISO-Latin1 encoding.   ISO-Latin2  and  ISO-Latin5  encodings  exist  in  the  library
           directory,  but  require  the  use of the program "ogonkify" (not included) to produce
           correct output on a printer.

       Super and Subscripts
           Superscript and subscript are designed to closely match those in  TeX  output,  though
           they  lack  the  proper  context-dependent kerning and other fancy features of TeX.  A
           superscript following a subscript results in a  superscripted  subscript.   To  get  a
           superscript  on  top  of  a  subscript,  use the backspace character (see below).  The
           Normalscript style is the way to get out of a sub or superscript  and  return  to  the
           normal  size  and  position.   Quick  super/sub/normalscripting  is available from the
           keypad with the "+" (plus), "-" (minus), and "Enter" keys, respectively.

       Overline and Underline
           Overlining and underlining styles remain in effect until  the  next  occurrence  of  a
           style  or font change.  Overlining is lower if all the characters are lowercase and do
           not include the "tall" lowercase characters.  Overlining or underlining can be stopped
           at  any  time using the No Line style.  Over and Underlining is *always* preferable to
           using a line.  PostScript will adjust the over or  underline  to  the  text  size  and
           extent  and actually grab the "_" character and compute its thickness in order to draw
           the line.

       Tabbing
           From version 2.3, xcircuit allows embedded tab  stops.   Tab  stops  must  be  defined
           before  using tab-forward or tab-backward.  The "Tab" keyboard key inserts an embedded
           tab-forward instruction into a label.  Tab-stop and tab-backward can be inserted using
           the  Text->Insert  menu.   A  tab-forward  instruction  moves  the cursor to the first
           defined tab stop forward of the current position.  A  tab-backward  instruction  moves
           the  cursor  to  the  first  defined tab stop backward of the current position.  If no
           appropriate tab stop exists, the instruction has no effect.

       Backspace
           The use of the backspace character is  deprecated  from  xcircuit  version  2.3.   The
           effect  of  an  embedded  backspace  is more reliably produced using tab-stop and tab-
           backward.

       Halfspace and Quarterspace
           These options allow fine  control  over  spacing,  particularly  useful  when  writing
           equations.

       Justification
           Text  justification  always  starts  with  the default, chosen from the options in the
           menu, but may be changed at any time using the numbers on the keypad.  The position of
           the  keys  on  the  keypad  reflect the point of justification: 1, 4, and 7 are right-
           justified, 7, 8, and 9 are bottom justified, 5 is centered in both directions.   Since
           the  letters  drawn  by  xcircuit  are  optimized  for  the  Helvetica  font,  correct
           justification is the main way to get text to come out on the PostScript  page  in  the
           desired way, relative to objects or boxes or whatever.

.XCIRCUITRC FILE

       Certain  parameters  of  the  xcircuit  program  can  be  initialized  from  a file called
       .xcircuitrc, which is first searched for in the current directory, and then in the  user's
       home directory as defined by the environment variable $HOME.

       The startup file is written in Tcl.  The command-line interface can be found in the online
       documentation on the website

       http://www.opencircuitdesign.com/xcircuit/.

CRASH RECOVERY

       XCircuit implements a crash recovery system by which a copy of the current  file  is  made
       every  15  minutes (see Xdefaults, below, for changing this value).  XCircuit deletes this
       file upon a normal exit.  If, however, XCircuit crashes or is terminated by  Control-C  or
       other  sudden  death,  the  backup copy will remain.  On startup, XCircuit checks the /tmp
       directory for any XCircuit backup files belonging to the user.  If one is found,  XCircuit
       will  prompt  the user for recovery.  Note that the backup is unique in that it contains a
       copy of the entire user space at the time of the crash.  Filenames may get overwritten, as
       the backup will treat all pages as belonging to the same file.

KEY BINDINGS

       As  noted  above,  keys can be bound and unbound through command-line functions "bind" and
       "unbind".  Default key bindings are used throughout this manual page.  Key names  use  the
       notation  of  /usr/X11R6/include/keysymdef.h,  but with the notation "XK_" being optional,
       and including the addition of prefixes  "Shift_",  "Control_",  "Capslock_",  and  "Alt_",
       which may be used in any combination.  Note that "Shift_" is not used for ASCII characters
       (e.g., "A" is used instead of "Shift_a") unless used in  combination  with  other  special
       keys  (such as "Control_Shift_A" to distinguish from "Control_a", should that be desired).
       "Button1", "Button2", and "Button3" are also valid names indicating functions attached  to
       the  mouse  buttons  in  normal  drawing  mode.  Valid functions which may be bound are as
       follows, with their default values given:

          Function name        Function performed         Default key binding
          ---------------------------------------------------------------------
          "Page",              change page,               Number keys 1-9 and 0
          "Justify",           change text justification, Keypad keys 1-9
          "Superscript",       set text superscript,      Keypad +
          "Subscript",         set text subscript,        Keypad -
          "Normalscript",      cancel sub/superscript,    Keypad Enter
          "Nextfont",          change to next font,       Alt-f
          "Boldfont",          change to bold font,       Alt-b
          "Italicfont",        change to italic font,     Alt-i
          "Normalfont",        cancel italic/bold,        Alt-n
          "Underline",         generate underline,        Alt-u
          "Overline",          generate overline,         Alt-o
          "ISO Encoding",      change to ISO encoding,    Alt-e
          "Return",            embedded return character, Alt-Enter
          "Halfspace",         embedded half-space,       Alt-h
          "Quarterspace",      embedded quarter-space,    Alt-q
          "Special",           special character,         Alt-c
          "Parameter",         embedded parameter,        Alt-p
          "Edit Break",        break at point,            x
          "Edit Delete",       delete point,              d, Delete
          "Edit Insert",       insert point,              i, Insert
          "Edit Next",         go to next point,          e
          "Attach",            attach line to object,     A
          "Next Library",      go to next library,        l
          "Library Directory", library directory,         L
          "Library Move",      arrange library objects,   M
          "Library Copy",      get object in copy mode,   c
          "Library Edit",      edit library name,         E
          "Library Delete",    delete library object,     D
          "Library Duplicate", duplicate object,          C
          "Library Hide",      hide library object,       H
          "Page Directory ",   page directory,            P
          "Library Pop",       return from library,       <
          "Help",              generate help screen,      h, ?
          "Redraw",            redraw the window,         space
          "View",              fit page to window,        v
          "Zoom In",           zoom in,                   Z
          "Zoom Out",          zoom out,                  z
          "Pan",               center pan,                p
          "Double Snap",       increase snap space,       +
          "Halve Snap",        decrease snap space,       -
          "Pan Left",          pan left one-half page,    Left arrow
          "Pan Right",         pan right one-half page,   Right arrow
          "Pan Up",            pan up one-half page,      Up arrow
          "Pan Down",          pan down one-half page,    Down arrow
          "Write",             popup output window,       W
          "Rotate",            Rotate,                    r,R,o,O
          "Flip X",            Flip horizontal,           f
          "Flip Y",            Flip vertical,             F
          "Snap",              Snap to grid,              S
          "Pop",               Return from object edit,   <
          "Push",              Edit object,               >
          "Delete",            Delete element,            d
          "Select",            Select element,            Select
          "Box",               Create box,                b
          "Arc",               Create arc,                a
          "Text",              Create label,              t
          "Exchange",          Exchange vertical order,   X
          "Copy",              Copy element,              c
          "Join",              Join into path,            j
          "Unjoin",            Split path into elements,  J
          "Spline",            Create spline,             s
          "Edit",              Edit element,              e
          "Undelete",          Undelete last deleted,     u
          "Select Save",       Make object from selected, M,m
          "Unselect",          Unselect element,          x
          "Dashed",            Set line style to dashed,  |
          "Dotted",            Set line style to dotted,  :
          "Solid",             Set line style to solid,   _
          "Prompt",            Execute from command line, %
          "Dot",               Place dot at location,     .
          "Exit",          Exit xcircuit          Ctrl-Alt-q
          "Netlist",       Generate a netlist,    Alt-q
          "Swap",          Swap schematic, symbol,     /
          "Pin Label",          Create pin label,      T
          "Info Label",    Create info label,     I
          "Connectivity",  Show wire connectivity,     Alt-w
          "Sim",      Generate sim netlist,       Alt-s
          "SPICE",         Generate SPICE netlist,     Alt-S
          "PCB",      Generate PCB netlist,       Alt-p
          "SPICE Flat"          Generate flattened SPICE,  Alt-f
          ------------------------------------------------------------------

       2-Button mouse users may find it  useful  to  forego  the  Shift-Button1  combination  and
       instead put the following commands in the startup script:

       bind('Escape', 'Cancel')
       unbind('Button3', Cancel')
       bind('Button3', 'Finish')

       This  will  move  the 3rd mouse button bindings to the "Escape" key, and duplicate the 2nd
       mouse button bindings onto the 3rd.

X DEFAULTS

       The color scheme of xcircuit has a default setup,  but  accepts  alternate  color  schemes
       using  the following keywords which can be put in the X Defaults (.Xdefaults, .Xresources)
       file, such as:

         !
         ! Sample X defaults for xcircuit, black-on-white version
         !
         xcircuit*foreground     : Black
         xcircuit*background     : White
         xcircuit*gridcolor      : Gray85
         xcircuit*snapcolor      : Orange
         xcircuit*selectcolor    : Blue
         xcircuit*querycolor     : Green
         xcircuit*axescolor      : NavajoWhite3
         xcircuit*offbuttoncolor : Gray30
         xcircuit*auxiliarycolor : MediumOrchid1

       Two color schemes are supported at a time, ostensibly for  those  people  who  prefer  the
       lessened eye strain of a white-on-black scheme.  The names of the secondary colors are the
       same as those for the primary colors, but followed by "2", e.g., "xcircuit*foreground2".

       One other resource defines the number of minutes between automatic saves to the  temporary
       file (in case of a crash or emergency Ctrl-C exit):

         xcircuit.timeout       : 15

       Xcircuit also recognizes the core resources, such as width and height:

         xcircuit.width         : 600
         xcircuit.height        : 500

       All  xcircuit foreground and background colors are taken from the Xdefaults foreground and
       background.  To get, for instance, white-on-black menus and buttons with a  black-on-white
       drawing area, use the following:

         xcircuit*foreground         : White
         xcircuit*background         : DarkSlateGray
         xcircuit.foreground         : Black
         xcircuit.background         : White
       This will ensure that only the drawing area is black-on-white, but all other
       windows will appear in the less eye-straining white-on-black.
       Five different fonts can be specified in the Xdefaults.  helpfont is
       the style of fonts on the help popup window.  filefont is the style
       of fonts in the list of files in the file selection popup window.  textfont
       is the style of font for entering text in the popup dialog boxes.  titlefont
       is the style of font for the cascade menu titles.  All other fonts take the
       type font. For example:
         xcircuit*font           : *times-bold-r-normal--14*
         xcircuit*helpfont   : *times-medium-r-normal--12*
         xcircuit*filefont   : *times-medium-r-normal--14*
         xcircuit*textfont   : *courier-medium-r-normal--14*
         xcircuit*titlefont       : *times-bold-r-normal--18*

FILES

       The  file  path  used  by xcircuit to find library files is system-dependent (i.e., can be
       changed at compile time), and can be overridden in many ways (in  .xcircuitrc  or  by  the
       XCIRCUIT_LIB_DIR environment variable), but by default is:

       /usr/lib

       xcircps2.pro   PostScript prolog appended to each file

       xcstartup.tcl  This startup script contains commands of the type library name number which
                      cause the designated library name to be  immediately  loaded  into  library
                      page number.  The startup script is also responsible for loading fonts, and
                      may also be used to load colors on the color palette,  set  other  options,
                      and execute commands.

       generic.lps, analog.lps, digital.lps, avlsi.lps, analoglib2.lps
                      Files  containing  pre-compiled  circuit  elements.   The .lps extension is
                      unique for xcircuit libraries.

       fonts          This subdirectory contains font definition  files  for  xcircuit's  vector-
                      drawn  fonts.   Characters  are defined by xcircuit objects and stored in a
                      .lps library.  The encoding scheme and other font information is stored  in
                      a .xfe ("xcircuit font encoding") file.

       ~/.xcircuitrc or ./xcircuitrc
                      Personal  xcircuit  initializer;   commands  are outlined above.  Libraries
                      listed in this file will be appended to the builtin libraries.

ENVIRONMENT VARIABLES

       xcircuit understands the following environment variables:

       TMPDIR         Directory for temporary (e.g., backup) files (defaults to TEMP_DIR).

       XCIRCUIT_LIB_DIR
                      Directory where xcircuit libraries and startup files can be found (defaults
                      to BUILTINS_DIR).

       XAPPLRESDIR    Directory where the xcircuit application defaults can be found (defaults to
                      RESOURCES_DIR)

       HOME           Directory where xcircuit will look for startup files, after  searching  the
                      current directory.

       HOST, HOSTNAME, USER
                      Environment  variables which xcircuit uses to fill in header information in
                      the PostScript output (HOST and HOSTNAME are equivalent).

BUGS

       PostScript printers have device-dependent limits on the  number  of  statements  within  a
       "def"  definition.   If  an object definition has an unusually large number of components,
       xcircuit will flag a warning when writing the file.  However, there is no  way  to  ensure
       that  a file will be accepted by a given printer.  The best way to avoid the problem is to
       make sure that large drawings make good use of hierarchically nested user-defined objects.
       Note that printer errors arising from this problem have not been observed in practice, and
       given the typical size of on-board memory on most modern laser  printers,  probably  never
       will be.

       A list of bugs can be found in the Manifest file in the source directory.

ONLINE TUTORIAL

       Look for the xcircuit online tutorial at

       http://opencircuitdesign.com/xcircuit/tutorial/tutorial.html

SEE ALSO

       xfig(1),  another  powerful freeware drawing program worthy of mention (see www.xfig.org).
       Another schematic capture package worth noting is "gschem"  from  the  gEDA  package  (see
       www.geda.seul.org).

NOTES

       PostScript is a registered trademark of Adobe Systems Incorporated.
       XCircuit  Copyright (c) 2002 Tim Edwards.  XCircuit is freely distributed under a generous
       public license.  See the source distribution for details.
       Xw widget set  Copyright  (c)  1988  by  Hewlett-Packard  Company  and  the  Massachusetts
       Institute of Technology.

AUTHOR

       Tim  Edwards  <tim@opencircuitdesign.com>.   Thanks  to  Tomas  Rokicki for the PostScript
       routine which manufactures a Symbol-Oblique font.   Thanks  to  Dave  Gillespie  and  John
       Lazzaro for the program "analog" on which the graphical interface of xcircuit is (roughly)
       based.  Thanks to many beta-testers, some of whom were kind enough to send patches.   Most
       contributors have been named in the Manifest file in the source distribution.