Content-type: text/html Manpage of PIGLET

PIGLET

Section: PD Piglet Users Manual (1P)
Updated: PD Piglet Users Manual
Index Return to Main Contents
 

NAME

PIGLET - execute the Piglet graphical editor under X11  

SYNOPSIS

pig  

DESCRIPTION

 

STARTUP

Piglet is started by typing "pig" in a terminal window. Piglet then creates an associated graphical window under X11. The editor scans both the graphic window and the original shell window that you used to start Piglet. You can either type coordinates, or click them with the mouse. Commands may be typed at the shell window prompt: "MAIN>". Anywhere that Piglet expects a number, you can enter a mathematical expression instead. Expressions may use the operators +,-,*,/,(,), and must be enclosed in surrounding parentheses. For example, you can add a rectangle to the current device with the command:
        ADD R1 (5.3/(4-2)),10 (3*5.3/4),20;
When entering points with the mouse, the clicks ALWAYS snap to the grid, giving a powerful way to enter precise coordinates.

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

Piglet's interactive command environment is also a simple shell. If you type the name of any executable that can be found in the $PATH variable, Piglet will run the program, displaying any output in the Piglet text window.

 

STARTUP

At startup, Piglet sets several internal environment variables including $PIG_PATH to reasonable defaults. Then it overwrites the defaults with any environment variables inherited from the parent shell. After that, Piglet searches the $PIG_PATH for a file named $PIG_RC. (Unless overridden, $PIG_RC will be set by default to "pigrc"). If this file is found in the path, Piglet will read the file for command input.

Any Piglet command can be placed in the $PIG_RC file. Macro definitions and SET commands will be read and added to the environment. This allows the $PIG_RC file to have the last say in setting the $PIG_PATH and $PIG_GEOMETRY variables. However, at this phase of startup, any EDIt commands are ignored.

After reading the $PIG_RC file, all the necessary support files are read using the $PIG_PATH. These include the menu and font definition files and process definition files. After all support files are read, the X11 graphical window is created using the $PIG_GEOMETRY specification.

Finally, the $PIG_RC file is read a second time. The contents are now executed just as if the user typed them. Now that the X11 system is initialized, EDIt commands will be honored.

The following example pigrc file sets the SHOW default to "#E", defines a three macros, sets the starting window geometry and begins an EDI of the cell named "PLAN". Piglet uses the double dollar sign "$$" as a comment character. Anything after a comment up to an end-of-line is discarded by the parser and treated as a single end-of-line character.

    $$ 
    $$ example piglet initialization file
    $$

    SET PIG_SHOW_DEFAULT "#E"   $$ make cells editable by default
    DEF wi "WIN :X.5;"          $$ window in macro
    DEF wo "WIN :X2;"           $$ window out macro
    DEF wf "WIN :F;"            $$ window fit macro
    SET PIG_GEOMETRY "700x440+10+30";
    EDI PLAN;

 

EDITING

Piglet initially displays a splash screen and sits at the MAIN> prompt waiting for commands. Typing "EDI <device>" will either load the named device from disk if it exists, or will initialize a new device. By default, Piglet locks all devices to prevent accidental modifications. The SHOW command controls the visibility and modifiability of individual layers. Most casual users will just need to type "SHOW #E;" to make all layers visible and modifiable. (Hint: "E" stands for "Everything"). From this point on, any edit command may be used. When finished, the device may be saved to disk with "SAVE;".

Piglet can nest edit commands. If you are editing <device1> and you decide that you need to create a new module, you can type "EDI <newdevice>;" without leaving your current edit session. After you SAVE and EXIT the nested edit, you will be returned to your original edit in progress. You can nest edit commands without limit subject to the constraint that you cannot simultaneously edit any device more than once.

 

NAVIGATION

Piglet makes use of the mouse scroll wheel if it exists. Scrolling the mouse zooms in or out of the current x,y location. By moving the mouse location while zooming it is possible to quickly zoom into any portion of a drawing. Zooming can be used in the middle of an ADD command. For example, one can mouse the starting coordinate of a line, zoom across the design, and then click the next coordinate. If you prefer not to use the scroll wheel, Piglet can also zoom by clicking on a point with the middle button and dragging either right or left to zoom in and out.

The WINDOW command can be used to adjust the current view. "WIN :F;" will fit the device in the window. "WIN 0,0 10,10;" will set the viewport so that a rectangle with a lower left coordinate of 0,0 and upper right of 10,10 fits as tightly as possible. Using the WINDOW command with mouse picks is a good way to zoom into a specific detail of the current device. After zooming in to check some detail, "WIN :Z;" is handy to return to the previous window setting.

 

UNDO/REDO

All commands which modify the drawing geometry can be undone with the UNDO command. The UNDO depth is limited only by available memory. Any undone operations can be redone with the REDO command. Once the user is satisfied with the state of the drawing, and proceeds to modify the geometry further, the REDO buffer is cleared.

 

AUTOSAVE

As part of the UNDO/REDO machinery, Piglet keeps an autosave file named "#<cellname>.d" in the directory "./cells". The autosave file is updated everytime the current cell is changed. When a cell is finally SAVed the autosave file is deleted so that the normal "<cellname>.d" file is the only one remaining. If Piglet crashes, or is QUIT without saving, then the autosave file will be found next time the cell is edited. Piglet then gives the user the opportunity to recover the unsaved changes at the next edit:

    MAIN> edi testcell;
    An autosave file was found that is newer than the device file.
       device file:    ./cells/testcell.d, 2803 bytes, Tue May  4 00:00:47 2010
       autosave file: ./cells/#testcellt.d, 2827 bytes, Tue May  4 00:31:58 2010
    read autosave file instead of .d file?: (y/n)? 

It is possible to examine the cells directory at any time and to compare the contents of any autosave files with the associated .d files, and to either delete the autosave file or copy it onto the .d file as appropriate.

 

COMMAND LINE EDITING

Anything typed at the command line goes into a readline buffer. A vi command history binding can be obtained by adding the lines


     set editing-mode vi
     set keymap vi

to the file "~/.inputrc". See the GNU readline(1) man page for more details about commandline editing.

 

OUTPUT

When a drawing is SAVed, Piglet creates a human readable cell definition file which consist of the same commands which were used to create the device originally. Piglet can also create postscript drawings with the PLOT command. Screendumps can be created in numerous formats with the DUMP command. By default, the compact png format is used for dumps.

 

FILES

Piglet requires several configuration files to start up. These include the TEXT and NOTE font definition files, the MENU definition file and the PROCESS layer definition file.

Unless overridden with Environment Variables (see below) Piglet sequentially searches the following directories to find the needed startup files.

    1) current working directory
    2) directory ".pigrc" under the current working directory
    3) directory ".pigrc" in the users HOME directory
    4) /usr/local/lib/piglet
    5) /usr/lib/piglet

The TEXT and FONT files by default are named "TEXTDATA.F" and "NOTEDATA.F" respectively. These names can be overridden with Environment Variables. The format for both files is plain ASCII. The files start with two integers separated by a comma. The first gives the height of each character definition and the second, the width. Each character is then listed in printed form and the glyph is defined by a set of vector coordinates. It is assumed that each successive x,y coordinate pair is connected by a stroke unless the path is broken by the special coordinate "-64,0". Each definition is terminated by the special coordinate "-64,-64". Here is an example of the first three definitions in "NOTEDATA.F" for the characters <exclam>, <double-quote>, and <pound>:

16,12
! 6,2 6,3 -64,0 6,5 6,14 -64,-64
" 4,14 4,10 -64,0 8,14 8,10 -64,-64
# 2,6 10,6 -64,0 2,10 10,10 -64,0 4,2 4,14 -64,0 8,2 8,14 -64,-64

Piglet's menu is also defined by a customizable file "MENUDATA_V". The default menu is defined as:

ayyyyy |ADD |R|P|L|N|T|
ayyyyb |SHO |C|E|I|A|O|
ayyggg |GRI |#|^|1|2|3|
aggggg |WIN |+|-|4|5|6|
yyyggg |:F|:V|:Z|7|8|9|
yyyggg |:D|:S|:L|,|0|.|
yyyyy  |:W|:C|:N|:O|:R|
yyaaaa |:X|:Y|:M|X|Y|@|
ggg    |LAY |LEV |LOC |
ggg    |FSI |TSL |    |
gyyy   |SHO #E; |;|!| |
wrgbapy|0|1|2|3|4|5|6 |
ww     |       |      |
aap    |MOV |COP |CHA |
ypy    |IDE |POI |LIS |
ygg    |DISP |DIST |  |
ggg    |DUM |PLO |ARC |
gby    |RET |SPL |INP |
ggb    |ARE |WRA |GRO |
ggr    |STR |SMA |PUR |
rrr    |DEL |EXI |BYE |
ygg    |SAV |    |    |
ygg    |EDI |UND |RED |

The file consists of fields separated by "|" characters. The first field consists of some combination of the characters "wrgbapy" which denote the colors white, red, green, blue, aqua, purple and yellow. There should be as many color designators as remaining fields. The subsequent fields on each line will be displayed exactly as shown, rendered in the corresponding color. The vertical bars are replaced with white bounding boxes.

When using the editor, any mouse pick on the menu boxes injects the menu text directly into the parse stream. The menu designer should take care to leave extra spaces after command names so that any combination of mouse picks results in intelligible commands.

The layer definition process file is named "PROCDATA.P". Its format is also plain ASCII. It consists of one EQUate command line per layer. The following PROCDATA.P file defines the characteristics of 9 layers.

EQU :C1 :P1 :M0 :B :F0 boundary 0
EQU :C2 :P2 :M1 :D :F2 layer1 1
EQU :C3 :P3 :M2 :D :F2 layer2 2
EQU :C4 :P4 :M3 :D :F2 layer3 3
EQU :C5 :P5 :M4 :S :F0 layer4 4
EQU :C6 :P6 :M5 :S :F0 layer5 5
EQU :C7 :P7 :M6 :I :F0 layer6 6
EQU :C1 :P1 :M0 :I :F0 layer7 7
EQU :C2 :P2 :M1 :I :F0 layer8 8

The first line, for example, says that layer 0 is named "boundary", drawn with color 1 (white), plotted with pen 1, and uses line type 0 (solid). The detail layers (2,3,4) are filled with fill pattern 2 and the other layers are unfilled. See the EQUate man page for full details.

 

ENVIRONMENT VARIABLES

Piglet inheirits any environment variables exported by the parent shell. In addition, new variables can be created as private variables by using the SET command.

 

VARIABLES USED BY PIGLET

PATH dir1<:dir2><:dir3>...
The PATH variable is used by the SHELL command to search for UNIX commands. It is initialized by the calling shell, but can be queried and modified within Piglet to customize the search path. When entering a new PATH the argument to SET will need to be quoted to protect the ":" delimiters from being interpreted as Piglet options.
PIG_PATH dir1<:dir2><:dir3>...
The search path used for loading all of Piglet's auxiliary files such as NOTEDATA, TEXTDATA, MENUDATA, PROCDATA, etc. Defaults to "./cells:.:./.pigrc:~/.pigrc:/usr/local/lib/piglet:/usr/lib/piglet"
PIG_FONT_SIZE <size> ; default is 10.0
The default font size used for both note and text if not otherwise overridden with :F option.
PIG_FONT_SLANT <degrees> ; default is 0.0
The default italic font slant (from -45.0 to +45.0) used for both note and text if not otherwise overridden with :Z option.
PIG_GEOMETRY [=]<width>x<height>{+-}xoffset{+-}yoffset
The argument is a standard X11 geometry specification. The first two numbers specify the width and height of the piglet window in pixels. The second two numbers must come as a pair and give the offset of the window from one edge of the display. Positive xoffsets are measured from the left edge and negative from the right. Positive yoffsets are measured from the top of the screen and negative from the bottom. If a width or height is too small to be usable with the current menu, the size will be increased to a reasonable minimum value. The geometry specification is useful for placing the graphics window above the command window so that interactive commands can be easily seen and edited.
    Some example geometries:

      PIG_GEOMETRY=500x500+0+0 pig      ; a small window in upper left corner
      PIG_GEOMETRY=900x700-0+0 pig      ; a wide window in upper right corner
      PIG_GEOMETRY=500x700-0-0 pig      ; a tall window in lower right corner
      PIG_GEOMETRY=600x600+0-0 pig      ; a medium window in lower left corner
PIG_GRID <dx> [<dy> [<dxs> [<dys> [<xorig> [<yorig>]]]]]
From one to six floats used to set the grid deltax, deltay, xskip, yskip, and x and y origins. Any parameters left off will remain set to the default grid specification of "10 10 1 1 0 0".
PIG_GRID_COLOR <num> ; default is 3
Used to set the default grid color when editing new cells.
PIG_SHOW_DEFAULT <SHO_CMD_OPTIONS> ; default is not defined
If defined, then the SHOW command will be run with <SHO_CMD_OPTIONS> as an argument immediately after opening any new drawing. A casual user may wish to set PIG_SHOW_DEFAULT to "#E" so that all layers are visible and editable by default.
PIG_MENUDATA_FILE <filename> ; default is MENUDATA_V
Sets the name used for loading the Menu definition file.
PIG_NOTEDATA_FILE <filename> ; default is NOTEDATA.F
Sets the name used for loading the stroke definition file for NOTEs.
PIG_TEXTDATA_FILE <filename> ; default is TEXTDATA.F
Sets the name used for loading the stroke definition file for TEXT.
PIG_PROCDATA_FILE <filename> ; default is PROCDATA.P
Sets the name used for loading the process layer definition.
PIG_SPLASH_REP <cellname> ; default is piglogo
Sets the name of the cell used for the initial splash screen during startup. The cell should already exist in PIG_PATH.

 

DEBUGGING

Since Piglet is under active development, it is distributed to run under the gdb() debugger. The script "pig" runs pig.bin under gdb(). When running under gdb() most run-time errors will print out a backtrace of the stack. If you would like help fixing a bug, please send a copy of the dump file (named "pigtrace.<process_id>") to Rick Walker <walker AT omnisterra DOT com> along with some description of what caused the bug.

When running pig.bin without the debugger, Piglet traps and ignores most signals, printing a notification to the terminal: "caught 2: Interrupt. Use QUIT command to end program". However, the special signal SIGQUIT elicits the message: "caught 3: Quit. do it again and I'll die!". Two SIGQUITs in a row will terminate the program.  

SEE ALSO

piglet(1p) add_arc(1p) add_circle(1p) add_instance(1p) add_line(1p) add_note(1p) add_oval(1p) add_polygon(1p) add_rectangle(1p) add_text(1p) archive(1p) area(1p) background(1p) bye(1p) change(1p) copy(1p) date(1p) define(1p) delete(1p) display(1p) distance(1p) dump(1p) echo(1p) edit(1p) equate(1p) exit(1p) files(1p) fsize(1p) grid(1p) group(1p) help(1p) identify(1p) input(1p) interrupt(1p) layer(1p) level(1p) list(1p) lock(1p) macro(1p) menu(1p) move(1p) plot(1p) point(1p) process(1p) purge(1p) quit(1p) redo(1p) retrieve(1p) save(1p) search(1p) set(1p) shell(1p) show(1p) smash(1p) split(1p) step(1p) stretch(1p) trace(1p) tslant(1p) undo(1p) units(1p) version(1p) window(1p) wrap(1p) memory(1p) time(1p)  

AUTHOR

Rick Walker (walker AT omnisterra DOT com)

The PD Piglet homepage is at http://www.omnisterra.com/walker/linux/piglet/intro.htm.


 

Index

NAME
SYNOPSIS
DESCRIPTION
STARTUP
STARTUP
EDITING
NAVIGATION
UNDO/REDO
AUTOSAVE
COMMAND LINE EDITING
OUTPUT
FILES
ENVIRONMENT VARIABLES
VARIABLES USED BY PIGLET
DEBUGGING
SEE ALSO
AUTHOR

This document was created by man2html, using the manual pages.
Time: 19:41:46 GMT, May 14, 2010