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