pic Command

Purpose

Preprocesses troff command input for the purpose of drawing pictures.

Syntax

pic-T Name ] [  -File ... ]

Description

The pic command is a troff command preprocessor for drawing simple figures on a typesetter. The basic objects are a box, circle, ellipse, line, spline, arrow, arc, and the text specified by the Text variable. The top-level object is the picture.

Item Description
File Specifies the output from a troff command that is processed by the pic command to draw pictures.

Pictures

The top-level object in the pic command is the picture.

.PS OptionalWidth OptionalHeight

ElementList

.PE

If the .PF macro is used instead of the .PE macro, the position after printing is restored to what it was upon entry.

Item Description
OptionalWidth Specifies the width of the picture (in inches), if present, regardless of any dimensions used internally. The maximum value is 8.5.
OptionalHeight Specifies a height value, in inches, different from the default, which is scaled to the same proportion. The maximum value is 14.
ElementList Represents the following list of elements:
Shape AttributeList 
For Statement
Placename: Element 
If Statement 
Placename: Position 
Copy Statement 
Variable = Expression
Print Statement 
Direction
Plot Statement 
{ List of Elements }
sh X Commandline X
[ List of Elements ]
troff-command

Variable names begin with a lowercase letter, followed by zero or more letters or numbers. Place names begin with an uppercase letter, followed by zero or more letters or numbers. Place and variable names retain their values from one picture to the next.

Elements in a list must be separated by new-line characters or ; (semicolon); a long element can be continued by ending the line with a \ (backslash). Comments are introduced by a # character and ended by a new-line character.

Primitives
The primitive objects are as follows:

box

circle

ellipse

arc

line

arrow

spline

move

Text-List

The arrow object is the same as the line object with the -> attribute.

Attributes
An AttributeList element is a sequence of zero or more attributes; each attribute consists of a keyword, perhaps followed by a value.
Attribute Attribute
h(eigh)t Expression wid(th) Expression
rad(ius) Expression diam(eter) Expression
up OptionalExpression down OptionalExpression
right OptionalExpression left OptionalExpression
from Position to Position
at Position with Corner
by Expression, Expression then
dotted OptionalExpression dashed OptionalExpression
chop OptionalExpression -> <- <->
invis same
Text-list  

Missing attributes and values are filled in from defaults. Not all attributes make sense for all primitives; irrelevant ones are not processed. The following are the currently meaningful attributes:

Item Description
Primitives Attributes
box h(eigh)t, wid(th), at, same, dotted, dashed, invis, Text
circle, ellipse rad(ius), diam(eter), h(eigh)t, wid(th), at, same, invis, Text
arc up, down, left, right, h(eigh)t, wid(th), from, to, at, rad(ius), invis, ccw, cw, <-, ->, <->, Text
line, arrow up, down, left, right, h(eigh)t, wid(th), from, to, by, then, at, same, dotted, dashed, invis, <-, ->, <->, Text
spline up, down, left, right, h(eigh)t, wid(th), from, to, by, then, at, same, invis, <-, ->, <->, Text
move up, down, left, right, to, by, same, Text
Text-list at, Text-item

The at attribute implies placing the geometrical center at the specified place. For lines, splines, and arcs, the h(eigh)t and wid(th) attributes refer to arrowhead size.

The Text-item variable is usually an attribute of some primitive; by default, it is placed at the geometrical center of the object. Stand-alone text is also permitted. A Text-list primitive is a list of text items; a text item is a quoted string optionally followed by a positioning request, as follows:

"..."

"..." center

"..." ljust

"..." rjust

"..." above

"..." below

If there are multiple text items for some primitives, they are centered vertically except as qualified. Positioning requests apply to each item independently.

Text items can contain troff commands that control, for example, size and font changes and local motions. Make sure these commands are balanced so that the entering state is restored before exiting.

Item Description
Positions/Places A position is ultimately an X,Y coordinate pair, but it can also be specified in the following ways:

Place

( Position )

Expression, Expression

(Position ) [+/- (Expression, Expression)]

( Position ) [+/- Expression, Expression]

( Place1, Place2 )

( Place1.X, Place2.Y)

Expression < Position, Position >

Expression [of the way] between Position and Position

Placename [Corner]

Corner Placename

Here

Corner of Nth Shape

Nth shape [Corner]

Note: A Corner variable designates one of the eight compass points or the center, beginning, or end of a primitive, as follows:

.n .e .w .s .ne .se .nw .sw

.t .b .r .l

c .start .end

Each object in a picture has an ordinal number; Nth refers to this, as follows:

The pic command is flexible enough to accept names like 1th and 3th. Usage like 1st and 3st are accepted as well.

Variables

The built-in variables and their default values are as follows:

Item Description
boxwid 0.75
boxht 0.5
circlerad 0.25
arcrad 0.25
ellipsewid 0.75
ellipseht 0.5
linewid 0.5
lineht 0.5
movewid 0.5
moveht 0.5
arrowwid 0.05
arrowht 0.1
textwid 0
textht 0
dashwid 0.5
scale 1

These default values can be changed at any time, and the new values remain in force from picture to picture until changed again.

The textht and textwid variables can be set to any value to control positioning. The width and height of the generated picture can be set independently from the .PS macro line. Variables changed within the [ (left bracket) delimiter and the ] (right bracket) delimiter revert to their previous value upon exit from the block. Dimensions are divided by scale during output.
Note: The pic command has an eight inch by eight inch limitation on picture sizes generated and sent to the troff command, even when the .ps (size) line specifies a size greater than eight inches.

Expressions

The following pic command expressions are evaluated in floating point. All numbers representing dimensions are taken to be in inches.

Expression + Expression

Expression - Expression

Expression * Expression

Expression / Expression

Expression % Expression (modulus)

- Expression

( Expression )

variable

number

Place .x

Place .y

Place .ht

Place .wid

Place .rad

sin(Expression) cos(Expression) atan2(Expression, Expression) log(Expression) sqrt(Expression) int(Expression) max(Expression, Expression) min(Expression,Expression) rand(Expression)

Logical Operators

The pic command provides the following operators for logical evaluation:

Item Description
! Not
> Greater than
< Less than
>/= Greater than or equal to
</= Less than or equal to
&& And
| Or
== Equal to
!= Not equal to

Definitions

The following define statement is not part of the grammar:

define Name X Replacement text X

Occurrences of values such as $1 and $2 in the Replacement text variable are replaced by the corresponding options if the Name variable is called, as follows:

Name(Option1, Option2, ...)

Non-existent options are replaced by null strings. The Replacement text variable can contain newline characters.

copy and copy thru Statements

The copy statement includes data from a file or values that immediately follow, such as:

copy File
copy thru Macro
copy File thru Macro
copy File thru Macro until String

The Macro parameter value can be either the name of a defined macro or the body of a macro enclosed in some character not part of the body. If no file name is given, the copy statement copies the input until the next .PE macro line.

for Loops and if Statements

The for and if statements provide for loops and decision-making, as follows:

Variable=Expression to Expression by Expression do X anything X
if Expression then X anything X else X anything X

The by and else clauses are optional. The Expression variable in an if statement can use the usual relational operators or the String1 == (or !=) String2 string tests.

Miscellaneous Information

The sh command runs a command line, as follows:

sh X Commandline X

It is possible to plot the value of an expression, as follows:

plot Expression OptionalFormat Attributes

The Expression variable value is evaluated and converted to a string (using the format specification, if provided).

The state of fill or no-fill mode is preserved with respect to pictures.

Input numbers can be expressed in E (exponential) notation.

Flags

Item Description
-TName Prepares the output for the specified printing device. Possible values for Name are:
ibm3812
3812 Pageprinter.
ibm3816
3816 Pageprinter.
hplj
Hewlett-Packard LaserJet II.
ibm5587G
5587-G01 Kanji Printer multi-byte language support.
psc
PostScript printer.
X100
AIXwindows display.
X100K
AIXwindows display for multi-byte character support.

The default is ibm3816.

Note: It is possible to set the TYPESETTER environment variable to one of the preceding values instead of using the -T Name flag of the troff command.
- Reverts to standard input.