contrib/groff/contrib/pdfmark/pdfroff.man

   1 .TH PDFROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   2 .\" --------------------------------------------------------------------
   3 .\" Legal Matters
   4 .\" --------------------------------------------------------------------
   5 .ig
   6 pdfroff.1
   7
   8 File position: <groff-source>/contrib/pdfmark/pdfroff.man
   9
  10 Last update: 5 Jan 2009
  11
  12 This file is part of groff, the GNU roff type-setting system.
  13
  14 Copyright (C) 2005, 2006, 2007, 2009 Free Software Foundation, Inc.
  15 written by Keith Marshall <keith.d.marshall@ntlworld.com>
  16
  17 Permission is granted to copy, distribute and/or modify this document
  18 under the terms of the GNU Free Documentation License, Version 1.3 or
  19 any later version published by the Free Software Foundation; with no
  20 Front-Cover Texts, no Back-Cover Texts, and the following Invariant
  21 Sections:--
  22
  23     a)  This "Legal Matters" section, extending from the start of
  24         the document, to the end of the enclosing ".ig" section.
  25
  26     b)  The entire section bearing the heading "AUTHOR", extending
  27         from the ".SH AUTHOR" tag, to the end of the document.
  28
  29 A copy of the Free Documentation License is included as a file called
  30 FDL in the main directory of the groff source package.
  31 ..
  32 .
  33 .
  34 .\" --------------------------------------------------------------------
  35 .\" Local macro definitions
  36 .
  37 .hw pdfmark
  38 .
  39 .de NH
  40 .  hy 0
  41 \&\\$*
  42 .  hy
  43 ..
  44 .
  45 .
  46 .\" --------------------------------------------------------------------
  47 .
  48 .SH NAME
  49 .
  50 pdfroff \- create PDF documents using groff
  51 .
  52 .
  53 .\" --------------------------------------------------------------------
  54 .
  55 .SH SYNOPSIS
  56 .
  57 .SY pdfroff
  58 .OP \-abcegilpstzCEGNRSUVXZ
  59 .OP \-d cs
  60 .OP \-f fam
  61 .OP \-F dir
  62 .OP \-I dir
  63 .OP \-L arg
  64 .OP \-m name
  65 .OP \-M dir
  66 .OP \-n num
  67 .OP \-o list
  68 .OP \-P arg
  69 .OP \-r cn
  70 .OP \-T dev
  71 .OP \-w name
  72 .OP \-W name
  73 .OP \-\-emit\-ps
  74 .OP \-\-no\-toc\-relocation
  75 .OP \-\-no-kill\-null\-pages
  76 .OP \-\-stylesheet=\fIname\fP
  77 .OP \-\-no\-pdf\-output
  78 .OP \-\-pdf\-output=\fIname\fP
  79 .OP \-\-no\-reference\-dictionary
  80 .OP \-\-reference\-dictionary=\fIname\fP
  81 .OP \-\-report\-progress
  82 .OP \-\-keep\-temporary\-files
  83 .I file .\|.\|.
  84 .
  85 .SY pdfroff
  86 .B \-h
  87 |
  88 .B \-\-help
  89 .
  90 .SY pdfroff
  91 .B \-v
  92 |
  93 .B \-\-version
  94 .RI [ option\ .\|.\|. ]
  95 .YS
  96 .
  97 .
  98 .\" --------------------------------------------------------------------
  99 .
 100 .SH DESCRIPTION
 101 .
 102 .B pdfroff
 103 is a wrapper program for the GNU text processing system,
 104 .BR  groff .
 105 It transparently handles the mechanics of multiple pass
 106 .B groff
 107 processing, when applied to suitably marked up
 108 .B groff
 109 source files,
 110 such that tables of contents and body text are formatted separately,
 111 and are subsequently combined in the correct order, for final publication
 112 as a single PDF document.
 113 A further optional
 114 \*(lqstyle sheet\*(rq
 115 capability is provided;
 116 this allows for the definition of content which is required to precede the
 117 table of contents, in the published document.
 118 .
 119 .P
 120 For each invocation of
 121 .BR pdfroff ,
 122 the ultimate
 123 .B groff
 124 output stream is post-processed by the GhostScript interpreter,
 125 to produce a finished PDF document.
 126 .
 127 .P
 128 .B pdfroff
 129 makes no assumptions about, and imposes no restrictions on,
 130 the use of any
 131 .B groff
 132 macro packages which the user may choose to employ,
 133 in order to achieve a desired document format;
 134 however, it
 135 .I does
 136 include specific built in support for the
 137 .B pdfmark
 138 macro package, should the user choose to employ it.
 139 Specifically, if the
 140 .I pdfhref
 141 macro, defined in the
 142 .B pdfmark.tmac
 143 package, is used to define public reference marks,
 144 or dynamic links to such reference marks, then
 145 .B pdfroff
 146 performs as many preformatting
 147 .B groff
 148 passes as required, up to a maximum limit of
 149 .IR four ,
 150 in order to compile a document reference dictionary,
 151 to resolve references, and to expand the dynamically defined
 152 content of links.
 153 .
 154 .
 155 .\" --------------------------------------------------------------------
 156 .
 157 .SH USAGE
 158 .
 159 The command line is parsed in accordance with normal GNU conventions,
 160 but with one exception \(em when specifying any short form option
 161 (i.e., a single character option introduced by a single hyphen),
 162 and if that option expects an argument, then it
 163 .I must
 164 be specified independently (i.e., it may
 165 .I not
 166 be appended to any group of other single character short form options).
 167 .
 168 .P
 169 Long form option names (i.e., those introduced by a double hyphen)
 170 may be abbreviated to their minimum length unambiguous initial
 171 substring.
 172 .
 173 .P
 174 Otherwise,
 175 .B pdfroff
 176 usage closely mirrors that of
 177 .B groff
 178 itself.
 179 Indeed,
 180 with the exception of the
 181 .BR \-h ,
 182 .BR \-v ,
 183 and
 184 .BI \-T \ dev
 185 short form options, and
 186 all long form options,
 187 which are parsed internally by
 188 .BR pdfroff ,
 189 all options and file name arguments specified on the command line are
 190 passed on to
 191 .BR groff ,
 192 to control the formatting of the PDF document.
 193 Consequently,
 194 .B pdfroff
 195 accepts all options and arguments, as specified in
 196 .BR groff (@MAN1EXT@),
 197 which may also be considered as the definitive reference for all standard
 198 .BR pdfroff
 199 options and argument usage.
 200 .
 201 .
 202 .\" --------------------------------------------------------------------
 203 .
 204 .SH OPTIONS
 205 .
 206 .B pdfroff
 207 accepts all of the short form options
 208 (i.e., those introduced by a single hyphen),
 209 which are available with
 210 .B groff
 211 itself.
 212 In most cases, these are simply passed transparently to
 213 .BR groff ;
 214 the following, however, are handled specially by
 215 .BR pdfroff .
 216 .
 217 .TP
 218 .B \-h
 219 Same as
 220 .BR \-\-help ;
 221 see below.
 222 .
 223 .TP
 224 .B \-i
 225 Process standard input, after all other specified input files.
 226 This is passed transparently to
 227 .BR groff ,
 228 but, if grouped with other options, it
 229 .I must
 230 be the first in the group.
 231 Hiding it within a group
 232 breaks standard input processing, in the multiple pass
 233 .B groff
 234 processing context of
 235 .BR pdfroff .
 236 .
 237 .TP
 238 .BI \-T \ dev
 239 Only
 240 .B \-T\ ps
 241 is supported by
 242 .BR pdfroff .
 243 Attempting to specify any other device causes
 244 .B pdfroff
 245 to abort.
 246 .
 247 .TP
 248 .B \-v
 249 Same as
 250 .BR \-\-version ;
 251 see below.
 252 .
 253 .P
 254 See
 255 .BR groff (@MAN1EXT@)
 256 for a description of all other short form options,
 257 which are transparently passed through
 258 .BR pdfroff
 259 to
 260 .BR groff .
 261 .
 262 .P
 263 All long form options
 264 (i.e., those introduced by a double hyphen)
 265 are interpreted locally by
 266 .BR pdfroff ;
 267 they are
 268 .B not
 269 passed on to
 270 .BR groff ,
 271 unless otherwise stated below.
 272 .
 273 .TP
 274 .B \-\-help
 275 Causes
 276 .B pdfroff
 277 to display a summary of the its usage syntax, and supported options,
 278 and then exit.
 279 .
 280 .TP
 281 .B \-\-emit\-ps
 282 Suppresses the final output conversion step,
 283 causing
 284 .B pdfroff
 285 to emit PostScript output instead of PDF.
 286 This may be useful,
 287 to capture intermediate PostScript output,
 288 when using a specialised postprocessor,
 289 such as
 290 .I gpresent
 291 for example,
 292 in place of the default
 293 .I GhostScript
 294 PDF writer.
 295 .
 296 .TP
 297 .B \-\-keep\-temporary\-files
 298 Suppresses the deletion of temporary files,
 299 which normally occurs after
 300 .B pdfroff
 301 has completed PDF document formatting;
 302 this may be useful,
 303 when debugging formatting problems.
 304 .IP
 305 See section
 306 .BR FILES ,
 307 for a description of the temporary files used by
 308 .BR pdfroff .
 309 .
 310 .TP
 311 .B \-\-no\-pdf\-output
 312 May be used with the
 313 .BI \%\-\-reference\-dictionary= name
 314 option (described below) to eliminate the overhead of PDF formatting,
 315 when running
 316 .B pdfroff
 317 to create a reference dictionary, for use in a different document.
 318 .
 319 .TP
 320 .B \-\-no\-reference\-dictionary
 321 May be used to eliminate the overhead of creating a reference dictionary,
 322 when it is known that the target PDF document contains no public
 323 references, created by the
 324 .I pdfhref
 325 macro.
 326 .
 327 .TP
 328 .B \-\-no\-toc\-relocation
 329 May be used to eliminate the extra
 330 .B groff
 331 processing pass,
 332 which is required to generate a table of contents,
 333 and relocate it to the start of the PDF document,
 334 when processing any document which lacks an automatically
 335 generated table of contents.
 336 .
 337 .TP
 338 .B \-\-no\-kill\-null\-pages
 339 While preparing for simulation of the manual collation step,
 340 which is traditionally required to relocate of a
 341 .I "table of contents"
 342 to the start of a document,
 343 .B pdfroff
 344 accumulates a number of empty page descriptions
 345 into the intermediate
 346 .I PostScript
 347 output stream.
 348 During the final collation step,
 349 these empty pages are normally discarded from the finished document;
 350 this option forces
 351 .B pdfroff
 352 to leave them in place.
 353 .
 354 .TP
 355 .BI \-\-pdf\-output= name
 356 Specifies the name to be used for the resultant PDF document;
 357 if unspecified, the PDF output is written to standard output.
 358 A future version of
 359 .B pdfroff
 360 may use this option,
 361 to encode the document name in a generated reference dictionary.
 362 .
 363 .TP
 364 .BI \-\-reference\-dictionary= name
 365 Specifies the name to be used for the generated reference dictionary file;
 366 if unspecified, the reference dictionary is created in a temporary file,
 367 which is deleted when
 368 .B pdfroff
 369 completes processing of the current document.
 370 This option
 371 .I must
 372 be specified, if it is desired to save the reference dictionary,
 373 for use in references placed in other PDF documents.
 374 .
 375 .TP
 376 .B \-\-report\-progress
 377 Causes
 378 .B pdfroff
 379 to display an informational message on standard error,
 380 at the start of each
 381 .B groff
 382 processing pass.
 383 .
 384 .TP
 385 .BI \-\-stylesheet= name
 386 Specifies the name of an
 387 .IR "input file" ,
 388 to be used as a style sheet for formatting of content,
 389 which is to be placed
 390 .I before
 391 the table of contents,
 392 in the formatted PDF document.
 393 .
 394 .TP
 395 .B \-\-version
 396 Causes
 397 .B pdfroff
 398 to display a version identification message.
 399 The entire command line is then passed transparently to
 400 .BR groff ,
 401 in a
 402 .I one
 403 pass operation
 404 .IR only ,
 405 in order to display the associated
 406 .B groff
 407 version information, before exiting.
 408 .
 409 .
 410 .\" --------------------------------------------------------------------
 411 .
 412 .SH ENVIRONMENT
 413 The following environment variables may be set, and exported,
 414 to modify the behaviour of
 415 .BR pdfroff .
 416 .
 417 .TP
 418 .B PDFROFF_COLLATE
 419 Specifies the program to be used
 420 for collation of the finshed PDF document.
 421 .IP
 422 This collation step may be required to move
 423 .I tables of contents
 424 to the start of the finished PDF document,
 425 when formatting with traditional macro packages,
 426 which print them at the end.
 427 However,
 428 users should not normally need to specify
 429 .BR \%PDFROFF_COLLATE ,
 430 (and indeed,
 431 are not encouraged to do so).
 432 If unspecified,
 433 .B pdfroff
 434 uses
 435 .BR sed (@MAN1EXT@)
 436 by default,
 437 which normally suffices.
 438 .IP
 439 If
 440 .B \%PDFROFF_COLLATE
 441 .I is
 442 specified,
 443 then it must act as a filter,
 444 accepting a list of file name arguments,
 445 and write its output to the
 446 .I stdout
 447 stream,
 448 whence it is piped to the
 449 .BR \%PDFROFF_POSTPROCESSOR_COMMAND ,
 450 to produce the finished PDF output.
 451 .IP
 452 When specifying
 453 .BR \%PDFROFF_COLLATE ,
 454 it is normally necessary to also specify
 455 .BR \%PDFROFF_KILL_NULL_PAGES .
 456 .IP
 457 .B \%PDFROFF_COLLATE
 458 is ignored,
 459 if
 460 .B pdfroff
 461 is invoked with the
 462 .I \%\-\-no\-kill\-null\-pages
 463 option.
 464 .
 465 .TP
 466 .B PDFROFF_KILL_NULL_PAGES
 467 Specifies options to be passed to the
 468 .B \%PDFROFF_COLLATE
 469 program.
 470 .IP
 471 It should not normally be necessary to specify
 472 .BR \%PDFROFF_KILL_NULL_PAGES .
 473 The internal default is a
 474 .BR sed (@MAN1EXT@)
 475 script,
 476 which is intended to remove completely blank pages
 477 from the collated output stream,
 478 and which should be appropriate in most applications of
 479 .BR pdfroff .
 480 However,
 481 if any alternative to
 482 .BR sed (@MAN1EXT@)
 483 is specified for
 484 .BR \%PDFROFF_COLLATE ,
 485 then it is likely that a corresponding alternative specification for
 486 .B \%PDFROFF_KILL_NULL_PAGES
 487 is required.
 488 .IP
 489 As in the case of
 490 .BR \%PDFROFF_COLLATE ,
 491 .B \%PDFROFF_KILL_NULL_PAGES
 492 is ignored,
 493 if
 494 .B pdfroff
 495 is invoked with the
 496 .I \%\-\-no\-kill\-null\-pages
 497 option.
 498 .
 499 .TP
 500 .B PDFROFF_POSTPROCESSOR_COMMAND
 501 Specifies the command to be used for the final document conversion
 502 from PostScript intermediate output to PDF.
 503 It must behave as a filter,
 504 writing its output to the
 505 .I stdout
 506 stream,
 507 and must accept an arbitrary number of
 508 .I files .\|.\|.\&
 509 arguments,
 510 with the special case of
 511 .I \-
 512 representing the
 513 .I stdin
 514 stream.
 515 .IP
 516 If unspecified,
 517 .B \%PDFROFF_POSTPROCESSOR_COMMAND
 518 defaults to
 519 .
 520 .RS 2
 521 .IP
 522 .I
 523 .ad l
 524 .NH gs \-dBATCH \-dQUIET \-dNOPAUSE \-sDEVICE=pdfwrite \-sOutputFile=\-
 525 .ad
 526 .RE
 527 .
 528 .TP
 529 .B GROFF_TMPDIR
 530 Identifies the directory in which
 531 .B pdfroff
 532 should create temporary files.
 533 If
 534 .B \%GROFF_TMPDIR
 535 is
 536 .I not
 537 specified, then the variables
 538 .BR TMPDIR ,
 539 .B TMP
 540 and
 541 .B TEMP
 542 are considered in turn, as possible temporary file repositories.
 543 If none of these are set, then temporary files are created
 544 in the current directory.
 545 .
 546 .TP
 547 .B GROFF_GHOSTSCRIPT_INTERPRETER
 548 Specifies the program to be invoked, when
 549 .B pdfroff
 550 converts
 551 .B groff
 552 PostScript output to PDF.
 553 If
 554 .B \%PDFROFF_POSTPROCESSOR_COMMAND
 555 is specified,
 556 then the command name it specifies is
 557 .I implicitly
 558 assigned to
 559 .BR \%GROFF_GHOSTSCRIPT_INTERPRETER ,
 560 overriding any explicit setting specified in the environment.
 561 If
 562 .B \%GROFF_GHOSTSCRIPT_INTERPRETER
 563 is not specified, then
 564 .B pdfroff
 565 searches the process
 566 .BR PATH ,
 567 looking for a program with any of the well known names
 568 for the GhostScript interpreter;
 569 if no GhostScript interpreter can be found,
 570 .B pdfroff
 571 aborts.
 572 .
 573 .TP
 574 .B GROFF_AWK_INTERPRETER
 575 Specifies the program to be invoked, when
 576 .B pdfroff
 577 is extracting reference dictionary entries from a
 578 .B groff
 579 intermediate message stream.
 580 If
 581 .B \%GROFF_AWK_INTERPRETER
 582 is not specified, then
 583 .B pdfroff
 584 searches the process
 585 .BR PATH ,
 586 looking for any of the preferred programs, `gawk', `mawk', `nawk'
 587 and `awk', in this order;
 588 if none of these are found,
 589 .B pdfroff
 590 issues a warning message, and continue processing;
 591 however, in this case, no reference dictionary is created.
 592 .
 593 .TP
 594 .B OSTYPE
 595 Typically defined automatically by the operating system,
 596 .B OSTYPE
 597 is used on Microsoft Win32/MS-DOS platforms
 598 .IR only ,
 599 to infer the default
 600 .B \%PATH_SEPARATOR
 601 character,
 602 which is used when parsing the process
 603 .B PATH
 604 to search for external helper programs.
 605 .
 606 .TP
 607 .B PATH_SEPARATOR
 608 If set,
 609 .B \%PATH_SEPARATOR
 610 overrides the default separator character,
 611 (`:' on POSIX/UNIX systems,
 612 inferred from
 613 .B OSTYPE
 614 on Microsoft Win32/MS-DOS),
 615 which is used when parsing the process
 616 .B PATH
 617 to search for external helper programs.
 618 .
 619 .TP
 620 .B SHOW_PROGRESS
 621 If this is set to a non-empty value, then
 622 .B pdfroff
 623 always behaves as if the
 624 .B \%\-\-report\-progress
 625 option is specified, on the command line.
 626 .
 627 .
 628 .\" --------------------------------------------------------------------
 629 .
 630 .SH FILES
 631 Input and output files for
 632 .B pdfroff
 633 may be named according to any convention of the user's choice.
 634 Typically, input files may be named according to the choice of the
 635 principal formatting macro package, e.g.,
 636 .IB file .ms
 637 might be an input file for formatting using the
 638 .B ms
 639 macros
 640 .RB ( s.tmac );
 641 normally, the final output file should be named
 642 .IB file .pdf\c
 643 \&.
 644 .
 645 .P
 646 Temporary files, created by
 647 .BR pdfroff ,
 648 are placed in the directory specified by environment variables (see
 649 section
 650 .BR ENVIRONMENT ),
 651 and named according to the convention
 652 .BI pdf $$ .*\c
 653 \&, where
 654 .I $$
 655 is the standard shell variable representing the process ID of the
 656 .B pdfroff
 657 process itself, and
 658 .I *
 659 represents any of the extensions used by
 660 .B pdfroff
 661 to identify the following temporary and intermediate files.
 662 .
 663 .TP
 664 .BI pdf $$ .tmp
 665 A scratch pad file,
 666 used to capture reference data emitted by
 667 .BR groff ,
 668 during the
 669 .I reference dictionary
 670 compilation phase.
 671 .
 672 .TP
 673 .BI pdf $$ .ref
 674 The
 675 .IR "reference dictionary" ,
 676 as compiled in the last but one pass of the
 677 .I reference dictionary
 678 compilation phase;
 679 (at the start of the first pass,
 680 this file is created empty;
 681 in successive passes,
 682 it contains the
 683 .I reference dictionary
 684 entries,
 685 as collected in the preceding pass).
 686 .IP
 687 If the
 688 .BR \%\-\-reference\-dictionary =\c
 689 .I name
 690 option is specified,
 691 this intermediate file becomes permanent,
 692 and is named
 693 .IR name ,
 694 rather than
 695 .BI pdf $$ .ref\c
 696 \&.
 697 .
 698 .TP
 699 .BI pdf $$ .cmp
 700 Used to collect
 701 .I reference dictionary
 702 entries during the active pass of the
 703 .I reference dictionary
 704 compilation phase.
 705 At the end of any pass,
 706 when the content of
 707 .BI pdf $$ .cmp
 708 compares as identical to
 709 .BI pdf $$ .ref\c
 710 \&,
 711 (or the corresponding file named by the
 712 .BR \%\-\-reference\-dictionary =\c
 713 .I name
 714 option),
 715 then
 716 .I reference dictionary
 717 compilation is terminated,
 718 and the
 719 .I document reference map
 720 is appended to this intermediate file,
 721 for inclusion in the final formatting passes.
 722 .
 723 .TP
 724 .BI pdf $$ .tc
 725 An intermediate
 726 .I PostScript
 727 file,
 728 in which \*(lqTable of Contents\*(rq entries are collected,
 729 to facilitate relocation before the body text,
 730 on ultimate output to the
 731 .I GhostScript
 732 postprocessor.
 733 .
 734 .TP
 735 .BI pdf $$ .ps
 736 An intermediate
 737 .I PostScript
 738 file,
 739 in which the body text is collected prior to ultimate output to the
 740 .I GhostScript
 741 postprocessor,
 742 in the proper sequence,
 743 .I after
 744 .BI pdf $$ .tc\c
 745 \&.
 746 .
 747 .
 748 .\" --------------------------------------------------------------------
 749 .
 750 .SH SEE ALSO
 751 See
 752 .BR groff (@MAN1EXT@)
 753 for the definitive reference to document formatting with
 754 .BR groff .
 755 Since
 756 .B pdfroff
 757 provides a superset of all
 758 .B groff
 759 capabilities,
 760 .BR groff (@MAN1EXT@)
 761 may also be considered to be the definitive reference to all
 762 .I standard
 763 capabilities of
 764 .BR pdfroff ,
 765 with this document providing the reference to
 766 .BR pdfroff 's
 767 extended features.
 768 .
 769 .P
 770 While
 771 .B pdfroff
 772 imposes neither any restriction on, nor any requirement for,
 773 the use of any specific
 774 .B groff
 775 macro package, a number of supplied macro packages,
 776 and in particular those associated with the package
 777 .BR pdfmark.tmac ,
 778 are best suited for use with
 779 .BR pdfroff
 780 as the preferred formatter.
 781 Detailed documentation on the use of these packages may be found,
 782 in PDF format, in the reference guide
 783 .BR "\*(lqPortable Document Format Publishing with GNU Troff\*(rq" ,
 784 included in the installed documentation set as
 785 .BR \%@PDFDOCDIR@/pdfmark.pdf .
 786 .
 787 .
 788 .\" --------------------------------------------------------------------
 789 .
 790 .SH AUTHOR
 791 Copyright \(co 2005, 2006, 2007, 2009 Free Software Foundation, Inc.
 792 .
 793 .P
 794 This man page is distributed under the terms of the
 795 GNU Free Documentation License (FDL), version 1.3 or later,
 796 and is part of the
 797 .I GNU troff
 798 software package.
 799 It was originally written by
 800 .MT keith.d.marshall@\:ntlworld.com
 801 Keith Marshall
 802 .ME ,
 803 who also wrote the implementation of the
 804 .I pdfroff
 805 program, to which it relates.
 806 .
 807 .P
 808 You should have received a copy of the FDL as part of the
 809 .I GNU troff
 810 distribution; it is also available on\-line, at
 811 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
 812 the GNU copyleft site
 813 .UE .
 814 .
 815 .\" --------------------------------------------------------------------
 816 .\" EOF / vim: ft=groff