/contrib/groff/src/preproc/grn/grn.man

  1'\" t
  2.ig
  3Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
  4
  5Permission is granted to make and distribute verbatim copies of
  6this manual provided the copyright notice and this permission notice
  7are preserved on all copies.
  8
  9Permission is granted to copy and distribute modified versions of this
 10manual under the conditions for verbatim copying, provided that the
 11entire resulting derived work is distributed under the terms of a
 12permission notice identical to this one.
 13
 14Permission is granted to copy and distribute translations of this
 15manual into another language, under the above conditions for modified
 16versions, except that this permission notice may be included in
 17translations approved by the Free Software Foundation instead of in
 18the original English.
 19..
 20.
 21.do nr grn_C \n[.C]
 22.cp 0
 23.
 24.de TQ
 25.  br
 26.  ns
 27.  TP \\$1
 28..
 29.
 30.\" Like TP, but if specified indent is more than half
 31.\" the current line-length - indent, use the default indent.
 32.de Tp
 33.  ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
 34.  el .TP "\\$1"
 35..
 36.
 37.
 38.TH @G@GRN @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
 39.SH NAME
 40@g@grn \- groff preprocessor for gremlin files
 41.SH SYNOPSIS
 42.BR @g@grn
 43[
 44.B \-Cv
 45]
 46[
 47.BI \-T dev
 48]
 49[
 50.BI \-M dir
 51]
 52[
 53.BI \-F dir
 54]
 55[
 56.IR file\.\.\.\&
 57]
 58.PP
 59It is possible to have whitespace between a command line option and its
 60parameter.
 61.SH DESCRIPTION
 62.I @g@grn
 63is a preprocessor for including
 64.I gremlin
 65pictures in
 66.I groff
 67input.
 68.I @g@grn
 69writes to standard output, processing only input lines between two that
 70start with
 71.B .GS
 72and
 73.BR .GE.
 74Those lines must contain
 75.I @g@grn
 76commands (see below).
 77These commands request a
 78.I gremlin
 79file, and the picture in that file is
 80converted and placed in the
 81.I @g@troff
 82input stream.
 83The
 84.B .GS
 85request may be followed by a C, L, or R to center, left, or right
 86justify the whole
 87.I gremlin
 88picture (default justification is center).
 89If no
 90.I file
 91is mentioned, the standard input is read.
 92At the end of the picture, the position on the page is the bottom of the
 93.I gremlin
 94picture.
 95If the
 96.I @g@grn
 97entry is ended with
 98.B .GF
 99instead of
100.BR .GE ,
101the position is left at the top of the picture.
102.PP
103Please note that currently only the \-me macro package has support for
104.BR .GS ,
105.BR .GE ,
106and
107.BR .GF .
108.PP
109The following command-line options are understood:
110.TP
111.BI \-T dev
112Prepare output for printer
113.IR dev .
114The default device is
115.BR @DEVICE@ .
116See
117.BR groff (@MAN1EXT@)
118for acceptable devices.
119.TP
120.BI \-M dir
121Prepend
122.I dir
123to the default search path for
124.I gremlin
125files.
126The default path is (in that order) the current directory, the home
127directory,
128.BR @SYSTEMMACRODIR@ ,
129.BR @LOCALMACRODIR@ ,
130and
131.BR @MACRODIR@ .
132.TP
133.BI \-F dir
134Search
135.I dir
136for subdirectories
137.BI dev name
138.RI ( name
139is the name of the device) for the
140.B DESC
141file before the default font directories
142.BR @LOCALFONTDIR@ ,
143.BR @FONTDIR@ ,
144and
145.BR @LEGACYFONTDIR@ .
146.TP
147.B \-C
148Recognize
149.B .GS
150and
151.B .GE
152(and
153.BR .GF )
154even when followed by a character other than space or newline.
155.\".TP
156.\".B \-s
157.\"This switch causes the picture to be traversed twice:
158.\"The first time, only the interiors of filled polygons (as borderless
159.\"polygons) are printed.
160.\"The second time, the outline is printed as a series of line segments.
161.\"This way, postprocessors that overwrite rather than merge picture elements
162.\"(such as Postscript) can still have text and graphics on a shaded
163.\"background.
164.TP
165.B \-v
166Print the version number.
167.SH GRN COMMANDS
168Each input line between
169.B .GS
170and
171.B .GE
172may have one
173.I @g@grn
174command.
175Commands consist of one or two strings separated by white space, the first
176string being the command and the second its operand.
177Commands may be upper or lower case and abbreviated down to one character.
178.PP
179Commands that affect a picture's environment (those listed before
180.BR default ,
181see below) are only in effect for the current picture:
182The environment is reinitialized to the defaults at the start of the next
183picture.
184The commands are as follows:
185.TP
186.BI 1\  N
187.TQ
188.BI 2\  N
189.TQ
190.BI 3\  N
191.TQ
192.BI 4\  N
193Set
194.IR gremlin 's
195text size number 1 (2, 3, or 4) to
196.I N
197points.
198The default is 12 (16, 24, and 36, respectively).
199.TP
200.BI roman\  f
201.TQ
202.BI italics\  f
203.TQ
204.BI bold\  f
205.TQ
206.BI special\  f
207Set the roman (italics, bold, or special) font to
208.IR @g@troff 's
209font
210.I f
211(either a name or number).
212The default is R (I, B, and S, respectively).
213.TP
214.BI l\  f
215.TQ
216.BI stipple\  f
217Set the stipple font to
218.IR @g@troff 's
219stipple font
220.I f
221(name or number).
222The command
223.B stipple
224may be abbreviated down as far as `st' (to avoid
225confusion with
226.BR special ).
227There is
228.I no
229default for stipples (unless one is set by the default command), and it is
230invalid to include a
231.I gremlin
232picture with polygons without specifying a
233stipple font.
234.TP
235.BI x\  N
236.TQ
237.BI scale\  N
238Magnify the picture (in addition to any default magnification) by
239.IR N ,
240a floating point number larger than zero.
241The command
242.B scale
243may be abbreviated down to `sc'.
244.TP
245.BI narrow\  N
246.TQ
247.BI medium\  N
248.TQ
249.BI thick\  N
250Set the thickness of
251.IR gremlin 's
252narrow (medium and thick, respectively) lines to
253.I N
254times 0.15pt (this value can be changed at compile time).
255The default is 1.0 (3.0 and 5.0, respectively), which corresponds to 0.15pt
256(0.45pt and 0.75pt, respectively).
257A thickness value of zero selects the smallest available line thickness.
258Negative values cause the line thickness to be proportional to the current
259point size.
260.TP
261.BI pointscale\  <off/on>
262Scale text to match the picture.
263Gremlin text is usually printed in the point size specified with the
264commands
265.BR 1 ,
266.BR 2 ,
267.BR 3 ,
268.RB or\~ 4 ,
269regardless of any scaling factors in the picture.
270Setting
271.B pointscale
272will cause the point sizes to scale with the picture (within
273.IR @g@troff 's
274limitations, of course).
275An operand of anything but
276.I off
277will turn text scaling on.
278.TP
279.B default
280Reset the picture environment defaults to the settings in the current
281picture.
282This is meant to be used as a global parameter setting mechanism at the
283beginning of the
284.I @g@troff
285input file, but can be used at any time to reset the
286default settings.
287.TP
288.BI width\  N
289Forces the picture to be
290.I N
291inches wide.
292This overrides any scaling factors present in the same picture.
293.RB ` width
294.IR 0 '
295is ignored.
296.TP
297.BI height\  N
298Forces picture to be
299.I N
300inches high, overriding other scaling factors.
301If both `width' and `height' are specified the tighter constraint will
302determine the scale of the picture.
303.B Height
304and
305.B width
306commands are not saved with a
307.B default
308command.
309They will, however, affect point size scaling if that option is set.
310.TP
311.BI file\  name
312Get picture from
313.I gremlin
314file
315.I name
316located the current directory (or in the library directory; see the
317.B \-M
318option above).
319If two
320.B file
321commands are given, the second one overrides the first.
322If
323.I name
324doesn't exist, an error message is reported and processing continues from
325the
326.B .GE
327line.
328.SH NOTES ABOUT GROFF
329Since
330.I @g@grn
331is a preprocessor, it doesn't know about current indents, point sizes,
332margins, number registers, etc.
333Consequently, no
334.I @g@troff
335input can be placed between the
336.B .GS
337and
338.B .GE
339requests.
340However,
341.I gremlin
342text is now processed by
343.IR @g@troff ,
344so anything legal in a single line of
345.I @g@troff
346input is legal in a line of
347.I gremlin
348text (barring `.' directives at the beginning of a line).
349Thus, it is possible to have equations within a
350.I gremlin
351figure by including in the
352.I gremlin
353file
354.I eqn
355expressions enclosed by previously defined delimiters (e.g.
356.IR $$ ).
357.PP
358When using
359.I @g@grn
360along with other preprocessors, it is best to run
361.I tbl
362before
363.IR @g@grn ,
364.IR pic ,
365and/or
366.I ideal
367to avoid overworking
368.IR tbl .
369.I Eqn
370should always be run last.
371.PP
372A picture is considered an entity, but that doesn't stop
373.I @g@troff
374from trying to break it up if it falls off the end of a page.
375Placing the picture between `keeps' in \-me macros will ensure proper
376placement.
377.PP
378.I @g@grn
379uses
380.IR @g@troff 's 
381number registers
382.B g1
383through
384.B g9
385and sets registers
386.B g1
387and
388.B g2
389to the width and height of the
390.I gremlin
391figure (in device units) before entering the
392.B .GS
393request (this is for those who want to rewrite these macros).
394.SH GREMLIN FILE FORMAT
395There exist two distinct 
396.I gremlin
397file formats, the original format from the
398.I AED
399graphic terminal version, and the
400.I SUN
401or
402.I X11
403version.
404An extension to the
405.IR SUN / X11
406version allowing reference points with negative coordinates is
407.B not
408compatible with the
409.I AED
410version.
411As long as a 
412.I gremlin
413file does not contain negative coordinates, either format will be read
414correctly by either version of
415.I gremlin
416or
417.IR @g@grn .
418The other difference to the
419.IR SUN / X11
420format is the use of names for picture objects (e.g., POLYGON, CURVE)
421instead of numbers.
422Files representing the same picture are shown in Table 1 in each format.
423.sp
424.TS
425center, tab(@);
426l lw(0.1i) l.
427sungremlinfile@@gremlinfile
4280 240.00 128.00@@0 240.00 128.00
429CENTCENT@@2
430240.00 128.00@@240.00 128.00
431185.00 120.00@@185.00 120.00
432240.00 120.00@@240.00 120.00
433296.00 120.00@@296.00 120.00
434*@@-1.00 -1.00
4352 3@@2 3
43610 A Triangle@@10 A Triangle
437POLYGON@@6
438224.00 416.00@@224.00 416.00
43996.00 160.00@@96.00 160.00
440384.00 160.00@@384.00 160.00
441*@@-1.00 -1.00
4425 1@@5 1
4430@@0
444-1@@-1
445.T&
446css.
447.sp
448Table 1. File examples
449.TE
450.sp
451.IP \(bu
452The first line of each
453.I gremlin
454file contains either the string
455.B gremlinfile
456.RI ( AED
457version) or
458.B sungremlinfile
459.RI ( SUN / X11 )
460.IP \(bu
461The second line of the file contains an orientation, and
462.B x
463and
464.B y
465values for a positioning point, separated by spaces.
466The orientation, either
467.B 0
468or
469.BR 1 ,
470is ignored by the
471.IR SUN / X11
472version.
473.B 0
474means that
475.I gremlin
476will display things in horizontal format (drawing area wider than it is
477tall, with menu across top).
478.B 1
479means that
480.I gremlin
481will display things in vertical format (drawing area taller than it is wide,
482with menu on left side).
483.B x
484and
485.B y
486are floating point values giving a positioning point to be used when this
487file is read into another file.
488The stuff on this line really isn't all that important; a value of ``1 0.00
4890.00'' is suggested.
490.IP \(bu
491The rest of the file consists of zero or more element specifications.
492After the last element specification is a line containing the string ``-1''.
493.IP \(bu
494Lines longer than 127 characters are chopped to this limit.
495.SH ELEMENT SPECIFICATIONS
496.IP \(bu
497The first line of each element contains a single decimal number giving the
498type of the element
499.RI ( AED
500version) or its ASCII name
501.RI ( SUN / X11
502version).
503See Table 2.
504.sp
505.TS
506center, tab(@);
507css
508ccc
509nll.
510\fIgremlin\fP File Format \(mi Object Type Specification
511.sp
512\fIAED\fP Number@\fISUN\fP/\fIX11\fP Name@Description
5130@BOTLEFT@bottom-left-justified text
5141@BOTRIGHT@bottom-right-justified text
5152@CENTCENT@center-justified text
5163@VECTOR@vector
5174@ARC@arc
5185@CURVE@curve
5196@POLYGON@polygon
5207@BSPLINE@b-spline
5218@BEZIER@B\['e]zier
52210@TOPLEFT@top-left-justified text
52311@TOPCENT@top-center-justified text
52412@TOPRIGHT@top-right-justified text
52513@CENTLEFT@left-center-justified text
52614@CENTRIGHT@right-center-justified text
52715@BOTCENT@bottom-center-justified text
528.T&
529css.
530.sp
531Table 2.
532Type Specifications in \fIgremlin\fP Files
533.TE
534.sp
535.IP \(bu
536After the object type comes a variable number of lines, each specifying a
537point used to display the element.
538Each line contains an x-coordinate and a y-coordinate in floating point
539format, separated by spaces.
540The list of points is terminated by a line containing the string ``-1.0
541-1.0''
542.RI ( AED
543version) or a single asterisk, ``*''
544.RI ( SUN / X11
545version).
546.IP \(bu
547After the points comes a line containing two decimal values, giving the
548brush and size for the element.
549The brush determines the style in which things are drawn.
550For vectors, arcs, and curves there are six legal brush values:
551.sp
552.TS
553center, tab(@);
554ncw(0.1i)l.
5551 \(mi@@thin dotted lines
5562 \(mi@@thin dot-dashed lines
5573 \(mi@@thick solid lines
5584 \(mi@@thin dashed lines
5595 \(mi@@thin solid lines
5606 \(mi@@medium solid lines
561.TE
562.sp
563For polygons, one more value, 0, is legal.
564It specifies a polygon with an invisible border.
565For text, the brush selects a font as follows:
566.sp
567.TS
568center, tab(@);
569ncw(0.1i)l.
5701 \(mi@@roman (R font in groff)
5712 \(mi@@italics (I font in groff)
5723 \(mi@@bold (B font in groff)
5734 \(mi@@special (S font in groff)
574.TE
575.sp
576If you're using
577.I @g@grn
578to run your pictures through
579.IR groff ,
580the font is really just a starting font:
581The text string can contain formatting sequences like
582``\efI''
583or
584``\ed''
585which may change the font (as well as do many other things).
586For text, the size field is a decimal value between 1 and 4.
587It selects the size of the font in which the text will be drawn.
588For polygons, this size field is interpreted as a stipple number to fill the
589polygon with.
590The number is used to index into a stipple font at print time.
591.IP \(bu
592The last line of each element contains a decimal number and a string of
593characters, separated by a single space.
594The number is a count of the number of characters in the string.
595This information is only used for text elements, and contains the text
596string.
597There can be spaces inside the text.
598For arcs, curves, and vectors, this line of the element contains the string
599``0''.
600.SH NOTES ON COORDINATES
601.I gremlin
602was designed for
603.IR AED s,
604and its coordinates reflect the
605.I AED
606coordinate space.
607For vertical pictures, x-values range 116 to 511, and y-values from 0 to
608483.
609For horizontal pictures, x-values range from 0 to 511 and y-values range
610from 0 to 367.
611Although you needn't absolutely stick to this range, you'll get best results
612if you at least stay in this vicinity.
613Also, point lists are terminated by a point of (-1, -1), so you shouldn't
614ever use negative coordinates.
615.I gremlin
616writes out coordinates using format ``%f1.2''; it's probably a good idea to
617use the same format if you want to modify the
618.I @g@grn
619code.
620.SH NOTES ON SUN/X11 COORDINATES
621There is no longer a restriction on the range of coordinates used to create
622objects in the
623.IR SUN / X11
624version of
625.IR gremlin .
626However, files with negative coordinates
627.B will
628cause problems if displayed on the
629.IR AED .
630.SH FILES
631.Tp \w'@FONTDIR@/devname/DESC'u+3n
632.BI @FONTDIR@/dev name /DESC
633Device description file for device
634.IR name .
635.SH SEE ALSO
636.BR gremlin (1),
637.BR groff (@MAN1EXT@),
638.BR @g@pic (@MAN1EXT@),
639.BR ideal (1)
640.SH HISTORY
641.PP
642David Slattengren and Barry Roitblat wrote the original Berkeley
643.IR @g@grn .
644.PP
645Daniel Senderowicz and Werner Lemberg modified it for
646.IR groff .
647.
648.cp \n[grn_C]
649.
650.\" Local Variables:
651.\" mode: nroff
652.\" End: