1GROPS(1)                    General Commands Manual                   GROPS(1)
2
3
4

NAME

6       grops - PostScript driver for groff
7

SYNOPSIS

9       grops [ -glmv ] [ -bn ] [ -cn ] [ -Fdir ] [ -ppapersize ]
10             [ -Pprologue ] [ -wn ] [ files... ]
11
12       It is possible to have whitespace between a command line option and its
13       parameter.
14

DESCRIPTION

16       grops translates the output of GNU troff to PostScript.  Normally grops
17       should be invoked by using  the  groff  command  with  a  -Tps  option.
18       (Actually,  this  is  the  default  for groff.)  If no files are given,
19       grops will read the standard input.  A filename of -  will  also  cause
20       grops  to read the standard input.  PostScript output is written to the
21       standard output.  When grops is run by groff options can be  passed  to
22       grops using the groff -P option.
23

OPTIONS

25       -bn    Workaround  broken spoolers and previewers.  Normally grops pro‐
26              duces output that conforms the Document Structuring  Conventions
27              version  3.0.   Unfortunately some spoolers and previewers can't
28              handle such output.  The value of n controls what grops does  to
29              its output acceptable to such programs.  A value of 0 will cause
30              grops not to employ any workarounds.  Add 1 if  no  %%BeginDocu‐
31              mentSetup  and  %%EndDocumentSetup comments should be generated;
32              this is needed for early versions of TranScript  that  get  con‐
33              fused  by anything between the %%EndProlog comment and the first
34              %%Page comment.  Add 2 if lines in included files beginning with
35              %!   should  be  stripped out; this is needed for Sun's pageview
36              previewer.  Add 4 if %%Page, %%Trailer and %%EndProlog  comments
37              should  be  stripped  out  of included files; this is needed for
38              spoolers that don't understand the %%BeginDocument and %%EndDoc‐
39              ument  comments.  Add 8 if the first line of the PostScript out‐
40              put should be %!PS-Adobe-2.0 rather than %!PS-Adobe-3.0; this is
41              needed  when  using Sun's Newsprint with a printer that requires
42              page reversal.  The default value can be specified by a
43
44                     broken n
45
46              command in the DESC file.  Otherwise the default value is 0.
47
48       -cn    Print n copies of each page.
49
50       -Fdir  Prepend directory dir/devname to the search path  for  prologue,
51              font,  and  device  description  files;  name is the name of the
52              device, usually ps.
53
54       -g     Guess the page length.   This  generates  PostScript  code  that
55              guesses  the page length.  The guess will be correct only if the
56              imageable area is vertically centered on the page.  This  option
57              allows  you  to  generate  documents that can be printed both on
58              letter (8.5×11) paper and on A4 paper without change.
59
60       -l     Print the document in landscape format.
61
62       -m     Turn manual feed on for the document.
63
64       -ppaper-size
65              Set physical dimension of output  medium.   This  overrides  the
66              papersize  and paperlength commands in the DESC file; it accepts
67              the same arguments as the papersize command.
68
69       -Pprologue-file
70              Use the file prologue-file (in the font path)  as  the  prologue
71              instead  of  the  default  prologue  file prologue.  This option
72              overrides the environment variable GROPS_PROLOGUE.
73
74       -wn    Lines should be drawn using a thickness of n thousandths  of  an
75              em.  If this option is not given, the line thickness defaults to
76              0.04 em.
77
78       -v     Print the version number.
79

USAGE

81       There are styles called R, I, B, and BI mounted  at  font  positions  1
82       to  4.  The fonts are grouped into families A, BM, C, H, HN, N, P and T
83       having members in each of these styles:
84
85              AR     AvantGarde-Book
86
87              AI     AvantGarde-BookOblique
88
89              AB     AvantGarde-Demi
90
91              ABI    AvantGarde-DemiOblique
92
93              BMR    Bookman-Light
94
95              BMI    Bookman-LightItalic
96
97              BMB    Bookman-Demi
98
99              BMBI   Bookman-DemiItalic
100
101              CR     Courier
102
103              CI     Courier-Oblique
104
105              CB     Courier-Bold
106
107              CBI    Courier-BoldOblique
108
109              HR     Helvetica
110
111              HI     Helvetica-Oblique
112
113              HB     Helvetica-Bold
114
115              HBI    Helvetica-BoldOblique
116
117              HNR    Helvetica-Narrow
118
119              HNI    Helvetica-Narrow-Oblique
120
121              HNB    Helvetica-Narrow-Bold
122
123              HNBI   Helvetica-Narrow-BoldOblique
124
125              NR     NewCenturySchlbk-Roman
126
127              NI     NewCenturySchlbk-Italic
128
129              NB     NewCenturySchlbk-Bold
130
131              NBI    NewCenturySchlbk-BoldItalic
132
133              PR     Palatino-Roman
134
135              PI     Palatino-Italic
136
137              PB     Palatino-Bold
138
139              PBI    Palatino-BoldItalic
140
141              TR     Times-Roman
142
143              TI     Times-Italic
144
145              TB     Times-Bold
146
147              TBI    Times-BoldItalic
148
149       There is also the following font which is not a member of a family:
150
151              ZCMI   ZapfChancery-MediumItalic
152
153       There are also some special fonts called SS and S.   Zapf  Dingbats  is
154       available  as  ZD  and a reversed version of ZapfDingbats (with symbols
155       pointing in the opposite direction) is available as ZDR;  most  charac‐
156       ters in these fonts are unnamed and must be accessed using \N.
157
158       The  default  color  for  \m and \M is black; for colors defined in the
159       `rgb' color space, setrgbcolor is used, for `cmy' and  `cmyk'  setcmyk‐
160       color, and for `gray' setgray.
161
162       grops  understands  various  X  commands  produced  using the \X escape
163       sequence; grops will only interpret commands that begin with a ps: tag.
164
165       \X'ps: exec code'
166              This executes the arbitrary PostScript commands  in  code.   The
167              PostScript  currentpoint  will  be set to the position of the \X
168              command before executing code.  The origin will be  at  the  top
169              left  corner  of  the page, and y coordinates will increase down
170              the page.  A procedure u will be  defined  that  converts  groff
171              units to the coordinate system in effect.  For example,
172
173                     .nr x 1i
174                     \X'ps: exec \nx u 0 rlineto stroke'
175
176              will  draw  a  horizontal  line  one  inch  long.  code may make
177              changes to the graphics state, but any changes will persist only
178              to the end of the page.  A dictionary containing the definitions
179              specified by the def and mdef will be on top of  the  dictionary
180              stack.   If  your  code adds definitions to this dictionary, you
181              should allocate space for them using \X'ps mdef n'.  Any defini‐
182              tions  will  persist only until the end of the page.  If you use
183              the \Y escape sequence with an argument that names a macro, code
184              can extend over multiple lines.  For example,
185
186                     .nr x 1i
187                     .de y
188                     ps: exec
189                     \nx u 0 rlineto
190                     stroke
191                     ..
192                     \Yy
193
194              is another way to draw a horizontal line one inch long.
195
196       \X'ps: file name'
197              This  is the same as the exec command except that the PostScript
198              code is read from file name.
199
200       \X'ps: def code'
201              Place a PostScript definition contained in code in the prologue.
202              There  should  be  at  most one definition per \X command.  Long
203              definitions can be split over several \X commands; all the  code
204              arguments are simply joined together separated by newlines.  The
205              definitions are placed in a dictionary  which  is  automatically
206              pushed on the dictionary stack when an exec command is executed.
207              If you use the \Y escape sequence with an argument that names  a
208              macro, code can extend over multiple lines.
209
210       \X'ps: mdef n code'
211              Like  def,  except  that  code  may contain up to n definitions.
212              grops needs to know how many definitions code contains  so  that
213              it  can  create  an appropriately sized PostScript dictionary to
214              contain them.
215
216       \X'ps: import file llx lly urx ury width [ height ]'
217              Import a PostScript graphic from file.  The arguments llx,  lly,
218              urx, and ury give the bounding box of the graphic in the default
219              PostScript coordinate system; they should all be  integers;  llx
220              and  lly are the x and y coordinates of the lower left corner of
221              the graphic; urx and ury are the x  and  y  coordinates  of  the
222              upper right corner of the graphic; width and height are integers
223              that give the desired width and height in  groff  units  of  the
224              graphic.   The  graphic will be scaled so that it has this width
225              and height and translated so that the lower left corner  of  the
226              graphic  is  located at the position associated with \X command.
227              If the height argument is omitted it will be scaled uniformly in
228              the x and y directions so that it has the specified width.  Note
229              that the contents of the  \X  command  are  not  interpreted  by
230              troff;  so  vertical  space for the graphic is not automatically
231              added, and the width and height arguments  are  not  allowed  to
232              have  attached  scaling indicators.  If the PostScript file com‐
233              plies with the Adobe Document Structuring Conventions  and  con‐
234              tains  a  %%BoundingBox  comment,  then  the bounding box can be
235              automatically extracted from within  groff  by  using  the  psbb
236              request.
237
238              The  -mps  macros  (which are automatically loaded when grops is
239              run by the groff command) include a PSPIC macro which  allows  a
240              picture to be easily imported.  This has the format
241
242                     .PSPIC [-L|-R|-I n] file [width [height]]
243
244              file  is the name of the file containing the illustration; width
245              and height give the desired width and  height  of  the  graphic.
246              The  width  and  height  arguments  may  have scaling indicators
247              attached; the default scaling indicator is i.  This  macro  will
248              scale the graphic uniformly in the x and y directions so that it
249              is no more than width wide and height  high.   By  default,  the
250              graphic  will be horizontally centered.  The -L and -R cause the
251              graphic to be left-aligned and right-aligned respectively.   The
252              -I option causes the graphic to be indented by n.
253
254       \X'ps: invis'
255       \X'ps: endinvis'
256              No  output  will be generated for text and drawing commands that
257              are bracketed  with  these  \X  commands.   These  commands  are
258              intended for use when output from troff will be previewed before
259              being processed with grops; if the previewer is unable  to  dis‐
260              play  certain characters or other constructs, then other substi‐
261              tute characters or constructs can  be  used  for  previewing  by
262              bracketing them with these \X commands.
263
264              For  example,  gxditview  is  not  able to display a proper \(em
265              character because the standard X11 fonts do not provide it; this
266              problem can be overcome by executing the following request
267
268                     .char \(em \X'ps: invis'\
269                     \Z'\v'-.25m'\h'.05m'\D'l .9m 0'\h'.05m''\
270                     \X'ps: endinvis'\(em
271
272              In this case, gxditview will be unable to display the \(em char‐
273              acter and will draw the line, whereas grops will print the  \(em
274              character and ignore the line.
275
276       The  input  to grops must be in the format output by troff(1).  This is
277       described in groff_out(5).  In addition the device and font description
278       files  for  the device used must meet certain requirements.  The device
279       and font description files  supplied  for  ps  device  meet  all  these
280       requirements.   afmtodit(1)  can  be used to create font files from AFM
281       files.  The resolution must be an integer  multiple  of  72  times  the
282       sizescale.  The ps device uses a resolution of 72000 and a sizescale of
283       1000.  The device description file should contain a command
284
285              paperlength n
286
287       which says that output should be generated which is suitable for print‐
288       ing  on  a  page  whose  length  is n machine units.  Common values are
289       792000 for letter paper and 841890 for paper in  A4  format.   Alterna‐
290       tively, it can contain
291
292              papersize string
293
294       to  specify a paper size; see groff_font(5) for more information.  Each
295       font description file must contain a command
296
297              internalname psname
298
299       which says that the PostScript name of the font is psname.  It may also
300       contain a command
301
302              encoding enc_file
303
304       which  says  that  the  PostScript  font  should be reencoded using the
305       encoding described in enc_file; this file should consist of a  sequence
306       of lines of the form:
307
308              pschar code
309
310       where  pschar  is the PostScript name of the character, and code is its
311       position in the encoding expressed as a decimal integer.  Lines  start‐
312       ing  with  #  and blank lines are ignored.  The code for each character
313       given in the font file must correspond to the code for the character in
314       encoding  file,  or to the code in the default encoding for the font if
315       the PostScript font is not to be reencoded.  This code can be used with
316       the  \N  escape  sequence in troff to select the character, even if the
317       character does not have a groff name.  Every character in the font file
318       must  exist  in  the  PostScript font, and the widths given in the font
319       file must match the widths used in the  PostScript  font.   grops  will
320       assume  that  a character with a groff name of space is blank (makes no
321       marks on the page); it can make use of such  a  character  to  generate
322       more efficient and compact PostScript output.
323
324       grops  can  automatically  include  the downloadable fonts necessary to
325       print  the  document.   Any  downloadable  fonts  which  should,   when
326       required,   be   included   by   grops  must  be  listed  in  the  file
327       /usr/share/groff/1.18.1.4/font/devps/download; this should  consist  of
328       lines of the form
329
330              font filename
331
332       where font is the PostScript name of the font, and filename is the name
333       of the file containing the font; lines beginning with # and blank lines
334       are  ignored;  fields may be separated by tabs or spaces; filename will
335       be searched for using the same mechanism that is used  for  groff  font
336       metric files.  The download file itself will also be searched for using
337       this mechanism; currently, only the first found file in the  font  path
338       is used.
339
340       If  the  file  containing a downloadable font or imported document con‐
341       forms to the Adobe Document Structuring Conventions,  then  grops  will
342       interpret any comments in the files sufficiently to ensure that its own
343       output is conforming.  It will also supply any  needed  font  resources
344       that  are  listed  in  the  download  file  as  well as any needed file
345       resources.  It is also able to handle inter-resource dependencies.  For
346       example, suppose that you have a downloadable font called Garamond, and
347       also a downloadable font called Garamond-Outline which depends on Gara‐
348       mond (typically it would be defined to copy Garamond's font dictionary,
349       and change the PaintType), then it is  necessary  for  Garamond  to  be
350       appear  before Garamond-Outline in the PostScript document.  grops will
351       handle this automatically provided that the downloadable font file  for
352       Garamond-Outline  indicates  its dependence on Garamond by means of the
353       Document Structuring Conventions, for example  by  beginning  with  the
354       following lines
355
356              %!PS-Adobe-3.0 Resource-Font
357              %%DocumentNeededResources: font Garamond
358              %%EndComments
359              %%IncludeResource: font Garamond
360
361       In this case both Garamond and Garamond-Outline would need to be listed
362       in the download file.  A downloadable font should not include  its  own
363       name in a %%DocumentSuppliedResources comment.
364
365       grops will not interpret %%DocumentFonts comments.  The %%DocumentNeed‐
366       edResources, %%DocumentSuppliedResources, %%IncludeResource, %%BeginRe‐
367       source  and %%EndResource comments (or possibly the old %%DocumentNeed‐
368       edFonts, %%DocumentSuppliedFonts, %%IncludeFont, %%BeginFont and %%End‐
369       Font comments) should be used.
370
371   TrueType fonts
372       TrueType  fonts  can  be  used with grops if converted first to Type 42
373       format, an especial PostScript wrapper equivalent  to  the  PFA  format
374       mentioned in pfbtops(1).  There are several different methods to gener‐
375       ate a type42 wrapper and most of them involve the use of  a  PostScript
376       interpreter  such  as Ghostscript — see gs(1).  Yet, the easiest method
377       involves the use  of  the  application  ttftot42.   This  program  uses
378       freetype(3)  (version 1.3.1) to generate type42 font wrappers and well-
379       formed AFM files that can be fed to the afmtodit(1)  script  to  create
380       appropriate  metric files.  The resulting font wrappers should be added
381       to the download file.  ttftot42 source code can be downloaded from
382       ftp://www.giga.or.at/pub/nih/ttftot42/ ⟨ftp://www.giga.or.at/pub/nih/
383       ttftot42/⟩.
384

ENVIRONMENT

386       GROPS_PROLOGUE
387              If this is set to foo, then grops will use the file foo (in  the
388              font  path)  instead of the default prologue file prologue.  The
389              option -P overrides this environment variable.
390

FILES

392       /usr/share/groff/1.18.1.4/font/devps/DESC
393              Device description file.
394
395       /usr/share/groff/1.18.1.4/font/devps/F
396              Font description file for font F.
397
398       /usr/share/groff/1.18.1.4/font/devps/download
399              List of downloadable fonts.
400
401       /usr/share/groff/1.18.1.4/font/devps/text.enc
402              Encoding used for text fonts.
403
404       /usr/share/groff/1.18.1.4/tmac/ps.tmac
405              Macros for use with grops; automatically loaded by troffrc
406
407       /usr/share/groff/1.18.1.4/tmac/pspic.tmac
408              Definition of PSPIC macro, automatically loaded by ps.tmac.
409
410       /usr/share/groff/1.18.1.4/tmac/psold.tmac
411              Macros to disable use of characters not present in  older  Post‐
412              Script printers (e.g. `eth' or `thorn').
413
414       /tmp/gropsXXXXXX
415              Temporary file.
416

SEE ALSO

418       afmtodit(1),  groff(1), troff(1), psbb(1), groff_out(5), groff_font(5),
419       groff_char(7)
420
421
422
423Groff Version 1.18.1.4          16 August 2002                        GROPS(1)
Impressum