Debian Codegraph @

upstream/debian-trixie/man5/groff_tmac.5

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