contrib/groff-1.19/man/groff_tmac.man

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