AAA_README

Compiling and Installing
-------------------------

Just type "make" and you should have a working piglet.

You can play with it in the src directory until you decide
you like it.  Then you can run "make install" with sufficient
priviledges to create and write in /usr/local/bin and /usr/local/man/man1.

Getting Started
---------------

Here are some things to try.  Firstly, the drawings that you create
will all be in the sub-directory ./cells.  Later on, piglet should probably
have a search path for drawings.

Start piglet by typing "pig" in the source directory.

Notice that piglet creates a graphic window.  The editor is scanning the
graphic window for mouse clicks and the original shell window that you
used to start piglet for keyboard input.  You can either type
coordinates, or click them with the mouse.  The shell window should have
a prompt:

    MAIN>

All commands in piglet are terminated either with another command, or
with a right mouse click, or with an ";" character.  If you don't
terminate a command with a ";" or right-button, you can usually keep
using a command over again to make multiple MOVes or COPys.  Once you
terminate a command, you have to type another command to start working
again. 

If you are using KDE under linux, then it works best to set the text window
just under the graphics window:

	-------------
	|           |
	|  graphics |
	|           |--
	------------- |
           | >text    |
	   ------------

and set your mouse focus preference to "Focus follows mouse".  That
way you can use either typing or mouse clicking to enter coordinates.
You'll definitely need the text window for typing cell names.

The latest version of piglet adds shell command capability.  When you
type a command at the text prompt, piglet searches for an internal command
of that name.  If it doesn't find one to execute, then it looks through
the $PATH variable to see if there is a UNIX command that can be executed.
If so, it spawns a subshell and runs the UNIX command sending stdout to
the terminal.  This is a handy facility for running the ls command.  I commonly 
type "ls cells" to see what cells I've created.

A few PIGLET commands terminate the current action with a double click
on the same coordinate.  An example of this is the "ADD L<layer>" add
line command.  A double-click terminates the current line, but leaves
you in the add line command to continue adding lines until you finally
are ready to do something different. 

Anything that you can type, you can also enter by clicking on the menu. 
Piglet's graphical language is identical to its command line language,
so you can either type "ADD R6 x1,y1 x2,y2;" or you can click the mouse
on the menu to input "ADD" "R" "6" and then mouse the two coordinates. 

Usually, it is only necessary to type on the keyboard for entering the
names of cells, and for entering TEXT and NOTE strings. Everything else
can be done by menu clicks.

All commands that change the drawing can be undone with the UNDO
command.  Any command that is UNDOne can be reapplied with the REDO
command.  The depth of the UNDO command is limited only by the
available memory.  This makes it safe to explore piglet's commands.
If you make a mistake, just UNDO it!

Open a piglet window and let's go through a tour of some commands:

----------------- GRID ---------------------

Try playing with the grid.  If you type "gri 20 2;", you'll get a 20x20
grid tick with a skip of two.  You'll see what I mean if you try it. 
You can move your mouse in the graphic area and see the xy coordinates
of the mouse displaying in the upper left corner. 

You can also offset the grid.  Try "gri 20 2 5 5;" and notice that the
origin is now at 5,5 instead of 0,0.

Finally, you can make a non-isotropic grid with something like 
"gri 10 20 2 4 7 7";  This form of the command sets:

   gri <xspacing> <yspacing> <xskip> <yskip> <xorig> <yorig>

When entering points with the mouse, the clicks ALWAYS snap to the grid,
giving a powerful way to enter precise coordinates.

The grid also allows an option ":C<0-9>" which will set the color of the
grid to any of the 8 system colors.  For example: "grid :c2 10 2" creates
a red grid.  The colors are "white, red, green, blue, cyan, magenta,
yellow, white, grey, dark_grey".

You can also turn the grid on with "GRI ON" or off with "GRI OFF". 
Typing "GRI;" with no arguments toggles the grid state.

COMMANDS
--------

All the piglet built-in commands can be abbreviated to just three letters
with one exception.  DISPLAY must be entered as "DISP" or "disp" to
distinguish it from "DIStance".

HELP
----

You can get a list of all commands by typing "?" or "HELP".  You can get a
summary on just one command by typing "HELP <command>".  

There are also UNIX style man pages in the ./web/man1p directory.  If you
did a "make install", these should be in your /usr/local/man/man1
directory.  If this is in your MANPATH environment variable, you can
type "man piglet" and get an overview of the editor and an index of all
the man pages available.  For commands that might conflict with existing
manual pages, you can ask man to look in the piglet man pages by saying
"man 1p copy", or "man 1p add_line".  Each command has a separate man
page so you can look at "man 1p add_rectangle", "man 1p move", "man 1p copy", and
so on. 


EDIT
-----

Once you are happy with the grid spacing and color, try adding some
primitives to the drawing.  First give your drawing a name with "edi
mycell".

SHOW
----

(Actually you can skip this section for now.  Out of the box, piglet
is already setup to make new cells editable by default.  Later, you
might want to change this behavior by change the appropriate environment
variable in your pigrc startup file).  If you want to learn about piglet's
locking and viewing mechanism, read on...

OVERVIEW:
Before you can add anything to your drawing you need to make some of the
layers modifiable.  They default to "visible and locked" by default.  Type
"SHO #E;" and you are set to go.  You'll need to do this everytime you edit
a new cell. 

Now the details:
The show command controls what layers are visible and modifiable in the
drawing.  The default when starting to edit a new file is ALL layers
visible and ALL layers non-modifiable.  This feature makes it much safer
to browse critical files with Piglet.  You can't change anything unless
you unlock the layers with the SHOW command.  The SHOW command syntax
is:

SHOW {+|-|#}[EACILN0PRT]<layer>

You can control visibility and modifiability with the following characters:

   + : make it visible
   - : turn it off
   # : visible and modifiable

You control which kinds of components you are working with by the following
component designators:

   E : everything
   A : arc
   C : circle
   I : instances
   L : lines
   N : notes
   O : oval
   P : polygons
   R : rectangles
   T : text

The <layer> is either specific layer number, or if omitted, will control all
layers.

Some examples:
	
    SHO #E;       /* ALL layers visible and modifiable */
    SHO #E -C7;   /* ALL layers vis. and mod. except circles on layer 7*/
    SHO -E #R3;   /* Nothing editable except Rectangles on layer 3 */
    SHO #E7 +E5;  /* display layers 7 and 5, only layer 7 is modifiable */

RECTANGLES
----------

NOTE: Remember that you can't add anything until you type "SHO #E;" to
unlock "Everything" and make the layers editable! 

Now try adding a rectangle on layer 7 by typing "ADD R7" then clicking
the two corners of your rectangle with your left mouse button.  You can
add as many rectangles as you want by continuing to click pairs.  The
command can be terminated with a right-click or by typing either a ";"
or another command name at the keyboard.  You can get different colors
by adding R<layer_number>.   

(Note: piglet defines the layer colors, line types and fill patterns in
a file called PROCDATA.P.  For now, you can just use the default file
and not worry about it.  Later on, you might want to read the man page
for the "equate" command and edit PROCDATA.P for your own preferred
colors.) 

As always with piglet, you can use either the mouse or the keyboard 
to enter coordinates.  For example, you can type:

	"ADD R22 0,0 100.01,121.44;"

to explicitly add precise coordinates without using the mouse.  This is
very handy when you are entering precise coordinates from a table or
from calculations. 

Coordinates from the mouse are always snapped to the grid, visible or
not.  Coordinates entered from the keyboard are used exactly as-is.

INPUT
-----

If you don't want to do all your typing at the prompt, you can use a
program to create lines like the above, print them into a file called
"./cells/foo", and then read them into your current cell using the input
command: "INP foo". 


COMMAND LINE EDITING
--------------------

Anything typed at the command line goes into a readline buffer.  I have
mine set up with a ksh-like vi command history binding.  You can change the
binding by editing ~/.inputrc.  My file looks like:

------------ cut here for gnu readline ~/.inputrc file ----------
set editing-mode vi
set keymap vi
------------ cut here for gnu readline ~/.inputrc file ----------

If you don't set anything, I think you get either an emacs or 
up-arrow, down-arrow editing mechanism.

When you use the CHAnge command on text or notes, the string of the note
is put in the command buffer.  You can move up with command line editing
and easily modify the string for re-entering a changed version. 

WINDOWING
---------

You can fit the window to the bounding box of the drawing
by typing "WIN :F;".   You can center the drawing on a particular
point by typing "WIN" and then double clicking on any given point.
Clicking two different points will window in on a region.  You can
get a zoom in or zoom out by using "WIN :X<factor>".

If you have a very complex drawing with lots of hierarchy, you can
simplify things by using the ":N<nest_level>" of the WIN command.  "WIN
:N0" will show all sub-cells as bounding boxes.  "WIN :N1" will show all
sub-cells of sub-cells as bounding boxes, and so on. 

Piglet also allows zooming at all times with the mouse scroll button. 
It will zoom in/out of the current mouse location on the screen.  If you
scroll out from one location and then in from another, you can
effectively pan the window from one location to another.  This feature
even works while in the middle of adding long and complicated
components, such as a line. 

If you click with the middle button, you can drag right/left or up/down to 
zoom in and out.

The middle button will also fit the window on a double click, and recenter the
window on any single click point.

ADDING LINES
-----

You can add lines with "ADD L<layer_number>".  Keep clicking your
coordinates with your left-mouse button.  Double-clicking on the same point
will terminate the line and still let you create new lines.  Right-clicking
or typing ";" will terminate both the line and the command.  If it is
a long line and you need to place the coordinates accurately, you can
zoom around in the middle of the command using the mouse scroll button.

Lines can have width.  Typing "ADD L7 :W20" will let you enter a line
with a width of 20.  The default is a width of zero.

If add the :B<nsegs> option, the line will convert to a smoothed spline curve.
Try something like "ADD L1 :w5 :b8 0,0 ....;".  The <nsegs> controls how many
smoothed points are inserted between your original line points.  The bigger
<nsegs>, the more smooth the line will look.  Reasonable values are between
1 and 10.  You can change any option of any primitive by typing "CHA" and then
clicking on the element you want to modify.  After it is highlighted type the
new option at the prompt and hit ";" to terminate the command.  For instance,
you can turn smoothing off with "CHA <select_the_line_with_the_mouse> :B0;"

ADDING CIRCLES
-------

Circles are added with "ADD C<layer> :R<degrees> XY1 XY2". The ":R" option 
gives the resolution in degrees.  This is handy for making regular polygons.
For instance "ADD C7 :R72" will create a perfect pentagon.  The pentagon
rotates during rubberband drawing such that the second point, XY2, is always
on one of the vertices.  "ADD C7 :R90" is a way to add a rotated square.
"ADD C7 :R120" adds an equilateral triangle.

You can add ovals by using the :Y<xyratio> option to "ADD C".  Try "ADD C7 :Y.3"
to add an oval with a major/minor axis ratio of 0.3.  

ADDING POLYGONS
--------

Similiar to lines.  The polygons are always closed for you while you are
drawing.  Double clicking terminates but keeps the command active.  You won't see
any feedback on the screen until you've clicked at least two points.

ADDING NOTES and TEXT
--------------

You can add notes (drawn with zero width strokes) with 

    ADD N<layer> :F<fontsize> "text to be displayed";

Text is drawn with polygons and can be entered with

    ADD T<layer> :F<fontsize> "text to be displayed";

The fontsize is the vertical spacing of the characters that will
produce single-spaced lines of text.  So, a fontsize of :F20 will
produce a capital letter with a height of about 15 units.

Other options are

    ":M<x|y|xy>"     mirror the text around x,y, or both xy axes
    ":R<angle>"      rotate text by <angle> in degrees
    ":Y<yxratio>"    set y to x ratio to make skinny or fat letters
    ":Z<slant>"      create italics by slanting the text by <slant> degrees

These fonts are defined in NOTEDATA.F and TEXTDATA.F and are easily
changed.  I have quite a few fonts that are derived from the Hershey
font database.  The format is pretty simple and is documented in
readfont.c. 

ADDING INSTANCES
---------

You can save your drawing with the "SAVE;" command.  You can then 
"EXIT;" and you are ready to "EDI" a new drawing.  This is the fun part 
of piglet.  Try doing "EDI newdrawing" and adding a copy of our previous
drawing as a sub-cell.   Doing "ADD mycell" lets you click to
add copies of your previous drawing "mycell" to "newdrawing".   You
can use options to add copies with scaling, rotation, etc:

    ":M<x|y|xy>"     mirror the text around x,y, or both xy axes
    ":R<angle>"      rotate text by <angle> in degrees
    ":X<factor>"      scale instance by <factor>
    ":Y<yxratio>"    set y to x ratio to make skinny or fat letters
    ":Z<slant>"      create italics by slanting the text by <slant> degrees

This nesting can be arbitrarily deep.  You can "SAVE newdrawing" and
then "EDI biggerdrawing" and add copies of both "newdrawing" and "mydrawing"
into "biggerdrawing".

Also, the subcells are live.  This means that if you finish with a
drawing using sub-drawings of slotted screws, you can change them all to
philips-style screws by simply editing the original definition.  It will
change in all the drawings that have called the cell, no matter how complex
the nesting or the transformations applied.

WRAP
----

You can wrap up any number of primitives by drawing a box around them
with the WRAP command.  These components are then "pushed" down one
level of the drawing and named something like "NO_NAMExxx".  This new
block can be moved, copied, scaled, mirrored and rotated.  You can also
give the block a new name and save it as a cell.  If you don't give the
WRAPped block a new name it will be automatically dismembered (SMAshed)
when you finally exit the edi. 

SMASH
----

Any cell that you add to the drawing can be SMAshed.  This will
un-bundle all the components in the sub-cell and add them directly to
the current drawing at the top level of hierarchy.  Be careful with this
command as it can easily create an unmanageably huge number of
components.   Smash has a "by region" option (:R) that will allow you
to draw a rectangular box around a bunch of things to smash all at once.

STRETCH
-------

An invaluable editing tool.  You can click on any vertex of a component
and pull it to a new position.  You can also use the "by region" option
(:R) to draw a box around any number of vertices and pull them all
together to an new position.  Lines and polygons will simply stretch to
accomodate. 

CHANGE
------

If you click on any component using the CHA command, you may then enter
any option such as :L<layer>, :F<fontsize>, :M<mirror_type>,
:R<rotation> and the new option will be applied to the selected
component.  You can also click on text or notes and then enter a new
string to replace the current value.  Command line editing is in effect. 
If you have your .inputrc file set up for vi command editing, then you
can type CHA, then click on a text or note, and use <esc>-k to pull up
the old string definition.  You can then edit the string using ksh-like
commands.  Use <enter> to replace the old text with the new string. 

SAVE
----

When you "SAV" a cell it creates a text file in ./cells/<CELLNAME>.d
The file is human readable and is a nicely formatted transcript of the
exact commands that you typed and moused to create the cell in the first
place.  You can edit this file (carefully) and the textual changes will
take effect next time you start a new piglet and read in the definition.
The "<CELLNAME>.d" file only contains the definition of the cell <CELLNAME>.
If <CELLNAME> includes other cells, they will only be called by name and not
defined.  In other words, if you mail a friend a ".d" file, they will be
unable to reconstruct your cell if it has any hierarchy.  If you want
a full definition of your work, then you should use the "ARCHIVE" command.

ARCHIVE
-------

When you "ARC" a cell it creates a text file in ./cells/<CELLNAME>_I
which contains a full hierarchical description of <CELLNAME> including
all sub-cells.  The "_I" archive file is constructed to have no forward
references and includes PURGE commands to delete any previously defined
cells before redefining them. 


PURGE
-----

If you want to use textual processing to change a cell that's already
been read into memory, you can "PURGE <cellname>", and then re-edit it.
The second edit will re-read the disk definition including any changes
that have been added.  If you type PURGE interactively, rather than
input it from a file, you will be asked permission to delete the memory
copy, and then any disk copies of the cell.

DEMOS
-----

There are several big drawings in the cells directory.  You can take
a look at these to see how piglet handles thousands of polygons.
Try: 

    "EDI CDRCFR"   a hybrid substrate for a 2.488 GHz phase locked loop
    "EDI tone"     a schematic for a PBX dial tone generator
    "EDI fontest"  an example of all the characters in note and text fonts
    "EDI H20919M1" a 24x36 inch 6-layer Printed Circuit Board design
    "EDI testpen"  a sample of all the line types
    "EDI PLAN2"    the floor plans of the two houses on my lot 
    "EDI slic"     a telephone subscriber line interface circui
    "EDI pict3"    a 3-D drawing of a high-speed test fixture
    "EDI RTILE"    a GAAS delay line integrated circuit layout 
    "EDI RINGOSC"  the layout for the first 3/5 ring oscillator

You can look at the CELL.d files to see the top level definitions or
you can look at the CELL_I file to see the full hierarchical archive
which includes all the sub-cell definitions.  The archive file is fully
self-contained and is suitable for e-mailing a complete design to another
person.

DUMP
----

The DUMP command creates a Portable Pix Map copy of the current graphic
window in the file "./<device_name>.ppm".  You can view/print/convert
this with xv(1), or convert it to gif format with ppmtogif(1) from the
pbmtools package. 

PLOT
----

The PLOT command creates a Postcript dump of the current windowed device
in the file "./<device_name>.ps.  There are several different options
available to also output in Gerber, DXF, SVG, or simple ASCII formats
too. 

IDENTIFY
--------

The IDEntify command takes a series of xy points and for each point
highlights the nearest primitive and prints some information about it to the
screen. In most cases, the information string is in the same format that
was used to create the object initially.  You can cut/paste this and edit
it to make a similar object again.

POINT
-----

The POInt command takes a series of xy points and simply prints their
coordinates to the screen.  No change is made to the database.


MISSING STUFF
-------------

MACROS
------

The original piglet had macros and command line math evaluation so
you could define more complex functions and type things like:

    ADD R7 0,0 35/2,100+5*sqrt(2);

for computing precise coordinates on the fly.

REVISION CONTROL
----------------

It would be easy to have every SAVE do a "ci -l" on the cell, thereby
keeping revision control on every cell.  

I'm thinking of allowing the user to create variables that are stored with
the cell.  They could look like:

$$F: "some text keyed to F" $$
$$H: "some text keyed to H" $$

The user could then add text to the drawing referencing these variables
with something like:

	ADD T7 :F20 $F;

If one of the variables has the $Id keyword in it, then RCS will substitute
that keyword dynamically with the version number at each checkin.  This
makes it trivial to put a text block in the lower left corner of your
drawing that is always lists the latest rev number for the drawing.

You could also define variables that would make the cell automatically
upgrade to the latest available version, or insist that the version be
frozen at particular rev number.


LEARN MORE
---------

Make sure and read the man pages for each command to discover more
options.  Please write if you have any questions or suggestions. 

kind regards,
--
Rick Walker
walker AT omnisterra DOT com