cb2a244a32329528c810bb26f326546df497a88f
[dragonfly.git] / usr.bin / mandoc / mdoc.7
1 .\"     $Id: mdoc.7,v 1.18 2009/10/27 21:40:07 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd October 29, 2009
18 .Dt MDOC 7
19 .Os
20 .
21 .
22 .Sh NAME
23 .Nm mdoc
24 .Nd mdoc language reference
25 .
26 .
27 .Sh DESCRIPTION
28 The
29 .Nm mdoc
30 language is used to format
31 .Bx
32 .Ux
33 manuals.  In this reference document, we describe its syntax, structure,
34 and usage.  Our reference implementation is
35 .Xr mandoc 1 .
36 The
37 .Sx COMPATIBILITY
38 section describes compatibility with
39 .Xr groff 1 .
40 .
41 .Pp
42 An
43 .Nm
44 document follows simple rules:  lines beginning with the control
45 character
46 .Sq \.
47 are parsed for macros.  Other lines are interpreted within the scope of
48 prior macros:
49 .Bd -literal -offset indent
50 \&.Sh Macro lines change control state.
51 Other lines are interpreted within the current state.
52 .Ed
53 .
54 .
55 .Sh LANGUAGE SYNTAX
56 .Nm
57 documents may contain only graphable 7-bit ASCII characters, the space
58 character, and, in certain circumstances, the tab character.  All
59 manuals must have
60 .Ux
61 line terminators.
62 .
63 .
64 .Ss Comments
65 Text following a
66 .Sq \e" ,
67 whether in a macro or free-form text line, is ignored to the end of
68 line.  A macro line with only a control character and comment escape,
69 .Sq \&.\e" ,
70 is also ignored.  Macro lines with only a control charater and optionally
71 whitespace are stripped from input.
72 .
73 .
74 .Ss Reserved Characters
75 Within a macro line, the following characters are reserved:
76 .Pp
77 .Bl -tag -width Ds -offset indent -compact
78 .It \&.
79 .Pq period
80 .It \&,
81 .Pq comma
82 .It \&:
83 .Pq colon
84 .It \&;
85 .Pq semicolon
86 .It \&(
87 .Pq left-parenthesis
88 .It \&)
89 .Pq right-parenthesis
90 .It \&[
91 .Pq left-bracket
92 .It \&]
93 .Pq right-bracket
94 .It \&?
95 .Pq question
96 .It \&!
97 .Pq exclamation
98 .It \&|
99 .Pq vertical bar
100 .El
101 .
102 .Pp
103 Use of reserved characters is described in
104 .Sx MACRO SYNTAX .
105 For general use in macro lines, these characters must either be escaped
106 with a non-breaking space
107 .Pq Sq \e&
108 or, if applicable, an appropriate escape sequence used.
109 .
110 .
111 .Ss Special Characters
112 Special characters may occur in both macro and free-form lines.
113 Sequences begin with the escape character
114 .Sq \e
115 followed by either an open-parenthesis
116 .Sq \&(
117 for two-character sequences; an open-bracket
118 .Sq \&[
119 for n-character sequences (terminated at a close-bracket
120 .Sq \&] ) ;
121 or a single one-character sequence.  See
122 .Xr mandoc_char 7
123 for a complete list.  Examples include
124 .Sq \e(em
125 .Pq em-dash
126 and
127 .Sq \ee
128 .Pq back-slash .
129 .
130 .
131 .Ss Text Decoration
132 Terms may be text-decorated using the
133 .Sq \ef
134 escape followed by an indicator: B (bold), I, (italic), or P and R
135 (Roman, or reset).  This form is not recommended for
136 .Nm ,
137 which encourages semantic, not presentation, annotation.
138 .
139 .
140 .Ss Predefined Strings
141 Historically,
142 .Xr groff 1
143 also defined a set of package-specific
144 .Dq predefined strings ,
145 which, like
146 .Sx Special Characters ,
147 demark special output characters and strings by way of input codes.
148 Predefined strings are escaped with the slash-asterisk,
149 .Sq \e* :
150 single-character
151 .Sq \e*X ,
152 two-character
153 .Sq \e*(XX ,
154 and N-character
155 .Sq \e*[N] .
156 See
157 .Xr mandoc_char 7
158 for a complete list.  Examples include
159 .Sq \e*(Am
160 .Pq ampersand
161 and
162 .Sq \e*(Ba
163 .Pq vertical bar .
164 .
165 .
166 .Ss Whitespace
167 In non-literal free-form lines, consecutive blocks of whitespace are
168 pruned from input and added later in the output filter, if applicable:
169 .Bd -literal -offset indent
170 These     spaces   are    pruned       from    input.
171 \&.Bd \-literal
172 These         are              not.
173 \&.Ed
174 .Ed
175 .
176 .Pp
177 In macro lines, whitespace delimits arguments and is discarded.  If
178 arguments are quoted, whitespace within the quotes is retained.
179 .
180 .Pp
181 Blank lines are only permitted within literal contexts, as are lines
182 containing only whitespace.  Tab characters are only acceptable when
183 delimiting
184 .Sq \&Bl \-column
185 or when in a literal context.
186 .
187 .
188 .Ss Quotation
189 Macro arguments may be quoted with a double-quote to group
190 space-delimited terms or to retain blocks of whitespace.  A quoted
191 argument begins with a double-quote preceded by whitespace.  The next
192 double-quote not pair-wise adjacent to another double-quote terminates
193 the literal, regardless of surrounding whitespace.
194 .
195 .Pp
196 This produces tokens
197 .Sq a" ,
198 .Sq b c ,
199 .Sq de ,
200 and
201 .Sq fg" .
202 Note that any quoted term, be it argument or macro, is indiscriminately
203 considered literal text.  Thus, the following produces
204 .Sq \&Em a :
205 .Bd -literal -offset indent
206 \&.Em "Em a"
207 .Ed
208 .
209 .Pp
210 In free-form mode, quotes are regarded as opaque text.
211 .
212 .Ss Dates
213 There are several macros in
214 .Nm
215 that require a date argument.  The
216 .Em canonical form
217 for dates is the American format:
218 .Pp
219 .D1 Cm Month Day , Year
220 .Pp
221 The
222 .Cm Day
223 value is an optionally zero-padded numeral.  The
224 .Cm Month
225 value is the full month name.  The
226 .Cm Year
227 value is the full four-digit year.
228 .Pp
229 The
230 .Em non-canonical form
231 is the same as the canonical form, but without the comma between the
232 .Cm Day
233 and
234 .Cm Year
235 field.
236 .Pp
237 Lastly,
238 .Em reduced form
239 dates range from only a
240 .Cm Year
241 to the full canonical or non-canonical form.
242 .Pp
243 Some examples of valid dates follow:
244 .Pp
245 .D1 "May, 2009" Pq reduced form
246 .D1 "2009" Pq reduced form
247 .D1 "May 20, 2009" Pq canonical form
248 .D1 "May 20 2009" Pq non-canonical form
249 .
250 .Ss Scaling Widths
251 Many macros support scaled widths for their arguments, such as
252 stipulating a two-inch list indentation with the following:
253 .Bd -literal -offset indent
254 \&.Bl -tag -width 2i
255 .Ed
256 .
257 .Pp
258 The syntax for scaled widths is
259 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
260 where a decimal must be preceded or proceeded by at least one digit.
261 Negative numbers, while accepted, are truncated to zero.  The following
262 scaling units are accepted:
263 .Pp
264 .Bl -tag -width Ds -offset indent -compact
265 .It c
266 centimetre
267 .It i
268 inch
269 .It P
270 pica (~1/6 inch)
271 .It p
272 point (~1/72 inch)
273 .It f
274 synonym for
275 .Sq u
276 .It v
277 default vertical span
278 .It m
279 width of rendered
280 .Sq m
281 .Pq em
282 character
283 .It n
284 width of rendered
285 .Sq n
286 .Pq en
287 character
288 .It u
289 default horizontal span
290 .It M
291 mini-em (~1/100 em)
292 .El
293 .Pp
294 Using anything other than
295 .Sq m ,
296 .Sq n ,
297 .Sq u ,
298 or
299 .Sq v
300 is necessarily non-portable across output media.  See
301 .Sx COMPATIBILITY .
302 .
303 .
304 .Sh MANUAL STRUCTURE
305 A well-formed
306 .Nm
307 document consists of a document prologue followed by one or more
308 sections.
309 .Pp
310 The prologue, which consists of (in order) the
311 .Sx \&Dd ,
312 .Sx \&Dt ,
313 and
314 .Sx \&Os
315 macros, is required for every document.
316 .Pp
317 The first section (sections are denoted by
318 .Sx \&Sh )
319 must be the NAME section, consisting of at least one
320 .Sx \&Nm
321 followed by
322 .Sx \&Nd .
323 .Pp
324 Following that, convention dictates specifying at least the SYNOPSIS and
325 DESCRIPTION sections, although this varies between manual sections.
326 .Pp
327 The following is a well-formed skeleton
328 .Nm
329 file:
330 .Bd -literal -offset indent
331 \&.Dd $\&Mdocdate$
332 \&.Dt mdoc 7
333 \&.Os
334 \&.
335 \&.Sh NAME
336 \&.Nm foo
337 \&.Nd a description goes here
338 \&.\e\*q The next is for sections 2 & 3 only.
339 \&.\e\*q .Sh LIBRARY
340 \&.
341 \&.Sh SYNOPSIS
342 \&.Nm foo
343 \&.Op Fl options
344 \&.Ar
345 \&.
346 \&.Sh DESCRIPTION
347 The
348 \&.Nm
349 utility processes files ...
350 \&.\e\*q .Sh IMPLEMENTATION NOTES
351 \&.\e\*q The next is for sections 1 & 8 only.
352 \&.\e\*q .Sh EXIT STATUS
353 \&.\e\*q The next is for sections 2, 3, & 9 only.
354 \&.\e\*q .Sh RETURN VALUES
355 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
356 \&.\e\*q .Sh ENVIRONMENT
357 \&.\e\*q .Sh FILES
358 \&.\e\*q .Sh EXAMPLES
359 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
360 \&.\e\*q .Sh DIAGNOSTICS
361 \&.\e\*q The next is for sections 2, 3, & 9 only.
362 \&.\e\*q .Sh ERRORS
363 \&.\e\*q .Sh SEE ALSO
364 \&.\e\*q .Xr foobar 1
365 \&.\e\*q .Sh STANDARDS
366 \&.\e\*q .Sh HISTORY
367 \&.\e\*q .Sh AUTHORS
368 \&.\e\*q .Sh CAVEATS
369 \&.\e\*q .Sh BUGS
370 \&.\e\*q .Sh SECURITY CONSIDERATIONS
371 .Ed
372 .Pp
373 The sections in a
374 .Nm
375 document are conventionally ordered as they appear above.  Sections
376 should be composed as follows:
377 .Bl -tag -width Ds -offset Ds
378 .It NAME
379 Must contain at least one
380 .Sx \&Nm
381 followed by
382 .Sx \&Nd .
383 The name needs re-stating since one
384 .Nm
385 documents can be used for more than one utility or function, such as
386 .Xr grep 1
387 also being referenced as
388 .Xr egrep 1
389 and
390 .Xr fgrep 1 .
391 .It LIBRARY
392 .It SYNOPSIS
393 .It DESCRIPTION
394 .It IMPLEMENTATION NOTES
395 .It EXIT STATUS
396 .It RETURN VALUES
397 .It ENVIRONMENT
398 .It FILES
399 .It EXAMPLES
400 .It DIAGNOSTICS
401 .It ERRORS
402 .It SEE ALSO
403 .It STANDARDS
404 .It HISTORY
405 .It AUTHORS
406 .It CAVEATS
407 .It BUGS
408 .It SECURITY CONSIDERATIONS
409 .El
410 .
411 .
412 .Sh MACRO SYNTAX
413 Macros are one to three three characters in length and begin with a
414 control character ,
415 .Sq \&. ,
416 at the beginning of the line.  An arbitrary amount of whitespace may
417 sit between the control character and the macro name.  Thus, the
418 following are equivalent:
419 .Bd -literal -offset indent
420 \&.Pp
421 \&.\ \ \ \&Pp
422 .Ed
423 .
424 .Pp
425 The syntax of a macro depends on its classification.  In this section,
426 .Sq \-arg
427 refers to macro arguments, which may be followed by zero or more
428 .Sq parm
429 parameters;
430 .Sq \&Yo
431 opens the scope of a macro; and if specified,
432 .Sq \&Yc
433 closes it out.
434 .
435 .Pp
436 The
437 .Em Callable
438 column indicates that the macro may be called subsequent to the initial
439 line-macro.  If a macro is not callable, then its invocation after the
440 initial line macro is interpreted as opaque text, such that
441 .Sq \&.Fl \&Sh
442 produces
443 .Sq Fl \&Sh .
444 .
445 .Pp
446 The
447 .Em Parsable
448 column indicates whether the macro may be followed by further
449 (ostensibly callable) macros.  If a macro is not parsable, subsequent
450 macro invocations on the line will be interpreted as opaque text.
451 .
452 .Pp
453 The
454 .Em Scope
455 column, if applicable, describes closure rules.
456 .
457 .
458 .Ss Block full-explicit
459 Multi-line scope closed by an explicit closing macro.  All macros
460 contains bodies; only
461 .Sx \&Bf
462 contains a head.
463 .Bd -literal -offset indent
464 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
465 \(lBbody...\(rB
466 \&.Yc
467 .Ed
468 .
469 .Pp
470 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
471 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
472 .It Sx \&Bd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ed
473 .It Sx \&Bf  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ef
474 .It Sx \&Bk  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ek
475 .It Sx \&Bl  Ta    \&No     Ta    \&No     Ta    closed by Sx \&El
476 .It Sx \&Ed  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bd
477 .It Sx \&Ef  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bf
478 .It Sx \&Ek  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bk
479 .It Sx \&El  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bl
480 .El
481 .
482 .
483 .Ss Block full-implicit
484 Multi-line scope closed by end-of-file or implicitly by another macro.
485 All macros have bodies; some
486 .Po
487 .Sx \&It Fl bullet ,
488 .Fl hyphen ,
489 .Fl dash ,
490 .Fl enum ,
491 .Fl item
492 .Pc
493 don't have heads; only one
494 .Po
495 .Sx \&It Fl column
496 .Pc
497 has multiple heads.
498 .Bd -literal -offset indent
499 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
500 \(lBbody...\(rB
501 .Ed
502 .
503 .Pp
504 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
505 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
506 .It Sx \&It  Ta    \&No     Ta    Yes      Ta    closed by Sx \&It , Sx \&El
507 .It Sx \&Nd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
508 .It Sx \&Sh  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
509 .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
510 .El
511 .
512 .
513 .Ss Block partial-explicit
514 Like block full-explicit, but also with single-line scope.  Each
515 has at least a body and, in limited circumstances, a head
516 .Po
517 .Sx \&Fo ,
518 .Sx \&Eo
519 .Pc
520 and/or tail
521 .Pq Sx \&Ec .
522 .Bd -literal -offset indent
523 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
524 \(lBbody...\(rB
525 \&.Yc \(lBtail...\(rB
526
527 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
528 \(lBbody...\(rB \&Yc \(lBtail...\(rB
529 .Ed
530 .
531 .Pp
532 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
533 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
534 .It Sx \&Ac  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Ao
535 .It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ac
536 .It Sx \&Bc  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Bo
537 .It Sx \&Bo  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Bc
538 .It Sx \&Brc Ta    Yes      Ta    Yes      Ta    opened by Sx \&Bro
539 .It Sx \&Bro Ta    Yes      Ta    Yes      Ta    closed by Sx \&Brc
540 .It Sx \&Dc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Do
541 .It Sx \&Do  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Dc
542 .It Sx \&Ec  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Eo
543 .It Sx \&Eo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ec
544 .It Sx \&Fc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Fo
545 .It Sx \&Fo  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Fc
546 .It Sx \&Oc  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Oo
547 .It Sx \&Oo  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Oc
548 .It Sx \&Pc  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Po
549 .It Sx \&Po  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Pc
550 .It Sx \&Qc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Oo
551 .It Sx \&Qo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Oc
552 .It Sx \&Re  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Rs
553 .It Sx \&Rs  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Re
554 .It Sx \&Sc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&So
555 .It Sx \&So  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Sc
556 .It Sx \&Xc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Xo
557 .It Sx \&Xo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Xc
558 .El
559 .
560 .
561 .Ss Block partial-implicit
562 Like block full-implicit, but with single-line scope closed by
563 .Sx Reserved Characters
564 or end of line.
565 .Bd -literal -offset indent
566 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
567 .Ed
568 .
569 .Pp
570 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
571 .It Em Macro Ta Em Callable Ta Em Parsable
572 .It Sx \&Aq  Ta    Yes      Ta    Yes
573 .It Sx \&Bq  Ta    Yes      Ta    Yes
574 .It Sx \&Brq Ta    Yes      Ta    Yes
575 .It Sx \&D1  Ta    \&No     Ta    \&Yes
576 .It Sx \&Dl  Ta    \&No     Ta    Yes
577 .It Sx \&Dq  Ta    Yes      Ta    Yes
578 .It Sx \&Op  Ta    Yes      Ta    Yes
579 .It Sx \&Pq  Ta    Yes      Ta    Yes
580 .It Sx \&Ql  Ta    Yes      Ta    Yes
581 .It Sx \&Qq  Ta    Yes      Ta    Yes
582 .It Sx \&Sq  Ta    Yes      Ta    Yes
583 .El
584 .
585 .
586 .Ss In-line
587 Closed by
588 .Sx Reserved Characters ,
589 end of line, fixed argument lengths, and/or subsequent macros.  In-line
590 macros have only text children.  If a number (or inequality) of
591 arguments is
592 .Pq n ,
593 then the macro accepts an arbitrary number of arguments.
594 .Bd -literal -offset indent
595 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
596
597 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
598
599 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
600 .Ed
601 .
602 .Pp
603 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
604 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
605 .It Sx \&%A  Ta    \&No     Ta    \&No     Ta    >0
606 .It Sx \&%B  Ta    \&No     Ta    \&No     Ta    >0
607 .It Sx \&%C  Ta    \&No     Ta    \&No     Ta    >0
608 .It Sx \&%D  Ta    \&No     Ta    \&No     Ta    >0
609 .It Sx \&%I  Ta    \&No     Ta    \&No     Ta    >0
610 .It Sx \&%J  Ta    \&No     Ta    \&No     Ta    >0
611 .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0
612 .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0
613 .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0
614 .It Sx \&%Q  Ta    \&No     Ta    \&No     Ta    >0
615 .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0
616 .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0
617 .It Sx \&%U  Ta    \&No     Ta    \&No     Ta    >0
618 .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0
619 .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n
620 .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n
621 .It Sx \&Ap  Ta    Yes      Ta    Yes      Ta    0
622 .It Sx \&Ar  Ta    Yes      Ta    Yes      Ta    n
623 .It Sx \&At  Ta    Yes      Ta    Yes      Ta    1
624 .It Sx \&Bsx Ta    Yes      Ta    Yes      Ta    n
625 .It Sx \&Bt  Ta    \&No     Ta    \&No     Ta    0
626 .It Sx \&Bx  Ta    Yes      Ta    Yes      Ta    n
627 .It Sx \&Cd  Ta    Yes      Ta    Yes      Ta    >0
628 .It Sx \&Cm  Ta    Yes      Ta    Yes      Ta    n
629 .It Sx \&Db  Ta    \&No     Ta    \&No     Ta    1
630 .It Sx \&Dd  Ta    \&No     Ta    \&No     Ta    >0
631 .It Sx \&Dt  Ta    \&No     Ta    \&No     Ta    n
632 .It Sx \&Dv  Ta    Yes      Ta    Yes      Ta    n
633 .It Sx \&Dx  Ta    Yes      Ta    Yes      Ta    n
634 .It Sx \&Em  Ta    Yes      Ta    Yes      Ta    >0
635 .It Sx \&En  Ta    \&No     Ta    \&No     Ta    0
636 .It Sx \&Er  Ta    Yes      Ta    Yes      Ta    >0
637 .It Sx \&Es  Ta    \&No     Ta    \&No     Ta    0
638 .It Sx \&Ev  Ta    Yes      Ta    Yes      Ta    n
639 .It Sx \&Ex  Ta    \&No     Ta    \&No     Ta    n
640 .It Sx \&Fa  Ta    Yes      Ta    Yes      Ta    n
641 .It Sx \&Fd  Ta    \&No     Ta    \&No     Ta    >0
642 .It Sx \&Fl  Ta    Yes      Ta    Yes      Ta    n
643 .It Sx \&Fn  Ta    Yes      Ta    Yes      Ta    >0
644 .It Sx \&Fr  Ta    \&No     Ta    \&No     Ta    n
645 .It Sx \&Ft  Ta    Yes      Ta    Yes      Ta    n
646 .It Sx \&Fx  Ta    Yes      Ta    Yes      Ta    n
647 .It Sx \&Hf  Ta    \&No     Ta    \&No     Ta    n
648 .It Sx \&Ic  Ta    Yes      Ta    Yes      Ta    >0
649 .It Sx \&In  Ta    \&No     Ta    \&No     Ta    n
650 .It Sx \&Lb  Ta    \&No     Ta    \&No     Ta    1
651 .It Sx \&Li  Ta    Yes      Ta    Yes      Ta    n
652 .It Sx \&Lk  Ta    Yes      Ta    Yes      Ta    n
653 .It Sx \&Lp  Ta    \&No     Ta    \&No     Ta    0
654 .It Sx \&Ms  Ta    Yes      Ta    Yes      Ta    >0
655 .It Sx \&Mt  Ta    Yes      Ta    Yes      Ta    >0
656 .It Sx \&Nm  Ta    Yes      Ta    Yes      Ta    n
657 .It Sx \&No  Ta    Yes      Ta    Yes      Ta    0
658 .It Sx \&Ns  Ta    Yes      Ta    Yes      Ta    0
659 .It Sx \&Nx  Ta    Yes      Ta    Yes      Ta    n
660 .It Sx \&Os  Ta    \&No     Ta    \&No     Ta    n
661 .It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n
662 .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n
663 .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n
664 .It Sx \&Pf  Ta    \&No     Ta    Yes      Ta    1
665 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
666 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n
667 .It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1
668 .It Sx \&St  Ta    \&No     Ta    Yes      Ta    1
669 .It Sx \&Sx  Ta    Yes      Ta    Yes      Ta    >0
670 .It Sx \&Sy  Ta    Yes      Ta    Yes      Ta    >0
671 .It Sx \&Tn  Ta    Yes      Ta    Yes      Ta    >0
672 .It Sx \&Ud  Ta    \&No     Ta    \&No     Ta    0
673 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
674 .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n
675 .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0
676 .It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0, <3
677 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
678 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
679 .El
680 .
681 .
682 .Sh REFERENCE
683 This section is a canonical reference of all macros, arranged
684 alphabetically.  For the scoping of individual macros, see
685 .Sx MACRO SYNTAX .
686 .
687 .Ss \&%A
688 Author name of an
689 .Sx \&Rs
690 block.  Multiple authors should each be accorded their own
691 .Sx \%%A
692 line.  Author names should be ordered with full or abbreviated
693 forename(s) first, then full surname.
694 .
695 .Ss \&%B
696 Book title of an
697 .Sx \&Rs
698 block.  This macro may also be used in a non-bibliographic context when
699 referring to book titles.
700 .
701 .Ss \&%C
702 Publication city or location of an
703 .Sx \&Rs
704 block.
705 .Pp
706 .Em Remarks :
707 this macro is not implemented in
708 .Xr groff 1 .
709 .
710 .Ss \&%D
711 Publication date of an
712 .Sx \&Rs
713 block.  This should follow the reduced syntax for
714 .Sx Dates .
715 Canonical or non-canonical form is not necessary since publications are
716 often referenced only by year, or month and year.
717 .
718 .Ss \&%I
719 Publisher or issuer name of an
720 .Sx \&Rs
721 block.
722 .
723 .Ss \&%J
724 Journal name of an
725 .Sx \&Rs
726 block.
727 .
728 .Ss \&%N
729 Issue number (usually for journals) of an
730 .Sx \&Rs
731 block.
732 .
733 .Ss \&%O
734 Optional information of an
735 .Sx \&Rs
736 block.
737 .
738 .Ss \&%P
739 Book or journal page number of an
740 .Sx \&Rs
741 block.
742 .
743 .Ss \&%Q
744 Institutional author (school, government, etc.) of an
745 .Sx \&Rs
746 block.  Multiple institutional authors should each be accorded their own
747 .Sx \&%Q
748 line.
749 .
750 .Ss \&%R
751 Technical report name of an
752 .Sx \&Rs
753 block.
754 .
755 .Ss \&%T
756 Article title of an
757 .Sx \&Rs
758 block.  This macro may also be used in a non-bibliographical context
759 when referring to article titles.
760 .
761 .Ss \&%U
762 URI of reference document.
763 .
764 .Ss \&%V
765 Volume number of an
766 .Sx \&Rs
767 block.
768 .
769 .Ss \&Ac
770 Closes an
771 .Sx \&Ao
772 block.  Does not have any tail arguments.
773 .
774 .Ss \&Ad
775 Address construct: usually in the context of an computational address in
776 memory, not a physical (post) address.
777 .Pp
778 Examples:
779 .Bd -literal -offset indent
780 \&.Ad [0,$]
781 \&.Ad 0x00000000
782 .Ed
783 .
784 .Ss \&An
785 Author name.  This macro may alternatively accepts the following
786 arguments, although these may not be specified along with a parameter:
787 .Bl -tag -width 12n -offset indent
788 .It Fl split
789 Renders a line break before each author listing.
790 .It Fl nosplit
791 The opposite of
792 .Fl split .
793 .El
794 .Pp
795 In the AUTHORS section, the default is not to split the first author
796 listing, but all subsequent author listings, whether or not they're
797 interspersed by other macros or text, are split.  Thus, specifying
798 .Fl split
799 will cause the first listing also to be split.  If not in the AUTHORS
800 section, the default is not to split.
801 .Pp
802 Examples:
803 .Bd -literal -offset indent
804 \&.An -nosplit
805 \&.An J. E. Hopcraft ,
806 \&.An J. D. Ullman .
807 .Ed
808 .Pp
809 .Em Remarks :
810 the effects of
811 .Fl split
812 or
813 .Fl nosplit
814 are re-set when entering the AUTHORS section, so if one specifies
815 .Sx \&An Fl nosplit
816 in the general document body, it must be re-specified in the AUTHORS
817 section.
818 .
819 .Ss \&Ao
820 Begins a block enclosed by angled brackets.  Does not have any head
821 arguments.
822 .Pp
823 Examples:
824 .Bd -literal -offset indent
825 \&.Fl -key= Ns Ao Ar val Ac
826 .Ed
827 .Pp
828 See also
829 .Sx \&Aq .
830 .
831 .Ss \&Ap
832 Inserts an apostrophe without any surrounding white-space.  This is
833 generally used as a grammatic device when referring to the verb form of
834 a function:
835 .Bd -literal -offset indent
836 \&.Fn execve Ap d
837 .Ed
838 .
839 .Ss \&Aq
840 Encloses its arguments in angled brackets.
841 .Pp
842 Examples:
843 .Bd -literal -offset indent
844 \&.Fl -key= Ns Aq Ar val
845 .Ed
846 .Pp
847 .Em Remarks :
848 this macro is often abused for rendering URIs, which should instead use
849 .Sx \&Lk
850 or
851 .Sx \&Mt ,
852 or to note pre-processor
853 .Dq Li #include
854 statements, which should use
855 .Sx \&In .
856 .Pp
857 See also
858 .Sx \&Ao .
859 .
860 .Ss \&Ar
861 Command arguments.  If an argument is not provided, the string
862 .Dq file ...
863 is used as a default.
864 .Pp
865 Examples:
866 .Bd -literal -offset indent
867 \&.Fl o Ns Ar file1
868 \&.Ar
869 \&.Ar arg1 , arg2 .
870 .Ed
871 .
872 .Ss \&At
873 Formats an AT&T version.  Accepts at most one parameter:
874 .Bl -tag -width 12n -offset indent
875 .It Cm v[1-7] | 32v
876 A version of
877 .At .
878 .It Cm V[.[1-4]]?
879 A system version of
880 .At .
881 .El
882 .Pp
883 Note that these parameters do not begin with a hyphen.
884 .Pp
885 Examples:
886 .Bd -literal -offset indent
887 \&.At
888 \&.At V.1
889 .Ed
890 .Pp
891 See also
892 .Sx \&Bsx ,
893 .Sx \&Bx ,
894 .Sx \&Dx ,
895 .Sx \&Fx ,
896 .Sx \&Nx ,
897 .Sx \&Ox ,
898 and
899 .Sx \&Ux .
900 .
901 .Ss \&Bc
902 Closes a
903 .Sx \&Bo
904 block.  Does not have any tail arguments.
905 .
906 .Ss \&Bd
907 Begins a display block.  A display is collection of macros or text which
908 may be collectively offset or justified in a manner different from that
909 of the enclosing context.  By default, the block is preceded by a
910 vertical space.
911 .Pp
912 Each display is associated with a type, which must be one of the
913 following arguments:
914 .Bl -tag -width 12n -offset indent
915 .It Fl ragged
916 Only left-justify the block.
917 .It Fl unfilled
918 Do not justify the block at all.
919 .It Fl filled
920 Left- and right-justify the block.
921 .It Fl literal
922 Alias for
923 .Fl unfilled .
924 .It Fl centered
925 Centre-justify each line.
926 .El
927 .Pp
928 The type must be provided first.  Secondary arguments are as follows:
929 .Bl -tag -width 12n -offset indent
930 .It Fl offset Ar width
931 Offset by the value of
932 .Ar width ,
933 which is interpreted as one of the following, specified in order:
934 .Bl -item
935 .It
936 As one of the pre-defined strings
937 .Ar indent ,
938 the width of standard indentation;
939 .Ar indent-two ,
940 twice
941 .Ar indent ;
942 .Ar left ,
943 which has no effect ;
944 .Ar right ,
945 which justifies to the right margin; and
946 .Ar center ,
947 which aligns around an imagined centre axis.
948 .It
949 As a precalculated width for a named macro.  The most popular is the
950 imaginary macro
951 .Ar \&Ds ,
952 which resolves to
953 .Ar 6n .
954 .It
955 As a scaling unit following the syntax described in
956 .Sx Scaling Widths .
957 .It
958 As the calculated string length of the opaque string.
959 .El
960 .Pp
961 If unset, it will revert to the value of
962 .Ar 8n
963 as described in
964 .Sx Scaling Widths .
965 .It Fl compact
966 Do not assert a vertical space before the block.
967 .It Fl file Ar file
968 Prepend the file
969 .Ar file
970 before any text or macros within the block.
971 .El
972 .Pp
973 Examples:
974 .Bd -literal -offset indent
975 \&.Bd \-unfilled \-offset two-indent \-compact
976    Hello       world.
977 \&.Ed
978 .Ed
979 .Pp
980 See also
981 .Sx \&D1
982 and
983 .Sx \&Dl .
984 .
985 .Ss \&Bf
986 .Ss \&Bk
987 .Ss \&Bl
988 .
989 .Ss \&Bo
990 Begins a block enclosed by square brackets.  Does not have any head
991 arguments.
992 .Pp
993 Examples:
994 .Bd -literal -offset indent
995 \&.Bo 1 ,
996 \&.Dv BUFSIZ Bc
997 .Ed
998 .Pp
999 See also
1000 .Sx \&Bq .
1001 .
1002 .Ss \&Bq
1003 Encloses its arguments in square brackets.
1004 .Pp
1005 Examples:
1006 .Bd -literal -offset indent
1007 \&.Bq 1 , Dv BUFSIZ
1008 .Ed
1009 .Pp
1010 .Em Remarks :
1011 this macro is sometimes abused to emulate optional arguments for
1012 commands; the correct macros to use for this purpose are
1013 .Sx \&Op ,
1014 .Sx \&Oo ,
1015 and
1016 .Sx \&Oc .
1017 .Pp
1018 See also
1019 .Sx \&Bo .
1020 .
1021 .Ss \&Brc
1022 Closes a
1023 .Sx \&Bro
1024 block.  Does not have any tail arguments.
1025 .
1026 .Ss \&Bro
1027 Begins a block enclosed by curly braces.  Does not have any head
1028 arguments.
1029 .Pp
1030 Examples:
1031 .Bd -literal -offset indent
1032 \&.Bro 1 , ... ,
1033 \&.Va n Brc
1034 .Ed
1035 .Pp
1036 See also
1037 .Sx \&Brq .
1038 .
1039 .Ss \&Brq
1040 Encloses its arguments in curly braces.
1041 .Pp
1042 Examples:
1043 .Bd -literal -offset indent
1044 \&.Brq 1 , ... , Va n
1045 .Ed
1046 .Pp
1047 See also
1048 .Sx \&Bro .
1049 .
1050 .Ss \&Bsx
1051 Format the BSD/OS version provided as an argument, or a default value if
1052 no argument is provided.
1053 .Pp
1054 Examples:
1055 .Bd -literal -offset indent
1056 \&.Bsx 1.0
1057 \&.Bsx
1058 .Ed
1059 .Pp
1060 See also
1061 .Sx \&At ,
1062 .Sx \&Bx ,
1063 .Sx \&Dx ,
1064 .Sx \&Fx ,
1065 .Sx \&Nx ,
1066 .Sx \&Ox ,
1067 and
1068 .Sx \&Ux .
1069 .
1070 .Ss \&Bt
1071 Prints
1072 .Dq is currently in beta test.
1073 .
1074 .Ss \&Bx
1075 Format the BSD version provided as an argument, or a default value if no
1076 argument is provided.
1077 .Pp
1078 Examples:
1079 .Bd -literal -offset indent
1080 \&.Bx 4.4
1081 \&.Bx
1082 .Ed
1083 .Pp
1084 See also
1085 .Sx \&At ,
1086 .Sx \&Bsx ,
1087 .Sx \&Dx ,
1088 .Sx \&Fx ,
1089 .Sx \&Nx ,
1090 .Sx \&Ox ,
1091 and
1092 .Sx \&Ux .
1093 .
1094 .Ss \&Cd
1095 Configuration declaration (suggested for use only in section four
1096 manuals).  This denotes strings accepted by
1097 .Xr config 8 .
1098 .Pp
1099 Examples:
1100 .Bd -literal -offset indent
1101 \&.Cd device le0 at scode?
1102 .Ed
1103 .Pp
1104 .Em Remarks :
1105 this macro is commonly abused by using quoted literals to retain
1106 white-space and align consecutive
1107 .Sx \&Cd
1108 declarations.  This practise is discouraged.
1109 .
1110 .Ss \&Cm
1111 Command modifiers.  Useful when specifying configuration options or
1112 keys.
1113 .Pp
1114 Examples:
1115 .Bd -literal -offset indent
1116 \&.Cm ControlPath
1117 \&.Cm ControlMaster
1118 .Ed
1119 .Pp
1120 See also
1121 .Sx \&Fl .
1122 .
1123 .Ss \&D1
1124 One-line indented display.  This is formatted by the default rules and
1125 is useful for simple indented statements.  It is followed by a newline.
1126 .Pp
1127 Examples:
1128 .Bd -literal -offset indent
1129 \&.D1 Fl abcdefgh
1130 .Ed
1131 .Pp
1132 See also
1133 .Sx \&Bd
1134 and
1135 .Sx \&Dl .
1136 .
1137 .Ss \&Db
1138 .Ss \&Dc
1139 Closes a
1140 .Sx \&Do
1141 block.  Does not have any tail arguments.
1142 .
1143 .Ss \&Dd
1144 Document date.  This is the mandatory first macro of any
1145 .Nm
1146 manual.  Its calling syntax is as follows:
1147 .Pp
1148 .D1 \. Ns Sx \&Dd Cm date
1149 .Pp
1150 The
1151 .Cm date
1152 field may be either
1153 .Ar $\&Mdocdate$ ,
1154 which signifies the current manual revision date dictated by
1155 .Xr cvs 1
1156 or instead a valid canonical date as specified by
1157 .Sx Dates .
1158 .Pp
1159 Examples:
1160 .Bd -literal -offset indent
1161 \&.Dd $\&Mdocdate$
1162 \&.Dd $\&Mdocdate: July 21 2007$
1163 \&.Dd July 21, 2007
1164 .Ed
1165 .Pp
1166 See also
1167 .Sx \&Dt
1168 and
1169 .Sx \&Os .
1170 .
1171 .Ss \&Dl
1172 One-line intended display.  This is formatted as literal text and is
1173 useful for commands and invocations.  It is followed by a newline.
1174 .Pp
1175 Examples:
1176 .Bd -literal -offset indent
1177 \&.Dl % mandoc mdoc.7 | less
1178 .Ed
1179 .Pp
1180 See also
1181 .Sx \&Bd
1182 and
1183 .Sx \&D1 .
1184 .
1185 .Ss \&Do
1186 Begins a block enclosed by double quotes.  Does not have any head
1187 arguments.
1188 .Pp
1189 Examples:
1190 .Bd -literal -offset indent
1191 \&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
1192 .Ed
1193 .Pp
1194 See also
1195 .Sx \&Dq .
1196 .
1197 .Ss \&Dq
1198 Encloses its arguments in double quotes.
1199 .Pp
1200 Examples:
1201 .Bd -literal -offset indent
1202 \&.Dq April is the cruellest month
1203 \e(em T.S. Eliot
1204 .Ed
1205 .Pp
1206 See also
1207 .Sx \&Do .
1208 .
1209 .Ss \&Dt
1210 Document title.  This is the mandatory second macro of any
1211 .Nm
1212 file.  Its calling syntax is as follows:
1213 .Pp
1214 .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
1215 .Pp
1216 Its arguments are as follows:
1217 .Bl -tag -width Ds -offset Ds
1218 .It Cm title
1219 The document's title (name).  This should be capitalised and is
1220 required.
1221 .It Cm section
1222 The manual section.  This may be one of
1223 .Ar 1
1224 .Pq utilities ,
1225 .Ar 2
1226 .Pq system calls ,
1227 .Ar 3
1228 .Pq libraries ,
1229 .Ar 3p
1230 .Pq Perl libraries ,
1231 .Ar 4
1232 .Pq devices ,
1233 .Ar 5
1234 .Pq file formats ,
1235 .Ar 6
1236 .Pq games ,
1237 .Ar 7
1238 .Pq miscellaneous ,
1239 .Ar 8
1240 .Pq system utilities ,
1241 .Ar 9
1242 .Pq kernel functions ,
1243 .Ar X11
1244 .Pq X Window System ,
1245 .Ar X11R6
1246 .Pq X Window System ,
1247 .Ar unass
1248 .Pq unassociated ,
1249 .Ar local
1250 .Pq local system ,
1251 .Ar draft
1252 .Pq draft manual ,
1253 or
1254 .Ar paper
1255 .Pq paper .
1256 It is also required and should correspond to the manual's filename
1257 suffix.
1258 .It Cm volume
1259 This overrides the volume inferred from
1260 .Ar section .
1261 This field is optional, and if specified, must be one of
1262 .Ar USD
1263 .Pq users' supplementary documents ,
1264 .Ar PS1
1265 .Pq programmers' supplementary documents ,
1266 .Ar AMD
1267 .Pq administrators' supplementary documents ,
1268 .Ar SMM
1269 .Pq system managers' manuals ,
1270 .Ar URM
1271 .Pq users' reference manuals ,
1272 .Ar PRM
1273 .Pq programmers' reference manuals ,
1274 .Ar KM
1275 .Pq kernel manuals ,
1276 .Ar IND
1277 .Pq master index ,
1278 .Ar MMI
1279 .Pq master index ,
1280 .Ar LOCAL
1281 .Pq local manuals ,
1282 .Ar LOC
1283 .Pq local manuals ,
1284 or
1285 .Ar CON
1286 .Pq contributed manuals .
1287 .It Cm arch
1288 This specifies a specific relevant architecture.  If
1289 .Cm volume
1290 is not provided, it may be used in its place, else it may be used
1291 subsequent that.  It, too, is optional.  It must be one of
1292 .Ar alpha ,
1293 .Ar amiga ,
1294 .Ar arc ,
1295 .Ar arm ,
1296 .Ar armish ,
1297 .Ar aviion ,
1298 .Ar hp300 ,
1299 .Ar hppa ,
1300 .Ar hppa64 ,
1301 .Ar i386 ,
1302 .Ar landisk ,
1303 .Ar luna88k ,
1304 .Ar mac68k ,
1305 .Ar macppc ,
1306 .Ar mvme68k ,
1307 .Ar mvme88k ,
1308 .Ar mvmeppc ,
1309 .Ar pmax ,
1310 .Ar sgi ,
1311 .Ar socppc ,
1312 .Ar sparc ,
1313 .Ar sparc64 ,
1314 .Ar sun3 ,
1315 .Ar vax ,
1316 .Ar x86_64 ,
1317 or
1318 .Ar zaurus .
1319 .El
1320 .Pp
1321 Examples:
1322 .Bd -literal -offset indent
1323 \&.Dt FOO 1
1324 \&.Dt FOO 4 KM
1325 \&.Dt FOO 9 i386
1326 \&.Dt FOO 9 KM i386
1327 .Ed
1328 .Pp
1329 See also
1330 .Sx \&Dd
1331 and
1332 .Sx \&Os .
1333 .
1334 .Ss \&Dv
1335 Defined variables such as preprocessor constants.
1336 .Pp
1337 Examples:
1338 .Bd -literal -offset indent
1339 \&.Dv BUFSIZ
1340 \&.Dv STDOUT_FILENO
1341 .Ed
1342 .Pp
1343 See also
1344 .Sx \&Er .
1345 .
1346 .Ss \&Dx
1347 Format the DragonFlyBSD version provided as an argument, or a default
1348 value if no argument is provided.
1349 .Pp
1350 Examples:
1351 .Bd -literal -offset indent
1352 \&.Dx 2.4.1
1353 \&.Dx
1354 .Ed
1355 .Pp
1356 See also
1357 .Sx \&At ,
1358 .Sx \&Bsx ,
1359 .Sx \&Bx ,
1360 .Sx \&Fx ,
1361 .Sx \&Nx ,
1362 .Sx \&Ox ,
1363 and
1364 .Sx \&Ux .
1365 .
1366 .Ss \&Ec
1367 .Ss \&Ed
1368 .Ss \&Ef
1369 .Ss \&Ek
1370 .Ss \&El
1371 .Ss \&Em
1372 Denotes text that should be emphasised.  Note that this is a
1373 presentation term and should not be used for stylistically decorating
1374 technical terms.
1375 .Pp
1376 Examples:
1377 .Bd -literal -offset indent
1378 \&.Ed Warnings!
1379 \&.Ed Remarks :
1380 .Ed
1381 .
1382 .Ss \&En
1383 .Ss \&Eo
1384 .Ss \&Er
1385 Error constants (suggested for use only in section two manuals).
1386 .Pp
1387 Examples:
1388 .Bd -literal -offset indent
1389 \&.Er EPERM
1390 \&.Er ENOENT
1391 .Ed
1392 .Pp
1393 See also
1394 .Sx \&Dv .
1395 .
1396 .Ss \&Es
1397 .
1398 .Ss \&Ev
1399 Environmental variables such as those specified in
1400 .Xr environ 7 .
1401 .Pp
1402 Examples:
1403 .Bd -literal -offset indent
1404 \&.Ev DISPLAY
1405 \&.Ev PATH
1406 .Ed
1407 .
1408 .Ss \&Ex
1409 Inserts text regarding a utility's exit values.  This macro must have
1410 first the
1411 .Fl std
1412 argument specified, then an optional
1413 .Ar utility .
1414 If
1415 .Ar utility
1416 is not provided, the document's name as stipulated in
1417 .Sx \&Nm
1418 is provided.
1419 .Ss \&Fa
1420 .Ss \&Fc
1421 .Ss \&Fd
1422 .Ss \&Fl
1423 .Ss \&Fn
1424 .Ss \&Fo
1425 .Ss \&Fr
1426 .Ss \&Ft
1427 .Ss \&Fx
1428 Format the FreeBSD version provided as an argument, or a default value
1429 if no argument is provided.
1430 .Pp
1431 Examples:
1432 .Bd -literal -offset indent
1433 \&.Fx 7.1
1434 \&.Fx
1435 .Ed
1436 .Pp
1437 See also
1438 .Sx \&At ,
1439 .Sx \&Bsx ,
1440 .Sx \&Bx ,
1441 .Sx \&Dx ,
1442 .Sx \&Nx ,
1443 .Sx \&Ox ,
1444 and
1445 .Sx \&Ux .
1446 .
1447 .Ss \&Hf
1448 .Ss \&Ic
1449 .Ss \&In
1450 .Ss \&It
1451 .Ss \&Lb
1452 .Ss \&Li
1453 .Ss \&Lk
1454 Format a hyperlink.  The calling syntax is as follows:
1455 .Pp
1456 .D1 \. Ns Sx \&Lk Cm uri Op Cm name
1457 .Pp
1458 Examples:
1459 .Bd -literal -offset indent
1460 \&.Lk http://bsd.lv "The BSD.lv Project"
1461 \&.Lk http://bsd.lv
1462 .Ed
1463 .Pp
1464 See also
1465 .Sx \&Mt .
1466 .
1467 .Ss \&Lp
1468 .Ss \&Ms
1469 .Ss \&Mt
1470 .Ss \&Nd
1471 .Ss \&Nm
1472 .Ss \&No
1473 .Ss \&Ns
1474 .Ss \&Nx
1475 Format the NetBSD version provided as an argument, or a default value if
1476 no argument is provided.
1477 .Pp
1478 Examples:
1479 .Bd -literal -offset indent
1480 \&.Nx 5.01
1481 \&.Nx
1482 .Ed
1483 .Pp
1484 See also
1485 .Sx \&At ,
1486 .Sx \&Bsx ,
1487 .Sx \&Bx ,
1488 .Sx \&Dx ,
1489 .Sx \&Fx ,
1490 .Sx \&Ox ,
1491 and
1492 .Sx \&Ux .
1493 .
1494 .Ss \&Oc
1495 .Ss \&Oo
1496 .Ss \&Op
1497 .Ss \&Os
1498 Document operating system version.  This is the mandatory third macro of
1499 any
1500 .Nm
1501 file.  Its calling syntax is as follows:
1502 .Pp
1503 .D1 \. Ns Sx \&Os Op Cm system
1504 .Pp
1505 The optional
1506 .Cm system
1507 parameter specifies the relevant operating system or environment.  Left
1508 unspecified, it defaults to the local operating system version.  This is
1509 the suggested form.
1510 .Pp
1511 Examples:
1512 .Bd -literal -offset indent
1513 \&.Os
1514 \&.Os KTH/CSC/TCS
1515 \&.Os BSD 4.3
1516 .Ed
1517 .Pp
1518 See also
1519 .Sx \&Dd
1520 and
1521 .Sx \&Dt .
1522 .
1523 .Ss \&Ot
1524 Unknown usage.
1525 .Pp
1526 .Em Remarks :
1527 this macro has been deprecated.
1528 .
1529 .Ss \&Ox
1530 Format the OpenBSD version provided as an argument, or a default value
1531 if no argument is provided.
1532 .Pp
1533 Examples:
1534 .Bd -literal -offset indent
1535 \&.Ox 4.5
1536 \&.Ox
1537 .Ed
1538 .Pp
1539 See also
1540 .Sx \&At ,
1541 .Sx \&Bsx ,
1542 .Sx \&Bx ,
1543 .Sx \&Dx ,
1544 .Sx \&Fx ,
1545 .Sx \&Nx ,
1546 and
1547 .Sx \&Ux .
1548 .
1549 .Ss \&Pa
1550 .Ss \&Pc
1551 .Ss \&Pf
1552 .Ss \&Po
1553 .Ss \&Pp
1554 .Ss \&Pq
1555 .Ss \&Qc
1556 .Ss \&Ql
1557 .Ss \&Qo
1558 .Ss \&Qq
1559 .
1560 .Ss \&Re
1561 Closes a
1562 .Sx \&Rs
1563 block.  Does not have any tail arguments.
1564 .
1565 .Ss \&Rs
1566 Begins a bibliographic
1567 .Pq Dq reference
1568 block.  Does not have any head arguments.  The block macro may only
1569 contain
1570 .Sx \&%A ,
1571 .Sx \&%B ,
1572 .Sx \&%C ,
1573 .Sx \&%D ,
1574 .Sx \&%I ,
1575 .Sx \&%J ,
1576 .Sx \&%N ,
1577 .Sx \&%O ,
1578 .Sx \&%P ,
1579 .Sx \&%Q ,
1580 .Sx \&%R ,
1581 .Sx \&%T ,
1582 and
1583 .Sx \&%V
1584 child macros (at least one must be specified).
1585 .Pp
1586 Examples:
1587 .Bd -literal -offset indent
1588 \&.Rs
1589 \&.%A J. E. Hopcroft
1590 \&.%A J. D. Ullman
1591 \&.%B Introduction to Automata Theory, Languages, and Computation
1592 \&.%I Addison-Wesley
1593 \&.%C Reading, Massachusettes
1594 \&.%D 1979
1595 \&.Re
1596 .Ed
1597 .Pp
1598 If an
1599 .Sx \&Rs
1600 block is used within a SEE ALSO section, a vertical space is asserted
1601 before the rendered output, else the block continues on the current
1602 line.
1603 .
1604 .Ss \&Rv
1605 .Ss \&Sc
1606 .Ss \&Sh
1607 .Ss \&Sm
1608 .Ss \&So
1609 .Ss \&Sq
1610 .Ss \&Ss
1611 .Ss \&St
1612 .Ss \&Sx
1613 .Ss \&Sy
1614 .Ss \&Tn
1615 .Ss \&Ud
1616 .Ss \&Ux
1617 Format the UNIX name.  Accepts no argument.
1618 .Pp
1619 Examples:
1620 .Bd -literal -offset indent
1621 \&.Ux
1622 .Ed
1623 .Pp
1624 See also
1625 .Sx \&At ,
1626 .Sx \&Bsx ,
1627 .Sx \&Bx ,
1628 .Sx \&Dx ,
1629 .Sx \&Fx ,
1630 .Sx \&Nx ,
1631 and
1632 .Sx \&Ox .
1633 .
1634 .Ss \&Va
1635 .Ss \&Vt
1636 .Ss \&Xc
1637 .Ss \&Xo
1638 .Ss \&Xr
1639 .Ss \&br
1640 .Ss \&sp
1641 .
1642 .
1643 .Sh COMPATIBILITY
1644 This section documents compatibility with other roff implementations, at
1645 this time limited to
1646 .Xr groff 1 .
1647 The term
1648 .Qq historic groff
1649 refers to those versions before the
1650 .Pa doc.tmac
1651 file re-write
1652 .Pq somewhere between 1.15 and 1.19 .
1653 .
1654 .Pp
1655 .Bl -dash -compact
1656 .It
1657 Negative scaling units are now truncated to zero instead of creating
1658 interesting conditions, such as with
1659 .Sq \&sp -1i .
1660 Furthermore, the
1661 .Sq f
1662 scaling unit, while accepted, is rendered as the default unit.
1663 .It
1664 In quoted literals, groff allowed pair-wise double-quotes to produce a
1665 standalone double-quote in formatted output.  This idiosyncratic
1666 behaviour is no longer applicable.
1667 .It
1668 Display types
1669 .Sx \&Bd Fl center
1670 and
1671 .Fl right
1672 are aliases for
1673 .Fl left .
1674 The
1675 .Fl file Ar file
1676 argument is ignored.  Since text is not right-justified,
1677 .Fl ragged
1678 and
1679 .Fl filled
1680 are aliases, as are
1681 .Fl literal
1682 and
1683 .Fl unfilled .
1684 .It
1685 Blocks of whitespace are stripped from both macro and free-form text
1686 lines (except when in literal mode), while groff would retain whitespace
1687 in free-form text lines.
1688 .It
1689 Historic groff has many un-callable macros.  Most of these (excluding
1690 some block-level macros) are now callable, conforming to the
1691 non-historic groff version.
1692 .It
1693 The vertical bar
1694 .Sq \(ba
1695 made historic groff
1696 .Qq go orbital
1697 but is a proper delimiter in this implementation.
1698 .It
1699 .Sx \&It Fl nested
1700 is assumed for all lists (it wasn't in historic groff): any list may be
1701 nested and
1702 .Fl enum
1703 lists will restart the sequence only for the sub-list.
1704 .It
1705 Some manuals use
1706 .Sx \&Li
1707 incorrectly by following it with a reserved character and expecting the
1708 delimiter to render.  This is not supported.
1709 .It
1710 In groff, the
1711 .Sx \&Fo
1712 macro only produces the first parameter.  This is no longer the case.
1713 .El
1714 .
1715 .
1716 .Sh SEE ALSO
1717 .Xr mandoc 1 ,
1718 .Xr mandoc_char 7
1719 .
1720 .
1721 .Sh AUTHORS
1722 The
1723 .Nm
1724 reference was written by
1725 .An Kristaps Dzonsons Aq kristaps@kth.se .
1726 .\"
1727 .\" XXX: this really isn't the place for these caveats.
1728 .\" .
1729 .\" .
1730 .\" .Sh CAVEATS
1731 .\" There are many ambiguous parts of mdoc.
1732 .\" .
1733 .\" .Pp
1734 .\" .Bl -dash -compact
1735 .\" .It
1736 .\" .Sq \&Fa
1737 .\" should be
1738 .\" .Sq \&Va
1739 .\" as function arguments are variables.
1740 .\" .It
1741 .\" .Sq \&Ft
1742 .\" should be
1743 .\" .Sq \&Vt
1744 .\" as function return types are still types.  Furthermore, the
1745 .\" .Sq \&Ft
1746 .\" should be removed and
1747 .\" .Sq \&Fo ,
1748 .\" which ostensibly follows it, should follow the same convention as
1749 .\" .Sq \&Va .
1750 .\" .It
1751 .\" .Sq \&Va
1752 .\" should formalise that only one or two arguments are acceptable: a
1753 .\" variable name and optional, preceding type.
1754 .\" .It
1755 .\" .Sq \&Fd
1756 .\" is ambiguous.  It's commonly used to indicate an include file in the
1757 .\" synopsis section.
1758 .\" .Sq \&In
1759 .\" should be used, instead.
1760 .\" .It
1761 .\" Only the
1762 .\" .Sq \-literal
1763 .\" argument to
1764 .\" .Sq \&Bd
1765 .\" makes sense.  The remaining ones should be removed.
1766 .\" .It
1767 .\" The
1768 .\" .Sq \&Xo
1769 .\" and
1770 .\" .Sq \&Xc
1771 .\" macros should be deprecated.
1772 .\" .It
1773 .\" The
1774 .\" .Sq \&Dt
1775 .\" macro lacks clarity.  It should be absolutely clear which title will
1776 .\" render when formatting the manual page.
1777 .\" .It
1778 .\" A
1779 .\" .Sq \&Lx
1780 .\" should be provided for Linux (\(`a la
1781 .\" .Sq \&Ox ,
1782 .\" .Sq \&Nx
1783 .\" etc.).
1784 .\" .It
1785 .\" There's no way to refer to references in
1786 .\" .Sq \&Rs/Re
1787 .\" blocks.
1788 .\" .It
1789 .\" The \-split and \-nosplit dictates via
1790 .\" .Sq \&An
1791 .\" are re-set when entering and leaving the AUTHORS section.
1792 .\" .El
1793 .\" .