diff options
Diffstat (limited to 'src/preproc/grn/grn.1.man')
| -rw-r--r-- | src/preproc/grn/grn.1.man | 978 |
1 files changed, 978 insertions, 0 deletions
diff --git a/src/preproc/grn/grn.1.man b/src/preproc/grn/grn.1.man new file mode 100644 index 0000000..cbc15ae --- /dev/null +++ b/src/preproc/grn/grn.1.man @@ -0,0 +1,978 @@ +'\" t +.TH @g@grn @MAN1EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +@g@grn \- embed Gremlin images in +.I groff +documents +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 2000-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_grn_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 +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY @g@grn +.RB [ \-C ] +.RB [ \-T\~\c +.IR dev ] +.RB [ \-M\~\c +.IR dir ] +.RB [ \-F\~\c +.IR dir ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY @g@grn +.B \-? +. +.SY @g@grn +.B \-\-help +.YS +. +. +.SY @g@grn +.B \-v +. +.SY @g@grn +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I @g@grn +is a preprocessor for including +.I gremlin +pictures in +.MR @g@troff @MAN1EXT@ +input. +. +.I @g@grn +writes to standard output, +processing only input lines between two that start with +.B .GS +and +.BR .GE . +. +Those lines must contain +.I @g@grn +commands +(see below). +. +These macros request a +.I gremlin +file; +the picture in that file is converted and placed in the +.I @g@troff +input stream. +. +.B .GS +may be called with a +.BR C , +.BR L , +or +.B R +argument to center, +left-, +or right-justify the whole +.I gremlin +picture +(the default is to center). +. +If no +.I file +is mentioned, +the standard input is read. +. +At the end of the picture, +the position on the page is the bottom of the +.I gremlin +picture. +. +If the +.I @g@grn +entry is ended with +.B .GF +instead of +.BR .GE , +the position is left at the top of the picture. +. +. +.PP +Currently only the +.I me +macro package has support for +.BR .GS , +.BR .GE , +and +.BR .GF . +. +. +.PP +.I @g@grn +produces drawing escape sequences that use +.IR groff 's +color scheme extension +.RB ( \[rs]D\[aq]F \~.\|.\|.\& \[aq] ), +and thus may not work with other +.IR troff s. +. +. +.\" ==================================================================== +.SS "\f[I]grn\f[] commands" +.\" ==================================================================== +. +Each input line between +.B .GS +and +.B .GE +may have one +.I @g@grn +command. +. +Commands consist of one or two strings separated by white space, +the first string being the command and the second its operand. +. +Commands may be upper- or lowercase and abbreviated down to one +character. +. +. +.PP +Commands that affect a picture's environment +(those listed before +.RB \%\[lq] default \[rq], +see below) +are only in effect for the current picture: +the environment is reinitialized to the defaults at the start of the +next picture. +. +The commands are as follows. +. +. +.TP +.BI 1\~ N +.TQ +.BI 2\~ N +.TQ +.BI 3\~ N +.TQ +.BI 4\~ N +. +Set +.IR gremlin 's +text size number 1 +(2, +3, +or 4) +to +.I N +points. +. +The default is 12 +(16, +24, +and 36, +respectively). +. +. +.TP +.BI roman\~ f +.TQ +.BI italics\~ f +.TQ +.BI bold\~ f +.TQ +.BI special\~ f +Set the roman +(italics, +bold, +or special) +font to +.IR @g@troff 's +font +.I f +(either a name or number). +. +The default is R +(I, +B, +and S, +respectively). +. +. +.TP +.BI l\~ f +.TQ +.BI stipple\~ f +Set the stipple font to +.IR @g@troff 's +stipple font +.I f +(name or number). +. +The command +.B \%stipple +may be abbreviated down as far as +.RB \[lq] st \[rq] +(to avoid confusion with +.RB \%\[lq] special \[rq]). +. +There is +.I no +default for stipples +(unless one is set by the +.RB \%\[lq] default \[rq] +command), +and it is invalid to include a +.I gremlin +picture with polygons without specifying a stipple font. +. +. +.TP +.BI x\~ N +.TQ +.BI scale\~ N +Magnify the picture +(in addition to any default magnification) +by +.IR N , +a floating-point number larger than zero. +. +The command +.B scale +may be abbreviated down to +.RB \[lq] sc \[rq]. +. +. +.TP +.BI narrow\~ N +.TQ +.BI medium\~ N +.TQ +.BI thick\~ N +. +Set the thickness of +.IR gremlin 's +narrow +(medium and thick, +respectively) +lines to +.I N +times 0.15pt +(this value can be changed at compile time). +. +The default is 1.0 +(3.0 and 5.0, +respectively), +which corresponds to 0.15pt +(0.45pt and 0.75pt, +respectively). +. +A thickness value of zero selects the smallest available line thickness. +. +Negative values cause the line thickness to be proportional to the +current point size. +. +. +.TP +.BR pointscale\~ [ off | on ] +Scale text to match the picture. +. +Gremlin text is usually printed in the point size specified with the +commands +.BR 1 , +.BR 2 , +.BR 3 , +.RB or\~ 4 , +regardless of any scaling factors in the picture. +. +Setting +.B pointscale +will cause the point sizes to scale with the picture +(within +.IR @g@troff 's +limitations, +of course). +. +An operand of anything but +.B off +will turn text scaling on. +. +. +.TP +.B default +Reset the picture environment defaults to the settings in the current +picture. +. +This is meant to be used as a global parameter setting mechanism at +the beginning of the +.I @g@troff +input file, +but can be used at any time to reset the default settings. +. +. +.TP +.BI width\~ N +Force the picture to be +.I N +inches wide. +. +This overrides any scaling factors present in the same picture. +. +.RB \[lq] "width 0" \[rq] +is ignored. +. +. +.TP +.BI height\~ N +Force the picture to be +.I N +inches high, +overriding other scaling factors. +. +If both +.B width +and +.B height +are specified, +the tighter constraint will determine the scale of the picture. +. +.B height +and +.B width +commands are not saved with a +.RB \%\[lq] default \[rq] +command. +. +They will, +however, +affect point size scaling if that option is set. +. +. +.TP +.BI file\~ name +Get picture from +.I gremlin +file +.I name +located the current directory +(or in the library directory; +see the +.B \-M +option above). +. +If multiple +.B file +commands are given, +the last one controls. +. +If +.I name +doesn't exist, +an error message is reported and processing continues from the +.B .GE +line. +. +. +.\" ==================================================================== +.SS "Usage with \f[I]groff\f[]" +.\" ==================================================================== +. +Since +.I @g@grn +is a preprocessor, +it has no access to elements of formatter state, +such as +indentation, +line length, +type size, +or +register values. +. +Consequently, +no +.I @g@troff +input can be placed between the +.B .GS +and +.B .GE +macros. +. +However, +.I gremlin +text elements are subsequently processed by +.IR @g@troff , +so anything valid in a single line of +.I @g@troff +input is valid in a line of +.I gremlin +text +(barring the dot control character \[lq].\[rq] at the beginning of a +line). +. +Thus, +it is possible to have equations within a +.I gremlin +figure by including in the +.I gremlin +file +.I eqn \" language +expressions enclosed by previously defined delimiters +(e.g., +\[lq]$$\[rq]). +. +. +.PP +When using +.I @g@grn +along with other preprocessors, +it is best to run +.MR @g@tbl @MAN1EXT@ +before +.IR @g@grn , +.MR @g@pic @MAN1EXT@ , +and/or +.I ideal \" no GNU version yet +to avoid overworking +.IR @g@tbl . +. +.MR @g@eqn @MAN1EXT@ +should always be run last. +. +.MR groff @MAN1EXT@ +will automatically run preprocessors in the correct order. +. +. +.PP +A picture is considered an entity, +but that doesn't stop +.I @g@troff +from trying to break it up if it falls off the end of a page. +. +Placing the picture between \[lq]keeps\[rq] in the +.I me +macros will ensure proper placement. +. +. +.PP +.I @g@grn +uses +.IR @g@troff 's +registers +.B g1 +through +.B g9 +and sets registers +.B g1 +and +.B g2 +to the width and height of the +.I gremlin +figure +(in device units) +before entering the +.B .GS +macro +(this is for those who want to rewrite these macros). +. +. +.\" ==================================================================== +.SS "Gremlin file format" +.\" ==================================================================== +. +There exist two distinct +.I gremlin +file formats: +the original format for AED graphic terminals, +and the Sun or X11 version. +. +An extension used by the Sun/X11 version allowing reference points with +negative coordinates is +.I not +compatible with the AED version. +. +As long as a +.I gremlin +file does not contain negative coordinates, +either format will be read correctly by either version of +.I gremlin +or +.IR @g@grn . +. +The other difference in +Sun/X11 format is the use of names for picture objects +(e.g., +.BR POLYGON , +.BR CURVE ) +instead of numbers. +. +Files representing the same picture are shown below. +. +. +.PP +.ie t .ne 18v +.el .ne 19v +.TS +center, tab(@); +l lw(0.1i) l. +sungremlinfile@@gremlinfile +0 240.00 128.00@@0 240.00 128.00 +CENTCENT@@2 +240.00 128.00@@240.00 128.00 +185.00 120.00@@185.00 120.00 +240.00 120.00@@240.00 120.00 +296.00 120.00@@296.00 120.00 +*@@\-1.00 \-1.00 +2 3@@2 3 +10 A Triangle@@10 A Triangle +POLYGON@@6 +224.00 416.00@@224.00 416.00 +96.00 160.00@@96.00 160.00 +384.00 160.00@@384.00 160.00 +*@@\-1.00 \-1.00 +5 1@@5 1 +0@@0 +\-1@@\-1 +.TE +. +. +.IP \[bu] 2n +The first line of each +.I gremlin +file contains either the string +.RB \[lq] gremlinfile \[rq] +(AED) +or +.RB \[lq] sungremlinfile \[rq] +(Sun/X11). +. +. +.IP \[bu] +The second line of the file contains an orientation and +.I x +and +.I y +values for a positioning point, +separated by spaces. +. +The orientation, +either +.B 0 +or +.BR 1 , +is ignored by the Sun/X11 version. +. +.B 0 +means that +.I gremlin +will display things in horizontal format +(a drawing area wider than it is tall, +with a menu across the top). +. +.B 1 +means that +.I gremlin +will display things in vertical format +(a drawing area taller than it is wide, +with a menu on the left side). +. +.I x +and +.I y +are floating-point values giving a positioning point to be used when +this file is read into another file. +. +The stuff on this line really isn't all that important; +a value of +.RB \[lq] "1 0.00 0.00" \[rq] +is suggested. +. +. +.IP \[bu] +The rest of the file consists of zero or more element specifications. +. +After the last element specification is a line containing the string +.RB \[lq] \-1 \[rq]. +. +. +.IP \[bu] +Lines longer than 127 characters are truncated to that length. +. +. +.\" ==================================================================== +.SS "Element specifications" +.\" ==================================================================== +. +.IP \[bu] 2n +The first line of each element contains a single decimal number giving +the type of the element (AED) or its name (Sun/X11). +. +. +.IP +.ie t .ne 18v +.el .ne 19v +.TS +center, tab(@); +css +ccc +nBlBl. +\f[I]gremlin\f[] File Format: Object Type Specification +_ +AED Number@Sun/X11 Name@Description +0@BOTLEFT@bottom-left-justified text +1@BOTRIGHT@bottom-right-justified text +2@CENTCENT@center-justified text +3@VECTOR@vector +4@ARC@arc +5@CURVE@curve +6@POLYGON@polygon +7@BSPLINE@b-spline +8@BEZIER@B\['e]zier +10@TOPLEFT@top-left-justified text +11@TOPCENT@top-center-justified text +12@TOPRIGHT@top-right-justified text +13@CENTLEFT@left-center-justified text +14@CENTRIGHT@right-center-justified text +15@BOTCENT@bottom-center-justified text +.TE +. +. +.IP \[bu] +After the object type comes a variable number of lines, +each specifying a point used to display the element. +. +Each line contains an x-coordinate and a y-coordinate in floating-point +format, +separated by spaces. +. +The list of points is terminated by a line containing the string +.RB \[lq] "\-1.0 \-1.0" \[rq] +(AED) or a single asterisk, +.RB \[lq] * \[rq] +(Sun/X11). +. +. +.IP \[bu] +After the points comes a line containing two decimal values, +giving the brush and size for the element. +. +The brush determines the style in which things are drawn. +. +For vectors, +arcs, +and curves there are six valid brush values. +. +. +.IP +.TS +center, tab(@); +nB l. +1@thin dotted lines +2@thin dot-dashed lines +3@thick solid lines +4@thin dashed lines +5@thin solid lines +6@medium solid lines +.TE +. +. +.IP +For polygons, +one more value, +0, +is valid. +. +It specifies a polygon with an invisible border. +. +For text, +the brush selects a font as follows. +. +. +.IP +.TS +center, tab(@); +nB l. +1@roman (R font in \f[I]@g@troff\f[]) +2@italics (I font in \f[I]@g@troff\f[]) +3@bold (B font in \f[I]@g@troff\f[]) +4@special (S font in \f[I]@g@troff\f[]) +.TE +. +. +.IP +If you're using +.I @g@grn +to run your pictures through +.IR groff , +the font is really just a starting font. +. +The text string can contain formatting sequences like +\[lq]\[rs]fI\[rq] +or +\[lq]\[rs]d\[rq] +which may change the font +(as well as do many other things). +. +For text, +the size field is a decimal value between 1 and 4. +. +It selects the size of the font in which the text will be drawn. +. +For polygons, +this size field is interpreted as a stipple number to fill the polygon +with. +. +The number is used to index into a stipple font at print time. +. +. +.IP \[bu] +The last line of each element contains a decimal number and a string of +characters, +separated by a single space. +. +The number is a count of the number of characters in the string. +. +This information is used only for text elements, +and contains the text string. +. +There can be spaces inside the text. +. +For arcs, +curves, +and vectors, +the character count is zero +.RB ( 0 ), +followed by exactly one space before the newline. +. +. +.\" ==================================================================== +.SS Coordinates +.\" ==================================================================== +. +.I gremlin +was designed for AED terminals, +and its coordinates reflect the AED coordinate space. +. +For vertical pictures, +.IR x \~values +range 116 to 511, +and +.IR y \~values +from 0 to 483. +. +For horizontal pictures, +.IR x \~values +range from 0 to 511, +and +.IR y \~values +from 0 to 367. +. +Although you needn't absolutely stick to this range, +you'll get better results if you at least stay in this vicinity. +. +Also, +point lists are terminated by a point of +(\-1, +\-1), +so you shouldn't ever use negative coordinates. +. +.I gremlin +writes out coordinates using the +.MR printf 3 +format \[lq]%f1.2\[rq]; +it's probably a good idea to use the same format if you want to modify +the +.I @g@grn +code. +. +. +.\" ==================================================================== +.SS "Sun/X11 coordinates" +.\" ==================================================================== +. +There is no restriction on the range of coordinates used to create +objects in the Sun/X11 version of +.IR gremlin . +. +However, +files with negative coordinates +.I will +cause problems if displayed on the AED. +. +. +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +.B \-?\& +and +.B \-\-help +display a usage message, +while +.B \-v +and +.B \-\-version +show version information; +all exit afterward. +. +. +.TP +.B \-C +Recognize +.B .GS +and +.B .GE +(and +.BR .GF ) +even when followed by a character other than space or newline. +. +. +.TP +.BI \-F\~ dir +Search +.I dir +for subdirectories +.IR dev name +.RI ( name +is the name of the output driver) +for the +.I DESC +file before the default font directories +.IR @LOCALFONTDIR@ , +.IR @FONTDIR@ , +and +.IR @LEGACYFONTDIR@ . +. +. +.TP +.BI \-M\~ dir +Prepend +.I dir +to the search path for +.I gremlin +files. +. +The default search path is the current directory, +the home directory, +.if !'@COMPATIBILITY_WRAPPERS@'no' .IR @SYSTEMMACRODIR@ , +.IR @LOCALMACRODIR@ , +and +.IR @MACRODIR@ , +in that order. +.\". +.\". +.\".TP +.\".B \-s +.\"This switch causes the picture to be traversed twice: +.\"The first time, +.\"only the interiors of filled polygons +.\"(as borderless polygons) +.\"are printed. +.\". +.\"The second time, +.\"the outline is printed as a series of line segments. +.\". +.\"This way, +.\"postprocessors that overwrite rather than merge picture elements +.\"(such as PostScript) +.\"can still have text and graphics on a shaded background. +. +. +.TP +.BI \-T\~ dev +Prepare device output using output driver +.IR dev . +. +The default is +.BR @DEVICE@ . +. +See +.MR groff @MAN1EXT@ +for a list of valid devices. +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.IR @FONTDIR@/\:\%dev name /\:DESC +describes the output device +.IR name . +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +David Slattengren and Barry Roitblat wrote the original Berkeley +.IR grn . +. +Daniel Senderowicz and Werner Lemberg modified it for +.IR groff . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR gremlin 1 , +.MR groff @MAN1EXT@ , +.MR @g@pic @MAN1EXT@ , +.MR ideal 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_grn_1_man_C] +.do rr *groff_grn_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |