Debian Codegraph @

upstream/debian-unstable/man1/gropdf.1

raw
1 .TH gropdf 1 "2026-04-22" "groff 1.24.1"
2 .SH Name
3 gropdf \-
4 .I groff
5 output driver for Portable Document Format
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright 2011-2026 Free Software Foundation, Inc.
13 .\" 2026 G. Branden Robinson
14 .\"
15 .\" Permission is granted to make and distribute verbatim copies of this
16 .\" manual provided the copyright notice and this permission notice are
17 .\" preserved on all copies.
18 .\"
19 .\" Permission is granted to copy and distribute modified versions of
20 .\" this manual under the conditions for verbatim copying, provided that
21 .\" the entire resulting derived work is distributed under the terms of
22 .\" a permission notice identical to this one.
23 .\"
24 .\" Permission is granted to copy and distribute translations of this
25 .\" manual into another language, under the above conditions for
26 .\" modified versions, except that this permission notice may be
27 .\" included in translations approved by the Free Software Foundation
28 .\" instead of in the original English.
29 .
30 .
31 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
32 .do nr *groff_gropdf_1_man_C \n[.cp]
33 .cp 0
34 .
35 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
36 .nr do-fallback 0
37 .if !\n(.f .nr do-fallback 1 \" mandoc
38 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
39 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
40 .if \n[do-fallback] \{\
41 . de MR
42 . ie \\n(.$=1 \
43 . I \%\\$1
44 . el \
45 . IR \%\\$1 (\\$2)\\$3
46 . .
47 .\}
48 .rr do-fallback
49 .
50 .\" This macro definition is poor style from a portability standpoint,
51 .\" but it's a good test and demonstration of the standard font
52 .\" repertoire for the devices where it has any effect at all, and so
53 .\" should be retained.
54 .de FT
55 . if \\n[.$] .if !F \\$1 .ftr \\$1 R
56 . if '\\*(.T'ps' .ft \\$1
57 . if '\\*(.T'pdf' .ft \\$1
58 ..
59 .
60 .\" This man page employs an unusual character.
61 .if !c \[u2717] .char \[u2717] X
62 .
63 .
64 .\" ====================================================================
65 .SH Synopsis
66 .\" ====================================================================
67 .
68 .SY gropdf
69 .RB [ \-delsW ]
70 .RB [{ \-f | \-\-format-options }\~\c
71 .IR bit-vector ]
72 .RB [ \-F\~\c
73 .IR font-directory ]
74 .RB [ \-I\~\c
75 .IR inclusion-directory ]
76 .RB [ \-p\~\c
77 .IR paper-format ]
78 .RB [ \-\-pdfver\~\c
79 .RB { 1.4 \||\| 1.7 }]
80 \#.RB [ \-w\~\c
81 \#.IR n ]
82 .RB [ \-u\~\c
83 .RI [ cmap-file ]]
84 .RB [ \-y\~\c
85 .IR foundry ]
86 .RI [ file\~ .\|.\|.]
87 .YS
88 .
89 .
90 .P
91 .SY gropdf
92 .B \-\-help
93 .YS
94 .
95 .
96 .P
97 .SY gropdf
98 .B \-v
99 .YS
100 .
101 .SY gropdf
102 .B \%\-\-version
103 .YS
104 .
105 .
106 .\" ====================================================================
107 .SH Description
108 .\" ====================================================================
109 .
110 The GNU
111 .I roff
112 PDF output driver translates the output of
113 .MR \%troff 1
114 into Portable Document Format.
115 .
116 Normally,
117 .I gropdf
118 is invoked by
119 .MR groff 1
120 when the latter is given the
121 .RB \[lq] \-T\~pdf \[rq]
122 option.
123 .
124 (In this installation,
125 .B \%ps
126 is the default output device.)
127 .
128 Use
129 .IR groff 's
130 .B \-P
131 option to pass any options shown above to
132 .IR gropdf .
133 .
134 If no
135 .I file
136 arguments are given,
137 or if
138 .I file
139 is \[lq]\-\[rq],
140 .I gropdf
141 reads the standard input stream.
142 .
143 It writes to the standard output stream.
144 .
145 .
146 .P
147 See section \[lq]Font installation\[rq] below for a guide to installing
148 fonts for
149 .IR gropdf .
150 .
151 .
152 .\" ====================================================================
153 .SH Options
154 .\" ====================================================================
155 .
156 .B \-\-help
157 displays a usage message,
158 while
159 .B \-v
160 and
161 .B \%\-\-version
162 show version information;
163 all exit afterward.
164 .
165 .
166 .TP 8n \" "-F dir" + 2n
167 .B \-d
168 Include debug information as comments within the PDF.
169 .
170 Also produces an uncompressed PDF.
171 .
172 .
173 .TP
174 .B \-e
175 Forces
176 .I gropdf
177 to embed
178 .I all
179 fonts (even the 14 base PDF fonts).
180 .
181 .
182 .TP
183 .BI \-\-format\-options\~ bit-vector
184 .TQ
185 .BI \-f\~ bit-vector
186 Specify advanced options for
187 .I gropdf.
188 .
189 Familiarity with the
190 .UR https://\:www\:.pdfa\-inc\:.org/\:product/\
191 \:iso\-32000\-2\-pdf\-2\-0\-bundle\-sponsored\-access/
192 ISO\~32000 PDF standard
193 .UE
194 is helpful.
195 .
196 The
197 .I bit-vector
198 argument is an integer
199 that configures characteristics of the generated PDF.
200 .
201 Add the following values to combine them.
202 .
203 .
204 .IP
205 .RS \" One inset to align with the indentation of `TP`...
206 .RS \" ...and one more to get "inboard" of it.
207 .TS
208 L L
209 Lb Lx.
210 Value Meaning
211 _
212 1 Subset included Type 1 fonts.
213 2 T{
214 Use more compact format for text by including space as a character.
215 Fonts that do not include space as a glyph
216 may conflict with this feature.
217 .\" GBR: How? Will there be an error message?
218 T}
219 4 T{
220 Compress all data streams.
221 T}
222 8 T{
223 Don't embed font files.
224 .
225 (A font required by the document is not embedded;
226 usually not useful.)
227 T}
228 .TE
229 .RE
230 .RE
231 .
232 .
233 .IP
234 The default feature combination is 7.
235 .
236 To mimic what
237 .I gropdf
238 from
239 .I groff
240 1.23 produced,
241 specify \[lq]6\[rq] to turn off subsetting.
242 .
243 .
244 .TP
245 .BI \-F " dir"
246 Prepend directory
247 .IR dir /dev name
248 to the search path for font, and device description files;
249 .I name
250 is the name of the device, usually
251 .BR pdf .
252 .
253 .
254 .TP
255 .BI \-I\~ dir
256 Search the directory
257 .I dir
258 for files named in
259 .B \[rs]X\[aq]pdf: pdfpic\[aq]
260 device extension commands.
261 .
262 .B \-I
263 may be specified more than once;
264 each
265 .I dir
266 is searched in the given order.
267 .
268 To search the current working directory before others,
269 add
270 .RB \[lq] "\-I .\&" \[rq]
271 at the desired place;
272 it is otherwise searched last.
273 .
274 .
275 .TP
276 .B \-l
277 Orient the document in landscape format.
278 .
279 .
280 .TP
281 .BI \-p " paper-format"
282 Set the physical dimensions of the output medium.
283 .
284 This overrides the
285 .BR papersize ,
286 .BR paperlength ,
287 and
288 .B paperwidth
289 directives in the
290 .I DESC
291 file;
292 it accepts the same arguments as the
293 .B papersize
294 directive.
295 .
296 See
297 .MR groff_font 5
298 for details.
299 .
300 .
301 .TP
302 .BR "\-\-pdfver " { 1.4 \||\| 1.7 }
303 PDF version 1.7 introduced a more compact object format;
304 this is now the default.
305 .
306 If you require the original format
307 (as produced by
308 .I gropdf
309 1.23)
310 set the version to
311 .BR 1.4 .
312 .
313 .
314 .TP
315 .B \-s
316 Append a comment line to end of PDF showing statistics,
317 i.e.\& number of pages in document.
318 .
319 Ghostscript's
320 .B ps2pdf
321 complains about this line if it is included, but works anyway.
322 .
323 .
324 .TP
325 .BR \-u \~[\c
326 .IR cmap-file ]
327 .I gropdf
328 normally includes a ToUnicode CMap with any font created using
329 .I text.enc
330 as the encoding file,
331 this makes it easier to search for words which contain ligatures.
332 .
333 You can include your own CMap by specifying a
334 .I cmap-file
335 or have no CMap at all by omitting the argument.
336 .
337 .
338 .TP
339 .B \-W
340 Exit with failure status if any warnings are issued.
341 .
342 .
343 .\" .TP
344 .\" .BI \-w n
345 .\" Lines should be drawn using a thickness of
346 .\" .IR n \~\c
347 .\" thousandths of an em.
348 .\" .
349 .\" If this option is not given, the line thickness defaults to
350 .\" 0.04\~em.
351 .\" .
352 .\" .
353 .TP
354 .BI \-y " foundry"
355 Set the foundry to use for selecting fonts of the same name.
356 .
357 .
358 .\" ====================================================================
359 .SH Usage
360 .\" ====================================================================
361 .
362 .IR gropdf 's
363 input must be in the format produced by
364 .MR \%troff 1
365 and described in
366 .MR groff_out 5 .
367 .
368 Further,
369 its device and font description files must meet certain requirements.
370 .
371 The device
372 .B resolution
373 must be an integer multiple of\~72 times
374 .BR sizescale .
375 .
376 By default,
377 .I gropdf
378 uses a
379 .B resolution
380 of 72000 and a
381 .B sizescale
382 of 1000.
383 .
384 A valid paper format is mandatory;
385 see
386 .MR groff_font 5 .
387 .
388 While the PDF standard allows several font file formats
389 (like TrueType),
390 at present
391 .I gropdf
392 accepts only the same Type\~1 Adobe PostScript format as
393 .MR grops 1 .
394 .
395 Fewer Type\~1 fonts are supported natively in PDF documents than the
396 standard 35 fonts supported by
397 .I grops
398 and PostScript printers, \" XXX: strictly, PostScript Level 2, right?
399 but all are available since
400 .I gropdf
401 automatically embeds any that aren't specified by the PDF standard.
402 .
403 .
404 .P
405 .I gropdf
406 supports
407 .I foundries
408 that permit multiple providers to supply the same
409 .I groff
410 font names.
411 .
412 .IR groff 's
413 compilation process
414 attempts to locate Type\~1 fonts on the system,
415 populates a
416 .I Foundry
417 file with their locations,
418 and generates font description files corresponding to them.
419 .
420 Font description files can also be added after installation.
421 Each such file must contain a directive
422 .RS
423 .BI internalname\ psname
424 .RE
425 that maps the
426 .I groff
427 font name
428 (such as \[lq]TR\[rq])
429 to a PostScript name
430 (such as \[lq]Times\-Roman\[rq]).
431 .
432 Lines starting with
433 .B #
434 and blank lines are ignored.
435 .
436 The code for each character given in the font file must correspond
437 to the code in the default encoding for the font.
438 .
439 This code can be used with the
440 .B \[rs]N
441 escape sequence in
442 .I \%troff
443 to select the character
444 even if it lacks a special character name.
445 .
446 Every character in the font description must exist in the font file,
447 and the widths given in the description must match those used in the
448 font file.
449 .
450 See
451 .MR groff_font 5 .
452 .\" .
453 .\" .
454 .\" .LP
455 .\" Note that
456 .\" .B grops
457 .\" is able to display all glyphs in a PostScript font, not only 256.
458 .\" .I enc_file
459 .\" (or the default encoding if no encoding file specified) just defines
460 .\" the order of glyphs for the first 256 characters;
461 .\" all other glyphs are accessed with additional encoding vectors which
462 .\" .B grops
463 .\" produces on the fly.
464 .
465 .
466 .P
467 .I gropdf
468 can automatically
469 .I embed
470 any downloadable fonts necessary to print the document.
471 .
472 Any fonts thus required must be listed in the file
473 .IR /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\:\%download ,
474 which should comprise lines of the form
475 .
476 .RS
477 .I "foundry font file-name"
478 .RE
479 .
480 where
481 .I foundry
482 is the foundry name, or blank for the default foundry;
483 .I font
484 is the PostScript name of the font,
485 and
486 .I file-name
487 is the name of the PFA or PFB font file,
488 and can be a pathname
489 (can contain slashes).
490 .
491 Any lines beginning with
492 .B #
493 and blank lines are ignored;
494 fields must be separated by tabs
495 (spaces are
496 .B not
497 allowed);
498 if
499 .I file-name
500 is not a pathname,
501 it is sought using the same mechanism as that used for
502 font metric files.
503 .\" XXX: This may be underspecified; do we mean groff font description
504 .\" files, or AFM files? Also, gropdf does its own path searches rather
505 .\" than the stuff in libgroff so I'm not sure what "the same mechanism"
506 .\" means. --GBR
507 .
508 The
509 .I download
510 file itself is also sought using this mechanism.
511 .
512 Foundry names are usually a single character
513 (such as \[oq]U\[cq] for the URW foundry)
514 or empty for the default foundry.
515 .
516 This default uses the same fonts as
517 .I Ghostscript
518 uses when it embeds fonts in a PDF file.
519 .
520 .
521 .P
522 The default stroke and fill colors are black.
523 .
524 .
525 .\" ====================================================================
526 . SS Typefaces
527 .\" ====================================================================
528 .
529 Styles called
530 .BR R ,
531 .BR I ,
532 .BR B ,
533 and
534 .B BI
535 mounted at font positions 1 to\~4.
536 .
537 Text fonts are grouped into families
538 .BR A ,
539 .BR BM ,
540 .BR C ,
541 .BR H ,
542 .BR HN ,
543 .BR N ,
544 .BR P ,
545 .RB and\~ T ,
546 each having members in each of these styles.
547 .
548 .
549 .RS
550 .TP 8n \" BMBI + 2n + hand-tuned for PDF
551 .B AR
552 .FT AR
553 AvantGarde-Book
554 .FT
555 .
556 .TQ
557 .B AI
558 .FT AI
559 AvantGarde-BookOblique
560 .FT
561 .
562 .TQ
563 .B AB
564 .FT AB
565 AvantGarde-Demi
566 .FT
567 .
568 .TQ
569 .B ABI
570 .FT ABI
571 AvantGarde-DemiOblique
572 .FT
573 .
574 .TQ
575 .B BMR
576 .FT BMR
577 Bookman-Light
578 .FT
579 .
580 .TQ
581 .B BMI
582 .FT BMI
583 Bookman-LightItalic
584 .FT
585 .
586 .TQ
587 .B BMB
588 .FT BMB
589 Bookman-Demi
590 .FT
591 .
592 .TQ
593 .B BMBI
594 .FT BMBI
595 Bookman-DemiItalic
596 .FT
597 .
598 .TQ
599 .B CR
600 .FT CR
601 Courier
602 .FT
603 .
604 .TQ
605 .B CI
606 .FT CI
607 Courier-Oblique
608 .FT
609 .
610 .TQ
611 .B CB
612 .FT CB
613 Courier-Bold
614 .FT
615 .
616 .TQ
617 .B CBI
618 .FT CBI
619 Courier-BoldOblique
620 .FT
621 .
622 .TQ
623 .B HR
624 .FT HR
625 Helvetica
626 .FT
627 .
628 .TQ
629 .B HI
630 .FT HI
631 Helvetica-Oblique
632 .FT
633 .
634 .TQ
635 .B HB
636 .FT HB
637 Helvetica-Bold
638 .FT
639 .
640 .TQ
641 .B HBI
642 .FT HBI
643 Helvetica-BoldOblique
644 .FT
645 .
646 .TQ
647 .B HNR
648 .FT HNR
649 Helvetica-Narrow
650 .FT
651 .
652 .TQ
653 .B HNI
654 .FT HNI
655 Helvetica-Narrow-Oblique
656 .FT
657 .
658 .TQ
659 .B HNB
660 .FT HNB
661 Helvetica-Narrow-Bold
662 .FT
663 .
664 .TQ
665 .B HNBI
666 .FT HNBI
667 Helvetica-Narrow-BoldOblique
668 .FT
669 .
670 .TQ
671 .B NR
672 .FT NR
673 NewCenturySchlbk-Roman
674 .FT
675 .
676 .TQ
677 .B NI
678 .FT NI
679 NewCenturySchlbk-Italic
680 .FT
681 .
682 .TQ
683 .B NB
684 .FT NB
685 NewCenturySchlbk-Bold
686 .FT
687 .
688 .TQ
689 .B NBI
690 .FT NBI
691 NewCenturySchlbk-BoldItalic
692 .FT
693 .
694 .TQ
695 .B PR
696 .FT PR
697 Palatino-Roman
698 .FT
699 .
700 .TQ
701 .B PI
702 .FT PI
703 Palatino-Italic
704 .FT
705 .
706 .TQ
707 .B PB
708 .FT PB
709 Palatino-Bold
710 .FT
711 .
712 .TQ
713 .B PBI
714 .FT PBI
715 Palatino-BoldItalic
716 .FT
717 .
718 .TQ
719 .B TR
720 .FT TR
721 Times-Roman
722 .FT
723 .
724 .TQ
725 .B TI
726 .FT TI
727 Times-Italic
728 .FT
729 .
730 .TQ
731 .B TB
732 .FT TB
733 Times-Bold
734 .FT
735 .
736 .TQ
737 .B TBI
738 .FT TBI
739 Times-BoldItalic
740 .FT
741 .RE
742 .
743 .
744 .br
745 .ne 3v
746 .P
747 Another text font is not a member of a family.
748 .
749 .RS
750 .TP 8n \" BMBI (above) + 2n + hand-tuned for PDF
751 .B ZCMI
752 .FT ZCMI
753 ZapfChancery-MediumItalic
754 .FT
755 .RE
756 .
757 .
758 .P
759 Special fonts include
760 .BR S ,
761 the PostScript Symbol font;
762 .BR SS ,
763 a subset of
764 .B S
765 with slanted lowercase Greek letters;
766 .BR EURO ,
767 which offers a Euro glyph
768 in several styles
769 for use with old devices lacking it;
770 and
771 .BR ZD ,
772 Zapf Dingbats.
773 .
774 In contrast to
775 .IR grops ,
776 .I gropdf
777 does not require a reversed variant of it
778 .RB ( ZDR );
779 the \[lq]hand pointing left\[rq] glyph
780 .RB ( \[rs][lh] )
781 is available nevertheless,
782 since
783 .I \%pdf.tmac
784 defines it using the
785 .B \[rs]X\[aq]pdf: xrev\[aq]
786 device extension command
787 (see below).
788 .
789 Some glyphs in these fonts are unnamed and must be accessed
790 as indexed characters,
791 using the
792 .B \[rs]N
793 escape sequence.
794 .
795 .P
796 The fonts corresponding to
797 .B EURO
798 and
799 .B SS
800 are unknown to the PDF standard;
801 .I groff
802 therefore provides their AFM files
803 (font metrics)
804 and PFA or PFB files
805 so that they can be used with other software
806 and embedded in PDF output.
807 .
808 .
809 .\" ====================================================================
810 . SS "Feature service levels and URW font support"
811 .\" ====================================================================
812 .
813 The traditional PostScript Type\~1 fonts
814 are limited in their glyph repertoire,
815 and the original versions from the Adobe foundry
816 are not free software.
817 .
818 Historically,
819 because their presence was mandated by the PostScript standard,
820 one could expect to find support for them in any conforming device
821 or software PostScript renderer.
822 .
823 PostScript
824 (\[lq]Level 1\[rq])
825 initially standardized 14 typefaces:
826 Times,
827 Helvetica,
828 and
829 Courier
830 each in four styles
831 (which
832 .I groff
833 groups into \[lq]families\[rq]);
834 a symbol font;
835 and a dingbats font.
836 .
837 PostScript Level 2 increased the number to 35,
838 adding the families
839 Avant Garde,
840 Bookman,
841 Helvetica Narrow,
842 New Century Schoolbook,
843 and
844 Palatino;
845 and a text font in one style,
846 Zapf Chancery medium italic.
847 .
848 A document could be small
849 because it did not need to embed font resources
850 unless it had unusual
851 (for the time)
852 glyph or typeface requirements.
853 .
854 This situation carried over into the early years
855 of PostScript's successor page description language,
856 PDF.
857 .
858 Nowadays,
859 it is common
860 to embed fonts in PDFs,
861 and authorities widely recommend this practice,
862 which increases the reliability of document rendering,
863 and many free software fonts are available
864 with much greater glyph coverage
865 than Adobe's Type\~1 fonts for PostScript.
866 .
867 .
868 .P
869 .I \%gropdf
870 attempts to work in variety of scenarios,
871 and delivers better results
872 when configured with supporting digital font files
873 (for embedding)
874 and font metrics files describing those fonts to the formatter.
875 .
876 .
877 .IP \[bu] 3n
878 .I "Full service"
879 is available
880 when
881 .I \%gropdf
882 can locate all 35 fonts of the PostScript Level 2 standard
883 on the file system
884 along with their corresponding font metrics (AFM) files.
885 .
886 The Adobe-compatible unnamed (default) foundry
887 supports up to 256 glyphs in each typeface.
888 .
889 Fonts from the URW foundry
890 (\[lq]U\[rq])
891 are compatible extensions of the Adobe fonts
892 with extended glyph coverage,
893 including support for Cyrillic script.
894 .
895 .IR groff 's
896 build process uses
897 .MR afmtodit 1
898 to generate font description files
899 from the URW foundry's AFM files;
900 see section \[lq]Files\[rq] below.
901 .
902 .
903 .IP \[bu]
904 .I "Intermediate service"
905 is available
906 when
907 .I \%gropdf
908 can locate all 35 fonts of the PostScript Level 2 standard
909 but not their corresponding font metrics (AFM) files.
910 .
911 .IR groff 's
912 build process copies the font description files
913 from those for the
914 .MR grops 1
915 driver,
916 reusing them for
917 .IR \%gropdf ;
918 this reduces glyph coverage to 256 glyphs maximum from each face,
919 and the \[lq]U\[rq] foundry is unavailable.
920 .
921 .
922 .IP \[bu]
923 .I "Basic service"
924 results when
925 .I \%gropdf
926 cannot locate all 35 fonts of the PostScript Level 2 standard.
927 .
928 Only the base 14 fonts of the PDF standard are available,
929 and only in the sense that the formatter can use their metrics
930 (copied from
931 .MR grops
932 font descriptions
933 as described above).
934 .
935 Use of the
936 .B \-e
937 option
938 to embed fonts in the generated PDF results in an error.
939 .
940 .
941 .\" ====================================================================
942 . SS "Device extension commands"
943 .\" ====================================================================
944 .
945 .I gropdf
946 supports many device extensions,
947 accessed with the
948 .I groff
949 request
950 .B \%device
951 or
952 .I roff
953 .B \[rs]X
954 escape sequence.
955 .
956 First,
957 it
958 understands many of the device extensions supported by
959 .MR grops 1 .
960 .
961 .
962 .TP
963 .B \[rs]X\[aq]ps: invis\[aq]
964 Suppress output.
965 .
966 .
967 .TP
968 .B \[rs]X\[aq]ps: endinvis\[aq]
969 Stop suppressing output.
970 .
971 .
972 .TP
973 .BI "\[rs]X\[aq]ps: exec gsave currentpoint 2 copy translate\~" n\~\c
974 .B rotate neg exch neg exch translate\[aq]
975 where
976 .I n
977 is the angle of rotation.
978 .
979 This is to support the
980 .B align
981 command in
982 .MR \%pic 1 .
983 .
984 .
985 .TP
986 .B \[rs]X\[aq]ps: exec grestore\[aq]
987 Used by
988 .MR \%pic 1
989 to restore state after rotation.
990 .
991 .
992 .TP
993 .BI "\[rs]X\[aq]ps: exec " "n\~" "setlinejoin\[aq]"
994 where
995 .I n
996 can be one of the following values.
997 .
998 .
999 .IP
1000 0 = Miter join
1001 .br
1002 1 = Round join
1003 .br
1004 2 = Bevel join
1005 .
1006 .
1007 .TP
1008 .BI "\[rs]X\[aq]ps: exec " "n " "setlinecap\[aq]"
1009 where
1010 .I n
1011 can be one of the following values.
1012 .
1013 .
1014 .IP
1015 0 = Butt cap
1016 .br
1017 1 = Round cap, and
1018 .br
1019 2 = Projecting square cap
1020 .
1021 .
1022 .br
1023 .ne 3v
1024 .P
1025 .I gropdf
1026 also supports a subset of the commands introduced in
1027 .IR gpresent 's
1028 .IR present.tmac .
1029 .
1030 .
1031 .RS
1032 .TP
1033 .B PAUSE
1034 .TQ
1035 .B BLOCKS
1036 .TQ
1037 .B BLOCKE
1038 .RE
1039 .
1040 .
1041 .P
1042 These allow you to create presentation PDFs.
1043 .
1044 Many of the other
1045 commands are already available in other macro packages.
1046 .
1047 .
1048 .LP
1049 These commands are implemented with
1050 .I groff
1051 X commands:-
1052 .
1053 .
1054 .LP
1055 .TP
1056 .B \[rs]X\[aq]ps: exec %%%%PAUSE\[aq]
1057 The section before this is treated as a block and is introduced using
1058 the current
1059 .B BLOCK
1060 transition setting
1061 (see
1062 .RB \[lq] "\[rs]X\[aq]pdf: transition\[aq]" \[rq]
1063 below).
1064 .
1065 Equivalently,
1066 .B \%.pdfpause
1067 is available as a macro.
1068 .TP
1069 .B \[rs]X\[aq]ps: exec %%%%BEGINONCE\[aq]
1070 Any text following this command (up to %%%%ENDONCE) is shown only once,
1071 the next %%%%PAUSE will remove it.
1072 If producing a non-presentation PDF, i.e.\&
1073 ignoring the pauses, see
1074 .I \%GROPDF_NOSLIDE
1075 below, this text is ignored.
1076 .LP
1077 .TP
1078 .B \[rs]X\[aq]ps: exec %%%%ENDONCE\[aq]
1079 This terminates the block defined by %%%%BEGINONCE.
1080 This pair of commands
1081 is what implements the \&.BLOCKS Once/.BLOCKE commands in
1082 .IR present.tmac .
1083 .
1084 .
1085 .LP
1086 The
1087 .I mom
1088 macro package already integrates these extensions,
1089 so you can build slides with
1090 .IR mom .
1091 .
1092 .
1093 .LP
1094 If you use
1095 .I present.tmac
1096 with
1097 .I gropdf
1098 there is no need to run the program
1099 .MR presentps 1
1100 since the output will already be a presentation PDF.
1101 .
1102 .
1103 .LP
1104 All other
1105 .B ps:
1106 tags are silently ignored.
1107 .
1108 .
1109 .LP
1110 .I gropdf
1111 also recognizes a device extension used by the DVI driver.
1112 .
1113 .
1114 .TP
1115 .BI \[rs]X\[aq]papersize= width , length \[aq]
1116 Set the page dimensions in centimeters to
1117 .I width
1118 by
1119 .I length.
1120 .
1121 If the
1122 .B \-l
1123 option was specified,
1124 these dimensions are swapped.
1125 .
1126 Changes to the paper dimensions should occur prior to the first page,
1127 or during page ejection before starting a subsequent one.
1128 .
1129 .
1130 .IP
1131 .I Caution:
1132 the ordering of dimensions differs from that used by
1133 .I papersize.tmac
1134 and
1135 .MR \%troff 1 's
1136 .RB \[lq] "\-d \%paper" \[rq]
1137 option.
1138 .
1139 .
1140 .TP
1141 .BI "\[rs]X\[aq]pdf: markstart " /ANN-definition \[aq]
1142 .TQ
1143 .B \[rs]X\[aq]pdf: markend\[aq]
1144 Macros that support PDF features use these extension commands internally
1145 to bracket
1146 .I hotspot
1147 text
1148 (a hyperlink).
1149 .
1150 User documents should call the
1151 .B \%.pdfhref
1152 macro instead.
1153 .
1154 Their application is found in other macro packages
1155 (like
1156 .MR groff_man 7
1157 or
1158 .MR groff_mdoc 7 )
1159 that call
1160 .B \%.pdfhref
1161 with a
1162 .B \-S
1163 argument,
1164 then indicate the end of hotspot text with
1165 .BR "\[rs]X\[aq]pdf: markend\[aq]\[rs]m[\[rs]*[pdf:curcol]]" .
1166 .
1167 .
1168 .TP
1169 .B \[rs]X\[aq]pdf: xrev\[aq]
1170 Toggle the reversal of glyph direction.
1171 .
1172 This feature works by reversing all following text.
1173 Each separate letter is also mirrored.
1174 .
1175 One application is the reversal of glyphs in the Zapf Dingbats font.
1176 .
1177 To restore the normal glyph orientation,
1178 repeat the command.
1179 .
1180 .
1181 .LP
1182 .I gropdf
1183 supports several more device extensions using the
1184 .B pdf:
1185 tag.
1186 .
1187 The following have counterpart
1188 .I "convenience macros"
1189 that take the same arguments and behave equivalently.
1190 .
1191 .
1192 .TP
1193 .BI ".pdfbackground " "cmd left top right bottom weight"
1194 .TQ
1195 .B ".pdfbackground off"
1196 .TQ
1197 .BI ".pdfbackground footnote " bottom
1198 .TQ
1199 .BI "\eX\[aq]pdf: background " "cmd left top right bottom weight" \[aq]
1200 .TQ
1201 .B "\eX\[aq]pdf: background off\[aq]"
1202 .TQ
1203 .BI "\eX\[aq]pdf: background footnote " bottom \[aq]
1204 Produce a background rectangle on the page.
1205 .
1206 .
1207 .RS
1208 .TP 8n \" "bottom" + 2n
1209 .I cmd
1210 is the command,
1211 which can be any of
1212 .RB \[lq] page | fill | box \[rq]
1213 in combination.
1214 .
1215 Thus,
1216 .RB \[lq] pagefill \[rq]
1217 would draw a rectangle which covers the whole current page size
1218 (in which case the rest of the parameters can be omitted because the box
1219 dimensions are taken from the current media size).
1220 .
1221 .RB \[lq] boxfill \[rq],
1222 on the other hand,
1223 requires the given dimensions to place the box.
1224 .
1225 Including
1226 .RB \[lq] fill \[rq]
1227 in the command paints the rectangle with the current fill colour
1228 (as with
1229 .BR \[rs]M[] )
1230 and including
1231 .RB \[lq] box \[rq]
1232 gives the rectangle a border in the current stroke colour
1233 (as with
1234 .BR \[rs]m[] ).
1235 .
1236 .
1237 .IP
1238 .I cmd
1239 may also be
1240 .RB \[lq] off \[rq]
1241 on its own,
1242 which terminates drawing the current box.
1243 .
1244 If you have specified a page colour with
1245 .RB \[lq] pagefill \[rq],
1246 it is always the first box in the stack,
1247 and if you specify it again,
1248 it replaces the first entry.
1249 .
1250 Be aware that the
1251 .RB \[lq] pagefill \[rq]
1252 box renders the page opaque,
1253 so tools that \[lq]watermark\[rq] PDF pages are unlikely to be
1254 successful.
1255 .
1256 To return the background to transparent,
1257 issue an
1258 .RB \[lq] off \[rq]
1259 command with no other boxes open.
1260 .
1261 .
1262 .IP
1263 Finally,
1264 .I cmd
1265 may be
1266 .RB \[lq] footnote \[rq]
1267 followed by a new value for
1268 .IR bottom ,
1269 which is used for all open boxes on the current page.
1270 This is to allow room for footnote areas that grow while a page is
1271 processed
1272 (to accommodate multiple footnotes,
1273 for instance).
1274 .
1275 (If the value is negative,
1276 it is used as an offset from the bottom of the page.)
1277 .
1278 .
1279 .TP
1280 .I left
1281 .TQ
1282 .I top
1283 .TQ
1284 .I right
1285 .TQ
1286 .I bottom
1287 are the coordinates of the box.
1288 .
1289 The
1290 .I top
1291 and
1292 .I bottom
1293 coordinates are the minimum and maximum for the box,
1294 since the actual start of the box is
1295 .IR groff 's
1296 drawing position when you issue the command,
1297 and the bottom of the box is the point where you turn the box
1298 .RB \[lq] off \[rq].
1299 .
1300 The top and bottom coordinates are used only if the box drawing extends
1301 onto the next page;
1302 ordinarily,
1303 they would be set to the header and footer margins.
1304 .
1305 .
1306 .TP
1307 .I weight
1308 provides the line width for the border if
1309 .RB \[lq] box \[rq]
1310 is included in the command.
1311 .
1312 .
1313 .P
1314 An
1315 .I sboxes
1316 macro file is also available;
1317 see
1318 .MR groff_tmac 5 .
1319 .RE
1320 .
1321 .
1322 .br
1323 .ne 6v
1324 .TP
1325 .B .pdfmarksuspend
1326 .TQ
1327 .B .pdfmarkrestart
1328 .TQ
1329 .B \[rs]X\[aq]pdf: marksuspend\[aq]
1330 .TQ
1331 .B \[rs]X\[aq]pdf: markrestart\[aq]
1332 If you use a page location trap to produce a header or footer,
1333 or otherwise interrupt a document's text,
1334 you need to use these commands if a PDF
1335 .I hotspot
1336 crosses a trap boundary;
1337 otherwise any text output by the trap will be marked as part
1338 of the hotspot.
1339 .
1340 To prevent this error,
1341 place these device extension escape sequences or their corresponding
1342 convenience macros
1343 .B \%.pdfmarksuspend
1344 and
1345 .B \%.pdfmarkrestart
1346 at the start and end of the trap macro,
1347 respectively.
1348 .
1349 .
1350 .TP
1351 .BI ".pdfpagename " name
1352 .TQ
1353 .BI "\[rs]X\[aq]pdf: pagename " name \[aq]
1354 Assign the current page a
1355 .IR name .
1356 .
1357 All documents bear two default names,
1358 .RB \[oq] top "\[cq] and \[oq]" bottom \[cq].
1359 .
1360 .
1361 .TP
1362 .BI ".pdfpagenumbering " "type prefix start"
1363 .TQ
1364 .BI "\[rs]X\[aq]pdf: pagenumbering " "type prefix start" \[aq]
1365 .RS
1366 Control the page numbering shown in a PDF reader's outline
1367 (which also contains bookmarks).
1368 .
1369 Normally,
1370 the page number associated with each bookmark is its sequence number in
1371 the file,
1372 but this might not match the desired numbering scheme.
1373 .
1374 A document may bear a cover sheet
1375 (which has no page number);
1376 front matter
1377 (possibly including a table of contents)
1378 that uses lowercase roman numerals;
1379 the main matter,
1380 which uses arabic numerals;
1381 and back matter,
1382 which may include appendices that are each prefixed with a letter and
1383 independently numbered.
1384 .
1385 Place this command prior to breaking the page to which the new numbering
1386 scheme is to apply.
1387 .
1388 It then persists until changed again.
1389 .
1390 .
1391 .P
1392 .TP 8n \" "prefix" + 2n
1393 .I type
1394 specifies the numbering system to use. It
1395 should be one of
1396 .RB \[lq] Decimal \[rq],
1397 .RB \[lq] Roman \[rq],
1398 .RB \[lq] roman \[rq],
1399 .RB \[lq] Alpha \[rq],
1400 or
1401 .RB \[lq] alpha \[rq].
1402 .
1403 This parameter may be abbreviated to the first letter,
1404 whose lettercase determines that used for the numbers where applicable.
1405 .
1406 The ordering used by the alphabetic numbering systems is
1407 A-Z \&.\|.\|.\& AA-AZ \&.\|.\|.\& ZA-ZZ.
1408 .
1409 .I type
1410 can also be
1411 .RB \[lq] .\& \[rq],
1412 which selects no numbering system;
1413 you may still provide a
1414 .I prefix.
1415 .
1416 .
1417 .TP
1418 .I prefix
1419 specifies text to precede the page number.
1420 .
1421 For example,
1422 to number the pages of an appendix
1423 \[lq]A-1\[rq],
1424 \[lq]A-2\[rq],
1425 and so forth,
1426 use a
1427 .I prefix
1428 of
1429 .RB \[lq] A- \[rq]
1430 and a
1431 .I type
1432 of
1433 .RB \[lq] Decimal \[rq].
1434 .
1435 .
1436 .TP
1437 .I start
1438 determines the page number.
1439 .
1440 It defaults to 1.
1441 .RE
1442 .
1443 .
1444 .TP
1445 .BI ".pdfpic " "file alignment width height line-length"
1446 .TQ
1447 .\" XXX: For consistency, this device extension command should be "pic".
1448 .\" --GBR
1449 .BI "\[rs]X\[aq]pdf: pdfpic " file\~\c
1450 .IB "alignment width height line-length" \[aq]
1451 Place an image from file
1452 .I file
1453 of desired
1454 .I width
1455 and
1456 .I height
1457 (if
1458 .I height
1459 is missing or zero then it is scaled proportionally).
1460 .
1461 If
1462 .I alignment
1463 is
1464 .B \-L
1465 the drawing is left-aligned.
1466 .
1467 If it is
1468 .B \-C
1469 or
1470 .B \-R
1471 a
1472 .I line-length
1473 greater than the width of the drawing is required as well.
1474 .
1475 If
1476 .I width
1477 is specified as zero then the width is scaled in proportion to the
1478 height.
1479 .
1480 If both
1481 .I width
1482 and
1483 .I height
1484 are non-zero the image is scaled to \[oq]best fit\[cq].
1485 .
1486 .
1487 .IP
1488 The availability of other software on the system,
1489 such as
1490 .IR PerlMagick ,
1491 influences the types of image files
1492 .I gropdf
1493 can embed in its output.
1494 .
1495 .
1496 .IP
1497 .TS
1498 allbox center;
1499 Cb Ci Ci Ci Ci
1500 Li C C C C.
1501 \& \fRnone file\fR(1) identify\fR(1) Image::Magick\fR(3pm)
1502 \&.pdf \[OK] \[OK] \[OK] \[OK]
1503 \&.jpg \[u2717] \[OK] \[OK] \[OK]
1504 \&.jp2 \[u2717] \[u2717] \[OK] \[OK]
1505 \fRother \[u2717] \[u2717] \[u2717] \[OK]
1506 .TE
1507 .
1508 .
1509 .IP
1510 See
1511 .MR groff_tmac 5
1512 for a description of the
1513 .B \%PDFPIC
1514 macro,
1515 which provides a convenient high-level interface for inclusion of
1516 various graphic file formats.
1517 .
1518 .
1519 .TP
1520 .BI ".pdfswitchtopage " "when name"
1521 .TQ
1522 .BI "\[rs]X\[aq]pdf: switchtopage " "when name" \[aq]
1523 Normally each new page is appended to the end of the document,
1524 this command allows following pages to be inserted at a
1525 .I \[oq]named\[cq]
1526 position within the document (see pagename command above).
1527 .I \[oq]when\[cq]
1528 can be either
1529 .RI \[oq] after "\[cq] or \[oq]" before \[cq].
1530 If it is omitted it defaults to
1531 .RI \[oq] before \[cq].
1532 .
1533 It should be used at the end of the page before you want the switch to
1534 happen.
1535 .
1536 This allows pages such as a TOC to be moved to elsewhere in the
1537 document,
1538 but more esoteric uses are possible.
1539 .
1540 .
1541 .br
1542 .ne 5v
1543 .TP
1544 .BI ".pdftransition " "scope mode duration dimension motion direction\
1545 scale bool"
1546 .TQ
1547 .BI "\[rs]X\[aq]pdf: transition " scope\~\c
1548 .IB "mode duration dimension motion direction scale bool" \[aq]
1549 Configure the style of page transitions,
1550 as used in \[lq]slides\[rq]
1551 (or \[lq]foils\[rq]).
1552 .
1553 .I scope
1554 can be either
1555 .B SLIDE
1556 or
1557 .BR BLOCK .
1558 .
1559 .B SLIDE
1560 applies the transition when a new slide is introduced to the screen;
1561 .B BLOCK
1562 applies it to the individual blocks making up the slide.
1563 .
1564 .
1565 .IP
1566 .I mode
1567 is the transition type between slides:-
1568 .RS
1569 .IP
1570 .B Split
1571 - Two lines sweep across the screen, revealing the new page.
1572 The lines
1573 may be either horizontal or vertical and may move inward from the
1574 edges of the page or outward from the center, as specified by the
1575 .I dimension
1576 and
1577 .I motion
1578 entries, respectively.
1579 .br
1580 .B Blinds
1581 - Multiple lines, evenly spaced across the screen, synchronously
1582 sweep in the same direction to reveal the new page.
1583 The lines may be
1584 either horizontal or vertical, as specified by the
1585 .I dimension
1586 entry.
1587 Horizontal
1588 lines move downward; vertical lines move to the right.
1589 .br
1590 .B Box
1591 - A rectangular box sweeps inward from the edges of the page or
1592 outward from the center, as specified by the
1593 .I motion
1594 entry, revealing the new page.
1595 .br
1596 .B Wipe
1597 - A single line sweeps across the screen from one edge to the other in
1598 the direction specified by the
1599 .I direction
1600 entry, revealing the new page.
1601 .br
1602 .B Dissolve
1603 - The old page dissolves gradually to reveal the new one.
1604 .br
1605 .B Glitter
1606 - As Dissolve,
1607 except that the effect sweeps across the page in a wide band moving from
1608 one side of the screen to the other in the direction specified by the
1609 .I direction
1610 entry.
1611 .br
1612 .B R
1613 - The new page simply replaces the old one with no special transition
1614 effect; the
1615 .I direction
1616 entry shall be ignored.
1617 .br
1618 .B Fly
1619 - (PDF 1.5) Changes are flown out or in (as specified by
1620 .IR motion ),
1621 in the
1622 direction specified by
1623 .IR direction ,
1624 to or from a location that is offscreen except
1625 when
1626 .I direction
1627 is
1628 .BR None .
1629 .br
1630 .B Push
1631 - (PDF 1.5) The old page slides off the screen while the new page
1632 slides in, pushing the old page out in the direction specified by
1633 .IR direction .
1634 .br
1635 .B Cover
1636 - (PDF 1.5) The new page slides on to the screen in the direction
1637 specified by
1638 .IR direction ,
1639 covering the old page.
1640 .br
1641 .B Uncover
1642 - (PDF 1.5) The old page slides off the screen in the direction
1643 specified by
1644 .IR direction ,
1645 uncovering the new page in the direction
1646 specified by
1647 .IR direction .
1648 .br
1649 .B Fade
1650 - (PDF 1.5) The new page gradually becomes visible through the
1651 old one.
1652 .RE
1653 .IP
1654 .I duration
1655 is the length of the transition in seconds (default 1).
1656 .IP
1657 .I dimension
1658 (Optional;
1659 .BR Split " and " Blinds
1660 transition styles only) The dimension in which the
1661 specified transition effect shall occur:
1662 .B H
1663 Horizontal, or
1664 .B V
1665 Vertical.
1666 .IP
1667 .I motion
1668 (Optional;
1669 .BR Split ,
1670 .BR Box " and " Fly
1671 transition styles only) The direction of motion for
1672 the specified transition effect:
1673 .B I
1674 Inward from the edges of the page, or
1675 .B O
1676 Outward from the center of the page.
1677 .IP
1678 .I direction
1679 (Optional;
1680 .BR Wipe ,
1681 .BR Glitter ,
1682 .BR Fly ,
1683 .BR Cover ,
1684 .BR Uncover " and " Push
1685 transition styles only)
1686 The direction in which the specified transition effect shall moves,
1687 expressed in degrees counterclockwise starting from a left-to-right
1688 direction.
1689 If the value is a number, it shall be one of:
1690 .B 0
1691 = Left to right,
1692 .B 90
1693 = Bottom to top (Wipe only),
1694 .B 180
1695 = Right to left (Wipe only),
1696 .B 270
1697 = Top to bottom,
1698 .B 315
1699 = Top-left to bottom-right (Glitter only)
1700 The value can be
1701 .BR None ,
1702 which is relevant only for the
1703 .B Fly
1704 transition when the value of
1705 .I scale
1706 is not 1.0.
1707 .IP
1708 .I scale
1709 (Optional; PDF 1.5;
1710 .B Fly
1711 transition style only) The starting or ending scale at
1712 which the changes shall be drawn.
1713 If
1714 .I motion
1715 specifies an inward transition, the scale
1716 of the changes drawn shall progress from
1717 .I scale
1718 to 1.0 over the course of the
1719 transition.
1720 If
1721 .I motion
1722 specifies an outward transition, the scale of the changes drawn
1723 shall progress from 1.0 to
1724 .I scale
1725 over the course of the transition
1726 .IP
1727 .I bool
1728 (Optional; PDF 1.5;
1729 .B Fly
1730 transition style only) If
1731 .BR true ,
1732 the area that shall be flown
1733 in is rectangular and opaque.
1734 .IP
1735 Any of the parameters may be
1736 replaced with a "." which signifies the parameter retains its
1737 previous value, also any trailing missing parameters are ignored.
1738 .IP
1739 .B Note:
1740 not all PDF Readers support any or all these transitions.
1741 .
1742 .
1743 .\" ====================================================================
1744 .SS Macros
1745 .\" ====================================================================
1746 .
1747 .IR gropdf 's
1748 support macros in
1749 .I pdf\.tmac
1750 define the convenience macros described above.
1751 .
1752 Some features have no direct device extension escape sequence
1753 counterpart.
1754 .
1755 .
1756 .TP
1757 .BR ".pdfbookmark " [ \-T\~\c
1758 .IR tag-name ]\~ "level text"
1759 Mark the nearest page location as a bookmark,
1760 and optionally a named destination as well.
1761 .
1762 .I Bookmarks
1763 populate the outline pane of the reader.
1764 .
1765 They are organized into a hierarchical tree;
1766 each level of the tree is numbered,
1767 starting at 1,
1768 and named as
1769 .I text
1770 in the outline.
1771 .
1772 .I "Named destinations"
1773 permit hyperlink-style navigation within the document.
1774 .
1775 Specifying
1776 .B \-T
1777 followed by
1778 .I tag-name
1779 creates a named destination
1780 making the page location eligible as a target named by
1781 .RB \[lq] ".pdfhref L" \~.\|.\|.\&\[rq].
1782 .
1783 .
1784 .TP
1785 .BR ".pdfhref L" \~\c
1786 .BI \-D\~ dest\~\c
1787 .RB [ \-S ] \~\c
1788 .RB [ \-P \~\c
1789 .IR prefix-text "] \c"
1790 .RB [ \-A \~\c
1791 .IR suffix-text "] \c"
1792 .RI [ link-text ]
1793 Create a hotspot link to
1794 .I dest,
1795 (the
1796 .IR tag-name )
1797 which a
1798 .RB \[lq] .pdfbookmark \~.\|.\|.\&\[rq]
1799 or
1800 .RB \[lq] ".pdfhref M" \~.\|.\|.\&\[rq]
1801 call elsewhere in the document should define.
1802 .
1803 (If the document employs forward references,
1804 it must be processed twice;
1805 see
1806 .MR pdfmom 1 .)
1807 .
1808 If
1809 .I link-text
1810 is omitted the text associated with
1811 .IR dest ,
1812 when it was created, is formatted as the link text.
1813 .
1814 The
1815 .B \-P
1816 and
1817 .B \-A
1818 arguments format their successors as text
1819 before and after the link text,
1820 respectively,
1821 without intervening space.
1822 .
1823 Specifying
1824 .B \-S
1825 prevents
1826 .B pdfhref
1827 from \[lq]closing\[rq] the hotspot,
1828 requiring the document
1829 (or macro package wrapping
1830 .BR pdfhref )
1831 to do so itself with
1832 .RB \[lq] "\[rs]X\[aq]pdf: markend\[aq]\[rs]m[\[rs]*[pdf:curcol]]" \[rq].
1833 .
1834 .
1835 .TP
1836 .BR ".pdfhref M" \~\c
1837 .RB [ \-E ]\~\c
1838 .RB [ \-N \~\c
1839 .IR tag-name ]\~\c
1840 .I dest
1841 Mark the nearest page location as a destination named
1842 (the first word of)
1843 .I dest,
1844 which should be unique within a document.
1845 .
1846 Specifying
1847 .B \-T
1848 followed by
1849 .I tag-name
1850 overrides this default.
1851 .
1852 Specifying
1853 .B \-E
1854 formats
1855 .I dest
1856 as text in the document as well.
1857 .
1858 .
1859 .TP
1860 .BR ".pdfhref W" \~\c
1861 .BI \-D\~ uri\~\c
1862 .RB [ \-S ] \~\c
1863 .RB [ \-P \~\c
1864 .IR prefix-text "] \c"
1865 .RB [ \-A \~\c
1866 .IR suffix-text "] \c"
1867 .I link-text
1868 .\" The link-text argument is not, presently, optional. See Savannah
1869 .\" #67916.
1870 .\" RI [ link-text ]
1871 Create a hotspot link to
1872 .I uri,
1873 a World Wide Web
1874 Universal Resource Identifier (URI).
1875 .
1876 .\" XXX: Nope--pdf.tmac formats "Unknown" as the link text instead. See
1877 .\" Savannah #67916.
1878 .\" If
1879 .\" .I link-text
1880 .\" is omitted,
1881 .\" .I uri
1882 .\" is formatted as the link text.
1883 .
1884 The
1885 .B \-P
1886 and
1887 .B \-A
1888 arguments format their successors as text
1889 before and after the link text,
1890 respectively,
1891 without intervening space.
1892 .
1893 Specifying
1894 .B \-S
1895 prevents
1896 .B pdfhref
1897 from \[lq]closing\[rq] the hotspot,
1898 requiring the document
1899 (or macro package wrapping
1900 .BR pdfhref )
1901 to do so itself with
1902 .RB \[lq] "\[rs]X\[aq]pdf: markend\[aq]\[rs]m[\[rs]*[pdf:curcol]]" \[rq].
1903 .
1904 .
1905 .TP
1906 .\" XXX: We don't need to expose PDF's '/' syntax in a *roff macro
1907 .\" file. It should prefix "field" with '/' itself. -- GBR
1908 .BI ".pdfinfo /" "field content"\~\c
1909 \&.\|.\|.
1910 Define PDF metadata.
1911 .
1912 .I field
1913 may be one of
1914 .BR Title ,
1915 .BR Author ,
1916 .BR Subject ,
1917 .BR Keywords ,
1918 or another datum supported by the PDF standard or your reader.
1919 .
1920 .I field
1921 must be prefixed with a slash.
1922 .
1923 .
1924 .TP
1925 .BR ".pdfnote " [ \-T\~\c
1926 .IR title ]\~ text
1927 Create an annotation in the document.
1928 .
1929 Reader support for this feature varies.
1930 .
1931 Some place an icon at the current position on the page;
1932 hovering over the icon reveals any
1933 .IR title ,
1934 while clicking on the icon
1935 pops up a window containing
1936 .IR text .
1937 .
1938 .
1939 .br
1940 .ne 12v
1941 .\" ====================================================================
1942 .SS "Parameters"
1943 .\" ====================================================================
1944 .
1945 The following parameters,
1946 shown as
1947 .I roff
1948 control lines,
1949 affect the operation of
1950 .IR gropdf .
1951 .
1952 .
1953 .P
1954 .TS
1955 box;
1956 Cb Cb Cb
1957 Lf(CR)p-1 Lx L .
1958 Parameter Purpose Default
1959 _
1960 \&.nr PDFNOTE.WIDTH T{
1961 .na
1962 Set width of annotation icon.
1963 T} 1c
1964 \&.nr PDFNOTE.HEIGHT T{
1965 .na
1966 Set height of annotation icon.
1967 T} 1c
1968 \&.ds PDFNOTE.COLOR T{
1969 .na
1970 Set RGB color of annotation icon (RGB)
1971 T} 1.00 1.00 0.00
1972 \&.ds PDFNOTE.OPACITY T{
1973 .na
1974 Set opacity of annotation icon
1975 (decimal value in [0, 1]).
1976 T} 0.6
1977 .\" XXX: Why not use \n[.R] for the next item's default? --GBR
1978 \&.nr PDFOUTLINE.FOLDLEVEL T{
1979 .na
1980 Set depth of visible bookmark hierarchy.
1981 T} 10000
1982 \&.nr PDFHREF.VIEW.LEADING T{
1983 .na
1984 Set position adjustment when clicking bookmark or internal hotspot.
1985 T} 5p
1986 \&.nr PDFHREF.LEADING T{
1987 .na
1988 Configure size of increased clickable area around a hotspot.
1989 T} 2.0p
1990 .\" XXX: Why require the user to specify two leading space-separated
1991 .\" zeroes? What do they mean? Why are we exposing this via the macro
1992 .\" package's API? Why not have a register named PDFHREF.BORDERWIDTH
1993 .\" that accepts a width value, and default it to use points? --GBR
1994 .\"
1995 .\" I add that if we're going to start improving this API, we could get
1996 .\" a good start by disposing of all these screaming capitals. --GBR
1997 \&.ds PDFHREF.BORDER T{
1998 .na
1999 Configure the border width around a hotspot
2000 by specifying two zeroes followed
2001 by the desired width in points.
2002 .
2003 Do not use a scaling unit.
2004 T} 0 0 0
2005 \&.ds PDFHREF.COLOR T{
2006 .na
2007 Set RGB color of link text.
2008 T} 0.00 0.35 0.60
2009 .TE
2010 .
2011 .
2012 .P
2013 In the foregoing,
2014 you can also spell \[lq]COLOR\[rq] in string names as \[lq]COLOUR\[rq].
2015 .
2016 .
2017 .\" ====================================================================
2018 .SS "Importing PDF graphics"
2019 .\" ====================================================================
2020 .
2021 If you are importing an image as a PDF file, it must be a single page
2022 and the drawing must just fit inside the media size of the PDF file.
2023 .
2024 In
2025 .MR inkscape 1
2026 or
2027 .MR gimp 1 ,
2028 for example,
2029 make sure the canvas size just fits the image.
2030 .
2031 .
2032 .P
2033 The PDF parser
2034 .I gropdf
2035 implements has not been rigorously tested with all applications that
2036 produce PDF.
2037 .
2038 If you find a single-page PDF which fails to import properly,
2039 try processing it with the
2040 .MR pdftk 1
2041 program.
2042 .
2043 .
2044 .RS
2045 .EX
2046 pdftk\~\c
2047 .I existing-file\~\c
2048 output\~\c
2049 .I new-file
2050 .EE
2051 .RE
2052 .
2053 You may find that
2054 .I new-file
2055 imports successfully.
2056 .
2057 .
2058 .\" ====================================================================
2059 .SS "TrueType and other font formats"
2060 .\" ====================================================================
2061 .
2062 .I gropdf
2063 does not yet support any font formats besides Adobe Type 1
2064 (PFA or PFB).
2065 .
2066 .
2067 .\" ====================================================================
2068 .SH "Font installation"
2069 .\" ====================================================================
2070 .
2071 For your convenience,
2072 .I groff
2073 offers
2074 .IR install\-font.bash ,
2075 a shell script that interactively assists
2076 the configuration of fonts for use with the
2077 GNU
2078 .I troff \" GNU
2079 formatter
2080 and the
2081 .I gropdf
2082 output driver.
2083 .
2084 See section \[lq]Files\[rq] below.
2085 .
2086 .
2087 .P
2088 The following is a step-by-step font installation guide for
2089 .I gropdf.
2090 .
2091 .
2092 .IP \[bu] 3n
2093 Convert your font to something
2094 .I groff
2095 understands.
2096 .
2097 This is a PostScript Type\~1 font in PFA or PFB format,
2098 together with an AFM file.
2099 .
2100 A PFA file begins as follows.
2101 .
2102 .RS
2103 .RS \" two RS calls to get inboard of IP indentation
2104 .EX
2105 %!PS\-AdobeFont\-1.0:
2106 .EE
2107 .RE \" but only one to get back to it
2108 .
2109 A PFB file contains this string as well,
2110 preceded by some non-printing bytes.
2111 .
2112 In the following steps,
2113 we will consider the use of CTAN's
2114 .UR https://\:ctan.org/\:tex\-archive/\:fonts/\:brushscr
2115 BrushScriptX-Italic
2116 .UE
2117 font in PFA format.
2118 .RE \" now restore left margin
2119 .
2120 .
2121 .IP \[bu]
2122 Convert the AFM file to a
2123 .I groff
2124 font description file with the
2125 .MR afmtodit 1
2126 program.
2127 .
2128 For instance,
2129 .
2130 .RS
2131 .RS \" two RS calls to get inboard of IP indentation
2132 .EX
2133 $ \c
2134 .B afmtodit BrushScriptX\-Italic.afm text.map BSI
2135 .EE
2136 .RE \" but only one to get back to it
2137 .
2138 converts the Adobe Font Metric file
2139 .I BrushScriptX\-Italic.afm
2140 to the
2141 .I groff
2142 font description file
2143 .IR BSI .
2144 .RE \" now restore left margin
2145 .
2146 .
2147 .IP
2148 If you have a font family which provides regular upright (roman),
2149 bold,
2150 italic,
2151 and
2152 bold-italic styles,
2153 (where \[lq]italic\[rq] may be \[lq]oblique\[rq] or \[lq]slanted\[rq]),
2154 we recommend using
2155 .BR R ,
2156 .BR B ,
2157 .BR I ,
2158 and
2159 .BR BI ,
2160 respectively,
2161 as suffixes to the
2162 .I groff
2163 font family name to enable
2164 .IR groff 's
2165 font family and style selection features.
2166 .
2167 An example is
2168 .IR groff 's
2169 built-in support for Times:
2170 the font family
2171 name is abbreviated as
2172 .BR T ,
2173 and the
2174 .I groff
2175 font names are therefore
2176 .BR TR ,
2177 .BR TB ,
2178 .BR TI ,
2179 and
2180 .BR TBI .
2181 .
2182 In our example,
2183 however,
2184 the BrushScriptX font is available in a single style only,
2185 italic.
2186 .
2187 .
2188 .IP \[bu]
2189 Install the
2190 .I groff
2191 font description file(s) in a
2192 .I devpdf
2193 subdirectory in the search path that
2194 .I groff
2195 uses for device and font file descriptions.
2196 .
2197 See the
2198 .I GROFF_FONT_PATH
2199 entry in section \[lq]Environment\[rq] of
2200 .MR \%troff 1
2201 for the current value of the font search path.
2202 .
2203 While
2204 .I groff
2205 doesn't directly use AFM files,
2206 it is a good idea to store them alongside its font description files.
2207 .
2208 .
2209 .IP \[bu]
2210 Register fonts in the
2211 .I devpdf/download
2212 file so they can be located for embedding in PDF files
2213 .I gropdf
2214 generates.
2215 .
2216 Only the first
2217 .I download
2218 file encountered in the font search path is read.
2219 .
2220 If in doubt,
2221 copy the default
2222 .I download
2223 file
2224 (see section \[lq]Files\[rq] below)
2225 to the first directory in the font search path and add your fonts there.
2226 .
2227 The PostScript font name used by
2228 .I gropdf
2229 is stored in the
2230 .B internalname
2231 field in the
2232 .I groff
2233 font description file.
2234 .
2235 (This name does not necessarily resemble the font's file name.)
2236 .
2237 If the font in our example had originated from a foundry named
2238 .BR Z ,
2239 we would add the following line to
2240 .IR download .
2241 .
2242 .RS
2243 .RS \" two RS calls to get inboard of IP indentation
2244 .EX
2245 Z\[->]BrushScriptX\-Italic\[->]BrushScriptX\-Italic.pfa
2246 .EE
2247 .RE \" but only one to get back to it
2248 .
2249 A tab character,
2250 depicted as \[->],
2251 separates the fields.
2252 .
2253 The default foundry has no name:
2254 its field is empty and
2255 entries corresponding to it start with a tab character,
2256 as will the one in our example.
2257 .RE \" now restore left margin
2258 .
2259 .
2260 .IP \[bu]
2261 Test the selection and embedding of the new font.
2262 .
2263 .RS
2264 .RS \" two RS calls to get inboard of IP indentation
2265 .EX
2266 printf "\[rs]\[rs]f[BSI]Hello, world!\[rs]n" \
2267 | groff \-T pdf \-P \-e >hello.pdf
2268 see hello.pdf
2269 .EE
2270 .RE
2271 .RE
2272 .
2273 .
2274 .\" ====================================================================
2275 .SH "Exit status"
2276 .\" ====================================================================
2277 .
2278 .IP 0
2279 .I gropdf
2280 successfully produced a PDF document.
2281 .
2282 .
2283 .IP 1
2284 .I gropdf
2285 experienced a critical error,
2286 or warnings were emitted and the
2287 .B \-W
2288 option was specified.
2289 .
2290 .
2291 .IP 2
2292 .I gropdf
2293 could not interpret its command-line arguments.
2294 .
2295 .
2296 .br
2297 .ne 5v
2298 .\" ====================================================================
2299 .SH Environment
2300 .\" ====================================================================
2301 .
2302 .TP
2303 .I GROFF_FONT_PATH
2304 A list of directories in which to seek the selected output device's
2305 directory of device and font description files.
2306 .
2307 If,
2308 in the
2309 .I download
2310 file,
2311 the font file has been specified with a full path,
2312 no directories are searched.
2313 .
2314 See
2315 .MR \%troff 1
2316 and
2317 .MR groff_font 5 .
2318 .
2319 .
2320 .TP
2321 .I GROPDF_NOSLIDE
2322 If set and evaluates to a true value
2323 (to Perl),
2324 .\" XXX: The above is inconsistent with the way grotty(1) handles
2325 .\" "GROFF_NO_SGR".
2326 .I gropdf
2327 ignores commands specific to presentation PDFs,
2328 producing a normal PDF instead.
2329 .
2330 .
2331 .TP
2332 .I GROPDF_OPTIONS
2333 .I gropdf
2334 interprets the contents of this environment variable
2335 as a space-separated list of command-line options.
2336 .
2337 Explicit command-line options override any settings
2338 from this environment variable.
2339 .
2340 .
2341 .TP
2342 .I SOURCE_DATE_EPOCH
2343 A timestamp
2344 (expressed as seconds since the Unix epoch)
2345 to use as the output creation timestamp in place of the current time.
2346 .
2347 The time is converted to human-readable form using Perl's
2348 .I \%gmtime()
2349 function and recorded in a PDF comment.
2350 .
2351 .
2352 .TP
2353 .I TZ
2354 The time zone to use when converting the current time to human-readable form;
2355 see
2356 .MR tzset 3 .
2357 If
2358 .I SOURCE_DATE_EPOCH
2359 is used, it is always converted to human-readable form using UTC.
2360 .
2361 .
2362 .\" ====================================================================
2363 .SH Files
2364 .\" ====================================================================
2365 .
2366 .TP
2367 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\:DESC
2368 describes the
2369 .B pdf
2370 output device.
2371 .
2372 .
2373 .TP
2374 .IR /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/ F
2375 describes the font known
2376 .RI as\~ F
2377 on device
2378 .BR pdf .
2379 .
2380 .
2381 .TP
2382 .IR /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\:U\- F
2383 describes the font
2384 from the URW foundry
2385 (versus the Adobe default)
2386 known
2387 .RI as\~ F
2388 on device
2389 .BR pdf .
2390 .
2391 .
2392 .TP
2393 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\%download
2394 lists fonts available for embedding within the PDF document
2395 (by analogy to the
2396 .B ps
2397 device's downloadable font support).
2398 .
2399 .
2400 .\" XXX: Why are we shipping this but not BuildFoundries.pl?
2401 .TP
2402 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\%Foundry
2403 is a data file used by the
2404 .I groff
2405 build system to locate PostScript Type\~1 fonts.
2406 .
2407 .
2408 .TP
2409 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\:\%symbolsl\:.afm
2410 provides metrics for the slanted symbol font known to
2411 .I groff
2412 as
2413 .BR SS .
2414 .
2415 These data facilitate use of the font with
2416 .RI non- groff
2417 software.
2418 .
2419 .
2420 .TP
2421 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\:\%symbolsl\:.pfb
2422 supplies the slanted symbol font known to
2423 .I groff
2424 as
2425 .BR SS .
2426 .
2427 .
2428 .TP
2429 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\:enc/\:\%text\:.enc
2430 describes the encoding scheme used by most PostScript Type\~1 fonts;
2431 the
2432 .B \%encoding
2433 directive of
2434 font description files for the
2435 .B pdf
2436 device refers to it.
2437 .
2438 .
2439 .TP
2440 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devpdf/\:\%generate/\:\%symbolsl\:.sfd
2441 is the source form of the
2442 .I \%symbolsl.pfb
2443 font,
2444 in spline font database (SFD) format.
2445 .
2446 .
2447 .TP
2448 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:pdf\:.tmac
2449 defines macros for use with the
2450 .B pdf
2451 output device.
2452 .
2453 It is automatically loaded by
2454 .I troffrc
2455 when the
2456 .B pdf
2457 output device is selected.
2458 .
2459 .
2460 .TP
2461 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:\%pdfpic\:.tmac
2462 defines the
2463 .B PDFPIC
2464 macro for embedding images in a document;
2465 see
2466 .MR groff_tmac 5 .
2467 .
2468 It is automatically loaded by
2469 .I troffrc.
2470 .
2471 .
2472 .TP
2473 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%examples/\:install\-font\:.bash
2474 This script,
2475 contributed by
2476 .I mom
2477 macro package author Peter Schaffter
2478 and long available at his web site,
2479 assists with making
2480 TrueType
2481 .RI ( .ttf ),
2482 OpenType
2483 .RI ( .otf ),
2484 and PostScript Type\~1
2485 .RI ( .pfa ,
2486 .IR .pfb )
2487 fonts available to
2488 .IR groff .
2489 .
2490 .IP
2491 Change to its directory and run
2492 .RB \[lq] "bash install\-font.bash \-H" \[rq]
2493 for a man page-like description of its features and operation.
2494 .\"
2495 .\"
2496 .\" .TP
2497 .\" .B /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/pspic.tmac
2498 .\" Definition of
2499 .\" .B PSPIC
2500 .\" macro,
2501 .\" automatically loaded by
2502 .\" .BR ps.tmac .
2503 .\" .
2504 .
2505 .
2506 .\" ====================================================================
2507 .SH Authors
2508 .\" ====================================================================
2509 .
2510 .I gropdf
2511 was written and is maintained by
2512 .MT deri@\:chuzzlewit\:.myzen\:.co\:.uk
2513 Deri James
2514 .ME .
2515 .
2516 .
2517 .br
2518 .ne 3v
2519 .\" ====================================================================
2520 .SH "See also"
2521 .\" ====================================================================
2522 .
2523 .TP
2524 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%sboxes/\:\%msboxes\:.ms
2525 .TQ
2526 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%sboxes/\:\%msboxes\:.pdf
2527 \[lq]Using PDF boxes with
2528 .I groff
2529 and the
2530 .I ms
2531 macros\[rq],
2532 by Deri James.
2533 .
2534 .
2535 .TP
2536 .I present.tmac
2537 is part of
2538 .UR https://\:bob\:.diertens\:.org/\:corner/\:useful/\:gpresent/
2539 .I gpresent
2540 .UE ,
2541 a software package by Bob Diertens that works with
2542 .I groff
2543 to produce presentations
2544 (\[lq]foils\[rq],
2545 or \[lq]slide decks\[rq]).
2546 .
2547 .
2548 .P
2549 .MR afmtodit 1 ,
2550 .MR groff 1 ,
2551 .MR \%troff 1 ,
2552 .MR groff_font 5 ,
2553 .MR groff_out 5
2554 .\" Not actually referenced in above discussion.
2555 .\" .BR \%pfbtops (1),
2556 .\" .BR \%groff_tmac (5),
2557 .
2558 .
2559 .\" Clean up.
2560 .rm FT
2561 .
2562 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
2563 .cp \n[*groff_gropdf_1_man_C]
2564 .do rr *groff_gropdf_1_man_C
2565 .
2566 .
2567 .\" Local Variables:
2568 .\" fill-column: 72
2569 .\" mode: nroff
2570 .\" End:
2571 .\" vim: set filetype=groff textwidth=72: