Debian Codegraph @

upstream/debian-unstable/man5/groff_tmac.5

raw
1 .TH groff_tmac 5 "2026-04-22" "groff 1.24.1"
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 2000-2024 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 .\" This man page employs an unusual character.
49 .if !c \[u2717] .char \[u2717] X
50 .
51 .
52 .\" TODO: Consider parallelizing with our Texinfo node "Macro Packages".
53 .\" ====================================================================
54 .SH Description
55 .\" ====================================================================
56 .
57 Definitions of macros,
58 strings,
59 and registers for use in a
60 .MR roff 7
61 document can be collected into
62 .IR "macro files" ,
63 .I roff
64 input files designed to produce no output themselves but instead ease
65 the preparation of other
66 .I roff
67 documents.
68 .
69 There is no syntactical difference between a macro file and any other
70 .I roff
71 document;
72 only its purpose distinguishes it.
73 .
74 When a macro file is installed at a standard location,
75 named according to a certain convention,
76 and suitable for use by a general audience,
77 it is termed a
78 .IR "macro package" .
79 .
80 The \[lq]tmac\[rq] name originated in early Unix culture as an
81 abbreviation of
82 .RI \[lq] troff \" generic
83 macros\[rq].
84 .
85 .
86 .P
87 Macro packages can be loaded by supplying the
88 .B \-m
89 option to
90 .MR \%troff 1
91 or a
92 .I groff
93 front end.
94 .
95 A macro file's name must have the form
96 .RI name .tmac
97 (or
98 .IR tmac. name)
99 and be placed in a
100 .RI \[lq] tmac
101 directory\[rq] to be loadable with the
102 .RB \[lq] \-m
103 .IR name \[rq]
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 Macro files are named for their most noteworthy application,
120 but a macro file need not define any macros.
121 .
122 It can restrict itself to defining registers and strings or invoking
123 other
124 .I groff
125 requests.
126 .
127 It can even be empty.
128 .
129 .
130 .P
131 Encode macro files in
132 ISO\~646:1991\~IRV (US-ASCII)
133 or ISO\~Latin-1 (8859-1).
134 .
135 To prepare for a future
136 .I groff
137 release supporting UTF-8 input,
138 restrict files to ISO 646 codes.
139 .
140 .
141 .MR \%soelim 1
142 by design does not interpret
143 .B mso
144 requests,
145 and the encodings used by documents employing a macro file can vary.
146 .
147 .
148 .\" ====================================================================
149 .SH "Macro packages"
150 .\" ====================================================================
151 .
152 Some macro packages
153 (\[lq]major\[rq] or \[lq]full-service\[rq])
154 assume responsibility for page layout
155 and other critical functions;
156 others
157 (\[lq]supplemental\[rq] or \[lq]auxiliary\[rq])
158 do not.
159 .
160 GNU
161 .I roff
162 provides most major macro packages found in AT&T and BSD Unix systems,
163 an additional full-service package,
164 and many supplemental packages.
165 .
166 Multiple full-service macro packages cannot be used by the same
167 document.
168 .
169 Auxiliary packages can,
170 in general,
171 be freely combined,
172 though attention to their use of the
173 .I groff
174 language name spaces for identifiers
175 (particularly registers,
176 macros,
177 strings,
178 and diversions)
179 should be paid.
180 .
181 Name space management challenged AT&T
182 .I troff \" AT&T
183 users;
184 GNU
185 .IR troff 's \" GNU
186 support for arbitrarily long identifiers affords few excuses for name
187 collisions,
188 apart from attempts at compatibility with the demands of historical
189 documents.
190 .
191 .
192 .\" ====================================================================
193 .SS "Man pages"
194 .\" ====================================================================
195 .
196 Two full-service macro packages are specialized for formatting Unix
197 reference manuals;
198 they do not support features like footnotes or multiple columnation.
199 .
200 .TP 9n \" "mandoc" + 2n + hand-tuned for PDF
201 .I an
202 constructs man pages in a format introduced by Seventh Edition Unix
203 (1979).
204 .
205 Its macro interface is small,
206 and the package widely used;
207 see
208 .MR groff_man 7 .
209 .
210 .
211 .TP
212 .I doc
213 constructs man pages in a format introduced by 4.3BSD-Reno (1990).
214 .
215 It provides many more features than
216 .IR an ,
217 but is also larger,
218 more complex,
219 and not as widely adopted;
220 see
221 .MR groff_mdoc 7 .
222 .
223 .
224 .P
225 Because readers of man pages often do not know in advance which macros
226 are used to format a given document,
227 a wrapper is available.
228 .
229 .
230 .TP 9n \" "mandoc" + 2n + hand-tuned for PDF
231 .I \%andoc
232 recognizes a document's use of
233 .I an
234 or
235 .I doc
236 and loads the corresponding macro package.
237 .
238 Multiple man pages,
239 in either format,
240 can be handled;
241 .I \%andoc
242 reloads each macro package as necessary.
243 .
244 .
245 .\" ====================================================================
246 .SS "General full-service packages"
247 .\" ====================================================================
248 .
249 The following packages each support composition of documents of any
250 kind,
251 from single-page memos to lengthy monographs.
252 .
253 They are similar in functionality;
254 select one that suits your taste.
255 .
256 .
257 .TP
258 .I me
259 originates in 2BSD (1978);
260 see
261 .MR groff_me 7 .
262 .
263 .
264 .TP
265 .I mm
266 originates in Programmer's Workbench (PWB) Unix 1.0 (1977);
267 see
268 .MR groff_mm 7 .
269 .
270 .
271 .TP
272 .I mom
273 was contributed to
274 .I groff
275 in 2002,
276 and freely exercises its many extended features.
277 .
278 See
279 .MR groff_mom 7 .
280 .
281 .
282 .TP
283 .I ms
284 originates in Sixth Edition Unix (1975);
285 see
286 .MR groff_ms 7 .
287 .
288 .
289 .\" ====================================================================
290 .SS "Localization packages"
291 .\" ====================================================================
292 .
293 For Western languages,
294 an auxiliary package for localization
295 sets the hyphenation mode and loads hyphenation patterns
296 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 supplemental 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 Sets the input encoding to Latin-1 by loading
369 .IR latin1.tmac .
370 .
371 .
372 .TP
373 .I es
374 Spanish;
375 localizes
376 .IR man ,
377 .IR me ,
378 .IR mm ,
379 .IR mom ,
380 and
381 .IR ms .
382 .
383 Sets the input encoding to Latin-9 by loading
384 .IR latin9.tmac .
385 .
386 .
387 .TP
388 .I fr
389 French;
390 localizes
391 .IR man ,
392 .IR me ,
393 .IR mm ,
394 .IR mom ,
395 and
396 .IR ms .
397 .
398 Sets the input encoding to Latin-9 by loading
399 .IR latin9.tmac .
400 .
401 .
402 .TP
403 .I it
404 Italian;
405 localizes
406 .IR man ,
407 .IR me ,
408 .IR mm ,
409 .IR mom ,
410 and
411 .IR ms .
412 .
413 Sets the input encoding to Latin-1 by loading
414 .IR latin1.tmac .
415 .
416 .
417 .TP
418 .I ja
419 Japanese.
420 .
421 .
422 .TP
423 .I pl
424 Polish;
425 localizes
426 .IR man ,
427 .IR me ,
428 .IR mm ,
429 .IR mom ,
430 and
431 .IR ms .
432 .
433 Sets the input encoding to Latin-2 by loading
434 .IR latin2.tmac .
435 .
436 .
437 .TP
438 .I ru
439 Russian;
440 localizes
441 .IR man ,
442 .IR me ,
443 .IR mm ,
444 .IR mom ,
445 and
446 .IR ms .
447 .
448 Sets the input encoding to KOI8-R by loading
449 .IR koi8-r.tmac .
450 .
451 .
452 .TP
453 .I sv
454 Swedish;
455 localizes
456 .IR man ,
457 .IR me ,
458 .IR mm ,
459 .IR mom ,
460 and
461 .IR ms .
462 .
463 Sets the input encoding to Latin-1 by loading
464 .IR latin1.tmac .
465 .
466 Some of the localization of the
467 .I mm
468 package is handled separately;
469 see
470 .MR groff_mmse 7
471 (only in Swedish locales).
472 .
473 .
474 .TP
475 .I zh
476 Chinese.
477 .
478 .
479 .\" ====================================================================
480 .SS "Input encodings"
481 .\" ====================================================================
482 .
483 Localization influences automatic hyphenation
484 in two distinct but related respects.
485 A macro file specific to a character coding identifies
486 which character codes correspond to letters expected
487 in the language's hyphenation pattern files
488 and sets up case equivalences for those letters.
489 A language's macro file determines which of these letters
490 are equivalent to other letters for hyphenation purposes.
491 .
492 .
493 .P
494 For example,
495 in English,
496 the letter \[lq]\[n a~]\[rq] occurs in loan words.
497 The
498 .I \%latin1.tmac
499 and
500 .I \%latin9.tmac
501 macro files define a hyphenation code for \[lq]\[n a~]\[rq]
502 and make \[lq]\[N a~]\[rq] equivalent to it.
503 The English localization file
504 .I \%en.tmac
505 furthermore makes \[lq]\[n a~]\[rq] equivalent to \[lq]n\[rq].
506 In Spanish
507 .RI \%( es.tmac ),
508 however,
509 \[lq]\[n a~]\[rq] and \[lq]n\[rq] are
510 .I not
511 equivalent.
512 The language localization file
513 .\" (@pxref{Manipulating Hyphenation})
514 loads an appropriate encoding localization file;
515 a document need not do so directly.
516 .
517 .
518 .TP 8n \" "latin1" + 2n
519 .I latin1
520 .TQ
521 .I latin2
522 .TQ
523 .I latin5
524 .TQ
525 .I latin9
526 support the ISO\~Latin-1,
527 Latin-2,
528 Latin-5,
529 and
530 Latin-9 encodings
531 (8859-1,
532 8859-2,
533 8859-9,
534 and
535 8859-15,
536 respectively).
537 .
538 .
539 .TP
540 .I koi8\-r
541 supports the KOI8-R encoding.
542 .
543 KOI8-R code points in the range 0x80\[en]0x9F are not valid input to GNU
544 .IR troff ; \" GNU
545 see section \[lq]Identifiers\[rq] in
546 .MR groff 7 .
547 .
548 This should be no impediment to practical documents,
549 as these KOI8-R code points do not encode letters,
550 but box-drawing symbols and characters that are better obtained via
551 special character escape sequences;
552 see
553 .MR groff_char 7 .
554 .
555 .
556 .\" ====================================================================
557 .SS "General auxiliary packages"
558 .\" ====================================================================
559 .
560 The macro packages in this section are not intended for stand-alone
561 use,
562 but can add functionality to any other macro package or to plain
563 (\[lq]raw\[rq])
564 .I groff
565 documents.
566 .
567 .
568 .\" TODO:
569 .\" devtag
570 .\" europs
571 .\" psatk
572 .\" psfig
573 .TP 11n \" "papersize" + 2n
574 .I 62bit
575 provides macros for addition,
576 multiplication,
577 and division of 62-bit integers
578 (allowing safe multiplication of signed 31-bit integers,
579 for example).
580 .
581 .
582 .br
583 .ne 4v
584 .TP
585 .I hdtbl
586 allows the generation of tables using a syntax similar to the HTML table
587 model.
588 .
589 This Heidelberger table macro package is not a preprocessor,
590 which can be useful if the contents of table entries are determined by
591 macro calls or string interpolations.
592 .
593 Compare to
594 .MR \%tbl 1 .
595 .
596 It works only with the
597 .B ps
598 and
599 .B pdf
600 output devices.
601 .
602 See
603 .MR groff_hdtbl 7 .
604 .
605 .
606 .TP
607 .I papersize
608 enables the paper format to be set on the command line with the
609 .RB \[lq] \-d
610 .BI \%paper= fmt\c
611 \[rq]
612 option to
613 .IR \%troff .
614 .
615 Valid
616 .IR fmt s
617 are the ISO and DIN formats
618 .RB \[lq] A0 \[en] A6 \[rq],
619 .RB \[lq] B0 \[en] B6 \[rq],
620 .RB \[lq] C0 \[en] C6 \[rq],
621 and
622 .RB \[lq] D0 \[en] D6 \[rq];
623 .\" XXX: src/libs/libgroff/paper.cpp also supports [ABCD]7.
624 the U.S.\& formats
625 .RB \%\[lq] letter \[rq],
626 .RB \%\[lq] legal \[rq],
627 .RB \%\[lq] tabloid \[rq],
628 .RB \%\[lq] ledger \[rq],
629 .RB \%\[lq] statement \[rq],
630 and
631 .RB \%\[lq] executive \[rq];
632 and the envelope formats
633 .RB \%\[lq] com10 \[rq],
634 .RB \%\[lq] monarch \[rq],
635 and
636 .RB \%\[lq] DL \[rq].
637 .
638 All formats,
639 even those for envelopes,
640 are in portrait orientation:
641 the longer measurement is vertical.
642 .
643 Appending \[lq]l\[rq] (ell) to any of these denotes landscape
644 orientation instead.
645 .
646 This macro file assumes one-inch horizontal margins,
647 and sets registers recognized by the
648 .I groff
649 .IR man ,
650 .IR mdoc ,
651 .IR mm ,
652 .IR mom ,
653 and
654 .I ms
655 packages to configure them accordingly.
656 .
657 If you want different margins,
658 you will need to use those packages' facilities,
659 or
660 .I \%troff
661 .B ll
662 and/or
663 .B po
664 requests,
665 to adjust them.
666 .
667 An output device typically requires command-line options
668 .B \-p
669 and
670 .B \-l
671 to override the paper dimensions and orientation,
672 respectively,
673 defined in its
674 .I DESC
675 file;
676 see subsection \[lq]Paper format\[rq]
677 of
678 .MR groff 1 .
679 .
680 This macro file is normally loaded at startup by the
681 .I troffrc
682 file when formatting for a typesetter
683 (but not a terminal).
684 .
685 .
686 .TP
687 .I pdfpic
688 provides a single macro,
689 .BR \%PDFPIC ,
690 that operates in two modes.
691 .
692 If it is not used with
693 .IR gropdf ,
694 the given
695 .I file
696 must be a PDF;
697 .B \%PDFPIC
698 then relies on the external program
699 .MR pdftops 1
700 to convert the PDF to an encapsulated PostScript (EPS) file
701 and calls the
702 .B PSPIC
703 macro with which it shares an interface.
704 .
705 If output is to a PDF document,
706 .B \%PDFPIC
707 uses the
708 .RB \[lq] "pdf: \%pdfpic" \[rq]
709 device extension command
710 (see
711 .MR gropdf 1 );
712 the given
713 .I file
714 can then be a PDF or any graphic file format supported by
715 .IR gropdf .
716 .
717 .
718 .IP
719 Since
720 .B \%PDFPIC
721 needs to discover the width and height of the image
722 (to check if sufficient room exists to place it on the page),
723 it has dependencies on external programs as shown below.
724 .
725 .
726 .IP
727 .TS
728 allbox center;
729 Cb Ci Ci Ci
730 Li C C C.
731 \& pdfinfo\fR(1) file\fR(1) identify\fR(1)
732 \&.pdf \[OK] \[OK] \[OK]
733 \&.jpg \[u2717] \[OK] \[OK]
734 \&.jp2 \[u2717] \[u2717] \[OK]
735 \fRother \[u2717] \[u2717] \[OK]
736 .TE
737 .
738 .
739 .IP
740 To include image formats such as PNG,
741 PAM,
742 and GIF,
743 .I gropdf
744 relies upon PerlMagick modules to embed the graphic.
745 .
746 They are not needed for the types listed in the table above.
747 .
748 .
749 .IP
750 If the required programs are not available,
751 .I file
752 is treated as a PDF;
753 failure is likely if it is not one.
754 .
755 .
756 .TP
757 .I pic
758 supplies definitions of the macros
759 .BR PS ,
760 .BR PE ,
761 .BR PF ,
762 and
763 .BR PY ,
764 used with the
765 .MR \%pic 1
766 preprocessor.
767 .
768 They center each picture.
769 .
770 Use it if your document does not use a full-service macro package,
771 or that package does not supply working
772 .I pic
773 macro definitions.
774 .
775 Except for
776 .I man
777 and
778 .IR mdoc ,
779 those provided with
780 .I groff
781 already do so
782 (exception:
783 .I mm
784 employs the name
785 .B PF
786 for a different purpose).
787 .
788 .
789 .TP
790 .I pspic
791 provides a macro,
792 .BR PSPIC ,
793 that includes a PostScript graphic in a document.
794 .
795 The
796 .BR ps ,
797 .BR dvi ,
798 .BR html ,
799 and
800 .B xhtml
801 output devices support such inclusions;
802 for all other drivers,
803 the image is replaced with a rectangular border of the same size.
804 .
805 .I pspic.tmac
806 is loaded at startup by the
807 .I troffrc
808 file.
809 .
810 .
811 .br
812 .ne 3v
813 .IP
814 Its syntax is as follows.
815 .RS
816 .IP
817 \&\fB.PSPIC\fP \
818 [\fB\-L\fP\|\
819 |\|\fB\-R\fP\|\
820 |\|\fB\-C\fP\|\
821 |\|\fB\-I\fP\~\fIn\fP] \
822 \fI\|file\fP [\fIwidth\fP [\,\fIheight\/\fP]]
823 .RE
824 .
825 .
826 .IP
827 .I file
828 is the name of the PostScript file;
829 .I width
830 and
831 .I height
832 give the desired width and height of the image.
833 .
834 If neither a
835 .I width
836 nor a
837 .I height
838 argument is specified,
839 the image's natural width
840 (as given in the file's bounding box)
841 or the current line length is used as the width,
842 whatever is smaller.
843 .
844 The
845 .I width
846 and
847 .I height
848 arguments may have scaling units attached;
849 the default scaling unit
850 .RB is\~ i .
851 .
852 .B PSPIC
853 scales the graphic uniformly in the horizontal and vertical directions
854 so that it is no more than
855 .I width
856 wide
857 and
858 .I height
859 high.
860 .
861 Option
862 .B \-C
863 centers the graphic horizontally;
864 this is the default.
865 .
866 .B \-L
867 and
868 .B \-R
869 left- and right-align the graphic,
870 respectively.
871 .
872 .B \-I
873 indents the graphic
874 .RI by\~ n
875 (with a default scaling unit
876 .RB of\~ m ).
877 .
878 .
879 .IP
880 To use
881 .B PSPIC
882 within a diversion,
883 we recommend extending it with the following code,
884 assuring that the diversion's width completely covers the image's width.
885 .
886 .
887 .RS
888 .IP
889 .EX
890 \&.am PSPIC
891 \&.\~\~vpt 0
892 \&\[rs]h\[aq](\[rs]\[rs]n[ps\-offset]u + \[rs]\[rs]n[ps\-deswid]u)\[aq]
893 \&.\~\~sp \-1
894 \&.\~\~vpt 1
895 \&..
896 .EE
897 .RE
898 .
899 .
900 .IP
901 Failure to load
902 .BR PSPIC 's
903 image argument is not an error.
904 .
905 (The
906 .B psbb
907 request does issue an error diagnostic.)
908 .
909 To make such a failure fatal,
910 append to the
911 .B pspic*error\-hook
912 macro.
913 .
914 .
915 .RS
916 .IP
917 .EX
918 \&.am pspic*error\-hook
919 \&.\~\~ab
920 \&..
921 .EE
922 .RE
923 .
924 .
925 .TP
926 .I ptx
927 provides a macro,
928 .BR xx ,
929 to format permuted index entries as produced by the GNU
930 .MR ptx 1
931 program.
932 .
933 If your formatting needs differ,
934 copy the macro into your document and adapt it.
935 .
936 .
937 .TP
938 .I rfc1345
939 defines special character escape sequences named for the glyph mnemonics
940 specified in RFC\~1345 and the digraph table of the Vim text editor.
941 .
942 See
943 .MR groff_rfc1345 7 .
944 .
945 .
946 .TP
947 .I sboxes
948 offers an interface to the
949 .RB \[lq] "pdf: background" \[rq]
950 device extension command supported by
951 .MR gropdf 1 .
952 .
953 Using this package,
954 .I groff ms
955 documents can draw colored rectangles beneath any output.
956 .
957 .RS
958 .TP
959 .BI \%.BOXSTART\~SHADED\~ color\~\c
960 .BI \%OUTLINED\~ color\~\c
961 .BI \%INDENT\~ size\~\c
962 .BI \%WEIGHT\~ size
963 begins a box,
964 where the argument after
965 .B \%SHADED
966 gives the fill color and that after
967 .B \%OUTLINED
968 the border color.
969 .
970 Omit the former to get a borderless filled box and the latter for a
971 border with no fill.
972 .
973 The specified
974 .B \%WEIGHT
975 is used if the box is
976 .BR \%OUTLINED .
977 .
978 .
979 .IP
980 .B \%INDENT
981 precedes a value that leaves a gap between the border and the contents
982 inside the box.
983 .
984 .
985 .IP
986 Each
987 .I color
988 must be a defined
989 .I groff
990 color name,
991 and each
992 .I size
993 a valid
994 .I groff
995 numeric expression.
996 .
997 The keyword/value pairs can be specified in any order.
998 .RE
999 .
1000 .
1001 .IP
1002 Boxes can be stacked,
1003 so you can start a box within another box;
1004 usually the later boxes would be smaller than the containing box,
1005 but this is not enforced.
1006 .
1007 When using
1008 .BR \%BOXSTART ,
1009 the left position is the current indent minus the
1010 .B \%INDENT
1011 in the command,
1012 and the right position is the left position
1013 (calculated above)
1014 plus the current line length and twice the indent.
1015 .
1016 .
1017 .RS
1018 .TP
1019 .B \%.BOXSTOP
1020 takes no parameters.
1021 .
1022 It closes the most recently started box at the current vertical position
1023 after adding its
1024 .B \%INDENT
1025 spacing.
1026 .RE
1027 .
1028 .
1029 .IP
1030 Your
1031 .I groff
1032 documents can conditionally exercise the
1033 .I sboxes
1034 macros.
1035 .
1036 The register
1037 .B \%GSBOX
1038 is defined if the package is loaded,
1039 and interpolates a true value if the
1040 .B pdf
1041 output device is in use.
1042 .
1043 .
1044 .IP
1045 .I sboxes
1046 furthermore hooks into the
1047 .MR groff_ms 7
1048 package to receive notifications when footnotes are growing,
1049 so that it can close boxes on a page before footnotes are printed.
1050 .
1051 When that condition obtains,
1052 .I sboxes
1053 will close open boxes two points
1054 above the footnote separator and re-open them on the next page.
1055 .
1056 (This amount probably will not match the box's
1057 .BR \%INDENT .)
1058 .
1059 .
1060 .IP
1061 See
1062 .UR file:///usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%msboxes\:.pdf
1063 \[lq]Using PDF boxes with
1064 .I groff
1065 and the
1066 .I ms
1067 macros\[rq]
1068 .UE
1069 for a demonstration.
1070 .
1071 .
1072 .TP
1073 .I trace
1074 aids the debugging of
1075 .I groff
1076 documents by tracing macro calls.
1077 .
1078 See
1079 .MR groff_trace 7 .
1080 .
1081 .
1082 .TP
1083 .I www
1084 defines macros corresponding to HTML elements.
1085 .
1086 See
1087 .MR groff_www 7 .
1088 .
1089 .
1090 .\" ====================================================================
1091 .SH Naming
1092 .\" ====================================================================
1093 .
1094 AT&T
1095 .I nroff \" AT&T
1096 and
1097 .I troff \" AT&T
1098 were implemented before the conventions of the modern C
1099 .MR getopt 3
1100 call evolved,
1101 and used a naming scheme for macro packages that looks oddly terse to
1102 modern eyes.
1103 .
1104 The formatter's
1105 .B \-m
1106 option was the main means of loading a macro package,
1107 and its argument had to follow immediately without intervening space.
1108 This looked like a long option name preceded by a single minus\[em]a
1109 sensation in the computer stone age.
1110 .
1111 Macro packages therefore came to be known by names that started with the
1112 letter \[lq]m\[rq],
1113 which was omitted from the name of the macro file as stored on disk.
1114 .
1115 For example,
1116 the manuscript macro package was stored as
1117 .I tmac.s
1118 and loaded with the option
1119 .BR \-ms .
1120 .
1121 It has since become conventional in operating systems to use a suffixed
1122 file name extension to suggest a file type or format,
1123 thus we see
1124 .I roff
1125 documents with names ending in
1126 .IR .man ,
1127 .IR .me ,
1128 and so on.
1129 .
1130 .
1131 .br
1132 .ne 2v
1133 .P
1134 .I groff
1135 commands permit space between an option and its argument.
1136 .
1137 The syntax
1138 .RB \[lq] "groff \-m s" \[rq]
1139 makes the macro file name more clear but may surprise users familiar
1140 with the original convention,
1141 unaware that the package's \[lq]real\[rq] name was \[lq]s\[rq] all
1142 along.
1143 .
1144 For such packages of long pedigree,
1145 .I groff
1146 accommodates different users' expectations by supplying wrapper macro
1147 files that load the desired file with
1148 .B mso
1149 requests.
1150 .
1151 Thus,
1152 all of
1153 .RB \[lq] "groff \-m s" \[rq],
1154 .RB \[lq] "groff \-m ms" \[rq],
1155 .RB \[lq] "groff \-ms" \[rq],
1156 and
1157 .RB \[lq] "groff \-mms" \[rq]
1158 serve to load the manuscript macros.
1159 .
1160 .
1161 .\" ====================================================================
1162 .SH Inclusion
1163 .\" ====================================================================
1164 .
1165 The traditional method of employing a macro package is to specify the
1166 .RB \[lq] \-m
1167 .IR package \[rq]
1168 option to the formatter,
1169 which then reads
1170 .IR package 's
1171 macro file prior to any input.
1172 .
1173 Historically,
1174 .I package
1175 was sought in a file named
1176 .IR tmac. package
1177 (that is,
1178 with a
1179 .RB \[lq] tmac.\& \[rq]
1180 prefix).
1181 .
1182 GNU
1183 .I troff \" GNU
1184 searches for
1185 .RI package .tmac
1186 in the macro path;
1187 if not found,
1188 it looks for
1189 .IR tmac. package
1190 instead,
1191 and vice versa.
1192 .
1193 .
1194 .P
1195 Alternatively,
1196 one could include a macro file with the request
1197 .RB \[lq] so
1198 .IR file-name \[rq];
1199 the argument is resolved as
1200 .MR fopen 3
1201 would,
1202 from the current working directory of the formatter.
1203 .
1204 This approach was inadequate to locate macro packages,
1205 since systems stored them in varying locations.
1206 .
1207 GNU
1208 .I troff \" GNU
1209 offers an improved feature in the similar request
1210 .RB \[lq] mso
1211 .IR package-file-name \[rq],
1212 which searches the macro path for
1213 .IR package-file-name .
1214 .
1215 Because its argument is a file name,
1216 its
1217 .RB \[lq] .tmac \[rq]
1218 component must be included for the file to be found.
1219 .
1220 .
1221 .P
1222 If a sourced file requires preprocessing,
1223 for example if it includes
1224 .I tbl \" generic
1225 tables
1226 or
1227 .I eqn \" generic
1228 equations,
1229 the preprocessor
1230 .MR \%soelim 1
1231 must be used.
1232 .
1233 This can be achieved with a pipeline or by specifying the
1234 .B \-s
1235 option to
1236 .MR groff 1 .
1237 .
1238 .MR man 1
1239 librarian programs typically run
1240 .I \%soelim
1241 automatically.
1242 .
1243 (As a rule,
1244 macro packages themselves do not require preprocessing.)
1245 .
1246 .
1247 .ig
1248 .\" ====================================================================
1249 .SH Convention
1250 .\" ====================================================================
1251 .
1252 .\" This section does not fit into the framework of this document.
1253 .
1254 There is a convention that is supported by many modern roff
1255 typesetters and
1256 .MR man 1
1257 programs, the
1258 .I preprocessor word
1259 described in the following.
1260 .
1261 .P
1262 If the first line in a document is a comment, the first word (after the
1263 comment characters and a blank) constitutes the
1264 .B preprocessor
1265 .BR word .
1266 That means that the letters of this word are interpreted as
1267 abbreviations for those preprocessor commands that should be run
1268 when formatting the document.
1269 .
1270 Mostly, only the letters corresponding to the options for the
1271 preprocessors are recognized,
1272 \[oq]e\[cq]
1273 (for
1274 .IR eqn ),
1275 .\" \[oq]G\[cq],
1276 .\" \[oq]g\[cq],
1277 \[oq]p\[cq]
1278 (for
1279 .IR pic ),
1280 \[oq]R\[cq]
1281 (for
1282 .IR refer ),
1283 \[oq]s\[cq]
1284 (for
1285 .IR soelim ),
1286 and
1287 \[oq]t\[cq]
1288 (for
1289 .IR tbl ).
1290 (see
1291 .MR roff 7 ).
1292 .
1293 .
1294 .P
1295 Besides being a good reminder for the user, some formatters (like the
1296 .MR man 1
1297 program) are even able to automatically start the preprocessors
1298 specified in the preprocessor word, but do not bet on this.
1299 .
1300 .
1301 .P
1302 The
1303 .I man
1304 program handles some preprocessors automatically, such that in
1305 man\~pages only the following characters should be used:
1306 \[oq]e\[cq], \[oq]p\[cq], and \[oq]t\[cq].
1307 .
1308 .
1309 ..
1310 .\" XXX: The next section requires significant revision.
1311 .\" ====================================================================
1312 .SH "Writing macros"
1313 .\" ====================================================================
1314 .
1315 A
1316 .MR roff 7
1317 document is a text file that is enriched by predefined formatting
1318 constructs, such as requests, escape sequences, strings, numeric
1319 registers, and macros from a macro package.
1320 .
1321 .MR roff 7
1322 describes these elements.
1323 .
1324 .
1325 .P
1326 To give a document a personal style, it is most useful to extend the
1327 existing elements by defining some macros for repeating tasks; the best
1328 place for this is near the beginning of the document or in a separate
1329 file.
1330 .
1331 .
1332 .P
1333 Macros without arguments are just like strings.
1334 .
1335 But the full power of macros occurs when arguments are passed with a
1336 macro call.
1337 .
1338 Within the macro definition, the arguments are available as the escape
1339 sequences
1340 .BR \[rs]$1 ,
1341 \&.\|.\|.,
1342 .BR \[rs]$9 ,
1343 .BR \[rs]$[ .\|.\|. ] ,
1344 .BR \[rs]$* ,
1345 and
1346 .BR \[rs]$@ ,
1347 the name under which the macro was called is in
1348 .BR \[rs]$0 ,
1349 and the number of arguments is in register
1350 .BR \[rs]n[.$] ;
1351 see
1352 .MR groff 7 .
1353 .
1354 .
1355 .\" ====================================================================
1356 .SS "Drafting macros"
1357 .\" ====================================================================
1358 .
1359 One approach temporarily disables escape sequences
1360 by bracketing a macro definition with
1361 .B eo
1362 and
1363 .B ec
1364 requests.
1365 .
1366 .
1367 .IP
1368 .RS
1369 .ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\"
1370 .ds @2 arguments:\"
1371 .EX
1372 \&.eo
1373 \&.ds midpart was called with the following
1374 \&.de print_args
1375 \&\*[@1]\~\[rs]*[midpart]\~\[rs]n[.$]\~\*[@2] \[rs]$*
1376 \&..
1377 \&.ec
1378 .EE
1379 .rm @1
1380 .rm @2
1381 .RE
1382 .
1383 .
1384 .P
1385 The above procedure has limitations;
1386 it is unsuitable for a macro that requires certain interpolations at the
1387 time it is defined,
1388 or for indirect definitions of identifiers.
1389 .
1390 See section \[lq]Copy mode\[rq] of
1391 .MR groff 7 .
1392 .
1393 In such cases,
1394 you might define and test the macro with the escape character doubled
1395 before escape sequences that are interpreted even in copy mode,
1396 then bracket it with
1397 .B eo
1398 and
1399 .B ec
1400 requests,
1401 un-double the escape characters,
1402 then test again.
1403 .
1404 .
1405 .\" ====================================================================
1406 .SS "Tips for macro definitions"
1407 .\" ====================================================================
1408 .
1409 .IP \(bu 3n
1410 Use only control lines in macro definitions;
1411 that is,
1412 start every input line with a control character.
1413 .
1414 .IR groff 's
1415 .B nop
1416 request makes use of text lines unnecessary.
1417 .
1418 .
1419 .RS
1420 .IP
1421 .EX
1422 \&.de Text
1423 \&. if (\[rs]\[rs]n[.$] == 0) \[rs]
1424 \&. return
1425 \&. nop \[rs]&\[rs]\[rs]$*\[rs]&
1426 \&..
1427 .EE
1428 .RE
1429 .
1430 .
1431 .IP \(bu
1432 Write a comment macro that works in both draft and non-draft modes;
1433 since the escape character is disabled in draft mode,
1434 trouble might occur when comment escape sequences are used.
1435 .
1436 .\" XXX: We need the vees.
1437 .ig
1438 For example,
1439 the following macro ignores its arguments,
1440 so calling it is a harmless
1441 (if somewhat busy)
1442 null operation.
1443 ..
1444 .
1445 .RS
1446 .IP
1447 .EX
1448 \&.de c
1449 \&..
1450 \&.c This is my comment.
1451 .EE
1452 .RE
1453 .
1454 .
1455 .IP \(bu
1456 Comment lengthy macro definitions.
1457 .
1458 .
1459 .IP \(bu
1460 Use empty requests,
1461 and indentation after control characters,
1462 to clarify a macro's structure.
1463 .
1464 .
1465 .\" ====================================================================
1466 .SH Authors
1467 .\" ====================================================================
1468 .
1469 This document was written by
1470 .MT wl@\:gnu\:.org
1471 Werner Lemberg
1472 .ME
1473 and
1474 .MT g.branden\:.robinson@\:gmail\:.com
1475 G.\& Branden Robinson
1476 .ME .
1477 .
1478 .
1479 .\" ====================================================================
1480 .SH "See also"
1481 .\" ====================================================================
1482 .
1483 .IR "Groff: The GNU Implementation of troff" ,
1484 by Trent A.\& Fisher and Werner Lemberg,
1485 is the primary
1486 .I groff
1487 manual.
1488 .
1489 You can browse it interactively with \[lq]info groff\[rq].
1490 .
1491 .
1492 .TP 18n "groff_rfc1345(7)" + 2n
1493 .MR groff 1
1494 is an overview of the
1495 .I groff
1496 system.
1497 .
1498 .
1499 .TP
1500 .MR groff_man 7 ,
1501 .TQ
1502 .MR groff_mdoc 7 ,
1503 .TQ
1504 .MR groff_me 7 ,
1505 .TQ
1506 .MR groff_mm 7 ,
1507 .TQ
1508 .MR groff_mom 7 ,
1509 .TQ
1510 .MR groff_ms 7 ,
1511 .TQ
1512 .MR groff_rfc1345 7 ,
1513 .TQ
1514 .MR groff_trace 7 ,
1515 .TQ
1516 and
1517 .TQ
1518 .MR groff_www 7
1519 are
1520 .I groff
1521 macro packages.
1522 .
1523 .
1524 .TP
1525 .MR groff 7
1526 summarizes the language recognized by GNU
1527 .IR troff . \" GNU
1528 .
1529 .
1530 .TP
1531 .MR \%troff 1
1532 documents the default macro file search path.
1533 .
1534 .
1535 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1536 .cp \n[*groff_groff_tmac_5_man_C]
1537 .do rr *groff_groff_tmac_5_man_C
1538 .
1539 .
1540 .\" Local Variables:
1541 .\" fill-column: 72
1542 .\" mode: nroff
1543 .\" End:
1544 .\" vim: set filetype=groff textwidth=72: