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