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