diff options
Diffstat (limited to 'contrib/groff/pic/pic.man')
| -rw-r--r-- | contrib/groff/pic/pic.man | 883 |
1 files changed, 0 insertions, 883 deletions
diff --git a/contrib/groff/pic/pic.man b/contrib/groff/pic/pic.man deleted file mode 100644 index 311a04e..0000000 --- a/contrib/groff/pic/pic.man +++ /dev/null @@ -1,883 +0,0 @@ -.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@/tmac.pic'u+3n -.B -@MACRODIR@/tmac.pic -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. |
