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