man/l_roff-tmac.5.in

   1 .ig
   2 @ @L_ROFF@-tmac.5
   3
   4 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
   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 @L_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 62bit
 289 Provide some macros for addition, multiplication, and division of 62bit
 290 integers (allowing safe multiplication of 31bit 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 .IP
 701 .EX
 702 \fIsh#\fP groff \-s docu.roff
 703 .EE
 704 .
 705 .P
 706 If you want to write your own @T_ROFF@ macro file, call it
 707 .IB whatever .tmac
 708 and put it in some directory of the tmac path, see section
 709 .BR FILES .
 710 Then documents can include it with the
 711 .B .mso
 712 request or the option
 713 .BR \-m .
 714 .
 715 .
 716 .ig
 717 .\"
 718 .SH CONVENTION
 719 .\"
 720 .
 721 There is a convention that is supported by many modern roff
 722 type-setters and
 723 .BR man (1)
 724 programs, the
 725 .I preprocessor word
 726 described in the following.
 727 .
 728 .P
 729 If the first line in a document is a comment, the first word (after the
 730 comment characters and a blank) constitutes the
 731 .B preprocessor
 732 .BR word .
 733 That means that the letters of this word are interpreted as
 734 abbreviations for those preprocessor commands that should be run
 735 when formatting the document.
 736 .
 737 Mostly, only the letters corresponding to the options for the
 738 preprocessors are recognized,
 739 `e'
 740 (for
 741 .BR eqn ),
 742 `p'
 743 (for
 744 .BR pic ),
 745 `R'
 746 (for
 747 .BR refer ),
 748 `s'
 749 (for
 750 .BR soelim ),
 751 and
 752 `t'
 753 (for
 754 .BR tbl ).
 755 (see
 756 .BR @L_ROFF@-history (@MAN7EXT@)).
 757 .
 758 .
 759 .P
 760 Besides being a good reminder for the user, some formatters (like the
 761 .BR man (1)
 762 program) are even able to automatically start the preprocessors
 763 specified in the preprocessor word, but do not bet on this.
 764 .
 765 .
 766 .P
 767 The
 768 .I man
 769 program handles some preprocessors automatically, such that in
 770 man\~pages only the following characters should be used:
 771 `e', `p', and `t'.
 772 ..
 773 .
 774 .
 775 .\"
 776 .SH "WRITING MACROS"
 777 .\"
 778 .
 779 A
 780 .BR @L_ROFF@ (@MAN7EXT@)
 781 document is a text file that is enriched by predefined formatting
 782 constructs, such as requests, escape sequences, strings, numeric
 783 registers, and macros from a macro package.
 784 .
 785 These elements are described in
 786 .BR @L_ROFF@ (@MAN7EXT@).
 787 .
 788 .
 789 .P
 790 To give a document a personal style, it is most useful to extend the
 791 existing elements by defining some macros for repeating tasks; the best
 792 place for this is near the beginning of the document or in a separate
 793 file.
 794 .
 795 .
 796 .P
 797 Macros without arguments are just like strings.
 798 .
 799 But the full power of macros reveals when arguments are passed with a
 800 macro call.
 801 .
 802 Within the macro definition, the arguments are available as the escape
 803 sequences
 804 .BR \[rs]$1 ,
 805 \*[Ellipsis],
 806 .BR \[rs]$9 ,
 807 .BR \[rs]$[ \*[Ellipsis] ] ,
 808 .BR \[rs]$* ,
 809 and
 810 .BR \[rs]$@ ,
 811 the name under which the macro was called is in
 812 .BR \[rs]$0 ,
 813 and the number of arguments is in register
 814 .BR \[rs]n[.$] ;
 815 see
 816 .BR @L_ROFF@ (@MAN7EXT@).
 817 .
 818 .
 819 .\"
 820 .SS "Copy-in Mode"
 821 .\"
 822 .
 823 The phase when @T_ROFF@ reads a macro is called
 824 .I "copy-in mode"
 825 or
 826 .I "copy mode"
 827 in roff-talk.
 828 .
 829 This is comparable to the C\~preprocessing phase during the development
 830 of a program written in the C\~language.
 831 .
 832 .
 833 .P
 834 In this phase all backslashes are interpreted; that means that all
 835 escape sequences in the macro body are interpreted and replaced by
 836 their value.
 837 .
 838 For constant expressions, this is wanted, but strings and registers
 839 that might change between calls of the macro must be protected from
 840 being evaluated.
 841 .
 842 This is most easily done by doubling the backslash that introduces the
 843 escape sequence.
 844 .
 845 This doubling is most important for the positional parameters.
 846 .
 847 For example, to print information on the arguments that were passed to
 848 the macro to the terminal, define a macro named `.print_args',
 849 say.
 850 .
 851 .
 852 .IP
 853 .ds @1 \[rs]f[I]\[rs]\[rs]$0\[rs]f[]\"
 854 .ds @2 arguments:\"
 855 .EX
 856 \&.ds midpart was called with
 857 \&.de print_args
 858 \&.\ \ tm\ \*[@1]\ \[rs]*[midpart]\ \[rs]\[rs]n[.$]\ \*[@2]
 859 \&.\ \ tm\ \[rs]\[rs]$*
 860 \&..
 861 .EE
 862 .rm @1
 863 .rm @2
 864 .
 865 .
 866 .P
 867 When calling this macro by
 868 .
 869 .IP
 870 .EX
 871 \&.print_args arg1 arg2
 872 .EE
 873 .
 874 .P
 875 the following text is printed to the terminal:
 876 .
 877 .IP
 878 .EX
 879 \&\f[CI]print_args\f[] was called with the following 2 arguments:
 880 arg1 arg2
 881 .EE
 882 .
 883 .
 884 .P
 885 Let's analyze each backslash in the macro definition.
 886 .
 887 As the positional parameters and the number of arguments change
 888 with each call of the macro their leading backslash must be doubled,
 889 which results in
 890 .RI \[rs]\[rs] $*
 891 and
 892 .RI \[rs]\[rs] [.$] .
 893 The same applies to the macro name because it could be called with an
 894 alias name, so
 895 .RI \[rs]\[rs] $0 .
 896 .
 897 .
 898 .P
 899 On the other hand,
 900 .I midpart
 901 is a constant string, it does not change, so no doubling for
 902 .RI \[rs] *[midpart] .
 903 The
 904 .RI \[rs] f
 905 escape sequences are predefined elements for setting the font
 906 within the text.
 907 .
 908 Of course, this behavior does not change, so no doubling with
 909 .RI \[rs] f[I]
 910 and
 911 .RI \[rs] f[] .
 912 .
 913 .
 914 .\"
 915 .SS "Draft Mode"
 916 .\"
 917 .
 918 Writing macros is easy when the escaping mechanism is temporarily
 919 disabled.
 920 .
 921 This is done by enclosing the macro definition(s) into a pair of
 922 .B .eo
 923 and
 924 .B .ec
 925 requests.
 926 .
 927 Then the body in the macro definition is just like a normal part of
 928 the document \[em] text enhanced by calls of requests, macros,
 929 strings, registers, etc.
 930 .
 931 For example, the code above can be written in a simpler way by
 932 .
 933 .
 934 .IP
 935 .ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\"
 936 .ds @2 arguments:\"
 937 .EX
 938 \&.eo
 939 \&.ds midpart was called with
 940 \&.de print_args
 941 \&.\ \ tm\ \*[@1]\ \[rs]*[midpart]\ \[rs]n[.$]\ \*[@2]
 942 \&.\ \ tm\ \[rs]$*
 943 \&..
 944 \&.ec
 945 .EE
 946 .rm @1
 947 .rm @2
 948 .
 949 .
 950 .P
 951 Unfortunately, draft mode cannot be used universally.
 952 .
 953 Although it is good enough for defining normal macros, draft mode
 954 fails with advanced applications, such as indirectly defined
 955 strings, registers, etc.
 956 .
 957 An optimal way is to define and test all macros in draft mode and then
 958 do the backslash doubling as a final step; do not forget to remove the
 959 .I .eo
 960 request.
 961 .
 962 .
 963 .\"
 964 .SS "Tips for Macro Definitions"
 965 .\"
 966 .
 967 .IP \(bu
 968 Start every line with a dot, for example, by using the request
 969 .B .nop
 970 for text lines, or write your own macro that handles also text lines
 971 with a leading dot.
 972 .
 973 .RS
 974 .IP
 975 .EX
 976 \&.de Text
 977 \&.\ \ if (\[rs]\[rs]n[.$] == 0)\ \[rs]
 978 \&.\ \ \ \ return
 979 \&.\ \ nop\ \[rs])\[rs]\[rs]$*\[rs])
 980 \&..
 981 .EE
 982 .RE
 983 .
 984 .IP \(bu
 985 Write a comment macro that works both for copy-in and draft mode; for
 986 as escaping is off in draft mode, trouble might occur when normal
 987 comments are used.
 988 .
 989 For example, the following macro just ignores its arguments, so it
 990 acts like a comment line:
 991 .
 992 .RS
 993 .IP
 994 .EX
 995 \&.de\ c
 996 \&..
 997 \&.c\ This\ is\ like\ a\ comment\ line.
 998 .EE
 999 .RE
1000 .
1001 .IP \(bu
1002 In long macro definitions, make ample use of comment lines or
1003 almost-empty lines (this is, lines which have a leading dot
1004 and nothing else) for a better structuring.
1005 .
1006 .IP \(bu
1007 To increase readability, use the indentation facility for requests
1008 and macro calls (arbitrary whitespace after the leading dot).
1009 .
1010 .
1011 .\"
1012 .SS "Diversions"
1013 .\"
1014 .
1015 Diversions can be used to implement quite advanced programming
1016 constructs.
1017 .
1018 They are comparable to pointers to large data structures in the
1019 C\~programming language, but their usage is quite different.
1020 .
1021 .
1022 .P
1023 In their simplest form, diversions are multi-line strings, but
1024 they get their power when diversions are used dynamically within macros.
1025 .
1026 The (formatted) information stored in a diversion can be retrieved by
1027 calling the diversion just like a macro.
1028 .
1029 .
1030 .P
1031 Most of the problems arising with diversions can be avoided if you remain
1032 aware of the fact that diversions always store complete lines.
1033 .
1034 If diversions are used when the line buffer has not been flushed,
1035 strange results are produced; not knowing this, many people get
1036 desperate about diversions.
1037 .
1038 To ensure that a diversion works, line breaks should be added at the
1039 right places.
1040 .
1041 To be on the secure side, enclose everything that has to do with
1042 diversions into a pair of line breaks; for example, by explicitly using
1043 .B .br
1044 requests.
1045 .
1046 This rule should be applied to diversion definition, both inside and
1047 outside, and to all calls of diversions.
1048 .
1049 This is a bit of overkill, but it works nicely.
1050 .
1051 .
1052 .P
1053 [If you really need diversions which should ignore the current partial
1054 line, use environments to save the current partial line and/\:or use the
1055 .B .box
1056 request.]
1057 .
1058 .
1059 .P
1060 The most powerful feature using diversions is to start a diversion
1061 within a macro definition and end it within another macro.
1062 .
1063 Then everything between each call of this macro pair is stored within
1064 the diversion and can be manipulated from within the macros.
1065 .
1066 .
1067 .\"
1068 .SH FILES
1069 .\"
1070 .
1071 All macro names must be named
1072 .IB name .tmac
1073 to fully use the tmac mechanism.
1074 .
1075 .BI tmac. name
1076 as with classical packages is possible as well, but deprecated.
1077 .
1078 .
1079 .P
1080 The macro files are kept in the
1081 .IR "tmac directories" ;
1082 a colon separated list of these constitutes the
1083 .IR "tmac path" .
1084 .
1085 .
1086 .P
1087 The search sequence for macro files is (in that order):
1088 .
1089 .IP \(bu
1090 the directories specified with the
1091 .B \-M
1092 command line option
1093 .
1094 .IP \(bu
1095 the directories given in the
1096 .B $@U_ROFF@_TMAC_PATH
1097 environment variable
1098 .
1099 .IP \(bu
1100 the current directory (only if in unsafe mode, which is enabled by the
1101 .B \-U
1102 command line switch)
1103 .
1104 .IP \(bu
1105 the home directory
1106 .
1107 .IP \(bu
1108 a platform-specific directory, being
1109 .
1110 .RS
1111 .IP
1112 .B @SYSTEMMACRODIR@
1113 .RE
1114 .
1115 .IP
1116 in this installation
1117 .
1118 .IP \(bu
1119 a site-specific (platform-independent) directory, being
1120 .
1121 .RS
1122 .IP
1123 .B @LOCALMACRODIR@
1124 .RE
1125 .
1126 .IP
1127 in this installation
1128 .
1129 .IP \(bu
1130 the main tmac directory, being
1131 .
1132 .RS
1133 .IP
1134 .B @MACRODIR@
1135 .RE
1136 .
1137 .IP
1138 in this installation
1139 .
1140 .
1141 .\"
1142 .SH ENVIRONMENT
1143 .\"
1144 .
1145 .TP
1146 .B $@U_ROFF@_TMAC_PATH
1147 A colon separated list of additional tmac directories in which to search
1148 for macro files.
1149 .
1150 See the previous section for a detailed description.
1151 .
1152 .
1153 .\"
1154 .SH AUTHOR
1155 .\"
1156 .
1157 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
1158
1159 Copyright (C) 2000 - 2004, 2006 - 2009
1160 Free Software Foundation, Inc.
1161 .
1162 .P
1163 This document is distributed under the terms of the FDL (GNU Free
1164 Documentation License) version 1.1 or later.
1165 .
1166 You should have received a copy of the FDL on your system, it is also
1167 available on-line at the
1168 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1169 GNU copyleft site
1170 .UE .
1171 .
1172 .P
1173 This document was written by
1174 .MT bwarken@mayn.de
1175 Bernd Warken
1176 .ME .
1177 .
1178 .\"
1179 .SH "SEE ALSO"
1180 .\"
1181 .
1182 .BR @L_ROFF@ (@MAN1EXT@)
1183 an overview of the @T_ROFF@ system.
1184 .
1185 .
1186 .TP
1187 .BR @L_ROFF@-man (@MAN7EXT@),
1188 .TQ
1189 .BR @L_ROFF@-mdoc (@MAN7EXT@),
1190 .TQ
1191 .BR @L_ROFF@-me (@MAN7EXT@),
1192 .TQ
1193 .BR @L_ROFF@-mm (@MAN7EXT@),
1194 .TQ
1195 .BR @L_ROFF@-ms (@MAN7EXT@),
1196 .TQ
1197 .BR @L_ROFF@-trace (@MAN7EXT@),
1198 .TQ
1199 .BR @L_ROFF@-www (@MAN7EXT@).
1200 the @T_ROFF@ tmac macro packages.
1201 .
1202 .
1203 .TP
1204 .BR @L_ROFF@ (@MAN7EXT@)
1205 the @T_ROFF@ language.
1206 .
1207 .
1208 .P
1209 The Filesystem Hierarchy Standard is available at the
1210 .UR http://\:www.pathname.com/\:fhs/
1211 FHS web site
1212 .UE .
1213 .
1214 .\" s-ts-mode