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.

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.

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:

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.

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

• Nth
• Nth last

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:

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

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:

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