Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1569 insertions, 0 deletions

diff --git a/src/preproc/pic/pic.1.man b/src/preproc/pic/pic.1.man
new file mode 100644
index 0000000..727cbc3
--- /dev/null
+++ b/src/preproc/pic/pic.1.man
@@ -0,0 +1,1569 @@
+.TH @g@pic @MAN1EXT@ "@MDATE@" "groff @VERSION@"
+.SH Name
+@g@pic \- compile pictures for
+.I troff
+or TeX
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2020 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.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_pic_1_man_C \n[.cp]
+.cp 0
+.
+.\" Define fallback for groff 1.23's MR macro if the system lacks it.
+.nr do-fallback 0
+.if !\n(.f           .nr do-fallback 1 \" mandoc
+.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
+.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
+.if \n[do-fallback]  \{\
+.  de MR
+.    ie \\n(.$=1 \
+.      I \%\\$1
+.    el \
+.      IR \%\\$1 (\\$2)\\$3
+.  .
+.\}
+.rr do-fallback
+.
+.
+.\" ====================================================================
+.\" Definitions
+.\" ====================================================================
+.
+.ie t \{\
+.  ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
+.  ds lx L\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\*[tx]
+.\}
+.el \{\
+.  ds tx TeX
+.  ds lx LaTeX
+.\}
+.
+.ie \n(.g .ds ic \/
+.el       .ds ic \^
+.
+.
+.\" ====================================================================
+.SH Synopsis
+.\" ====================================================================
+.
+.SY @g@pic
+.RB [ \-CnSU ]
+.RI [ file\~ .\|.\|.]
+.YS
+.
+.
+.SY @g@pic
+.B \-t
+.RB [ \-cCSUz ]
+.RI [ file\~ .\|.\|.]
+.YS
+.
+.
+.SY @g@pic
+.B \-\-help
+.YS
+.
+.
+.SY @g@pic
+.B \-v
+.
+.SY @g@pic
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH Description
+.\" ====================================================================
+.
+The GNU implementation of
+.I pic \" generic
+is part of the
+.MR groff @MAN1EXT@
+document formatting system.
+.
+.I @g@pic
+is a
+.MR @g@troff @MAN1EXT@
+preprocessor that translates descriptions of diagrammatic pictures
+embedded in
+.MR roff @MAN7EXT@
+or \*[tx] input files into the language understood by \*[tx] or
+.IR @g@troff .
+.
+It copies the contents of each
+.I file
+to the standard output stream,
+except that lines between
+.B .PS
+and any of
+.BR .PE ,
+.BR .PF ,
+or
+.B .PY
+are interpreted as picture descriptions in the
+.I pic
+language.
+.
+End a
+.I @g@pic
+picture with
+.B .PE
+to leave the drawing position at the bottom of the picture,
+and with
+.B .PF
+or
+.B .PY
+to leave it at the top.
+.
+Normally,
+.I @g@pic
+is not executed directly by the user,
+but invoked by specifying the
+.B \-p
+option to
+.MR groff @MAN1EXT@ .
+.
+If no
+.I file
+operands are given on the command line,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+the standard input stream is read.
+.
+.
+.P
+It is the user's responsibility to provide appropriate definitions
+of the
+.BR PS ,
+.BR PE ,
+and one or both of the
+.B PF
+and
+.B PY
+macros.
+.
+When a macro package does not supply these,
+obtain simple definitions with the
+.I groff
+option
+.BR \-mpic ;
+these will center each picture.
+.
+.
+.P
+GNU
+.I pic \" GNU
+supports
+.B PY
+as a synonym of
+.B PF
+to work around a name space collision with the
+.I mm
+macro package,
+which defines
+.B PF
+as a page footer management macro.
+.
+Use
+.B PF
+preferentially unless a similar problem faces your document.
+.
+.
+.\" ====================================================================
+.SH Options
+.\" ====================================================================
+.
+.B \-\-help
+displays a usage message,
+while
+.B \-v
+and
+.B \-\-version
+show version information;
+all exit afterward.
+.
+.
+.TP
+.B \-c
+Be more compatible with
+.IR tpic ;
+implies
+.BR \-t .
+.
+Lines beginning with
+.B \[rs]
+are not passed through transparently.
+.
+Lines beginning with
+.B .\&
+are passed through with the initial
+.B .\&
+changed to
+.BR \[rs] .
+.
+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 \-C
+Recognize
+.BR .PS ,
+.BR .PE ,
+.BR .PF ,
+and
+.B .PY
+even when followed by a character other than space or newline.
+.
+.
+.TP
+.B \-n
+Don't use
+.I groff
+extensions to the
+.I troff \" generic
+drawing commands.
+.
+Specify this option if a postprocessor you're using doesn't support
+these extensions,
+described in
+.MR groff_out @MAN5EXT@ .
+.
+This option also causes
+.I @g@pic
+not to use zero-length lines to draw dots in
+.I troff \" generic
+mode.
+.
+.
+.TP
+.B \-S
+Operate in
+.I safer mode;
+.B sh
+commands are ignored.
+.
+This mode,
+enabled by default,
+can be useful when operating on untrustworthy input.
+.
+.
+.TP
+.B \-t
+Produce \*[tx] output.
+.
+.
+.TP
+.B \-U
+Operate in
+.I unsafe mode;
+.B sh
+commands are interpreted.
+.
+.
+.TP
+.B \-z
+In \*[tx] mode,
+draw dots using zero-length lines.
+.
+.
+.P
+The following options supported by other versions of
+.I pic \" generic
+are ignored.
+.
+.
+.TP
+.B \-D
+Draw all lines using the \[rs]D escape sequence.
+GNU
+.I pic \" GNU
+always does this.
+.
+.TP
+.BI \-T\~ dev
+Generate output for the
+.I troff \" generic
+device
+.IR dev .
+.
+This is unnecessary because the
+.I troff \" generic
+output generated by
+GNU
+.I pic \" GNU
+is device-independent.
+.
+.
+.\" ====================================================================
+.SH Usage
+.\" ====================================================================
+.
+This section primarily discusses the differences between GNU
+.I pic \" GNU
+and the Eighth Edition Research Unix version of AT&T
+.I pic \" AT&T
+(1985).
+.
+Many of these differences also apply to later versions of AT&T
+.IR pic .
+.
+.
+.\" ====================================================================
+.SS "\*[tx] mode"
+.\" ====================================================================
+.
+\*[tx]-compatible output is produced when the
+.B \-t
+option is specified.
+.
+You must use a \*[tx] driver that supports
+.I tpic
+version 2 specials.
+.
+.RI ( tpic
+was a fork of AT&T
+.I pic \" AT&T
+by Tim Morgan of the University of California at Irvine that diverged
+from its source around 1984.
+.
+It is best known today for lending its name to a group of
+.B \[rs]special
+commands it produced for \*[tx].)
+.\" http://ftp.cs.stanford.edu/tex/texhax/texhax90.019
+.
+.
+.P
+Lines beginning with
+.B \[rs]
+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 the value of
+.BR \[rs]baselineskip .
+.
+Anything else may well produce undesirable results;
+use at your own risk.
+.
+By default,
+lines beginning with a dot are not treated specially\[em]but see the
+.B \-c
+option.
+.
+.
+.P
+In \*[tx] mode,
+.I @g@pic
+will define a vbox called
+.B \[rs]graph
+for each picture.
+.
+Use GNU
+.IR pic 's \" GNU
+.B figname
+command to change the name of the vbox.
+.
+You must print that vbox yourself using the command
+.
+.RS
+.EX
+\[rs]centerline{\[rs]box\[rs]graph}
+.EE
+.RE
+.
+for instance.
+.
+Since the vbox has a height of zero
+(it is defined with
+.BR \[rs]vtop )
+this will produce slightly more vertical space above the picture than
+below it;
+.
+.RS
+.EX
+\[rs]centerline{\[rs]raise 1em\[rs]box\[rs]graph}
+.EE
+.RE
+.
+would avoid this.
+.
+To give the vbox a positive height and a depth of zero
+(as used by \*[lx]'s
+.IR \%graphics.sty ,
+for example)
+define the following macro in your document.
+.
+.RS
+.EX
+\[rs]def\[rs]gpicbox#1{%
+  \[rs]vbox{\[rs]unvbox\[rs]csname #1\[rs]endcsname\[rs]kern 0pt}}
+.EE
+.RE
+.
+You can then simply say
+.B \[rs]gpicbox{graph}
+instead of
+.BR \[rs]box\[rs]graph .
+.
+.
+.\" ====================================================================
+.SS Commands
+.\" ====================================================================
+.
+Several commands new to GNU
+.I pic \" GNU
+accept delimiters,
+shown in their synopses as braces
+.BR "{ }" .
+.
+Nesting of braces is supported.
+.
+Any other characters
+(except a space,
+tab,
+or newline)
+.\" XXX even crazy control characters, ugh--src/preproc/pic/lex.cpp:1266
+may be used as alternative delimiters,
+in which case the members of a given pair must be identical.
+.
+Strings are recognized within delimiters of either kind;
+they may contain the delimiter character or unbalanced braces.
+.
+.
+.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 .
+.
+The value of
+.I expr3
+can be negative for the additive case;
+.I variable
+is then tested whether it is greater than or equal to
+.IR expr2 .
+.
+For the multiplicative case,
+.I expr3
+must be greater than zero.
+.
+If the constraints aren't met,
+the loop isn't executed.
+.
+.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
+.BI print\~ arg\c
+\~.\|.\|.
+Concatenate and write arguments to the standard error stream followed by
+a newline.
+.
+Each
+.I arg
+must be an expression,
+a position,
+or text.
+.
+This is useful for debugging.
+.
+.TP
+.BI command\~ arg\c
+\~.\|.\|.
+.\" Move right margin to indentation since we must indent more later.
+.RS
+Concatenate arguments
+and pass them as a line to
+.I troff \" generic
+or \*[tx].
+.
+Each
+.I arg
+must be an expression,
+a position,
+or text.
+.
+.B command
+allows the values of
+.I pic
+variables to be passed to the formatter.
+.
+For example,
+.
+.RS
+.EX
+\&.PS
+x = 14
+command ".ds string x is " x "."
+\&.PE
+\[rs]*[string]
+.EE
+.RE
+.
+produces
+.
+.RS
+.EX
+x is 14.
+.EE
+.RE
+when formatted with
+.IR troff . \" generic
+.RE
+.
+.
+.TP
+\fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR
+Pass
+.I command
+to a shell.
+.
+.
+.TP
+\fBcopy\fR \fB"\,\fIfilename\/\fB"\fR
+Include
+.I filename
+at this point in the file.
+.
+.
+.TP
+.BR copy\~ [ \[dq]\c
+.IB filename \[dq]\c
+.RB ]\~ thru\~\c
+.IR "X body X" \~\c \" space in roman: we must use 2-font macro with \c
+.RB [ until\~ \[dq]\c
+.IB word \[dq]\c
+]
+.TQ
+.BR copy\~ [ \[dq]\c
+.IB filename \[dq]\c
+.RB ]\~ thru\~\c
+.IR macro \~\c \" space roman because we must use 2-font macro with \c
+.RB [ until\~ \[dq]\c
+.IB word \[dq]\c
+]
+.\" Move right margin to indentation since we must indent more later.
+.RS
+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 \" now move further
+.EX
+\&.PS
+copy thru % circle at ($1,$2) % until "END"
+1 2
+3 4
+5 6
+END
+box
+\&.PE
+.EE
+.RE
+.
+and
+.
+.RS
+.EX
+\&.PS
+circle at (1,2)
+circle at (3,4)
+circle at (5,6)
+box
+\&.PE
+.EE
+.RE
+.
+are equivalent.
+.
+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 .
+.
+The argument after
+.B thru
+is looked up as a macro name first;
+if not defined,
+its first character is interpreted as a delimiter.
+.RE
+.
+.
+.TP
+.B reset
+.TQ
+.BI reset\~ pvar1\c
+.RB [ , ]\~\c
+.IR pvar2 \~.\|.\|.
+Reset predefined variables
+.IR pvar1 ,
+.I pvar2
+\&.\|.\|.\& to their default values;
+if no arguments are given,
+reset all predefined variables to their default values.
+.
+Variable names may be separated by commas,
+spaces,
+or both.
+.
+Assigning a value to
+.B scale
+also causes all predefined variables that control dimensions to be reset
+to their default values times the new value of
+.BR 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 \[dq]%g\[dq]
+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;
+.I @g@pic
+does only very limited checking of the string.
+.
+This is deprecated in favour of
+.BR sprintf .
+.
+.TP
+.IB var \~:=\~ expr
+.RS
+This syntax resembles variable assignment with
+.B =
+except that
+.I var
+must already be defined,
+and
+.I expr
+will be assigned to
+.I var
+without creating a variable local to the current block.
+.
+(By contrast,
+.B =
+defines
+.I var
+in the current block if it is not already defined there,
+and then changes the value in the current block only.)
+.
+For example,
+.
+.RS
+.EX
+.B .PS
+.B x = 3
+.B y = 3
+.B [
+.B   x := 5
+.B   y = 5
+.B ]
+.B print x " " y
+.B .PE
+.EE
+.RE
+.
+writes
+.
+.RS
+.EX
+5 3
+.EE
+.RE
+.
+to the standard error stream.
+.RE
+.
+.
+.\" ====================================================================
+.SS Expressions
+.\" ====================================================================
+.
+The syntax for expressions has been significantly extended.
+.
+.
+.P
+.IB  x\  \[ha]\  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, i.e.\&
+.ie t 10\v'-.4m'\fIx\*(ic\fR\v'.4m')
+.el   10\[ha]\fIx\fR)
+.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"
+.\" ====================================================================
+.
+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
+.LP
+.RS
+.B line 2i
+.RE
+.LP
+means draw a line 2\ inches long in the current direction.
+.
+The \[oq]i\[cq]
+(or \[oq]I\[cq])
+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
+.
+.
+.RS
+.LP
+.B
+x = 5e\-2
+.RE
+.
+.
+.LP
+Text attributes can be compounded.
+.
+For example,
+.
+.RS
+.LP
+.B
+"foo" above ljust
+.RE
+.
+.
+.LP
+is valid.
+.
+.
+.LP
+There is no limit to the depth to which blocks can be examined.
+.
+For example,
+.RS
+.LP
+.EX
+[A: [B: [C: box ]]] with .A.B.C.sw at 1,2
+circle at last [\^].A.B.C
+.EE
+.RE
+.
+.
+.LP
+is acceptable.
+.
+.
+.LP
+Arcs now have compass points determined by the circle of which the arc
+is a part.
+.
+.
+.LP
+Circles,
+ellipses,
+and arcs can be dotted or dashed.
+.
+In \*[tx] mode splines can be dotted or dashed also.
+.
+.
+.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
+Boxes can have slanted sides.
+.
+This effectively changes the shape of a box from a rectangle to an
+arbitrary parallelogram.
+.
+The
+.B xslanted
+and
+.B yslanted
+attributes specify the x and y\~offset of the box's upper right
+corner from its default position.
+.
+.
+.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.
+.
+GNU
+.I pic \" GNU
+will always scale a picture by the same amount vertically as well as
+horizontally.
+.
+This is different from DWB 2.0
+.I pic \" foreign
+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
+(almost all)
+places where a quoted text string can be used,
+an expression of the form
+.
+.
+.IP
+.BI sprintf(\[dq] format \[dq],\~ 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
+.MR printf 3
+appropriate for the number of arguments supplied.
+.
+Only the modifiers
+.RB \[lq] # \[rq],
+.RB \[lq] \- \[rq],
+.RB \[lq] + \[rq],
+and \[lq]\~\[rq] [space]),
+a minimum field width,
+an optional precision,
+and the conversion specifiers
+.BR %e ,
+.BR %E ,
+.BR %f ,
+.BR %g ,
+.BR %G ,
+and
+.B %%
+are supported.
+.
+.
+.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
+.I 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 or slanted sides),
+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 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.
+.
+.
+.P
+Additional modifiers are available to draw 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 expect a subsequent string argument specifying the color.
+.
+.RS
+.EX
+circle shaded \[dq]green\[dq] outline \[dq]black\[dq]
+.EE
+.RE
+.
+Color is not yet supported in \*[tx] mode.
+.
+Device macro files like
+.I ps.tmac
+declare color names;
+you can define additional ones with the
+.B \%defcolor
+request
+(see
+.MR groff @MAN7EXT@ ).
+.
+.
+.LP
+To change the name of the vbox in \*[tx] mode,
+set the pseudo-variable
+.B \%figname
+(which is actually a specially parsed command)
+within a picture.
+.
+Example:
+.RS
+.LP
+.B .PS
+.br
+.B figname = foobar;
+.br
+.B ...
+.br
+.B .PE
+.RE
+.
+.
+.LP
+The picture is then available in the box
+.BR \[rs]foobar .
+.
+.
+.LP
+.I @g@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 \-n
+option has not been given.
+.
+Initially,
+.B arrowhead
+has a value of\ 1.
+.
+Solid arrow heads are always filled with the current outline color.
+.
+.
+.LP
+The
+.I troff
+output of
+.I @g@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
+.I troff
+machine units.
+.
+.
+.LP
+Objects can have an
+.B aligned
+attribute.
+.
+This will only work if the postprocessor is
+.MR grops @MAN1EXT@
+or
+.MR gropdf @MAN1EXT@ .
+.
+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.
+.
+This attribute will have no effect on objects whose start and end points
+are coincident.
+.
+.
+.LP
+In places where
+.IB n th
+is allowed,
+.BI \[aq] expr \[aq]th
+is also allowed.
+.
+.RB \[lq] \[aq]th \[lq]
+is a single token:
+no space is allowed between the apostrophe and the
+.RB \[lq] th \[rq].
+.
+.
+For example,
+.IP
+.EX
+for i = 1 to 4 do {
+   line from \[aq]i\[aq]th box.nw to \[aq]i+1\[aq]th box.se
+}
+.EE
+.
+.
+.\" ====================================================================
+.SH Conversion
+.\" ====================================================================
+.
+To obtain a stand-alone picture from a
+.I @g@pic
+file,
+enclose your
+.I pic \" language
+code with
+.B .PS
+and
+.B .PE
+requests;
+.I roff
+configuration commands may be added at the beginning of the file,
+but no
+.I roff
+text.
+.
+.
+.LP
+It is necessary to feed this file into
+.I groff
+without adding any page information,
+so you must check which
+.B .PS
+and
+.B .PE
+requests are actually called.
+.
+For example,
+the
+.I mm
+macro package adds a page number,
+which is very annoying.
+.
+At the moment,
+calling standard
+.I groff
+without any macro package works.
+.
+Alternatively,
+you can define your own requests,
+e.g.,
+to do nothing:
+.
+.
+.LP
+.RS
+.EX
+\&.de PS
+\&..
+\&.de PE
+\&..
+.EE
+.RE
+.
+.
+.LP
+.I 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
+.I 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 Ghostscript
+.RI ( gs (1))
+has built-in graphics conversion devices that are called with the option
+.
+.
+.LP
+.RS
+.BI "gs \-sDEVICE=" <devname>
+.RE
+.
+.
+.LP
+Call
+.
+.
+.LP
+.RS
+.B gs \-\-help
+.RE
+.
+.
+.LP
+for a list of the available devices.
+.
+.
+.LP
+An alternative may be to use the
+.B \-Tpdf
+option to convert your picture directly into
+.B PDF
+format.
+.
+The MediaBox of the file produced can be controlled by passing a
+.B \-P\-p
+papersize to
+.IR groff .
+.
+.
+.br
+.ne 3v
+.P
+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
+.I ps2eps
+which does the right job.
+.
+It is much better than the tool
+.I ps2epsi
+packaged with
+.IR gs .
+.
+.
+.LP
+For bitmapped graphic formats,
+you should use
+.IR pstopnm ;
+the resulting (intermediate)
+.MR pnm 5
+file can be then converted to virtually any graphics format using the
+tools of the
+.B netpbm
+package.
+.
+.
+.\" ====================================================================
+.SH Files
+.\" ====================================================================
+.
+.TP
+.I @MACRODIR@/pic.tmac
+offers simple definitions of the
+.BR PS ,
+.BR PE ,
+.BR PF ,
+and
+.B PY
+macros.
+.
+.
+.\" ====================================================================
+.SH Bugs
+.\" ====================================================================
+.
+Characters that are invalid as input to GNU
+.I troff \" GNU
+(see the
+.I groff
+Texinfo manual or
+.MR groff_char @MAN7EXT@
+for a list)
+are rejected even in \*[tx] mode.
+.
+.
+.LP
+The interpretation of
+.B \%fillval
+is incompatible with the
+.I pic \" AT&T
+in Tenth Edition Research Unix,
+which interprets 0 as black and 1 as white.
+.
+.
+.\" ====================================================================
+.SH "See also"
+.\" ====================================================================
+.
+.TP
+.I @DOCDIR@/\:pic\:.ps
+\[lq]Making Pictures with GNU pic\[rq],
+by Eric S.\& Raymond.
+.
+This file,
+together with its source,
+.IR pic.ms ,
+is part of the
+.I groff
+distribution.
+.
+.
+.P
+\[lq]PIC\[em]A Graphics Language for Typesetting: User Manual\[rq],
+by Brian W.\& Kernighan,
+1984
+(revised 1991),
+AT&T Bell Laboratories Computing Science Technical Report No.\& 116
+.
+.
+.P
+.I ps2eps
+is available from CTAN mirrors, e.g.,
+.UR ftp://\:ftp\:.dante\:.de/\:tex\-archive/\:support/\:ps2eps/
+.UE
+.
+.
+.LP
+W.\& Richard Stevens,
+.UR http://\:www\:.kohala\:.com/\:start/\:troff/\:pic2html\:.html
+.I Turning PIC into HTML
+.UE
+.
+.
+.LP
+W.\& Richard Stevens,
+.UR http://\:www\:.kohala\:.com/\:start/\:troff/\:pic\:.examples\:.ps
+.IR "Examples of " pic " Macros"
+.UE
+.
+.
+.LP
+.MR @g@troff @MAN1EXT@ ,
+.MR groff_out @MAN5EXT@ ,
+.MR tex 1 ,
+.MR gs 1 ,
+.MR ps2eps 1 ,
+.MR pstopnm 1 ,
+.MR ps2epsi 1 ,
+.MR pnm 5
+.
+.
+.\" Clean up.
+.rm tx
+.rm lx
+.rm ic
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_pic_1_man_C]
+.do rr *groff_pic_1_man_C
+.
+.
+.\" Local Variables:
+.\" fill-column: 72
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff textwidth=72: