man/src-troff.1.in

   1 '\" t -- preprocess: tbl(1)
   2 .ig
   3 @ @L_TROFF@.1
   4
   5 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
   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 .TE
 319 .
 320 .P
 321 .nr x \w'\fBright-brace'+1n+\w'00000'u
 322 .ta \nxuR
 323 .
 324 .TP \nxu+3n
 325 .BR break "\t4"
 326 In fill mode, lines which could not be broken so that their length was
 327 less than the line length.
 328 This is enabled by default.
 329 .
 330 .TP
 331 .BR char "\t1"
 332 Non-existent characters.
 333 This is enabled by default.
 334 .
 335 .TP
 336 .BR color "\t524288"
 337 Color related warnings.
 338 .
 339 .TP
 340 .BR delim "\t8"
 341 Missing or mismatched closing delimiters.
 342 .
 343 .TP
 344 .BR di "\t256"
 345 Use of
 346 .B di
 347 or
 348 .B da
 349 without an argument when there is no current diversion.
 350 .
 351 .TP
 352 .BR el "\t16"
 353 Use of the
 354 .B el
 355 request with no matching
 356 .B ie
 357 request.
 358 .
 359 .TP
 360 .BR escape "\t32768"
 361 Unrecognized escape sequences.
 362 When an unrecognized escape sequence is encountered, the escape
 363 character is ignored.
 364 .
 365 .TP
 366 .BR font "\t131072"
 367 Non-existent fonts.
 368 This is enabled by default.
 369 .
 370 .TP
 371 .BR ig "\t262144"
 372 Invalid escapes in text ignored with the
 373 .B ig
 374 request.
 375 These are conditions that are errors when they do not occur in ignored
 376 text.
 377 .
 378 .TP
 379 .BR input "\t16384"
 380 Invalid input characters.
 381 .
 382 .TP
 383 .BR mac "\t512"
 384 Use of undefined strings, macros and diversions.
 385 When an undefined string, macro or diversion is used, that string is
 386 automatically defined as empty.
 387 So, in most cases, at most one warning will be given for each name.
 388 .
 389 .TP
 390 .BR missing "\t8192"
 391 Requests that are missing non-optional arguments.
 392 .
 393 .TP
 394 .BR number "\t2"
 395 Invalid numeric expressions.
 396 This is enabled by default.
 397 .
 398 .TP
 399 .BR range "\t64"
 400 Out of range arguments.
 401 .
 402 .TP
 403 .BR reg "\t1024"
 404 Use of undefined number registers.
 405 When an undefined number register is used, that register is
 406 automatically defined to have a value of\~0.
 407 So, in most cases, at most one warning will be given for use of a
 408 particular name.
 409 .
 410 .TP
 411 .BR right-brace "\t4096"
 412 Use of
 413 .B \[rs]}
 414 where a number was expected.
 415 .
 416 .TP
 417 .BR scale "\t32"
 418 Meaningless scaling indicators.
 419 .
 420 .TP
 421 .BR space "\t65536"
 422 Missing space between a request or macro and its argument.
 423 This warning will be given when an undefined name longer than two
 424 characters is encountered, and the first two characters of the name
 425 make a defined name.
 426 The request or macro will not be invoked.
 427 When this warning is given, no macro is automatically defined.
 428 This is enabled by default.
 429 This warning will never occur in compatibility mode.
 430 .
 431 .TP
 432 .BR syntax "\t128"
 433 Dubious syntax in numeric expressions.
 434 .
 435 .TP
 436 .BR tab "\t2048"
 437 Inappropriate use of a tab character.
 438 Either use of a tab character where a number was expected, or use of tab
 439 character in an unquoted macro argument.
 440 .
 441 .P
 442 There are also names that can be used to refer to groups of warnings:
 443 .
 444 .TP
 445 .B all
 446 All warnings except
 447 .BR di ,
 448 .BR mac ,
 449 and
 450 .BR reg .
 451 It is intended that this covers all warnings that are useful with
 452 traditional macro packages.
 453 .
 454 .TP
 455 .B w
 456 All warnings.
 457 .
 458 .\"
 459 .SH ENVIRONMENT
 460 .
 461 .TP
 462 .SM
 463 .B @U_ROFF@_TMAC_PATH
 464 A colon separated list of directories in which to search for
 465 macro files.
 466 .B @L_TROFF@
 467 will scan directories given in the
 468 .B \-M
 469 option before these, and in standard directories (current directory if
 470 in unsafe mode, home directory,
 471 .BR @SYSTEMMACRODIR@ ,
 472 .BR @LOCALMACRODIR@ ,
 473 .BR @MACRODIR@ )
 474 after these.
 475 .
 476 .TP
 477 .SM
 478 .B @U_ROFF@_TYPESETTER
 479 Default device.
 480 .
 481 .TP
 482 .SM
 483 .B @U_ROFF@_FONT_PATH
 484 A colon separated list of directories in which to search for the
 485 .BI dev name
 486 directory.
 487 .B @L_TROFF@
 488 will scan directories given in the
 489 .B \-F
 490 option before these, and in standard directories
 491 .RB ( @LOCALFONTDIR@ ,
 492 .BR @FONTDIR@ )
 493 after these.
 494 .
 495 .\"
 496 .SH FILES
 497 .
 498 .TP
 499 .B @MACRODIR@/troffrc
 500 Initialization file (called before any other macro package).
 501 .
 502 .TP
 503 .B @MACRODIR@/troffrc-end
 504 Initialization file (called after any other macro package).
 505 .
 506 .TP
 507 .BI @MACRODIR@/ name .tmac
 508 .TQ
 509 .BI @MACRODIR@/tmac. name
 510 Macro files
 511 .
 512 .TP
 513 .BI @FONTDIR@/dev name /DESC
 514 Device description file for device
 515 .IR name .
 516 .
 517 .TP
 518 .BI @FONTDIR@/dev name / F
 519 Font file for font
 520 .I F
 521 of device
 522 .IR name .
 523 .
 524 .P
 525 Note that
 526 .B troffrc
 527 and
 528 .B troffrc-end
 529 are neither searched in the current nor in the home directory by
 530 default for security reasons (even if the
 531 .B \-U
 532 option is given).
 533 Use the
 534 .B \-M
 535 command line option or the
 536 .B @U_ROFF@_TMAC_PATH
 537 environment variable to add these directories to the search path if
 538 necessary.
 539 .
 540 .\"
 541 .SH AUTHOR
 542 .
 543 Copyright (C) 1989, 2001 - 2003, 2007, 2008
 544 Free Software Foundation, Inc.
 545 .
 546 .P
 547 This document is distributed under the terms of the FDL (GNU Free
 548 Documentation License) version 1.1 or later.
 549 .
 550 You should have received a copy of the FDL on your system, it is also
 551 available on-line at the
 552 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
 553 GNU copyleft site
 554 .UE .
 555 This document was written by James Clark, with modifications from
 556 .MT wl@gnu.org
 557 Werner Lemberg
 558 .ME
 559 and
 560 .MT bwarken@mayn.de
 561 Bernd Warken
 562 .ME .
 563 .
 564 .\"
 565 .SH "SEE ALSO"
 566 .
 567 .TP
 568 .BR @L_ROFF@ (@MAN1EXT@)
 569 The main program of the
 570 .I @T_ROFF@
 571 system, a wrapper around
 572 .IR @L_TROFF@ .
 573 .
 574 .TP
 575 .BR @L_ROFF@ (@MAN7EXT@)
 576 A description of the roff language, including a short but complete
 577 reference of all predefined requests, registers, and escapes.
 578 .
 579 .TP
 580 .BR \%@L_ROFF@_diff (@MAN7EXT@)
 581 The differences of the
 582 .I @T_ROFF@
 583 language, GNU troff and the
 584 .I classical troff
 585 language.
 586 .
 587 .TP
 588 .BR roff (@MAN7EXT@)
 589 An overview over roff.
 590 .
 591 .\" s-it2-mode