Print this page
feedback from Hans
   1 .\"
   2 .\" Permission to use, copy, modify, and distribute this software for any
   3 .\" purpose with or without fee is hereby granted, provided that the above
   4 .\" copyright notice and this permission notice appear in all copies.
   5 .\"
   6 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   7 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   8 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   9 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  10 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  11 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  12 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  13 .\"
  14 .\"
  15 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  16 .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
  17 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.

  18 .\"
  19 .Dd Jan 3, 2012
  20 .Dt MDOC 5
  21 .Os
  22 .Sh NAME
  23 .Nm mdoc
  24 .Nd semantic markup language for formatting manual pages
  25 .Sh DESCRIPTION
  26 The
  27 .Nm mdoc
  28 language supports authoring of manual pages for the
  29 .Xr man 1
  30 utility by allowing semantic annotations of words, phrases,
  31 page sections and complete manual pages.
  32 Such annotations are used by formatting tools to achieve a uniform
  33 presentation across all manuals written in
  34 .Nm ,
  35 and to support hyperlinking if supported by the output medium.
  36 .Pp
  37 This reference document describes the structure of manual pages
  38 and the syntax and usage of the
  39 .Nm


 131 \&.Nm progname
 132 \&.Op Fl options
 133 \&.Ar
 134 \&.Sh DESCRIPTION
 135 The
 136 \&.Nm
 137 utility processes files ...
 138 \&.\e\(dq .Sh IMPLEMENTATION NOTES
 139 \&.\e\(dq .Sh RETURN VALUES
 140 \&.\e\(dq For sections 2, 3, & 9 only.
 141 \&.\e\(dq .Sh ENVIRONMENT
 142 \&.\e\(dq For sections 1, 1M, 5, & 6 only.
 143 \&.\e\(dq .Sh FILES
 144 \&.\e\(dq .Sh EXIT STATUS
 145 \&.\e\(dq For sections 1, 1M, & 6 only.
 146 \&.\e\(dq .Sh EXAMPLES
 147 \&.\e\(dq .Sh DIAGNOSTICS
 148 \&.\e\(dq For sections 1, 1M, 5, 6, & 7 only.
 149 \&.\e\(dq .Sh ERRORS
 150 \&.\e\(dq For sections 2, 3, & 9 only.






 151 \&.\e\(dq .Sh SEE ALSO
 152 \&.\e\(dq .Xr foobar 1
 153 \&.\e\(dq .Sh STANDARDS
 154 \&.\e\(dq .Sh HISTORY
 155 \&.\e\(dq .Sh AUTHORS
 156 \&.\e\(dq .Sh CAVEATS
 157 \&.\e\(dq .Sh BUGS
 158 \&.\e\(dq .Sh SECURITY CONSIDERATIONS
 159 \&.\e\(dq Not used in OpenBSD.
 160 .Ed
 161 .Pp
 162 The sections in an
 163 .Nm
 164 document are conventionally ordered as they appear above.
 165 Sections should be composed as follows:
 166 .Bl -ohang -offset Ds
 167 .It Em NAME
 168 The name(s) and a one line description of the documented material.
 169 The syntax for this as follows:
 170 .Bd -literal -offset indent


 355 .It Em EXAMPLES
 356 Example usages.
 357 This often contains snippets of well-formed, well-tested invocations.
 358 Make sure that examples work properly!
 359 .It Em DIAGNOSTICS
 360 Documents error conditions.
 361 This is most useful in section 4 manuals.
 362 Historically, this section was used in place of
 363 .Em EXIT STATUS
 364 for manuals in sections 1, 6, and 8; however, this practise is
 365 discouraged.
 366 .Pp
 367 See
 368 .Sx \&Bl
 369 .Fl diag .
 370 .It Em ERRORS
 371 Documents error handling in sections 2, 3, and 9.
 372 .Pp
 373 See
 374 .Sx \&Er .
















































































































 375 .It Em SEE ALSO
 376 References other manuals with related topics.
 377 This section should exist for most manuals.
 378 Cross-references should conventionally be ordered first by section, then
 379 alphabetically.
 380 .Pp
 381 References to other documentation concerning the topic of the manual page,
 382 for example authoritative books or journal articles, may also be
 383 provided in this section.
 384 .Pp
 385 See
 386 .Sx \&Rs
 387 and
 388 .Sx \&Xr .
 389 .It Em STANDARDS
 390 References any standards implemented or used.
 391 If not adhering to any standards, the
 392 .Em HISTORY
 393 section should be used instead.
 394 .Pp


1216 .It
1217 If no date string is given, the current date is used.
1218 .El
1219 .Pp
1220 Examples:
1221 .Dl \&.Dd $\&Mdocdate$
1222 .Dl \&.Dd $\&Mdocdate: July 21 2007$
1223 .Dl \&.Dd July 21, 2007
1224 .Pp
1225 See also
1226 .Sx \&Dt
1227 and
1228 .Sx \&Os .
1229 .Ss \&Dl
1230 One-line intended display.
1231 This is formatted as literal text and is useful for commands and
1232 invocations.
1233 It is followed by a newline.
1234 .Pp
1235 Examples:
1236 .Dl \&.Dl % mandoc mdoc.7 \e(ba less
1237 .Pp
1238 See also
1239 .Sx \&Bd
1240 and
1241 .Sx \&D1 .
1242 .Ss \&Do
1243 Begin a block enclosed by double quotes.
1244 Does not have any head arguments.
1245 .Pp
1246 Examples:
1247 .Bd -literal -offset indent -compact
1248 \&.Do
1249 April is the cruellest month
1250 \&.Dc
1251 \e(em T.S. Eliot
1252 .Ed
1253 .Pp
1254 See also
1255 .Sx \&Dq .
1256 .Ss \&Dq


1401 argument is used as the enclosure head, for example, specifying \e(lq
1402 will emulate
1403 .Sx \&Do .
1404 .Ss \&Er
1405 Error constants for definitions of the
1406 .Va errno
1407 libc global variable.
1408 This is most often used in section 2 and 3 manual pages.
1409 .Pp
1410 Examples:
1411 .Dl \&.Er EPERM
1412 .Dl \&.Er ENOENT
1413 .Pp
1414 See also
1415 .Sx \&Dv
1416 for general constants.
1417 .Ss \&Es
1418 This macro is obsolete and not implemented.
1419 .Ss \&Ev
1420 Environmental variables such as those specified in
1421 .Xr environ 7 .
1422 .Pp
1423 Examples:
1424 .Dl \&.Ev DISPLAY
1425 .Dl \&.Ev PATH
1426 .Pp
1427 See also
1428 .Sx \&Dv
1429 for general constants.
1430 .Ss \&Ex
1431 Insert a standard sentence regarding command exit values of 0 on success
1432 and >0 on failure.
1433 This is most often used in section 1, 6, and 8 manual pages.
1434 Its syntax is as follows:
1435 .Pp
1436 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1437 .Pp
1438 If
1439 .Ar utility
1440 is not specified, the document's name set by
1441 .Sx \&Nm


2015 .Dl \&.Ox 4.5
2016 .Dl \&.Ox
2017 .Pp
2018 See also
2019 .Sx \&At ,
2020 .Sx \&Bsx ,
2021 .Sx \&Bx ,
2022 .Sx \&Dx ,
2023 .Sx \&Fx ,
2024 .Sx \&Nx ,
2025 and
2026 .Sx \&Ux .
2027 .Ss \&Pa
2028 An absolute or relative file system path, or a file or directory name.
2029 If an argument is not provided, the character
2030 .Sq \(ti
2031 is used as a default.
2032 .Pp
2033 Examples:
2034 .Dl \&.Pa /usr/bin/mandoc
2035 .Dl \&.Pa /usr/share/man/man7/mdoc.7
2036 .Pp
2037 See also
2038 .Sx \&Lk .
2039 .Ss \&Pc
2040 Close parenthesised context opened by
2041 .Sx \&Po .
2042 .Ss \&Pf
2043 Removes the space between its argument
2044 .Pq Dq prefix
2045 and the following macro.
2046 Its syntax is as follows:
2047 .Pp
2048 .D1 .Pf Ar prefix macro arguments ...
2049 .Pp
2050 This is equivalent to:
2051 .Pp
2052 .D1 .No Ar prefix No \&Ns Ar macro arguments ...
2053 .Pp
2054 Examples:
2055 .Dl ".Pf $ Ar variable_name"


3066 .El
3067 .Sh SEE ALSO
3068 .Xr man 1 ,
3069 .Xr mandoc 1 ,
3070 .Xr eqn 5 ,
3071 .Xr man 5 ,
3072 .Xr mandoc_char 5 ,
3073 .Xr roff 5 ,
3074 .Xr tbl 5
3075 .Sh HISTORY
3076 The
3077 .Nm
3078 language first appeared as a troff macro package in
3079 .Bx 4.4 .
3080 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3081 in groff-1.17.
3082 The standalone implementation that is part of the
3083 .Xr mandoc 1
3084 utility written by Kristaps Dzonsons appeared in
3085 .Ox 4.6 .

3086 .Sh AUTHORS
3087 The
3088 .Nm
3089 reference was written by
3090 .An Kristaps Dzonsons ,
3091 .Mt kristaps@bsd.lv .
   1 .\"
   2 .\" Permission to use, copy, modify, and distribute this software for any
   3 .\" purpose with or without fee is hereby granted, provided that the above
   4 .\" copyright notice and this permission notice appear in all copies.
   5 .\"
   6 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   7 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   8 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   9 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  10 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  11 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  12 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  13 .\"
  14 .\"
  15 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  16 .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
  17 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
  18 .\" Copyright 2014 Garrett D'Amore <garrett@dmaore.org>
  19 .\"
  20 .Dd Jul 16, 2014
  21 .Dt MDOC 5
  22 .Os
  23 .Sh NAME
  24 .Nm mdoc
  25 .Nd semantic markup language for formatting manual pages
  26 .Sh DESCRIPTION
  27 The
  28 .Nm mdoc
  29 language supports authoring of manual pages for the
  30 .Xr man 1
  31 utility by allowing semantic annotations of words, phrases,
  32 page sections and complete manual pages.
  33 Such annotations are used by formatting tools to achieve a uniform
  34 presentation across all manuals written in
  35 .Nm ,
  36 and to support hyperlinking if supported by the output medium.
  37 .Pp
  38 This reference document describes the structure of manual pages
  39 and the syntax and usage of the
  40 .Nm


 132 \&.Nm progname
 133 \&.Op Fl options
 134 \&.Ar
 135 \&.Sh DESCRIPTION
 136 The
 137 \&.Nm
 138 utility processes files ...
 139 \&.\e\(dq .Sh IMPLEMENTATION NOTES
 140 \&.\e\(dq .Sh RETURN VALUES
 141 \&.\e\(dq For sections 2, 3, & 9 only.
 142 \&.\e\(dq .Sh ENVIRONMENT
 143 \&.\e\(dq For sections 1, 1M, 5, & 6 only.
 144 \&.\e\(dq .Sh FILES
 145 \&.\e\(dq .Sh EXIT STATUS
 146 \&.\e\(dq For sections 1, 1M, & 6 only.
 147 \&.\e\(dq .Sh EXAMPLES
 148 \&.\e\(dq .Sh DIAGNOSTICS
 149 \&.\e\(dq For sections 1, 1M, 5, 6, & 7 only.
 150 \&.\e\(dq .Sh ERRORS
 151 \&.\e\(dq For sections 2, 3, & 9 only.
 152 \&.\e\(dq .Sh ARCHITECTURE
 153 \&.\e\(dq .Sh CODE SET INDEPENDENCE
 154 \&.\e\(dq For sections 1, 1M, & 3 only.
 155 \&.\e\(dq .Sh INTERFACE STABILITY
 156 \&.\e\(dq .Sh MT-LEVEL
 157 \&.\e\(dq For sections 2 & 3 only.
 158 \&.\e\(dq .Sh SEE ALSO
 159 \&.\e\(dq .Xr foobar 1
 160 \&.\e\(dq .Sh STANDARDS
 161 \&.\e\(dq .Sh HISTORY
 162 \&.\e\(dq .Sh AUTHORS
 163 \&.\e\(dq .Sh CAVEATS
 164 \&.\e\(dq .Sh BUGS
 165 \&.\e\(dq .Sh SECURITY CONSIDERATIONS
 166 \&.\e\(dq Not used in OpenBSD.
 167 .Ed
 168 .Pp
 169 The sections in an
 170 .Nm
 171 document are conventionally ordered as they appear above.
 172 Sections should be composed as follows:
 173 .Bl -ohang -offset Ds
 174 .It Em NAME
 175 The name(s) and a one line description of the documented material.
 176 The syntax for this as follows:
 177 .Bd -literal -offset indent


 362 .It Em EXAMPLES
 363 Example usages.
 364 This often contains snippets of well-formed, well-tested invocations.
 365 Make sure that examples work properly!
 366 .It Em DIAGNOSTICS
 367 Documents error conditions.
 368 This is most useful in section 4 manuals.
 369 Historically, this section was used in place of
 370 .Em EXIT STATUS
 371 for manuals in sections 1, 6, and 8; however, this practise is
 372 discouraged.
 373 .Pp
 374 See
 375 .Sx \&Bl
 376 .Fl diag .
 377 .It Em ERRORS
 378 Documents error handling in sections 2, 3, and 9.
 379 .Pp
 380 See
 381 .Sx \&Er .
 382 .It Em ARCHITECTURE
 383 This section is usually absent, but will be present when the
 384 interface is specific to one or more architectures.
 385 .It Em CODE SET INDEPENDENCE
 386 Indicates whether the interface operates correctly with various different
 387 code sets.  True independent code sets will support not only ASCII and
 388 Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
 389 UTF-8 and GB2312.
 390 .Pp
 391 Generally there will be some limitations that are fairly standard.  See
 392 .Xr standards 5 for more information about some of these.  Most interfaces
 393 should support at least UTF-8 in addition to ASCII.
 394 .It Em INTERFACE STABILITY
 395 Indicates the level of commitment to the interface. Interfaces can be described
 396 with in the following ways:
 397 .Bl -tag
 398 .It Nm Standard
 399 Indicates that the interface is defined by one or more standards bodies.
 400 Generally, changes to the interface will be carefully managed to conform
 401 to the relevant standards.  These interfaces are generally the most suitable
 402 for use in portable programs.
 403 .It Nm Committed
 404 Indicates that the interface is intended to be preserved for the long-haul, and
 405 will rarely, if ever change, and never without notification (barring
 406 extraordinary and extenuating circumstances). These interfaces are 
 407 preferred over other interfaces with the exeception of
 408 .Nm Standard
 409 interfaces.
 410 .It Nm Uncommitted
 411 Indicates that the interface may change.  Generally, changes to these interfaces
 412 should be infrequent, and some effort will be made to address compatibility
 413 considerations when changing or removing such interfaces.  However, there is
 414 no firm commitment to the preservation of the interface.  Most often this
 415 is applied to interfaces where operational experience with the interface
 416 is still limited and some need to change may be anticipated.
 417 .Pp
 418 Consumers should expect to revalidate any
 419 .Nm Uncommitted
 420 interfaces when crossing release boundaries.  Products intended for
 421 use on many releases or intended to support compatibility with future
 422 releases should avoid these interfaces.
 423 .It Nm Volatile
 424 The interface can change at any time for any reason. Often this relates to
 425 interfaces that are part of external software components that are still evolving
 426 rapidly.  Consumers should not expect that the interface (either binary or
 427 source level) will be unchanged from one release to the next.
 428 .It Nm Not-an-Interface
 429 Describes something that is specifically not intended for programmatic
 430 consumption.  For example, specific human-readable output, or the layout
 431 of graphical items on a user interface, may be described this way.  Generally
 432 programmatic alternatives to these will be available, and should be used
 433 when programmatic consumption is needed.
 434 .It Nm Private
 435 This is an internal interface.  Generally these interfaces should only be
 436 used within the project, and should not be used by other programs or modules.
 437 The interface can and will change without notice as the project needs, at
 438 any time.
 439 .Pp
 440 Most often, Private interfaces will lack any documentation whatsoever, and
 441 generally any undocumented interface can be assumed to be Private.
 442 .It Nm Obsolete
 443 The interface is not intended for use in new projects or programs, and may
 444 be removed at a future date.  The
 445 .Nm Obsolete
 446 word is a modifier that can
 447 be applied to other commitment levels. For example an
 448 .Nm Obsolete Committed
 449 interface is unlikely to be removed or changed, but nonetheless new use
 450 is discouraged (perhaps a better newer alternative is present).
 451 .El
 452 .It Em MT-LEVEL
 453 This section describes considerations for the interface when used within
 454 programs that use multiple threads.  More discussion of these considerations
 455 is made in the MT-Level section of
 456 .Xr attributes 5 .
 457 The interface can be described in the following ways.
 458 .Bl -tag
 459 .It Nm Safe
 460 Indicates the interface is safe for use within multiple threads.  There
 461 may be additional caveats that apply, in which case those will be
 462 described.  Note that some interfaces have semantics which may affect
 463 other threads, but these should be an intrinsic part of the interface
 464 rather than an unexpected side effect.  For example, closing a file in
 465 one thread will cause that file to be closed in all threads.
 466 .It Nm Unsafe
 467 Indicates the interface is unsuitable for concurrent use within multiple
 468 threads.  A threaded application may still make use of the interface, but
 469 will be required to provide external synchronization means to ensure that
 470 only a single thread calls the interface at a time.
 471 .It Nm MT-Safe
 472 Indicates that the interface is not only safe for concurrent use, but is
 473 designed for such use.  For example, a
 474 .Nm Safe
 475 interface may make use of a global lock to provide safety, but at reduced
 476 internal concurrency, whereas an
 477 .Nm MT-Safe
 478 interface will be designed to be efficient even when used concurrently.
 479 .It Nm Async-Signal-Safe
 480 Indicates that the library is safe for use within a signal handler.  An
 481 .Nm MT-Safe
 482 interface can be made
 483 .Nm Async-Signal-Safe
 484 by ensuring that it blocks signals when acquiring locks.
 485 .It Nm Safe with Exections
 486 As for
 487 .Nm Safe
 488 but with specific exceptions noted.
 489 .It Nm MT-Safe with Exections
 490 As for
 491 .Nm MT-Safe
 492 but with specific exceptions noted.
 493 .El
 494 .It Em SEE ALSO
 495 References other manuals with related topics.
 496 This section should exist for most manuals.
 497 Cross-references should conventionally be ordered first by section, then
 498 alphabetically.
 499 .Pp
 500 References to other documentation concerning the topic of the manual page,
 501 for example authoritative books or journal articles, may also be
 502 provided in this section.
 503 .Pp
 504 See
 505 .Sx \&Rs
 506 and
 507 .Sx \&Xr .
 508 .It Em STANDARDS
 509 References any standards implemented or used.
 510 If not adhering to any standards, the
 511 .Em HISTORY
 512 section should be used instead.
 513 .Pp


1335 .It
1336 If no date string is given, the current date is used.
1337 .El
1338 .Pp
1339 Examples:
1340 .Dl \&.Dd $\&Mdocdate$
1341 .Dl \&.Dd $\&Mdocdate: July 21 2007$
1342 .Dl \&.Dd July 21, 2007
1343 .Pp
1344 See also
1345 .Sx \&Dt
1346 and
1347 .Sx \&Os .
1348 .Ss \&Dl
1349 One-line intended display.
1350 This is formatted as literal text and is useful for commands and
1351 invocations.
1352 It is followed by a newline.
1353 .Pp
1354 Examples:
1355 .Dl \&.Dl % mandoc mdoc.5 \e(ba less
1356 .Pp
1357 See also
1358 .Sx \&Bd
1359 and
1360 .Sx \&D1 .
1361 .Ss \&Do
1362 Begin a block enclosed by double quotes.
1363 Does not have any head arguments.
1364 .Pp
1365 Examples:
1366 .Bd -literal -offset indent -compact
1367 \&.Do
1368 April is the cruellest month
1369 \&.Dc
1370 \e(em T.S. Eliot
1371 .Ed
1372 .Pp
1373 See also
1374 .Sx \&Dq .
1375 .Ss \&Dq


1520 argument is used as the enclosure head, for example, specifying \e(lq
1521 will emulate
1522 .Sx \&Do .
1523 .Ss \&Er
1524 Error constants for definitions of the
1525 .Va errno
1526 libc global variable.
1527 This is most often used in section 2 and 3 manual pages.
1528 .Pp
1529 Examples:
1530 .Dl \&.Er EPERM
1531 .Dl \&.Er ENOENT
1532 .Pp
1533 See also
1534 .Sx \&Dv
1535 for general constants.
1536 .Ss \&Es
1537 This macro is obsolete and not implemented.
1538 .Ss \&Ev
1539 Environmental variables such as those specified in
1540 .Xr environ 5 .
1541 .Pp
1542 Examples:
1543 .Dl \&.Ev DISPLAY
1544 .Dl \&.Ev PATH
1545 .Pp
1546 See also
1547 .Sx \&Dv
1548 for general constants.
1549 .Ss \&Ex
1550 Insert a standard sentence regarding command exit values of 0 on success
1551 and >0 on failure.
1552 This is most often used in section 1, 6, and 8 manual pages.
1553 Its syntax is as follows:
1554 .Pp
1555 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1556 .Pp
1557 If
1558 .Ar utility
1559 is not specified, the document's name set by
1560 .Sx \&Nm


2134 .Dl \&.Ox 4.5
2135 .Dl \&.Ox
2136 .Pp
2137 See also
2138 .Sx \&At ,
2139 .Sx \&Bsx ,
2140 .Sx \&Bx ,
2141 .Sx \&Dx ,
2142 .Sx \&Fx ,
2143 .Sx \&Nx ,
2144 and
2145 .Sx \&Ux .
2146 .Ss \&Pa
2147 An absolute or relative file system path, or a file or directory name.
2148 If an argument is not provided, the character
2149 .Sq \(ti
2150 is used as a default.
2151 .Pp
2152 Examples:
2153 .Dl \&.Pa /usr/bin/mandoc
2154 .Dl \&.Pa /usr/share/man/man5/mdoc.5
2155 .Pp
2156 See also
2157 .Sx \&Lk .
2158 .Ss \&Pc
2159 Close parenthesised context opened by
2160 .Sx \&Po .
2161 .Ss \&Pf
2162 Removes the space between its argument
2163 .Pq Dq prefix
2164 and the following macro.
2165 Its syntax is as follows:
2166 .Pp
2167 .D1 .Pf Ar prefix macro arguments ...
2168 .Pp
2169 This is equivalent to:
2170 .Pp
2171 .D1 .No Ar prefix No \&Ns Ar macro arguments ...
2172 .Pp
2173 Examples:
2174 .Dl ".Pf $ Ar variable_name"


3185 .El
3186 .Sh SEE ALSO
3187 .Xr man 1 ,
3188 .Xr mandoc 1 ,
3189 .Xr eqn 5 ,
3190 .Xr man 5 ,
3191 .Xr mandoc_char 5 ,
3192 .Xr roff 5 ,
3193 .Xr tbl 5
3194 .Sh HISTORY
3195 The
3196 .Nm
3197 language first appeared as a troff macro package in
3198 .Bx 4.4 .
3199 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3200 in groff-1.17.
3201 The standalone implementation that is part of the
3202 .Xr mandoc 1
3203 utility written by Kristaps Dzonsons appeared in
3204 .Ox 4.6 .
3205 in July, 2014.
3206 .Sh AUTHORS
3207 The
3208 .Nm
3209 reference was written by
3210 .An Kristaps Dzonsons ,
3211 .Mt kristaps@bsd.lv .