/contrib/groff/contrib/pdfmark/pdfroff.man

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