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

NAME

6       gropdf - PDF driver for groff
7

SYNOPSIS

9       gropdf [-delvs] [-F dir] [-p papersize] [-y foundry] [-u [cmapfile]]
10              [files ...]
11
12       It is possible to have whitespace between a command line option and its
13       parameter.
14

DESCRIPTION

16       gropdf  translates  the  output  of  GNU troff to PDF.  Normally gropdf
17       should be invoked by using the groff command with a -Tpdf  option.   If
18       no  files  are given, gropdf reads the standard input.  A filename of -
19       also causes gropdf to read the standard input.  PDF output  is  written
20       to  the  standard  output.   When gropdf is run by groff options can be
21       passed to gropdf using groff's -P option.
22
23       See section FONT INSTALLATION below for a guide how  to  install  fonts
24       for gropdf.
25

OPTIONS

27       -d     Include debug information as comments within the PDF.  Also pro‐
28              duces an uncompressed PDF.
29
30       -e     Force all fonts to be embedded in the PDF.
31
32       -Fdir  Prepend directory dir/devname to the search path for  font,  and
33              device  description  files; name is the name of the device, usu‐
34              ally pdf.
35
36       -l     Print the document in landscape format.
37
38       -ppaper-size
39              Set physical dimension of output  medium.   This  overrides  the
40              papersize,  paperlength,  and  paperwidth  commands  in the DESC
41              file; it accepts the same arguments as  the  papersize  command.
42              See groff_font (5) for details.
43
44       -v     Print the version number.
45
46       -yfoundry
47              Set the foundry to use for selecting fonts of the same name.
48
49       -e     Forces gropdf to embed ALL fonts (even the 14 base PDF fonts).
50
51       -s     Append  a  comment  line  to end of PDF showing statistics, i.e.
52              number of pages in  document.   Ghostscript's  ps2pdf  complains
53              about this line if it is included, but works anyway.
54
55       -u
56       -ucmapfilename
57              Gropdf  normally includes a ToUnicode CMap with any font created
58              using text.enc as the encoding file, this  makes  it  easier  to
59              search  for words which contain ligatures.  You can include your
60              own CMap by specifying a cmapfilename or have no CMap at all  by
61              omitting the argument.
62

USAGE

64       The  input to gropdf must be in the format output by troff(1).  This is
65       described in groff_out(5).
66
67       In addition, the device and font description files for the device  used
68       must  meet certain requirements: The resolution must be an integer mul‐
69       tiple of 72 times the sizescale.  The pdf device uses a  resolution  of
70       72000 and a sizescale of 1000.
71
72       The  device  description  file  must  contain  a  valid paper size; see
73       groff_font(5) for more information.  gropdf uses the same Type 1  Adobe
74       postscript fonts as the grops device driver.  Although the PDF Standard
75       allows the use of other font types (like TrueType) this  implementation
76       only  accepts  the Type 1 postscript font.  Fewer Type 1 fonts are sup‐
77       ported natively in PDF documents than the standard 35  fonts  supported
78       by  grops  and all postscript printers, but all the fonts are available
79       since any which aren't supported natively are automatically embedded in
80       the PDF.
81
82       gropdf supports the concept of foundries, that is different versions of
83       basically the same font.  During install a Foundry file controls  where
84       fonts  are  found and builds groff fonts from the files it discovers on
85       your system.
86
87       Each font description file must contain a command
88
89              internalname psname
90
91       which says that the PostScript name  of  the  font  is  psname.   Lines
92       starting with # and blank lines are ignored.  The code for each charac‐
93       ter given in the font file must correspond to the code in  the  default
94       encoding  for  the  font.   This  code  can  be used with the \N escape
95       sequence in troff to select the character, even if the  character  does
96       not  have a groff name.  Every character in the font file must exist in
97       the PostScript font, and the widths given in the font file  must  match
98       the widths used in the PostScript font.
99
100       Note that gropdf is currently only able to display the first 256 glyphs
101       in any font.  This restriction will be lifted in a later version.
102
103       gropdf can automatically include the downloadable  fonts  necessary  to
104       print the document.  Fonts may be in PFA or PFB format.
105
106       Any  downloadable  fonts  which  should,  when required, be included by
107       gropdf       must       be       listed       in        the        file
108       /usr/share/groff/1.22.2/font/devpdf/download;  this  should  consist of
109       lines of the form
110
111              foundry font filename
112
113       where foundry is the foundry name or blank  for  the  default  foundry.
114       font  is  the  PostScript name of the font, and filename is the name of
115       the file containing the font; lines beginning with #  and  blank  lines
116       are ignored; fields must be separated by tabs; filename is searched for
117       using the same mechanism that is used for groff font metric files.  The
118       download  file  itself  is also searched for using this mechanism; cur‐
119       rently, only the first found file in the font path  is  used.   Foundry
120       names  are usually a single character (such as `U' for the URW Foundry)
121       or blank for the default foundry.  This default uses the same fonts  as
122       ghostscript uses when it embeds fonts in a PDF file.
123
124       In the default setup there are styles called R, I, B, and BI mounted at
125       font positions 1 to 4.  The fonts are grouped into families A,  BM,  C,
126       H, HN, N, P, and T having members in each of these styles:
127
128              AR     AvantGarde-Book
129              AI     AvantGarde-BookOblique
130              AB     AvantGarde-Demi
131              ABI    AvantGarde-DemiOblique
132              BMR    Bookman-Light
133              BMI    Bookman-LightItalic
134              BMB    Bookman-Demi
135              BMBI   Bookman-DemiItalic
136              CR     Courier
137              CI     Courier-Oblique
138              CB     Courier-Bold
139              CBI    Courier-BoldOblique
140              HR     Helvetica
141              HI     Helvetica-Oblique
142              HB     Helvetica-Bold
143              HBI    Helvetica-BoldOblique
144              HNR    Helvetica-Narrow
145              HNI    Helvetica-Narrow-Oblique
146              HNB    Helvetica-Narrow-Bold
147              HNBI   Helvetica-Narrow-BoldOblique
148              NR     NewCenturySchlbk-Roman
149              NI     NewCenturySchlbk-Italic
150              NB     NewCenturySchlbk-Bold
151              NBI    NewCenturySchlbk-BoldItalic
152              PR     Palatino-Roman
153              PI     Palatino-Italic
154              PB     Palatino-Bold
155              PBI    Palatino-BoldItalic
156              TR     Times-Roman
157              TI     Times-Italic
158              TB     Times-Bold
159              TBI    Times-BoldItalic
160
161       There is also the following font which is not a member of a family:
162
163              ZCMI   ZapfChancery-MediumItalic
164
165       There  are also some special fonts called S for the PS Symbol font. The
166       lower case greek characters are automatically  slanted  (to  match  the
167       SymbolSlanted  font  (SS)  available  to postscript).  Zapf Dingbats is
168       available as ZD, the "hand pointing  left"  glyph  (\lh)  is  available
169       since  it  has  been  defined  using  the \X'pdf: xrev' extension which
170       reverses the direction of letters within words.
171
172       The default color for \m and \M is black; for  colors  defined  in  the
173       `rgb'  color  space  setrgbcolor is used, for `cmy' and `cmyk' setcmyk‐
174       color, and for `gray' setgray.  Note that setcmykcolor is a  PostScript
175       LanguageLevel 2 command and thus not available on some older printers.
176
177       gropdf  understands some of the X commands produced using the \X escape
178       sequences supported by grops.   Specifically,  the  following  is  sup‐
179       ported.
180
181       \X'ps: invis'
182              Suppress output.
183
184       \X'ps: endinvis'
185              Stop suppressing output.
186
187       \X'ps:  exec  gsave currentpoint 2 copy translate n rotate neg exch neg
188       exch translate'
189              where n is the angle of rotation.  This is to support the  align
190              command in gpic.
191
192       \X'ps: exec grestore'
193              Again used by gpic to restore after rotation.
194
195       \X'ps: exec n setlinejoin'
196              where n can be one of the following values.
197
198              0 = Miter join
199              1 = Round join
200              2 = Bevel join
201
202       \X'ps: exec n setlinecap'
203              where n can be one of the following values.
204
205              0 = Butt cap
206              1 = Round cap, and
207              2 = Projecting square cap
208
209       \X'ps: ... pdfmark'
210              All the pdfmark macros installed by using -m pdfmark or -m mspdf
211              (see documentation in `pdfmark.pdf').  A subset of these  macros
212              are installed automatically when you use -Tpdf so you should not
213              need to use `-m pdfmark' for using most of the  PDF  functional‐
214              ity.
215
216       All other ps: tags are silently ignored.
217
218       One \X special used by the DVI driver is also recognised:
219
220       \X'papersize=paper-size'
221              where the paper-size parameter is the same as the papersize com‐
222              mand.  See groff_font(5) for details.  This means that  you  can
223              alter the page size at will within the PDF file being created by
224              gropdf.  If you do want to change the paper  size,  it  must  be
225              done before you start creating the page.
226
227       In addition, gropdf supports its own suite of pdf: tags.  The following
228       tags are supported:
229
230       \X'pdf: pdfpic file alignment width height line-length'
231              Place an image of the specified width containing the PDF drawing
232              from file file of desired width and height (if height is missing
233              or zero then it is scaled proportionally).  If alignment  is  -L
234              the  drawing  is  left  aligned.  If it is -C or -R a linelength
235              greater than the width of the drawing is required as  well.   If
236              width  is  specified as zero then the width is scaled in propor‐
237              tion to the height.
238
239       \X'pdf: xrev'
240              This toggles a flag which reverses  the  direction  of  printing
241              letter  by  letter,  i.e., each separate letter is reversed, not
242              the entire word.  This is useful for reversing the direction  of
243              glyphs  in  the  Dingbats  font.   To  return to normal printing
244              repeat the command again.
245
246       \X'pdf: markstart /ANN definition'
247              The macros which support PDF Bookmarks use this call  internally
248              to  start  the  definition  of  bookmark hotspot (user will have
249              called `.pdfhref L' with the text which  will  become  the  `hot
250              spot'  region).   Normally this is never used except from within
251              the pdfmark macros.
252
253       \X'pdf: markend'
254              The macros which support PDF Bookmarks use this call  internally
255              to  stop  the  definition  of  bookmark  hotspot (user will have
256              called `.pdfhref L' with the text which  will  become  the  `hot
257              spot'  region).   Normally this is never used except from within
258              the pdfmark macros.
259
260       \X'pdf: marksuspend'
261       \X'pdf: markrestart'
262              If you are using page traps to produce headings, footings, etc.,
263              you need to use these in case a `hot spot' crosses a page bound‐
264              ary, otherwise any text output by the heading or  footing  macro
265              will  be marked as part of the `hot spot'.  To stop this happen‐
266              ing just place `.pdfmarksuspend' and  `.pdfmarkrestart'  at  the
267              start  and end of the page trap macro, respectively.  (These are
268              just convenience macros which emit the \X  code.   These  macros
269              must only be used within page traps.)
270
271   Importing graphics
272       gropdf  only  supports importing other PDF files as graphics.  But that
273       PDF file may contain any of the graphic formats supported  by  the  PDF
274       standard (such as JPEG, PNG, GIF, etc.).  So any application which out‐
275       puts PDF can be used as an embedded file in gropdf.  The PDF  file  you
276       wish  to  insert  must  be  a single page and the drawing must just fit
277       inside the media size of the PDF file.  So, in inkscape(1)  or  gimp(1)
278       (for example) make sure the canvas size just fits the image.
279
280       The  PDF  parser used in gropdf has not been rigorously tested with all
281       possible applications which produce PDFs.  If you find  a  single  page
282       PDF  which fails to import properly, it is worth running it through the
283       pdftk(1) program by issuing the command:
284
285              pdftk oldfile.pdf output newfile.pdf
286
287       You may find that newfile.pdf will now load successfully.
288
289   TrueType and other font formats
290       gropdf does not support any other fonts except Adobe  Type  1  (PFA  or
291       PFB).
292

FONT INSTALLATION

294       This section gives a summary of the above explanations; it can serve as
295       a step-by-step font installation guide for gropdf.
296
297        ·  Convert your font to something groff understands.  This is either a
298           PostScript  Type  1 font in either PFA or PFB, together with an AFM
299           file.
300
301           The very first line in a PFA/PFB file contains this:
302
303                  %!PS-AdobeFont-1.0:
304
305           A PFB file has this also in the first line, but the string is  pre‐
306           ceded with some binary bytes.
307
308        ·  Convert  the  AFM  file  to  a groff font description file with the
309           afmtodit(1) program.  An example call is
310
311                  afmtodit Foo-Bar-Bold.afm map/textmap FBB
312
313           which converts the metric file `Foo-Bar-Bold.afm' to the groff font
314           `FBB'.   If  you  have a font family which comes with normal, bold,
315           italic, and bold italic faces, it is recommended to use the letters
316           R, B, I, and BI, respectively, as postfixes in the groff font names
317           to make groff's `.fam' request work.  An example is groff's  built-
318           in  Times-Roman font: The font family name is T, and the groff font
319           names are TR, TB, TI, and TBI.
320
321        ·  Install both the groff font description files and the  fonts  in  a
322           `devpdf'  subdirectory of the font path which groff finds.  See the
323           ENVIRONMENT section in the troff(1) man page which lists the actual
324           value  of the font path.  Note that groff doesn't use the AFM files
325           (but it is a good idea to store them anyway).
326
327        ·  Register all fonts which must be downloaded to the printer  in  the
328           `devpdf/download'  file.  Only the first occurrence of this file in
329           the font path is read.  This means that you should copy the default
330           `download'  file  to  the first directory in your font path and add
331           your fonts there.  To continue the above example we assume that the
332           PS font name for Foo-Bar-Bold.pfa is `XY-Foo-Bar-Bold' (the PS font
333           name is stored in the internalname field in  the  `FBB'  file)  and
334           belongs  to foundry `F', thus the following line should be added to
335           `download':
336
337                  F XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
338
339           Use a tab character to separate the fields, and the `foundry' field
340           should be null for the default foundry.
341

ENVIRONMENT

343       GROFF_FONT_PATH
344              A  list of directories in which to search for the devname direc‐
345              tory in addition to the default ones.   If,  in  the  `download'
346              file,  the  font  file  has  been specified with a full path, no
347              directories are searched.  See troff(1)  and  groff_font(5)  for
348              more details.
349

FILES

351       /usr/share/groff/1.22.2/font/devpdf/DESC
352              Device description file.
353
354       /usr/share/groff/1.22.2/font/devpdf/F
355              Font description file for font F.
356
357       /usr/share/groff/1.22.2/font/devpdf/U-F
358              Font  description  file  for font F (using foundry U rather than
359              the default foundry).
360
361       /usr/share/groff/1.22.2/font/devpdf/download
362              List of downloadable fonts.
363
364       /usr/share/groff/1.22.2/font/devpdf/Foundry
365              A Perl script used during install to locate suitable fonts.
366
367       /usr/share/groff/1.22.2/font/devpdf/enc/text.enc
368              Encoding used for text fonts.
369
370       /usr/share/groff/1.22.2/tmac/pdf.tmac
371              Macros for use with gropdf; automatically loaded by troffrc.
372

SEE ALSO

374       afmtodit(1),  groff(1),  grops(1),  troff(1),   grops(1),   pfbtops(1),
375       groff_out(5), groff_font(5), groff_char(7), groff_tmac(5)
376
377
378
379Groff Version 1.22.2            7 February 2013                      GROPDF(1)
Impressum