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
  12 This file is part of groff, the GNU roff type-setting system.
  13
  14 Copyright (C) 2005 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.1 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 .SH NAME
  35 pdfroff \- create PDF documents using
  36 .I groff
  37 .
  38 .hw pdfmark
  39 .de Q
  40 \&\\$3\*(lq\\$1\*(rq\\$2
  41 ..
  42 .de nohy
  43 .hy 0
  44 \&\\$*
  45 .hy
  46 ..
  47 .\" --------------------------------------------------------------------
  48 .
  49 .SH SYNOPSIS
  50 .de cmd
  51 .   if r@i .in
  52 .   nr @i \\n(.i
  53 .   in +\w'\f[B]\\$1\0'u
  54 .   ti \\n(@iu
  55 .   B \\$1\0\c
  56 ..
  57 .de opt
  58 .   tr -\-
  59 .   RB [ -\\$1\c
  60 .   IR \&\\$2 ]
  61 .   tr --
  62 ..
  63 .de opta
  64 .   ie \\n(.$>1 .opt \\$1 \0\\$2
  65 .   el .opt \\$1
  66 ..
  67 .de opte
  68 .   tr -\-
  69 .   RB [ -\\$1 =\c
  70 .   IR \&\\$2 ]
  71 .   tr --
  72 ..
  73 .de optx
  74 .   tr -\-
  75 .   RB [ --no\\$1 \0|\0\c
  76 .   BR -\\$1 =\c
  77 .   IR \&\\$2 ]
  78 .   tr --
  79 ..
  80 .ad l
  81 .hy 0
  82 .ll -5
  83 .cmd pdfroff
  84 .opt  abcegilpstzCEGNRSUVXZ
  85 .opta d cs
  86 .opta f fam
  87 .opta F dir
  88 .opta I dir
  89 .opta L arg
  90 .opta m name
  91 .opta M dir
  92 .opta n num
  93 .opta o list
  94 .opta P arg
  95 .opta r cn
  96 .opta T dev
  97 .opta w name
  98 .opta W name
  99 .opt  -no-toc-relocation
 100 .opte -stylesheet name
 101 .optx -pdf-output name
 102 .optx -reference-dictionary name
 103 .opt  -report-progress
 104 .B file
 105 .I ...
 106 .ll
 107 .sp
 108 .cmd pdfroff
 109 .B -h
 110 |
 111 .B --help
 112 .sp
 113 .cmd pdfroff
 114 .B -v
 115 |
 116 .B --version
 117 .RI [ option
 118 .IR ... ]
 119 .rr @i
 120 .in
 121 .ad
 122 .hy
 123 .P
 124 The command line is parsed in accordance with normal GNU conventions,
 125 but with one exception \(em when specifying any short form option
 126 (i.e., a single character option introduced by a single hyphen),
 127 and if that option expects an argument, then it
 128 .I must
 129 be specified independently (i.e., it may
 130 .I not
 131 be appended to any group of other single character short form options).
 132 .P
 133 Long form option names (i.e., those introduced by a double hyphen)
 134 may be abbreviated to their minimum length unambigous initial substring.
 135 .
 136 .\" --------------------------------------------------------------------
 137 .
 138 .SH DESCRIPTION
 139 .B pdfroff
 140 is a wrapper program for the GNU text processing system,
 141 .BR  groff .
 142 It transparently handles the mechanics of multiple pass
 143 .B groff
 144 processing, when applied to suitably marked up
 145 .B groff
 146 source files,
 147 such that tables of contents and body text are formatted separately,
 148 and are subsequently combined in the correct order, for final publication
 149 as a single PDF document.
 150 A further optional
 151 .Q style\0sheet
 152 capability is provided;
 153 this allows for the definition of content which is required to preceed the
 154 table of contents, in the published document.
 155 .P
 156 For each invocation of
 157 .BR pdfroff ,
 158 the ultimate
 159 .B groff
 160 output stream is post\(hyprocessed by the GhostScript interpreter,
 161 to produce a finished PDF document.
 162 .P
 163 .B pdfroff
 164 makes no assumptions about, and imposes no restrictions on,
 165 the use of any
 166 .B groff
 167 macro packages which the user may choose to employ,
 168 in order to achieve a desired document format;
 169 however, it
 170 .I does
 171 include specific built in support for the
 172 .B pdfmark
 173 macro package, should the user choose to employ it.
 174 Specifically, if the
 175 .I pdfhref
 176 macro, defined in the
 177 .B pdfmark.tmac
 178 package, is used to define public reference marks,
 179 or dynamic links to such reference marks, then
 180 .B pdfroff
 181 will perform as many preformatting
 182 .B groff
 183 passes as required, up to a maximum limit of
 184 .IR four ,
 185 in order to compile a document reference dictionary,
 186 to resolve references, and to expand the dynamically defined
 187 content of links.
 188 .
 189 .\" --------------------------------------------------------------------
 190 .
 191 .SH USAGE
 192 .B pdfroff
 193 usage closely mirrors that of
 194 .B groff
 195 itself.
 196 Indeed,
 197 with the exception of the
 198 .BR \-h ,
 199 .BR \-v ,
 200 and
 201 .BI \-T \0dev
 202 short form options, and
 203 all long form options,
 204 which are parsed internally by
 205 .BR pdfroff ,
 206 all options and file name arguments specified on the command line are
 207 passed on to
 208 .BR groff ,
 209 to control the formatting of the PDF document.
 210 Consequently,
 211 .B pdfroff
 212 accepts all options and arguments, as specified in
 213 .BR groff (@MAN1EXT@),
 214 which may also be considered as the definitive reference for all standard
 215 .BR pdfroff
 216 options and argument usage.
 217 .
 218 .\" --------------------------------------------------------------------
 219 .
 220 .SH OPTIONS
 221 .B pdfroff
 222 accepts all of the short form options
 223 (i.e., those introduced by a single hyphen),
 224 which are available with
 225 .B groff
 226 itself.
 227 In most cases, these are simply passed transparently to
 228 .BR groff ;
 229 the following, however, are handled specially by
 230 .BR pdfroff .
 231 .TP
 232 .B \-h
 233 Same as
 234 .BR \-\-help ;
 235 see below.
 236 .TP
 237 .B \-i
 238 Process standard input, after all other specified input files.
 239 This is passed transparently to
 240 .BR groff ,
 241 but, if grouped with other options, it
 242 .I must
 243 be the first in the group.
 244 Hiding it within a group will
 245 break standard input processing, in the multiple pass
 246 .B groff
 247 processing context of
 248 .BR pdfroff .
 249 .TP
 250 .BI \-T \0dev
 251 Only
 252 .BI \-T \0ps
 253 is supported by
 254 .BR pdfroff .
 255 Attempting to specify any other device will cause
 256 .B pdfroff
 257 to abort.
 258 .TP
 259 .B \-v
 260 Same as
 261 .BR \-\-version ;
 262 see below.
 263 .P
 264 See
 265 .BR groff (@MAN1EXT@)
 266 for a description of all other short form options,
 267 which are transparently passed through
 268 .BR pdfroff
 269 to
 270 .BR groff .
 271 .P
 272 All long form options
 273 (i.e., those introduced by a double hyphen)
 274 are interpreted locally by
 275 .BR pdfroff ;
 276 they are
 277 .B not
 278 passed on to
 279 .BR groff ,
 280 unless otherwise stated below.
 281 .TP
 282 .B \-\-help
 283 Causes
 284 .B pdfroff
 285 to display a summary of the its usage syntax, and supported options,
 286 and then exit.
 287 .TP
 288 .B \-\-no\-pdf\-output
 289 May be used with the
 290 .BI \-\-reference\-dictionary= name
 291 option (described below) to eliminate the overhead of PDF formatting,
 292 when running
 293 .B pdfroff
 294 to create a reference dictionary, for use in a different document.
 295 .TP
 296 .B \-\-no\-reference\-dictionary
 297 May be used to eliminate the overhead of creating a reference dictionary,
 298 when it is known that the target PDF document will contain no public
 299 references, created by the
 300 .I pdfhref
 301 macro.
 302 .TP
 303 .B \-\-no\-toc\-relocation
 304 May be used to eliminate the extra
 305 .B groff
 306 processing pass,
 307 which is required to generate a table of contents,
 308 and relocate it to the start of the PDF document,
 309 when processing any document which lacks an automatically
 310 generated table of contents.
 311 .TP
 312 .BI \-\-pdf\-output= name
 313 Specifies the name to be used for the resultant PDF document;
 314 if unspecified, the PDF output is written to standard output.
 315 A future version of
 316 .B pdfroff
 317 may use this option,
 318 to encode the document name in a generated reference dictionary.
 319 .TP
 320 .BI \-\-reference\-dictionary= name
 321 Specifies the name to be used for the generated reference dictionary file;
 322 if unspecified, the reference dictionary is created in a temporary file,
 323 which is deleted when
 324 .B pdfroff
 325 completes processing of the current document.
 326 This option
 327 .I must
 328 be specified, if it is desired to save the reference dictionary,
 329 for use in references placed in other PDF documents.
 330 .TP
 331 .B \-\-report\-progress
 332 Causes
 333 .B pdfroff
 334 to display an informational message on standard error,
 335 at the start of each
 336 .B groff
 337 processing pass.
 338 .TP
 339 .BI \-\-stylesheet= name
 340 Specifies the name of an
 341 .IR "input file" ,
 342 to be used as a style sheet for formatting of content,
 343 which is to be placed
 344 .I before
 345 the table of contents,
 346 in the formatted PDF document.
 347 .TP
 348 .B \-\-version
 349 Causes
 350 .B pdfroff
 351 to display a version identification message.
 352 The entire command line is then passed transparently to
 353 .BR groff ,
 354 in a
 355 .I one
 356 pass operation
 357 .IR only ,
 358 in order to display the associated
 359 .B groff
 360 version information, before exiting.
 361 .
 362 .\" --------------------------------------------------------------------
 363 .
 364 .SH ENVIRONMENT
 365 The following environment variables may be set, and exported,
 366 to modify the behaviour of
 367 .BR pdfroff .
 368 .TP
 369 .B GROFF_TMPDIR
 370 Identifies the directory in which
 371 .B pdfroff
 372 should create temporary files.
 373 If
 374 .B GROFF_TMPDIR
 375 is
 376 .I not
 377 specified, then the variables
 378 .BR TMPDIR ,
 379 .B TMP
 380 and
 381 .B TEMP
 382 are considered in turn, as possible temporary file repositories.
 383 If none of these are set, then temporary files will be created
 384 in the current directory.
 385 .TP
 386 .B GROFF_GHOSTSCRIPT_INTERPRETER
 387 Specifies the program to be invoked, when
 388 .B pdfroff
 389 converts
 390 .B groff
 391 PostScript output to PDF.
 392 If
 393 .B GROFF_GHOSTSCRIPT_INTERPRETER
 394 is not specified, then
 395 .B pdfroff
 396 will search the process
 397 .BR PATH ,
 398 looking for a program with any of the well known names
 399 for the GhostScript interpreter;
 400 if no GhostScript interpreter can be found,
 401 .B pdfroff
 402 will abort.
 403 .TP
 404 .B GROFF_AWK_INTERPRETER
 405 Specifies the program to be invoked, when
 406 .B pdfroff
 407 is extracting reference dictionary entries from a
 408 .B groff
 409 intermediate message stream.
 410 If
 411 .B GROFF_AWK_INTERPRETER
 412 is not specified, then
 413 .B pdfroff
 414 will search the process
 415 .BR PATH ,
 416 looking for any of the preferred programs, `gawk', `mawk', `nawk'
 417 and `awk', in this order;
 418 if none of these are found,
 419 .B pdfroff
 420 will issue a warning message, and continue processing;
 421 however, in this case, no reference dictionary will be created.
 422 .TP
 423 .B OSTYPE
 424 Typically defined automatically by the operating system,
 425 .B OSTYPE
 426 is used on Microsoft Win32/MS\(hyDOS platforms
 427 .IR only ,
 428 to infer the default
 429 .B PATH_SEPARATOR
 430 character,
 431 which is used when parsing the process
 432 .B PATH
 433 to search for external helper programs.
 434 .TP
 435 .B PATH_SEPARATOR
 436 If set,
 437 .B PATH_SEPARATOR
 438 overrides the default separator character,
 439 (':' on POSIX/UNIX systems,
 440 inferred from
 441 .B OSTYPE
 442 on Microsoft Win32/MS\(hyDOS),
 443 which is used when parsing the process
 444 .B PATH
 445 to search for external helper programs.
 446 .TP
 447 .B SHOW_PROGRESS
 448 If this is set to a non-empty value, then
 449 .B pdfroff
 450 will always behave as if the
 451 .B \-\-report\-progress
 452 option is specified, on the command line.
 453 .
 454 .\" --------------------------------------------------------------------
 455 .
 456 .SH FILES
 457 Input and output files for
 458 .B pdfroff
 459 may be named according to any convention of the user's choice.
 460 Typically, input files may be named according to the choice of the
 461 principal formatting macro package, e.g.,
 462 .IB file .ms
 463 might be an input file for formatting using the
 464 .B ms
 465 macros
 466 .RB ( s.tmac );
 467 normally, the final output file should be named
 468 .IB file .pdf\c
 469 \&.
 470 .P
 471 Temporary files, created by
 472 .BR pdfroff ,
 473 are placed in the directory specified by environment variables (see
 474 section
 475 .BR ENVIRONMENT ),
 476 and named according to the convention
 477 .BI pdf $$ .*\c
 478 \&, where
 479 .I $$
 480 is the standard shell variable representing the process ID of the
 481 .B pdfroff
 482 process itself, and
 483 .I *
 484 represents any of a number of extensions used by
 485 .B pdfroff
 486 for temporary and intermediate files.
 487 .
 488 .\" --------------------------------------------------------------------
 489 .
 490 .SH SEE ALSO
 491 See
 492 .BR groff (@MAN1EXT@)
 493 for the definitive reference to document formatting with
 494 .BR groff .
 495 Since
 496 .B pdfroff
 497 provides a superset of all
 498 .B groff
 499 capabilities,
 500 .BR groff (@MAN1EXT@)
 501 may also be considered to be the definitive reference to all
 502 .I standard
 503 capabilities of
 504 .BR pdfroff ,
 505 with this document providing the reference to
 506 .BR pdfroff 's
 507 extended features.
 508 .P
 509 While
 510 .B pdfroff
 511 imposes neither any restriction on, nor any requirement for,
 512 the use of any specific
 513 .B groff
 514 macro package, a number of supplied macro packages,
 515 and in particular those associated with the package
 516 .BR pdfmark.tmac ,
 517 are best suited for use with
 518 .BR pdfroff
 519 as the preferred formatter.
 520 Detailed documentation on the use of these packages may be found,
 521 in PDF format, in the reference guide
 522 .BR "\*(lqPortable Document Format Publishing with GNU Troff\*(rq" ,
 523 included in the installed documentation set as
 524 .hy 0
 525 .BR @PDFDOCDIR@/pdfmark.pdf .
 526 .hy
 527 .
 528 .\" --------------------------------------------------------------------
 529 .
 530 .SH AUTHOR
 531 Copyright \(co 2005, Free Software Foundation, Inc.
 532 .LP
 533 This man page is distributed under the terms of the
 534 GNU Free Documentation License (FDL), version 1.1 or later,
 535 and is part of the
 536 .I GNU troff
 537 software package.
 538 It was originally written by Keith Marshall,
 539 .nohy <keith.d.marshall@ntlworld.com>,
 540 who also wrote the implementation of the
 541 .I pdfroff
 542 program, to which it relates.
 543 .LP
 544 You should have received a copy of the FDL as part of the
 545 .I GNU troff
 546 distribution; it is also available on\-line, at the GNU
 547 .Q copyleft
 548 site,
 549 .nohy <http://www.gnu.org/copyleft/fdl.html>.
 550 .
 551 .\" --------------------------------------------------------------------
 552 .\" EOF / vim: ft=groff