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