Debian Codegraph @

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