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