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