src/roff/troff/troff.1.man

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