Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GRN(1)			    General Commands Manual			GRN(1)

NAME
       grn - groff preprocessor	for gremlin files

SYNOPSIS
       grn [ -Cv ] [ -Tdev ] [ -Mdir ] [ -Fdir ] [ file... ]

       It is possible to have whitespace between a command line	option and its
       parameter.

DESCRIPTION
       grn is a	preprocessor for including gremlin pictures  in	 groff	input.
       grn  writes to standard output, processing only input lines between two
       that start with .GS and .GE.  Those lines  must	contain	 grn  commands
       (see below).  These commands request a gremlin file, and	the picture in
       that file is converted and placed in the	troff input stream.   The  .GS
       request	may be followed	by a C,	L, or R	to center, left, or right jus-
       tify the	whole gremlin picture (default justification is	 center).   If
       no  file	 is  mentioned,	the standard input is read.  At	the end	of the
       picture,	the position on	the page is the	bottom of the gremlin picture.
       If the grn entry	is ended with .GF instead of .GE, the position is left
       at the top of the picture.

       Please note that	currently only the -me macro package has  support  for
       .GS, .GE, and .GF.

       The following command-line options are understood:

       -Tdev  Prepare  output for printer dev.	The default device is ps.  See
	      groff(1) for acceptable devices.

       -Mdir  Prepend dir to the default search	path for gremlin  files.   The
	      default  path is (in that	order) the current directory, the home
	      directory,       /usr/local/lib/groff/site-tmac,	      /usr/lo-
	      cal/share/groff/site-tmac,	      and	      /usr/lo-
	      cal/share/groff/1.18.1/tmac.

       -Fdir  Search dir for subdirectories devname (name is the name  of  the
	      device)  for  the	 DESC file before the default font directories
	      /usr/local/share/groff/site-font,			      /usr/lo-
	      cal/share/groff/1.18.1/font, and /usr/lib/font.

       -C     Recognize	.GS and	.GE (resp.  .GF) even when followed by a char-
	      acter other than space or	newline.

       -v     Print the	version	number.

GRN COMMANDS
       Each input line between .GS and .GE may have one	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	lower case and abbreviated down	to one character.

       Commands	 that  affect a	picture's environment (those listed before de-
       fault, see below) are only in effect for	the current picture: The envi-
       ronment	is reinitialized to the	defaults at the	start of the next pic-
       ture.  The commands are as follows:

       1 N
       2 N
       3 N
       4 N    Set gremlin's text size number 1 (2, 3, or 4) to N points.   The
	      default is 12 (resp. 16, 24, and 36).

       roman f
       italics f
       bold f
       special f
	      Set the roman (italics, bold, or special)	font to	troff's	font f
	      (either a	name or	number).  The default is R (resp.  I,  B,  and
	      S).

       l f
       stipple f
	      Set the stipple font to troff's stipple font f (name or number).
	      The command stipple may be abbreviated down as far as  `st'  (to
	      avoid confusion with special).  There is no default for stipples
	      (unless one is set by the	default	command), and it is invalid to
	      include  a  gremlin  picture  with polygons without specifying a
	      stipple font.

       x N
       scale N
	      Magnify the picture (in addition to any  default	magnification)
	      by  N,  a	 floating  point number	larger than zero.  The command
	      scale may	be abbreviated down to `sc'.

       narrow N
       medium N
       thick N
	      Set the thickness	of gremlin's narrow (resp. medium  and	thick)
	      lines  to	 N  times 0.15pt (this value can be changed at compile
	      time).  The default is 1.0 (resp.	3.0  and  5.0),	 which	corre-
	      sponds  to  0.15pt (resp.	0.45pt and 0.75pt).  A thickness value
	      of zero selects the smallest available line thickness.  Negative
	      values  cause  the line thickness	to be proportional to the cur-
	      rent point size.

       pointscale _off/on_
	      Scale text to  match  the	 picture.   Gremlin  text  is  usually
	      printed	in   the   point  size	specified  with	 the  commands
	      1, 2, 3, or 4 regardless of any scaling factors in the  picture.
	      Setting  pointscale will cause the point sizes to	scale with the
	      picture (within troff's limitations, of course).	An operand  of
	      anything but off will turn text scaling on.

       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 troff input file, but
	      can be used at any time to reset the default settings.

       width N
	      Forces the picture to be N  inches  wide.	  This	overrides  any
	      scaling  factors	present	in the same picture.  `width 0'	is ig-
	      nored.

       height N
	      Forces picture to	be N inches  high,  overriding	other  scaling
	      factors.	If both	`width'	and `height' are specified the tighter
	      constraint will determine	the scale of the picture.  Height  and
	      width commands are not saved with	a default command.  They will,
	      however, affect point size scaling if that option	is set.

       file name
	      Get picture from gremlin file name located the current directory
	      (or  in the library directory; see the -M	option above).	If two
	      file commands are	given, the second one overrides	the first.  If
	      name  doesn't exist, an error message is reported	and processing
	      continues	from the .GE line.

NOTES ABOUT GROFF
       Since grn is a preprocessor, it doesn't	know  about  current  indents,
       point  sizes,  margins,	number registers, etc.	Consequently, no troff
       input can be placed between the .GS and .GE requests.  However, gremlin
       text  is	 now processed by troff, so anything legal in a	single line of
       troff input is legal in a line of gremlin text (barring `.'  directives
       at  the	beginning  of a	line).	Thus, it is possible to	have equations
       within a	gremlin	figure by including in the gremlin  file  eqn  expres-
       sions enclosed by previously defined delimiters (e.g.  $$).

       When  using  grn	 along with other preprocessors, it is best to run tbl
       before grn, pic,	and/or ideal to	avoid overworking tbl.	Eqn should al-
       ways be run last.

       A  picture  is  considered  an entity, but that doesn't stop troff from
       trying to break it up if	it falls off the end of	a page.	  Placing  the
       picture between `keeps' in -me macros will ensure proper	placement.

       grn  uses  troff's number registers g1 through g9 and sets registers g1
       and g2 to the width and height of the gremlin figure (in	device	units)
       before  entering	the .GS	request	(this is for those who want to rewrite
       these macros).

GREMLIN	FILE FORMAT
       There exist two distinct	gremlin	file formats, the original format from
       the  AED	 graphic terminal version, and the SUN or X11 version.	An ex-
       tension to the SUN/X11 version allowing reference points	with  negative
       coordinates is not compatible with the AED version.  As long as a grem-
       lin file	does not contain negative coordinates, either format  will  be
       read  correctly by either version of gremlin or grn.  The other differ-
       ence to the SUN/X11 format is the use  of  names	 for  picture  objects
       (e.g., POLYGON, CURVE) instead of numbers.  Files representing the same
       picture are shown in Table 1 in each format.

			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

			       Table 1.	File examples

       o      The first	line of	each gremlin file contains either  the	string
	      gremlinfile (AED version)	or sungremlinfile (SUN/X11)

       o      The second line of the file contains an orientation, and x and y
	      values for a positioning point, separated	by spaces.  The	orien-
	      tation,  either  0  or  1, is ignored by the SUN/X11 version.  0
	      means that gremlin will  display	things	in  horizontal	format
	      (drawing	area  wider than it is tall, with menu across top).  1
	      means that gremlin will display things in	vertical format	(draw-
	      ing area taller than it is wide, with menu on left side).	 x and
	      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  ``1  0.00
	      0.00'' is	suggested.

       o      The rest of the file consists of zero or more element specifica-
	      tions.  After the	last element specification is a	line  contain-
	      ing the string ``-1''.

       o      Lines longer than	127 characters are chopped to this limit.

ELEMENT	SPECIFICATIONS
       o      The  first line of each element contains a single	decimal	number
	      giving the type of the element (AED version) or its  ASCII  name
	      (SUN/X11 version).  See Table 2.

		      gremlin 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	      Bezier
		      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

					  Table	2.
			    Type Specifications	in gremlin Files

       o      After  the  object  type	comes a	variable number	of lines, each
	      specifying a point used to display the element.  Each line  con-
	      tains  an	x-coordinate and a y-coordinate	in floating point for-
	      mat, separated by	spaces.	 The list of points is terminated by a
	      line containing the string ``-1.0	-1.0'' (AED version) or	a sin-
	      gle asterisk, ``*'' (SUN/X11 version).

       o      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 legal brush values:

			      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

	      For polygons, one	more value, 0, is legal.  It specifies a poly-
	      gon with an invisible border.  For text,	the  brush  selects  a
	      font as follows:

			    1 -	      roman (R font in groff)
			    2 -	      italics (I font in groff)
			    3 -	      bold (B font in groff)
			    4 -	      special (S font in groff)

	      If you're	using grn to run your pictures through groff, the font
	      is really	just a starting	font: The text string can contain for-
	      matting  sequences  like	``\fI''	or ``\d'' 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 poly-
	      gon with.	 The number is used to index into a  stipple  font  at
	      print time.

       o      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 in-
	      formation	is only	used for text elements,	and contains the  text
	      string.  There can be spaces inside the text.  For arcs, curves,
	      and vectors, this	line of	the element contains the string	``0''.

NOTES ON COORDINATES
       gremlin was designed for	AEDs, and its coordinates reflect the AED  co-
       ordinate	 space.	 For vertical pictures,	x-values range 116 to 511, and
       y-values	from 0 to 483.	For horizontal pictures, x-values range	from 0
       to  511	and  y-values range from 0 to 367.  Although you needn't abso-
       lutely stick to this range, you'll get best 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.   gremlin
       writes  out  coordinates	 using	format ``%f1.2''; it's probably	a good
       idea to use the same format if you want to modify the grn code.

NOTES ON SUN/X11 COORDINATES
       There is	no longer a restriction	on the range of	 coordinates  used  to
       create  objects in the SUN/X11 version of gremlin.  However, files with
       negative	coordinates will cause problems	if displayed on	the AED.

FILES
       /usr/local/share/groff/1.18.1/font/devname/DESC
	      Device description file for device name.

SEE ALSO
       gremlin(1), groff(1), pic(1), ideal(1)

HISTORY
       David Slattengren and Barry Roitblat wrote the original Berkeley	grn.

       Daniel Senderowicz and Werner Lemberg modified it for groff.

Groff Version 1.18.1		07 October 2002				GRN(1)

NAME | SYNOPSIS | DESCRIPTION | GRN COMMANDS | NOTES ABOUT GROFF | GREMLIN FILE FORMAT | ELEMENT SPECIFICATIONS | NOTES ON COORDINATES | NOTES ON SUN/X11 COORDINATES | FILES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=grn&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help