2 Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc.
4 Permission is granted to make and distribute verbatim copies of
5 this manual provided the copyright notice and this permission notice
6 are preserved on all copies.
8 Permission is granted to copy and distribute modified versions of this
9 manual under the conditions for verbatim copying, provided that the
10 entire resulting derived work is distributed under the terms of a
11 permission notice identical to this one.
13 Permission is granted to copy and distribute translations of this
14 manual into another language, under the above conditions for modified
15 versions, except that this permission notice may be included in
16 translations approved by the Free Software Foundation instead of in
19 .\" Like TP, but if specified indent is more than half
20 .\" the current line-length - indent, use the default indent.
22 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
25 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
29 .\" The BSD man macros can't handle " in arguments to font change macros,
30 .\" so use \(ts instead of ".
32 .TH PIC 1 "27 June 2001" "Groff Version 1.17.2"
34 pic \- compile pictures for troff or TeX
55 This manual page describes the GNU version of
57 which is part of the groff document formatting system.
59 compiles descriptions of pictures embedded within
61 or \*(tx input files into commands that are understood by \*(tx or
63 Each picture starts with a line beginning with
65 and ends with a line beginning with
71 is passed through without change.
73 It is the user's responsibility to provide appropriate definitions of the
78 When the macro package being used does not supply such definitions
79 (for example, old versions of \-ms),
80 appropriate definitions can be obtained with
82 these will center each picture.
84 Options that do not take arguments may be grouped behind a single
88 can be used to mark the end of the options.
91 refers to the standard input.
98 even when followed by a character other than space or newline.
101 Safer mode; do not execute
104 This can be useful when operating on untrustworthy input.
108 Unsafe mode; revert the default option
112 Don't use the groff extensions to the troff drawing commands.
113 You should use this if you are using a postprocessor that doesn't support
115 The extensions are described in
121 not to use zero-length lines to draw dots in troff mode.
127 Be more compatible with
133 are not passed through transparently.
136 are passed through with the initial
140 A line beginning with
142 is given special treatment:
143 it takes an optional integer argument specifying
144 the line thickness (pen size) in milliinches;
145 a missing argument restores the previous line thickness;
146 the default line thickness is 8 milliinches.
147 The line thickness thus specified takes effect only
148 when a non-negative line thickness has not been
149 specified by use of the
151 attribute or by setting the
156 Print the version number.
159 In \*(tx mode draw dots using zero-length lines.
161 The following options supported by other versions of
166 Draw all lines using the \eD escape sequence.
171 Generate output for the
175 This is unnecessary because the
179 is device-independent.
181 This section describes only the differences between GNU
183 and the original version of
185 Many of these differences also apply to newer versions of Unix
189 \*(tx mode is enabled by the
194 will define a vbox called
197 You must yourself print that vbox using, for example, the command
201 \ecenterline{\ebox\egraph}
204 Actually, since the vbox has a height of zero this will produce
205 slightly more vertical space above the picture than below it;
209 \ecenterline{\eraise 1em\ebox\egraph}
214 You must use a \*(tx driver that supports the
220 are passed through transparently; a
222 is added to the end of the line to avoid unwanted spaces.
223 You can safely use this feature to change fonts or to
226 Anything else may well produce undesirable results; use at your own risk.
227 Lines beginning with a period are not given any special treatment.
230 \fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\fR \fBto\fR \fIexpr2\fR \
231 [\fBby\fR [\fB*\fR]\fIexpr3\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR
238 is less than or equal to
248 is not given, increment
257 will instead be multiplied by
260 can be any character not occurring in
263 \fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \
264 [\fBelse\fR \fIY\fR \fIif-false\fR \fIY\fR]
267 if it is non-zero then do
272 can be any character not occurring in
275 can be any character not occurring in
278 \fBprint\fR \fIarg\fR\|.\|.\|.
279 Concatenate the arguments and print as a line on stderr.
282 must be an expression, a position, or text.
283 This is useful for debugging.
285 \fBcommand\fR \fIarg\fR\|.\|.\|.
286 Concatenate the arguments
287 and pass them through as a line to troff or\*(tx.
290 must be an expression, a position, or text.
291 This has a similar effect to a line beginning with
295 but allows the values of variables to be passed through.
297 \fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR
302 can be any character not occurring in
305 \fBcopy\fR \fB"\fIfilename\fB"\fR
308 at this point in the file.
310 \fBcopy\fR [\fB"\fIfilename\fB"\fR] \fBthru\fR \fIX\fR \fIbody\fR \fIX\fR \
311 [\fBuntil\fR \fB"\fIword\*(ic\fB"\fR]
314 \fBcopy\fR [\fB"\fIfilename\fB"\fR] \fBthru\fR \fImacro\fR \
315 [\fBuntil\fR \fB"\fIword\*(ic\fB"\fR]
318 once for each line of
320 the line is split into blank-delimited words,
333 is not given, lines are taken from the current input up to
338 lines will be read only until a line the first word of which is
340 that line will then be discarded.
342 can be any character not occurring in
350 copy thru % circle at ($1,$2) % until "END"
376 The commands to be performed for each line can also be taken
377 from a macro defined earlier by giving the name of the macro
385 \fBreset\fI variable1\fB,\fI variable2 .\^.\^.
386 Reset pre-defined variables
389 \&.\^.\^. to their default values.
390 If no arguments are given, reset all pre-defined variables
391 to their default values.
392 Note that assigning a value to
394 also causes all pre-defined variables that control dimensions
395 to be reset to their default values times the new value of scale.
397 \fBplot\fR \fIexpr\fR [\fB"\fItext\*(ic\fB"\fR]
398 This is a text object which is constructed by using
400 as a format string for sprintf
405 is omitted a format string of
408 Attributes can be specified in the same way as for a normal text
410 Be very careful that you specify an appropriate format string;
412 does only very limited checking of the string.
413 This is deprecated in favour of
421 must already be defined,
424 will be changed only in the innermost block in which it is defined.
427 defines the variable in the current block if it is not already defined there,
428 and then changes the value in the current block.)
430 Arguments of the form
434 are also allowed to be of the form
440 can contain balanced occurrences of
446 or imbalanced occurrences of
451 The syntax for expressions has been significantly extended:
466 (base 10, ie 10\v'-.4m'\fIx\*(ic\fR\v'.4m')
473 (return a random number between 0 and 1)
476 (return a random number between 1 and
481 (set the random number seed)
505 \fB"\fIstr1\*(ic\fB" == "\fIstr2\*(ic\fB"\fR
507 \fB"\fIstr1\*(ic\fB" != "\fIstr2\*(ic\fB"\fR
510 String comparison expressions must be parenthesised in some contexts
516 is acceptable as an attribute;
521 is the current direction.
526 means draw a line 2 inches long in the current direction.
528 The maximum width and height of the picture are taken from the variables
532 Initially these have values 8.5 and 11.
534 Scientific notation is allowed for numbers.
541 Text attributes can be compounded.
549 There is no limit to the depth to which blocks can be examined.
553 [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
556 circle at last [\^].A.B.C
560 Arcs now have compass points
561 determined by the circle of which the arc is a part.
563 Circles and arcs can be dotted or dashed.
564 In \*(tx mode splines can be dotted or dashed.
566 Boxes can have rounded corners.
569 attribute specifies the radius of the quarter-circles at each corner.
574 attribute is given, a radius of
580 A box with rounded corners can be dotted or dashed.
584 line can have a second argument specifying a maximum height for
586 If the width of zero is specified the width will be ignored in computing
587 the scaling factor for the picture.
590 will always scale a picture by the same amount vertically as horizontally.
591 This is different from the
595 which may scale a picture by a different amount vertically than
596 horizontally if a height is specified.
598 Each text object has an invisible box associated with it.
599 The compass points of a text object are determined by this box.
600 The implicit motion associated with the object is also determined
602 The dimensions of this box are taken from the width and height attributes;
603 if the width attribute is not supplied then the width will be taken to be
605 if the height attribute is not supplied then the height will be taken to be
606 the number of text strings associated with the object
615 In places where a quoted text string can be used,
616 an expression of the form
618 .BI sprintf(\(ts format \(ts,\ arg ,\fR.\|.\|.\fB)
621 this will produce the arguments formatted according to
623 which should be a string as described in
625 appropriate for the number of arguments supplied,
634 The thickness of the lines used to draw objects is controlled by the
637 This gives the thickness of lines in points.
638 A negative value means use the default thickness:
639 in \*(tx output mode, this means use a thickness of 8 milliinches;
640 in \*(tx output mode with the
642 option, this means use the line thickness specified by
645 in troff output mode, this means use a thickness proportional
647 A zero value means draw the thinnest possible line supported by
649 Initially it has a value of -1.
656 .B circle thickness 1.5
659 would draw a circle using a line with a thickness of 1.5 points.
660 The thickness of lines is not affected by the
663 variable, nor by the width or height given in the
667 Boxes (including boxes with rounded corners),
668 circles and ellipses can be filled by giving then an attribute of
670 This takes an optional argument of an expression with a value between
671 0 and 1; 0 will fill it with white, 1 with black, values in between
672 with a proportionally gray shade.
673 A value greater than 1 can also be used:
674 this means fill with the
675 shade of gray that is currently being used for text and lines.
676 Normally this will be black, but output devices may provide
677 a mechanism for changing this.
678 Without an argument, then the value of the variable
681 Initially this has a value of 0.5.
682 The invisible attribute does not affect the filling of objects.
683 Any text associated with a filled object will be added after the
684 object has been filled, so that the text will not be obscured
687 Arrow heads will be drawn as solid triangles if the variable
689 is non-zero and either \*(tx mode is enabled or
692 option has been given.
699 is device-independent.
702 option is therefore redundant.
703 All numbers are taken to be in inches; numbers are never interpreted
704 to be in troff machine units.
709 This will only work when the postprocessor is
711 Any text associated with an object having the
713 attribute will be rotated about the center of the object
714 so that it is aligned in the direction from the start point
715 to the end point of the object.
716 Note that this attribute will have no effect for objects whose start and
717 end points are coincident.
726 is a single token: no space is allowed between the
735 line from `i'th box.nw to `i+1'th box.se
739 To obtain a stand-alone picture from a
749 configuration commands may be added at the beginning of the file, but no
753 It is necessary to feed this file into
755 without adding any page information, so you must check which
759 requests are actually called.
760 For example, the mm macro package adds a page number, which is very
762 At the moment, calling standard
764 without any macro package works.
765 Alternatively, you can define your own requests, e.g. to do nothing:
779 itself does not provide direct conversion into other graphics file
781 But there are lots of possibilities if you first transform your picture
782 into PostScript\*R format using the
788 lacks BoundingBox information it is not very useful by itself, but it
789 may be fed into other conversion programs, usually named
794 Moreover, the PostScript interpreter
797 has built-in graphics conversion devices that are called with the option
800 .BI "gs -sDEVICE=" <devname>
808 for a list of the available devices.
810 As the Encapsulated PostScript File Format
812 is getting more and more important, and the conversion wasn't regarded
813 trivial in the past you might be interested to know that there is a
814 conversion tool named
816 which does the right job.
817 It is much better than the tool
822 For bitmapped graphic formats, you should use
824 the resulting (intermediate)
826 file can be then converted to virtually any graphics format using the tools
831 .Tp \w'\fB/usr/share/groff/1.17.2/tmac/pic.tmac'u+3n
833 /usr/share/groff/1.17.2/tmac/pic.tmac
834 Example definitions of the
852 PIC \(em A Graphics Language for Typesetting (User Manual).
853 AT&T Bell Laboratories, Computing Science Technical Report No.\ 116
854 <URL:http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz>
858 is available from CTAN mirrors, e.g.
860 <ftp://ftp.dante.de/tex-archive/support/ps2eps/>
862 W. Richard Stevens - Turning PIC Into HTML
864 <http://www.kohala.com/start/troff/pic2html.html>
866 W. Richard Stevens - Examples of picMacros
868 <http://www.kohala.com/start/troff/pic.examples.ps>
871 Input characters that are illegal for
875 code 0 or between 013 and 037 octal or between 0200 and 0237 octal)
876 are rejected even in \*(tx mode.
878 The interpretation of
880 is incompatible with the pic in 10th edition Unix,
881 which interprets 0 as black and 1 as white.
883 PostScript\*R is a registered trademark of Adobe Systems Incorporation.
OSDN Git Service
