Debian Codegraph @

upstream/debian-unstable/man7/groff_man_style.7

raw
1 '\" t
2 .\" This page is generated by m4 from tmac/groff_man.7.man.in.
3 .TH groff_man_style 7 "2026-04-22" "groff 1.24.1"
4 .SH Name
5 groff_man_style \- GNU
6 .I roff
7 man page tutorial and style guide
8 .
9 .
10 .\" ====================================================================
11 .\" Legal Terms
12 .\" ====================================================================
13 .\"
14 .\" Copyright 1999-2017 Free Software Foundation, Inc.
15 .\" 2017 Ingo Schwarze
16 .\" 2017-2025 G. Branden Robinson
17 .\"
18 .\" Permission is granted to make and distribute verbatim copies of this
19 .\" manual provided the copyright notice and this permission notice are
20 .\" preserved on all copies.
21 .\"
22 .\" Permission is granted to copy and distribute modified versions of
23 .\" this manual under the conditions for verbatim copying, provided that
24 .\" the entire resulting derived work is distributed under the terms of
25 .\" a permission notice identical to this one.
26 .\"
27 .\" Permission is granted to copy and distribute translations of this
28 .\" manual into another language, under the above conditions for
29 .\" modified versions, except that this permission notice may be
30 .\" included in translations approved by the Free Software Foundation
31 .\" instead of in the original English.
32 .
33 .
34 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
35 .do nr *groff_groff_man_7_man_C \n[.cp]
36 .cp 0
37 .
38 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
39 .nr do-fallback 0
40 .if !\n(.f .nr do-fallback 1 \" mandoc
41 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
42 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
43 .if \n[do-fallback] \{\
44 . de MR
45 . ie \\n(.$=1 \
46 . I \%\\$1
47 . el \
48 . IR \%\\$1 (\\$2)\\$3
49 . .
50 .\}
51 .rr do-fallback
52 .
53 .
54 .\" ====================================================================
55 .SH Synopsis
56 .\" ====================================================================
57 .
58 .SY "groff \-man"
59 .RI [ option\~ .\|.\|.\&]
60 .RI [ file\~ .\|.\|.]
61 .YS
62 .
63 .SY "groff \-m man"
64 .RI [ option\~ .\|.\|.\&]
65 .RI [ file\~ .\|.\|.]
66 .YS
67 .
68 .
69 .\" ====================================================================
70 .SH Description
71 .\" ====================================================================
72 .
73 The GNU implementation of the
74 .I man
75 macro package is part of the
76 .I groff
77 document formatting system.
78 .
79 It is used to compose manual pages
80 .\" We use an unbreakable space \~ here to keep the phrase intact for
81 .\" its introduction; in subsequent discussion, that is not important.
82 (\[lq]man\~pages\[rq])
83 like the one you are reading.
84 .
85 This document presents the macros thematically;
86 for those needing only a quick reference,
87 the following table lists them alphabetically,
88 with references to appropriate subsections below.
89 Experienced
90 .I man
91 authors may prefer
92 .MR groff_man 7 .
93 .
94 .
95 .P
96 .if t .vs 11.75p \" begin hideous cheat for U.S. letter paper
97 .if n .if \n[LL]<68n .RS -3n \" begin shameless cheat for slim terminals
98 .TS
99 l l l.
100 Macro Meaning Subsection
101 .T&
102 lB l l.
103 _
104 \&.B Bold Font style macros
105 \&.BI Bold, italic alternating Font style macros
106 \&.BR Bold, roman alternating Font style macros
107 \&.EE Example end Document structure macros
108 \&.EX Example begin Document structure macros
109 \&.HP Begin hanging paragraph Paragraphing macros
110 \&.I Italic Font style macros
111 \&.IB Italic, bold alternating Font style macros
112 \&.IP Indented paragraph Paragraphing macros
113 \&.IR Italic, roman alternating Font style macros
114 \&.LP Begin paragraph Paragraphing macros
115 \&.ME Mail-to end Hyperlink macros
116 \&.MR Man page cross reference Hyperlink macros
117 \&.MT Mail-to start Hyperlink macros
118 \&.P Begin paragraph Paragraphing macros
119 \&.PP Begin paragraph Paragraphing macros
120 \&.RB Roman, bold alternating Font style macros
121 \&.RE Relative inset end Document structure macros
122 \&.RI Roman, italic alternating Font style macros
123 \&.RS Relative inset start Document structure macros
124 \&.SH Section heading Document structure macros
125 \&.SM Small Font style macros
126 \&.SS Subsection heading Document structure macros
127 \&.SY Synopsis start Synopsis macros
128 \&.TH Title heading Document structure macros
129 \&.TP Tagged paragraph Paragraphing macros
130 \&.TQ Supplemental paragraph tag Paragraphing macros
131 \&.UE URI end Hyperlink macros
132 \&.UR URI start Hyperlink macros
133 \&.YS Synopsis end Synopsis macros
134 .TE
135 .if n .if \n[LL]<68n .RE \" end shameless cheat for slim terminals
136 .if t .vs \" end hideous cheat for U.S. letter paper
137 .
138 .
139 .P
140 We discuss other macros
141 .RB ( AT ,
142 .BR DT ,
143 .BR OP ,
144 .BR PD ,
145 .BR SB ,
146 and
147 .BR UC )
148 in subsection \[lq]Deprecated features\[rq] below.
149 .
150 .
151 .P
152 Throughout Unix documentation,
153 a manual entry is referred to simply as a \[lq]man page\[rq],
154 regardless of its length,
155 without gendered implication,
156 and irrespective of the macro package selected for its composition.
157 .
158 .
159 .P
160 A man page employs the Unix line-ending convention
161 (U+000A only).
162 .
163 Some basic Latin characters have special meaning to
164 .I roff;
165 see subsection \[lq]Portability\[rq] below.
166 .
167 .
168 .\" ====================================================================
169 .SS "Fundamental concepts"
170 .\" ====================================================================
171 .
172 .I groff
173 is a programming system for typesetting:
174 we thus often use the verb \[lq]to set\[rq] in the sense
175 \[lq]to typeset\[rq].
176 .
177 The formatter
178 .MR \%troff 1
179 collects words from the input and
180 .I fills
181 output lines with as many as can fit.
182 .
183 .I Words
184 are separated by spaces and newlines.
185 .\" Also tabs and leaders, but let's not discuss those in man(7).
186 .
187 A transition to a new output line is called a
188 .I break.
189 .
190 Breaks can occur at explicit hyphens,
191 at
192 .B \e%
193 or
194 .B \e:
195 escape sequences
196 (see subsection \[lq]Portability\[rq] below),
197 or at predetermined locations in a word
198 if automatic hyphenation is enabled
199 (see the
200 .B \-rHY
201 option in section \[lq]Options\[rq] below).
202 .
203 An output line may be supplemented with
204 .I "inter-sentence space,"
205 then potentially
206 .I adjusted
207 with more space to a consistent length
208 (see the
209 .B \-dAD
210 option).
211 .
212 .MR roff 7
213 details these processes.
214 .
215 The formatter prepares output for
216 .I terminals
217 or for more capable
218 .I typesetters
219 that can change the type size and font family.
220 .
221 .
222 .P
223 A
224 .I roff
225 document can contain
226 .I "control lines,"
227 which start with a dot
228 .RB ( .\& )
229 or neutral apostrophe
230 .RB ( \[aq] ).
231 .
232 All other input lines are
233 .I "text lines"
234 to be formatted.
235 .
236 A
237 .I macro
238 collects control and/or text lines
239 to ease document composition.
240 .
241 .I man
242 is a
243 .I "macro package."
244 .
245 To call a macro,
246 put its name after a dot on a control line.
247 .\" You never need to indent macro calls in man(7), or call them with
248 .\" the no-break control character.
249 .
250 Some macros interpret
251 .I arguments,
252 words that follow its name.
253 .
254 A newline,
255 unless escaped
256 (see subsection \[lq]Portability\[rq] below),
257 marks the end of the macro call.
258 .
259 A control line with no macro name on it is called an
260 .I "empty request;"
261 it does nothing.
262 .
263 .
264 .P
265 We describe below several
266 .I man
267 macros that plant one-line
268 .I "input traps:"
269 the next input line that directly produces formatted output is treated
270 specially.
271 .
272 For
273 .I man
274 documents that follow the advice in section
275 \[lq]Portability\[rq] below,
276 this means that control lines using the empty request
277 and uncommented input lines ending with an escaped newline
278 do not spring the trap;
279 anything else does
280 (but see the
281 .B TP
282 macro description).
283 .
284 .
285 .\" ====================================================================
286 .\" .SS "Why have a tutorial and style guide?"
287 .\" ====================================================================
288 .\" the processing pipeline in brief
289 .\" preprocessors, roff itself, various output devices
290 .\" Things that aren't groff--why you want the man page language to be
291 .\" small (mandoc, Kerrisk's man7.org, manpages.debian.org, non-expert
292 .\" humans).
293 .\" possibly exhibit a horrorshow docbook-to-man example
294 .
295 .
296 .\" ====================================================================
297 .SS "Macro reference preliminaries"
298 .\" ====================================================================
299 .
300 A tagged paragraph describes each macro.
301 .
302 We present coupled pairs together,
303 as with
304 .B EX
305 and
306 .BR EE .
307 .
308 Square brackets surround optional macro arguments.
309 .
310 If a macro accepts multiple arguments,
311 those containing space \" or tab (in Plan 9 troff [only?])
312 characters must be double-quoted to be interpreted correctly.
313 .
314 If you require an empty macro argument,
315 specify it as a pair of neutral double quotes
316 .RB ( \[dq]\^\[dq] ).
317 .
318 See section \[lq]Notes\[rq] below for examples of cases where better
319 alternatives to empty arguments in macro calls are available.
320 .
321 Most macro arguments are formatted as text in the output;
322 exceptions are noted.
323 .
324 We identify some macros as
325 .I extensions
326 to the set originally implemented.
327 .
328 They are not supported everywhere;
329 see subsection \[lq]Use of extensions\[rq]
330 below.
331 .
332 .
333 .\" ====================================================================
334 .SS "Document structure macros"
335 .\" ====================================================================
336 .
337 Document structure macros organize a man page's content.
338 .
339 All of them break the output line.
340 .
341 .B TH
342 (title heading)
343 identifies the document as a man page and configures the page headers
344 and footers.
345 .
346 Section headings
347 .RB ( SH ),
348 one of which is mandatory and many of which are conventionally expected,
349 facilitate location of material by the reader and aid the man page
350 writer to discuss all essential aspects of the topics presented.
351 .
352 Subsection headings
353 .RB ( SS )
354 are optional and permit sections that grow long to develop in a
355 controlled way.
356 .
357 Many technical discussions benefit from examples;
358 lengthy ones,
359 especially those reflecting multiple lines of input to or output from
360 the system,
361 are usefully bracketed by
362 .B EX
363 and
364 .BR EE .
365 .
366 When none of the foregoing meets a structural demand,
367 use
368 .BR RS / RE
369 to inset a region within a (sub)section.
370 .
371 .
372 .TP
373 .BI .TH " identifier section"\~\c
374 .RI [ footer-middle \~\c
375 .RI [ footer-inside \~\c
376 .RI [ header-middle ]]]
377 Break the page,
378 reset the page number to\~1
379 (unless the
380 .B \-rC1
381 option is given),
382 and use the arguments to populate the page header and footer.
383 .
384 .I roff
385 systems refer to these collectively as \[lq]titles\[rq].
386 .
387 Together,
388 .I identifier
389 and the
390 .I section
391 of the manual to which it belongs
392 can uniquely identify a
393 .I man
394 document on the system.
395 .
396 This use of \[lq]section\[rq] has nothing to do with the section headings
397 otherwise discussed in this page;
398 it arises from the organizational scheme of printed and bound Unix
399 manuals.
400 .
401 See
402 .MR man 1
403 or
404 .MR intro 1
405 for the manual sectioning applicable to your system.
406 .
407 .I identifier
408 and
409 .I section
410 are positioned at the left and right in the header;
411 the latter is set after the former,
412 in parentheses and without space.
413 .
414 .I footer-middle
415 is centered in the footer.
416 .
417 By default,
418 .I footer-inside
419 is positioned at the bottom left.
420 .
421 Use of the double-sided layout option
422 .B \-rD1
423 places
424 .I footer-inside
425 at the bottom left on recto (odd-numbered) pages,
426 and the bottom right on verso (even-numbered) pages.
427 .
428 By default,
429 the outside footer is the page number.
430 .
431 Use of the continuous-rendering option
432 .B \-rcR=1
433 replaces it with
434 .I identifier
435 and
436 .I section,
437 as in the header.
438 .
439 .I header-middle
440 is centered in the header.
441 .
442 If
443 .I section
444 is an integer between 1 and\~9 (inclusive),
445 there is no need to specify
446 .I header-middle;
447 .I an.tmac
448 supplies text for it.
449 .
450 If
451 .I identifier
452 or
453 .I footer-inside
454 would overrun the space available in the header and/or footer,
455 this package may abbreviate them with
456 ellipses
457 .RB ( .\|.\|.\& ).
458 .
459 .I "groff man"
460 suppresses headers and footers in HTML output.
461 .
462 .\" Does anyone try to do anything different? GBR hasn't seen it.
463 .\" This feature is intended only for formatting multiple
464 .\" .I man
465 .\" documents in sequence.
466 .
467 .
468 .IP
469 A valid
470 .I man
471 document calls
472 .B TH
473 only once,
474 early in the file,
475 prior to any other macro calls.
476 .
477 By convention,
478 .I footer-middle
479 is the date of the most recent modification to the source document,
480 in ISO\~8601 format
481 .RI ( YYYY - MM - DD ),
482 and
483 .I footer-inside
484 is the name and version or release of the project providing it.
485 .
486 .
487 .TP
488 .BR .SH " ["\c
489 .IR heading-text ]
490 Set
491 .I heading-text
492 as a section heading.
493 .
494 Given no argument,
495 .B SH
496 plants a one-line input trap;
497 text on the next line
498 .\", which can be formatted with a macro, \" true but discouraged
499 becomes
500 .I heading-text.
501 .
502 The heading text is set in bold
503 (or the font specified by the string
504 .BR HF ),
505 and,
506 on typesetters,
507 slightly larger than the base type size.
508 .
509 If the heading font
510 .B \[rs]*[HF]
511 is bold,
512 use of an italic style in
513 .I heading-text
514 is mapped to the bold-italic style if available in the font family.
515 .
516 The inset level is reset to 1;
517 see subsection \[lq]Horizontal and vertical spacing\[rq] below.
518 .
519 Text lines after the call are set as an ordinary paragraph
520 .RB ( P ).
521 .
522 .
523 .IP
524 The content of
525 .I heading-text
526 and ordering of sections follows a set of common practices,
527 as does much of the layout of material within sections.
528 .
529 For example,
530 a section called \[lq]Name\[rq] or \[lq]NAME\[rq] must exist,
531 must be the first section after the
532 .B TH
533 call,
534 and must contain only text of the form
535 .RS \" Invisibly move left margin to current IP indentation.
536 .RS \" Now indent further, visibly.
537 .IR topic [\c
538 .BI , " another-topic"\c
539 ].\|.\|.\& \e\-
540 .I summary-description
541 .RE \" Move left margin back to IP indentation.
542 for tools like
543 .MR makewhatis 8
544 or
545 .MR mandb 8
546 to index them.
547 .RE \" Move left margin back to standard position.
548 .
549 .
550 .TP
551 .BR .SS " ["\c
552 .IR subheading-text ]
553 Set
554 .I subheading-text
555 as a subsection heading indented between a section heading and an
556 ordinary paragraph
557 .RB ( P ).
558 .
559 Given no argument,
560 .B SS
561 plants a one-line input trap;
562 text on the next line
563 .\", which can be formatted with a macro, \" true but discouraged
564 becomes
565 .I subheading-text.
566 .
567 The subheading text is set in bold
568 (or the font specified by the string
569 .BR HF ).
570 .
571 If the heading font
572 .B \[rs]*[HF]
573 is bold,
574 use of an italic style in
575 .I subheading-text
576 is mapped to the bold-italic style if available in the font family.
577 .
578 The inset level is reset to 1;
579 see subsection \[lq]Horizontal and vertical spacing\[rq] below.
580 .
581 Text lines after the call are set as an ordinary paragraph
582 .RB ( P ).
583 .
584 .
585 .TP
586 .B .EX
587 .TQ
588 .B .EE
589 Begin and end example.
590 .
591 After
592 .BR EX ,
593 filling is disabled
594 (and,
595 on typesetters,
596 a monospaced font family is selected).
597 .
598 Calling
599 .B EE
600 enables filling
601 (and restores the previous family).
602 .
603 .
604 .IP
605 Example regions are useful for formatting code,
606 shell sessions,
607 and text file contents.
608 .
609 An example region is not
610 a \[lq]literal mode\[rq]
611 of any sort:
612 special character escape sequences must still be used to produce correct
613 glyphs for
614 .BR \[aq] ,
615 .BR \- ,
616 .BR \[rs] ,
617 .BR \[ha] ,
618 .BR \[ga] ,
619 and
620 .B \[ti]
621 (see subsection \[lq]Portability\[rq] below).
622 .
623 Sentence endings are still detected
624 and supplemental inter-sentence space applied.
625 .
626 If the amount of supplemental inter-sentence spacing is altered,
627 the rendering of,
628 for instance,
629 regular expressions using
630 .B .\&
631 or
632 .B ?\&
633 followed by multiple spaces can change.
634 .
635 Use the dummy character escape sequence
636 .B \[rs]&
637 before the spaces.
638 .
639 .
640 .IP
641 Ninth Edition Unix introduced the
642 .\" Also see subsection "History" below...
643 .B EX
644 and
645 .B EE
646 extensions.
647 .
648 Documenter's Workbench (DWB),
649 Heirloom Doctools,
650 and
651 Plan\~9
652 .IR troff s, \" DWB, Heirloom, Plan 9
653 and
654 .I mandoc
655 (since 1.12.2)
656 support them.
657 .
658 Solaris
659 .I troff \" Solaris
660 does not.
661 .\" Neatroff doesn't ship (m)an macros.
662 .
663 .
664 .TP
665 .BR .RS " ["\c
666 .IR inset-amount ]
667 Start new relative inset.
668 .
669 .I man
670 saves any current inset amount
671 and moves right by:
672 .I inset-amount,
673 if specified;
674 the
675 .I indentation
676 amount of the preceding
677 .BR IP ,
678 .BR TP ,
679 or
680 .B HP
681 macro call if no (sub-)sectioning or ordinary paragraphing macro has
682 intervened;
683 or the amount of the
684 .B IN
685 register.
686 .
687 .B RS
688 calls can nest;
689 each increments by\~1 the
690 .I level
691 used by
692 .BR RE .
693 .
694 The level prior to any
695 .B RS
696 call is\~1.
697 .
698 .
699 .TP
700 .BR .RE " ["\c
701 .IR inset-level ]
702 End a relative inset,
703 reducing it to that of
704 .I inset-level
705 (or by\~1 if not specified)
706 and restoring the corresponding inset amount.
707 .
708 .
709 .\" ====================================================================
710 .SS "Paragraphing macros"
711 .\" ====================================================================
712 .
713 These macros break the output line.
714 .
715 An
716 .I ordinary
717 paragraph
718 .RB ( P )
719 like this one
720 indents all output lines by the same amount.
721 .
722 A hanging paragraph
723 .RB ( HP )
724 is a cosmetic variant of
725 .B P
726 with a hanging indent.
727 .
728 Definition lists frequently occur in man pages;
729 these can be set as
730 .I "tagged paragraphs,"
731 which have one
732 .RB ( TP )
733 or more
734 .RB ( TQ )
735 leading tags followed by a paragraph that has an additional indentation.
736 .
737 The indented paragraph
738 .RB ( IP )
739 macro
740 can continue the indented content of a narrative started
741 with
742 .BR TP ,
743 or present an itemized or ordered list.
744 .
745 If a paragraphing macro has been called since
746 .B SH
747 or
748 .BR SS ,
749 all except
750 .B TQ
751 follow the break with vertical space
752 (in an amount configured by the deprecated
753 .B PD
754 macro);
755 see subsection \[lq]Horizontal and vertical spacing\[rq] below.
756 .
757 Except for
758 .BR TQ ,
759 these macros
760 reset the type size,
761 hyphenation,
762 and adjustment to (configured) defaults,
763 and the font style to roman.
764 .\" slack wording for managing stranded lines in PS/PDF output
765 .\" [end previous text line with semicolon, not period]
766 .\"see subsections \[lq]Font style macros\[rq] and \[lq]Options\[rq]
767 .\"below.
768 .
769 .
770 .br
771 .ne 4v
772 .TP
773 .B .P
774 .TQ
775 .B .LP
776 .TQ
777 .B .PP
778 Begin a new paragraph;
779 these macros are synonymous.
780 .
781 Any indentation from use of
782 .BR IP ,
783 .BR TP ,
784 or
785 .B HP
786 is cleared.
787 .
788 The inset amount,
789 as affected by
790 .B RS
791 and
792 .BR RE ,
793 is not.
794 .
795 .
796 .TP
797 .BR .HP " ["\c
798 .IR indentation ]
799 Set a paragraph with a hanging indentation.
800 .
801 Text on output lines after the first is indented by
802 .I indentation,
803 if specified,
804 and by the amount of the
805 .B IN
806 register otherwise.
807 .
808 .
809 .IP
810 .I Caution:
811 A hanging indentation cannot be expressed naturally in (pure) HTML,
812 a hanging paragraph is not distinguishable from an ordinary one if it
813 formats on only one output line,
814 and
815 .RI non- roff -based
816 man page interpreters may treat
817 .B HP
818 as an ordinary paragraph anyway.
819 .
820 Thus,
821 information or distinctions you mean to express with indentation may be
822 lost.
823 .
824 .
825 .TP
826 .BR .TP " ["\c
827 .IR indentation ]
828 Set an indented paragraph with a leading unindented tag.
829 .
830 The macro plants a one-line input trap that honors the
831 .B \[rs]c
832 escape sequence;
833 text on the next line becomes the tag,
834 set without indentation.
835 .
836 Text on subsequent lines is indented by
837 .I indentation,
838 if specified,
839 and by the amount of the
840 .B IN
841 register otherwise.
842 .
843 If the tag,
844 plus the \[lq]tag spacing\[rq] stored in the
845 .B TS
846 register
847 (see section \[lq]Options\[rq] below)
848 is wider than the indentation,
849 the package breaks the line after the tag.
850 .
851 .
852 .IP
853 The line containing the tag can include a macro call,
854 for instance to set the tag in bold with
855 .BR B .
856 .
857 .B TP
858 was used to write the first paragraph of this description of
859 .BR TP ,
860 and
861 .B IP
862 the subsequent one.
863 .
864 .
865 .TP
866 .B .TQ
867 Set an additional tag for a paragraph tagged with
868 .BR TP ,
869 planting a one-line input trap as with
870 .BR TP .
871 .
872 .
873 .IP
874 .B TQ
875 is a GNU extension supported by
876 Heirloom Doctools
877 .I troff \" Heirloom
878 .\" commit 5e4181af2a1562c542caaa3b2cc129e40e3e76e5
879 (since Git snapshot 151218)
880 and
881 .I mandoc
882 (since 1.14.5)
883 but not by
884 DWB,
885 Plan\~9,
886 or
887 Solaris
888 .IR troff s. \" DWB, Plan 9, Solaris
889 .
890 .
891 .IP
892 The description of
893 .BR P ,
894 .BR LP ,
895 and
896 .B PP
897 above was written using
898 .B TP
899 and
900 .BR TQ .
901 .
902 .
903 .TP
904 .BR .IP\~ [\c
905 .IR mark \~\c
906 .RI [ indentation ]]
907 Set an indented paragraph with an optional mark.
908 .
909 Arguments,
910 if present,
911 are handled as with
912 .BR TP ,
913 except that the
914 .I mark
915 argument to
916 .B IP
917 cannot include a macro call,
918 and the tag separation amount stored in the
919 .B TS
920 register is not enforced.
921 .
922 .
923 .IP
924 Two convenient uses for
925 .B IP
926 are
927 .
928 .
929 .RS \" Invisibly move left margin to current IP indentation.
930 .RS 4n \" Now indent further, visibly.
931 .IP (1) 5n \" "(1)" + 3n
932 to start a new paragraph with the same indentation as an immediately
933 preceding
934 .B IP
935 or
936 .B TP
937 paragraph,
938 if no
939 .I indentation
940 argument is given;
941 and
942 .
943 .
944 .IP (2)
945 to set a paragraph with a short
946 .I mark
947 that is not semantically important,
948 such as a bullet (\[bu])\[em]obtained with the
949 .B \e[bu]
950 special character escape sequence\[em]or list enumerator,
951 as seen in this very paragraph.
952 .RE \" Move left margin back to IP indentation.
953 .RE \" Move left margin back to standard position.
954 .
955 .
956 .\" ====================================================================
957 .SS "Synopsis macros"
958 .\" ====================================================================
959 .
960 Use
961 .B SY
962 and
963 .B YS
964 to summarize syntax using familiar Unix conventions.
965 .
966 .\" TODO: Determine whether this (is still? was ever?) true.
967 .\" Furthermore,
968 .\" some tools are able to interpret these macros semantically and treat
969 .\" them appropriately for localization and/or presentation.
970 .
971 Heirloom Doctools
972 .I troff \" Heirloom
973 .\" commit 5e4181af2a1562c542caaa3b2cc129e40e3e76e5
974 (since Git snapshot 151218)
975 and
976 .I mandoc
977 (since 1.14.5)
978 support these GNU extensions;
979 DWB,
980 Plan\~9,
981 and
982 Solaris
983 .IR troff s \" DWB, Plan 9, Solaris
984 do not.
985 .
986 .
987 .TP
988 .BI .SY\~ keyword\~\c
989 .RI [ suffix ]
990 Begin synopsis.
991 .
992 Adjustment and automatic hyphenation are disabled.
993 .
994 If
995 .B SY
996 has already been called without a corresponding
997 .BR YS ,
998 a break is performed.
999 .
1000 .I keyword
1001 and any
1002 .I suffix
1003 are set in bold.
1004 .
1005 When
1006 .I suffix
1007 is present,
1008 the package
1009 sets the next word after it without intervening space.
1010 .
1011 If a break is required in subsequent text
1012 (up to a paragraphing,
1013 sectioning,
1014 or
1015 .B YS
1016 macro call),
1017 lines after the first are indented.
1018 .
1019 Unless the previous synopsis's indentation is reused
1020 (see
1021 .B YS
1022 below),
1023 output lines after the first
1024 indent by the width of the pending output line up to the end of
1025 .I keyword
1026 plus a space,
1027 if
1028 .I keyword
1029 is the only argument,
1030 and up to the end of
1031 .I suffix
1032 otherwise.
1033 .
1034 .
1035 .br
1036 .ne 4v
1037 .TP
1038 .BR .YS\~ [\c
1039 .IR reuse-indentation ]
1040 End synopsis,
1041 breaking the line and restoring
1042 indentation,
1043 adjustment,
1044 and hyphenation
1045 to their previous states.
1046 .
1047 If an argument is given,
1048 the indentation corresponding to the previous
1049 .B SY
1050 call is reused by the next
1051 .B SY
1052 call instead of being computed.
1053 .
1054 .
1055 .P
1056 Interleave multiple
1057 .BR SY / YS
1058 blocks with paragraphing macros to distinguish differing modes of
1059 operation of a complex command like
1060 .MR tar 1 .
1061 .
1062 Omit the paragraphing macro to indicate synonymous ways of invoking a
1063 particular mode of operation.
1064 .
1065 Paragraphing macros can similarly manage grouping of function synopses.
1066 .
1067 .
1068 .br
1069 .ne 4v
1070 .P
1071 .IR groff 's
1072 own command-line interface illustrates most specimens
1073 of synopsis syntax one may encounter.
1074 .
1075 .
1076 .IP
1077 .\" from src/roff/groff/groff.1.man
1078 .EX
1079 \&.SY groff
1080 \&.RB [ \e\-abcCeEgGijklNpRsStUVXzZ ]
1081 \&.RB [ \e\-d\e\[ti]\ec
1082 \&.IR ctext ]
1083 \&.RB [ \e\-d\e\[ti]\ec
1084 \&.IB string =\ec
1085 \&.IR text ]
1086 \&.RB [ \e\-D\e\[ti]\ec
1087 \&.IR fallback\-encoding ]
1088 .EE
1089 .
1090 .I "(and so on similarly)"
1091 .
1092 .EX
1093 \&.RI [ file\e\[ti] .\e|.\e|.]
1094 \&.YS
1095 \&.
1096 \&.
1097 \&.P
1098 \&.SY groff
1099 \&.B \e\-h
1100 \&.YS
1101 \&.
1102 \&.SY groff
1103 \&.B \e\-\e\-help
1104 \&.YS
1105 \&.
1106 \&.
1107 \&.P
1108 \&.SY groff
1109 \&.B \e\-v
1110 \&.RI [ option\e\[ti] .\e|.\e|.\e&]
1111 \&.RI [ file\e\[ti] .\e|.\e|.]
1112 \&.YS
1113 \&.
1114 \&.SY groff
1115 \&.B \e\-\e\-version
1116 \&.RI [ option\e\[ti] .\e|.\e|.\e&]
1117 \&.RI [ file\e\[ti] .\e|.\e|.]
1118 \&.YS
1119 .EE
1120 .
1121 .
1122 .P
1123 Given the foregoing input,
1124 .I "groff man"
1125 produces the following output.
1126 .
1127 .
1128 .P
1129 .RS
1130 .SY groff
1131 .RB [ \-abcCeEgGijklNpRsStUVXzZ ]
1132 .RB [ \-d\~\c
1133 .IR ctext ]
1134 .RB [ \-d\~\c
1135 .IB string =\c
1136 .IR text ]
1137 .RB [ \-D\~\c
1138 .IR fallback-encoding ]
1139 .RB [ \-f\~\c
1140 .IR font-family ]
1141 .RB [ \-F\~\c
1142 .IR font-directory ]
1143 .RB [ \-I\~\c
1144 .IR inclusion-directory ]
1145 .RB [ \-K\~\c
1146 .IR input-encoding ]
1147 .RB [ \-L\~\c
1148 .IR spooler-argument ]
1149 .RB [ \-m\~\c
1150 .IR macro-package ]
1151 .RB [ \-M\~\c
1152 .IR macro-directory ]
1153 .RB [ \-n\~\c
1154 .IR page-number ]
1155 .RB [ \-o\~\c
1156 .IR page-list ]
1157 .RB [ \-P\~\c
1158 .IR postprocessor-argument ]
1159 .RB [ \-r\~\c
1160 .IR cnumeric-expression ]
1161 .RB [ \-r\~\c
1162 .IB register =\c
1163 .IR numeric-expression ]
1164 .RB [ \-T\~\c
1165 .IR output-device ]
1166 .RB [ \-w\~\c
1167 .IR warning-category ]
1168 .RB [ \-W\~\c
1169 .IR warning-category ]
1170 .RI [ file\~ .\|.\|.]
1171 .YS
1172 .
1173 .
1174 .br
1175 .ne 2v
1176 .P
1177 .SY groff
1178 .B \-h
1179 .YS
1180 .
1181 .SY groff
1182 .B \-\-help
1183 .YS
1184 .
1185 .
1186 .P
1187 .SY groff
1188 .B \-v
1189 .RI [ option\~ .\|.\|.\&]
1190 .RI [ file\~ .\|.\|.]
1191 .YS
1192 .
1193 .SY groff
1194 .B \%\-\-version
1195 .RI [ option\~ .\|.\|.\&]
1196 .RI [ file\~ .\|.\|.]
1197 .YS
1198 .RE
1199 .
1200 .
1201 .P
1202 Several features of the above example are of note.
1203 .
1204 .
1205 .IP \[bu] 3n
1206 The empty request (.),
1207 which does nothing,
1208 vertically spaces the input file for readability by the document
1209 maintainer;
1210 see subsection \[lq]Portability\[rq] below regarding blank lines.
1211 .
1212 .
1213 .IP \[bu]
1214 Command and option names are presented in
1215 .B bold
1216 to cue the user that they should be input literally.
1217 .
1218 .
1219 .IP \[bu]
1220 Option dashes are specified with the
1221 .B \e\-
1222 escape sequence;
1223 this is an important practice to make them clearly visible and to
1224 facilitate copy-and-paste from the rendered man page to a shell prompt
1225 or text file.
1226 .
1227 .
1228 .IP \[bu]
1229 Option arguments and command operands are presented in
1230 .I italics
1231 (but see subsection \[lq]Font style macros\[rq] below regarding terminals)
1232 to cue the user that they must be replaced with appropriate input.
1233 .
1234 .
1235 .IP \[bu]
1236 Symbols that are neither to be typed literally nor replaced at the
1237 user's discretion appear in the roman style;
1238 brackets surround optional arguments,
1239 and an ellipsis indicates that the previous syntactic element may be
1240 repeated arbitrarily.
1241 .
1242 Where whitespace separates optional arguments,
1243 a space precedes the ellipsis.
1244 .
1245 .
1246 .IP \[bu]
1247 The non-breaking adjustable space escape sequence
1248 .B \e\[ti]
1249 prevents the output line from breaking within the option brackets;
1250 see subsection \[lq]Portability\[rq] below.
1251 .
1252 .
1253 .IP \[bu]
1254 The output line continuation escape sequence
1255 .B \ec
1256 is used with font style alternation macros to allow all three font
1257 styles to be set without (breakable) space among them;
1258 see subsection \[lq]Portability\[rq] below.
1259 .
1260 .
1261 .IP \[bu]
1262 The dummy character escape sequence
1263 .B \e&
1264 follows the ellipsis when further text is to follow after space on the
1265 output line,
1266 keeping its last period from being interpreted as the end of a
1267 sentence
1268 because it is followed by characters that are transparent to
1269 end-of-sentence detection,
1270 and/or a newline,
1271 which would in turn normally cause the formatter
1272 to place supplemental inter-sentence space after it.
1273 .
1274 See subsection \[lq]Portability\[rq] below.
1275 .
1276 .
1277 .P
1278 We might synopsize the standard C library function
1279 .MR bsearch 3
1280 as follows.
1281 .
1282 .
1283 .P
1284 .RS
1285 .EX
1286 \&.P
1287 \&.B void *\[rs]c
1288 \&.SY bsearch (
1289 \&.BI const\[rs]\[ti]void\[rs]\[ti]* key ,
1290 \&.BI const\[rs]\[ti]void\[rs]\[ti]* base ,
1291 \&.BI size_t\[rs]\[ti] nmemb ,
1292 \&.BI int\[rs]\[ti](* compar )\[rs]c
1293 \&.B (const\[rs]\[ti]void\[rs]\[ti]*, const\[rs]\[ti]void\[rs]\[ti]*));
1294 \&.YS
1295 .EE
1296 .RE
1297 .
1298 .
1299 .P
1300 .I "groff man"
1301 produces the following result.
1302 .
1303 .
1304 .RS
1305 .P
1306 .B void *\c
1307 .SY bsearch (
1308 .BI const\~void\~* key ,
1309 .BI const\~void\~* base ,
1310 .BI size_t\~ nmemb ,
1311 .BI int\~(* compar )\c
1312 .B (const\~void\~*, const\~void\~*));
1313 .YS
1314 .RE
1315 .
1316 .
1317 .\" ====================================================================
1318 .SS "Hyperlink macros"
1319 .\" ====================================================================
1320 .
1321 Man page cross references
1322 like
1323 .MR ls 1
1324 are best presented with
1325 .BR MR .
1326 .
1327 Mark email addresses with
1328 .BR MT / ME
1329 and other sorts of URI with
1330 .BR UR / UE .
1331 .
1332 To hyperlink text,
1333 terminals and pager programs must support ECMA-48 OSC\~8 escape
1334 sequences
1335 (see
1336 .MR grotty 1 ).
1337 .
1338 When device support is unavailable or disabled with the
1339 .B U
1340 register
1341 (see section \[lq]Options\[rq] below),
1342 .I "groff man"
1343 renders these URIs between angle brackets
1344 .RB ( \[la]\~\[ra] )
1345 after the linked text.
1346 .
1347 .
1348 .P
1349 .BR MT ,
1350 .BR ME ,
1351 .BR UR ,
1352 and
1353 .B UE
1354 are GNU extensions supported by
1355 Heirloom Doctools
1356 .I troff \" Heirloom
1357 .\" commit 5e4181af2a1562c542caaa3b2cc129e40e3e76e5
1358 (since Git snapshot 151218)
1359 and
1360 .I mandoc
1361 .RB ( UR / UE
1362 since 1.12.3;
1363 .BR MT / ME
1364 since 1.14.2)
1365 but not by
1366 DWB,
1367 Plan\~9 (original),
1368 or
1369 Solaris
1370 .IR troff s. \" DWB, Plan 9, Solaris
1371 .
1372 Plan\~9 from User Space's
1373 .I troff \" plan9port
1374 implements
1375 .BR MR .
1376 .
1377 .
1378 .br
1379 .ne 2v
1380 .P
1381 Prepare arguments to
1382 .BR MR ,
1383 .BR MT ,
1384 and
1385 .B UR
1386 for typesetting;
1387 they can appear in the output.
1388 .
1389 Use special character escape sequences to encode Unicode basic Latin
1390 characters where necessary,
1391 particularly the hyphen-minus.
1392 .
1393 (See subsection \[lq]Portability\[rq] below.)
1394 .
1395 URIs can be lengthy;
1396 rendering them can result in jarring adjustment or variations in line
1397 length,
1398 or
1399 .I \%troff
1400 warnings when one is longer than an output line.
1401 .
1402 The application of non-printing break point escape sequences
1403 .B \e:
1404 after each slash
1405 (or series thereof),
1406 and before each dot
1407 (or series thereof)
1408 is recommended as a rule of thumb.
1409 .
1410 The former practice avoids forcing a trailing slash in a URI onto a
1411 separate output line,
1412 and the latter helps the reader to avoid mistakenly interpreting a dot
1413 at the end of a line as a period
1414 (or multiple dots as an ellipsis).
1415 .
1416 Thus,
1417 .RS
1418 .EX
1419 \&.UR http://\e:example\e:.com/\e:fb8afcfbaebc74e\e:.cc
1420 .EE
1421 .RE
1422 has several potential break points in the URI shown.
1423 .
1424 Consider adding break points before or after at signs in email
1425 addresses,
1426 and question marks,
1427 ampersands,
1428 and number signs in HTTP(S) URIs.
1429 .
1430 .\" XXX: We don't need to say this, do we? It shouldn't be the man(7)
1431 .\" user's problem.
1432 .\" The formatter removes
1433 .\" .B \e:
1434 .\" escape sequences from hyperlinks when supplying
1435 .\" device extension command arguments to output drivers.
1436 .
1437 .
1438 .TP
1439 .BI .MR \~topic\c
1440 .RI \~[ manual-section \~[ trailing-text ]]
1441 .IR (since\~ groff \~1.23) \" TODO: remove note once novelty dies down
1442 Set a man page cross reference as
1443 \[lq]\c
1444 .IB topic ( manual-section )\c
1445 \[rq].
1446 .
1447 If
1448 .I manual-section
1449 is absent,
1450 the package omits the surrounding parentheses.
1451 .
1452 If
1453 .I trailing-text
1454 (typically punctuation)
1455 is specified,
1456 it follows the closing parenthesis without intervening space.
1457 .
1458 Hyphenation is disabled while the cross reference is set.
1459 .
1460 .I topic
1461 is set in the font specified by the
1462 .B MF
1463 string.
1464 .
1465 If
1466 .I manual-section
1467 is present,
1468 the cross reference hyperlinks to a URI of the form
1469 .RB \[lq] man:\c
1470 .IR topic ( manual-section )\[rq].
1471 .
1472 .
1473 .RS
1474 .IP
1475 .EX
1476 The output driver
1477 \&.MR grops 1
1478 produces PostScript from
1479 \&.I troff
1480 output.
1481 \&.
1482 The Ghostscript program (\[rs]c
1483 \&.MR gs 1 )
1484 interprets PostScript and PDF.
1485 .EE
1486 .RE
1487 .
1488 .
1489 .TP
1490 .BI .MT " address"
1491 .TQ
1492 .BR .ME " ["\c
1493 .IR trailing-text ]
1494 Identify
1495 .I address
1496 as an RFC 6068
1497 .I addr-spec
1498 for a \[lq]mailto:\[rq] URI with the text between the two macro
1499 calls as the link text.
1500 .
1501 An argument to
1502 .B ME
1503 is placed after the link text without intervening space.
1504 .
1505 .I address
1506 may not be visible in the rendered document if hyperlinks are enabled
1507 and supported by the output driver.
1508 .
1509 If they are not,
1510 .I address
1511 is set in angle brackets after the link text and before
1512 .I trailing-text.
1513 .
1514 If hyperlinking is enabled but there is no link text,
1515 .I address
1516 is formatted and hyperlinked
1517 .I without
1518 angle brackets,
1519 except when
1520 .I address
1521 appears as a
1522 .B TP
1523 paragraph tag.
1524 .
1525 .
1526 .IP
1527 When rendered by
1528 .I groff
1529 to a PostScript device,
1530 .RS
1531 .IP
1532 .EX
1533 Contact
1534 \&.MT fred\e:.foonly@\e:fubar\e:.net
1535 Fred Foonly
1536 \&.ME
1537 for more information.
1538 .EE
1539 .RE
1540 .
1541 .
1542 .IP
1543 formats as
1544 \[lq]Contact Fred Foonly \[la]fred\:.foonly@\:fubar\:.net\[ra]
1545 for more information.\[rq].
1546 .
1547 .
1548 .TP
1549 .BI .UR " uri"
1550 .TQ
1551 .BR .UE " ["\c
1552 .IR trailing-text ]
1553 Identify
1554 .I uri
1555 as an RFC 3986 URI hyperlink with the text between the two macro calls
1556 as the link text.
1557 .
1558 An argument to
1559 .B UE
1560 is placed after the link text without intervening space.
1561 .
1562 .I uri
1563 may not be visible in the rendered document if hyperlinks are enabled
1564 and supported by the output driver.
1565 .
1566 If they are not,
1567 .I uri
1568 is set in angle brackets after the link text and before
1569 .I trailing-text.
1570 .
1571 If hyperlinking is enabled but there is no link text,
1572 .I uri
1573 is formatted and hyperlinked
1574 .I without
1575 angle brackets,
1576 except when
1577 .I uri
1578 appears as a
1579 .B TP
1580 paragraph tag.
1581 .
1582 .
1583 .br
1584 .ne 2v
1585 .IP
1586 When rendered by
1587 .I groff
1588 to a PostScript device,
1589 .RS
1590 .IP
1591 .EX
1592 The GNU Project of the Free Software Foundation
1593 hosts the
1594 \&.UR https://\e:www\e:.gnu\e:.org/\e:software/\e:groff/
1595 \&.I groff
1596 home page
1597 \&.UE .
1598 .EE
1599 .RE
1600 .
1601 .
1602 .IP
1603 formats as \[lq]The GNU Project of the Free Software Foundation hosts
1604 the
1605 .I groff
1606 home page
1607 \[la]https://\:www\:.gnu\:.org/\:software/\:groff/\[ra].\[rq].
1608 .
1609 .
1610 .P
1611 If a
1612 .BR UR / UE
1613 or
1614 .BR MT / ME
1615 pair occurs in a
1616 .B TP
1617 tag
1618 and hyperlinking is unavailable,
1619 .I "groff man"
1620 sets the link target at the beginning
1621 of the indented paragraph,
1622 not as part of the tag,
1623 unless there is no link text.
1624 .
1625 .
1626 .\" ====================================================================
1627 .SS "Font style macros"
1628 .\" ====================================================================
1629 .
1630 The
1631 .I man
1632 macro package is limited in its font styling options,
1633 offering only
1634 .BR bold \~( B ),
1635 .I italic\c
1636 .RB \~( I ),
1637 and roman.
1638 .
1639 Italic text may instead render underscored on terminals.
1640 .
1641 .B SM
1642 sets text at a smaller type size,
1643 which differs visually from regular-sized text only on typesetters.
1644 .
1645 The macros
1646 .BR BI ,
1647 .BR BR ,
1648 .BR IB ,
1649 .BR IR ,
1650 .BR RB ,
1651 and
1652 .B RI
1653 set their odd- and even-numbered arguments
1654 as text in the alternating styles their names indicate,
1655 with no space separating them.
1656 .
1657 .
1658 .P
1659 Because font styles are presentational rather than semantic,
1660 conflicting traditions have arisen regarding which font styles should be
1661 used to mark file or path names,
1662 environment variables,
1663 and inlined literals.
1664 .
1665 .
1666 .P
1667 The default type size and family for typesetters is 10-point Times,
1668 except on the
1669 .B \%X75\-12
1670 and
1671 .B \%X100\-12
1672 devices where the type size is 12 points.
1673 .
1674 The default style is roman.
1675 .
1676 .
1677 .TP
1678 .BR .B \~[\c
1679 .IR text ]
1680 Set
1681 .I text
1682 in bold.
1683 .
1684 Given no argument,
1685 .B B
1686 plants a one-line input trap;
1687 text on the next line,
1688 which can be further formatted with a macro,
1689 is set in bold.
1690 .
1691 .
1692 .IP
1693 Use bold
1694 for literal portions of syntax synopses,
1695 for command-line options in running text,
1696 and for literals that are major topics of the subject under discussion;
1697 for example,
1698 this page uses bold for macro,
1699 string,
1700 and register names.
1701 .
1702 In an
1703 .BR EX / EE
1704 example of interactive I/O
1705 (such as a shell session),
1706 set only user input in bold.
1707 .
1708 .
1709 .
1710 .TP
1711 .BR .I \~[\c
1712 .IR text ]
1713 Set
1714 .I text
1715 in an italic or oblique face.
1716 .
1717 Given no argument,
1718 .B I
1719 plants a one-line input trap;
1720 text on the next line,
1721 which can be further formatted with a macro,
1722 is set in an italic or oblique face.
1723 .
1724 .
1725 .IP
1726 Use italics
1727 for file and path names,
1728 for environment variables,
1729 for C data types,
1730 for enumeration or preprocessor constants in C,
1731 for variant (user-replaceable) portions of syntax synopses,
1732 for the first occurrence (only) of a technical concept being introduced,
1733 for names of journals and of literary works longer than an article,
1734 and anywhere a parameter requiring replacement by the user is
1735 encountered.
1736 .
1737 An exception involves variant text in a context already typeset in
1738 italics,
1739 such as file or path names with replaceable components;
1740 in such cases,
1741 follow the convention of mathematical typography:
1742 set the file or path name in italics as usual
1743 but use roman for the variant part
1744 (see
1745 .B IR
1746 and
1747 .B RI
1748 below),
1749 and italics again in running roman text when referring to the variant
1750 material.
1751 .
1752 .
1753 .TP
1754 .BR .SM \~[\c
1755 .IR text ]
1756 Set
1757 .I text
1758 one point smaller than the default type size on typesetters.
1759 .
1760 Given no argument,
1761 .B SM
1762 plants a one-line input trap;
1763 text on the next line,
1764 which can be further formatted with a macro,
1765 is set smaller.
1766 .
1767 .
1768 .IP
1769 .I Note:
1770 terminals render
1771 .I text
1772 at normal size instead.
1773 .
1774 Do not rely upon
1775 .B SM
1776 to communicate semantic information distinct from using roman style at
1777 normal size;
1778 it is hidden from readers using such devices.
1779 .
1780 .
1781 .P
1782 Observe what is
1783 .I not
1784 prescribed for setting in bold or italics above:
1785 elements of \[lq]synopsis language\[rq] such as ellipses and brackets
1786 around options;
1787 proper names and adjectives;
1788 titles of anything other than major works of literature;
1789 identifiers for standards documents or technical reports such as
1790 CSTR\~#54,
1791 RFC\~1918,
1792 Unicode\~16,
1793 or
1794 POSIX.1-2024;
1795 acronyms;
1796 and occurrences after the first of a technical term.
1797 .
1798 .
1799 .P
1800 Use italics for emphasis rarely,
1801 and bold almost never.
1802 .
1803 Brief specimens of literal text,
1804 such as article titles,
1805 inline examples,
1806 mentions of individual characters or short strings,
1807 and (sub)section headings in man pages,
1808 are suitable for quotation;
1809 see the
1810 .BR \e[lq] ,
1811 .BR \e[rq] ,
1812 .BR \e[oq] ,
1813 and
1814 .B \e[cq]
1815 escape sequences in subsection \[lq]Portability\[rq] below.
1816 .
1817 .
1818 .br
1819 .ne 2v
1820 .P
1821 Unlike the above font style macros,
1822 the font style alternation macros below set no input traps;
1823 they must be given arguments to have effect.
1824 .
1825 They apply italic corrections as appropriate.
1826 .
1827 If a space is required within an argument,
1828 first consider whether the same result could be achieved with as much
1829 clarity by using single-style macros on separate input lines.
1830 .
1831 When it cannot,
1832 double-quote an argument containing embedded space characters.
1833 .
1834 Setting all three different styles within a word
1835 presents challenges;
1836 it is possible with the
1837 .B \ec
1838 and/or
1839 .B \ef
1840 escape sequences.
1841 .
1842 See subsection \[lq]Portability\[rq]
1843 below for approaches.
1844 .
1845 .
1846 .TP
1847 .BI .BI " bold-text italic-text "\c
1848 \&.\|.\|.\&
1849 Set each argument in bold and italics,
1850 alternately.
1851 .
1852 .
1853 .RS
1854 .IP
1855 .\" from src/roff/troff/troff.1.man
1856 .EX
1857 \&.BI \-r\e\[ti] register = numeric-expression
1858 .EE
1859 .RE
1860 .
1861 .
1862 .TP
1863 .BI .BR " bold-text roman-text "\c
1864 \&.\|.\|.\&
1865 Set each argument in bold and roman,
1866 alternately.
1867 .
1868 .
1869 .RS
1870 .IP
1871 .\" from src/preproc/eqn/eqn.1.man
1872 .EX
1873 Set an ellipsis on the math axis with the GNU extension macro
1874 \&.BR cdots .
1875 .EE
1876 .RE
1877 .
1878 .
1879 .TP
1880 .BI .IB " italic-text bold-text "\c
1881 \&.\|.\|.\&
1882 Set each argument in italics and bold,
1883 alternately.
1884 .
1885 .
1886 .RS
1887 .IP
1888 .\" from src/preproc/pic/pic.1.man
1889 .EX
1890 In places where
1891 \&.IB n th
1892 is allowed,
1893 .EE
1894 .RE
1895 .
1896 .
1897 .TP
1898 .BI .IR " italic-text roman-text "\c
1899 \&.\|.\|.\&
1900 Set each argument in italics and roman,
1901 alternately.
1902 .
1903 .
1904 .RS
1905 .IP
1906 .\" from src/preproc/pic/pic.1.man
1907 .EX
1908 Use GNU
1909 \&.IR pic \[aq]s
1910 \&.B figname
1911 command to change the name of the vbox.
1912 .EE
1913 .RE
1914 .
1915 .
1916 .TP
1917 .BI .RB " roman-text bold-text "\c
1918 \&.\|.\|.\&
1919 Set each argument in roman and bold,
1920 alternately.
1921 .
1922 .
1923 .RS
1924 .IP
1925 .\" from src/roff/groff/groff.1.man
1926 .EX
1927 \&.I file
1928 is
1929 \&.RB \[rs][lq] \[rs]\- \[rs][rq],
1930 \&.I groff
1931 reads the standard input stream.
1932 .RE
1933 .EE
1934 .
1935 .
1936 .TP
1937 .BI .RI " roman-text italic-text "\c
1938 \&.\|.\|.\&
1939 Set each argument in roman and italics,
1940 alternately.
1941 .
1942 .
1943 .RS
1944 .IP
1945 .\" from src/preproc/pic/pic.1.man
1946 .EX
1947 \&.RI ( tpic
1948 was a fork of AT&T
1949 \&.I pic \" AT&T
1950 by Tim Morgan of the University of California at Irvine
1951 .EE
1952 .RE
1953 .
1954 .
1955 .\" ====================================================================
1956 .SS "Horizontal and vertical spacing"
1957 .\" ====================================================================
1958 .
1959 The package sets all text inboard of the left edge of the output medium
1960 by the amount of the
1961 .I "page offset;"
1962 see register
1963 .B PO
1964 in section \[lq]Options\[rq] below.
1965 .
1966 Headers,
1967 footers
1968 (both set with
1969 .BR TH ),
1970 and section headings
1971 .RB ( SH )
1972 lie at the page offset.
1973 .
1974 .I groff
1975 .I man
1976 indents
1977 subsection headings
1978 .RB ( SS )
1979 by the amount in the
1980 .B SN
1981 register.
1982 .
1983 .
1984 .P
1985 Ordinary paragraphs not within an
1986 .BR RS / RE
1987 inset region are inset by the amount stored in the
1988 .B BP
1989 register;
1990 see section \[lq]Options\[rq] below.
1991 .
1992 The
1993 .B IN
1994 register configures the default indentation amount used by
1995 .B RS
1996 (as the
1997 .IR inset-amount ),
1998 .BR IP ,
1999 .BR TP ,
2000 and
2001 .BR HP ;
2002 an overriding argument
2003 is a number plus an optional scaling unit.
2004 .
2005 If no scaling unit is given,
2006 the
2007 .I man
2008 package assumes \[lq]n\[rq];
2009 that is,
2010 roughly the width of a letter \[lq]n\[rq] in the font current when the
2011 macro is called\[em]see section \[lq]Measurements\[rq] in
2012 .MR groff 7 .
2013 .
2014 An indentation specified in a call to
2015 .BR IP ,
2016 .BR TP ,
2017 or
2018 .B HP
2019 persists until
2020 (1) another of these macros is called with an
2021 .I indentation
2022 argument,
2023 or
2024 (2)
2025 .BR SH ,
2026 .BR SS ,
2027 or
2028 .B P
2029 or its synonyms is called;
2030 these clear the indentation entirely.
2031 .\" XXX: This is not true, but they do handle it badly.
2032 .\"
2033 .\" HTML output devices ignore indentation.
2034 .
2035 .
2036 .P
2037 The inset amount and indentation are related but distinct parameters
2038 with the same defaults.
2039 .
2040 The former is manipulated by
2041 .B RS
2042 and
2043 .B RE
2044 (and by
2045 .\".BR TH ,\" True but not to be encouraged within a document.
2046 .B SH
2047 and
2048 .BR SS ,
2049 which reset it to the default).
2050 .
2051 Indentation is controlled by the paragraphing macros
2052 (though,
2053 again,
2054 .\".BR TH ,
2055 .B SH
2056 and
2057 .B SS
2058 reset it);
2059 it is imposed by the
2060 .BR TP ,
2061 .BR IP ,
2062 and
2063 .B HP
2064 macros,
2065 and cancelled by
2066 .B P
2067 and its synonyms.
2068 .
2069 An extensive example follows.
2070 .
2071 .
2072 .br
2073 .ne 2v
2074 .P
2075 This ordinary
2076 .RB ( P )
2077 paragraph is not in a relative inset nor does it possess an indentation.
2078 .
2079 .
2080 .RS
2081 .P
2082 Now we have created a relative inset with
2083 .B RS
2084 and started another ordinary paragraph with
2085 .BR P .
2086 .
2087 We observe that all of its lines are inset and indented the same;
2088 contrast with a first-line indentation.
2089 .
2090 .
2091 .TP
2092 .B tag
2093 This tagged paragraph,
2094 set with
2095 .BR TP ,
2096 is still within the
2097 .B RS
2098 region,
2099 but lines after the first have a supplementary indentation that the
2100 tag lacks.
2101 .
2102 .
2103 .IP
2104 A paragraph like this one,
2105 set with
2106 .BR IP ,
2107 appears to the reader as also associated with the tag above,
2108 because
2109 .B IP
2110 re-uses the previous paragraph's indentation unless given an argument
2111 to change it.
2112 .
2113 Both the inset amount
2114 .RB ( RS )
2115 and indentation
2116 .RB ( IP )
2117 affect this paragraph.
2118 .
2119 .TS
2120 box;
2121 l.
2122 This table is affected both by
2123 the inset amount and indentation.
2124 .TE
2125 .
2126 .
2127 .IP \[bu]
2128 This indented paragraph is marked with a bullet,
2129 contrasting the inset amount and the indentation;
2130 only the former affects the mark,
2131 but both affect the text of the paragraph.
2132 .
2133 .
2134 .P
2135 This ordinary
2136 .RB ( P )
2137 paragraph resets the indentation,
2138 but the inset amount is unchanged.
2139 .
2140 .TS
2141 box;
2142 l.
2143 This table is affected only
2144 by the inset amount.
2145 .TE
2146 .RE
2147 .
2148 .
2149 .P
2150 Finally,
2151 we have ended the relative inset by using
2152 .BR RE ,
2153 which
2154 (because we used only one
2155 .BR RS / RE
2156 pair)
2157 has restored the inset amount to its initial value.
2158 .
2159 This is an ordinary
2160 .B P
2161 paragraph.
2162 .
2163 .
2164 .P
2165 Resist the temptation to mock up tabular or multi-column output with
2166 tab characters or the indentation arguments to
2167 .BR IP ,
2168 .BR TP ,
2169 .BR RS ,
2170 or
2171 .BR HP ;
2172 the result may not be comprehensible on an output device you fail to
2173 check,
2174 or which is developed in the future.
2175 .
2176 Consider the table preprocessor
2177 .MR \%tbl 1
2178 instead.
2179 .
2180 .
2181 .P
2182 Several macros insert vertical space:
2183 .BR SH ,
2184 .BR SS ,
2185 .BR TP ,
2186 .B P
2187 (and its synonyms),
2188 .BR IP ,
2189 and
2190 .BR HP .
2191 .
2192 They then enable
2193 .I "no-space mode;"
2194 see
2195 .MR groff 7 .
2196 .
2197 The default inter-section and inter-paragraph spacing
2198 is 1v for terminals and 0.4v for typesetters.
2199 \[lq]v\[rq] is a unit of vertical distance,
2200 where 1v is the distance between adjacent text baselines.
2201 .
2202 (The deprecated macro
2203 .B PD
2204 can change this vertical spacing,
2205 but we discourage its use.)
2206 .
2207 Between
2208 .B EX
2209 and
2210 .B EE
2211 calls,
2212 the inter-paragraph spacing is 1v regardless of output
2213 device.
2214 .
2215 .
2216 .\" ====================================================================
2217 .SS Registers
2218 .\" ====================================================================
2219 .
2220 Registers are described in section \[lq]Options\[rq] below.
2221 .
2222 They can be set not only on the command line but in the site
2223 .I man.local
2224 file as well;
2225 see section \[lq]Files\[rq] below.
2226 .
2227 .
2228 .\" ====================================================================
2229 .SS Strings
2230 .\" ====================================================================
2231 .
2232 The following strings are defined for use in man pages.
2233 .
2234 .
2235 .I "groff man"
2236 supports others for configuration of rendering parameters;
2237 see section \[lq]Options\[rq] below.
2238 .
2239 .
2240 .\" In the rest of this section, we retain use of legacy AT&T syntax;
2241 .\" there seems little point in illustrating groff syntax for features
2242 .\" of man(7) that users of groff don't need, and should avoid.
2243 .\"
2244 .\" Special characters named here are not in AT&T's repertoire.
2245 .TP 8n \" accommodate "\e*(Tm", hand-tuned for PDF
2246 .B \e*R
2247 interpolates a special character escape sequence for the \[lq]registered
2248 sign\[rq] glyph,
2249 .BR \e(rg ,
2250 if available,
2251 and \[lq](Reg.)\[rq] otherwise.
2252 .
2253 .
2254 .
2255 .TP
2256 .B \e*S
2257 interpolates an escape sequence setting the type size to the document
2258 default.
2259 .
2260 .
2261 .TP
2262 .B \e*(lq
2263 .TQ
2264 .B \e*(rq
2265 interpolate special character escape sequences for left and right
2266 double-quotation marks,
2267 .B \e(lq
2268 and
2269 .BR \e(rq ,
2270 respectively.
2271 .
2272 .
2273 .TP
2274 .B \e*(Tm
2275 interpolates a special character escape sequence for the \[lq]trade mark
2276 sign\[rq] glyph,
2277 .BR \e(tm ,
2278 if available,
2279 and \[lq](TM)\[rq] otherwise.
2280 .
2281 .
2282 .P
2283 A contemporary man page needs none of the above.
2284 .
2285 .B \e*S
2286 is superfluous;
2287 type size changes are invisible on terminals,
2288 and macros that change it restore its original value afterward.
2289 .
2290 Better alternatives exist for the rest;
2291 simply use the
2292 .BR \[rs][rg] , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9, Solaris
2293 .BR \[rs][lq] , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
2294 .BR \[rs][rq] , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
2295 and
2296 .B \[rs][tm] \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
2297 special character escape sequences directly.
2298 .
2299 Unless you are aiming for a pathological level of portability\[em]\
2300 perhaps composing a man page
2301 for consumption on simulators of 1980s Unix systems
2302 (or Solaris
2303 .IR troff ,
2304 though even it supports
2305 .RB \[lq]\^ \[rs](rg \[rq])\[em]\c
2306 avoid using the above strings.
2307 .
2308 .
2309 .\" ====================================================================
2310 .SS "Use of extensions"
2311 .\" ====================================================================
2312 .
2313 To ensure that your man page formats reliably on a wide variety of
2314 viewers,
2315 write it solely with the macros described in this page
2316 (except for the ones identified as deprecated,
2317 which you should avoid).
2318 .
2319 Macros described as extensions might be unsupported by a formatter that
2320 is important to your audience.
2321 .
2322 Nevertheless,
2323 .IR groff 's
2324 extensions are present because they perform tasks that are otherwise
2325 difficult or tedious to achieve portably.
2326 .
2327 If you require an extension but expect your man page to be rendered
2328 on a system that doesn't support it,
2329 write a configuration test to measure a property of the system,
2330 and use
2331 .MR m4 1 ,
2332 .MR sed 1 ,
2333 or a similar tool to generate a
2334 .I .man
2335 file from a
2336 .I .man.in
2337 file,
2338 defining page-local versions of extension macros only where necessary.
2339 .
2340 You can copy extension macro definitions from
2341 .IR groff ;
2342 see
2343 .I \%an\-ext.tmac
2344 in section \[lq]Files\[rq] below.
2345 .
2346 .
2347 .P
2348 For example,
2349 we might put a line
2350 .
2351 .RS
2352 .EX
2353 @DEFINE_MR@
2354 .EE
2355 .RE
2356 .
2357 in our
2358 .I man
2359 document at the end of the \[lq]Name\[rq] section,
2360 test a system for the availability of the
2361 .I "groff man"
2362 .B MR
2363 macro,
2364 remove the line if the macro is present,
2365 and \[lq]inline\[rq] a definition otherwise,
2366 as follows.
2367 .
2368 (This version is slightly simplified and does not attempt to disable
2369 hyphenation when setting arguments to
2370 .BR MR .)
2371 .
2372 .RS
2373 .EX
2374 have_MR=$(echo .pm | troff \-man 2>&1 | grep \[aq]MR[[:space:]]\[aq])
2375 if [ \-n "$have_MR" ]
2376 then
2377 sed \[aq]/@DEFINE_MR@/d\[aq] myprog.man.in > myprog.man
2378 else
2379 sed \[aq]s/@DEFINE_MR@/.de MR\e
2380 \&. ie \e\e\e\en(.$=1 .I \e\e\e\e$1\e
2381 \&. el .IR \e\e\e\e$1 (\e\e\e\e$2)\e\e\e\e$3\e
2382 \&../\[aq] myprog.man.in > myprog.man
2383 fi
2384 .EE
2385 .RE
2386 .
2387 (The profusion of backslashes is due to its status as an escape
2388 character in both
2389 .I roff
2390 and
2391 .IR sed .)
2392 .
2393 .
2394 .\" XXX: too preachy?
2395 .P
2396 If the foregoing method is too much trouble,
2397 you could apply the radical technique of reading your man page using
2398 every formatter of interest,
2399 confirming satisfactory output from each.
2400 .
2401 Test documentation for syntactic validity and semantic correctness,
2402 just as you would test code.
2403 .
2404 .
2405 .\" ====================================================================
2406 .SS Portability
2407 .\" ====================================================================
2408 .
2409 GNU
2410 .I troff \" GNU
2411 expects its input to contain Unicode basic Latin code points
2412 exclusively.
2413 .
2414 One can
2415 .I maintain
2416 it in a more convenient encoding,
2417 using
2418 .MR preconv 1 ,
2419 as with
2420 .MR groff 1 's
2421 .B \-k
2422 option,
2423 to generate a basic Latin version
2424 that employs special character escape sequences
2425 to access other glyphs.
2426 .
2427 .
2428 .P
2429 AT&T
2430 .IR troff 's \" AT&T
2431 .I man
2432 package and those of many of its descendants format man pages
2433 using a line length of 65 ens
2434 (character cells)
2435 on terminals,
2436 whereas
2437 .I "groff man"
2438 uses 80 ens
2439 (and
2440 .MR mandoc 1
2441 78).
2442 .
2443 Readers with low vision may also benefit from the narrower line length.
2444 .
2445 Inspect your documents with
2446 .RB \[lq] "nroff \-t \-r LL=65n \-man" \[rq]
2447 to ensure that their output lines don't overrun.
2448 .
2449 .
2450 .P
2451 In
2452 .I roff
2453 systems,
2454 elemental functions called
2455 .I requests
2456 and
2457 .I "escape sequences"
2458 control formatting operations.
2459 .
2460 A request appears on a control line.
2461 .
2462 An escape sequence starts with a backslash
2463 .RB ( \[rs] )
2464 and can appear almost anywhere.
2465 .
2466 However,
2467 use of
2468 .I roff
2469 requests
2470 (apart from the empty request
2471 .RB \[lq] . \[rq])\&
2472 risks poor rendering when a page is processed by
2473 .RI non- roff
2474 formatters that attempt to interpret page sources.
2475 .
2476 (Historically,
2477 this was commonly attempted for HTML conversion.)
2478 .
2479 Many of these programs don't interpret the full
2480 .I roff
2481 language
2482 (let alone extensions):
2483 they may be incapable of handling numeric expressions,
2484 control structures,
2485 or register,
2486 string,
2487 and macro definitions,
2488 causing a document's contents
2489 to be presented incomprehensibly
2490 or omitted entirely.
2491 .
2492 If your document uses formatter requests,
2493 or escape sequences not shown below,
2494 it accepts responsibility for restoring
2495 formatter state to what the
2496 .I man
2497 macro package expects.
2498 .
2499 .
2500 .P
2501 Do not put blank (empty) lines in a man page source document.
2502 .
2503 They can produce excessive space in the output,
2504 or less than is attempted;
2505 some
2506 .MR man 1
2507 programs \[lq]squeeze\[rq] multiple blank output lines into one.
2508 .
2509 .
2510 .P
2511 The wise
2512 .I man
2513 author
2514 quotes multi-word section and subsection headings;
2515 the
2516 .B SH
2517 and
2518 .B SS
2519 macros of
2520 .MR man 7
2521 implementations descended from Seventh Edition Unix supported six
2522 arguments at most.
2523 .
2524 This restriction also applied to the
2525 .BR B ,
2526 .BR I ,
2527 .BR SM ,
2528 and font style alternation macros.
2529 .
2530 .
2531 .P
2532 Exercise restraint with escape sequences as with requests.
2533 .
2534 Some escape sequences are however required for correct typesetting
2535 even in man pages and usually do not cause portability problems.
2536 .
2537 Several of these render glyphs corresponding to punctuation code points
2538 in the Unicode basic Latin range
2539 (U+0020\[en]U+007F)
2540 that are handled specially in
2541 .I roff
2542 input;
2543 the escape sequences below must be used to render them correctly and
2544 portably when documenting material that uses them
2545 as literals\[em]namely,
2546 any of the set
2547 .B \[aq] \- \[rs] \[ha] \[ga] \[ti]
2548 (apostrophe,
2549 dash or hyphen-minus,
2550 backslash,
2551 caret,
2552 grave accent,
2553 tilde).
2554 .
2555 .
2556 .if n .TP 10n \" "\newline" + 2n
2557 .if t .TP 9n \" we can get away with less on typesetters
2558 .B \e\[dq]
2559 Comment.
2560 .
2561 The formatter ignores everything after the double quote to the end of
2562 the input line.
2563 .
2564 Place whole-line comments on a control line
2565 immediately after the empty request
2566 .RB (\[lq] . \[rq]).
2567 .
2568 .
2569 .TP
2570 .BI \e newline
2571 Join the next input line to the current one.
2572 .
2573 Except for the update of the input line counter
2574 (used for diagnostic messages and related purposes),
2575 a series of lines ending in backslash-newline appears to
2576 .I groff
2577 as a single input line.
2578 .
2579 Splitting excessively long input lines can ease document maintenance.
2580 .
2581 .
2582 .TP
2583 .B \e%
2584 Control hyphenation.
2585 .
2586 The location of this escape sequence within a word marks a hyphenation
2587 point,
2588 supplementing
2589 .IR groff 's
2590 automatic hyphenation patterns.
2591 .
2592 At the beginning of a word,
2593 it suppresses any hyphenation breaks within
2594 .I except
2595 those specified with
2596 .BR \e% .
2597 .
2598 .
2599 .TP
2600 .B \e:
2601 Insert a non-printing break point.
2602 .
2603 A word can break at such a point,
2604 but a hyphen glyph is not written to the output if it does.
2605 .
2606 The remainder of the word is subject to hyphenation as normal.
2607 .\" XXX: That's a bug; see Savannah #65549, because GNU troff doesn't
2608 .\" stick a hyphenation suppression node at the beginning of the new
2609 .\" output line. Worse, there's no portability here anyway.
2610 .\" See <https://lists.gnu.org/archive/html/groff/2024-04/msg00000.html>
2611 .\" and the thread generally.
2612 .
2613 You can use
2614 .B \e:
2615 and
2616 .B \e%
2617 in combination to control breaking of a file name or URI or to permit
2618 hyphenation only after certain explicit hyphens within a word.
2619 .
2620 See subsection \[lq]Hyperlink macros\[rq] above for an example.
2621 .
2622 .
2623 .IP
2624 .B \e:
2625 is a GNU extension also supported by Heirloom Doctools
2626 .I troff \" Heirloom
2627 050915 (September 2005),
2628 .I mandoc
2629 1.13.1 (2014-08-10),
2630 and
2631 .I neatroff
2632 (commit 399a4936,
2633 2014-02-17),
2634 but not by
2635 DWB,
2636 Plan\~9,
2637 or
2638 Solaris
2639 .IR troff s. \" DWB, Plan 9, Solaris
2640 .\" as of this writing, 2022-08-13
2641 .
2642 .
2643 .TP
2644 .B \e\[ti]
2645 Adjustable non-breaking space.
2646 .
2647 Use this escape sequence to prevent a break inside a short phrase or
2648 between a numerical quantity and its corresponding unit(s).
2649 .
2650 .
2651 .RS
2652 .IP
2653 .EX
2654 Before starting the motor,
2655 set the output speed to\e\[ti]1.
2656 There are 1,024\e\[ti]bytes in 1\e\[ti]KiB.
2657 CSTR\e\[ti]#8 documents the B\e\[ti]language.
2658 .EE
2659 .RE
2660 .
2661 .
2662 .IP
2663 .B \e\[ti]
2664 is a GNU extension
2665 .\" BEGIN Keep in sync with groff.texi node "Other Differences" and
2666 .\" groff_diff(7).
2667 also supported by Heirloom Doctools
2668 .I troff \" Heirloom
2669 050915 (September 2005),
2670 .I mandoc
2671 1.9.14 (2009-11-16),
2672 .I neatroff
2673 (commit 1c6ab0f6e,
2674 2016-09-13),
2675 and
2676 Plan\~9 from User Space
2677 .I troff \" Plan 9
2678 (commit 93f8143600,
2679 2022-08-12),
2680 but not by
2681 DWB
2682 or
2683 Solaris
2684 .IR troff s. \" DWB, Solaris
2685 .\" as of this writing, 2022-08-13
2686 .\" END Keep in sync with groff.texi node "Other Differences" and
2687 .\" groff_diff(7).
2688 .
2689 .
2690 .TP
2691 .B \e&
2692 Dummy character.
2693 .
2694 Prefix an input line with it
2695 to prevent a dot or apostrophe
2696 from being interpreted as beginning a
2697 .I roff
2698 control line.
2699 .
2700 Append
2701 .B \e&
2702 to an end-of-sentence punctuation sequence
2703 to keep it from being recognized as such.
2704 .
2705 .
2706 .TP
2707 .B \e|
2708 Thin space
2709 (one-sixth em on typesetters,
2710 zero-width on terminals);
2711 a non-breaking space.
2712 .
2713 Used primarily in ellipses
2714 (\[lq].\e|.\e|.\[rq])\&
2715 to space the dots more pleasantly on typesetters.
2716 .
2717 .
2718 .TP
2719 .B \ec
2720 End a text line without inserting space or attempting a break.
2721 .
2722 Nothing on the input line after this escape sequence is formatted.
2723 .
2724 .B \[rs]c
2725 is useful when three font styles are
2726 needed in a single word,
2727 as in a command synopsis.
2728 .
2729 .
2730 .RS
2731 .IP
2732 .\" from contrib/pdfmark/pdfroff.1.man
2733 .EX
2734 \&.RB [ \e\-\e\-stylesheet=\ec
2735 \&.IR name ]
2736 .EE
2737 .RE
2738 .
2739 .
2740 .br
2741 .ne 4v
2742 .IP
2743 .B \ec
2744 also helps when changing font styles in
2745 .BR EX / EE
2746 examples,
2747 since they are not filled.
2748 .
2749 .
2750 .br
2751 .ne 6v
2752 .RS
2753 .IP
2754 .\" from src/devices/grotty/grotty.1.man
2755 .EX
2756 \&.EX
2757 $ \ec
2758 \&.B groff \e\-T utf8 \e\-Z \ec
2759 \&.I file \ec
2760 \&.B | grotty \e\-i
2761 \&.EE
2762 .EE
2763 .RE
2764 .
2765 .
2766 .IP
2767 .\" TODO: When we explain what a "sentence" is, move this pargraph
2768 .\" there.
2769 Normally,
2770 if filling is enabled,
2771 the formatter treats the end of a text line like a space.
2772 .
2773 It checks for the end of a sentence,
2774 and
2775 .I may
2776 break the output line
2777 (if not,
2778 it inserts an adjustable space).
2779 .
2780 If filling is disabled,
2781 the formatter
2782 .I will
2783 break the output line,
2784 as in
2785 .BR EX / EE
2786 examples.
2787 .
2788 The formatter interprets the next input line as usual,
2789 recognizing control lines,
2790 including macro calls
2791 (contrast with
2792 .BI \e newline\/\c
2793 ).
2794 .
2795 .
2796 .\" We once warned of \f possibly having "better portability" than \c;
2797 .\" after several years of looking, GBR finds no evidence that this is
2798 .\" the case. However, po4a is confused by \c and refuses to process
2799 .\" documents using it. https://github.com/mquinson/po4a/issues/527
2800 .IP
2801 The
2802 .B \ef
2803 font selection escape sequence is an alternative to
2804 .BR \ec ;
2805 see below.
2806 .
2807 Using
2808 .B \ec
2809 to continue a
2810 .B TP
2811 paragraph tag across multiple input lines renders incorrectly with
2812 .I groff
2813 1.22.3,
2814 .I mandoc
2815 1.14.1,
2816 older versions of these programs,
2817 and perhaps with some other formatters.
2818 .
2819 .
2820 .TP
2821 .B \ee
2822 Format the
2823 .I roff
2824 escape character on the output;
2825 widely used in man pages to render a backslash glyph.
2826 .
2827 .\" Don't bold the ec request in this discussion; it's not a major
2828 .\" topic of _this_ page as it would be in groff(7). Also, we don't
2829 .\" want to encourage people to mess with this old kludge by drawing
2830 .\" attention to it.
2831 It works reliably as long as the \[lq]ec\[rq] request is not used,
2832 which should never happen in man pages,
2833 and it is slightly more portable than the more explicit
2834 .B \e[rs]
2835 (\[lq]reverse solidus\[rq]) special character escape sequence.
2836 .
2837 .
2838 .TP
2839 .BR \efB ,\~ \efI ,\~ \efR ,\~ \efP
2840 Switch to bold,
2841 italic,
2842 roman,
2843 or back to the previous style,
2844 respectively.
2845 .
2846 Either
2847 .B \ef
2848 or
2849 .B \ec
2850 is needed when three different font styles are required in a word.
2851 .
2852 .
2853 .RS
2854 .IP
2855 .\" second example from contrib/pdfmark/pdfroff.1.man
2856 .EX
2857 \&.RB [ \e\-\e\-reference\e\-dictionary=\efI\e,name\e/\efP ]
2858 .IP
2859 \&.RB [ \e\-\e\-reference\e\-dictionary=\ec
2860 \&.IR name ]
2861 .EE
2862 .RE
2863 .
2864 .
2865 .IP
2866 Style escape sequences may be more portable than
2867 .BR \ec .
2868 .
2869 As shown above,
2870 it is up to you to account for italic corrections with
2871 .\" Normally we don't quote escape sequences, but these use
2872 .\" potentially-confusing prose punctuation.
2873 .RB \[lq] \^\e\|/\^ \[rq]
2874 and
2875 .RB \[lq] \^\e\^, \[rq],
2876 which are themselves GNU extensions,
2877 if desired and if supported by your implementation.
2878 .
2879 .
2880 .IP
2881 .B \efP
2882 reliably returns to the style in use immediately preceding the
2883 previous
2884 .B \ef
2885 escape sequence only if no
2886 sectioning,
2887 paragraph,
2888 example,
2889 or style macro calls have intervened.
2890 .
2891 .
2892 .IP
2893 As long as at most two styles are needed in a word,
2894 style macros like
2895 .B B
2896 and
2897 .B BI
2898 usually result in more readable
2899 .I roff
2900 source than
2901 .B \ef
2902 escape sequences do.
2903 .
2904 .
2905 .P
2906 Several special characters are also widely portable.
2907 .\" meaning: groff, Heirloom Doctools troff, neatroff, mandoc
2908 .
2909 Except for
2910 .BR \[rs]\- ,
2911 .BR \[rs][em] ,
2912 and
2913 .BR \[rs][ga] ,
2914 AT&T
2915 .I troff
2916 did not consistently define the characters listed below,
2917 .\" Only \-, \[em], and \[ga] were documented in CSTR #54 (1976). CSTR
2918 .\" #54 (1992) offers no _comprehensive_ list but shows \[en] in its
2919 .\" PostScript DESC file example. In DWB 3.3, \[aq] was supported by the
2920 .\" "post" device, and \[dq] by "pcl" and "Latin1".
2921 but its descendants,
2922 like
2923 DWB,
2924 Plan\~9,
2925 or
2926 Solaris
2927 .IR troff , \" DWB, Plan 9, Solaris
2928 can be made to support them by defining them in font description files,
2929 making them aliases of existing glyphs if necessary;
2930 see
2931 .MR groff_font 5 .
2932 .
2933 .IR groff 's
2934 extended notation for special characters,
2935 .BI \e[ xx ]\c
2936 ,
2937 is also supported by
2938 .MR mandoc 1 ,
2939 Heirloom Doctools
2940 .IR troff , \" Heirloom Doctools
2941 and
2942 .IR neatroff ,
2943 but not
2944 DWB,
2945 Plan\~9,
2946 or
2947 Solaris
2948 .IR troff s. \" DWB, Plan 9, Solaris
2949 .
2950 .
2951 .TP
2952 .B \e\-
2953 Minus sign.
2954 .
2955 .B \e\-
2956 produces the basic Latin hyphen-minus (U+002D) specifying Unix
2957 command-line options and frequently used in file names.
2958 .
2959 .RB \[lq] \- \[rq]
2960 is a hyphen in
2961 .IR roff ;
2962 some output devices format it as U+2010
2963 (hyphen).
2964 .
2965 .
2966 .TP
2967 .B \e[aq]
2968 Basic Latin neutral apostrophe.
2969 .
2970 Some output devices format
2971 .RB \[lq]\| \[aq] \|\[rq]
2972 as a right single quotation mark.
2973 .
2974 .
2975 .TP
2976 .B \e[oq]
2977 .TQ
2978 .B \e[cq]
2979 Opening (left) and closing (right) single quotation marks.
2980 .
2981 Use these for paired directional single quotes,
2982 \[oq]like this\[cq].
2983 .
2984 .
2985 .TP
2986 .B \e[dq]
2987 Basic Latin quotation mark
2988 (double quote).
2989 .
2990 Employ it in macro calls to work around interpretation of
2991 .RB \[oq]\| \[dq] \|\[cq]
2992 as an argument delimiter.
2993 .\" This page prefers double quotes, but not here because they are more
2994 .\" confusing to the eye when another double quote is what is quoted!
2995 .\" AT&T: .RB """
2996 .
2997 .
2998 .RS
2999 .IP
3000 .\" from src/preproc/eqn/eqn.1.man
3001 .EX
3002 \&.TP
3003 \&.BI \[dq]split \e[dq]\[dq] text \e[dq]
3004 .EE
3005 .RE
3006 .
3007 .
3008 .br
3009 .\" XXX: We need only 2v, but 2v more are necessary due to bad
3010 .\" interaction with TP's own use of the ne request.
3011 .ne 4v
3012 .TP
3013 .B \e[lq]
3014 .TQ
3015 .B \e[rq]
3016 Left and right double quotation marks.
3017 .
3018 Use these for paired directional double quotes,
3019 \[lq]like this\[rq].
3020 .
3021 .
3022 .TP
3023 .B \e[em]
3024 Em dash.
3025 .
3026 Use for an interruption\[em]such as this one\[em]in a sentence.
3027 .
3028 .
3029 .TP
3030 .B \e[en]
3031 En dash.
3032 .
3033 Use to separate the ends of a range,
3034 as between numbers;
3035 for example,
3036 \[lq]the digits 1\[en]9\[rq].
3037 .
3038 .
3039 .TP
3040 .B \e[ga]
3041 Basic Latin grave accent.
3042 .
3043 Some output devices format
3044 .RB \[lq]\| \[ga] \|\[rq]
3045 as a left single quotation mark.
3046 .
3047 .
3048 .TP
3049 .B \e[ha]
3050 Basic Latin circumflex accent
3051 (\[lq]hat\[rq]).
3052 .
3053 Some output devices format
3054 .RB \[lq] \[ha] \[rq]
3055 as U+02C6
3056 (modifier letter circumflex accent).
3057 .
3058 .
3059 .TP
3060 .B \e[rs]
3061 Reverse solidus
3062 (backslash).
3063 .
3064 The backslash is the default escape character in the
3065 .I roff
3066 language,
3067 so it does not represent itself in output.
3068 .
3069 Also see
3070 .B \ee
3071 above.
3072 .
3073 .
3074 .TP
3075 .B \e[ti]
3076 Basic Latin tilde.
3077 .
3078 Some output devices format
3079 .RB \[lq] \[ti] \[rq]
3080 as U+02DC
3081 (small tilde).
3082 .
3083 .
3084 .P
3085 For maximum portability,
3086 avoid escape sequences
3087 (including special characters) not listed above.
3088 .
3089 .
3090 .\" ====================================================================
3091 .SS Hooks
3092 .\" ====================================================================
3093 .
3094 Two macros,
3095 both GNU extensions,\" from groff 1.19
3096 are called internally by the
3097 .I "groff man"
3098 package to format page headers and footers and can be redefined by the
3099 administrator in a site's
3100 .I man.local
3101 file
3102 (see section \[lq]Files\[rq] below).
3103 .
3104 The presentation of
3105 .B TH
3106 above describes the default headers and footers.
3107 .
3108 Because these macros are hooks for
3109 .I "groff man"
3110 internals,
3111 man pages have no reason to call them.
3112 .
3113 Such hook definitions typically consist of \[lq]sp\[rq] and
3114 \[lq]tl\[rq] requests.
3115 .
3116 .B PT
3117 furthermore has the responsibility of emitting a PDF bookmark after
3118 writing the first page header in a document.
3119 .
3120 Consult the existing implementations in
3121 .I an.tmac
3122 when drafting replacements.
3123 .
3124 .
3125 .TP
3126 .B .BT
3127 Set the page footer text
3128 (\[lq]bottom trap\[rq]).
3129 .
3130 .
3131 .TP
3132 .B .PT
3133 Set the page header text
3134 (\[lq]page trap\[rq]).
3135 .
3136 .
3137 .P
3138 To remove a page header or footer entirely,
3139 define the appropriate macro as empty rather than deleting it.
3140 .
3141 .
3142 .\" ====================================================================
3143 .SS "Deprecated features"
3144 .\" ====================================================================
3145 .
3146 Use of the following in man pages for public distribution is
3147 discouraged.
3148 .
3149 .
3150 .TP
3151 .BR .AT " ["\c
3152 .IR system " [" release ]]
3153 Alter the footer for use with legacy AT&T man pages,
3154 overriding any definition of the
3155 .I footer-inside
3156 argument to
3157 .BR TH .
3158 .
3159 This macro exists only to render man pages from historical systems.
3160 .
3161 .
3162 .IP
3163 The inside footer is populated per the value of
3164 .I system.
3165 .
3166 .
3167 .RS \" Invisibly move left margin to current IP indentation.
3168 .RS \" Now indent further, visibly.
3169 .TP
3170 3
3171 7th edition
3172 .I (default)
3173 .
3174 .
3175 .TP
3176 4
3177 System III
3178 .
3179 .
3180 .TP
3181 5
3182 System V
3183 .RE \" Move left margin back to IP indentation.
3184 .RE \" Move left margin back to standard position.
3185 .
3186 .
3187 .IP
3188 The optional
3189 .I release
3190 argument specifies the release number,
3191 as in \[lq]System\~V Release\~3\[rq].
3192 .
3193 .
3194 .TP
3195 .B .DT
3196 Reset tab stops to the default
3197 (every 0.5i [inches]).
3198 .
3199 .IP
3200 Use of this presentation-oriented macro is deprecated.
3201 .
3202 It translates poorly to HTML,
3203 under which exact space control and tabulation are not readily
3204 available.
3205 .
3206 Thus,
3207 information or distinctions that you use tab stops to express are likely
3208 to be lost.
3209 .
3210 If you feel tempted to change the tab stops such that calling this macro
3211 later to restore them is desirable,
3212 consider composing a table using
3213 .MR \%tbl 1
3214 instead.
3215 .
3216 .
3217 .br
3218 .ne 5v
3219 .TP
3220 .BI .OP " option-name"\/\c
3221 .RI " [" option-argument ]
3222 Indicate an optional command parameter called
3223 .IR option-name ,
3224 which is set in bold.
3225 .
3226 If the option takes an argument,
3227 specify
3228 .I option-argument
3229 using a noun,
3230 abbreviation,
3231 or hyphenated noun phrase.
3232 .
3233 If present,
3234 .I option-argument
3235 is preceded by a space and set in italics.
3236 .
3237 Square brackets in roman surround both arguments.
3238 .
3239 .
3240 .IP
3241 Use of this quasi-semantic macro,
3242 .\" https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/an.sr#L37
3243 an extension whose name originated in DWB
3244 .IR troff ,\" DWB
3245 is deprecated;
3246 .IR groff 's
3247 interface differs.
3248 .
3249 Neither can easily be used to annotate options
3250 that take optional arguments
3251 or options whose arguments have internal structure
3252 (such as a mixture of literal and variable components).
3253 .
3254 One could work around these limitations
3255 with font selection escape sequences,
3256 but font style alternation macros are preferable;
3257 they are more flexible and perform italic corrections on typesetters.
3258 .
3259 .
3260 .TP
3261 .BR .PD " ["\c
3262 .IR vertical-space ]
3263 Configure the amount of vertical space between paragraphs or
3264 (sub)sections.
3265 .
3266 The optional argument
3267 .I vertical-space
3268 specifies the amount;
3269 the default scaling unit is \[lq]v\[rq].
3270 .
3271 Without an argument,
3272 inter-paragraph spacing resets to its default value;
3273 see subsection \[lq]Horizontal and vertical spacing\[rq] above.
3274 .
3275 .
3276 .IP
3277 Use of this presentation-oriented macro is deprecated.
3278 .
3279 It translates poorly to HTML,
3280 under which exact control of inter-paragraph spacing is not readily
3281 available.
3282 .
3283 Thus,
3284 information or distinctions that you use
3285 .B PD
3286 to express are likely to be lost.
3287 .
3288 .
3289 .TP
3290 .BR .SB \~[\c
3291 .IR text ]
3292 Set
3293 .I text
3294 in bold and
3295 (on typesetters)
3296 one point smaller than the default type size.
3297 .
3298 Given no argument,
3299 .B SB
3300 plants a one-line input trap;
3301 text on the next line,
3302 which can be further formatted with a macro,
3303 is set smaller and in bold.
3304 .
3305 Use of this macro,
3306 an extension originating in SunOS\~4.0
3307 .IR troff ,\" SunOS
3308 .\" ...and which Clark included in groff man(7) from 1.01 or earlier...
3309 is deprecated.
3310 .
3311 .B SM
3312 without an argument,
3313 followed immediately by
3314 .RB \[lq] B
3315 .IR text \[rq],
3316 produces the same output more portably.
3317 .
3318 The macros' order is interchangeable;
3319 put
3320 .I text
3321 with the latter.
3322 .
3323 .
3324 .IP
3325 .I Note:
3326 terminals render
3327 .I text
3328 in bold at the normal size instead.
3329 .
3330 Do not rely upon
3331 .B SB
3332 to communicate semantic information distinct from using bold style at
3333 normal size;
3334 it is hidden from readers using such devices.
3335 .
3336 .
3337 .TP
3338 .BR .UC " ["\c
3339 .IR version ]
3340 Alter the footer for use with legacy BSD man pages,
3341 overriding any definition of the
3342 .I footer-inside
3343 argument to
3344 .BR TH .
3345 .
3346 This macro exists only to render man pages from historical systems.
3347 .
3348 .
3349 .IP
3350 The inside footer is populated per the value of
3351 .I version.
3352 .
3353 .
3354 .RS \" Invisibly move left margin to current IP indentation.
3355 .RS \" Now indent further, visibly.
3356 .TP
3357 .if t \{\
3358 . \" begin hideous cheat for U.S. letter paper
3359 . do nr saved-PD \n[PD]
3360 . do nr PD 0.25v
3361 .\}
3362 3
3363 3rd Berkeley Distribution
3364 .I (default)
3365 .
3366 .
3367 .TP
3368 4
3369 4th Berkeley Distribution
3370 .
3371 .
3372 .TP
3373 5
3374 4.2 Berkeley Distribution
3375 .
3376 .
3377 .TP
3378 6
3379 4.3 Berkeley Distribution
3380 .
3381 .
3382 .TP
3383 7
3384 4.4 Berkeley Distribution
3385 .RE \" Move left margin back to IP indentation.
3386 .RE \" Move left margin back to standard position.
3387 .if t \{\
3388 . \" end hideous cheat for U.S. letter paper
3389 . do nr PD \n[saved-PD]u
3390 . do rr saved-PD
3391 .\}
3392 .
3393 .
3394 .\" ====================================================================
3395 .SS History
3396 .\" ====================================================================
3397 .
3398 .MT [email protected]
3399 M.\& Douglas McIlroy
3400 .ME
3401 designed,
3402 implemented,
3403 and documented the AT&T
3404 .I man
3405 macros
3406 for
3407 Unix Version\~7 (1979) and employed them
3408 to edit Volume\~1 of its
3409 .IR "Programmer's Manual" ,
3410 a compilation of all man pages supplied by the system.
3411 .
3412 The package supported the macros listed in this page
3413 not described as extensions,
3414 except
3415 .B P
3416 .\" SS was implemented in tmac.an but not documented in man(7).
3417 and the deprecated
3418 .B AT
3419 and
3420 .BR UC .
3421 .
3422 It documented no registers and defined only
3423 .B R
3424 and
3425 .B S
3426 strings.
3427 .
3428 .
3429 .P
3430 .B UC
3431 appeared in 3BSD (1980).
3432 .
3433 .\" per https://archive.org/details/\
3434 .\" bitsavers_attunixSysalRelease3Jun80_33886798
3435 Unix System\~III (1980) introduced
3436 .B P
3437 .\" ...and de-documented LP...
3438 and exposed the registers
3439 .B IN
3440 and
3441 .BR LL ,
3442 .\" ...as well as \n[PD], which we implement but don't expose.
3443 which had been internal to Seventh Edition Unix
3444 .IR man .
3445 .
3446 .\" This inference is based on RCS idents of "PWB Manual Entry Macros"
3447 .\" from various forms of "an.src" distributed with System III (an.src
3448 .\" 1.35, dated 5/6/80, lacks the Tm string), Research Unix Version 10
3449 .\" (1.36, dated 11/11/80, has it), Ultrix 3.1 (1.37, dated 12/19/80,
3450 .\" retains it) and "pdp11v" (also 1.37). One source (S. S. Pirzada)
3451 .\" says PWB 2.0 was released in June 1979. I found no record of later
3452 .\" releases and cannot account for the discrepancy (field updates?).
3453 .\" -- GBR
3454 PWB/Unix 2.0 (1980) added the
3455 .B Tm
3456 string.
3457 .
3458 4BSD (1980) added
3459 .\" undocumented VS and VE macros to mark regions with 12-point box
3460 .\" rules (\[br]) as margin characters, as well as...
3461 .B lq
3462 and
3463 .B rq
3464 strings.
3465 .
3466 .\" The SunOS inferences here and below are based on inspection of SunOS
3467 .\" 2.0 (May 1985), 3.2 (September 1986), 3.5 (January 1988), and 4.0
3468 .\" (December 1988) tape archives (only).
3469 SunOS\~2.0 (1985) recognized
3470 .BR C ,
3471 .BR D ,
3472 .BR P ,
3473 and
3474 .B X
3475 registers.
3476 .
3477 4.3BSD (1986) added
3478 .\" undocumented DS and DE macros for "displays", which are RS/RE
3479 .\" wrappers with filling disabled and vertical space of 1v before and
3480 .\" .5v after, as well as...
3481 .B AT
3482 and
3483 .BR P .
3484 .
3485 .\" Per Doug McIlroy in
3486 .\" <https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html>...
3487 Ninth Edition Unix (1986) introduced
3488 .B EX
3489 and
3490 .BR EE .
3491 .\" DWB added EX/EE support, albeit slightly incompatibly.* It
3492 .\" was in 3.3 (1992) but could have appeared as early as 2.0 (1986)
3493 .\" given its relationship to Research Unix.
3494 .\"
3495 .\" * See <https://lists.gnu.org/archive/html/bug-ncurses/2024-03/\
3496 .\" msg00173.html>.
3497 .
3498 SunOS\~4.0 (1988) added
3499 .BR SB .
3500 .
3501 Unix System\~V (1988) incorporated the
3502 .B lq
3503 and
3504 .B rq
3505 strings.
3506 .\" ...whereas DWB 2.0 (1984) apparently did not.
3507 .\" https://lists.gnu.org/archive/html/groff/2025-09/msg00079.html
3508 .\" Going by the SCCS header, DWB had incorporated them by 3.2 (1991?).
3509 .\" https://github.com/n-t-roff/DWB3.3/blob/\
3510 .\" 562bb8615116f46077ca03e8561323cc7a89673e/macros/man/an.sr#L20
3511 .
3512 .
3513 .P
3514 Except for
3515 .BR EX / EE ,
3516 James Clark implemented the foregoing features in early versions of
3517 .I groff.
3518 .
3519 Later,
3520 .I groff
3521 1.20 (2009) resurrected
3522 .BR EX / EE
3523 and originated
3524 .BR SY / YS ,
3525 .BR TQ ,
3526 .BR MT / ME ,
3527 and
3528 .BR UR / UE .
3529 .\" ...along with implementations of OP, EX, and EE.
3530 .\"
3531 .\" It's not clear exactly when OP showed up in DWB troff. It wasn't
3532 .\" in 1.0 (1984), but was by the time of the 3.3 release (1992). Scans
3533 .\" of DWB manuals online suggest that AT&T did not bother to document
3534 .\" DWB's man(7) implementation in printed matter (nor its ms(7)).
3535 .
3536 Plan\~9 from User Space's
3537 .I troff \" plan9port
3538 introduced
3539 .B MR
3540 in 2020,
3541 .\" https://github.com/9fans/plan9port/commit/\
3542 .\" 977b25a76ae8263e53fb4eb1abfc395769f23e3d
3543 .\" d32deab17bfffa5bffc5fab3e6577558e40888c5
3544 .\" 36cd4c58c1346375b98f517fb8568be5bb47618d
3545 and incorporated the
3546 .B lq
3547 and
3548 .B rq
3549 strings in 2025.
3550 .\" https://github.com/9fans/plan9port/commit/\
3551 .\" e5b5757e640371974d2e70144c8e59c6a5b613f6
3552 .
3553 .
3554 .br
3555 .ne 4v
3556 .\" ====================================================================
3557 .SH Options
3558 .\" ====================================================================
3559 .
3560 The following
3561 .I groff
3562 options set registers
3563 (with
3564 .BR \-r )
3565 and strings
3566 (with
3567 .BR \-d )
3568 recognized and used by the
3569 .I man
3570 macro package.
3571 .
3572 To ensure rendering consistent with output device capabilities and
3573 reader preferences,
3574 man pages should never manipulate them.
3575 .
3576 .
3577 .TP 9.25n \" "-rHY=0" + 2n + hand-tuned for PDF
3578 .BI \-dAD= adjustment-mode
3579 Set line adjustment to
3580 .I adjustment-mode,
3581 which is typically
3582 .RB \[lq] b \[rq]
3583 for adjustment to both margins
3584 (the default),
3585 or
3586 .RB \[lq] l \[rq]
3587 for left alignment
3588 (ragged right margin).
3589 .
3590 Any valid argument to
3591 .IR groff 's
3592 \[lq]ad\[rq] request may be used.
3593 .
3594 See
3595 .MR groff 7
3596 for less-common choices.
3597 .
3598 .
3599 .TP
3600 .BI \-rBP= base-paragraph-inset
3601 Set the inset amount for ordinary paragraphs not within an
3602 .BR RS / RE
3603 inset.
3604 .
3605 The default is\~5n.
3606 .
3607 .
3608 .TP
3609 .B \-rcR=1
3610 Enable continuous rendering.
3611 .
3612 Output is not paginated;
3613 instead,
3614 one
3615 (potentially very long)
3616 page is produced.
3617 .
3618 This is the default for terminal and HTML devices.
3619 .
3620 Use
3621 .B \-rcR=0
3622 to disable it on terminals;
3623 on HTML devices,
3624 it cannot be disabled.
3625 .
3626 .
3627 .TP
3628 .B \-rC1
3629 Number output pages consecutively,
3630 in strictly increasing sequence,
3631 rather than resetting the page number to\~1
3632 (or the value of register
3633 .BR P )
3634 with each new
3635 .I man
3636 document.
3637 .
3638 .
3639 .TP
3640 .BI \-rCHECKSTYLE= n
3641 Report problems with usage of this macro package exhibited by the input
3642 at verbosity level
3643 .IR n ,
3644 where
3645 .I n
3646 is an integer in the range 0\[en]3,
3647 inclusive;
3648 .B 0
3649 disables the messages and is the default.
3650 .
3651 This feature is a development and debugging aid
3652 for man page maintainers;
3653 the problems diagnosed,
3654 and range and meanings of the supported levels,
3655 are subject to change.
3656 .
3657 .
3658 .TP
3659 .B \-rCS=1
3660 Set section headings
3661 (the argument(s) to
3662 .BR SH )
3663 in full capitals.
3664 .
3665 This transformation is off by default because it discards lettercase
3666 distinctions.
3667 .
3668 .
3669 .TP
3670 .B \-rCT=1
3671 Set the man page identifier
3672 (the first argument to
3673 .BR TH )
3674 in full capitals in headers and footers.
3675 .
3676 This transformation is off by default because it discards lettercase
3677 distinctions.
3678 .
3679 .
3680 .TP
3681 .B \-rD1
3682 Enable double-sided layout,
3683 formatting footers for even and odd pages differently;
3684 see the description of
3685 .B TH
3686 in subsection \[lq]Document structure macros\[rq] above.
3687 .
3688 .
3689 .TP
3690 .BI \-rFT= footer-distance
3691 Set distance of the footer relative to the bottom of the page to
3692 .I footer-distance;
3693 this amount is always negative.
3694 .
3695 At one half-inch above this location,
3696 the page text is broken before writing the footer.
3697 .
3698 Ignored if continuous rendering is enabled.
3699 .
3700 The default is \[lq]\-0.5i\~\-\~1v\[rq].
3701 .
3702 .
3703 .TP
3704 .BI \-dHF= heading-font
3705 Select the font used for section and subsection headings;
3706 the default is
3707 .RB \[lq] B \[rq]
3708 (bold style of the default family).
3709 .
3710 Any valid argument to
3711 .IR groff 's
3712 \[lq]ft\[rq] request may be used.
3713 .
3714 See
3715 .MR groff 7 .
3716 .
3717 .
3718 .TP
3719 .B \-rHY=0
3720 Disable automatic hyphenation.
3721 .
3722 Normally,
3723 it is enabled\~(1).
3724 .
3725 The hyphenation mode is determined by the
3726 .I groff
3727 locale;
3728 see section \[lq]Localization\[lq] of
3729 .MR groff 7 .
3730 .
3731 .
3732 .TP
3733 .BI \-rIN= standard-indentation
3734 Set the default indentation amount used by
3735 .BR IP ,
3736 .BR TP ,
3737 .\" TQ inherits its indentation from the preceding TP.
3738 and
3739 .BR HP ,
3740 and the inset amount used by
3741 .BR RS .
3742 .
3743 The default is 7n on terminals and 7.2n on typesetters.
3744 .
3745 Use only integer multiples of unit \[lq]n\[rq] on terminals for consistent
3746 indentation.
3747 .
3748 .
3749 .TP
3750 .BI \-rLL= line-length
3751 Set line length;
3752 the default is 80n on terminals
3753 and 6.5i on typesetters.
3754 .
3755 .
3756 .TP
3757 .BI \-rLT= title-length
3758 Set the line length for titles.
3759 .
3760 (\[lq]Titles\[rq] is the
3761 .I roff
3762 term for headers and footers.)
3763 .
3764 By default,
3765 it is set to the line length
3766 (see
3767 .B \-rLL
3768 above).
3769 .
3770 .
3771 .br
3772 .ne 5v
3773 .TP
3774 .BI \-dMF= man-page-topic-font
3775 Select the font used for man page identifiers in
3776 .B TH
3777 calls and topics named in
3778 .B MR
3779 calls;
3780 the default is
3781 .RB \[lq] I \[rq]
3782 (italic style of the default family).
3783 .
3784 Any valid argument to
3785 .IR groff 's
3786 \[lq]ft\[rq] request may be used.
3787 .
3788 If the
3789 .B MF
3790 string ends in \[lq]I\[rq],
3791 the package assumes it to be an oblique typeface,
3792 and applies italic corrections before and after man page topics and
3793 identifiers.
3794 .
3795 .
3796 .TP
3797 .BI \-rP n
3798 Start enumeration of pages at
3799 .IR n .
3800 .
3801 The default is\~1.
3802 .
3803 .
3804 .TP
3805 .BI \-rPO= page-offset
3806 Set page offset;
3807 the default is 0 on terminals
3808 and 1i on typesetters.
3809 .
3810 .
3811 .TP
3812 .BI \-rS type-size
3813 Use
3814 .I type-size
3815 for the document's body text;
3816 acceptable values are 10,
3817 11,
3818 or 12 points.
3819 .
3820 See subsection \[lq]Font style macros\[rq] above for the default.
3821 .
3822 .
3823 .TP
3824 .BI \-rSN= subsection-indentation
3825 Set indentation of subsection headings to
3826 .I subsection-indentation.
3827 .
3828 The default is\~3n.
3829 .
3830 .
3831 .TP
3832 .BI \-rTS= separation
3833 Require the given
3834 .I separation
3835 between a
3836 .B TP
3837 paragraph's tag and its body.
3838 .
3839 The default is\~2n.
3840 .
3841 .
3842 .TP
3843 .B \-rU0
3844 Disable generation of URI hyperlinks in output drivers capable of them,
3845 making the arguments to
3846 .B MT
3847 and
3848 .B UR
3849 calls visible as formatted text.
3850 .
3851 .MR grohtml 1 ,
3852 .MR gropdf 1 ,
3853 and
3854 .MR grotty 1
3855 enable hyperlinks by default
3856 (the last only if not in its legacy output mode).
3857 .
3858 .
3859 .TP
3860 .BI \-rX p
3861 Number successors of
3862 .RI page\~ p
3863 as
3864 .IR p a,
3865 .IR p b,
3866 .IR p c,
3867 and so forth.
3868 .
3869 The register tracking the suffixed page letter uses format \[lq]a\[rq]
3870 (see the \[lq]af\[rq] request in
3871 .MR groff 7 ).
3872 .
3873 For example,
3874 the option
3875 .B \-rX2
3876 produces the following page
3877 numbers: 1,
3878 2,
3879 2a,
3880 2b,
3881 \&.\|.\|.\|,
3882 2aa,
3883 2ab,
3884 and so on.
3885 .
3886 .
3887 .br
3888 .if n .ne 3v
3889 .if t .ne 4v \" section headings are taller on typesetters
3890 .\" ====================================================================
3891 .SH Files
3892 .\" ====================================================================
3893 .
3894 .TP
3895 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:an\:.tmac
3896 Most
3897 .I man
3898 macros are defined in this file.
3899 .
3900 It also loads extensions from
3901 .I \%an\-ext.tmac
3902 (see below).
3903 .
3904 .
3905 .TP
3906 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:\%andoc\:.tmac
3907 This brief
3908 .I groff
3909 program detects whether the
3910 .I man
3911 or
3912 .I mdoc
3913 macro package is used by a document
3914 and loads the correct macro definitions,
3915 taking advantage of the fact that pages using them must call
3916 .B TH
3917 or
3918 .BR Dd ,
3919 respectively,
3920 before any other macros.
3921 .
3922 A
3923 .I man
3924 program or a user typing,
3925 for example,
3926 .RB \[lq] "groff \-mandoc page.1" \[rq],
3927 need not know which package the file
3928 .I page.1
3929 uses.
3930 .
3931 Multiple man pages,
3932 in either format,
3933 can be handled;
3934 .I \%andoc
3935 reloads each macro package as necessary.
3936 .
3937 Page-local redefinitions of names used by the
3938 .I man
3939 or
3940 .I mdoc
3941 packages prior to
3942 .B TH
3943 or
3944 .B Dd
3945 calls are \[lq]clobbered\[rq] by the reloading process.
3946 .
3947 If you want to provide your own definition of an extension macro to
3948 ensure its availability,
3949 the
3950 .I \%an\-ext\:.tmac
3951 entry below offers advice.
3952 .
3953 .
3954 .TP
3955 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:\%an\-ext\:.tmac
3956 Definitions of macros described above as extensions
3957 (and not deprecated)
3958 are contained in this file;
3959 in some cases,
3960 they are simpler versions of definitions appearing in
3961 .IR an.tmac ,
3962 and are ignored if the formatter is GNU
3963 .IR troff .\" GNU
3964 .
3965 They are written to be compatible with AT&T
3966 .I troff \" AT&T
3967 and permissively licensed\[em]not copylefted.
3968 .
3969 To reduce the risk of name space collisions,
3970 string and register names begin only with
3971 .RB \[lq] m \[rq].
3972 .
3973 We encourage man page authors
3974 who are concerned about portability to legacy Unix systems
3975 to copy these definitions into their pages,
3976 and maintainers of
3977 .I troff \" generic
3978 implementations or work-alike systems that format man pages
3979 to re-use them.
3980 .
3981 To ensure reliable rendering,
3982 define them after your page calls
3983 .BR TH ;
3984 see the discussion of
3985 .I \%andoc\:.tmac
3986 above.
3987 .
3988 Further,
3989 it is wise to define such page-local macros
3990 (if at all)
3991 after the \[lq]Name\[rq] section to accommodate timid
3992 .MR makewhatis 8
3993 or
3994 .MR mandb 8
3995 implementations that easily give up scanning for indexing material.
3996 .
3997 .
3998 .TP
3999 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:man\:.tmac
4000 is a wrapper enabling the package to be loaded with the option
4001 .RB \[lq] "\-m man" \[rq].
4002 .
4003 .
4004 .TP
4005 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:\%mandoc\:.tmac
4006 is a wrapper enabling
4007 .I \&andoc.tmac
4008 to be loaded with the option
4009 .RB \[lq] "\-m mandoc" \[rq].
4010 .
4011 .
4012 .TP
4013 .I /usr/\:\%share/\:\%groff/\:\%site\-tmac/\:\%man\:\%.local
4014 Put site-local changes and customizations into this file.
4015 .
4016 .
4017 .RS
4018 .RS
4019 .P
4020 .EX
4021 .ne 2v
4022 \&.\e" Put only one space after the end of a sentence.
4023 \&.ss 12 0 \e" See groff(7).
4024 .ne 2v
4025 \&.\e" Keep pages narrow even on wide terminals.
4026 \&.if n .if \en[LL]>80n .nr LL 80n
4027 .EE
4028 .RE
4029 .RE
4030 .
4031 .
4032 .IP
4033 On multi-user systems,
4034 it is more considerate to users whose preferences may differ from the
4035 administrator's to be less aggressive with such settings,
4036 or to permit their override with a user-specific
4037 .I man.local
4038 file.
4039 .
4040 Place the requests below at the end of the site-local file to
4041 manifest courtesy.
4042 .
4043 .RS
4044 .RS
4045 .EX
4046 \&.soquiet \eV[XDG_CONFIG_HOME]/man.local
4047 \&.soquiet \eV[HOME]/.man.local
4048 .EE
4049 .RE
4050 .
4051 However,
4052 a security-sandboxed
4053 .MR man 1 \" such as man-db 2.8.5
4054 program may lack permission to open such files.
4055 .RE
4056 .
4057 .
4058 .\" ====================================================================
4059 .SH Notes
4060 .\" ====================================================================
4061 .
4062 Some tips on composing and troubleshooting your man pages follow.
4063 .
4064 .
4065 .IP \[bu] 2n
4066 What's the difference between a man page topic and identifier?
4067 .
4068 .
4069 .IP
4070 A single man page may document several related but distinct topics.
4071 For example,
4072 .MR printf 3
4073 and
4074 .MR fprintf 3
4075 are often presented together.
4076 .
4077 Moreover,
4078 multiple programming languages have functions named \[lq]printf\[rq],
4079 and may document these in a man page.
4080 .
4081 The identifier is intended to
4082 (with the section)
4083 uniquely identify a page on the system;
4084 it may furthermore correspond closely to the file name of the document.
4085 .
4086 .
4087 .IP
4088 The
4089 .MR man 1
4090 librarian makes access to man pages convenient by resolving topics to
4091 man page identifiers.
4092 .
4093 Thus,
4094 you can type
4095 .RB \[lq] "man fprintf" \|\[rq],
4096 and other pages can refer to it,
4097 without knowing whether the installed document uses
4098 \[lq]printf\|\[rq],
4099 \[lq]fprintf\|\[rq],
4100 or even \[lq]c_printf\|\[rq]
4101 as its identifier.
4102 .
4103 .
4104 .IP \[bu] 2n
4105 Some ASCII characters look funny or copy and paste wrong.
4106 .
4107 .
4108 .IP
4109 On devices with large glyph repertoires,
4110 like UTF-8-capable terminals and PDF,
4111 GNU
4112 .IR troff , \" GNU
4113 like AT&T
4114 .I troff \" AT&T
4115 before it,
4116 maps several keycaps to code points
4117 outside the Unicode basic Latin range
4118 (historically \[lq]ASCII\[rq])
4119 because that usually results in better typography in the general case.
4120 .
4121 When documenting GNU/Linux command or C language syntax,
4122 however,
4123 this translation is sometimes not desirable.
4124 .
4125 .
4126 .IP
4127 .if t .ne 2v
4128 .if n .ne 3v \" account for horizontal rule
4129 .TS
4130 Cb Cb
4131 RfCR LfCR.
4132 To get a \[lq]literal\[rq].\|.\|. .\|.\|.should be input.
4133 _
4134 \[aq] \[rs][aq]
4135 \- \[rs]\-
4136 \[rs] \[rs][rs]
4137 \[ha] \[rs][ha]
4138 \[ga] \[rs][ga]
4139 \[ti] \[rs][ti]
4140 _
4141 .TE
4142 .
4143 .
4144 .IP
4145 If a neutral double quote (") is needed in a macro argument,
4146 you can use
4147 .B \[rs][dq]
4148 to get it.
4149 .
4150 Do
4151 .I not
4152 use
4153 .B \[rs][aq]
4154 for an ordinary apostrophe
4155 (as in \[lq]can't\[rq])
4156 or
4157 .B \[rs]\-
4158 for an ordinary hyphen
4159 (as in \[lq]word-aligned\[rq]).
4160 .
4161 .\" slack wording for managing stranded lines in PS/PDF output
4162 .\"Review subsection \[lq]Portability\[rq] above.
4163 .
4164 .
4165 .IP \[bu]
4166 Do I ever need to use an empty macro argument ("")?
4167 .
4168 .
4169 .IP
4170 Probably not.
4171 .
4172 When this seems necessary,
4173 often a shorter or clearer alternative is available.
4174 .
4175 .
4176 .IP
4177 .if n .if \n[LL]<72n .RS -4n \" begin shameless cheat for slim terminals
4178 .if t .ne 10v
4179 .if n .ne 16v \" account for horizontal rules
4180 .TS
4181 Cb Cb
4182 LfCR LfCR.
4183 Instead of.\|.\|.\& \&.\|.\|.should be considered.
4184 _
4185 \&.TP \[dq]\[dq] .TP
4186 _
4187 \&.BI \[dq]\[dq] \fIitalic-text bold-text .IB \fIitalic-text bold-text
4188 _
4189 \&.TH foo 1 \[dq]\[dq] \[dq]foo 1.2.3\[dq] .TH foo 1 \
4190 \f(CIyyyy\fP-\f(CImm\fP-\f(CIdd\fP \[dq]foo 1.2.3\[dq]
4191 _
4192 \&.IP \[dq]\[dq] 4n .IP
4193 _
4194 \&.IP \[dq]\[dq] 4n .RS 4n
4195 \fIparagraph .P
4196 \fR.\|.\|. \fIparagraph
4197 \fR.\|.\|. .RE
4198 _
4199 \&.B one two \[dq]\[dq] three .B one two three
4200 .TE
4201 .if n .if \n[LL]<68n .RE \" end shameless cheat for slim terminals
4202 .
4203 .
4204 .IP
4205 In the title heading
4206 .RB ( TH ),
4207 the date of the page's last revision is more important than packaging
4208 information;
4209 it should not be omitted.
4210 .
4211 Ideally,
4212 a page maintainer keeps both up to date.
4213 .
4214 .
4215 .IP
4216 .B IP
4217 is sometimes ill-understood and misused,
4218 especially when no mark argument is supplied\[em]an indentation argument
4219 is not required.
4220 .
4221 By setting an explicit indentation,
4222 you may be overriding the reader's preference as set with the
4223 .B \-rIN
4224 option.
4225 .
4226 If your page renders adequately without one,
4227 use the simpler form.
4228 .
4229 If you need to indent multiple (unmarked) paragraphs,
4230 consider setting an inset region with
4231 .B RS
4232 and
4233 .B RE
4234 instead.
4235 .
4236 .
4237 .IP
4238 In the last example,
4239 the empty argument does have a subtly different effect than its
4240 suggested replacement:
4241 the empty argument causes an additional space character to be
4242 interpolated between the arguments \[lq]two\[rq] and \[lq]three\[rq]\[em]but
4243 it is a regular breaking space,
4244 so it can be discarded at the end of an output line.
4245 .
4246 It is better not to be subtle,
4247 particularly with space,
4248 which can be overlooked in source and rendered forms.
4249 .
4250 .
4251 .IP \[bu]
4252 .B RS
4253 doesn't indent relative to my indented paragraph.
4254 .
4255 .
4256 .IP
4257 The
4258 .B RS
4259 macro determines the
4260 .I "inset amount,"
4261 the position at which an
4262 .I ordinary
4263 paragraph
4264 .RB ( P
4265 and its synonyms)
4266 is set;
4267 the value of the
4268 .B IN
4269 register determines its default amount.
4270 .
4271 This register also determines
4272 the default indentation used by
4273 .BR IP ,
4274 .BR TP ,
4275 and
4276 .BR HP .
4277 .
4278 To create an inset relative to an indented paragraph,
4279 call
4280 .B RS
4281 repeatedly until an acceptable indentation is achieved,
4282 or give
4283 .B RS
4284 an indentation argument that is at least as much as the paragraph's
4285 indentation amount relative to an adjacent ordinary
4286 .RB ( P )
4287 paragraph.
4288 .
4289 .
4290 .IP
4291 Another approach to tagged paragraphs places an
4292 .B RS
4293 call immediately after the tag;
4294 this also forces a break regardless of the tag's width,
4295 which some authors prefer.
4296 .
4297 Follow-up paragraphs under the tag can then be set with
4298 .B P
4299 instead of
4300 .BR IP .
4301 .
4302 Remember to use
4303 .B RE
4304 to end the indented region before starting the next tagged paragraph
4305 (at the appropriate nesting level).
4306 .
4307 .
4308 .IP \[bu]
4309 .B RE
4310 doesn't move the inset back to the expected level.
4311 .
4312 .
4313 .IP
4314 .B RE
4315 takes an inset
4316 .I level
4317 as an argument,
4318 unlike
4319 .BR RS 's
4320 inset
4321 .I amount.
4322 .
4323 .RB \[lq] .RE\~1 \[rq]
4324 goes to the level before any
4325 .B RS
4326 macros were called,
4327 .B RE\~2
4328 goes to the level of the first
4329 .B RS
4330 call you made,
4331 and so forth.
4332 .
4333 If you desire symmetry in your macro calls,
4334 simply issue one
4335 .B RE
4336 without an argument
4337 for each
4338 .B RS
4339 that precedes it.
4340 .
4341 .
4342 .IP
4343 The
4344 .B SH
4345 and
4346 .B SS
4347 sectioning macros clear relative insets;
4348 .B RE
4349 calls have no effect until
4350 .B RS
4351 is used again.
4352 .
4353 .
4354 .IP \[bu]
4355 Do I need to keep typing the indentation in a series of
4356 .B IP
4357 calls?
4358 .
4359 .
4360 .IP
4361 Not if you don't want to change it.
4362 .
4363 Review subsection \[lq]Horizontal and vertical spacing\[rq] above.
4364 .
4365 .
4366 .IP
4367 .if t .ne 5v
4368 .if n .ne 7v \" account for horizontal rules
4369 .TS
4370 Cb Cb
4371 LfCR LfCR.
4372 Instead of.\|.\|. .\|.\|.should be considered.
4373 _
4374 \&.IP \[rs][bu] 4n .IP \[rs][bu] 4n
4375 \fIparagraph \fIparagraph
4376 \&.IP \[rs][bu] 4n .IP \[rs][bu]
4377 \fIanother-paragraph \fIanother-paragraph
4378 _
4379 .TE
4380 .
4381 .
4382 .IP \[bu]
4383 Why doesn't the package provide a string to insert an ellipsis?
4384 .
4385 .
4386 .IP
4387 Examples of ellipsis usage are shown above,
4388 in subsection \[lq]Synopsis macros\[rq].
4389 .
4390 The idiomatic
4391 .I roff
4392 ellipsis is three dots (periods)
4393 with thin space escape sequences
4394 .B \[rs]|
4395 internally separating them.
4396 .
4397 Since dots both begin control lines and are candidate end-of-sentence
4398 characters,
4399 however,
4400 it is sometimes necessary to prefix and/or suffix an ellipsis with the
4401 dummy character escape sequence
4402 .BR \[rs]& .
4403 .
4404 That fact stands even if a string is defined to contain the sequence;
4405 further,
4406 if the string ends with
4407 .BR \[rs]& ,
4408 end-of-sentence detection is defeated when you use the string at the end
4409 of an actual sentence.
4410 .
4411 (Ending a sentence with an ellipsis is often poor style,
4412 but not always.)
4413 .
4414 A hypothetical string
4415 .B EL
4416 that contained an ellipsis,
4417 but not the trailing dummy character
4418 .BR \[rs]& ,
4419 would then need to be suffixed with the latter
4420 when not ending a sentence.
4421 .
4422 .
4423 .IP
4424 .if t .ne 5v
4425 .if n .ne 7v \" account for horizontal rules
4426 .TS
4427 Cb Cb
4428 LfCR LfCR.
4429 Instead of.\|.\|.\& \&.\|.\|.do this.
4430 _
4431 \&.ds EL \[rs]&.\[rs]|.\[rs]|. Arguments are
4432 Arguments are .IR src-file\[rs]\[ti] .\[rs]|.\[rs]|.\[rs]&
4433 \&.IR src-file\[rs]\[ti] \[rs]*(EL\[rs]& .IR dest-dir .
4434 \&.IR dest-dir .
4435 _
4436 .TE
4437 .
4438 .
4439 .IP
4440 The first column practices a false economy;
4441 the savings in typing is offset by the cost of obscuring even the
4442 suggestion of an ellipsis to a casual reader of the source document,
4443 and reduced portability to
4444 .RI non- roff
4445 man page formatters that cannot handle string definitions.
4446 .
4447 .
4448 .IP
4449 Unicode defines an ellipsis code point,
4450 and some fonts have an ellipsis glyph,
4451 which some man pages have accessed non-portably with the font-dependent
4452 .B \[rs]N
4453 escape sequence.
4454 .
4455 We discourage their use;
4456 on terminals,
4457 they may crowd the dots into a half-width character cell,
4458 and do not render at all if the output device lacks the glyph.
4459 .
4460 In synopses,
4461 missing ellipses can mislead the reader.
4462 .
4463 Dots and space are universally supported.
4464 .\" XXX: Does an unconditional _preceding_ dummy character cause
4465 .\" problems?
4466 .
4467 .
4468 .br
4469 .ne 4v
4470 .IP \[bu]
4471 When and how should I use quotation marks?
4472 .
4473 .
4474 .IP
4475 As noted above in subsection \[lq]Font style macros\[rq],
4476 apply quotation marks to
4477 \[lq]brief specimens of literal text,
4478 such as article titles,
4479 inline examples,
4480 mentions of individual characters or short strings,
4481 and (sub)section headings in man pages\[rq].
4482 .
4483 Multi-word literals,
4484 such as Unix commands with arguments,
4485 when set inline
4486 (as opposed to displayed between
4487 .B EX
4488 and
4489 .BR EE ),
4490 should be quoted
4491 to ensure that the boundaries of the literal
4492 are clear even when the material is stripped of font styling
4493 by,
4494 for example,
4495 copy-and-paste operations.
4496 .
4497 .IR groff ,
4498 Heirloom Doctools
4499 .IR troff , \" Heirloom
4500 .IR neatroff ,
4501 and
4502 .I mandoc
4503 support all of the special characters
4504 .BR \[rs][oq] ,
4505 .BR \[rs][cq] ,
4506 .BR \[rs][lq] ,
4507 .BR \[rs][rq] ,
4508 .BR \[rs][aq] ,
4509 and
4510 .B \[rs][dq]
4511 described in subsection \[lq]Portability\[rq] above.
4512 .
4513 DWB,
4514 Plan\~9,
4515 and
4516 Solaris
4517 .IR troff s \" DWB, Plan 9, Solaris
4518 do not.
4519 .
4520 Interpolating the strings
4521 .B \e*(lq
4522 and
4523 .B \e*(rq
4524 portably yields directional double quotation marks,
4525 if available,
4526 in all these formatters
4527 .\" including plan9port/Plan 9 from User Space as of commit e5b5757e64,
4528 .\" 10 October 2025
4529 (though
4530 .I neatroff
4531 does not supply a
4532 .I man
4533 macro package),
4534 but they cannot reliably be used in macro arguments.
4535 .
4536 .
4537 .IP
4538 Obtaining directional single quotation marks is more of a challenge.
4539 .
4540 Historically,
4541 man pages used
4542 .B \[ga]
4543 and
4544 .B \[aq],
4545 which
4546 .I troff \" generic
4547 rendered on typesetters
4548 as \[oq] and \[cq],
4549 exclusively for them.
4550 .
4551 However,
4552 in recent years,
4553 some distributors of
4554 .I groff
4555 have chosen to override the meanings of these characters in man pages,
4556 remapping them to their Unicode Basic Latin code points.
4557 .
4558 Unfortunately,
4559 .B \[ga]
4560 and
4561 .B \[aq]
4562 are the
4563 .I only
4564 reliable means of obtaining directional single quotation marks in AT&T
4565 .IR troff ; \" AT&T
4566 in that implementation,
4567 often no special character escape sequences exist to obtain them.
4568 .
4569 Further,
4570 AT&T
4571 .IR troff 's \" troff
4572 special character identifiers,
4573 like its font names,
4574 were device-specific.
4575 .
4576 To achieve quotation portably in man pages rendered both by
4577 AT&T and more modern
4578 .IR troff s, \" generic
4579 consider adding a preamble to your page after the
4580 .B TH
4581 call as follows.
4582 .
4583 .
4584 .RS
4585 .P
4586 .RS
4587 .EX
4588 \&.ie \[rs]n(.g \[rs]{\[rs]
4589 \&. ds oq \[rs][oq]\[rs]"
4590 \&. ds cq \[rs][cq]\[rs]"
4591 \&.\[rs]}
4592 \&.el \[rs]{\[rs]
4593 \&. ds oq \[ga]\[rs]"
4594 \&. ds cq \[aq]\[rs]"
4595 \&.\[rs]}
4596 .EE
4597 .RE
4598 .
4599 .
4600 .P
4601 You must then use the
4602 .B \[rs]*
4603 escape sequence to interpolate the quotation mark strings.
4604 .
4605 .
4606 .P
4607 .\" begin shameless cheat for slim terminals
4608 .ds Indent \" empty
4609 .if n .if \n[LL]<68n .ds Indent 2n
4610 .RS \*[Indent]
4611 .rm Indent
4612 .\" end shameless cheat for slim terminals
4613 .EX
4614 The command
4615 \&.RB \[rs]*(oq "while !\[rs]& git pull; do sleep 10; done" \[rs]*(cq
4616 retries an update from the repository until it succeeds.
4617 .EE
4618 .RE
4619 .
4620 .P
4621 If this procedure seems complex,
4622 petition your distributor to revert their remapping of the
4623 \[ga] and \[aq] characters.
4624 .RE
4625 .
4626 .
4627 .IP \[bu]
4628 Escape sequences of the form
4629 .BI \[rs][ xx ]
4630 don't format correctly.
4631 .
4632 .
4633 .IP
4634 The
4635 .BI \[rs][ xx ]
4636 special character escape sequence is a
4637 GNU
4638 .I troff
4639 extension also supported by
4640 .I mandoc,
4641 Heirloom Doctools
4642 .I troff,
4643 and
4644 .I neatroff.
4645 .
4646 DWB,
4647 Plan\~9,
4648 and
4649 Solaris
4650 .IR troff s \" DWB, Plan 9, Solaris
4651 don't implement it.
4652 .
4653 If your man page requires portability to these formatters,
4654 spell such escape sequences as
4655 .RB \[lq]\^ \[rs](\c
4656 .IR xx \[rq];
4657 no closing parenthesis is used.
4658 .
4659 .I xx
4660 must be exactly two characters;
4661 .MR groff_char 7
4662 lists portable special character identifiers.
4663 .
4664 .
4665 .\" ====================================================================
4666 .SH Authors
4667 .\" ====================================================================
4668 .
4669 James Clark wrote the initial GNU implementation of the
4670 .I man
4671 macro package. \" by 1.01
4672 .
4673 Later,
4674 .MT wl@\:gnu\:.org
4675 Werner Lemberg
4676 .ME
4677 supplied the
4678 .BR S , \" 1.16
4679 .BR LT , \" 1.18
4680 and
4681 .B cR \" 1.17
4682 registers,
4683 the last a 4.3BSD-Reno
4684 .IR mdoc (7)
4685 feature.
4686 .\" "Assume nroff on crt's [sic] only if cR==1"
4687 .\" https://minnie.tuhs.org/cgi-bin/utree.pl
4688 .\" ?file=4.3BSD-Reno/share/tmac/tmac.doc
4689 .
4690 .MT kollar@\:alltel\:.net
4691 Larry Kollar
4692 .ME
4693 added the
4694 .BR FT ,
4695 .BR HY ,
4696 and
4697 .B SN
4698 registers;
4699 the
4700 .B HF
4701 string;
4702 and the
4703 .B PT
4704 and
4705 .B BT
4706 macros in
4707 .I groff
4708 1.19 (2003).
4709 .
4710 Lemberg and
4711 .MT esr@\:thyrsus\:.com
4712 Eric S.\& Raymond
4713 .ME
4714 contributed
4715 .BR EX / EE ,
4716 .BR MT / ME ,
4717 .BR UR / UE ,
4718 .BR TQ ,
4719 and an early version of the
4720 .BR SY / YS
4721 macros to
4722 .I groff
4723 1.20 (2009).
4724 .
4725 .MT g.branden\:.robinson@\:gmail\:.com
4726 G.\& Branden Robinson
4727 .ME
4728 implemented the
4729 .B AD
4730 and
4731 .B MF
4732 strings;
4733 .BR CS ,
4734 .BR CT ,
4735 and
4736 .B U
4737 registers;
4738 and the
4739 .B MR
4740 macro for
4741 .I groff
4742 1.23 (2023),
4743 and the
4744 .BR BP ,
4745 .BR PO ,
4746 and
4747 .B TS
4748 registers
4749 and a revised implementation of the
4750 .BR SY / YS
4751 macros for
4752 .I groff
4753 1.24 (2026).
4754 .
4755 .
4756 .P
4757 .MT sgk@\:debian\:.org
4758 Susan G.\& Kleinmann
4759 .ME
4760 wrote the initial version of this document
4761 for the Debian GNU/Linux system.
4762 .
4763 Lemberg imported it to
4764 .I groff.
4765 He and Robinson revised and updated it.
4766 .
4767 Raymond and Robinson documented the extension macros.
4768 Raymond also originated the portability section,
4769 to which
4770 .MT schwarze@\:usta\:.de
4771 Ingo Schwarze
4772 .ME
4773 contributed most of the material on escape sequences.
4774 .
4775 .
4776 .\" ====================================================================
4777 .SH "See also"
4778 .\" ====================================================================
4779 .
4780 .MR \%tbl 1 ,
4781 .MR \%eqn 1 ,
4782 and
4783 .MR \%refer 1
4784 are preprocessors used with man pages.
4785 .
4786 .MR man 1
4787 describes the man page librarian on your system.
4788 .
4789 .MR groff_mdoc 7
4790 details the
4791 .I groff
4792 version of BSD's alternative macro package for man pages.
4793 .
4794 .
4795 .P
4796 .MR groff_man 7 ,
4797 .MR groff 7 ,
4798 .MR groff_char 7
4799 .
4800 .
4801 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
4802 .cp \n[*groff_groff_man_7_man_C]
4803 .do rr *groff_groff_man_7_man_C
4804 .
4805 .
4806 .\" Local Variables:
4807 .\" fill-column: 72
4808 .\" mode: nroff
4809 .\" End:
4810 .\" vim: set filetype=groff textwidth=72: