1 .\"
2 .\" Permission to use, copy, modify, and distribute this software for any
3 .\" purpose with or without fee is hereby granted, provided that the above
4 .\" copyright notice and this permission notice appear in all copies.
5 .\"
6 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
7 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
8 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
9 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
10 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
11 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
12 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
13 .\"
14 .\"
15 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
16 .\" Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
17 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
18 .\"
19 .Dd Jan 3, 2012
20 .Dt MAN 5
21 .Os
22 .Sh NAME
23 .Nm man
24 .Nd legacy formatting language for manual pages
25 .Sh DESCRIPTION
26 Traditionally, the
27 .Nm man
28 language has been used to write
29 .Ux
30 manuals for the
31 .Xr man 1
32 utility.
33 It supports limited control of presentational details like fonts,
34 indentation and spacing.
35 This reference document describes the structure of manual pages
36 and the syntax and usage of the man language.
37 .Pp
38 .Bf -emphasis
39 Do not use
40 .Nm
41 to write your manuals:
42 .Ef
43 It lacks support for semantic markup.
44 Use the
45 .Xr mdoc 5
46 language, instead.
47 .Pp
48 In a
49 .Nm
50 document, lines beginning with the control character
51 .Sq \&.
52 are called
53 .Dq macro lines .
54 The first word is the macro name.
55 It usually consists of two capital letters.
56 For a list of available macros, see
57 .Sx MACRO OVERVIEW .
58 The words following the macro name are arguments to the macro.
59 .Pp
60 Lines not beginning with the control character are called
61 .Dq text lines .
62 They provide free-form text to be printed; the formatting of the text
63 depends on the respective processing context:
64 .Bd -literal -offset indent
65 \&.SH Macro lines change control state.
66 Text lines are interpreted within the current state.
67 .Ed
68 .Pp
69 Many aspects of the basic syntax of the
70 .Nm
71 language are based on the
72 .Xr roff 5
73 language; see the
74 .Em LANGUAGE SYNTAX
75 and
76 .Em MACRO SYNTAX
77 sections in the
78 .Xr roff 5
79 manual for details, in particular regarding
80 comments, escape sequences, whitespace, and quoting.
81 .Sh MANUAL STRUCTURE
82 Each
83 .Nm
84 document must contain the
85 .Sx \&TH
86 macro describing the document's section and title.
87 It may occur anywhere in the document, although conventionally it
88 appears as the first macro.
89 .Pp
90 Beyond
91 .Sx \&TH ,
92 at least one macro or text line must appear in the document.
93 .Pp
94 The following is a well-formed skeleton
95 .Nm
96 file for a utility
97 .Qq progname :
98 .Bd -literal -offset indent
99 \&.TH PROGNAME 1 "Oct 10, 2009"
100 \&.SH NAME
101 \efBprogname\efR \e(en a description goes here
102 \&.\e\(dq .SH LIBRARY
103 \&.\e\(dq For sections 2 & 3 only.
104 \&.SH SYNOPSIS
105 \efBprogname\efR [\efB\e-options\efR] arguments...
106 \&.SH DESCRIPTION
107 The \efBfoo\efR utility processes files...
108 \&.\e\(dq .SH IMPLEMENTATION NOTES
109 \&.\e\(dq .SH RETURN VALUES
110 \&.\e\(dq For sections 2, 3, & 9 only.
111 \&.\e\(dq .SH ENVIRONMENT
112 \&.\e\(dq For sections 1, 1M, 5, & 6 only.
113 \&.\e\(dq .SH FILES
114 \&.\e\(dq .SH EXIT STATUS
115 \&.\e\(dq For sections 1, 1M, & 6 only.
116 \&.\e\(dq .SH EXAMPLES
117 \&.\e\(dq .SH DIAGNOSTICS
118 \&.\e\(dq For sections 1, 1M, 5, 6, & 7 only.
119 \&.\e\(dq .SH ERRORS
120 \&.\e\(dq For sections 2, 3, & 9 only.
121 \&.\e\(dq .SH SEE ALSO
122 \&.\e\(dq .BR foo ( 1 )
123 \&.\e\(dq .SH STANDARDS
124 \&.\e\(dq .SH HISTORY
125 \&.\e\(dq .SH AUTHORS
126 \&.\e\(dq .SH CAVEATS
127 \&.\e\(dq .SH BUGS
128 \&.\e\(dq .SH SECURITY CONSIDERATIONS
129 .Ed
130 .Pp
131 The sections in a
132 .Nm
133 document are conventionally ordered as they appear above.
134 Sections should be composed as follows:
135 .Bl -ohang -offset indent
136 .It Em NAME
137 The name(s) and a short description of the documented material.
138 The syntax for this is generally as follows:
139 .Pp
140 .D1 \efBname\efR \e(en description
141 .It Em LIBRARY
142 The name of the library containing the documented material, which is
143 assumed to be a function in a section 2 or 3 manual.
144 For functions in the C library, this may be as follows:
145 .Pp
146 .D1 Standard C Library (libc, -lc)
147 .It Em SYNOPSIS
148 Documents the utility invocation syntax, function call syntax, or device
149 configuration.
150 .Pp
151 For the first, utilities (sections 1, 1M, and 6), this is
152 generally structured as follows:
153 .Pp
154 .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
155 .Pp
156 For the second, function calls (sections 2, 3, 9):
157 .Pp
158 .D1 \&.B char *name(char *\efIarg\efR);
159 .Pp
160 And for the third, configurations (section 7):
161 .Pp
162 .D1 \&.B name* at cardbus ? function ?
163 .Pp
164 Manuals not in these sections generally don't need a
165 .Em SYNOPSIS .
166 .It Em DESCRIPTION
167 This expands upon the brief, one-line description in
168 .Em NAME .
169 It usually contains a break-down of the options (if documenting a
170 command).
171 .It Em IMPLEMENTATION NOTES
172 Implementation-specific notes should be kept here.
173 This is useful when implementing standard functions that may have side
174 effects or notable algorithmic implications.
175 .It Em RETURN VALUES
176 This section documents the return values of functions in sections 2, 3, and 9.
177 .It Em ENVIRONMENT
178 Documents any usages of environment variables, e.g.,
179 .Xr environ 5 .
180 .It Em FILES
181 Documents files used.
182 It's helpful to document both the file name and a short description of how
183 the file is used (created, modified, etc.).
184 .It Em EXIT STATUS
185 This section documents the command exit status for
186 section 1, 6, and 8 utilities.
187 Historically, this information was described in
188 .Em DIAGNOSTICS ,
189 a practise that is now discouraged.
190 .It Em EXAMPLES
191 Example usages.
192 This often contains snippets of well-formed,
193 well-tested invocations.
194 Make sure that examples work properly!
195 .It Em DIAGNOSTICS
196 Documents error conditions.
197 This is most useful in section 4 manuals.
198 Historically, this section was used in place of
199 .Em EXIT STATUS
200 for manuals in sections 1, 6, and 8; however, this practise is
201 discouraged.
202 .It Em ERRORS
203 Documents error handling in sections 2, 3, and 9.
204 .It Em SEE ALSO
205 References other manuals with related topics.
206 This section should exist for most manuals.
207 .Pp
208 .D1 \&.BR bar \&( 1 \&),
209 .Pp
210 Cross-references should conventionally be ordered
211 first by section, then alphabetically.
212 .It Em STANDARDS
213 References any standards implemented or used, such as
214 .Pp
215 .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
216 .Pp
217 If not adhering to any standards, the
218 .Em HISTORY
219 section should be used.
220 .It Em HISTORY
221 A brief history of the subject, including where support first appeared.
222 .It Em AUTHORS
223 Credits to the person or persons who wrote the code and/or documentation.
224 Authors should generally be noted by both name and email address.
225 .It Em CAVEATS
226 Common misuses and misunderstandings should be explained
227 in this section.
228 .It Em BUGS
229 Known bugs, limitations, and work-arounds should be described
230 in this section.
231 .It Em SECURITY CONSIDERATIONS
232 Documents any security precautions that operators should consider.
233 .El
234 .Sh MACRO OVERVIEW
235 This overview is sorted such that macros of similar purpose are listed
236 together, to help find the best macro for any given purpose.
237 Deprecated macros are not included in the overview, but can be found
238 in the alphabetical reference below.
239 .Ss Page header and footer meta-data
240 .Bl -column "PP, LP, P" description
241 .It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
242 .It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
243 .It Sx UC Ta display BSD version in the page footer (<= 1 argument)
244 .El
245 .Ss Sections and paragraphs
246 .Bl -column "PP, LP, P" description
247 .It Sx SH Ta section header (one line)
248 .It Sx SS Ta subsection header (one line)
249 .It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
250 .It Sx RS , RE Ta reset the left margin: Op Ar width
251 .It Sx IP Ta indented paragraph: Op Ar head Op Ar width
252 .It Sx TP Ta tagged paragraph: Op Ar width
253 .It Sx HP Ta hanged paragraph: Op Ar width
254 .It Sx \&br Ta force output line break in text mode (no arguments)
255 .It Sx \&sp Ta force vertical space: Op Ar height
256 .It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
257 .It Sx in Ta additional indent: Op Ar width
258 .El
259 .Ss Physical markup
260 .Bl -column "PP, LP, P" description
261 .It Sx B Ta boldface font
262 .It Sx I Ta italic font
263 .It Sx R Ta roman (default) font
264 .It Sx SB Ta small boldface font
265 .It Sx SM Ta small roman font
266 .It Sx BI Ta alternate between boldface and italic fonts
267 .It Sx BR Ta alternate between boldface and roman fonts
268 .It Sx IB Ta alternate between italic and boldface fonts
269 .It Sx IR Ta alternate between italic and roman fonts
270 .It Sx RB Ta alternate between roman and boldface fonts
271 .It Sx RI Ta alternate between roman and italic fonts
272 .El
273 .Ss Semantic markup
274 .Bl -column "PP, LP, P" description
275 .It Sx OP Ta optional arguments
276 .El
277 .Sh MACRO REFERENCE
278 This section is a canonical reference to all macros, arranged
279 alphabetically.
280 For the scoping of individual macros, see
281 .Sx MACRO SYNTAX .
282 .Ss \&AT
283 Sets the volume for the footer for compatibility with man pages from
284 .Tn AT&T UNIX
285 releases.
286 The optional arguments specify which release it is from.
287 .Ss \&B
288 Text is rendered in bold face.
289 .Pp
290 See also
291 .Sx \&I
292 and
293 .Sx \&R .
294 .Ss \&BI
295 Text is rendered alternately in bold face and italic.
296 Thus,
297 .Sq .BI this word and that
298 causes
299 .Sq this
300 and
301 .Sq and
302 to render in bold face, while
303 .Sq word
304 and
305 .Sq that
306 render in italics.
307 Whitespace between arguments is omitted in output.
308 .Pp
309 Examples:
310 .Pp
311 .Dl \&.BI bold italic bold italic
312 .Pp
313 The output of this example will be emboldened
314 .Dq bold
315 and italicised
316 .Dq italic ,
317 with spaces stripped between arguments.
318 .Pp
319 See also
320 .Sx \&IB ,
321 .Sx \&BR ,
322 .Sx \&RB ,
323 .Sx \&RI ,
324 and
325 .Sx \&IR .
326 .Ss \&BR
327 Text is rendered alternately in bold face and roman (the default font).
328 Whitespace between arguments is omitted in output.
329 .Pp
330 See
331 .Sx \&BI
332 for an equivalent example.
333 .Pp
334 See also
335 .Sx \&BI ,
336 .Sx \&IB ,
337 .Sx \&RB ,
338 .Sx \&RI ,
339 and
340 .Sx \&IR .
341 .Ss \&DT
342 Has no effect.
343 Included for compatibility.
344 .Ss \&HP
345 Begin a paragraph whose initial output line is left-justified, but
346 subsequent output lines are indented, with the following syntax:
347 .Bd -filled -offset indent
348 .Pf \. Sx \&HP
349 .Op Cm width
350 .Ed
351 .Pp
352 The
353 .Cm width
354 argument must conform to
355 .Sx Scaling Widths .
356 If specified, it's saved for later paragraph left-margins; if unspecified, the
357 saved or default width is used.
358 .Pp
359 See also
360 .Sx \&IP ,
361 .Sx \&LP ,
362 .Sx \&P ,
363 .Sx \&PP ,
364 and
365 .Sx \&TP .
366 .Ss \&I
367 Text is rendered in italics.
368 .Pp
369 See also
370 .Sx \&B
371 and
372 .Sx \&R .
373 .Ss \&IB
374 Text is rendered alternately in italics and bold face.
375 Whitespace between arguments is omitted in output.
376 .Pp
377 See
378 .Sx \&BI
379 for an equivalent example.
380 .Pp
381 See also
382 .Sx \&BI ,
383 .Sx \&BR ,
384 .Sx \&RB ,
385 .Sx \&RI ,
386 and
387 .Sx \&IR .
388 .Ss \&IP
389 Begin an indented paragraph with the following syntax:
390 .Bd -filled -offset indent
391 .Pf \. Sx \&IP
392 .Op Cm head Op Cm width
393 .Ed
394 .Pp
395 The
396 .Cm width
397 argument defines the width of the left margin and is defined by
398 .Sx Scaling Widths .
399 It's saved for later paragraph left-margins; if unspecified, the saved or
400 default width is used.
401 .Pp
402 The
403 .Cm head
404 argument is used as a leading term, flushed to the left margin.
405 This is useful for bulleted paragraphs and so on.
406 .Pp
407 See also
408 .Sx \&HP ,
409 .Sx \&LP ,
410 .Sx \&P ,
411 .Sx \&PP ,
412 and
413 .Sx \&TP .
414 .Ss \&IR
415 Text is rendered alternately in italics and roman (the default font).
416 Whitespace between arguments is omitted in output.
417 .Pp
418 See
419 .Sx \&BI
420 for an equivalent example.
421 .Pp
422 See also
423 .Sx \&BI ,
424 .Sx \&IB ,
425 .Sx \&BR ,
426 .Sx \&RB ,
427 and
428 .Sx \&RI .
429 .Ss \&LP
430 Begin an undecorated paragraph.
431 The scope of a paragraph is closed by a subsequent paragraph,
432 sub-section, section, or end of file.
433 The saved paragraph left-margin width is reset to the default.
434 .Pp
435 See also
436 .Sx \&HP ,
437 .Sx \&IP ,
438 .Sx \&P ,
439 .Sx \&PP ,
440 and
441 .Sx \&TP .
442 .Ss \&OP
443 Optional command-line argument.
444 This has the following syntax:
445 .Bd -filled -offset indent
446 .Pf \. Sx \&OP
447 .Cm key Op Cm value
448 .Ed
449 .Pp
450 The
451 .Cm key
452 is usually a command-line flag and
453 .Cm value
454 its argument.
455 .Ss \&P
456 Synonym for
457 .Sx \&LP .
458 .Pp
459 See also
460 .Sx \&HP ,
461 .Sx \&IP ,
462 .Sx \&LP ,
463 .Sx \&PP ,
464 and
465 .Sx \&TP .
466 .Ss \&PP
467 Synonym for
468 .Sx \&LP .
469 .Pp
470 See also
471 .Sx \&HP ,
472 .Sx \&IP ,
473 .Sx \&LP ,
474 .Sx \&P ,
475 and
476 .Sx \&TP .
477 .Ss \&R
478 Text is rendered in roman (the default font).
479 .Pp
480 See also
481 .Sx \&I
482 and
483 .Sx \&B .
484 .Ss \&RB
485 Text is rendered alternately in roman (the default font) and bold face.
486 Whitespace between arguments is omitted in output.
487 .Pp
488 See
489 .Sx \&BI
490 for an equivalent example.
491 .Pp
492 See also
493 .Sx \&BI ,
494 .Sx \&IB ,
495 .Sx \&BR ,
496 .Sx \&RI ,
497 and
498 .Sx \&IR .
499 .Ss \&RE
500 Explicitly close out the scope of a prior
501 .Sx \&RS .
502 The default left margin is restored to the state of the original
503 .Sx \&RS
504 invocation.
505 .Ss \&RI
506 Text is rendered alternately in roman (the default font) and italics.
507 Whitespace between arguments is omitted in output.
508 .Pp
509 See
510 .Sx \&BI
511 for an equivalent example.
512 .Pp
513 See also
514 .Sx \&BI ,
515 .Sx \&IB ,
516 .Sx \&BR ,
517 .Sx \&RB ,
518 and
519 .Sx \&IR .
520 .Ss \&RS
521 Temporarily reset the default left margin.
522 This has the following syntax:
523 .Bd -filled -offset indent
524 .Pf \. Sx \&RS
525 .Op Cm width
526 .Ed
527 .Pp
528 The
529 .Cm width
530 argument must conform to
531 .Sx Scaling Widths .
532 If not specified, the saved or default width is used.
533 .Pp
534 See also
535 .Sx \&RE .
536 .Ss \&SB
537 Text is rendered in small size (one point smaller than the default font)
538 bold face.
539 .Ss \&SH
540 Begin a section.
541 The scope of a section is only closed by another section or the end of
542 file.
543 The paragraph left-margin width is reset to the default.
544 .Ss \&SM
545 Text is rendered in small size (one point smaller than the default
546 font).
547 .Ss \&SS
548 Begin a sub-section.
549 The scope of a sub-section is closed by a subsequent sub-section,
550 section, or end of file.
551 The paragraph left-margin width is reset to the default.
552 .Ss \&TH
553 Sets the title of the manual page with the following syntax:
554 .Bd -filled -offset indent
555 .Pf \. Sx \&TH
556 .Ar title section date
557 .Op Ar source Op Ar volume
558 .Ed
559 .Pp
560 Conventionally, the document
561 .Ar title
562 is given in all caps.
563 The recommended
564 .Ar date
565 format is
566 .Sy YYYY-MM-DD
567 as specified in the ISO-8601 standard;
568 if the argument does not conform, it is printed verbatim.
569 If the
570 .Ar date
571 is empty or not specified, the current date is used.
572 The optional
573 .Ar source
574 string specifies the organisation providing the utility.
575 The
576 .Ar volume
577 string replaces the default rendered volume, which is dictated by the
578 manual section.
579 .Pp
580 Examples:
581 .Pp
582 .Dl \&.TH CVS 5 "1992-02-12" GNU
583 .Ss \&TP
584 Begin a paragraph where the head, if exceeding the indentation width, is
585 followed by a newline; if not, the body follows on the same line after a
586 buffer to the indentation width.
587 Subsequent output lines are indented.
588 The syntax is as follows:
589 .Bd -filled -offset indent
590 .Pf \. Sx \&TP
591 .Op Cm width
592 .Ed
593 .Pp
594 The
595 .Cm width
596 argument must conform to
597 .Sx Scaling Widths .
598 If specified, it's saved for later paragraph left-margins; if
599 unspecified, the saved or default width is used.
600 .Pp
601 See also
602 .Sx \&HP ,
603 .Sx \&IP ,
604 .Sx \&LP ,
605 .Sx \&P ,
606 and
607 .Sx \&PP .
608 .Ss \&UC
609 Sets the volume for the footer for compatibility with man pages from
610 BSD releases.
611 The optional first argument specifies which release it is from.
612 .Ss \&br
613 Breaks the current line.
614 Consecutive invocations have no further effect.
615 .Pp
616 See also
617 .Sx \&sp .
618 .Ss \&fi
619 End literal mode begun by
620 .Sx \&nf .
621 .Ss \&ft
622 Change the current font mode.
623 See
624 .Sx Text Decoration
625 for a listing of available font modes.
626 .Ss \&in
627 Indent relative to the current indentation:
628 .Pp
629 .D1 Pf \. Sx \&in Op Cm width
630 .Pp
631 If
632 .Cm width
633 is signed, the new offset is relative.
634 Otherwise, it is absolute.
635 This value is reset upon the next paragraph, section, or sub-section.
636 .Ss \&na
637 Don't align to the right margin.
638 .Ss \&nf
639 Begin literal mode: all subsequent free-form lines have their end of
640 line boundaries preserved.
641 May be ended by
642 .Sx \&fi .
643 Literal mode is implicitly ended by
644 .Sx \&SH
645 or
646 .Sx \&SS .
647 .Ss \&sp
648 Insert vertical spaces into output with the following syntax:
649 .Bd -filled -offset indent
650 .Pf \. Sx \&sp
651 .Op Cm height
652 .Ed
653 .Pp
654 Insert
655 .Cm height
656 spaces, which must conform to
657 .Sx Scaling Widths .
658 If 0, this is equivalent to the
659 .Sx \&br
660 macro.
661 Defaults to 1, if unspecified.
662 .Pp
663 See also
664 .Sx \&br .
665 .Sh MACRO SYNTAX
666 The
667 .Nm
668 macros are classified by scope: line scope or block scope.
669 Line macros are only scoped to the current line (and, in some
670 situations, the subsequent line).
671 Block macros are scoped to the current line and subsequent lines until
672 closed by another block macro.
673 .Ss Line Macros
674 Line macros are generally scoped to the current line, with the body
675 consisting of zero or more arguments.
676 If a macro is scoped to the next line and the line arguments are empty,
677 the next line, which must be text, is used instead.
678 Thus:
679 .Bd -literal -offset indent
680 \&.I
681 foo
682 .Ed
683 .Pp
684 is equivalent to
685 .Sq \&.I foo .
686 If next-line macros are invoked consecutively, only the last is used.
687 If a next-line macro is followed by a non-next-line macro, an error is
688 raised, except for
689 .Sx \&br ,
690 .Sx \&sp ,
691 and
692 .Sx \&na .
693 .Pp
694 The syntax is as follows:
695 .Bd -literal -offset indent
696 \&.YO \(lBbody...\(rB
697 \(lBbody...\(rB
698 .Ed
699 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
700 .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
701 .It Sx \&AT Ta <=1 Ta current Ta \&
702 .It Sx \&B Ta n Ta next-line Ta \&
703 .It Sx \&BI Ta n Ta current Ta \&
704 .It Sx \&BR Ta n Ta current Ta \&
705 .It Sx \&DT Ta 0 Ta current Ta \&
706 .It Sx \&I Ta n Ta next-line Ta \&
707 .It Sx \&IB Ta n Ta current Ta \&
708 .It Sx \&IR Ta n Ta current Ta \&
709 .It Sx \&OP Ta 0, 1 Ta current Ta compat
710 .It Sx \&R Ta n Ta next-line Ta \&
711 .It Sx \&RB Ta n Ta current Ta \&
712 .It Sx \&RI Ta n Ta current Ta \&
713 .It Sx \&SB Ta n Ta next-line Ta \&
714 .It Sx \&SM Ta n Ta next-line Ta \&
715 .It Sx \&TH Ta >1, <6 Ta current Ta \&
716 .It Sx \&UC Ta <=1 Ta current Ta \&
717 .It Sx \&br Ta 0 Ta current Ta compat
718 .It Sx \&fi Ta 0 Ta current Ta compat
719 .It Sx \&ft Ta 1 Ta current Ta compat
720 .It Sx \&in Ta 1 Ta current Ta compat
721 .It Sx \&na Ta 0 Ta current Ta compat
722 .It Sx \&nf Ta 0 Ta current Ta compat
723 .It Sx \&sp Ta 1 Ta current Ta compat
724 .El
725 .Pp
726 Macros marked as
727 .Qq compat
728 are included for compatibility with the significant corpus of existing
729 manuals that mix dialects of roff.
730 These macros should not be used for portable
731 .Nm
732 manuals.
733 .Ss Block Macros
734 Block macros comprise a head and body.
735 As with in-line macros, the head is scoped to the current line and, in
736 one circumstance, the next line (the next-line stipulations as in
737 .Sx Line Macros
738 apply here as well).
739 .Pp
740 The syntax is as follows:
741 .Bd -literal -offset indent
742 \&.YO \(lBhead...\(rB
743 \(lBhead...\(rB
744 \(lBbody...\(rB
745 .Ed
746 .Pp
747 The closure of body scope may be to the section, where a macro is closed
748 by
749 .Sx \&SH ;
750 sub-section, closed by a section or
751 .Sx \&SS ;
752 part, closed by a section, sub-section, or
753 .Sx \&RE ;
754 or paragraph, closed by a section, sub-section, part,
755 .Sx \&HP ,
756 .Sx \&IP ,
757 .Sx \&LP ,
758 .Sx \&P ,
759 .Sx \&PP ,
760 or
761 .Sx \&TP .
762 No closure refers to an explicit block closing macro.
763 .Pp
764 As a rule, block macros may not be nested; thus, calling a block macro
765 while another block macro scope is open, and the open scope is not
766 implicitly closed, is syntactically incorrect.
767 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
768 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
769 .It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
770 .It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
771 .It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
772 .It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
773 .It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
774 .It Sx \&RE Ta 0 Ta current Ta none Ta compat
775 .It Sx \&RS Ta 1 Ta current Ta part Ta compat
776 .It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
777 .It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
778 .It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
779 .El
780 .Pp
781 Macros marked
782 .Qq compat
783 are as mentioned in
784 .Sx Line Macros .
785 .Pp
786 If a block macro is next-line scoped, it may only be followed by in-line
787 macros for decorating text.
788 .Ss Font handling
789 In
790 .Nm
791 documents, both
792 .Sx Physical markup
793 macros and
794 .Xr roff 5
795 .Ql \ef
796 font escape sequences can be used to choose fonts.
797 In text lines, the effect of manual font selection by escape sequences
798 only lasts until the next macro invocation; in macro lines, it only lasts
799 until the end of the macro scope.
800 Note that macros like
801 .Sx \&BR
802 open and close a font scope for each argument.
803 .Sh COMPATIBILITY
804 This section documents areas of questionable portability between
805 implementations of the
806 .Nm
807 language.
808 .Pp
809 .Bl -dash -compact
810 .It
811 Do not depend on
812 .Sx \&SH
813 or
814 .Sx \&SS
815 to close out a literal context opened with
816 .Sx \&nf .
817 This behaviour may not be portable.
818 .It
819 In quoted literals, GNU troff allowed pair-wise double-quotes to produce
820 a standalone double-quote in formatted output.
821 It is not known whether this behaviour is exhibited by other formatters.
822 .It
823 troff suppresses a newline before
824 .Sq \(aq
825 macro output; in mandoc, it is an alias for the standard
826 .Sq \&.
827 control character.
828 .It
829 The
830 .Sq \eh
831 .Pq horizontal position ,
832 .Sq \ev
833 .Pq vertical position ,
834 .Sq \em
835 .Pq text colour ,
836 .Sq \eM
837 .Pq text filling colour ,
838 .Sq \ez
839 .Pq zero-length character ,
840 .Sq \ew
841 .Pq string length ,
842 .Sq \ek
843 .Pq horizontal position marker ,
844 .Sq \eo
845 .Pq text overstrike ,
846 and
847 .Sq \es
848 .Pq text size
849 escape sequences are all discarded in mandoc.
850 .It
851 The
852 .Sq \ef
853 scaling unit is accepted by mandoc, but rendered as the default unit.
854 .It
855 The
856 .Sx \&sp
857 macro does not accept negative values in mandoc.
858 In GNU troff, this would result in strange behaviour.
859 .It
860 In page header lines, GNU troff versions up to and including 1.21
861 only print
862 .Ar volume
863 names explicitly specified in the
864 .Sx \&TH
865 macro; mandoc and newer groff print the default volume name
866 corresponding to the
867 .Ar section
868 number when no
869 .Ar volume
870 is given, like in
871 .Xr mdoc 5 .
872 .El
873 .Pp
874 The
875 .Sx OP
876 macro is part of the extended
877 .Nm
878 macro set, and may not be portable to non-GNU troff implementations.
879 .Sh INTERFACE STABILITY
880 .Nm "Obsolete Committed" .
881 .Sh SEE ALSO
882 .Xr man 1 ,
883 .Xr mandoc 1 ,
884 .Xr eqn 5 ,
885 .Xr mandoc_char 5 ,
886 .Xr mdoc 5 ,
887 .Xr roff 5 ,
888 .Xr tbl 5
889 .Sh HISTORY
890 The
891 .Nm
892 language first appeared as a macro package for the roff typesetting
893 system in
894 .At v7 .
895 It was later rewritten by James Clark as a macro package for groff.
896 Eric S. Raymond wrote the extended
897 .Nm
898 macros for groff in 2007.
899 The stand-alone implementation that is part of the
900 .Xr mandoc 1
901 utility written by Kristaps Dzonsons appeared in
902 .Ox 4.6 .
903 .Sh AUTHORS
904 This
905 .Nm
906 reference was written by
907 .An Kristaps Dzonsons ,
908 .Mt kristaps@bsd.lv .
909 .Sh CAVEATS
910 Do not use this language.
911 Use
912 .Xr mdoc 5 ,
913 instead.
|
1 .\" Copyright (c) 1995, Sun Microsystems, Inc.
2 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
3 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
4 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
5 .Dd "Jul 19, 2014"
6 .Dt MAN 5
7 .Os
8 .Sh NAME
9 .Nm man
10 .Nd macros to format Reference Manual pages
11 .Sh SYNOPSIS
12 .Nm mandoc
13 .Fl T Ar man
14 .Ar
15 .Nm nroff
16 .Fl man
17 .Ar
18 .Nm troff
19 .Fl man
20 .Ar
21 .Sh DESCRIPTION
22 These macros are used to lay out the reference pages in this manual. Note: if
23 .Ar file
24 contains format input for a preprocessor, the commands shown
25 above must be piped through the appropriate preprocessor. This is handled
26 automatically by the
27 .Xr man 1
28 command. See the
29 .Sx Conventions
30 section.
31 .Lp
32 Any text argument
33 .Ar t
34 may be zero to six words. Quotes may be used to
35 include SPACE characters in a
36 .Qq word .
37 If
38 .Ar text
39 is empty, the special
40 treatment is applied to the next input line with text to be printed. In this
41 way
42 .Nm \&.I
43 may be used to italicize a whole line, or
44 .Nm \&.SB
45 may be used to make small bold letters.
46 .Lp
47 A prevailing indent distance is remembered between successive indented
48 paragraphs, and is reset to default value upon reaching a non-indented
49 paragraph. Default units for indents
50 .Nm i
51 are ens.
52 .Lp
53 Type font and size are reset to default values before each paragraph, and after
54 processing font and size setting macros.
55 .Pp
56 These strings are predefined by
57 .Nm -man :
58 .Bl -tag -width Ds
59 .It Nm \e*R
60 .Sq \(rg ,
61 .Sq (Reg)
62 in
63 .Nm nroff .
64 .It Nm \e*S
65 Change to default type size.
66 .El
67 .Sh "Requests"
68 * n.t.l. = next text line; p.i. = prevailing indent
69 .Bl -column ".TH n s d f m" "Cause " "t=n.t.l.*" "Explanation " -offset Ds
70 .It Sy Request Sy Cause Sy "If No" Sy Explanation
71 .It "" Sy Break Sy "Argument" ""
72 .It Nm \&.B Ar "t" no Ar t Ns =n.t.l.* Text is in bold font.
73 .It Nm \&.BI Ar t no Ar t Ns =n.t.l. Join words, alternating bold and italic.
74 .It Nm \&.BR Ar t no Ar t Ns =n.t.l. Join words, alternating bold and roman.
75 .It Nm \&.DT no Li \&.5i 1i... Restore default tabs.
76 .It Nm \&.HP Ar i yes Ar i Ns =p.i.* "Begin paragraph with hanging indent. Set prevailing indent to" Ar i .
77 .It Nm \&.I Ar t no Ar t Ns =n.t.l. Text is italic.
78 .It Nm \&.IB Ar t no Ar t Ns =n.t.l. Join words, altenrating italic and bold.
79 .It Nm \&.IP Ar x Ar i yes Ar x Ns ="" Same as
80 .Nm \&.TP
81 with tag
82 .Ar x .
83 .It Nm \&.IR Ar t no Ar t Ns =n.t.l. Join words, alternating italic and roman.
84 .It Nm \&.IX Ar t no - Index macro, not used (obsolete).
85 .It Nm \&.LP yes - Begin left-aligned paragraph. Set prevailing indent to .5i.
86 .It Nm \&.P yes - Same as
87 .Nm \&.LP .
88 .It Nm \&.PD Ar d no Ar d Ns =.4v Set vertical distance between paragraphs.
89 .It Nm \&.PP yes - Same as
90 .Nm \&.LP .
91 .It Nm \&.RE yes - End of relative indent. Restores prevailing indent.
92 .It Nm \&.RB Ar t no Ar t Ns =n.t.l. Join words, alternating roman and bold.
93 .It Nm \&.RI Ar t no Ar t Ns =n.t.l. Join words, alternating roman and italic.
94 .It Nm \&.RS Ar i yes Ar i Ns =p.i. Start relative indent, increase indent by Ar i .
95 Sets prevailing indent to .5i for nested indents.
96 .It Nm \&.SB Ar t no - Reduce size of text by 1 point, make text bold.
97 .It Nm \&.SH Ar t yes - Section Heading.
98 .It Nm \&.SM Ar t no Ar t Ns =n.t.l. Reduce size of text by 1 point.
99 .It Nm \&.SS Ar t yes Ar t Ns =n.t.l. Section Subheading.
100 .It Nm \&.TH Ar n s d f m yes - Begin reference page Ar n , No of section Ar s ; Ar d No is the date of the most recent change. If present, Ar f No is the left page footer; Ar m No is the main page (center) header. Sets prevailing indent and tabs to .5i.
101 .It Nm \&.TP Ar i yes Ar i Ns =p.i. Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to
102 .Ar i .
103 .It Nm \&.TX Ar t p no - Resolve the title abbreviation Ar t ; No join to punctuation mark (or text) Ar p .
104 .El
105 .Ss "Conventions"
106 When formatting a manual page,
107 .Nm
108 examines the first line to determine
109 whether it requires special processing. For example a first line consisting of:
110 .Lp
111 .Dl \&'\e" t
112 .Lp
113 indicates that the manual page must be run through the
114 .Xr tbl 1
115 preprocessor.
116 .Lp
117 A typical manual page for a command or function is laid out as follows:
118 .Bl -tag -width ".SH RETURN VALUES"
119 .
120 .It Nm \&.TH Ar title Op "1-9"
121 .
122 The name of the command or function, which serves as the title of the manual
123 page. This is followed by the number of the section in which it appears.
124 .
125 .It Nm SH NAME
126 .
127 The name, or list of names, by which the command is called, followed by a dash
128 and then a one-line summary of the action performed. All in roman font, this
129 section contains no
130 .Xr troff 1
131 commands or escapes, and no macro requests.
132 It is used to generate the database used by the
133 .Xr whatis 1
134 command.
135 .
136 .It Nm SH SYNOPSIS
137 .Bl -tag -width "Functions:"
138 .It Sy Commands:
139 The syntax of the command and its arguments, as typed on the command line.
140 When in boldface, a word must be typed exactly as printed. When in italics, a
141 word can be replaced with an argument that you supply. References to bold or
142 italicized items are not capitalized in other sections, even when they begin a
143 sentence.
144 .Lp
145 Syntactic symbols appear in roman face:
146 .Bl -tag -width " "
147 .It Op " "
148 An argument, when surrounded by brackets is optional.
149 .It |
150 Arguments separated by a vertical bar are exclusive. You can supply only one
151 item from such a list.
152 .It \&.\|.\|.
153 Arguments followed by an ellipsis can be repeated. When an ellipsis follows a
154 bracketed set, the expression within the brackets can be repeated.
155 .El
156 .It Sy Functions:
157 If required, the data declaration, or
158 .Li #include
159 directive, is shown first,
160 followed by the function declaration. Otherwise, the function declaration is
161 shown.
162 .El
163 .
164 .It Nm \&.SH DESCRIPTION
165 .
166 A narrative overview of the command or function's external behavior. This
167 includes how it interacts with files or data, and how it handles the standard
168 input, standard output and standard error. Internals and implementation details
169 are normally omitted. This section attempts to provide a succinct overview in
170 answer to the question, "what does it do?"
171 .Lp
172 Literal text from the synopsis appears in constant width, as do literal
173 filenames and references to items that appear elsewhere in the reference
174 manuals. Arguments are italicized.
175 .Lp
176 If a command interprets either subcommands or an input grammar, its command
177 interface or input grammar is normally described in a
178 .Nm USAGE
179 section, which follows the
180 .Nm OPTIONS
181 section. The
182 .Nm DESCRIPTION
183 section only
184 describes the behavior of the command itself, not that of subcommands.
185 .
186 .It Nm \&.SH OPTIONS
187 .
188 The list of options along with a description of how each affects the command's
189 operation.
190 .
191 .It Nm \&.SH RETURN VALUES
192 .
193 A list of the values the library routine will return to the calling program
194 and the conditions that cause these values to be returned.
195 .
196 .It Nm \&.SH EXIT STATUS
197 .
198 A list of the values the utility will return to the calling program or shell,
199 and the conditions that cause these values to be returned.
200 .
201 .It Nm \&.SH FILES
202 .
203 A list of files associated with the command or function.
204 .
205 .It Nm \&.SH SEE ALSO
206 .
207 A comma-separated list of related manual pages, followed by references to other
208 published materials.
209 .
210 .It Nm \&.SH DIAGNOSTICS
211 .
212 A list of diagnostic messages and an explanation of each.
213 .
214 .It Nm \&.SH BUGS
215 .
216 A description of limitations, known defects, and possible problems associated
217 with the command or function.
218 .El
219 .Sh FILES
220 .Pa /usr/share/man/whatis
221 .Sh NOTES
222 The
223 .Nm
224 package should not be used for new documentation. The
225 .Xr mdoc 5 ,
226 package is preferred, as it uses semantic markup rather than physical markup.
227 .Sh CODE SET INDEPENDENCE
228 When processed with
229 .Xr mandoc 1 ,
230 this package is Code Set Independent. However, when processed with
231 legacy tools such as
232 .Xr nroff 1
233 and
234 .Xr troff 1 ,
235 the use of multi-byte characters may not be supported.
236 .Sh INTERFACE STABILITY
237 .Nm Obsolete Committed .
238 The
239 .Xr mdoc 5
240 package should be used instead.
241 .Sh SEE ALSO
242 .Xr eqn 1 ,
243 .Xr man 1 ,
244 .Xr mandoc 1 ,
245 .Xr nroff 1 ,
246 .Xr troff 1 ,
247 .Xr tbl 1 ,
248 .Xr whatis 1 ,
249 .Xr mdoc 5 ,
250 .Rs
251 .%A Dale Dougherty and Tim O'Reilly
252 .%B Unix Text Processing
253 .Re
|