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