src/roff/troff/troff.man

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