Remove usage of *TypePtr and *TypeHandle type aliases

[geda-pcb/pcjc2.git] / doc / pcb.texi

\input texinfo    @c -*-texinfo-*-
@comment %**start of header
@setfilename pcb.info
@settitle Pcb
@setcontentsaftertitlepage
@macro pcb{}
@code{Pcb}
@end macro
@comment %**end of header

@include version.texi

@ifinfo
@format
INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* pcb: (pcb).                   An interactive printed circuit board editor.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@iftex
@finalout
@end iftex

@ifinfo
This file documents how to use Pcb,
the open source, interactive printed circuit board layout system.

Copyright (C) 1994,1995,1996, 2004 Thomas Nau

Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 harry eaton

Copyright (C) 2003, 2004, 2005, 2006, 2007, 2009 Dan McMahill

Copyright (C) 2004 DJ Delorie

This program is free software; you may redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANT-ABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@b{GNU General Public License} for more details.

@end ifinfo

@setchapternewpage on
@headings single

@titlepage
@title Pcb-@value{VERSION}
@subtitle an open source, interactive
@subtitle printed circuit board
@subtitle layout system
@author harry eaton
@end titlepage

@ifnottex
@node Top
@top Pcb

This document is a manual for @pcb{}, the open source, interactive printed circuit
board layout system.
@end ifnottex

@menu
* Copying::                @pcb{} is freely redistributable!
* History::                How it all began.
* Overview::               An overview of @pcb{}.
* Intro::                  A short description of the basic objects.
* Getting Started::        Introduction to @pcb{}.
* Autorouter::             Using the autorouter.
* User Commands::          User commands of @pcb{}.
* Command-Line Options::   Calling @pcb{} from a shell.
* X11 Interface::          Action routines, resources and default translation.
* File Formats::           Description of @code{ASCII} files used by @pcb{}.
* Library Creation::       Detailed description of symbol library creation.
* Schematic Frontends::    Schematic capture programs that work with PCB.
* Installation::           Compiling, installing and troubleshooting.
* Custom Menus::           Customizing the menu bar.
* Regular Expressions::    Searching for elements with regular expressions
* Standard Drill Sizes::   Tables of standard drill sizes
* Centroid File Format::   Details of the centroid (x-y) output file
* Annotation File Format:: Details of the back annotation output file
* Action Reference::       Documentation for all available actions
* Glossary::               Glossary
* Index::                  The Index.
@end menu

@c ---------------------------------------------------------------------
@node Copying
@unnumbered Copying

Copyright @copyright{} 1994,1995,1996,1997 Thomas Nau

Copyright @copyright{} 1998,1999,2000,2001,2002 harry eaton

This program is free software; you may redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANT-ABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
@b{GNU General Public License} for more details.


@c --------------------------- chapter 0 -------------------------------
@node History
@unnumbered History

@cindex Atari version
@pcb{} is a handy tool for laying out printed circuit
boards.

@pcb{} was first written by Thomas Nau for an Atari ST in 1990 and
ported to @code{UNIX} and @code{X11} in 1994.
It was not intended as a professional layout system,
but as a tool which supports people who do some
home-developing of hardware.

The second release 1.2 included menus for the first time. This made
@pcb{} easier to use and thus a more important tool.

Release 1.3 introduced undo for highly-destructive commands,
more straightforward action handling and scalable fonts. Layer-groups
were introduced to group signal-layers together.

Release 1.4 provided support for add-on device drivers.
Two layers (the solder and the component side)
were added to support SMD elements. The handling of libraries
was also improved in 1.4.1. Support for additional devices like
GERBER plotters started in 1.4.4. The undo feature was expanded
and the redo-feature added in 1.4.5.

harry eaton took over pcb development beginning with Release 1.5,
although he contributed some code beginning with Release 1.4.3

Release 1.5 provides support for rats-nest generation from simple net
lists.  It also allows for automatic clearances around pins that pierce
a polygon.  A variety of other enhancements including a Gerber RS-274X
driver and NC drill file generation have also been added.

Release 1.6 provides automatic screen updates of changed regions.
This should eliminate most of the need for the redraw ((@emph{R} key).
Also some changes to what order items under the cursor are selected
were made for better consistency - it is no longer possible to
accidentally move a line or line point that is completely obscured
by a polygon laying over top of it.  Larger objects on the upper
most layers can be selected ahead of smaller objects on lower layers.
These changes make operations more intuitive.  A new mode of line
creation was added that creates two line on 45 degree angles
with a single click. The actual outline of the prospective line(s) are
now shown during line creation.  An arc creation mode was added.
Drawn arcs are quarter circles and can be useful for high frequency
controlled impedance lines.  (You can have eighth circle arc if the
source is compiled with -DARC45, but be aware that the ends of such
arcs can never intersect a grid point).  Two new flags for pins and
vias were created - one indicates that the pin or via is purely a
drill hole and has no copper annulus.  You can only toggle this flag
for vias - for elements, it must be an integral part of the element
definition.  The other flag controls whether the pad will be round
or octagonal.  There is also now a feature for converting the contents
of a buffer into an element.

Release 1.6.1 added the ability to make groups of action commands bound to
a single X11 event to be undone by a single undo. Also a simple design rule
checker was added - it checks for minimum spacing and overlap rules. Plus
many fixes for bugs introduced with the many changes of 1.6

Release 1.7 added support for routing tracks through polygons without touching
them. It also added support for unplated drill files, and drawing directly
on the silk layer. A Netlist window for easily working with netlist was also added.

Release 2.0 adds an auto-router, a new simpler library mechanism, much improved
support for graphically creating (and editing) elements, viewable solder-mask
layers (and editing), snap to pins and pads, netlist entry by drawing rats, element
files (and libraries) that can contain whole sub-layouts, metric grids, improved
user interface, a GNU autoconf/automake based build system, and a host
of other improvements.

Special thanks goes to:
@display
Thomas Nau (who started the project and wrote the early versions).
C. Scott Ananian (who wrote the auto-router code).
Bernhard Daeubler (Bernhard.Daeubler@@physik.uni-ulm.de)
Harald Daeubler (Harald.Daeubler@@physik.uni-ulm.de)
DJ Delorie (djdelorie@@users.sourceforge.net)
Larry Doolittle (ldoolitt@@recycle.lbl.gov)
Dan McMahill (danmc@@users.sourceforge.net)
Roland Merk (merk@@faw.uni-ulm.de)
Erland Unruh (Erland.Unruh@@malmo.trab.se)
Albert John FitzPatrick III (ajf_nylorac@@acm.org)
Boerge Strand (borges@@ifi.uio.no)
Andre M. Hedrick (hedrick@@Astro.Dyer.Vanderbilt.Edu)
@end display

@noindent
who provided all sorts of help including porting @pcb{} to
several operating systems and platforms, bug fixes, library enhancement,
user interface suggestions and more. In addition to these people,
many others donated time for bug-fixing and
other important work. Some of them can be identified in the source code
files.  Thanks to all of them. If you feel left out of this list, I
apologize; please send me an e-mail and I'll try to correct the omission.


@c --------------------------- overview chapter -------------------------------
@node Overview
@chapter Overview
@cindex PCB, an overview

@pcb{} is an open source printed circuit board editor.
@pcb{} includes many professional features such as:
@itemize @bullet
@item Up to 16 copper layer designs by default.  By changing a compile time setting, this
can be set as high as needed.
@item RS-274X (Gerber) output
@item NC Drill output
@item Centroid (X-Y) data output
@item Postscript and Encapsulated Postscript output
@item Autorouter
@item Trace optimizer
@item Rats nest
@item Design Rule Checker (DRC)
@item Connectivity verification
@item @pcb{} is Free Software
@item Can interoperate with free schematic capture tools such as gEDA and
  xcircuit
@item Runs under Linux, NetBSD, Solaris, and other similar operating
systems.
@item Windows version is available
@end itemize

@c --------------------------- chapter 1 -------------------------------
@node Intro
@chapter Introduction
@cindex layout objects, an overview

Each layout consists of several, mostly independent, objects. This chapter
gives an overview of the object types and their relationship to each other.
For a complete description of how to use @pcb{}, refer to
@ref{Getting Started}.
The layout is generated on-screen on a grid that can have its origin
at any desired location.
The X coordinate increases to the right, Y increases down to the bottom.
All distances and sizes in @pcb{} are measured in mils
(0.001 inch).  One unit on the coordinate display is one mil in
distance on the board. 
The grid may be set on a metric pitch, but is only correct to within
the nearest +/- 0.01 mil because @pcb{} stores all dimensions as
integer multiples of 1/100 of a mil or 0.00001 inch.

The sections in this chapter are sorted by the
order of appearance of the objects within a layout file.

@menu
* Symbol Objects::         Information about fonts and symbols.
* Via Objects::            Vias and pins connect layers.
* Element Objects::        Element, the basic type of circuits.
* Layer Objects::          A @samp{container} for lines, text...
* Line Objects::           Tracks on the board
* Arc Objects::            Curved tracks
* Polygon Objects::        Planes and such
* Text Objects::           Objects to add symbols to your board.
* Net Objects::            Describes the desired connections on the board.
@end menu

@node Symbol Objects
@section Symbols
@cindex symbols, an overview
@cindex font, an overview

The top object is the layout itself. It uses a set of symbols
that resides at the first logical level. Each symbol is uniquely identified
by a seven bit @code{ASCII} code. All layout objects share the same set of
symbols. These symbols are used to form text objects on the silkscreen
and copper layers.  Undefined symbols are drawn as filled rectangles.

Every font file is preprocessed by a user-defined command when it is loaded.
For details see @samp{fontCommand}, @ref{Resources}.


@node Via Objects
@section Vias
@cindex vias, an overview

Vias provide through-hole connectivity across all layers.
While vias look a lot like element pins, don't use vias
for adding elements to the layout, even if that seems
easier than creating a new element. The default solder-mask
will cover over vias, so you won't be able to solder to them.
Of course, you can change this so that vias also have
solder-mask cut-outs, but it is not the default.
Vias are also useful for defining arbitrary drill points such as
those used for mounting a board. Vias used in this way have
a special flag set so that they have no annular copper ring,
and also appear in the unplated drill file. @emph{Ctrl-H} key over
a via switches it between being a pure-mounting hole and a regular via.
You can assign a name to a via, which is useful during the creation
of new element definitions.
Each via exists on all copper layers. (@emph{i.e.}
blind and buried vias are not supported)


@node Element Objects
@section Elements
@cindex element, an overview
@cindex layout-name

Elements represent the components on a board.
Elements are loaded from @code{ASCII} coded files in a
similar manner to the layout file itself, or from the
library selector window.
An element is composed of lines and arcs on the silk-screen
layer (used to define the package outline), pins
(or pads for SMD) and three labels that define the
description, the element's layout-name (which also
appears on the silk-screen layer) and its value. You
can choose which of the names are displayed on the screen
with the @b{Screen} menu; however, the silk screen in
the printout will always show the layout-name.
Element pins are contained on the first logical level
and so reside on all layers, but the pads of surface-mount
elements reside on only the component or solder
layers. An element can have a mixture of pins, pads
(on one or both sides), and mounting holes.

A mark is used to position the element with
respect to the cross hair during pasting.
The mark will lie on a grid point when the element
is positioned.  The mark is drawn as a small diamond
shape, but is only visible when @emph{both} the @code{silk}
and @code{pins/pads} layers are visible.
All parts of an element are treated as one unit, except for
the name.
It is not possible to delete a single pin or move
only part of an element on the layout.
You can resize separate pieces of an element,
but doing so is usually a bad idea. You can move/rotate
the element name independently of the element it belongs
to. When you move an element name, a line is draw from
the cursor to the element mark so it is easy to tell
which element the name belongs to.


Each pin and pad has two string identifiers, one is the
"name" which is a functional description of the pin
(@emph{e.g.} "clock in") and the other is the "number" of the
pin which is used to identify it in a netlist. The "number"
is usually an integer, but it can be any string. You
can edit the "name" of each pin of an element, but the
"number" is embedded in the element definition and is
determined when the new element is first created.
Pads are similar to lines on a layer but they must be oriented
either vertically or horizontally.
Pads can have either rounded or square ends. Pins
can be round, square, or octagonal.


Elements are supported by several special layers: @code{silk}, @code{pins/pads} and
@code{far-side}.  The @code{silk} layer shows the package outline and
also holds legend text and element names. The @code{pins/pads} layer is used to toggle
whether the element's pins and pads are displayed. The @code{far-side} layer controls visibility
of objects (silkscreen and pads) that are on the far (@emph{i.e.} not currently viewed) side
of the board.

The ``oldlib'' style of footprint libraries distributed with
@pcb{} rely upon the M4 macro processor.  M4 is typically
installed under the name @code{m4} on most unix-like operating
systems.  It is recommended that you use the GNU version of M4 to
avoid limitations found in some vendor implementations.  See the m4
man page on your system for more information.
Every element file is preprocessed by a user-defined command when the file is read.
For details see @samp{elementCommand}, @ref{Resources}. @code{m4}, the default
value of @samp{elementCommand}, allows you to create libraries for
package definitions that are shared by all elements.
The old element libraries distributed with @pcb{} expect @code{m4} or an
equivalent to be the @emph{elementCommand}. The new library scheme simply has
each element stored in a self-contained file, so there is no need to learn
@code{m4} to add to the libraries.

@pcb{} can create a list of
all connections from one (or all) elements to the others or a list of
unconnected pins.
It can also verify the layout connections against a netlist file.
The element's @samp{layout-name} is the name used to identify the element
in a netlist file (see @ref{Netlist File}).

The old libraries, or very old (pre-1.6) layout files may have
incorrect pin numbering since there was no concept of pin numbers
when they were created. @pcb{} uses the order of appearance of
the pin definitions in the layout or library file if it uses the
old format, but there is no guarantee that it will be correct for
these old objects.

@cindex old library
@cindex library accuracy
@b{Be aware that a few of the old library parts may still be incorrectly
implemented regarding pin-numbering.}  All of the DIL (Dual-
Inline-Pins) parts are correct and most of the others are too,
but you should verify the pin numbering
of any non-DIL part before using an old library part.
(use the @samp{generate object report} in the @b{Info} menu
to see what @pcb{} thinks a pin's number is)
All of the old
library names begin with a ~, so you can easily identify them.
The old libraries also @emph{may} contain other sorts of errors,
including incorrect pin spacing, silkscreen overlapping solder areas, etc.
@b{Check carefully any element in the old library before using it!}
As the new library grows, the old library will be pared down to
at least remove all of the elements with errors, but this will
take time.

You can make your own element definitions graphically now.
Simply draw vias for the pins, lines on the solder and/or
component layers for surface-mount pads (they must be either horizontal
or vertical),
and lines and arcs on the silkscreen layer for the silkscreen
outline. You should @emph{name} (@emph{N} key) each via and copper line with the pin @emph{number}.
Once you are happy with the geometry, select everything that is to become part of
the element, then choose @samp{convert selection to element} from the @b{Select} menu.
Afterwords you can make pin (or pad) one
square if you like, and give the element its various names. You can also give
the pins and pads their functional names. Note that the
element mark corresponds to the position you click after choosing the
conversion from the menu, so decide where the mark goes and make
sure it falls on a grid point before you request the conversion.
If the vias/lines are not named, then the pin numbering will correspond to the
order in which they were placed.

When you create a new element, remember that silkscreen lines
should @emph{never} overlap the copper part of the
pins or pads, as this can interfere with soldering. The silkscreen
should identify the maximum extent of the element package so it
is easy to see how close elements can be placed together.

If you want to make an element similar to an existing one, you can
break an element into constituent pieces from the @b{Buffer} menu.
Paste the pieces to the layout, make the necessary changes, then
convert it back into an element. If the pin numbers haven't changed,
there is no need to name each via/line as they are pre-named when
the element was broken apart. When you create a new element, you
can save it to a file in order to have easy access to it the next
time you run @pcb{}.


@node Layer Objects
@section Layers
@cindex layers, an overview

Every layout consists of several layers that can be used independently
or treated as a group.
Layer groups can be used to logically separate (and color-code)
different traces (@emph{e.g.} power and signal); however, all
layers within a group reside on the same physical
copper layer of a board, so using different layers within the same
group won't provide electrical separation where they touch or overlap.
For details, see @samp{layerGroups}, @ref{Resources}.
Each layer is drawn in a color defined in the resource file
and identified by a name that you can change (for details
see @samp{layerColor}, @ref{Resources}.)
Layers are really just containers for line, arc, polygon, and text objects.  The
component and solder layers contain SMD elements as well, but the
file structure doesn't reflect that fact directly.

@cindex layer groups
Each layer group
represents a physical layer on the printed circuit board.  If you want to make
a four layer board, you'll need to have at least four layer groups.
Connections between layer groups are established only through element pins and vias.
The relationship between a specific layer and the board itself is configurable from
the @samp{Edit layer groups} option in the @b{Settings} menu.
The layer groups corresponding to the physical layers: @emph{component-side}
and @emph{solder-side} are always defined and you must map at least one
logical layer to each, even if you plan to make a single-sided board.
You are not obligated to put tracks on either of them.
Surface mount elements always reside on either the component-side or the
solder-side layer group. When you paste an element from the buffer,
it will go onto whichever side of the board you are viewing.
You can swap which side of the board you are viewing by pressing
the @emph{Tab} key, or by selecting @samp{view solder side} from the
@b{Screen} menu.
The layer groups just have a name or number associated with them - where
they are sandwiched in the board is left for you to tell the
manufacturer.

The silkscreen layer is special because there are actually two silkscreen
layers, one for the top (component) and one for the bottom (solder) side
of the board. Which silk layer you draw on is determined by the side of the
board that you are viewing. If you are viewing the component side, then
drawing on the silk layer draws to the component-side silk layer.

The netlist layer is another special layer. It shows rat's-nest lines
(@emph{i.e.} guides that show how the netlist expects the element to interconnect).
If you make this the active layer, you can use the Line tool to add
entries into the netlist, or to delete connections from the netlist
window. Except for these two purposes, you should not
make the netlist layer the active layer. Usually there is no need to
do this because a separate schematic package should be used to create the
netlist. @pcb{} can automatically draw all of the rats from
the netlist. In some cases you may want to make a small change without
going to the trouble of modifying the schematic, which is why this
facility is provided.


@node Line Objects
@section Lines
@cindex lines, an overview

Lines are used to draw tracks on the pc board.
When in the line mode, each @emph{Btn1}
press establishes one end of a line.
Once the second point is defined, the line is drawn
and a new line started where the first one ended.
You can abandon the new starting point in favor
of another by pressing @emph{Ctrl-Btn1}, or
@emph{Btn3}, but don't use @emph{Btn2}.
The undo function (@emph{U} key or @samp{undo last operation}
from the @b{Edit} menu) will take you back
point by point if you use it while in the line mode.

@cindex two line mode
New lines can be restricted to 45 degree angles if desired. You can toggle this
restriction on and off while creating lines by pressing the @emph{period} key.
If the 45 degree restriction is turned on, then the @emph{/} (forward slash) key
can be used to cycle through three different modes of 45 degree line creation.
One mode just creates a single line forced to the nearest 45 degree vector.  The next
mode creates two lines from the start to end points such that the first line leaves the
start point at a 90 degree vector, and the second line enters the end point on a 45
degree vector. The last mode creates two lines such that the first line leaves the
start point on a 45 degree vector and arrives at the end point on a 90 degree vector.
You can temporarily swap between the last two modes by holding the @emph{Shift} key down.

It is simple to edit a line object by breaking it into pieces (insert point mode),
moving an end point or the whole line (@emph{Arrow tool}),
or changing the layer it resides on (@emph{M} key moves the line under the pointer
to the active layer).
In the case when two line segments meet at exactly the same
point you can delete the intermediate point, otherwise the delete tool removes an entire line.
Feel free to experiment
since @pcb{} will allow you to undo and redo anything that materially affects your work.
If you switch active layers in the midst of placing lines a via will automatically be
placed, when necessary, in order to continue the connection.

@cindex clearance
If you draw a line inside a polygon, it will either plow through the
polygon creating a clearance, or touch the polygon. This behavior is
selectable in the @b{Settings} menu for new lines. To change the
behavior of an existing line, hit the @emph{J} key with the cross hair
over the line. You can increase the size of the clearance by 2 mils on
each edge with the with the
@emph{K} key. @emph{Shift-K} will decrease the clearance by 2 mils.
The increment may be changed from 2 mils through the application
resource file.
The clearance can be also increased, decreased and set
by the @emph{ChangeClearSize} action.

Lines do not need to intersect the center of a pin, pad, via, or other
line for @pcb{} to understand that they make electrical connection.
If the connection is too tenuous, running the design rule checker will report
that the connection may break if the line width shrinks slightly.


@node Arc Objects
@section Arcs
@cindex arc

@pcb{} can handle arcs of any angular extent, but when you
create an arc with the Arc tool, it will
be a quarter circle (this means they always bend a right angle).  Arcs are very similar
to lines otherwise.  They are created on the active layer and have the same thickness
that new lines will have.  The various clicks for creating lines work pretty much the
same way for creating arcs.
In order to make the arc curve in the desired direction, drag the mouse along
the tangent line from the starting position towards the end position. If the grid is
too coarse, it may not be possible to distinguish whether you've moved over then up,
or up then over, so if you can't seem to make the arc go in the direction you want, try pressing
the @emph{Shift} key while drawing the arc. Decreasing the grid spacing may also help.
Alternatively you can draw the wrong arc, then
rotate and move it where you want. Like the Line tool, after an arc is drawn a new
starting point is established at the end point.

Whenever a starting point is established
by either the Line or Arc tools it will be retained if you switch directly between the
tools (e.g. @emph{F2} key for Lines, @emph{F8} key for Arcs. Arcs can either touch or
clear polygons just like lines do. Of course connection
searches, undo and all the other features you'd expect work with arcs too.


@node Polygon Objects
@section Polygons
@cindex polygon, an overview

Sometimes it's useful to fill large areas with solid copper.
The way to do this is with polygons.
Polygons can be created in either the polygon mode or the rectangle mode.
In the polygon mode, you'll have to define each corner of the polygon
with a mouse click (@emph{Btn1}). When the last point is clicked
exactly on top of the starting point, the polygon is finished.
Since this can be hard to do, the @emph{Shift-P} key will enter the
final point for you, closing the polygon.
If the 45 degree angle restriction is turned on
and you try to close the polygon when it is not possible, you'll get a
warning instead. If you haven't finished entering a polygon, but want to
undo one (or more) of the points that you've already defined, use the
undo command (@emph{U} key).

With the rectangle tool, defining
the two diagonally opposite corners is sufficient, but of course the resulting
polygon is a rectangle.
Like lines, a polygon can by edited by deleting, inserting and moving the points
that define it. Pins and vias @emph{always} clear through polygons without
touching them when first positioned. You must add a thermal with the thermal
tool in order to connect pins and vias to polygons. Thermals can be added and removed by
clicking @emph{Btn1} with the thermal tool over the pin or via.
The thermal tool always
places a thermal to polygons on the active layer, so if the tool doesn't
seem to work, it's probably because the polygon you want to touch is not
on the active layer.  You can change the style of thermal used or make
a solid connection by holding down @emph{Shift} while clicking
@emph{Btn1} with the thermal tool over the pin or via.

@pcb{} is capable of handling complex polygons, but
using a number of simpler ones improves performance of the connection tracing code.
You also must be careful not to create polygons that touch or overlap themselves.
The fabricated board may not look the way you expect if you violate this
principle. It is always ok to have two (or more) polygons touch or overlap
each other, but not for points within the same polygon to do so.

The great advantage to this new polygon behavior is that simple or complex ground
and/or power planes can be easily made with polygons and seen on the screen.
If you don't want this auto-clearance behavior, or you load a layout created by
an early version of @pcb{}, the old behavior
(shorts to all piercing pins and vias) is available.  A @samp{ChangeSize}
operation (@emph{S} key) toggles a polygon between the new and old polygon/pin
behavior.


@node Text Objects
@section Text
@cindex text, an overview
@cindex strings, an overview

Text objects should be used to label a layout or to put additional
information on the board. Elements have their @samp{layout-name} labels on the
silk-screen layer. If you are making a board without a silkscreen,
you can use copper text to label the elements, but you have to do
this manually.

Text is always horizontal when first created, but the
rotate mode can align it along 0, 90, 180 and 270 degree angles.
Text on the far side of the board will automatically appear mirror-imaged.

@emph{Warning:} @b{TEXT OBJECTS ON A COPPER LAYER CREATE COPPER LINES BUT THEY ARE NOT SCANNED FOR
CONNECTIONS OR TESTED FOR CREATING SHORTS VS. THE NETLIST. NEITHER ARE TEXT OBJECTS TESTED AGAINST ANY DESIGN RULES}.


@node Net Objects
@section Nets
@cindex rats-nest
@cindex netlist

Layout files also contain the netlist that describes how the elements
are supposed to be interconnected. This list of connections can be
loaded from a netlist file (see @ref{Netlist File}), or
entered by drawing rat-lines as described
previously. Each net has a name and routing style associated with it.
The net contains a list of all element @emph{layout-name} names and
pin @emph{numbers} that should
be connected to the net. Loading a netlist file will replace all
existing nets with the ones from the file.
The @emph{Netlist} window provides an easy way to
browse through the net list. You can display the rat's-nest by selecting
@samp{optimize rats-nest} from the @b{Connects} menu. If you move or rotate elements,
the rat's-nest will automatically follow the movements, but they won't
necessarily show the shortest paths until you optimize them again.

@c --------------------------- chapter 2 -------------------------------
@node Getting Started
@chapter Getting Started
@cindex how to start

The goal of this chapter is to give you enough information to learn how
@pcb{} works and how to develop your layouts to make the best use of @pcb{}'s
features. All event translations (@emph{i.e.} the buttons and keys you
press) refer to the default application resource file shipped with @pcb{}.
There is probably no need to change this unless your window
manager uses some of the button events itself; however, if you @emph{want}
to customize the behavior of @pcb{} then changing the resource file
is usually the best way to do it.

Get yourself a printout of this chapter and @emph{User Commands}, if you
haven't already done so, and follow the examples.

Start @pcb{} (the actual command will use all lower-case letters)
without any additional options.
If you get the error message:

@display
    can't find default font-symbol-file 'default_font'
@end display
@noindent
then the font searchpath or filename in the application resource
file is wrong. Be sure that your @code{m4} program supports search paths.
If not, get @code{GNU m4}.
For other messages, see @ref{problems}.
Another quick-start is provided by @code{pcbtest.sh} in the @file{src}
directory. If some features don't seem to work, try running @code{pcbtest.sh},
if that works, then @pcb{} hasn't been installed properly.

@menu
* Application Window::     The elements of the main window.
* Log Window::             The optional logging window
* Library Window::         The circuit selection window
* Netlist Window::         The desired connections window
* Drawing and Removing::
* Moving and Copying::
* Loading and Saving::
* Printing::               Creating Gerber files or postscript files
* Exporting::              Exporting a layout.
* Arrow Tool::             Selecting/Moving objects.
* Rats Nest::              Helps you place and route tracks against a netlist.
* Design Rule Checking::   Check for manufactureability
* Trace Optimizer::        Optimization of layouts
* Searching for elements:: Searching for elements
* Measuring distances::    Measuring distances
* Vendor drill mapping::   Mapping drills to a vendor specified list
* Connection Lists::       How to get a list of all or some connections.
@end menu


@node Application Window
@section The Application Window

The main window consists of five areas:
the menu at the top, the layer control in the upper left, the tool buttons
located below the layer controls, the Layout area to the right of these, and the
status line at the bottom of the window.

@menu
* Menu::
* Status-line and Input-field::  What is the program configuration.
* Layer Controls::               Switch layers on/off; change current one.
* Tool Selectors::               Select a layout tool.
* Layout Area::                  Where the layout is drawn.
@end menu

@node Menu
@subsection Menus
@cindex menus
@cindex popping up menus

The menus are located at the top of the Layout area. Most, but not all,
of their functions are also available from the keyboard. Similarly, some
functions are only achievable through the keyboard or command entry.
Some menu entries such as @samp{center layout} in the @b{Screen} menu require a certain cross hair position.
In this case a prompt message will popup at the bottom of the screen
with wording similar to the following:
@example
move pointer to the appropriate screen position and press a button
@end example
Any mouse button will do the job, whereas any key except the arrow (cursor) keys
will cancel the operation. If it seems like the menu hasn't done what you
expected, check to see if it is waiting for the position click. For details see @ref{Actions}.

Pressing @emph{Btn3} in the Layout area also pops up a menu with many of the most common operations (except
when you're in the midst of drawing a line or arc). When
a choice in the @emph{Btn3} popup menu needs a cross hair position, it uses the position
where the cross hair was when @emph{Btn3} was pressed. For example, to get detailed
information on an object, place the cross hair over the object, press @emph{Btn3}, then
choose @samp{object report}.  If you pop up the @emph{Btn3} menu but don't want to
take any of the actions, click on one of the headers in the menu.

@table @b

@cindex File, popup menu
@item File
This menu offers a choice of loading, saving and printing data, saving
connection information to a file or quitting the application. Most
of the entries in the @b{File} menu are self explanatory.
Selecting
@samp{print layout} pops up a printer control dialog.
A selection of several device drivers is available from the printer control
dialog. Presently @emph{PostScript}, @emph{encapsulated PostScript},
and @emph{GerberX} are supported. The @emph{GerberX} driver produces
all of the files necessary to have the board professionally manufactured.
The connection saving features in the @b{File} menu produce outputs in an
arcane format that is not too useful. They do @emph{not} produce netlist
files.

@cindex Edit, popup menu
@cindex undo
@cindex redo
@item Edit
The @b{Edit} menu provides the usual cut, copy, paste
which work on selections. To learn how to
create complex selections, see @ref{Arrow Tool}.
The @b{Edit} menu also
provides access to Undo and Redo of the last operation. These
can also be accomplished with the @emph{U} key and @emph{Shift-R}
key.  Finally, the @b{Edit} menu allows you to change the names
of: the layout, the active layer, or text objects on the layout.

@cindex Screen, popup menu
@cindex displaying element names
@cindex element, display names of
@cindex grid, display
@cindex grid, alignment
@cindex zoom, setting
@item Screen
The @b{Screen} menu supports most functions related to
the whole Layout area. There are various entries to change the grid to some popular
values, the zoom factor, and which kind of element name is displayed.
You can also re-align the grid origin and turn on and off the display
of the grid.
Before changing the grid alignment, I recommend that you zoom in as close as
possible so that you're sure the grid
points appear exactly where you want them.

@cindex solder mask, viewing and editing
The @b{Screen} menu also allows you to turn on and off the
visibility of the solder-mask layer. When the solder-mask layer
is made visible it obscures most of the layout, so only turn
this on when you really want to know what the solder-mask will
look like. The solder-mask that you see belongs to the
side of the board you are viewing, which can be changed with
the @samp{view solder side} option, also found in the @b{Screen} menu.
When the solder-mask is displayed, the pin and pad clearance adjustments
(@pxref{Line Objects}) alter the size of mask cut-outs.

@cindex Sizes, popup menu
@item Sizes
The @b{Sizes} menu allows you to select a group of line thickness, via diameter, via drill
size, and clearance (keepaway) (collectively called a "routing style") to be copied to the "active" sizes.
You can also change the names given to the routing styles and adjust their values from
this menu.  The "active" sizes are also adjustable from this menu.
The "active" sizes are shown in the status-line and control the initial size of new vias,
drilling holes, lines, clearances, text-objects and also the maximum dimensions of the
board layout.

@cindex Settings, popup menu
@cindex unique names
@cindex rubber band
@cindex snap to pins
@cindex clearance, for new lines
@item Settings
The @b{Settings} menu controls several operating configuration
parameters. The @samp{edit layer groups} entry brings up a dialog
that allows you to change the way layers are grouped. Layer grouping
is described in @ref{Layer Objects}. The @samp{all-direction lines}
entry controls
the clipping of lines to 45-degree angles. You can also control
whether moving individual objects causes the attached lines to
"rubber band" with the move or not from the @b{Settings} menu. Another
entry controls whether the starting clip angle for the two-line
mode (@pxref{Line Objects}) alternates every other line. You can
also control whether element names must be unique from the @b{Settings}
menu.  When unique element names are enforced, copying a new element
will automatically create a unique @samp{layout-name} name for it
provided that the name originally ended with a digit (@emph{e.g.}
U7 or R6). The @b{Settings} menu allows you to control
whether the cross hair will snap to pins and pads even when they
are off-grid. Finally you can control whether new lines and
arcs touch or clear intersecting polygons from this menu.

@cindex Select, popup menu
@cindex selected objects, removing
@cindex selected objects, changing sizes
@item Select
This menu covers most of the operations that work with selected objects.
You may either (un)select all visible objects on a layout or only the ones
which have been found by the last connection scan see
@c DRM: not sure where this was suppose to xfef to.
@c @ref{find connections}
.
You can delete all selected objects from this menu.
Other entries in the @b{Select} menu change the sizes of selected objects.
Note that a select action only affects those objects that are
selected @emph{and} have their visibility turned on in the Layer Control
panel. The @b{Select} menu also provides a means for selecting objects
by name using unix @ref{Regular Expressions}.

@cindex Buffer, popup menu
@cindex pastebuffer, popup menu
@cindex element, editing
@item Buffer
From the @b{Buffer} menu you may select one out of five
buffers to use, rotate or clear its contents or save the buffer contents
to a file. You can also use the @samp{break buffer element to pieces} entry
to de-compose an element into pieces for editing.
Note: only objects with visibility turned on are pasted to the layout. If
you have something in a buffer, then change which side of the board you
are viewing, the contents of the buffer will automatically be mirrored
for pasting on the side you are viewing. It is not necessary to clear
a buffer before cutting or copying something into it - it will automatically
be cleared first.

@cindex Connects, popup menu
@cindex auto-router
@cindex design rule checker, invoking
@item Connects
The entries available through the @b{Connects} menu allow you to find
connections from objects and to manipulate these.
You can also optimize or erase rat's nests from this menu. Finally,
the @samp{auto-route all rats} entry allows you to auto-route
all connections show by the rat's nest. The auto-router will use
any visible copper layer for routing, so turn off the visibility of any
layers you don't want it to use. The auto-router will automatically
understand and avoid any traces that are already on the board, but
it is not restricted to the grid. Finally,
the auto-router routes using the active sizes (except for nets that
have a route-style defined). @pcb{} always knows which tracks
were routed by the auto-router, and you can selectively remove them
without fear of changing tracks that you have manually routed
with the @samp{rip-up all auto-routed tracks} entry in the @b{Connects}
menu.  The @samp{design rule checker} entry runs a check for copper
areas that are too close together, or connections that touch too
tenuously for reliable production. The DRC stops when the first
problem is encountered so after fixing a problem be sure to
run it again until no problems are found.
@display
@emph{Warning:} @b{COPPER TEXT IS IGNORED BY THE DRC CHECKER}.
@end display

@cindex Info, popup menu
@cindex report
@cindex object report
@cindex drill report
@item Info
The @samp{generate object report} entry from the @b{Info} menu
provides a way to get detailed information
about an object, such as its coordinates, dimensions, etc.
You can also get a report summarizing all of the drills
used on the board with @samp{generate drill summary}. Lastly,
you can get a list of all pins, pads and vias that were
found during a connection search.

@cindex Window, popup menu
@item Window
The @b{Window} menu provides a way to bring each of @code{Pcb's}
windows to the front. The @emph{Library} window is used to
bring elements from the library into the paste-buffer. The
@emph{Message Log} window holds the various messages that
@pcb{} sends to the user. The @emph{Netlist} window shows
the list of connections desired.

@end table

Now that you're familiar with the various menus, it's time
to try some things out. From the @b{File} menu choose
@samp{load layout}, navigate to the tutorial folder, then
load the file @samp{tut1.pcb}.


@node Status-line and Input-field
@subsection The Status-line and Input-field
@cindex status information
@cindex displaying status information
@cindex input-field, position of

The status-line is located at the bottom edge of the main window.
During normal operation the status information is visible there.
When a selected menu operation requires an additional button click, the
status-line is replaced by a message telling you to position the cursor
and click.
When a text input is required, the status-line is replaced by the
Input-field which has a prompt for typing the input.

The status-line shows, from left to right, the side of the board that you
are viewing (@emph{Tab} key changes this), the current grid values,
if new lines are restricted to 45 degrees,
which type of 45 degree line mode is active, whether rubberband move and
rotate mode is on (R), and the zoom factor.
This information is followed by the active line-width, via-size
and drilling hole, keepaway spacing, and text scaling. Last is the active buffer number and the
name of the layout. An asterisk appearing at the far left indicates that the
layout has been modified since the last save.
Note that the name of the layout is not the same
thing as the filename of the layout.
Change the grid factor to 1.0 mm from the @b{Screen} menu. Observe how the
status line shows the new grid setting. Except for the case of the metric
grid, all dimensions in the status line are in units of 0.001 inch (1 mil).

The input-field pops up (temporarily replacing the status-line) whenever user input
is required. Two keys are bound to the input field: the @emph{Escape} key
aborts the input, @emph{Return} accepts it. Let's change the name of a component
on the board to see how the input-field works. Position the cross hair over
R5, and press the @emph{N} key. The input field pops-up showing the name
for you to edit. Go ahead and change the name, then hit return. Notice the name
of the element changed. Now undo the change by pressing the @emph{U} key. You can
position the cross hair over the name, or the element before pressing the
@emph{N} key.

Now select @samp{realign grid} from the @b{Screen} menu. Notice that the
status line has been replaced with an instruction to position the cursor
where you want a grid point to fall. In this case, since the cross hair
can only fall on a grid point, you must move the tip of the finger cursor
to the place where you want a grid point to appear. Do not worry that
the cross hair is not coincident with the cursor. Click @emph{Btn1} at
your chosen location. See how the grid has shifted, and the status line
has returned.

The present cross hair position is displayed in the upper right corner of the window.
Normally this position is an absolute coordinate, but you can anchor a marker at
the cross hair location by pressing @emph{Ctrl-M} (try it now) and then the
display will read both the absolute cross hair position as well as the difference
between it and the marker. The numbers enclosed in < > are the X and Y distances
between the cross hair and the mark, while the numbers enclosed in parenthesis
are the distance and angle from the mark to the cross hair. The values displayed
are always in units of 0.001 inch (1 mil).
Pressing @emph{Ctrl-M} again turns the marker off.

@node Layer Controls
@subsection The Layer Controls
@cindex layer controls
@cindex layers, switching on/off
@cindex layers, changing which is active
@cindex change active layer

The layer control panel, located in the upper left, is used to turn on
and off the display of layer groups and to select the active drawing layer.
If a layer hasn't been named, the label "@emph{(unknown)}" is used as the default.
If this happens, it probably means the application resources are not installed
properly.

The upper buttons are used to switch layers on and off. Click
@emph{<Btn1>} on one or more of them. Each click toggles the setting.
If you turn off the currently active layer, another one that is visible
will become active. If there are no others visible, you will not be
able to turn off the active layer.
When the layers are grouped, clicking on these buttons will toggle
the visibility of all layers in the same group. This is a good idea because
layers in the same group reside on the same physical layer of
the actual board. Notice that this example has 2 groups each having
3 layers, plus two other layers named @samp{unused}.
Use the @samp{Edit layer groups} option in the @samp{Settings} menu to
change the layer groupings in the lesstif GUI or the @samp{Preferences}
dialog from the @samp{File} menu in the GTK+ GUI. Note that changing the
groupings can radically alter the connectivity on the board.
Grouping layers is only useful for helping you to color-code
signals in your layout. Note that grouping layers actually reduces the number
of different physical layers available for your board, so to make an eight
layer board, you cannot group any layers.

The @emph{far side} button turns on and off the visibility of elements
(including SMD pads) on the opposite (to the side you're viewing)
board side, as well as silk screening on that side. It does not
hide the x-ray view of the other copper layers, these must be turned off
separately if desired.  Use the @emph{tab} key to view the entire board from the other
side.  To see a view of what the back side of the board will actually look like,
make the solder layer the active layer then press @emph{tab} until the status
line says "solder" on the right, then turn off the visibility of all layers
except solder, pins/pads, vias, and silk. Now turn them all back on.

The lowest button, named @emph{active}, is used to change the active
drawing layer. Pressing @emph{<Btn1>} on it pops up a menu to select which
layer should be active.
Each entry is labeled with the layer's name and drawn in its color.
The active layer is automatically made visible. The active layer is
always drawn on top of the other layers, so the ordering of layers
on the screen does not generally reflect the ordering of the manufactured
board. Only the solder, component, silkscreen, and solder-mask layers
are always drawn in their physical order. Bringing the active layer
to the top makes it easier to select and change objects on the active layer.
Try changing the active layer's name to @emph{ABC} by selecting
@samp{edit name of active layer} from the @samp{Edit} menu.
Changing the active layer can also be done by pressing keys
@emph{1..MAX_LAYER}.

Turn off the visibility of the component layer.
Now make the component layer the active layer. Notice that it
automatically became visible. Try setting a few
other layers as the active layer. You should also experiment
with turning on and off each of the layers to see what happens.

The netlist layer is a special layer for adding connections to
the netlist by drawing rat lines. This is not the recommended
way to add to the netlist, but occasionally may be convenient.
To learn how to use the netlist layer see @ref{Net Objects}.


@node Tool Selectors
@subsection The Tool Selectors
@cindex mode selection
@cindex tool selection
@cindex selecting a new tool

The tool selector buttons reside below the layer controls.
They are used to select which layout tool to use in the drawing
area. Each tool performs its function when @emph{Btn1} is pressed.
Every tool gives the cursor a unique shape that identifies it.
The tool selector buttons themselves are icons that illustrate their function.
Each layout tool can also be selected from the keyboard:
@example
    @emph{F1} key       Via tool
    @emph{F2} key       Line tool
    @emph{F3} key       Arc tool
    @emph{F4} key       Text tool
    @emph{F5} key       Rectangle tool
    @emph{F6} key       Polygon tool
    @emph{F7} key       Buffer tool
    @emph{F8} key       Delete tool
    @emph{F9} key       Rotate tool
    @emph{Insert} key   Insert-point tool
    @emph{F10} key      Thermal tool
    @emph{F11} key      Arrow tool
    @emph{F12} key      Lock tool
@end example

Some of the tools are very simple, such as the Via tool.  Clicking
@emph{Btn1} with the Via tool creates a via at the cross hair position.
The via will have the diameter and drill sizes that are active,
as shown in the status line.
The Buffer tool is similar.  With it, @emph{<Btn1>} copies
the contents of the active buffer to the layout, but only
those parts that reside on visible layers are copied.
The Rotate tool allows you to rotate elements, arcs, and text objects
90 degrees counter-clockwise with each click. Holding the @emph{Shift}
key down changes the Rotate tool to clockwise operation.
Anything including groups of objects
can be rotated inside a buffer using the rotate buffer menu option.

The Line tool is explained in detail in @ref{Line Objects}. Go read
that section if you haven't already.
Activate the Line tool. Set the active layer to the solder layer.
Try drawing some lines. Use the @emph{U} key to undo some of the
lines you just created. Zoom in a bit closer with the @emph{Z} key.
Draw some more lines. Be sure to draw some separate lines by starting
a new anchor point with @emph{Ctrl-Btn1}. Change the @samp{crosshair snaps to pin/pads}
behavior in the @b{Settings} menu. Now draw a line. Notice that
the new line points must now always be on a grid point. It might not
be able to reach some pins or pads with this setting. Increase the active line thickness
by pressing the @emph{L} key. Note that the status line updates
to reflect the new active line thickness. Now draw another line. Before completing the
next line, make the component layer active by pressing the @emph{4} key.
Now finish the line. Notice that a via was automatically placed where
you switched layers. @pcb{} does not do any checks to make sure that
the via could safely be placed there. Neither does it interfere with
your desire to place lines haphazardly. It is up to you to place
things properly when doing manual routing with the Line tool.

The Arc tool is explained in detail in @ref{Arc Objects}. Its
use is very similar to the Line tool.

The Rectangle tool, Polygon tool and Thermal tool are explained in detail in
@ref{Polygon Objects}. Go read that section.
Remember that the Thermal tool will only create and destroy thermals
to polygons on the active layer. Use the Rectangle tool to make a
small copper plane on the component layer. Now place a via in the
middle of the plane. Notice that it does not touch the plane, and
they are not electrically connected. Use the Thermal tool to make
the via connect to the plane. Thermals allow the via or pin to
be heated by a soldering iron without having to heat the entire
plane. If solid connections were made to the plane, it could be
nearly impossible to solder. Shift-click on the via with the Thermal
tool to change the style of thermal used or to make the connection
solid.  Click on the via again with the Thermal tool to remove the
connection to the plane.

The Insert-point tool is an editing tool that allows you to add
points into lines and polygons.  The
Insert-point tool enforces the 45 degree line
rule.  You can force only the shorter line segment to 45
degrees by holding the @emph{Shift} key down while inserting the point.
Try adding a point into one of the lines you created. Since line
clipping is turned on, you may need to move the cross hair quite far
from the point where you first clicked on the line. Turn off the
line clipping by selecting @samp{all-direction lines} from the
@b{Settings} menu (or hit
the @emph{Period} key). Now you can place an inserted point anywhere.
Try adding a point to the rectangle you made earlier. Start by clicking
somewhere along an edge of the rectangle, then move the pointer to
a new location and click again.

The delete-mode deletes the object beneath the cursor with each
@emph{Btn1} click.
If you click at an end-point that two lines have in common, it will replace the two lines with a single line
spanning the two remaining points.  This can be used to delete an "inserted"
point in a line, restoring the previous line.  Now delete one of the original corner
points of the polygon you were just playing with. To do this, place the cross hair over the
corner and click on it with the Delete tool. You could also use the @emph{Backspace} key
if some other tool is active. Try deleting some of
the lines and intermediate points that you created earlier. Use undo
repeatedly to undo all the changes that you've made. Use redo
a few times to see what happens. Now add a new line. Notice that
you can no longer use redo since the layout has changed since
the last undo happened. The undo/redo tree is always pruned in this
way (@emph{i.e.} it has a root, but no branches).

The Arrow tool is so important, it has its own section: @ref{Arrow Tool}.
Go read it now.

The Lock tool allows you to lock objects on the layout. When an object
is locked, it can't be selected, moved, rotated, or resized. This is
useful for very large objects like ground planes, or board-outlines that
are defined as an element. With such large objects, nearly anywhere you
click with the Arrow tool will be on the large object, so it could be
hard to draw box selections. If you lock an object, the Arrow tool will
behave as if it didn't exist.  You cannot unlock an object with undo.
You must click on it again with the Lock tool. If an object is locked,
previous changes to it cannot be undone either. When you lock
an object, a report message about it is popped up and will always tell
you what object it is, and that it is locked if you just locked it.
Other than noticing your inability to manipulate something, the only
way to tell an object is locked is with a report from the @b{Info}
menu. Use the Lock tool sparingly.


@node Layout Area
@subsection Layout Area
@cindex grid

The layout area is where you see the layout. The cursor shape depends
on the active tool when the pointer is moved into the layout area.
A cross hair follows the mouse pointer with respect to the grid setting.
Select a new grid from the @emph{Screen} menu.
The new value is updated in the status line.
A different way to change the grid is
@emph{Shift<Key>g} to decrease or @emph{<Key>g} to increase
it, but this only works for English (integer mil) grids.
The grid setting is saved along with the data when you save a pcb layout.
For homemade layouts a value around 50 is a good setting.
The cursor can also be moved in the layout area with the cursor (arrow) keys or, for larger
distances, by pressing the @emph{Shift} modifier together with a cursor key.


@node Log Window
@section Log Window
@cindex log window
@cindex messages

This optional window is used to display all kind of messages including
the ones written to @emph{stderr} by external commands. The main advantage
of using it is
that its contents are saved in a scrolling list until the
program exits. Disabling this feature by setting the resource
@emph{useLogWindow} to @emph{false} will generate popup windows to display
messages. The @emph{stderr} of external commands will appear on @pcb{}s
@emph{stderr} which normally is the parent shell. I suggest you iconify
the log window after startup for example by setting @emph{*log.iconic} to
@emph{true} in the resource file. If @emph{raiseLogWindow} is set @emph{true},
the window will deiconify and raise itself whenever new messages are to be
displayed.


@node Library Window
@section Library Window
@cindex library window

The library window makes loading elements (or even partial layouts) easy.
Just click the appropriate library from the list on the left. A list
of its elements then appears on the right. Select an element
from the list by clicking on its description. Selecting an element from the
library will also automatically copy the element into
the active buffer, then invoke the @emph{Buffer} tool so
you can paste it to the layout. Elements in the old library should be
taken with a grain of salt (@emph{i.e.} check them carefully before
using).  The old library names all begin with ~ so you can easily distinguish between
the old and new libraries.  All of the elements in the new library
should  be thoroughly vetted, so you
can use them with confidence. The new libraries are stored simply
as directories full of element files, so making additions to the
new library is easy since there is no need to learn @code{m4}.
For details on the old libraries,
check-out @ref{Library File} and @ref{Library Contents File}. For
details on the format of an element file used for the new libraries,
see @ref{Element File}.


@node Netlist Window
@section Netlist Window
@cindex Netlist Window

The netlist window is very similar to the library window. On the left
is a list of all of the nets, on the right is the list of connections
belonging to the chosen net. The chosen net is highlighted in the
list and also shown on the second line of the window in red. If the
net name has a star to the left of it then it is "disabled". A disabled
net is treated as if it were not in the net list. This is useful, for
example, if you plan to use a ground plane and don't want the ground
net showing up in the rat's nest. You can enable/disable individual
nets by double-clicking the net name. If you want to enable or disable
all nets at once, there are two buttons at the top of the netlist
window for this purpose.

The button labeled @samp{Sel Net On Layout}
can be used to select (on the layout) everything that is connected
(or is supposed to be connected) to the net. If you click on a
connection in the connection list, it will select/deselect
the corresponding pin or pad in the layout and also center the layout
window where it is located. If you "Find" (@samp{lookup connection
to object} in the @b{Connects} menu [also @emph{F} key]), a pin
or pad it will also choose the net and connection in the netlist window
if it exists in the netlist.

If no netlist exists for the layout, then the netlist window does not
appear. You can load a netlist from a file from the @b{File} menu. The
format for netlist files is described in @ref{Netlist File}.


@node Drawing and Removing
@section Drawing and Removing Basic Objects
@cindex drawing objects
@cindex removing objects
@cindex erasing objects
@cindex object, drawing and removing

hace begging gutting here, and do a real-world tutorial example.

There are several ways of creating new objects: you can draw them yourself,
you can copy an existing object (or selection), or you can load an element from a file or
from the Library window. Each type of object has a particular tool for creating it.

The active tool can be selected from the tool selectors in the bottom
left corner or by one of the function keys listed earlier in this chapter.
Each @emph{<Btn1>} press with the tool tells the application to create
or change the appropriate object or at least take
the first step to do so. Each tools causes the cursor to take
on a unique shape and also causes the corresponding
tool selector button to be highlighted. You can use either cue
to see which tool is active.

Insert mode provides the capability of inserting new points into existing
polygons or lines. The 45 degree line clipping is now enforced when selected.
Press and hold the shift key while positioning the new point to only clip
the line segment to the nearer of the two existing points to 45 degrees.
You can also toggle the 45-degree clipping in the middle of a point
insertion by pressing the @emph{<Key>.}
If the shift key is not depressed and the 45 degree line clipping mode
is on, both new line segments must be on 45 degree angles - greatly
restricting where the new point may be placed. In some cases this can cause
confusion as to whether an insertion has been started since the two new
lines may be forced to lie parallel on top of the original line until the
pointer is moved far from the end points.

Removing objects, changing their size or moving them only applies to objects
that are visible when the command is executed.

@menu
* Common::           Keystrokes common to some objects.
* Lines::
* Arcs::
* Polygons::         Drawing polygons and rectangles.
* Text::
* Vias::
* Elements::
* Pastebuffer::      A multi-purpose buffer.
@end menu

@node Common
@subsection Common Drawing and Removing Methods
@cindex creating objects
@cindex object, creating an
@cindex removing objects
@cindex object, removing an
@cindex thickness of objects
@cindex object, changing the size of an

There are several keystrokes and button events referring to an @emph{object}
without identifying its type. Here's a list of them:

@emph{<Btn1>} creates (or deletes)  an object depending on the
current mode.

@emph{<Key>BackSpace} or @emph{<Key>Delete} removes the visible
object at the cursor location. When more than one object exists at the
location, the order of removal is: via, line, text, polygon and
element. The drawn layer order also affects the search - whatever is
top - most (except elements) is affected before lower items.  Basically
all this means that what is removed is probably just what you expect.
If for some reason it isn't, undo and try again.
Only one object is removed for each keystroke. If two or more
of the same type match, the newest one is removed.

Use @emph{<Key>s} and @emph{Shift<Key>s} to change the size (width)
of lines, arcs, text objects, pins, pads and vias, or to toggle the style
of polygons (whether pins and vias automatically have clearances).

@emph{<Key>n} changes the name of pins, pads, vias, the
string of a text object, or the currently displayed label of an element.

@emph{<Key>m} moves the line, arc, or polygon under the cross hair to the
active layer if it wasn't on that layer already.

@emph{<Key>u} (undo) recovers from an unlimited number of operations
such as creating, removing, moving, copying, selecting etc. It works like
you'd expect even if you're in the midst of creating something.

@emph{Shift<Key>r} restores the last undone operation provided no other
changes have been made since the undo was performed.

@emph{<Key>tab} changes the board side you are viewing.

For a complete list of keystrokes and button events see @ref{Translations}.


@node Lines
@subsection Lines
@cindex lines, an example
@cindex example of line handling

To draw new lines you have to be in @emph{line-mode}. Get there either by
selecting it from the @emph{Tool palette} or by pressing @emph{<Key>F2}.
Each successive @emph{notify} event creates a new line. The
adjustment to 45 degree lines is done automatically if it is selected from the
@emph{Display} menu. You can toggle the 45 degree mode setting by
pressing the @emph{<Key>.} (That is the period key). When 45 degree enforcement
is turned on there are three distinct modes of line creation: a single
line on the closest 45 degree vector towards the cross hair (but not necessarily
actually ending at the cross hair), two lines created such that the first leaves
the start point on a 90 degree vector and the second arrives at the cross hair
on a 45 degree vector, and finally two lines created such that the first leaves
the start point on a 45 degree vector and the second arrives at the cross hair
on a 90 degree vector.  These last two modes always connect all the way from
the start and end points, and all lines have angles in 45 degree multiples.
The @emph{<Key>/} cycles through the three modes.  The status line shows a
text icon to indicate which of the modes is active and the lines following
the cross hair motion show the outline of the line(s) that will actually be created.
Press @emph{<Key>Escape} to leave line-mode.

@emph{<Key>l}, @emph{Shift<Key>l} and the entries in the
@emph{Sizes} menu change the initial width of new lines.  This width is also
displayed in the status line.


@node Arcs
@subsection Arcs
@cindex arc, an example

An Arc is drawn  with the @emph{arc-tool}. Get there either by selecting it
from the @emph{Tool palette} or by pressing @emph{<Key>F8}. Press @emph{Btn1} to
define the starting point for the arc.  Drag the mouse towards the desired
end point along the path you want the arc to follow.  The outline of the arc that
will be created is shown on the screen as you move the mouse.  Arcs are always
forced to be 90 degrees and have symmetrical length and width ( i.e. they are
a quarter circle).  The next @emph{Btn1} click creates the arc.  It will have
the same width as new lines (displayed in the status line) and appear on the
active layer. The arc leaves the starting point towards the cross hair along
the axis whose distance from the cross hair is largest.  Normally this means that
if you drag along the path you want the arc to follow, you'll get what you
want.  If the grid is set to the arc radius, then the two distances will be
equal and you won't be able to get all of the possible directions.  If this
is thwarting your desires, reduce the grid spacing (@emph{!Shift<Key>G}) and
try again.


@node Polygons
@subsection Polygons and Rectangles
@cindex polygon, an example
@cindex example of polygon handling
@cindex rectangle, an example
@cindex example of rectangle handling

A polygon is drawn by defining all of its segments as a series of
consecutive line segments. If the first point matches a new one and if
the number of points is greater than two, then the polygon is closed.
Since matching up with the first point may be difficult, you may use
@emph{Shift<Key>p} to close the polygon. The @emph{Shift<Key>p} won't
work if clipping to 45 degree lines is selected
and the final segment cannot match this condition.
I suggest you create simple convex polygons in order to avoid a strong
negative impact on the performance of the connection scanning routines.
The @emph{rectangle-mode} is just an easy way to generate rectangular polygons.
@emph{Polygon-mode} also is selected by @emph{<Key>F6} whereas
@emph{rectangle-mode} uses @emph{<Key>F4}.
Pressing a @emph{<Btn1>} at two locations creates a rectangle by
defining two of its corners.
@emph{<Key>Insert} brings you to @emph{insert-point-mode} which lets you
add additional points to an already existing polygon.
Single points may be removed by moving the cross hair to them and selecting
one of the delete actions @emph{(remove-mode, BackSpace, or Delete}. This only works
if the remaining polygon will still have three or more corners.
Pressing @emph{<Key>u}  or @emph{<Key>p} while entering a new polygon
brings you back to the previous corner. Removing a point does not
force clipping to 45 degree angles (because it's not generally possible).
Newly created polygons will not connect to pins or vias
that pierce it unless you create a thermal (using the thermal mode) to make
the connection. If the edge of a polygon gets too close to a pin or via that
lies outside of it, a warning will be issued and the pin will be given a
special color. Increasing the distance between them will remove the warning
color.


@node Text
@subsection Text
@cindex text, an example
@cindex strings, an example
@cindex example of text handling

Pressing @emph{<Key>F5} or clicking one of the text selector buttons
changes to @emph{text-mode}.
Each successive notify event (@emph{<Btn1>})
pops up the input line at the bottom and queries for a string.
Enter it and press @emph{<Key>Return} to confirm or
@emph{<Key>Escape} to abort.
The text object is created with its upper left corner at the current pointer
location.
The initial scaling is changed by @emph{<Key>t} and
@emph{Shift<Key>t} or from the @emph{Sizes} menu.

Now switch to @emph{rotate-mode} and press
@emph{<Btn1>} at the text-objects location. Text objects
on the solder side of the layout are automatically mirrored and
flipped so that they are seen correctly when viewing the solder-side.

Use @emph{<Key>n} to edit the string.

@b{TEXT OBJECTS ON COPPER LAYERS CREATE COPPER LINES BUT THEY ARE NOT SCANNED FOR
CONNECTIONS}. If they are moved to the silkscreen layer, they
no longer create copper.


@node Vias
@subsection Vias
@cindex vias, an example
@cindex example of via handling

The initial size of new vias may be changed by @emph{<Key>v} and
@emph{Shift<Key>v} or by selecting the appropriate entry from the
@emph{Sizes} menu. @emph{Mod1<Key>v} and @emph{Mod1 Shift<Key>v} do
the same for the drilling hole of the via.
The statusline is updated with the new values.
Creating a via is similar to the other objects. Switch to @emph{via-mode}
by using either the selector button or @emph{<Key>F1} then press
@emph{<Key>]} or @emph{<Btn1>} to create one.
@emph{<Key>n} changes the name of a via. If you want to create a mounting
hole for your board, then you can place a via where you want the hole to
be then convert the via into a hole.  The conversion is done by pressing
@emph{!Ctrl<Key>h} with the cross hair over the via.  Conceptually it is
still a via, but it has no copper annulus.  If you create such a hole in
the middle of two polygons on different layers, it will short the layers.
Theoretically you could arrange for such a hole not to be plated, but a
metal screw inserted in the hole would still risk shorting the layers.
A good rule is to realize that holes in the board really are vias between
the layers and so place them where they won't interfere with connectivity.
You can convert a hole back into a normal via with the same keystroke used
to convert it in the first place.

@node Elements
@subsection Elements
@cindex element, an example
@cindex example of element handling

Some of the functions related to elements only work if both the package
layer and the pin layer are switched on.

Now that you're familiar with many of the basic commands, it is
time to put the first element on the layout.
First of all, you have to load data into the paste buffer.
There are four ways to do this:
@example
   1) load the data from a library
   2) load the data from a file
   3) copy data from an already existing element
   4) convert objects in the buffer into an element
@end example
We don't have any elements on the screen yet nor anything in the
buffer, so we use number one.

@cindex example files
@cindex m4, preprocessing example files
Select @emph{lsi} from the menu in the library window press
@emph{<Btn1>} twice at the appropriate text-line to get
the MC68030 CPU.
The data is loaded and the mode is switched to @emph{pastebuffer-mode}.
Each notify event now creates one of these beasts. Leave the mode
by selecting a different one or by @emph{<Key>Escape} which resets
all modes..
The cross hair is located at the @emph{mark} position as defined by
the data file. Rotating the buffer contents is done by selecting
the @emph{rotate} entry of the @emph{Buffer} menu or by pressing
@emph{Shift<Key>F3}. The contents of the buffer
are valid until new data is loaded into it either by a cut-to-buffer
operation, copy-to-buffer operation or by loading a new data file.
There are 5 buffers
available  (possibly more or less if changed at compile time
with the @code{MAX_BUFFER} variable in @file{globalconfig.h}).
Switching between them is done by selecting a menu entry or
by @emph{Shift<Key>1..MAX_BUFFER}.
Each of the two board sides has its own buffers.

The release includes all data files for the circuits that are used
by the demo layout. The elements in the LED example are not found in the library,
but you can lift them from the example itself if you want.
If you have problems with the color of the cross hair, change the resource
@emph{cross hairColor} setting to a different one.

@cindex example of loading an element file
@cindex pins, an example
@cindex example of pin handling
Now load a second circuit, the MC68882 FPU for example.
Create the circuit as explained above. You now have two different unnamed
elements. Unnamed means that the layout-name of the element
hasn't been set yet. Selecting @emph{description} from the @emph{Display}
menu displays the description string of the two circuits which
are CPU and FPU. The values of the circuits are set to MC68030 and MC68882.
Each of the names of an element may be changed
by @emph{<Key>n} at the elements location and editing the old name in
the bottom input line. Naming pins and vias is similar to elements.
You can hide the element name so that it won't appear on the board
silkscreen by pressing @emph{<key>h} with the cursor over the element.
Doing so again un-hides the element name.

Entering @kbd{:le} and selecting an element data file is
the second way to load circuits.

The third way to create a new element is to copy an existing one.
Please refer to @ref{Moving and Copying}.

@cindex example of creating an element
@cindex element, creating a new package
@cindex pastebuffer, convert contents to element
@cindex buffer, convert contents to element
The fourth way to create a new element is to convert a buffer's contents
into an element.  Here's how it's done: Select the Via-tool from the
@emph{Tool pallet}.  Set the grid spacing to something appropriate for
the element pin spacing.  Now create a series of vias where the pins
go.  Create them in pin number order. It is often handy to place a reference
point (@emph{!Ctrl<Key>m}) in the center of the first pin in order to measure
the location of the other pins.  Next make a solder-side layer the active
layer from the @emph{active-layer} popup menu.  Now draw the outline of
the element using lines and arcs.  When you're done, select everything that
makes up the element with a box selection (@emph{<Btn3Down> drag,
<Btn3Up>}). Now select "cut selection to buffer" from the @emph{Buffer}
menu. Position the cursor over the center of pin 1 and press the left
button to load the data into the buffer.
Finally select "convert buffer to element" from the @emph{Buffer} menu.
You'll only want to create elements this way if they aren't already in the
library.  It's also probably a good idea to do this before starting any of
the other aspects of a layout, but it isn't necessary.

To display the pinout of a circuit move to it and press @emph{Shift<Key>d}
or select @emph{show pinout} from the @emph{Objects} menu. A new window
pops up and displays the complete pinout of the element. This display can
be difficult to read if the component has been rotated 90 degrees :-(
therefore, the new window will show an un-rotated view so the pin names
are readable.
@emph{<Key>d} displays the name of one or all pins/pads inside the
Layout area, this is only for display on-screen, it has no effect on any
printing of the layout.

You also may want to change a pin's or pad's current size by pressing
@emph{<Key>s} to increase or @emph{Shift<Key>s} to decrease it. While
this is possible, it is not recommended since care was probably taken
to define the element structure in the first place. You can also change the thickness
of the element's silkscreen outline with the same keys. You can
change whether a pin or SMD pad is rounded or square with the @emph{<Key>q}.
SMD pads should usually have squared ends. Finally, you can change whether
the non-square pins are round or octagonal with the @emph{!Ctrl<Key>o}.

SMD elements and silkscreen objects are drawn in the "invisible object"
color if they are located on the opposite side of the board.

For information on element connections refer to @ref{Connection Lists}.


@node Pastebuffer
@subsection Pastebuffer
@cindex pastebuffer, an example
@cindex example of pastebuffer handling
@cindex buffer, an example
@cindex example of buffer handling

The line-stack and element-buffer of former releases have been replaced
by 5 (possibly more or less if changed at compile time
with the @code{MAX_BUFFER} variable in @file{globalconfig.h})
multi-purpose buffers that are selected by
@emph{Shift<Key>1..MAX_BUFFER}. The status line shows which buffer is
the active one.
You may load data from a file or layout into them.
Cut-and-paste works too.
If you followed the instructions earlier in this chapter you should
now have several objects on the screen. Move the cross hair to one of them
and press @emph{<Btn3Down>} to toggle its selection flag. (If you drag the
mouse while the button is down, a box selection will be attempted instead
of toggling the selection.)  The object
is redrawn in a different color. You also may want to try
moving the pointer while holding the third button down and
release it on a different location. This selects all objects inside the
rectangle and unselects everything else.  If you want to add a box selection
to an existing selection, drag with @emph{Mod1<Btn3Down>} instead.
Dragging @emph{Shift Mod1<Btn3Down>} unselects objects in a box.
Now change to @emph{pastebuffer-mode} and select some operations from the
@emph{Buffer} menu. Copying objects to the buffer is available as
@emph{Mod1<Key>c} while cutting them uses @emph{Mod1<Key>x} as
shortcut. Both clear the buffer before new data is added.
If you use the menu entries, you have to supply a cross hair position by
pressing a mouse button. The objects are attached to the pastebuffer
relative to that cross hair location.
Element data or PCB data may be merged into an existing layout by loading
the datafiles into the pastebuffer. Both operations are available from
the @emph{File} menu or as user commands.

@node Moving and Copying
@section Moving and Copying
@cindex moving, an example
@cindex copying, an example
@cindex example of moving
@cindex example of copying

All objects can be moved including element-names, by
@emph{<Btn2Down>}, dragging the pointer while holding the button down
and releasing it at the new location of the object. If you use
@emph{Mod1<Btn2Down>} instead, the object is copied. Copying does not work for
element-names of course. You can move all selected objects with
@emph{Shift <Btn1>}.  This uses the Pastebuffer, so
it will remove whatever was previously in the Pastebuffer.
Please refer to @ref{Pastebuffer}.
If you want to give a small nudge to an object, but you don't think
that the mouse will give you the fine level of control that you want,
you can position the cursor over the object, press @emph{<Key>[},
move it with the arrow keys, then press @emph{<Key>]} when it's at the
desired position.  Remember that all movements are forced onto grid coordinates, so
you may want to change the grid spacing first.

@cindex moving, traces to a different layer
@cindex changing layers
To move a trace or group of traces to a different layer, first select
the tracks to be moved.  It's easiest to do this if you shut off everything
but that layer first (i.e. silk, pins, other layers, etc).
Now set the current layer to be the new layer.  
Press Shift-M to move all the selected tracks to the current layer.
See the @emph{MoveToCurrentLayer} action for more details.

@node Loading and Saving
@section Loading and Saving
@cindex loading, an example
@cindex saving, an example
@cindex example of saving
@cindex example of loading

After your first experience with @pcb{} you will probably want to save
your work. @kbd{:s name} passes the data to an external program which
is responsible for saving it. For details see @emph{saveCommand} in
@ref{Resources}.
Saving also is available from the @emph{File} menu, either with or
without supplying a filename. @pcb{} reuses the last
filename if you do not pass a new one to the save routine.

To load an existing layout either select @emph{load layout data} from the
@emph{File} menu or use @kbd{:l filename}. A file select box pops up if you
don't specify a filename. Merging existing layouts into the new one is
supported either by the @emph{File} menu or by @kbd{:m filename}.

@cindex backup
@cindex saving layouts
@cindex preventing loss of data
@cindex /tmp
@cindex directory /tmp
@cindex temporary files
@pcb{} saves a backup of the current layout at a user specified interval.
The backup filename is created by appending a dash, "-", to the @file{.pcb} filename.
For example, if you are editing the layout in @file{projects/board.pcb} then the
backup file name will be @file{projects/board.pcb-}.  If the layout is new and
has not been saved yet, then the backup file name is @file{PCB.####.backup} where the "####"
will be replaced by the process ID of the currenting running copy of @pcb{}.
This default backup file name may be changed at compilation time via the
@code{BACKUP_NAME}
variable in @file{globalconfig.h}).  During critical
sections of the program or when data would be lost it is saved as
@file{PCB.%i.save}.  This file name may be changed at compile time
with the @code{SAVE_NAME} variable in @file{globalconfig.h}.


@node Printing
@section Printing
@cindex printing, an example
@cindex example of printing

@pcb{} now has support for device drivers,
@code{PostScript}, @emph{encapsulated PostScript},
and @emph{Gerber RS-274X} drivers are
available so far.  The @emph{Gerber RS-274X}
driver additionally generates a numerical control (NC) drill file for
automated drilling,
a bill of materials file to assist in materials procurement and
inventory control, and a centroid (X-Y) file which includes the
centroid data needed
by automatic assembly (pick and place) machines.
 I recommend the use of @code{GhostScript} if you
don't have a @code{PostScript} printer for handling the PostScript
output. Printing always generates
a complete set of files for a specified driver.
See the page about
the @emph{Print()} action for additional information about the filenames.
The control panel offers a number of options. Most of them are not available
for Gerber output because it wouldn't make sense, for example,  to scale the gerber output
(you'd get an incorrectly made board!)  The options are:

@table @samp
@cindex device, selecting an output
@cindex output device
@item device
The top menu button selects from the available device drivers.

@cindex rotating printout
@item rotate
Rotate layout 90 degrees counter-clockwise before printing (default).

@cindex mirroring printout
@item mirror
Mirror layout before printing. Use this option depending
on your production line.

@cindex color printout
@item color
Created colored output. All colors will be converted to black if this option
is inactive.

@cindex outline printout
@item outline
Add a board outline to the output file. The size is determined by the
maximum board size changeable from the @emph{sizes} menu. The outline appears
on the top and bottom sides of the board, but not on the internal layers.
An outline can be useful for determining where to shear the board from the
panel, but be aware that it creates a copper line.  Thus it has the potential
to cause short circuits if you don't leave enough room from your wiring
to the board edge.  Use a viewer to see what the output outline looks like
if you want to know what it looks like.

@cindex alignment targets
@item alignment
Additional alignment targets are added to the output. The distances between
the board outline is set by the resource @emph{alignmentDistance}.  Alignment
targets should only be used if you know for certain that YOU WILL BE USING
THEM YOURSELF.  It is extremely unlikely that you will want to have alignment
targets if you send gerber files to a commercial pcb manufacture to be made.

@cindex scaling a printout
@item scaling
It's quite useful to enlarge your printout for checking the layout.
Use the scrollbar to adjust the scaling factor to your needs.

@cindex print media
@cindex media, size of
@item media
Select the size of the output media from this menu. The user defined size
may be set by the resource @emph{media} either from one of the well known
paper sizes or by a @code{X11} geometry specification.
This entry is only available if you use @code{X11R5} or later.
For earlier releases the user defined size or, if not available, @emph{A4}
is used.
Well known size are:
@display
        A3
        A4
        A5
        letter
        tabloid
        ledger
        legal
        executive
@end display

@cindex offset of printout
@cindex print offset
@item offset
Adjust the offsets of the printout by using the panner at the right side
of the dialog box.
This entry is only available if you use @code{X11R5} or later. A zero
offset is used for earlier releases.

@cindex DOS filenames
@item 8.3 filenames
Select this button to generate DOS compatible filenames for the output files.
The @emph{command} input area will disappear if selected.

@cindex print command
@item commandline
Use this line to enter a command (starts with @kbd{|}) or a filename.
A %f is replaced by the current filename.
The default is set by the resource @emph{printCommand}.

@end table

The created file includes some labels which are guaranteed to stay unchanged
@table @samp
@item PCBMIN
identifies the lowest x and y coordinates in mil.

@item PCBMAX
identifies the highest x and y coordinates in mil.

@item PCBOFFSET
is set to the x and y offset in mil.

@item PCBSCALE
is a floating point value which identifies the scaling factor.

@item PCBSTARTDATA
@itemx PCBENDDATA
all layout data is included between these two marks. You may use them with an
@code{awk} script to produce several printouts on one piece of paper by
duplicating the code and putting some @code{translate} commands in front.
Note, the normal @code{PostScript} units are 1/72 inch.
@end table

@node Exporting
@section Exporting a layout
@cindex Exporting a layout
@vindex Exporting a layout

To export a layout choose @emph{Export layout} from the @emph{File} menu, then
select the desired exporter.

@menu
* bom::                Bill of materials.
* gcode::              G-code.
* gerber::             Gerber.
* nelma::              Nelma.
* png::                Image.
* ps::                 Postscript.
* eps::                Eps.
@end menu

@node bom
@subsection Bill of materials (bom)
@cindex bom
@cindex bill of materials

Produces a bill of materials (BOM) file and a centroid (XY) file.

@node gcode
@subsection G-code (gcode)
@cindex gcode
@cindex g-code
@cindex cnc

The gcode exporter can generate RS274/NGC G-CODE files to be used with a CNC mill to
produce pcb's by mechanically removing copper from the perimeter of all elements.

The elements are enlarged in order to compensate for the cutting tool size so
that the remaining copper corresponds to the original size; however all
polygons are left unchanged and will end up being a little smaller; this is not a
problem because the electrical connection is done with traces, which are correctly
enlarged.

A .cnc file is generated for every copper layer, with the bottom layer mirrored so
that the milling is done right; of course it's not possible to produce directly
multi-layer (more than 2) pcb's with this method, but the cnc files for
intermediate layers are generated anyways.

A drill file is also generated, and it contains all drills regardless of the hole
size; the drilling sequence is optimized in order to require the least amount of
movement.

The export function generates an intermediate raster image before extracting the contour
of copper elements, and this image is saved as well (in .png format) for inspection.

When the spacing between two elements is less than the tool diameter they will merge
and no isolation will be cut between them; the control image should be checked for
this behaviour.

Possible workarounds are: increasing spacing, decreasing the tool size, increasing
the intermediate image resolution.

To maximize the chance of producing correct pcb's it would be better to increase
the DRC clearance to at least the tool diameter and use traces as thick as possible;
the rule is: use the largest element that will not prevent the isolation cut.

The exporter parameters are:

@table @b
@item basename
base name for generated files

@item dpi
intermediate image resolution; affects precision when extracting contours

@item mill depth
should be the copper depth

@item safe z
Z value when moving between polygons

@item tool radius
copper elements are enlarged by this amount

@item drill depth
depth of drills

@item measurement unit
for all parameters above, can be mm,um,inch,mil; g-code is always mm or inch
@end table

All .cnc files specify Z values as parameters, so that it's easy to
change them without the need to run the exporter again.

Operation was verified with the EMC2 g-code interpreter.

Following is a sample layout that is converted with default settings:
@center @image{gcode,,,Sample Layout,png}

The control image shows that the spacing is sufficient:
@center @image{gcode_control_img,,,Control Image,png}

The final tool path follows the perimeter of all elements:
@center @image{gcode_tool_path,,,Resulting Tool Path,png}

@node gerber
@subsection Gerber (gerber)
@cindex gerber

Produces RS274-X (a.k.a. gerber) photo plot files and Excellon drill files.

@node nelma
@subsection Nelma (nelma)
@cindex nelma

Numerical analysis package export.

@node png
@subsection Image (png)
@cindex png
@cindex image export

Produces GIF/JPEG/PNG image files.

@node ps
@subsection Postscript (ps)
@cindex ps
@cindex postscript

Export as postscript.
Can be later converted to pdf.

@node eps
@subsection Encapsulated Postscript (eps)
@cindex eps
@cindex encapsulated postscript

Export as eps (encapsulated postscript) for inclusion in other documents.
Can be later converted to pdf.


@node Connection Lists
@section Connection Lists
@cindex example of connection lists
@cindex connections, creating list of

After completing parts of your layout you may want to check if all drawn
connections match the ones you have in mind. This is probably best done
in conjunction with a net-list file: see @ref{Rats Nest}.
The following examples give more rudimentary ways to examine
the connections.
@example
    1) create at least two elements and name them
    2) create some connections between their pins
    3) optionally add some vias and connections to them
@end example

Now select @emph{lookup connection} from the @emph{Connections} menu,
move the cursor to a pin or via and press any mouse button. @pcb{}
will look for all other pins and/or vias connected to the one you have
selected and display the objects in a different color.
Now try some of the reset options available from the same menu.

There also is a way to scan all connections of one element. Select
@emph{a single element} from the menu and press any button at the
element's location. All connections of this element will be saved
to the specified file.
Either the layout name of the element or its canonical name is used to
identify pins depending on the one which is displayed on the screen
(may be changed by @emph{Display} menu).

An automatic scan of all elements is initiated by choosing
@emph{all elements}. It behaves in a similar fashion to scanning a single
element except the resource @emph{resetAfterElement}
is used to determine if connections should be reset before a new element is
scanned. Doing so will produce very long lists because the power lines are
rescanned for every element. By default the resource is set to @emph{false}
for this reason.

To scan for unconnected pins select @emph{unused pins} from the same
menu.


@node Arrow Tool
@section Arrow Tool
@cindex selecting, using the arrow tool
@cindex moving objects
@cindex arrow tool
@cindex tool, arrow

Some commands mentioned earlier in this chapter also are able to operate on all
selected and visible objects. The Arrow tool is used to select/deselect
objects and also to move objects or selections.  If you click and release
on an object with the Arrow tool, it will unselect everything else and
select the object. Selected objects change color to reflect that
they are selected. If you @emph{Shift} click, it will add the object to
(or remove) the object from the existing selection. If you drag with
the mouse button down with the Arrow tool, one of several things could
happen: if you first pressed the button on a selected object, you
will be moving the selection to where you release the button. If you
first pressed the button on an unselected object, you will be moving
that object. If you first pressed the button over empty space, you
will be drawing a box to select everything inside the box. The @emph{Shift}
key works the same way with box selections as it does with single objects.

Moving a single un-selected object is different from moving a selection.
First of all, you can move the end of line, or a point in a polygon this
way which is impossible by moving selections. Secondly, if rubber banding
is turned on, moving a single object will rubber-band the attached lines.
Finally, it is faster to move a single object this way since there is no need
to select it first.

You can select any visible object unless it is locked. If you select an
object, then turn off its visibility with the Layer controls, it won't
be moved if you move the remaining visible selection.

If you have not configured to use strokes in the @pcb{} user interface, then
the middle mouse button is automatically bound to the arrow tool, regardless
of the active tool (which is bound to the first mouse button). So using
the middle button any time is just like using the first mouse button
with the Arrow tool active.

The entries of the @emph{Selection} menu are hopefully self-explanatory.
Many of the @emph{Action Commands} can take various key words that make
them function on all or some of the selected items.

@node Rats Nest
@section Rats Nest
@cindex rats nest
@cindex netlist
@cindex rat-line

If you have a netlist that corresponds to the layout you are working on, you
can use the rats-nest feature to add rat-lines to the layout.
First you will need to load a netlist file (see @emph{:rn},
@ref{User Commands}).
@emph{<Key>w} adds rat-lines on the active layer using the current
line thickness shown in the status line (usually you'll want them to be thin lines).
Only those rat-lines that fill in missing connectivity (since you have
probably routed some connections already) are added.
If the layout is already completely wired, nothing will be added, and you will
get a message that the wiring is complete.

Rat-lines are lines having the special property that they only connect to pins and
pads at their end points.  Rat-lines may be drawn differently to other lines
to make them easier to identify since they have special behavior and cannot
remain in a completed layout.
Rat-lines are added in the minimum length straight-line tree pattern
(always ending on pins or pads) that satisfies the missing connectivity in the circuit.
Used in connection with moves and rotates of the elements, they are extremely useful for
deciding where to place elements on the board. The rat-lines will always automatically
rubberband to the elements whether or not the rubberband mode is on. The only way for
you to move them is by moving the parts they connect to.
This is because it is never desirable to have the rat-lines disconnected from
their element pins.  Rat-lines will normally criss-cross
all over which gives rise to the name "rats nest" describing a layout connected with
them.  If a SMD pad is unreachable on the active layer, a warning will be issued
about it and the rat-line to that pad will not be generated.

A common way to use rats nests is to place some
elements on the board, add the rat-lines, and then use a series of moves/rotates of the
elements until the rats nest appears to have minimum tangling.  You may want to iterate this step
several times. Don't worry if the layout looks messy - as long as you can get a sense for whether
the criss-crossing is better or worse as you move things, you're fine.
After moving some elements around, you may want to optimize the rats nest @emph{<Key>o}
so that the lines are drawn between the closest points (this can change once you've moved components).
Adding rat-lines only to selected pads/pins (@emph{Shift<Key>w})
is often useful to layout a circuit a little bit at a time.
Sometimes you'll want to delete all the rat-lines (@emph{<Key>e}) or
selected rat-lines (@emph{Shift<Key>e}) in order to reduce confusion.
With a little practice you'll be able to achieve a near optimal component placement with
the use of a rats nest.

Rat-lines are not only used for assisting your element placement, they can also help
you to route traces on the board.
Use the @emph{<Key>m} to convert a rat-line under the cursor into
a normal line on the active layer.
Inserting a point into a rat-line will also cause the two new lines to be normal lines
on the board.
Another way that you can use rat-lines is to
use the @emph{<Key>f} with the cursor over a pad or pin.  All of the pins and
pads and rat-lines belonging to that net will be highlighted. This is a helpful way to
distinguish one net from the rest of the rats nest.  You can then route those tracks,
turn off the highlighting (@emph{Shift<Key>f}) and repeat the process. This will work even
if the layer that the rat-lines reside on is made invisible - so only the pins and pads
are highlighted.
Be sure to erase the rat-lines (@emph{<Key>e} erases them all) once you've
duplicated their connectivity by adding your own lines.
When in doubt, the @emph{<Key>o} will delete only those
rat-lines that are no longer needed.

If connections exist on the board that are not listed in the netlist when
@emph{<Key>w} is pressed, warning messages are issued and the affected pins and
pads are drawn in a special @emph{warnColor} until the next @emph{Notify()} event.
If the entire layout agrees completely with the netlist, a message informs you that
the layout is complete and no rat-lines will be added (since none are needed).
If the layout is complete, but still has rat-lines then you will be warned
that rat-lines remain. If you get no message at all it's probably because some
elements listed in the net list can't be found and where reported in an earlier
message.
There shouldn't be any rat-lines left in a completed layout, only normal lines.

The @emph{Shift<Key>w} is used to add rat-lines to only those missing connections among
the selected pins and pads.  This can be used to add rat-lines in an incremental
manner, or to force a rat-line to route between two points that are not the
closest points within the net. Often it is best to add the rats nest in an incremental fashion, laying
out a sub-section of the board before going further. This is easy to accomplish since
new rat-lines are never added where routed connectivity already makes the necessary
connections.

@node Design Rule Checking
@section Design Rule Checking
@cindex design rule checking
@cindex drc
@cindex spacing, minimum
@cindex overlap, minimum

After you've finished laying out a board, you may want to check
to be certain that none of your interconnections are too closely
spaced or too tenuously touching to be reliably fabricated. The design
rule checking (DRC) function does this for you. Use the command ":DRC()" (without
the quotes of course) to invoke the checker.  If there are no problem areas,
you'll get a message to that effect.  If any problem is encountered, you will get
a message about it and the affected traces will be highlighted. One part of the
tracks of concern will be selected, while the other parts of concern will have the
"FindConnection" highlighting. The screen will automatically be centered in the
middle of the object having the "FindConnection" (Green) highlighting.  The middle of
the object is also the coordinates reported to be "near" the problem.  The actual trouble
region will be somewhere on the boundary of this object.  If the two parts are
from different nets then there is some place where they approach each
other closer than the minimum rule.  If the parts are from the same net, then
there is place where they are only barely connected. Find that place and connect
them better.

After a DRC error is found and corrected you must run the DRC again because
the search for errors is halted as soon as the first problem is found. Unless you've
been extremely careless there should be no more than a few design rule errors
in your layout.  The DRC checker does not check for minimum spacing rules to
copper text, so always be very careful when adding copper text to a layout.
The rules for the DRC are specified in the application resource file.  The minimum
spacing value (in mils) is given by the @emph{Settings.Bloat} value. The default
is 7 mils. The minimum touching overlap (in mils) is given by the
@emph{Settings.Shrink} value. This value defaults to 5 mils. Check with your
fabrication process people to determine the values that are right for you.

If you want to turn off the highlighting produced by the DRC, perform an
undo (assuming no other changes have been made).  To restore the highlighting,
use redo.  The redo will restore the highlighting quickly without re-running
the DRC checker.

@node Trace Optimizer
@section Trace Optimizer
@cindex trace optimizer
@cindex optimizer

PCB includes a flexible trace optimizer.  The trace optimizer can be run
after auto routing or hand routing to clean up the traces.

@table @b
@item Auto-Optimize
Performs debumpify, unjaggy, orthopull, vianudge, and viatrim, in that
order, repeating until no further optimizations are performed.

@item Debumpify
Looks for U shaped traces that can be shortened or eliminated.

@item Unjaggy
Looks for corners which could be flipped to eliminate one or more
corners (i.e. jaggy lines become simpler).

@item Vianudge
Looks for vias where all traces leave in the same direction. Tries to
move via in that direction to eliminate one of the traces (and thus a
corner).

@item Viatrim
Looks for traces that go from via to via, where moving that trace to a
different layer eliminates one or both vias.

@item Orthopull
Looks for chains of traces all going in one direction, with more traces
orthogonal on one side than on the other. Moves the chain in that
direction, causing a net reduction in trace length, possibly eliminating
traces and/or corners.

@item SimpleOpts
Removing unneeded vias, replacing two or more trace segments in a row
with a single segment. This is usually performed automatically after
other optimizations.

@item Miter
Replaces 90 degree corners with a pair of 45 degree corners, to reduce
RF losses and trace length.

@end table

@node Searching for elements 
@section Searching for elements
@cindex Searching for elements
@vindex Searching for elements

To locate text or a specific element or grouping of similar elements
choose @samp{Select by name} from the @b{Select} menu, then choose the
appropriate subsection.  At the bottom of the screen the prompt
@emph{pattern:} appears.  Enter the text or @ref{Regular Expressions}
of the text to be found.  Found text will be highlighted.

@node Measuring distances
@section Measuring distances
@cindex Measuring distances
@vindex Measuring distances

To measure distances, for example the pin-to-pin pitch of a part to
validate a footprint, place the cursor at the starting
measurement point, then press @emph{!Ctrl<Key>m}.  This marks the
current  location with a @emph{X}. The @emph{X} mark is now the zero point
origin for the relative cursor position display.  The cursor display
shows both absolute position and position relative to the mark as
the mouse is moved away from the mark.  If a mark is already present,
the mark is removed and the cursor display stops displaying relative
cursor coordinates.

@node Vendor drill mapping
@section Vendor Drill Mapping
@cindex Vendor rules
@cindex Vendor mapping
@cindex Drill table
@cindex Vendor drill table

@pcb{} includes support for mapping drill holes to a specified set
of sizes used by a particular vendor.  Many PCB manufacturers have a
prefered set of drill sizes and charge extra when others are used.
The mapping can be performed on an existing design and can also be
enabled to automatically map drill holes as vias and elements are
instantiated. 

The first step in using the vendor drill mapping feature is to create
a resource file describing the capabilities of your vendor.  The file
format is the resource file format described in @ref{Resource Syntax}.
A complete example is given below.

@example
# Optional name of the vendor
vendor = "Vendor Name"

# units for dimensions in this file.
# Allowed values:  mil/inch/mm
units = mil

# drill table
drillmap = @{
   # When mapping drill sizes, select the nearest size
   # or always round up.  Allowed values:  up/nearest
   round = up

   # The list of vendor drill sizes.  Units are as specified
   # above.
   20
   28
   35
   38
   42
   52
   59.5
   86
  125   
  152

   # optional section for skipping mapping of certain elements
   # based on reference designator, value, or description
   # this is useful for critical parts where you may not
   # want to change the drill size.  Note that the strings
   # are regular expressions.  
   skips = @{
      @{refdes "^J3$"@}  # Skip J3.
      @{refdes "J3"@}  # Skip anything with J3 as part of the refdes.
      @{refdes "^U[1-3]$" "^X.*"@} # Skip U1, U2, U3, and anything starting with X.
      @{value "^JOHNSTECH_.*"@} # Skip all Johnstech footprints based on the value of a part.
      @{descr "^AMP_MICTOR_767054_1$"@} # Skip based on the description.
   @}
@}

# If specified, this section will change the current DRC
# settings for the design.  Units are as specified above.
drc = @{
   copper_space = 7
   copper_width = 7
   silk_width = 10
   copper_overlap = 4
@}
@end example

The vendor resource is loaded using the @emph{LoadVendor} action.
This is invoked by entering:
@example
:LoadVendor(vendorfile)
@end example
from within @pcb{}.  Substitute the file name of your vendor
resource file for @samp{vendorfile}.  This action will load the vendor
resource and modify all the drill holes in the design as well as the
default via hole size for the various routing styles.

Once a vendor drill map has been loaded, new vias and elements will
automatically have their drill hole sizes mapped to the vendor drill
table.  Automatic drill mapping may be disabled under the ``Settings''
menu.  To re-apply an already loaded vendor drill table to a design,
choose ``Apply vendor drill mapping'' from the ``Connects'' menu.

See @ref{Actions} for a complete description of the actions associated
with vendor drill mapping.

Note that the expressions used in the @code{skips} section are regular
expressions.  See @ref{Regular Expressions} for an introduction to
regular expressions.  

@c --------------------------- Autorouter Chapter -------------------------------
@node Autorouter
@chapter Autorouter
@cindex autorouter

@pcb{} includes an autorouter which can greatly speed up the
layout of a circuit board.  The autorouter is a rectangle-expansion
type of autorouter based on 
``A Method for Gridless Routing of Printed Circuit Boards'' by
A. C. Finch, K. J. Mackenzie, G. J. Balsdon, and G. Symonds in the
1985 Proceedings of the 22nd ACM/IEEE Design Automation Conference.
This reference is available from the ACM Digital Library at
@url{http://www.acm.org/dl} for those with institutional or personal
access to it.  It's also available from your local engineering
library.  The reference paper is not needed for using the autorouter.

Before using the autorouter, all elements need to be loaded into the
layout and placed and the connectivity netlist must be loaded.  Once
the elements have been placed and the netlist loaded, the following
steps will autoroute your design.

@enumerate
@item Turn off visibility of any layers that you don't want the router
to use.

@item Turn of via visibility if you don't want the router to use any
new vias. 

@item Use only plain rectangles for power/ground planes that you want
   the router to use [use the rectangle tool!]

@item Make at least one connection from any plane you want the router to
   use to the net you want it to connect to.

@item Draw continuous lines (on all routing layers) to outline keep-out
   zones if desired.

@item Use routing styles in the netlist to have per-net routing styles.  
  Note that the routing style will be used for an entire net.  This means
  if you have a wide metal setting for a power net you will need to manually
  route breakouts from any fine pitch parts on their power pins because
  the router will not be able to change to a narrow trace to connect
  to the part.

@item Set the current routing style to whatever you'd like the router to
   use for any nets not having a defined route style in the netlist.

@item Disable any nets that you don't want the autorouter to route
   (double-click them in the  netlist window to add/remove the *)

         NOTE: If you will be manually routing these later not using
   planes, it is usually better to let the autorouter route them then rip
   them up yourself afterwards. If you plan to use a ground/power plane
   manually, consider making it from one or more pure rectangles and
   letting the autorouter have a go at it.

@item Create a fresh rat's nest. ('E' the 'W')

@item Select ``show autorouter trials'' in the settings menu if you want
   to watch what's happening

@item Choose ``autoroute all rats'' in the connection menu.

@item If you really want to muck with the router because you have a
   special design, e.g. all through-hole components you can mess with
   layer directional costs by editing the autoroute.c source file and
   changing the directional costs in lines 929-940. and try again. Even
   more mucking about with costs is possible in lines 4540-4569, but it's
   probably not such a good idea unless you really just want to
   experiment.

@end enumerate

After the design has been autorouted, you may want to run the trace
optimizer.  See section @ref{Trace Optimizer} for more information on
the trace optimizer.


@c --------------------------- User Commands chapter -------------------------------
@node User Commands
@chapter User Commands

@cindex user commands
@cindex entering user commands
The entering of user-commands is initiated by the action routine
@emph{Command()} (normally bound to the @code{(":")} character) which
replaces the bottom statusline with an input area or opens a separate
command window.  It is finished by either @emph{<Key>Return} or
@emph{<Key>Escape} to confirm or to abort. These two key-bindings
cannot be changed from the resource file.  The triggering event,
normally a key press, is ignored.

Commands can be entered in one of two styles, command entry syntax:
``@emph{Command arg1 arg2}'' or action script syntax ``@emph{Action1(arg1,
arg2); Action2(arg1, arg2);}''.  Quoting arguments works similar to
bash quoting:

@itemize
@item A backslash (\) is the escape character.  It preserves the literal
value of the next character that follows.  To get a literal '\' use
"\\".

@item Enclosing characters in single quotes preserves the literal value of
each character within the quotes.  A single quote may not occur
between single quotes, even when preceded by a blackslash.

@item Enclosing characters in double quotes preserves the literal value of
all characters within the quotes, with the exception of '\' which
maintains its special meaning as an escape character.
@end itemize

There are simple @emph{usage} dialogs for each command and one for the
complete set of commands.

@table @samp

@findex :l
@cindex loading layouts
@cindex layout, loading a
@item l [filename]
Loads a new datafile (layout) and, if confirmed, overwrites any existing unsaved data.
The filename and the searchpath (@emph{filePath}) are passed to the
command defined by @emph{fileCommand}.
If no filename is specified a file select box will popup.

@findex :le
@cindex loading elements to buffer
@cindex element, loading to buffer
@item le [filename]
Loads an element description into the paste buffer.
The filename and the searchpath (@emph{elementPath}) are passed to the
command defined by @emph{elementCommand}.
If no filename is specified a file select box will popup.

@findex :m
@cindex loading a layout to buffer
@cindex merging layouts
@cindex layout, loading to buffer
@cindex layout, merging a
@item m [filename]
Loads an layout file into the paste buffer.
The filename and the searchpath (@emph{filePath}) are passed to the
command defined by @emph{fileCommand}.
If no filename is specified a file select box will popup.

@findex :q
@cindex exit
@cindex quit
@item q[!]
Quits the program without saving any data (after confirmation).
q! doesn't ask for confirmation, it just quits.

@findex :s
@cindex saving layouts
@cindex layout files, saving of
@item s [filename]
Data and the filename are passed to the command defined by the resource
@emph{saveCommand}. It must read the layout data from @emph{stdin}.
If no filename is entered, either the last one is used
again or, if it is not available, a file select box will pop up.

@findex :rn
@cindex rat's nest
@cindex layout-name
@item rn [filename]
Reads in a netlist file.  If no filename is given
a file select box will pop up.
The file is read via the command defined by the
@emph{RatCommand} resource. The command must send its output to @emph{stdout}.

Netlists are used for generating rat's nests (see @ref{Rats Nest}) and for
verifying the board layout (which is also accomplished by the @emph{Ratsnest}
command).

@findex :w[q]
@cindex saving layouts
@cindex layout files, saving of
@item w[q] [filename]
These commands have been added for the convenience of @code{vi} users and
have the same functionality as @emph{s} combined with @emph{q}.

@findex :actionCommand()
@cindex action command
@cindex Actions, initiating
@item actionCommand
Causes the actionCommand to be executed.  This allows you to initiate actions
for which no bindings exist in the resource file.  It can be used to initiate any
action with whatever arguments you enter.  This makes it possible to do things
that otherwise would be extremely tedious.  For example, to change the drilling
hole diameter of all vias in the layout to 32 mils, you could select everything using the
selection menu, then type "@emph{:ChangeDrillSize(SelectedVias, 32)}".  (This will
only work provided the via's diameter is sufficiently large to accommodate a 32 mil hole).
Another example might be to set the grid to 1 mil by typing "@emph{:SetValue(Grid, 1)}".
Note that some actions use the current cursor location, so be sure to place the cursor
where you want before entering the command.  This is one of my favorite new
features in 1.5 and can be a powerful tool. Study the @ref{Actions} section to
see what actions are available.

@end table


@c --------------------------- chapter 4 -------------------------------
@node Command-Line Options
@chapter Command-Line Options
@cindex starting @pcb{}
@cindex command-line options

The synopsis of the pcb command is:

@code{pcb [OPTION ...] [LAYOUT-FILE.pcb]} to start the application in GUI mode,

@noindent or

@code{pcb [-h | -V | --copyright]} for a list of options, version, and copyright,

@noindent or

@code{pcb -p [OPTION ...] [LAYOUT-FILE.pcb]} to print a layout,

@noindent or

@code{pcb -x HID [OPTION ...] [LAYOUT-FILE.pcb]} to export.

@noindent Possible values for the parameter @samp{HID} are:
 @table @samp
   @item bom
    Export a bill of materials
   @item gcode
    Export to G-Code
   @item gerber
    Export RS-274X (Gerber)
   @item nelma
    Numerical analysis package export
   @item png
    export GIF/JPEG/PNG
   @item ps
    export postscript
   @item eps
    export encapsulated postscript
@end table

@noindent There are several resources which may be set or reset in addition to the
standard toolkit command-line options. For a complete list refer to
@ref{Resources}.


@include options.texi



@c --------------------------- chapter 5 -------------------------------
@node X11 Interface
@chapter X11 Interface
@cindex X11

This chapter gives an overview about the additional @code{X11} resources which
are defined by @pcb{} as well as the defined action routines.

@menu
* Resources::      Non-standard @code{X11} application resources.
* Actions::        A list of available action routines.
* Translations::   A list of the default key translations (as shipped).
@end menu


@node Resources
@section Non-Standard X11 Application Resources
@cindex resources
@cindex X11 resources

In addition to the toolkit resources, @pcb{} defines the
following resources:

@table @samp

@vindex absoluteGrid
@cindex grid
@item absoluteGrid (boolean)
Selects if either the grid is relative to the position where it has changed
last or absolute, the default, to the origin (0,0).

@vindex alignmentDistance
@cindex alignment
@item alignmentDistance (dimension)
Specifies the distance between the boards outline to the alignment targets.

@vindex allDirectionLines
@cindex lines, clipping to 45 degree
@cindex clipping lines to 45 degree
@item allDirectionLines (boolean)
Enables (default) or disables clipping of new lines to 45 degree angles.

@vindex backgroundImage
@cindex background
@item backgroundImage (string)
If specified, this image will be drawn as the background for the
board.  The purpose of this option is to allow you to use a scan of an
existing layout as a prototype for your new layout.  To do this, there
are some limitations as to what this image must be.  The image must be
a PPM binary image (magic number @samp{P6}).  It must have a maximum
pixel value of 255 or less (i.e. no 16-bit images).  It must represent
the entire board, as it will be scaled to fit the board dimensions
exactly.  Note that it may be scaled unevenly if the image doesn't
have the same aspect ratio of your board.  You must ensure that the
image does not use more colors than are available on your system
(mostly this is for pseudo-color displays, like old 8-bit displays).
For best results, I suggest the following procedure using The Gimp:
Load your image (any type).  Image->Scale if needed.
Image->Colors->Curves and for each of Red, Green, and Blue channel
move the lower left point up to about the 3/4 line (value 192).  This
will make your image pale so it doesn't interfere with the traces
you'll be adding.  Image->Mode->Indexed and select, say, 32 colors
with Normal F-S dithering.  File->Save As, file type by extension,
use @file{.ppm} as the extension.  Select Raw formatting.

@vindex backupInterval
@cindex backup
@item backupInterval (int)
@pcb{} has an automatic backup feature which saves the current data
every n seconds. The default is @emph{300} seconds. A value of zero disables
the feature. The backup file is named @file{/tmp/PCB.%i.backup} by
default (this may have been changed at compilation time via the
@code{BACKUP_NAME}
variable in @file{globalconfig.h}).
@emph{%i} is replaced by the process ID.
See also, the command-line option @emph{--backup-interval}.

@vindex bloat
@cindex bloat
@cindex drc
@item Bloat (dimension)
Specifies the minimum spacing design rule in mils.

@vindex connectedColor
@cindex colors
@cindex connections, colors
@item connectedColor (color)
All pins, vias, lines and rectangles which are selected during a connection
search are drawn with this color. The default value is determined by
@emph{XtDefaultForeground}.

@vindex cross hairColor
@cindex colors
@cindex cursor color
@item cross hairColor (color)
This color is used to draw the cross hair cursor. The color is a result of
a @emph{XOR} operation with the contents of the Layout area. The result
also depends on the default colormap of the @code{X11} server because only
the colormap index is used in the boolean operation and @pcb{} doesn't
create its own colormap. The default setting is @emph{XtDefaultForeground}.

@vindex elementColor
@vindex elementSelectedColor
@cindex colors
@cindex element, color
@item elementColor (color)
@itemx elementSelectedColor (color)
The elements package part is drawn in these colors, for normal and selected
mode, respectively, which both default to @emph{XtDefaultForeground}.

@vindex elementCommand
@cindex element, command
@cindex element, files
@cindex loading elements
@cindex preprocessing element data
@cindex unix command
@cindex m4
@item elementCommand (string)
@pcb{} uses a user defined command to read element files. This resources
is used to set the command which is executed by the users default shell.
Two escape sequences are defined to pass the selected filename (%f) and the
current search path (%p). The command must write the element data
to its standard output. The default value is
@example
    M4PATH="%p";export M4PATH;echo 'include(%f)' | m4
@end example
Using the GNU version of @code{m4} is highly recommended.
See also, the command-line option @emph{--element-command}.

@vindex elementPath
@cindex searchpath for element files
@cindex path for element files
@cindex element, files
@cindex loading elements
@item elementPath (string)
A colon separated list of directories or commands (starts with '|').
The path is passed to the program specified in @emph{elementCommand} together
with the selected element name. A specified command will be executed in order
to create entries for the fileselect box. It must write its results to
@emph{stdout} one entry per line.
See also, the user-command @emph{le[!]}.

@vindex fileCommand
@cindex file load command
@cindex layout files
@cindex loading layouts
@cindex preprocessing layout data
@cindex unix command
@cindex cat
@item fileCommand (string)
The command is executed by the user's default shell whenever existing layout
files are loaded. Data is read from the command's standard output.
Two escape sequences may be specified to pass the selected filename (%f)
and the current search path (%p). The default value is:
@example
    cat %f
@end example
See also, the command-line option @emph{--file-command}.

@vindex filePath
@cindex searchpath for layout files
@cindex path for layout files
@cindex layout files
@cindex loading layouts
@item filePath (string)
A colon separated list of directories or commands (starts with '|').
The path is passed to the program specified in @emph{fileCommand} together
with the selected filename. A specified command will be executed in order
to create entries for the fileselect box. It must write its results to
@emph{stdout} one entry per line.
See also, the user-command @emph{l[!]}.

@vindex fontCommand
@cindex font command
@cindex font files
@cindex loading fonts
@cindex loading symbols
@cindex preprocessing font data
@cindex unix command
@cindex cat
@item fontCommand (string)
Loading new symbol sets also is handled by an external command. You again
may pass the selected filename and the current search path by passing
%f and %p in the command string. Data is read from the commands standard
output. This command defaults to
@example
    cat %f
@end example
See also, the command-line option @emph{--font-command}.

@vindex fontFile
@cindex default font
@cindex symbols
@item fontFile (string)
The default font for new layouts is read from this file which is searched
in the directories as defined by the resource @emph{fontPath}.
Searching is only performed if the filename does not contain a directory
component.
The default filename is @file{default_font}.

@vindex fontPath
@cindex searchpath for font files
@cindex path for font files
@cindex font files
@cindex loading fonts
@cindex loading symbols
@item fontPath (string)
This resource, a colon separated list of directories, defines the searchpath
for font files. See also, the resource @emph{fontFile}.

@vindex grid
@cindex grid
@cindex cursor steps
@item grid (int)
This resources defines the initial value of one cursor step. It defaults
to @emph{100 mil} and any changes are saved together with the layout data.

@vindex gridColor
@cindex colors
@cindex grid color
@item gridColor (color)
This color is used to draw the grid. The color is a result of
a @emph{INVERT} operation with the contents of the Layout area. The result
also depends on the default colormap of the @code{X11} server because only
the colormap index is used in the boolean operation and @pcb{} doesn't
create its own colormap. The default setting is @emph{XtDefaultForeground}.

@vindex invisibleObjectsColor
@cindex colors
@cindex element, color
@item invisibleObjectsColor (color)
Elements located on the opposite side of the board are drawn in this color.
The default is @emph{XtDefaultForeground}.

@vindex layerColor
@vindex layerSelectedColor
@cindex colors
@cindex layers, colors
@item layerColor1..MAX_LAYER (color)
@itemx layerSelectedColor1..MAX_LAYER (color)
These resources define the drawing colors of the different layers in
normal and selected state. All values are preset to @emph{XtDefaultForeground}.

@vindex layerGroups
@cindex layers, groups
@cindex groups
@item layerGroups (string)
The argument to this resource is a colon separated list of comma separated
layer numbers (1..MAX_LAYER). All layers within one group are switched on/off
together. The default setting is @emph{1:2:3:...:MAX_LAYER} which means
all layers are handled separately. Grouping layers one to three looks like
@emph{1,2,3:4:...:MAX_LAYER}

@vindex layerName
@cindex layer, name of
@item layerName1..MAX_LAYER (string)
The default name of the layers in a new layout are determined by these
resources. The defaults are empty strings.

@vindex libraryCommand
@cindex library command
@cindex loading elements
@cindex unix command
@item libraryCommand (string)
@pcb{} uses a command to read element data from libraries.
The resources is used to set the command which is executed by the users
default shell.  Three escape sequences are defined to pass the selected
filename (%f), the current search path (%p) as well (%a) as the three
parameters @emph{template}, @emph{value} and @emph{package} to the command.
It must write the element data to its standard output. The default value is
@example
    NONE/share/pcb/oldlib/QueryLibrary.sh %p %f %a
@end example

@vindex elementContentsCommand
@cindex library contents command
@cindex listing library contents
@cindex unix command
@item libraryContentsCommand (string)
Similar to @emph{libraryCommand}, @pcb{} uses the command specified
by this resource to list the contents of a library.
@example
        NONE/share/pcb/oldlib/ListLibraryContents.sh %p %f
@end example
is the default.

@vindex libraryFilename
@cindex default library
@cindex library name
@item libraryFilename (string)
The resource specifies the name of the library. The default value is
@emph{pcblib} unless changed at compile time
with the @code{LIBRARYFILENAME} variable in @file{globalconfig.h}.

@vindex libraryPath
@cindex searchpath for libraries
@cindex path for libraries
@cindex library searchpath
@item libraryPath (string)
A colon separated list of directories that will be passed to the commands
specified by @emph{elementCommand} and @emph{elementContentsCommand}.

@vindex lineThickness
@cindex lines, size
@cindex size of lines
@cindex thickness of lines
@item lineThickness (dimension)
The value, in the range [1..250] (the range may be changed at compile
time with the @code{MIN_LINESIZE} and @code{MAX_LINESIZE} variables in
@file{globalconfig.h}), defines the
initial thickness of new lines. The value is preset to @emph{ten mil}.

@vindex media
@cindex media
@cindex media margin
@cindex print media
@item media (<predefined> | <width>x<height>+-<left_margin>+-<top_margin>)
The default (user defined) media of the @code{PostScript} device. Predefined
values are @emph{a3}, @emph{a4}, @emph{a5}, @emph{letter}, @emph{tabloit},
@emph{ledger}, @emph{legal}, and @emph{executive}.
The second way is to specify the medias width, height and margins in mil.
The resource defaults to @emph{a4} size unless changed at compile time
with the @code{DEFAULT_MEDIASIZE} variable in @file{globalconfig.h}.

@vindex offLimitColor
@cindex colors
@cindex off limit color
@item offLimitColor (color)
The area outside the current maximum settings for width and height is drawn
with this color. The default value is determined by @emph{XtDefaultBackground}.

@vindex pinColor
@vindex pinSelectedColor
@cindex colors
@cindex pin color
@item pinColor (color)
@itemx pinSelectedColor(color)
This resource defines the drawing color of pins and pads in both states.
The values are preset to @emph{XtDefaultForeground}.

@vindex pinoutFont0..6
@cindex font, used for pin names
@cindex pinout, font to display pin names
@item pinoutFont (string)
This fonts are used to display pin names. There is one font for each zoom
value. The values are preset to @emph{XtdefaultFont}.

@vindex pinoutNameLength
@cindex namelength of pins
@cindex pin, name of
@cindex length of a pin name
@item pinoutNameLength (int)
This resource limits the number of characters which are displayed for
pin names in the pinout window. By default the string length is limited
to @emph{eight} characters per name.

@vindex pinoutOffsetX
@vindex pinoutOffsetY
@cindex offset of pinout
@item pinoutOffsetX (int)
@itemx pinoutOffsetY (int)
These resources determine the offset in @emph{mil} of the circuit from the
upper left corner of the window when displaying pinout information.
Both default to @emph{100 mil}.

@vindex pinoutTextOffsetX
@vindex pinoutTextOffsetY
@cindex offset of pinnames
@item pinoutTextOffsetX (int)
@itemx pinoutTextOffsetY (int)
The resources determine the distance in mil between the drilling hole of a pin
to the location where its name is displayed in the pinout window.
They default to @emph{X:50} and @emph{Y:0}.

@vindex pinoutZoom
@cindex pinout, zoomfactor of display
@cindex zoom of pinout window
@item pinoutZoom (int)
Sets the zoom factor for the pinout window according to the formula:
scale = 1:(2 power value). Its default value is @emph{two} which results in
a @emph{1:4} scale.

@vindex printCommand
@cindex printing
@item printCommand (string)
Default file for printouts. If the name starts with a '|' the output
is piped through the command. A %f is replaced by the current filename.
There is no default file or command.

@vindex raiseLogWindow
@cindex log window
@cindex messages
@item raiseLogWindow (boolean)
The log window will be raised when new messages arrive if this resource
is set @emph{true}, the default.

@vindex ratCommand
@cindex rats nest
@cindex netlist
@item ratCommand (string)
Default command for reading a netlist. A %f is replaced by the netlist
filename. Its default value is "@emph{cat %f}".

@vindex ratPath
@cindex rats nest
@cindex netlist
@item ratPath (string)
Default path to look for netlist files. It's default value is "."

@vindex resetAfterElement
@cindex connections, reseting after element
@cindex reseting found connections
@item resetAfterElement (boolean)
If set to @emph{true}, all found connections will be reset before a new
element is scanned. This will produce long lists when scanning the whole
layout for connections. The resource is set to @emph{false} by default.
The feature is only used while looking up connections of all elements.

@vindex ringBellWhenFinished
@cindex keyboard bell
@item ringBellWhenFinished (boolean)
Whether to ring the bell (the default) when a possibly lengthy operation
has finished or not.
See also, the command-line option @emph{--ring-bell-finished}.

@vindex routeStyle
@cindex routing style
@item routeStyle (string)
Default values for the menu of routing styles (seen in the sizes menu).
The string is a comma separated list of name, line thickness,
via diameter, and via drill size.
e.g. "Fat,50,100,40:Skinny,8,35,20:75Ohm,110,110,20"
See also, the command-line option @emph{--route-styles} and @emph{Sizes Menu}

@vindex rubberBandMode
@cindex move
@cindex rubberband
@cindex rotate
@item rubberBandMode (boolean)
Whether rubberband move and rotate (attached lines stretch like
rubberbands) is enabled (the default).

@vindex saveCommand
@cindex file save command
@cindex layout files
@cindex saving layouts
@cindex postprocessing layout data
@cindex unix command
@cindex cat
@item saveCommand (string)
This command is used to save data to a layout file. The filename may be
indicated by placing @code{%f} in the string. It must read the data from
its standard input.  The default command is:
@example
    cat - > %f
@end example
See also, the command-line option @emph{--save-command}.

@vindex saveInTMP
@cindex backup
@cindex saving layouts
@cindex preventing loss of data
@cindex temporary files
@cindex /tmp
@cindex directory /tmp
@item saveInTMP (boolean)
Enabling this resource will save all data which would otherwise be lost
in a temporary file @file{/tmp/PCB.%i.save}.  The file name may
be changed at compile time
with the @code{EMERGENCY_NAME} variable in @file{globalconfig.h}.
.
@emph{%i} is replaced by the process ID.
As an example, loading a new layout when the old one hasn't been saved would
use this resource.
See also, the command-line option @emph{--save-in-tmp}.

@vindex saveLastCommand
@cindex saving last entered user command
@cindex inputfield, saving entered command-line
@item saveLastCommand (boolean)
Enables the saving of the last entered user command. The option is
@emph{disabled} by default.
See also, the command-line option @emph{--save-last-command}.

@vindex shrink
@cindex shrink
@cindex drc
@item Shrink (dimension)
Specifies the minimum overlap (touching) design rule in mils.

@vindex size
@cindex default layout size
@cindex layout, default size of
@item size (<width>x<height>)
Defines the width and height of a new layout. The default is
@emph{7000x5000} unless changed at compile time
with the @code{DEFAULT_SIZE} variable in @file{globalconfig.h}.


@vindex stipplePolygons
@cindex polygon
@cindex display
@item stipllePolygons (boolean)
Determines whether to display polygons on the screen with a stippled
pattern.  Stippling can create some amount of transparency so that
you can still (to some extent) see layers beneath polygons.
It defaults to False.

@vindex textScale
@cindex text, default scaling
@cindex default text scaling
@item textScale (dimension)
The font scaling in percent is defined by this resource. The default is
@emph{100} percent.

@vindex useLogWindow
@cindex log window
@cindex messages
@item useLogWindow (boolean)
Several subroutines send messages to the user if an error occurs.
This resource determines if they appear inside the log window or as a separate
dialog box. See also, the resource @emph{raiseLogWindow} and the command line
option @emph{-loggeometry}.
The default value is @emph{true}.

@vindex viaColor
@vindex viaSelectedColor
@cindex colors
@cindex vias, color
@item viaColor (color)
@item viaSelectedColor (color)
This resource defines the drawing color of vias in both states.
The values are preset to @emph{XtDefaultForeground}.

@vindex viaThickness
@vindex viaDrillingHole
@cindex vias, size
@cindex size of vias
@cindex thickness of vias
@item viaThickness (dimension)
@itemx viaDrillingHole (dimension)
The initial thickness and drilling hole of new vias. The values must be in the
range [30..400] (the range may be changed at compile
time with the @code{MIN_PINORVIASIZE} and @code{MAX_PINEORVIASIZE} variables in
@file{globalconfig.h}), with at least 20
mil of copper.
The default thickness is @emph{40 mil} and the default drilling hole is
@emph{20 mil}.

@vindex volume
@cindex speaker volume
@cindex volume of speaker
@item volume (int)
The value is passed to @code{XBell()} which sets the volume of the @code{X}
speaker.
The value lies in the range -100..100 and it defaults to the maximum volume of
@emph{100}.

@vindex warnColor
@cindex colors
@cindex color, warning
@item warnColor (color)
This resources defines the color to be used for drawing pins and pads when
a warning has been issued about them.

@vindex zoom
@cindex zoom of Layout area
@item zoom (int)
The initial value for output scaling is set according to the following
formula: scale = 1:(2 power value). It defaults to @emph{three} which results
in an output scale of @emph{1:8}.

@end table

Refer also to @ref{Command-Line Options}.

@node Actions
@section Actions
@cindex actions
@cindex translations
@cindex key translations
@cindex button translations
@cindex X11 translations

All user accessible commands may be bound to almost any @code{X} event. Almost
no default binding for commands is done in the binaries, so it is vital for the
application that at least a system-wide application resource file exists.
This file normally resides in the @file{share/pcb} directory and
is called @file{Pcb}. The bindings to which the manual refers to are the
ones as defined by the shipped resource file. Besides binding an action to
an X11 event, you can also execute any action command using a ":" command
(see @ref{User Commands}).

Take special care about translations related to the functions keys and the
pointer buttons because most of the window managers use them too.
Change the file according to your hardware/software environment.
You may have to replace all occurances of @emph{baseTranslations} to
@emph{translations} if you use a @code{X11R4} server.

Passing @emph{Object} as an argument to an action routine causes the object
at the cursor location to be changed, removed or whatever. If more than
one object is located at the cross hair position the smallest type is used.
If there are two of the same type the newer one is taken.
@emph{SelectedObjects} will handle all selected and visible objects.


@table @samp
@findex AddRats()
@cindex rats nest
@cindex netlist
@cindex rat-line
@item AddRats(AllRats|SelectedRats)
Adds rat-lines to the layout using the loaded netlist file (see the @emph{:rn},
@ref{User Commands}.). Rat lines are added on the active layer using the current
line thickness shown in the status line.
Only missing connectivity is added by the
AddRats command so if, for example, the layout is complete nothing will be added.
Rat lines may be drawn different to other lines on the screen
to make them easier to identify since they cannot appear in a completed layout.
The rat-lines are added in the minimum length straight-line tree pattern
(always ending on pins or pads) that satisfies the missing connectivity in the circuit.
If a SMD pad is unreachable on the active layer, a warning will be issued
about it and the rat-line to that pad will not be generated.
If connections exist on the board which are not listed in the netlist while
AllRats are being added, warning messages will be issued and the affected pins and
pads will be drawn in a special @emph{warnColor} until the next @emph{Notify()} event.
If the entire layout agrees completely with the net-list a message informs you that
the layout is complete and no rat-lines are added (since none are needed).
If @emph{SelectedRats}
is passed as the argument, only those missing connections that might connect among
the selected pins and pads are drawn.
Default:
@example
None<Key>w:     AddRats(AllRats)
!Shift<Key>w:   AddRats(SelectedRats)
None<Key>o:     DeleteRats(AllRats) AddRats(AllRats)
!Shift<Key>o:   DeleteRats(SelectedRats) AddRats(SelectedRats)
@end example

@findex ApplyVendor()
@cindex vendor map
@cindex vendor drill table
@item ApplyVendor()
Applies an already loaded vendor drill map to the design.
@example
ApplyVendor()
@end example

@findex Atomic()
@cindex undo, multi-action resources
@cindex atomic
@item Atomic(Save|Restore|Block|Close)
Controls the undo grouping of sequences of actions. Before the first action
in a group, Atomic(Save) should be issued.  After each action that might
be undoable, Atomic(Restore) should be issued.  Atomic(Block) concludes
and save the undo grouping if there was anything in the group to undo.
Atomic(Close) concludes and save the undo grouping even if nothing was
actually done.  Thus it might produce an "empty" undo.  This can be useful
when you want to use undo in a group of actions.

@findex Bell()
@cindex signal
@cindex bell
@item Bell([-100..100])
Rings the bell of your display. If no value is passed the setting
of the resource @emph{volume} will be used.

@findex ChangeClearSize()
@cindex change sizes
@cindex sizes, changing of objects
@cindex clearance, changing of objects
@item ChangeClearSize(Object, value[, unit])
@itemx ChangeClearSize(SelectedPins|SelectedVias, value[, unit])
The effect of this action depends on if the soldermask display is presently
turned on or off. If soldermask is displayed, then the soldermask
relief size will be changed.  If soldermask display is turned off,
then the clearance to polygons will be changed.
@emph{unit} is "mil" or "mm".  If not specified the units will default
to the internal unit of 0.01 mil.
@example
!Mod1<Key>k:      ChangeClearSize(Object, +2, mil)
!Mod1 Shift<Key>k: ChangeClearSize(Object, -2, mil)
@end example

@findex ChangeDrillSize()
@cindex change sizes
@cindex sizes, changing of objects
@cindex drilling hole, changing of objects
@item ChangeDrillSize(Object, value[, unit])
@itemx ChangeDrillSize(SelectedPins|SelectedVias, value[, unit])
This action routine changes the drilling hole of pins and vias.
If @emph{value} starts with + or -, then it adds (or subtracts)
@emph{value} from the current hole diameter, otherwise it sets the
diameter to the value.
@emph{unit} is "mil" or "mm".  If not specified the units will default
to the internal unit of 0.01 mil.
Default:
@example
!Mod1<Key>s:       Change2ndSize(Object, +5, mil)
!Mod1 Shift<Key>s: Change2ndSize(Object, -5, mil)
@end example

@findex ChangeFlag()
@cindex flags, changing
@cindex octagonal flag, changing
@cindex square flag, changing
@cindex thermal flag, changing
@itemx ChangeFlag(Object|SelectElements|SelectedPins|SelectedVias|Selected,thermal|octagon|square,0|1)
Sets/clears the indicated flag.  This adds/removes thermals, adds/removes the flag
which indicates a pin/pad should be square, or adds/removes the flag which
indicates a pin/pad should be octagonal.
@example
:ChangeFlag(SelectedVias,thermal,1)
:ChangeFlag(SelectedPads,square,0)
@end example

@findex ChangeHole()
@cindex vias, converting to mounting hole
@cindex mounting holes
@item ChangeHole(Object|SelectedVias)
This action routine converts a via to and from a hole.  A hole is
a via that has no copper annulus. The drill size for the via
determines the hole diameter.
@example
!Ctrl<Key>h:    ChangeHole(Object)
@end example

@findex ChangeName()
@cindex name, change an objects
@cindex change object name
@cindex object, change name of
@item ChangeName(Object)
@itemx ChangeName(Layer|Layout)
Changes the name of the visible object at the cursor location. A text object
doesn't have a name therefore the text string itself is changed.
The element name currently used for display is always the one changed with this
command.
See @emph{Display(Description|NameOnPCB|Value)} for details.
Passing @emph{Layer} changes the current layers name.
Default:
@example
None<Key>n: ChangeName(Object)
@end example

@findex ChangeOctagon()
@cindex pins, changing shape of
@cindex vias, changing shape of
@cindex octagonal pins and vias
@itemx ChangeOctagon(Object|SelectElements|SelectedPins|SelectedVias|Selected)
Toggles what shape the affected pin(s) or via(s) will be drawn when they
are not square. The shape will either be round or octagonal.
Default:
@example
!Ctrl<Key>o: ChangeOctagon(Object)
@end example

@findex ChangePinName()
@cindex changing pin/pad names
@cindex pin/pad names, changing
@item ChangePinName(ElementName, PinNumber, PinName)
Changes the name for a specified pin or pad number on a specified element.
This action is typically used to forward annotate pin/pad names from a schematic
to the layout.
@example
ChangePinName(U1, 14, VDD)
@end example


@findex ChangeSize()
@cindex change sizes
@cindex sizes, changing of objects
@cindex thickness, changing of objects
@item ChangeSize(Object, value[, unit])
@itemx ChangeSize(SelectedLines|SelectedPins|SelectedVias, value[, unit])
@itemx ChangeSize(SelectedPads|SelectedTexts|SelectedNames, value[, unit])
@itemx ChangeSize(SelectedElements, value[, unit])
To change the size of an object you have to bind these action to some
@code{X} event (or use :ChangeSize(...)).  If @emph{value} begins with
a + or - then the value will be added (or subtracted) from the current
size, otherwise the size is set equal to @emph{value}. Range checking is
done to insure that none of the maximum/minimums of any size are violated.
If @emph{Object} is passed then a single object at the cursor location is
changed. If any of the @emph{Selected} arguments are passed then all selected
and visible objects of that type are changed. If the type being modified is
an element, then the thickness of the silkscreen lines defining the element
is changed.
@emph{unit} is "mil" or "mm".  If not specified the units will default
to the internal unit of 0.01 mil.
Default:
@example
None<Key>s:   ChangeSize(Object, +5)
!Shift<Key>s: ChangeSize(Object, -5)
@end example

@findex ChangeSquare()
@cindex change square flag
@cindex square flag, changing of objects
@cindex thickness, changing of objects
@item ChangeSquare(Object|SelectedElements|SelectedPins)
Toggles the setting of the square flag. The flag is used to identify a
certain pin, normally the first one, of circuits. It is also used to
make SMD pads have square ends.
@example
None<Key>q:   ChangeSquare(Object)
@end example

@findex ClrFlag()
@cindex flags, clearing
@cindex flags, clearing
@cindex octagonal flag, clearing
@cindex square flag, clearing
@cindex thermal flag, clearing
@itemx ClrFlag(Object|SelectElements|SelectedPins|SelectedVias|Selected,thermal|octagon|square)
Clears the indicated flag.  This removes thermals, removes the flag
which indicates a pin/pad should be square, or removes the flag which
indicates a pin/pad should be octagonal.
@example
:ClrFlag(SelectedVias,thermal)
@end example

@findex Command()
@cindex start user input
@cindex inputfield, start user input
@item Command()
Calling @emph{Command()} pops up an input line at the bottom of the window
which allows you to enter commands. Including all action commands!
The dialog ends when @emph{None<Key>Return}
to confirm or @emph{None<Key>Escape} to abort is entered.
Default:
@example
<Key>colon: Command()
@end example

@findex Connection()
@cindex scanning connections
@cindex searching connections
@cindex connections, reseting
@cindex reseting found connections
@cindex connections, searching for
@cindex saving found connections
@item Connection(Find)
@itemx Connection(ResetFoundLinesAndRectangles|ResetPinsViasAndPads|Reset)
The @emph{Connection()} action is used to mark all connections from one pin,
line or via to others.
The @emph{ResetFoundLinesAndRectangles, ResetFoundPinsAndVias} and
@emph{Reset} arguments may be used to reset all marked lines and rectangles,
vias and pins or all of them. The search starts with the pin or via
at the cursor position. All found objects are drawn with the color
defined by the resource @emph{connectedColor}.
See also, @emph{Display(Description|NameOnPCB|Value)}.
Default:
@example
!Shift<Key>c: Connection(Reset)
None<Key>f:   Connection(Find)
!Shift<Key>f: Connection(Reset)
@end example

@findex DeleteRats()
@cindex rats nest
@cindex rat-line
@cindex netlist
@item DeleteRats(AllRats|SelectedRats)
This routine deletes either all rat-lines in the layout, or only
the selected and visible ones. Non-rat-lines and other layout
objects are unaffected.
Default:
@example
None<Key>e:   DeleteRats(AllRats)
!Shift<Key>e: DeleteRats(SelectedRats)
@end example

@findex DisableVendor()
@cindex vendor map, disabling
@cindex vendor drill table, disabling
@item DisableVendor()
Disables automatic drill size mapping to the loaded vendor drill table.
@example
DisableVendor()
@end example

@findex DisperseElements()
@cindex dispersing elements
@cindex distributing elements
@cindex elements, dispersing
@cindex elements, distributing
@item DisperseElements(All|Selected)
Disperses either all elements or only the selected elements in the
layout.  This action should be used at the
start of a design to spread out all footprints before any placement or
routing is done.  
@example
DisperseElements(All)
@end example


@findex Display()
@cindex centering
@cindex redrawing layout
@cindex refreshing layout
@cindex name of an element
@cindex displaying element names
@cindex element, display names of
@cindex grid, absolute and relative
@cindex grid, display
@cindex rubberband
@cindex pinout, display of
@cindex displaying pinout
@cindex lines, clipping to 45 degree
@cindex clipping lines to 45 degree
@item Display(Description|NameOnPCB|Value)
@itemx Display(Toggle45Degree|CycleClip)
@itemx Display(Grid|ToggleGrid)
@itemx Display(ToggleRubberBandMode)
@itemx Display(Center|ClearAndRedraw|Redraw)
@itemx Display(Pinout|PinOrPadName)
This action routines handles some output related settings. It is
used to center the display around the cursor location and to redraw the
output area optionally after clearing the window.
Centering is done with respect to the @emph{grid} setting. Displaying the
grid itself may be switched on and off by @emph{Grid} but only if
the distance between two pixels exceeds 4 pixels.
@pcb{} is able to handle several labels of an element. One of them
is a description of the functionality (eg resistor), the second should be
a unique identifier (R1) whereas the last one is a value (100k).
The @emph{Display()} action selects which of the names is displayed.
It also controls which name will be affected by the @emph{ChangeName} command.
If @emph{ToggleGrid} is passed, @pcb{} changes between relative
('rel' in the statusline) and absolute grid (an 'abs' in the statusline).
Relative grid means the pointer position when the command is issued is
used as the grid origin; while (0,0) is used in the absolute grid case.
Passing @emph{Pinout} displays the pinout of the element at the current
cursor location whereas @emph{PinOrPadName} toggles displaying of the
pins or pads name under the cursor. If none of them matches but the cursor
is inside of an element, the flags is toggled for all of its pins and pads.
For details about rubberbands see also the details about @emph{Mode}.
Default:
@example
None<Key>c:  Display(Center)
None<Key>d:  Display(PinOrPadName)
!Shift<Key>d: Display(Pinout)
None<Key>r:  Display(ClearAndRedraw)
None<Key>.:  Display(Toggle45Degree)
None<Key>/:  Display(CycleClip)
@end example

@findex DRC()
@cindex design rule checking
@cindex drc
@item DRC()
Initiates design rule checking of the entire layout. Must be repeated
until no errors are found.

@findex ExecuteFile()
@cindex actions file, executing
@cindex script file, executing
@itemx ExecuteFile(filename)
Executes the PCB actions contained in the specified file.
This can be used to automate a complex sequence of operations.
@example
:ExecuteFile(custom.cmd)
@end example
The command file contains a list of PCB actions.  Blank lines
are ignored and lines starting with a # are treated as comment
lines.  For example
@example
# This is a comment line
Display(Grid)
SetValue(Zoom,2)
DRC()
@end example

@findex EditLayerGroups()
@cindex layers, editing of groups
@cindex groups, editing of
@item EditLayerGroups()
Pops up a dialog box to edit the layergroup setting. The function is also
available from the @emph{Objects} menu.
There are no defaults.

@findex EnableVendor()
@cindex vendor map, enabling
@cindex vendor drill table, enabling
@item EnableVendor()
Enables automatic drill size mapping to the loaded vendor drill table.
@example
EnableVendor()
@end example


@findex Load()
@cindex loading files
@item Load(ElementToBuffer|Layout|LayoutToBuffer|Nelist)
This routine pops up a fileselect box to load layout, element data,
or netlist.
The passed filename for layout data is saved and may be reused.
@emph{ElementToBuffer} and @emph{LayoutToBuffer} load the data into the
current buffer.
There are no defaults.

@findex LoadVendor()
@cindex vendor map, loading
@cindex vendor drill table, loading
@item LoadVendor(vendorfile)
Loads the specified vendor resource file.
@example
LoadVendor(myvendor.res)
@end example

@findex MarkCrosshair()
@cindex mark
@cindex cursor position
@item MarkCrosshair()
This routine marks the current cursor location with an X, and then
the cursor display shows both absolute position and position relative to
the mark.  If a mark is already present, this routine removes it and
stops displaying relative cursor coordinates.
Defaults:
@example
!Ctrl<key>m:    MarkCrosshair()
@end example

@findex Mode()
@cindex mode, selecting of
@cindex operation modes, selecting of
@item Mode(Copy|InsertPoint|Line|Move|None|PasteBuffer|Polygon|Thermal)
@itemx Mode(Remove|Rectangle|RubberbandMove|Text|Via)
@itemx Mode(Cycle)
@itemx Mode(Notify)
@itemx Mode(Save|Restore)
Switches to a new mode of operation. The active mode is displayed by a thick
line around the matching mode selector button.
Most of the functionality of @pcb{} is implemented by selecting a mode
and calling @emph{Mode(Notify)}. The arguments @emph{Line}, @emph{Polygon},
@emph{Rectangle}, @emph{Text} and @emph{Via} are used to create the
appropriate object whenever @emph{Mode(Notify)} is called. Some of them,
such as @emph{Polygon}, need more than one call for one object to be created.
@emph{InsertPoint} adds points to existing polygons or lines.
@emph{Save} and @emph{Restore} are used to temporarily save the mode, switch
to another one, call @emph{Mode(Notify)} and restore the saved one. Have
a look at the application resource file for examples.
@emph{Copy} and @emph{Move} modes are used to change an object's location and,
optionally, to create a new one. The first call of @emph{Mode(Notify)} attaches
the object at the pointer location to the cross hair whereas the second
one drops it to the layout. The @emph{rubberband} version of move performs the
move while overriding the current rubberband mode.
Passing @emph{PasteBuffer} attaches the contents of the currently selected
buffer to the cross hair. Each call to @emph{Mode(Notify)} pastes this contents
to the layout. @emph{Mode(Cycle)} cycles through the modes available in the
mode-button pallet.
@emph{Mode(None)} switches all modes off.
Default:
@example
<Key>Escape:             Mode(None)
<Key>space:              Mode(Cycle)
None<Key>BackSpace:      Mode(Save) Mode(Remove) Mode(Notify) Mode(Restore)
None<Key>Delete:         Mode(Save) Mode(Remove) Mode(Notify) Mode(Restore)
None<Key>F1:             Mode(Via)
None<Key>F2:             Mode(Line)
None<Key>F3:             Mode(PasteBuffer)
None<Key>F4:             Mode(Rectangle)
None<Key>F5:             Mode(Text)
None<Key>F6:             Mode(Polygon)
None<Key>F7:             Mode(Thermal)
None<Key>F8:             Mode(Arc)
None<Key>Insert:         Mode(InsertPoint)
None<Key>[:              Mode(Save) Mode(Move) Mode(Notify)
None<Key>]:              Mode(Notify) Mode(Restore)
None<Btn1>:          Mode(Notify)
!Shift Ctrl<Btn1>:   Mode(Save) Mode(Remove) Mode(Notify) Mode(Restore)
None<Btn2Down>:          Mode(Save) Mode(Move) Mode(Notify)
None<Btn2Up>:            Mode(Notify) Mode(Restore)
!Mod1<Btn2Down>:       Mode(Save) Mode(Copy) Mode(Notify)
!Mod1<Btn2Up>:         Mode(Notify) Mode(Restore)
Shift BTNMOD<Btn2Down>: Mode(Save) Mode(RubberbandMove) Mode(Notify)
@end example

@findex MovePointer()
@cindex pointer, moving of
@cindex cursor movements
@item MovePointer(delta_x, delta_y)
With this function it is possible to move the cross hair cursor by using the
cursor keys. The @code{X} server's pointer follows because the necessary
events are generated by @pcb{}. All movements are performed with respect
to the currently set grid value.
Default:
@example
None<Key>Up:      MovePointer(0, -1)
!Shift<Key>Up:    MovePointer(0, -10)
None<Key>Down:    MovePointer(0, 1)
!Shift<Key>Down:  MovePointer(0, 10)
None<Key>Right:   MovePointer(1, 0)
!Shift<Key>Right: MovePointer(10, 0)
None<Key>Left:    MovePointer(-1, 0)
!Shift<Key>Left:  MovePointer(-10, 0)
@end example

@findex MoveToCurrentLayer()
@cindex objects, moving to current layer
@cindex moving objects to current layer
@item MoveToCurrentLayer(Object|SelectedObjects)
The function moves a single object at the cross hair location or all selected
objects to the current layer. Elements are not movable by this function.
They have to be deleted and replaced on the other side.
If a line segment is moved and the movement would result in a loss of
connectivity to another segment then via(s) are automatically added to
maintain the connectivity.
@example
None<Key>m:       MoveToCurrentLayer(Object)
!Shift<Key>m:     MoveToCurrentLayer(SelectedObjects)
@end example

@findex New()
@cindex layout, start a new
@cindex starting a new layout
@item New()
Clear the current layout and starts a new one after entering its name.
Refer to the resource @emph{backup} for more information.
No defaults.

@findex PasteBuffer()
@cindex buffer, selecting a
@cindex pastebuffer, selecting a
@cindex selecting a buffer
@cindex rotating a buffer
@cindex cutting objects
@cindex copying objects
@item PasteBuffer(AddSelected|Clear|1..5)
@itemx PasteBuffer(Rotate, 1..3)
@itemx PasteBuffer(Convert)
This action routine controls and selects the pastebuffer as well as all
cut-and-paste operations. Passing a buffer number selects one in of the
range 1..5. The statusline is updated with the new number.
@emph{Rotate} performs a number of 90 degree counter clockwise rotations
of the buffer contents. @emph{AddSelected} as first argument copies all
selected and visible objects into the buffer. Passing @emph{Clear} removes
all objects from the currently selected buffer. @emph{Convert} causes
the contents of the buffer (lines, arc, vias) to be converted into an
element definition. Refer to @ref{Pastebuffer}
for examples.
Default:
@example
!Ctrl<Key>x:       PasteBuffer(Clear) PasteBuffer(AddSelected)
                   Mode(PasteBuffer)
!Shift Ctrl<Key>x: PasteBuffer(Clear) PasteBuffer(AddSelected)
                   RemoveSelected() Mode(PasteBuffer)
!Mod1<Key>c:       PasteBuffer(Clear) PasteBuffer(AddSelected)
!Mod1<key>x:       PasteBuffer(Clear) PasteBuffer(AddSelected)
                   RemoveSelected()
!Shift<Key>1:      PasteBuffer(1)
!Shift<Key>2:      PasteBuffer(2)
!Shift<Key>3:      PasteBuffer(3)
!Shift<Key>4:      PasteBuffer(4)
!Shift<Key>5:      PasteBuffer(5)
None<Key>F3:       Mode(PasteBuffer)
@end example

@findex Polygon()
@cindex polygon, closing a
@cindex polygon point, go back to previous
@cindex closing a polygon
@item Polygon((Close|PreviousPoint)
Polygons need a special action routine to make life easier. Calling
@emph{Polygon(PreviousPoint)} resets the newly entered corner to the
previous one. The Undo action will call Polygon(PreviousPoint)
when appropriate to do so.  @emph{Close} creates the final
segment of the polygon.  This may fail if clipping to 45 degree
lines is switched on, in which case a warning is issued.
Default:
@example
None<Key>p:             Polygon(Close)
!Shift<Key>p:           Polygon(Close)
@end example

@findex Print()
@cindex layout, printing a
@cindex printing a layout
@item Print()
Pops up a print control box that lets you select the output
device, scaling and many more options. Each run creates all
files that are supported by the selected device. These are
mask files as well as drilling files, silk screens and so on. The table
shows the filenames for all possible files:
@example
        POSIX (extension)             8.3 filename
                ---------------------------------------------
                *_componentmask.*             cmsk.*
                *_componentsilk.*             cslk.*
                *_soldermask.*                smsk.*
                *_soldersilk.*                sslk.*
                *_drill.*                     dril.*
                *_groundplane.*               gpl.*
                *_group[1..8].*     [..8].*
@end example
The output may be sent to a post-processor by starting the filename with the
@emph{pipe} @code{("|")} character. Any @code{"%f"} in a command is replaced
with the current filename. The function is available from the @emph{file} menu.
There are no defaults.

@findex Quit()
@cindex quit
@cindex exit
@item Quit()
Quits the application after confirming the operation.
Default:
@example
<Message>WM_PROTOCOLS: Quit()
@end example

@findex Redo()
@cindex redo
@cindex recover
@item Redo()
This routine allows you to recover from the last undo command.
You might want to do this if you thought that undo was going to
revert something other than what it actually did (in case you
are confused about which operations are un-doable), or if you
have been backing up through a long undo list and over-shoot
your stopping point.  Any change that is made since the undo
in question will trim the redo list.  For example if you add
ten lines, then undo three of them you could use redo to put
them back, but if you move a line on the board before performing
the redo, you will lose the ability to "redo" the three "undone" lines.
Default:
@example
!Shift<Key>r:   Redo()
@end example

@findex RemoveSelected()
@cindex removing selected objects
@cindex selected object, removing an
@item RemoveSelected()
This routine removes all visible and selected objects.
There are no defaults.

@findex Report()
@cindex report
@cindex information about objects
@cindex drill
@item Report(Object|DrillReport)
This routine pops up a dialog box describing the various
characteristics of an object (or piece of an object such as a pad or pin)
in the layout at the cursor position, or a report about all of the
drill holes in the layout.
There are no defaults.

@findex RouteStyle()
@cindex routing style
@cindex size of lines and vias
@item RouteStyle(1|2|3|4)
This routine copies the sizes corresponding to the numbered route style
into the active line thickens, via diameter, and via drill size.
Defaults:
@example
!Ctrl<Key>1: RouteStyle(1)
...
!Ctrl<Key>NUM_STYLES: RouteStyle(NUM_STYLES)
@end example
The variable @code{NUM_STYLES} is set at compile time in
@file{globalconfig.h}.

@findex Save()
@cindex saving files
@cindex saving connections
@item Save(Layout|LayoutAs)
@itemx Save(AllConnections|AllUnusedPins|ElementConnections)
Passing @emph{Layout} saves the layout using the file from which it was
loaded or, if it is a new layout, calls @emph{Save(LayoutAs)} which queries
the user for a filename.
The values: @emph{AllConnections}, @emph{AllUnusedPins} and
@emph{ElementConnections} start a connection scan and save all connections,
all unused pins or the connections of a single element to a file.
There are no defaults.

@findex Select()
@cindex selection
@cindex selecting objects
@item Select(All|Block|Connection|ToggleObject)
@itemx Select(ElementByName|ObjectByName|PadByName|PinByName)
@itemx Select(TextByName|ViaByName)
Toggles either the selection flag of the object at the cross hair position
(@emph{ToggleObject}) or selects all visible objects, all inside a
rectangle or all objects which have been found during the last connection
scan. The @emph{ByName} functions use a @ref{Regular Expressions} search,
always case insensitive, to select the objects.
Default:
@example
None<Btn3Down>:  Select(ToggleObject)
None<Btn3Down>,None<Btn3Motion>: See resource file - this is complex
@end example

@findex SetFlag()
@cindex flags, setting
@cindex octagonal flag, setting
@cindex square flag, setting
@cindex thermal flag, setting
@itemx SetFlag(Object|SelectElements|SelectedPins|SelectedVias|Selected,thermal|octagon|square)
Sets the indicated flag.  This adds thermals, sets the flag
which indicates a pin/pad should be square, or sets the flag which
indicates a pin/pad should be octagonal.
@example
:SetFlag(Selected,thermal)
@end example

@findex SetValue()
@cindex change settings
@cindex zoom, setting of
@cindex grid, setting of
@cindex drilling hole, setting of initial size
@cindex vias, setting of initial size
@cindex lines, setting of initial size
@item SetValue(Grid|LineSize|TextScale|ViaDrillingHole|ViaSize|Zoom, value)
Some internal values may be changed online by this function.
The first parameter specifies which data has to be changed. The other one
determines if the resource is set to the passed value, if @emph{value} is
specified without sign, or increments/decrements if it is specified with
a plus or minus sign.
The function doesn't change any existing object only the initial values of
new objects.  Use the @emph{ChangeSize()} and @emph{ChangeDrillSize()}
to change existing objects.
Default:
@example
None<Key>g:        SetValue(Grid, +5)
!Shift<Key>g:      SetValue(Grid, -5)
None<Key>l:        SetValue(LineSize, +5)
!Shift<Key>l:      SetValue(LineSize, -5)
None<Key>t:        SetValue(TextScale, +10)
!Shift<Key>t:      SetValue(TextScale, -10)
None<Key>v:        SetValue(ViaSize, +5)
!Shift<Key>v:      SetValue(ViaSize, -5)
!Mod1<Key>v:       SetValue(ViaDrillingHole, +5)
!Mod1 Shift<Key>v: SetValue(ViaDrillingHole, -5)
None<Key>z:        SetValue(Zoom, -1)
!Shift<Key>z:      SetValue(Zoom, +1)
@end example

@findex SwapSides()
@cindex change viewing side
@cindex viewing side, changing of
@item SwapSides()
This routine changes the board side you are viewing.
Default:
@example
None<Key>Tab:      SwapSides()
@end example

@findex SwitchDrawingLayer()
@cindex change drawing layer
@cindex layer, change active
@item SwitchDrawingLayer(value)
Makes layer number 1..MAX_LAYER the current one.
Default:
@example
None<Key>1:        SwitchDrawingLayer(1)
...
None<Key>MAX_LAYER:        SwitchDrawingLayer(MAX_LAYER)
@end example

@findex ToggleHideName()
@cindex hide element name
@cindex element name, hiding
@cindex element name, removing from silk-screen
@item ToggleHideName(Object|SelectedElements)
Toggles whether the element's name is displayed or hidden. If it
is hidden you won't see it on the screen and it will not appear
on the silk layer when you print the layout.
@example
None<Key>h:     ToggleHideName(Object)
!Shift<Key>h:   ToggleHideName(SelectedElements)
@end example

@findex ToggleVendor()
@cindex vendor map, toggling
@cindex vendor drill table, toggling
@item ToggleVendor()
Toggles automatic drill size mapping to the loaded vendor drill table.
@example
ToggleVendor()
@end example

@findex ToggleVisibility()
@cindex toggle layer visibility
@cindex layer visibility, toggling
@item ToggleVisibility(Layer)
Toggles the visibility of the layer.
@example
Mod1<Key>1:     ToggleVisibility(1)
Mod1<Key>2:     ToggleVisibility(2)
Mod1<Key>3:     ToggleVisibility(3)
Mod1<Key>4:     ToggleVisibility(4)
@end example

@findex Undo()
@cindex undo
@cindex recover
@item Undo()
@itemx Undo(ClearList)
The unlimited undo feature of @pcb{} allows you to recover
from most operations that materially affect you work.
Calling @emph{Undo()} without any parameter recovers
from the last (non-undo) operation. @emph{ClearList} is used to release the
allocated memory. @emph{ClearList} is called whenever a new layout is started
or loaded. See also @emph{Redo}.
Default:
@example
None<Key>u:        Undo()
!Shift Ctrl<Key>u: Undo(ClearList)
@end example

@findex UnloadVendor()
@cindex vendor map, unloading
@cindex vendor drill table, unloading
@item UnloadVendor()
Unloads the loaded vendor drill table.
@example
UnloadVendor()
@end example

@findex Unselect()
@cindex selection
@cindex unselect objects
@item Unselect(All|Block|Connection)
Unselects all visible objects, all inside a rectangle or all objects which
have been found during the last connection scan.
Default:
@example
!Shift <Btn3Down>: Mode(Save) Mode(None) Unselect(Block)
!Shift <Btn3Up>:   Unselect(Block) Mode(Restore)
@end example

@end table


@node Translations
@section Default Translations
@cindex translations
@cindex default translations
@cindex X11 default translations

This section covers some default translations of key and button events as
defined in the shipped default application resource file. Most of them have
already been listed in @ref{Actions}. @pcb{} makes use of a nice @code{X11}
feature; calling several action routines for one event.

@table @samp

@cindex removing objects
@cindex removing connections
@cindex object, removing an
@cindex connection, removing an
@item  None<Key>BackSpace:
@item  None<key>Delete:
@itemx !Shift<Key>BackSpace:
@itemx !Shift Ctrl<Btn1>:
The object at the cursor location is removed by @emph{None<Key>BackSpace} or
@emph{Shift Ctrl<Btn1>} whereas @emph{Shift<Key>BackSpace} also removes
all other objects that are fully-connected to the one at the cursor location.

@cindex scrolling
@item  !Mod1 Ctrl<Key>Left:
@itemx !Mod1 Ctrl<Key>Right:
@itemx !Mod1 Ctrl<Key>Up:
@itemx !Mod1 Ctrl<Key>Down:
Scroll one page in one of the four directions.

@cindex scrolling
@item  None<Key>Left:, !Shift<Key>Left:
@itemx None<Key>Right:, !Shift<Key>Right:
@itemx None<Key>Up:, !Shift<Key>Up:
@itemx None<Key>Down:, !Shift<Key>Down:
Move cross hair either one or ten points in grid.

@cindex user input
@item None<Key>Return:
Finished user input, selects the 'default' button of dialogs.

@cindex user input
@item None<Key>Escape:
@emph{Mode(Reset)}, aborts user input, selects the 'abort' button of
dialogs or resets all modes.

@cindex element, move name of
@cindex object, move an
@cindex object, copy an
@cindex move an object
@cindex copy an object
@item None<Btn2Down>, Btn2<Motion>, None<Btn2Up>:
@itemx !Mod1<Btn2Down>, Btn2<Motion>, !Mod1<Btn2Up>:
The first sequence moves the object or element name at the cursor location.
The second one copies the objects. Copying isn't available for
element names.

@end table


@c --------------------------- chapter 6 -------------------------------
@node File Formats
@chapter File Formats
@cindex file formats
@cindex ASCII files, format of

All files used by @pcb{} are read from the standard output of a command
or written to the standard input of one as plain seven bit @code{ASCII}. This
makes it possible to use any editor to change the contents of a layout file.
It is the only way for element or font description files to be created.
To do so you'll need to study the example files @file{example/*} and
@file{default_font} which are shipped with @pcb{}.
For an overview refer to @ref{Intro}.

@vindex elementCommand
@vindex fileCommand
@vindex fontCommand
@vindex libraryCommand
@vindex libraryContentsCommand
@vindex saveCommand
The following sections provide the necessary information about the syntax of
the files.
Netlist files are not created by @pcb{}, but it does use them. For information
on the format of a netlist file see the @emph{:rn},
@ref{User Commands}.
The commands described allow you to add almost any additional
functionality you may need. Examples are compressed read and write access as
well as archives. The commands themselves are defined by the resources
@emph{elementCommand}, @emph{fileCommand}, @emph{fontCommand},
@emph{libraryCommand}, @emph{libraryContentsCommand} and @emph{saveCommand}.
Note that the commands are not saved along with the data.
It is considered an advantage to have the layout file contain all necessary
information, independent of any other files.

One thing common to all files is they may include comments, newlines,
and carriage returns at any place except within quoted strings.

@menu
* Pad and Line Representation::
* Layout File::
* Element File::
* Font File::
* Netlist File::
* Library Contents File::
* Library File::
* File Syntax::
* Object Flags::
* PCBFlags::
@end menu



@node Pad and Line Representation
@section Pad and Line Representation
@cindex pad specification
@cindex file formats, pads and lines

Pads and lines (copper traces, silk screen lines, etc) are represented by the
line end points and the aperture used to draw the line.  It is important to 
understand this when creating the pads for a new footprint.  The following figure
illustrates a pad or line which is drawn using a square aperture.  The end
points (X0,Y0), (X1,Y1) specify the center of the aperture.  The size parameter
specifies the size of the aperture.

@center @image{pad,,,Pad Layout,png}

Pads and lines are represented in this way because this is how lines are 
specified in RS-274X (Gerber) files which are used for creating
the masks used in board manufacturing.  In fact, older mask making
equipment created lines in precisely this fashion.  A physical aperture was
used to pass light through onto a photosensitive film.

@node Layout File
@section Layout File Format
@cindex layout files, format of
@cindex format of layout files
@cindex file format, layout data

The layout file describes a complete layout including symbols, vias,
elements and layers with lines, rectangles and text. This is the most
complex file of all.  As @pcb{} has evolved, the file format has
changed several times to accommodate new features.  @pcb{} has
always been able to read all older versions of the @code{.pcb} file.
This allows the migration of older designs to newer versions of the
program.  Obviously older versions of @pcb{} will not be able
to properly read layout files stored in newer versions of the file
format.

In practice it is very common for footprint libraries to contain
elements which have been defined in various versions of the @pcb{}
file format.  When faced with trying to understand an element file or
layout file which includes syntax not defined here, the best approach
is to examine the file @file{src/parse_y.y} which is the definitive
definition of the file format.

The PCB layout file contains the following contents, in this order (individual items
are defined in @ref{File Syntax}:

@table @code

@item PCB
This names the board and sets its size

@item Grid
Optional.

@item Cursor
Optional.

@item Flags
Optional.

@item Groups
Optional.

@item Styles
Optional.

@item Symbols
Optional.

@item Vias, Rats, Layers, and Elements
These may occur in any order, at this point in the file.

@item Netlists
Optional.

@end table

@node Element File
@section Element File Format
@cindex element, file format
@cindex format of element files
@cindex file format, element data

Element files are used to describe one component which then may be used
several times within one or more layouts. You will normally split the
file into two parts, one for the pinout and one for the package description.
Using @code{m4} allows you to define pin names as macros in one file and
include a package description file which evaluates the macros. See
the resource @emph{elementCommand} for more information. The pins (and pads)
must appear in sequential order in the element file (new in 1.5) so that
pin 1 must be the first PIN(...) in the file.

Doing things this way makes it possible to use one package file for several
different circuits. See the sample files @file{dil*}.

The lowest x and y coordinates of all sub-objects of an element are
used as an attachment point for the cross hair cursor of the main
window, unless the element has a mark, in which case that's the
attachment point.



@node Font File
@section Font File Format
@cindex font file, format of
@cindex format of font files
@cindex file format, font data

A number of user defined Symbols are called a font. There is only one per
layout. All symbols are made of lines. See the file @file{default_font}
as an example.

The lowest x and y coordinates of all lines of a font are transformed to (0,0).

@node Netlist File
@section Netlist File Format
@cindex netlist, file format
@cindex netlist, reading

Netlists read by @pcb{} must have this simple text form:

@example
netname [style] NAME-PINNUM NAME2-PINNUM2 NAME3-PINNUM3 ... [\]
@end example

@noindent
for each net on the layout.
where "netname" is the name of the net which must be unique for each
net, [style] is an optional route-style name,
NAME is the layout-name name given to an element,
and PINNUM is the (usually numeric)
pin number of the element that connects to the net
(for details on pin numbering see @ref{Element Objects}).
Spaces or tabs separate the fields.
If the line ends with a "\" the
net continues on the next line and the "\" is treated exactly as if it
were a space.  If a NAME ends with a lower-case letter,
all lower-case letters are stripped from the end of the NAME to determine the
matching layout-name name.  For example:

@example
     Data U1-3 U2abc-4 FLOP1a-7 Uabc3-A9
@end example

specifies that the net called "Data" should have
pin 3 of U1 connected to pin 4 of U2, to pin 7 of
FLOP1 and to pin A9 of Uabc3.  Note that element name and
pin number strings are case-sensitive.
It is up to you to name the elements so that their layout-name names
agrees with the netlist.

@node Library Contents File
@section Library Contents File Format
@cindex library contents file, format of
@cindex format of library contents
@cindex file format, library contents

There is nothing like a special library format. The ones that have been
introduced in 1.4.1 just use some nice (and time consuming) features of GNU
@code{m4}. The only predefined format is the one of the contents file
which is read during startup. It is made up of two basic line types:

@example
menu entry      = "TYPE="name
contents line   = template":"package":"value":"description
name            = String
template        = String
package         = String
value           = String
description     = String
String          = <anything except ":", "\n" and "\r">
@end example

No leading white spaces or comments are allowed in this file. If you need
either one, define a command that removes them before loading. Have a look
to the @emph{libraryContentsCommand} resource.

The menu entry will appear in the selection menu at the top and of the
library window.

@node Library File
@section Library File Format
@cindex library file, format of
@cindex format of libraries
@cindex file format, libraries

This section provides an overview about the existing @code{m4} definitions
of the elements. There are basically two different types of files. One
to define element specific data like the pinout, package and so on, the
other to define the values. For example the static RAM circuits 43256 and
62256 are very similar. They therefore share a common definition in the
macro file but are defined with two different value labels.

The macro file entry:
@example
define(`Description_43256_dil', `SRAM 32Kx8')
define(`Param1_43256_dil', 28)
define(`Param2_43256_dil', 600)
define(`PinList_43256_dil', ``pin1', `pin2', ...')
@end example

And the list file:
@example
43256_dil:N:43256:62256
@end example

The macro must define a description, the pin list and up to two additional
parameters that are passed to the package definitions. The first one is
the number of pins whereas the second one defines for example the width
of a package.

It is very important to select a unique identifier for each macro. In
the example this would be @emph{43256_dil} which is also the templates name.
It is required by some low-level macros that
@emph{Description_, Param1_, Param2_} and @emph{PinList_} are perpended.

The list file uses a syntax:
@example
template:package:value[:more values]
@end example

This means that the shown example will create two element entries with the
same package and pinout but with different names.

A number of packages are defined in @file{common.m4}. Included are:

@example
DIL packages with suffix D, DW, J, JD, JG, N, NT, P
PLCC
TO3
generic connectors
DIN 41.612 connectors
zick-zack (SD suffix)
15 pin multiwatt
@end example

If you are going to start your own library please take care about @code{m4}
functions. Be aware of quoting and so on and, most important check your
additional entry by calling the macro:

@example
CreateObject(`template', `value', `package suffix')
@end example

If quoting is incorrect an endless loop may occur (broken by a out-of-memory
message).

The scripts in the @file{lib} directory handle the creation of libraries
as well as of their contents files. Querying is also supported.

I know quite well that this description of the library implementation is
not what some out there expect. But in my opinion it's much more useful to
look at the comments and follow the macros step by step.

@node File Syntax
@section File Syntax
@cindex File sytax
@cindex Syntax, file

@include pcbfile.texi

@c --------------------------- chapter 7 -------------------------------
@node Library Creation
@chapter Library Creation
@cindex library creation

This chapter provides a detailed look at how footprint libraries are
created and used.  The chapter is split into two section, the first
section covers the "old" style libraries which use the @code{m4} macro
processor and the second section covers the "new" style libraries.

Despite the names "old" and "new", both styles of libraries are useful
and the "old" style should not be discounted because of its name.  The
advantage of the old style libraries is that one can define a family of
footprints, say a DIP package, and then quickly produce all the members
of that family.  Because the individual packages make use of a base
definition, corrections made to the base definition propagate to all the
members of a family.  The primary drawback to using this library
approach is that the effort to create a single footprint is more than a
graphical interface and may take even longer if the user has not used
the @code{m4} macro language previously.

The new style of footprint libraries stores each footprint in its own
file.  The footprints are created graphically by placing pads and then
converting a group of pads to a component.  This library method has the
advantage of being quick to learn and it is easily to build single
footprints quickly.  If you are building a family of parts, however, the
additional effort in creating each one individually makes this approach
undesirable.  In addition, creating a part with a large pin count
can be quite tedious when done by hand.


@section Old Style (m4) Libraries
The old style libraries for pcb use the @code{m4} macro processor to
allow the definition of a family of parts.  There are several files
associated with the old style library.  The file @file{common.m4} is the
top level file associated with the library.  @file{common.m4} defines a
few utility macros which are used by other portions of the library,
and then includes a predefined set of library files (the lines like
@code{include(geda.inc)}).

@subsection Overview of Oldlib Operation
The big picture view of the old style library system is that the library
is simply a collection of macro definitions.  The macros are written in
the @code{m4} macro language.  An example of a macro and what it expands
to is the following.  One of the predefined footprints in the library
which comes with PCB is the @code{PKG_SO8} macro.  Note that all the
footprint macros begin with @code{PKG_}.  For this particular example,
@code{PKG_SO8} is a macro for an 8-pin small outline surface mount
package.  All of the footprint macros take 3 arguments.  The first is the
canonical name of the footprint on the board.  In this case "SO8" is an
appropriate name.  The second argument is the reference designator on
the board such as "U1" or "U23".  The third and final argument is the
value.  For an integrated circuit this is usually the part number such
as "MAX4107" or "78L05" and for a component such as a resistor or
capacitor it is the resistance or capacitance.  The complete call to the
macro in our example is @samp{PKG_SO8(SO8, U1, MAX4107)}.  When
processed by @code{m4} using the macros defined in the PCB library, this
macro expands to
@example
Element(0x00 "SO8" "U1" "MAX4107" 146 50 3 100 0x00)
(
        Pad(10 25 38 25 20 "1" 0x00)
        Pad(10 75 38 75 20 "2" 0x100)
        Pad(10 125 38 125 20 "3" 0x100)
        Pad(10 175 38 175 20 "4" 0x100)
        Pad(214 175 242 175 20 "5" 0x100)
        Pad(214 125 242 125 20 "6" 0x100)
        Pad(214 75 242 75 20 "7" 0x100)
        Pad(214 25 242 25 20 "8" 0x100)
        ElementLine(0 0 151 0 10)
        ElementArc(126 0 25 25 0 180 10)
        ElementLine(101 0 252 0 10)
        ElementLine(252 0 252 200 10)
        ElementLine(252 200 0 200 10)
        ElementLine(0 200 0 0 10)
        Mark(29 25)
)
@end example
which is the actual definition of the footprint that the PCB program
works with.  As a user of PCB the only time you will need or want to run
@code{m4} directly is when you are debugging a new library addition.  In
normal operation, the calls to @code{m4} are made by helper scripts that
come with PCB.

Tools such as @code{gsch2pcb} (used to interface the gEDA schematic
capture program to PCB layout) will call @code{m4} to produce an initial
PCB layout that includes all the components on a schematic.  In
addition, when manually instantiating parts from within PCB, @code{m4}
will be called by PCB's helper scripts to produce the footprints.

@subsection The Library Scripts
There are several scripts that are used for processing the m4
libraries.  This section briefly describes these scripts and details how
they are used by PCB.

@subsubsection Scripts Used During Compilation
The scripts described in this section are used during compilation of
PCB.  They are run automatically by the build system, but are described
here to help document the complete library processing that occurs.
During the build of PCB, the following actions are taken.  The
@code{CreateLibrary.sh} script is run to produce an M4 "frozen file".
This frozen file is simply a partially processed M4 input file which can
be loaded by M4 more quickly than the original input file.

A typical call to @code{CreateLibrary.sh} used during the compilation of
PCB is:
@example
./CreateLibrary.sh -I . pcblib ./common.m4 TTL_74xx_DIL.m4
connector.m4 crystal.m4 generic.m4 genericsmt.m4 gtag.m4
jerry.m4 linear.m4 logic.m4 lsi.m4 memory.m4 optical.m4 pci.m4
resistor_0.25W.m4 resistor_adjust.m4 resistor_array.m4
texas_inst_amplifier.m4 texas_inst_voltage_reg.m4
transistor.m4 geda.m4
@end example
The @samp{-I .} says to search in the current directory for the
@file{.m4} files.  The output frozen file is @file{pcblib}.  The main
@file{common.m4} file is listed as well as all of the @file{*.m4} files
which define the components in the library.

In addition, a library contents file is created during the build with
the @code{CreateLibraryContents.sh} script.
A typical call to @code{CreateLibrary.sh} used during the compilation of
PCB is:
@example
./CreateLibraryContents.sh -I . ./common.m4 TTL_74xx_DIL.list
connector.list crystal.list generic.list genericsmt.list gtag.list
jerry.list linear.list logic.list lsi.list memory.list optical.list
pci.list resistor_0.25W.list resistor_adjust.list resistor_array.list
texas_inst_amplifier.list texas_inst_voltage_reg.list transistor.list
geda.list > pcblib.contents
@end example

The @file{pcblib.contents} file is used by the PCB program to define the
libraries and components which will be displayed when you bring up
the library window from within PCB.  An example of part of the
@file{pcblib.contents} file is:
@example
TYPE=~TTL 74xx DIL
7400_dil:N:7400:4 dual-NAND
7401_dil:N:7401:4 dual-NAND OC
7402_dil:N:7402:4 dual-NOR
TYPE=~geda
geda_DIP6:DIP6:DIP6:Dual in-line package, narrow (300 mil)
geda_DIP8:DIP8:DIP8:Dual in-line package, narrow (300 mil)
geda_DIP14:DIP14:DIP14:Dual in-line package, narrow (300 mil)
geda_ACY300:ACY300:ACY300:Axial non-polar component,
@end example
The @code{TYPE=} lines define the library name that will show up in the
library window in PCB.  The other lines define the actual components in
the library.

@subsubsection Scripts Used by PCB at Runtime
When PCB is first executed, it makes a call to the
@code{ListLibraryContents.sh} script.  This script provides the PCB
program with the contents of the library contents file created when PCB
was compiled.  A typical call to @code{ListLibraryContents.sh} is
@example
../lib/ListLibraryContents.sh .:/tmp/pcb-20030903/src/../lib pcblib
@end example
This command says to search the path
@samp{.:/tmp/pcb-20030903/src/../lib} for a file called
@file{pcblib.contents} (the @file{.contents} part is added
automatically) and display the contents of the file.
PCB parses this output and generates the library window entries.

When you pick a library component from the library window, PCB calls the
@code{QueryLibrary.sh} script to actually pull the footprint into the
layout.  For example, when the ACY300 component is selected from the
@code{~geda} library, the generated call may be:

@example
/tmp/pcb-20030903/src/../lib/QueryLibrary.sh
.:/tmp/pcb-20030903/src/../lib pcblib geda_ACY300 ACY300
ACY300
@end example
If you were to run this command by hand you would see the PCB code for
the element:
@example
Element(0x00 "Axial non-polar component," "" "ACY300" 245 70 0 100 0x00)
(
        Pin(0 25 50 20 "1" 0x101)
        Pin(300 25 50 20 "2" 0x01)

        ElementLine(0 25 75 25 10)
        ElementLine(225 25 300 25 10)

        ElementLine(75 0 225 0 10)
        ElementLine(225 0 225 50 10)
        ElementLine(225 50 75 50 10)
        ElementLine(75 50 75 0 10)

#       ElementArc(X1 Y 50 50 270 180 10)
#       ElementArc(X2 Y 50 50 90 180 10)

        Mark(75 25)
)
@end example

@subsection Creating an Oldlib Footprint
This section provides a complete example of defining a family of
footprints using the M4 style library.  As a vehicle for this example, a
family of footprints for surface mount resistors and capacitors will be
developed.   The file @file{example.inc} should have been installed on
your system as @file{$prefix/share/examples/oldlib/example.inc} where
@file{$prefix} is often times @file{/usr/local}.

The @file{example.inc} file defines a macro called
@code{COMMON_PKG_RCSMT} which is a generic definition for a surface
mount footprint with two identical, rectangular pads.  This macro will
be called with different parameters to fill out the family of parts.
The arguments to the @code{COMMON_PKG_RCSMT} are:
@example
# -------------------------------------------------------------------
# the definition for surface mount resistors and capacitors
# $1: canonical name
# $2: name on PCB
# $3: value
# $4: pad width   (in direction perpendicular to part)
# $5: pad length  (in direction parallel with part)
# $6: pad spacing (center to center)
# $7: distance from edge of pad to silk (in direction
#     perpendicular to part)
# $8: distance from edge of pad to silk (in direction parallel
#     with part)
# $9: Set to "no" to skip silk screen on the sides of the part
@end example

@example
define(`COMMON_PKG_RCSMT',
        `define(`XMIN', `eval( -1*`$6'/2 - `$5'/2 - `$8')')
        define(`XMAX', `eval(  `$6'/2 + `$5'/2 + `$8')')
        define(`YMIN', `eval(-1*`$4'/2 - `$7')')
        define(`YMAX', `eval(   `$4'/2 + `$7')')
Element(0x00 "$1" "$2" "$3" eval(XMIN+20) eval(YMAX+20) 0 100 0x00)
(
        ifelse(0, eval($4>$5),
        # Pads which have the perpendicular pad dimension less
        # than or equal to the parallel pad dimension
        Pad(eval(-1*(   $6 + $5 - $4)/2) 0
            eval((-1*$6 + $5 - $4)/2) 0 eval($4) "1" 0x100)
        Pad(eval(-1*(-1*$6 + $5 - $4)/2) 0
            eval((   $6 + $5 - $4)/2) 0 eval($4) "2" 0x100)
        ,
        # Pads which have the perpendicular pad dimension greater
        # than or equal to the parallel pad dimension
        Pad(eval(-1*$6/2) eval(-1*($4 - $5)/2)
            eval(-1*$6/2)  eval(($4 - $5)/2) eval($5) "1" 0x100)
        Pad(eval(   $6/2) eval(-1*($4 - $5)/2)
            eval(   $6/2)  eval(($4 - $5)/2) eval($5) "2" 0x100)
        )

        # silk screen
        # ends
        ElementLine(XMIN YMIN XMIN YMAX 10)
        ElementLine(XMAX YMAX XMAX YMIN 10)
        # sides
ifelse($9,"no",
        #skip side silk
        ,
        ElementLine(XMIN YMIN XMAX YMIN 10)
        ElementLine(XMAX YMAX XMIN YMAX 10)
)
        Mark(0 0)
)')
@end example
Note that the part has been defined with the mark located at
@code{(0,0)} and that the pads have been placed with the mark at the
common centroid of the footprint.  While not a requirement, this is
highly desirable when developing a library that will need to interface
with a pick and place machine used for factory assembly of a board.

The final part of @file{example.inc} defines particular versions of the
generic footprint we have created.  These particular versions correspond
to various industry standard package sizes.
@example
# 0402 package
#
# 30x30 mil pad, 15 mil metal-metal spacing=>
# 15 + 15 + 15 = 45 center-to-center
define(`PKG_RC0402',
  `COMMON_PKG_RCSMT(`$1', `$2', `$3', 30, 30, 45, 0, 10, "no")')

# 0603 package
#
# 40x40 mil pad, 30 mil metal-metal spacing=>
#  30 + 20 + 20 = 70 center-to-center
define(`PKG_RC0603',
  `COMMON_PKG_RCSMT(`$1', `$2', `$3', 40, 40, 70, 10, 10)')

# 1206 package
#
# 40x60 mil pad, 90 mil metal-metal spacing=>
#  90 + 20 + 20 = 130 center-to-center
define(`PKG_RC1206',
  `COMMON_PKG_RCSMT(`$1', `$2', `$3', 60, 40, 130, 10, 10)')
@end example

At this point, the @file{example.inc} file could be used by third party
tools such as @code{gsch2pcb}.  However to fully integrate our
footprints into PCB we need to create the @file{example.m4} and
@file{example.list} files.  The @file{example.m4} file defines
descriptions for the new footprints.
@example
define(`Description_my_RC0402',
  ``Standard SMT resistor/capacitor (0402)'')
define(`Description_my_RC0603',
  ``Standard SMT resistor/capacitor (0603)'')
define(`Description_my_RC1206',
  ``Standard SMT resistor/capacitor (1206)'')
@end example
Finally we need to create the @file{example.list} file.
@example
my_RC0402:RC0402:RES0402
my_RC0402:RC0402:CAP0402
my_RC0603:RC0603:RES0603
my_RC0603:RC0603:CAP0603
my_RC1206:RC1206:RES1206
my_RC1206:RC1206:CAP1206
@end example
The first field in the list file has the name corresponding to the
Description definitions in @file{example.m4}.  The second field is the
template name which corresponds to the macros @code{PKG_*} we defined in
@file{example.inc} with the leading @code{PKG_} removed.  It is the
second field which controls what footprint will actually appear on the
board.  The final
field is the name of the part type on the board.  The first line in our
@file{example.list} file will produce a menu entry in the library window
that reads:
@example
CAP0402, Standard SMT resistor/capacitor (0402)
@end example
The @code{CAP0402} portion comes directly from the third field in
@code{example.list} and the longer description comes from descriptions
macros in @code{example.m4}.  Please note that any extra white space
at the end of a line in the @file{.list} files will cause them to
not work properly.

@subsection Troubleshooting Old Style Libraries

A powerful technique to help debug problems with libraries is to invoke
the @code{m4} processor directly.  This approach will provide error
output which is not visible from within PCB.  The following example
shows how one might try to debug an 8 pin small outline (SO8) package.  The
macro name for the package is PKG_SO8.  In this example, the
canonical name that is to be associated with the part is SO8, the
reference designator is U1, and the value is MAX4107 (the part number).

@example
echo "PKG_SO8(SO8, U1, MAX4107)" | \
   gm4 common.m4 - | \
   awk '/^[ \t]*$/ @{next@} @{print@}' | \
   more
@end example
The @code{awk} call simply removes blank lines which make the output
hard to read.

For this particular example, the output is:
@example
Element(0x00 "SO8" "U1" "MAX4107" 146 50 3 100 0x00)
(
        Pad(10 25 38 25 20 "1" 0x00)
        Pad(10 75 38 75 20 "2" 0x100)
        Pad(10 125 38 125 20 "3" 0x100)
        Pad(10 175 38 175 20 "4" 0x100)
        Pad(214 175 242 175 20 "5" 0x100)
        Pad(214 125 242 125 20 "6" 0x100)
        Pad(214 75 242 75 20 "7" 0x100)
        Pad(214 25 242 25 20 "8" 0x100)
        ElementLine(0 0 151 0 10)
        ElementArc(126 0 25 25 0 180 10)
        ElementLine(101 0 252 0 10)
        ElementLine(252 0 252 200 10)
        ElementLine(252 200 0 200 10)
        ElementLine(0 200 0 0 10)
        Mark(29 25)
)
@end example

@section New Style Libraries
Footprints for the new style library are created graphically using the
PCB program.  A single footprint is saved in each file.

@subsection Creating Newlib Footprints
To create
@enumerate
@item Start PCB with an empty layout.
@item Make the component layer active.
@item For a leaded part, select the via tool and place vias where the
pads for the part should go.  For surface mount pads, draw line
segments.  Note that until the footprint is completed, the surface
mount pads will remain rounded.  Currently a rectangle or polygon
may not be used as a pad.
@item For each via and line segment which will become a pad, select it
and press 'n' to be able to enter a name.  Enter
the pin number and press enter.
@item Make the silk layer active.
@item Using the line and arc tools, draw a silk screen outline for the
part.
@item Using the selection tool, select all of the pins and silk screen
for the part.
@item Place the pointer above the reference point for the part.  This is
typically the common centroid.  Keeping the pointer there, shift-right-click
to bring up the popup menu and choose "convert
selection to element".
@item At this point, the vias, line segments, and silk screen will have
been converted to an element.  To change any of the line segments to
have square ends rather than round ends, select the pads by holding
down the shift key and clicking each pad with the center mouse button.
Now under the Select menu, "Change square-flag of selected objects"
section, choose "Pins".
@item Select the element, shift-right-click to bring up the popup menu, and
choose "Copy Selection to Buffer".  Now left-click on the center of 
the new element.
@item Under the buffer menu, choose "save buffer elements to file" to
save the new footprint to a file.
@item Press ESC to exit from buffer mode.
@end enumerate

@subsection Modifying Newlib Footprints
@enumerate
@item In the @pcb{} program, instantiate the footprint you wish to modify.
@item Using the selection tool, select the footprint.
@item Now left-click on the selected element, this brings up a popup menu, choose
"Cut Selection to Buffer" from the popup menu.
@item Under the buffer menu, choose "break buffer element to pieces",
and then left-click to place the broken apart footprint to an open area of
the layout.  Note that you must use the items under the buffer menu, the
items with the same names in the popup menu do not work.
@item Make your desired modifications to the footprint and then convert
the pieces back to an element using the same procedure as when starting
from scratch on a new footprint.
@end enumerate


@c --------------------------- chapter 8 -------------------------------
@node Schematic Frontends
@chapter Schematic Capture for PCB
@cindex schematic capture
@cindex schematic frontend

When designing a circuit board of any complexity, a schematic capture
front-end for the design is highly desired.  Any schematic capture
program which is able to generate a netlist in a user defined format as
well as a bill of materials can be made to work with PCB.  Currently, we
are aware of two freely available schematic capture programs which can
interface with PCB.  This chapter shows how a design can be taken from
start to finish using either of these two tools for schematic capture
and PCB for layout.

@menu
* gEDA::          Interfacing with GNU EDA (gEDA).
* xcircuit::      Interfacing with xcircuit.
@end menu

@node gEDA
@section gEDA
@cindex gschem, how to interface with
@cindex gEDA, how to interface with

This section shows how to use gEDA as the schematic capture front-end for
a PCB design.  This section is not intended to be complete documentation
on gEDA and it is assumed that the user has at least some familiarity
with the gEDA suite of programs.

The basic steps in a gEDA + PCB design flow are:
@enumerate
@item Set up project directories
@item Set up gEDA (gschem/gnetlist) config files
@item Set up gsch2pcb config files
@item Capture schematics using @code{gschem} (part of gEDA)
@item Create any unique PCB footprints needed for the design
@item Generate initial PCB design using @code{gsch2pcb} (part of gEDA)
@item Layout circuit board using @code{pcb}
@item Make any additional schematic changes with @code{gschem} and
forward annotate to PCB with @code{gsch2pcb}
@item Generate photoplot files (RS-274X, also known as "Gerber") for
board vendor
@end enumerate

@subsection Set Up Project Directories
Although not required, a typical project directory will contain the
schematics and board layout at the top level.
Schematic symbols and circuit board footprints which are unique to this
project are stored in subdirectories.  For this example, @file{sym}
contains the project specific schematic symbols and @file{pkg} contains
the project specific footprints.  Set up the project subdirectory and
subdirectories by executing:
@example
mkdir ~/myproj
cd ~/myproj
mkdir sym
mkdir pkg
mkdir pkg/newlib
mkdir pkg/m4
@end example

@subsection Set Up gEDA Config Files
The gEDA tools, specifically @code{gschem} and @code{gnetlist}, use
configuration files to set the search path for symbol libraries in
addition to other user preferences.  Create a file in the top level
project directory called @file{gschemrc}.  Add the following lines to
that file:
@example

;; list libraries here.  Order matters as it sets the
;; search order
(component-library "./sym")

@end example
This sets the local search path for the schematic capture program
@code{gschem}.  Now the netlister, @code{gnetlist}, must also be
configured.  This can be done by copying the file @file{gschemrc} to
@file{gnetlistrc} by running @samp{cp gschemrc gnetlistrc}.
Alternatively, you can create a soft link so only a single file needs to
be updated if additional symbol paths are added.  The link is created by
running @samp{ln -s gschemrc gnetlistrc}.

@subsection Set Up @code{gsch2pcb} Config Files
The program @code{gsch2pcb}, not to be confused with the older
@code{gschem2pcb} script, is used to link the schematic to layout.
@code{gsch2pcb} is responsible for creating the netlist used to provide
connectivity information to PCB as well creating an initial layout with
all components instantiated in the design.  Forward annotation of
schematic changes to the layout is also done using @code{gsch2pcb}.
@code{gsch2pcb} uses a project file to set up the schematic file names,
PCB library locations, and output file names.  Create a project file
called @file{project} using the following as an example:
@example

# List all the schematics to be netlisted
# and laid out on the pc board.
schematics      first.sch second.sch third.sch

# For an output-name of foo, gsch2pcb generates files
# foo.net, foo.pcb, and foo.new.pcb.  If there is no
# output-name specified, the file names are derived from
# the first listed schematic, i.e. first.net, etc.
output-name  preamp

@end example


@subsection Capture Schematics Using @code{gschem}
This section is fairly brief and assumes familiarity with using the
@code{gschem} schematic capture program.  As you are creating your
schematics, be sure to observe the following rules:
@itemize
@item Make sure that each component in the schematic has a
@code{footprint} attribute that corresponds to a footprint in the PCB
library or a footprint you plan on creating.
@item Make sure all reference designators are unique.  One way to ensure
this is to run the @code{refdes_renum} script (part of gEDA) after the
schematics are created.
@end itemize

@subsection Create Any Unique PCB Footprints
Create the new footprints you design needs using either the m4 style or
newlib style of PCB libraries.  Refer to @ref{Library Creation} for details on this
process.  For m4 style footprints, store them in the @file{pkg/m4}
subdirectory and for newlib footprints, store them in the
@file{pkg/newlib} subdirectory.

@subsection Generate Initial PCB Design Using @code{gsch2pcb}
The @code{gsch2pcb} program connects the schematic and layout.  It basic
operation is to call @code{gnetlist} to generate the connectivity
netlist that PCB used to verify connectivity and to instantiate all
elements found in the schematic to a new layout.
The default, as of @code{gsch2pcb} version 0.9,  is to use any found  m4
style parts first and then search for newlib style if no old style part
was found.  By using the @code{--use-files} or @code{-f} flag to @code{gsch2pcb}
priority is given to newlib style parts even if m4 style are found.  You
may wish to verify this in the @code{gsch2pcb} documentation in case
this changes in the future.
To start your layout,
run @samp{gsch2pcb project} where @file{project} is the project file
created previously.  This will create a new netlist file,
@file{preamp.net}, and a new layout file, @file{preamp.pcb}.


@subsection Layout Circuit Board
Run PCB on the new layout by running @samp{pcb preamp.pcb}.
Load the netlist file by selecting "load netlist file" from the "file"
menu.  In the file selection dialog box, choose @file{preamp.net}.  This
loads connectivity information into PCB.

Using the selection tool, grab and move apart the various footprints
with the middle mouse button.  Once the parts are moved apart from each
other, choose "optimize rats-nest" from the "Connects" menu.  This menu
choice will display and optimize the rats nest.  Use the rats nest to
help guide placement of the parts.  You may wish to re-run the "optimize
rats-nest" command after moving parts around.

After the placement is complete, use the line tool to add traces to the
board.  As traces are added, the corresponding rats line will disappear.

@subsection Forward Annotation of Schematic Changes
If schematic changes are made after the layout has started,
@code{gsch2pcb} can be used to forward annotate these changes to the
layout.  To forward annotate schematic changes, run @samp{gsch2pcb
project}.  This command will create the files @file{preamp.new.pcb},
@file{preamp.net}, and modify the file @file{preamp.pcb}.  The
modifications to @file{preamp.pcb} include forward annotation of
schematic component value changes, adds any new components, and removes
any deleted components.

@subsection Generate Photoplot Files (RS-274X)
After the layout is complete, choose "edit layer-groupings" from the
"Settings" menu.  The LayerGroups form lets you specify which layers
will appear in each output layer group.  For example, in the default
form, layer group 1 has "front" and "front side" in it.  The
output file @file{1.gbr} if DOS file names are used, or
@file{somename_front.gbr} if long file names are used will contain the
"front" and "front side" layers in it.  Usually the defaults are
sufficient, but this form is still a useful reference.

Choose "print layout..." from the "File" menu.  In the print dialog box,
select "Gerber/RS-274X" for the device
driver.  Select the "outline", "alignment", and "drillhelper" options.
To get DOS compatible file names, select the "DOS (8.3) names" option,
otherwise enter "preamp" for the filename.  Press "OK".

The following output files should have been created in the project directory.
The names in parentheses correspond to the DOS compatible output file names.
@table @file
@item preamp_frontsilk.gbr (csilk.gbr)
Top side silk screen.
@item preamp_frontmask.gbr (cmask.gbr)
Top side soldermask relief.
@item preamp_front.gbr (1.gbr)
Top copper.
@item preamp_backmask.gbr (smask.gbr)
Bottom side soldermask relief.
@item preamp_back.gbr (2.gbr)
Bottom Copper.
@item preamp_fab.gbr (fab.gbr)
Fabrication drawing.  Also known as the drill drawing.  This drawing is
used for reference by the board vendor but is not directly used in the
fabrication process.
@item preamp_plated-drill.cnc (pdrill.cnc)
NC Drill format file for the plated through holes.
@item preamp_unplated-drill.cnc (udrill.cnc)
NC Drill format file for the unplated through holes.
@item preamp_bom.txt (bom.txt)
A bill of materials for the layout.
@item preamp_xy.txt (xy.txt)
Centroid (X-Y) data for driving automated assembly equipment.
@end table

@comment to include an image:
@comment @image{geda1, 6in, 4in, geda schematic, png}

@node xcircuit
@section xcircuit
@cindex xcircuit, how to interface with
@cindex xcircuit, how to interface with

If anyone cares to contribute this section, it will get added.  Please
submit changes to the bug tracking system for PCB which can be found from
the PCB homepage at @url{http://pcb.gpleda.org}.

@c --------------------------- Appendix A -------------------------------

@node Installation
@appendix Installation and Troubleshooting

Compiling and installing the package should be straightforward. If any problems
occur, please contact the author @email{Thomas.Nau@@rz.uni-ulm.de}, or the
current maintainer @email{haceaton@@aplcomm.jhuapl.edu} to find
a solution and include it into the next release.

@menu
* compiling::     Compiling and installing.
* problems::      Troubleshooting.
@end menu


@node compiling
@section Compiling and Installing
@cindex install, how to
@cindex compile, how to

This section covers the steps which are necessary to compile the package.

@menu
* quickstart::                 Quick start.
* running configure::          Customizing Pcb with Configure
@end menu

@node quickstart
@subsection Quick Start
@cindex GNU build system

Starting with version 2.0, @pcb{} has switched to a GNU
autoconf/automake build system.  Installation of @pcb{} consists of
three steps:  configuration, building, and installing.
In a typical installation, these steps are as simple as
@example
./configure
make
make install
@end example

@node running configure
@subsection Running the configure Script
@cindex GNU configure script
@cindex configure

The @code{configure} script accepts all of the standard GNU configure
options.  For a complete list of configuration options, run
@code{./configure --help}.


@table @samp
@vindex INFOLIBDIR
@item INFOLIBDIR
must be set to the directory where your GNU info files are located.

@vindex PCBLIBDIR
@item PCBLIBDIR
is the path of a directory where the font files will be installed.

@vindex DEFAULTFONT
@item DEFAULTFONT
the name of the default font file.

@vindex DEFAULTLIBRARY
@item DEFAULTLIBRARY
the name of the default library.

@vindex GNUM4
@item GNUM4
the name of GNUs m4 version.

@vindex BTNMOD
@item BTNMOD
If your window manager has already bound @emph{Mod1} together with some
function keys you may want to change this setting. This is true for HP-VUE.


@end table

If you find things which must be changed to compile on your system,
please add the appropriate autoconf tests (if you are familiar with
that) and mail a copy to the maintainer, harry eaton,  at
@email{haceaton@@aplcomm.jhuapl.edu}.


If you do not have the appropriate permissions you should run
@file{./pcbtest.sh} in the @file{src} directory to run @pcb{} from
the installation directory.


@node problems
@section Troubleshooting
@cindex problems
@cindex troubleshooting

There are some known problems. Most of them are related to
missing parts of a standard @code{X11} distribution. Some others are caused by
third party applications such as @code{X} servers. To make this list more
complete please mail your problems and, if available, solutions to the author.
The mail address may be found at the beginning of this chapter.
In any case, read @ref{X11}.

By the way, you @code{MUST HAVE AN ANSI COMPILER} to make @pcb{} work.


Another source of problems are older versions of @code{flex} and @code{bison}.
@pcb{} definitely works with @code{flex-2.4.7} and @code{bison-1.22} or
later. The problems will result in a @emph{syntax error} while parsing files.
This should only be a problem if you have modified the @code{flex} or
@code{bison} input files.

The following list gives you just an idea because I'm not able to test
all @pcb{} releases on all platforms.

@menu
* HP::              Hewlett-Packard series 700 and 800 running HP-UX 10.*
* Sun::             Sun, Solaris 2.5
* SGI::             SGI, IRIX 5.3 and 6.*
* DEC Alpha::       DEC Alpha, DEC UNIX 3.2c and 4.0
* SCO::             SCO Unix ODT 3.0, PC hardware
* Linux::           Linux 0.99pl14 and later
* BSD::             FreeBSD, NetBSD ...
* X11::             Refers to @code{X11R4}, @code{X11R5}, and @code{OpenWindows}
* TeX and Manuals:: Problems creating the @file{pcb.dvi}
@end menu

@node HP
@subsection HP Series 700 and 800
@cindex architecture
@cindex HP
@cindex Hewlett Packard

You have to install several @code{X11} include files
or, better, install a complete @code{X11R5} release. Hewlett-Packard doesn't
support the Athena Widgets. So the header files and libraries are missing
from the application media, but they are available as a patch.
They also do not ship the @code{ANSI} compiler with the normal operating
system release so you have to buy one or use @code{GCC}.
Some of the tools are available as patches.

In addition, @pcb{} has been successfully tested on these platforms with
@code{HPUX 9.*, 10.*} running self-compiled @code{X11R5}.


@node Sun
@subsection Sun SPARC architecture
@cindex architecture
@cindex Sun
@cindex Solaris
@cindex OpenWindows

There are no known problems with Sun machines if they use @code{X11R5} instead
of @code{OpenWindows}. @pcb{} compiled successfully with all kinds of
SPARCstations @code{Solaris-2.[345]}.

For problems with @code{OpenWindows} refer to @ref{X11}.

@node SGI
@subsection Silicon Graphics
@cindex architecture
@cindex Silicon Graphics
@cindex SGI

@pcb{} has been tested on some boxes running either @code{IRIX-4.0.5} or
@code{IRIX-5.3}. The former one uses a @code{X11R4} server.
There are no problems.
For known problems
with @code{X11R4}, see @ref{X11}.


@node DEC Alpha
@subsection DEC Alpha
@cindex architecture
@cindex DEC
@cindex Alpha

@pcb{} compiled and runs without problems on @code{DEC UNIX V3.2c}.


@node SCO
@subsection SCO Unix
@cindex architecture
@cindex SCO
@cindex PC UNIX

John DuBois <spcecdt@@deeptht.armory.com> wrote:
@example
@code{SCO-ODT-3.0} requires the latest version of tls003, the Athena
widget library (available from sosco.sco.com). The main problems
I have encountered are it core dumps fairly often, especially
while loading/dropping elements...
@end example
I'll see what I am able to do as soon as I have access to an @code{SCO} system.


@node Linux
@subsection Linux
@cindex architecture
@cindex Linux
@cindex PC UNIX

Since the @code{X11} version of @pcb{} has been developed on a Linux
system here are no known problems.


@node BSD
@subsection FreeBSD and NetBSD
@cindex FreeBSD
@cindex NetBSD
@cindex PC UNIX

@pcb{} has been tested on NetBSD and works without any problems.
You may also be able to find a NetBSD package at
@url{ftp://ftp.netbsd.org/pub/NetBSD/packages/cad/pcb/README.html} or a
FreeBSD port at
@url{http://www.freebsd.org/cgi/url.cgi?ports/cad/pcb/pkg-descr}.

@node X11
@subsection Problems related to X11
@cindex X11, problems

There are a some problems related to @code{X11R4} or systems derived from
@code{X11} such as @code{OpenWindows}. @xref{Sun}. You at least have to change
all occurances of @emph{baseTranslations} in the resource files to
@emph{translations} if you are using a @code{X11R4} server. Look at the
@code{X11R5} @emph{Intrinsics} manual for details.

The panner widget (print dialog box) appears only in release @code{X11R5} and
later. It really simplifies adjusting the offsets.
With earlier releases the printout will always appear in the center of the
page.

You may have some problems in a mixed @code{X11-OpenWindows}
environment.

@pcb{} has been tested successfully with @code{X11R6} under Linux 1.1.59
and later.


@node TeX and Manuals
@subsection Problems related to TeX
@cindex TeX, problems

If your @code{TeX} installation complains about a missing @file{texinfo.tex}
file copy the one included in this release (directory @file{doc}
to your @code{TeX} macro directory.
Note, there are probably newer versions of this file available from some
FTP sites.
@code{TeX-3.0} failed, @code{TeX-3.14} worked just fine. Check our FTP server
@emph{ftp.uni-ulm.de} for ready-to-print versions of the manuals.


@c --------------------------- Appendix B -------------------------------

@node Custom Menus
@appendix Customizing the Menus

The menu system is driven off a data file that contains
@dfn{resources}.  A resource is a hierarchical description of a data
tree which, in this case, is mapped to the hierarchical menus used by
Pcb.

@menu
* Resource Syntax::          What a resource file looks like.
* Menu Definitions::         Using a resource to define a menu.
* Menu Files and Defaults::  Where Pcb looks for its menu resource.
@end menu

@node Resource Syntax
@section Resource Syntax

A resource file is a simple text file.  It contains curly braces to
group things, spaces between things, and double quotes when strings
need to include spaces.  There are four fundamental ways of adding
data to a resource.

First, a string (either a single word or a quoted string with spaces,
we call both ``strings'' in this appendix) can be added all by itself,
to add a string resource to the current resource.  This is used, for
example, to define the string printed on a menu button.  In this
example, four strings are added to the @var{File} resource:

@example
File = @{
  Sample
  "longer sample"
  some text
@}
@end example

Second, a named string may be added by giving two strings separated by
an equals sign.  This is used to specify X resources and a few other
optional parameters of menus, for example.  Note that a string all by
itself is thus an ``unnamed'' string.

@example
@{"Layer groups" foreground=red sensitive=false@}
@end example

Third, an unnamed subresource may be added.  This is used to create
submenus and menu buttons.  To add a subresource, simply group other
things in curly braces.  This example describes a resource containing
one string and three subresources:

@example
@{File
  @{New do_new()@}
  @{Save do_save()@}
  @{Quit do_quit()@}
@}
@end example

Lastly, a named subresource may be added by prefixing an unnamed
subresource with a string and an equals sign, just as when naming
strings.  This syntax is used to name the resources used for the main
menu and popup menus:

@example
MainMenu = @{
  @dots{}
  @}
@end example

Additionally, the menu parser allows for ``hooks'' whereby portions of
the menu system can be programmatically created at runtime by the
application.  These hooks are invoked by a single word proceeded by an
at sign, such as this example where most of the Sizes menu is created
automatically:

@example
@{Sizes
    @@sizes
    @{"Adjust active sizes ..." AdjustStyle(0)@}
    @}
@end example

In addition to all that, any unquoted pound sign (@code{#}) begins a
comment.  Commented text continues until the end of the containing
line.  Comments may begin at the beginning of a line, or after other
text on the line:

@example
# This is a comment
MainMenu = @{ # This is also a comment
@end example

@node Menu Definitions
@section Menu Definitions

To best understand this section, you should find the
@file{pcb-menu.res} file that your Pcb uses and refer to it for
examples (@pxref{Menu Files and Defaults}).  Note that the lesstif
GUI uses @file{pcb-menu.res} and the GTK+ GUI uses @file{gpcb-menu.res}.
The file format is identical however and if so desired, one can make
one file be a soft link to the other.

A resource defines a menu when it meets certain semantic requirements.
The menu hierarchy is reflected as a hierarchy of unnamed
subresources, with the first string of each subresource defining the
label used for the menu button.  A subresource that itself contains
subresources becomes a submenu, a subresource that does not becomes a
button.

A submenu should only contain subresources for the buttons or submenus
within that submenu.  Two exceptions are allowed: an initial string
sets the label, and the string ``-'' (a single dash) will create a
separator.

A button should not contain subresources, but will contain many
strings, named and unnamed.  The first member shall be an unnamed
string which is the label for the button.  Any other unnamed strings
within the button's resource will be used as actions (much like the
.Xdefaults action strings), which are functions that will be called
when the button is pressed (or popped up, or created, depending on the
action).  As a convenience, if a left parenthesis is seen, the current
``word'' will continue at least until the matching right parenthesis.
This allows you to pass strings with spaces as arguments to actions
without needing to quote the action.

Named resources in button resources will be used as X resources.  Such
resources can be used to set the font, color, and spacing of buttons.
As a convenience, ``fg'' can be used as an abbreviation for ``foreground''.

Within the menu's resource file, Pcb will look for a few key named
subresources.  At the moment, the only one it looks for is one called
@code{MainMenu}.  This will be used for the main menu bar.  In the
future, other named subresources will be used for popup resources.

Given all this, a small sample @file{pcb-menu.res} would be:

@example
MainMenu = @{
  @{File
    @{"Load layout" Load(Layout)@}
    -
    @{"Quit Program" Quit() fg=red font=10x20@}
  @}
@}
@end example

Within the Pcb sources are specially crafted comments that mark all
the actions, flags, menu hooks, and whatnot that Pcb offers.  Read the
file @file{src/gather-actions} in the Pcb source tree for
documentation for these comments.

@node Menu Files and Defaults
@section Menu Files and Defaults

Pcb will look for a file which defines its menus, trying the following
names (the example is for the lesstif GUI, the GTK+ GUI has ``gpcb-menu.res''
in place of ``pcb-menu.res''):

@example
./pcb-menu.res
$HOME/.pcb-menu.res
$PCBLIBDIR/pcb-menu.res
<internal>
@end example

Note that @var{pcblibdir} defaults to @file{/usr/local/share/pcb}
(hence, @file{/usr/local/share/pcb/pcb-menu.res}).  The
@file{<internal>} entry refers to a menu definition within the Pcb
application itself.  The master file for all this is the file
@file{src/pcb-menu.res} in the Pcb source tree.  This master source is
used to create the internal menu definition as well as being installed
in @file{$pcblibdir}.

@c --------------------------- Appendix C -------------------------------
@node Regular Expressions
@appendix Element Search/Regular Expressions
@cindex Element Search
@cindex Regular Expressions
@vindex Element Search
@vindex Regular Expressions

@section Element Search/Regular Expressions
@pcb{}'s search is based on POSIX 1003.2 Regular Expressions.  Full POSIX
Regular Expressions are supported by @pcb{} if the regex library was
available when @pcb{} was built.  One difference from the regular
expressions found in tools like awk or grep is that PCB implicitly
adds a ``^'' to the begining of a regular expression and ``$'' to the
end of the regular expression.  For example, if you enter ``C1'', the
actual regular expression used internally is ``^C1$''.  Another difference
is that search patterns in pcb are not case sensitive. That is, ``CON'' is
treated the same as ``con''.

It is easier to show by example how to search than explain
POSIX 1003.2.  With regular expressions most characters are just
themselves, but some are special:

@table @samp
@item *
Matches 0 or more instances of preceding character.

@item +
Matches 1 or more instances of preceding character.

@item ?
Matches 0 or 1 instances of preceding character.

@item .
Matches any single character other than the newline character.

@item |
The vertical bar is the alternation operator. It combines two
regular expressions. The result matches if either of them matches.

@item \
A backslash indicates the next character should not be interpreted literally
if it normally is, and should be interpreted literally if it normally isn't.

@item @{n@}
An integer n enclosed in curly brackets matches the preceding item if
it occurs exactly n times.

@item [ ]
A pair of square brackets matches every character they contain.  Characters
may be given explicitly, or as ranges.

@item -
A hyphen in the context of square brackets denotes the range between the
preceding and the following character.  E.g., the range of digits is
``0-9'' .  The range of letters from C to K is ``C-K'' .

@item \^ inside square brackets
Inside square brackets the caret is an anti operator. Its presence makes
the square prackets match anything except the contents of the brackets.

@item ( )
Round parenthesis group parts of a regular expression. This is very much
like they do in math formulars.

@end table

If you need a special character literally, you can escape it with a
backslash.

The following examples illustrate how regular expressions can be used to
specify element names (reference designators) to search for.
@table @samp

@item C5
Select the element whose name is exactly ``C5''.

@item C5 | R3
Select C5 and R3.

@item C.*
Select all elements whose name start with the letter ``C'', such as C5, or
C42, or CF1.

@item C.*1
Select all elements that start with ``C'' and end with ``1'', such as C1,
or C51 or C5/9B71.

@item R10?
Search for R1 or R10, but will not select R100 or R105. The question mark
is a quantifier for the character ``0''.

@item R128+
Selects R128, R1288, R12888, etc.

@item TB.
Select all terminal blocks having exactly one character designator after
``TB'' such as TB1, TBA, or TBx but not TB.

@item TB..
Select all terminal blocks having a two character designator such as TB21 or
TB1a.

@item TB.*
Select all terminal blocks with any designator.

@item .*31
Select all items, whose name ends with ``31'' such as Q31, or R31, or R531.

@item Q[12]
Select Q1 and Q2.

@item [A-D].*
Select all items, whose name starts with ``A'', ``B'', ``C'', or ``D''.

@item .*N@{2@}.*
Select all items, whose name contains two ``N'' in a row such as
CONN23, or connA, but not CON5

@item [^D].*
Select all items that do not start with the letter ``D'', such as C2, or
R34, but not D34

@end table


@c --------------------------- Appendix -- drill sizes -------------------------------
@node Standard Drill Sizes
@appendix Standard Drill Size Tables
@cindex drill sizes, list of standard
@cindex standard drill sizes

@section American Standard Wire Size Drills
@include wire_size.texi

@section American Standard Letter Size Drills
@include letter_size.texi

@section Fractional Inch Size Drills
@include fractional_size.texi

@section Metric Drills
@include metric_size.texi

@c --------------------------- Appendix -- Centroid File Format ----------------------
@node Centroid File Format
@appendix Centroid (X-Y) File Format
@cindex centroid file format
@cindex x-y file format

@section Overview

@section File Format
The centroid output file is in a standard comma seperated values (CSV)
format.  Comment lines begin with a ``#''.  The output file contains a
header with a version number for the file format, some comments
containing the author and title of the board, and a comment describing
the remainder of the file format.

An example centroid file is shown below.

@example

# PcbXY Version 1.0
# Date: Fri Jul 22 03:40:08 2005 UTC
# Author: PCB User
# Title: MyBoard - PCB X-Y
# RefDes, Description, Value, X, Y, rotation, top/bottom
# X,Y in mils.  rotation in degrees.
# --------------------------------------------
R61,"0603","10",2610.00,3560.00,90,top
J5,"AMPHENOL_ARFX1231","unknown",2390.00,4220.00,180,top
C13,"0402","0.01u",2340.00,3014.00,270,top

@end example

@section Computation of Centroid and Rotation
@cindex centroid file, algorithms
@cindex x-y file, algorithms
The center of each element is found by averaging the (X,Y) coordinates
for the center of each pin and pad in the element.  For example if an
element has 2 pins, 1 at (1,0) and another at (1,4) then the centroid
will be at (1,2).

The calculation of rotation is a bit more complex.  Currently a
rotation is not stored for each element but rather the rotated element
is stored.  In other words if the element from the library has a pin
at (0,0) and (0,2) and it has been rotated by 90 degrees, then the
@file{.pcb} file will store (0,0) and (2,0) for the pin locations with
no indication that they have been rotated from the original.

In the event that the element has only 1 pin, then the rotation is set
to zero.  If the element has only one pad (as opposed to a
through-hole pin), then the rotation of the pad is used.

When the element has multiple pins, the location of pin #1 is placed
in the coordinate system which has the centroid of the part at (0,0).
Then which quadrant pin #1 falls in determines the rotation.  Zero
degrees of rotation is defined as pin #1 being in the upper left
quadrant.  Increasing angles correspond to counterclockwise rotation so a
rotation of 90 degrees places pin #1 in the lower left quadrant.
Currently, the only allowed rotations are 0, 90, 180, and 270 degrees.

If pin #1 happens to be at the centroid of the part, then pin #2 is
examined to see which quadrant it is located in.  The same rules apply
for the definitions of rotation.  In other words, when pin #1 is at
the centroid of the part and pin #2 is in the upper left quadrant, the
rotation is declared to be zero degrees.

@c --------------------------- Appendix -- Annotation File Format ----------------------
@node Annotation File Format
@appendix Annotation File Format
@cindex annotation file format
@cindex backannotation file format

@section Overview

@section File Format
The annotation output file an ASCII file that can be used to communicate 
layout changes that affect the netlist back to a schematic tool.  Currently
the only place this file is used is if when the Renumber() action is called
within Pcb.  Renumber() will renumber all the reference designators (instance
names) in the layout.  The result of the renumbering will be written out to 
an annotation file which can be used to propagate the changes to the schematic
sources.  See @ref{Renumber Action} for details on the Renumber() action.  If you
are using gschem (part of gEDA/gaf) as your schematic entry tool then refer
to pcb_backannotate(1) for details on how to use the annotation file to make
the changes to the schematics.

The annotation file format is fairly simple.  Each line consists of a command followed
by arguments.  Blank lines and lines consisting of only whitespace are ignored.
There are no line continuations.

An example annotation file is shown below.
@example

*COMMENT* PCB Annotation File
*FILEVERSION* 20061031
*RENAME* "C17" "C1"
*RENAME* "U5" "U1"
*RENAME* "U6" "U2"
*RENAME* "C21" "C2"
*RENAME* "R14" "R1"
*RENAME* "C7" "C3"
*RENAME* "C8" "C4"
*RENAME* "C6" "C5"

@end example

@subsection *COMMENT*
Command for a comment.  The text of a comment is ignored by tools which process
the annotation file.
@cartouche
@format
*COMMENT* text
@end format
@end cartouche

@subsection *FILEVERSION*
Indicates what version of the annotation file is in use.  The date code corresponds to the 
date when the current version was added to the Pcb sources.  
@cartouche
@format
*FILEVERSION* datecode
@end format
@end cartouche

@subsection *RENAME*
Renames an element.  The arguments are enclosed in double quotes and are the original name
and the new name.
@cartouche
@format
*RENAME* ``old'' ``new''
@end format
@end cartouche

@c --------------------------- Appendix -- Actions ----------------------
@node Action Reference
@appendix Action Reference
@cindex action reference

@include actions.texi

@c --------------------------- Appendix -- Glossary ----------------------
@node Glossary
@appendix Glossary
@cindex glossary
@cindex terminology
@cindex index of terms

@table @asis

@item Footprint
The pattern of metal, silkscreen, soldermask relief, and drills which
defines where you place a component on a circuit board.
Footprints are the placed by the user onto the PC board during the
placement phase of PCB layout.

@item Gerber File
The file format used in the industry to convey a board database to the
manufacturer is RS-274X (which replaces the now obsolete RS-274D
format).  This file format was originally developed by Gerber for
their photo plotters and thus RS-274D and RS-274X format files 
are often times refered to as ``Gerber'' files.

@item Thermal, Thermal Relief
A thermal relief is a way of connecting a pin to a ground
or power plane.  Instead of directly connecting to the plane, small "spokes"
are used to increase the thermal resistance between the pin and the plane.
Often times these connections are refered to as simply a thermal.  By increasing
the thermal resistance to the plane, it becomes easier to solder to the
pin.  In the drawing below, the pin on the left is connected to the
polygon using a solid connection with no thermal relief, the middle
pin is connected using a thermal, while the pin on the right has no
connection to the polygon.  In PCB, the ``Thermal'' Tool is used to
make both a solid connection and one with thermal relief (see @ref{Polygon Objects}).

@center @image{thermal,,,Example of a thermal relief,png}

@end table

@c ---------------------------------------------------------------------
@node Index
@unnumbered Index of Resources
@printindex vr

@unnumbered Index of Actions, Commands and Options
@printindex fn

@unnumbered Index of Concepts
@printindex cp

@contents
@bye