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