man/src-troff.1.in

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