Debian Codegraph @

upstream/debian-trixie/man7/groff_man.7

raw
1 '\" t
2 .\" This page is generated by m4 from tmac/groff_man.7.man.in.
3 .TH groff_man 7 "3 June 2025" "groff 1.23.0"
4 .SH Name
5 groff_man \- compose manual pages with GNU
6 .I roff
7 .
8 .
9 .\" ====================================================================
10 .\" Legal Terms
11 .\" ====================================================================
12 .\"
13 .\" Copyright (C) 1999-2018, 2020-2021 Free Software Foundation, Inc.
14 .\"
15 .\" Permission is granted to make and distribute verbatim copies of this
16 .\" manual provided the copyright notice and this permission notice are
17 .\" preserved on all copies.
18 .\"
19 .\" Permission is granted to copy and distribute modified versions of
20 .\" this manual under the conditions for verbatim copying, provided that
21 .\" the entire resulting derived work is distributed under the terms of
22 .\" a permission notice identical to this one.
23 .\"
24 .\" Permission is granted to copy and distribute translations of this
25 .\" manual into another language, under the above conditions for
26 .\" modified versions, except that this permission notice may be
27 .\" included in translations approved by the Free Software Foundation
28 .\" instead of in the original English.
29 .
30 .
31 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
32 .do nr *groff_groff_man_7_man_C \n[.cp]
33 .cp 0
34 .
35 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
36 .nr do-fallback 0
37 .if !\n(.f .nr do-fallback 1 \" mandoc
38 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
39 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
40 .if \n[do-fallback] \{\
41 . de MR
42 . ie \\n(.$=1 \
43 . I \%\\$1
44 . el \
45 . IR \%\\$1 (\\$2)\\$3
46 . .
47 .\}
48 .rr do-fallback
49 .
50 .
51 .\" ====================================================================
52 .SH Synopsis
53 .\" ====================================================================
54 .
55 .SY "groff \-man"
56 .RI [ option\~ .\|.\|.\&]
57 .RI [ file\~ .\|.\|.]
58 .
59 .SY "groff \-m man"
60 .RI [ option\~ .\|.\|.\&]
61 .RI [ file\~ .\|.\|.]
62 .YS
63 .
64 .
65 .\" ====================================================================
66 .SH Description
67 .\" ====================================================================
68 .
69 The GNU implementation of the
70 .I man
71 macro package is part of the
72 .I groff
73 document formatting system.
74 .
75 It is used to produce manual pages
76 .\" We use an unbreakable space \~ here to keep the phrase intact for
77 .\" its introduction; in subsequent discussion, that is not important.
78 (\(lqman\~pages\(rq)
79 like the one you are reading.
80 .
81 .
82 .P
83 This document presents the macros thematically;
84 for those needing only a quick reference,
85 the following table lists them alphabetically,
86 with cross references to appropriate subsections below.
87 .
88 .
89 .P
90 Man page authors and maintainers who are not already experienced
91 .I groff
92 users should consult
93 .MR groff_man_style 7 ,
94 an expanded version of this document,
95 for additional explanations and advice.
96 .
97 It covers only those concepts required for man page document
98 maintenance,
99 and not the full breadth of the
100 .I groff
101 typesetting system.
102 .
103 .
104 .P
105 .TS
106 l l l.
107 Macro Meaning Subsection
108 .T&
109 lB l l.
110 _
111 \&.B Bold Font style macros
112 \&.BI Bold, italic alternating Font style macros
113 \&.BR Bold, roman alternating Font style macros
114 \&.EE Example end Document structure macros
115 \&.EX Example begin Document structure macros
116 \&.I Italic Font style macros
117 \&.IB Italic, bold alternating Font style macros
118 \&.IP Indented paragraph Paragraphing macros
119 \&.IR Italic, roman alternating Font style macros
120 \&.LP Begin paragraph Paragraphing macros
121 \&.ME Mail-to end Hyperlink macros
122 \&.MR Man page cross reference Hyperlink macros
123 \&.MT Mail-to start Hyperlink macros
124 \&.P Begin paragraph Paragraphing macros
125 \&.PP Begin paragraph Paragraphing macros
126 \&.RB Roman, bold alternating Font style macros
127 \&.RE Relative inset end Document structure macros
128 \&.RI Roman, italic alternating Font style macros
129 \&.RS Relative inset start Document structure macros
130 \&.SB Small bold Font style macros
131 \&.SH Section heading Document structure macros
132 \&.SM Small Font style macros
133 \&.SS Subsection heading Document structure macros
134 \&.SY Synopsis start Command synopsis macros
135 \&.TH Title heading Document structure macros
136 \&.TP Tagged paragraph Paragraphing macros
137 \&.TQ Supplemental paragraph tag Paragraphing macros
138 \&.UE URI end Hyperlink macros
139 \&.UR URI start Hyperlink macros
140 \&.YS Synopsis end Command synopsis macros
141 .TE
142 .
143 .
144 .P
145 We discuss other macros
146 .RB ( .AT ,
147 .BR .DT ,
148 .BR .HP ,
149 .BR .OP ,
150 .BR .PD ,
151 and
152 .BR .UC )
153 in subsection \(lqDeprecated features\(rq below.
154 .
155 .
156 .P
157 Throughout Unix documentation,
158 a manual entry is referred to simply as a \(lqman page\(rq,
159 regardless of its length,
160 without gendered implication,
161 and irrespective of the macro package selected for its composition.
162 .
163 .
164 .br
165 .ne 6v
166 .\" ====================================================================
167 .SS "Macro reference preliminaries"
168 .\" ====================================================================
169 .
170 A tagged paragraph describes each macro.
171 .
172 We present coupled pairs together,
173 as with
174 .B .EX
175 and
176 .BR .EE .
177 .
178 .
179 .br
180 .ne 2v
181 .P
182 An empty macro argument can be specified with a pair of double-quotes
183 (""),
184 but the
185 .I man
186 package is designed such that this should seldom be necessary.
187 .
188 Most macro arguments will be formatted as text in the output;
189 exceptions are noted.
190 .
191 .
192 .\" ====================================================================
193 .SS "Document structure macros"
194 .\" ====================================================================
195 .
196 Document structure macros organize a man page's content.
197 .
198 All of them break the output line.
199 .
200 .B .TH
201 (title heading)
202 identifies the document as a man page and configures the page headers
203 and footers.
204 .
205 Section headings
206 .RB ( .SH ),
207 one of which is mandatory and many of which are conventionally expected,
208 facilitate location of material by the reader and aid the man page
209 writer to discuss all essential aspects of the topic.
210 .
211 Subsection headings
212 .RB ( .SS )
213 are optional and permit sections that grow long to develop in a
214 controlled way.
215 .
216 Many technical discussions benefit from examples;
217 lengthy ones,
218 especially those reflecting multiple lines of input to or output from
219 the system,
220 are usefully bracketed by
221 .B .EX
222 and
223 .BR .EE .
224 .
225 When none of the foregoing meets a structural demand,
226 use
227 .BR .RS / .RE
228 to inset a region within a (sub)section.
229 .
230 .
231 .TP
232 .BI .TH " topic section"\c
233 .RI " [" footer-middle ]\c
234 .RI " [" footer-inside ]\c
235 .RI " [" header-middle ]
236 Determine the contents of the page header and footer.
237 .
238 The subject of the man page is
239 .I topic
240 and the section of the manual to which it belongs is
241 .I section.
242 .
243 See
244 .MR man 1
245 or
246 .MR intro 1
247 for the manual sectioning applicable to your system.
248 .
249 .I topic
250 and
251 .I section
252 are positioned together at the left and right in the header
253 (with
254 .I section
255 in parentheses immediately appended to
256 .IR topic ).
257 .
258 .I footer-middle
259 is centered in the footer.
260 .
261 The arrangement of the rest of the footer depends on whether
262 double-sided layout is enabled with the option
263 .BR \-rD1 .
264 .
265 When disabled (the default),
266 .I footer-inside
267 is positioned at the bottom left.
268 .
269 Otherwise,
270 .I footer-inside
271 appears at the bottom left on recto (odd-numbered) pages,
272 and at the bottom right on verso (even-numbered) pages.
273 .
274 The outside footer is the page number,
275 except in the continuous-rendering mode enabled by the option
276 .BR \-rcR=1 ,
277 in which case it is the
278 .I topic
279 and
280 .I section,
281 as in the header.
282 .
283 .I header-middle
284 is centered in the header.
285 .
286 If
287 .I section
288 is an integer between 1 and\~9 (inclusive),
289 there is no need to specify
290 .I header-middle;
291 .I an.tmac
292 will supply text for it.
293 .
294 The macro package may also abbreviate
295 .I topic
296 and
297 .I footer-inside
298 with ellipses
299 if they would overrun the space available in the header and footer,
300 respectively.
301 .
302 For HTML output,
303 headers and footers are suppressed.
304 .
305 .
306 .IP
307 Additionally,
308 this macro breaks the page,
309 resetting the number to\~1
310 (unless the
311 .B \-rC1
312 option is given).
313 .
314 This feature is intended only for formatting multiple
315 .I man
316 documents in sequence.
317 .
318 .
319 .IP
320 A valid
321 .I man
322 document calls
323 .B .TH
324 once,
325 early in the file,
326 prior to any other macro calls.
327 .
328 .
329 .TP
330 .BR .SH " ["\c
331 .IR heading-text ]
332 Set
333 .I heading-text
334 as a section heading.
335 .
336 If no argument is given,
337 a one-line input trap is planted;
338 text on the next line
339 .\", which can be formatted with a macro, \" true but discouraged
340 becomes
341 .I heading-text.
342 .
343 The left margin is reset to zero to set the heading text in bold
344 (or the font specified by the string
345 .BR HF ),
346 and,
347 on typesetting devices,
348 slightly larger than the base type size.
349 .
350 If the heading font
351 .B \[rs]*[HF]
352 is bold,
353 use of an italic style in
354 .I heading-text
355 is mapped to the bold-italic style if available in the font family.
356 .
357 The inset level is reset to 1,
358 setting the left margin to the value of the
359 .B IN \" TODO: future: BP or BI register ("base paragraph indentation")
360 register.
361 .
362 Text after
363 .I heading-text
364 is set as an ordinary paragraph
365 .RB ( .P ).
366 .
367 .
368 .IP
369 The content of
370 .I heading-text
371 and ordering of sections follows a set of common practices,
372 as has much of the layout of material within sections.
373 .
374 For example,
375 a section called \(lqName\(rq or \(lqNAME\(rq must exist,
376 must be the first section after the
377 .B .TH
378 call,
379 and must contain only text of the form
380 .RS \" Invisibly move left margin to current .IP indentation.
381 .RS \" Now indent further, visibly.
382 .IR topic [\c
383 .BI , " another-topic"\c
384 .RB "].\|.\|.\& \e\- "\c
385 .I summary-description
386 .RE \" Move left margin back to .IP indentation.
387 for a man page to be properly indexed.
388 .
389 See
390 .MR groff_man_style 7
391 for suggestions and
392 .MR man 7
393 for the conventions prevailing on your system.
394 .RE \" Move left margin back to standard position.
395 .
396 .
397 .TP
398 .BR .SS " ["\c
399 .IR subheading-text ]
400 Set
401 .I subheading-text
402 as a subsection heading indented between a section heading and an
403 ordinary paragraph
404 .RB ( .P ).
405 .
406 If no argument is given,
407 a one-line input trap is planted;
408 text on the next line
409 .\", which can be formatted with a macro, \" true but discouraged
410 becomes
411 .I subheading-text.
412 .
413 The left margin is reset to the value of the
414 .B SN
415 register to set the heading text in bold
416 (or the font specified by the string
417 .BR HF ).
418 .
419 If the heading font
420 .B \[rs]*[HF]
421 is bold,
422 use of an italic style in
423 .I subheading-text
424 is mapped to the bold-italic style if available in the font family.
425 .
426 The inset level is reset to 1,
427 setting the left margin to the value of the
428 .B IN \" TODO: future: BP or BI register ("base paragraph indentation")
429 register.
430 .
431 Text after
432 .I subheading-text
433 is set as an ordinary paragraph
434 .RB ( .P ).
435 .
436 .
437 .TP
438 .B .EX
439 .TQ
440 .B .EE
441 Begin and end example.
442 .
443 After
444 .BR .EX ,
445 filling is disabled and a constant-width (monospaced) font is selected.
446 .
447 Calling
448 .B .EE
449 enables filling and restores the previous font.
450 .
451 .
452 .IP
453 .\" Also see subsection "History" below...
454 These macros are extensions introduced in Ninth Edition Research Unix.
455 .
456 Systems running that
457 .IR troff , \" AT&T Research Unix
458 or those from
459 Documenter's Workbench,
460 Heirloom Doctools,
461 or Plan\~9
462 .I troff
463 support them.
464 .\" Solaris 10 troff does not support .EX/.EE. Neatroff doesn't ship
465 .\" (m)an macros.
466 .
467 To be certain your page will be portable to systems that do not,
468 copy their definitions from the
469 .I \%an\-ext.tmac
470 file of a
471 .I groff
472 installation.
473 .
474 .
475 .TP
476 .BR .RS " ["\c
477 .IR inset-amount ]
478 Start a new relative inset level.
479 .
480 The position of the left margin is saved,
481 then moved right by
482 .I inset-amount,
483 if specified,
484 and by the amount of the
485 .B IN
486 register otherwise.
487 .
488 Calls to
489 .B .RS
490 can be nested;
491 each increments by\~1
492 the inset level used by
493 .BR .RE .
494 .
495 The level prior to any
496 .B .RS
497 calls is\~1.
498 .
499 .
500 .TP
501 .BR .RE " ["\c
502 .IR level ]
503 End a relative inset.
504 .
505 The left margin corresponding to inset level
506 .I level
507 is restored.
508 .
509 If no argument is given,
510 the inset level is reduced by\~1.
511 .
512 .
513 .\" ====================================================================
514 .SS "Paragraphing macros"
515 .\" ====================================================================
516 .
517 An ordinary paragraph
518 .RB ( .P )
519 is set without a first-line indentation at the current left margin.
520 .
521 In man pages and other technical literature,
522 definition lists are frequently encountered;
523 these can be set as \(lqtagged paragraphs\(rq,
524 which have one
525 .RB ( .TP )
526 or more
527 .RB ( .TQ )
528 leading tags followed by a paragraph that has an additional indentation.
529 .
530 The indented paragraph
531 .RB ( .IP )
532 macro is useful to continue the indented content of a narrative started
533 with
534 .BR .TP ,
535 or to present an itemized or ordered list.
536 .
537 All of these macros break the output line.
538 .
539 If another paragraph macro has occurred since the previous
540 .B .SH
541 or
542 .BR .SS ,
543 they
544 (except for
545 .BR .TQ )
546 follow the break with a default amount of vertical space,
547 which can be changed by the deprecated
548 .B .PD
549 macro;
550 see subsection \(lqHorizontal and vertical spacing\(rq below.
551 .
552 They also reset the type size and font style to defaults
553 .RB ( .TQ
554 again excepted);
555 see subsection \(lqFont style macros\(rq below.
556 .
557 .
558 .br
559 .ne 4v
560 .TP
561 .B .P
562 .TQ
563 .B .LP
564 .TQ
565 .B .PP
566 Begin a new paragraph;
567 these macros are synonymous.
568 .
569 The indentation is reset to the default value;
570 the left margin,
571 as affected by
572 .B .RS
573 and
574 .BR .RE ,
575 is not.
576 .
577 .
578 .TP
579 .BR .TP " ["\c
580 .IR indentation ]
581 Set a paragraph with a leading tag,
582 and the remainder of the paragraph indented.
583 .
584 A one-line input trap is planted;
585 text on the next line,
586 which can be formatted with a macro,
587 becomes the tag,
588 which is placed at the current left margin.
589 .
590 The tag can be extended with the
591 .B \(rsc
592 escape sequence.
593 .
594 Subsequent text is indented by
595 .I indentation,
596 if specified,
597 and by the amount of the
598 .B IN
599 register otherwise.
600 .
601 If the tag is not as wide as the indentation,
602 the paragraph starts on the same line as the tag,
603 at the applicable indentation,
604 and continues on the following lines.
605 .
606 Otherwise,
607 the descriptive part of the paragraph begins on the line following the
608 tag.
609 .
610 .
611 .TP
612 .B .TQ
613 Set an additional tag for a paragraph tagged with
614 .BR .TP .
615 .
616 An input trap is planted as with
617 .BR .TP .
618 .
619 .
620 .IP
621 This macro is a GNU extension not defined on systems running
622 AT&T,
623 Plan\~9,
624 or
625 Solaris
626 .IR troff ;
627 see
628 .I \%an\-ext.tmac
629 in section \(lqFiles\(rq below.
630 .
631 .
632 .TP
633 .BR .IP " ["\c
634 .IR tag "] "\c
635 .RI [ indentation ]
636 Set an indented paragraph with an optional tag.
637 .
638 The
639 .I tag
640 and
641 .I indentation
642 arguments,
643 if present,
644 are handled as with
645 .BR .TP ,
646 with the exception that the
647 .I tag
648 argument to
649 .B .IP
650 cannot include a macro call.
651 .
652 .
653 .\" ====================================================================
654 .SS "Command synopsis macros"
655 .\" ====================================================================
656 .
657 .B .SY
658 and
659 .B .YS
660 aid you to construct a command synopsis that has the classical Unix
661 appearance.
662 .
663 They break the output line.
664 .
665 .\" TODO: Determine whether this (is still? was ever?) true.
666 .\" Furthermore,
667 .\" some tools are able to interpret these macros semantically and treat
668 .\" them appropriately for localization and/or presentation.
669 .
670 .
671 .P
672 These macros are GNU extensions not defined on systems running
673 AT&T,
674 Plan\~9,
675 or
676 Solaris
677 .IR troff ;
678 see
679 .I \%an\-ext.tmac
680 in section \(lqFiles\(rq below.
681 .
682 .
683 .TP
684 .BI .SY " command"
685 Begin synopsis.
686 .
687 A new paragraph begins at the left margin
688 unless
689 .B .SY
690 has already been called without a corresponding
691 .BR .YS ,
692 in which case only a break is performed.
693 .
694 Adjustment and automatic hyphenation are disabled.
695 .
696 .I command
697 is set in bold.
698 .
699 If a break is required,
700 lines after the first are indented by the width of
701 .I command
702 plus a space.
703 .
704 .
705 .TP
706 .B .YS
707 End synopsis.
708 .
709 Indentation,
710 adjustment,
711 and hyphenation
712 are restored to their previous states.
713 .
714 .
715 .\" ====================================================================
716 .SS "Hyperlink macros"
717 .\" ====================================================================
718 .
719 Man page cross references
720 are best presented with
721 .BR .MR .
722 .
723 Text may be hyperlinked to email addresses with
724 .BR .MT / .ME
725 or other URIs with
726 .BR .UR / .UE .
727 .
728 Hyperlinked text is supported on HTML
729 .\", PDF,
730 and terminal output devices;
731 terminals and pager programs must support ECMA-48 OSC\~8 escape
732 sequences
733 (see
734 .MR grotty 1 ).
735 .
736 When device support is unavailable or disabled with the
737 .B U
738 register
739 (see section \[lq]Options\[rq] below),
740 .B .MT
741 and
742 .B .UR
743 URIs are rendered between angle brackets after the linked text.
744 .
745 .
746 .P
747 .BR .MT ,
748 .BR .ME ,
749 .BR .UR ,
750 and
751 .B .UE
752 are GNU extensions not defined on systems running
753 AT&T,
754 Plan\~9,
755 or
756 Solaris
757 .IR troff ; \" Solaris
758 see
759 .I \%an\-ext.tmac
760 in section \(lqFiles\(rq below.
761 .
762 Plan\~9 from User Space's
763 .I troff \" plan9port
764 implements
765 .BR .MR .
766 .
767 .
768 .P
769 The arguments to
770 .BR .MR ,
771 .BR .MT ,
772 and
773 .B .UR
774 should be prepared for typesetting since they can appear in the
775 output.
776 .
777 Use special character escape sequences to encode Unicode basic Latin
778 characters where necessary,
779 particularly the hyphen-minus.
780 The formatter removes
781 .B \e:
782 escape sequences from hyperlinks when supplying device control commands
783 to output drivers.
784 .
785 .
786 .TP
787 .BI .MR "\~topic manual-section"\c
788 .RI \~[ trailing-text ]
789 .IR (since\~ groff \~1.23) \" TODO: remove note once novelty dies down
790 Set a man page cross reference as
791 \[lq]\c
792 .IB topic ( manual-section )\c
793 \[rq].
794 .
795 If
796 .I trailing-text
797 (typically punctuation)
798 is specified,
799 it follows the closing parenthesis without intervening space.
800 .
801 Hyphenation is disabled while the cross reference is set.
802 .
803 .I topic
804 is set in the font specified by the
805 .B MF
806 string.
807 .
808 The cross reference hyperlinks to a URI of the form
809 .RB \[lq] man:\c
810 .IR topic ( manual-section )\[rq].
811 .
812 .
813 .TP
814 .BI .MT " address"
815 .TQ
816 .BR .ME " ["\c
817 .IR trailing-text ]
818 Identify
819 .I address
820 as an RFC 6068
821 .I addr-spec
822 for a \(lqmailto:\(rq URI with the text between the two macro
823 calls as the link text.
824 .
825 An argument to
826 .B .ME
827 is placed after the link text without intervening space.
828 .
829 .I address
830 may not be visible in the rendered document if hyperlinks are enabled
831 and supported by the output driver.
832 .
833 If they are not,
834 .I address
835 is set in angle brackets after the link text and before
836 .I trailing-text.
837 .
838 If hyperlinking is enabled but there is no link text,
839 .I address
840 is formatted and hyperlinked
841 .I without
842 angle brackets.
843 .
844 .
845 .TP
846 .BI .UR " uri"
847 .TQ
848 .BR .UE " ["\c
849 .IR trailing-text ]
850 Identify
851 .I uri
852 as an RFC 3986 URI hyperlink with the text between the two macro calls
853 as the link text.
854 .
855 An argument to
856 .B .UE
857 is placed after the link text without intervening space.
858 .
859 .I uri
860 may not be visible in the rendered document if hyperlinks are enabled
861 and supported by the output driver.
862 .
863 If they are not,
864 .I uri
865 is set in angle brackets after the link text and before
866 .I trailing-text.
867 .
868 If hyperlinking is enabled but there is no link text,
869 .I uri
870 is formatted and hyperlinked
871 .I without
872 angle brackets.
873 .
874 .
875 .P
876 The hyperlinking of
877 .B .TP
878 paragraph tags with
879 .BR .UR / .UE
880 and
881 .BR .MT / .ME
882 is not yet supported;
883 if attempted,
884 the hyperlink will be typeset at the beginning of the indented paragraph
885 even on hyperlink-supporting devices.
886 .
887 .
888 .\" ====================================================================
889 .SS "Font style macros"
890 .\" ====================================================================
891 .
892 The
893 .I man
894 macro package is limited in its font styling options,
895 offering only
896 .BR bold \~( .B ),
897 .I italic\c
898 .RB \~( .I ),
899 and roman.
900 .
901 Italic text is usually set underscored instead on terminal devices.
902 .
903 The
904 .B .SM
905 and
906 .B .SB
907 macros set text in roman or bold,
908 respectively,
909 at a smaller type size;
910 these differ visually from regular-sized roman or bold text only on
911 typesetting devices.
912 .
913 It is often necessary to set text in different styles without
914 intervening space.
915 .
916 The macros
917 .BR .BI ,
918 .BR .BR ,
919 .BR .IB ,
920 .BR .IR ,
921 .BR .RB ,
922 and
923 .BR .RI ,
924 where \(lqB\(rq,
925 \(lqI\(rq,
926 and \(lqR\(rq indicate bold,
927 italic,
928 and roman,
929 respectively,
930 set their odd- and even-numbered arguments in alternating styles,
931 with no space separating them.
932 .
933 .
934 .br
935 .ne 2v
936 .P
937 The default type size and family for typesetting devices is 10-point
938 Times,
939 except on the
940 .B \%X75\-12
941 and
942 .B \%X100\-12
943 devices where the type size is 12 points.
944 .
945 The default style is roman.
946 .
947 .
948 .TP
949 .BR .B \~[\c
950 .IR text ]
951 Set
952 .I text
953 in bold.
954 .
955 If no argument is given,
956 a one-line input trap is planted;
957 text on the next line,
958 which can be further formatted with a macro,
959 is set in bold.
960 .
961 .
962 .TP
963 .BR .I \~[\c
964 .IR text ]
965 Set
966 .I text
967 in an italic or oblique face.
968 .
969 If no argument is given,
970 a one-line input trap is planted;
971 text on the next line,
972 which can be further formatted with a macro,
973 is set in an italic or oblique face.
974 .
975 .
976 .TP
977 .BR .SM \~[\c
978 .IR text ]
979 Set
980 .I text
981 one point smaller than the default type size on typesetting devices.
982 .
983 If no argument is given,
984 a one-line input trap is planted;
985 text on the next line,
986 which can be further formatted with a macro,
987 is set smaller.
988 .
989 .
990 .TP
991 .BR .SB \~[\c
992 .IR text ]
993 Set
994 .I text
995 in bold and
996 (on typesetting devices)
997 one point smaller than the default type size.
998 .
999 If no argument is given,
1000 a one-line input trap is planted;
1001 text on the next line,
1002 which can be further formatted with a macro,
1003 is set smaller and in bold.
1004 .
1005 This macro is an extension introduced in SunOS\~4.0.
1006 .
1007 .
1008 .P
1009 Unlike the above font style macros,
1010 the font style alternation macros below set no input traps;
1011 they must be given arguments to have effect.
1012 .
1013 Italic corrections are applied as appropriate.
1014 .
1015 .
1016 .
1017 .TP
1018 .BI .BI " bold-text italic-text "\c
1019 \&.\|.\|.\&
1020 Set each argument in bold and italics,
1021 alternately.
1022 .
1023 .
1024 .TP
1025 .BI .BR " bold-text roman-text "\c
1026 \&.\|.\|.\&
1027 Set each argument in bold and roman,
1028 alternately.
1029 .
1030 .
1031 .TP
1032 .BI .IB " italic-text bold-text "\c
1033 \&.\|.\|.\&
1034 Set each argument in italics and bold,
1035 alternately.
1036 .
1037 .
1038 .TP
1039 .BI .IR " italic-text roman-text "\c
1040 \&.\|.\|.\&
1041 Set each argument in italics and roman,
1042 alternately.
1043 .
1044 .
1045 .TP
1046 .BI .RB " roman-text bold-text "\c
1047 \&.\|.\|.\&
1048 Set each argument in roman and bold,
1049 alternately.
1050 .
1051 .
1052 .TP
1053 .BI .RI " roman-text italic-text "\c
1054 \&.\|.\|.\&
1055 Set each argument in roman and italics,
1056 alternately.
1057 .
1058 .
1059 .\" ====================================================================
1060 .SS "Horizontal and vertical spacing"
1061 .\" ====================================================================
1062 .
1063 The
1064 .I indentation
1065 argument accepted by
1066 .BR .IP ,
1067 .BR .TP ,
1068 and the deprecated
1069 .B .HP
1070 is a number plus an optional scaling unit,
1071 as is
1072 .BR .RS 's
1073 .IR inset-amount .
1074 .
1075 If no scaling unit is given,
1076 the
1077 .I man
1078 package assumes \(lqn\(rq.
1079 .
1080 An indentation specified in a call to
1081 .BR .IP ,
1082 .BR .TP ,
1083 or the deprecated
1084 .B .HP
1085 persists until
1086 (1) another of these macros is called with an
1087 .I indentation
1088 argument,
1089 or
1090 (2)
1091 .BR .SH ,
1092 .BR .SS ,
1093 or
1094 .B .P
1095 or its synonyms is called;
1096 these clear the indentation entirely.
1097 .
1098 .
1099 .P
1100 The left margin used by ordinary paragraphs set with
1101 .B .P
1102 (and its synonyms)
1103 not within an
1104 .BR .RS / .RE
1105 relative inset
1106 .\" TODO: future: BP or BI register ("base paragraph indentation")
1107 is 7.2n for typesetting devices
1108 and 7n for terminal devices
1109 (but see the
1110 .B \-rIN
1111 option).
1112 .
1113 Headers,
1114 footers
1115 (both set with
1116 .BR .TH ),
1117 and section headings
1118 .RB ( .SH )
1119 are set at the page offset
1120 (see
1121 .MR groff 7 )
1122 and subsection headings
1123 .RB ( .SS )
1124 indented from it by 3n
1125 (but see the
1126 .B \-rSN
1127 option).
1128 .
1129 .\" XXX: This is not true, but they do handle it badly.
1130 .\" HTML output devices ignore indentation.
1131 .
1132 .
1133 .P
1134 Several macros insert vertical space:
1135 .BR .SH ,
1136 .BR .SS ,
1137 .BR .TP ,
1138 .B .P
1139 (and its synonyms),
1140 .BR .IP ,
1141 and the deprecated
1142 .BR .HP .
1143 .
1144 The default inter-section and inter-paragraph spacing is
1145 is 1v for terminal devices
1146 and 0.4v for typesetting devices.
1147 .
1148 (The deprecated macro
1149 .B .PD
1150 can change this vertical spacing,
1151 but its use is discouraged.)
1152 .
1153 Between
1154 .B .EX
1155 and
1156 .B .EE
1157 calls,
1158 the inter-paragraph spacing is 1v regardless of output
1159 device.
1160 .
1161 .
1162 .\" ====================================================================
1163 .SS Registers
1164 .\" ====================================================================
1165 .
1166 Registers are described in section \(lqOptions\(rq below.
1167 .
1168 They can be set not only on the command line but in the site
1169 .I man.local
1170 file as well;
1171 see section \(lqFiles\(rq below.
1172 .
1173 .
1174 .br
1175 .ne 7v
1176 .\" ====================================================================
1177 .SS Strings
1178 .\" ====================================================================
1179 .
1180 The following strings are defined for use in man pages.
1181 .
1182 None of these is necessary in a contemporary man page;
1183 see
1184 .MR groff_man_style 7 .
1185 .
1186 Others are supported for configuration of rendering parameters;
1187 see section \(lqOptions\(rq below.
1188 .
1189 .
1190 .TP
1191 .B \e*R
1192 interpolates a special character escape sequence for the \(lqregistered
1193 sign\(rq glyph,
1194 .BR \e(rg ,
1195 if available,
1196 and \(lq(Reg.)\(rq otherwise.
1197 .
1198 .
1199 .
1200 .TP
1201 .B \e*S
1202 interpolates an escape sequence setting the type size to the document
1203 default.
1204 .
1205 .
1206 .TP
1207 .B \e*(lq
1208 .TQ
1209 .B \e*(rq
1210 interpolate special character escape sequences for left and right
1211 double-quotation marks,
1212 .B \e(lq
1213 and
1214 .BR \e(rq ,
1215 respectively.
1216 .
1217 .
1218 .TP
1219 .B \e*(Tm
1220 interpolates a special character escape sequence for the \(lqtrade mark
1221 sign\(rq glyph,
1222 .BR \e(tm ,
1223 if available,
1224 and \(lq(TM)\(rq otherwise.
1225 .
1226 .
1227 .\" ====================================================================
1228 .SS Hooks
1229 .\" ====================================================================
1230 .
1231 Two macros,
1232 both GNU extensions,\" from groff 1.19
1233 are called internally by the
1234 .I groff man
1235 package to format page headers and footers and can be redefined by the
1236 administrator in a site's
1237 .I man.local
1238 file
1239 (see section \(lqFiles\(rq below).
1240 .
1241 The presentation of
1242 .B .TH
1243 above describes the default headers and footers.
1244 .
1245 Because these macros are hooks for
1246 .I groff man
1247 internals,
1248 man pages have no reason to call them.
1249 .
1250 Such hook definitions will likely consist of \[lq].sp\[rq] and
1251 \[lq].tl\[rq] requests.
1252 .
1253 They must also increase the page length with \[lq].pl\[rq] requests in
1254 continuous rendering mode;
1255 .B .PT
1256 furthermore has the responsibility of emitting a PDF bookmark after
1257 writing the first page header in a document.
1258 .
1259 Consult the existing implementations in
1260 .I an.tmac
1261 when drafting replacements.
1262 .
1263 .
1264 .TP
1265 .B .BT
1266 Set the page footer text
1267 (\(lqbottom trap\(rq).
1268 .
1269 .
1270 .TP
1271 .B .PT
1272 Set the page header text
1273 (\(lqpage trap\(rq).
1274 .
1275 .
1276 .P
1277 To remove a page header or footer entirely,
1278 define the appropriate macro as empty rather than deleting it.
1279 .
1280 .
1281 .\" ====================================================================
1282 .SS "Deprecated features"
1283 .\" ====================================================================
1284 .
1285 Use of the following in man pages for public distribution is
1286 discouraged.
1287 .
1288 .
1289 .TP
1290 .BR .AT " ["\c
1291 .IR system " [" release ]]
1292 Alter the footer for use with legacy AT&T man pages,
1293 overriding any definition of the
1294 .I footer-inside
1295 argument to
1296 .BR .TH .
1297 .
1298 This macro exists only to render man pages from historical systems.
1299 .
1300 .
1301 .IP
1302 .I system
1303 can be any of the following.
1304 .
1305 .
1306 .RS \" Invisibly move left margin to current .IP indentation.
1307 .RS \" Now indent further, visibly.
1308 .TP
1309 3
1310 7th edition
1311 .I (default)
1312 .
1313 .
1314 .TP
1315 4
1316 System III
1317 .
1318 .
1319 .TP
1320 5
1321 System V
1322 .RE \" Move left margin back to .IP indentation.
1323 .RE \" Move left margin back to standard position.
1324 .
1325 .
1326 .IP
1327 The optional
1328 .I release
1329 argument specifies the release number,
1330 as in \(lqSystem\~V Release\~3\(rq.
1331 .
1332 .
1333 .TP
1334 .B .DT
1335 Reset tab stops to the default
1336 (every 0.5i).
1337 .
1338 .IP
1339 Use of this presentation-oriented macro is deprecated.
1340 .
1341 It translates poorly to HTML,
1342 under which exact space control and tabulation are not readily
1343 available.
1344 .
1345 Thus,
1346 information or distinctions that you use tab stops to express are likely
1347 to be lost.
1348 .
1349 If you feel tempted to change the tab stops such that calling this macro
1350 later is desirable to restore them,
1351 you should probably be composing a table using
1352 .MR \%tbl 1
1353 instead.
1354 .
1355 .
1356 .TP
1357 .BR .HP " ["\c
1358 .IR indentation ]
1359 Set up a paragraph with a hanging left indentation.
1360 .
1361 The
1362 .I indentation
1363 argument,
1364 if present,
1365 is handled as with
1366 .BR .TP .
1367 .
1368 .
1369 .IP
1370 Use of this presentation-oriented macro is deprecated.
1371 .
1372 A hanging indentation cannot be expressed naturally under HTML,
1373 and
1374 .RI non- roff -based
1375 man page interpreters may treat
1376 .B .HP
1377 as an ordinary paragraph.
1378 .
1379 Thus,
1380 information or distinctions you mean to express with indentation may be
1381 lost.
1382 .
1383 .
1384 .TP
1385 .BI .OP " option-name"\/\c
1386 .RI " [" option-argument ]
1387 Indicate an optional command parameter called
1388 .IR option-name ,
1389 which is set in bold.
1390 .
1391 If the option takes an argument,
1392 specify
1393 .I option-argument
1394 using a noun,
1395 abbreviation,
1396 or hyphenated noun phrase.
1397 .
1398 If present,
1399 .I option-argument
1400 is preceded by a space and set in italics.
1401 .
1402 Square brackets in roman surround both arguments.
1403 .
1404 .
1405 .IP
1406 Use of this quasi-semantic macro,
1407 .\" https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/an.sr#L37
1408 an extension originating in Documenter's Workbench
1409 .IR troff ,\" DWB
1410 is deprecated.
1411 .
1412 It cannot easily be used to annotate options that take optional
1413 arguments or options whose arguments have internal structure
1414 (such as a mixture of literal and variable components).
1415 .
1416 One could work around these limitations with font selection escape
1417 sequences,
1418 but it is preferable to use font style alternation macros,
1419 which afford greater flexibility.
1420 .
1421 .
1422 .TP
1423 .BR .PD " ["\c
1424 .IR vertical-space ]
1425 Define the vertical space between paragraphs or (sub)sections.
1426 .
1427 The optional argument
1428 .I vertical-space
1429 specifies the amount;
1430 the default scaling unit is \(lqv\(rq.
1431 .
1432 Without an argument,
1433 the spacing is reset to its default value;
1434 see subsection \(lqHorizontal and vertical spacing\(rq above.
1435 .
1436 .
1437 .IP
1438 Use of this presentation-oriented macro is deprecated.
1439 .
1440 It translates poorly to HTML,
1441 under which exact control of inter-paragraph spacing is not readily
1442 available.
1443 .
1444 Thus,
1445 information or distinctions that you use
1446 .B .PD
1447 to express are likely to be lost.
1448 .
1449 .
1450 .TP
1451 .BR .UC " ["\c
1452 .IR version ]
1453 Alter the footer for use with legacy BSD man pages,
1454 overriding any definition of the
1455 .I footer-inside
1456 argument to
1457 .BR .TH .
1458 .
1459 This macro exists only to render man pages from historical systems.
1460 .
1461 .
1462 .IP
1463 .I version
1464 can be any of the following.
1465 .
1466 .
1467 .RS \" Invisibly move left margin to current .IP indentation.
1468 .RS \" Now indent further, visibly.
1469 .TP
1470 3
1471 3rd Berkeley Distribution
1472 .I (default)
1473 .
1474 .
1475 .TP
1476 4
1477 4th Berkeley Distribution
1478 .
1479 .
1480 .TP
1481 5
1482 4.2 Berkeley Distribution
1483 .
1484 .
1485 .TP
1486 6
1487 4.3 Berkeley Distribution
1488 .
1489 .
1490 .TP
1491 7
1492 4.4 Berkeley Distribution
1493 .RE \" Move left margin back to .IP indentation.
1494 .RE \" Move left margin back to standard position.
1495 .
1496 .
1497 .\" ====================================================================
1498 .SS History
1499 .\" ====================================================================
1500 .
1501 .MT [email protected]
1502 M.\& Douglas McIlroy
1503 .ME
1504 designed,
1505 implemented,
1506 and documented the AT&T
1507 .I man
1508 macros
1509 for
1510 Unix Version\~7 (1979) and employed them
1511 to edit the first volume of its
1512 .IR "Programmer's Manual" ,
1513 a compilation of all man pages supplied by the system.
1514 .
1515 That
1516 .I man
1517 supported the macros listed in this page not described as extensions,
1518 except
1519 .B .P
1520 .\" .SS was implemented in tmac.an but not documented in man(7).
1521 and the deprecated
1522 .B .AT
1523 and
1524 .BR .UC .
1525 .
1526 The only strings defined were
1527 .B R
1528 and
1529 .BR S ;
1530 no registers were documented.
1531 .
1532 .
1533 .P
1534 .B .UC
1535 appeared in 3BSD (1980).
1536 .
1537 .\" per https://archive.org/details/\
1538 .\" bitsavers_attunixSysalRelease3Jun80_33886798
1539 Unix System\~III (1980) introduced
1540 .B .P
1541 .\" ...and de-documented .LP...
1542 and exposed the registers
1543 .B IN
1544 and
1545 .BR LL ,
1546 .\" ...as well as \n[PD], which we implement but don't expose.
1547 which had been internal to Seventh Edition Unix
1548 .IR man .
1549 .
1550 .\" This inference is based on RCS idents of "PWB Manual Entry Macros"
1551 .\" from various forms of "an.src" distributed with System III (an.src
1552 .\" 1.35, dated 5/6/80, lacks the Tm string), Research Unix Version 10
1553 .\" (1.36, dated 11/11/80, has it), Ultrix 3.1 (1.37, dated 12/19/80,
1554 .\" retains it) and "pdp11v" (also 1.37). One source (S. S. Pirzada)
1555 .\" says PWB 2.0 was released in June 1979. I found no record of later
1556 .\" releases and cannot account for the discrepancy (field updates?).
1557 .\" -- GBR
1558 PWB/UNIX 2.0 (1980) added the
1559 .B Tm
1560 string.
1561 .
1562 4BSD (1980) added
1563 .\" undocumented .VS and .VE macros to mark regions with 12-point box
1564 .\" rules (\[br]) as margin characters, as well as...
1565 .B lq
1566 and
1567 .B rq
1568 strings.
1569 .
1570 .\" The SunOS inferences here and below are based on inspection of SunOS
1571 .\" 2.0 (May 1985), 3.2 (September 1986), 3.5 (January 1988), and 4.0
1572 .\" (December 1988) tape archives (only).
1573 SunOS\~2.0 (1985) recognized
1574 .BR C ,
1575 .BR D ,
1576 .BR P ,
1577 and
1578 .B X
1579 registers.
1580 .
1581 4.3BSD (1986) added
1582 .\" undocumented .DS and .DE macros for "displays", which are .RS/.RE
1583 .\" wrappers with filling disabled and vertical space of 1v before and
1584 .\" .5v after, as well as...
1585 .B .AT
1586 and
1587 .BR .P .
1588 .
1589 .\" Per Doug McIlroy in
1590 .\" <https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html>...
1591 Ninth Edition Research Unix (1986) introduced
1592 .B .EX
1593 and
1594 .BR .EE .
1595 .
1596 SunOS\~4.0 (1988) added
1597 .BR .SB .
1598 .
1599 .
1600 .P
1601 The foregoing features were what James Clark implemented in early
1602 versions of
1603 .IR groff .
1604 .
1605 .
1606 Later,
1607 .I groff
1608 1.20 (2009) originated
1609 .BR .SY / .YS ,
1610 .BR .TQ ,
1611 .BR .MT / .ME ,
1612 and
1613 .BR .UR / .UE .
1614 .\" ...along with implementations of OP, EX, and EE.
1615 .
1616 Plan\~9 from User Space's
1617 .I troff \" plan9port
1618 introduced
1619 .B .MR
1620 in 2020.
1621 .\" https://github.com/9fans/plan9port/commit/\
1622 .\" 977b25a76ae8263e53fb4eb1abfc395769f23e3d
1623 .\" d32deab17bfffa5bffc5fab3e6577558e40888c5
1624 .\" 36cd4c58c1346375b98f517fb8568be5bb47618d
1625 .
1626 .
1627 .br
1628 .ne 4v
1629 .\" ====================================================================
1630 .SH Options
1631 .\" ====================================================================
1632 .
1633 The following
1634 .I groff
1635 options set registers
1636 (with
1637 .BR \-r )
1638 and strings
1639 (with
1640 .BR \-d )
1641 recognized and used by the
1642 .I man
1643 macro package.
1644 .
1645 To ensure rendering consistent with output device capabilities and
1646 reader preferences,
1647 man pages should never manipulate them.
1648 .
1649 .
1650 .TP
1651 .BI \-dAD= adjustment-mode
1652 Set line adjustment to
1653 .I adjustment-mode,
1654 which is typically
1655 .RB \[lq] b \[rq]
1656 for adjustment to both margins
1657 (the default),
1658 or
1659 .RB \[lq] l \[rq]
1660 for left alignment
1661 (ragged right margin).
1662 .
1663 Any valid argument to
1664 .IR groff 's
1665 \[lq].ad\[rq] request may be used.
1666 .
1667 See
1668 .MR groff 7
1669 for less-common choices.
1670 .
1671 .
1672 .TP
1673 .B \-rcR=1
1674 Enable continuous rendering.
1675 .
1676 Output is not paginated;
1677 instead,
1678 one
1679 (potentially very long)
1680 page is produced.
1681 .
1682 This is the default for terminal and HTML devices.
1683 .
1684 Use
1685 .B \-rcR=0
1686 to disable it on terminal devices;
1687 on HTML devices,
1688 it cannot be disabled.
1689 .
1690 .
1691 .TP
1692 .B \-rC1
1693 Number output pages consecutively,
1694 in strictly increasing sequence,
1695 rather than resetting the page number to\~1
1696 (or the value of register
1697 .BR P )
1698 with each new
1699 .I man
1700 document.
1701 .
1702 .
1703 .TP
1704 .B \-rCS=1
1705 Set section headings
1706 (the argument(s) to
1707 .BR .SH )
1708 in full capitals.
1709 .
1710 This transformation is off by default because it discards case
1711 distinction information.
1712 .
1713 .
1714 .TP
1715 .B \-rCT=1
1716 Set the man page topic
1717 (the first argument to
1718 .BR .TH )
1719 in full capitals in headers and footers.
1720 .
1721 This transformation is off by default because it discards case
1722 distinction information.
1723 .
1724 .
1725 .TP
1726 .B \-rD1
1727 Enable double-sided layout,
1728 formatting footers for even and odd pages differently;
1729 see the description of
1730 .B .TH
1731 in subsection \(lqDocument structure macros\(rq above.
1732 .
1733 .
1734 .TP
1735 .BI \-rFT= footer-distance
1736 Set distance of the footer relative to the bottom of the page to
1737 .I footer-distance;
1738 this amount is always negative.
1739 .
1740 At one half-inch above this location,
1741 the page text is broken before writing the footer.
1742 .
1743 Ignored if continuous rendering is enabled.
1744 .
1745 The default is \-0.5i.
1746 .
1747 .
1748 .TP
1749 .BI \-dHF= heading-font
1750 Set the font used for section and subsection headings;
1751 the default is
1752 .RB \(lq B \(rq
1753 (bold style of the default family).
1754 .
1755 Any valid argument to
1756 .IR groff 's
1757 \[lq].ft\[rq] request may be used.
1758 .
1759 See
1760 .MR groff 7 .
1761 .
1762 .
1763 .TP
1764 .B \-rHY=0
1765 Disable automatic hyphenation.
1766 .
1767 Normally,
1768 it is enabled\~(1).
1769 .
1770 The hyphenation mode is determined by the
1771 .I groff
1772 locale;
1773 see section \[lq]Localization\[lq] of
1774 .MR groff 7 .
1775 .
1776 .
1777 .TP
1778 .BI \-rIN= standard-indentation
1779 Set the amount of indentation used for ordinary paragraphs
1780 .RB ( .P
1781 and its synonyms)
1782 and the default indentation amount used by
1783 .BR .IP ,
1784 .BR .RS ,
1785 .BR .TP ,
1786 .\" .TQ inherits its indentation from the preceding .TP.
1787 and the deprecated
1788 .BR .HP .
1789 .
1790 See subsection \(lqHorizontal and vertical spacing\(rq above for the
1791 default.
1792 .
1793 For
1794 terminal devices,
1795 .I standard-indentation
1796 should always be an integer multiple of unit \(lqn\(rq to get consistent
1797 indentation.
1798 .
1799 .
1800 .TP
1801 .BI \-rLL= line-length
1802 Set line length;
1803 the default is 78n for terminal devices
1804 and 6.5i for typesetting devices.
1805 .
1806 .
1807 .TP
1808 .BI \-rLT= title-length
1809 Set the line length for titles.
1810 .
1811 By default,
1812 it is set to the line length
1813 (see
1814 .B \-rLL
1815 above).
1816 .
1817 .
1818 .TP
1819 .BI \-dMF= man-page-topic-font
1820 Set the font used for man page topics named in
1821 .B .TH
1822 and
1823 .B .MR
1824 calls;
1825 the default is
1826 .RB \(lq I \(rq
1827 (italic style of the default family).
1828 .
1829 Any valid argument to
1830 .IR groff 's
1831 \[lq].ft\[rq] request may be used.
1832 .
1833 If the
1834 .B MF
1835 string ends in \[lq]I\[rq],
1836 it is assumed to be an oblique typeface,
1837 and italic corrections are applied before and after man page topics.
1838 .
1839 .
1840 .TP
1841 .BI \-rP n
1842 Start enumeration of pages at
1843 .IR n .
1844 .
1845 The default is\~1.
1846 .
1847 .
1848 .TP
1849 .BI \-rS type-size
1850 Use
1851 .I type-size
1852 for the document's body text;
1853 acceptable values are 10,
1854 11,
1855 or 12 points.
1856 .
1857 See subsection \(lqFont style macros\(rq above for the default.
1858 .
1859 .
1860 .TP
1861 .BI \-rSN= subsection-indentation
1862 Set indentation of subsection headings to
1863 .I subsection-indentation.
1864 .
1865 See subsection \(lqHorizontal and vertical spacing\(rq above for the
1866 default.
1867 .
1868 .
1869 .br
1870 .ne 4v
1871 .TP
1872 .B \-rU1
1873 Enable generation of URI hyperlinks in the
1874 .I grohtml
1875 and
1876 .I grotty
1877 output drivers.
1878 .
1879 .I grohtml
1880 enables them by default;
1881 .I grotty
1882 does not,
1883 pending more widespread pager support for OSC\~8 escape sequences.
1884 .
1885 Use
1886 .B \-rU0
1887 to disable hyperlinks;
1888 this will make the arguments to
1889 .B MT
1890 and
1891 .B UR
1892 calls visible in the document text produced by link-capable drivers.
1893 .
1894 .
1895 .TP
1896 .BI \-rX p
1897 Number successors of
1898 .RI page\~ p
1899 as
1900 .IR p a,
1901 .IR p b,
1902 .IR p c,
1903 and so forth.
1904 .
1905 The register tracking the suffixed page letter uses format \(lqa\(rq
1906 (see the \(lq.af\(rq request in
1907 .MR groff 7 ).
1908 .
1909 .
1910 .
1911 .\" ====================================================================
1912 .SH Files
1913 .\" ====================================================================
1914 .
1915 .TP
1916 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:an\:.tmac
1917 Most
1918 .I man
1919 macros are defined in this file.
1920 .
1921 It also loads extensions from
1922 .I \%an\-ext.tmac
1923 (see below).
1924 .
1925 .
1926 .TP
1927 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%andoc\:.tmac
1928 This brief
1929 .I groff
1930 program detects whether the
1931 .I man
1932 or
1933 .I mdoc
1934 macro package is being used by a document and loads the correct macro
1935 definitions,
1936 taking advantage of the fact that pages using them must call
1937 .B .TH
1938 or
1939 .BR .Dd ,
1940 respectively,
1941 before any other macros.
1942 .
1943 A
1944 .I man
1945 program or user typing,
1946 for example,
1947 .RB \[lq] "groff \-mandoc page.1" \[rq],
1948 need not know which package the file
1949 .I page.1
1950 uses.
1951 .
1952 Multiple man pages,
1953 in either format,
1954 can be handled;
1955 .I \%andoc
1956 reloads each macro package as necessary.
1957 .
1958 .
1959 .TP
1960 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%an\-ext\:.tmac
1961 Except for
1962 .BR .SB ,
1963 definitions of macros described above as extensions
1964 are contained in this file;
1965 in some cases,
1966 they are simpler versions of definitions appearing in
1967 .IR an.tmac ,
1968 and are ignored if the formatter is GNU
1969 .IR troff .\" GNU
1970 .
1971 They are written to be compatible with AT&T
1972 .I troff \" AT&T
1973 and permissively licensed\(emnot copylefted.
1974 .
1975 To reduce the risk of name space collisions,
1976 string and register names begin only with
1977 .RB \[lq] m \[rq] .
1978 .
1979 We encourage man page authors
1980 who are concerned about portability to legacy Unix systems
1981 to copy these definitions into their pages,
1982 and maintainers of
1983 .I troff \" generic
1984 implementations or work-alike systems that format man pages
1985 to re-use them.
1986 .
1987 .
1988 .IP
1989 The definitions for these macros are read after a page calls
1990 .BR .TH ,
1991 so they will replace any macros of the same names preceding it in your
1992 file.
1993 .
1994 If you use your own implementations of these macros,
1995 they must be defined after
1996 .B .TH
1997 is called to have any effect.
1998 .
1999 Furthermore,
2000 it is wise to define such page-local macros
2001 (if at all)
2002 after the \(lqName\(rq section to accommodate timid
2003 .I makewhatis
2004 or
2005 .I mandb
2006 implementations that may give up their scan for indexing material early.
2007 .
2008 .
2009 .TP
2010 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:man\:.tmac
2011 This is a wrapper that loads
2012 .IR an.tmac .
2013 .
2014 .
2015 .TP
2016 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%mandoc\:.tmac
2017 This is a wrapper that loads
2018 .IR \%andoc.tmac .
2019 .
2020 .
2021 .TP
2022 .I /usr/\:\%share/\:\%groff/\:\%site\-tmac/\:\%man\:\%.local
2023 Put site-local changes and customizations into this file.
2024 .
2025 .
2026 .\" ====================================================================
2027 .SH Authors
2028 .\" ====================================================================
2029 .
2030 The initial GNU implementation of the
2031 .I man
2032 macro package was written by James Clark. \" by 1.01
2033 .
2034 Later,
2035 .MT wl@\:gnu\:.org
2036 Werner Lemberg
2037 .ME
2038 supplied the
2039 .BR S , \" 1.16
2040 .BR LT , \" 1.18
2041 and
2042 .B cR \" 1.17
2043 registers,
2044 the last a 4.3BSD-Reno
2045 .IR mdoc (7)
2046 feature.
2047 .\" "Assume nroff on crt's [sic] only if cR==1"
2048 .\" https://minnie.tuhs.org/cgi-bin/utree.pl
2049 .\" ?file=4.3BSD-Reno/share/tmac/tmac.doc
2050 .
2051 .MT kollar@\:alltel\:.net
2052 Larry Kollar
2053 .ME
2054 added the
2055 .BR FT ,
2056 .BR HY ,
2057 and
2058 .B SN
2059 registers;
2060 the
2061 .B HF
2062 string;
2063 and the
2064 .B PT
2065 and
2066 .B BT
2067 macros.
2068 .
2069 .MT g.branden\:.robinson@\:gmail\:.com
2070 G.\& Branden Robinson
2071 .ME
2072 implemented the
2073 .B AD
2074 and
2075 .B MF
2076 strings;
2077 .BR CS ,
2078 .BR CT ,
2079 and
2080 .B U
2081 registers;
2082 and the
2083 .B MR
2084 macro. \" all 1.23
2085 .
2086 .
2087 Except for
2088 .BR .SB , \" Clark, as noted above
2089 the extension macros were written by
2090 Lemberg,
2091 .MT esr@\:thyrsus\:.com
2092 Eric S.\& Raymond
2093 .ME ,
2094 and
2095 Robinson. \" 1.23: MR
2096 .
2097 .
2098 .br
2099 .ne 3v
2100 .P
2101 This document was originally written for the Debian GNU/Linux system by
2102 .MT sgk@\:debian\:.org
2103 Susan G.\& Kleinmann
2104 .ME .
2105 .
2106 It was corrected and updated by Lemberg and Robinson.
2107 .
2108 The extension macros were documented by Raymond and Robinson.
2109 .
2110 .
2111 .\" ====================================================================
2112 .SH "See also"
2113 .\" ====================================================================
2114 .
2115 .MR \%tbl 1 ,
2116 .MR \%eqn 1 ,
2117 and
2118 .MR \%refer 1
2119 are preprocessors used with man pages.
2120 .
2121 .MR man 1
2122 describes the man page librarian on your system.
2123 .
2124 .MR groff_mdoc 7
2125 details the
2126 .I groff
2127 version of the BSD-originated alternative macro package for man pages.
2128 .
2129 .
2130 .P
2131 .MR groff_man_style 7 ,
2132 .MR groff 7 ,
2133 .MR groff_char 7 ,
2134 .MR man 7
2135 .
2136 .
2137 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
2138 .cp \n[*groff_groff_man_7_man_C]
2139 .do rr *groff_groff_man_7_man_C
2140 .
2141 .
2142 .\" Local Variables:
2143 .\" fill-column: 72
2144 .\" mode: nroff
2145 .\" End:
2146 .\" vim: set filetype=groff textwidth=72: