Preprocesses troff command input for the purpose of drawing pictures.
pic [ -T Name ] [ - | File ... ]
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.
| File | Specifies the output from a troff command that is processed by the pic command to draw pictures. |
The top-level object in the pic command is the picture.
.PS OptionalWidth OptionalHeight
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 # (comment character) and ended by a new-line character.
The arrow object is the same as the line object with the -> 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 normally 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:
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:
The pic command is flexible enough to accept names like 1th and 3th. Usage like 1st and 3st are accepted as well.
The built-in variables and their default values are as follows:
| 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 troff, even when the .ps (size) line specifies a size greater than eight inches.
The following pic command expressions are evaluated in floating point. All numbers representing dimensions are taken to be in inches.
Expression % Expression (modulus)
sin(Expression) cos(Expression) atan2(Expression, Expression) log(Expression) sqrt(Expression) int(Expression) max(Expression, Expression) min(Expression,Expression) rand(Expression)
The pic command provides the following operators for logical evaluation:
| ! | Not |
| > | Greater than |
| < | Less than |
| >/= | Greater than or equal to |
| </= | Less than or equal to |
| && | And |
| | | Or |
| == | Equal to |
| != | Not equal to |
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:
Non-existent options are replaced by null strings. The Replacement text variable can contain newline characters.
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.
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.
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.
The grap command, troff command.
The .PE macro, .PF macro, .PS macro, me macro package.