View Source: pic(1) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
PIC
!!!PIC
NAME
SYNOPSIS
DESCRIPTION
OPTIONS
USAGE
CONVERSION
FILES
SEE ALSO
BUGS
----
!!NAME


pic - compile pictures for troff or TeX
!!SYNOPSIS


__pic__ [[ __-nvCSU__ ] [[ ''filename'' ... ]__
pic -t__ [[ __-cvzCSU__ ] [[ ''filename'' ...
]
!!DESCRIPTION


This manual page describes the GNU version of __pic__,
which is part of the groff document formatting system.
__pic__ compiles descriptions of pictures embedded within
__troff__ or TEX input files into commands that are
understood by TEX or __troff__. Each picture starts with
a line beginning with __.PS__ and ends with a line
beginning with __.PE__. Anything outside of __.PS__
and __.PE__ is passed through without
change.


It is the user's responsibility to provide appropriate
definitions of the __PS__ and __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 __-mpic__: these will center each
picture.
!!OPTIONS


Options that do not take arguments may be grouped behind a
single __-__. The special option __--__ can be used to
mark the end of the options. A filename of __-__ refers
to the standard input.


__-C__


Recognize __.PS__ and __.PE__ even when followed by a
character other than space or newline.


__-S__


Safer mode; do not execute __sh__ commands. This can be
useful when operating on untrustworthy input. (enabled by
default)


__-U__


Unsafe mode; revert the default option
__-S__.


__-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 groff_out(5). The
__-n__ option also causes __pic__ not to use
zero-length lines to draw dots in troff mode.


__-t__


TEX mode.


__-c__


Be more compatible with __tpic__. Implies __-t__.
Lines beginning with __\__ are not passed through
transparently. Lines beginning with __.__ are passed
through with the initial __.__ changed to __\__. A
line beginning with __.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
__thickness__ attribute or by setting the
__linethick__ variable.


__-v__


Print the version number.


__-z__


In TEX mode draw dots using zero-length lines.


The following options supported by other versions of
__pic__ are ignored:


__-D__


Draw all lines using the D escape sequence. __pic__
always does this.


__-T__ ''dev''


Generate output for the __troff__ device ''dev''. This
is unnecessary because the __troff__ output generated by
__pic__ is device-independent.
!!USAGE


This section describes only the differences between GNU
__pic__ and the original version of __pic__. Many of
these differences also apply to newer versions of Unix
__pic__.


__TEX mode__


TEX mode is enabled by the __-t__ option. In TEX mode,
__pic__ will define a vbox called __graph__ for each
picture. You must yourself print that vbox using, for
example, the command


__centerline{boxgraph}__


Actually, since the vbox has a height of zero this will
produce slightly more vertical space above the picture than
below it;


__centerline{raise 1emboxgraph}__


would avoid this.


You must use a TEX driver that supports the __tpic__
specials, version 2.


Lines beginning with __\__ are passed through
transparently; a __%__ 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 __baselineskip__.
Anything else may well produce undesirable results; use at
your own risk. Lines beginning with a period are not given
any special treatment.


__Commands__


__for__ ''variable'' __=__ ''expr1'' __to__
''expr2'' [[__by__ [[__*__]''expr3''] __do__
''X body X''


Set ''variable'' to ''expr1''. While the value of
''variable'' is less than or equal to ''expr2'', do
''body'' and increment ''variable'' by ''expr3'';
if __by__ is not given, increment ''variable'' by 1.
If ''expr3'' is prefixed by __*__ then ''variable''
will instead be multiplied by ''expr3''. ''X'' can be
any character not occurring in ''body''.


__if__ ''expr'' __then__ ''X if-true X''
[[__else__ ''Y if-false Y'']


Evaluate ''expr''; if it is non-zero then do
''if-true'', otherwise do ''if-false''. ''X'' can
be any character not occurring in ''if-true''. ''Y''
can be any character not occurring in
''if-false''.


__print__ ''arg''...


Concatenate the arguments and print as a line on stderr.
Each ''arg'' must be an expression, a position, or text.
This is useful for debugging.


__command__ ''arg''...


Concatenate the arguments and pass them through as a line to
troff orTEX. Each ''arg'' must be an expression, a
position, or text. This has a similar effect to a line
beginning with __.__ or __\__, but allows the values
of variables to be passed through.


__sh__ ''X command X''


Pass ''command'' to a shell. ''X'' can be any
character not occurring in ''command''.


__copy __''filename''____


Include ''filename'' at this point in the
file.


__copy__ [[____''filename''____]
__thru__ ''X body X'' [[__until
__''word''____]


__copy__ [[____''filename''____]
__thru__ ''macro'' [[__until
__''word''____]


This construct does ''body'' once for each line of
''filename''; the line is split into blank-delimited
words, and occurrences of __$__''i'' in ''body'',
for ''i'' between 1 and 9, are replaced by the
''i''-th word of the line. If ''filename'' is not
given, lines are taken from the current input up to
__.PE__. If an __until__ clause is specified, lines
will be read only until a line the first word of which is
''word''; that line will then be discarded. ''X'' can
be any character not occurring in ''body''. For
example,


__.PS
copy thru % circle at ($1,$2) % until
__


is equivalent to


__.PS
circle at (1,2)
circle at (3,4)
circle at (5,6)
box
.PE
__


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 __thru__.


__reset__


__reset__ ''variable1''__,__ ''variable2
...''


Reset pre-defined variables ''variable1'',
''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
__scale__ also causes all pre-defined variables that
control dimensions to be reset to their default values times
the new value of scale.


__plot__ ''expr''
[[____''text''____]


This is a text object which is constructed by using
''text'' as a format string for sprintf with an argument
of ''expr''. If ''text'' is omitted a format string of
____ 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; __pic__
does only very limited checking of the string. This is
deprecated in favour of __sprintf__.


''variable''__:=__''expr''


This is similar to __=__ except ''variable'' must
already be defined, and the value of ''variable'' will be
changed only in the innermost block in which it is defined.
(By contrast, __=__ defines the variable in the current
block if it is not already defined there, and then changes
the value in the current block.)


Arguments of the form


''X'' anything ''X''


are also allowed to be of the form


__{__ ''anything'' __}__


In this case ''anything'' can contain balanced
occurrences of __{__ and __}__. Strings may contain
''X'' or imbalanced occurrences of __{__ and
__}__.


__Expressions__


The syntax for expressions has been significantly
extended:


''x'' __^__ ''y'' (exponentiation)__
sin(__''x''__)
cos(__''x''__)
atan2(__''y''__,__ ''x''__)
log(__''x''__)__ (base 10)__
exp(__''x''__)__ (base 10, ie 10''x'')__
sqrt(__''x''__)
int(__''x''__)
rand()__ (return a random number between 0 and 1)__
rand(__''x''__)__ (return a random number between 1
and ''x''; deprecated)__
srand(__''x''__)__ (set the random number
seed)__
max(__''e1''__,__ ''e2''__)
min(__''e1''__,__ ''e2''__)
!__''e
e1'' ____ ''e2
e1'' __||__ ''e2
e1'' __==__ ''e2
e1'' __!=__ ''e2
e1'' ____ ''e2
e1'' ____ ''e2
e1'' ____ ''e2
e1'' ____ ''e2''__
''str1''__
__''str2''____
__''str1''__
__''str2''____


String comparison expressions must be parenthesised in some
contexts to avoid ambiguity.


__Other Changes__


A bare expression, ''expr'', is acceptable as an
attribute; it is equivalent to ''dir expr'', where
''dir'' is the current direction. For
example


__line 2i__


means draw a line 2 inches long in the current
direction.


The maximum width and height of the picture are taken from
the variables __maxpswid__ and __maxpsht__. Initially
these have values 8.5 and 11.


Scientific notation is allowed for numbers. For
example


__x = 5e-2__


Text attributes can be compounded. For example,


____


is legal.


There is no limit to the depth to which blocks can be
examined. For example,


__[[A: [[B: [[C: box ]]] with .A.B.C.sw at 1,2
circle at last [[].A.B.C__


is acceptable.


Arcs now have compass points determined by the circle of
which the arc is a part.


Circles and arcs can be dotted or dashed. In TEX mode
splines can be dotted or dashed.


Boxes can have rounded corners. The __rad__ attribute
specifies the radius of the quarter-circles at each corner.
If no __rad__ or __diam__ attribute is given, a radius
of __boxrad__ is used. Initially, __boxrad__ has a
value of 0. A box with rounded corners can be dotted or
dashed.


The __.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 __pic__ will always
scale a picture by the same amount vertically as
horizontally. This is different from the DWB
2.0 __pic__ which may scale a picture by a different
amount vertically than horizontally if a height is
specified.


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
__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 __textht__. Initially
__textwid__ and __textht__ have a value of
0.


In places where a quoted text string can be used, an
expression of the form


__sprintf(__''format''____
''arg''__,__...__)__


can also be used; this will produce the arguments formatted
according to ''format'', which should be a string as
described in printf(3) appropriate for the number of
arguments supplied, using only the __e__, __f__,
__g__ or __%__ format characters.


The thickness of the lines used to draw objects is
controlled by the __linethick__ variable. This gives the
thickness of lines in points. A negative value means use the
default thickness: in TEX output mode, this means use a
thickness of 8 milliinches; in TEX output mode with the
__-c__ option, this means use the line thickness
specified by __.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 __thick__[[__ness__] attribute. For
example,


__circle thickness 1.5__


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 __scale__ variable, nor by the width or height
given in the __.PS__ line.


Boxes (including boxes with rounded corners), circles and
ellipses can be filled by giving then an attribute of
__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 __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.


Arrow heads will be drawn as solid triangles if the variable
__arrowhead__ is non-zero and either TEX mode is enabled
or the __-x__ option has been given. Initially
__arrowhead__ has a value of 1.


The troff output of __pic__ is device-independent. The
__-T__ option is therefore redundant. All numbers are
taken to be in inches; numbers are never interpreted to be
in troff machine units.


Objects can have an __aligned__ attribute. This will only
work when the postprocessor is __grops__. Any text
associated with an object having the __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.


In places where ''n''__th__ is allowed
__`__''expr''__'th__ is also allowed. Note that
__'th__ is a single token: no space is allowed between
the __'__ and the __th__. For example,


__for i = 1 to 4 do {
__   line from `i'th box.nw to `i+1'th box.se
}
!!CONVERSION


To obtain a stand-alone picture from a __pic__ file,
enclose your __pic__ code with __.PS__ and __.PE__
requests; __roff__ configuration commands may be added at
the beginning of the file, but no __roff__
text.


It is necessary to feed this file into __groff__ without
adding any page information, so you must check which
__.PS__ and __.PE__ requests are actually called. For
example, the mm macro package adds a page number, which is
very annoying. At the moment, calling standard __groff__
without any macro package works. Alternatively, you can
define your own requests, e.g. to do nothing:


__.de PS
..
.de PE
..
__


__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 format using the __groff__ option __-Tps__.
Since this ''ps''-file lacks !BoundingBox information it
is not very useful by itself, but it may be fed into other
conversion programs, usually named __ps2__''other'' or
__psto__''other'' or the like. Moreover, the
!PostScript interpreter __ghostscript__ (__gs__) has
built-in graphics conversion devices that are called with
the option


__gs -sDEVICE=__''''


Call


__gs --help__


for a list of the available devices.


As the Encapsulated !PostScript File Format __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 __ps2eps__ which
does the right job. It is much better than the tool
__ps2epsi__ packaged with __gs__.


For bitmapped graphic formats, you should use
__pstopnm__; the resulting (intermediate) __PNM__ file
can be then converted to virtually any graphics format using
the tools of the __netpbm__ package .
!!FILES


__/usr/share/groff/1.17.2/tmac/pic.tmac__


Example definitions of the __PS__ and __PE__
macros.
!!SEE ALSO


troff(1), groff_out(5), tex(1),
gs(1), ps2eps(1), pstopnm(1),
ps2epsi(1), pnm(5)


Tpic: Pic for TEX


Brian W. Kernighan, PIC -- A Graphics Language for
Typesetting (User Manual). AT


__ps2eps__ is available from CTAN mirrors, e.g.


W. Richard Stevens - Turning PIC Into HTML


W. Richard Stevens - Examples of picMacros
!!BUGS


Input characters that are illegal for __groff__ (ie those
with ASCII code 0 or between 013 and 037
octal or between 0200 and 0237 octal) are rejected even in
TEX mode.


The interpretation of __fillval__ is incompatible with
the pic in 10th edition Unix, which interprets 0 as black
and 1 as white.


!PostScript is a registered trademark of Adobe Systems
Incorporation.
----
11 pages link to pic(1):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Tuesday, June 4, 2002 12:22:42 am by "perry"
Edit PageHistory Diff Info LikePages