10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
360 lines
8.3 KiB
Groff
360 lines
8.3 KiB
Groff
.TH PIC 1
|
|
.de PS \" start picture
|
|
. \" $1 is height, $2 is width, both in inches
|
|
.if \\$1>0 .sp .35
|
|
.ie \\$1>0 .nr $1 \\$1
|
|
.el .nr $1 0
|
|
.in (\\n(.lu-\\$2)/2u
|
|
.ne \\$1
|
|
..
|
|
.de PE \" end of picture
|
|
.in
|
|
.if \\n($1>0 .sp .65
|
|
..
|
|
.SH NAME
|
|
pic, tpic, svgpic \- troff and tex preprocessors for drawing pictures
|
|
.SH SYNOPSIS
|
|
.B pic
|
|
[
|
|
.I files
|
|
]
|
|
.PP
|
|
.B tpic
|
|
[
|
|
.I files
|
|
]
|
|
.PP
|
|
.B svgpic
|
|
[
|
|
.I files
|
|
]
|
|
.SH DESCRIPTION
|
|
.I Pic
|
|
is a
|
|
.MR troff 1
|
|
preprocessor for drawing figures on a typesetter.
|
|
.I Pic
|
|
code is contained between
|
|
.B .PS
|
|
and
|
|
.B .PE
|
|
lines:
|
|
.IP
|
|
.EX
|
|
\&.PS \f2optional-width\fP \f2optional-height\fP
|
|
\f2element-list\fP
|
|
\&.PE
|
|
.EE
|
|
.LP
|
|
or in a file mentioned in a
|
|
.B .PS
|
|
line:
|
|
.IP
|
|
.BI .PS " " < file
|
|
.LP
|
|
If
|
|
.IR optional-width
|
|
is present, the picture is made that many inches wide,
|
|
regardless of any dimensions used internally.
|
|
The height is scaled in the same proportion unless
|
|
.IR optional-height
|
|
is present.
|
|
If
|
|
.B .PF
|
|
is used instead of
|
|
.BR .PE ,
|
|
the typesetting position after printing is restored to what it was
|
|
upon entry.
|
|
.PP
|
|
An
|
|
.IR element-list
|
|
is a list of elements:
|
|
.EX
|
|
\f2primitive attribute-list\fP
|
|
\f2placename\fP : \f2element\fP
|
|
\f2placename\fP : \f2position\fP
|
|
\f2var\fP = \f2expr\fP
|
|
\f2direction\fP
|
|
{ \f2element-list\fP }
|
|
[ \f2element-list\fP ]
|
|
for \f2var\fP = \f2expr\fP to \f2expr\fP by \f2expr\fP do { \f2anything\fP }
|
|
if \f2expr\fP then { \f2anything\fP } else { \f2anything\fP }
|
|
copy \f2file,\fP copy thru \f2macro,\fP copy \f2file\fP thru \fPmacro\fP
|
|
sh { \f2commandline\fP }
|
|
print \f2expr\fP
|
|
reset \f2optional var-list\fP
|
|
\f2troff-command\fP
|
|
.EE
|
|
.PP
|
|
Elements are separated by newlines or semicolons;
|
|
a long element may be continued by ending the line with a backslash.
|
|
Comments are introduced by a
|
|
.BI #
|
|
and terminated by a newline.
|
|
Variable names begin with a lower case letter;
|
|
place names begin with upper case.
|
|
Place and variable names retain their values
|
|
from one picture to the next.
|
|
.PP
|
|
After each primitive
|
|
the current position moves in the current direction
|
|
.RB ( up , down ,
|
|
.BR left , right
|
|
(default)) by the size of the primitive.
|
|
The current position and direction are saved upon entry
|
|
to a
|
|
.BR { ... }
|
|
block and restored upon exit.
|
|
Elements within a block enclosed in
|
|
.BR [ ... ]
|
|
are treated as a unit;
|
|
the dimensions are determined by the extreme points
|
|
of the contained objects.
|
|
Names, variables, and direction of motion within a block are local to that block.
|
|
.PP
|
|
.IR Troff-command
|
|
is any line that begins with a period.
|
|
Such a line is assumed to make sense in the context where it appears;
|
|
generally, this means only size and font changes.
|
|
.PP
|
|
The
|
|
.I primitive
|
|
objects are:
|
|
.br
|
|
.EX
|
|
box circle ellipse arc line arrow spline move \f2text-list\fP
|
|
.EE
|
|
.L arrow
|
|
is a synonym for
|
|
.LR "line ->" .
|
|
.PP
|
|
An
|
|
.IR attribute-list
|
|
is a sequence of zero or more attributes;
|
|
each attribute consists of a keyword, perhaps followed by a value.
|
|
.EX
|
|
.ta .5i 2.5i
|
|
h(eigh)t \f2expr\fP wid(th) \f2expr\fP
|
|
rad(ius) \f2expr\fP diam(eter) \f2expr\fP
|
|
up \f2opt-expr\fP down \f2opt-expr\fP
|
|
right \f2opt-expr\fP left \f2opt-expr\fP
|
|
from \f2position\fP to \f2position\fP
|
|
at \f2position\fP with \f2corner\fP
|
|
by \f2expr, expr\fP then
|
|
dotted \f2opt-expr\fP dashed \f2opt-expr\fP
|
|
chop \f2opt-expr\fP -> <- <->
|
|
invis same
|
|
fill \f2opt-expr\fP
|
|
\f2text-list\fP \f2expr\fP
|
|
.EE
|
|
Missing attributes and values are filled in from defaults.
|
|
Not all attributes make sense for all primitives;
|
|
irrelevant ones are silently ignored.
|
|
The attribute
|
|
.L at
|
|
causes the geometrical center to be put at the specified place;
|
|
.L with
|
|
causes the position on the object to be put at the specified place.
|
|
For lines, splines and arcs,
|
|
.L height
|
|
and
|
|
.L width
|
|
refer to arrowhead size.
|
|
A bare
|
|
.I expr
|
|
implies motion in the current direction.
|
|
.PP
|
|
Text 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
|
|
is a list of text items:
|
|
.EX
|
|
\f2 text-item\fP:
|
|
"..." \f2positioning ...\fP
|
|
sprintf("\f2format\fP", \f2expr\fP, \f2...\fP) \f2positioning ...\fP
|
|
\f2 positioning\fP:
|
|
center ljust rjust above below
|
|
.EE
|
|
If there are multiple text items for some primitive,
|
|
they are arranged vertically and centered except as qualified.
|
|
Positioning requests apply to each item independently.
|
|
Text items may contain
|
|
.I troff
|
|
commands for size and font changes, local motions, etc.,
|
|
but make sure that these are balanced
|
|
so that the entering state is restored before exiting.
|
|
.PP
|
|
A position is ultimately an
|
|
.I x,y
|
|
coordinate pair, but it may be specified in other ways.
|
|
.EX
|
|
\f2 position\fP:
|
|
\f2expr, expr\fP
|
|
\f2place\fP ± \f2expr, expr\fP
|
|
\f2place\fP ± ( \f2expr, expr\fP )
|
|
( \f2position\fP,\f2 position\fP ) \f2x\fP\fR from one, \f2y\fP\fR the other\fP
|
|
\f2expr\fP [\fLof the way\fP] between \f2position\fP and \f2position\fP
|
|
\f2expr\fP < \f2position\fP , \f2position\fP >
|
|
( \f2position\fP )
|
|
.EE
|
|
.PP
|
|
.EX
|
|
\f2 place\fP:
|
|
\f2placename\fP \f2optional-corner\fP
|
|
\f2corner\fP of \f2placename\fP
|
|
\f2nth\fP \f2primitive\fP \f2optional-corner\fP
|
|
\f2corner\fP of \f2nth\fP \f2primitive\fP
|
|
Here
|
|
.EE
|
|
An
|
|
.IR optional-corner
|
|
is one of the eight compass points
|
|
or the center or the start or end of a primitive.
|
|
.EX
|
|
\f2 optional-corner\fP:
|
|
.n .e .w .s .ne .se .nw .sw .c .start .end
|
|
\f2 corner\fP:
|
|
top bot left right start end
|
|
.EE
|
|
Each object in a picture has an ordinal number;
|
|
.IR nth
|
|
refers to this.
|
|
.EX
|
|
\f2 nth\fP:
|
|
\f2n\fPth\f2, n\fPth last
|
|
.EE
|
|
.PP
|
|
The built-in variables and their default values are:
|
|
.EX
|
|
.ta .5i 2.5i
|
|
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
|
|
textwid 0 textht 0
|
|
arrowwid 0.05 arrowht 0.1
|
|
dashwid 0.1 arrowhead 2
|
|
scale 1
|
|
.EE
|
|
These may be changed at any time,
|
|
and the new values remain in force from picture to picture until changed again
|
|
or reset by a
|
|
.L reset
|
|
statement.
|
|
Variables changed within
|
|
.B [
|
|
and
|
|
.B ]
|
|
revert to their previous value upon exit from the block.
|
|
Dimensions are divided by
|
|
.B scale
|
|
during output.
|
|
.PP
|
|
Expressions in
|
|
.I pic
|
|
are evaluated in floating point.
|
|
All numbers representing dimensions are taken to be in inches.
|
|
.EX
|
|
\f2 expr\fP:
|
|
\f2expr\fP \f2op\fP \f2expr\fP
|
|
- \f2expr\fP
|
|
! \f2expr\fP
|
|
( \f2expr\fP )
|
|
variable
|
|
number
|
|
\f2place\fP .x \f2place\fP .y \f2place\fP .ht \f2place\fP .wid \f2place\fP .rad
|
|
sin(\f2expr\fP) cos(\f2expr\fP) atan2(\f2expr,expr\fP) log(\f2expr\fP) exp(\f2expr\fP)
|
|
sqrt(\f2expr\fP) max(\f2expr,expr\fP) min(\f2expr,expr\fP) int(\f2expr\fP) rand()
|
|
\f2 op\fP:
|
|
+ - * / % < <= > >= == != && ||
|
|
.EE
|
|
.PP
|
|
The
|
|
.B define
|
|
and
|
|
.B undef
|
|
statements are not part of the grammar.
|
|
.EX
|
|
define \f2name\fP { \f2replacement text\fP }
|
|
undef \f2name\fP
|
|
.EE
|
|
Occurrences of
|
|
.BR $1 ,
|
|
.BR $2 ,
|
|
etc.,
|
|
in the replacement text
|
|
will be replaced by the corresponding arguments if
|
|
.I name
|
|
is invoked as
|
|
.EX
|
|
\f2name\fP(\f2arg1\fP, \f2arg2\fP, ...)
|
|
.EE
|
|
Non-existent arguments are replaced by null strings.
|
|
Replacement text
|
|
may contain newlines.
|
|
The
|
|
.B undef
|
|
statement removes the definition of a macro.
|
|
.PP
|
|
.I Tpic
|
|
is a
|
|
.MR tex 1
|
|
preprocessor that accepts
|
|
.IR pic
|
|
language.
|
|
It produces Tex commands that define a box called
|
|
.BR \egraph ,
|
|
which contains the picture.
|
|
The box may be output this way:
|
|
.IP
|
|
.L
|
|
\ecenterline{\ebox\egraph}
|
|
.PP
|
|
.I Svgpic
|
|
accepts
|
|
.IR pic
|
|
language and produces a Scalable Vector Graphics (SVG) image
|
|
suitable for use in HTML documents.
|
|
.SH EXAMPLES
|
|
.EX
|
|
arrow "input" above; box "process"; arrow "output" above
|
|
move
|
|
A: ellipse
|
|
circle rad .1 with .w at A.e
|
|
circle rad .05 at 0.5 <A.c, A.ne>
|
|
circle rad .065 at 0.5 <A.c, A.ne>
|
|
spline from last circle.nw left .25 then left .05 down .05
|
|
arc from A.c to A.se rad 0.5
|
|
for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 }
|
|
.EE
|
|
.PP
|
|
.PS
|
|
arrow "input" above; box "process"; arrow "output" above
|
|
move
|
|
A: ellipse
|
|
circle rad .1 with .w at A.e
|
|
circle rad .05 at 0.5 <A.c, A.ne>
|
|
circle rad .065 at 0.5 <A.c, A.ne>
|
|
spline from last circle.nw left .25 then left .05 down .05
|
|
arc from A.c to A.se rad 0.5
|
|
for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 }
|
|
.PE
|
|
.SH SOURCE
|
|
.B \*9/src/cmd/pic
|
|
.SH "SEE ALSO"
|
|
.IR grap (1),
|
|
.MR doctype 1 ,
|
|
.MR troff 1
|
|
.br
|
|
B. W. Kernighan,
|
|
``PIC\(ema Graphics Language for Typesetting'',
|
|
.I
|
|
Unix Research System Programmer's Manual,
|
|
Tenth Edition, Volume 2
|
|
.SH BUGS
|
|
.I Svgpic
|
|
is only lightly tested.
|
|
It should handle troff commands in text output.
|