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