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