| 1 | .\" $Id: mdoc.7,v 1.234 2014/08/08 16:38:06 schwarze Exp $ |
| 2 | .\" |
| 3 | .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
| 4 | .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org> |
| 5 | .\" |
| 6 | .\" Permission to use, copy, modify, and distribute this software for any |
| 7 | .\" purpose with or without fee is hereby granted, provided that the above |
| 8 | .\" copyright notice and this permission notice appear in all copies. |
| 9 | .\" |
| 10 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
| 11 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
| 12 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
| 13 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| 14 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
| 15 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
| 16 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| 17 | .\" |
| 18 | .Dd $Mdocdate: August 8 2014 $ |
| 19 | .Dt MDOC 7 |
| 20 | .Os |
| 21 | .Sh NAME |
| 22 | .Nm mdoc |
| 23 | .Nd semantic markup language for formatting manual pages |
| 24 | .Sh DESCRIPTION |
| 25 | The |
| 26 | .Nm mdoc |
| 27 | language supports authoring of manual pages for the |
| 28 | .Xr man 1 |
| 29 | utility by allowing semantic annotations of words, phrases, |
| 30 | page sections and complete manual pages. |
| 31 | Such annotations are used by formatting tools to achieve a uniform |
| 32 | presentation across all manuals written in |
| 33 | .Nm , |
| 34 | and to support hyperlinking if supported by the output medium. |
| 35 | .Pp |
| 36 | This reference document describes the structure of manual pages |
| 37 | and the syntax and usage of the |
| 38 | .Nm |
| 39 | language. |
| 40 | The reference implementation of a parsing and formatting tool is |
| 41 | .Xr mandoc 1 ; |
| 42 | the |
| 43 | .Sx COMPATIBILITY |
| 44 | section describes compatibility with other implementations. |
| 45 | .Pp |
| 46 | In an |
| 47 | .Nm |
| 48 | document, lines beginning with the control character |
| 49 | .Sq \&. |
| 50 | are called |
| 51 | .Dq macro lines . |
| 52 | The first word is the macro name. |
| 53 | It consists of two or three letters. |
| 54 | Most macro names begin with a capital letter. |
| 55 | For a list of available macros, see |
| 56 | .Sx MACRO OVERVIEW . |
| 57 | The words following the macro name are arguments to the macro, optionally |
| 58 | including the names of other, callable macros; see |
| 59 | .Sx MACRO SYNTAX |
| 60 | for details. |
| 61 | .Pp |
| 62 | Lines not beginning with the control character are called |
| 63 | .Dq text lines . |
| 64 | They provide free-form text to be printed; the formatting of the text |
| 65 | depends on the respective processing context: |
| 66 | .Bd -literal -offset indent |
| 67 | \&.Sh Macro lines change control state. |
| 68 | Text lines are interpreted within the current state. |
| 69 | .Ed |
| 70 | .Pp |
| 71 | Many aspects of the basic syntax of the |
| 72 | .Nm |
| 73 | language are based on the |
| 74 | .Xr roff 7 |
| 75 | language; see the |
| 76 | .Em LANGUAGE SYNTAX |
| 77 | and |
| 78 | .Em MACRO SYNTAX |
| 79 | sections in the |
| 80 | .Xr roff 7 |
| 81 | manual for details, in particular regarding |
| 82 | comments, escape sequences, whitespace, and quoting. |
| 83 | However, using |
| 84 | .Xr roff 7 |
| 85 | requests in |
| 86 | .Nm |
| 87 | documents is discouraged; |
| 88 | .Xr mandoc 1 |
| 89 | supports some of them merely for backward compatibility. |
| 90 | .Sh MANUAL STRUCTURE |
| 91 | A well-formed |
| 92 | .Nm |
| 93 | document consists of a document prologue followed by one or more |
| 94 | sections. |
| 95 | .Pp |
| 96 | The prologue, which consists of the |
| 97 | .Sx \&Dd , |
| 98 | .Sx \&Dt , |
| 99 | and |
| 100 | .Sx \&Os |
| 101 | macros in that order, is required for every document. |
| 102 | .Pp |
| 103 | The first section (sections are denoted by |
| 104 | .Sx \&Sh ) |
| 105 | must be the NAME section, consisting of at least one |
| 106 | .Sx \&Nm |
| 107 | followed by |
| 108 | .Sx \&Nd . |
| 109 | .Pp |
| 110 | Following that, convention dictates specifying at least the |
| 111 | .Em SYNOPSIS |
| 112 | and |
| 113 | .Em DESCRIPTION |
| 114 | sections, although this varies between manual sections. |
| 115 | .Pp |
| 116 | The following is a well-formed skeleton |
| 117 | .Nm |
| 118 | file for a utility |
| 119 | .Qq progname : |
| 120 | .Bd -literal -offset indent |
| 121 | \&.Dd $\&Mdocdate$ |
| 122 | \&.Dt PROGNAME section |
| 123 | \&.Os |
| 124 | \&.Sh NAME |
| 125 | \&.Nm progname |
| 126 | \&.Nd one line about what it does |
| 127 | \&.\e\(dq .Sh LIBRARY |
| 128 | \&.\e\(dq For sections 2, 3, and 9 only. |
| 129 | \&.\e\(dq Not used in OpenBSD. |
| 130 | \&.Sh SYNOPSIS |
| 131 | \&.Nm progname |
| 132 | \&.Op Fl options |
| 133 | \&.Ar |
| 134 | \&.Sh DESCRIPTION |
| 135 | The |
| 136 | \&.Nm |
| 137 | utility processes files ... |
| 138 | \&.\e\(dq .Sh CONTEXT |
| 139 | \&.\e\(dq For section 9 functions only. |
| 140 | \&.\e\(dq .Sh IMPLEMENTATION NOTES |
| 141 | \&.\e\(dq Not used in OpenBSD. |
| 142 | \&.\e\(dq .Sh RETURN VALUES |
| 143 | \&.\e\(dq For sections 2, 3, and 9 function return values only. |
| 144 | \&.\e\(dq .Sh ENVIRONMENT |
| 145 | \&.\e\(dq For sections 1, 6, 7, and 8 only. |
| 146 | \&.\e\(dq .Sh FILES |
| 147 | \&.\e\(dq .Sh EXIT STATUS |
| 148 | \&.\e\(dq For sections 1, 6, and 8 only. |
| 149 | \&.\e\(dq .Sh EXAMPLES |
| 150 | \&.\e\(dq .Sh DIAGNOSTICS |
| 151 | \&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. |
| 152 | \&.\e\(dq .Sh ERRORS |
| 153 | \&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. |
| 154 | \&.\e\(dq .Sh SEE ALSO |
| 155 | \&.\e\(dq .Xr foobar 1 |
| 156 | \&.\e\(dq .Sh STANDARDS |
| 157 | \&.\e\(dq .Sh HISTORY |
| 158 | \&.\e\(dq .Sh AUTHORS |
| 159 | \&.\e\(dq .Sh CAVEATS |
| 160 | \&.\e\(dq .Sh BUGS |
| 161 | \&.\e\(dq .Sh SECURITY CONSIDERATIONS |
| 162 | \&.\e\(dq Not used in OpenBSD. |
| 163 | .Ed |
| 164 | .Pp |
| 165 | The sections in an |
| 166 | .Nm |
| 167 | document are conventionally ordered as they appear above. |
| 168 | Sections should be composed as follows: |
| 169 | .Bl -ohang -offset Ds |
| 170 | .It Em NAME |
| 171 | The name(s) and a one line description of the documented material. |
| 172 | The syntax for this as follows: |
| 173 | .Bd -literal -offset indent |
| 174 | \&.Nm name0 , |
| 175 | \&.Nm name1 , |
| 176 | \&.Nm name2 |
| 177 | \&.Nd a one line description |
| 178 | .Ed |
| 179 | .Pp |
| 180 | Multiple |
| 181 | .Sq \&Nm |
| 182 | names should be separated by commas. |
| 183 | .Pp |
| 184 | The |
| 185 | .Sx \&Nm |
| 186 | macro(s) must precede the |
| 187 | .Sx \&Nd |
| 188 | macro. |
| 189 | .Pp |
| 190 | See |
| 191 | .Sx \&Nm |
| 192 | and |
| 193 | .Sx \&Nd . |
| 194 | .It Em LIBRARY |
| 195 | The name of the library containing the documented material, which is |
| 196 | assumed to be a function in a section 2, 3, or 9 manual. |
| 197 | The syntax for this is as follows: |
| 198 | .Bd -literal -offset indent |
| 199 | \&.Lb libarm |
| 200 | .Ed |
| 201 | .Pp |
| 202 | See |
| 203 | .Sx \&Lb . |
| 204 | .It Em SYNOPSIS |
| 205 | Documents the utility invocation syntax, function call syntax, or device |
| 206 | configuration. |
| 207 | .Pp |
| 208 | For the first, utilities (sections 1, 6, and 8), this is |
| 209 | generally structured as follows: |
| 210 | .Bd -literal -offset indent |
| 211 | \&.Nm bar |
| 212 | \&.Op Fl v |
| 213 | \&.Op Fl o Ar file |
| 214 | \&.Op Ar |
| 215 | \&.Nm foo |
| 216 | \&.Op Fl v |
| 217 | \&.Op Fl o Ar file |
| 218 | \&.Op Ar |
| 219 | .Ed |
| 220 | .Pp |
| 221 | Commands should be ordered alphabetically. |
| 222 | .Pp |
| 223 | For the second, function calls (sections 2, 3, 9): |
| 224 | .Bd -literal -offset indent |
| 225 | \&.In header.h |
| 226 | \&.Vt extern const char *global; |
| 227 | \&.Ft "char *" |
| 228 | \&.Fn foo "const char *src" |
| 229 | \&.Ft "char *" |
| 230 | \&.Fn bar "const char *src" |
| 231 | .Ed |
| 232 | .Pp |
| 233 | Ordering of |
| 234 | .Sx \&In , |
| 235 | .Sx \&Vt , |
| 236 | .Sx \&Fn , |
| 237 | and |
| 238 | .Sx \&Fo |
| 239 | macros should follow C header-file conventions. |
| 240 | .Pp |
| 241 | And for the third, configurations (section 4): |
| 242 | .Bd -literal -offset indent |
| 243 | \&.Cd \(dqit* at isa? port 0x2e\(dq |
| 244 | \&.Cd \(dqit* at isa? port 0x4e\(dq |
| 245 | .Ed |
| 246 | .Pp |
| 247 | Manuals not in these sections generally don't need a |
| 248 | .Em SYNOPSIS . |
| 249 | .Pp |
| 250 | Some macros are displayed differently in the |
| 251 | .Em SYNOPSIS |
| 252 | section, particularly |
| 253 | .Sx \&Nm , |
| 254 | .Sx \&Cd , |
| 255 | .Sx \&Fd , |
| 256 | .Sx \&Fn , |
| 257 | .Sx \&Fo , |
| 258 | .Sx \&In , |
| 259 | .Sx \&Vt , |
| 260 | and |
| 261 | .Sx \&Ft . |
| 262 | All of these macros are output on their own line. |
| 263 | If two such dissimilar macros are pairwise invoked (except for |
| 264 | .Sx \&Ft |
| 265 | before |
| 266 | .Sx \&Fo |
| 267 | or |
| 268 | .Sx \&Fn ) , |
| 269 | they are separated by a vertical space, unless in the case of |
| 270 | .Sx \&Fo , |
| 271 | .Sx \&Fn , |
| 272 | and |
| 273 | .Sx \&Ft , |
| 274 | which are always separated by vertical space. |
| 275 | .Pp |
| 276 | When text and macros following an |
| 277 | .Sx \&Nm |
| 278 | macro starting an input line span multiple output lines, |
| 279 | all output lines but the first will be indented to align |
| 280 | with the text immediately following the |
| 281 | .Sx \&Nm |
| 282 | macro, up to the next |
| 283 | .Sx \&Nm , |
| 284 | .Sx \&Sh , |
| 285 | or |
| 286 | .Sx \&Ss |
| 287 | macro or the end of an enclosing block, whichever comes first. |
| 288 | .It Em DESCRIPTION |
| 289 | This begins with an expansion of the brief, one line description in |
| 290 | .Em NAME : |
| 291 | .Bd -literal -offset indent |
| 292 | The |
| 293 | \&.Nm |
| 294 | utility does this, that, and the other. |
| 295 | .Ed |
| 296 | .Pp |
| 297 | It usually follows with a breakdown of the options (if documenting a |
| 298 | command), such as: |
| 299 | .Bd -literal -offset indent |
| 300 | The arguments are as follows: |
| 301 | \&.Bl \-tag \-width Ds |
| 302 | \&.It Fl v |
| 303 | Print verbose information. |
| 304 | \&.El |
| 305 | .Ed |
| 306 | .Pp |
| 307 | Manuals not documenting a command won't include the above fragment. |
| 308 | .Pp |
| 309 | Since the |
| 310 | .Em DESCRIPTION |
| 311 | section usually contains most of the text of a manual, longer manuals |
| 312 | often use the |
| 313 | .Sx \&Ss |
| 314 | macro to form subsections. |
| 315 | In very long manuals, the |
| 316 | .Em DESCRIPTION |
| 317 | may be split into multiple sections, each started by an |
| 318 | .Sx \&Sh |
| 319 | macro followed by a non-standard section name, and each having |
| 320 | several subsections, like in the present |
| 321 | .Nm |
| 322 | manual. |
| 323 | .It Em CONTEXT |
| 324 | This section lists the contexts in which functions can be called in section 9. |
| 325 | The contexts are autoconf, process, or interrupt. |
| 326 | .It Em IMPLEMENTATION NOTES |
| 327 | Implementation-specific notes should be kept here. |
| 328 | This is useful when implementing standard functions that may have side |
| 329 | effects or notable algorithmic implications. |
| 330 | .It Em RETURN VALUES |
| 331 | This section documents the |
| 332 | return values of functions in sections 2, 3, and 9. |
| 333 | .Pp |
| 334 | See |
| 335 | .Sx \&Rv . |
| 336 | .It Em ENVIRONMENT |
| 337 | Lists the environment variables used by the utility, |
| 338 | and explains the syntax and semantics of their values. |
| 339 | The |
| 340 | .Xr environ 7 |
| 341 | manual provides examples of typical content and formatting. |
| 342 | .Pp |
| 343 | See |
| 344 | .Sx \&Ev . |
| 345 | .It Em FILES |
| 346 | Documents files used. |
| 347 | It's helpful to document both the file name and a short description of how |
| 348 | the file is used (created, modified, etc.). |
| 349 | .Pp |
| 350 | See |
| 351 | .Sx \&Pa . |
| 352 | .It Em EXIT STATUS |
| 353 | This section documents the |
| 354 | command exit status for section 1, 6, and 8 utilities. |
| 355 | Historically, this information was described in |
| 356 | .Em DIAGNOSTICS , |
| 357 | a practise that is now discouraged. |
| 358 | .Pp |
| 359 | See |
| 360 | .Sx \&Ex . |
| 361 | .It Em EXAMPLES |
| 362 | Example usages. |
| 363 | This often contains snippets of well-formed, well-tested invocations. |
| 364 | Make sure that examples work properly! |
| 365 | .It Em DIAGNOSTICS |
| 366 | Documents error messages. |
| 367 | In section 4 and 9 manuals, these are usually messages printed by the |
| 368 | kernel to the console and to the kernel log. |
| 369 | In section 1, 6, 7, and 8, these are usually messages printed by |
| 370 | userland programs to the standard error output. |
| 371 | .Pp |
| 372 | Historically, this section was used in place of |
| 373 | .Em EXIT STATUS |
| 374 | for manuals in sections 1, 6, and 8; however, this practise is |
| 375 | discouraged. |
| 376 | .Pp |
| 377 | See |
| 378 | .Sx \&Bl |
| 379 | .Fl diag . |
| 380 | .It Em ERRORS |
| 381 | Documents |
| 382 | .Xr errno 2 |
| 383 | settings in sections 2, 3, 4, and 9. |
| 384 | .Pp |
| 385 | See |
| 386 | .Sx \&Er . |
| 387 | .It Em SEE ALSO |
| 388 | References other manuals with related topics. |
| 389 | This section should exist for most manuals. |
| 390 | Cross-references should conventionally be ordered first by section, then |
| 391 | alphabetically. |
| 392 | .Pp |
| 393 | References to other documentation concerning the topic of the manual page, |
| 394 | for example authoritative books or journal articles, may also be |
| 395 | provided in this section. |
| 396 | .Pp |
| 397 | See |
| 398 | .Sx \&Rs |
| 399 | and |
| 400 | .Sx \&Xr . |
| 401 | .It Em STANDARDS |
| 402 | References any standards implemented or used. |
| 403 | If not adhering to any standards, the |
| 404 | .Em HISTORY |
| 405 | section should be used instead. |
| 406 | .Pp |
| 407 | See |
| 408 | .Sx \&St . |
| 409 | .It Em HISTORY |
| 410 | A brief history of the subject, including where it was first implemented, |
| 411 | and when it was ported to or reimplemented for the operating system at hand. |
| 412 | .It Em AUTHORS |
| 413 | Credits to the person or persons who wrote the code and/or documentation. |
| 414 | Authors should generally be noted by both name and email address. |
| 415 | .Pp |
| 416 | See |
| 417 | .Sx \&An . |
| 418 | .It Em CAVEATS |
| 419 | Common misuses and misunderstandings should be explained |
| 420 | in this section. |
| 421 | .It Em BUGS |
| 422 | Known bugs, limitations, and work-arounds should be described |
| 423 | in this section. |
| 424 | .It Em SECURITY CONSIDERATIONS |
| 425 | Documents any security precautions that operators should consider. |
| 426 | .El |
| 427 | .Sh MACRO OVERVIEW |
| 428 | This overview is sorted such that macros of similar purpose are listed |
| 429 | together, to help find the best macro for any given purpose. |
| 430 | Deprecated macros are not included in the overview, but can be found below |
| 431 | in the alphabetical |
| 432 | .Sx MACRO REFERENCE . |
| 433 | .Ss Document preamble and NAME section macros |
| 434 | .Bl -column "Brq, Bro, Brc" description |
| 435 | .It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year |
| 436 | .It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch |
| 437 | .It Sx \&Os Ta operating system version: Op Ar system Op Ar version |
| 438 | .It Sx \&Nm Ta document name (one argument) |
| 439 | .It Sx \&Nd Ta document description (one line) |
| 440 | .El |
| 441 | .Ss Sections and cross references |
| 442 | .Bl -column "Brq, Bro, Brc" description |
| 443 | .It Sx \&Sh Ta section header (one line) |
| 444 | .It Sx \&Ss Ta subsection header (one line) |
| 445 | .It Sx \&Sx Ta internal cross reference to a section or subsection |
| 446 | .It Sx \&Xr Ta cross reference to another manual page: Ar name section |
| 447 | .It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments) |
| 448 | .El |
| 449 | .Ss Displays and lists |
| 450 | .Bl -column "Brq, Bro, Brc" description |
| 451 | .It Sx \&Bd , \&Ed Ta display block: |
| 452 | .Fl Ar type |
| 453 | .Op Fl offset Ar width |
| 454 | .Op Fl compact |
| 455 | .It Sx \&D1 Ta indented display (one line) |
| 456 | .It Sx \&Dl Ta indented literal display (one line) |
| 457 | .It Sx \&Bl , \&El Ta list block: |
| 458 | .Fl Ar type |
| 459 | .Op Fl width Ar val |
| 460 | .Op Fl offset Ar val |
| 461 | .Op Fl compact |
| 462 | .It Sx \&It Ta list item (syntax depends on Fl Ar type ) |
| 463 | .It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists |
| 464 | .It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references) |
| 465 | .El |
| 466 | .Ss Spacing control |
| 467 | .Bl -column "Brq, Bro, Brc" description |
| 468 | .It Sx \&Pf Ta prefix, no following horizontal space (one argument) |
| 469 | .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments) |
| 470 | .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments) |
| 471 | .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off |
| 472 | .It Sx \&Bk , \&Ek Ta keep block: Fl words |
| 473 | .It Sx \&br Ta force output line break in text mode (no arguments) |
| 474 | .It Sx \&sp Ta force vertical space: Op Ar height |
| 475 | .El |
| 476 | .Ss Semantic markup for command line utilities: |
| 477 | .Bl -column "Brq, Bro, Brc" description |
| 478 | .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility |
| 479 | .It Sx \&Fl Ta command line options (flags) (>=0 arguments) |
| 480 | .It Sx \&Cm Ta command modifier (>0 arguments) |
| 481 | .It Sx \&Ar Ta command arguments (>=0 arguments) |
| 482 | .It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) |
| 483 | .It Sx \&Ic Ta internal or interactive command (>0 arguments) |
| 484 | .It Sx \&Ev Ta environmental variable (>0 arguments) |
| 485 | .It Sx \&Pa Ta file system path (>=0 arguments) |
| 486 | .El |
| 487 | .Ss Semantic markup for function libraries: |
| 488 | .Bl -column "Brq, Bro, Brc" description |
| 489 | .It Sx \&Lb Ta function library (one argument) |
| 490 | .It Sx \&In Ta include file (one argument) |
| 491 | .It Sx \&Fd Ta other preprocessor directive (>0 arguments) |
| 492 | .It Sx \&Ft Ta function type (>0 arguments) |
| 493 | .It Sx \&Fo , \&Fc Ta function block: Ar funcname |
| 494 | .It Sx \&Fn Ta function name: |
| 495 | .Op Ar functype |
| 496 | .Ar funcname |
| 497 | .Oo |
| 498 | .Op Ar argtype |
| 499 | .Ar argname |
| 500 | .Oc |
| 501 | .It Sx \&Fa Ta function argument (>0 arguments) |
| 502 | .It Sx \&Vt Ta variable type (>0 arguments) |
| 503 | .It Sx \&Va Ta variable name (>0 arguments) |
| 504 | .It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments) |
| 505 | .It Sx \&Er Ta error constant (>0 arguments) |
| 506 | .It Sx \&Ev Ta environmental variable (>0 arguments) |
| 507 | .El |
| 508 | .Ss Various semantic markup: |
| 509 | .Bl -column "Brq, Bro, Brc" description |
| 510 | .It Sx \&An Ta author name (>0 arguments) |
| 511 | .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name |
| 512 | .It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address |
| 513 | .It Sx \&Cd Ta kernel configuration declaration (>0 arguments) |
| 514 | .It Sx \&Ad Ta memory address (>0 arguments) |
| 515 | .It Sx \&Ms Ta mathematical symbol (>0 arguments) |
| 516 | .El |
| 517 | .Ss Physical markup |
| 518 | .Bl -column "Brq, Bro, Brc" description |
| 519 | .It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments) |
| 520 | .It Sx \&Sy Ta boldface font (symbolic) (>0 arguments) |
| 521 | .It Sx \&Li Ta typewriter font (literal) (>0 arguments) |
| 522 | .It Sx \&No Ta return to roman font (normal) (no arguments) |
| 523 | .It Sx \&Bf , \&Ef Ta font block: |
| 524 | .Op Fl Ar type | Cm \&Em | \&Li | \&Sy |
| 525 | .El |
| 526 | .Ss Physical enclosures |
| 527 | .Bl -column "Brq, Bro, Brc" description |
| 528 | .It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text |
| 529 | .It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text |
| 530 | .It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text |
| 531 | .It Sx \&Ql Ta single-quoted literal text: Ql text |
| 532 | .It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text |
| 533 | .It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text |
| 534 | .It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text |
| 535 | .It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text |
| 536 | .It Sx \&Eo , \&Ec Ta generic enclosure |
| 537 | .El |
| 538 | .Ss Text production |
| 539 | .Bl -column "Brq, Bro, Brc" description |
| 540 | .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ... |
| 541 | .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ... |
| 542 | .It Sx \&St Ta reference to a standards document (one argument) |
| 543 | .It Sx \&At Ta At |
| 544 | .It Sx \&Bx Ta Bx |
| 545 | .It Sx \&Bsx Ta Bsx |
| 546 | .It Sx \&Nx Ta Nx |
| 547 | .It Sx \&Fx Ta Fx |
| 548 | .It Sx \&Ox Ta Ox |
| 549 | .It Sx \&Dx Ta Dx |
| 550 | .El |
| 551 | .Sh MACRO REFERENCE |
| 552 | This section is a canonical reference of all macros, arranged |
| 553 | alphabetically. |
| 554 | For the scoping of individual macros, see |
| 555 | .Sx MACRO SYNTAX . |
| 556 | .Ss \&%A |
| 557 | Author name of an |
| 558 | .Sx \&Rs |
| 559 | block. |
| 560 | Multiple authors should each be accorded their own |
| 561 | .Sx \%%A |
| 562 | line. |
| 563 | Author names should be ordered with full or abbreviated forename(s) |
| 564 | first, then full surname. |
| 565 | .Ss \&%B |
| 566 | Book title of an |
| 567 | .Sx \&Rs |
| 568 | block. |
| 569 | This macro may also be used in a non-bibliographic context when |
| 570 | referring to book titles. |
| 571 | .Ss \&%C |
| 572 | Publication city or location of an |
| 573 | .Sx \&Rs |
| 574 | block. |
| 575 | .Ss \&%D |
| 576 | Publication date of an |
| 577 | .Sx \&Rs |
| 578 | block. |
| 579 | Recommended formats of arguments are |
| 580 | .Ar month day , year |
| 581 | or just |
| 582 | .Ar year . |
| 583 | .Ss \&%I |
| 584 | Publisher or issuer name of an |
| 585 | .Sx \&Rs |
| 586 | block. |
| 587 | .Ss \&%J |
| 588 | Journal name of an |
| 589 | .Sx \&Rs |
| 590 | block. |
| 591 | .Ss \&%N |
| 592 | Issue number (usually for journals) of an |
| 593 | .Sx \&Rs |
| 594 | block. |
| 595 | .Ss \&%O |
| 596 | Optional information of an |
| 597 | .Sx \&Rs |
| 598 | block. |
| 599 | .Ss \&%P |
| 600 | Book or journal page number of an |
| 601 | .Sx \&Rs |
| 602 | block. |
| 603 | .Ss \&%Q |
| 604 | Institutional author (school, government, etc.) of an |
| 605 | .Sx \&Rs |
| 606 | block. |
| 607 | Multiple institutional authors should each be accorded their own |
| 608 | .Sx \&%Q |
| 609 | line. |
| 610 | .Ss \&%R |
| 611 | Technical report name of an |
| 612 | .Sx \&Rs |
| 613 | block. |
| 614 | .Ss \&%T |
| 615 | Article title of an |
| 616 | .Sx \&Rs |
| 617 | block. |
| 618 | This macro may also be used in a non-bibliographical context when |
| 619 | referring to article titles. |
| 620 | .Ss \&%U |
| 621 | URI of reference document. |
| 622 | .Ss \&%V |
| 623 | Volume number of an |
| 624 | .Sx \&Rs |
| 625 | block. |
| 626 | .Ss \&Ac |
| 627 | Close an |
| 628 | .Sx \&Ao |
| 629 | block. |
| 630 | Does not have any tail arguments. |
| 631 | .Ss \&Ad |
| 632 | Memory address. |
| 633 | Do not use this for postal addresses. |
| 634 | .Pp |
| 635 | Examples: |
| 636 | .Dl \&.Ad [0,$] |
| 637 | .Dl \&.Ad 0x00000000 |
| 638 | .Ss \&An |
| 639 | Author name. |
| 640 | Can be used both for the authors of the program, function, or driver |
| 641 | documented in the manual, or for the authors of the manual itself. |
| 642 | Requires either the name of an author or one of the following arguments: |
| 643 | .Pp |
| 644 | .Bl -tag -width "-nosplitX" -offset indent -compact |
| 645 | .It Fl split |
| 646 | Start a new output line before each subsequent invocation of |
| 647 | .Sx \&An . |
| 648 | .It Fl nosplit |
| 649 | The opposite of |
| 650 | .Fl split . |
| 651 | .El |
| 652 | .Pp |
| 653 | The default is |
| 654 | .Fl nosplit . |
| 655 | The effect of selecting either of the |
| 656 | .Fl split |
| 657 | modes ends at the beginning of the |
| 658 | .Em AUTHORS |
| 659 | section. |
| 660 | In the |
| 661 | .Em AUTHORS |
| 662 | section, the default is |
| 663 | .Fl nosplit |
| 664 | for the first author listing and |
| 665 | .Fl split |
| 666 | for all other author listings. |
| 667 | .Pp |
| 668 | Examples: |
| 669 | .Dl \&.An -nosplit |
| 670 | .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv |
| 671 | .Ss \&Ao |
| 672 | Begin a block enclosed by angle brackets. |
| 673 | Does not have any head arguments. |
| 674 | .Pp |
| 675 | Examples: |
| 676 | .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac |
| 677 | .Pp |
| 678 | See also |
| 679 | .Sx \&Aq . |
| 680 | .Ss \&Ap |
| 681 | Inserts an apostrophe without any surrounding whitespace. |
| 682 | This is generally used as a grammatical device when referring to the verb |
| 683 | form of a function. |
| 684 | .Pp |
| 685 | Examples: |
| 686 | .Dl \&.Fn execve \&Ap d |
| 687 | .Ss \&Aq |
| 688 | Encloses its arguments in angle brackets. |
| 689 | .Pp |
| 690 | Examples: |
| 691 | .Dl \&.Fl -key= \&Ns \&Aq \&Ar val |
| 692 | .Pp |
| 693 | .Em Remarks : |
| 694 | this macro is often abused for rendering URIs, which should instead use |
| 695 | .Sx \&Lk |
| 696 | or |
| 697 | .Sx \&Mt , |
| 698 | or to note pre-processor |
| 699 | .Dq Li #include |
| 700 | statements, which should use |
| 701 | .Sx \&In . |
| 702 | .Pp |
| 703 | See also |
| 704 | .Sx \&Ao . |
| 705 | .Ss \&Ar |
| 706 | Command arguments. |
| 707 | If an argument is not provided, the string |
| 708 | .Dq file ...\& |
| 709 | is used as a default. |
| 710 | .Pp |
| 711 | Examples: |
| 712 | .Dl ".Fl o Ar file" |
| 713 | .Dl ".Ar" |
| 714 | .Dl ".Ar arg1 , arg2 ." |
| 715 | .Pp |
| 716 | The arguments to the |
| 717 | .Sx \&Ar |
| 718 | macro are names and placeholders for command arguments; |
| 719 | for fixed strings to be passed verbatim as arguments, use |
| 720 | .Sx \&Fl |
| 721 | or |
| 722 | .Sx \&Cm . |
| 723 | .Ss \&At |
| 724 | Formats an |
| 725 | .At |
| 726 | version. |
| 727 | Accepts one optional argument: |
| 728 | .Pp |
| 729 | .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact |
| 730 | .It Cm v[1-7] | 32v |
| 731 | A version of |
| 732 | .At . |
| 733 | .It Cm III |
| 734 | .At III . |
| 735 | .It Cm V[.[1-4]]? |
| 736 | A version of |
| 737 | .At V . |
| 738 | .El |
| 739 | .Pp |
| 740 | Note that these arguments do not begin with a hyphen. |
| 741 | .Pp |
| 742 | Examples: |
| 743 | .Dl \&.At |
| 744 | .Dl \&.At III |
| 745 | .Dl \&.At V.1 |
| 746 | .Pp |
| 747 | See also |
| 748 | .Sx \&Bsx , |
| 749 | .Sx \&Bx , |
| 750 | .Sx \&Dx , |
| 751 | .Sx \&Fx , |
| 752 | .Sx \&Nx , |
| 753 | and |
| 754 | .Sx \&Ox . |
| 755 | .Ss \&Bc |
| 756 | Close a |
| 757 | .Sx \&Bo |
| 758 | block. |
| 759 | Does not have any tail arguments. |
| 760 | .Ss \&Bd |
| 761 | Begin a display block. |
| 762 | Its syntax is as follows: |
| 763 | .Bd -ragged -offset indent |
| 764 | .Pf \. Sx \&Bd |
| 765 | .Fl Ns Ar type |
| 766 | .Op Fl offset Ar width |
| 767 | .Op Fl compact |
| 768 | .Ed |
| 769 | .Pp |
| 770 | Display blocks are used to select a different indentation and |
| 771 | justification than the one used by the surrounding text. |
| 772 | They may contain both macro lines and text lines. |
| 773 | By default, a display block is preceded by a vertical space. |
| 774 | .Pp |
| 775 | The |
| 776 | .Ar type |
| 777 | must be one of the following: |
| 778 | .Bl -tag -width 13n -offset indent |
| 779 | .It Fl centered |
| 780 | Produce one output line from each input line, and centre-justify each line. |
| 781 | Using this display type is not recommended; many |
| 782 | .Nm |
| 783 | implementations render it poorly. |
| 784 | .It Fl filled |
| 785 | Change the positions of line breaks to fill each line, and left- and |
| 786 | right-justify the resulting block. |
| 787 | .It Fl literal |
| 788 | Produce one output line from each input line, |
| 789 | and do not justify the block at all. |
| 790 | Preserve white space as it appears in the input. |
| 791 | Always use a constant-width font. |
| 792 | Use this for displaying source code. |
| 793 | .It Fl ragged |
| 794 | Change the positions of line breaks to fill each line, and left-justify |
| 795 | the resulting block. |
| 796 | .It Fl unfilled |
| 797 | The same as |
| 798 | .Fl literal , |
| 799 | but using the same font as for normal text, which is a variable width font |
| 800 | if supported by the output device. |
| 801 | .El |
| 802 | .Pp |
| 803 | The |
| 804 | .Ar type |
| 805 | must be provided first. |
| 806 | Additional arguments may follow: |
| 807 | .Bl -tag -width 13n -offset indent |
| 808 | .It Fl offset Ar width |
| 809 | Indent the display by the |
| 810 | .Ar width , |
| 811 | which may be one of the following: |
| 812 | .Bl -item |
| 813 | .It |
| 814 | One of the pre-defined strings |
| 815 | .Cm indent , |
| 816 | the width of a standard indentation (six constant width characters); |
| 817 | .Cm indent-two , |
| 818 | twice |
| 819 | .Cm indent ; |
| 820 | .Cm left , |
| 821 | which has no effect; |
| 822 | .Cm right , |
| 823 | which justifies to the right margin; or |
| 824 | .Cm center , |
| 825 | which aligns around an imagined centre axis. |
| 826 | .It |
| 827 | A macro invocation, which selects a predefined width |
| 828 | associated with that macro. |
| 829 | The most popular is the imaginary macro |
| 830 | .Ar \&Ds , |
| 831 | which resolves to |
| 832 | .Sy 6n . |
| 833 | .It |
| 834 | A scaling width as described in |
| 835 | .Xr roff 7 . |
| 836 | .It |
| 837 | An arbitrary string, which indents by the length of this string. |
| 838 | .El |
| 839 | .Pp |
| 840 | When the argument is missing, |
| 841 | .Fl offset |
| 842 | is ignored. |
| 843 | .It Fl compact |
| 844 | Do not assert vertical space before the display. |
| 845 | .El |
| 846 | .Pp |
| 847 | Examples: |
| 848 | .Bd -literal -offset indent |
| 849 | \&.Bd \-literal \-offset indent \-compact |
| 850 | Hello world. |
| 851 | \&.Ed |
| 852 | .Ed |
| 853 | .Pp |
| 854 | See also |
| 855 | .Sx \&D1 |
| 856 | and |
| 857 | .Sx \&Dl . |
| 858 | .Ss \&Bf |
| 859 | Change the font mode for a scoped block of text. |
| 860 | Its syntax is as follows: |
| 861 | .Bd -ragged -offset indent |
| 862 | .Pf \. Sx \&Bf |
| 863 | .Oo |
| 864 | .Fl emphasis | literal | symbolic | |
| 865 | .Cm \&Em | \&Li | \&Sy |
| 866 | .Oc |
| 867 | .Ed |
| 868 | .Pp |
| 869 | The |
| 870 | .Fl emphasis |
| 871 | and |
| 872 | .Cm \&Em |
| 873 | argument are equivalent, as are |
| 874 | .Fl symbolic |
| 875 | and |
| 876 | .Cm \&Sy , |
| 877 | and |
| 878 | .Fl literal |
| 879 | and |
| 880 | .Cm \&Li . |
| 881 | Without an argument, this macro does nothing. |
| 882 | The font mode continues until broken by a new font mode in a nested |
| 883 | scope or |
| 884 | .Sx \&Ef |
| 885 | is encountered. |
| 886 | .Pp |
| 887 | See also |
| 888 | .Sx \&Li , |
| 889 | .Sx \&Ef , |
| 890 | .Sx \&Em , |
| 891 | and |
| 892 | .Sx \&Sy . |
| 893 | .Ss \&Bk |
| 894 | For each macro, keep its output together on the same output line, |
| 895 | until the end of the macro or the end of the input line is reached, |
| 896 | whichever comes first. |
| 897 | Line breaks in text lines are unaffected. |
| 898 | The syntax is as follows: |
| 899 | .Pp |
| 900 | .D1 Pf \. Sx \&Bk Fl words |
| 901 | .Pp |
| 902 | The |
| 903 | .Fl words |
| 904 | argument is required; additional arguments are ignored. |
| 905 | .Pp |
| 906 | The following example will not break within each |
| 907 | .Sx \&Op |
| 908 | macro line: |
| 909 | .Bd -literal -offset indent |
| 910 | \&.Bk \-words |
| 911 | \&.Op Fl f Ar flags |
| 912 | \&.Op Fl o Ar output |
| 913 | \&.Ek |
| 914 | .Ed |
| 915 | .Pp |
| 916 | Be careful in using over-long lines within a keep block! |
| 917 | Doing so will clobber the right margin. |
| 918 | .Ss \&Bl |
| 919 | Begin a list. |
| 920 | Lists consist of items specified using the |
| 921 | .Sx \&It |
| 922 | macro, containing a head or a body or both. |
| 923 | The list syntax is as follows: |
| 924 | .Bd -ragged -offset indent |
| 925 | .Pf \. Sx \&Bl |
| 926 | .Fl Ns Ar type |
| 927 | .Op Fl width Ar val |
| 928 | .Op Fl offset Ar val |
| 929 | .Op Fl compact |
| 930 | .Op HEAD ... |
| 931 | .Ed |
| 932 | .Pp |
| 933 | The list |
| 934 | .Ar type |
| 935 | is mandatory and must be specified first. |
| 936 | The |
| 937 | .Fl width |
| 938 | and |
| 939 | .Fl offset |
| 940 | arguments accept scaling widths as described in |
| 941 | .Xr roff 7 |
| 942 | or use the length of the given string. |
| 943 | The |
| 944 | .Fl offset |
| 945 | is a global indentation for the whole list, affecting both item heads |
| 946 | and bodies. |
| 947 | For those list types supporting it, the |
| 948 | .Fl width |
| 949 | argument requests an additional indentation of item bodies, |
| 950 | to be added to the |
| 951 | .Fl offset . |
| 952 | Unless the |
| 953 | .Fl compact |
| 954 | argument is specified, list entries are separated by vertical space. |
| 955 | .Pp |
| 956 | A list must specify one of the following list types: |
| 957 | .Bl -tag -width 12n -offset indent |
| 958 | .It Fl bullet |
| 959 | No item heads can be specified, but a bullet will be printed at the head |
| 960 | of each item. |
| 961 | Item bodies start on the same output line as the bullet |
| 962 | and are indented according to the |
| 963 | .Fl width |
| 964 | argument. |
| 965 | .It Fl column |
| 966 | A columnated list. |
| 967 | The |
| 968 | .Fl width |
| 969 | argument has no effect; instead, each argument specifies the width |
| 970 | of one column, using either the scaling width syntax described in |
| 971 | .Xr roff 7 |
| 972 | or the string length of the argument. |
| 973 | If the first line of the body of a |
| 974 | .Fl column |
| 975 | list is not an |
| 976 | .Sx \&It |
| 977 | macro line, |
| 978 | .Sx \&It |
| 979 | contexts spanning one input line each are implied until an |
| 980 | .Sx \&It |
| 981 | macro line is encountered, at which point items start being interpreted as |
| 982 | described in the |
| 983 | .Sx \&It |
| 984 | documentation. |
| 985 | .It Fl dash |
| 986 | Like |
| 987 | .Fl bullet , |
| 988 | except that dashes are used in place of bullets. |
| 989 | .It Fl diag |
| 990 | Like |
| 991 | .Fl inset , |
| 992 | except that item heads are not parsed for macro invocations. |
| 993 | Most often used in the |
| 994 | .Em DIAGNOSTICS |
| 995 | section with error constants in the item heads. |
| 996 | .It Fl enum |
| 997 | A numbered list. |
| 998 | No item heads can be specified. |
| 999 | Formatted like |
| 1000 | .Fl bullet , |
| 1001 | except that cardinal numbers are used in place of bullets, |
| 1002 | starting at 1. |
| 1003 | .It Fl hang |
| 1004 | Like |
| 1005 | .Fl tag , |
| 1006 | except that the first lines of item bodies are not indented, but follow |
| 1007 | the item heads like in |
| 1008 | .Fl inset |
| 1009 | lists. |
| 1010 | .It Fl hyphen |
| 1011 | Synonym for |
| 1012 | .Fl dash . |
| 1013 | .It Fl inset |
| 1014 | Item bodies follow items heads on the same line, using normal inter-word |
| 1015 | spacing. |
| 1016 | Bodies are not indented, and the |
| 1017 | .Fl width |
| 1018 | argument is ignored. |
| 1019 | .It Fl item |
| 1020 | No item heads can be specified, and none are printed. |
| 1021 | Bodies are not indented, and the |
| 1022 | .Fl width |
| 1023 | argument is ignored. |
| 1024 | .It Fl ohang |
| 1025 | Item bodies start on the line following item heads and are not indented. |
| 1026 | The |
| 1027 | .Fl width |
| 1028 | argument is ignored. |
| 1029 | .It Fl tag |
| 1030 | Item bodies are indented according to the |
| 1031 | .Fl width |
| 1032 | argument. |
| 1033 | When an item head fits inside the indentation, the item body follows |
| 1034 | this head on the same output line. |
| 1035 | Otherwise, the body starts on the output line following the head. |
| 1036 | .El |
| 1037 | .Pp |
| 1038 | Lists may be nested within lists and displays. |
| 1039 | Nesting of |
| 1040 | .Fl column |
| 1041 | and |
| 1042 | .Fl enum |
| 1043 | lists may not be portable. |
| 1044 | .Pp |
| 1045 | See also |
| 1046 | .Sx \&El |
| 1047 | and |
| 1048 | .Sx \&It . |
| 1049 | .Ss \&Bo |
| 1050 | Begin a block enclosed by square brackets. |
| 1051 | Does not have any head arguments. |
| 1052 | .Pp |
| 1053 | Examples: |
| 1054 | .Bd -literal -offset indent -compact |
| 1055 | \&.Bo 1 , |
| 1056 | \&.Dv BUFSIZ \&Bc |
| 1057 | .Ed |
| 1058 | .Pp |
| 1059 | See also |
| 1060 | .Sx \&Bq . |
| 1061 | .Ss \&Bq |
| 1062 | Encloses its arguments in square brackets. |
| 1063 | .Pp |
| 1064 | Examples: |
| 1065 | .Dl \&.Bq 1 , \&Dv BUFSIZ |
| 1066 | .Pp |
| 1067 | .Em Remarks : |
| 1068 | this macro is sometimes abused to emulate optional arguments for |
| 1069 | commands; the correct macros to use for this purpose are |
| 1070 | .Sx \&Op , |
| 1071 | .Sx \&Oo , |
| 1072 | and |
| 1073 | .Sx \&Oc . |
| 1074 | .Pp |
| 1075 | See also |
| 1076 | .Sx \&Bo . |
| 1077 | .Ss \&Brc |
| 1078 | Close a |
| 1079 | .Sx \&Bro |
| 1080 | block. |
| 1081 | Does not have any tail arguments. |
| 1082 | .Ss \&Bro |
| 1083 | Begin a block enclosed by curly braces. |
| 1084 | Does not have any head arguments. |
| 1085 | .Pp |
| 1086 | Examples: |
| 1087 | .Bd -literal -offset indent -compact |
| 1088 | \&.Bro 1 , ... , |
| 1089 | \&.Va n \&Brc |
| 1090 | .Ed |
| 1091 | .Pp |
| 1092 | See also |
| 1093 | .Sx \&Brq . |
| 1094 | .Ss \&Brq |
| 1095 | Encloses its arguments in curly braces. |
| 1096 | .Pp |
| 1097 | Examples: |
| 1098 | .Dl \&.Brq 1 , ... , \&Va n |
| 1099 | .Pp |
| 1100 | See also |
| 1101 | .Sx \&Bro . |
| 1102 | .Ss \&Bsx |
| 1103 | Format the |
| 1104 | .Bsx |
| 1105 | version provided as an argument, or a default value if |
| 1106 | no argument is provided. |
| 1107 | .Pp |
| 1108 | Examples: |
| 1109 | .Dl \&.Bsx 1.0 |
| 1110 | .Dl \&.Bsx |
| 1111 | .Pp |
| 1112 | See also |
| 1113 | .Sx \&At , |
| 1114 | .Sx \&Bx , |
| 1115 | .Sx \&Dx , |
| 1116 | .Sx \&Fx , |
| 1117 | .Sx \&Nx , |
| 1118 | and |
| 1119 | .Sx \&Ox . |
| 1120 | .Ss \&Bt |
| 1121 | Supported only for compatibility, do not use this in new manuals. |
| 1122 | Prints |
| 1123 | .Dq is currently in beta test. |
| 1124 | .Ss \&Bx |
| 1125 | Format the |
| 1126 | .Bx |
| 1127 | version provided as an argument, or a default value if no |
| 1128 | argument is provided. |
| 1129 | .Pp |
| 1130 | Examples: |
| 1131 | .Dl \&.Bx 4.3 Tahoe |
| 1132 | .Dl \&.Bx 4.4 |
| 1133 | .Dl \&.Bx |
| 1134 | .Pp |
| 1135 | See also |
| 1136 | .Sx \&At , |
| 1137 | .Sx \&Bsx , |
| 1138 | .Sx \&Dx , |
| 1139 | .Sx \&Fx , |
| 1140 | .Sx \&Nx , |
| 1141 | and |
| 1142 | .Sx \&Ox . |
| 1143 | .Ss \&Cd |
| 1144 | Kernel configuration declaration. |
| 1145 | This denotes strings accepted by |
| 1146 | .Xr config 8 . |
| 1147 | It is most often used in section 4 manual pages. |
| 1148 | .Pp |
| 1149 | Examples: |
| 1150 | .Dl \&.Cd device le0 at scode? |
| 1151 | .Pp |
| 1152 | .Em Remarks : |
| 1153 | this macro is commonly abused by using quoted literals to retain |
| 1154 | whitespace and align consecutive |
| 1155 | .Sx \&Cd |
| 1156 | declarations. |
| 1157 | This practise is discouraged. |
| 1158 | .Ss \&Cm |
| 1159 | Command modifiers. |
| 1160 | Typically used for fixed strings passed as arguments, unless |
| 1161 | .Sx \&Fl |
| 1162 | is more appropriate. |
| 1163 | Also useful when specifying configuration options or keys. |
| 1164 | .Pp |
| 1165 | Examples: |
| 1166 | .Dl ".Nm mt Fl f Ar device Cm rewind" |
| 1167 | .Dl ".Nm ps Fl o Cm pid , Ns Cm command" |
| 1168 | .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" |
| 1169 | .Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa" |
| 1170 | .Dl ".Cm LogLevel Dv DEBUG" |
| 1171 | .Ss \&D1 |
| 1172 | One-line indented display. |
| 1173 | This is formatted by the default rules and is useful for simple indented |
| 1174 | statements. |
| 1175 | It is followed by a newline. |
| 1176 | .Pp |
| 1177 | Examples: |
| 1178 | .Dl \&.D1 \&Fl abcdefgh |
| 1179 | .Pp |
| 1180 | See also |
| 1181 | .Sx \&Bd |
| 1182 | and |
| 1183 | .Sx \&Dl . |
| 1184 | .Ss \&Db |
| 1185 | Switch debugging mode. |
| 1186 | Its syntax is as follows: |
| 1187 | .Pp |
| 1188 | .D1 Pf \. Sx \&Db Cm on | off |
| 1189 | .Pp |
| 1190 | This macro is ignored by |
| 1191 | .Xr mandoc 1 . |
| 1192 | .Ss \&Dc |
| 1193 | Close a |
| 1194 | .Sx \&Do |
| 1195 | block. |
| 1196 | Does not have any tail arguments. |
| 1197 | .Ss \&Dd |
| 1198 | Document date for display in the page footer. |
| 1199 | This is the mandatory first macro of any |
| 1200 | .Nm |
| 1201 | manual. |
| 1202 | Its syntax is as follows: |
| 1203 | .Pp |
| 1204 | .D1 Pf \. Sx \&Dd Ar month day , year |
| 1205 | .Pp |
| 1206 | The |
| 1207 | .Ar month |
| 1208 | is the full English month name, the |
| 1209 | .Ar day |
| 1210 | is an optionally zero-padded numeral, and the |
| 1211 | .Ar year |
| 1212 | is the full four-digit year. |
| 1213 | .Pp |
| 1214 | Other arguments are not portable; the |
| 1215 | .Xr mandoc 1 |
| 1216 | utility handles them as follows: |
| 1217 | .Bl -dash -offset 3n -compact |
| 1218 | .It |
| 1219 | To have the date automatically filled in by the |
| 1220 | .Ox |
| 1221 | version of |
| 1222 | .Xr cvs 1 , |
| 1223 | the special string |
| 1224 | .Dq $\&Mdocdate$ |
| 1225 | can be given as an argument. |
| 1226 | .It |
| 1227 | The traditional, purely numeric |
| 1228 | .Xr man 7 |
| 1229 | format |
| 1230 | .Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day |
| 1231 | is accepted, too. |
| 1232 | .It |
| 1233 | If a date string cannot be parsed, it is used verbatim. |
| 1234 | .It |
| 1235 | If no date string is given, the current date is used. |
| 1236 | .El |
| 1237 | .Pp |
| 1238 | Examples: |
| 1239 | .Dl \&.Dd $\&Mdocdate$ |
| 1240 | .Dl \&.Dd $\&Mdocdate: July 21 2007$ |
| 1241 | .Dl \&.Dd July 21, 2007 |
| 1242 | .Pp |
| 1243 | See also |
| 1244 | .Sx \&Dt |
| 1245 | and |
| 1246 | .Sx \&Os . |
| 1247 | .Ss \&Dl |
| 1248 | One-line intended display. |
| 1249 | This is formatted as literal text and is useful for commands and |
| 1250 | invocations. |
| 1251 | It is followed by a newline. |
| 1252 | .Pp |
| 1253 | Examples: |
| 1254 | .Dl \&.Dl % mandoc mdoc.7 \e(ba less |
| 1255 | .Pp |
| 1256 | See also |
| 1257 | .Sx \&Bd |
| 1258 | and |
| 1259 | .Sx \&D1 . |
| 1260 | .Ss \&Do |
| 1261 | Begin a block enclosed by double quotes. |
| 1262 | Does not have any head arguments. |
| 1263 | .Pp |
| 1264 | Examples: |
| 1265 | .Bd -literal -offset indent -compact |
| 1266 | \&.Do |
| 1267 | April is the cruellest month |
| 1268 | \&.Dc |
| 1269 | \e(em T.S. Eliot |
| 1270 | .Ed |
| 1271 | .Pp |
| 1272 | See also |
| 1273 | .Sx \&Dq . |
| 1274 | .Ss \&Dq |
| 1275 | Encloses its arguments in |
| 1276 | .Dq typographic |
| 1277 | double-quotes. |
| 1278 | .Pp |
| 1279 | Examples: |
| 1280 | .Bd -literal -offset indent -compact |
| 1281 | \&.Dq April is the cruellest month |
| 1282 | \e(em T.S. Eliot |
| 1283 | .Ed |
| 1284 | .Pp |
| 1285 | See also |
| 1286 | .Sx \&Qq , |
| 1287 | .Sx \&Sq , |
| 1288 | and |
| 1289 | .Sx \&Do . |
| 1290 | .Ss \&Dt |
| 1291 | Document title for display in the page header. |
| 1292 | This is the mandatory second macro of any |
| 1293 | .Nm |
| 1294 | file. |
| 1295 | Its syntax is as follows: |
| 1296 | .Bd -ragged -offset indent |
| 1297 | .Pf \. Sx \&Dt |
| 1298 | .Ar TITLE |
| 1299 | .Ar section |
| 1300 | .Op Ar volume | arch |
| 1301 | .Ed |
| 1302 | .Pp |
| 1303 | Its arguments are as follows: |
| 1304 | .Bl -tag -width section -offset 2n |
| 1305 | .It Ar TITLE |
| 1306 | The document's title (name), defaulting to |
| 1307 | .Dq UNTITLED |
| 1308 | if unspecified. |
| 1309 | To achieve a uniform appearance of page header lines, |
| 1310 | it should by convention be all caps. |
| 1311 | .It Ar section |
| 1312 | The manual section. |
| 1313 | This may be one of |
| 1314 | .Cm 1 |
| 1315 | .Pq utilities , |
| 1316 | .Cm 2 |
| 1317 | .Pq system calls , |
| 1318 | .Cm 3 |
| 1319 | .Pq libraries , |
| 1320 | .Cm 3p |
| 1321 | .Pq Perl libraries , |
| 1322 | .Cm 4 |
| 1323 | .Pq devices , |
| 1324 | .Cm 5 |
| 1325 | .Pq file formats , |
| 1326 | .Cm 6 |
| 1327 | .Pq games , |
| 1328 | .Cm 7 |
| 1329 | .Pq miscellaneous , |
| 1330 | .Cm 8 |
| 1331 | .Pq system utilities , |
| 1332 | .Cm 9 |
| 1333 | .Pq kernel functions , |
| 1334 | .Cm X11 |
| 1335 | .Pq X Window System , |
| 1336 | .Cm X11R6 |
| 1337 | .Pq X Window System , |
| 1338 | .Cm unass |
| 1339 | .Pq unassociated , |
| 1340 | .Cm local |
| 1341 | .Pq local system , |
| 1342 | .Cm draft |
| 1343 | .Pq draft manual , |
| 1344 | or |
| 1345 | .Cm paper |
| 1346 | .Pq paper . |
| 1347 | It should correspond to the manual's filename suffix and defaults to |
| 1348 | the empty string if unspecified. |
| 1349 | .It Ar volume |
| 1350 | This overrides the volume inferred from |
| 1351 | .Ar section . |
| 1352 | This field is optional, and if specified, must be one of |
| 1353 | .Cm USD |
| 1354 | .Pq users' supplementary documents , |
| 1355 | .Cm PS1 |
| 1356 | .Pq programmers' supplementary documents , |
| 1357 | .Cm AMD |
| 1358 | .Pq administrators' supplementary documents , |
| 1359 | .Cm SMM |
| 1360 | .Pq system managers' manuals , |
| 1361 | .Cm URM |
| 1362 | .Pq users' reference manuals , |
| 1363 | .Cm PRM |
| 1364 | .Pq programmers' reference manuals , |
| 1365 | .Cm KM |
| 1366 | .Pq kernel manuals , |
| 1367 | .Cm IND |
| 1368 | .Pq master index , |
| 1369 | .Cm MMI |
| 1370 | .Pq master index , |
| 1371 | .Cm LOCAL |
| 1372 | .Pq local manuals , |
| 1373 | .Cm LOC |
| 1374 | .Pq local manuals , |
| 1375 | or |
| 1376 | .Cm CON |
| 1377 | .Pq contributed manuals . |
| 1378 | .It Ar arch |
| 1379 | This specifies the machine architecture a manual page applies to, |
| 1380 | where relevant, for example |
| 1381 | .Cm alpha , |
| 1382 | .Cm amd64 , |
| 1383 | .Cm i386 , |
| 1384 | or |
| 1385 | .Cm sparc64 . |
| 1386 | The list of supported architectures varies by operating system. |
| 1387 | For the full list of all architectures recognized by |
| 1388 | .Xr mandoc 1 , |
| 1389 | see the file |
| 1390 | .Pa arch.in |
| 1391 | in the source distribution. |
| 1392 | .El |
| 1393 | .Pp |
| 1394 | Examples: |
| 1395 | .Dl \&.Dt FOO 1 |
| 1396 | .Dl \&.Dt FOO 4 KM |
| 1397 | .Dl \&.Dt FOO 9 i386 |
| 1398 | .Pp |
| 1399 | See also |
| 1400 | .Sx \&Dd |
| 1401 | and |
| 1402 | .Sx \&Os . |
| 1403 | .Ss \&Dv |
| 1404 | Defined variables such as preprocessor constants, constant symbols, |
| 1405 | enumeration values, and so on. |
| 1406 | .Pp |
| 1407 | Examples: |
| 1408 | .Dl \&.Dv NULL |
| 1409 | .Dl \&.Dv BUFSIZ |
| 1410 | .Dl \&.Dv STDOUT_FILENO |
| 1411 | .Pp |
| 1412 | See also |
| 1413 | .Sx \&Er |
| 1414 | and |
| 1415 | .Sx \&Ev |
| 1416 | for special-purpose constants, |
| 1417 | .Sx \&Va |
| 1418 | for variable symbols, and |
| 1419 | .Sx \&Fd |
| 1420 | for listing preprocessor variable definitions in the |
| 1421 | .Em SYNOPSIS . |
| 1422 | .Ss \&Dx |
| 1423 | Format the |
| 1424 | .Dx |
| 1425 | version provided as an argument, or a default |
| 1426 | value if no argument is provided. |
| 1427 | .Pp |
| 1428 | Examples: |
| 1429 | .Dl \&.Dx 2.4.1 |
| 1430 | .Dl \&.Dx |
| 1431 | .Pp |
| 1432 | See also |
| 1433 | .Sx \&At , |
| 1434 | .Sx \&Bsx , |
| 1435 | .Sx \&Bx , |
| 1436 | .Sx \&Fx , |
| 1437 | .Sx \&Nx , |
| 1438 | and |
| 1439 | .Sx \&Ox . |
| 1440 | .Ss \&Ec |
| 1441 | Close a scope started by |
| 1442 | .Sx \&Eo . |
| 1443 | Its syntax is as follows: |
| 1444 | .Pp |
| 1445 | .D1 Pf \. Sx \&Ec Op Ar TERM |
| 1446 | .Pp |
| 1447 | The |
| 1448 | .Ar TERM |
| 1449 | argument is used as the enclosure tail, for example, specifying \e(rq |
| 1450 | will emulate |
| 1451 | .Sx \&Dc . |
| 1452 | .Ss \&Ed |
| 1453 | End a display context started by |
| 1454 | .Sx \&Bd . |
| 1455 | .Ss \&Ef |
| 1456 | End a font mode context started by |
| 1457 | .Sx \&Bf . |
| 1458 | .Ss \&Ek |
| 1459 | End a keep context started by |
| 1460 | .Sx \&Bk . |
| 1461 | .Ss \&El |
| 1462 | End a list context started by |
| 1463 | .Sx \&Bl . |
| 1464 | .Pp |
| 1465 | See also |
| 1466 | .Sx \&Bl |
| 1467 | and |
| 1468 | .Sx \&It . |
| 1469 | .Ss \&Em |
| 1470 | Denotes text that should be |
| 1471 | .Em emphasised . |
| 1472 | Note that this is a presentation term and should not be used for |
| 1473 | stylistically decorating technical terms. |
| 1474 | Depending on the output device, this is usually represented |
| 1475 | using an italic font or underlined characters. |
| 1476 | .Pp |
| 1477 | Examples: |
| 1478 | .Dl \&.Em Warnings! |
| 1479 | .Dl \&.Em Remarks : |
| 1480 | .Pp |
| 1481 | See also |
| 1482 | .Sx \&Bf , |
| 1483 | .Sx \&Li , |
| 1484 | .Sx \&No , |
| 1485 | and |
| 1486 | .Sx \&Sy . |
| 1487 | .Ss \&En |
| 1488 | This macro is obsolete. |
| 1489 | Use |
| 1490 | .Sx \&Eo |
| 1491 | or any of the other enclosure macros. |
| 1492 | .Pp |
| 1493 | It encloses its argument in the delimiters specified by the last |
| 1494 | .Sx \&Es |
| 1495 | macro. |
| 1496 | .Ss \&Eo |
| 1497 | An arbitrary enclosure. |
| 1498 | Its syntax is as follows: |
| 1499 | .Pp |
| 1500 | .D1 Pf \. Sx \&Eo Op Ar TERM |
| 1501 | .Pp |
| 1502 | The |
| 1503 | .Ar TERM |
| 1504 | argument is used as the enclosure head, for example, specifying \e(lq |
| 1505 | will emulate |
| 1506 | .Sx \&Do . |
| 1507 | .Ss \&Er |
| 1508 | Error constants for definitions of the |
| 1509 | .Va errno |
| 1510 | libc global variable. |
| 1511 | This is most often used in section 2 and 3 manual pages. |
| 1512 | .Pp |
| 1513 | Examples: |
| 1514 | .Dl \&.Er EPERM |
| 1515 | .Dl \&.Er ENOENT |
| 1516 | .Pp |
| 1517 | See also |
| 1518 | .Sx \&Dv |
| 1519 | for general constants. |
| 1520 | .Ss \&Es |
| 1521 | This macro is obsolete. |
| 1522 | Use |
| 1523 | .Sx \&Eo |
| 1524 | or any of the other enclosure macros. |
| 1525 | .Pp |
| 1526 | It takes two arguments, defining the delimiters to be used by subsequent |
| 1527 | .Sx \&En |
| 1528 | macros. |
| 1529 | .Ss \&Ev |
| 1530 | Environmental variables such as those specified in |
| 1531 | .Xr environ 7 . |
| 1532 | .Pp |
| 1533 | Examples: |
| 1534 | .Dl \&.Ev DISPLAY |
| 1535 | .Dl \&.Ev PATH |
| 1536 | .Pp |
| 1537 | See also |
| 1538 | .Sx \&Dv |
| 1539 | for general constants. |
| 1540 | .Ss \&Ex |
| 1541 | Insert a standard sentence regarding command exit values of 0 on success |
| 1542 | and >0 on failure. |
| 1543 | This is most often used in section 1, 6, and 8 manual pages. |
| 1544 | Its syntax is as follows: |
| 1545 | .Pp |
| 1546 | .D1 Pf \. Sx \&Ex Fl std Op Ar utility ... |
| 1547 | .Pp |
| 1548 | If |
| 1549 | .Ar utility |
| 1550 | is not specified, the document's name set by |
| 1551 | .Sx \&Nm |
| 1552 | is used. |
| 1553 | Multiple |
| 1554 | .Ar utility |
| 1555 | arguments are treated as separate utilities. |
| 1556 | .Pp |
| 1557 | See also |
| 1558 | .Sx \&Rv . |
| 1559 | .Ss \&Fa |
| 1560 | Function argument. |
| 1561 | Its syntax is as follows: |
| 1562 | .Bd -ragged -offset indent |
| 1563 | .Pf \. Sx \&Fa |
| 1564 | .Qo |
| 1565 | .Op Ar argtype |
| 1566 | .Op Ar argname |
| 1567 | .Qc Ar \&... |
| 1568 | .Ed |
| 1569 | .Pp |
| 1570 | Each argument may be a name and a type (recommended for the |
| 1571 | .Em SYNOPSIS |
| 1572 | section), a name alone (for function invocations), |
| 1573 | or a type alone (for function prototypes). |
| 1574 | If both a type and a name are given or if the type consists of multiple |
| 1575 | words, all words belonging to the same function argument have to be |
| 1576 | given in a single argument to the |
| 1577 | .Sx \&Fa |
| 1578 | macro. |
| 1579 | .Pp |
| 1580 | This macro is also used to specify the field name of a structure. |
| 1581 | .Pp |
| 1582 | Most often, the |
| 1583 | .Sx \&Fa |
| 1584 | macro is used in the |
| 1585 | .Em SYNOPSIS |
| 1586 | within |
| 1587 | .Sx \&Fo |
| 1588 | blocks when documenting multi-line function prototypes. |
| 1589 | If invoked with multiple arguments, the arguments are separated by a |
| 1590 | comma. |
| 1591 | Furthermore, if the following macro is another |
| 1592 | .Sx \&Fa , |
| 1593 | the last argument will also have a trailing comma. |
| 1594 | .Pp |
| 1595 | Examples: |
| 1596 | .Dl \&.Fa \(dqconst char *p\(dq |
| 1597 | .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq |
| 1598 | .Dl \&.Fa \(dqchar *\(dq size_t |
| 1599 | .Pp |
| 1600 | See also |
| 1601 | .Sx \&Fo . |
| 1602 | .Ss \&Fc |
| 1603 | End a function context started by |
| 1604 | .Sx \&Fo . |
| 1605 | .Ss \&Fd |
| 1606 | Preprocessor directive, in particular for listing it in the |
| 1607 | .Em SYNOPSIS . |
| 1608 | Historically, it was also used to document include files. |
| 1609 | The latter usage has been deprecated in favour of |
| 1610 | .Sx \&In . |
| 1611 | .Pp |
| 1612 | Its syntax is as follows: |
| 1613 | .Bd -ragged -offset indent |
| 1614 | .Pf \. Sx \&Fd |
| 1615 | .Li # Ns Ar directive |
| 1616 | .Op Ar argument ... |
| 1617 | .Ed |
| 1618 | .Pp |
| 1619 | Examples: |
| 1620 | .Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler |
| 1621 | .Dl \&.Fd #define SIO_MAXNFDS |
| 1622 | .Dl \&.Fd #ifdef FS_DEBUG |
| 1623 | .Dl \&.Ft void |
| 1624 | .Dl \&.Fn dbg_open \(dqconst char *\(dq |
| 1625 | .Dl \&.Fd #endif |
| 1626 | .Pp |
| 1627 | See also |
| 1628 | .Sx MANUAL STRUCTURE , |
| 1629 | .Sx \&In , |
| 1630 | and |
| 1631 | .Sx \&Dv . |
| 1632 | .Ss \&Fl |
| 1633 | Command-line flag or option. |
| 1634 | Used when listing arguments to command-line utilities. |
| 1635 | Prints a fixed-width hyphen |
| 1636 | .Sq \- |
| 1637 | directly followed by each argument. |
| 1638 | If no arguments are provided, a hyphen is printed followed by a space. |
| 1639 | If the argument is a macro, a hyphen is prefixed to the subsequent macro |
| 1640 | output. |
| 1641 | .Pp |
| 1642 | Examples: |
| 1643 | .Dl ".Fl R Op Fl H | L | P" |
| 1644 | .Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" |
| 1645 | .Dl ".Fl type Cm d Fl name Pa CVS" |
| 1646 | .Dl ".Fl Ar signal_number" |
| 1647 | .Dl ".Fl o Fl" |
| 1648 | .Pp |
| 1649 | See also |
| 1650 | .Sx \&Cm . |
| 1651 | .Ss \&Fn |
| 1652 | A function name. |
| 1653 | Its syntax is as follows: |
| 1654 | .Bd -ragged -offset indent |
| 1655 | .Pf \. Ns Sx \&Fn |
| 1656 | .Op Ar functype |
| 1657 | .Ar funcname |
| 1658 | .Op Oo Ar argtype Oc Ar argname |
| 1659 | .Ed |
| 1660 | .Pp |
| 1661 | Function arguments are surrounded in parenthesis and |
| 1662 | are delimited by commas. |
| 1663 | If no arguments are specified, blank parenthesis are output. |
| 1664 | In the |
| 1665 | .Em SYNOPSIS |
| 1666 | section, this macro starts a new output line, |
| 1667 | and a blank line is automatically inserted between function definitions. |
| 1668 | .Pp |
| 1669 | Examples: |
| 1670 | .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq |
| 1671 | .Dl \&.Fn funcname \(dqint arg0\(dq |
| 1672 | .Dl \&.Fn funcname arg0 |
| 1673 | .Pp |
| 1674 | .Bd -literal -offset indent -compact |
| 1675 | \&.Ft functype |
| 1676 | \&.Fn funcname |
| 1677 | .Ed |
| 1678 | .Pp |
| 1679 | When referring to a function documented in another manual page, use |
| 1680 | .Sx \&Xr |
| 1681 | instead. |
| 1682 | See also |
| 1683 | .Sx MANUAL STRUCTURE , |
| 1684 | .Sx \&Fo , |
| 1685 | and |
| 1686 | .Sx \&Ft . |
| 1687 | .Ss \&Fo |
| 1688 | Begin a function block. |
| 1689 | This is a multi-line version of |
| 1690 | .Sx \&Fn . |
| 1691 | Its syntax is as follows: |
| 1692 | .Pp |
| 1693 | .D1 Pf \. Sx \&Fo Ar funcname |
| 1694 | .Pp |
| 1695 | Invocations usually occur in the following context: |
| 1696 | .Bd -ragged -offset indent |
| 1697 | .Pf \. Sx \&Ft Ar functype |
| 1698 | .br |
| 1699 | .Pf \. Sx \&Fo Ar funcname |
| 1700 | .br |
| 1701 | .Pf \. Sx \&Fa Qq Ar argtype Ar argname |
| 1702 | .br |
| 1703 | \&.\.\. |
| 1704 | .br |
| 1705 | .Pf \. Sx \&Fc |
| 1706 | .Ed |
| 1707 | .Pp |
| 1708 | A |
| 1709 | .Sx \&Fo |
| 1710 | scope is closed by |
| 1711 | .Sx \&Fc . |
| 1712 | .Pp |
| 1713 | See also |
| 1714 | .Sx MANUAL STRUCTURE , |
| 1715 | .Sx \&Fa , |
| 1716 | .Sx \&Fc , |
| 1717 | and |
| 1718 | .Sx \&Ft . |
| 1719 | .Ss \&Fr |
| 1720 | This macro is obsolete. |
| 1721 | No replacement markup is needed. |
| 1722 | .Pp |
| 1723 | It was used to show numerical function return values in an italic font. |
| 1724 | .Ss \&Ft |
| 1725 | A function type. |
| 1726 | Its syntax is as follows: |
| 1727 | .Pp |
| 1728 | .D1 Pf \. Sx \&Ft Ar functype |
| 1729 | .Pp |
| 1730 | In the |
| 1731 | .Em SYNOPSIS |
| 1732 | section, a new output line is started after this macro. |
| 1733 | .Pp |
| 1734 | Examples: |
| 1735 | .Dl \&.Ft int |
| 1736 | .Bd -literal -offset indent -compact |
| 1737 | \&.Ft functype |
| 1738 | \&.Fn funcname |
| 1739 | .Ed |
| 1740 | .Pp |
| 1741 | See also |
| 1742 | .Sx MANUAL STRUCTURE , |
| 1743 | .Sx \&Fn , |
| 1744 | and |
| 1745 | .Sx \&Fo . |
| 1746 | .Ss \&Fx |
| 1747 | Format the |
| 1748 | .Fx |
| 1749 | version provided as an argument, or a default value |
| 1750 | if no argument is provided. |
| 1751 | .Pp |
| 1752 | Examples: |
| 1753 | .Dl \&.Fx 7.1 |
| 1754 | .Dl \&.Fx |
| 1755 | .Pp |
| 1756 | See also |
| 1757 | .Sx \&At , |
| 1758 | .Sx \&Bsx , |
| 1759 | .Sx \&Bx , |
| 1760 | .Sx \&Dx , |
| 1761 | .Sx \&Nx , |
| 1762 | and |
| 1763 | .Sx \&Ox . |
| 1764 | .Ss \&Hf |
| 1765 | This macro is not implemented in |
| 1766 | .Xr mandoc 1 . |
| 1767 | .Pp |
| 1768 | It was used to include the contents of a (header) file literally. |
| 1769 | The syntax was: |
| 1770 | .Pp |
| 1771 | .Dl Pf . Sx \&Hf Ar filename |
| 1772 | .Ss \&Ic |
| 1773 | Designate an internal or interactive command. |
| 1774 | This is similar to |
| 1775 | .Sx \&Cm |
| 1776 | but used for instructions rather than values. |
| 1777 | .Pp |
| 1778 | Examples: |
| 1779 | .Dl \&.Ic :wq |
| 1780 | .Dl \&.Ic hash |
| 1781 | .Dl \&.Ic alias |
| 1782 | .Pp |
| 1783 | Note that using |
| 1784 | .Sx \&Bd Fl literal |
| 1785 | or |
| 1786 | .Sx \&D1 |
| 1787 | is preferred for displaying code; the |
| 1788 | .Sx \&Ic |
| 1789 | macro is used when referring to specific instructions. |
| 1790 | .Ss \&In |
| 1791 | An |
| 1792 | .Dq include |
| 1793 | file. |
| 1794 | When invoked as the first macro on an input line in the |
| 1795 | .Em SYNOPSIS |
| 1796 | section, the argument is displayed in angle brackets |
| 1797 | and preceded by |
| 1798 | .Dq #include , |
| 1799 | and a blank line is inserted in front if there is a preceding |
| 1800 | function declaration. |
| 1801 | This is most often used in section 2, 3, and 9 manual pages. |
| 1802 | .Pp |
| 1803 | Examples: |
| 1804 | .Dl \&.In sys/types.h |
| 1805 | .Pp |
| 1806 | See also |
| 1807 | .Sx MANUAL STRUCTURE . |
| 1808 | .Ss \&It |
| 1809 | A list item. |
| 1810 | The syntax of this macro depends on the list type. |
| 1811 | .Pp |
| 1812 | Lists |
| 1813 | of type |
| 1814 | .Fl hang , |
| 1815 | .Fl ohang , |
| 1816 | .Fl inset , |
| 1817 | and |
| 1818 | .Fl diag |
| 1819 | have the following syntax: |
| 1820 | .Pp |
| 1821 | .D1 Pf \. Sx \&It Ar args |
| 1822 | .Pp |
| 1823 | Lists of type |
| 1824 | .Fl bullet , |
| 1825 | .Fl dash , |
| 1826 | .Fl enum , |
| 1827 | .Fl hyphen |
| 1828 | and |
| 1829 | .Fl item |
| 1830 | have the following syntax: |
| 1831 | .Pp |
| 1832 | .D1 Pf \. Sx \&It |
| 1833 | .Pp |
| 1834 | with subsequent lines interpreted within the scope of the |
| 1835 | .Sx \&It |
| 1836 | until either a closing |
| 1837 | .Sx \&El |
| 1838 | or another |
| 1839 | .Sx \&It . |
| 1840 | .Pp |
| 1841 | The |
| 1842 | .Fl tag |
| 1843 | list has the following syntax: |
| 1844 | .Pp |
| 1845 | .D1 Pf \. Sx \&It Op Cm args |
| 1846 | .Pp |
| 1847 | Subsequent lines are interpreted as with |
| 1848 | .Fl bullet |
| 1849 | and family. |
| 1850 | The line arguments correspond to the list's left-hand side; body |
| 1851 | arguments correspond to the list's contents. |
| 1852 | .Pp |
| 1853 | The |
| 1854 | .Fl column |
| 1855 | list is the most complicated. |
| 1856 | Its syntax is as follows: |
| 1857 | .Pp |
| 1858 | .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ... |
| 1859 | .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... |
| 1860 | .Pp |
| 1861 | The arguments consist of one or more lines of text and macros |
| 1862 | representing a complete table line. |
| 1863 | Cells within the line are delimited by tabs or by the special |
| 1864 | .Sx \&Ta |
| 1865 | block macro. |
| 1866 | The tab cell delimiter may only be used within the |
| 1867 | .Sx \&It |
| 1868 | line itself; on following lines, only the |
| 1869 | .Sx \&Ta |
| 1870 | macro can be used to delimit cells, and |
| 1871 | .Sx \&Ta |
| 1872 | is only recognised as a macro when called by other macros, |
| 1873 | not as the first macro on a line. |
| 1874 | .Pp |
| 1875 | Note that quoted strings may span tab-delimited cells on an |
| 1876 | .Sx \&It |
| 1877 | line. |
| 1878 | For example, |
| 1879 | .Pp |
| 1880 | .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; |
| 1881 | .Pp |
| 1882 | will preserve the semicolon whitespace except for the last. |
| 1883 | .Pp |
| 1884 | See also |
| 1885 | .Sx \&Bl . |
| 1886 | .Ss \&Lb |
| 1887 | Specify a library. |
| 1888 | The syntax is as follows: |
| 1889 | .Pp |
| 1890 | .D1 Pf \. Sx \&Lb Ar library |
| 1891 | .Pp |
| 1892 | The |
| 1893 | .Ar library |
| 1894 | parameter may be a system library, such as |
| 1895 | .Cm libz |
| 1896 | or |
| 1897 | .Cm libpam , |
| 1898 | in which case a small library description is printed next to the linker |
| 1899 | invocation; or a custom library, in which case the library name is |
| 1900 | printed in quotes. |
| 1901 | This is most commonly used in the |
| 1902 | .Em SYNOPSIS |
| 1903 | section as described in |
| 1904 | .Sx MANUAL STRUCTURE . |
| 1905 | .Pp |
| 1906 | Examples: |
| 1907 | .Dl \&.Lb libz |
| 1908 | .Dl \&.Lb libmandoc |
| 1909 | .Ss \&Li |
| 1910 | Denotes text that should be in a |
| 1911 | .Li literal |
| 1912 | font mode. |
| 1913 | Note that this is a presentation term and should not be used for |
| 1914 | stylistically decorating technical terms. |
| 1915 | .Pp |
| 1916 | On terminal output devices, this is often indistinguishable from |
| 1917 | normal text. |
| 1918 | .Pp |
| 1919 | See also |
| 1920 | .Sx \&Bf , |
| 1921 | .Sx \&Em , |
| 1922 | .Sx \&No , |
| 1923 | and |
| 1924 | .Sx \&Sy . |
| 1925 | .Ss \&Lk |
| 1926 | Format a hyperlink. |
| 1927 | Its syntax is as follows: |
| 1928 | .Pp |
| 1929 | .D1 Pf \. Sx \&Lk Ar uri Op Ar name |
| 1930 | .Pp |
| 1931 | Examples: |
| 1932 | .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq |
| 1933 | .Dl \&.Lk http://bsd.lv |
| 1934 | .Pp |
| 1935 | See also |
| 1936 | .Sx \&Mt . |
| 1937 | .Ss \&Lp |
| 1938 | Synonym for |
| 1939 | .Sx \&Pp . |
| 1940 | .Ss \&Ms |
| 1941 | Display a mathematical symbol. |
| 1942 | Its syntax is as follows: |
| 1943 | .Pp |
| 1944 | .D1 Pf \. Sx \&Ms Ar symbol |
| 1945 | .Pp |
| 1946 | Examples: |
| 1947 | .Dl \&.Ms sigma |
| 1948 | .Dl \&.Ms aleph |
| 1949 | .Ss \&Mt |
| 1950 | Format a |
| 1951 | .Dq mailto: |
| 1952 | hyperlink. |
| 1953 | Its syntax is as follows: |
| 1954 | .Pp |
| 1955 | .D1 Pf \. Sx \&Mt Ar address |
| 1956 | .Pp |
| 1957 | Examples: |
| 1958 | .Dl \&.Mt discuss@manpages.bsd.lv |
| 1959 | .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv |
| 1960 | .Ss \&Nd |
| 1961 | A one line description of the manual's content. |
| 1962 | This may only be invoked in the |
| 1963 | .Em SYNOPSIS |
| 1964 | section subsequent the |
| 1965 | .Sx \&Nm |
| 1966 | macro. |
| 1967 | .Pp |
| 1968 | Examples: |
| 1969 | .Dl Pf . Sx \&Nd mdoc language reference |
| 1970 | .Dl Pf . Sx \&Nd format and display UNIX manuals |
| 1971 | .Pp |
| 1972 | The |
| 1973 | .Sx \&Nd |
| 1974 | macro technically accepts child macros and terminates with a subsequent |
| 1975 | .Sx \&Sh |
| 1976 | invocation. |
| 1977 | Do not assume this behaviour: some |
| 1978 | .Xr whatis 1 |
| 1979 | database generators are not smart enough to parse more than the line |
| 1980 | arguments and will display macros verbatim. |
| 1981 | .Pp |
| 1982 | See also |
| 1983 | .Sx \&Nm . |
| 1984 | .Ss \&Nm |
| 1985 | The name of the manual page, or \(em in particular in section 1, 6, |
| 1986 | and 8 pages \(em of an additional command or feature documented in |
| 1987 | the manual page. |
| 1988 | When first invoked, the |
| 1989 | .Sx \&Nm |
| 1990 | macro expects a single argument, the name of the manual page. |
| 1991 | Usually, the first invocation happens in the |
| 1992 | .Em NAME |
| 1993 | section of the page. |
| 1994 | The specified name will be remembered and used whenever the macro is |
| 1995 | called again without arguments later in the page. |
| 1996 | The |
| 1997 | .Sx \&Nm |
| 1998 | macro uses |
| 1999 | .Sx Block full-implicit |
| 2000 | semantics when invoked as the first macro on an input line in the |
| 2001 | .Em SYNOPSIS |
| 2002 | section; otherwise, it uses ordinary |
| 2003 | .Sx In-line |
| 2004 | semantics. |
| 2005 | .Pp |
| 2006 | Examples: |
| 2007 | .Bd -literal -offset indent |
| 2008 | \&.Sh SYNOPSIS |
| 2009 | \&.Nm cat |
| 2010 | \&.Op Fl benstuv |
| 2011 | \&.Op Ar |
| 2012 | .Ed |
| 2013 | .Pp |
| 2014 | In the |
| 2015 | .Em SYNOPSIS |
| 2016 | of section 2, 3 and 9 manual pages, use the |
| 2017 | .Sx \&Fn |
| 2018 | macro rather than |
| 2019 | .Sx \&Nm |
| 2020 | to mark up the name of the manual page. |
| 2021 | .Ss \&No |
| 2022 | Normal text. |
| 2023 | Closes the scope of any preceding in-line macro. |
| 2024 | When used after physical formatting macros like |
| 2025 | .Sx \&Em |
| 2026 | or |
| 2027 | .Sx \&Sy , |
| 2028 | switches back to the standard font face and weight. |
| 2029 | Can also be used to embed plain text strings in macro lines |
| 2030 | using semantic annotation macros. |
| 2031 | .Pp |
| 2032 | Examples: |
| 2033 | .Dl ".Em italic , Sy bold , No and roman" |
| 2034 | .Pp |
| 2035 | .Bd -literal -offset indent -compact |
| 2036 | \&.Sm off |
| 2037 | \&.Cm :C No / Ar pattern No / Ar replacement No / |
| 2038 | \&.Sm on |
| 2039 | .Ed |
| 2040 | .Pp |
| 2041 | See also |
| 2042 | .Sx \&Em , |
| 2043 | .Sx \&Li , |
| 2044 | and |
| 2045 | .Sx \&Sy . |
| 2046 | .Ss \&Ns |
| 2047 | Suppress a space between the output of the preceding macro |
| 2048 | and the following text or macro. |
| 2049 | Following invocation, input is interpreted as normal text |
| 2050 | just like after an |
| 2051 | .Sx \&No |
| 2052 | macro. |
| 2053 | .Pp |
| 2054 | This has no effect when invoked at the start of a macro line. |
| 2055 | .Pp |
| 2056 | Examples: |
| 2057 | .Dl ".Ar name Ns = Ns Ar value" |
| 2058 | .Dl ".Cm :M Ns Ar pattern" |
| 2059 | .Dl ".Fl o Ns Ar output" |
| 2060 | .Pp |
| 2061 | See also |
| 2062 | .Sx \&No |
| 2063 | and |
| 2064 | .Sx \&Sm . |
| 2065 | .Ss \&Nx |
| 2066 | Format the |
| 2067 | .Nx |
| 2068 | version provided as an argument, or a default value if |
| 2069 | no argument is provided. |
| 2070 | .Pp |
| 2071 | Examples: |
| 2072 | .Dl \&.Nx 5.01 |
| 2073 | .Dl \&.Nx |
| 2074 | .Pp |
| 2075 | See also |
| 2076 | .Sx \&At , |
| 2077 | .Sx \&Bsx , |
| 2078 | .Sx \&Bx , |
| 2079 | .Sx \&Dx , |
| 2080 | .Sx \&Fx , |
| 2081 | and |
| 2082 | .Sx \&Ox . |
| 2083 | .Ss \&Oc |
| 2084 | Close multi-line |
| 2085 | .Sx \&Oo |
| 2086 | context. |
| 2087 | .Ss \&Oo |
| 2088 | Multi-line version of |
| 2089 | .Sx \&Op . |
| 2090 | .Pp |
| 2091 | Examples: |
| 2092 | .Bd -literal -offset indent -compact |
| 2093 | \&.Oo |
| 2094 | \&.Op Fl flag Ns Ar value |
| 2095 | \&.Oc |
| 2096 | .Ed |
| 2097 | .Ss \&Op |
| 2098 | Optional part of a command line. |
| 2099 | Prints the argument(s) in brackets. |
| 2100 | This is most often used in the |
| 2101 | .Em SYNOPSIS |
| 2102 | section of section 1 and 8 manual pages. |
| 2103 | .Pp |
| 2104 | Examples: |
| 2105 | .Dl \&.Op \&Fl a \&Ar b |
| 2106 | .Dl \&.Op \&Ar a | b |
| 2107 | .Pp |
| 2108 | See also |
| 2109 | .Sx \&Oo . |
| 2110 | .Ss \&Os |
| 2111 | Operating system version for display in the page footer. |
| 2112 | This is the mandatory third macro of |
| 2113 | any |
| 2114 | .Nm |
| 2115 | file. |
| 2116 | Its syntax is as follows: |
| 2117 | .Pp |
| 2118 | .D1 Pf \. Sx \&Os Op Ar system Op Ar version |
| 2119 | .Pp |
| 2120 | The optional |
| 2121 | .Ar system |
| 2122 | parameter specifies the relevant operating system or environment. |
| 2123 | Left unspecified, it defaults to the local operating system version. |
| 2124 | This is the suggested form. |
| 2125 | .Pp |
| 2126 | Examples: |
| 2127 | .Dl \&.Os |
| 2128 | .Dl \&.Os KTH/CSC/TCS |
| 2129 | .Dl \&.Os BSD 4.3 |
| 2130 | .Pp |
| 2131 | See also |
| 2132 | .Sx \&Dd |
| 2133 | and |
| 2134 | .Sx \&Dt . |
| 2135 | .Ss \&Ot |
| 2136 | This macro is obsolete. |
| 2137 | Use |
| 2138 | .Sx \&Ft |
| 2139 | instead; with |
| 2140 | .Xr mandoc 1 , |
| 2141 | both have the same effect. |
| 2142 | .Pp |
| 2143 | Historical |
| 2144 | .Nm |
| 2145 | packages described it as |
| 2146 | .Dq "old function type (FORTRAN)" . |
| 2147 | .Ss \&Ox |
| 2148 | Format the |
| 2149 | .Ox |
| 2150 | version provided as an argument, or a default value |
| 2151 | if no argument is provided. |
| 2152 | .Pp |
| 2153 | Examples: |
| 2154 | .Dl \&.Ox 4.5 |
| 2155 | .Dl \&.Ox |
| 2156 | .Pp |
| 2157 | See also |
| 2158 | .Sx \&At , |
| 2159 | .Sx \&Bsx , |
| 2160 | .Sx \&Bx , |
| 2161 | .Sx \&Dx , |
| 2162 | .Sx \&Fx , |
| 2163 | and |
| 2164 | .Sx \&Nx . |
| 2165 | .Ss \&Pa |
| 2166 | An absolute or relative file system path, or a file or directory name. |
| 2167 | If an argument is not provided, the character |
| 2168 | .Sq \(ti |
| 2169 | is used as a default. |
| 2170 | .Pp |
| 2171 | Examples: |
| 2172 | .Dl \&.Pa /usr/bin/mandoc |
| 2173 | .Dl \&.Pa /usr/share/man/man7/mdoc.7 |
| 2174 | .Pp |
| 2175 | See also |
| 2176 | .Sx \&Lk . |
| 2177 | .Ss \&Pc |
| 2178 | Close parenthesised context opened by |
| 2179 | .Sx \&Po . |
| 2180 | .Ss \&Pf |
| 2181 | Removes the space between its argument |
| 2182 | .Pq Dq prefix |
| 2183 | and the following macro. |
| 2184 | Its syntax is as follows: |
| 2185 | .Pp |
| 2186 | .D1 .Pf Ar prefix macro arguments ... |
| 2187 | .Pp |
| 2188 | This is equivalent to: |
| 2189 | .Pp |
| 2190 | .D1 .No Ar prefix No \&Ns Ar macro arguments ... |
| 2191 | .Pp |
| 2192 | Examples: |
| 2193 | .Dl ".Pf $ Ar variable_name" |
| 2194 | .Dl ".Pf 0x Ar hex_digits" |
| 2195 | .Pp |
| 2196 | See also |
| 2197 | .Sx \&Ns |
| 2198 | and |
| 2199 | .Sx \&Sm . |
| 2200 | .Ss \&Po |
| 2201 | Multi-line version of |
| 2202 | .Sx \&Pq . |
| 2203 | .Ss \&Pp |
| 2204 | Break a paragraph. |
| 2205 | This will assert vertical space between prior and subsequent macros |
| 2206 | and/or text. |
| 2207 | .Pp |
| 2208 | Paragraph breaks are not needed before or after |
| 2209 | .Sx \&Sh |
| 2210 | or |
| 2211 | .Sx \&Ss |
| 2212 | macros or before displays |
| 2213 | .Pq Sx \&Bd |
| 2214 | or lists |
| 2215 | .Pq Sx \&Bl |
| 2216 | unless the |
| 2217 | .Fl compact |
| 2218 | flag is given. |
| 2219 | .Ss \&Pq |
| 2220 | Parenthesised enclosure. |
| 2221 | .Pp |
| 2222 | See also |
| 2223 | .Sx \&Po . |
| 2224 | .Ss \&Qc |
| 2225 | Close quoted context opened by |
| 2226 | .Sx \&Qo . |
| 2227 | .Ss \&Ql |
| 2228 | Format a single-quoted literal. |
| 2229 | See also |
| 2230 | .Sx \&Qq |
| 2231 | and |
| 2232 | .Sx \&Sq . |
| 2233 | .Ss \&Qo |
| 2234 | Multi-line version of |
| 2235 | .Sx \&Qq . |
| 2236 | .Ss \&Qq |
| 2237 | Encloses its arguments in |
| 2238 | .Qq typewriter |
| 2239 | double-quotes. |
| 2240 | Consider using |
| 2241 | .Sx \&Dq . |
| 2242 | .Pp |
| 2243 | See also |
| 2244 | .Sx \&Dq , |
| 2245 | .Sx \&Sq , |
| 2246 | and |
| 2247 | .Sx \&Qo . |
| 2248 | .Ss \&Re |
| 2249 | Close an |
| 2250 | .Sx \&Rs |
| 2251 | block. |
| 2252 | Does not have any tail arguments. |
| 2253 | .Ss \&Rs |
| 2254 | Begin a bibliographic |
| 2255 | .Pq Dq reference |
| 2256 | block. |
| 2257 | Does not have any head arguments. |
| 2258 | The block macro may only contain |
| 2259 | .Sx \&%A , |
| 2260 | .Sx \&%B , |
| 2261 | .Sx \&%C , |
| 2262 | .Sx \&%D , |
| 2263 | .Sx \&%I , |
| 2264 | .Sx \&%J , |
| 2265 | .Sx \&%N , |
| 2266 | .Sx \&%O , |
| 2267 | .Sx \&%P , |
| 2268 | .Sx \&%Q , |
| 2269 | .Sx \&%R , |
| 2270 | .Sx \&%T , |
| 2271 | .Sx \&%U , |
| 2272 | and |
| 2273 | .Sx \&%V |
| 2274 | child macros (at least one must be specified). |
| 2275 | .Pp |
| 2276 | Examples: |
| 2277 | .Bd -literal -offset indent -compact |
| 2278 | \&.Rs |
| 2279 | \&.%A J. E. Hopcroft |
| 2280 | \&.%A J. D. Ullman |
| 2281 | \&.%B Introduction to Automata Theory, Languages, and Computation |
| 2282 | \&.%I Addison-Wesley |
| 2283 | \&.%C Reading, Massachusettes |
| 2284 | \&.%D 1979 |
| 2285 | \&.Re |
| 2286 | .Ed |
| 2287 | .Pp |
| 2288 | If an |
| 2289 | .Sx \&Rs |
| 2290 | block is used within a SEE ALSO section, a vertical space is asserted |
| 2291 | before the rendered output, else the block continues on the current |
| 2292 | line. |
| 2293 | .Ss \&Rv |
| 2294 | Insert a standard sentence regarding a function call's return value of 0 |
| 2295 | on success and \-1 on error, with the |
| 2296 | .Va errno |
| 2297 | libc global variable set on error. |
| 2298 | Its syntax is as follows: |
| 2299 | .Pp |
| 2300 | .D1 Pf \. Sx \&Rv Fl std Op Ar function ... |
| 2301 | .Pp |
| 2302 | If |
| 2303 | .Ar function |
| 2304 | is not specified, the document's name set by |
| 2305 | .Sx \&Nm |
| 2306 | is used. |
| 2307 | Multiple |
| 2308 | .Ar function |
| 2309 | arguments are treated as separate functions. |
| 2310 | .Pp |
| 2311 | See also |
| 2312 | .Sx \&Ex . |
| 2313 | .Ss \&Sc |
| 2314 | Close single-quoted context opened by |
| 2315 | .Sx \&So . |
| 2316 | .Ss \&Sh |
| 2317 | Begin a new section. |
| 2318 | For a list of conventional manual sections, see |
| 2319 | .Sx MANUAL STRUCTURE . |
| 2320 | These sections should be used unless it's absolutely necessary that |
| 2321 | custom sections be used. |
| 2322 | .Pp |
| 2323 | Section names should be unique so that they may be keyed by |
| 2324 | .Sx \&Sx . |
| 2325 | Although this macro is parsed, it should not consist of child node or it |
| 2326 | may not be linked with |
| 2327 | .Sx \&Sx . |
| 2328 | .Pp |
| 2329 | See also |
| 2330 | .Sx \&Pp , |
| 2331 | .Sx \&Ss , |
| 2332 | and |
| 2333 | .Sx \&Sx . |
| 2334 | .Ss \&Sm |
| 2335 | Switches the spacing mode for output generated from macros. |
| 2336 | Its syntax is as follows: |
| 2337 | .Pp |
| 2338 | .D1 Pf \. Sx \&Sm Op Cm on | off |
| 2339 | .Pp |
| 2340 | By default, spacing is |
| 2341 | .Cm on . |
| 2342 | When switched |
| 2343 | .Cm off , |
| 2344 | no white space is inserted between macro arguments and between the |
| 2345 | output generated from adjacent macros, but text lines |
| 2346 | still get normal spacing between words and sentences. |
| 2347 | .Pp |
| 2348 | When called without an argument, the |
| 2349 | .Sx \&Sm |
| 2350 | macro toggles the spacing mode. |
| 2351 | Using this is not recommended because it makes the code harder to read. |
| 2352 | .Ss \&So |
| 2353 | Multi-line version of |
| 2354 | .Sx \&Sq . |
| 2355 | .Ss \&Sq |
| 2356 | Encloses its arguments in |
| 2357 | .Sq typewriter |
| 2358 | single-quotes. |
| 2359 | .Pp |
| 2360 | See also |
| 2361 | .Sx \&Dq , |
| 2362 | .Sx \&Qq , |
| 2363 | and |
| 2364 | .Sx \&So . |
| 2365 | .Ss \&Ss |
| 2366 | Begin a new subsection. |
| 2367 | Unlike with |
| 2368 | .Sx \&Sh , |
| 2369 | there is no convention for the naming of subsections. |
| 2370 | Except |
| 2371 | .Em DESCRIPTION , |
| 2372 | the conventional sections described in |
| 2373 | .Sx MANUAL STRUCTURE |
| 2374 | rarely have subsections. |
| 2375 | .Pp |
| 2376 | Sub-section names should be unique so that they may be keyed by |
| 2377 | .Sx \&Sx . |
| 2378 | Although this macro is parsed, it should not consist of child node or it |
| 2379 | may not be linked with |
| 2380 | .Sx \&Sx . |
| 2381 | .Pp |
| 2382 | See also |
| 2383 | .Sx \&Pp , |
| 2384 | .Sx \&Sh , |
| 2385 | and |
| 2386 | .Sx \&Sx . |
| 2387 | .Ss \&St |
| 2388 | Replace an abbreviation for a standard with the full form. |
| 2389 | The following standards are recognised. |
| 2390 | Where multiple lines are given without a blank line in between, |
| 2391 | they all refer to the same standard, and using the first form |
| 2392 | is recommended. |
| 2393 | .Bl -tag -width 1n |
| 2394 | .It C language standards |
| 2395 | .Pp |
| 2396 | .Bl -tag -width "-p1003.1g-2000" -compact |
| 2397 | .It \-ansiC |
| 2398 | .St -ansiC |
| 2399 | .It \-ansiC-89 |
| 2400 | .St -ansiC-89 |
| 2401 | .It \-isoC |
| 2402 | .St -isoC |
| 2403 | .It \-isoC-90 |
| 2404 | .St -isoC-90 |
| 2405 | .br |
| 2406 | The original C standard. |
| 2407 | .Pp |
| 2408 | .It \-isoC-amd1 |
| 2409 | .St -isoC-amd1 |
| 2410 | .Pp |
| 2411 | .It \-isoC-tcor1 |
| 2412 | .St -isoC-tcor1 |
| 2413 | .Pp |
| 2414 | .It \-isoC-tcor2 |
| 2415 | .St -isoC-tcor2 |
| 2416 | .Pp |
| 2417 | .It \-isoC-99 |
| 2418 | .St -isoC-99 |
| 2419 | .It \-ansiC-99 |
| 2420 | .St -ansiC-99 |
| 2421 | .br |
| 2422 | The second major version of the C language standard. |
| 2423 | .Pp |
| 2424 | .It \-isoC-2011 |
| 2425 | .St -isoC-2011 |
| 2426 | .br |
| 2427 | The third major version of the C language standard. |
| 2428 | .El |
| 2429 | .It POSIX.1 before the Single UNIX Specification |
| 2430 | .Pp |
| 2431 | .Bl -tag -width "-p1003.1g-2000" -compact |
| 2432 | .It \-p1003.1-88 |
| 2433 | .St -p1003.1-88 |
| 2434 | .It \-p1003.1 |
| 2435 | .St -p1003.1 |
| 2436 | .br |
| 2437 | The original POSIX standard, based on ANSI C. |
| 2438 | .Pp |
| 2439 | .It \-p1003.1-90 |
| 2440 | .St -p1003.1-90 |
| 2441 | .It \-iso9945-1-90 |
| 2442 | .St -iso9945-1-90 |
| 2443 | .br |
| 2444 | The first update of POSIX.1. |
| 2445 | .Pp |
| 2446 | .It \-p1003.1b-93 |
| 2447 | .St -p1003.1b-93 |
| 2448 | .It \-p1003.1b |
| 2449 | .St -p1003.1b |
| 2450 | .br |
| 2451 | Real-time extensions. |
| 2452 | .Pp |
| 2453 | .It \-p1003.1c-95 |
| 2454 | .St -p1003.1c-95 |
| 2455 | .br |
| 2456 | POSIX thread interfaces. |
| 2457 | .Pp |
| 2458 | .It \-p1003.1i-95 |
| 2459 | .St -p1003.1i-95 |
| 2460 | .br |
| 2461 | Technical Corrigendum. |
| 2462 | .Pp |
| 2463 | .It \-p1003.1-96 |
| 2464 | .St -p1003.1-96 |
| 2465 | .It \-iso9945-1-96 |
| 2466 | .St -iso9945-1-96 |
| 2467 | .br |
| 2468 | Includes POSIX.1-1990, 1b, 1c, and 1i. |
| 2469 | .El |
| 2470 | .It X/Open Portability Guide version 4 and related standards |
| 2471 | .Pp |
| 2472 | .Bl -tag -width "-p1003.1g-2000" -compact |
| 2473 | .It \-xpg3 |
| 2474 | .St -xpg3 |
| 2475 | .br |
| 2476 | An XPG4 precursor, published in 1989. |
| 2477 | .Pp |
| 2478 | .It \-p1003.2 |
| 2479 | .St -p1003.2 |
| 2480 | .It \-p1003.2-92 |
| 2481 | .St -p1003.2-92 |
| 2482 | .It \-iso9945-2-93 |
| 2483 | .St -iso9945-2-93 |
| 2484 | .br |
| 2485 | An XCU4 precursor. |
| 2486 | .Pp |
| 2487 | .It \-p1003.2a-92 |
| 2488 | .St -p1003.2a-92 |
| 2489 | .br |
| 2490 | Updates to POSIX.2. |
| 2491 | .Pp |
| 2492 | .It \-xpg4 |
| 2493 | .St -xpg4 |
| 2494 | .br |
| 2495 | Based on POSIX.1 and POSIX.2, published in 1992. |
| 2496 | .El |
| 2497 | .It Single UNIX Specification version 1 and related standards |
| 2498 | .Pp |
| 2499 | .Bl -tag -width "-p1003.1g-2000" -compact |
| 2500 | .It \-xpg4.2 |
| 2501 | .St -xpg4.2 |
| 2502 | .br |
| 2503 | This standard was published in 1994 and is also called SUSv1. |
| 2504 | It was used as the basis for UNIX 95 certification. |
| 2505 | The following three refer to parts of it. |
| 2506 | .Pp |
| 2507 | .It \-xsh4.2 |
| 2508 | .St -xsh4.2 |
| 2509 | .Pp |
| 2510 | .It \-xcurses4.2 |
| 2511 | .St -xcurses4.2 |
| 2512 | .Pp |
| 2513 | .It \-p1003.1g-2000 |
| 2514 | .St -p1003.1g-2000 |
| 2515 | .br |
| 2516 | Networking APIs, including sockets. |
| 2517 | .Pp |
| 2518 | .It \-xpg4.3 |
| 2519 | .St -xpg4.3 |
| 2520 | .Pp |
| 2521 | .It \-svid4 |
| 2522 | .St -svid4 , |
| 2523 | .br |
| 2524 | Published in 1995. |
| 2525 | .El |
| 2526 | .It Single UNIX Specification version 2 and related standards |
| 2527 | .Pp |
| 2528 | .Bl -tag -width "-p1003.1g-2000" -compact |
| 2529 | .It \-susv2 |
| 2530 | .St -susv2 |
| 2531 | This Standard was published in 1997 |
| 2532 | and is also called X/Open Portability Guide version 5. |
| 2533 | It was used as the basis for UNIX 98 certification. |
| 2534 | The following refer to parts of it. |
| 2535 | .Pp |
| 2536 | .It \-xbd5 |
| 2537 | .St -xbd5 |
| 2538 | .Pp |
| 2539 | .It \-xsh5 |
| 2540 | .St -xsh5 |
| 2541 | .Pp |
| 2542 | .It \-xcu5 |
| 2543 | .St -xcu5 |
| 2544 | .Pp |
| 2545 | .It \-xns5 |
| 2546 | .St -xns5 |
| 2547 | .It \-xns5.2d2.0 |
| 2548 | .St -xns5.2d2.0 |
| 2549 | .It \-xns5.2 |
| 2550 | .St -xns5.2 |
| 2551 | .Pp |
| 2552 | .It \-p1387.2 |
| 2553 | .St -p1387.2 |
| 2554 | .It \-p1387.2-95 |
| 2555 | .St -p1387.2-95 |
| 2556 | .br |
| 2557 | POSIX software administration. |
| 2558 | .El |
| 2559 | .It Single UNIX Specification version 3 and related standards |
| 2560 | .Pp |
| 2561 | .Bl -tag -width "-p1003.1g-2000X" -compact |
| 2562 | .It \-p1003.1d-99 |
| 2563 | .St -p1003.1d-99 |
| 2564 | .br |
| 2565 | Additional real-time extensions. |
| 2566 | .Pp |
| 2567 | .It \-p1003.1j-2000 |
| 2568 | .St -p1003.1j-2000 |
| 2569 | .br |
| 2570 | Advanced real-time extensions. |
| 2571 | .Pp |
| 2572 | .It \-p1003.1q-2000 |
| 2573 | .St -p1003.1q-2000 |
| 2574 | .br |
| 2575 | Amendment 7: Tracing [C Language]. |
| 2576 | .Pp |
| 2577 | .It \-p1003.1-2001 |
| 2578 | .St -p1003.1-2001 |
| 2579 | .It \-susv3 |
| 2580 | .St -susv3 |
| 2581 | .br |
| 2582 | This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. |
| 2583 | It is also called X/Open Portability Guide version 6. |
| 2584 | It is used as the basis for UNIX 03 certification. |
| 2585 | .Pp |
| 2586 | .It \-p1003.1-2004 |
| 2587 | .St -p1003.1-2004 |
| 2588 | .br |
| 2589 | The second and last Technical Corrigendum. |
| 2590 | .El |
| 2591 | .It Single UNIX Specification version 4 |
| 2592 | .Pp |
| 2593 | .Bl -tag -width "-p1003.1g-2000" -compact |
| 2594 | .It \-p1003.1-2008 |
| 2595 | .St -p1003.1-2008 |
| 2596 | .br |
| 2597 | This standard is also called SUSv4 and |
| 2598 | X/Open Portability Guide version 7. |
| 2599 | .Pp |
| 2600 | .It \-p1003.1-2013 |
| 2601 | .St -p1003.1-2013 |
| 2602 | .br |
| 2603 | This is the first Technical Corrigendum. |
| 2604 | .El |
| 2605 | .It Other standards |
| 2606 | .Pp |
| 2607 | .Bl -tag -width "-p1003.1g-2000" -compact |
| 2608 | .It \-ieee754 |
| 2609 | .St -ieee754 |
| 2610 | .br |
| 2611 | Floating-point arithmetic. |
| 2612 | .Pp |
| 2613 | .It \-iso8601 |
| 2614 | .St -iso8601 |
| 2615 | .br |
| 2616 | Representation of dates and times, published in 1988. |
| 2617 | .Pp |
| 2618 | .It \-iso8802-3 |
| 2619 | .St -iso8802-3 |
| 2620 | .br |
| 2621 | Ethernet local area networks. |
| 2622 | .Pp |
| 2623 | .It \-ieee1275-94 |
| 2624 | .St -ieee1275-94 |
| 2625 | .El |
| 2626 | .El |
| 2627 | .Ss \&Sx |
| 2628 | Reference a section or subsection in the same manual page. |
| 2629 | The referenced section or subsection name must be identical to the |
| 2630 | enclosed argument, including whitespace. |
| 2631 | .Pp |
| 2632 | Examples: |
| 2633 | .Dl \&.Sx MANUAL STRUCTURE |
| 2634 | .Pp |
| 2635 | See also |
| 2636 | .Sx \&Sh |
| 2637 | and |
| 2638 | .Sx \&Ss . |
| 2639 | .Ss \&Sy |
| 2640 | Format enclosed arguments in symbolic |
| 2641 | .Pq Dq boldface . |
| 2642 | Note that this is a presentation term and should not be used for |
| 2643 | stylistically decorating technical terms. |
| 2644 | .Pp |
| 2645 | See also |
| 2646 | .Sx \&Bf , |
| 2647 | .Sx \&Em , |
| 2648 | .Sx \&Li , |
| 2649 | and |
| 2650 | .Sx \&No . |
| 2651 | .Ss \&Ta |
| 2652 | Table cell separator in |
| 2653 | .Sx \&Bl Fl column |
| 2654 | lists; can only be used below |
| 2655 | .Sx \&It . |
| 2656 | .Ss \&Tn |
| 2657 | Supported only for compatibility, do not use this in new manuals. |
| 2658 | Even though the macro name |
| 2659 | .Pq Dq tradename |
| 2660 | suggests a semantic function, historic usage is inconsistent, mostly |
| 2661 | using it as a presentation-level macro to request a small caps font. |
| 2662 | .Ss \&Ud |
| 2663 | Supported only for compatibility, do not use this in new manuals. |
| 2664 | Prints out |
| 2665 | .Dq currently under development. |
| 2666 | .Ss \&Ux |
| 2667 | Supported only for compatibility, do not use this in new manuals. |
| 2668 | Prints out |
| 2669 | .Dq Ux . |
| 2670 | .Ss \&Va |
| 2671 | A variable name. |
| 2672 | .Pp |
| 2673 | Examples: |
| 2674 | .Dl \&.Va foo |
| 2675 | .Dl \&.Va const char *bar ; |
| 2676 | .Ss \&Vt |
| 2677 | A variable type. |
| 2678 | This is also used for indicating global variables in the |
| 2679 | .Em SYNOPSIS |
| 2680 | section, in which case a variable name is also specified. |
| 2681 | Note that it accepts |
| 2682 | .Sx Block partial-implicit |
| 2683 | syntax when invoked as the first macro on an input line in the |
| 2684 | .Em SYNOPSIS |
| 2685 | section, else it accepts ordinary |
| 2686 | .Sx In-line |
| 2687 | syntax. |
| 2688 | In the former case, this macro starts a new output line, |
| 2689 | and a blank line is inserted in front if there is a preceding |
| 2690 | function definition or include directive. |
| 2691 | .Pp |
| 2692 | Note that this should not be confused with |
| 2693 | .Sx \&Ft , |
| 2694 | which is used for function return types. |
| 2695 | .Pp |
| 2696 | Examples: |
| 2697 | .Dl \&.Vt unsigned char |
| 2698 | .Dl \&.Vt extern const char * const sys_signame[] \&; |
| 2699 | .Pp |
| 2700 | See also |
| 2701 | .Sx MANUAL STRUCTURE |
| 2702 | and |
| 2703 | .Sx \&Va . |
| 2704 | .Ss \&Xc |
| 2705 | Close a scope opened by |
| 2706 | .Sx \&Xo . |
| 2707 | .Ss \&Xo |
| 2708 | Extend the header of an |
| 2709 | .Sx \&It |
| 2710 | macro or the body of a partial-implicit block macro |
| 2711 | beyond the end of the input line. |
| 2712 | This macro originally existed to work around the 9-argument limit |
| 2713 | of historic |
| 2714 | .Xr roff 7 . |
| 2715 | .Ss \&Xr |
| 2716 | Link to another manual |
| 2717 | .Pq Qq cross-reference . |
| 2718 | Its syntax is as follows: |
| 2719 | .Pp |
| 2720 | .D1 Pf \. Sx \&Xr Ar name Op section |
| 2721 | .Pp |
| 2722 | Cross reference the |
| 2723 | .Ar name |
| 2724 | and |
| 2725 | .Ar section |
| 2726 | number of another man page; |
| 2727 | omitting the section number is rarely useful. |
| 2728 | .Pp |
| 2729 | Examples: |
| 2730 | .Dl \&.Xr mandoc 1 |
| 2731 | .Dl \&.Xr mandoc 1 \&; |
| 2732 | .Dl \&.Xr mandoc 1 \&Ns s behaviour |
| 2733 | .Ss \&br |
| 2734 | Emits a line-break. |
| 2735 | This macro should not be used; it is implemented for compatibility with |
| 2736 | historical manuals. |
| 2737 | .Pp |
| 2738 | Consider using |
| 2739 | .Sx \&Pp |
| 2740 | in the event of natural paragraph breaks. |
| 2741 | .Ss \&sp |
| 2742 | Emits vertical space. |
| 2743 | This macro should not be used; it is implemented for compatibility with |
| 2744 | historical manuals. |
| 2745 | Its syntax is as follows: |
| 2746 | .Pp |
| 2747 | .D1 Pf \. Sx \&sp Op Ar height |
| 2748 | .Pp |
| 2749 | The |
| 2750 | .Ar height |
| 2751 | argument is a scaling width as described in |
| 2752 | .Xr roff 7 . |
| 2753 | If unspecified, |
| 2754 | .Sx \&sp |
| 2755 | asserts a single vertical space. |
| 2756 | .Sh MACRO SYNTAX |
| 2757 | The syntax of a macro depends on its classification. |
| 2758 | In this section, |
| 2759 | .Sq \-arg |
| 2760 | refers to macro arguments, which may be followed by zero or more |
| 2761 | .Sq parm |
| 2762 | parameters; |
| 2763 | .Sq \&Yo |
| 2764 | opens the scope of a macro; and if specified, |
| 2765 | .Sq \&Yc |
| 2766 | closes it out. |
| 2767 | .Pp |
| 2768 | The |
| 2769 | .Em Callable |
| 2770 | column indicates that the macro may also be called by passing its name |
| 2771 | as an argument to another macro. |
| 2772 | For example, |
| 2773 | .Sq \&.Op \&Fl O \&Ar file |
| 2774 | produces |
| 2775 | .Sq Op Fl O Ar file . |
| 2776 | To prevent a macro call and render the macro name literally, |
| 2777 | escape it by prepending a zero-width space, |
| 2778 | .Sq \e& . |
| 2779 | For example, |
| 2780 | .Sq \&Op \e&Fl O |
| 2781 | produces |
| 2782 | .Sq Op \&Fl O . |
| 2783 | If a macro is not callable but its name appears as an argument |
| 2784 | to another macro, it is interpreted as opaque text. |
| 2785 | For example, |
| 2786 | .Sq \&.Fl \&Sh |
| 2787 | produces |
| 2788 | .Sq Fl \&Sh . |
| 2789 | .Pp |
| 2790 | The |
| 2791 | .Em Parsed |
| 2792 | column indicates whether the macro may call other macros by receiving |
| 2793 | their names as arguments. |
| 2794 | If a macro is not parsed but the name of another macro appears |
| 2795 | as an argument, it is interpreted as opaque text. |
| 2796 | .Pp |
| 2797 | The |
| 2798 | .Em Scope |
| 2799 | column, if applicable, describes closure rules. |
| 2800 | .Ss Block full-explicit |
| 2801 | Multi-line scope closed by an explicit closing macro. |
| 2802 | All macros contains bodies; only |
| 2803 | .Sx \&Bf |
| 2804 | and |
| 2805 | .Pq optionally |
| 2806 | .Sx \&Bl |
| 2807 | contain a head. |
| 2808 | .Bd -literal -offset indent |
| 2809 | \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB |
| 2810 | \(lBbody...\(rB |
| 2811 | \&.Yc |
| 2812 | .Ed |
| 2813 | .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent |
| 2814 | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
| 2815 | .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed |
| 2816 | .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef |
| 2817 | .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek |
| 2818 | .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El |
| 2819 | .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd |
| 2820 | .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf |
| 2821 | .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk |
| 2822 | .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl |
| 2823 | .El |
| 2824 | .Ss Block full-implicit |
| 2825 | Multi-line scope closed by end-of-file or implicitly by another macro. |
| 2826 | All macros have bodies; some |
| 2827 | .Po |
| 2828 | .Sx \&It Fl bullet , |
| 2829 | .Fl hyphen , |
| 2830 | .Fl dash , |
| 2831 | .Fl enum , |
| 2832 | .Fl item |
| 2833 | .Pc |
| 2834 | don't have heads; only one |
| 2835 | .Po |
| 2836 | .Sx \&It |
| 2837 | in |
| 2838 | .Sx \&Bl Fl column |
| 2839 | .Pc |
| 2840 | has multiple heads. |
| 2841 | .Bd -literal -offset indent |
| 2842 | \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB |
| 2843 | \(lBbody...\(rB |
| 2844 | .Ed |
| 2845 | .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent |
| 2846 | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
| 2847 | .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El |
| 2848 | .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh |
| 2849 | .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss |
| 2850 | .It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh |
| 2851 | .It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss |
| 2852 | .El |
| 2853 | .Pp |
| 2854 | Note that the |
| 2855 | .Sx \&Nm |
| 2856 | macro is a |
| 2857 | .Sx Block full-implicit |
| 2858 | macro only when invoked as the first macro |
| 2859 | in a |
| 2860 | .Em SYNOPSIS |
| 2861 | section line, else it is |
| 2862 | .Sx In-line . |
| 2863 | .Ss Block partial-explicit |
| 2864 | Like block full-explicit, but also with single-line scope. |
| 2865 | Each has at least a body and, in limited circumstances, a head |
| 2866 | .Po |
| 2867 | .Sx \&Fo , |
| 2868 | .Sx \&Eo |
| 2869 | .Pc |
| 2870 | and/or tail |
| 2871 | .Pq Sx \&Ec . |
| 2872 | .Bd -literal -offset indent |
| 2873 | \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB |
| 2874 | \(lBbody...\(rB |
| 2875 | \&.Yc \(lBtail...\(rB |
| 2876 | |
| 2877 | \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ |
| 2878 | \(lBbody...\(rB \&Yc \(lBtail...\(rB |
| 2879 | .Ed |
| 2880 | .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent |
| 2881 | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
| 2882 | .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao |
| 2883 | .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac |
| 2884 | .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo |
| 2885 | .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc |
| 2886 | .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro |
| 2887 | .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc |
| 2888 | .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do |
| 2889 | .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc |
| 2890 | .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo |
| 2891 | .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec |
| 2892 | .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo |
| 2893 | .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc |
| 2894 | .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo |
| 2895 | .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc |
| 2896 | .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po |
| 2897 | .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc |
| 2898 | .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo |
| 2899 | .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc |
| 2900 | .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs |
| 2901 | .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re |
| 2902 | .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So |
| 2903 | .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc |
| 2904 | .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo |
| 2905 | .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc |
| 2906 | .El |
| 2907 | .Ss Block partial-implicit |
| 2908 | Like block full-implicit, but with single-line scope closed by the |
| 2909 | end of the line. |
| 2910 | .Bd -literal -offset indent |
| 2911 | \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
| 2912 | .Ed |
| 2913 | .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent |
| 2914 | .It Em Macro Ta Em Callable Ta Em Parsed |
| 2915 | .It Sx \&Aq Ta Yes Ta Yes |
| 2916 | .It Sx \&Bq Ta Yes Ta Yes |
| 2917 | .It Sx \&Brq Ta Yes Ta Yes |
| 2918 | .It Sx \&D1 Ta \&No Ta \&Yes |
| 2919 | .It Sx \&Dl Ta \&No Ta Yes |
| 2920 | .It Sx \&Dq Ta Yes Ta Yes |
| 2921 | .It Sx \&En Ta Yes Ta Yes |
| 2922 | .It Sx \&Op Ta Yes Ta Yes |
| 2923 | .It Sx \&Pq Ta Yes Ta Yes |
| 2924 | .It Sx \&Ql Ta Yes Ta Yes |
| 2925 | .It Sx \&Qq Ta Yes Ta Yes |
| 2926 | .It Sx \&Sq Ta Yes Ta Yes |
| 2927 | .It Sx \&Vt Ta Yes Ta Yes |
| 2928 | .El |
| 2929 | .Pp |
| 2930 | Note that the |
| 2931 | .Sx \&Vt |
| 2932 | macro is a |
| 2933 | .Sx Block partial-implicit |
| 2934 | only when invoked as the first macro |
| 2935 | in a |
| 2936 | .Em SYNOPSIS |
| 2937 | section line, else it is |
| 2938 | .Sx In-line . |
| 2939 | .Ss Special block macro |
| 2940 | The |
| 2941 | .Sx \&Ta |
| 2942 | macro can only be used below |
| 2943 | .Sx \&It |
| 2944 | in |
| 2945 | .Sx \&Bl Fl column |
| 2946 | lists. |
| 2947 | It delimits blocks representing table cells; |
| 2948 | these blocks have bodies, but no heads. |
| 2949 | .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent |
| 2950 | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
| 2951 | .It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
| 2952 | .El |
| 2953 | .Ss In-line |
| 2954 | Closed by the end of the line, fixed argument lengths, |
| 2955 | and/or subsequent macros. |
| 2956 | In-line macros have only text children. |
| 2957 | If a number (or inequality) of arguments is |
| 2958 | .Pq n , |
| 2959 | then the macro accepts an arbitrary number of arguments. |
| 2960 | .Bd -literal -offset indent |
| 2961 | \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB |
| 2962 | |
| 2963 | \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... |
| 2964 | |
| 2965 | \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN |
| 2966 | .Ed |
| 2967 | .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent |
| 2968 | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments |
| 2969 | .It Sx \&%A Ta \&No Ta \&No Ta >0 |
| 2970 | .It Sx \&%B Ta \&No Ta \&No Ta >0 |
| 2971 | .It Sx \&%C Ta \&No Ta \&No Ta >0 |
| 2972 | .It Sx \&%D Ta \&No Ta \&No Ta >0 |
| 2973 | .It Sx \&%I Ta \&No Ta \&No Ta >0 |
| 2974 | .It Sx \&%J Ta \&No Ta \&No Ta >0 |
| 2975 | .It Sx \&%N Ta \&No Ta \&No Ta >0 |
| 2976 | .It Sx \&%O Ta \&No Ta \&No Ta >0 |
| 2977 | .It Sx \&%P Ta \&No Ta \&No Ta >0 |
| 2978 | .It Sx \&%Q Ta \&No Ta \&No Ta >0 |
| 2979 | .It Sx \&%R Ta \&No Ta \&No Ta >0 |
| 2980 | .It Sx \&%T Ta \&No Ta \&No Ta >0 |
| 2981 | .It Sx \&%U Ta \&No Ta \&No Ta >0 |
| 2982 | .It Sx \&%V Ta \&No Ta \&No Ta >0 |
| 2983 | .It Sx \&Ad Ta Yes Ta Yes Ta >0 |
| 2984 | .It Sx \&An Ta Yes Ta Yes Ta >0 |
| 2985 | .It Sx \&Ap Ta Yes Ta Yes Ta 0 |
| 2986 | .It Sx \&Ar Ta Yes Ta Yes Ta n |
| 2987 | .It Sx \&At Ta Yes Ta Yes Ta 1 |
| 2988 | .It Sx \&Bsx Ta Yes Ta Yes Ta n |
| 2989 | .It Sx \&Bt Ta \&No Ta \&No Ta 0 |
| 2990 | .It Sx \&Bx Ta Yes Ta Yes Ta n |
| 2991 | .It Sx \&Cd Ta Yes Ta Yes Ta >0 |
| 2992 | .It Sx \&Cm Ta Yes Ta Yes Ta >0 |
| 2993 | .It Sx \&Db Ta \&No Ta \&No Ta 1 |
| 2994 | .It Sx \&Dd Ta \&No Ta \&No Ta n |
| 2995 | .It Sx \&Dt Ta \&No Ta \&No Ta n |
| 2996 | .It Sx \&Dv Ta Yes Ta Yes Ta >0 |
| 2997 | .It Sx \&Dx Ta Yes Ta Yes Ta n |
| 2998 | .It Sx \&Em Ta Yes Ta Yes Ta >0 |
| 2999 | .It Sx \&Er Ta Yes Ta Yes Ta >0 |
| 3000 | .It Sx \&Es Ta Yes Ta Yes Ta 2 |
| 3001 | .It Sx \&Ev Ta Yes Ta Yes Ta >0 |
| 3002 | .It Sx \&Ex Ta \&No Ta \&No Ta n |
| 3003 | .It Sx \&Fa Ta Yes Ta Yes Ta >0 |
| 3004 | .It Sx \&Fd Ta \&No Ta \&No Ta >0 |
| 3005 | .It Sx \&Fl Ta Yes Ta Yes Ta n |
| 3006 | .It Sx \&Fn Ta Yes Ta Yes Ta >0 |
| 3007 | .It Sx \&Fr Ta Yes Ta Yes Ta >0 |
| 3008 | .It Sx \&Ft Ta Yes Ta Yes Ta >0 |
| 3009 | .It Sx \&Fx Ta Yes Ta Yes Ta n |
| 3010 | .It Sx \&Hf Ta \&No Ta \&No Ta n |
| 3011 | .It Sx \&Ic Ta Yes Ta Yes Ta >0 |
| 3012 | .It Sx \&In Ta \&No Ta \&No Ta 1 |
| 3013 | .It Sx \&Lb Ta \&No Ta \&No Ta 1 |
| 3014 | .It Sx \&Li Ta Yes Ta Yes Ta >0 |
| 3015 | .It Sx \&Lk Ta Yes Ta Yes Ta >0 |
| 3016 | .It Sx \&Lp Ta \&No Ta \&No Ta 0 |
| 3017 | .It Sx \&Ms Ta Yes Ta Yes Ta >0 |
| 3018 | .It Sx \&Mt Ta Yes Ta Yes Ta >0 |
| 3019 | .It Sx \&Nm Ta Yes Ta Yes Ta n |
| 3020 | .It Sx \&No Ta Yes Ta Yes Ta 0 |
| 3021 | .It Sx \&Ns Ta Yes Ta Yes Ta 0 |
| 3022 | .It Sx \&Nx Ta Yes Ta Yes Ta n |
| 3023 | .It Sx \&Os Ta \&No Ta \&No Ta n |
| 3024 | .It Sx \&Ot Ta Yes Ta Yes Ta >0 |
| 3025 | .It Sx \&Ox Ta Yes Ta Yes Ta n |
| 3026 | .It Sx \&Pa Ta Yes Ta Yes Ta n |
| 3027 | .It Sx \&Pf Ta Yes Ta Yes Ta 1 |
| 3028 | .It Sx \&Pp Ta \&No Ta \&No Ta 0 |
| 3029 | .It Sx \&Rv Ta \&No Ta \&No Ta n |
| 3030 | .It Sx \&Sm Ta \&No Ta \&No Ta <2 |
| 3031 | .It Sx \&St Ta \&No Ta Yes Ta 1 |
| 3032 | .It Sx \&Sx Ta Yes Ta Yes Ta >0 |
| 3033 | .It Sx \&Sy Ta Yes Ta Yes Ta >0 |
| 3034 | .It Sx \&Tn Ta Yes Ta Yes Ta >0 |
| 3035 | .It Sx \&Ud Ta \&No Ta \&No Ta 0 |
| 3036 | .It Sx \&Ux Ta Yes Ta Yes Ta n |
| 3037 | .It Sx \&Va Ta Yes Ta Yes Ta n |
| 3038 | .It Sx \&Vt Ta Yes Ta Yes Ta >0 |
| 3039 | .It Sx \&Xr Ta Yes Ta Yes Ta >0 |
| 3040 | .It Sx \&br Ta \&No Ta \&No Ta 0 |
| 3041 | .It Sx \&sp Ta \&No Ta \&No Ta 1 |
| 3042 | .El |
| 3043 | .Ss Delimiters |
| 3044 | When a macro argument consists of one single input character |
| 3045 | considered as a delimiter, the argument gets special handling. |
| 3046 | This does not apply when delimiters appear in arguments containing |
| 3047 | more than one character. |
| 3048 | Consequently, to prevent special handling and just handle it |
| 3049 | like any other argument, a delimiter can be escaped by prepending |
| 3050 | a zero-width space |
| 3051 | .Pq Sq \e& . |
| 3052 | In text lines, delimiters never need escaping, but may be used |
| 3053 | as normal punctuation. |
| 3054 | .Pp |
| 3055 | For many macros, when the leading arguments are opening delimiters, |
| 3056 | these delimiters are put before the macro scope, |
| 3057 | and when the trailing arguments are closing delimiters, |
| 3058 | these delimiters are put after the macro scope. |
| 3059 | For example, |
| 3060 | .Pp |
| 3061 | .D1 Pf \. \&Aq "( [ word ] ) ." |
| 3062 | .Pp |
| 3063 | renders as: |
| 3064 | .Pp |
| 3065 | .D1 Aq ( [ word ] ) . |
| 3066 | .Pp |
| 3067 | Opening delimiters are: |
| 3068 | .Pp |
| 3069 | .Bl -tag -width Ds -offset indent -compact |
| 3070 | .It \&( |
| 3071 | left parenthesis |
| 3072 | .It \&[ |
| 3073 | left bracket |
| 3074 | .El |
| 3075 | .Pp |
| 3076 | Closing delimiters are: |
| 3077 | .Pp |
| 3078 | .Bl -tag -width Ds -offset indent -compact |
| 3079 | .It \&. |
| 3080 | period |
| 3081 | .It \&, |
| 3082 | comma |
| 3083 | .It \&: |
| 3084 | colon |
| 3085 | .It \&; |
| 3086 | semicolon |
| 3087 | .It \&) |
| 3088 | right parenthesis |
| 3089 | .It \&] |
| 3090 | right bracket |
| 3091 | .It \&? |
| 3092 | question mark |
| 3093 | .It \&! |
| 3094 | exclamation mark |
| 3095 | .El |
| 3096 | .Pp |
| 3097 | Note that even a period preceded by a backslash |
| 3098 | .Pq Sq \e.\& |
| 3099 | gets this special handling; use |
| 3100 | .Sq \e&. |
| 3101 | to prevent that. |
| 3102 | .Pp |
| 3103 | Many in-line macros interrupt their scope when they encounter |
| 3104 | delimiters, and resume their scope when more arguments follow that |
| 3105 | are not delimiters. |
| 3106 | For example, |
| 3107 | .Pp |
| 3108 | .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" |
| 3109 | .Pp |
| 3110 | renders as: |
| 3111 | .Pp |
| 3112 | .D1 Fl a ( b | c \*(Ba d ) e |
| 3113 | .Pp |
| 3114 | This applies to both opening and closing delimiters, |
| 3115 | and also to the middle delimiter: |
| 3116 | .Pp |
| 3117 | .Bl -tag -width Ds -offset indent -compact |
| 3118 | .It \&| |
| 3119 | vertical bar |
| 3120 | .El |
| 3121 | .Pp |
| 3122 | As a special case, the predefined string \e*(Ba is handled and rendered |
| 3123 | in the same way as a plain |
| 3124 | .Sq \&| |
| 3125 | character. |
| 3126 | Using this predefined string is not recommended in new manuals. |
| 3127 | .Ss Font handling |
| 3128 | In |
| 3129 | .Nm |
| 3130 | documents, usage of semantic markup is recommended in order to have |
| 3131 | proper fonts automatically selected; only when no fitting semantic markup |
| 3132 | is available, consider falling back to |
| 3133 | .Sx Physical markup |
| 3134 | macros. |
| 3135 | Whenever any |
| 3136 | .Nm |
| 3137 | macro switches the |
| 3138 | .Xr roff 7 |
| 3139 | font mode, it will automatically restore the previous font when exiting |
| 3140 | its scope. |
| 3141 | Manually switching the font using the |
| 3142 | .Xr roff 7 |
| 3143 | .Ql \ef |
| 3144 | font escape sequences is never required. |
| 3145 | .Sh COMPATIBILITY |
| 3146 | This section provides an incomplete list of compatibility issues |
| 3147 | between mandoc and other troff implementations, at this time limited |
| 3148 | to GNU troff |
| 3149 | .Pq Qq groff . |
| 3150 | The term |
| 3151 | .Qq historic groff |
| 3152 | refers to groff versions before 1.17, |
| 3153 | which featured a significant update of the |
| 3154 | .Pa doc.tmac |
| 3155 | file. |
| 3156 | .Pp |
| 3157 | Heirloom troff, the other significant troff implementation accepting |
| 3158 | \-mdoc, is similar to historic groff. |
| 3159 | .Pp |
| 3160 | The following problematic behaviour is found in groff: |
| 3161 | .ds hist (Historic groff only.) |
| 3162 | .Pp |
| 3163 | .Bl -dash -compact |
| 3164 | .It |
| 3165 | Display macros |
| 3166 | .Po |
| 3167 | .Sx \&Bd , |
| 3168 | .Sx \&Dl , |
| 3169 | and |
| 3170 | .Sx \&D1 |
| 3171 | .Pc |
| 3172 | may not be nested. |
| 3173 | \*[hist] |
| 3174 | .It |
| 3175 | .Sx \&At |
| 3176 | with unknown arguments produces no output at all. |
| 3177 | \*[hist] |
| 3178 | Newer groff and mandoc print |
| 3179 | .Qq AT&T UNIX |
| 3180 | and the arguments. |
| 3181 | .It |
| 3182 | .Sx \&Bl Fl column |
| 3183 | does not recognise trailing punctuation characters when they immediately |
| 3184 | precede tabulator characters, but treats them as normal text and |
| 3185 | outputs a space before them. |
| 3186 | .It |
| 3187 | .Sx \&Bd Fl ragged compact |
| 3188 | does not start a new line. |
| 3189 | \*[hist] |
| 3190 | .It |
| 3191 | .Sx \&Dd |
| 3192 | with non-standard arguments behaves very strangely. |
| 3193 | When there are three arguments, they are printed verbatim. |
| 3194 | Any other number of arguments is replaced by the current date, |
| 3195 | but without any arguments the string |
| 3196 | .Dq Epoch |
| 3197 | is printed. |
| 3198 | .It |
| 3199 | .Sx \&Fl |
| 3200 | does not print a dash for an empty argument. |
| 3201 | \*[hist] |
| 3202 | .It |
| 3203 | .Sx \&Fn |
| 3204 | does not start a new line unless invoked as the line macro in the |
| 3205 | .Em SYNOPSIS |
| 3206 | section. |
| 3207 | \*[hist] |
| 3208 | .It |
| 3209 | .Sx \&Fo |
| 3210 | with |
| 3211 | .Pf non- Sx \&Fa |
| 3212 | children causes inconsistent spacing between arguments. |
| 3213 | In mandoc, a single space is always inserted between arguments. |
| 3214 | .It |
| 3215 | .Sx \&Ft |
| 3216 | in the |
| 3217 | .Em SYNOPSIS |
| 3218 | causes inconsistent vertical spacing, depending on whether a prior |
| 3219 | .Sx \&Fn |
| 3220 | has been invoked. |
| 3221 | See |
| 3222 | .Sx \&Ft |
| 3223 | and |
| 3224 | .Sx \&Fn |
| 3225 | for the normalised behaviour in mandoc. |
| 3226 | .It |
| 3227 | .Sx \&In |
| 3228 | ignores additional arguments and is not treated specially in the |
| 3229 | .Em SYNOPSIS . |
| 3230 | \*[hist] |
| 3231 | .It |
| 3232 | .Sx \&It |
| 3233 | sometimes requires a |
| 3234 | .Fl nested |
| 3235 | flag. |
| 3236 | \*[hist] |
| 3237 | In new groff and mandoc, any list may be nested by default and |
| 3238 | .Fl enum |
| 3239 | lists will restart the sequence only for the sub-list. |
| 3240 | .It |
| 3241 | .Sx \&Li |
| 3242 | followed by a delimiter is incorrectly used in some manuals |
| 3243 | instead of properly quoting that character, which sometimes works with |
| 3244 | historic groff. |
| 3245 | .It |
| 3246 | .Sx \&Lk |
| 3247 | only accepts a single link-name argument; the remainder is misformatted. |
| 3248 | .It |
| 3249 | .Sx \&Pa |
| 3250 | does not format its arguments when used in the FILES section under |
| 3251 | certain list types. |
| 3252 | .It |
| 3253 | .Sx \&Ta |
| 3254 | can only be called by other macros, but not at the beginning of a line. |
| 3255 | .It |
| 3256 | .Sx \&%C |
| 3257 | is not implemented (up to and including groff-1.22.2). |
| 3258 | .It |
| 3259 | Historic groff only allows up to eight or nine arguments per macro input |
| 3260 | line, depending on the exact situation. |
| 3261 | Providing more arguments causes garbled output. |
| 3262 | The number of arguments on one input line is not limited with mandoc. |
| 3263 | .It |
| 3264 | Historic groff has many un-callable macros. |
| 3265 | Most of these (excluding some block-level macros) are callable |
| 3266 | in new groff and mandoc. |
| 3267 | .It |
| 3268 | .Sq \(ba |
| 3269 | (vertical bar) is not fully supported as a delimiter. |
| 3270 | \*[hist] |
| 3271 | .It |
| 3272 | .Sq \ef |
| 3273 | .Pq font face |
| 3274 | and |
| 3275 | .Sq \eF |
| 3276 | .Pq font family face |
| 3277 | .Sx Text Decoration |
| 3278 | escapes behave irregularly when specified within line-macro scopes. |
| 3279 | .It |
| 3280 | Negative scaling units return to prior lines. |
| 3281 | Instead, mandoc truncates them to zero. |
| 3282 | .El |
| 3283 | .Pp |
| 3284 | The following features are unimplemented in mandoc: |
| 3285 | .Pp |
| 3286 | .Bl -dash -compact |
| 3287 | .It |
| 3288 | .Sx \&Bd |
| 3289 | .Fl file Ar file . |
| 3290 | .It |
| 3291 | .Sx \&Bd |
| 3292 | .Fl offset Cm center |
| 3293 | and |
| 3294 | .Fl offset Cm right . |
| 3295 | Groff does not implement centred and flush-right rendering either, |
| 3296 | but produces large indentations. |
| 3297 | .El |
| 3298 | .Sh SEE ALSO |
| 3299 | .Xr man 1 , |
| 3300 | .Xr mandoc 1 , |
| 3301 | .Xr eqn 7 , |
| 3302 | .Xr man 7 , |
| 3303 | .Xr mandoc_char 7 , |
| 3304 | .Xr roff 7 , |
| 3305 | .Xr tbl 7 |
| 3306 | .Sh HISTORY |
| 3307 | The |
| 3308 | .Nm |
| 3309 | language first appeared as a troff macro package in |
| 3310 | .Bx 4.4 . |
| 3311 | It was later significantly updated by Werner Lemberg and Ruslan Ermilov |
| 3312 | in groff-1.17. |
| 3313 | The standalone implementation that is part of the |
| 3314 | .Xr mandoc 1 |
| 3315 | utility written by Kristaps Dzonsons appeared in |
| 3316 | .Ox 4.6 . |
| 3317 | .Sh AUTHORS |
| 3318 | The |
| 3319 | .Nm |
| 3320 | reference was written by |
| 3321 | .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |