| blob | 7706b5ca23df88bd4beabeabdf6585ec45635a4c |
1 .\" $Id: man.7,v 1.143 2019/03/02 22:04:40 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2011-2015,2017,2018,2019 Ingo Schwarze <schwarze@openbsd.org>
5 .\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org>
6 .\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
7 .\"
8 .\" Permission to use, copy, modify, and distribute this software for any
9 .\" purpose with or without fee is hereby granted, provided that the above
10 .\" copyright notice and this permission notice appear in all copies.
11 .\"
12 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
13 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
14 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
15 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
16 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
17 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 .\"
20 .Dd $Mdocdate: March 2 2019 $
21 .Dt MAN 7
22 .Os
23 .Sh NAME
24 .Nm man
25 .Nd legacy formatting language for manual pages
26 .Sh DESCRIPTION
27 The
28 .Nm man
29 language was the standard formatting language for
30 .At
31 manual pages from 1979 to 1989.
32 Do not use it to write new manual pages: it is a purely presentational
33 language and lacks support for semantic markup.
34 Use the
35 .Xr mdoc 7
36 language, instead.
37 .Pp
38 In a
39 .Nm
40 document, lines beginning with the control character
41 .Sq \&.
42 are called
43 .Dq macro lines .
44 The first word is the macro name.
45 It usually consists of two capital letters.
46 For a list of portable macros, see
47 .Sx MACRO OVERVIEW .
48 The words following the macro name are arguments to the macro.
49 .Pp
50 Lines not beginning with the control character are called
51 .Dq text lines .
52 They provide free-form text to be printed; the formatting of the text
53 depends on the respective processing context:
54 .Bd -literal -offset indent
55 \&.SH Macro lines change control state.
56 Text lines are interpreted within the current state.
57 .Ed
58 .Pp
59 Many aspects of the basic syntax of the
60 .Nm
61 language are based on the
62 .Xr roff 7
63 language; see the
64 .Em LANGUAGE SYNTAX
65 and
66 .Em MACRO SYNTAX
67 sections in the
68 .Xr roff 7
69 manual for details, in particular regarding
70 comments, escape sequences, whitespace, and quoting.
71 .Pp
72 Each
73 .Nm
74 document starts with the
75 .Ic TH
76 macro specifying the document's name and section, followed by the
77 .Sx NAME
78 section formatted as follows:
79 .Bd -literal -offset indent
80 \&.TH PROGNAME 1 1979-01-10
81 \&.SH NAME
82 \efBprogname\efR \e(en one line about what it does
83 .Ed
84 .Sh MACRO OVERVIEW
85 This overview is sorted such that macros of similar purpose are listed
86 together.
87 Deprecated and non-portable macros are not included in the overview,
88 but can be found in the alphabetical reference below.
89 .Ss Page header and footer meta-data
90 .Bl -column "RS, RE" description
91 .It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume
92 .It Ic AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
93 .It Ic UC Ta display BSD version in the page footer (<= 1 argument)
94 .El
95 .Ss Sections and paragraphs
96 .Bl -column "RS, RE" description
97 .It Ic SH Ta section header (one line)
98 .It Ic SS Ta subsection header (one line)
99 .It Ic PP Ta start an undecorated paragraph (no arguments)
100 .It Ic RS , RE Ta reset the left margin: Op Ar width
101 .It Ic IP Ta indented paragraph: Op Ar head Op Ar width
102 .It Ic TP Ta tagged paragraph: Op Ar width
103 .It Ic PD Ta set vertical paragraph distance: Op Ar height
104 .It Ic in Ta additional indent: Op Ar width
105 .El
106 .Ss Physical markup
107 .Bl -column "RS, RE" description
108 .It Ic B Ta boldface font
109 .It Ic I Ta italic font
110 .It Ic SB Ta small boldface font
111 .It Ic SM Ta small roman font
112 .It Ic BI Ta alternate between boldface and italic fonts
113 .It Ic BR Ta alternate between boldface and roman fonts
114 .It Ic IB Ta alternate between italic and boldface fonts
115 .It Ic IR Ta alternate between italic and roman fonts
116 .It Ic RB Ta alternate between roman and boldface fonts
117 .It Ic RI Ta alternate between roman and italic fonts
118 .El
119 .Sh MACRO REFERENCE
120 This section is a canonical reference to all macros, arranged
121 alphabetically.
122 For the scoping of individual macros, see
123 .Sx MACRO SYNTAX .
124 .Bl -tag -width 3n
125 .It Ic AT
126 Sets the volume for the footer for compatibility with man pages from
127 .At
128 releases.
129 The optional arguments specify which release it is from.
130 .It Ic B
131 Text is rendered in bold face.
132 .It Ic BI
133 Text is rendered alternately in bold face and italic.
134 Thus,
135 .Sq .BI this word and that
136 causes
137 .Sq this
138 and
139 .Sq and
140 to render in bold face, while
141 .Sq word
142 and
143 .Sq that
144 render in italics.
145 Whitespace between arguments is omitted in output.
146 .Pp
147 Example:
148 .Pp
149 .Dl \&.BI bold italic bold italic
150 .It Ic BR
151 Text is rendered alternately in bold face and roman (the default font).
152 Whitespace between arguments is omitted in output.
153 See also
154 .Ic BI .
155 .It Ic DT
156 Restore the default tabulator positions.
157 They are at intervals of 0.5 inches.
158 This has no effect unless the tabulator positions were changed with the
159 .Xr roff 7
160 .Ic ta
161 request.
162 .It Ic EE
163 This is a non-standard GNU extension.
164 In
165 .Xr mandoc 1 ,
166 it does the same as the
167 .Xr roff 7
168 .Ic fi
169 request (switch to fill mode).
170 .It Ic EX
171 This is a non-standard GNU extension.
172 In
173 .Xr mandoc 1 ,
174 it does the same as the
175 .Xr roff 7
176 .Ic nf
177 request (switch to no-fill mode).
178 .It Ic HP
179 Begin a paragraph whose initial output line is left-justified, but
180 subsequent output lines are indented, with the following syntax:
181 .Pp
182 .D1 Pf . Ic HP Op Ar width
183 .Pp
184 The
185 .Ar width
186 argument is a
187 .Xr roff 7
188 scaling width.
189 If specified, it's saved for later paragraph left margins;
190 if unspecified, the saved or default width is used.
191 .Pp
192 This macro is portable, but deprecated
193 because it has no good representation in HTML output,
194 usually ending up indistinguishable from
195 .Ic PP .
196 .It Ic I
197 Text is rendered in italics.
198 .It Ic IB
199 Text is rendered alternately in italics and bold face.
200 Whitespace between arguments is omitted in output.
201 See also
202 .Ic BI .
203 .It Ic IP
204 Begin an indented paragraph with the following syntax:
205 .Pp
206 .D1 Pf . Ic IP Op Ar head Op Ar width
207 .Pp
208 The
209 .Ar width
210 argument is a
211 .Xr roff 7
212 scaling width defining the left margin.
213 It's saved for later paragraph left-margins; if unspecified, the saved or
214 default width is used.
215 .Pp
216 The
217 .Ar head
218 argument is used as a leading term, flushed to the left margin.
219 This is useful for bulleted paragraphs and so on.
220 .It Ic IR
221 Text is rendered alternately in italics and roman (the default font).
222 Whitespace between arguments is omitted in output.
223 See also
224 .Ic BI .
225 .It Ic LP
226 A synonym for
227 .Ic PP .
228 .It Ic ME
229 End a mailto block started with
230 .Ic MT .
231 This is a non-standard GNU extension.
232 .It Ic MT
233 Begin a mailto block.
234 This is a non-standard GNU extension.
235 It has the following syntax:
236 .Bd -unfilled -offset indent
237 .Pf . Ic MT Ar address
238 link description to be shown
239 .Pf . Ic ME
240 .Ed
241 .It Ic OP
242 Optional command-line argument.
243 This is a non-standard GNU extension.
244 It has the following syntax:
245 .Pp
246 .D1 Pf . Ic OP Ar key Op Ar value
247 .Pp
248 The
249 .Ar key
250 is usually a command-line flag and
251 .Ar value
252 its argument.
253 .It Ic P
254 A synonym for
255 .Ic PP .
256 .It Ic PD
257 Specify the vertical space to be inserted before each new paragraph.
258 .br
259 The syntax is as follows:
260 .Pp
261 .D1 Pf . Ic PD Op Ar height
262 .Pp
263 The
264 .Ar height
265 argument is a
266 .Xr roff 7
267 scaling width.
268 It defaults to
269 .Cm 1v .
270 If the unit is omitted,
271 .Cm v
272 is assumed.
273 .Pp
274 This macro affects the spacing before any subsequent instances of
275 .Ic HP ,
276 .Ic IP ,
277 .Ic LP ,
278 .Ic P ,
279 .Ic PP ,
280 .Ic SH ,
281 .Ic SS ,
282 .Ic SY ,
283 and
284 .Ic TP .
285 .It Ic PP
286 Begin an undecorated paragraph.
287 The scope of a paragraph is closed by a subsequent paragraph,
288 sub-section, section, or end of file.
289 The saved paragraph left-margin width is reset to the default.
290 .It Ic RB
291 Text is rendered alternately in roman (the default font) and bold face.
292 Whitespace between arguments is omitted in output.
293 See also
294 .Ic BI .
295 .It Ic RE
296 Explicitly close out the scope of a prior
297 .Ic RS .
298 The default left margin is restored to the state before that
299 .Ic RS
300 invocation.
301 .Pp
302 The syntax is as follows:
303 .Pp
304 .D1 Pf . Ic RE Op Ar level
305 .Pp
306 Without an argument, the most recent
307 .Ic RS
308 block is closed out.
309 If
310 .Ar level
311 is 1, all open
312 .Ic RS
313 blocks are closed out.
314 Otherwise,
315 .Ar level No \(mi 1
316 nested
317 .Ic RS
318 blocks remain open.
319 .It Ic RI
320 Text is rendered alternately in roman (the default font) and italics.
321 Whitespace between arguments is omitted in output.
322 See also
323 .Ic BI .
324 .It Ic RS
325 Temporarily reset the default left margin.
326 This has the following syntax:
327 .Pp
328 .D1 Pf . Ic RS Op Ar width
329 .Pp
330 The
331 .Ar width
332 argument is a
333 .Xr roff 7
334 scaling width.
335 If not specified, the saved or default width is used.
336 .Pp
337 See also
338 .Ic RE .
339 .It Ic SB
340 Text is rendered in small size (one point smaller than the default font)
341 bold face.
342 .It Ic SH
343 Begin a section.
344 The scope of a section is only closed by another section or the end of
345 file.
346 The paragraph left-margin width is reset to the default.
347 .It Ic SM
348 Text is rendered in small size (one point smaller than the default
349 font).
350 .It Ic SS
351 Begin a sub-section.
352 The scope of a sub-section is closed by a subsequent sub-section,
353 section, or end of file.
354 The paragraph left-margin width is reset to the default.
355 .It Ic SY
356 Begin a synopsis block with the following syntax:
357 .Bd -unfilled -offset indent
358 .Pf . Ic SY Ar command
359 .Ar arguments
360 .Pf . Ic YS
361 .Ed
362 .Pp
363 This is a non-standard GNU extension
364 and very rarely used even in GNU manual pages.
365 Formatting is similar to
366 .Ic IP .
367 .It Ic TH
368 Set the name of the manual page for use in the page header
369 and footer with the following syntax:
370 .Pp
371 .D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume
372 .Pp
373 Conventionally, the document
374 .Ar name
375 is given in all caps.
376 The
377 .Ar section
378 is usually a single digit, in a few cases followed by a letter.
379 The recommended
380 .Ar date
381 format is
382 .Sy YYYY-MM-DD
383 as specified in the ISO-8601 standard;
384 if the argument does not conform, it is printed verbatim.
385 If the
386 .Ar date
387 is empty or not specified, the current date is used.
388 The optional
389 .Ar source
390 string specifies the organisation providing the utility.
391 When unspecified,
392 .Xr mandoc 1
393 uses its
394 .Fl Ios
395 argument.
396 The
397 .Ar volume
398 string replaces the default volume title of the
399 .Ar section .
400 .Pp
401 Examples:
402 .Pp
403 .Dl \&.TH CVS 5 "1992-02-12" GNU
404 .It Ic TP
405 Begin a paragraph where the head, if exceeding the indentation width, is
406 followed by a newline; if not, the body follows on the same line after
407 advancing to the indentation width.
408 Subsequent output lines are indented.
409 The syntax is as follows:
410 .Bd -unfilled -offset indent
411 .Pf . Ic TP Op Ar width
412 .Ar head No \e" one line
413 .Ar body
414 .Ed
415 .Pp
416 The
417 .Ar width
418 argument is a
419 .Xr roff 7
420 scaling width.
421 If specified, it's saved for later paragraph left-margins; if
422 unspecified, the saved or default width is used.
423 .It Ic TQ
424 Like
425 .Ic TP ,
426 except that no vertical spacing is inserted before the paragraph.
427 This is a non-standard GNU extension
428 and very rarely used even in GNU manual pages.
429 .It Ic UC
430 Sets the volume for the footer for compatibility with man pages from
431 .Bx
432 releases.
433 The optional first argument specifies which release it is from.
434 .It Ic UE
435 End a uniform resource identifier block started with
436 .Ic UR .
437 This is a non-standard GNU extension.
438 .It Ic UR
439 Begin a uniform resource identifier block.
440 This is a non-standard GNU extension.
441 It has the following syntax:
442 .Bd -unfilled -offset indent
443 .Pf . Ic UR Ar uri
444 link description to be shown
445 .Pf . Ic UE
446 .Ed
447 .It Ic YS
448 End a synopsis block started with
449 .Ic SY .
450 This is a non-standard GNU extension.
451 .It Ic in
452 Indent relative to the current indentation:
453 .Pp
454 .D1 Pf . Ic in Op Ar width
455 .Pp
456 If
457 .Ar width
458 is signed, the new offset is relative.
459 Otherwise, it is absolute.
460 This value is reset upon the next paragraph, section, or sub-section.
461 .El
462 .Sh MACRO SYNTAX
463 The
464 .Nm
465 macros are classified by scope: line scope or block scope.
466 Line macros are only scoped to the current line (and, in some
467 situations, the subsequent line).
468 Block macros are scoped to the current line and subsequent lines until
469 closed by another block macro.
470 .Ss Line Macros
471 Line macros are generally scoped to the current line, with the body
472 consisting of zero or more arguments.
473 If a macro is scoped to the next line and the line arguments are empty,
474 the next line, which must be text, is used instead.
475 Thus:
476 .Bd -literal -offset indent
477 \&.I
478 foo
479 .Ed
480 .Pp
481 is equivalent to
482 .Sq .I foo .
483 If next-line macros are invoked consecutively, only the last is used.
484 If a next-line macro is followed by a non-next-line macro, an error is
485 raised.
486 .Pp
487 The syntax is as follows:
488 .Bd -literal -offset indent
489 \&.YO \(lBbody...\(rB
490 \(lBbody...\(rB
491 .Ed
492 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
493 .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
494 .It Ic AT Ta <=1 Ta current Ta \&
495 .It Ic B Ta n Ta next-line Ta \&
496 .It Ic BI Ta n Ta current Ta \&
497 .It Ic BR Ta n Ta current Ta \&
498 .It Ic DT Ta 0 Ta current Ta \&
499 .It Ic EE Ta 0 Ta current Ta GNU
500 .It Ic EX Ta 0 Ta current Ta GNU
501 .It Ic I Ta n Ta next-line Ta \&
502 .It Ic IB Ta n Ta current Ta \&
503 .It Ic IR Ta n Ta current Ta \&
504 .It Ic OP Ta >=1 Ta current Ta GNU
505 .It Ic PD Ta 1 Ta current Ta \&
506 .It Ic RB Ta n Ta current Ta \&
507 .It Ic RI Ta n Ta current Ta \&
508 .It Ic SB Ta n Ta next-line Ta \&
509 .It Ic SM Ta n Ta next-line Ta \&
510 .It Ic TH Ta >1, <6 Ta current Ta \&
511 .It Ic UC Ta <=1 Ta current Ta \&
512 .It Ic in Ta 1 Ta current Ta Xr roff 7
513 .El
514 .Ss Block Macros
515 Block macros comprise a head and body.
516 As with in-line macros, the head is scoped to the current line and, in
517 one circumstance, the next line (the next-line stipulations as in
518 .Sx Line Macros
519 apply here as well).
520 .Pp
521 The syntax is as follows:
522 .Bd -literal -offset indent
523 \&.YO \(lBhead...\(rB
524 \(lBhead...\(rB
525 \(lBbody...\(rB
526 .Ed
527 .Pp
528 The closure of body scope may be to the section, where a macro is closed
529 by
530 .Ic SH ;
531 sub-section, closed by a section or
532 .Ic SS ;
533 or paragraph, closed by a section, sub-section,
534 .Ic HP ,
535 .Ic IP ,
536 .Ic LP ,
537 .Ic P ,
538 .Ic PP ,
539 .Ic RE ,
540 .Ic SY ,
541 or
542 .Ic TP .
543 No closure refers to an explicit block closing macro.
544 .Pp
545 As a rule, block macros may not be nested; thus, calling a block macro
546 while another block macro scope is open, and the open scope is not
547 implicitly closed, is syntactically incorrect.
548 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
549 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
550 .It Ic HP Ta <2 Ta current Ta paragraph Ta \&
551 .It Ic IP Ta <3 Ta current Ta paragraph Ta \&
552 .It Ic LP Ta 0 Ta current Ta paragraph Ta \&
553 .It Ic ME Ta 0 Ta none Ta none Ta GNU
554 .It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU
555 .It Ic P Ta 0 Ta current Ta paragraph Ta \&
556 .It Ic PP Ta 0 Ta current Ta paragraph Ta \&
557 .It Ic RE Ta <=1 Ta current Ta none Ta \&
558 .It Ic RS Ta 1 Ta current Ta to \&RE Ta \&
559 .It Ic SH Ta >0 Ta next-line Ta section Ta \&
560 .It Ic SS Ta >0 Ta next-line Ta sub-section Ta \&
561 .It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU
562 .It Ic TP Ta n Ta next-line Ta paragraph Ta \&
563 .It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU
564 .It Ic UE Ta 0 Ta current Ta none Ta GNU
565 .It Ic UR Ta 1 Ta current Ta part Ta GNU
566 .It Ic YS Ta 0 Ta none Ta none Ta GNU
567 .El
568 .Pp
569 If a block macro is next-line scoped, it may only be followed by in-line
570 macros for decorating text.
571 .Ss Font handling
572 In
573 .Nm
574 documents, both
575 .Sx Physical markup
576 macros and
577 .Xr roff 7
578 .Ql \ef
579 font escape sequences can be used to choose fonts.
580 In text lines, the effect of manual font selection by escape sequences
581 only lasts until the next macro invocation; in macro lines, it only lasts
582 until the end of the macro scope.
583 Note that macros like
584 .Ic BR
585 open and close a font scope for each argument.
586 .Sh SEE ALSO
587 .Xr man 1 ,
588 .Xr mandoc 1 ,
589 .Xr eqn 7 ,
590 .Xr mandoc_char 7 ,
591 .Xr mdoc 7 ,
592 .Xr roff 7 ,
593 .Xr tbl 7
594 .Sh HISTORY
595 The
596 .Nm
597 language first appeared as a macro package for the roff typesetting
598 system in
599 .At v7 .
600 It was later rewritten by James Clark as a macro package for groff.
601 Eric S. Raymond wrote the extended
602 .Nm
603 macros for groff in 2007.
604 The stand-alone implementation that is part of the
605 .Xr mandoc 1
606 utility written by Kristaps Dzonsons appeared in
607 .Ox 4.6 .
608 .Sh AUTHORS
609 This
610 .Nm
611 reference was written by
612 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .