Print this page
Latest round of fixes per RM and AL.  Fix bugs found in man.c.
   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


 123 \&.Dd Jan 1, 1970
 124 \&.Dt PROGNAME section
 125 \&.Os
 126 \&.Sh NAME
 127 \&.Nm progname
 128 \&.Nd one line description
 129 \&.\e\(dq .Sh LIBRARY
 130 \&.\e\(dq For sections 2, 3, & 9 only.
 131 \&.Sh SYNOPSIS
 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
 178 \&.Nm name0 ,
 179 \&.Nm name1 ,
 180 \&.Nm name2
 181 \&.Nd a one line description
 182 .Ed
 183 .Pp
 184 Multiple
 185 .Sq \&Nm
 186 names should be separated by commas.


 192 macro.
 193 .Pp
 194 See
 195 .Sx \&Nm
 196 and
 197 .Sx \&Nd .
 198 .It Em LIBRARY
 199 The name of the library containing the documented material, which is
 200 assumed to be a function in a section 2, 3, or 9 manual.
 201 The syntax for this is as follows:
 202 .Bd -literal -offset indent
 203 \&.Lb libarm
 204 .Ed
 205 .Pp
 206 See
 207 .Sx \&Lb .
 208 .It Em SYNOPSIS
 209 Documents the utility invocation syntax, function call syntax, or device
 210 configuration.
 211 .Pp
 212 For the first, utilities (sections 1, 1M, and 6), this is
 213 generally structured as follows:
 214 .Bd -literal -offset indent
 215 \&.Nm bar
 216 \&.Op Fl v
 217 \&.Op Fl o Ar file
 218 \&.Op Ar
 219 \&.Nm foo
 220 \&.Op Fl v
 221 \&.Op Fl o Ar file
 222 \&.Op Ar
 223 .Ed
 224 .Pp
 225 Commands should be ordered alphabetically.
 226 .Pp
 227 For the second, function calls (sections 2, 3, 9):
 228 .Bd -literal -offset indent
 229 \&.In header.h
 230 \&.Vt extern const char *global;
 231 \&.Ft "char *"
 232 \&.Fn foo "const char *src"
 233 \&.Ft "char *"
 234 \&.Fn bar "const char *src"
 235 .Ed
 236 .Pp
 237 Ordering of
 238 .Sx \&In ,
 239 .Sx \&Vt ,
 240 .Sx \&Fn ,
 241 and
 242 .Sx \&Fo
 243 macros should follow C header-file conventions.
 244 .Pp
 245 And for the third, configurations (section 7):
 246 .Bd -literal -offset indent
 247 \&.Cd \(dqit* at isa? port 0x2e\(dq
 248 \&.Cd \(dqit* at isa? port 0x4e\(dq
 249 .Ed
 250 .Pp
 251 Manuals not in these sections generally don't need a
 252 .Em SYNOPSIS .
 253 .Pp
 254 Some macros are displayed differently in the
 255 .Em SYNOPSIS
 256 section, particularly
 257 .Sx \&Nm ,
 258 .Sx \&Cd ,
 259 .Sx \&Fd ,
 260 .Sx \&Fn ,
 261 .Sx \&Fo ,
 262 .Sx \&In ,
 263 .Sx \&Vt ,
 264 and
 265 .Sx \&Ft .
 266 All of these macros are output on their own line.
 267 If two such dissimilar macros are pairwise invoked (except for
 268 .Sx \&Ft


 335 See
 336 .Sx \&Rv .
 337 .It Em ENVIRONMENT
 338 Lists the environment variables used by the utility,
 339 and explains the syntax and semantics of their values.
 340 The
 341 .Xr environ 5
 342 manual provides examples of typical content and formatting.
 343 .Pp
 344 See
 345 .Sx \&Ev .
 346 .It Em FILES
 347 Documents files used.
 348 It's helpful to document both the file name and a short description of how
 349 the file is used (created, modified, etc.).
 350 .Pp
 351 See
 352 .Sx \&Pa .
 353 .It Em EXIT STATUS
 354 This section documents the
 355 command exit status for section 1, 6, and 8 utilities.
 356 Historically, this information was described in
 357 .Em DIAGNOSTICS ,
 358 a practise that is now discouraged.
 359 .Pp
 360 See
 361 .Sx \&Ex .
 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


 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
 514 See
 515 .Sx \&St .
 516 .It Em HISTORY
 517 A brief history of the subject, including where it was first implemented,
 518 and when it was ported to or reimplemented for the operating system at hand.
 519 .It Em AUTHORS
 520 Credits to the person or persons who wrote the code and/or documentation.
 521 Authors should generally be noted by both name and email address.
 522 .Pp
 523 See
 524 .Sx \&An .
 525 .It Em CAVEATS
 526 Common misuses and misunderstandings should be explained
 527 in this section.
 528 .It Em BUGS
 529 Known bugs, limitations, and work-arounds should be described
 530 in this section.
 531 .It Em SECURITY CONSIDERATIONS
 532 Documents any security precautions that operators should consider.
 533 .El
 534 .Sh MACRO OVERVIEW
 535 This overview is sorted such that macros of similar purpose are listed
 536 together, to help find the best macro for any given purpose.
 537 Deprecated macros are not included in the overview, but can be found below
 538 in the alphabetical
 539 .Sx MACRO REFERENCE .
 540 .Ss Document preamble and NAME section macros
 541 .Bl -column "Brq, Bro, Brc" description
 542 .It Sx \&Dd Ta document date: Ar month day , year
 543 .It Sx \&Dt Ta document title: Ar TITLE SECTION Op Ar volume | arch
 544 .It Sx \&Os Ta operating system version: Op Ar system Op Ar version
 545 .It Sx \&Nm Ta document name (one argument)
 546 .It Sx \&Nd Ta document description (one line)
 547 .El
 548 .Ss Sections and cross references
 549 .Bl -column "Brq, Bro, Brc" description
 550 .It Sx \&Sh Ta section header (one line)
 551 .It Sx \&Ss Ta subsection header (one line)
 552 .It Sx \&Sx Ta internal cross reference to a section or subsection


1228 .Dq is currently in beta test.
1229 .Ss \&Bx
1230 Format the BSD version provided as an argument, or a default value if no
1231 argument is provided.
1232 .Pp
1233 Examples:
1234 .Dl \&.Bx 4.3 Tahoe
1235 .Dl \&.Bx 4.4
1236 .Dl \&.Bx
1237 .Pp
1238 See also
1239 .Sx \&At ,
1240 .Sx \&Bsx ,
1241 .Sx \&Dx ,
1242 .Sx \&Fx ,
1243 .Sx \&Nx ,
1244 .Sx \&Ox ,
1245 and
1246 .Sx \&Ux .
1247 .Ss \&Cd
1248 Kernel configuration declaration.
1249 This denotes strings accepted by
1250 .Xr config 8 .
1251 It is most often used in section 4 manual pages.
1252 .Pp
1253 Examples:
1254 .Dl \&.Cd device le0 at scode?
1255 .Pp
1256 .Em Remarks :
1257 this macro is commonly abused by using quoted literals to retain
1258 whitespace and align consecutive
1259 .Sx \&Cd
1260 declarations.
1261 This practise is discouraged.
1262 .Ss \&Cm
1263 Command modifiers.
1264 Typically used for fixed strings passed as arguments, unless
1265 .Sx \&Fl
1266 is more appropriate.
1267 Also useful when specifying configuration options or keys.
1268 .Pp
1269 Examples:
1270 .Dl ".Nm mt Fl f Ar device Cm rewind"
1271 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"


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
1561 is used.
1562 Multiple
1563 .Ar utility
1564 arguments are treated as separate utilities.
1565 .Pp
1566 See also
1567 .Sx \&Rv .
1568 .Ss \&Fa
1569 Function argument.
1570 Its syntax is as follows:
1571 .Bd -ragged -offset indent
1572 .Pf \. Sx \&Fa


1948 .Sx \&Nm
1949 macro.
1950 .Pp
1951 Examples:
1952 .Dl Pf . Sx \&Nd mdoc language reference
1953 .Dl Pf . Sx \&Nd format and display UNIX manuals
1954 .Pp
1955 The
1956 .Sx \&Nd
1957 macro technically accepts child macros and terminates with a subsequent
1958 .Sx \&Sh
1959 invocation.
1960 Do not assume this behaviour: some
1961 .Xr whatis 1
1962 database generators are not smart enough to parse more than the line
1963 arguments and will display macros verbatim.
1964 .Pp
1965 See also
1966 .Sx \&Nm .
1967 .Ss \&Nm
1968 The name of the manual page, or \(em in particular in section 1, 6,
1969 and 8 pages \(em of an additional command or feature documented in
1970 the manual page.
1971 When first invoked, the
1972 .Sx \&Nm
1973 macro expects a single argument, the name of the manual page.
1974 Usually, the first invocation happens in the
1975 .Em NAME
1976 section of the page.
1977 The specified name will be remembered and used whenever the macro is
1978 called again without arguments later in the page.
1979 The
1980 .Sx \&Nm
1981 macro uses
1982 .Sx Block full-implicit
1983 semantics when invoked as the first macro on an input line in the
1984 .Em SYNOPSIS
1985 section; otherwise, it uses ordinary
1986 .Sx In-line
1987 semantics.
1988 .Pp
1989 Examples:


2066 .Sx \&Ux .
2067 .Ss \&Oc
2068 Close multi-line
2069 .Sx \&Oo
2070 context.
2071 .Ss \&Oo
2072 Multi-line version of
2073 .Sx \&Op .
2074 .Pp
2075 Examples:
2076 .Bd -literal -offset indent -compact
2077 \&.Oo
2078 \&.Op Fl flag Ns Ar value
2079 \&.Oc
2080 .Ed
2081 .Ss \&Op
2082 Optional part of a command line.
2083 Prints the argument(s) in brackets.
2084 This is most often used in the
2085 .Em SYNOPSIS
2086 section of section 1 and 8 manual pages.
2087 .Pp
2088 Examples:
2089 .Dl \&.Op \&Fl a \&Ar b
2090 .Dl \&.Op \&Ar a | b
2091 .Pp
2092 See also
2093 .Sx \&Oo .
2094 .Ss \&Os
2095 Document operating system version.
2096 This is the mandatory third macro of
2097 any
2098 .Nm
2099 file.
2100 Its syntax is as follows:
2101 .Pp
2102 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2103 .Pp
2104 The optional
2105 .Ar system
2106 parameter specifies the relevant operating system or environment.


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 .
   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 19, 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


 123 \&.Dd Jan 1, 1970
 124 \&.Dt PROGNAME section
 125 \&.Os
 126 \&.Sh NAME
 127 \&.Nm progname
 128 \&.Nd one line description
 129 \&.\e\(dq .Sh LIBRARY
 130 \&.\e\(dq For sections 2, 3, & 9 only.
 131 \&.Sh SYNOPSIS
 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, and 5.
 144 \&.\e\(dq .Sh FILES
 145 \&.\e\(dq .Sh EXIT STATUS
 146 \&.\e\(dq For sections 1, 1M, and 5.
 147 \&.\e\(dq .Sh EXAMPLES
 148 \&.\e\(dq .Sh DIAGNOSTICS

 149 \&.\e\(dq .Sh ERRORS
 150 \&.\e\(dq For sections 2, 3, & 9 only.
 151 \&.\e\(dq .Sh ARCHITECTURE
 152 \&.\e\(dq .Sh CODE SET INDEPENDENCE
 153 \&.\e\(dq For sections 1, 1M, & 3 only.
 154 \&.\e\(dq .Sh INTERFACE STABILITY
 155 \&.\e\(dq .Sh MT-LEVEL
 156 \&.\e\(dq For sections 2 & 3 only.
 157 \&.\e\(dq .Sh SECURITY
 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 .Ed
 166 .Pp
 167 The sections in an
 168 .Nm
 169 document are conventionally ordered as they appear above.
 170 Sections should be composed as follows:
 171 .Bl -ohang -offset Ds
 172 .It Em NAME
 173 The name(s) and a one line description of the documented material.
 174 The syntax for this as follows:
 175 .Bd -literal -offset indent
 176 \&.Nm name0 ,
 177 \&.Nm name1 ,
 178 \&.Nm name2
 179 \&.Nd a one line description
 180 .Ed
 181 .Pp
 182 Multiple
 183 .Sq \&Nm
 184 names should be separated by commas.


 190 macro.
 191 .Pp
 192 See
 193 .Sx \&Nm
 194 and
 195 .Sx \&Nd .
 196 .It Em LIBRARY
 197 The name of the library containing the documented material, which is
 198 assumed to be a function in a section 2, 3, or 9 manual.
 199 The syntax for this is as follows:
 200 .Bd -literal -offset indent
 201 \&.Lb libarm
 202 .Ed
 203 .Pp
 204 See
 205 .Sx \&Lb .
 206 .It Em SYNOPSIS
 207 Documents the utility invocation syntax, function call syntax, or device
 208 configuration.
 209 .Pp
 210 For the first, utilities (sections 1 and 1M), this is
 211 generally structured as follows:
 212 .Bd -literal -offset indent
 213 \&.Nm bar
 214 \&.Op Fl v
 215 \&.Op Fl o Ar file
 216 \&.Op Ar
 217 \&.Nm foo
 218 \&.Op Fl v
 219 \&.Op Fl o Ar file
 220 \&.Op Ar
 221 .Ed
 222 .Pp
 223 Commands should be ordered alphabetically.
 224 .Pp
 225 For the second, function calls (sections 2, 3, 7I, 7P, 9):
 226 .Bd -literal -offset indent
 227 \&.In header.h
 228 \&.Vt extern const char *global;
 229 \&.Ft "char *"
 230 \&.Fn foo "const char *src"
 231 \&.Ft "char *"
 232 \&.Fn bar "const char *src"
 233 .Ed
 234 .Pp
 235 Ordering of
 236 .Sx \&In ,
 237 .Sx \&Vt ,
 238 .Sx \&Fn ,
 239 and
 240 .Sx \&Fo
 241 macros should follow C header-file conventions.
 242 .Pp
 243 And for the third, configurations (section 7D):
 244 .Bd -literal -offset indent
 245 \&.Pa /dev/device_node

 246 .Ed
 247 .Pp
 248 Manuals not in these sections generally don't need a
 249 .Em SYNOPSIS .
 250 .Pp
 251 Some macros are displayed differently in the
 252 .Em SYNOPSIS
 253 section, particularly
 254 .Sx \&Nm ,
 255 .Sx \&Cd ,
 256 .Sx \&Fd ,
 257 .Sx \&Fn ,
 258 .Sx \&Fo ,
 259 .Sx \&In ,
 260 .Sx \&Vt ,
 261 and
 262 .Sx \&Ft .
 263 All of these macros are output on their own line.
 264 If two such dissimilar macros are pairwise invoked (except for
 265 .Sx \&Ft


 332 See
 333 .Sx \&Rv .
 334 .It Em ENVIRONMENT
 335 Lists the environment variables used by the utility,
 336 and explains the syntax and semantics of their values.
 337 The
 338 .Xr environ 5
 339 manual provides examples of typical content and formatting.
 340 .Pp
 341 See
 342 .Sx \&Ev .
 343 .It Em FILES
 344 Documents files used.
 345 It's helpful to document both the file name and a short description of how
 346 the file is used (created, modified, etc.).
 347 .Pp
 348 See
 349 .Sx \&Pa .
 350 .It Em EXIT STATUS
 351 This section documents the
 352 command exit status for sections 1 and 1M.
 353 Historically, this information was described in
 354 .Em DIAGNOSTICS ,
 355 a practise that is now discouraged.
 356 .Pp
 357 See
 358 .Sx \&Ex .
 359 .It Em EXAMPLES
 360 Example usages.
 361 This often contains snippets of well-formed, well-tested invocations.
 362 Make sure that examples work properly!
 363 .It Em DIAGNOSTICS
 364 Documents error and diagnostic messages displayed to the user or
 365 sent to logs. Note that exit
 366 status and return values should be documented in the
 367 .Em EXIT STATUS
 368 and
 369 .Em RETURN VALUES
 370 sections.
 371 .Pp
 372 See
 373 .Sx \&Bl
 374 .Fl diag .
 375 .It Em ERRORS
 376 Documents error handling in sections 2, 3, and 9.
 377 .Pp
 378 See
 379 .Sx \&Er .
 380 .It Em ARCHITECTURE
 381 This section is usually absent, but will be present when the
 382 interface is specific to one or more architectures.
 383 .It Em CODE SET INDEPENDENCE
 384 Indicates whether the interface operates correctly with various different
 385 code sets.  True independent code sets will support not only ASCII and
 386 Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
 387 UTF-8 and GB2312.
 388 .Pp
 389 Generally there will be some limitations that are fairly standard.  See
 390 .Xr standards 5 for more information about some of these.  Most interfaces


 472 .Nm Safe
 473 interface may make use of a global lock to provide safety, but at reduced
 474 internal concurrency, whereas an
 475 .Nm MT-Safe
 476 interface will be designed to be efficient even when used concurrently.
 477 .It Nm Async-Signal-Safe
 478 Indicates that the library is safe for use within a signal handler.  An
 479 .Nm MT-Safe
 480 interface can be made
 481 .Nm Async-Signal-Safe
 482 by ensuring that it blocks signals when acquiring locks.
 483 .It Nm Safe with Exections
 484 As for
 485 .Nm Safe
 486 but with specific exceptions noted.
 487 .It Nm MT-Safe with Exections
 488 As for
 489 .Nm MT-Safe
 490 but with specific exceptions noted.
 491 .El
 492 .It Em SECURITY
 493 Documents any security precautions that operators should consider.
 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
 514 See
 515 .Sx \&St .
 516 .It Em HISTORY
 517 A brief history of the subject, including where it was first implemented,
 518 and when it was ported to or reimplemented for the operating system at hand.
 519 .It Em AUTHORS
 520 Credits to the person or persons who wrote the code and/or documentation.
 521 Authors should generally be noted by both name and email address.
 522 .Pp
 523 See
 524 .Sx \&An .
 525 .It Em CAVEATS
 526 Common misuses and misunderstandings should be explained
 527 in this section.
 528 .It Em BUGS
 529 Known bugs, limitations, and work-arounds should be described
 530 in this section.


 531 .El
 532 .Sh MACRO OVERVIEW
 533 This overview is sorted such that macros of similar purpose are listed
 534 together, to help find the best macro for any given purpose.
 535 Deprecated macros are not included in the overview, but can be found below
 536 in the alphabetical
 537 .Sx MACRO REFERENCE .
 538 .Ss Document preamble and NAME section macros
 539 .Bl -column "Brq, Bro, Brc" description
 540 .It Sx \&Dd Ta document date: Ar month day , year
 541 .It Sx \&Dt Ta document title: Ar TITLE SECTION Op Ar volume | arch
 542 .It Sx \&Os Ta operating system version: Op Ar system Op Ar version
 543 .It Sx \&Nm Ta document name (one argument)
 544 .It Sx \&Nd Ta document description (one line)
 545 .El
 546 .Ss Sections and cross references
 547 .Bl -column "Brq, Bro, Brc" description
 548 .It Sx \&Sh Ta section header (one line)
 549 .It Sx \&Ss Ta subsection header (one line)
 550 .It Sx \&Sx Ta internal cross reference to a section or subsection


1226 .Dq is currently in beta test.
1227 .Ss \&Bx
1228 Format the BSD version provided as an argument, or a default value if no
1229 argument is provided.
1230 .Pp
1231 Examples:
1232 .Dl \&.Bx 4.3 Tahoe
1233 .Dl \&.Bx 4.4
1234 .Dl \&.Bx
1235 .Pp
1236 See also
1237 .Sx \&At ,
1238 .Sx \&Bsx ,
1239 .Sx \&Dx ,
1240 .Sx \&Fx ,
1241 .Sx \&Nx ,
1242 .Sx \&Ox ,
1243 and
1244 .Sx \&Ux .
1245 .Ss \&Cd
1246 Kernel configuration declaration.  It is found in pages for
1247 .Bx
1248 and not used here.

1249 .Pp
1250 Examples:
1251 .Dl \&.Cd device le0 at scode?
1252 .Pp
1253 .Em Remarks :
1254 this macro is commonly abused by using quoted literals to retain
1255 whitespace and align consecutive
1256 .Sx \&Cd
1257 declarations.
1258 This practise is discouraged.
1259 .Ss \&Cm
1260 Command modifiers.
1261 Typically used for fixed strings passed as arguments, unless
1262 .Sx \&Fl
1263 is more appropriate.
1264 Also useful when specifying configuration options or keys.
1265 .Pp
1266 Examples:
1267 .Dl ".Nm mt Fl f Ar device Cm rewind"
1268 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"


1529 .Pp
1530 See also
1531 .Sx \&Dv
1532 for general constants.
1533 .Ss \&Es
1534 This macro is obsolete and not implemented.
1535 .Ss \&Ev
1536 Environmental variables such as those specified in
1537 .Xr environ 5 .
1538 .Pp
1539 Examples:
1540 .Dl \&.Ev DISPLAY
1541 .Dl \&.Ev PATH
1542 .Pp
1543 See also
1544 .Sx \&Dv
1545 for general constants.
1546 .Ss \&Ex
1547 Insert a standard sentence regarding command exit values of 0 on success
1548 and >0 on failure.
1549 This is most often used in section 1 and 1M manual pages.
1550 Its syntax is as follows:
1551 .Pp
1552 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1553 .Pp
1554 If
1555 .Ar utility
1556 is not specified, the document's name set by
1557 .Sx \&Nm
1558 is used.
1559 Multiple
1560 .Ar utility
1561 arguments are treated as separate utilities.
1562 .Pp
1563 See also
1564 .Sx \&Rv .
1565 .Ss \&Fa
1566 Function argument.
1567 Its syntax is as follows:
1568 .Bd -ragged -offset indent
1569 .Pf \. Sx \&Fa


1945 .Sx \&Nm
1946 macro.
1947 .Pp
1948 Examples:
1949 .Dl Pf . Sx \&Nd mdoc language reference
1950 .Dl Pf . Sx \&Nd format and display UNIX manuals
1951 .Pp
1952 The
1953 .Sx \&Nd
1954 macro technically accepts child macros and terminates with a subsequent
1955 .Sx \&Sh
1956 invocation.
1957 Do not assume this behaviour: some
1958 .Xr whatis 1
1959 database generators are not smart enough to parse more than the line
1960 arguments and will display macros verbatim.
1961 .Pp
1962 See also
1963 .Sx \&Nm .
1964 .Ss \&Nm
1965 The name of the manual page, or \(em in particular in section 1
1966 and 1M pages \(em of an additional command or feature documented in
1967 the manual page.
1968 When first invoked, the
1969 .Sx \&Nm
1970 macro expects a single argument, the name of the manual page.
1971 Usually, the first invocation happens in the
1972 .Em NAME
1973 section of the page.
1974 The specified name will be remembered and used whenever the macro is
1975 called again without arguments later in the page.
1976 The
1977 .Sx \&Nm
1978 macro uses
1979 .Sx Block full-implicit
1980 semantics when invoked as the first macro on an input line in the
1981 .Em SYNOPSIS
1982 section; otherwise, it uses ordinary
1983 .Sx In-line
1984 semantics.
1985 .Pp
1986 Examples:


2063 .Sx \&Ux .
2064 .Ss \&Oc
2065 Close multi-line
2066 .Sx \&Oo
2067 context.
2068 .Ss \&Oo
2069 Multi-line version of
2070 .Sx \&Op .
2071 .Pp
2072 Examples:
2073 .Bd -literal -offset indent -compact
2074 \&.Oo
2075 \&.Op Fl flag Ns Ar value
2076 \&.Oc
2077 .Ed
2078 .Ss \&Op
2079 Optional part of a command line.
2080 Prints the argument(s) in brackets.
2081 This is most often used in the
2082 .Em SYNOPSIS
2083 section of section 1 and 1M manual pages.
2084 .Pp
2085 Examples:
2086 .Dl \&.Op \&Fl a \&Ar b
2087 .Dl \&.Op \&Ar a | b
2088 .Pp
2089 See also
2090 .Sx \&Oo .
2091 .Ss \&Os
2092 Document operating system version.
2093 This is the mandatory third macro of
2094 any
2095 .Nm
2096 file.
2097 Its syntax is as follows:
2098 .Pp
2099 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2100 .Pp
2101 The optional
2102 .Ar system
2103 parameter specifies the relevant operating system or environment.


3182 .El
3183 .Sh SEE ALSO
3184 .Xr man 1 ,
3185 .Xr mandoc 1 ,
3186 .Xr eqn 5 ,
3187 .Xr man 5 ,
3188 .Xr mandoc_char 5 ,
3189 .Xr roff 5 ,
3190 .Xr tbl 5
3191 .Sh HISTORY
3192 The
3193 .Nm
3194 language first appeared as a troff macro package in
3195 .Bx 4.4 .
3196 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3197 in groff-1.17.
3198 The standalone implementation that is part of the
3199 .Xr mandoc 1
3200 utility written by Kristaps Dzonsons appeared in
3201 .Ox 4.6 .

3202 .Sh AUTHORS
3203 The
3204 .Nm
3205 reference was written by
3206 .An Kristaps Dzonsons ,
3207 .Mt kristaps@bsd.lv .