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

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