aboutsummaryrefslogtreecommitdiff
path: root/man/man1/pic.1
diff options
context:
space:
mode:
authorwkj <devnull@localhost>2004-05-16 08:07:11 +0000
committerwkj <devnull@localhost>2004-05-16 08:07:11 +0000
commitdfc67f9b6dbbf741f3ee7a87082398347fa9410a (patch)
treedec29fafafbfbbfbc3f2fb97b68817c5e6ad63cd /man/man1/pic.1
parent6cc703dc9a8154efe7d8fc0445656c8f44486f07 (diff)
downloadplan9port-dfc67f9b6dbbf741f3ee7a87082398347fa9410a.tar.gz
plan9port-dfc67f9b6dbbf741f3ee7a87082398347fa9410a.tar.bz2
plan9port-dfc67f9b6dbbf741f3ee7a87082398347fa9410a.zip
Bring in some more man pages.
Diffstat (limited to 'man/man1/pic.1')
-rw-r--r--man/man1/pic.1344
1 files changed, 344 insertions, 0 deletions
diff --git a/man/man1/pic.1 b/man/man1/pic.1
new file mode 100644
index 00000000..685de68f
--- /dev/null
+++ b/man/man1/pic.1
@@ -0,0 +1,344 @@
+.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 \- troff and tex preprocessors for drawing pictures
+.SH SYNOPSIS
+.B pic
+[
+.I files
+]
+.PP
+.B tpic
+[
+.I files
+]
+.SH DESCRIPTION
+.I Pic
+is a
+.IR 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
+.IR 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}
+.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 /sys/src/cmd/pic
+.SH "SEE ALSO"
+.IR grap (1),
+.IR doctype (1),
+.IR troff (1)
+.br
+B. W. Kernighan,
+``PIC\(ema Graphics Language for Typesetting'',
+.I
+Unix Research System Programmer's Manual,
+Tenth Edition, Volume 2