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

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