diff options
Diffstat (limited to 'contrib/groff/src/preproc/pic/pic.man')
| -rw-r--r-- | contrib/groff/src/preproc/pic/pic.man | 221 |
1 files changed, 180 insertions, 41 deletions
diff --git a/contrib/groff/src/preproc/pic/pic.man b/contrib/groff/src/preproc/pic/pic.man index ea53074..406246f 100644 --- a/contrib/groff/src/preproc/pic/pic.man +++ b/contrib/groff/src/preproc/pic/pic.man @@ -1,5 +1,5 @@ .ig -Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc. +Copyright (C) 1989-2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -16,30 +16,43 @@ 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 +.el .ds tx TeX +. .ie \n(.g .ds ic \/ -.el .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 @@ -49,9 +62,12 @@ the original English. ] [ .I filename -\&.\|.\|. +\&.\|.\|.\& ] +. +. .SH DESCRIPTION +. This manual page describes the GNU version of .BR pic , which is part of the groff document formatting system. @@ -80,7 +96,10 @@ When the macro package being used does not supply such definitions 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 @@ -89,6 +108,7 @@ can be used to mark the end of the options. A filename of .B \- refers to the standard input. +. .TP .B \-C Recognize @@ -96,6 +116,7 @@ Recognize and .B .PE even when followed by a character other than space or newline. +. .TP .B \-S Safer mode; do not execute @@ -103,10 +124,12 @@ Safer mode; do not execute 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. @@ -119,9 +142,11 @@ The 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 @@ -151,21 +176,26 @@ specified by use of the 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 @@ -177,15 +207,24 @@ This is unnecessary because the 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 +A complete documentation is available in the file .LP +.RS +.B @DOCDIR@/pic.ms +.RE +. +.SS \*(tx mode +. \*(tx mode is enabled by the .B \-t option. @@ -225,7 +264,9 @@ 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 @@ -259,6 +300,7 @@ will instead be multiplied by .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] @@ -274,6 +316,7 @@ can be any character not occurring in .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. @@ -281,18 +324,20 @@ 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. +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 . +.B .\& or .BR \e , but allows the values of variables to be passed through. +. .TP \fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR Pass @@ -301,11 +346,13 @@ 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] @@ -377,12 +424,13 @@ 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 .\^.\^. +\fBreset\fI variable1\fR[\fB,\fR]\fI variable2 .\^.\^. Reset pre-defined variables .IR variable1 , .I variable2 @@ -393,6 +441,7 @@ 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 @@ -412,24 +461,48 @@ Be very careful that you specify an appropriate format string; does only very limited checking of the string. This is deprecated in favour of .BR sprintf . +. .TP -.IB variable := expr +.IB variable\ := \ expr This is similar to .B = except .I variable must already be defined, -and the value of +and +.I expr +will be assigned to .I variable -will be changed only in the innermost block in which it is defined. +without creating a variable local to the current block. (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.) +and then changes the value in the current block only.) +For example, the following: +.RS +.IP +.ft B +.nf +\&.PS +x = 3 +y = 3 +[ + x := 5 + y = 5 +] +print x " " y +\&.PE +.ft +.fi +.RE +.IP +prints +.BR 5\ 3 . +. .LP Arguments of the form .IP -.IR X\ anything\ X +.I X anything X .LP are also allowed to be of the form .IP @@ -447,8 +520,11 @@ or imbalanced occurrences of .B { and .BR } . +. .SS Expressions +. The syntax for expressions has been significantly extended: +. .LP .IB x\ ^\ y (exponentiation) @@ -463,7 +539,9 @@ The syntax for expressions has been significantly extended: (base 10) .br .BI exp( x ) -(base 10, ie 10\v'-.4m'\fIx\*(ic\fR\v'.4m') +(base 10, ie +.ie t 10\v'-.4m'\fIx\*(ic\fR\v'.4m') +.el 10^\fIx\fR) .br .BI sqrt( x ) .br @@ -506,11 +584,13 @@ deprecated) .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; @@ -523,13 +603,19 @@ For example .IP .B line 2i .LP -means draw a line 2 inches long in the current direction. +means draw a line 2\ inches long in the current direction. +The `i' (or `I') character is ignored; to use another measurement unit, +set the +.I scale +variable to an appropriate value. +. .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 @@ -537,6 +623,7 @@ For example .B x = 5e\-2 .RE +. .LP Text attributes can be compounded. For example, @@ -545,6 +632,7 @@ For example, "foo" above ljust .RE is legal. +. .LP There is no limit to the depth to which blocks can be examined. For example, @@ -556,12 +644,15 @@ For example, 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 @@ -576,8 +667,9 @@ attribute is given, a radius of is used. Initially, .B boxrad -has a value of 0. +has a value of\ 0. A box with rounded corners can be dotted or dashed. +. .LP The .B .PS @@ -587,13 +679,15 @@ 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. +will always scale a picture by the same amount vertically as well 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. @@ -611,8 +705,9 @@ Initially and .B textht have a value of 0. +. .LP -In places where a quoted text string can be used, +In (almost all) places where a quoted text string can be used, an expression of the form .IP .BI sprintf(\(ts format \(ts,\ arg ,\fR.\|.\|.\fB) @@ -622,14 +717,8 @@ 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. +appropriate for the number of arguments supplied. +. .LP The thickness of the lines used to draw objects is controlled by the .B linethick @@ -663,9 +752,10 @@ value of the 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 +circles and ellipses can be filled by giving them 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 @@ -683,16 +773,48 @@ 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 +Three additional modifiers are available to specify colored objects: +.BR outline [ d ] +sets the color of the outline, +.B shaded +the fill color, and +.BR colo [ u ] r [ ed ] +sets both. +All three keywords expect a suffix specifying the color, for example +.RS +.LP +.B circle shaded """green""" outline """black""" +.RE +.LP +Currently, color support isn't available in \*(tx mode. +Predefined color names for +.B groff +are in the device macro files, for example +.BR ps.tmac ; +additional colors can be defined with the +.B .defcolor +request (see the manual page of +.BR @g@troff (@MAN1EXT@) +for more details). +.LP +.B pic +assumes that at the beginning of a picture both glyph and fill color are +set to the default value. +. .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. +is non-zero and either \*(tx mode is enabled or the +.B \-n +option has not been given. Initially .B arrowhead -has a value of 1. +has a value of\ 1. +Note that solid arrow heads are always filled with the current outline +color. +. .LP The troff output of .B pic @@ -702,11 +824,12 @@ The 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 +This will only work if the postprocessor is .BR grops . Any text associated with an object having the .B aligned @@ -715,6 +838,7 @@ 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 @@ -729,13 +853,17 @@ and the .BR th . For example, .IP -.B +.ft B .nf for i = 1 to 4 do { line from `i'th box.nw to `i+1'th box.se } +.ft .fi +. +. .SH CONVERSION +. To obtain a stand-alone picture from a .B pic file, enclose your @@ -749,6 +877,7 @@ requests; 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 @@ -774,6 +903,7 @@ Alternatively, you can define your own requests, e.g. to do nothing: .ft .fi .RE +. .LP .B groff itself does not provide direct conversion into other graphics file @@ -806,6 +936,7 @@ Call .RE .LP for a list of the available devices. +. .LP As the Encapsulated PostScript File Format .B EPS @@ -827,7 +958,10 @@ 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 @@ -836,7 +970,10 @@ Example definitions of the and .B PE macros. +. +. .SH "SEE ALSO" +. .BR @g@troff (@MAN1EXT@), .BR groff_out (@MAN5EXT@), .BR tex (1), @@ -851,7 +988,7 @@ Tpic: Pic for \*(tx 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> +<http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz> (revised May, 1991). .LP .B ps2eps @@ -866,14 +1003,16 @@ W. Richard Stevens - Turning PIC Into HTML 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 +. +Input characters that are invalid 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. +code 0, or 013 octal, or between 015 and 037 octal, or between 0200 and 0237 +octal) are rejected even in \*(tx mode. .LP The interpretation of .B fillval |
