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