man/src-roff.1.in

   1 .ig
   2 @ @L_ROFF@.1
   3
   4 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
   5
   6 Copyright (C) 1989, 2002 - 2008
   7 Free Software Foundation, Inc.
   8 Rewritten in 2002 by Bernd Warken <bwarken@mayn.de>
   9
  10 Permission is granted to copy, distribute and/or modify this document
  11 under the terms of the GNU Free Documentation License, Version 1.1 or
  12 any later version published by the Free Software Foundation; with the
  13 Invariant Sections being this .ig-section and AUTHOR, with no
  14 Front-Cover Texts, and with no Back-Cover Texts.
  15
  16 You should have received a copy of the Free Documentation License
  17 as part of the file COPYING; also located in the main directory of the
  18 source package of this program.
  19 ..
  20 .
  21 .
  22 .\" Environment variable
  23 .de EnvVar
  24 .  SM
  25 .  BR \%\\$1 \\$2
  26 ..
  27 .\" `char or string'
  28 .de Quoted
  29 .  ft CR
  30 \[oq]\\$*\[cq]
  31 .  ft
  32 ..
  33 .
  34 .TH @U_ROFF@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
  35 .
  36 .\"
  37 .SH NAME
  38 @L_ROFF@ \- front-end for the @T_ROFF@ document formatting system
  39 .
  40 .\"
  41 .SH SYNOPSIS
  42 .
  43 .SY @L_ROFF@
  44 .OP \-abcegiklpstzCEGNRSUVZ
  45 .OP \-d cs
  46 .OP \-D arg
  47 .OP \-f fam
  48 .OP \-F dir
  49 .OP \-I dir
  50 .OP \-K arg
  51 .OP \-L arg
  52 .OP \-m name
  53 .OP \-M dir
  54 .OP \-n num
  55 .OP \-o list
  56 .OP \-P arg
  57 .OP \-r cn
  58 .OP \-T dev
  59 .OP \-w name
  60 .OP \-W name
  61 .RI [ file\~ .\|.\|.]
  62 .
  63 .SY @L_ROFF@
  64 .B \-h
  65 |
  66 .B \-\-help
  67 .
  68 .SY @L_ROFF@
  69 .B \-v
  70 |
  71 .B \-\-version
  72 .RI [ option\~ .\|.\|.]
  73 .YS
  74 .
  75 .\"
  76 .SH DESCRIPTION
  77 .
  78 This document describes the
  79 .B @L_ROFF@
  80 program, the main front-end for the
  81 .I @T_ROFF@
  82 document formatting system, which is a
  83 .BR roff (@MAN7EXT@)
  84 implementation that has all features of the classical
  85 .IR roff ,
  86 but also adds extensions.
  87 .
  88 .P
  89 The
  90 .B @L_ROFF@
  91 program allows to control the whole
  92 .I @T_ROFF@
  93 system by command line options.
  94 .
  95 .\"
  96 .SH OPTIONS
  97 .
  98 Whitespace between a command line option and its argument is
  99 optional.
 100 .
 101 Options can be grouped behind a single `\-' (minus character).
 102 .
 103 A filename of
 104 .B \-
 105 (minus character) denotes the standard input.
 106 .
 107 .\"
 108 .SS Native @L_ROFF@ Options
 109 .
 110 The following options either do not exist for
 111 .B @L_TROFF@
 112 or are differently interpreted by
 113 .BR @L_ROFF@ .
 114 .
 115 .TP
 116 .BI \-D\  arg
 117 Set default input encoding used by
 118 .B @L_P_PRECONV@
 119 to
 120 .IR arg .
 121 Implies
 122 .BR \-k .
 123 .
 124 .TP
 125 .B \-e
 126 Preprocess with
 127 .BR @L_P_EQN@ .
 128 .
 129 .TP
 130 .B \-g
 131 Preprocess with
 132 .BR @L_P_GRN@ .
 133 .
 134 .TP
 135 .B \-G
 136 Preprocess with
 137 .BR grap .
 138 .
 139 .TP
 140 .B \-h
 141 .TQ
 142 .B \-\-help
 143 Print a help message.
 144 .
 145 .TP
 146 .BI \-I\  dir
 147 This option may be used to specify a directory to search for
 148 files (both those on the command line and those named in
 149 .B .psbb
 150 and
 151 .B .so
 152 requests, and
 153 .B \eX'ps: import'
 154 and
 155 .B \eX'ps: file'
 156 escapes).
 157 The current directory is always searched first.
 158 This option may be specified more than once;
 159 the directories are searched in the order specified.
 160 No directory search is performed for files specified using an absolute path.
 161 This option implies the
 162 .B \-s
 163 option.
 164 .
 165 .TP
 166 .B \-k
 167 Preprocess with
 168 .BR @L_P_PRECONV@ .
 169 This is run before any other preprocessor.
 170 .
 171 Please refer to
 172 .BR @L_P_PRECONV@ 's
 173 manual page for its behaviour if no
 174 .B \-K
 175 (or
 176 .BR \-D )
 177 option is specified.
 178 .
 179 .TP
 180 .BI \-K\  arg
 181 Set input encoding used by
 182 .B @L_P_PRECONV@
 183 to
 184 .IR arg .
 185 Implies
 186 .BR \-k .
 187 .
 188 .TP
 189 .B \-l
 190 Send the output to a spooler program for printing.
 191 The command that should be used for this is specified by the
 192 .B print
 193 command in the device description file, see
 194 .BR \%@L_ROFF@_font (@MAN5EXT@).
 195 If this command is not present, the output is piped into the
 196 .BR lpr (1)
 197 program by default.
 198 See options
 199 .B \-L
 200 and
 201 .BR \-X .
 202 .
 203 .TP
 204 .BI \-L\  arg
 205 Pass
 206 .I arg
 207 to the spooler program.
 208 Several arguments should be passed with a separate
 209 -L
 210 option each.
 211 Note that
 212 .B @L_ROFF@
 213 does not prepend
 214 `-'
 215 (a minus sign) to
 216 .I arg
 217 before passing it to the spooler program.
 218 .
 219 .TP
 220 .B \-N
 221 Don't allow newlines within
 222 .I @L_P_EQN@
 223 delimiters.
 224 This is the same as the
 225 .B \-N
 226 option in
 227 .BR @L_P_EQN@ .
 228 .
 229 .TP
 230 .B \-p
 231 Preprocess with
 232 .BR @L_P_PIC@ .
 233 .
 234 .TP
 235 .BI \-P\  \-option
 236 .TQ
 237 .BI \-P\  \-option \ \-P\  arg
 238 Pass
 239 .I \-option
 240 or
 241 .I "\-option\~arg"
 242 to the postprocessor.
 243 The option must be specified with the necessary preceding minus
 244 sign(s)
 245 .Quoted -
 246 or
 247 .Quoted --
 248 because
 249 .B @L_ROFF@
 250 does not prepend any dashes before passing it to the postprocessor.
 251 .
 252 .TP
 253 .B \-R
 254 Preprocess with
 255 .BR @L_P_REFER@ .
 256 .
 257 No mechanism is provided for passing arguments to
 258 .B @L_P_REFER@
 259 because most
 260 .B @L_P_REFER@
 261 options have equivalent language elements that can be specified within
 262 the document.
 263 See
 264 .BR \%@L_P_REFER@ (@MAN1EXT@)
 265 for more details.
 266 .
 267 .TP
 268 .B \-s
 269 Preprocess with
 270 .BR @L_P_SOELIM@ .
 271 .
 272 .TP
 273 .B \-S
 274 Safer mode.
 275 Pass the
 276 .B \-S
 277 option to
 278 .B @L_P_PIC@
 279 and disable the following
 280 .B @L_TROFF@
 281 requests:
 282 .BR .open ,
 283 .BR .opena ,
 284 .BR .pso ,
 285 .BR .sy ,
 286 and
 287 .BR .pi .
 288 For security reasons, safer mode is enabled by default.
 289 .
 290 .TP
 291 .B \-t
 292 Preprocess with
 293 .BR @L_P_TBL@ .
 294 .
 295 .TP
 296 .BI \-T\  dev
 297 Set output device to
 298 .IR dev .
 299 For this device,
 300 .B @L_TROFF@
 301 generates the
 302 .I intermediate
 303 .IR output ;
 304 see
 305 .BR \%@L_ROFF@_out (@MAN5EXT@).
 306 Then
 307 .B @L_ROFF@
 308 calls a postprocessor to convert
 309 .BR @L_TROFF@ 's
 310 .I intermediate output
 311 to its final format.
 312 Real devices in
 313 .B @L_ROFF@
 314 are
 315 .
 316 .RS
 317 .RS
 318 .TP
 319 dvi
 320 TeX DVI format (postprocessor is
 321 .BR @L_D_DVI@ ).
 322 .
 323 .TP
 324 html
 325 .TQ
 326 xhtml
 327 HTML and XHTML output (preprocessors are
 328 .B @L_P_SOELIM@
 329 and
 330 .BR \%@L_D_PREHTML@ ,
 331 postprocessor is
 332 .BR \%@L_D_POSTHTML@ ).
 333 .
 334 .TP
 335 ps
 336 PostScript output (postprocessor is
 337 .BR @L_D_PS@ ).
 338 .RE
 339 .RE
 340 .
 341 .IP
 342 For the following TTY output devices (postprocessor is always
 343 .BR @L_D_TTY@ ),
 344 .B \-T
 345 selects the output encoding:
 346 .
 347 .RS
 348 .RS
 349 .TP
 350 ascii
 351 7bit \f[CR]ASCII\f[].
 352 .
 353 .TP
 354 cp1047
 355 \%Latin-1 character set for EBCDIC hosts.
 356 .
 357 .TP
 358 latin1
 359 ISO \%8859-1.
 360 .
 361 .TP
 362 utf8
 363 Unicode character set in \%UTF-8 encoding.
 364 .RE
 365 .RE
 366 .
 367 .IP
 368 The default device is
 369 .BR @DEVICE@ .
 370 .
 371 .TP
 372 .B \-U
 373 Unsafe mode.
 374 .
 375 Reverts to the (old) unsafe behaviour; see option
 376 .BR \-S .
 377 .
 378 .TP
 379 .B \-v
 380 .TQ
 381 .B \-\-version
 382 Output version information (of all programs that would be run by the
 383 specified pipeline).
 384 .
 385 .TP
 386 .B \-V
 387 Output the pipeline that would be run on the standard output, but do not
 388 execute it.
 389 If given more than once,
 390 the commands are both printed on the standard error and run.
 391 .
 392 .TP
 393 .B \-z
 394 Suppress output generated by
 395 .BR @L_TROFF@ .
 396 Only error messages are printed.
 397 .
 398 .TP
 399 .B \-Z
 400 Do not automatically postprocess intermediate output in the usual manner.
 401 This will cause
 402 .B @L_TROFF@
 403 output to appear on standard output,
 404 replacing the usual postprocessor output; see
 405 .BR \%@L_ROFF@_out (@MAN5EXT@).
 406 .
 407 .\"
 408 .SS Transparent Options
 409 .
 410 The following options are transparently handed over to the formatter
 411 program
 412 .B @L_TROFF@ .
 413 These options are described in more detail in
 414 .BR @L_TROFF@ (@MAN1EXT@).
 415 .
 416 .TP
 417 .B \-a
 418 \f[CR]ASCII\f[] approximation of output.
 419 .
 420 .TP
 421 .B \-b
 422 Backtrace on error or warning.
 423 .
 424 .TP
 425 .B \-c
 426 Disable color output.
 427 .
 428 Please consult the
 429 .BR \%@L_D_TTY@ (@MAN1EXT@)
 430 man page for more details.
 431 .
 432 .TP
 433 .B \-C
 434 Enable compatibility mode.
 435 .
 436 .TP
 437 .BI \-d\  cs
 438 .TQ
 439 .BI \-d\  name = s
 440 Define string.
 441 .
 442 .TP
 443 .B \-E
 444 Disable
 445 .B @L_TROFF@
 446 error messages.
 447 .
 448 .TP
 449 .BI \-f\  fam
 450 Set default font family.
 451 .
 452 .TP
 453 .BI \-F\  dir
 454 Set path for font DESC files.
 455 .
 456 .TP
 457 .B \-i
 458 Process standard input after the specified input files.
 459 .
 460 .TP
 461 .BI \-m\  name
 462 Include macro file
 463 .IB name .tmac
 464 (or
 465 .BI tmac. name\c
 466 ); see also
 467 .BR \%@L_ROFF@_tmac (@MAN5EXT@).
 468 .
 469 .TP
 470 .BI \-M\  dir
 471 Path for macro files.
 472 .
 473 .TP
 474 .BI \-n\  num
 475 Number the first page
 476 .IR num .
 477 .
 478 .TP
 479 .BI \-o\  list
 480 Output only pages in
 481 .IR list .
 482 .
 483 .TP
 484 .BI \-r\  cn
 485 .TQ
 486 .BI \-r\  name = n
 487 Set number register.
 488 .
 489 .TP
 490 .BI \-w\  name
 491 Enable warning
 492 .IR name .
 493 .
 494 .TP
 495 .BI \-W\  name
 496 disable warning
 497 .IR name .
 498 .
 499 .
 500 .\"
 501 .SH "USING @U_ROFF@"
 502 .
 503 The
 504 .I @T_ROFF@ system
 505 implements the infrastructure of classical roff; see
 506 .BR roff (@MAN7EXT@)
 507 for a survey on how a
 508 .I roff
 509 system works in general.
 510 @T_ROFF@ adds front-end programs and other facilities which make using
 511 it easier than
 512 .IR "classical roff"
 513 with its pipeline approach.
 514 This section gives an overview of those added parts and complements
 515 .BR roff (@MAN7EXT@).
 516 .
 517 .\"
 518 .SS Paper Size
 519 .
 520 The
 521 .I virtual
 522 paper size used by
 523 .B troff
 524 to format the input is controlled globally with the requests
 525 .BR .po ,
 526 .BR .pl ,
 527 and
 528 .BR .ll .
 529 See
 530 .BR @L_ROFF@_tmac (@MAN5EXT@)
 531 for the `papersize' macro package which provides a convenient interface.
 532 .
 533 .P
 534 The
 535 .I physical
 536 paper size, giving the actual dimensions of the paper sheets, is
 537 controlled by output devices like
 538 .BR @L_D_PS@
 539 with the command line options
 540 .B \-p
 541 and
 542 .BR \-l .
 543 See
 544 .BR @L_ROFF@_font (@MAN5EXT@)
 545 and the man pages of the output devices for more details.
 546 .B @L_ROFF@
 547 uses the command line option
 548 .B \-P
 549 to pass options to output devices; for example, the following selects
 550 A4 paper in landscape orientation for the PS device:
 551 .
 552 .IP
 553 .EX
 554 @L_ROFF@ -Tps -P-pa4 -P-l ...
 555 .EE
 556 .
 557 .\"
 558 .SS Front-ends
 559 .
 560 @L_ROFF@ allows to specify the preprocessors by command line options,
 561 and automatically runs the postprocessor that is appropriate for the
 562 selected device after processing the data with @L_TROFF@.
 563 @L_ROFF@ therefore acts as a replacement for the necessity to manually
 564 specify the processor pipeline as is required by classical
 565 .BR roff (@MAN7EXT@).
 566 .
 567 .\"
 568 .SS Preprocessors
 569 .
 570 The standard preprocessors distributed along with
 571 .I @T_ROFF@
 572 are
 573 .
 574 .TP
 575 .BR \%@L_P_EQN@ (@MAN1EXT@)
 576 for mathematical formul\(ae,
 577 .
 578 .TP
 579 .BR \%@L_P_GRN@ (@MAN1EXT@)
 580 for including
 581 .BR gremlin (1)
 582 pictures,
 583 .
 584 .TP
 585 .BR \%@L_P_PIC@ (@MAN1EXT@)
 586 for drawing diagrams,
 587 .
 588 .TP
 589 .BR \%@L_P_REFER@ (@MAN1EXT@)
 590 for bibliographic references,
 591 .
 592 .TP
 593 .BR \%@L_P_SOELIM@ (@MAN1EXT@)
 594 for including macro files from standard locations,
 595 .
 596 .TP
 597 .BR @L_P_TABLES (@MAN1EXT@)
 598 for tables.
 599 .
 600 .P
 601 A new preprocessor is
 602 .BR \%@L_P_PRECONV@ (@MAN1EXT@)
 603 which converts various input encodings to something
 604 .B @L_ROFF@
 605 can understand.
 606 It is always run first before any other preprocessor.
 607 .
 608 .\"
 609 .SS "Macro Packages"
 610 .
 611 Macro packages can be included by option
 612 .BR \-m .
 613 .
 614 The
 615 .I @T_ROFF@
 616 system implements and extends all classical macro packages in a
 617 compatible way and adds some packages of its own.
 618 .
 619 Actually, the following macro packages are included:
 620 .
 621 .TP
 622 .B man
 623 The traditional man page format; see
 624 .BR \%@L_ROFF@_man (@MAN7EXT@).
 625 It can be specified on the command line as
 626 .B \-man
 627 or
 628 .BR \-m\~man .
 629 .
 630 .TP
 631 .B mandoc
 632 The general package for man pages; it automatically recognizes
 633 whether the documents uses the
 634 .I man
 635 or the
 636 .I mdoc
 637 format and branches to the corresponding macro package.
 638 .
 639 It can be specified on the command line as
 640 .B \%\-mandoc
 641 or
 642 .BR \-m\~\%mandoc .
 643 .
 644 .TP
 645 .B mdoc
 646 The \f[CR]BSD\f[]-style man page format; see
 647 .BR \%@L_ROFF@_mdoc (@MAN7EXT@).
 648 It can be specified on the command line as
 649 .B \-mdoc
 650 or
 651 .BR \-m\~mdoc .
 652 .
 653 .TP
 654 .B me
 655 The classical
 656 .I me
 657 document format; see
 658 .BR \%@L_ROFF@_me (@MAN7EXT@).
 659 It can be specified on the command line as
 660 .B \-me
 661 or
 662 .BR \-m\~me .
 663 .
 664 .TP
 665 .B ms
 666 The classical
 667 .I ms
 668 document format; see
 669 .BR \%@L_ROFF@_ms (@MAN7EXT@).
 670 It can be specified on the command line as
 671 .B \-ms
 672 or
 673 .BR \-m\~ms .
 674 .
 675 .TP
 676 .B www
 677 HTML-like macros for inclusion in arbitrary
 678 .I groff
 679 documents; see
 680 .BR \%@L_ROFF@_www (@MAN7EXT@).
 681 .
 682 .P
 683 Details on the naming of macro files and their placement can be found
 684 in
 685 .BR \%@L_ROFF@_tmac (@MAN5EXT@);
 686 this man page also documents some other, minor auxiliary macro packages
 687 not mentioned here.
 688 .
 689 .\"
 690 .SS "Programming Language"
 691 .
 692 General concepts common to all
 693 .I roff
 694 programming languages are described in
 695 .BR roff (@MAN7EXT@).
 696 .
 697 .P
 698 The
 699 .I @T_ROFF@
 700 extensions to the classical
 701 .I troff
 702 language are documented in
 703 .BR \%@L_ROFF@_diff (@MAN7EXT@).
 704 In here you find also differences in between GNU troff and @T_ROFF@.
 705 .
 706 .P
 707 The
 708 .I @T_ROFF@
 709 language as a whole is described in
 710 .BR @L_ROFF@ (@MAN7EXT@).
 711 .
 712 .\"
 713 .SS Formatters
 714 .
 715 The central
 716 .I roff
 717 formatter within the
 718 .I @T_ROFF@
 719 system is
 720 .BR @L_TROFF@ (@MAN1EXT@).
 721 It provides the features of both the classical
 722 .I troff
 723 and
 724 .IR nroff ,
 725 as well as the
 726 .I @T_ROFF@
 727 extensions.
 728 .
 729 The command line option
 730 .B \-C
 731 switches
 732 .B @L_TROFF@
 733 into
 734 .I "compatibility mode"
 735 which tries to emulate classical
 736 .I roff
 737 as much as possible.
 738 .
 739 .P
 740 There is a shell script
 741 .BR @L_NROFF@ (@MAN1EXT@)
 742 that emulates the behavior of classical
 743 .BR nroff .
 744 It tries to automatically select the proper output encoding, according to
 745 the current locale.
 746 .
 747 .P
 748 The formatter program generates
 749 .IR "intermediate output" ;
 750 see
 751 .BR \%@L_ROFF@_out (@MAN7EXT@).
 752 .
 753 .\"
 754 .SS Devices
 755 .
 756 In
 757 .IR roff ,
 758 the output targets are called
 759 .IR devices .
 760 A device can be a piece of hardware, e.g., a printer, or a software
 761 file format.
 762 .
 763 A device is specified by the option
 764 .BR \-T .
 765 The following devices are included:
 766 .
 767 .TP
 768 .B ascii
 769 Text output using the
 770 .BR ascii (7)
 771 character set.
 772 .
 773 .TP
 774 .B cp1047
 775 Text output using the EBCDIC code page IBM cp1047 (e.g., OS/390 Unix).
 776 .
 777 .TP
 778 .B dvi
 779 TeX DVI format.
 780 .
 781 .TP
 782 .B html
 783 HTML output.
 784 .
 785 .TP
 786 .B latin1
 787 Text output using the ISO \%Latin-1 (ISO \%8859-1) character set; see
 788 .BR \%iso_8859_1 (7).
 789 .
 790 .TP
 791 .B ps
 792 PostScript output; suitable for printers and previewers like
 793 .BR gv (1).
 794 .
 795 .TP
 796 .B utf8
 797 Text output using the Unicode (ISO 10646) character set with \%UTF-8
 798 encoding; see
 799 .BR unicode (7).
 800 .
 801 .TP
 802 .B xhtml
 803 XHTML output.
 804 .
 805 .P
 806 The postprocessor to be used for a device is specified by the
 807 .B postpro
 808 command in the device description file; see
 809 .BR \%@L_ROFF@_font (@MAN5EXT@).
 810 .
 811 .P
 812 The default device is
 813 .BR @DEVICE@ .
 814 .
 815 .\"
 816 .SS Postprocessors
 817 .
 818 .I @L_ROFF@
 819 provides 3\~hardware postprocessors:
 820 .
 821 .TP
 822 .BR \%@L_D_TTY@ (@MAN1EXT@)
 823 for text output using various encodings, e.g., on text-oriented
 824 terminals or line-printers.
 825 .
 826 .P
 827 Today, most printing or drawing hardware is handled by the operating
 828 system, by device drivers, or by software interfaces, usually accepting
 829 PostScript.
 830 Consequently, there isn't an urgent need for more hardware device
 831 postprocessors.
 832 .
 833 .P
 834 The software devices for conversion into other document file formats are:
 835 .
 836 .TP
 837 .BR \%@L_D_DVI@ (@MAN1EXT@)
 838 for the DVI format,
 839 .
 840 .TP
 841 .BR \%@L_D_HTML@ (@MAN1EXT@)
 842 for HTML and XHTML formats,
 843 .
 844 .TP
 845 .BR \%@L_D_PS@ (@MAN1EXT@)
 846 for PostScript.
 847 .
 848 .P
 849 Combined with the many existing free conversion tools this should
 850 be sufficient to convert a
 851 .I troff
 852 document into virtually any existing data format.
 853 .
 854 .\"
 855 .SS Utilities
 856 .
 857 The following utility programs around are available:
 858 .
 859 .TP
 860 .BR \%@L_ADDFTINFO@ (@MAN1EXT@)
 861 Add information to
 862 .I troff
 863 font description files for use with
 864 .IR @T_ROFF@ .
 865 .
 866 .TP
 867 .BR \%@L_AFMTODIT@ (@MAN1EXT@)
 868 Create font description files for PostScript device.
 869 .
 870 .TP
 871 .BR \%@L_INDXBIB@ (@MAN1EXT@)
 872 Make inverted index for bibliographic databases.
 873 .
 874 .TP
 875 .BR \%@L_LKBIB@ (@MAN1EXT@)
 876 Search bibliographic databases.
 877 .
 878 .TP
 879 .BR \%@L_LOOKBIB@ (@MAN1EXT@)
 880 Interactively search bibliographic databases.
 881 .
 882 .TP
 883 .BR \%@L_PDFROFF@ (@MAN1EXT@)
 884 Create PDF documents.
 885 .
 886 .TP
 887 .BR \%@L_PFBTOPS@ (@MAN1EXT@)
 888 Translate a PostScript font in .pfb format to \f[CR]ASCII\f[].
 889 .
 890 .TP
 891 .BR \%@L_TFMTODIT@ (@MAN1EXT@)
 892 Create font description files for TeX DVI device.
 893 .
 894 .\"
 895 .SH ENVIRONMENT
 896 .
 897 Normally, the path separator in the following environment variables is the
 898 colon; this may vary depending on the operating system.
 899 For example, DOS and Windows use a semicolon instead.
 900 .
 901 .TP
 902 .EnvVar @U_ROFF@_BIN_PATH
 903 This search path, followed by
 904 .EnvVar $PATH ,
 905 is used for commands that are executed by
 906 .BR @T_ROFF@ .
 907 If it is not set then the directory where the
 908 .I @T_ROFF@
 909 binaries were installed is prepended to
 910 .EnvVar PATH .
 911 .
 912 .TP
 913 .EnvVar @U_ROFF@_COMMAND_PREFIX
 914 When there is a need to run different
 915 .I roff
 916 implementations at the same time
 917 .I @T_ROFF@
 918 provides the facility to prepend a prefix to most of its programs that
 919 could provoke name clashings at run time (default is to have none).
 920 .
 921 More exactly, if it is set to prefix
 922 .I xxx
 923 then
 924 .B @L_ROFF@
 925 as a wrapper program internally calls
 926 .IB xxx @L_TROFF@
 927 instead of
 928 .BR @L_TROFF@ .
 929 This also applies to the preprocessors
 930 .BR \%@L_P_EQN@ ,
 931 .BR \%@L_P_GRN@ ,
 932 .BR \%@L_P_PIC@ ,
 933 .BR \%@L_P_REFER@ ,
 934 .BR \%@L_P_TBL@ ,
 935 .BR \%@L_P_SOELIM@ ,
 936 and to the utilities
 937 .B \%@L_INDXBIB@
 938 and
 939 .BR \%@L_LOOKBIB@ .
 940 .
 941 This feature does not apply to any programs different from the ones
 942 above (most notably
 943 .B @L_ROFF@
 944 itself).
 945 .
 946 .TP
 947 .EnvVar @U_ROFF@_ENCODING
 948 The value of this environment value is passed to the
 949 .B @L_P_PRECONV@
 950 preprocessor to select the encoding of input files, i.e.,
 951 setting this option implies
 952 .BR @L_ROFF@ 's
 953 command line option
 954 .B \-k .
 955 If set to an empty value then the automatic character set guessing
 956 heuristics are used, as documented for
 957 .BR preconv (@MAN1EXT@).
 958 An explicit
 959 .B \-K
 960 command line option overrides the value of
 961 .EnvVar @U_ROFF@_ENCODING .
 962 .
 963 .TP
 964 .EnvVar @U_ROFF@_FONT_PATH
 965 A list of directories in which to search for the
 966 .BI dev name
 967 directory in addition to the default ones.
 968 See
 969 .BR @L_TROFF@ (@MAN1EXT@)
 970 and
 971 .BR \%@L_ROFF@_font (@MAN5EXT@)
 972 for more details.
 973 .
 974 .TP
 975 .EnvVar @U_ROFF@_TMAC_PATH
 976 A list of directories in which to search for macro files in addition to
 977 the default directories.
 978 See
 979 .BR @L_TROFF@ (@MAN1EXT@)
 980 and
 981 .BR \%@L_ROFF@_tmac (@MAN5EXT@)
 982 for more details.
 983 .
 984 .TP
 985 .EnvVar @U_ROFF@_TMPDIR
 986 The directory in which temporary files are created.
 987 If this is not set but the environment variable
 988 .EnvVar TMPDIR
 989 instead, temporary files are created in the directory
 990 .EnvVar $TMPDIR .
 991 On MS-DOS and Windows\~32 platforms, the environment variables
 992 .EnvVar TMP
 993 and
 994 .EnvVar TEMP
 995 (in that order) are searched also, after
 996 .EnvVar @U_ROFF@_TMPDIR
 997 and
 998 .EnvVar TMPDIR .
 999 Otherwise, temporary files are created in
1000 .BR /tmp .
1001 The
1002 .BR \%@L_P_REFER@ (@MAN1EXT@),
1003 .BR \%@L_D_HTML@ (@MAN1EXT@),
1004 and
1005 .BR \%@L_D_PS@ (@MAN1EXT@)
1006 commands use temporary files.
1007 .
1008 .TP
1009 .EnvVar @U_ROFF@_TYPESETTER
1010 Preset the default device.
1011 If this is not set the
1012 .B @DEVICE@
1013 device is used as default.
1014 This device name is overwritten by the option
1015 .BR \-T .
1016 .
1017 .\"
1018 .SH FILES
1019 .
1020 There are some directories in which
1021 .I @T_ROFF@
1022 installs all of its data files.
1023 Due to different installation habits on different operating systems,
1024 their locations are not absolutely fixed, but their function is
1025 clearly defined and coincides on all systems.
1026 .
1027 .\"
1028 .SS "groff Macro Directory"
1029 .
1030 This contains all information related to macro packages;
1031 in the @T_ROFF@ system installation this directory is
1032 .IR @MACRODIR@ .
1033 Note that more than a single directory is searched for those files
1034 as documented in
1035 .BR \%@L_ROFF@_tmac (@MAN5EXT@)
1036 .
1037 .P
1038 The following files contained in the
1039 .I macro directory
1040 have a special meaning:
1041 .
1042 .TP
1043 .B troffrc
1044 Initialization file for
1045 .IR @L_TROFF@ .
1046 This is interpreted by
1047 .B @L_TROFF@
1048 before reading the macro sets and any input.
1049 .
1050 .TP
1051 .B troffrc-end
1052 Final startup file for
1053 .IR @L_TROFF@ .
1054 It is parsed after all macro sets have been read.
1055 .
1056 .TP
1057 .IB name .tmac
1058 .TQ
1059 .BI tmac. name
1060 Macro file for macro package
1061 .IR name .
1062 .
1063 .\"
1064 .SS "groff Font Directory"
1065 .
1066 This contains all information related to output devices;
1067 in the @T_ROFF@ system installation this directory is
1068 .IR @FONTDIR@ .
1069 Note that more than a single directory is searched for those files; see
1070 .BR @L_TROFF@ (@MAN1EXT@).
1071 .
1072 .P
1073 The following files contained in the
1074 .I font directory
1075 have a special meaning:
1076 .
1077 .TP
1078 .BI dev name /DESC
1079 Device description file for device
1080 .IR name ,
1081 see
1082 .BR \%@L_ROFF@_font (@MAN5EXT@).
1083 .
1084 .TP
1085 .BI dev name / F
1086 Font file for font
1087 .I F
1088 of device
1089 .IR name .
1090 .
1091 .\"
1092 .SH BUGS
1093 .
1094 .P
1095 On \f[CR]EBCDIC\f[] hosts (e.g., \f[CR]OS/390 Unix\f[]), output
1096 devices
1097 .B ascii
1098 and
1099 .B latin1
1100 aren't available.
1101 Similarly, output for \f[CR]EBCDIC\f[] code page
1102 .B cp1047
1103 is not available on \f[CR]ASCII\f[] based operating systems.
1104 .
1105 .P
1106 Report bugs to the
1107 .MT @BUGMAIL@
1108 mailing list
1109 .ME .
1110 .
1111 .\"
1112 .SH AUTHORS
1113 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
1114 .
1115 Copyright \(co 1989, 2002 - 2008
1116 Free Software Foundation, Inc.
1117 .
1118 .P
1119 This document is distributed under the terms of the \f[CR]FDL\f[]
1120 (\f[CR]GNU Free Documentation License\f[]) version 1.1 or later.
1121 .
1122 You should have received a copy of the \f[CR]FDL\f[] on your system,
1123 it is also available on-line at the
1124 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1125 GNU copyleft site
1126 .UE .
1127 .
1128 .P
1129 This document is based on the original
1130 .I groff
1131 man page written by
1132 .MT jjc@jclark.com
1133 James Clark
1134 .UE .
1135 .
1136 It was rewritten, enhanced, and put under the FDL license by
1137 Bernd Warken.
1138 .
1139 It is maintained by
1140 .MT wl@gnu.org
1141 Werner Lemberg
1142 .ME .
1143 .
1144 .\"
1145 .SH "SEE ALSO"
1146 .
1147 .TP
1148 Introduction, history and further readings:
1149 .BR roff (@MAN7EXT@).
1150 .
1151 .TP
1152 Wrapper programs for formatters:
1153 .BR \%@L_ROFF@ (@MAN1EXT@).
1154 .
1155 .TP
1156 Roff preprocessors:
1157 .BR \%@L_P_EQN@ (@MAN1EXT@),
1158 .BR \%@L_P_GRN@ (@MAN1EXT@),
1159 .BR \%@L_P_PIC@ (@MAN1EXT@),
1160 .BR \%@L_P_PRECONV@ (@MAN1EXT@),
1161 .BR \%@L_P_REFER@ (@MAN1EXT@),
1162 .BR \%@L_P_SOELIM@ (@MAN1EXT@),
1163 .BR \%@L_P_TBL@ (@MAN1EXT@),
1164 .BR grap (1).
1165 .
1166 .TP
1167 Roff language with the groff extensions:
1168 .BR \%@L_ROFF@ (@MAN7EXT@),
1169 .BR \%@L_ROFF@_char (@MAN7EXT@),
1170 .BR \%@L_ROFF@_diff (@MAN7EXT@),
1171 .BR \%@L_ROFF@_font (@MAN5EXT@).
1172 .
1173 .TP
1174 Roff formatter programs:
1175 .BR \%@L_NROFF@ (@MAN1EXT@),
1176 .BR \%@L_TROFF@ (@MAN1EXT@),
1177 .BR ditroff (@MAN7EXT@).
1178 .
1179 .TP
1180 The intermediate output language:
1181 .BR \%@L_ROFF@_out (@MAN7EXT@).
1182 .
1183 .TP
1184 Postprocessors for the output devices:
1185 .BR \%@L_D_DVI@ (@MAN1EXT@),
1186 .BR \%@L_D_HTML@ (@MAN1EXT@),
1187 .BR \%@L_D_PS@ (@MAN1EXT@),
1188 .BR \%@L_D_TTY@ (@MAN1EXT@).
1189 .
1190 .TP
1191 Groff macro packages and macro-specific utilities:
1192 .BR \%@L_ROFF@_tmac (@MAN5EXT@),
1193 .BR \%@L_ROFF@_man (@MAN7EXT@),
1194 .BR \%@L_ROFF@_mdoc (@MAN7EXT@),
1195 .BR \%@L_ROFF@_me (@MAN7EXT@),
1196 .BR \%@L_ROFF@_ms (@MAN7EXT@),
1197 .BR \%@L_ROFF@_www (@MAN7EXT@),
1198 .BR \%@L_ROFF@_trace (@MAN7EXT@),
1199 .
1200 .TP
1201 The following utilities are available:
1202 .BR \%@L_ADDFTINFO@ (@MAN1EXT@),
1203 .BR \%@L_AFMTODIT@ (@MAN1EXT@),
1204 .BR \%@L_INDXBIB@ (@MAN1EXT@),
1205 .BR \%@L_LKBIB@ (@MAN1EXT@),
1206 .BR \%@L_LOOKBIB@ (@MAN1EXT@),
1207 .BR \%@L_PDFROFF@ (@MAN1EXT@),
1208 .BR \%@L_PFBTOPS@ (@MAN1EXT@),
1209 .BR \%@L_TFMTODIT@ (@MAN1EXT@),
1210 .
1211 .\" s-ts-mode