man/l_roff_tmac.5.in

   1 .ig
   2 @ @L_ROFF@_tmac.5
   3
   4 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
   5
   6 Copyright (C) 2000 - 2004, 2006 - 2009
   7   Free Software Foundation, Inc.
   8 written by Bernd Warken <bwarken@mayn.de> and Werner Lemberg
   9 <wl@gnu.org>
  10
  11 Permission is granted to copy, distribute and/or modify this document
  12 under the terms of the GNU Free Documentation License, Version 1.1 or
  13 any later version published by the Free Software Foundation; with the
  14 Invariant Sections being this .ig-section and AUTHOR, with no
  15 Front-Cover Texts, and with no Back-Cover Texts.
  16
  17 You should have received a copy of the Free Documentation License
  18 as part of the file COPYING; also located in the main directory of the
  19 source package of this program.
  20 ..
  21 .ds Ellipsis \&.\|.\|.\&\"
  22 .
  23 .TH @U_ROFF@_TMAC @MAN5EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
  24 .SH NAME
  25 @L_ROFF@_tmac \- macro files in the roff typesetting system
  26 .
  27 .
  28 .\"
  29 .SH DESCRIPTION
  30 .\"
  31 .
  32 The
  33 .BR roff (@MAN7EXT@)
  34 type-setting system provides a set of macro packages suitable for
  35 special kinds of documents.
  36 .
  37 Each macro package stores its macros and definitions in a file called
  38 the package's
  39 .BR "tmac file" .
  40 The name is deduced from
  41 .RB ` T\c
  42 .IB roff MAC\c
  43 .IR ros '.
  44 .
  45 .P
  46 The tmac files are normal roff source documents, except that they
  47 usually contain only definitions and setup commands, but no text.
  48 .
  49 All tmac files are kept in a single or a small number of directories,
  50 the
  51 .B tmac
  52 directories.
  53 .
  54 .
  55 .\"
  56 .SH "@T_ROFF@ MACRO PACKAGES"
  57 .\"
  58 .
  59 .I @T_ROFF@
  60 provides most classical macro packages, some more full packages, and
  61 some secondary packages for special purposes.
  62 .
  63 Note that it is not possible to use multiple primary macro packages at the
  64 same time; saying e.g.\&
  65 .
  66 .IP
  67 .EX
  68 \fIsh#\fP @L_ROFF@ \-m man \-m ms foo
  69 .EE
  70 .
  71 .P
  72 or
  73 .
  74 .IP
  75 .EX
  76 \fIsh#\fP @L_ROFF@ \-m man foo \-m ms bar
  77 .EE
  78 .
  79 .P
  80 fails.
  81 Exception to this is the use of man pages written with either the
  82 .B mdoc
  83 or the
  84 .B man
  85 macro package.
  86 See below the description of the
  87 .B andoc.tmac
  88 file.
  89 .
  90 .
  91 .\"
  92 .SS "Man\~Pages"
  93 .\"
  94 .
  95 .TP
  96 .B man
  97 This is the classical macro package for UNIX manual pages
  98 (man\~pages); it is quite handy and easy to use; see
  99 .BR @L_ROFF@_man (@MAN7EXT@).
 100 .
 101 .
 102 .TP
 103 .B doc
 104 .TQ
 105 .B mdoc
 106 An alternative macro package for man\~pages mainly used in BSD
 107 systems; it provides many new features, but it is not the standard for
 108 man\~pages; see
 109 .BR @L_ROFF@_mdoc (@MAN7EXT@).
 110 .
 111 .
 112 .TP
 113 .B andoc
 114 .TQ
 115 .B mandoc
 116 Use this file in case you don't know whether the
 117 .B man
 118 macros or the
 119 .B mdoc
 120 package should be used.
 121 Multiple man pages (in either format) can be handled.
 122 .
 123 .
 124 .\"
 125 .SS "Full Packages"
 126 .\"
 127 .
 128 The packages in this section provide a complete set of macros for
 129 writing documents of any kind, up to whole books.
 130 .
 131 They are similar in functionality; it is a matter of taste which one
 132 to use.
 133 .
 134 .
 135 .TP
 136 .B me
 137 The classical
 138 .I me
 139 macro package; see
 140 .BR @L_ROFF@_me (@MAN7EXT@).
 141 .
 142 .
 143 .TP
 144 .B mm
 145 The semi-classical
 146 .I mm
 147 macro package; see
 148 .BR @L_ROFF@_mm (@MAN7EXT@).
 149 .
 150 .
 151 .TP
 152 .B ms
 153 The classical
 154 .I ms
 155 macro package; see
 156 .BR @L_ROFF@_ms (@MAN7EXT@).
 157 .
 158 .
 159 .\"
 160 .SS "Language-specific Packages"
 161 .\"
 162 .
 163 .TP
 164 .B cs
 165 This file adds support for Czech localization, including the main macro
 166 packages (me, mm, and ms).
 167 .
 168 .IP
 169 Note that
 170 .B cs.tmac
 171 sets the input encoding to latin-2.
 172 .
 173 .
 174 .TP
 175 .B de
 176 .TQ
 177 .B den
 178 German localization support, including the main macro packages (me, mom, mm,
 179 and ms).
 180 .
 181 .IP
 182 .B de.tmac
 183 selects hyphenation patterns for traditional orthography, and
 184 .B den.tmac
 185 does the same for the new orthography (`Recht\%schreib\%reform').
 186 .
 187 It should be used as the last macro package on the command line.
 188 .
 189 .
 190 .TP
 191 .B fr
 192 This file adds support for French localization, including the main macro
 193 packages (me, mom, mm, and ms).
 194 .
 195 .
 196 Example:
 197 .RS
 198 .IP
 199 .EX
 200 \fIsh#\fP @L_ROFF@ -ms -mfr foo.ms > foo.ps
 201 .EE
 202 .RE
 203 .
 204 .IP
 205 Note that
 206 .B fr.tmac
 207 sets the input encoding to latin-9 to get proper support of the `oe'
 208 ligature.
 209 .
 210 .
 211 .TP
 212 .B sv
 213 Swedish localization support, including the me, mom, and ms macro packages.
 214 .
 215 Note that Swedish for the mm macros is handled separately; see
 216 .BR @L_ROFF@_mmse (@MAN7EXT@).
 217 .
 218 It should be used as the last macro package on the command line.
 219 .
 220 .
 221 .\"
 222 .SS "Input Encodings"
 223 .\"
 224 .
 225 .
 226 .TP
 227 .B latin1
 228 .TQ
 229 .B latin2
 230 .TQ
 231 .B latin5
 232 .TQ
 233 .B latin9
 234 Various input encodings supported directly by @T_ROFF@.
 235 .
 236 Normally, this macro is loaded at the very beginning of a document or
 237 specified as the first macro argument on the command line.
 238 .
 239 .B @L_ROFF@
 240 loads latin1 by default at start-up.
 241 .
 242 Note that these macro packages don't work on EBCDIC hosts.
 243 .
 244 .
 245 .TP
 246 .B cp1047
 247 Encoding support for EBCDIC.
 248 .
 249 On those platforms it is loaded automatically at start-up.
 250 .
 251 Due to different character ranges used in
 252 .B @L_ROFF@
 253 it doesn't work on architectures which are based on ASCII.
 254 .
 255 .
 256 .P
 257 Note that it can happen that some input encoding characters are not
 258 available for a particular output device.
 259 .
 260 For example, saying
 261 .
 262 .P
 263 .EX
 264 @L_ROFF@ -Tlatin1 -mlatin9 ...
 265 .EE
 266 .
 267 .P
 268 fails if you use the Euro character in the input.
 269 .
 270 Usually, this limitation is present only for devices which have a
 271 limited set of output glyphs
 272 .RB ( \-Tascii ,
 273 .BR \-Tlatin1 );
 274 for other devices it is usually sufficient to install proper
 275 fonts which contain the necessary glyphs.
 276 .
 277 .
 278 .\"
 279 .SS "Special Packages"
 280 .\"
 281 .
 282 The macro packages in this section are not intended for stand-alone
 283 usage, but can be used to add special functionality to any other
 284 macro package or to plain @L_ROFF@.
 285 .
 286 .
 287 .TP
 288 .B 60bit
 289 Provide some macros for addition, multiplication, and division of 60bit
 290 integers (allowing safe multiplication of 30bit integers, for example).
 291 .
 292 .
 293 .TP
 294 .B ec
 295 Switch to the EC and TC font families.
 296 .
 297 To be used with
 298 .BR \%@L_D_DVI@ (@MAN1EXT@)
 299 \[en] this man page also gives more details of how to use it.
 300 .
 301 .
 302 .TP
 303 .B papersize
 304 This macro file is already loaded at start-up by
 305 .B @L_TROFF@
 306 so it isn't necessary to call it explicitly.
 307 .
 308 It provides an interface to set the paper size on the command line with
 309 the option \f[B]\%\-dpaper=\f[]\f[I]size\f[].
 310 .
 311 Possible values for
 312 .I size
 313 are the same as the predefined
 314 .B papersize
 315 values in the DESC file (only lowercase; see
 316 .BR @L_ROFF@_font (@MAN5EXT@)
 317 for more) except
 318 .BR a7 - d7 .
 319 .
 320 An appended
 321 .B l
 322 (ell) character denotes landscape orientation.
 323 .
 324 Examples:
 325 .BR a4 ,
 326 .BR c3l ,
 327 .BR letterl .
 328 .
 329 .IP
 330 Most output drivers need additional command line switches
 331 .B \-p
 332 and
 333 .B \-l
 334 to override the default paper length and orientation as set in the driver
 335 specific DESC file.
 336 .
 337 For example, use the following for PS output on A4 paper in landscape
 338 orientation:
 339 .
 340 .IP
 341 .EX
 342 .SM
 343 \fIsh#\fP @L_ROFF@ \-Tps \-dpaper=a4l \-P\-pa4 \-P\-l \-ms foo.ms > foo.ps
 344 .EE
 345 .
 346 .
 347 .TP
 348 .B pic
 349 This file provides proper definitions for the macros
 350 .B PS
 351 and
 352 .BR PE ,
 353 needed for the
 354 .BR @L_P_PIC@ (@MAN1EXT@)
 355 preprocessor.
 356 .
 357 They center each picture.
 358 .
 359 Use it only if your macro package doesn't provide proper definitions
 360 for those two macros (actually, most of them already do).
 361 .
 362 .
 363 .TP
 364 .B pspic
 365 A single macro is provided in this file,
 366 .BR PSPIC ,
 367 to include a PostScript graphic in a document.
 368 .
 369 The following output devices support inclusion of PS images:
 370 .BR \-Tps ,
 371 .BR \-Tdvi ,
 372 .BR \-Thtml ,
 373 and
 374 .BR \-Txhtml ;
 375 for all other devices the image is replaced with a hollow rectangle
 376 of the same size.
 377 .
 378 This macro file is already loaded at start-up by
 379 .B @L_TROFF@
 380 so it isn't necessary to call it explicitly.
 381 .
 382 .IP
 383 Syntax:
 384 .RS
 385 .IP
 386 \&\fB.PSPIC\fP \
 387 [\fB\-L\fP\|\
 388 |\|\fB\-R\fP\|\
 389 |\|\fB\-C\fP\|\
 390 |\|\fB\-I\fP\ \fIn\fP] \
 391 \fI\|file\fP [\fIwidth\fP [\fIheight\fP]]
 392 .RE
 393 .
 394 .IP
 395 .I file
 396 is the name of the PostScript file;
 397 .I width
 398 and
 399 .I height
 400 give the desired width and height of the image.
 401 .
 402 If neither a
 403 .I width
 404 nor a
 405 .I height
 406 argument is specified, the image's natural width (as given in
 407 the file's bounding box) or the current line length is used
 408 as the width, whatever is smaller.
 409 .
 410 The
 411 .I width
 412 and
 413 .I height
 414 arguments may have scaling indicators attached;
 415 the default scaling indicator is\~\c
 416 .BR i .
 417 .
 418 This macro scales the graphic uniformly
 419 in the x and y\~directions so that it is no more than
 420 .I width
 421 wide
 422 and
 423 .I height
 424 high.
 425 .
 426 Option
 427 .B \-C
 428 centers the graphic horizontally, which is the default.
 429 .
 430 The
 431 .B \-L
 432 and
 433 .B \-R
 434 options cause the graphic to be left-aligned and right-aligned,
 435 respectively.
 436 .
 437 The
 438 .B \-I
 439 option causes the graphic to be indented by\~\c
 440 .I n
 441 (default scaling indicator is\~\c
 442 .BR m ).
 443 .
 444 .IP
 445 For use of
 446 .B .PSPIC
 447 within a diversion it is recommended to extend it with
 448 the following code, assuring that the diversion's width completely
 449 covers the image's width.
 450 .
 451 .RS
 452 .IP
 453 .EX
 454 \&.am PSPIC
 455 \&.\ \ vpt 0
 456 \&\[rs]h'(\[rs]\[rs]n[ps-offset]u + \[rs]\[rs]n[ps-deswid]u)'
 457 \&.\ \ sp -1
 458 \&.\ \ vpt 1
 459 \&..
 460 .EE
 461 .RE
 462 .
 463 .
 464 .TP
 465 .B ptx
 466 A single macro is provided in this file,
 467 .BR xx ,
 468 for formatting permuted index entries as produces by the GNU
 469 .BR ptx (1)
 470 program.
 471 .
 472 In case you need a different formatting, copy the macro into
 473 your document and adapt it to your needs.
 474 .
 475 .
 476 .TP
 477 .B trace
 478 Use this for tracing macro calls.
 479 .
 480 It is only useful for debugging.
 481 .
 482 See
 483 .BR @L_ROFF@_trace (@MAN7EXT@) .
 484 .
 485 .
 486 .TP
 487 .B tty-char
 488 Overrides the definition of standard troff characters and some @T_ROFF@
 489 characters for TTY devices.
 490 .
 491 The optical appearance is intentionally inferior compared to that of
 492 normal TTY formatting to allow processing with critical equipment.
 493 .
 494 .
 495 .TP
 496 .B www
 497 Additions of elements known from the HTML format, as used in the
 498 internet (World Wide Web) pages; this includes URL links and mail
 499 addresses; see
 500 .BR @L_ROFF@_www (@MAN7EXT@).
 501 .
 502 .
 503 .\"
 504 .SH NAMING
 505 .\"
 506 .
 507 Classical roff systems were designed before the conventions of the
 508 modern C
 509 .BR getopt (3)
 510 call evolved, and used a naming scheme for macro packages that looks
 511 odd to modern eyes. Macro packages were always included with the option
 512 .BR \-m ;
 513 when this option was directly followed by its argument without an
 514 intervening space, this looked like a long option preceded by a single
 515 minus \[em] a sensation in the computer stone age.
 516 To make this invocation form work, classical troff
 517 macro packages used names that started with the letter `m',
 518 which was omitted in the naming of the macro file.
 519 .
 520 .
 521 .P
 522 For example, the macro package for the man pages was called
 523 .IR man ,
 524 while its macro file
 525 .IR tmac.an .
 526 So it could be activated by the argument
 527 .I an
 528 to option
 529 .BR \-m ,
 530 or
 531 .BR \-man
 532 for short.
 533 .
 534 .
 535 .P
 536 For similar reasons, macro packages that did not start with an `m'
 537 had a leading `m'
 538 added in the documentation and in speech; for example, the package
 539 corresponding to
 540 .I tmac.doc
 541 was called
 542 .I mdoc
 543 in the documentation, although a more suitable name would be
 544 .IR doc .
 545 For, when omitting the space between the option and its argument, the
 546 command line option for activating this package reads
 547 .BR \-mdoc .
 548 .
 549 .
 550 .P
 551 To cope with all situations, actual versions of
 552 .BR @L_ROFF@ (@MAN1EXT@)
 553 are smart about both naming schemes by providing two macro files
 554 for the inflicted macro packages; one with a leading `m'
 555 the other one without it.
 556 .
 557 Newer packages are more specific; for example, the
 558 .I www
 559 macro package may be specified only as one of the two methods:
 560 .
 561 .IP
 562 .EX
 563 \fIsh#\fP @L_ROFF@\ \-m\ www
 564 \fIsh#\fP @L_ROFF@\ \-mwww
 565 .EE
 566 .
 567 .
 568 .P
 569 Obviously, variants like
 570 .I \-mmwww
 571 would not make much sense.
 572 .
 573 .
 574 .P
 575 A second strange feature of classical troff was to name macro files
 576 in the form \f[B]tmac.\f[]\f[I]name\f[].
 577 In modern operating systems, the type of a file is specified as a
 578 postfix, the file name extension.
 579 .
 580 Again, @T_ROFF@ copes with this situation by searching both
 581 .IB anything .tmac
 582 and
 583 .BI tmac. anything
 584 if only
 585 .I anything
 586 is specified.
 587 .
 588 .
 589 .P
 590 The easiest way to find out which macro packages are available on a
 591 system is to check the man\~page
 592 .BR @L_ROFF@ (@MAN1EXT@),
 593 or the contents of the
 594 .I tmac
 595 directories.
 596 .
 597 .
 598 .P
 599 Most macro packages are described in\~man pages called
 600 .BR @L_ROFF@_\f[I]name\f[] (@MAN7EXT@),
 601 with a leading `m'
 602 for the classical packages.
 603 .
 604 .
 605 .\"
 606 .SH INCLUSION
 607 .\"
 608 .
 609 There are several ways to use a macro package in a document.
 610 .
 611 The classical way is to specify the option
 612 .BR \-m
 613 .I name
 614 at run-time; this makes the contents of the macro package
 615 .I name
 616 available.
 617 .
 618 In @T_ROFF@, the file
 619 .IB name .tmac
 620 is searched within the tmac path; if not found,
 621 .BI tmac. name
 622 is searched for instead.
 623 .
 624 .
 625 .P
 626 Alternatively, it is also possible to include a macro file by adding
 627 the request
 628 .B .so
 629 .I filename
 630 into the document; the argument must be the full file name of an
 631 existing file, possibly with the directory where it is kept.
 632 .
 633 In @T_ROFF@ this was improved by the similar request
 634 .B .mso
 635 .IR package ,
 636 which added searching in the tmac path, just like option
 637 .BR \-m
 638 does.
 639 .
 640 .
 641 .P
 642 Note that in order to resolve the
 643 .B .so
 644 and
 645 .B .mso
 646 requests, the roff preprocessor
 647 .BR @L_P_SOELIM@ (@MAN1EXT@)
 648 must be called if the files to be included need preprocessing.
 649 .
 650 This can be done either directly by a pipeline on the command line or
 651 by using the option
 652 .BR \-s .
 653 .
 654 .I man
 655 calls @L_P_SOELIM@ automatically.
 656 .
 657 .
 658 .P
 659 For example, suppose a macro file is stored as
 660 .
 661 .IP
 662 .I @MACRODIR@/macros.tmac
 663 .
 664 .P
 665 and is used in some document called
 666 .IR docu.roff .
 667 .
 668 .
 669 .P
 670 At run-time, the formatter call for this is
 671 .
 672 .IP
 673 .EX
 674 \fIsh#\fP @L_ROFF@ \-m macros docu.roff
 675 .EE
 676 .
 677 .
 678 .P
 679 To include the macro file directly in the document either
 680 .
 681 .IP
 682 .EX
 683 \&.mso macros.tmac
 684 .EE
 685 .
 686 .P
 687 is used or
 688 .
 689 .IP
 690 .EX
 691 \&.so @MACRODIR@/macros.tmac
 692 .EE
 693 .
 694 .
 695 .P
 696 In both cases, the formatter should be called with option
 697 .B \-s
 698 to invoke
 699 .BR @L_P_SOELIM@ .
 700 .
 701 .
 702 .P
 703 If you want to write your own @T_ROFF@ macro file, call it
 704 .IB whatever .tmac
 705 and put it in some directory of the tmac path, see section
 706 .BR FILES .
 707 Then documents can include it with the
 708 .B .mso
 709 request or the option
 710 .BR \-m .
 711 .
 712 .
 713 .ig
 714 .\"
 715 .SH CONVENTION
 716 .\"
 717 .
 718 There is a convention that is supported by many modern roff
 719 type-setters and
 720 .BR man (1)
 721 programs, the
 722 .I preprocessor word
 723 described in the following.
 724 .
 725 .P
 726 If the first line in a document is a comment, the first word (after the
 727 comment characters and a blank) constitutes the
 728 .B preprocessor
 729 .BR word .
 730 That means that the letters of this word are interpreted as
 731 abbreviations for those preprocessor commands that should be run
 732 when formatting the document.
 733 .
 734 Mostly, only the letters corresponding to the options for the
 735 preprocessors are recognized,
 736 `e'
 737 (for
 738 .BR eqn ),
 739 .\" `G',
 740 .\" `g',
 741 `p`
 742 (for
 743 .BR pic ),
 744 `R'
 745 (for
 746 .BR refer ),
 747 `s'
 748 (for
 749 .BR soelim ),
 750 and
 751 `t'
 752 (for
 753 .BR tbl ).
 754 (see
 755 .BR roff (@MAN7EXT@)).
 756 .
 757 .
 758 .P
 759 Besides being a good reminder for the user, some formatters (like the
 760 .BR man (1)
 761 program) are even able to automatically start the preprocessors
 762 specified in the preprocessor word, but do not bet on this.
 763 .
 764 .
 765 .P
 766 The
 767 .I man
 768 program handles some preprocessors automatically, such that in
 769 man\~pages only the following characters should be used:
 770 `e', `p', and `t'.
 771 .
 772 .
 773 .
 774 .\"
 775 .SH "WRITING MACROS"
 776 .\"
 777 .
 778 A
 779 .BR roff (@MAN7EXT@)
 780 document is a text file that is enriched by predefined formatting
 781 constructs, such as requests, escape sequences, strings, numeric
 782 registers, and macros from a macro package.
 783 .
 784 These elements are described in
 785 .BR roff (@MAN7EXT@).
 786 .
 787 .
 788 .P
 789 To give a document a personal style, it is most useful to extend the
 790 existing elements by defining some macros for repeating tasks; the best
 791 place for this is near the beginning of the document or in a separate
 792 file.
 793 .
 794 .
 795 .P
 796 Macros without arguments are just like strings.
 797 .
 798 But the full power of macros reveals when arguments are passed with a
 799 macro call.
 800 .
 801 Within the macro definition, the arguments are available as the escape
 802 sequences
 803 .BR \[rs]$1 ,
 804 \*[Ellipsis],
 805 .BR \[rs]$9 ,
 806 .BR \[rs]$[ \*[Ellipsis] ] ,
 807 .BR \[rs]$* ,
 808 and
 809 .BR \[rs]$@ ,
 810 the name under which the macro was called is in
 811 .BR \[rs]$0 ,
 812 and the number of arguments is in register
 813 .BR \[rs]n[.$] ;
 814 see
 815 .BR @L_ROFF@ (@MAN7EXT@).
 816 .
 817 .
 818 .\"
 819 .SS "Copy-in Mode"
 820 .\"
 821 .
 822 The phase when @T_ROFF@ reads a macro is called
 823 .I "copy-in mode"
 824 or
 825 .I "copy mode"
 826 in roff-talk.
 827 .
 828 This is comparable to the C\~preprocessing phase during the development
 829 of a program written in the C\~language.
 830 .
 831 .
 832 .P
 833 In this phase all backslashes are interpreted; that means that all
 834 escape sequences in the macro body are interpreted and replaced by
 835 their value.
 836 .
 837 For constant expressions, this is wanted, but strings and registers
 838 that might change between calls of the macro must be protected from
 839 being evaluated.
 840 .
 841 This is most easily done by doubling the backslash that introduces the
 842 escape sequence.
 843 .
 844 This doubling is most important for the positional parameters.
 845 .
 846 For example, to print information on the arguments that were passed to
 847 the macro to the terminal, define a macro named `.print_args',
 848 say.
 849 .
 850 .
 851 .IP
 852 .ds @1 \[rs]f[I]\[rs]\[rs]$0\[rs]f[]\"
 853 .ds @2 arguments:\"
 854 .EX
 855 \&.ds midpart was called with
 856 \&.de print_args
 857 \&.\ \ tm\ \*[@1]\ \[rs]*[midpart]\ \[rs]\[rs]n[.$]\ \*[@2]
 858 \&.\ \ tm\ \[rs]\[rs]$*
 859 \&..
 860 .EE
 861 .rm @1
 862 .rm @2
 863 .
 864 .
 865 .P
 866 When calling this macro by
 867 .
 868 .IP
 869 .EX
 870 \&.print_args arg1 arg2
 871 .EE
 872 .
 873 .P
 874 the following text is printed to the terminal:
 875 .
 876 .IP
 877 .EX
 878 \&\f[CI]print_args\f[] was called with the following 2 arguments:
 879 arg1 arg2
 880 .EE
 881 .
 882 .
 883 .P
 884 Let's analyze each backslash in the macro definition.
 885 .
 886 As the positional parameters and the number of arguments change
 887 with each call of the macro their leading backslash must be doubled,
 888 which results in
 889 .I \[rs]\[rs]$*
 890 and
 891 .IR \[rs]\[rs][.$] .
 892 The same applies to the macro name because it could be called with an
 893 alias name, so
 894 .IR \[rs]\[rs]$0 .
 895 .
 896 .
 897 .P
 898 On the other hand,
 899 .I midpart
 900 is a constant string, it does not change, so no doubling for
 901 .IR \[rs]*[midpart] .
 902 The
 903 .I \[rs]f
 904 escape sequences are predefined elements for setting the font
 905 within the text.
 906 .
 907 Of course, this behavior does not change, so no doubling with
 908 .I \[rs]f[I]
 909 and
 910 .IR \[rs]f[] .
 911 .
 912 .
 913 .\"
 914 .SS "Draft Mode"
 915 .\"
 916 .
 917 Writing macros is easy when the escaping mechanism is temporarily
 918 disabled.
 919 .
 920 This is done by enclosing the macro definition(s) into a pair of
 921 .B .eo
 922 and
 923 .B .ec
 924 requests.
 925 .
 926 Then the body in the macro definition is just like a normal part of
 927 the document \[em] text enhanced by calls of requests, macros,
 928 strings, registers, etc.
 929 .
 930 For example, the code above can be written in a simpler way by
 931 .
 932 .
 933 .IP
 934 .ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\"
 935 .ds @2 arguments:\"
 936 .EX
 937 \&.eo
 938 \&.ds midpart was called with
 939 \&.de print_args
 940 \&.\ \ tm\ \*[@1]\ \[rs]*[midpart]\ \[rs]n[.$]\ \*[@2]
 941 \&.\ \ tm\ \[rs]$*
 942 \&..
 943 \&.ec
 944 .EE
 945 .rm @1
 946 .rm @2
 947 .
 948 .
 949 .P
 950 Unfortunately, draft mode cannot be used universally.
 951 .
 952 Although it is good enough for defining normal macros, draft mode
 953 fails with advanced applications, such as indirectly defined
 954 strings, registers, etc.
 955 .
 956 An optimal way is to define and test all macros in draft mode and then
 957 do the backslash doubling as a final step; do not forget to remove the
 958 .I .eo
 959 request.
 960 .
 961 .
 962 .\"
 963 .SS "Tips for Macro Definitions"
 964 .\"
 965 .
 966 .IP \(bu
 967 Start every line with a dot, for example, by using the request
 968 .B .nop
 969 for text lines, or write your own macro that handles also text lines
 970 with a leading dot.
 971 .
 972 .RS
 973 .IP
 974 .EX
 975 \&.de Text
 976 \&.\ \ if (\[rs]\[rs]n[.$] == 0)\ \[rs]
 977 \&.\ \ \ \ return
 978 \&.\ \ nop\ \[rs])\[rs]\[rs]$*\[rs])
 979 \&..
 980 .EE
 981 .RE
 982 .
 983 .IP \(bu
 984 Write a comment macro that works both for copy-in and draft mode; for
 985 as escaping is off in draft mode, trouble might occur when normal
 986 comments are used.
 987 .
 988 For example, the following macro just ignores its arguments, so it
 989 acts like a comment line:
 990 .
 991 .RS
 992 .IP
 993 .EX
 994 \&.de\ c
 995 \&..
 996 \&.c\ This\ is\ like\ a\ comment\ line.
 997 .EE
 998 .RE
 999 .
1000 .IP \(bu
1001 In long macro definitions, make ample use of comment lines or
1002 almost-empty lines (this is, lines which have a leading dot
1003 and nothing else) for a better structuring.
1004 .
1005 .IP \(bu
1006 To increase readability, use the indentation facility for requests
1007 and macro calls (arbitrary whitespace after the leading dot).
1008 .
1009 .
1010 .\"
1011 .SS "Diversions"
1012 .\"
1013 .
1014 Diversions can be used to implement quite advanced programming
1015 constructs.
1016 .
1017 They are comparable to pointers to large data structures in the
1018 C\~programming language, but their usage is quite different.
1019 .
1020 .
1021 .P
1022 In their simplest form, diversions are multi-line strings, but
1023 they get their power when diversions are used dynamically within macros.
1024 .
1025 The (formatted) information stored in a diversion can be retrieved by
1026 calling the diversion just like a macro.
1027 .
1028 .
1029 .P
1030 Most of the problems arising with diversions can be avoided if you remain
1031 aware of the fact that diversions always store complete lines.
1032 .
1033 If diversions are used when the line buffer has not been flushed,
1034 strange results are produced; not knowing this, many people get
1035 desperate about diversions.
1036 .
1037 To ensure that a diversion works, line breaks should be added at the
1038 right places.
1039 .
1040 To be on the secure side, enclose everything that has to do with
1041 diversions into a pair of line breaks; for example, by explicitly using
1042 .B .br
1043 requests.
1044 .
1045 This rule should be applied to diversion definition, both inside and
1046 outside, and to all calls of diversions.
1047 .
1048 This is a bit of overkill, but it works nicely.
1049 .
1050 .
1051 .P
1052 [If you really need diversions which should ignore the current partial
1053 line, use environments to save the current partial line and/\:or use the
1054 .B .box
1055 request.]
1056 .
1057 .
1058 .P
1059 The most powerful feature using diversions is to start a diversion
1060 within a macro definition and end it within another macro.
1061 .
1062 Then everything between each call of this macro pair is stored within
1063 the diversion and can be manipulated from within the macros.
1064 .
1065 .
1066 .\"
1067 .SH FILES
1068 .\"
1069 .
1070 All macro names must be named
1071 .IB name .tmac
1072 to fully use the tmac mechanism.
1073 .
1074 .BI tmac. name
1075 as with classical packages is possible as well, but deprecated.
1076 .
1077 .
1078 .P
1079 The macro files are kept in the
1080 .IR "tmac directories" ;
1081 a colon separated list of these constitutes the
1082 .IR "tmac path" .
1083 .
1084 .
1085 .P
1086 The search sequence for macro files is (in that order):
1087 .
1088 .IP \(bu
1089 the directories specified with the
1090 .B \-M
1091 command line option
1092 .
1093 .IP \(bu
1094 the directories given in the
1095 .B $@U_ROFF@_TMAC_PATH
1096 environment variable
1097 .
1098 .IP \(bu
1099 the current directory (only if in unsafe mode, which is enabled by the
1100 .B \-U
1101 command line switch)
1102 .
1103 .IP \(bu
1104 the home directory
1105 .
1106 .IP \(bu
1107 a platform-specific directory, being
1108 .
1109 .RS
1110 .IP
1111 .B @SYSTEMMACRODIR@
1112 .RE
1113 .
1114 .IP
1115 in this installation
1116 .
1117 .IP \(bu
1118 a site-specific (platform-independent) directory, being
1119 .
1120 .RS
1121 .IP
1122 .B @LOCALMACRODIR@
1123 .RE
1124 .
1125 .IP
1126 in this installation
1127 .
1128 .IP \(bu
1129 the main tmac directory, being
1130 .
1131 .RS
1132 .IP
1133 .B @MACRODIR@
1134 .RE
1135 .
1136 .IP
1137 in this installation
1138 .
1139 .
1140 .\"
1141 .SH ENVIRONMENT
1142 .\"
1143 .
1144 .TP
1145 .B $@U_ROFF@_TMAC_PATH
1146 A colon separated list of additional tmac directories in which to search
1147 for macro files.
1148 .
1149 See the previous section for a detailed description.
1150 .
1151 .
1152 .\"
1153 .SH AUTHOR
1154 .\"
1155 .
1156 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
1157
1158 Copyright (C) 2000 - 2004, 2006 - 2009
1159 Free Software Foundation, Inc.
1160 .
1161 .P
1162 This document is distributed under the terms of the FDL (GNU Free
1163 Documentation License) version 1.1 or later.
1164 .
1165 You should have received a copy of the FDL on your system, it is also
1166 available on-line at the
1167 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1168 GNU copyleft site
1169 .UE .
1170 .
1171 .P
1172 This document was written by
1173 .MT bwarken@mayn.de
1174 Bernd Warken
1175 .ME .
1176 .
1177 .\"
1178 .SH "SEE ALSO"
1179 .\"
1180 .
1181 .BR @L_ROFF@ (@MAN1EXT@)
1182 an overview of the @T_ROFF@ system.
1183 .
1184 .
1185 .TP
1186 .BR @L_ROFF@_man (@MAN7EXT@),
1187 .TQ
1188 .BR @L_ROFF@_mdoc (@MAN7EXT@),
1189 .TQ
1190 .BR @L_ROFF@_me (@MAN7EXT@),
1191 .TQ
1192 .BR @L_ROFF@_mm (@MAN7EXT@),
1193 .TQ
1194 .BR @L_ROFF@_ms (@MAN7EXT@),
1195 .TQ
1196 .BR @L_ROFF@_trace (@MAN7EXT@),
1197 .TQ
1198 .BR @L_ROFF@_www (@MAN7EXT@).
1199 the @T_ROFF@ tmac macro packages.
1200 .
1201 .
1202 .TP
1203 .BR @L_ROFF@ (@MAN7EXT@)
1204 the @T_ROFF@ language.
1205 .
1206 .
1207 .P
1208 The Filesystem Hierarchy Standard is available at the
1209 .UR http://\:www.pathname.com/\:fhs/
1210 FHS web site
1211 .UE .
1212 .
1213 .\" s-ts-mode