Debian Codegraph @

upstream/opensuse-tumbleweed/man5/groff_tmac.5

raw
1 .TH groff_tmac 5 "2 March 2026" "groff 1.23.0"
2 .SH Name
3 groff_tmac \- macro files in the GNU
4 .I roff
5 typesetting system
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright (C) 2000-2022 Free Software Foundation, Inc.
13 .\"
14 .\" This file is part of groff, the GNU roff typesetting system.
15 .\"
16 .\" Permission is granted to copy, distribute and/or modify this
17 .\" document under the terms of the GNU Free Documentation License,
18 .\" Version 1.3 or any later version published by the Free Software
19 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
20 .\" and with no Back-Cover Texts.
21 .\"
22 .\" A copy of the Free Documentation License is included as a file
23 .\" called FDL in the main directory of the groff source package.
24 .
25 .
26 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
27 .do nr *groff_groff_tmac_5_man_C \n[.cp]
28 .cp 0
29 .
30 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
31 .nr do-fallback 0
32 .if !\n(.f .nr do-fallback 1 \" mandoc
33 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
34 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
35 .if \n[do-fallback] \{\
36 . de MR
37 . ie \\n(.$=1 \
38 . I \%\\$1
39 . el \
40 . IR \%\\$1 (\\$2)\\$3
41 . .
42 .\}
43 .rr do-fallback
44 .
45 .
46 .\" TODO: Consider parallelizing with our Texinfo node "Macro Packages".
47 .\" ====================================================================
48 .SH Description
49 .\" ====================================================================
50 .
51 Definitions of macros,
52 strings,
53 and registers for use in a
54 .MR roff 7
55 document can be collected into
56 .IR "macro files" ,
57 .I roff
58 input files designed to produce no output themselves but instead ease
59 the preparation of other
60 .I roff
61 documents.
62 .
63 There is no syntactical difference between a macro file and any other
64 .I roff
65 document;
66 only its purpose distinguishes it.
67 .
68 When a macro file is installed at a standard location,
69 named according to a certain convention,
70 and suitable for use by a general audience,
71 it is termed a
72 .IR "macro package" .
73 .
74 Macro packages can be loaded by supplying the
75 .B \-m
76 option to
77 .MR \%troff 1
78 or a
79 .I groff
80 front end.
81 .
82 .
83 .P
84 Each macro package stores its macro,
85 string,
86 and register definitions in one or more
87 .I tmac
88 files.
89 .
90 This name originated in early Unix culture as an abbreviation of
91 .RI \[lq] troff \" generic
92 macros\[rq].
93 .
94 .
95 .P
96 A macro file must have a name in the form
97 .RI name .tmac
98 (or
99 .IR tmac. name)
100 and be placed in a
101 .RI \[lq] tmac
102 directory\[rq] to be loadable with the
103 .BI \-m name
104 option.
105 .
106 Section \[lq]Environment\[rq] of
107 .MR \%troff 1
108 lists these directories.
109 .
110 Alternatively,
111 a
112 .I groff
113 document requiring a macro file can load it with the
114 .B mso
115 (\[lq]macro source\[rq]) request.
116 .
117 .
118 .P
119 Like any other
120 .I roff
121 document,
122 a macro file can use the
123 .RB \[lq] so \[rq]
124 request (\[lq]source\[rq]) to load further files relative to its own
125 location.
126 .
127 .
128 .P
129 Macro files are named for their most noteworthy application,
130 but a macro file need not define any macros.
131 .
132 It can restrict itself to defining registers and strings or invoking
133 other
134 .I groff
135 requests.
136 .
137 It can even be empty.
138 .
139 .
140 .\" ====================================================================
141 .SH "Macro packages"
142 .\" ====================================================================
143 .
144 Macro packages come in two varieties;
145 those which assume responsibility for page layout and other critical
146 functions
147 (\[lq]major\[rq] or \[lq]full-service\[rq])
148 and those which do not
149 (\[lq]supplemental\[rq] or \[lq]auxiliary\[rq]).
150 .
151 GNU
152 .I roff
153 provides most major macro packages found in AT&T and BSD Unix systems,
154 an additional full-service package,
155 and many supplemental packages.
156 .
157 Multiple full-service macro packages cannot be used by the same
158 document.
159 .
160 Auxiliary packages can generally be freely combined,
161 though attention to their use of the
162 .I groff
163 language name spaces for identifiers
164 (particularly registers,
165 macros,
166 strings,
167 and diversions)
168 should be paid.
169 .
170 Name space management was a significant challenge in AT&T
171 .IR troff ;
172 .IR groff 's
173 support for arbitrarily long identifiers affords few excuses for name
174 collisions,
175 apart from attempts at compatibility with the demands of historical
176 documents.
177 .
178 .
179 .\" ====================================================================
180 .SS "Man pages"
181 .\" ====================================================================
182 .
183 .TP
184 .I an
185 .TQ
186 .I man
187 .I an
188 is used to compose man pages in the format originating in Version\~7
189 Unix (1979).
190 .
191 It has a small macro interface and is widely used;
192 see
193 .MR groff_man 7 .
194 .
195 .
196 .TP
197 .I doc
198 .TQ
199 .I mdoc
200 .I doc
201 is used to compose man pages in the format originating in 4.3BSD-Reno
202 (1990).
203 .
204 It provides many more features than
205 .IR an ,
206 but is also larger,
207 more complex,
208 and not as widely adopted;
209 see
210 .MR groff_mdoc 7 .
211 .
212 .
213 .P
214 Because readers of man pages often do not know in advance which macros
215 are used to format a given document,
216 a wrapper is available.
217 .
218 .
219 .TP
220 .I \%andoc
221 .TQ
222 .I mandoc
223 This macro file,
224 specific to
225 .IR groff ,
226 recognizes whether a document uses
227 .I man
228 or
229 .I mdoc
230 format and loads the corresponding macro package.
231 .
232 Multiple man pages,
233 in either format,
234 can be handled;
235 .I \%andoc
236 reloads each macro package as necessary.
237 .
238 .
239 .\" ====================================================================
240 .SS "Full-service packages"
241 .\" ====================================================================
242 .
243 The packages in this section provide a complete set of macros for
244 writing documents of any kind, up to whole books.
245 .
246 They are similar in functionality; it is a matter of taste which one
247 to use.
248 .
249 .
250 .TP
251 .I me
252 The classical
253 .I me
254 macro package; see
255 .MR groff_me 7 .
256 .
257 .
258 .TP
259 .I mm
260 The semi-classical
261 .I mm
262 macro package; see
263 .MR groff_mm 7 .
264 .
265 .
266 .TP
267 .I mom
268 The
269 .I mom
270 macro package, only available in groff.
271 .
272 As this was not based on other packages, it was freely designed as
273 quite a nice, modern macro package.
274 .
275 See
276 .MR groff_mom 7 .
277 .
278 .
279 .TP
280 .I ms
281 The classical
282 .I ms
283 macro package; see
284 .MR groff_ms 7 .
285 .
286 .
287 .\" ====================================================================
288 .SS "Localization packages"
289 .\" ====================================================================
290 .
291 For Western languages,
292 the localization file sets the hyphenation mode and loads hyphenation
293 patterns and exceptions.
294 .
295 Localization files can also adjust the date format and provide
296 translations of strings used by some of the full-service macro packages;
297 alter the input encoding
298 (see the next section);
299 and change the amount of additional inter-sentence space.
300 .
301 For Eastern languages,
302 the localization file defines character classes and sets flags on them.
303 .
304 By default,
305 .I troffrc
306 loads the localization file for English.
307 .
308 .
309 .TP
310 .I trans
311 loads localized strings used by various macro packages after their
312 localized forms have been prepared by a localization macro file.
313 .
314 .
315 .P
316 .I groff
317 provides the following localization files.
318 .
319 .
320 .TP
321 .I cs
322 Czech;
323 localizes
324 .IR man ,
325 .IR me ,
326 .IR mm ,
327 .IR mom ,
328 and
329 .IR ms .
330 .
331 Sets the input encoding to Latin-2 by loading
332 .IR latin2.tmac .
333 .
334 .
335 .TP
336 .I de
337 .TQ
338 .I den
339 German;
340 localizes
341 .IR man ,
342 .IR me ,
343 .IR mm ,
344 .IR mom ,
345 and
346 .IR ms .
347 .
348 Sets the input encoding to Latin-1 by loading
349 .IR latin1.tmac .
350 .
351 .
352 .IP
353 .I de.tmac
354 selects hyphenation patterns for traditional orthography,
355 and
356 .I den.tmac
357 does the same for the new orthography
358 (\[lq]Recht\%schreib\%reform\[rq]).
359 .
360 .
361 .TP
362 .I en
363 English.
364 .
365 .
366 .TP
367 .I fr
368 French;
369 localizes
370 .IR man ,
371 .IR me ,
372 .IR mm ,
373 .IR mom ,
374 and
375 .IR ms .
376 .
377 Sets the input encoding to Latin-9 by loading
378 .IR latin9.tmac .
379 .
380 .
381 .TP
382 .I it
383 Italian;
384 localizes
385 .IR man ,
386 .IR me ,
387 .IR mm ,
388 .IR mom ,
389 and
390 .IR ms .
391 .
392 .
393 .TP
394 .I ja
395 Japanese.
396 .
397 .
398 .TP
399 .I sv
400 Swedish;
401 localizes
402 .IR man ,
403 .IR me ,
404 .IR mm ,
405 .IR mom ,
406 and
407 .IR ms .
408 .
409 Sets the input encoding to Latin-1 by loading
410 .IR latin1.tmac .
411 .
412 Some of the localization of the
413 .I mm
414 package is handled separately;
415 see
416 .MR groff_mmse 7 .
417 .
418 .
419 .TP
420 .I zh
421 Chinese.
422 .
423 .
424 .\" ====================================================================
425 .SS "Input encodings"
426 .\" ====================================================================
427 .
428 .TP
429 .I latin1
430 .TQ
431 .I latin2
432 .TQ
433 .I latin5
434 .TQ
435 .I latin9
436 are various ISO\~8859 input encodings supported by
437 .IR groff .
438 .
439 On systems using ISO character encodings,
440 .I groff
441 loads
442 .I latin1.tmac
443 automatically at startup.
444 .
445 A document that uses Latin-2,
446 Latin-5,
447 or Latin-9
448 can specify one of these alternative encodings.
449 .
450 .
451 .TP
452 .I cp1047
453 provides support for EBCDIC-based systems.
454 .
455 On those platforms,
456 .I groff
457 loads
458 .I cp1047.tmac
459 automatically at startup.
460 .
461 .
462 .P
463 Because different input character codes constitute valid GNU
464 .I troff \" GNU
465 input on ISO and EBCDIC systems,
466 the
467 .I latin
468 macro files cannot be used on EBCDIC systems,
469 and
470 .I cp1047
471 cannot be used on ISO systems.
472 .
473 .
474 .\" ====================================================================
475 .SS "Auxiliary packages"
476 .\" ====================================================================
477 .
478 The macro packages in this section are not intended for stand-alone
479 use,
480 but can add functionality to any other macro package or to plain
481 (\[lq]raw\[rq])
482 .I groff
483 documents.
484 .
485 .
486 .\" TODO:
487 .\" a4
488 .\" devtag
489 .\" doc-old
490 .\" europs
491 .\" psatk
492 .\" psfig
493 .TP
494 .I 62bit
495 provides macros for addition,
496 multiplication,
497 and division of 62-bit integers
498 (allowing safe multiplication of signed 31-bit integers,
499 for example).
500 .
501 .
502 .TP
503 .I hdtbl
504 allows the generation of tables using a syntax similar to the HTML table
505 model.
506 .
507 This Heidelberger table macro package is not a preprocessor,
508 which can be useful if the contents of table entries are determined by
509 macro calls or string interpolations.
510 .
511 Compare to
512 .MR \%tbl 1 .
513 .
514 It works only with the
515 .B ps
516 and
517 .B pdf
518 output devices.
519 .
520 See
521 .MR groff_hdtbl 7 .
522 .
523 .
524 .TP
525 .I papersize
526 enables the paper format to be set on the command line by giving a
527 .RB \[lq] \-d
528 .BI \%paper= format\c
529 \[rq]
530 option to
531 .IR \%troff .
532 .
533 Possible values for
534 .I format
535 are the ISO and DIN formats
536 .RB \[lq] A0 \[en] A6 \[rq],
537 .RB \[lq] B0 \[en] B6 \[rq],
538 .RB \[lq] C0 \[en] C6 \[rq],
539 and
540 .RB \[lq] D0 \[en] D6 \[rq];
541 .\" XXX: src/libs/libgroff/paper.cpp also supports [ABCD]7.
542 the U.S.\& formats
543 .RB \%\[lq] letter \[rq],
544 .RB \%\[lq] legal \[rq],
545 .RB \%\[lq] tabloid \[rq],
546 .RB \%\[lq] ledger \[rq],
547 .RB \%\[lq] statement \[rq],
548 and
549 .RB \%\[lq] executive \[rq];
550 and the envelope formats
551 .RB \%\[lq] com10 \[rq],
552 .RB \%\[lq] monarch \[rq],
553 and
554 .RB \%\[lq] DL \[rq].
555 .
556 All formats,
557 even those for envelopes,
558 are in portrait orientation:
559 the length measurement is vertical.
560 .
561 Appending \[lq]l\[rq] (ell) to any of these denotes landscape
562 orientation instead.
563 .
564 This macro file assumes one-inch horizontal margins,
565 and sets registers recognized by the
566 .I groff
567 .IR man ,
568 .IR mdoc ,
569 .IR mm ,
570 .IR mom ,
571 and
572 .I ms
573 packages to configure them accordingly.
574 .
575 If you want different margins,
576 you will need to use those packages' facilities,
577 or
578 .I \%troff
579 .B ll
580 and/or
581 .B po
582 requests to adjust them.
583 .
584 An output device typically requires command-line options
585 .B \-p
586 and
587 .B \-l
588 to override the paper dimensions and orientation,
589 respectively,
590 defined in its
591 .I DESC
592 file;
593 see subsection \[lq]Paper format\[rq]
594 of
595 .MR groff 1 .
596 .
597 This macro file is normally loaded at startup by the
598 .I troffrc
599 file when formatting for a typesetting device
600 (but not a terminal).
601 .
602 .
603 .TP
604 .I pdfpic
605 provides a single macro,
606 .BR PDFPIC ,
607 to include a PDF graphic in a document using features of the
608 .B pdf
609 output driver.
610 .
611 For other output devices,
612 .B PDFPIC
613 calls
614 .BR PSPIC ,
615 with which it shares an interface
616 (see below).
617 .
618 This macro file is normally loaded at startup by the
619 .I troffrc
620 file.
621 .
622 .
623 .TP
624 .I pic
625 supplies definitions of the macros
626 .BR PS ,
627 .BR PE ,
628 and
629 .BR PF ,
630 usable with the
631 .MR \%pic 1
632 preprocessor.
633 .
634 They center each picture.
635 .
636 Use it if your document does not use a full-service macro package,
637 or that package does not supply working
638 .I pic
639 macro definitions.
640 .
641 Except for
642 .I man
643 and
644 .IR mdoc ,
645 those provided with
646 .I groff
647 already do so
648 (exception:
649 .I mm
650 employs the name
651 .B PF
652 for a different purpose).
653 .
654 .
655 .TP
656 .I pspic
657 provides a macro,
658 .BR PSPIC ,
659 that includes a PostScript graphic in a document.
660 .
661 The
662 .BR ps ,
663 .BR dvi ,
664 .BR html ,
665 and
666 .B xhtml
667 output devices support such inclusions;
668 for all other drivers,
669 the image is replaced with a rectangular border of the same size.
670 .
671 .I pspic.tmac
672 is loaded at startup by the
673 .I troffrc
674 file.
675 .
676 .
677 .IP
678 Its syntax is as follows.
679 .RS
680 .IP
681 \&\fB.PSPIC\fP \
682 [\fB\-L\fP\|\
683 |\|\fB\-R\fP\|\
684 |\|\fB\-C\fP\|\
685 |\|\fB\-I\fP\~\fIn\fP] \
686 \fI\|file\fP [\fIwidth\fP [\,\fIheight\/\fP]]
687 .RE
688 .
689 .
690 .IP
691 .I file
692 is the name of the PostScript file;
693 .I width
694 and
695 .I height
696 give the desired width and height of the image.
697 .
698 If neither a
699 .I width
700 nor a
701 .I height
702 argument is specified,
703 the image's natural width
704 (as given in the file's bounding box)
705 or the current line length is used as the width,
706 whatever is smaller.
707 .
708 The
709 .I width
710 and
711 .I height
712 arguments may have scaling units attached;
713 the default scaling unit
714 .RB is\~ i .
715 .
716 .B PSPIC
717 scales the graphic uniformly in the horizontal and vertical directions
718 so that it is no more than
719 .I width
720 wide
721 and
722 .I height
723 high.
724 .
725 Option
726 .B \-C
727 centers the graphic horizontally;
728 this is the default.
729 .
730 .B \-L
731 and
732 .B \-R
733 left- and right-align the graphic,
734 respectively.
735 .
736 .B \-I
737 indents the graphic
738 .RI by\~ n
739 (with a default scaling unit
740 .RB of\~ m ).
741 .
742 .
743 .IP
744 To use
745 .B PSPIC
746 within a diversion,
747 we recommend extending it with the following code,
748 assuring that the diversion's width completely covers the image's width.
749 .
750 .
751 .RS
752 .IP
753 .EX
754 \&.am PSPIC
755 \&.\~\~vpt 0
756 \&\[rs]h\[aq](\[rs]\[rs]n[ps\-offset]u + \[rs]\[rs]n[ps\-deswid]u)\[aq]
757 \&.\~\~sp \-1
758 \&.\~\~vpt 1
759 \&..
760 .EE
761 .RE
762 .
763 .
764 .IP
765 Failure to load
766 .BR PSPIC 's
767 image argument is not an error.
768 .
769 (The
770 .B psbb
771 request does issue an error diagnostic.)
772 .
773 To make such a failure fatal,
774 append to the
775 .B pspic*error\-hook
776 macro.
777 .
778 .
779 .RS
780 .IP
781 .EX
782 \&.am pspic*error\-hook
783 \&.\~\~ab
784 \&..
785 .EE
786 .RE
787 .
788 .
789 .TP
790 .I ptx
791 provides a macro,
792 .BR xx ,
793 to format permuted index entries as produced by the GNU
794 .MR ptx 1
795 program.
796 .
797 If your formatting needs differ,
798 copy the macro into your document and adapt it to your needs.
799 .
800 .
801 .TP
802 .I rfc1345
803 defines special character escape sequences named for the glyph mnemonics
804 specified in RFC\~1345 and the digraph table of the Vim text editor.
805 .
806 See
807 .MR groff_rfc1345 7 .
808 .
809 .
810 .TP
811 .I sboxes
812 offers an interface to the
813 .RB \[lq] "pdf: background" \[rq]
814 device control command supported by
815 .MR gropdf 1 .
816 .
817 Using this package,
818 .I groff ms
819 documents can draw colored rectangles beneath any output.
820 .
821 .RS
822 .TP
823 .BI \%.BOXSTART\~SHADED\~ color\~\c
824 .BI \%OUTLINED\~ color\~\c
825 .BI \%INDENT\~ size\~\c
826 .BI \%WEIGHT\~ size
827 begins a box,
828 where the argument after
829 .B \%SHADED
830 gives the fill color and that after
831 .B \%OUTLINED
832 the border color.
833 .
834 Omit the former to get a borderless filled box and the latter for a
835 border with no fill.
836 .
837 The specified
838 .B \%WEIGHT
839 is used if the box is
840 .BR \%OUTLINED .
841 .
842 .
843 .IP
844 .B \%INDENT
845 precedes a value which leaves a gap between the border and the contents
846 inside the box.
847 .
848 .
849 .IP
850 Each
851 .I color
852 must be a defined
853 .I groff
854 color name,
855 and each
856 .I size
857 a valid
858 .I groff
859 numeric expression.
860 .
861 The keyword/value pairs can be specified in any order.
862 .RE
863 .
864 .
865 .IP
866 Boxes can be stacked,
867 so you can start a box within another box;
868 usually the later boxes would be smaller than the containing box,
869 but this is not enforced.
870 .
871 When using
872 .BR \%BOXSTART ,
873 the left position is the current indent minus the
874 .B \%INDENT
875 in the command,
876 and the right position is the left position
877 (calculated above)
878 plus the current line length and twice the indent.
879 .
880 .
881 .RS
882 .TP
883 .B \%.BOXSTOP
884 takes no parameters.
885 .
886 It closes the most recently started box at the current vertical position
887 after adding its
888 .B \%INDENT
889 spacing.
890 .RE
891 .
892 .
893 .IP
894 Your
895 .I groff
896 documents can conditionally exercise the
897 .I sboxes
898 macros.
899 .
900 The register
901 .B \%GSBOX
902 is defined if the package is loaded,
903 and interpolates a true value if the
904 .B pdf
905 output device is in use.
906 .
907 .
908 .IP
909 .I sboxes
910 furthermore hooks into the
911 .MR groff_ms 7
912 package to receive notifications when footnotes are growing,
913 so that it can close boxes on a page before footnotes are printed.
914 .
915 When that condition obtains,
916 .I sboxes
917 will close open boxes two points
918 above the footnote separator and re-open them on the next page.
919 .
920 (This amount probably will not match the box's
921 .BR \%INDENT .)
922 .
923 .
924 .IP
925 See
926 .UR file:///usr/\:\%share/\:\%doc/\:\%packages/\:\%groff/\:\%msboxes\:.pdf
927 \[lq]Using PDF boxes with
928 .I groff
929 and the
930 .I ms
931 macros\[rq]
932 .UE
933 for a demonstration.
934 .
935 .
936 .TP
937 .I trace
938 aids the debugging of
939 .I groff
940 documents by tracing macro calls.
941 .
942 See
943 .MR groff_trace 7 .
944 .
945 .
946 .TP
947 .I www
948 defines macros corresponding to HTML elements.
949 .
950 See
951 .MR groff_www 7 .
952 .
953 .
954 .\" ====================================================================
955 .SH Naming
956 .\" ====================================================================
957 .
958 AT&T
959 .I nroff \" AT&T
960 and
961 .I troff \" AT&T
962 were implemented before the conventions of the modern C
963 .MR getopt 3
964 call evolved,
965 and used a naming scheme for macro packages that looks odd to modern
966 eyes.
967 .
968 Macro packages were typically loaded using the
969 .B \-m
970 option to the formatter;
971 when directly followed by its argument without an intervening space,
972 this looked like a long option preceded by a single minus\[em]a
973 sensation in the computer stone age.
974 .
975 Macro packages therefore came to be known by names that started with the
976 letter \[lq]m\[rq],
977 which was omitted from the name of the macro file as stored on disk.
978 .
979 For example,
980 the manuscript macro package was stored as
981 .I tmac.s
982 and loaded with the option
983 .BR \-ms .
984 .
985 .
986 .P
987 .I groff
988 commands permit space between an option and its argument.
989 .
990 The syntax
991 .RB \[lq] "groff \-m s" \[rq]
992 makes the macro file name more clear but may surprise users familiar
993 with the original convention,
994 unaware that the package's \[lq]real\[rq] name was \[lq]s\[rq] all
995 along.
996 .
997 For such packages of long pedigree,
998 .I groff
999 accommodates different users' expectations by supplying wrapper macro
1000 files that load the desired file with
1001 .B mso
1002 requests.
1003 .
1004 Thus,
1005 all of
1006 .RB \[lq] "groff \-m s" \[rq],
1007 .RB \[lq] "groff \-m ms" \[rq],
1008 .RB \[lq] "groff \-ms" \[rq],
1009 and
1010 .RB \[lq] "groff \-mms" \[rq]
1011 serve to load the manuscript macros.
1012 .
1013 .
1014 .P
1015 Wrappers are not provided for packages of more recent vintage,
1016 like
1017 .IR www.tmac .
1018 .
1019 .
1020 .P
1021 As noted in passing above,
1022 AT&T
1023 .I troff \" AT&T
1024 named macro files in the form
1025 .IR tmac. name.
1026 .
1027 It has since become conventional in operating systems to use a suffixed
1028 file name extension to suggest a file type or format.
1029 .
1030 .
1031 .\" ====================================================================
1032 .SH Inclusion
1033 .\" ====================================================================
1034 .
1035 The traditional method of employing a macro package is to specify the
1036 .B \-m
1037 .I package
1038 option to the formatter,
1039 which then reads
1040 .IR package 's
1041 macro file prior to any input files.
1042 .
1043 Historically,
1044 .I package
1045 was sought in a file named
1046 .IR tmac. package
1047 (that is,
1048 with a
1049 .RB \[lq] tmac.\& \[rq]
1050 prefix).
1051 .
1052 GNU
1053 .I troff \" GNU
1054 searches for
1055 .RI package .tmac
1056 in the macro path;
1057 if not found,
1058 it looks for
1059 .IR tmac. package
1060 instead,
1061 and vice versa.
1062 .
1063 .
1064 .P
1065 Alternatively,
1066 one could include a macro file by using the request
1067 .RB \[lq] .so
1068 .IR file-name \[rq]
1069 in the document;
1070 .I file-name
1071 is resolved relative to the location of the input document.
1072 .
1073 GNU
1074 .I troff \" GNU
1075 offers an improved feature in the similar request
1076 .RB \[lq] mso
1077 .IR package-file-name \[rq],
1078 which searches the macro path for
1079 .IR package-file-name .
1080 .
1081 Because its argument is a file name,
1082 its
1083 .RB \[lq] .tmac \[rq]
1084 component must be included for the file to be found;
1085 however,
1086 as a convenience,
1087 if opening it fails,
1088 .B mso
1089 strips any such suffix and tries again with a
1090 .RB \[lq] tmac.\& \[rq]
1091 prefix,
1092 and vice versa.
1093 .
1094 .
1095 .P
1096 If a sourced file requires preprocessing,
1097 for example if it includes
1098 .I tbl \" generic
1099 tables
1100 or
1101 .I eqn \" generic
1102 equations,
1103 the preprocessor
1104 .MR \%soelim 1
1105 must be used.
1106 .
1107 This can be achieved with a pipeline or,
1108 in
1109 .IR groff ,
1110 by specifying
1111 the
1112 .B \-s
1113 option to the formatter
1114 (or front end).
1115 .
1116 .MR man 1
1117 librarian programs generally call
1118 .I \%soelim
1119 automatically.
1120 .
1121 (Macro packages themselves generally do not require preprocessing.)
1122 .
1123 .
1124 .ig
1125 .\" ====================================================================
1126 .SH Convention
1127 .\" ====================================================================
1128 .
1129 .\" This section does not fit into the framework of this document.
1130 .
1131 There is a convention that is supported by many modern roff
1132 typesetters and
1133 .MR man 1
1134 programs, the
1135 .I preprocessor word
1136 described in the following.
1137 .
1138 .P
1139 If the first line in a document is a comment, the first word (after the
1140 comment characters and a blank) constitutes the
1141 .B preprocessor
1142 .BR word .
1143 That means that the letters of this word are interpreted as
1144 abbreviations for those preprocessor commands that should be run
1145 when formatting the document.
1146 .
1147 Mostly, only the letters corresponding to the options for the
1148 preprocessors are recognized,
1149 \[oq]e\[cq]
1150 (for
1151 .IR eqn ),
1152 .\" \[oq]G\[cq],
1153 .\" \[oq]g\[cq],
1154 \[oq]p\[cq]
1155 (for
1156 .IR pic ),
1157 \[oq]R\[cq]
1158 (for
1159 .IR refer ),
1160 \[oq]s\[cq]
1161 (for
1162 .IR soelim ),
1163 and
1164 \[oq]t\[cq]
1165 (for
1166 .IR tbl ).
1167 (see
1168 .MR roff 7 ).
1169 .
1170 .
1171 .P
1172 Besides being a good reminder for the user, some formatters (like the
1173 .MR man 1
1174 program) are even able to automatically start the preprocessors
1175 specified in the preprocessor word, but do not bet on this.
1176 .
1177 .
1178 .P
1179 The
1180 .I man
1181 program handles some preprocessors automatically, such that in
1182 man\~pages only the following characters should be used:
1183 \[oq]e\[cq], \[oq]p\[cq], and \[oq]t\[cq].
1184 .
1185 .
1186 ..
1187 .\" ====================================================================
1188 .SH "Writing macros"
1189 .\" ====================================================================
1190 .
1191 A
1192 .MR roff 7
1193 document is a text file that is enriched by predefined formatting
1194 constructs, such as requests, escape sequences, strings, numeric
1195 registers, and macros from a macro package.
1196 .
1197 These elements are described in
1198 .MR roff 7 .
1199 .
1200 .
1201 .P
1202 To give a document a personal style, it is most useful to extend the
1203 existing elements by defining some macros for repeating tasks; the best
1204 place for this is near the beginning of the document or in a separate
1205 file.
1206 .
1207 .
1208 .P
1209 Macros without arguments are just like strings.
1210 .
1211 But the full power of macros occurs when arguments are passed with a
1212 macro call.
1213 .
1214 Within the macro definition, the arguments are available as the escape
1215 sequences
1216 .BR \[rs]$1 ,
1217 \&.\|.\|.,
1218 .BR \[rs]$9 ,
1219 .BR \[rs]$[ .\|.\|. ] ,
1220 .BR \[rs]$* ,
1221 and
1222 .BR \[rs]$@ ,
1223 the name under which the macro was called is in
1224 .BR \[rs]$0 ,
1225 and the number of arguments is in register
1226 .BR \[rs]n[.$] ;
1227 see
1228 .MR groff 7 .
1229 .
1230 .
1231 .\" ====================================================================
1232 .SS "Draft mode"
1233 .\" ====================================================================
1234 .
1235 Writing groff macros is easy when the escaping mechanism is temporarily
1236 disabled.
1237 .
1238 In groff, this is done by enclosing the macro definition(s) within a
1239 pair of
1240 .B .eo
1241 and
1242 .B .ec
1243 requests.
1244 .
1245 Then the body in the macro definition is just like a normal part of
1246 the document \[em] text enhanced by calls of requests, macros,
1247 strings, registers, etc.
1248 .
1249 For example, the code above can be written in a simpler way by
1250 .
1251 .
1252 .IP
1253 .ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\"
1254 .ds @2 arguments:\"
1255 .EX
1256 \&.eo
1257 \&.ds midpart was called with the following
1258 \&.de print_args
1259 \&\*[@1]\ \[rs]*[midpart]\ \[rs]n[.$]\ \*[@2]
1260 \&\[rs]$*
1261 \&..
1262 \&.ec
1263 .EE
1264 .rm @1
1265 .rm @2
1266 .
1267 .
1268 .P
1269 Unfortunately, draft mode cannot be used universally.
1270 .
1271 Although it is good enough for defining normal macros, draft mode
1272 fails with advanced applications, such as indirectly defined
1273 strings, registers, etc.
1274 .
1275 An optimal way is to define and test all macros in draft mode and then
1276 do the backslash doubling as a final step; do not forget to remove the
1277 .I .eo
1278 request.
1279 .
1280 .
1281 .\" ====================================================================
1282 .SS "Tips for macro definitions"
1283 .\" ====================================================================
1284 .
1285 .IP \(bu
1286 Start every line with a dot, for example, by using the groff request
1287 .B .nop
1288 for text lines, or write your own macro that handles also text lines
1289 with a leading dot.
1290 .
1291 .RS
1292 .IP
1293 .EX
1294 \&.de Text
1295 \&.\ \ if (\[rs]\[rs]n[.$] == 0)\ \[rs]
1296 \&.\ \ \ \ return
1297 \&.\ \ nop\ \[rs])\[rs]\[rs]$*\[rs])
1298 \&..
1299 .EE
1300 .RE
1301 .
1302 .IP \(bu
1303 Write a comment macro that works both for copy and draft modes;
1304 since the escape character is off in draft mode,
1305 trouble might occur when comment escape sequences are used.
1306 .
1307 For example, the following macro just ignores its arguments, so it
1308 acts like a comment line:
1309 .
1310 .RS
1311 .IP
1312 .EX
1313 \&.de\ c
1314 \&..
1315 \&.c\ This\ is\ like\ a\ comment\ line.
1316 .EE
1317 .RE
1318 .
1319 .IP \(bu
1320 In long macro definitions, make ample use of comment lines or
1321 almost-empty lines (this is, lines which have a leading dot
1322 and nothing else) for a better structuring.
1323 .
1324 .IP \(bu
1325 To increase readability, use groff's indentation facility for
1326 requests and macro calls (arbitrary whitespace after the leading dot).
1327 .
1328 .
1329 .\" ====================================================================
1330 .SS Diversions
1331 .\" ====================================================================
1332 .
1333 Diversions can be used to implement quite advanced programming
1334 constructs.
1335 .
1336 They are comparable to pointers to large data structures in the
1337 C\~programming language, but their usage is quite different.
1338 .
1339 .
1340 .P
1341 In their simplest form, diversions are multi-line strings, but
1342 diversions get their power when used dynamically within macros.
1343 .
1344 The (formatted) information stored in a diversion can be retrieved by
1345 calling the diversion just like a macro.
1346 .
1347 .
1348 .P
1349 Most of the problems arising with diversions can be avoided if you
1350 remember that diversions always store complete lines.
1351 .
1352 Using diversions when the line buffer has not been flushed produces
1353 strange results; not knowing this, many people get desperate about
1354 diversions.
1355 .
1356 To ensure that a diversion works, add line breaks at the right
1357 places.
1358 .
1359 To be safe, enclose everything that has to do with diversions within
1360 a pair of line breaks; for example, by explicitly using
1361 .B .br
1362 requests.
1363 .
1364 This rule should be applied to diversion definition, both inside and
1365 outside, and to all calls of diversions.
1366 .
1367 This is a bit of overkill, but it works nicely.
1368 .
1369 .
1370 .P
1371 (If you really need diversions which should ignore the current partial
1372 line, use environments to save the current partial line and/\:or use the
1373 .B .box
1374 request.)
1375 .
1376 .
1377 .P
1378 The most powerful feature using diversions is to start a diversion
1379 within a macro definition and end it within another macro.
1380 .
1381 Then everything between each call of this macro pair is stored within
1382 the diversion and can be manipulated from within the macros.
1383 .
1384 .
1385 .\" ====================================================================
1386 .SH Authors
1387 .\" ====================================================================
1388 .
1389 This document was written by
1390 .MT groff\-bernd\:.warken\-72@\:web\:.de
1391 Bernd Warken
1392 .ME ,
1393 .MT wl@\:gnu\:.org
1394 Werner Lemberg
1395 .ME ,
1396 and
1397 .MT g.branden\:.robinson@\:gmail\:.com
1398 G.\& Branden Robinson
1399 .ME .
1400 .
1401 .
1402 .\" ====================================================================
1403 .SH "See also"
1404 .\" ====================================================================
1405 .
1406 .IR "Groff: The GNU Implementation of troff" ,
1407 by Trent A.\& Fisher and Werner Lemberg,
1408 is the primary
1409 .I groff
1410 manual.
1411 .
1412 You can browse it interactively with \[lq]info groff\[rq].
1413 .
1414 .
1415 .LP
1416 The
1417 .UR https://\:wiki\:.linuxfoundation\:.org/\:lsb/\:fhs
1418 Filesystem Hierarchy Standard
1419 .UE
1420 is maintained by the Linux Foundation.
1421 .
1422 .
1423 .TP
1424 .MR groff 1
1425 is an overview of the
1426 .I groff
1427 system.
1428 .
1429 .
1430 .TP
1431 .MR groff_man 7 ,
1432 .TQ
1433 .MR groff_mdoc 7 ,
1434 .TQ
1435 .MR groff_me 7 ,
1436 .TQ
1437 .MR groff_mm 7 ,
1438 .TQ
1439 .MR groff_mom 7 ,
1440 .TQ
1441 .MR groff_ms 7 ,
1442 .TQ
1443 .MR groff_rfc1345 7 ,
1444 .TQ
1445 .MR groff_trace 7 ,
1446 \~and
1447 .TQ
1448 .MR groff_www 7
1449 are
1450 .I groff
1451 macro packages.
1452 .
1453 .
1454 .TP
1455 .MR groff 7
1456 summarizes the language recognized by GNU
1457 .IR troff . \" GNU
1458 .
1459 .
1460 .TP
1461 .MR troff 1
1462 documents the default macro file search path.
1463 .
1464 .
1465 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1466 .cp \n[*groff_groff_tmac_5_man_C]
1467 .do rr *groff_groff_tmac_5_man_C
1468 .
1469 .
1470 .\" Local Variables:
1471 .\" fill-column: 72
1472 .\" mode: nroff
1473 .\" End:
1474 .\" vim: set filetype=groff textwidth=72: