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

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