/contrib/groff/src/roff/troff/troff.man

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 705 lines · 698 code · 7 blank · 0 comment · 0 complexity · d09e3bf3f400e272235c8dc2cb46c999 MD5 · raw file

  1. '\" t
  2. .ig
  3. troff.man
  4. Last update : 12 Oct 2003
  5. This file is part of groff, the GNU roff type-setting system.
  6. Copyright (C) 1989, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
  7. written by James Clark
  8. modified by Werner Lemberg <wl@gnu.org>
  9. Bernd Warken <bwarken@mayn.de>
  10. Permission is granted to copy, distribute and/or modify this document
  11. under the terms of the GNU Free Documentation License, Version 1.1 or
  12. any later version published by the Free Software Foundation; with the
  13. Invariant Sections being this .ig-section and AUTHOR, with no
  14. Front-Cover Texts, and with no Back-Cover Texts.
  15. A copy of the Free Documentation License is included as a file called
  16. FDL in the main directory of the groff source package.
  17. ..
  18. .
  19. .
  20. .\" --------------------------------------------------------------------
  21. .\" Setup
  22. .\" --------------------------------------------------------------------
  23. .
  24. .do nr troff_C \n[.C]
  25. .cp 0
  26. .
  27. .mso www.tmac
  28. .
  29. .if n \{\
  30. . mso tty-char.tmac
  31. . ftr CR R
  32. . ftr CI I
  33. . ftr CB B
  34. .\}
  35. .
  36. .if '\*[.T]'dvi' \
  37. . ftr CB CW
  38. .
  39. .de TQ
  40. .br
  41. .ns
  42. .TP \\$1
  43. ..
  44. .
  45. .\" Like TP, but if specified indent is more than half
  46. .\" the current line-length - indent, use the default indent.
  47. .de Tp
  48. .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
  49. .el .TP "\\$1"
  50. ..
  51. .
  52. .
  53. .\" --------------------------------------------------------------------
  54. .\" Title
  55. .\" --------------------------------------------------------------------
  56. .
  57. .TH @G@TROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
  58. .SH NAME
  59. @g@troff \- the troff processor of the groff text formatting system
  60. .
  61. .
  62. .\" --------------------------------------------------------------------
  63. .SH SYNOPSIS
  64. .\" --------------------------------------------------------------------
  65. .
  66. .nr a \n(.j
  67. .ad l
  68. .nr i \n(.i
  69. .in +\w'\fB@g@troff 'u
  70. .ti \niu
  71. .B @g@troff
  72. .de OP
  73. .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
  74. .el .RB "[\ " "\\$1" "\ ]"
  75. ..
  76. .OP \-abcivzCERU
  77. .OP \-d cs
  78. .OP \-f fam
  79. .OP \-F dir
  80. .OP \-I dir
  81. .OP \-m name
  82. .OP \-M dir
  83. .OP \-n num
  84. .OP \-o list
  85. .OP \-r cn
  86. .OP \-T name
  87. .OP \-w name
  88. .OP \-W name
  89. .RI "[\ " files\|.\|.\|. "\ ]"
  90. .br
  91. .ad \na
  92. .P
  93. It is possible to have whitespace between a command line option and
  94. its parameter.
  95. .
  96. .
  97. .\" --------------------------------------------------------------------
  98. .SH DESCRIPTION
  99. .\" --------------------------------------------------------------------
  100. .
  101. This manual page describes the GNU version of
  102. .BR troff .
  103. It is part of the groff document formatting system.
  104. .
  105. It is functionally compatible with UNIX troff, but has many extensions,
  106. see
  107. .BR \%groff_diff (@MAN7EXT@).
  108. Usually it should be invoked using the
  109. .BR groff (@MAN1EXT@)
  110. command which will also run preprocessors and postprocessors in the
  111. appropriate order and with the appropriate options.
  112. .
  113. .
  114. .\" --------------------------------------------------------------------
  115. .SH OPTIONS
  116. .\" --------------------------------------------------------------------
  117. .
  118. .TP \w'\-dname=s'u+2n
  119. .B \-a
  120. Generate an
  121. .SM ASCII
  122. approximation of the typeset output.
  123. .
  124. .TP
  125. .B \-b
  126. Print a backtrace with each warning or error message.
  127. .
  128. This backtrace should help track down the cause of the error.
  129. .
  130. The line numbers given in the backtrace may not always be correct, for
  131. .BR @g@troff 's
  132. idea of line numbers gets confused by
  133. .B as
  134. or
  135. .B am
  136. requests.
  137. .
  138. .TP
  139. .B \-c
  140. Disable color output (always disabled in compatibility mode).
  141. .
  142. .TP
  143. .B \-C
  144. Enable compatibility mode.
  145. .
  146. .TP
  147. .BI \-d cs
  148. .TQ
  149. .BI \-d name = s
  150. Define
  151. .I c
  152. or
  153. .I name
  154. to be a string
  155. .IR s ;
  156. .I c
  157. must be a one letter name.
  158. .
  159. .TP
  160. .B \-E
  161. Inhibit all error messages of
  162. .BR @g@troff .
  163. Note that this doesn't affect messages output to standard error by macro
  164. packages using the
  165. .B tm
  166. or
  167. .B tm1
  168. requests.
  169. .
  170. .TP
  171. .BI \-f fam
  172. Use
  173. .I fam
  174. as the default font family.
  175. .
  176. .TP
  177. .BI \-F dir
  178. Search in directory (or directory path)
  179. .I dir
  180. for subdirectories
  181. .BI dev name
  182. .RI ( name
  183. is the name of the device) and there for the
  184. .B DESC
  185. file and font files.
  186. .I dir
  187. is scanned before all other font directories.
  188. .
  189. .TP
  190. .B \-i
  191. Read the standard input after all the named input files have been
  192. processed.
  193. .
  194. .TP
  195. .BI \-I dir
  196. This option may be used to specify a directory to search for
  197. files (both those on the command line and those named in
  198. .B \&.psbb
  199. requests).
  200. The current directory is always searched first.
  201. This option may be specified more than once;
  202. the directories will be searched in the order specified.
  203. No directory search is performed for files specified using an absolute path.
  204. .
  205. .TP
  206. .BI \-m name
  207. Read in the file
  208. .IB name .tmac\fR.
  209. If it isn't found, try
  210. .BI tmac. name
  211. instead.
  212. .
  213. It will be first searched for in directories given with the
  214. .B \-M
  215. command line option, then in directories given in the
  216. .B GROFF_TMAC_PATH
  217. environment variable, then in the current directory (only if in unsafe
  218. mode), the home directory, @SYSTEMMACRODIR@, @LOCALMACRODIR@, and
  219. @MACRODIR@.
  220. .
  221. .TP
  222. .BI \-M dir
  223. Search directory (or directory path)
  224. .I dir
  225. for macro files.
  226. .
  227. This is scanned before all other macro directories.
  228. .
  229. .TP
  230. .BI \-n num
  231. Number the first page
  232. .IR num .
  233. .
  234. .TP
  235. .BI \-o list
  236. Output only pages in
  237. .IR list ,
  238. which is a comma-separated list of page ranges;
  239. .I n
  240. means print page
  241. .IR n ,
  242. .IB m \- n
  243. means print every page between
  244. .I m
  245. and
  246. .IR n ,
  247. .BI \- n
  248. means print every page up to
  249. .IR n ,
  250. .IB n \-
  251. means print every page from
  252. .IR n .
  253. .B @g@troff
  254. will exit after printing the last page in the list.
  255. .
  256. .TP
  257. .BI \-r cn
  258. .TQ
  259. .BI \-r name = n
  260. Set number register
  261. .I c
  262. or
  263. .I name
  264. to
  265. .IR n ;
  266. .I c
  267. must be a one character name;
  268. .I n
  269. can be any troff numeric expression.
  270. .
  271. .TP
  272. .B \-R
  273. Don't load
  274. .B troffrc
  275. and
  276. .BR troffrc-end .
  277. .
  278. .TP
  279. .BI \-T name
  280. Prepare output for device
  281. .IR name ,
  282. rather than the default
  283. .BR @DEVICE@ ;
  284. see
  285. .BR groff (@MAN1EXT@)
  286. for a more detailed description.
  287. .
  288. .TP
  289. .B \-U
  290. Unsafe mode.
  291. .
  292. This will enable the following requests:
  293. .BR open ,
  294. .BR opena ,
  295. .BR pso ,
  296. .BR sy ,
  297. and
  298. .BR pi .
  299. For security reasons, these potentially dangerous requests are disabled
  300. otherwise.
  301. .
  302. It will also add the current directory to the macro search path.
  303. .
  304. .TP
  305. .B \-v
  306. Print the version number.
  307. .
  308. .TP
  309. .BI \-w name
  310. Enable warning
  311. .IR name .
  312. Available warnings are described in the section
  313. .I WARNINGS
  314. below.
  315. .
  316. For example, to enable all warnings, use
  317. .B \-w
  318. .BR all .
  319. Multiple
  320. .B \-w
  321. options are allowed.
  322. .
  323. .TP
  324. .BI \-W name
  325. Inhibit warning
  326. .IR name .
  327. Multiple
  328. .B \-W
  329. options are allowed.
  330. .
  331. .TP
  332. .B \-z
  333. Suppress formatted output.
  334. .
  335. .
  336. .\" --------------------------------------------------------------------
  337. .SH WARNINGS
  338. .\" --------------------------------------------------------------------
  339. .
  340. The warnings that can be given by
  341. .B @g@troff
  342. are divided into the following categories.
  343. .
  344. The name associated with each warning is used by the
  345. .B \-w
  346. and
  347. .B \-W
  348. options; the number is used by the
  349. .B warn
  350. request, and by the
  351. .B .warn
  352. register; it is always a power of 2 to allow bitwise composition.
  353. .
  354. .P
  355. .TS
  356. tab(@), center, box;
  357. c c c | c c c
  358. r rI lB | r rI lB.
  359. Bit@Code@Warning@Bit@Code@Warning
  360. _
  361. 0@1@char@10@1024@reg
  362. 1@2@number@11@2048@tab
  363. 2@4@break@12@4096@right-brace
  364. 3@8@delim@13@8192@missing
  365. 4@16@el@14@16384@input
  366. 5@32@scale@15@32768@escape
  367. 6@64@range@16@65536@space
  368. 7@128@syntax@17@131072@font
  369. 8@256@di@18@262144@ig
  370. 9@512@mac@19@524288@color
  371. .TE
  372. .
  373. .P
  374. .nr x \w'\fBright-brace'+1n+\w'00000'u
  375. .ta \nxuR
  376. .
  377. .TP \nxu+3n
  378. .BR break "\t4"
  379. In fill mode, lines which could not be broken so that their length was
  380. less than the line length.
  381. .
  382. This is enabled by default.
  383. .
  384. .TP
  385. .BR char "\t1"
  386. Non-existent characters.
  387. .
  388. This is enabled by default.
  389. .
  390. .TP
  391. .BR color "\t524288"
  392. Color related warnings.
  393. .
  394. .TP
  395. .BR delim "\t8"
  396. Missing or mismatched closing delimiters.
  397. .
  398. .TP
  399. .BR di "\t256"
  400. Use of
  401. .B di
  402. or
  403. .B da
  404. without an argument when there is no current diversion.
  405. .
  406. .TP
  407. .BR el "\t16"
  408. Use of the
  409. .B el
  410. request with no matching
  411. .B ie
  412. request.
  413. .
  414. .TP
  415. .BR escape "\t32768"
  416. Unrecognized escape sequences.
  417. .
  418. When an unrecognized escape sequence is encountered, the escape
  419. character is ignored.
  420. .
  421. .TP
  422. .BR font "\t131072"
  423. Non-existent fonts.
  424. .
  425. This is enabled by default.
  426. .
  427. .TP
  428. .BR ig "\t262144"
  429. Invalid escapes in text ignored with the
  430. .B ig
  431. request.
  432. .
  433. These are conditions that are errors when they do not occur in ignored
  434. text.
  435. .
  436. .TP
  437. .BR input "\t16384"
  438. Invalid input characters.
  439. .
  440. .TP
  441. .BR mac "\t512"
  442. Use of undefined strings, macros and diversions.
  443. .
  444. When an undefined string, macro or diversion is used, that string is
  445. automatically defined as empty.
  446. .
  447. So, in most cases, at most one warning will be given for each name.
  448. .
  449. .TP
  450. .BR missing "\t8192"
  451. Requests that are missing non-optional arguments.
  452. .
  453. .TP
  454. .BR number "\t2"
  455. Invalid numeric expressions.
  456. .
  457. This is enabled by default.
  458. .
  459. .TP
  460. .BR range "\t64"
  461. Out of range arguments.
  462. .
  463. .TP
  464. .BR reg "\t1024"
  465. Use of undefined number registers.
  466. .
  467. When an undefined number register is used, that register is
  468. automatically defined to have a value of\~0.
  469. .
  470. So, in most cases, at most one warning will be given for use of a
  471. particular name.
  472. .
  473. .TP
  474. .BR right-brace "\t4096"
  475. Use of
  476. .B \[rs]}
  477. where a number was expected.
  478. .
  479. .TP
  480. .BR scale "\t32"
  481. Meaningless scaling indicators.
  482. .
  483. .TP
  484. .BR space "\t65536"
  485. Missing space between a request or macro and its argument.
  486. .
  487. This warning will be given when an undefined name longer than two
  488. characters is encountered, and the first two characters of the name
  489. make a defined name.
  490. .
  491. The request or macro will not be invoked.
  492. .
  493. When this warning is given, no macro is automatically defined.
  494. .
  495. This is enabled by default.
  496. .
  497. This warning will never occur in compatibility mode.
  498. .
  499. .TP
  500. .BR syntax "\t128"
  501. Dubious syntax in numeric expressions.
  502. .
  503. .TP
  504. .BR tab "\t2048"
  505. Inappropriate use of a tab character.
  506. Either use of a tab character where a number was expected, or use of tab
  507. character in an unquoted macro argument.
  508. .
  509. .P
  510. There are also names that can be used to refer to groups of warnings:
  511. .
  512. .TP
  513. .B all
  514. All warnings except
  515. .BR di ,
  516. .BR mac ,
  517. and
  518. .BR reg .
  519. It is intended that this covers all warnings that are useful with
  520. traditional macro packages.
  521. .
  522. .TP
  523. .B w
  524. All warnings.
  525. .
  526. .
  527. .\" --------------------------------------------------------------------
  528. .SH ENVIRONMENT
  529. .\" --------------------------------------------------------------------
  530. .
  531. .TP
  532. .SM
  533. .B GROFF_TMAC_PATH
  534. A colon separated list of directories in which to search for
  535. macro files.
  536. .B @g@troff
  537. will scan directories given in the
  538. .B \-M
  539. option before these, and in standard directories (current directory if
  540. in unsafe mode, home directory,
  541. .BR @SYSTEMMACRODIR@ ,
  542. .BR @LOCALMACRODIR@ ,
  543. .BR @MACRODIR@ )
  544. after these.
  545. .
  546. .TP
  547. .SM
  548. .B GROFF_TYPESETTER
  549. Default device.
  550. .
  551. .TP
  552. .SM
  553. .B GROFF_FONT_PATH
  554. A colon separated list of directories in which to search for the
  555. .BI dev name
  556. directory.
  557. .B @g@troff
  558. will scan directories given in the
  559. .B \-F
  560. option before these, and in standard directories
  561. .RB ( @LOCALFONTDIR@ ,
  562. .BR @FONTDIR@ ,
  563. .BR @LEGACYFONTDIR@ )
  564. after these.
  565. .
  566. .
  567. .\" --------------------------------------------------------------------
  568. .SH FILES
  569. .\" --------------------------------------------------------------------
  570. .
  571. .Tp \w'@FONTDIR@/devname/DESC'u+3n
  572. .B @MACRODIR@/troffrc
  573. Initialization file (called before any other macro package).
  574. .
  575. .TP
  576. .B @MACRODIR@/troffrc-end
  577. Initialization file (called after any other macro package).
  578. .
  579. .TP
  580. .BI @MACRODIR@/ name .tmac
  581. .TQ
  582. .BI @MACRODIR@/tmac. name
  583. Macro files
  584. .
  585. .TP
  586. .BI @FONTDIR@/dev name /DESC
  587. Device description file for device
  588. .IR name .
  589. .
  590. .TP
  591. .BI @FONTDIR@/dev name / F
  592. Font file for font
  593. .I F
  594. of device
  595. .IR name .
  596. .P
  597. Note that
  598. .B troffrc
  599. and
  600. .B troffrc-end
  601. are neither searched in the current nor in the home directory by
  602. default for security reasons (even if the
  603. .B \-U
  604. option is given).
  605. .
  606. Use the
  607. .B \-M
  608. command line option or the
  609. .B GROFF_TMAC_PATH
  610. environment variable to add these directories to the search path if
  611. necessary.
  612. .
  613. .
  614. .\" --------------------------------------------------------------------
  615. .SH AUTHOR
  616. .\" --------------------------------------------------------------------
  617. .
  618. Copyright (C) 1989, 2001, 2002, 2003 Free Software Foundation, Inc.
  619. .
  620. .P
  621. This document is distributed under the terms of the FDL (GNU Free
  622. Documentation License) version 1.1 or later.
  623. .
  624. You should have received a copy of the FDL on your system, it is also
  625. available on-line at the
  626. .URL http://www.gnu.org/copyleft/fdl.html "GNU copyleft site" .
  627. This document was written by James Clark, with modifications from
  628. .MTO wl@gnu.org "Werner Lemberg"
  629. and
  630. .MTO bwarken@mayn.de "Bernd Warken"
  631. .
  632. .P
  633. This document is part of
  634. .IR groff ,
  635. the GNU roff distribution.
  636. .
  637. .
  638. .\" --------------------------------------------------------------------
  639. .SH "SEE ALSO"
  640. .\" --------------------------------------------------------------------
  641. .
  642. .TP
  643. .BR groff (@MAN1EXT@)
  644. The main program of the
  645. .I groff
  646. system, a wrapper around
  647. .IR @g@troff .
  648. .
  649. .TP
  650. .BR groff (@MAN7EXT@)
  651. A description of the
  652. .I groff
  653. language, including a short but complete reference of all predefined
  654. requests, registers, and escapes of plain
  655. .IR groff .
  656. From the command line, this is called by
  657. .RS
  658. .IP
  659. .B man 7 groff
  660. .RE
  661. .
  662. .TP
  663. .BR \%groff_diff (@MAN7EXT@)
  664. The differences of the
  665. .I groff
  666. language and the
  667. .I classical troff
  668. language.
  669. .
  670. Currently, this is the most actual document of the
  671. .I groff
  672. system.
  673. .
  674. .TP
  675. .BR roff (@MAN7EXT@)
  676. An overview over
  677. .I groff
  678. and other
  679. .I roff
  680. systems, including pointers to further related documentation.
  681. .
  682. .P
  683. The
  684. .I groff info
  685. .IR file ,
  686. cf.\&
  687. .BR info (@MAN1EXT@),
  688. presents all groff documentation within a single document.
  689. .
  690. .cp \n[troff_C]
  691. .
  692. .\" --------------------------------------------------------------------
  693. .\" Emacs variables
  694. .\" --------------------------------------------------------------------
  695. .
  696. .\" Local Variables:
  697. .\" mode: nroff
  698. .\" End: