Print this page
9718 update mandoc to 1.14.4
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/mdoc.5.man.txt
+++ new/usr/src/man/man5/mdoc.5.man.txt
1 1 MDOC(5) Standards, Environments, and Macros MDOC(5)
2 2
3 3 NAME
4 4 mdoc - semantic markup language for formatting manual pages
5 5
6 6 DESCRIPTION
7 7 The mdoc language supports authoring of manual pages for the man(1)
8 8 utility by allowing semantic annotations of words, phrases, page sections
9 9 and complete manual pages. Such annotations are used by formatting tools
10 10 to achieve a uniform presentation across all manuals written in mdoc, and
11 11 to support hyperlinking if supported by the output medium.
12 12
13 13 This reference document describes the structure of manual pages and the
14 14 syntax and usage of the mdoc language. The reference implementation of a
15 15 parsing and formatting tool is mandoc(1); the COMPATIBILITY section
16 16 describes compatibility with other implementations.
17 17
18 18 In an mdoc document, lines beginning with the control character `.' are
19 19 called "macro lines". The first word is the macro name. It consists of
20 20 two or three letters. Most macro names begin with a capital letter. For
21 21 a list of available macros, see MACRO OVERVIEW. The words following the
22 22 macro name are arguments to the macro, optionally including the names of
23 23 other, callable macros; see MACRO SYNTAX for details.
24 24
25 25 Lines not beginning with the control character are called "text lines".
26 26 They provide free-form text to be printed; the formatting of the text
27 27 depends on the respective processing context:
28 28
29 29 .Sh Macro lines change control state.
30 30 Text lines are interpreted within the current state.
31 31
32 32 Many aspects of the basic syntax of the mdoc language are based on the
33 33 mandoc_roff(5) language; see the LANGUAGE SYNTAX and MACRO SYNTAX
34 34 sections in the mandoc_roff(5) manual for details, in particular
35 35 regarding comments, escape sequences, whitespace, and quoting. However,
36 36 using mandoc_roff(5) requests in mdoc documents is discouraged; mandoc(1)
37 37 supports some of them merely for backward compatibility.
38 38
39 39 MANUAL STRUCTURE
40 40 A well-formed mdoc document consists of a document prologue followed by
41 41 one or more sections.
42 42
43 43 The prologue, which consists of the Dd, Dt, and Os macros in that order,
44 44 is required for every document.
45 45
46 46 The first section (sections are denoted by Sh) must be the NAME section,
47 47 consisting of at least one Nm followed by Nd.
48 48
49 49 Following that, convention dictates specifying at least the SYNOPSIS and
50 50 DESCRIPTION sections, although this varies between manual sections.
51 51
52 52 The following is a well-formed skeleton mdoc file for a utility
53 53 "progname":
54 54
55 55 .Dd Jan 1, 1970
56 56 .Dt PROGNAME section
57 57 .Os
58 58 .Sh NAME
59 59 .Nm progname
60 60 .Nd one line about what it does
61 61 .\" .Sh LIBRARY
62 62 .\" For sections 2, 3, and 9 only.
63 63 .Sh SYNOPSIS
64 64 .Nm progname
65 65 .Op Fl options
66 66 .Ar
67 67 .Sh DESCRIPTION
68 68 The
69 69 .Nm
70 70 utility processes files ...
71 71 .\" .Sh IMPLEMENTATION NOTES
72 72 .\" .Sh RETURN VALUES
73 73 .\" For sections 2, 3, and 9 only.
74 74 .\" .Sh CONTEXT
75 75 .\" For section 9 functions only.
76 76 .\" .Sh ENVIRONMENT
77 77 .\" For sections 1, 1M, and 5.
78 78 .\" .Sh FILES
79 79 .\" .Sh EXIT STATUS
80 80 .\" For sections 1, 1M, and 5.
81 81 .\" .Sh EXAMPLES
82 82 .\" .Sh DIAGNOSTICS
83 83 .\" .Sh ERRORS
84 84 .\" For sections 2, 3, and 9 only.
85 85 .\" .Sh ARCHITECTURE
86 86 .\" .Sh CODE SET INDEPENDENCE
87 87 .\" For sections 1, 1M, and 3 only.
88 88 .\" .Sh INTERFACE STABILITY
89 89 .\" .Sh MT-LEVEL
90 90 .\" For sections 2 and 3 only.
91 91 .\" .Sh SECURITY
92 92 .\" .Sh SEE ALSO
93 93 .\" .Xr foobar 1
94 94 .\" .Sh STANDARDS
95 95 .\" .Sh HISTORY
96 96 .\" .Sh AUTHORS
97 97 .\" .Sh CAVEATS
98 98 .\" .Sh BUGS
99 99
100 100 The sections in an mdoc document are conventionally ordered as they
101 101 appear above. Sections should be composed as follows:
102 102
103 103 NAME
104 104 The name(s) and a one line description of the documented material.
105 105 The syntax for this as follows:
106 106
107 107 .Nm name0 ,
108 108 .Nm name1 ,
109 109 .Nm name2
110 110 .Nd a one line description
111 111
112 112 Multiple `Nm' names should be separated by commas.
113 113
114 114 The Nm macro(s) must precede the Nd macro.
115 115
116 116 See Nm and Nd.
117 117
118 118 LIBRARY
119 119 The name of the library containing the documented material, which
120 120 is assumed to be a function in a section 2, 3, or 9 manual. The
121 121 syntax for this is as follows:
122 122
123 123 .Lb libarm
124 124
125 125 See Lb.
126 126
127 127 SYNOPSIS
128 128 Documents the utility invocation syntax, function call syntax, or
129 129 device configuration.
130 130
131 131 For the first, utilities (sections 1 and 1M), this is generally
132 132 structured as follows:
133 133
134 134 .Nm bar
135 135 .Op Fl v
136 136 .Op Fl o Ar file
137 137 .Op Ar
138 138 .Nm foo
139 139 .Op Fl v
140 140 .Op Fl o Ar file
141 141 .Op Ar
142 142
143 143 Commands should be ordered alphabetically.
144 144
145 145 For the second, function calls (sections 2, 3, 7I, 7P, 9):
146 146
147 147 .In header.h
148 148 .Vt extern const char *global;
149 149 .Ft "char *"
150 150 .Fn foo "const char *src"
151 151 .Ft "char *"
152 152 .Fn bar "const char *src"
153 153
154 154 Ordering of In, Vt, Fn, and Fo macros should follow C header-file
155 155 conventions.
156 156
157 157 And for the third, configurations (section 7D):
158 158
159 159 .Pa /dev/device_node
160 160
161 161 Manuals not in these sections generally don't need a SYNOPSIS.
162 162
163 163 Some macros are displayed differently in the SYNOPSIS section,
164 164 particularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft. All of these
165 165 macros are output on their own line. If two such dissimilar macros
166 166 are pairwise invoked (except for Ft before Fo or Fn), they are
167 167 separated by a vertical space, unless in the case of Fo, Fn, and
168 168 Ft, which are always separated by vertical space.
169 169
170 170 When text and macros following an Nm macro starting an input line
171 171 span multiple output lines, all output lines but the first will be
172 172 indented to align with the text immediately following the Nm macro,
173 173 up to the next Nm, Sh, or Ss macro or the end of an enclosing
174 174 block, whichever comes first.
175 175
176 176 DESCRIPTION
177 177 This begins with an expansion of the brief, one line description in
178 178 NAME:
179 179
180 180 The
181 181 .Nm
182 182 utility does this, that, and the other.
183 183
184 184 It usually follows with a breakdown of the options (if documenting
185 185 a command), such as:
186 186
187 187 The arguments are as follows:
188 188 .Bl -tag -width Ds
189 189 .It Fl v
190 190 Print verbose information.
191 191 .El
192 192
193 193 List the options in alphabetical order, uppercase before lowercase
194 194 for each letter and with no regard to whether an option takes an
195 195 argument. Put digits in ascending order before all letter options.
196 196
197 197 Manuals not documenting a command won't include the above fragment.
198 198
199 199 Since the DESCRIPTION section usually contains most of the text of
200 200 a manual, longer manuals often use the Ss macro to form
201 201 subsections. In very long manuals, the DESCRIPTION may be split
202 202 into multiple sections, each started by an Sh macro followed by a
203 203 non-standard section name, and each having several subsections,
204 204 like in the present mdoc manual.
205 205
206 206 IMPLEMENTATION NOTES
207 207 Implementation-specific notes should be kept here. This is useful
208 208 when implementing standard functions that may have side effects or
209 209 notable algorithmic implications.
210 210
211 211 RETURN VALUES
212 212 This section documents the return values of functions in sections
213 213 2, 3, and 9.
214 214
215 215 See Rv.
216 216
217 217 CONTEXT
218 218 This section lists the contexts in which functions can be called in
219 219 section 9. The contexts are user, kernel, or interrupt.
220 220
221 221 ENVIRONMENT
222 222 Lists the environment variables used by the utility, and explains
223 223 the syntax and semantics of their values. The environ(5) manual
224 224 provides examples of typical content and formatting.
225 225
226 226 See Ev.
227 227
228 228 FILES
229 229 Documents files used. It's helpful to document both the file name
230 230 and a short description of how the file is used (created, modified,
231 231 etc.).
232 232
233 233 See Pa.
234 234
235 235 EXIT STATUS
236 236 This section documents the command exit status for sections 1 and
237 237 1M. Historically, this information was described in DIAGNOSTICS, a
238 238 practise that is now discouraged.
239 239
240 240 See Ex.
241 241
242 242 EXAMPLES
243 243 Example usages. This often contains snippets of well-formed, well-
244 244 tested invocations. Make sure that examples work properly!
245 245
246 246 DIAGNOSTICS
247 247 Documents error and diagnostic messages displayed to the user or
248 248 sent to logs. Note that exit status and return values should be
249 249 documented in the EXIT STATUS and RETURN VALUES sections.
250 250
251 251 See Bl -diag.
252 252
253 253 ERRORS
254 254 Documents error handling in sections 2, 3, and 9.
255 255
256 256 See Er.
257 257
258 258 ARCHITECTURE
259 259 This section is usually absent, but will be present when the
260 260 interface is specific to one or more architectures.
261 261
262 262 CODE SET INDEPENDENCE
263 263 Indicates whether the interface operates correctly with various
264 264 different code sets. True independent code sets will support not
265 265 only ASCII and Extended UNIX Codesets (EUC), but also other multi-
266 266 byte encodings such as UTF-8 and GB2312.
267 267
268 268 Generally there will be some limitations that are fairly standard.
269 269 See standards(5) for more information about some of these. Most
270 270 interfaces should support at least UTF-8 in addition to ASCII.
271 271
272 272 INTERFACE STABILITY
273 273 Indicates the level of commitment to the interface. Interfaces can
274 274 be described with in the following ways:
275 275
276 276 Standard
277 277 Indicates that the interface is defined by one or more
278 278 standards bodies. Generally, changes to the interface will
279 279 be carefully managed to conform to the relevant standards.
280 280 These interfaces are generally the most suitable for use in
281 281 portable programs.
282 282
283 283 Committed
284 284 Indicates that the interface is intended to be preserved
285 285 for the long-haul, and will rarely, if ever change, and
286 286 never without notification (barring extraordinary and
287 287 extenuating circumstances). These interfaces are preferred
288 288 over other interfaces with the exeception of Standard
289 289 interfaces.
290 290
291 291 Uncommitted
292 292 Indicates that the interface may change. Generally,
293 293 changes to these interfaces should be infrequent, and some
294 294 effort will be made to address compatibility considerations
295 295 when changing or removing such interfaces. However, there
296 296 is no firm commitment to the preservation of the interface.
297 297 Most often this is applied to interfaces where operational
298 298 experience with the interface is still limited and some
299 299 need to change may be anticipated.
300 300
301 301 Consumers should expect to revalidate any Uncommitted
302 302 interfaces when crossing release boundaries. Products
303 303 intended for use on many releases or intended to support
304 304 compatibility with future releases should avoid these
305 305 interfaces.
306 306
307 307 Volatile
308 308 The interface can change at any time for any reason. Often
309 309 this relates to interfaces that are part of external
310 310 software components that are still evolving rapidly.
311 311 Consumers should not expect that the interface (either
312 312 binary or source level) will be unchanged from one release
313 313 to the next.
314 314
315 315 Not-an-Interface
316 316 Describes something that is specifically not intended for
317 317 programmatic consumption. For example, specific human-
318 318 readable output, or the layout of graphical items on a user
319 319 interface, may be described this way. Generally
320 320 programmatic alternatives to these will be available, and
321 321 should be used when programmatic consumption is needed.
322 322
323 323 Private
324 324 This is an internal interface. Generally these interfaces
325 325 should only be used within the project, and should not be
326 326 used by other programs or modules. The interface can and
327 327 will change without notice as the project needs, at any
328 328 time.
329 329
330 330 Most often, Private interfaces will lack any documentation
331 331 whatsoever, and generally any undocumented interface can be
332 332 assumed to be Private.
333 333
334 334 Obsolete
335 335 The interface is not intended for use in new projects or
336 336 programs, and may be removed at a future date. The
337 337 Obsolete word is a modifier that can be applied to other
338 338 commitment levels. For example an Obsolete Committed
339 339 interface is unlikely to be removed or changed, but
340 340 nonetheless new use is discouraged (perhaps a better newer
341 341 alternative is present).
342 342
343 343 MT-LEVEL
344 344 This section describes considerations for the interface when used
345 345 within programs that use multiple threads. More discussion of
346 346 these considerations is made in the MT-Level section of
347 347 attributes(5). The interface can be described in the following
348 348 ways.
349 349
350 350 Safe Indicates the interface is safe for use within multiple
351 351 threads. There may be additional caveats that apply, in
352 352 which case those will be described. Note that some
353 353 interfaces have semantics which may affect other threads,
354 354 but these should be an intrinsic part of the interface
355 355 rather than an unexpected side effect. For example,
356 356 closing a file in one thread will cause that file to be
357 357 closed in all threads.
358 358
359 359 Unsafe Indicates the interface is unsuitable for concurrent use
360 360 within multiple threads. A threaded application may still
361 361 make use of the interface, but will be required to provide
362 362 external synchronization means to ensure that only a single
363 363 thread calls the interface at a time.
364 364
365 365 MT-Safe
366 366 Indicates that the interface is not only safe for
367 367 concurrent use, but is designed for such use. For example,
368 368 a Safe interface may make use of a global lock to provide
369 369 safety, but at reduced internal concurrency, whereas an
370 370 MT-Safe interface will be designed to be efficient even
371 371 when used concurrently.
372 372
373 373 Async-Signal-Safe
374 374 Indicates that the library is safe for use within a signal
375 375 handler. An MT-Safe interface can be made
376 376 Async-Signal-Safe by ensuring that it blocks signals when
377 377 acquiring locks.
378 378
379 379 Safe with Exceptions
380 380 As for Safe but with specific exceptions noted.
381 381
382 382 MT-Safe with Exceptions
383 383 As for MT-Safe but with specific exceptions noted.
384 384
385 385 SECURITY
386 386 Documents any security precautions that operators should consider.
387 387
388 388 SEE ALSO
389 389 References other manuals with related topics. This section should
390 390 exist for most manuals. Cross-references should conventionally be
391 391 ordered first by section, then alphabetically (ignoring case).
392 392
393 393 References to other documentation concerning the topic of the
394 394 manual page, for example authoritative books or journal articles,
395 395 may also be provided in this section.
396 396
397 397 See Rs and Xr.
398 398
399 399 STANDARDS
400 400 References any standards implemented or used. If not adhering to
401 401 any standards, the HISTORY section should be used instead.
402 402
403 403 See St.
404 404
405 405 HISTORY
406 406 A brief history of the subject, including where it was first
407 407 implemented, and when it was ported to or reimplemented for the
408 408 operating system at hand.
409 409
410 410 AUTHORS
411 411 Credits to the person or persons who wrote the code and/or
412 412 documentation. Authors should generally be noted by both name and
413 413 email address.
414 414
415 415 See An.
416 416
417 417 CAVEATS
418 418 Common misuses and misunderstandings should be explained in this
419 419 section.
420 420
421 421 BUGS
422 422 Known bugs, limitations, and work-arounds should be described in
423 423 this section.
424 424
425 425 MACRO OVERVIEW
426 426 This overview is sorted such that macros of similar purpose are listed
427 427 together, to help find the best macro for any given purpose. Deprecated
428 428 macros are not included in the overview, but can be found below in the
429 429 alphabetical MACRO REFERENCE.
430 430
431 431 Document preamble and NAME section macros
432 432 Dd document date: month day, year
433 433 Dt document title: TITLE SECTION [arch]
434 434 Os operating system version: [system [version]]
435 435 Nm document name (one argument)
436 436 Nd document description (one line)
437 437
438 438 Sections and cross references
439 439 Sh section header (one line)
440 440 Ss subsection header (one line)
441 441 Sx internal cross reference to a section or subsection
442 442 Xr cross reference to another manual page: name section
443 443 Pp, Lp start a text paragraph (no arguments)
444 444
445 445 Displays and lists
446 446 Bd, Ed display block: -type [-offset width] [-compact]
447 447 D1 indented display (one line)
448 448 Dl indented literal display (one line)
449 449 Ql in-line literal display: `text'
450 450 Bl, El list block: -type [-width val] [-offset val] [-compact]
451 451 It list item (syntax depends on -type)
452 452 Ta table cell separator in Bl -column lists
453 453 Rs, %*, Re bibliographic block (references)
454 454
455 455 Spacing control
456 456 Pf prefix, no following horizontal space (one argument)
457 457 Ns roman font, no preceding horizontal space (no arguments)
458 458 Ap apostrophe without surrounding whitespace (no arguments)
459 459 Sm switch horizontal spacing mode: [on | off]
460 460 Bk, Ek keep block: -words
461 461
462 462 Semantic markup for command line utilities
463 463 Nm start a SYNOPSIS block with the name of a utility
464 464 Fl command line options (flags) (>=0 arguments)
465 465 Cm command modifier (>0 arguments)
466 466 Ar command arguments (>=0 arguments)
467 467 Op, Oo, Oc optional syntax elements (enclosure)
468 468 Ic internal or interactive command (>0 arguments)
469 469 Ev environmental variable (>0 arguments)
470 470 Pa file system path (>=0 arguments)
471 471
472 472 Semantic markup for function libraries
473 473 Lb function library (one argument)
474 474 In include file (one argument)
475 475 Fd other preprocessor directive (>0 arguments)
476 476 Ft function type (>0 arguments)
477 477 Fo, Fc function block: funcname
478 478 Fn function name: [functype] funcname [[argtype] argname]
479 479 Fa function argument (>0 arguments)
480 480 Vt variable type (>0 arguments)
481 481 Va variable name (>0 arguments)
482 482 Dv defined variable or preprocessor constant (>0 arguments)
483 483 Er error constant (>0 arguments)
484 484 Ev environmental variable (>0 arguments)
485 485
486 486 Various semantic markup
487 487 An author name (>0 arguments)
488 488 Lk hyperlink: uri [name]
489 489 Mt "mailto" hyperlink: address
490 490 Cd kernel configuration declaration (>0 arguments)
491 491 Ad memory address (>0 arguments)
492 492 Ms mathematical symbol (>0 arguments)
493 493
494 494 Physical markup
495 495 Em italic font or underline (emphasis) (>0 arguments)
496 496 Sy boldface font (symbolic) (>0 arguments)
497 497 Li typewriter font (literal) (>0 arguments)
498 498 No return to roman font (normal) (no arguments)
499 499 Bf, Ef font block: [-type | Em | Li | Sy]
500 500
501 501 Physical enclosures
502 502 Dq, Do, Dc enclose in typographic double quotes: "text"
503 503 Qq, Qo, Qc enclose in typewriter double quotes: "text"
504 504 Sq, So, Sc enclose in single quotes: `text'
505 505 Pq, Po, Pc enclose in parentheses: (text)
506 506 Bq, Bo, Bc enclose in square brackets: [text]
507 507 Brq, Bro, Brc enclose in curly braces: {text}
508 508 Aq, Ao, Ac enclose in angle brackets: <text>
509 509 Eo, Ec generic enclosure
510 510
511 511 Text production
512 512 Ex -std standard command exit values: [utility ...]
513 513 Rv -std standard function return values: [function ...]
514 514 St reference to a standards document (one argument)
515 515 At AT&T UNIX
516 516 Bx BSD
517 517 Bsx BSD/OS
518 518 Nx NetBSD
519 519 Fx FreeBSD
520 520 Ox OpenBSD
521 521 Dx DragonFly
522 522
523 523 MACRO REFERENCE
524 524 This section is a canonical reference of all macros, arranged
525 525 alphabetically. For the scoping of individual macros, see MACRO SYNTAX.
526 526
527 527 %A
528 528 Author name of an Rs block. Multiple authors should each be accorded
529 529 their own %A line. Author names should be ordered with full or
530 530 abbreviated forename(s) first, then full surname.
531 531
532 532 %B
533 533 Book title of an Rs block. This macro may also be used in a non-
534 534 bibliographic context when referring to book titles.
535 535
536 536 %C
537 537 Publication city or location of an Rs block.
538 538
539 539 %D
540 540 Publication date of an Rs block. Recommended formats of arguments are
541 541 month day, year or just year.
542 542
543 543 %I
544 544 Publisher or issuer name of an Rs block.
545 545
546 546 %J
547 547 Journal name of an Rs block.
548 548
549 549 %N
550 550 Issue number (usually for journals) of an Rs block.
551 551
552 552 %O
553 553 Optional information of an Rs block.
554 554
555 555 %P
556 556 Book or journal page number of an Rs block.
557 557
558 558 %Q
559 559 Institutional author (school, government, etc.) of an Rs block. Multiple
560 560 institutional authors should each be accorded their own %Q line.
561 561
562 562 %R
563 563 Technical report name of an Rs block.
564 564
565 565 %T
566 566 Article title of an Rs block. This macro may also be used in a non-
567 567 bibliographical context when referring to article titles.
568 568
569 569 %U
570 570 URI of reference document.
571 571
572 572 %V
573 573 Volume number of an Rs block.
574 574
575 575 Ac
576 576 Close an Ao block. Does not have any tail arguments.
577 577
578 578 Ad
579 579 Memory address. Do not use this for postal addresses.
580 580
581 581 Examples:
582 582 .Ad [0,$]
583 583 .Ad 0x00000000
584 584
585 585 An
586 586 Author name. Can be used both for the authors of the program, function,
587 587 or driver documented in the manual, or for the authors of the manual
588 588 itself. Requires either the name of an author or one of the following
589 589 arguments:
590 590
591 591 -split Start a new output line before each subsequent
592 592 invocation of An.
593 593 -nosplit The opposite of -split.
594 594
595 595 The default is -nosplit. The effect of selecting either of the -split
|
↓ open down ↓ |
595 lines elided |
↑ open up ↑ |
596 596 modes ends at the beginning of the AUTHORS section. In the AUTHORS
597 597 section, the default is -nosplit for the first author listing and -split
598 598 for all other author listings.
599 599
600 600 Examples:
601 601 .An -nosplit
602 602 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
603 603
604 604 Ao
605 605 Begin a block enclosed by angle brackets. Does not have any head
606 - arguments.
606 + arguments. This macro is almost never useful. See Aq for more details.
607 607
608 - Examples:
609 - .Fl -key= Ns Ao Ar val Ac
610 -
611 - See also Aq.
612 -
613 608 Ap
614 609 Inserts an apostrophe without any surrounding whitespace. This is
615 610 generally used as a grammatical device when referring to the verb form of
616 611 a function.
617 612
618 613 Examples:
619 614 .Fn execve Ap d
620 615
621 616 Aq
622 - Encloses its arguments in angle brackets.
617 + Encloses its arguments in angle brackets. The only important use case is
618 + for email addresses. See Mt for an example.
623 619
624 - Examples:
625 - .Fl -key= Ns Aq Ar val
620 + Occasionally, it is used for names of characters and keys, for example:
626 621
627 - Remarks: this macro is often abused for rendering URIs, which should
628 - instead use Lk or Mt, or to note pre-processor "#include" statements,
629 - which should use In.
622 + Press the
623 + .Aq escape
624 + key to ...
630 625
626 + For URIs, use Lk instead, and In for "#include" directives. Never wrap
627 + Ar in Aq.
628 +
629 + Since Aq usually renders with non-ASCII characters in non-ASCII output
630 + modes, do not use it where the ASCII characters `<' and `>' are required
631 + as syntax elements. Instead, use these characters directly in such
632 + cases, combining them with the macros Pf, Ns, or Eo as needed.
633 +
631 634 See also Ao.
632 635
633 636 Ar
634 637 Command arguments. If an argument is not provided, the string "file ..."
635 638 is used as a default.
636 639
637 640 Examples:
638 641 .Fl o Ar file
639 642 .Ar
640 643 .Ar arg1 , arg2 .
641 644
642 645 The arguments to the Ar macro are names and placeholders for command
643 646 arguments; for fixed strings to be passed verbatim as arguments, use Fl
644 647 or Cm.
645 648
646 649 At
647 650 Formats an AT&T UNIX version. Accepts one optional argument:
648 651
649 652 v[1-7] | 32v A version of AT&T UNIX.
650 653 III AT&T System III UNIX.
651 654 V | V.[1-4] A version of AT&T System V UNIX.
652 655
653 656 Note that these arguments do not begin with a hyphen.
654 657
655 658 Examples:
656 659 .At
657 660 .At III
658 661 .At V.1
659 662
660 663 See also Bsx, Bx, Dx, Fx, Nx, and Ox.
661 664
662 665 Bc
663 666 Close a Bo block. Does not have any tail arguments.
664 667
665 668 Bd
666 669 Begin a display block. Its syntax is as follows:
667 670
668 671 .Bd -type [-offset width] [-compact]
669 672
670 673 Display blocks are used to select a different indentation and
671 674 justification than the one used by the surrounding text. They may
672 675 contain both macro lines and text lines. By default, a display block is
673 676 preceded by a vertical space.
674 677
675 678 The type must be one of the following:
676 679
677 680 -centered Produce one output line from each input line, and
678 681 center-justify each line. Using this display type
679 682 is not recommended; many mdoc implementations render
680 683 it poorly.
681 684
682 685 -filled Change the positions of line breaks to fill each
683 686 line, and left- and right-justify the resulting
684 687 block.
685 688
686 689 -literal Produce one output line from each input line, and do
687 690 not justify the block at all. Preserve white space
688 691 as it appears in the input. Always use a constant-
689 692 width font. Use this for displaying source code.
690 693
691 694 -ragged Change the positions of line breaks to fill each
692 695 line, and left-justify the resulting block.
693 696
694 697 -unfilled The same as -literal, but using the same font as for
695 698 normal text, which is a variable width font if
696 699 supported by the output device.
697 700
698 701 The type must be provided first. Additional arguments may follow:
699 702
700 703 -offset width Indent the display by the width, which may be one of
701 704 the following:
702 705
703 706 One of the pre-defined strings indent, the width of
704 707 a standard indentation (six constant width
705 708 characters); indent-two, twice indent; left, which
706 709 has no effect; right, which justifies to the right
707 710 margin; or center, which aligns around an imagined
708 711 center axis.
709 712
710 713 A macro invocation, which selects a predefined width
711 714 associated with that macro. The most popular is the
712 715 imaginary macro Ds, which resolves to 6n.
713 716
714 717 A scaling width as described in mandoc_roff(5).
715 718
716 719 An arbitrary string, which indents by the length of
717 720 this string.
718 721
719 722 When the argument is missing, -offset is ignored.
720 723
721 724 -compact Do not assert vertical space before the display.
722 725
723 726 Examples:
724 727
725 728 .Bd -literal -offset indent -compact
726 729 Hello world.
727 730 .Ed
728 731
729 732 See also D1 and Dl.
730 733
731 734 Bf
732 735 Change the font mode for a scoped block of text. Its syntax is as
733 736 follows:
734 737
735 738 .Bf [-emphasis | -literal | -symbolic | Em | Li | Sy]
736 739
737 740 The -emphasis and Em argument are equivalent, as are -symbolic and Sy,
738 741 and -literal and Li. Without an argument, this macro does nothing. The
739 742 font mode continues until broken by a new font mode in a nested scope or
740 743 Ef is encountered.
741 744
742 745 See also Li, Ef, Em, and Sy.
743 746
744 747 Bk
745 748 For each macro, keep its output together on the same output line, until
746 749 the end of the macro or the end of the input line is reached, whichever
747 750 comes first. Line breaks in text lines are unaffected. The syntax is as
748 751 follows:
749 752
750 753 .Bk -words
751 754
752 755 The -words argument is required; additional arguments are ignored.
753 756
754 757 The following example will not break within each Op macro line:
755 758
756 759 .Bk -words
757 760 .Op Fl f Ar flags
758 761 .Op Fl o Ar output
759 762 .Ek
760 763
761 764 Be careful in using over-long lines within a keep block! Doing so will
762 765 clobber the right margin.
763 766
764 767 Bl
765 768 Begin a list. Lists consist of items specified using the It macro,
766 769 containing a head or a body or both. The list syntax is as follows:
767 770
768 771 .Bl -type [-width val] [-offset val] [-compact] [HEAD ...]
769 772
770 773 The list type is mandatory and must be specified first. The -width and
771 774 -offset arguments accept macro names as described for Bd -offset, scaling
772 775 widths as described in mandoc_roff(5), or use the length of the given
773 776 string. The -offset is a global indentation for the whole list,
774 777 affecting both item heads and bodies. For those list types supporting
775 778 it, the -width argument requests an additional indentation of item
776 779 bodies, to be added to the -offset. Unless the -compact argument is
777 780 specified, list entries are separated by vertical space.
778 781
779 782 A list must specify one of the following list types:
780 783
781 784 -bullet No item heads can be specified, but a bullet will be
782 785 printed at the head of each item. Item bodies start
783 786 on the same output line as the bullet and are
784 787 indented according to the -width argument.
785 788
786 789 -column A columnated list. The -width argument has no
787 790 effect; instead, the string length of each argument
788 791 specifies the width of one column. If the first line
789 792 of the body of a -column list is not an It macro
790 793 line, It contexts spanning one input line each are
791 794 implied until an It macro line is encountered, at
792 795 which point items start being interpreted as
793 796 described in the It documentation.
794 797
795 798 -dash Like -bullet, except that dashes are used in place of
796 799 bullets.
797 800
798 801 -diag Like -inset, except that item heads are not parsed
799 802 for macro invocations. Most often used in the
800 803 DIAGNOSTICS section with error constants in the item
801 804 heads.
802 805
803 806 -enum A numbered list. No item heads can be specified.
804 807 Formatted like -bullet, except that cardinal numbers
805 808 are used in place of bullets, starting at 1.
806 809
807 810 -hang Like -tag, except that the first lines of item bodies
808 811 are not indented, but follow the item heads like in
809 812 -inset lists.
810 813
811 814 -hyphen Synonym for -dash.
812 815
813 816 -inset Item bodies follow items heads on the same line,
814 817 using normal inter-word spacing. Bodies are not
815 818 indented, and the -width argument is ignored.
816 819
817 820 -item No item heads can be specified, and none are printed.
818 821 Bodies are not indented, and the -width argument is
819 822 ignored.
820 823
821 824 -ohang Item bodies start on the line following item heads
822 825 and are not indented. The -width argument is
823 826 ignored.
824 827
825 828 -tag Item bodies are indented according to the -width
826 829 argument. When an item head fits inside the
827 830 indentation, the item body follows this head on the
828 831 same output line. Otherwise, the body starts on the
829 832 output line following the head.
830 833
831 834 Lists may be nested within lists and displays. Nesting of -column and
832 835 -enum lists may not be portable.
833 836
834 837 See also El and It.
835 838
836 839 Bo
837 840 Begin a block enclosed by square brackets. Does not have any head
838 841 arguments.
839 842
840 843 Examples:
841 844 .Bo 1 ,
842 845 .Dv BUFSIZ Bc
843 846
844 847 See also Bq.
845 848
846 849 Bq
847 850 Encloses its arguments in square brackets.
848 851
849 852 Examples:
850 853 .Bq 1, Dv BUFSIZ
851 854
852 855 Remarks: this macro is sometimes abused to emulate optional arguments for
853 856 commands; the correct macros to use for this purpose are Op, Oo, and Oc.
854 857
855 858 See also Bo.
856 859
857 860 Brc
858 861 Close a Bro block. Does not have any tail arguments.
859 862
860 863 Bro
861 864 Begin a block enclosed by curly braces. Does not have any head
862 865 arguments.
863 866
864 867 Examples:
865 868 .Bro 1 , ... ,
866 869 .Va n Brc
867 870
868 871 See also Brq.
869 872
870 873 Brq
871 874 Encloses its arguments in curly braces.
872 875
873 876 Examples:
874 877 .Brq 1, ..., Va n
875 878
876 879 See also Bro.
877 880
878 881 Bsx
879 882 Format the BSD/OS version provided as an argument, or a default value if
880 883 no argument is provided.
881 884
882 885 Examples:
883 886 .Bsx 1.0
884 887 .Bsx
885 888
886 889 See also At, Bx, Dx, Fx, Nx, and Ox.
887 890
888 891 Bt
889 892 Supported only for compatibility, do not use this in new manuals. Prints
890 893 "is currently in beta test."
891 894
892 895 Bx
893 896 Format the BSD version provided as an argument, or a default value if no
894 897 argument is provided.
895 898
896 899 Examples:
897 900 .Bx 4.3 Tahoe
898 901 .Bx 4.4
899 902 .Bx
900 903
901 904 See also At, Bsx, Dx, Fx, Nx, and Ox.
902 905
903 906 Cd
904 907 Kernel configuration declaration. It is found in pages for BSD and not
905 908 used here.
906 909
907 910 Examples:
908 911 .Cd device le0 at scode?
909 912
910 913 Remarks: this macro is commonly abused by using quoted literals to retain
911 914 whitespace and align consecutive Cd declarations. This practise is
912 915 discouraged.
913 916
914 917 Cm
915 918 Command modifiers. Typically used for fixed strings passed as arguments,
916 919 unless Fl is more appropriate. Also useful when specifying configuration
917 920 options or keys.
918 921
919 922 Examples:
920 923 .Nm mt Fl f Ar device Cm rewind
921 924 .Nm ps Fl o Cm pid , Ns Cm command
922 925 .Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2
923 926 .Cm IdentityFile Pa ~/.ssh/id_rsa
924 927 .Cm LogLevel Dv DEBUG
925 928
926 929 D1
927 930 One-line indented display. This is formatted by the default rules and is
928 931 useful for simple indented statements. It is followed by a newline.
929 932
930 933 Examples:
931 934 .D1 Fl abcdefgh
932 935
933 936 See also Bd and Dl.
934 937
935 938 Db
936 939 This macro is obsolete. No replacement is needed. It is ignored by
937 940 mandoc(1) and groff including its arguments. It was formerly used to
938 941 toggle a debugging mode.
|
↓ open down ↓ |
298 lines elided |
↑ open up ↑ |
939 942
940 943 Dc
941 944 Close a Do block. Does not have any tail arguments.
942 945
943 946 Dd
944 947 Document date for display in the page footer. This is the mandatory
945 948 first macro of any mdoc manual. Its syntax is as follows:
946 949
947 950 .Dd month day, year
948 951
949 - The month is the full English month name, the day is an optionally zero-
950 - padded numeral, and the year is the full four-digit year.
952 + The month is the full English month name, the day is an integer number,
953 + and the year is the full four-digit year.
951 954
952 955 Other arguments are not portable; the mandoc(1) utility handles them as
953 956 follows:
954 957 - To have the date automatically filled in by the OpenBSD version of
955 958 cvs(1), the special string "$Mdocdate$" can be given as an
956 959 argument.
957 960 - The traditional, purely numeric man(5) format year-month-day is
958 961 accepted, too.
959 962 - If a date string cannot be parsed, it is used verbatim.
960 963 - If no date string is given, the current date is used.
961 964
962 965 Examples:
963 966 .Dd $Mdocdate$
964 - .Dd $Mdocdate: July 21 2007$
965 - .Dd July 21, 2007
967 + .Dd $Mdocdate: July 2 2018$
968 + .Dd July 2, 2018
966 969
967 970 See also Dt and Os.
968 971
969 972 Dl
970 973 One-line indented display. This is formatted as literal text and is
971 974 useful for commands and invocations. It is followed by a newline.
972 975
973 976 Examples:
974 977 .Dl % mandoc mdoc.5 \(ba less
975 978
976 979 See also Ql, Bd -literal, and D1.
977 980
978 981 Do
979 982 Begin a block enclosed by double quotes. Does not have any head
980 983 arguments.
981 984
982 985 Examples:
983 986 .Do
984 987 April is the cruellest month
985 988 .Dc
986 989 \(em T.S. Eliot
987 990
988 991 See also Dq.
989 992
990 993 Dq
991 994 Encloses its arguments in "typographic" double-quotes.
992 995
993 996 Examples:
994 997 .Dq April is the cruellest month
995 998 \(em T.S. Eliot
996 999
997 1000 See also Qq, Sq, and Do.
998 1001
999 1002 Dt
1000 1003 Document title for display in the page header. This is the mandatory
1001 1004 second macro of any mdoc file. Its syntax is as follows:
1002 1005
1003 1006 .Dt TITLE section [arch]
1004 1007
1005 1008 Its arguments are as follows:
1006 1009
1007 1010 TITLE The document's title (name), defaulting to "UNTITLED" if
1008 1011 unspecified. To achieve a uniform appearance of page header
1009 1012 lines, it should by convention be all caps.
1010 1013
1011 1014 SECTION The manual section. It should correspond to the manual's
1012 1015 filename suffix and defaults to the empty string if
1013 1016 unspecified. This field is optional. To achieve a uniform
1014 1017 appearance of page header lines, it should by convention be
1015 1018 all caps.
1016 1019
1017 1020 arch This specifies the machine architecture a manual page applies
1018 1021 to, where relevant.
1019 1022
1020 1023 Dv
1021 1024 Defined variables such as preprocessor constants, constant symbols,
1022 1025 enumeration values, and so on.
1023 1026
1024 1027 Examples:
1025 1028 .Dv NULL
1026 1029 .Dv BUFSIZ
1027 1030 .Dv STDOUT_FILENO
1028 1031
1029 1032 See also Er and Ev for special-purpose constants, Va for variable
1030 1033 symbols, and Fd for listing preprocessor variable definitions in the
1031 1034 SYNOPSIS.
1032 1035
1033 1036 Dx
1034 1037 Format the DragonFly version provided as an argument, or a default value
1035 1038 if no argument is provided.
1036 1039
1037 1040 Examples:
1038 1041 .Dx 2.4.1
1039 1042 .Dx
1040 1043
1041 1044 See also At, Bsx, Bx, Fx, Nx, and Ox.
1042 1045
1043 1046 Ec
1044 1047 Close a scope started by Eo. Its syntax is as follows:
1045 1048
1046 1049 .Ec [TERM]
1047 1050
1048 1051 The TERM argument is used as the enclosure tail, for example, specifying
1049 1052 \(rq will emulate Dc.
1050 1053
1051 1054 Ed
1052 1055 End a display context started by Bd.
1053 1056
1054 1057 Ef
1055 1058 End a font mode context started by Bf.
1056 1059
1057 1060 Ek
1058 1061 End a keep context started by Bk.
1059 1062
1060 1063 El
1061 1064 End a list context started by Bl.
1062 1065
1063 1066 See also Bl and It.
1064 1067
1065 1068 Em
1066 1069 Request an italic font. If the output device does not provide that,
1067 1070 underline.
1068 1071
1069 1072 This is most often used for stress emphasis (not to be confused with
1070 1073 importance, see Sy). In the rare cases where none of the semantic markup
1071 1074 macros fit, it can also be used for technical terms and placeholders,
1072 1075 except that for syntax elements, Sy and Ar are preferred, respectively.
1073 1076
1074 1077 Examples:
1075 1078 Selected lines are those
1076 1079 .Em not
1077 1080 matching any of the specified patterns.
1078 1081 Some of the functions use a
1079 1082 .Em hold space
1080 1083 to save the pattern space for subsequent retrieval.
1081 1084
1082 1085 See also Bf, Li, No, and Sy.
1083 1086
1084 1087 En
1085 1088 This macro is obsolete. Use Eo or any of the other enclosure macros.
1086 1089
1087 1090 It encloses its argument in the delimiters specified by the last Es
1088 1091 macro.
1089 1092
1090 1093 Eo
1091 1094 An arbitrary enclosure. Its syntax is as follows:
1092 1095
1093 1096 .Eo [TERM]
1094 1097
1095 1098 The TERM argument is used as the enclosure head, for example, specifying
1096 1099 \(lq will emulate Do.
1097 1100
1098 1101 Er
1099 1102 Error constants for definitions of the errno libc global variable. This
1100 1103 is most often used in section 2 and 3 manual pages.
1101 1104
1102 1105 Examples:
1103 1106 .Er EPERM
1104 1107 .Er ENOENT
1105 1108
1106 1109 See also Dv for general constants.
1107 1110
1108 1111 Es
1109 1112 This macro is obsolete. Use Eo or any of the other enclosure macros.
1110 1113
1111 1114 It takes two arguments, defining the delimiters to be used by subsequent
1112 1115 En macros.
1113 1116
1114 1117 Ev
1115 1118 Environmental variables such as those specified in environ(5).
1116 1119
1117 1120 Examples:
1118 1121 .Ev DISPLAY
1119 1122 .Ev PATH
1120 1123
1121 1124 See also Dv for general constants.
1122 1125
1123 1126 Ex
1124 1127 Insert a standard sentence regarding command exit values of 0 on success
1125 1128 and >0 on failure. This is most often used in section 1 and 1M manual
1126 1129 pages. Its syntax is as follows:
1127 1130
1128 1131 .Ex -std [utility ...]
1129 1132
1130 1133 If utility is not specified, the document's name set by Nm is used.
1131 1134 Multiple utility arguments are treated as separate utilities.
1132 1135
1133 1136 See also Rv.
1134 1137
1135 1138 Fa
1136 1139 Function argument or parameter. Its syntax is as follows:
1137 1140
1138 1141 .Fa "[argtype] [argname]" ...
1139 1142
1140 1143 Each argument may be a name and a type (recommended for the SYNOPSIS
1141 1144 section), a name alone (for function invocations), or a type alone (for
1142 1145 function prototypes). If both a type and a name are given or if the type
1143 1146 consists of multiple words, all words belonging to the same function
1144 1147 argument have to be given in a single argument to the Fa macro.
1145 1148
1146 1149 This macro is also used to specify the field name of a structure.
1147 1150
1148 1151 Most often, the Fa macro is used in the SYNOPSIS within Fo blocks when
1149 1152 documenting multi-line function prototypes. If invoked with multiple
1150 1153 arguments, the arguments are separated by a comma. Furthermore, if the
1151 1154 following macro is another Fa, the last argument will also have a
1152 1155 trailing comma.
1153 1156
1154 1157 Examples:
1155 1158 .Fa "const char *p"
1156 1159 .Fa "int a" "int b" "int c"
1157 1160 .Fa "char *" size_t
1158 1161
1159 1162 See also Fo.
1160 1163
1161 1164 Fc
1162 1165 End a function context started by Fo.
1163 1166
1164 1167 Fd
1165 1168 Preprocessor directive, in particular for listing it in the SYNOPSIS.
1166 1169 Historically, it was also used to document include files. The latter
1167 1170 usage has been deprecated in favour of In.
1168 1171
1169 1172 Its syntax is as follows:
1170 1173
1171 1174 .Fd #directive [argument ...]
1172 1175
1173 1176 Examples:
1174 1177 .Fd #define sa_handler __sigaction_u.__sa_handler
1175 1178 .Fd #define SIO_MAXNFDS
1176 1179 .Fd #ifdef FS_DEBUG
1177 1180 .Ft void
1178 1181 .Fn dbg_open "const char *"
1179 1182 .Fd #endif
1180 1183
1181 1184 See also MANUAL STRUCTURE, In, and Dv.
1182 1185
1183 1186 Fl
1184 1187 Command-line flag or option. Used when listing arguments to command-line
1185 1188 utilities. Prints a fixed-width hyphen `-' directly followed by each
1186 1189 argument. If no arguments are provided, a hyphen is printed followed by
1187 1190 a space. If the argument is a macro, a hyphen is prefixed to the
1188 1191 subsequent macro output.
1189 1192
1190 1193 Examples:
1191 1194 .Fl R Op Fl H | L | P
1192 1195 .Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux
1193 1196 .Fl type Cm d Fl name Pa CVS
1194 1197 .Fl Ar signal_number
1195 1198 .Fl o Fl
1196 1199
1197 1200 See also Cm.
1198 1201
1199 1202 Fn
1200 1203 A function name. Its syntax is as follows:
1201 1204
1202 1205 .Fn [functype] funcname [[argtype] argname]
1203 1206
1204 1207 Function arguments are surrounded in parenthesis and are delimited by
1205 1208 commas. If no arguments are specified, blank parenthesis are output. In
1206 1209 the SYNOPSIS section, this macro starts a new output line, and a blank
1207 1210 line is automatically inserted between function definitions.
1208 1211
1209 1212 Examples:
1210 1213 .Fn "int funcname" "int arg0" "int arg1"
1211 1214 .Fn funcname "int arg0"
1212 1215 .Fn funcname arg0
1213 1216
1214 1217 .Ft functype
1215 1218 .Fn funcname
1216 1219
1217 1220 When referring to a function documented in another manual page, use Xr
1218 1221 instead. See also MANUAL STRUCTURE, Fo, and Ft.
1219 1222
1220 1223 Fo
1221 1224 Begin a function block. This is a multi-line version of Fn. Its syntax
1222 1225 is as follows:
1223 1226
1224 1227 .Fo funcname
1225 1228
1226 1229 Invocations usually occur in the following context:
1227 1230
1228 1231 .Ft functype
1229 1232 .Fo funcname
1230 1233 .Fa "argtype argname"
1231 1234 ...
1232 1235 .Fc
1233 1236
1234 1237 A Fo scope is closed by Fc.
1235 1238
1236 1239 See also MANUAL STRUCTURE, Fa, Fc, and Ft.
1237 1240
1238 1241 Fr
1239 1242 This macro is obsolete. No replacement markup is needed.
1240 1243
1241 1244 It was used to show numerical function return values in an italic font.
1242 1245
1243 1246 Ft
1244 1247 A function type. Its syntax is as follows:
1245 1248
1246 1249 .Ft functype
1247 1250
1248 1251 In the SYNOPSIS section, a new output line is started after this macro.
1249 1252
1250 1253 Examples:
1251 1254 .Ft int
1252 1255 .Ft functype
1253 1256 .Fn funcname
1254 1257
1255 1258 See also MANUAL STRUCTURE, Fn, and Fo.
1256 1259
1257 1260 Fx
1258 1261 Format the FreeBSD version provided as an argument, or a default value if
1259 1262 no argument is provided.
1260 1263
1261 1264 Examples:
1262 1265 .Fx 7.1
1263 1266 .Fx
1264 1267
1265 1268 See also At, Bsx, Bx, Dx, Nx, and Ox.
1266 1269
1267 1270 Hf
1268 1271 This macro is not implemented in mandoc(1).
1269 1272
1270 1273 It was used to include the contents of a (header) file literally. The
1271 1274 syntax was:
1272 1275
1273 1276 .Hf filename
1274 1277
1275 1278 Ic
1276 1279 Designate an internal or interactive command. This is similar to Cm but
1277 1280 used for instructions rather than values.
1278 1281
1279 1282 Examples:
1280 1283 .Ic :wq
1281 1284 .Ic hash
1282 1285 .Ic alias
1283 1286
1284 1287 Note that using Bd -literal or D1 is preferred for displaying code; the
1285 1288 Ic macro is used when referring to specific instructions.
1286 1289
1287 1290 In
1288 1291 The name of an include file. This macro is most often used in section 2,
1289 1292 3, and 9 manual pages.
1290 1293
1291 1294 When invoked as the first macro on an input line in the SYNOPSIS section,
1292 1295 the argument is displayed in angle brackets and preceded by "#include",
1293 1296 and a blank line is inserted in front if there is a preceding function
1294 1297 declaration. In other sections, it only encloses its argument in angle
1295 1298 brackets and causes no line break.
1296 1299
1297 1300 Examples:
1298 1301 .In sys/types.h
1299 1302
1300 1303 See also MANUAL STRUCTURE.
1301 1304
1302 1305 It
1303 1306 A list item. The syntax of this macro depends on the list type.
1304 1307
1305 1308 Lists of type -hang, -ohang, -inset, and -diag have the following syntax:
1306 1309
1307 1310 .It args
1308 1311
1309 1312 Lists of type -bullet, -dash, -enum, -hyphen and -item have the following
1310 1313 syntax:
1311 1314
1312 1315 .It
1313 1316
1314 1317 with subsequent lines interpreted within the scope of the It until either
1315 1318 a closing El or another It.
1316 1319
1317 1320 The -tag list has the following syntax:
1318 1321
1319 1322 .It [args]
1320 1323
1321 1324 Subsequent lines are interpreted as with -bullet and family. The line
1322 1325 arguments correspond to the list's left-hand side; body arguments
1323 1326 correspond to the list's contents.
1324 1327
1325 1328 The -column list is the most complicated. Its syntax is as follows:
1326 1329
1327 1330 .It cell [Ta cell ...]
1328 1331 .It cell [<TAB> cell ...]
1329 1332
1330 1333 The arguments consist of one or more lines of text and macros
1331 1334 representing a complete table line. Cells within the line are delimited
1332 1335 by the special Ta block macro or by literal tab characters.
1333 1336
1334 1337 Using literal tabs is strongly discouraged because they are very hard to
1335 1338 use correctly and mdoc code using them is very hard to read. In
1336 1339 particular, a blank character is syntactically significant before and
1337 1340 after the literal tab character. If a word precedes or follows the tab
1338 1341 without an intervening blank, that word is never interpreted as a macro
1339 1342 call, but always output literally.
1340 1343
1341 1344 The tab cell delimiter may only be used within the It line itself; on
1342 1345 following lines, only the Ta macro can be used to delimit cells, and
1343 1346 portability requires that Ta is called by other macros: some parsers do
1344 1347 not recognize it when it appears as the first macro on a line.
1345 1348
1346 1349 Note that quoted strings may span tab-delimited cells on an It line. For
1347 1350 example,
1348 1351
1349 1352 .It "col1 , <TAB> col2 ," ;
1350 1353
1351 1354 will preserve the whitespace before both commas, but not the whitespace
1352 1355 before the semicolon.
1353 1356
1354 1357 See also Bl.
1355 1358
1356 1359 Lb
1357 1360 Specify a library. The syntax is as follows:
1358 1361
1359 1362 .Lb library
1360 1363
1361 1364 The library parameter may be a system library, such as libz or libpam, in
1362 1365 which case a small library description is printed next to the linker
1363 1366 invocation; or a custom library, in which case the library name is
1364 1367 printed in quotes. This is most commonly used in the SYNOPSIS section as
1365 1368 described in MANUAL STRUCTURE.
1366 1369
1367 1370 Examples:
1368 1371 .Lb libz
1369 1372 .Lb mdoc
1370 1373
1371 1374 Li
1372 1375 Denotes text that should be in a literal font mode. Note that this is a
1373 1376 presentation term and should not be used for stylistically decorating
1374 1377 technical terms.
1375 1378
1376 1379 On terminal output devices, this is often indistinguishable from normal
1377 1380 text.
1378 1381
1379 1382 See also Bf, Em, No, and Sy.
1380 1383
1381 1384 Lk
1382 1385 Format a hyperlink. Its syntax is as follows:
1383 1386
1384 1387 .Lk uri [name]
1385 1388
1386 1389 Examples:
1387 1390 .Lk http://bsd.lv "The BSD.lv Project"
1388 1391 .Lk http://bsd.lv
1389 1392
1390 1393 See also Mt.
1391 1394
1392 1395 Lp
1393 1396 Synonym for Pp.
1394 1397
1395 1398 Ms
1396 1399 Display a mathematical symbol. Its syntax is as follows:
1397 1400
1398 1401 .Ms symbol
1399 1402
1400 1403 Examples:
1401 1404 .Ms sigma
1402 1405 .Ms aleph
1403 1406
1404 1407 Mt
1405 1408 Format a "mailto:" hyperlink. Its syntax is as follows:
1406 1409
1407 1410 .Mt address
1408 1411
1409 1412 Examples:
1410 1413 .Mt discuss@manpages.bsd.lv
1411 1414 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1412 1415
1413 1416 Nd
1414 1417 A one line description of the manual's content. This is the mandatory
1415 1418 last macro of the NAME section and not appropriate for other sections.
1416 1419
1417 1420 Examples:
1418 1421 .Nd mdoc language reference
1419 1422 .Nd format and display UNIX manuals
1420 1423
1421 1424 The Nd macro technically accepts child macros and terminates with a
1422 1425 subsequent Sh invocation. Do not assume this behaviour: some whatis(1)
1423 1426 database generators are not smart enough to parse more than the line
1424 1427 arguments and will display macros verbatim.
1425 1428
1426 1429 See also Nm.
1427 1430
1428 1431 Nm
1429 1432 The name of the manual page, or -- in particular in section 1 pages -- of
1430 1433 an additional command or feature documented in the manual page. When
1431 1434 first invoked, the Nm macro expects a single argument, the name of the
1432 1435 manual page. Usually, the first invocation happens in the NAME section
1433 1436 of the page. The specified name will be remembered and used whenever the
1434 1437 macro is called again without arguments later in the page. The Nm macro
1435 1438 uses Block full-implicit semantics when invoked as the first macro on an
1436 1439 input line in the SYNOPSIS section; otherwise, it uses ordinary In-line
1437 1440 semantics.
1438 1441
1439 1442 Examples:
1440 1443
1441 1444 .Sh SYNOPSIS
1442 1445 .Nm cat
1443 1446 .Op Fl benstuv
1444 1447 .Op Ar
1445 1448
1446 1449 In the SYNOPSIS of section 2, 3 and 9 manual pages, use the Fn macro
1447 1450 rather than Nm to mark up the name of the manual page.
1448 1451
1449 1452 No
1450 1453 Normal text. Closes the scope of any preceding in-line macro. When used
1451 1454 after physical formatting macros like Em or Sy, switches back to the
1452 1455 standard font face and weight. Can also be used to embed plain text
1453 1456 strings in macro lines using semantic annotation macros.
1454 1457
1455 1458 Examples:
1456 1459 .Em italic , Sy bold , No and roman
1457 1460
1458 1461 .Sm off
1459 1462 .Cm :C No / Ar pattern No / Ar replacement No /
1460 1463 .Sm on
1461 1464
1462 1465 See also Em, Li, and Sy.
1463 1466
1464 1467 Ns
1465 1468 Suppress a space between the output of the preceding macro and the
1466 1469 following text or macro. Following invocation, input is interpreted as
1467 1470 normal text just like after an No macro.
1468 1471
1469 1472 This has no effect when invoked at the start of a macro line.
1470 1473
1471 1474 Examples:
1472 1475 .Ar name Ns = Ns Ar value
1473 1476 .Cm :M Ns Ar pattern
1474 1477 .Fl o Ns Ar output
1475 1478
1476 1479 See also No and Sm.
1477 1480
1478 1481 Nx
1479 1482 Format the NetBSD version provided as an argument, or a default value if
1480 1483 no argument is provided.
1481 1484
1482 1485 Examples:
1483 1486 .Nx 5.01
1484 1487 .Nx
1485 1488
1486 1489 See also At, Bsx, Bx, Dx, Fx, and Ox.
1487 1490
1488 1491 Oc
1489 1492 Close multi-line Oo context.
1490 1493
1491 1494 Oo
1492 1495 Multi-line version of Op.
1493 1496
1494 1497 Examples:
1495 1498 .Oo
1496 1499 .Op Fl flag Ns Ar value
1497 1500 .Oc
1498 1501
1499 1502 Op
1500 1503 Optional part of a command line. Prints the argument(s) in brackets.
1501 1504 This is most often used in the SYNOPSIS section of section 1 and 1M
1502 1505 manual pages.
1503 1506
1504 1507 Examples:
1505 1508 .Op Fl a Ar b
1506 1509 .Op Ar a | b
1507 1510
1508 1511 See also Oo.
1509 1512
1510 1513 Os
1511 1514 Operating system version for display in the page footer. This is the
1512 1515 mandatory third macro of any mdoc file. Its syntax is as follows:
1513 1516
1514 1517 .Os [system [version]]
1515 1518
1516 1519 The optional system parameter specifies the relevant operating system or
1517 1520 environment. It is suggested to leave it unspecified, in which case
1518 1521 mandoc(1) uses its -Ios argument or, if that isn't specified either,
1519 1522 sysname and release as returned by uname(3).
1520 1523
1521 1524 Examples:
1522 1525 .Os
1523 1526 .Os KTH/CSC/TCS
1524 1527 .Os BSD 4.3
1525 1528
1526 1529 See also Dd and Dt.
1527 1530
1528 1531 Ot
1529 1532 This macro is obsolete. Use Ft instead; with mandoc(1), both have the
1530 1533 same effect.
1531 1534
1532 1535 Historical mdoc packages described it as "old function type (FORTRAN)".
1533 1536
1534 1537 Ox
1535 1538 Format the OpenBSD version provided as an argument, or a default value if
1536 1539 no argument is provided.
1537 1540
1538 1541 Examples:
1539 1542 .Ox 4.5
1540 1543 .Ox
1541 1544
1542 1545 See also At, Bsx, Bx, Dx, Fx, and Nx.
1543 1546
1544 1547 Pa
1545 1548 An absolute or relative file system path, or a file or directory name.
1546 1549 If an argument is not provided, the character `~' is used as a default.
1547 1550
1548 1551 Examples:
1549 1552 .Pa /usr/bin/mandoc
1550 1553 .Pa /usr/share/man/man5/mdoc.5
1551 1554
1552 1555 See also Lk.
1553 1556
1554 1557 Pc
1555 1558 Close parenthesised context opened by Po.
1556 1559
1557 1560 Pf
1558 1561 Removes the space between its argument and the following macro. Its
1559 1562 syntax is as follows:
1560 1563
1561 1564 .Pf prefix macro arguments ...
1562 1565
1563 1566 This is equivalent to:
1564 1567
1565 1568 .No \&prefix Ns macro arguments ...
1566 1569
1567 1570 The prefix argument is not parsed for macro names or delimiters, but used
1568 1571 verbatim as if it were escaped.
1569 1572
1570 1573 Examples:
1571 1574 .Pf $ Ar variable_name
1572 1575 .Pf . Ar macro_name
1573 1576 .Pf 0x Ar hex_digits
1574 1577
1575 1578 See also Ns and Sm.
1576 1579
1577 1580 Po
1578 1581 Multi-line version of Pq.
1579 1582
1580 1583 Pp
1581 1584 Break a paragraph. This will assert vertical space between prior and
1582 1585 subsequent macros and/or text.
1583 1586
1584 1587 Paragraph breaks are not needed before or after Sh or Ss macros or before
1585 1588 displays (Bd) or lists (Bl) unless the -compact flag is given.
1586 1589
1587 1590 Pq
1588 1591 Parenthesised enclosure.
1589 1592
1590 1593 See also Po.
1591 1594
1592 1595 Qc
1593 1596 Close quoted context opened by Qo.
1594 1597
1595 1598 Ql
1596 1599 In-line literal display. This can for example be used for complete
1597 1600 command invocations and for multi-word code fragments when more specific
1598 1601 markup is not appropriate and an indented display is not desired. While
1599 1602 mandoc(1) always encloses the arguments in single quotes, other
1600 1603 formatters usually omit the quotes on non-terminal output devices when
1601 1604 the arguments have three or more characters.
1602 1605
1603 1606 See also Dl and Bd -literal.
1604 1607
1605 1608 Qo
1606 1609 Multi-line version of Qq.
1607 1610
1608 1611 Qq
1609 1612 Encloses its arguments in "typewriter" double-quotes. Consider using Dq.
1610 1613
1611 1614 See also Dq, Sq, and Qo.
1612 1615
1613 1616 Re
1614 1617 Close an Rs block. Does not have any tail arguments.
1615 1618
1616 1619 Rs
1617 1620 Begin a bibliographic ("reference") block. Does not have any head
1618 1621 arguments. The block macro may only contain %A, %B, %C, %D, %I, %J, %N,
1619 1622 %O, %P, %Q, %R, %T, %U, and %V child macros (at least one must be
1620 1623 specified).
1621 1624
1622 1625 Examples:
1623 1626 .Rs
1624 1627 .%A J. E. Hopcroft
1625 1628 .%A J. D. Ullman
1626 1629 .%B Introduction to Automata Theory, Languages, and Computation
1627 1630 .%I Addison-Wesley
1628 1631 .%C Reading, Massachusetts
1629 1632 .%D 1979
1630 1633 .Re
1631 1634
1632 1635 If an Rs block is used within a SEE ALSO section, a vertical space is
1633 1636 asserted before the rendered output, else the block continues on the
1634 1637 current line.
1635 1638
1636 1639 Rv
1637 1640 Insert a standard sentence regarding a function call's return value of 0
1638 1641 on success and -1 on error, with the errno libc global variable set on
1639 1642 error. Its syntax is as follows:
1640 1643
1641 1644 .Rv -std [function ...]
1642 1645
1643 1646 If function is not specified, the document's name set by Nm is used.
1644 1647 Multiple function arguments are treated as separate functions.
1645 1648
1646 1649 See also Ex.
1647 1650
1648 1651 Sc
1649 1652 Close single-quoted context opened by So.
1650 1653
1651 1654 Sh
1652 1655 Begin a new section. For a list of conventional manual sections, see
1653 1656 MANUAL STRUCTURE. These sections should be used unless it's absolutely
1654 1657 necessary that custom sections be used.
1655 1658
1656 1659 Section names should be unique so that they may be keyed by Sx. Although
1657 1660 this macro is parsed, it should not consist of child node or it may not
1658 1661 be linked with Sx.
1659 1662
1660 1663 See also Pp, Ss, and Sx.
1661 1664
1662 1665 Sm
1663 1666 Switches the spacing mode for output generated from macros. Its syntax
1664 1667 is as follows:
1665 1668
1666 1669 .Sm [on | off]
1667 1670
1668 1671 By default, spacing is on. When switched off, no white space is inserted
1669 1672 between macro arguments and between the output generated from adjacent
1670 1673 macros, but text lines still get normal spacing between words and
1671 1674 sentences.
1672 1675
1673 1676 When called without an argument, the Sm macro toggles the spacing mode.
1674 1677 Using this is not recommended because it makes the code harder to read.
1675 1678
1676 1679 So
1677 1680 Multi-line version of Sq.
1678 1681
1679 1682 Sq
1680 1683 Encloses its arguments in `typewriter' single-quotes.
1681 1684
1682 1685 See also Dq, Qq, and So.
1683 1686
1684 1687 Ss
1685 1688 Begin a new subsection. Unlike with Sh, there is no convention for the
1686 1689 naming of subsections. Except DESCRIPTION, the conventional sections
1687 1690 described in MANUAL STRUCTURE rarely have subsections.
1688 1691
1689 1692 Sub-section names should be unique so that they may be keyed by Sx.
1690 1693 Although this macro is parsed, it should not consist of child node or it
1691 1694 may not be linked with Sx.
1692 1695
1693 1696 See also Pp, Sh, and Sx.
1694 1697
1695 1698 St
1696 1699 Replace an abbreviation for a standard with the full form. The following
1697 1700 standards are recognised. Where multiple lines are given without a blank
1698 1701 line in between, they all refer to the same standard, and using the first
1699 1702 form is recommended.
1700 1703
1701 1704 C language standards
1702 1705
1703 1706 -ansiC ANSI X3.159-1989 ("ANSI C89")
1704 1707 -ansiC-89 ANSI X3.159-1989 ("ANSI C89")
1705 1708 -isoC ISO/IEC 9899:1990 ("ISO C90")
1706 1709 -isoC-90 ISO/IEC 9899:1990 ("ISO C90")
1707 1710 The original C standard.
1708 1711
1709 1712 -isoC-amd1 ISO/IEC 9899/AMD1:1995 ("ISO C90, Amendment 1")
1710 1713
1711 1714 -isoC-tcor1 ISO/IEC 9899/TCOR1:1994 ("ISO C90, Technical
1712 1715 Corrigendum 1")
1713 1716
1714 1717 -isoC-tcor2 ISO/IEC 9899/TCOR2:1995 ("ISO C90, Technical
1715 1718 Corrigendum 2")
1716 1719
1717 1720 -isoC-99 ISO/IEC 9899:1999 ("ISO C99")
1718 1721 The second major version of the C language standard.
1719 1722
1720 1723 -isoC-2011 ISO/IEC 9899:2011 ("ISO C11")
1721 1724 The third major version of the C language standard.
1722 1725
1723 1726 POSIX.1 before the Single UNIX Specification
1724 1727
1725 1728 -p1003.1-88 IEEE Std 1003.1-1988 ("POSIX.1")
1726 1729 -p1003.1 IEEE Std 1003.1 ("POSIX.1")
1727 1730 The original POSIX standard, based on ANSI C.
1728 1731
1729 1732 -p1003.1-90 IEEE Std 1003.1-1990 ("POSIX.1")
1730 1733 -iso9945-1-90 ISO/IEC 9945-1:1990 ("POSIX.1")
1731 1734 The first update of POSIX.1.
1732 1735
1733 1736 -p1003.1b-93 IEEE Std 1003.1b-1993 ("POSIX.1b")
1734 1737 -p1003.1b IEEE Std 1003.1b ("POSIX.1b")
1735 1738 Real-time extensions.
1736 1739
1737 1740 -p1003.1c-95 IEEE Std 1003.1c-1995 ("POSIX.1c")
1738 1741 POSIX thread interfaces.
1739 1742
1740 1743 -p1003.1i-95 IEEE Std 1003.1i-1995 ("POSIX.1i")
1741 1744 Technical Corrigendum.
1742 1745
1743 1746 -p1003.1-96 ISO/IEC 9945-1:1996 ("POSIX.1")
1744 1747 -iso9945-1-96 ISO/IEC 9945-1:1996 ("POSIX.1")
1745 1748 Includes POSIX.1-1990, 1b, 1c, and 1i.
1746 1749
1747 1750 X/Open Portability Guide version 4 and related standards
1748 1751
1749 1752 -xpg3 X/Open Portability Guide Issue 3 ("XPG3")
1750 1753 An XPG4 precursor, published in 1989.
1751 1754
1752 1755 -p1003.2 IEEE Std 1003.2 ("POSIX.2")
1753 1756 -p1003.2-92 IEEE Std 1003.2-1992 ("POSIX.2")
1754 1757 -iso9945-2-93 ISO/IEC 9945-2:1993 ("POSIX.2")
1755 1758 An XCU4 precursor.
1756 1759
1757 1760 -p1003.2a-92 IEEE Std 1003.2a-1992 ("POSIX.2")
1758 1761 Updates to POSIX.2.
1759 1762
1760 1763 -xpg4 X/Open Portability Guide Issue 4 ("XPG4")
1761 1764 Based on POSIX.1 and POSIX.2, published in 1992.
1762 1765
1763 1766 Single UNIX Specification version 1 and related standards
1764 1767
1765 1768 -susv1 Version 1 of the Single UNIX Specification ("SUSv1")
1766 1769 -xpg4.2 X/Open Portability Guide Issue 4, Version 2 ("XPG4.2")
1767 1770 This standard was published in 1994. It was used as
1768 1771 the basis for UNIX 95 certification. The following
1769 1772 three refer to parts of it.
1770 1773
1771 1774 -xsh4.2 X/Open System Interfaces and Headers Issue 4,
1772 1775 Version 2 ("XSH4.2")
1773 1776
1774 1777 -xcurses4.2 X/Open Curses Issue 4, Version 2 ("XCURSES4.2")
1775 1778
1776 1779 -p1003.1g-2000 IEEE Std 1003.1g-2000 ("POSIX.1g")
1777 1780 Networking APIs, including sockets.
1778 1781
1779 1782 -svid4 System V Interface Definition, Fourth Edition
1780 1783 ("SVID4"),
1781 1784 Published in 1995.
1782 1785
1783 1786 Single UNIX Specification version 2 and related standards
1784 1787
1785 1788 -susv2 Version 2 of the Single UNIX Specification ("SUSv2")
1786 1789 This Standard was published in 1997 and is also called
1787 1790 X/Open Portability Guide version 5. It was used as
1788 1791 the basis for UNIX 98 certification. The following
1789 1792 refer to parts of it.
1790 1793
1791 1794 -xbd5 X/Open Base Definitions Issue 5 ("XBD5")
1792 1795
1793 1796 -xsh5 X/Open System Interfaces and Headers Issue 5 ("XSH5")
1794 1797
1795 1798 -xcu5 X/Open Commands and Utilities Issue 5 ("XCU5")
1796 1799
1797 1800 -xns5 X/Open Networking Services Issue 5 ("XNS5")
1798 1801 -xns5.2 X/Open Networking Services Issue 5.2 ("XNS5.2")
1799 1802
1800 1803 Single UNIX Specification version 3
1801 1804
1802 1805 -p1003.1-2001 IEEE Std 1003.1-2001 ("POSIX.1")
1803 1806 -susv3 Version 3 of the Single UNIX Specification ("SUSv3")
1804 1807 This standard is based on C99, SUSv2, POSIX.1-1996, 1d,
1805 1808 and 1j. It is also called X/Open Portability Guide
1806 1809 version 6. It is used as the basis for UNIX 03
1807 1810 certification.
1808 1811
1809 1812 -p1003.1-2004 IEEE Std 1003.1-2004 ("POSIX.1")
1810 1813 The second and last Technical Corrigendum.
1811 1814
1812 1815 Single UNIX Specification version 4
1813 1816
1814 1817 -p1003.1-2008 IEEE Std 1003.1-2008 ("POSIX.1")
1815 1818 -susv4 Version 4 of the Single UNIX Specification ("SUSv4")
1816 1819 This standard is also called X/Open Portability Guide
1817 1820 version 7.
1818 1821
1819 1822 Other standards
1820 1823
1821 1824 -ieee754 IEEE Std 754-1985
1822 1825 Floating-point arithmetic.
1823 1826
1824 1827 -iso8601 ISO 8601
1825 1828 Representation of dates and times, published in 1988.
1826 1829
1827 1830 -iso8802-3 ISO 8802-3: 1989
1828 1831 Ethernet local area networks.
1829 1832
1830 1833 -ieee1275-94 IEEE Std 1275-1994 ("Open Firmware")
1831 1834
1832 1835 Sx
1833 1836 Reference a section or subsection in the same manual page. The
1834 1837 referenced section or subsection name must be identical to the enclosed
1835 1838 argument, including whitespace.
1836 1839
1837 1840 Examples:
1838 1841 .Sx MANUAL STRUCTURE
1839 1842
1840 1843 See also Sh and Ss.
1841 1844
1842 1845 Sy
1843 1846 Request a boldface font.
1844 1847
1845 1848 This is most often used to indicate importance or seriousness (not to be
1846 1849 confused with stress emphasis, see Em). When none of the semantic macros
1847 1850 fit, it is also adequate for syntax elements that have to be given or
1848 1851 that appear verbatim.
1849 1852
1850 1853 Examples:
1851 1854 .Sy Warning :
1852 1855 If
1853 1856 .Sy s
1854 1857 appears in the owner permissions, set-user-ID mode is set.
1855 1858 This utility replaces the former
1856 1859 .Sy dumpdir
1857 1860 program.
1858 1861
1859 1862 See also Bf, Em, Li, and No.
1860 1863
1861 1864 Ta
1862 1865 Table cell separator in Bl -column lists; can only be used below It.
1863 1866
1864 1867 Tn
1865 1868 Supported only for compatibility, do not use this in new manuals. Even
1866 1869 though the macro name ("tradename") suggests a semantic function,
1867 1870 historic usage is inconsistent, mostly using it as a presentation-level
1868 1871 macro to request a small caps font.
1869 1872
1870 1873 Ud
1871 1874 Supported only for compatibility, do not use this in new manuals. Prints
1872 1875 out "currently under development."
1873 1876
1874 1877 Ux
1875 1878 Supported only for compatibility, do not use this in new manuals. Prints
1876 1879 out "UNIX".
1877 1880
1878 1881 Va
1879 1882 A variable name.
1880 1883
1881 1884 Examples:
1882 1885 .Va foo
1883 1886 .Va const char *bar;
1884 1887
1885 1888 For function arguments and parameters, use Fa instead. For declarations
1886 1889 of global variables in the SYNOPSIS section, use Vt.
1887 1890
1888 1891 Vt
1889 1892 A variable type.
1890 1893
1891 1894 This is also used for indicating global variables in the SYNOPSIS
1892 1895 section, in which case a variable name is also specified. Note that it
1893 1896 accepts Block partial-implicit syntax when invoked as the first macro on
1894 1897 an input line in the SYNOPSIS section, else it accepts ordinary In-line
1895 1898 syntax. In the former case, this macro starts a new output line, and a
1896 1899 blank line is inserted in front if there is a preceding function
1897 1900 definition or include directive.
1898 1901
1899 1902 Examples:
1900 1903 .Vt unsigned char
1901 1904 .Vt extern const char * const sys_signame[] ;
1902 1905
1903 1906 For parameters in function prototypes, use Fa instead, for function
1904 1907 return types Ft, and for variable names outside the SYNOPSIS section Va,
1905 1908 even when including a type with the name. See also MANUAL STRUCTURE.
1906 1909
1907 1910 Xc
1908 1911 Close a scope opened by Xo.
1909 1912
1910 1913 Xo
1911 1914 Extend the header of an It macro or the body of a partial-implicit block
1912 1915 macro beyond the end of the input line. This macro originally existed to
1913 1916 work around the 9-argument limit of historic mandoc_roff(5).
1914 1917
1915 1918 Xr
1916 1919 Link to another manual ("cross-reference"). Its syntax is as follows:
1917 1920
1918 1921 .Xr name section
1919 1922
1920 1923 Cross reference the name and section number of another man page.
1921 1924
1922 1925 Examples:
1923 1926 .Xr mandoc 1
1924 1927 .Xr mandoc 1 ;
1925 1928 .Xr mandoc 1 Ns s behaviour
1926 1929
1927 1930 MACRO SYNTAX
1928 1931 The syntax of a macro depends on its classification. In this section,
1929 1932 `-arg' refers to macro arguments, which may be followed by zero or more
1930 1933 `parm' parameters; `Yo' opens the scope of a macro; and if specified,
1931 1934 `Yc' closes it out.
1932 1935
1933 1936 The Callable column indicates that the macro may also be called by
1934 1937 passing its name as an argument to another macro. For example, `.Op Fl O
1935 1938 Ar file' produces `[-O file]'. To prevent a macro call and render the
1936 1939 macro name literally, escape it by prepending a zero-width space, `\&'.
1937 1940 For example, `Op \&Fl O' produces `[Fl O]'. If a macro is not callable
1938 1941 but its name appears as an argument to another macro, it is interpreted
1939 1942 as opaque text. For example, `.Fl Sh' produces `-Sh'.
1940 1943
1941 1944 The Parsed column indicates whether the macro may call other macros by
1942 1945 receiving their names as arguments. If a macro is not parsed but the
1943 1946 name of another macro appears as an argument, it is interpreted as opaque
1944 1947 text.
1945 1948
1946 1949 The Scope column, if applicable, describes closure rules.
1947 1950
1948 1951 Block full-explicit
1949 1952 Multi-line scope closed by an explicit closing macro. All macros
1950 1953 contains bodies; only Bf and (optionally) Bl contain a head.
1951 1954
1952 1955 .Yo [-arg [parm...]] [head...]
1953 1956 [body...]
1954 1957 .Yc
1955 1958
1956 1959 Macro Callable Parsed Scope
1957 1960 Bd No No closed by Ed
1958 1961 Bf No No closed by Ef
1959 1962 Bk No No closed by Ek
1960 1963 Bl No No closed by El
1961 1964 Ed No No opened by Bd
1962 1965 Ef No No opened by Bf
1963 1966 Ek No No opened by Bk
1964 1967 El No No opened by Bl
1965 1968
1966 1969 Block full-implicit
1967 1970 Multi-line scope closed by end-of-file or implicitly by another macro.
1968 1971 All macros have bodies; some (It -bullet, -hyphen, -dash, -enum, -item)
1969 1972 don't have heads; only one (It in Bl -column) has multiple heads.
1970 1973
1971 1974 .Yo [-arg [parm...]] [head... [Ta head...]]
1972 1975 [body...]
1973 1976
1974 1977 Macro Callable Parsed Scope
1975 1978 It No Yes closed by It, El
1976 1979 Nd No No closed by Sh
1977 1980 Nm No Yes closed by Nm, Sh, Ss
1978 1981 Sh No Yes closed by Sh
1979 1982 Ss No Yes closed by Sh, Ss
1980 1983
1981 1984 Note that the Nm macro is a Block full-implicit macro only when invoked
1982 1985 as the first macro in a SYNOPSIS section line, else it is In-line.
1983 1986
1984 1987 Block partial-explicit
1985 1988 Like block full-explicit, but also with single-line scope. Each has at
1986 1989 least a body and, in limited circumstances, a head (Fo, Eo) and/or tail
1987 1990 (Ec).
1988 1991
1989 1992 .Yo [-arg [parm...]] [head...]
1990 1993 [body...]
1991 1994 .Yc [tail...]
1992 1995
1993 1996 .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
1994 1997
1995 1998 Macro Callable Parsed Scope
1996 1999 Ac Yes Yes opened by Ao
1997 2000 Ao Yes Yes closed by Ac
1998 2001 Bc Yes Yes closed by Bo
1999 2002 Bo Yes Yes opened by Bc
2000 2003 Brc Yes Yes opened by Bro
2001 2004 Bro Yes Yes closed by Brc
2002 2005 Dc Yes Yes opened by Do
2003 2006 Do Yes Yes closed by Dc
2004 2007 Ec Yes Yes opened by Eo
2005 2008 Eo Yes Yes closed by Ec
2006 2009 Fc Yes Yes opened by Fo
2007 2010 Fo No No closed by Fc
2008 2011 Oc Yes Yes closed by Oo
2009 2012 Oo Yes Yes opened by Oc
2010 2013 Pc Yes Yes closed by Po
2011 2014 Po Yes Yes opened by Pc
2012 2015 Qc Yes Yes opened by Oo
2013 2016 Qo Yes Yes closed by Oc
2014 2017 Re No No opened by Rs
2015 2018 Rs No No closed by Re
2016 2019 Sc Yes Yes opened by So
2017 2020 So Yes Yes closed by Sc
2018 2021 Xc Yes Yes opened by Xo
2019 2022 Xo Yes Yes closed by Xc
2020 2023
2021 2024 Block partial-implicit
2022 2025 Like block full-implicit, but with single-line scope closed by the end of
2023 2026 the line.
2024 2027
2025 2028 .Yo [-arg [val...]] [body...] [res...]
2026 2029
2027 2030 Macro Callable Parsed
2028 2031 Aq Yes Yes
2029 2032 Bq Yes Yes
2030 2033 Brq Yes Yes
2031 2034 D1 No Yes
2032 2035 Dl No Yes
2033 2036 Dq Yes Yes
2034 2037 En Yes Yes
2035 2038 Op Yes Yes
2036 2039 Pq Yes Yes
2037 2040 Ql Yes Yes
2038 2041 Qq Yes Yes
2039 2042 Sq Yes Yes
2040 2043 Vt Yes Yes
2041 2044
2042 2045 Note that the Vt macro is a Block partial-implicit only when invoked as
2043 2046 the first macro in a SYNOPSIS section line, else it is In-line.
2044 2047
2045 2048 Special block macro
2046 2049 The Ta macro can only be used below It in Bl -column lists. It delimits
2047 2050 blocks representing table cells; these blocks have bodies, but no heads.
2048 2051
2049 2052 Macro Callable Parsed Scope
2050 2053 Ta Yes Yes closed by Ta, It
2051 2054
2052 2055 In-line
2053 2056 Closed by the end of the line, fixed argument lengths, and/or subsequent
2054 2057 macros. In-line macros have only text children. If a number (or
2055 2058 inequality) of arguments is (n), then the macro accepts an arbitrary
2056 2059 number of arguments.
2057 2060
2058 2061 .Yo [-arg [val...]] [args...] [res...]
2059 2062
2060 2063 .Yo [-arg [val...]] [args...] Yc...
2061 2064
2062 2065 .Yo [-arg [val...]] arg0 arg1 argN
2063 2066
2064 2067 Macro Callable Parsed Arguments
2065 2068 %A No No >0
2066 2069 %B No No >0
2067 2070 %C No No >0
2068 2071 %D No No >0
2069 2072 %I No No >0
2070 2073 %J No No >0
2071 2074 %N No No >0
2072 2075 %O No No >0
2073 2076 %P No No >0
2074 2077 %Q No No >0
2075 2078 %R No No >0
2076 2079 %T No No >0
2077 2080 %U No No >0
2078 2081 %V No No >0
2079 2082 Ad Yes Yes >0
2080 2083 An Yes Yes >0
2081 2084 Ap Yes Yes 0
2082 2085 Ar Yes Yes n
2083 2086 At Yes Yes 1
2084 2087 Bsx Yes Yes n
2085 2088 Bt No No 0
2086 2089 Bx Yes Yes n
2087 2090 Cd Yes Yes >0
2088 2091 Cm Yes Yes >0
2089 2092 Db No No 1
2090 2093 Dd No No n
2091 2094 Dt No No n
2092 2095 Dv Yes Yes >0
2093 2096 Dx Yes Yes n
2094 2097 Em Yes Yes >0
2095 2098 Er Yes Yes >0
2096 2099 Es Yes Yes 2
2097 2100 Ev Yes Yes >0
2098 2101 Ex No No n
2099 2102 Fa Yes Yes >0
2100 2103 Fd No No >0
2101 2104 Fl Yes Yes n
2102 2105 Fn Yes Yes >0
2103 2106 Fr Yes Yes >0
2104 2107 Ft Yes Yes >0
2105 2108 Fx Yes Yes n
2106 2109 Hf No No n
2107 2110 Ic Yes Yes >0
2108 2111 In No No 1
2109 2112 Lb No No 1
2110 2113 Li Yes Yes >0
2111 2114 Lk Yes Yes >0
2112 2115 Lp No No 0
2113 2116 Ms Yes Yes >0
2114 2117 Mt Yes Yes >0
2115 2118 Nm Yes Yes n
2116 2119 No Yes Yes 0
2117 2120 Ns Yes Yes 0
2118 2121 Nx Yes Yes n
2119 2122 Os No No n
2120 2123 Ot Yes Yes >0
2121 2124 Ox Yes Yes n
2122 2125 Pa Yes Yes n
2123 2126 Pf Yes Yes 1
2124 2127 Pp No No 0
2125 2128 Rv No No n
2126 2129 Sm No No <2
2127 2130 St No Yes 1
2128 2131 Sx Yes Yes >0
2129 2132 Sy Yes Yes >0
2130 2133 Tn Yes Yes >0
2131 2134 Ud No No 0
2132 2135 Ux Yes Yes n
2133 2136 Va Yes Yes n
2134 2137 Vt Yes Yes >0
2135 2138 Xr Yes Yes 2
2136 2139
2137 2140 Delimiters
2138 2141 When a macro argument consists of one single input character considered
2139 2142 as a delimiter, the argument gets special handling. This does not apply
2140 2143 when delimiters appear in arguments containing more than one character.
2141 2144 Consequently, to prevent special handling and just handle it like any
2142 2145 other argument, a delimiter can be escaped by prepending a zero-width
2143 2146 space (`\&'). In text lines, delimiters never need escaping, but may be
2144 2147 used as normal punctuation.
2145 2148
2146 2149 For many macros, when the leading arguments are opening delimiters, these
2147 2150 delimiters are put before the macro scope, and when the trailing
2148 2151 arguments are closing delimiters, these delimiters are put after the
2149 2152 macro scope. Spacing is suppressed after opening delimiters and before
2150 2153 closing delimiters. For example,
2151 2154
2152 2155 .Aq ( [ word ] ) .
2153 2156
2154 2157 renders as:
2155 2158
2156 2159 ([<word>]).
2157 2160
2158 2161 Opening delimiters are:
2159 2162
2160 2163 ( left parenthesis
2161 2164 [ left bracket
2162 2165
2163 2166 Closing delimiters are:
2164 2167
2165 2168 . period
2166 2169 , comma
2167 2170 : colon
2168 2171 ; semicolon
2169 2172 ) right parenthesis
2170 2173 ] right bracket
2171 2174 ? question mark
2172 2175 ! exclamation mark
2173 2176
2174 2177 Note that even a period preceded by a backslash (`\.') gets this special
2175 2178 handling; use `\&.' to prevent that.
2176 2179
2177 2180 Many in-line macros interrupt their scope when they encounter delimiters,
2178 2181 and resume their scope when more arguments follow that are not
2179 2182 delimiters. For example,
2180 2183
2181 2184 .Fl a ( b | c \*(Ba d ) e
2182 2185
2183 2186 renders as:
2184 2187
2185 2188 -a (-b | -c | -d) -e
2186 2189
2187 2190 This applies to both opening and closing delimiters, and also to the
2188 2191 middle delimiter, which does not suppress spacing:
2189 2192
2190 2193 | vertical bar
2191 2194
2192 2195 As a special case, the predefined string \*(Ba is handled and rendered in
2193 2196 the same way as a plain `|' character. Using this predefined string is
2194 2197 not recommended in new manuals.
2195 2198
2196 2199 Font handling
2197 2200 In mdoc documents, usage of semantic markup is recommended in order to
2198 2201 have proper fonts automatically selected; only when no fitting semantic
2199 2202 markup is available, consider falling back to Physical markup macros.
2200 2203 Whenever any mdoc macro switches the mandoc_roff(5) font mode, it will
2201 2204 automatically restore the previous font when exiting its scope. Manually
2202 2205 switching the font using the mandoc_roff(5) `\f' font escape sequences is
2203 2206 never required.
2204 2207
2205 2208 COMPATIBILITY
2206 2209 This section provides an incomplete list of compatibility issues between
2207 2210 mandoc and GNU troff ("groff").
2208 2211
2209 2212 The following problematic behaviour is found in groff:
2210 2213
2211 2214 - Dd with non-standard arguments behaves very strangely. When there
2212 2215 are three arguments, they are printed verbatim. Any other number of
2213 2216 arguments is replaced by the current date, but without any arguments
2214 2217 the string "Epoch" is printed.
2215 2218 - Lk only accepts a single link-name argument; the remainder is
2216 2219 misformatted.
2217 2220 - Pa does not format its arguments when used in the FILES section under
2218 2221 certain list types.
2219 2222 - Ta can only be called by other macros, but not at the beginning of a
2220 2223 line.
2221 2224 - %C is not implemented (up to and including groff-1.22.2).
2222 2225 - `\f' (font face) and `\F' (font family face) Text Decoration escapes
2223 2226 behave irregularly when specified within line-macro scopes.
2224 2227 - Negative scaling units return to prior lines. Instead, mandoc
2225 2228 truncates them to zero.
2226 2229
2227 2230 The following features are unimplemented in mandoc:
2228 2231
2229 2232 - Bd -file file is unsupported for security reasons.
2230 2233 - Bd -filled does not adjust the right margin, but is an alias for Bd
2231 2234 -ragged.
2232 2235 - Bd -literal does not use a literal font, but is an alias for Bd
2233 2236 -unfilled.
2234 2237 - Bd -offset center and -offset right don't work. Groff does not
2235 2238 implement centered and flush-right rendering either, but produces
2236 2239 large indentations.
2237 2240
2238 2241 SEE ALSO
2239 2242 man(1), mandoc(1), eqn(5), man(5), mandoc_char(5), mandoc_roff(5), tbl(5)
2240 2243
2241 2244 The web page extended documentation for the mdoc language:
2242 2245 http://mandoc.bsd.lv/mdoc/ provides a few tutorial-style pages for
2243 2246 beginners, an extensive style guide for advanced authors, and an
2244 2247 alphabetic index helping to choose the best macros for various kinds of
2245 2248 content.
|
↓ open down ↓ |
1270 lines elided |
↑ open up ↑ |
2246 2249
2247 2250 HISTORY
2248 2251 The mdoc language first appeared as a troff macro package in 4.4BSD. It
2249 2252 was later significantly updated by Werner Lemberg and Ruslan Ermilov in
2250 2253 groff-1.17. The standalone implementation that is part of the mandoc(1)
2251 2254 utility written by Kristaps Dzonsons appeared in OpenBSD 4.6.
2252 2255
2253 2256 AUTHORS
2254 2257 The mdoc reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
2255 2258
2256 -illumos July 20, 2017 illumos
2259 +illumos July 28, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX