Annotation of mandoc/mdoc.7, Revision 1.195
1.195 ! schwarze 1: .\" $Id: mdoc.7,v 1.194 2011/08/01 07:45:11 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.195 ! schwarze 18: .Dd $Mdocdate: August 1 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.141 kristaps 1040: Requires either the name of an author or one of the following arguments:
1.140 kristaps 1041: .Pp
1042: .Bl -tag -width "-nosplitX" -offset indent -compact
1.64 kristaps 1043: .It Fl split
1.141 kristaps 1044: Start a new output line before each subsequent invocation of
1045: .Sx \&An .
1.64 kristaps 1046: .It Fl nosplit
1047: The opposite of
1048: .Fl split .
1049: .El
1050: .Pp
1.141 kristaps 1051: The default is
1052: .Fl nosplit .
1053: The effect of selecting either of the
1054: .Fl split
1055: modes ends at the beginning of the
1056: .Em AUTHORS
1057: section.
1.140 kristaps 1058: In the
1059: .Em AUTHORS
1.141 kristaps 1060: section, the default is
1061: .Fl nosplit
1062: for the first author listing and
1.64 kristaps 1063: .Fl split
1.141 kristaps 1064: for all other author listings.
1.64 kristaps 1065: .Pp
1066: Examples:
1.173 kristaps 1067: .Dl \&.An -nosplit
1068: .Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
1.63 kristaps 1069: .Ss \&Ao
1.141 kristaps 1070: Begin a block enclosed by angle brackets.
1.100 kristaps 1071: Does not have any head arguments.
1.63 kristaps 1072: .Pp
1.64 kristaps 1073: Examples:
1.173 kristaps 1074: .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
1.63 kristaps 1075: .Pp
1.64 kristaps 1076: See also
1077: .Sx \&Aq .
1.63 kristaps 1078: .Ss \&Ap
1.138 kristaps 1079: Inserts an apostrophe without any surrounding whitespace.
1.124 kristaps 1080: This is generally used as a grammatical device when referring to the verb
1.140 kristaps 1081: form of a function.
1082: .Pp
1083: Examples:
1.173 kristaps 1084: .Dl \&.Fn execve \&Ap d
1.63 kristaps 1085: .Ss \&Aq
1.141 kristaps 1086: Encloses its arguments in angle brackets.
1.64 kristaps 1087: .Pp
1088: Examples:
1.173 kristaps 1089: .Dl \&.Fl -key= \&Ns \&Aq \&Ar val
1.64 kristaps 1090: .Pp
1091: .Em Remarks :
1092: this macro is often abused for rendering URIs, which should instead use
1093: .Sx \&Lk
1094: or
1095: .Sx \&Mt ,
1096: or to note pre-processor
1097: .Dq Li #include
1098: statements, which should use
1099: .Sx \&In .
1100: .Pp
1101: See also
1102: .Sx \&Ao .
1.63 kristaps 1103: .Ss \&Ar
1.100 kristaps 1104: Command arguments.
1105: If an argument is not provided, the string
1.141 kristaps 1106: .Dq file ...\&
1.66 kristaps 1107: is used as a default.
1.64 kristaps 1108: .Pp
1109: Examples:
1.173 kristaps 1110: .Dl \&.Fl o \&Ns \&Ar file1
1111: .Dl \&.Ar
1112: .Dl \&.Ar arg1 , arg2 .
1.63 kristaps 1113: .Ss \&At
1.100 kristaps 1114: Formats an AT&T version.
1.141 kristaps 1115: Accepts one optional argument:
1.140 kristaps 1116: .Pp
1117: .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
1.64 kristaps 1118: .It Cm v[1-7] | 32v
1119: A version of
1120: .At .
1.192 schwarze 1121: .It Cm III
1122: .At III .
1.64 kristaps 1123: .It Cm V[.[1-4]]?
1.141 kristaps 1124: A version of
1125: .At V .
1.64 kristaps 1126: .El
1127: .Pp
1.141 kristaps 1128: Note that these arguments do not begin with a hyphen.
1.64 kristaps 1129: .Pp
1130: Examples:
1.173 kristaps 1131: .Dl \&.At
1.192 schwarze 1132: .Dl \&.At III
1.173 kristaps 1133: .Dl \&.At V.1
1.65 kristaps 1134: .Pp
1135: See also
1.66 kristaps 1136: .Sx \&Bsx ,
1.65 kristaps 1137: .Sx \&Bx ,
1.66 kristaps 1138: .Sx \&Dx ,
1.65 kristaps 1139: .Sx \&Fx ,
1140: .Sx \&Nx ,
1141: .Sx \&Ox ,
1142: and
1143: .Sx \&Ux .
1.63 kristaps 1144: .Ss \&Bc
1.141 kristaps 1145: Close a
1.64 kristaps 1146: .Sx \&Bo
1.138 kristaps 1147: block.
1148: Does not have any tail arguments.
1.63 kristaps 1149: .Ss \&Bd
1.141 kristaps 1150: Begin a display block.
1.131 kristaps 1151: Its syntax is as follows:
1152: .Bd -ragged -offset indent
1153: .Pf \. Sx \&Bd
1.141 kristaps 1154: .Fl Ns Ar type
1.131 kristaps 1155: .Op Fl offset Ar width
1156: .Op Fl compact
1157: .Ed
1158: .Pp
1.141 kristaps 1159: Display blocks are used to select a different indentation and
1160: justification than the one used by the surrounding text.
1.185 kristaps 1161: They may contain both macro lines and text lines.
1.141 kristaps 1162: By default, a display block is preceded by a vertical space.
1.64 kristaps 1163: .Pp
1.141 kristaps 1164: The
1165: .Ar type
1166: must be one of the following:
1167: .Bl -tag -width 13n -offset indent
1168: .It Fl centered
1169: Centre-justify each line.
1170: Using this display type is not recommended; many
1171: .Nm
1172: implementations render it poorly.
1173: .It Fl filled
1174: Left- and right-justify the block.
1175: .It Fl literal
1176: Do not justify the block at all.
1.169 kristaps 1177: Preserve white space as it appears in the input.
1.64 kristaps 1178: .It Fl ragged
1179: Only left-justify the block.
1180: .It Fl unfilled
1.141 kristaps 1181: An alias for
1182: .Fl literal .
1.64 kristaps 1183: .El
1184: .Pp
1.141 kristaps 1185: The
1186: .Ar type
1187: must be provided first.
1188: Additional arguments may follow:
1189: .Bl -tag -width 13n -offset indent
1190: .It Fl offset Ar width
1191: Indent the display by the
1192: .Ar width ,
1193: which may be one of the following:
1.64 kristaps 1194: .Bl -item
1195: .It
1.141 kristaps 1196: One of the pre-defined strings
1197: .Cm indent ,
1.64 kristaps 1198: the width of standard indentation;
1.141 kristaps 1199: .Cm indent-two ,
1.64 kristaps 1200: twice
1.141 kristaps 1201: .Cm indent ;
1202: .Cm left ,
1.131 kristaps 1203: which has no effect;
1.141 kristaps 1204: .Cm right ,
1205: which justifies to the right margin; or
1206: .Cm center ,
1.64 kristaps 1207: which aligns around an imagined centre axis.
1208: .It
1.141 kristaps 1209: A macro invocation, which selects a predefined width
1210: associated with that macro.
1.100 kristaps 1211: The most popular is the imaginary macro
1.67 kristaps 1212: .Ar \&Ds ,
1.64 kristaps 1213: which resolves to
1.141 kristaps 1214: .Sy 6n .
1.64 kristaps 1215: .It
1.141 kristaps 1216: A width using the syntax described in
1.64 kristaps 1217: .Sx Scaling Widths .
1218: .It
1.141 kristaps 1219: An arbitrary string, which indents by the length of this string.
1.64 kristaps 1220: .El
1221: .Pp
1.141 kristaps 1222: When the argument is missing,
1223: .Fl offset
1224: is ignored.
1.64 kristaps 1225: .It Fl compact
1.141 kristaps 1226: Do not assert vertical space before the display.
1.64 kristaps 1227: .El
1228: .Pp
1229: Examples:
1230: .Bd -literal -offset indent
1.141 kristaps 1231: \&.Bd \-literal \-offset indent \-compact
1.65 kristaps 1232: Hello world.
1.64 kristaps 1233: \&.Ed
1234: .Ed
1.66 kristaps 1235: .Pp
1236: See also
1237: .Sx \&D1
1238: and
1239: .Sx \&Dl .
1.63 kristaps 1240: .Ss \&Bf
1.129 kristaps 1241: Change the font mode for a scoped block of text.
1242: Its syntax is as follows:
1243: .Bd -ragged -offset indent
1244: .Pf \. Sx \&Bf
1245: .Oo
1246: .Fl emphasis | literal | symbolic |
1247: .Cm \&Em | \&Li | \&Sy
1248: .Oc
1249: .Ed
1250: .Pp
1251: The
1252: .Fl emphasis
1253: and
1254: .Cm \&Em
1255: argument are equivalent, as are
1256: .Fl symbolic
1257: and
1.144 schwarze 1258: .Cm \&Sy ,
1.129 kristaps 1259: and
1260: .Fl literal
1261: and
1262: .Cm \&Li .
1263: Without an argument, this macro does nothing.
1264: The font mode continues until broken by a new font mode in a nested
1265: scope or
1266: .Sx \&Ef
1267: is encountered.
1268: .Pp
1269: See also
1270: .Sx \&Li ,
1271: .Sx \&Ef ,
1.141 kristaps 1272: .Sx \&Em ,
1.129 kristaps 1273: and
1274: .Sx \&Sy .
1.63 kristaps 1275: .Ss \&Bk
1.186 schwarze 1276: For each macro, keep its output together on the same output line,
1277: until the end of the macro or the end of the input line is reached,
1278: whichever comes first.
1.185 kristaps 1279: Line breaks in text lines are unaffected.
1.141 kristaps 1280: The syntax is as follows:
1.131 kristaps 1281: .Pp
1282: .D1 Pf \. Sx \&Bk Fl words
1283: .Pp
1.133 kristaps 1284: The
1285: .Fl words
1.141 kristaps 1286: argument is required; additional arguments are ignored.
1.127 schwarze 1287: .Pp
1.141 kristaps 1288: The following example will not break within each
1.133 kristaps 1289: .Sx \&Op
1290: macro line:
1.127 schwarze 1291: .Bd -literal -offset indent
1292: \&.Bk \-words
1.133 kristaps 1293: \&.Op Fl f Ar flags
1294: \&.Op Fl o Ar output
1.127 schwarze 1295: \&.Ek
1296: .Ed
1.129 kristaps 1297: .Pp
1.133 kristaps 1298: Be careful in using over-long lines within a keep block!
1299: Doing so will clobber the right margin.
1.63 kristaps 1300: .Ss \&Bl
1.141 kristaps 1301: Begin a list.
1.171 schwarze 1302: Lists consist of items specified using the
1.141 kristaps 1303: .Sx \&It
1304: macro, containing a head or a body or both.
1305: The list syntax is as follows:
1.131 kristaps 1306: .Bd -ragged -offset indent
1307: .Pf \. Sx \&Bl
1.141 kristaps 1308: .Fl Ns Ar type
1.131 kristaps 1309: .Op Fl width Ar val
1310: .Op Fl offset Ar val
1311: .Op Fl compact
1312: .Op HEAD ...
1313: .Ed
1314: .Pp
1.141 kristaps 1315: The list
1316: .Ar type
1317: is mandatory and must be specified first.
1318: The
1319: .Fl width
1320: and
1321: .Fl offset
1322: arguments accept
1.104 kristaps 1323: .Sx Scaling Widths
1.141 kristaps 1324: or use the length of the given string.
1325: The
1326: .Fl offset
1327: is a global indentation for the whole list, affecting both item heads
1328: and bodies.
1329: For those list types supporting it, the
1330: .Fl width
1331: argument requests an additional indentation of item bodies,
1332: to be added to the
1333: .Fl offset .
1334: Unless the
1335: .Fl compact
1336: argument is specified, list entries are separated by vertical space.
1337: .Pp
1.103 kristaps 1338: A list must specify one of the following list types:
1339: .Bl -tag -width 12n -offset indent
1340: .It Fl bullet
1.141 kristaps 1341: No item heads can be specified, but a bullet will be printed at the head
1342: of each item.
1343: Item bodies start on the same output line as the bullet
1344: and are indented according to the
1.104 kristaps 1345: .Fl width
1.141 kristaps 1346: argument.
1.103 kristaps 1347: .It Fl column
1348: A columnated list.
1.104 kristaps 1349: The
1350: .Fl width
1.141 kristaps 1351: argument has no effect; instead, each argument specifies the width
1352: of one column, using either the
1.103 kristaps 1353: .Sx Scaling Widths
1.141 kristaps 1354: syntax or the string length of the argument.
1355: If the first line of the body of a
1.114 kristaps 1356: .Fl column
1357: list is not an
1358: .Sx \&It
1.141 kristaps 1359: macro line,
1360: .Sx \&It
1361: contexts spanning one input line each are implied until an
1.114 kristaps 1362: .Sx \&It
1.141 kristaps 1363: macro line is encountered, at which point items start being interpreted as
1.114 kristaps 1364: described in the
1365: .Sx \&It
1366: documentation.
1.103 kristaps 1367: .It Fl dash
1.141 kristaps 1368: Like
1369: .Fl bullet ,
1370: except that dashes are used in place of bullets.
1.103 kristaps 1371: .It Fl diag
1372: Like
1373: .Fl inset ,
1.141 kristaps 1374: except that item heads are not parsed for macro invocations.
1375: .\" but with additional formatting to the head.
1.103 kristaps 1376: .It Fl enum
1.141 kristaps 1377: A numbered list.
1378: Formatted like
1379: .Fl bullet ,
1380: except that cardinal numbers are used in place of bullets,
1381: starting at 1.
1.103 kristaps 1382: .It Fl hang
1383: Like
1384: .Fl tag ,
1.141 kristaps 1385: except that the first lines of item bodies are not indented, but follow
1386: the item heads like in
1387: .Fl inset
1388: lists.
1.103 kristaps 1389: .It Fl hyphen
1390: Synonym for
1391: .Fl dash .
1392: .It Fl inset
1.141 kristaps 1393: Item bodies follow items heads on the same line, using normal inter-word
1394: spacing.
1395: Bodies are not indented, and the
1.104 kristaps 1396: .Fl width
1397: argument is ignored.
1.103 kristaps 1398: .It Fl item
1.141 kristaps 1399: No item heads can be specified, and none are printed.
1400: Bodies are not indented, and the
1.104 kristaps 1401: .Fl width
1402: argument is ignored.
1.103 kristaps 1403: .It Fl ohang
1.141 kristaps 1404: Item bodies start on the line following item heads and are not indented.
1.104 kristaps 1405: The
1406: .Fl width
1407: argument is ignored.
1.103 kristaps 1408: .It Fl tag
1.141 kristaps 1409: Item bodies are indented according to the
1.103 kristaps 1410: .Fl width
1411: argument.
1.141 kristaps 1412: When an item head fits inside the indentation, the item body follows
1413: this head on the same output line.
1414: Otherwise, the body starts on the output line following the head.
1.103 kristaps 1415: .El
1.114 kristaps 1416: .Pp
1417: See also
1.141 kristaps 1418: .Sx \&El
1419: and
1.114 kristaps 1420: .Sx \&It .
1.63 kristaps 1421: .Ss \&Bo
1.141 kristaps 1422: Begin a block enclosed by square brackets.
1.100 kristaps 1423: Does not have any head arguments.
1.65 kristaps 1424: .Pp
1425: Examples:
1.140 kristaps 1426: .Bd -literal -offset indent -compact
1.65 kristaps 1427: \&.Bo 1 ,
1.91 kristaps 1428: \&.Dv BUFSIZ \&Bc
1.65 kristaps 1429: .Ed
1430: .Pp
1431: See also
1432: .Sx \&Bq .
1.63 kristaps 1433: .Ss \&Bq
1.82 kristaps 1434: Encloses its arguments in square brackets.
1.65 kristaps 1435: .Pp
1436: Examples:
1.173 kristaps 1437: .Dl \&.Bq 1 , \&Dv BUFSIZ
1.65 kristaps 1438: .Pp
1439: .Em Remarks :
1440: this macro is sometimes abused to emulate optional arguments for
1441: commands; the correct macros to use for this purpose are
1442: .Sx \&Op ,
1443: .Sx \&Oo ,
1444: and
1445: .Sx \&Oc .
1446: .Pp
1447: See also
1448: .Sx \&Bo .
1.63 kristaps 1449: .Ss \&Brc
1.141 kristaps 1450: Close a
1.65 kristaps 1451: .Sx \&Bro
1.138 kristaps 1452: block.
1453: Does not have any tail arguments.
1.63 kristaps 1454: .Ss \&Bro
1.141 kristaps 1455: Begin a block enclosed by curly braces.
1.100 kristaps 1456: Does not have any head arguments.
1.65 kristaps 1457: .Pp
1458: Examples:
1.140 kristaps 1459: .Bd -literal -offset indent -compact
1.65 kristaps 1460: \&.Bro 1 , ... ,
1.91 kristaps 1461: \&.Va n \&Brc
1.65 kristaps 1462: .Ed
1463: .Pp
1464: See also
1465: .Sx \&Brq .
1.63 kristaps 1466: .Ss \&Brq
1.65 kristaps 1467: Encloses its arguments in curly braces.
1468: .Pp
1469: Examples:
1.173 kristaps 1470: .Dl \&.Brq 1 , ... , \&Va n
1.65 kristaps 1471: .Pp
1472: See also
1473: .Sx \&Bro .
1.63 kristaps 1474: .Ss \&Bsx
1.65 kristaps 1475: Format the BSD/OS version provided as an argument, or a default value if
1476: no argument is provided.
1477: .Pp
1478: Examples:
1.173 kristaps 1479: .Dl \&.Bsx 1.0
1480: .Dl \&.Bsx
1.65 kristaps 1481: .Pp
1482: See also
1483: .Sx \&At ,
1484: .Sx \&Bx ,
1.66 kristaps 1485: .Sx \&Dx ,
1.65 kristaps 1486: .Sx \&Fx ,
1487: .Sx \&Nx ,
1488: .Sx \&Ox ,
1489: and
1490: .Sx \&Ux .
1.63 kristaps 1491: .Ss \&Bt
1.66 kristaps 1492: Prints
1.144 schwarze 1493: .Dq is currently in beta test .
1.63 kristaps 1494: .Ss \&Bx
1.65 kristaps 1495: Format the BSD version provided as an argument, or a default value if no
1496: argument is provided.
1497: .Pp
1498: Examples:
1.173 kristaps 1499: .Dl \&.Bx 4.4
1500: .Dl \&.Bx
1.65 kristaps 1501: .Pp
1502: See also
1503: .Sx \&At ,
1504: .Sx \&Bsx ,
1.66 kristaps 1505: .Sx \&Dx ,
1.65 kristaps 1506: .Sx \&Fx ,
1507: .Sx \&Nx ,
1508: .Sx \&Ox ,
1509: and
1510: .Sx \&Ux .
1.63 kristaps 1511: .Ss \&Cd
1.141 kristaps 1512: Kernel configuration declaration.
1.100 kristaps 1513: This denotes strings accepted by
1.66 kristaps 1514: .Xr config 8 .
1515: .Pp
1516: Examples:
1.173 kristaps 1517: .Dl \&.Cd device le0 at scode?
1.66 kristaps 1518: .Pp
1519: .Em Remarks :
1520: this macro is commonly abused by using quoted literals to retain
1.138 kristaps 1521: whitespace and align consecutive
1.66 kristaps 1522: .Sx \&Cd
1.100 kristaps 1523: declarations.
1524: This practise is discouraged.
1.63 kristaps 1525: .Ss \&Cm
1.100 kristaps 1526: Command modifiers.
1527: Useful when specifying configuration options or keys.
1.66 kristaps 1528: .Pp
1529: Examples:
1.173 kristaps 1530: .Dl \&.Cm ControlPath
1531: .Dl \&.Cm ControlMaster
1.66 kristaps 1532: .Pp
1533: See also
1534: .Sx \&Fl .
1.63 kristaps 1535: .Ss \&D1
1.100 kristaps 1536: One-line indented display.
1537: This is formatted by the default rules and is useful for simple indented
1538: statements.
1539: It is followed by a newline.
1.66 kristaps 1540: .Pp
1541: Examples:
1.173 kristaps 1542: .Dl \&.D1 \&Fl abcdefgh
1.66 kristaps 1543: .Pp
1544: See also
1545: .Sx \&Bd
1546: and
1547: .Sx \&Dl .
1.63 kristaps 1548: .Ss \&Db
1.141 kristaps 1549: Switch debugging mode.
1.120 kristaps 1550: Its syntax is as follows:
1.117 kristaps 1551: .Pp
1.120 kristaps 1552: .D1 Pf \. Sx \&Db Cm on | off
1.141 kristaps 1553: .Pp
1554: This macro is ignored by
1555: .Xr mandoc 1 .
1.63 kristaps 1556: .Ss \&Dc
1.141 kristaps 1557: Close a
1.66 kristaps 1558: .Sx \&Do
1.138 kristaps 1559: block.
1560: Does not have any tail arguments.
1.63 kristaps 1561: .Ss \&Dd
1.100 kristaps 1562: Document date.
1563: This is the mandatory first macro of any
1.66 kristaps 1564: .Nm
1.100 kristaps 1565: manual.
1.120 kristaps 1566: Its syntax is as follows:
1.66 kristaps 1567: .Pp
1.181 schwarze 1568: .D1 Pf \. Sx \&Dd Ar month day , year
1.66 kristaps 1569: .Pp
1.82 kristaps 1570: The
1.181 schwarze 1571: .Ar month
1572: is the full English month name, the
1573: .Ar day
1574: is an optionally zero-padded numeral, and the
1575: .Ar year
1576: is the full four-digit year.
1577: .Pp
1578: Other arguments are not portable; the
1579: .Xr mandoc 1
1580: utility handles them as follows:
1581: .Bl -dash -offset 3n -compact
1582: .It
1583: To have the date automatically filled in by the
1584: .Ox
1585: version of
1.72 kristaps 1586: .Xr cvs 1 ,
1.181 schwarze 1587: the special string
1588: .Dq $\&Mdocdate$
1589: can be given as an argument.
1590: .It
1591: A few alternative date formats are accepted as well
1592: and converted to the standard form.
1593: .It
1594: If a date string cannot be parsed, it is used verbatim.
1595: .It
1596: If no date string is given, the current date is used.
1597: .El
1.66 kristaps 1598: .Pp
1599: Examples:
1.173 kristaps 1600: .Dl \&.Dd $\&Mdocdate$
1601: .Dl \&.Dd $\&Mdocdate: July 21 2007$
1602: .Dl \&.Dd July 21, 2007
1.66 kristaps 1603: .Pp
1604: See also
1605: .Sx \&Dt
1606: and
1607: .Sx \&Os .
1.63 kristaps 1608: .Ss \&Dl
1.100 kristaps 1609: One-line intended display.
1610: This is formatted as literal text and is useful for commands and
1611: invocations.
1612: It is followed by a newline.
1.66 kristaps 1613: .Pp
1614: Examples:
1.173 kristaps 1615: .Dl \&.Dl % mandoc mdoc.7 \e(ba less
1.66 kristaps 1616: .Pp
1617: See also
1618: .Sx \&Bd
1619: and
1620: .Sx \&D1 .
1.63 kristaps 1621: .Ss \&Do
1.141 kristaps 1622: Begin a block enclosed by double quotes.
1.138 kristaps 1623: Does not have any head arguments.
1.66 kristaps 1624: .Pp
1625: Examples:
1.140 kristaps 1626: .Bd -literal -offset indent -compact
1627: \&.Do
1628: April is the cruellest month
1629: \&.Dc
1630: \e(em T.S. Eliot
1631: .Ed
1.66 kristaps 1632: .Pp
1633: See also
1634: .Sx \&Dq .
1.63 kristaps 1635: .Ss \&Dq
1.138 kristaps 1636: Encloses its arguments in
1637: .Dq typographic
1638: double-quotes.
1.66 kristaps 1639: .Pp
1640: Examples:
1.91 kristaps 1641: .Bd -literal -offset indent -compact
1.66 kristaps 1642: \&.Dq April is the cruellest month
1643: \e(em T.S. Eliot
1644: .Ed
1645: .Pp
1646: See also
1.139 kristaps 1647: .Sx \&Qq ,
1648: .Sx \&Sq ,
1.138 kristaps 1649: and
1.66 kristaps 1650: .Sx \&Do .
1.139 kristaps 1651: .Ss \&Dt
1.100 kristaps 1652: Document title.
1653: This is the mandatory second macro of any
1.66 kristaps 1654: .Nm
1.100 kristaps 1655: file.
1.120 kristaps 1656: Its syntax is as follows:
1657: .Bd -ragged -offset indent
1658: .Pf \. Sx \&Dt
1659: .Oo
1.141 kristaps 1660: .Ar title
1.120 kristaps 1661: .Oo
1.141 kristaps 1662: .Ar section
1663: .Op Ar volume | arch
1.120 kristaps 1664: .Oc
1665: .Oc
1666: .Ed
1.66 kristaps 1667: .Pp
1668: Its arguments are as follows:
1669: .Bl -tag -width Ds -offset Ds
1.141 kristaps 1670: .It Ar title
1.111 kristaps 1671: The document's title (name), defaulting to
1.138 kristaps 1672: .Dq UNKNOWN
1.111 kristaps 1673: if unspecified.
1674: It should be capitalised.
1.141 kristaps 1675: .It Ar section
1.100 kristaps 1676: The manual section.
1677: This may be one of
1.66 kristaps 1678: .Ar 1
1679: .Pq utilities ,
1680: .Ar 2
1681: .Pq system calls ,
1682: .Ar 3
1683: .Pq libraries ,
1684: .Ar 3p
1685: .Pq Perl libraries ,
1686: .Ar 4
1687: .Pq devices ,
1688: .Ar 5
1689: .Pq file formats ,
1690: .Ar 6
1691: .Pq games ,
1692: .Ar 7
1693: .Pq miscellaneous ,
1694: .Ar 8
1695: .Pq system utilities ,
1696: .Ar 9
1697: .Pq kernel functions ,
1698: .Ar X11
1699: .Pq X Window System ,
1700: .Ar X11R6
1701: .Pq X Window System ,
1702: .Ar unass
1703: .Pq unassociated ,
1704: .Ar local
1705: .Pq local system ,
1706: .Ar draft
1707: .Pq draft manual ,
1708: or
1709: .Ar paper
1710: .Pq paper .
1.111 kristaps 1711: It should correspond to the manual's filename suffix and defaults to
1.138 kristaps 1712: .Dq 1
1.111 kristaps 1713: if unspecified.
1.141 kristaps 1714: .It Ar volume
1.66 kristaps 1715: This overrides the volume inferred from
1716: .Ar section .
1717: This field is optional, and if specified, must be one of
1718: .Ar USD
1719: .Pq users' supplementary documents ,
1720: .Ar PS1
1721: .Pq programmers' supplementary documents ,
1722: .Ar AMD
1723: .Pq administrators' supplementary documents ,
1724: .Ar SMM
1725: .Pq system managers' manuals ,
1726: .Ar URM
1727: .Pq users' reference manuals ,
1728: .Ar PRM
1729: .Pq programmers' reference manuals ,
1730: .Ar KM
1731: .Pq kernel manuals ,
1732: .Ar IND
1733: .Pq master index ,
1734: .Ar MMI
1735: .Pq master index ,
1736: .Ar LOCAL
1737: .Pq local manuals ,
1738: .Ar LOC
1739: .Pq local manuals ,
1740: or
1741: .Ar CON
1742: .Pq contributed manuals .
1.141 kristaps 1743: .It Ar arch
1.100 kristaps 1744: This specifies a specific relevant architecture.
1745: If
1.141 kristaps 1746: .Ar volume
1.66 kristaps 1747: is not provided, it may be used in its place, else it may be used
1.100 kristaps 1748: subsequent that.
1749: It, too, is optional.
1750: It must be one of
1.66 kristaps 1751: .Ar alpha ,
1752: .Ar amd64 ,
1753: .Ar amiga ,
1754: .Ar arc ,
1755: .Ar arm ,
1756: .Ar armish ,
1757: .Ar aviion ,
1758: .Ar hp300 ,
1759: .Ar hppa ,
1760: .Ar hppa64 ,
1761: .Ar i386 ,
1762: .Ar landisk ,
1.86 kristaps 1763: .Ar loongson ,
1.66 kristaps 1764: .Ar luna88k ,
1765: .Ar mac68k ,
1766: .Ar macppc ,
1.160 kristaps 1767: .Ar mips64 ,
1.66 kristaps 1768: .Ar mvme68k ,
1769: .Ar mvme88k ,
1770: .Ar mvmeppc ,
1771: .Ar pmax ,
1772: .Ar sgi ,
1773: .Ar socppc ,
1774: .Ar sparc ,
1775: .Ar sparc64 ,
1776: .Ar sun3 ,
1777: .Ar vax ,
1778: or
1779: .Ar zaurus .
1780: .El
1781: .Pp
1782: Examples:
1.173 kristaps 1783: .Dl \&.Dt FOO 1
1784: .Dl \&.Dt FOO 4 KM
1785: .Dl \&.Dt FOO 9 i386
1.66 kristaps 1786: .Pp
1787: See also
1788: .Sx \&Dd
1789: and
1790: .Sx \&Os .
1.63 kristaps 1791: .Ss \&Dv
1.189 kristaps 1792: Defined variables such as preprocessor constants, constant symbols,
1793: enumeration values, and so on.
1.66 kristaps 1794: .Pp
1795: Examples:
1.189 kristaps 1796: .Dl \&.Dv NULL
1.173 kristaps 1797: .Dl \&.Dv BUFSIZ
1798: .Dl \&.Dv STDOUT_FILENO
1.66 kristaps 1799: .Pp
1800: See also
1.189 kristaps 1801: .Sx \&Er
1802: and
1803: .Sx \&Ev
1804: for special-purpose constants and
1805: .Sx \&Va
1806: for variable symbols.
1.63 kristaps 1807: .Ss \&Dx
1.71 kristaps 1808: Format the DragonFly BSD version provided as an argument, or a default
1.66 kristaps 1809: value if no argument is provided.
1810: .Pp
1811: Examples:
1.173 kristaps 1812: .Dl \&.Dx 2.4.1
1813: .Dl \&.Dx
1.66 kristaps 1814: .Pp
1815: See also
1816: .Sx \&At ,
1817: .Sx \&Bsx ,
1818: .Sx \&Bx ,
1819: .Sx \&Fx ,
1820: .Sx \&Nx ,
1821: .Sx \&Ox ,
1822: and
1823: .Sx \&Ux .
1.63 kristaps 1824: .Ss \&Ec
1.131 kristaps 1825: Close a scope started by
1826: .Sx \&Eo .
1827: Its syntax is as follows:
1828: .Pp
1.141 kristaps 1829: .D1 Pf \. Sx \&Ec Op Ar TERM
1.131 kristaps 1830: .Pp
1831: The
1.141 kristaps 1832: .Ar TERM
1.131 kristaps 1833: argument is used as the enclosure tail, for example, specifying \e(rq
1834: will emulate
1835: .Sx \&Dc .
1.63 kristaps 1836: .Ss \&Ed
1.131 kristaps 1837: End a display context started by
1838: .Sx \&Bd .
1.63 kristaps 1839: .Ss \&Ef
1.141 kristaps 1840: End a font mode context started by
1.129 kristaps 1841: .Sx \&Bf .
1.63 kristaps 1842: .Ss \&Ek
1.141 kristaps 1843: End a keep context started by
1.127 schwarze 1844: .Sx \&Bk .
1.63 kristaps 1845: .Ss \&El
1.141 kristaps 1846: End a list context started by
1.117 kristaps 1847: .Sx \&Bl .
1848: .Pp
1849: See also
1850: .Sx \&Bl
1851: and
1852: .Sx \&It .
1.63 kristaps 1853: .Ss \&Em
1.100 kristaps 1854: Denotes text that should be emphasised.
1855: Note that this is a presentation term and should not be used for
1856: stylistically decorating technical terms.
1.66 kristaps 1857: .Pp
1858: Examples:
1.173 kristaps 1859: .Dl \&.Em Warnings!
1860: .Dl \&.Em Remarks :
1.138 kristaps 1861: .Pp
1862: See also
1863: .Sx \&Bf ,
1864: .Sx \&Sy ,
1865: and
1866: .Sx \&Li .
1.63 kristaps 1867: .Ss \&En
1.141 kristaps 1868: This macro is obsolete and not implemented in
1869: .Xr mandoc 1 .
1.63 kristaps 1870: .Ss \&Eo
1.131 kristaps 1871: An arbitrary enclosure.
1872: Its syntax is as follows:
1873: .Pp
1.141 kristaps 1874: .D1 Pf \. Sx \&Eo Op Ar TERM
1.131 kristaps 1875: .Pp
1876: The
1.141 kristaps 1877: .Ar TERM
1.131 kristaps 1878: argument is used as the enclosure head, for example, specifying \e(lq
1879: will emulate
1880: .Sx \&Do .
1.63 kristaps 1881: .Ss \&Er
1.189 kristaps 1882: Error constants for definitions of the
1883: .Va errno
1884: libc global variable.
1.66 kristaps 1885: .Pp
1886: Examples:
1.173 kristaps 1887: .Dl \&.Er EPERM
1888: .Dl \&.Er ENOENT
1.66 kristaps 1889: .Pp
1890: See also
1.189 kristaps 1891: .Sx \&Dv
1892: for general constants.
1.63 kristaps 1893: .Ss \&Es
1.132 kristaps 1894: This macro is obsolete and not implemented.
1.63 kristaps 1895: .Ss \&Ev
1.66 kristaps 1896: Environmental variables such as those specified in
1897: .Xr environ 7 .
1898: .Pp
1899: Examples:
1.173 kristaps 1900: .Dl \&.Ev DISPLAY
1901: .Dl \&.Ev PATH
1.189 kristaps 1902: .Pp
1903: See also
1904: .Sx \&Dv
1905: for general constants.
1.63 kristaps 1906: .Ss \&Ex
1.191 kristaps 1907: Insert a standard sentence regarding command exit values of 0 on success
1908: and >0 on failure.
1.141 kristaps 1909: Its syntax is as follows:
1910: .Pp
1.193 schwarze 1911: .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1.141 kristaps 1912: .Pp
1.191 kristaps 1913: If
1.66 kristaps 1914: .Ar utility
1.141 kristaps 1915: is not specified, the document's name set by
1.66 kristaps 1916: .Sx \&Nm
1.141 kristaps 1917: is used.
1.191 kristaps 1918: Multiple
1919: .Ar utility
1920: arguments are treated as separate utilities.
1.139 kristaps 1921: .Pp
1922: See also
1923: .Sx \&Rv .
1.63 kristaps 1924: .Ss \&Fa
1.117 kristaps 1925: Function argument.
1.120 kristaps 1926: Its syntax is as follows:
1927: .Bd -ragged -offset indent
1928: .Pf \. Sx \&Fa
1929: .Op Cm argtype
1930: .Cm argname
1931: .Ed
1932: .Pp
1.117 kristaps 1933: This may be invoked for names with or without the corresponding type.
1934: It is also used to specify the field name of a structure.
1935: Most often, the
1936: .Sx \&Fa
1937: macro is used in the
1938: .Em SYNOPSIS
1.120 kristaps 1939: within
1940: .Sx \&Fo
1.117 kristaps 1941: section when documenting multi-line function prototypes.
1942: If invoked with multiple arguments, the arguments are separated by a
1943: comma.
1944: Furthermore, if the following macro is another
1945: .Sx \&Fa ,
1946: the last argument will also have a trailing comma.
1947: .Pp
1948: Examples:
1.173 kristaps 1949: .Dl \&.Fa \(dqconst char *p\(dq
1950: .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1951: .Dl \&.Fa foo
1.120 kristaps 1952: .Pp
1953: See also
1954: .Sx \&Fo .
1.63 kristaps 1955: .Ss \&Fc
1.141 kristaps 1956: End a function context started by
1.131 kristaps 1957: .Sx \&Fo .
1.63 kristaps 1958: .Ss \&Fd
1.117 kristaps 1959: Historically used to document include files.
1960: This usage has been deprecated in favour of
1961: .Sx \&In .
1962: Do not use this macro.
1963: .Pp
1964: See also
1.122 kristaps 1965: .Sx MANUAL STRUCTURE
1966: and
1.117 kristaps 1967: .Sx \&In .
1.63 kristaps 1968: .Ss \&Fl
1.100 kristaps 1969: Command-line flag.
1970: Used when listing arguments to command-line utilities.
1971: Prints a fixed-width hyphen
1.79 kristaps 1972: .Sq \-
1.100 kristaps 1973: directly followed by each argument.
1974: If no arguments are provided, a hyphen is printed followed by a space.
1975: If the argument is a macro, a hyphen is prefixed to the subsequent macro
1976: output.
1.79 kristaps 1977: .Pp
1978: Examples:
1.173 kristaps 1979: .Dl \&.Fl a b c
1980: .Dl \&.Fl \&Pf a b
1981: .Dl \&.Fl
1982: .Dl \&.Op \&Fl o \&Ns \&Ar file
1.79 kristaps 1983: .Pp
1984: See also
1985: .Sx \&Cm .
1.63 kristaps 1986: .Ss \&Fn
1.119 kristaps 1987: A function name.
1.120 kristaps 1988: Its syntax is as follows:
1.119 kristaps 1989: .Bd -ragged -offset indent
1990: .Pf \. Ns Sx \&Fn
1.185 kristaps 1991: .Op Ar functype
1992: .Ar funcname
1993: .Op Oo Ar argtype Oc Ar argname
1.119 kristaps 1994: .Ed
1.120 kristaps 1995: .Pp
1.122 kristaps 1996: Function arguments are surrounded in parenthesis and
1.119 kristaps 1997: are delimited by commas.
1998: If no arguments are specified, blank parenthesis are output.
1999: .Pp
2000: Examples:
1.183 kristaps 2001: .Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q
2002: .Dl \&.Fn funcname \*qint arg0\*q
1.173 kristaps 2003: .Dl \&.Fn funcname arg0
1.120 kristaps 2004: .Bd -literal -offset indent -compact
2005: \&.Ft functype
2006: \&.Fn funcname
2007: .Ed
1.119 kristaps 2008: .Pp
1.163 schwarze 2009: When referring to a function documented in another manual page, use
1.162 schwarze 2010: .Sx \&Xr
1.163 schwarze 2011: instead.
1.119 kristaps 2012: See also
1.122 kristaps 2013: .Sx MANUAL STRUCTURE
1.119 kristaps 2014: and
2015: .Sx \&Ft .
1.63 kristaps 2016: .Ss \&Fo
1.120 kristaps 2017: Begin a function block.
2018: This is a multi-line version of
2019: .Sx \&Fn .
2020: Its syntax is as follows:
2021: .Pp
1.185 kristaps 2022: .D1 Pf \. Sx \&Fo Ar funcname
1.120 kristaps 2023: .Pp
2024: Invocations usually occur in the following context:
2025: .Bd -ragged -offset indent
1.185 kristaps 2026: .Pf \. Sx \&Ft Ar functype
1.120 kristaps 2027: .br
1.185 kristaps 2028: .Pf \. Sx \&Fo Ar funcname
1.120 kristaps 2029: .br
1.185 kristaps 2030: .Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
1.120 kristaps 2031: .br
1.183 kristaps 2032: \&.\.\.
1.120 kristaps 2033: .br
2034: .Pf \. Sx \&Fc
2035: .Ed
2036: .Pp
2037: A
2038: .Sx \&Fo
2039: scope is closed by
2040: .Pp
2041: See also
1.122 kristaps 2042: .Sx MANUAL STRUCTURE ,
1.120 kristaps 2043: .Sx \&Fa ,
2044: .Sx \&Fc ,
2045: and
1.139 kristaps 2046: .Sx \&Ft .
1.190 schwarze 2047: .Ss \&Fr
2048: This macro is obsolete and not implemented.
1.63 kristaps 2049: .Ss \&Ft
1.120 kristaps 2050: A function type.
2051: Its syntax is as follows:
2052: .Pp
1.185 kristaps 2053: .D1 Pf \. Sx \&Ft Ar functype
1.120 kristaps 2054: .Pp
2055: Examples:
1.173 kristaps 2056: .Dl \&.Ft int
1.120 kristaps 2057: .Bd -literal -offset indent -compact
2058: \&.Ft functype
2059: \&.Fn funcname
2060: .Ed
2061: .Pp
2062: See also
1.122 kristaps 2063: .Sx MANUAL STRUCTURE ,
2064: .Sx \&Fn ,
1.120 kristaps 2065: and
1.122 kristaps 2066: .Sx \&Fo .
1.63 kristaps 2067: .Ss \&Fx
1.144 schwarze 2068: Format the
2069: .Fx
2070: version provided as an argument, or a default value
1.65 kristaps 2071: if no argument is provided.
2072: .Pp
2073: Examples:
1.173 kristaps 2074: .Dl \&.Fx 7.1
2075: .Dl \&.Fx
1.65 kristaps 2076: .Pp
2077: See also
2078: .Sx \&At ,
1.66 kristaps 2079: .Sx \&Bsx ,
1.65 kristaps 2080: .Sx \&Bx ,
1.66 kristaps 2081: .Sx \&Dx ,
1.65 kristaps 2082: .Sx \&Nx ,
2083: .Sx \&Ox ,
2084: and
2085: .Sx \&Ux .
1.63 kristaps 2086: .Ss \&Hf
1.132 kristaps 2087: This macro is obsolete and not implemented.
1.63 kristaps 2088: .Ss \&Ic
1.132 kristaps 2089: Designate an internal or interactive command.
2090: This is similar to
2091: .Sx \&Cm
2092: but used for instructions rather than values.
2093: .Pp
2094: Examples:
1.173 kristaps 2095: .Dl \&.Ic hash
2096: .Dl \&.Ic alias
1.132 kristaps 2097: .Pp
2098: Note that using
1.144 schwarze 2099: .Sx \&Bd Fl literal
1.132 kristaps 2100: or
2101: .Sx \&D1
2102: is preferred for displaying code; the
2103: .Sx \&Ic
2104: macro is used when referring to specific instructions.
1.63 kristaps 2105: .Ss \&In
1.118 kristaps 2106: An
1.138 kristaps 2107: .Dq include
1.118 kristaps 2108: file.
2109: In the
2110: .Em SYNOPSIS
2111: section (only if invoked as the line macro), the first argument is
2112: preceded by
1.138 kristaps 2113: .Dq #include ,
1.141 kristaps 2114: the arguments is enclosed in angle brackets.
1.118 kristaps 2115: .Pp
1.122 kristaps 2116: Examples:
1.173 kristaps 2117: .Dl \&.In sys/types
1.122 kristaps 2118: .Pp
2119: See also
2120: .Sx MANUAL STRUCTURE .
1.63 kristaps 2121: .Ss \&It
1.120 kristaps 2122: A list item.
2123: The syntax of this macro depends on the list type.
1.114 kristaps 2124: .Pp
2125: Lists
2126: of type
2127: .Fl hang ,
2128: .Fl ohang ,
2129: .Fl inset ,
2130: and
2131: .Fl diag
1.120 kristaps 2132: have the following syntax:
1.114 kristaps 2133: .Pp
1.185 kristaps 2134: .D1 Pf \. Sx \&It Ar args
1.114 kristaps 2135: .Pp
2136: Lists of type
2137: .Fl bullet ,
2138: .Fl dash ,
2139: .Fl enum ,
2140: .Fl hyphen
2141: and
2142: .Fl item
1.120 kristaps 2143: have the following syntax:
1.114 kristaps 2144: .Pp
1.120 kristaps 2145: .D1 Pf \. Sx \&It
1.114 kristaps 2146: .Pp
2147: with subsequent lines interpreted within the scope of the
2148: .Sx \&It
2149: until either a closing
2150: .Sx \&El
2151: or another
2152: .Sx \&It .
2153: .Pp
2154: The
2155: .Fl tag
1.120 kristaps 2156: list has the following syntax:
1.114 kristaps 2157: .Pp
1.120 kristaps 2158: .D1 Pf \. Sx \&It Op Cm args
1.114 kristaps 2159: .Pp
1.120 kristaps 2160: Subsequent lines are interpreted as with
1.114 kristaps 2161: .Fl bullet
2162: and family.
2163: The line arguments correspond to the list's left-hand side; body
2164: arguments correspond to the list's contents.
2165: .Pp
2166: The
2167: .Fl column
2168: list is the most complicated.
1.120 kristaps 2169: Its syntax is as follows:
1.114 kristaps 2170: .Pp
1.190 schwarze 2171: .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
2172: .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
1.114 kristaps 2173: .Pp
1.190 schwarze 2174: The arguments consist of one or more lines of text and macros
2175: representing a complete table line.
2176: Cells within the line are delimited by tabs or by the special
2177: .Sx \&Ta
2178: block macro.
2179: The tab cell delimiter may only be used within the
1.114 kristaps 2180: .Sx \&It
1.190 schwarze 2181: line itself; on following lines, only the
2182: .Sx \&Ta
2183: macro can be used to delimit cells, and
2184: .Sx \&Ta
2185: is only recognized as a macro when called by other macros,
2186: not as the first macro on a line.
2187: .Pp
2188: Note that quoted strings may span tab-delimited cells on an
1.114 kristaps 2189: .Sx \&It
1.190 schwarze 2190: line.
2191: For example,
1.114 kristaps 2192: .Pp
1.173 kristaps 2193: .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
1.114 kristaps 2194: .Pp
2195: will preserve the semicolon whitespace except for the last.
2196: .Pp
2197: See also
2198: .Sx \&Bl .
1.63 kristaps 2199: .Ss \&Lb
1.109 kristaps 2200: Specify a library.
1.120 kristaps 2201: The syntax is as follows:
1.109 kristaps 2202: .Pp
1.185 kristaps 2203: .D1 Pf \. Sx \&Lb Ar library
1.109 kristaps 2204: .Pp
2205: The
1.185 kristaps 2206: .Ar library
1.109 kristaps 2207: parameter may be a system library, such as
1.193 schwarze 2208: .Cm libz
1.109 kristaps 2209: or
1.193 schwarze 2210: .Cm libpam ,
1.109 kristaps 2211: in which case a small library description is printed next to the linker
2212: invocation; or a custom library, in which case the library name is
2213: printed in quotes.
2214: This is most commonly used in the
2215: .Em SYNOPSIS
2216: section as described in
2217: .Sx MANUAL STRUCTURE .
2218: .Pp
2219: Examples:
1.173 kristaps 2220: .Dl \&.Lb libz
2221: .Dl \&.Lb mdoc
1.63 kristaps 2222: .Ss \&Li
1.131 kristaps 2223: Denotes text that should be in a literal font mode.
2224: Note that this is a presentation term and should not be used for
2225: stylistically decorating technical terms.
1.138 kristaps 2226: .Pp
2227: See also
2228: .Sx \&Bf ,
2229: .Sx \&Sy ,
2230: and
2231: .Sx \&Em .
1.63 kristaps 2232: .Ss \&Lk
1.100 kristaps 2233: Format a hyperlink.
1.120 kristaps 2234: Its syntax is as follows:
1.70 kristaps 2235: .Pp
1.185 kristaps 2236: .D1 Pf \. Sx \&Lk Ar uri Op Ar name
1.70 kristaps 2237: .Pp
2238: Examples:
1.173 kristaps 2239: .Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
2240: .Dl \&.Lk http://bsd.lv
1.70 kristaps 2241: .Pp
2242: See also
2243: .Sx \&Mt .
1.63 kristaps 2244: .Ss \&Lp
1.132 kristaps 2245: Synonym for
2246: .Sx \&Pp .
1.63 kristaps 2247: .Ss \&Ms
1.138 kristaps 2248: Display a mathematical symbol.
1.140 kristaps 2249: Its syntax is as follows:
2250: .Pp
1.185 kristaps 2251: .D1 Pf \. Sx \&Ms Ar symbol
1.138 kristaps 2252: .Pp
2253: Examples:
1.173 kristaps 2254: .Dl \&.Ms sigma
2255: .Dl \&.Ms aleph
1.63 kristaps 2256: .Ss \&Mt
1.116 kristaps 2257: Format a
1.138 kristaps 2258: .Dq mailto:
1.116 kristaps 2259: hyperlink.
1.120 kristaps 2260: Its syntax is as follows:
1.116 kristaps 2261: .Pp
1.185 kristaps 2262: .D1 Pf \. Sx \&Mt Ar address
1.116 kristaps 2263: .Pp
2264: Examples:
1.173 kristaps 2265: .Dl \&.Mt discuss@manpages.bsd.lv
1.63 kristaps 2266: .Ss \&Nd
1.144 schwarze 2267: A one line description of the manual's content.
1.132 kristaps 2268: This may only be invoked in the
2269: .Em SYNOPSIS
2270: section subsequent the
2271: .Sx \&Nm
2272: macro.
2273: .Pp
2274: Examples:
1.173 kristaps 2275: .Dl \&.Sx \&Nd mdoc language reference
2276: .Dl \&.Sx \&Nd format and display UNIX manuals
1.132 kristaps 2277: .Pp
2278: The
2279: .Sx \&Nd
2280: macro technically accepts child macros and terminates with a subsequent
2281: .Sx \&Sh
2282: invocation.
2283: Do not assume this behaviour: some
2284: .Xr whatis 1
2285: database generators are not smart enough to parse more than the line
2286: arguments and will display macros verbatim.
2287: .Pp
2288: See also
2289: .Sx \&Nm .
1.63 kristaps 2290: .Ss \&Nm
1.128 schwarze 2291: The name of the manual page, or \(em in particular in section 1, 6,
2292: and 8 pages \(em of an additional command or feature documented in
2293: the manual page.
2294: When first invoked, the
2295: .Sx \&Nm
2296: macro expects a single argument, the name of the manual page.
2297: Usually, the first invocation happens in the
2298: .Em NAME
2299: section of the page.
2300: The specified name will be remembered and used whenever the macro is
2301: called again without arguments later in the page.
2302: The
2303: .Sx \&Nm
2304: macro uses
2305: .Sx Block full-implicit
2306: semantics when invoked as the first macro on an input line in the
2307: .Em SYNOPSIS
2308: section; otherwise, it uses ordinary
2309: .Sx In-line
2310: semantics.
2311: .Pp
2312: Examples:
2313: .Bd -literal -offset indent
2314: \&.Sh SYNOPSIS
2315: \&.Nm cat
2316: \&.Op Fl benstuv
2317: \&.Op Ar
2318: .Ed
2319: .Pp
2320: In the
2321: .Em SYNOPSIS
2322: of section 2, 3 and 9 manual pages, use the
2323: .Sx \&Fn
2324: macro rather than
2325: .Sx \&Nm
2326: to mark up the name of the manual page.
1.63 kristaps 2327: .Ss \&No
1.132 kristaps 2328: A
1.138 kristaps 2329: .Dq noop
1.132 kristaps 2330: macro used to terminate prior macro contexts.
2331: .Pp
2332: Examples:
1.173 kristaps 2333: .Dl \&.Sx \&Fl ab \&No cd \&Fl ef
1.63 kristaps 2334: .Ss \&Ns
1.138 kristaps 2335: Suppress a space.
2336: Following invocation, text is interpreted as free-form text until a
2337: macro is encountered.
1.178 kristaps 2338: .Pp
2339: This has no effect when invoked at the start of a macro line.
1.138 kristaps 2340: .Pp
2341: Examples:
1.173 kristaps 2342: .Dl \&.Fl o \&Ns \&Ar output
1.138 kristaps 2343: .Pp
2344: See also
2345: .Sx \&No
2346: and
2347: .Sx \&Sm .
1.63 kristaps 2348: .Ss \&Nx
1.144 schwarze 2349: Format the
2350: .Nx
2351: version provided as an argument, or a default value if
1.65 kristaps 2352: no argument is provided.
2353: .Pp
2354: Examples:
1.173 kristaps 2355: .Dl \&.Nx 5.01
2356: .Dl \&.Nx
1.65 kristaps 2357: .Pp
2358: See also
2359: .Sx \&At ,
1.66 kristaps 2360: .Sx \&Bsx ,
1.65 kristaps 2361: .Sx \&Bx ,
1.66 kristaps 2362: .Sx \&Dx ,
1.65 kristaps 2363: .Sx \&Fx ,
2364: .Sx \&Ox ,
2365: and
2366: .Sx \&Ux .
1.63 kristaps 2367: .Ss \&Oc
1.141 kristaps 2368: Close multi-line
1.132 kristaps 2369: .Sx \&Oo
2370: context.
1.63 kristaps 2371: .Ss \&Oo
1.132 kristaps 2372: Multi-line version of
2373: .Sx \&Op .
2374: .Pp
2375: Examples:
1.138 kristaps 2376: .Bd -literal -offset indent -compact
1.132 kristaps 2377: \&.Oo
2378: \&.Op Fl flag Ns Ar value
2379: \&.Oc
2380: .Ed
1.63 kristaps 2381: .Ss \&Op
1.132 kristaps 2382: Command-line option.
2383: Used when listing options to command-line utilities.
2384: Prints the argument(s) in brackets.
2385: .Pp
2386: Examples:
1.173 kristaps 2387: .Dl \&.Op \&Fl a \&Ar b
2388: .Dl \&.Op \&Ar a | b
1.132 kristaps 2389: .Pp
2390: See also
2391: .Sx \&Oo .
1.63 kristaps 2392: .Ss \&Os
1.100 kristaps 2393: Document operating system version.
2394: This is the mandatory third macro of
1.66 kristaps 2395: any
2396: .Nm
1.120 kristaps 2397: file.
2398: Its syntax is as follows:
1.66 kristaps 2399: .Pp
1.185 kristaps 2400: .D1 Pf \. Sx \&Os Op Ar system Op Ar version
1.66 kristaps 2401: .Pp
2402: The optional
1.185 kristaps 2403: .Ar system
1.100 kristaps 2404: parameter specifies the relevant operating system or environment.
2405: Left unspecified, it defaults to the local operating system version.
2406: This is the suggested form.
1.66 kristaps 2407: .Pp
2408: Examples:
1.173 kristaps 2409: .Dl \&.Os
2410: .Dl \&.Os KTH/CSC/TCS
2411: .Dl \&.Os BSD 4.3
1.66 kristaps 2412: .Pp
2413: See also
2414: .Sx \&Dd
2415: and
2416: .Sx \&Dt .
1.63 kristaps 2417: .Ss \&Ot
1.66 kristaps 2418: Unknown usage.
2419: .Pp
2420: .Em Remarks :
2421: this macro has been deprecated.
1.63 kristaps 2422: .Ss \&Ox
1.144 schwarze 2423: Format the
2424: .Ox
2425: version provided as an argument, or a default value
1.65 kristaps 2426: if no argument is provided.
2427: .Pp
2428: Examples:
1.173 kristaps 2429: .Dl \&.Ox 4.5
2430: .Dl \&.Ox
1.65 kristaps 2431: .Pp
2432: See also
2433: .Sx \&At ,
2434: .Sx \&Bsx ,
2435: .Sx \&Bx ,
1.66 kristaps 2436: .Sx \&Dx ,
1.65 kristaps 2437: .Sx \&Fx ,
2438: .Sx \&Nx ,
2439: and
2440: .Sx \&Ux .
1.63 kristaps 2441: .Ss \&Pa
1.132 kristaps 2442: A file-system path.
1.165 kristaps 2443: If an argument is not provided, the string
2444: .Dq \(ti
2445: is used as a default.
1.132 kristaps 2446: .Pp
2447: Examples:
1.173 kristaps 2448: .Dl \&.Pa /usr/bin/mandoc
2449: .Dl \&.Pa /usr/share/man/man7/mdoc.7
1.132 kristaps 2450: .Pp
2451: See also
2452: .Sx \&Lk .
1.63 kristaps 2453: .Ss \&Pc
1.132 kristaps 2454: Close parenthesised context opened by
2455: .Sx \&Po .
1.63 kristaps 2456: .Ss \&Pf
1.132 kristaps 2457: Removes the space
1.138 kristaps 2458: .Pq Dq prefix
1.132 kristaps 2459: between its arguments.
2460: Its syntax is as follows:
2461: .Pp
1.185 kristaps 2462: .D1 Pf \. \&Pf Ar prefix suffix
1.132 kristaps 2463: .Pp
2464: The
1.185 kristaps 2465: .Ar suffix
1.132 kristaps 2466: argument may be a macro.
2467: .Pp
2468: Examples:
1.185 kristaps 2469: .Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix
1.63 kristaps 2470: .Ss \&Po
1.132 kristaps 2471: Multi-line version of
2472: .Sx \&Pq .
1.63 kristaps 2473: .Ss \&Pp
1.132 kristaps 2474: Break a paragraph.
2475: This will assert vertical space between prior and subsequent macros
2476: and/or text.
1.63 kristaps 2477: .Ss \&Pq
1.132 kristaps 2478: Parenthesised enclosure.
2479: .Pp
2480: See also
2481: .Sx \&Po .
1.63 kristaps 2482: .Ss \&Qc
1.138 kristaps 2483: Close quoted context opened by
2484: .Sx \&Qo .
1.63 kristaps 2485: .Ss \&Ql
1.138 kristaps 2486: Format a single-quoted literal.
2487: See also
2488: .Sx \&Qq
2489: and
2490: .Sx \&Sq .
1.63 kristaps 2491: .Ss \&Qo
1.138 kristaps 2492: Multi-line version of
2493: .Sx \&Qq .
1.63 kristaps 2494: .Ss \&Qq
1.138 kristaps 2495: Encloses its arguments in
2496: .Dq typewriter
2497: double-quotes.
2498: Consider using
2499: .Sx \&Dq .
2500: .Pp
2501: See also
2502: .Sx \&Dq ,
2503: .Sx \&Sq ,
2504: and
2505: .Sx \&Qo .
1.63 kristaps 2506: .Ss \&Re
1.141 kristaps 2507: Close an
1.63 kristaps 2508: .Sx \&Rs
1.100 kristaps 2509: block.
2510: Does not have any tail arguments.
1.63 kristaps 2511: .Ss \&Rs
1.141 kristaps 2512: Begin a bibliographic
1.63 kristaps 2513: .Pq Dq reference
1.100 kristaps 2514: block.
2515: Does not have any head arguments.
2516: The block macro may only contain
1.63 kristaps 2517: .Sx \&%A ,
2518: .Sx \&%B ,
2519: .Sx \&%C ,
2520: .Sx \&%D ,
2521: .Sx \&%I ,
2522: .Sx \&%J ,
2523: .Sx \&%N ,
2524: .Sx \&%O ,
2525: .Sx \&%P ,
2526: .Sx \&%Q ,
2527: .Sx \&%R ,
2528: .Sx \&%T ,
1.120 kristaps 2529: .Sx \&%U ,
1.63 kristaps 2530: and
2531: .Sx \&%V
2532: child macros (at least one must be specified).
2533: .Pp
1.64 kristaps 2534: Examples:
1.91 kristaps 2535: .Bd -literal -offset indent -compact
1.63 kristaps 2536: \&.Rs
2537: \&.%A J. E. Hopcroft
2538: \&.%A J. D. Ullman
2539: \&.%B Introduction to Automata Theory, Languages, and Computation
2540: \&.%I Addison-Wesley
2541: \&.%C Reading, Massachusettes
2542: \&.%D 1979
2543: \&.Re
2544: .Ed
2545: .Pp
2546: If an
2547: .Sx \&Rs
2548: block is used within a SEE ALSO section, a vertical space is asserted
2549: before the rendered output, else the block continues on the current
2550: line.
2551: .Ss \&Rv
1.193 schwarze 2552: Insert a standard sentence regarding a function call's return value of 0
1.191 kristaps 2553: on success and \-1 on error, with the
2554: .Va errno
2555: libc global variable set on error.
2556: Its syntax is as follows:
2557: .Pp
1.193 schwarze 2558: .D1 Pf \. Sx \&Rv Fl std Op Ar function ...
1.191 kristaps 2559: .Pp
1.139 kristaps 2560: If
2561: .Ar function
1.191 kristaps 2562: is not specified, the document's name set by
1.139 kristaps 2563: .Sx \&Nm
1.191 kristaps 2564: is used.
2565: Multiple
2566: .Ar function
2567: arguments are treated as separate functions.
1.139 kristaps 2568: .Pp
2569: See also
2570: .Sx \&Ex .
1.63 kristaps 2571: .Ss \&Sc
1.138 kristaps 2572: Close single-quoted context opened by
2573: .Sx \&So .
1.63 kristaps 2574: .Ss \&Sh
1.138 kristaps 2575: Begin a new section.
2576: For a list of conventional manual sections, see
2577: .Sx MANUAL STRUCTURE .
2578: These sections should be used unless it's absolutely necessary that
2579: custom sections be used.
2580: .Pp
2581: Section names should be unique so that they may be keyed by
2582: .Sx \&Sx .
2583: .Pp
2584: See also
2585: .Sx \&Pp ,
2586: .Sx \&Ss ,
2587: and
2588: .Sx \&Sx .
1.63 kristaps 2589: .Ss \&Sm
1.134 schwarze 2590: Switches the spacing mode for output generated from macros.
2591: Its syntax is as follows:
2592: .Pp
2593: .D1 Pf \. Sx \&Sm Cm on | off
2594: .Pp
2595: By default, spacing is
1.193 schwarze 2596: .Cm on .
1.134 schwarze 2597: When switched
1.193 schwarze 2598: .Cm off ,
1.134 schwarze 2599: no white space is inserted between macro arguments and between the
1.185 kristaps 2600: output generated from adjacent macros, but text lines
1.134 schwarze 2601: still get normal spacing between words and sentences.
1.63 kristaps 2602: .Ss \&So
1.138 kristaps 2603: Multi-line version of
2604: .Sx \&Sq .
1.63 kristaps 2605: .Ss \&Sq
1.138 kristaps 2606: Encloses its arguments in
2607: .Dq typewriter
2608: single-quotes.
2609: .Pp
2610: See also
2611: .Sx \&Dq ,
2612: .Sx \&Qq ,
2613: and
2614: .Sx \&So .
1.63 kristaps 2615: .Ss \&Ss
1.138 kristaps 2616: Begin a new sub-section.
2617: Unlike with
2618: .Sx \&Sh ,
2619: there's no convention for sub-sections.
2620: Conventional sections, as described in
2621: .Sx MANUAL STRUCTURE ,
2622: rarely have sub-sections.
2623: .Pp
2624: Sub-section names should be unique so that they may be keyed by
2625: .Sx \&Sx .
2626: .Pp
2627: See also
2628: .Sx \&Pp ,
2629: .Sx \&Sh ,
2630: and
2631: .Sx \&Sx .
1.63 kristaps 2632: .Ss \&St
1.139 kristaps 2633: Replace an abbreviation for a standard with the full form.
2634: The following standards are recognised:
2635: .Pp
2636: .Bl -tag -width "-p1003.1g-2000X" -compact
2637: .It \-p1003.1-88
2638: .St -p1003.1-88
2639: .It \-p1003.1-90
2640: .St -p1003.1-90
2641: .It \-p1003.1-96
2642: .St -p1003.1-96
2643: .It \-p1003.1-2001
2644: .St -p1003.1-2001
2645: .It \-p1003.1-2004
2646: .St -p1003.1-2004
2647: .It \-p1003.1-2008
2648: .St -p1003.1-2008
2649: .It \-p1003.1
2650: .St -p1003.1
2651: .It \-p1003.1b
2652: .St -p1003.1b
2653: .It \-p1003.1b-93
2654: .St -p1003.1b-93
2655: .It \-p1003.1c-95
2656: .St -p1003.1c-95
2657: .It \-p1003.1g-2000
2658: .St -p1003.1g-2000
2659: .It \-p1003.1i-95
2660: .St -p1003.1i-95
2661: .It \-p1003.2-92
2662: .St -p1003.2-92
2663: .It \-p1003.2a-92
2664: .St -p1003.2a-92
2665: .It \-p1387.2-95
2666: .St -p1387.2-95
2667: .It \-p1003.2
2668: .St -p1003.2
2669: .It \-p1387.2
2670: .St -p1387.2
2671: .It \-isoC
2672: .St -isoC
2673: .It \-isoC-90
2674: .St -isoC-90
2675: .It \-isoC-amd1
2676: .St -isoC-amd1
2677: .It \-isoC-tcor1
2678: .St -isoC-tcor1
2679: .It \-isoC-tcor2
2680: .St -isoC-tcor2
2681: .It \-isoC-99
2682: .St -isoC-99
2683: .It \-iso9945-1-90
2684: .St -iso9945-1-90
2685: .It \-iso9945-1-96
2686: .St -iso9945-1-96
2687: .It \-iso9945-2-93
2688: .St -iso9945-2-93
2689: .It \-ansiC
2690: .St -ansiC
2691: .It \-ansiC-89
2692: .St -ansiC-89
2693: .It \-ansiC-99
2694: .St -ansiC-99
2695: .It \-ieee754
2696: .St -ieee754
2697: .It \-iso8802-3
2698: .St -iso8802-3
2699: .It \-ieee1275-94
2700: .St -ieee1275-94
2701: .It \-xpg3
2702: .St -xpg3
2703: .It \-xpg4
2704: .St -xpg4
2705: .It \-xpg4.2
2706: .St -xpg4.2
2707: .St -xpg4.3
2708: .It \-xbd5
2709: .St -xbd5
2710: .It \-xcu5
2711: .St -xcu5
2712: .It \-xsh5
2713: .St -xsh5
2714: .It \-xns5
2715: .St -xns5
2716: .It \-xns5.2
2717: .St -xns5.2
2718: .It \-xns5.2d2.0
2719: .St -xns5.2d2.0
2720: .It \-xcurses4.2
2721: .St -xcurses4.2
2722: .It \-susv2
2723: .St -susv2
2724: .It \-susv3
2725: .St -susv3
2726: .It \-svid4
2727: .St -svid4
2728: .El
1.63 kristaps 2729: .Ss \&Sx
1.138 kristaps 2730: Reference a section or sub-section.
2731: The referenced section or sub-section name must be identical to the
2732: enclosed argument, including whitespace.
2733: .Pp
2734: Examples:
1.173 kristaps 2735: .Dl \&.Sx MANUAL STRUCTURE
1.172 kristaps 2736: .Pp
2737: See also
2738: .Sx \&Sh
2739: and
2740: .Sx \&Ss .
1.63 kristaps 2741: .Ss \&Sy
1.138 kristaps 2742: Format enclosed arguments in symbolic
2743: .Pq Dq boldface .
2744: Note that this is a presentation term and should not be used for
2745: stylistically decorating technical terms.
2746: .Pp
2747: See also
2748: .Sx \&Bf ,
2749: .Sx \&Li ,
2750: and
2751: .Sx \&Em .
1.190 schwarze 2752: .Ss \&Ta
2753: Table cell separator in
2754: .Sx \&Bl Fl column
2755: lists; can only be used below
2756: .Sx \&It .
1.63 kristaps 2757: .Ss \&Tn
1.138 kristaps 2758: Format a tradename.
2759: .Pp
2760: Examples:
1.173 kristaps 2761: .Dl \&.Tn IBM
1.63 kristaps 2762: .Ss \&Ud
1.110 kristaps 2763: Prints out
1.144 schwarze 2764: .Dq currently under development .
1.63 kristaps 2765: .Ss \&Ux
1.100 kristaps 2766: Format the UNIX name.
2767: Accepts no argument.
1.65 kristaps 2768: .Pp
2769: Examples:
1.173 kristaps 2770: .Dl \&.Ux
1.65 kristaps 2771: .Pp
2772: See also
2773: .Sx \&At ,
1.66 kristaps 2774: .Sx \&Bsx ,
1.65 kristaps 2775: .Sx \&Bx ,
1.66 kristaps 2776: .Sx \&Dx ,
1.65 kristaps 2777: .Sx \&Fx ,
2778: .Sx \&Nx ,
2779: and
2780: .Sx \&Ox .
1.63 kristaps 2781: .Ss \&Va
1.132 kristaps 2782: A variable name.
2783: .Pp
2784: Examples:
1.173 kristaps 2785: .Dl \&.Va foo
2786: .Dl \&.Va const char *bar ;
1.63 kristaps 2787: .Ss \&Vt
1.100 kristaps 2788: A variable type.
1.122 kristaps 2789: This is also used for indicating global variables in the
2790: .Em SYNOPSIS
1.100 kristaps 2791: section, in which case a variable name is also specified.
2792: Note that it accepts
1.83 kristaps 2793: .Sx Block partial-implicit
1.123 kristaps 2794: syntax when invoked as the first macro in the
1.122 kristaps 2795: .Em SYNOPSIS
2796: section, else it accepts ordinary
1.83 kristaps 2797: .Sx In-line
2798: syntax.
2799: .Pp
2800: Note that this should not be confused with
2801: .Sx \&Ft ,
2802: which is used for function return types.
2803: .Pp
2804: Examples:
1.173 kristaps 2805: .Dl \&.Vt unsigned char
2806: .Dl \&.Vt extern const char * const sys_signame[] \&;
1.83 kristaps 2807: .Pp
2808: See also
1.122 kristaps 2809: .Sx MANUAL STRUCTURE
1.83 kristaps 2810: and
2811: .Sx \&Va .
1.84 kristaps 2812: .Ss \&Xc
1.87 kristaps 2813: Close a scope opened by
2814: .Sx \&Xo .
1.84 kristaps 2815: .Ss \&Xo
1.170 schwarze 2816: Extend the header of an
2817: .Sx \&It
2818: macro or the body of a partial-implicit block macro
2819: beyond the end of the input line.
2820: This macro originally existed to work around the 9-argument limit
2821: of historic
2822: .Xr roff 7 .
1.84 kristaps 2823: .Ss \&Xr
2824: Link to another manual
2825: .Pq Qq cross-reference .
1.120 kristaps 2826: Its syntax is as follows:
1.84 kristaps 2827: .Pp
1.185 kristaps 2828: .D1 Pf \. Sx \&Xr Ar name section
1.84 kristaps 2829: .Pp
2830: The
1.185 kristaps 2831: .Ar name
1.84 kristaps 2832: and
1.185 kristaps 2833: .Ar section
1.100 kristaps 2834: are the name and section of the linked manual.
2835: If
1.185 kristaps 2836: .Ar section
1.84 kristaps 2837: is followed by non-punctuation, an
2838: .Sx \&Ns
1.100 kristaps 2839: is inserted into the token stream.
2840: This behaviour is for compatibility with
1.148 kristaps 2841: GNU troff.
1.84 kristaps 2842: .Pp
2843: Examples:
1.173 kristaps 2844: .Dl \&.Xr mandoc 1
2845: .Dl \&.Xr mandoc 1 \&;
2846: .Dl \&.Xr mandoc 1 \&Ns s behaviour
1.84 kristaps 2847: .Ss \&br
1.140 kristaps 2848: Emits a line-break.
2849: This macro should not be used; it is implemented for compatibility with
2850: historical manuals.
2851: .Pp
2852: Consider using
2853: .Sx \&Pp
2854: in the event of natural paragraph breaks.
1.84 kristaps 2855: .Ss \&sp
1.140 kristaps 2856: Emits vertical space.
2857: This macro should not be used; it is implemented for compatibility with
2858: historical manuals.
2859: Its syntax is as follows:
2860: .Pp
1.185 kristaps 2861: .D1 Pf \. Sx \&sp Op Ar height
1.140 kristaps 2862: .Pp
2863: The
1.185 kristaps 2864: .Ar height
1.140 kristaps 2865: argument must be formatted as described in
2866: .Sx Scaling Widths .
2867: If unspecified,
2868: .Sx \&sp
2869: asserts a single vertical space.
1.4 kristaps 2870: .Sh COMPATIBILITY
1.93 kristaps 2871: This section documents compatibility between mandoc and other other
2872: troff implementations, at this time limited to GNU troff
2873: .Pq Qq groff .
1.50 kristaps 2874: The term
1.57 kristaps 2875: .Qq historic groff
1.166 schwarze 2876: refers to groff versions before 1.17,
2877: which featured a significant update of the
1.57 kristaps 2878: .Pa doc.tmac
1.166 schwarze 2879: file.
1.57 kristaps 2880: .Pp
1.93 kristaps 2881: Heirloom troff, the other significant troff implementation accepting
2882: \-mdoc, is similar to historic groff.
2883: .Pp
1.150 kristaps 2884: The following problematic behaviour is found in groff:
2885: .ds hist (Historic groff only.)
2886: .Pp
1.57 kristaps 2887: .Bl -dash -compact
1.168 kristaps 2888: .It
2889: Display macros
1.171 schwarze 2890: .Po
2891: .Sx \&Bd ,
2892: .Sx \&Dl ,
2893: and
2894: .Sx \&D1
2895: .Pc
1.168 kristaps 2896: may not be nested.
2897: \*[hist]
1.147 kristaps 2898: .It
1.150 kristaps 2899: .Sx \&At
2900: with unknown arguments produces no output at all.
2901: \*[hist]
2902: Newer groff and mandoc print
2903: .Qq AT&T UNIX
2904: and the arguments.
1.149 kristaps 2905: .It
1.190 schwarze 2906: .Sx \&Bl Fl column
1.150 kristaps 2907: does not recognize trailing punctuation characters when they immediately
2908: precede tabulator characters, but treats them as normal text and
2909: outputs a space before them.
2910: .It
2911: .Sx \&Bd Fl ragged compact
2912: does not start a new line.
2913: \*[hist]
1.142 kristaps 2914: .It
1.150 kristaps 2915: .Sx \&Dd
1.181 schwarze 2916: with non-standard arguments behaves very strangely.
2917: When there are three arguments, they are printed verbatim.
2918: Any other number of arguments is replaced by the current date,
2919: but without any arguments the string
2920: .Dq Epoch
2921: is printed.
1.125 kristaps 2922: .It
1.150 kristaps 2923: .Sx \&Fl
2924: does not print a dash for an empty argument.
2925: \*[hist]
1.137 kristaps 2926: .It
1.150 kristaps 2927: .Sx \&Fn
2928: does not start a new line unless invoked as the line macro in the
2929: .Em SYNOPSIS
2930: section.
2931: \*[hist]
1.119 kristaps 2932: .It
1.150 kristaps 2933: .Sx \&Fo
2934: with
1.120 kristaps 2935: .Pf non- Sx \&Fa
1.150 kristaps 2936: children causes inconsistent spacing between arguments.
2937: In mandoc, a single space is always inserted between arguments.
1.120 kristaps 2938: .It
2939: .Sx \&Ft
2940: in the
1.150 kristaps 2941: .Em SYNOPSIS
2942: causes inconsistent vertical spacing, depending on whether a prior
1.120 kristaps 2943: .Sx \&Fn
2944: has been invoked.
2945: See
2946: .Sx \&Ft
2947: and
2948: .Sx \&Fn
1.150 kristaps 2949: for the normalised behaviour in mandoc.
1.120 kristaps 2950: .It
1.150 kristaps 2951: .Sx \&In
2952: ignores additional arguments and is not treated specially in the
2953: .Em SYNOPSIS .
2954: \*[hist]
1.118 kristaps 2955: .It
1.150 kristaps 2956: .Sx \&It
2957: sometimes requires a
2958: .Fl nested
2959: flag.
2960: \*[hist]
2961: In new groff and mandoc, any list may be nested by default and
2962: .Fl enum
2963: lists will restart the sequence only for the sub-list.
1.115 kristaps 2964: .It
1.150 kristaps 2965: .Sx \&Li
1.195 ! schwarze 2966: followed by a delimiter is incorrectly used in some manuals
1.150 kristaps 2967: instead of properly quoting that character, which sometimes works with
2968: historic groff.
1.57 kristaps 2969: .It
1.150 kristaps 2970: .Sx \&Lk
2971: only accepts a single link-name argument; the remainder is misformatted.
1.81 kristaps 2972: .It
1.80 kristaps 2973: .Sx \&Pa
1.150 kristaps 2974: does not format its arguments when used in the FILES section under
1.100 kristaps 2975: certain list types.
1.80 kristaps 2976: .It
1.150 kristaps 2977: .Sx \&Ta
2978: can only be called by other macros, but not at the beginning of a line.
2979: .It
2980: .Sx \&%C
2981: is not implemented.
1.166 schwarze 2982: .It
2983: Historic groff only allows up to eight or nine arguments per macro input
2984: line, depending on the exact situation.
2985: Providing more arguments causes garbled output.
2986: The number of arguments on one input line is not limited with mandoc.
1.150 kristaps 2987: .It
2988: Historic groff has many un-callable macros.
2989: Most of these (excluding some block-level macros) are callable
2990: in new groff and mandoc.
2991: .It
2992: .Sq \(ba
2993: (vertical bar) is not fully supported as a delimiter.
2994: \*[hist]
1.79 kristaps 2995: .It
1.77 kristaps 2996: .Sq \ef
1.150 kristaps 2997: .Pq font face
2998: and
2999: .Sq \ef
3000: .Pq font family face
1.93 kristaps 3001: .Sx Text Decoration
1.150 kristaps 3002: escapes behave irregularly when specified within line-macro scopes.
1.77 kristaps 3003: .It
1.150 kristaps 3004: Negative scaling units return to prior lines.
3005: Instead, mandoc truncates them to zero.
3006: .El
3007: .Pp
3008: The following features are unimplemented in mandoc:
3009: .Pp
3010: .Bl -dash -compact
1.61 kristaps 3011: .It
1.150 kristaps 3012: .Sx \&Bd
3013: .Fl file Ar file .
1.57 kristaps 3014: .It
1.78 kristaps 3015: .Sx \&Bd
1.126 kristaps 3016: .Fl offset Ar center
1.64 kristaps 3017: and
1.150 kristaps 3018: .Fl offset Ar right .
3019: Groff does not implement centered and flush-right rendering either,
3020: but produces large indentations.
3021: .It
3022: The
3023: .Sq \eh
3024: .Pq horizontal position ,
3025: .Sq \ev
3026: .Pq vertical position ,
3027: .Sq \em
3028: .Pq text colour ,
3029: .Sq \eM
3030: .Pq text filling colour ,
1.152 kristaps 3031: .Sq \ez
3032: .Pq zero-length character ,
1.153 kristaps 3033: .Sq \ew
3034: .Pq string length ,
1.154 kristaps 3035: .Sq \ek
3036: .Pq horizontal position marker ,
1.157 kristaps 3037: .Sq \eo
3038: .Pq text overstrike ,
1.64 kristaps 3039: and
1.150 kristaps 3040: .Sq \es
3041: .Pq text size
1.153 kristaps 3042: escape sequences are all discarded in mandoc.
1.57 kristaps 3043: .It
1.150 kristaps 3044: The
3045: .Sq \ef
3046: scaling unit is accepted by mandoc, but rendered as the default unit.
1.57 kristaps 3047: .It
1.150 kristaps 3048: In quoted literals, groff allows pairwise double-quotes to produce a
3049: standalone double-quote in formatted output.
3050: This is not supported by mandoc.
1.57 kristaps 3051: .El
1.2 kristaps 3052: .Sh SEE ALSO
1.159 schwarze 3053: .Xr man 1 ,
1.57 kristaps 3054: .Xr mandoc 1 ,
1.180 kristaps 3055: .Xr eqn 7 ,
1.174 kristaps 3056: .Xr man 7 ,
1.57 kristaps 3057: .Xr mandoc_char 7
1.174 kristaps 3058: .Xr roff 7 ,
3059: .Xr tbl 7
1.151 kristaps 3060: .Sh HISTORY
3061: The
3062: .Nm
3063: language first appeared as a troff macro package in
3064: .Bx 4.4 .
3065: It was later significantly updated by Werner Lemberg and Ruslan Ermilov
1.155 kristaps 3066: in groff-1.17.
1.151 kristaps 3067: The standalone implementation that is part of the
3068: .Xr mandoc 1
3069: utility written by Kristaps Dzonsons appeared in
3070: .Ox 4.6 .
1.2 kristaps 3071: .Sh AUTHORS
3072: The
1.57 kristaps 3073: .Nm
1.50 kristaps 3074: reference was written by
1.94 kristaps 3075: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb