man/man1/pic.1 - plan9 - Git at Google

 .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
 ]
 .PP
 .B svgpic
 [
 .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}
 .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),
 .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
 .SH BUGS
 .I Svgpic
 is only lightly tested.
 It should handle troff commands in text output.
	.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
	]
	.PP
	.B svgpic
	[
	.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}
	.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+.025i,.01i 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+.025i,.01i down i/50 }
	.PE
	.SH SOURCE
	.B \*9/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
	.SH BUGS
	.I Svgpic
	is only lightly tested.
	It should handle troff commands in text output.