diff options
Diffstat (limited to 'pic/pic.1')
| -rw-r--r-- | pic/pic.1 | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/pic/pic.1 b/pic/pic.1 new file mode 100644 index 0000000000000..2df6db736aa90 --- /dev/null +++ b/pic/pic.1 @@ -0,0 +1,368 @@ +.\" +.\" Changes by Gunnar Ritter, Freiburg i. Br., Germany, October 2005. +.\" +.\" Derived from Plan 9 v4 /opt/unix/plan9v4/sys/man/1/pic +.\" +.\" Copyright (C) 2003, Lucent Technologies Inc. and others. +.\" All Rights Reserved. +.\" +.\" Distributed under the terms of the Lucent Public License Version 1.02. +.\" +.\" Sccsid @(#)pic.1 1.7 (gritter) 2/2/07 +.TH PIC 1 "2/2/07" "Heirloom Documentation Tools" "User Commands" +.\".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 \- troff preprocessor for drawing pictures +.SH SYNOPSIS +\fBpic\fR [\fB\-SU\fR] [\fIfiles\fR] +.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: +.sp +.RS +.nf +\&.PS \f2optional-width\fP \f2optional-height\fP +\f2element-list\fP +\&.PE +.RE +.fi +.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 +Arbitrary whitespace can be inserted between the dot and the token PS, PE or +PF. +Macros with these names are ignored by pic if "'" is used instead of ".". +.PP +An +.IR element-list +is a list of elements: +.sp +.nf + \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 +.fi +.sp +.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: +.sp +.nf + box circle ellipse arc line arrow spline move \f2text-list\fP +.fi +.sp +.B arrow +is a synonym for +.BR "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. +.sp +.nf +.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 +.fi +.sp +Missing attributes and values are filled in from defaults. +Not all attributes make sense for all primitives; +irrelevant ones are silently ignored. +The attribute +.B at +causes the geometrical center to be put at the specified place; +.B with +causes the position on the object to be put at the specified place. +For lines, splines and arcs, +.B height +and +.B 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: +.sp +.nf +\f2 text-item\fP: + "..." \f2positioning ...\fP + sprintf("\f2format\fP", \f2expr\fP, \f2...\fP) \f2positioning ...\fP +\f2 positioning\fP: + center ljust rjust above below +.fi +.sp +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. +.sp +.nf +\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 [\fRof the way\fP] between \f2position\fP and \f2position\fP + \f2expr\fP < \f2position\fP , \f2position\fP > + ( \f2position\fP ) +.sp +\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 +.fi +.sp +An +.IR optional-corner +is one of the eight compass points +or the center or the start or end of a primitive. +.sp +.nf +\f2 optional-corner\fP: + .n .e .w .s .ne .se .nw .sw .c .start .end +\f2 corner\fP: + top bot left right start end +.fi +.sp +Each object in a picture has an ordinal number; +.IR nth +refers to this. +.sp +.nf +\f2 nth\fP: + \f2n\fPth\f2, n\fPth last +.fi +.sp +.PP +The built-in variables and their default values are: +.sp +.nf +.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 +.fi +.sp +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. +.sp +.nf +\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: + + \- * / % < <= > >= == != && || +.fi +.sp +.PP +The +.B define +and +.B undef +statements are not part of the grammar. +.sp +.nf + define \f2name\fP { \f2replacement text\fP } + undef \f2name\fP +.fi +.sp +Occurrences of +.BR $1 , +.BR $2 , +etc., +in the replacement text +will be replaced by the corresponding arguments if +.I name +is invoked as +.sp +.nf + \f2name\fP(\f2arg1\fP, \f2arg2\fP, ...) +.fi +.sp +Non-existent arguments are replaced by null strings. +Replacement text +may contain newlines. +The +.B undef +statement removes the definition of a macro. +.PP +The +.B \-S +command line option will disable execution of +.RB ` sh ' +command elements. +.B \-U +reverts the effect of a previous +.IR \-S . +.\".SH EXAMPLES +.\".sp +.\".nf +.\"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 } +.\".fi +.\".sp +.\".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 troff (1) +.br +B. W. Kernighan, +``PIC\(ema Graphics Language for Typesetting'', +.I +Unix Research System Programmer's Manual, +Tenth Edition, Volume 2 |