diff options
Diffstat (limited to 'contrib/groff/src/preproc/pic/pic.man')
| -rw-r--r-- | contrib/groff/src/preproc/pic/pic.man | 883 |
1 files changed, 883 insertions, 0 deletions
diff --git a/contrib/groff/src/preproc/pic/pic.man b/contrib/groff/src/preproc/pic/pic.man new file mode 100644 index 0000000..e187021 --- /dev/null +++ b/contrib/groff/src/preproc/pic/pic.man @@ -0,0 +1,883 @@ +.ig \"-*- nroff -*- +Copyright (C) 1989-2000 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be included in +translations approved by the Free Software Foundation instead of in +the original English. +.. +.\" Like TP, but if specified indent is more than half +.\" the current line-length - indent, use the default indent. +.de Tp +.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP +.el .TP "\\$1" +.. +.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X +.el .ds tx TeX +.ie \n(.g .ds ic \/ +.el .ds ic \^ +.\" The BSD man macros can't handle " in arguments to font change macros, +.\" so use \(ts instead of ". +.tr \(ts" +.TH @G@PIC @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +@g@pic \- compile pictures for troff or TeX +.SH SYNOPSIS +.B @g@pic +[ +.B \-nvCSU +] +[ +.I filename +\&.\|.\|. +] +.br +.B @g@pic +.B \-t +[ +.B \-cvzCSU +] +[ +.I filename +\&.\|.\|. +] +.SH DESCRIPTION +This manual page describes the GNU version of +.BR pic , +which is part of the groff document formatting system. +.B pic +compiles descriptions of pictures embedded within +.B troff +or \*(tx input files into commands that are understood by \*(tx or +.BR troff . +Each picture starts with a line beginning with +.B .PS +and ends with a line beginning with +.BR .PE . +Anything outside of +.B .PS +and +.B .PE +is passed through without change. +.LP +It is the user's responsibility to provide appropriate definitions of the +.B PS +and +.B PE +macros. +When the macro package being used does not supply such definitions +(for example, old versions of \-ms), +appropriate definitions can be obtained with +.BR \-mpic : +these will center each picture. +.SH OPTIONS +Options that do not take arguments may be grouped behind a single +.BR \- . +The special option +.B \-\^\- +can be used to mark the end of the options. +A filename of +.B \- +refers to the standard input. +.TP +.B \-C +Recognize +.B .PS +and +.B .PE +even when followed by a character other than space or newline. +.TP +.B \-S +Safer mode; do not execute +.B sh +commands. +This can be useful when operating on untrustworthy input. +(enabled by default) +.TP +.B \-U +Unsafe mode; revert the default option +.BR \-S . +.TP +.B \-n +Don't use the groff extensions to the troff drawing commands. +You should use this if you are using a postprocessor that doesn't support +these extensions. +The extensions are described in +.BR groff_out (@MAN5EXT@). +The +.B \-n +option also causes +.B pic +not to use zero-length lines to draw dots in troff mode. +.TP +.B \-t +\*(tx mode. +.TP +.B \-c +Be more compatible with +.BR tpic . +Implies +.BR \-t . +Lines beginning with +.B \e +are not passed through transparently. +Lines beginning with +.B . +are passed through with the initial +.B . +changed to +.BR \e . +A line beginning with +.B .ps +is given special treatment: +it takes an optional integer argument specifying +the line thickness (pen size) in milliinches; +a missing argument restores the previous line thickness; +the default line thickness is 8 milliinches. +The line thickness thus specified takes effect only +when a non-negative line thickness has not been +specified by use of the +.B thickness +attribute or by setting the +.B linethick +variable. +.TP +.B \-v +Print the version number. +.TP +.B \-z +In \*(tx mode draw dots using zero-length lines. +.LP +The following options supported by other versions of +.B pic +are ignored: +.TP +.B \-D +Draw all lines using the \eD escape sequence. +.B pic +always does this. +.TP +.BI \-T \ dev +Generate output for the +.B troff +device +.IR dev . +This is unnecessary because the +.B troff +output generated by +.B pic +is device-independent. +.SH USAGE +This section describes only the differences between GNU +.B pic +and the original version of +.BR pic . +Many of these differences also apply to newer versions of Unix +.BR pic . +.SS \*(tx mode +.LP +\*(tx mode is enabled by the +.B \-t +option. +In \*(tx mode, +.B pic +will define a vbox called +.B \egraph +for each picture. +You must yourself print that vbox using, for example, the command +.RS +.LP +.B +\ecenterline{\ebox\egraph} +.RE +.LP +Actually, since the vbox has a height of zero this will produce +slightly more vertical space above the picture than below it; +.RS +.LP +.B +\ecenterline{\eraise 1em\ebox\egraph} +.RE +.LP +would avoid this. +.LP +You must use a \*(tx driver that supports the +.B tpic +specials, version 2. +.LP +Lines beginning with +.B \e +are passed through transparently; a +.B % +is added to the end of the line to avoid unwanted spaces. +You can safely use this feature to change fonts or to +change the value of +.BR \ebaselineskip . +Anything else may well produce undesirable results; use at your own risk. +Lines beginning with a period are not given any special treatment. +.SS Commands +.TP +\fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\fR \fBto\fR \fIexpr2\fR \ +[\fBby\fR [\fB*\fR]\fIexpr3\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR +Set +.I variable +to +.IR expr1 . +While the value of +.I variable +is less than or equal to +.IR expr2 , +do +.I body +and increment +.I variable +by +.IR expr3 ; +if +.B by +is not given, increment +.I variable +by 1. +If +.I expr3 +is prefixed by +.B * +then +.I variable +will instead be multiplied by +.IR expr3 . +.I X +can be any character not occurring in +.IR body . +.TP +\fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \ +[\fBelse\fR \fIY\fR \fIif-false\fR \fIY\fR] +Evaluate +.IR expr ; +if it is non-zero then do +.IR if-true , +otherwise do +.IR if-false . +.I X +can be any character not occurring in +.IR if-true . +.I Y +can be any character not occurring in +.IR if-false . +.TP +\fBprint\fR \fIarg\fR\|.\|.\|. +Concatenate the arguments and print as a line on stderr. +Each +.I arg +must be an expression, a position, or text. +This is useful for debugging. +.TP +\fBcommand\fR \fIarg\fR\|.\|.\|. +Concatenate the arguments +and pass them through as a line to troff or\*(tx. +Each +.I arg +must be an expression, a position, or text. +This has a similar effect to a line beginning with +.B . +or +.BR \e , +but allows the values of variables to be passed through. +.TP +\fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR +Pass +.I command +to a shell. +.I X +can be any character not occurring in +.IR command . +.TP +\fBcopy\fR \fB"\fIfilename\fB"\fR +Include +.I filename +at this point in the file. +.TP +\fBcopy\fR [\fB"\fIfilename\fB"\fR] \fBthru\fR \fIX\fR \fIbody\fR \fIX\fR \ +[\fBuntil\fR \fB"\fIword\*(ic\fB"\fR] +.ns +.TP +\fBcopy\fR [\fB"\fIfilename\fB"\fR] \fBthru\fR \fImacro\fR \ +[\fBuntil\fR \fB"\fIword\*(ic\fB"\fR] +This construct does +.I body +once for each line of +.IR filename ; +the line is split into blank-delimited words, +and occurrences of +.BI $ i +in +.IR body , +for +.I i +between 1 and 9, +are replaced by the +.IR i -th +word of the line. +If +.I filename +is not given, lines are taken from the current input up to +.BR .PE . +If an +.B until +clause is specified, +lines will be read only until a line the first word of which is +.IR word ; +that line will then be discarded. +.I X +can be any character not occurring in +.IR body . +For example, +.RS +.IP +.ft B +.nf +\&.PS +copy thru % circle at ($1,$2) % until "END" +1 2 +3 4 +5 6 +END +box +\&.PE +.ft +.fi +.RE +.IP +is equivalent to +.RS +.IP +.ft B +.nf +\&.PS +circle at (1,2) +circle at (3,4) +circle at (5,6) +box +\&.PE +.ft +.fi +.RE +.IP +The commands to be performed for each line can also be taken +from a macro defined earlier by giving the name of the macro +as the argument to +.BR thru . +.LP +.B reset +.br +.ns +.TP +\fBreset\fI variable1\fB,\fI variable2 .\^.\^. +Reset pre-defined variables +.IR variable1 , +.I variable2 +\&.\^.\^. to their default values. +If no arguments are given, reset all pre-defined variables +to their default values. +Note that assigning a value to +.B scale +also causes all pre-defined variables that control dimensions +to be reset to their default values times the new value of scale. +.TP +\fBplot\fR \fIexpr\fR [\fB"\fItext\*(ic\fB"\fR] +This is a text object which is constructed by using +.I text +as a format string for sprintf +with an argument of +.IR expr . +If +.I text +is omitted a format string of +.B "\(ts%g\(ts" +is used. +Attributes can be specified in the same way as for a normal text +object. +Be very careful that you specify an appropriate format string; +.B pic +does only very limited checking of the string. +This is deprecated in favour of +.BR sprintf . +.TP +.IB variable := expr +This is similar to +.B = +except +.I variable +must already be defined, +and the value of +.I variable +will be changed only in the innermost block in which it is defined. +(By contrast, +.B = +defines the variable in the current block if it is not already defined there, +and then changes the value in the current block.) +.LP +Arguments of the form +.IP +.IR X\ anything\ X +.LP +are also allowed to be of the form +.IP +.BI {\ anything\ } +.LP +In this case +.I anything +can contain balanced occurrences of +.B { +and +.BR } . +Strings may contain +.I X +or imbalanced occurrences of +.B { +and +.BR } . +.SS Expressions +The syntax for expressions has been significantly extended: +.LP +.IB x\ ^\ y +(exponentiation) +.br +.BI sin( x ) +.br +.BI cos( x ) +.br +.BI atan2( y , \ x ) +.br +.BI log( x ) +(base 10) +.br +.BI exp( x ) +(base 10, ie 10\v'-.4m'\fIx\*(ic\fR\v'.4m') +.br +.BI sqrt( x ) +.br +.BI int( x ) +.br +.B rand() +(return a random number between 0 and 1) +.br +.BI rand( x ) +(return a random number between 1 and +.IR x ; +deprecated) +.br +.BI srand( x ) +(set the random number seed) +.br +.BI max( e1 , \ e2 ) +.br +.BI min( e1 , \ e2 ) +.br +.BI ! e +.br +\fIe1\fB && \fIe2\fR +.br +\fIe1\fB || \fIe2\fR +.br +\fIe1\fB == \fIe2\fR +.br +\fIe1\fB != \fIe2\fR +.br +\fIe1\fB >= \fIe2\fR +.br +\fIe1\fB > \fIe2\fR +.br +\fIe1\fB <= \fIe2\fR +.br +\fIe1\fB < \fIe2\fR +.br +\fB"\fIstr1\*(ic\fB" == "\fIstr2\*(ic\fB"\fR +.br +\fB"\fIstr1\*(ic\fB" != "\fIstr2\*(ic\fB"\fR +.br +.LP +String comparison expressions must be parenthesised in some contexts +to avoid ambiguity. +.SS Other Changes +.LP +A bare expression, +.IR expr , +is acceptable as an attribute; +it is equivalent to +.IR dir\ expr , +where +.I dir +is the current direction. +For example +.IP +.B line 2i +.LP +means draw a line 2 inches long in the current direction. +.LP +The maximum width and height of the picture are taken from the variables +.B maxpswid +and +.BR maxpsht . +Initially these have values 8.5 and 11. +.LP +Scientific notation is allowed for numbers. +For example +.RS +.B +x = 5e\-2 +.RE +.LP +Text attributes can be compounded. +For example, +.RS +.B +"foo" above ljust +.RE +is legal. +.LP +There is no limit to the depth to which blocks can be examined. +For example, +.RS +.B +[A: [B: [C: box ]]] with .A.B.C.sw at 1,2 +.br +.B +circle at last [\^].A.B.C +.RE +is acceptable. +.LP +Arcs now have compass points +determined by the circle of which the arc is a part. +.LP +Circles and arcs can be dotted or dashed. +In \*(tx mode splines can be dotted or dashed. +.LP +Boxes can have rounded corners. +The +.B rad +attribute specifies the radius of the quarter-circles at each corner. +If no +.B rad +or +.B diam +attribute is given, a radius of +.B boxrad +is used. +Initially, +.B boxrad +has a value of 0. +A box with rounded corners can be dotted or dashed. +.LP +The +.B .PS +line can have a second argument specifying a maximum height for +the picture. +If the width of zero is specified the width will be ignored in computing +the scaling factor for the picture. +Note that GNU +.B pic +will always scale a picture by the same amount vertically as horizontally. +This is different from the +.SM DWB +2.0 +.B pic +which may scale a picture by a different amount vertically than +horizontally if a height is specified. +.LP +Each text object has an invisible box associated with it. +The compass points of a text object are determined by this box. +The implicit motion associated with the object is also determined +by this box. +The dimensions of this box are taken from the width and height attributes; +if the width attribute is not supplied then the width will be taken to be +.BR textwid ; +if the height attribute is not supplied then the height will be taken to be +the number of text strings associated with the object +times +.BR textht . +Initially +.B textwid +and +.B textht +have a value of 0. +.LP +In places where a quoted text string can be used, +an expression of the form +.IP +.BI sprintf(\(ts format \(ts,\ arg ,\fR.\|.\|.\fB) +.LP +can also be used; +this will produce the arguments formatted according to +.IR format , +which should be a string as described in +.BR printf (3) +appropriate for the number of arguments supplied, +using only the +.BR e , +.BR f , +.B g +or +.B % +format characters. +.LP +The thickness of the lines used to draw objects is controlled by the +.B linethick +variable. +This gives the thickness of lines in points. +A negative value means use the default thickness: +in \*(tx output mode, this means use a thickness of 8 milliinches; +in \*(tx output mode with the +.B -c +option, this means use the line thickness specified by +.B .ps +lines; +in troff output mode, this means use a thickness proportional +to the pointsize. +A zero value means draw the thinnest possible line supported by +the output device. +Initially it has a value of -1. +There is also a +.BR thick [ ness ] +attribute. +For example, +.RS +.LP +.B circle thickness 1.5 +.RE +.LP +would draw a circle using a line with a thickness of 1.5 points. +The thickness of lines is not affected by the +value of the +.B scale +variable, nor by the width or height given in the +.B .PS +line. +.LP +Boxes (including boxes with rounded corners), +circles and ellipses can be filled by giving then an attribute of +.BR fill [ ed ]. +This takes an optional argument of an expression with a value between +0 and 1; 0 will fill it with white, 1 with black, values in between +with a proportionally gray shade. +A value greater than 1 can also be used: +this means fill with the +shade of gray that is currently being used for text and lines. +Normally this will be black, but output devices may provide +a mechanism for changing this. +Without an argument, then the value of the variable +.B fillval +will be used. +Initially this has a value of 0.5. +The invisible attribute does not affect the filling of objects. +Any text associated with a filled object will be added after the +object has been filled, so that the text will not be obscured +by the filling. +.LP +Arrow heads will be drawn as solid triangles if the variable +.B arrowhead +is non-zero and either \*(tx mode is enabled or +the +.B \-x +option has been given. +Initially +.B arrowhead +has a value of 1. +.LP +The troff output of +.B pic +is device-independent. +The +.B \-T +option is therefore redundant. +All numbers are taken to be in inches; numbers are never interpreted +to be in troff machine units. +.LP +Objects can have an +.B aligned +attribute. +This will only work when the postprocessor is +.BR grops . +Any text associated with an object having the +.B aligned +attribute will be rotated about the center of the object +so that it is aligned in the direction from the start point +to the end point of the object. +Note that this attribute will have no effect for objects whose start and +end points are coincident. +.LP +In places where +.IB n th +is allowed +.BI ` expr 'th +is also allowed. +Note that +.B 'th +is a single token: no space is allowed between the +.B ' +and the +.BR th . +For example, +.IP +.B +.nf +for i = 1 to 4 do { + line from `i'th box.nw to `i+1'th box.se +} +.fi +.SH CONVERSION +To obtain a stand-alone picture from a +.B pic +file, enclose your +.B pic +code with +.B .PS +and +.B .PE +requests; +.B roff +configuration commands may be added at the beginning of the file, but no +.B roff +text. +.LP +It is necessary to feed this file into +.B groff +without adding any page information, so you must check which +.B .PS +and +.B .PE +requests are actually called. +For example, the mm macro package adds a page number, which is very +annoying. +At the moment, calling standard +.B groff +without any macro package works. +Alternatively, you can define your own requests, e.g. to do nothing: +.LP +.RS +.nf +.ft B +\&.de PS +\&.. +\&.de PE +\&.. +.ft +.fi +.RE +.LP +.B groff +itself does not provide direct conversion into other graphics file +formats. +But there are lots of possibilities if you first transform your picture +into PostScript\*R format using the +.B groff +option +.BR -Tps . +Since this +.IR ps -file +lacks BoundingBox information it is not very useful by itself, but it +may be fed into other conversion programs, usually named +.BI ps2 other +or +.BI psto other +or the like. +Moreover, the PostScript interpreter +.B ghostscript +.RB ( gs ) +has built-in graphics conversion devices that are called with the option +.LP +.RS +.BI "gs -sDEVICE=" <devname> +.RE +.LP +Call +.RS +.B gs --help +.RE +.LP +for a list of the available devices. +.LP +As the Encapsulated PostScript File Format +.B EPS +is getting more and more important, and the conversion wasn't regarded +trivial in the past you might be interested to know that there is a +conversion tool named +.B ps2eps +which does the right job. +It is much better than the tool +.B ps2epsi +packaged with +.BR gs . +.LP +For bitmapped graphic formats, you should use +.BR pstopnm ; +the resulting (intermediate) +.B PNM +file can be then converted to virtually any graphics format using the tools +of the +.B netpbm +package . +.SH FILES +.Tp \w'\fB@MACRODIR@/pic.tmac'u+3n +.B +@MACRODIR@/pic.tmac +Example definitions of the +.B PS +and +.B PE +macros. +.SH "SEE ALSO" +.BR @g@troff (@MAN1EXT@), +.BR groff_out (@MAN5EXT@), +.BR tex (1), +.BR gs (1), +.BR ps2eps (1), +.BR pstopnm (1), +.BR ps2epsi (1), +.BR pnm (5) +.LP +Tpic: Pic for \*(tx +.LP +Brian W. Kernighan, +PIC \(em A Graphics Language for Typesetting (User Manual). +AT&T Bell Laboratories, Computing Science Technical Report No.\ 116 +<URL:http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz> +(revised May, 1991). +.LP +.B ps2eps +is available from CTAN mirrors, e.g. +.br +<ftp://ftp.dante.de/tex-archive/support/ps2eps/> +.LP +W. Richard Stevens - Turning PIC Into HTML +.br +<http://www.kohala.com/start/troff/pic2html.html> +.LP +W. Richard Stevens - Examples of picMacros +.br +<http://www.kohala.com/start/troff/pic.examples.ps> +.SH BUGS +.LP +Input characters that are illegal for +.B groff +(ie those with +.SM ASCII +code 0 or between 013 and 037 octal or between 0200 and 0237 octal) +are rejected even in \*(tx mode. +.LP +The interpretation of +.B fillval +is incompatible with the pic in 10th edition Unix, +which interprets 0 as black and 1 as white. +.LP +PostScript\*R is a registered trademark of Adobe Systems Incorporation. |
