Annotation of mandoc/mdoc.7, Revision 1.65
1.65 ! kristaps 1: .\" $Id: mdoc.7,v 1.64 2009/10/19 10:18:05 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.43 kristaps 134: escape followed by an indicator: B (bold), I, (italic), or P and R
1.54 kristaps 135: (Roman, or reset). This form is not recommended for
1.57 kristaps 136: .Nm ,
1.54 kristaps 137: which encourages semantic, not presentation, annotation.
1.56 kristaps 138: .
139: .
1.57 kristaps 140: .Ss Predefined Strings
1.54 kristaps 141: Historically,
1.57 kristaps 142: .Xr groff 1
1.54 kristaps 143: also defined a set of package-specific
1.57 kristaps 144: .Dq predefined strings ,
1.54 kristaps 145: which, like
1.57 kristaps 146: .Sx Special Characters ,
1.54 kristaps 147: demark special output characters and strings by way of input codes.
148: Predefined strings are escaped with the slash-asterisk,
1.57 kristaps 149: .Sq \e* :
1.54 kristaps 150: single-character
1.57 kristaps 151: .Sq \e*X ,
1.54 kristaps 152: two-character
1.57 kristaps 153: .Sq \e*(XX ,
1.54 kristaps 154: and N-character
1.57 kristaps 155: .Sq \e*[N] .
1.54 kristaps 156: See
1.57 kristaps 157: .Xr mandoc_char 7
1.54 kristaps 158: for a complete list. Examples include
1.57 kristaps 159: .Sq \e*(Am
160: .Pq ampersand
1.54 kristaps 161: and
1.57 kristaps 162: .Sq \e*(Ba
163: .Pq vertical bar .
1.56 kristaps 164: .
165: .
1.57 kristaps 166: .Ss Whitespace
1.46 kristaps 167: In non-literal free-form lines, consecutive blocks of whitespace are
168: pruned from input and added later in the output filter, if applicable:
1.57 kristaps 169: .Bd -literal -offset indent
1.46 kristaps 170: These spaces are pruned from input.
1.50 kristaps 171: \&.Bd \-literal
1.46 kristaps 172: These are not.
173: \&.Ed
1.57 kristaps 174: .Ed
175: .
176: .Pp
1.46 kristaps 177: In macro lines, whitespace delimits arguments and is discarded. If
1.47 kristaps 178: arguments are quoted, whitespace within the quotes is retained.
1.57 kristaps 179: .
180: .Pp
1.46 kristaps 181: Blank lines are only permitted within literal contexts, as are lines
182: containing only whitespace. Tab characters are only acceptable when
1.50 kristaps 183: delimiting
1.57 kristaps 184: .Sq \&Bl \-column
1.46 kristaps 185: or when in a literal context.
1.56 kristaps 186: .
187: .
1.57 kristaps 188: .Ss Quotation
1.46 kristaps 189: Macro arguments may be quoted with a double-quote to group
190: space-delimited terms or to retain blocks of whitespace. A quoted
191: argument begins with a double-quote preceded by whitespace. The next
1.48 kristaps 192: double-quote not pair-wise adjacent to another double-quote terminates
1.50 kristaps 193: the literal, regardless of surrounding whitespace.
1.57 kristaps 194: .
195: .Pp
1.50 kristaps 196: This produces tokens
1.57 kristaps 197: .Sq a" ,
198: .Sq b c ,
199: .Sq de ,
1.47 kristaps 200: and
1.57 kristaps 201: .Sq fg" .
1.47 kristaps 202: Note that any quoted term, be it argument or macro, is indiscriminately
1.50 kristaps 203: considered literal text. Thus, the following produces
1.57 kristaps 204: .Sq \&Em a :
205: .Bd -literal -offset indent
1.47 kristaps 206: \&.Em "Em a"
1.57 kristaps 207: .Ed
208: .
209: .Pp
1.46 kristaps 210: In free-form mode, quotes are regarded as opaque text.
1.56 kristaps 211: .
1.63 kristaps 212: .Ss Dates
213: TODO.
214: .
1.61 kristaps 215: .Ss Scaling Widths
216: Many macros support scaled widths for their arguments, such as
217: stipulating a two-inch list indentation with the following:
218: .Bd -literal -offset indent
219: \&.Bl -tag -width 2i
220: .Ed
221: .
222: .Pp
223: The syntax for scaled widths is
1.62 kristaps 224: .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
1.61 kristaps 225: where a decimal must be preceded or proceeded by at least one digit.
226: Negative numbers, while accepted, are truncated to zero. The following
227: scaling units are accepted:
228: .Pp
229: .Bl -tag -width Ds -offset indent -compact
230: .It c
231: centimetre
232: .It i
233: inch
234: .It P
235: pica (~1/6 inch)
236: .It p
237: point (~1/72 inch)
238: .It f
239: synonym for
240: .Sq u
241: .It v
242: default vertical span
243: .It m
244: width of rendered
245: .Sq m
246: .Pq em
247: character
248: .It n
249: width of rendered
250: .Sq n
251: .Pq en
252: character
253: .It u
254: default horizontal span
255: .It M
256: mini-em (~1/100 em)
257: .El
258: .Pp
259: Using anything other than
260: .Sq m ,
261: .Sq n ,
262: .Sq u ,
263: or
264: .Sq v
265: is necessarily non-portable across output media. See
266: .Sx COMPATIBILITY .
267: .
1.56 kristaps 268: .
1.43 kristaps 269: .Sh MANUAL STRUCTURE
1.33 kristaps 270: Each
1.57 kristaps 271: .Nm
1.50 kristaps 272: document must begin with a document prologue, containing, in order,
1.64 kristaps 273: .Sx \&Dd ,
274: .Sx \&Dt ,
1.33 kristaps 275: and
1.64 kristaps 276: .Sx \&Os ,
1.46 kristaps 277: then the NAME section containing at least one
1.64 kristaps 278: .Sx \&Nm
1.50 kristaps 279: followed by
1.64 kristaps 280: .Sx \&Nd :
1.57 kristaps 281: .Bd -literal -offset indent
1.43 kristaps 282: \&.Dd $\&Mdocdate$
283: \&.Dt mdoc 7
284: \&.Os
1.58 kristaps 285: \&.
1.43 kristaps 286: \&.Sh NAME
1.58 kristaps 287: \&.Nm foo
288: \&.Nd a description goes here
289: \&.\e\*q The next is for sections 2 & 3 only.
290: \&.\e\*q .Sh LIBRARY
291: \&.
292: \&.Sh SYNOPSIS
293: \&.Nm foo
294: \&.Op Fl options
295: \&.Ar
296: \&.
297: \&.Sh DESCRIPTION
298: The
299: \&.Nm
300: utility processes files ...
1.59 kristaps 301: \&.\e\*q .Sh IMPLEMENTATION NOTES
1.58 kristaps 302: \&.\e\*q The next is for sections 1 & 8 only.
303: \&.\e\*q .Sh EXIT STATUS
304: \&.\e\*q The next is for sections 2, 3, & 9 only.
305: \&.\e\*q .Sh RETURN VALUES
306: \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
307: \&.\e\*q .Sh ENVIRONMENT
308: \&.\e\*q .Sh FILES
309: \&.\e\*q .Sh EXAMPLES
310: \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
311: \&.\e\*q .Sh DIAGNOSTICS
312: \&.\e\*q The next is for sections 2, 3, & 9 only.
313: \&.\e\*q .Sh ERRORS
314: \&.\e\*q .Sh SEE ALSO
315: \&.\e\*q .Xr foobar 1
316: \&.\e\*q .Sh STANDARDS
317: \&.\e\*q .Sh HISTORY
318: \&.\e\*q .Sh AUTHORS
319: \&.\e\*q .Sh CAVEATS
320: \&.\e\*q .Sh BUGS
321: \&.\e\*q .Sh SECURITY CONSIDERATIONS
1.57 kristaps 322: .Ed
323: .
324: .Pp
1.43 kristaps 325: Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
1.50 kristaps 326: but non-compulsory.
1.56 kristaps 327: .
328: .
1.43 kristaps 329: .Sh MACRO SYNTAX
1.56 kristaps 330: Macros are one to three three characters in length and begin with a
331: control character ,
1.57 kristaps 332: .Sq \&. ,
1.56 kristaps 333: at the beginning of the line. An arbitrary amount of whitespace may
1.64 kristaps 334: sit between the control character and the macro name. Thus, the
335: following are equivalent:
336: .Bd -literal -offset indent
337: \&.Pp
338: \&.\ \ \ \&Pp
339: .Ed
1.57 kristaps 340: .
341: .Pp
1.46 kristaps 342: The syntax of a macro depends on its classification. In this section,
1.57 kristaps 343: .Sq \-arg
1.43 kristaps 344: refers to macro arguments, which may be followed by zero or more
1.57 kristaps 345: .Sq parm
1.43 kristaps 346: parameters;
1.57 kristaps 347: .Sq \&Yo
1.43 kristaps 348: opens the scope of a macro; and if specified,
1.57 kristaps 349: .Sq \&Yc
1.43 kristaps 350: closes it out.
1.57 kristaps 351: .
352: .Pp
1.43 kristaps 353: The
1.57 kristaps 354: .Em Callable
1.43 kristaps 355: column indicates that the macro may be called subsequent to the initial
1.55 kristaps 356: line-macro. If a macro is not callable, then its invocation after the
357: initial line macro is interpreted as opaque text, such that
1.60 kristaps 358: .Sq \&.Fl \&Sh
1.55 kristaps 359: produces
1.60 kristaps 360: .Sq Fl \&Sh .
1.57 kristaps 361: .
362: .Pp
1.55 kristaps 363: The
1.57 kristaps 364: .Em Parsable
1.43 kristaps 365: column indicates whether the macro may be followed by further
1.55 kristaps 366: (ostensibly callable) macros. If a macro is not parsable, subsequent
367: macro invocations on the line will be interpreted as opaque text.
1.57 kristaps 368: .
369: .Pp
1.55 kristaps 370: The
1.57 kristaps 371: .Em Scope
1.43 kristaps 372: column, if applicable, describes closure rules.
1.56 kristaps 373: .
374: .
1.57 kristaps 375: .Ss Block full-explicit
1.43 kristaps 376: Multi-line scope closed by an explicit closing macro. All macros
377: contains bodies; only
1.64 kristaps 378: .Sx \&Bf
1.43 kristaps 379: contains a head.
1.57 kristaps 380: .Bd -literal -offset indent
1.50 kristaps 381: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
382: \(lBbody...\(rB
1.43 kristaps 383: \&.Yc
1.57 kristaps 384: .Ed
385: .
386: .Pp
387: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
388: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.64 kristaps 389: .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
390: .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
391: .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
392: .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
393: .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
394: .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
395: .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
396: .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
1.57 kristaps 397: .El
1.56 kristaps 398: .
399: .
1.57 kristaps 400: .Ss Block full-implicit
1.43 kristaps 401: Multi-line scope closed by end-of-file or implicitly by another macro.
1.50 kristaps 402: All macros have bodies; some
1.57 kristaps 403: .Po
1.64 kristaps 404: .Sx \&It Fl bullet ,
405: .Fl hyphen ,
406: .Fl dash ,
407: .Fl enum ,
408: .Fl item
1.57 kristaps 409: .Pc
1.64 kristaps 410: don't have heads; only one
411: .Po
412: .Sx \&It Fl column
413: .Pc
414: has multiple heads.
1.57 kristaps 415: .Bd -literal -offset indent
1.50 kristaps 416: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
417: \(lBbody...\(rB
1.57 kristaps 418: .Ed
1.56 kristaps 419: .
1.57 kristaps 420: .Pp
421: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
422: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.64 kristaps 423: .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
424: .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
425: .It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh
426: .It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss
1.57 kristaps 427: .El
1.56 kristaps 428: .
1.57 kristaps 429: .
430: .Ss Block partial-explicit
1.43 kristaps 431: Like block full-explicit, but also with single-line scope. Each
1.50 kristaps 432: has at least a body and, in limited circumstances, a head
1.64 kristaps 433: .Po
434: .Sx \&Fo ,
435: .Sx \&Eo
436: .Pc
1.50 kristaps 437: and/or tail
1.64 kristaps 438: .Pq Sx \&Ec .
1.57 kristaps 439: .Bd -literal -offset indent
1.50 kristaps 440: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
441: \(lBbody...\(rB
442: \&.Yc \(lBtail...\(rB
1.2 kristaps 443:
1.43 kristaps 444: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
1.50 kristaps 445: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.57 kristaps 446: .Ed
447: .
448: .Pp
449: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
450: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.64 kristaps 451: .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
1.63 kristaps 452: .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
1.64 kristaps 453: .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
454: .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
455: .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
456: .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
457: .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
458: .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
459: .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
460: .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
461: .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
462: .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
463: .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
464: .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
465: .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
466: .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
467: .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
468: .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
1.63 kristaps 469: .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
470: .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
1.64 kristaps 471: .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
472: .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
473: .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
474: .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
1.57 kristaps 475: .El
1.56 kristaps 476: .
477: .
1.57 kristaps 478: .Ss Block partial-implicit
1.50 kristaps 479: Like block full-implicit, but with single-line scope closed by
1.57 kristaps 480: .Sx Reserved Characters
1.43 kristaps 481: or end of line.
1.57 kristaps 482: .Bd -literal -offset indent
1.43 kristaps 483: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
1.57 kristaps 484: .Ed
1.56 kristaps 485: .
1.57 kristaps 486: .Pp
487: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
488: .It Em Macro Ta Em Callable Ta Em Parsable
1.64 kristaps 489: .It Sx \&Aq Ta Yes Ta Yes
490: .It Sx \&Bq Ta Yes Ta Yes
491: .It Sx \&Brq Ta Yes Ta Yes
492: .It Sx \&D1 Ta \&No Ta \&Yes
493: .It Sx \&Dl Ta \&No Ta Yes
494: .It Sx \&Dq Ta Yes Ta Yes
495: .It Sx \&Op Ta Yes Ta Yes
496: .It Sx \&Pq Ta Yes Ta Yes
497: .It Sx \&Ql Ta Yes Ta Yes
498: .It Sx \&Qq Ta Yes Ta Yes
499: .It Sx \&Sq Ta Yes Ta Yes
1.57 kristaps 500: .El
1.56 kristaps 501: .
1.57 kristaps 502: .
503: .Ss In-line
1.50 kristaps 504: Closed by
1.57 kristaps 505: .Sx Reserved Characters ,
1.43 kristaps 506: end of line, fixed argument lengths, and/or subsequent macros. In-line
507: macros have only text children. If a number (or inequality) of
1.3 kristaps 508: arguments is
1.57 kristaps 509: .Pq n ,
1.3 kristaps 510: then the macro accepts an arbitrary number of arguments.
1.57 kristaps 511: .Bd -literal -offset indent
1.43 kristaps 512: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
513:
514: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
515:
516: \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
1.57 kristaps 517: .Ed
518: .
519: .Pp
520: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
521: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.63 kristaps 522: .It Sx \&%A Ta \&No Ta \&No Ta >0
523: .It Sx \&%B Ta \&No Ta \&No Ta >0
524: .It Sx \&%C Ta \&No Ta \&No Ta >0
525: .It Sx \&%D Ta \&No Ta \&No Ta >0
526: .It Sx \&%I Ta \&No Ta \&No Ta >0
527: .It Sx \&%J Ta \&No Ta \&No Ta >0
528: .It Sx \&%N Ta \&No Ta \&No Ta >0
529: .It Sx \&%O Ta \&No Ta \&No Ta >0
530: .It Sx \&%P Ta \&No Ta \&No Ta >0
531: .It Sx \&%R Ta \&No Ta \&No Ta >0
532: .It Sx \&%T Ta \&No Ta \&No Ta >0
533: .It Sx \&%V Ta \&No Ta \&No Ta >0
1.64 kristaps 534: .It Sx \&Ad Ta Yes Ta Yes Ta n
535: .It Sx \&An Ta Yes Ta Yes Ta n
536: .It Sx \&Ap Ta Yes Ta Yes Ta 0
537: .It Sx \&Ar Ta Yes Ta Yes Ta n
538: .It Sx \&At Ta Yes Ta Yes Ta 1
539: .It Sx \&Bsx Ta Yes Ta Yes Ta n
540: .It Sx \&Bt Ta \&No Ta \&No Ta 0
541: .It Sx \&Bx Ta Yes Ta Yes Ta n
542: .It Sx \&Cd Ta Yes Ta Yes Ta >0
543: .It Sx \&Cm Ta Yes Ta Yes Ta n
544: .It Sx \&Db Ta \&No Ta \&No Ta 1
545: .It Sx \&Dd Ta \&No Ta \&No Ta >0
546: .It Sx \&Dt Ta \&No Ta \&No Ta n
547: .It Sx \&Dv Ta Yes Ta Yes Ta n
548: .It Sx \&Dx Ta Yes Ta Yes Ta n
549: .It Sx \&Em Ta Yes Ta Yes Ta >0
550: .It Sx \&En Ta \&No Ta \&No Ta 0
551: .It Sx \&Er Ta Yes Ta Yes Ta >0
552: .It Sx \&Es Ta \&No Ta \&No Ta 0
553: .It Sx \&Ev Ta Yes Ta Yes Ta n
554: .It Sx \&Ex Ta \&No Ta \&No Ta n
555: .It Sx \&Fa Ta Yes Ta Yes Ta n
556: .It Sx \&Fd Ta \&No Ta \&No Ta >0
557: .It Sx \&Fl Ta Yes Ta Yes Ta n
558: .It Sx \&Fn Ta Yes Ta Yes Ta >0
559: .It Sx \&Fr Ta \&No Ta \&No Ta n
560: .It Sx \&Ft Ta Yes Ta Yes Ta n
561: .It Sx \&Fx Ta Yes Ta Yes Ta n
562: .It Sx \&Hf Ta \&No Ta \&No Ta n
563: .It Sx \&Ic Ta Yes Ta Yes Ta >0
564: .It Sx \&In Ta \&No Ta \&No Ta n
565: .It Sx \&Lb Ta \&No Ta \&No Ta 1
566: .It Sx \&Li Ta Yes Ta Yes Ta n
567: .It Sx \&Lk Ta Yes Ta Yes Ta n
568: .It Sx \&Lp Ta \&No Ta \&No Ta 0
569: .It Sx \&Ms Ta Yes Ta Yes Ta >0
570: .It Sx \&Mt Ta Yes Ta Yes Ta >0
571: .It Sx \&Nm Ta Yes Ta Yes Ta n
572: .It Sx \&No Ta Yes Ta Yes Ta 0
573: .It Sx \&Ns Ta Yes Ta Yes Ta 0
574: .It Sx \&Nx Ta Yes Ta Yes Ta n
575: .It Sx \&Os Ta \&No Ta \&No Ta n
576: .It Sx \&Ot Ta \&No Ta \&No Ta n
577: .It Sx \&Ox Ta Yes Ta Yes Ta n
578: .It Sx \&Pa Ta Yes Ta Yes Ta n
579: .It Sx \&Pf Ta \&No Ta Yes Ta 1
580: .It Sx \&Pp Ta \&No Ta \&No Ta 0
581: .It Sx \&Rv Ta \&No Ta \&No Ta n
582: .It Sx \&Sm Ta \&No Ta \&No Ta 1
583: .It Sx \&St Ta \&No Ta Yes Ta 1
584: .It Sx \&Sx Ta Yes Ta Yes Ta >0
585: .It Sx \&Sy Ta Yes Ta Yes Ta >0
586: .It Sx \&Tn Ta Yes Ta Yes Ta >0
587: .It Sx \&Ud Ta \&No Ta \&No Ta 0
588: .It Sx \&Ux Ta Yes Ta Yes Ta n
589: .It Sx \&Va Ta Yes Ta Yes Ta n
590: .It Sx \&Vt Ta Yes Ta Yes Ta >0
591: .It Sx \&Xr Ta Yes Ta Yes Ta >0, <3
592: .It Sx \&br Ta \&No Ta \&No Ta 0
593: .It Sx \&sp Ta \&No Ta \&No Ta 1
1.57 kristaps 594: .El
1.56 kristaps 595: .
596: .
1.63 kristaps 597: .Sh REFERENCE
598: This section is a canonical reference of all macros, arranged
599: alphabetically. For the scoping of individual macros, see
600: .Sx MACRO SYNTAX .
601: .
602: .Ss \&%A
603: Author name of an
604: .Sx \&Rs
605: block. Multiple authors should each be accorded their own
1.64 kristaps 606: .Sx \%%A
1.63 kristaps 607: line.
608: .Pp
609: Author names should be ordered with full or abbreviated forename(s)
610: first, then full surname.
1.64 kristaps 611: .
1.63 kristaps 612: .Ss \&%B
613: Book title of an
614: .Sx \&Rs
615: block. This macro may also be used in a non-bibliographic context when
616: referring to book titles.
1.64 kristaps 617: .
1.63 kristaps 618: .Ss \&%C
619: Publication city or location of an
620: .Sx \&Rs
621: block.
622: .Pp
1.65 ! kristaps 623: .Em Remarks :
1.63 kristaps 624: this macro is not implemented in
625: .Xr groff 1 .
1.64 kristaps 626: .
1.63 kristaps 627: .Ss \&%D
628: Publication date of an
629: .Sx \&Rs
630: block. This should follow the canonical syntax for
631: .Sx Dates .
1.64 kristaps 632: .
1.63 kristaps 633: .Ss \&%I
634: Publisher or issuer name of an
635: .Sx \&Rs
636: block.
1.64 kristaps 637: .
1.63 kristaps 638: .Ss \&%J
639: Journal name of an
640: .Sx \&Rs
641: block.
1.64 kristaps 642: .
1.63 kristaps 643: .Ss \&%N
644: Issue number (usually for journals) of an
645: .Sx \&Rs
646: block.
1.64 kristaps 647: .
1.63 kristaps 648: .Ss \&%O
649: Optional information of an
650: .Sx \&Rs
651: block.
1.64 kristaps 652: .
1.63 kristaps 653: .Ss \&%P
654: Book or journal page number of an
655: .Sx \&Rs
656: block.
1.64 kristaps 657: .
1.63 kristaps 658: .Ss \&%Q
659: Institutional author (school, government, etc.) of an
660: .Sx \&Rs
661: block. Multiple institutional authors should each be accorded their own
1.64 kristaps 662: .Sx \&%Q
1.63 kristaps 663: line.
1.64 kristaps 664: .
1.63 kristaps 665: .Ss \&%R
666: Technical report name of an
667: .Sx \&Rs
668: block.
1.64 kristaps 669: .
1.63 kristaps 670: .Ss \&%T
671: Article title of an
672: .Sx \&Rs
673: block. This macro may also be used in a non-bibliographical context
674: when referring to article titles.
1.64 kristaps 675: .
1.63 kristaps 676: .Ss \&%V
677: Volume number of an
678: .Sx \&Rs
679: block.
1.64 kristaps 680: .
1.63 kristaps 681: .Ss \&Ac
682: Closes an
683: .Sx \&Ao
684: block. Does not have any tail arguments.
1.64 kristaps 685: .
1.63 kristaps 686: .Ss \&Ad
687: Address construct: usually in the context of an computational address in
688: memory, not a physical (post) address.
689: .Pp
1.64 kristaps 690: Examples:
1.63 kristaps 691: .Bd -literal -offset indent
692: \&.Ad [0,$]
693: \&.Ad 0x00000000
694: .Ed
1.64 kristaps 695: .
1.63 kristaps 696: .Ss \&An
1.64 kristaps 697: Author name. This macro may alternatively accepts the following
698: arguments, although these may not be specified along with a parameter:
699: .Bl -tag -width 12n -offset indent
700: .It Fl split
701: Renders a line break is rendered before each author listing.
702: .It Fl nosplit
703: The opposite of
704: .Fl split .
705: .El
706: .Pp
707: In the AUTHORS section, the default is not to split the first author
708: listing, but all subsequent author listings, whether or not they're
709: interspersed by other macros or text, are split. Thus, specifying
710: .Fl split
711: will cause the first listing also to be split. If not in the AUTHORS
712: section, the default is not to split.
713: .Pp
714: Examples:
715: .Bd -literal -offset indent
716: \&.An -nosplit
717: \&.An J. E. Hopcraft ,
718: \&.An J. D. Ullman .
719: .Ed
720: .Pp
721: .Em Remarks :
722: the effects of
723: .Fl split
724: or
725: .Fl nosplit
726: are re-set when entering the AUTHORS section, so if one specifies
727: .Sx \&An Fl nosplit
728: in the general document body, it must be re-specified in the AUTHORS
729: section.
730: .
1.63 kristaps 731: .Ss \&Ao
732: Begins a block enclosed by angled brackets. Does not have any head
733: arguments.
734: .Pp
1.64 kristaps 735: Examples:
1.63 kristaps 736: .Bd -literal -offset indent
737: \&.Fl -key= Ns Ao Ar val Ac
738: .Ed
739: .Pp
1.64 kristaps 740: See also
741: .Sx \&Aq .
742: .
1.63 kristaps 743: .Ss \&Ap
1.64 kristaps 744: Inserts an apostrophe without any surrounding white-space. This is
745: generally used as a grammatic device when referring to the verb form of
746: a function:
747: .Bd -literal -offset indent
748: \&.Fn execve Ap d
749: .Ed
750: .
1.63 kristaps 751: .Ss \&Aq
1.64 kristaps 752: Encloses its arguments in angled brackets.
753: .Pp
754: Examples:
755: .Bd -literal -offset indent
756: \&.Fl -key= Ns Aq Ar val
757: .Ed
758: .Pp
759: .Em Remarks :
760: this macro is often abused for rendering URIs, which should instead use
761: .Sx \&Lk
762: or
763: .Sx \&Mt ,
764: or to note pre-processor
765: .Dq Li #include
766: statements, which should use
767: .Sx \&In .
768: .Pp
769: See also
770: .Sx \&Ao .
771: .
1.63 kristaps 772: .Ss \&Ar
1.64 kristaps 773: Command arguments. If an argument is not provided, the strings
774: .Dq file ...
775: are used as a default.
776: .Pp
777: Examples:
778: .Bd -literal -offset indent
779: \&.Fl o Ns Ar file1
780: \&.Ar
781: \&.Ar arg1 , arg2 .
782: .Ed
783: .
1.63 kristaps 784: .Ss \&At
1.64 kristaps 785: Formats an AT&T version. Accepts at most one parameter:
786: .Bl -tag -width 12n -offset indent
787: .It Cm v[1-7] | 32v
788: A version of
789: .At .
790: .It Cm V[.[1-4]]?
791: A system version of
792: .At .
793: .El
794: .Pp
795: Note that these parameters do not begin with a hyphen.
796: .Pp
797: Examples:
798: .Bd -literal -offset indent
799: \&.At
800: \&.At V.1
801: .Ed
1.65 ! kristaps 802: .Pp
! 803: See also
! 804: .Sx \&Bx ,
! 805: .Sx \&Bsx ,
! 806: .Sx \&Fx ,
! 807: .Sx \&Nx ,
! 808: .Sx \&Ox ,
! 809: and
! 810: .Sx \&Ux .
1.64 kristaps 811: .
1.63 kristaps 812: .Ss \&Bc
1.64 kristaps 813: Closes a
814: .Sx \&Bo
815: block. Does not have any tail arguments.
816: .
1.63 kristaps 817: .Ss \&Bd
1.64 kristaps 818: Begins a display block. A display is collection of macros or text which
819: may be collectively offset or justified in a manner different from that
820: of the enclosing context. By default, the block is preceded by a
821: vertical space.
822: .Pp
823: Each display is associated with a type, which must be one of the
824: following arguments:
825: .Bl -tag -width 12n -offset indent
826: .It Fl ragged
827: Only left-justify the block.
828: .It Fl unfilled
829: Do not justify the block at all.
830: .It Fl filled
831: Left- and right-justify the block.
832: .It Fl literal
833: Alias for
834: .Fl unfilled .
835: .It Fl centered
836: Centre-justify each line.
837: .El
838: .Pp
839: The type must be provided first. Secondary arguments are as follows:
840: .Bl -tag -width 12n -offset indent
841: .It Fl offset Ar width
842: Offset by the value of
843: .Ar width ,
844: which is interpreted as one of the following, specified in order:
845: .Bl -item
846: .It
847: As one of the pre-defined strings
848: .Ar indent ,
849: the width of standard indentation;
850: .Ar indent-two ,
851: twice
852: .Ar indent ;
853: .Ar left ,
854: which has no effect ;
855: .Ar right ,
856: which justifies to the right margin; and
857: .Ar center ,
858: which aligns around an imagined centre axis.
859: .It
860: As a precalculated width for a named macro. The most popular is the
861: imaginary macro
862: .Ar Ds ,
863: which resolves to
864: .Ar 6n .
865: .It
866: As a scaling unit following the syntax described in
867: .Sx Scaling Widths .
868: .It
869: As the calculated string length of the opaque string.
870: .El
871: .Pp
872: If unset, it will revert to the value of
873: .Ar 8n
874: as described in
875: .Sx Scaling Widths .
876: .It Fl compact
877: Do not assert a vertical space before the block.
878: .It Fl file Ar file
879: Prepend the file
880: .Ar file
881: before any text or macros within the block.
882: .El
883: .Pp
884: Examples:
885: .Bd -literal -offset indent
886: \&.Bd \-unfilled \-offset two-indent \-compact
1.65 ! kristaps 887: Hello world.
1.64 kristaps 888: \&.Ed
889: .Ed
890: .
1.63 kristaps 891: .Ss \&Bf
892: .Ss \&Bk
893: .Ss \&Bl
1.65 ! kristaps 894: .
1.63 kristaps 895: .Ss \&Bo
1.65 ! kristaps 896: Begins a block enclosed by square brackets. Does not have any head
! 897: arguments.
! 898: .Pp
! 899: Examples:
! 900: .Bd -literal -offset indent
! 901: \&.Bo 1 ,
! 902: \&.Dv BUFSIZ Bc
! 903: .Ed
! 904: .Pp
! 905: See also
! 906: .Sx \&Bq .
! 907: .
1.63 kristaps 908: .Ss \&Bq
1.65 ! kristaps 909: Encloses its arguments in square brackets.
! 910: .Pp
! 911: Examples:
! 912: .Bd -literal -offset indent
! 913: \&.Bq 1 , Dv BUFSIZ
! 914: .Ed
! 915: .Pp
! 916: .Em Remarks :
! 917: this macro is sometimes abused to emulate optional arguments for
! 918: commands; the correct macros to use for this purpose are
! 919: .Sx \&Op ,
! 920: .Sx \&Oo ,
! 921: and
! 922: .Sx \&Oc .
! 923: .Pp
! 924: See also
! 925: .Sx \&Bo .
! 926: .
1.63 kristaps 927: .Ss \&Brc
1.65 ! kristaps 928: Closes a
! 929: .Sx \&Bro
! 930: block. Does not have any tail arguments.
! 931: .
1.63 kristaps 932: .Ss \&Bro
1.65 ! kristaps 933: Begins a block enclosed by curly braces. Does not have any head
! 934: arguments.
! 935: .Pp
! 936: Examples:
! 937: .Bd -literal -offset indent
! 938: \&.Bro 1 , ... ,
! 939: \&.Va n Brc
! 940: .Ed
! 941: .Pp
! 942: See also
! 943: .Sx \&Brq .
! 944: .
1.63 kristaps 945: .Ss \&Brq
1.65 ! kristaps 946: Encloses its arguments in curly braces.
! 947: .Pp
! 948: Examples:
! 949: .Bd -literal -offset indent
! 950: \&.Brq 1 , ... , Va n
! 951: .Ed
! 952: .Pp
! 953: See also
! 954: .Sx \&Bro .
! 955: .
1.63 kristaps 956: .Ss \&Bsx
1.65 ! kristaps 957: Format the BSD/OS version provided as an argument, or a default value if
! 958: no argument is provided.
! 959: .Pp
! 960: Examples:
! 961: .Bd -literal -offset indent
! 962: \&.Bsx 1.0
! 963: \&.Bsx
! 964: .Ed
! 965: .Pp
! 966: See also
! 967: .Sx \&At ,
! 968: .Sx \&Bx ,
! 969: .Sx \&Fx ,
! 970: .Sx \&Nx ,
! 971: .Sx \&Ox ,
! 972: and
! 973: .Sx \&Ux .
! 974: .
1.63 kristaps 975: .Ss \&Bt
976: .Ss \&Bx
1.65 ! kristaps 977: Format the BSD version provided as an argument, or a default value if no
! 978: argument is provided.
! 979: .Pp
! 980: Examples:
! 981: .Bd -literal -offset indent
! 982: \&.Bx 4.4
! 983: \&.Bx
! 984: .Ed
! 985: .Pp
! 986: See also
! 987: .Sx \&At ,
! 988: .Sx \&Bsx ,
! 989: .Sx \&Fx ,
! 990: .Sx \&Nx ,
! 991: .Sx \&Ox ,
! 992: and
! 993: .Sx \&Ux .
! 994: .
1.63 kristaps 995: .Ss \&Cd
996: .Ss \&Cm
997: .Ss \&D1
998: .Ss \&Db
999: .Ss \&Dc
1000: .Ss \&Dd
1001: .Ss \&Dl
1002: .Ss \&Do
1003: .Ss \&Dq
1004: .Ss \&Dt
1005: .Ss \&Dv
1006: .Ss \&Dx
1007: .Ss \&Ec
1008: .Ss \&Ed
1009: .Ss \&Ef
1010: .Ss \&Ek
1011: .Ss \&El
1012: .Ss \&Em
1013: .Ss \&En
1014: .Ss \&Eo
1015: .Ss \&Er
1016: .Ss \&Es
1017: .Ss \&Ev
1018: .Ss \&Ex
1019: .Ss \&Fa
1020: .Ss \&Fc
1021: .Ss \&Fd
1022: .Ss \&Fl
1023: .Ss \&Fn
1024: .Ss \&Fo
1025: .Ss \&Fr
1026: .Ss \&Ft
1027: .Ss \&Fx
1.65 ! kristaps 1028: Format the FreeBSD version provided as an argument, or a default value
! 1029: if no argument is provided.
! 1030: .Pp
! 1031: Examples:
! 1032: .Bd -literal -offset indent
! 1033: \&.Fx 7.1
! 1034: \&.Fx
! 1035: .Ed
! 1036: .Pp
! 1037: See also
! 1038: .Sx \&At ,
! 1039: .Sx \&Bx ,
! 1040: .Sx \&Bsx ,
! 1041: .Sx \&Nx ,
! 1042: .Sx \&Ox ,
! 1043: and
! 1044: .Sx \&Ux .
! 1045: .
1.63 kristaps 1046: .Ss \&Hf
1047: .Ss \&Ic
1048: .Ss \&In
1049: .Ss \&It
1050: .Ss \&Lb
1051: .Ss \&Li
1052: .Ss \&Lk
1053: .Ss \&Lp
1054: .Ss \&Ms
1055: .Ss \&Mt
1056: .Ss \&Nd
1057: .Ss \&Nm
1058: .Ss \&No
1059: .Ss \&Ns
1060: .Ss \&Nx
1.65 ! kristaps 1061: Format the NetBSD version provided as an argument, or a default value if
! 1062: no argument is provided.
! 1063: .Pp
! 1064: Examples:
! 1065: .Bd -literal -offset indent
! 1066: \&.Nx 5.01
! 1067: \&.Nx
! 1068: .Ed
! 1069: .Pp
! 1070: See also
! 1071: .Sx \&At ,
! 1072: .Sx \&Bx ,
! 1073: .Sx \&Bsx ,
! 1074: .Sx \&Fx ,
! 1075: .Sx \&Ox ,
! 1076: and
! 1077: .Sx \&Ux .
! 1078: .
1.63 kristaps 1079: .Ss \&Oc
1080: .Ss \&Oo
1081: .Ss \&Op
1082: .Ss \&Os
1083: .Ss \&Ot
1084: .Ss \&Ox
1.65 ! kristaps 1085: Format the OpenBSD version provided as an argument, or a default value
! 1086: if no argument is provided.
! 1087: .Pp
! 1088: Examples:
! 1089: .Bd -literal -offset indent
! 1090: \&.Ox 4.5
! 1091: \&.Ox
! 1092: .Ed
! 1093: .Pp
! 1094: See also
! 1095: .Sx \&At ,
! 1096: .Sx \&Bsx ,
! 1097: .Sx \&Bx ,
! 1098: .Sx \&Fx ,
! 1099: .Sx \&Nx ,
! 1100: and
! 1101: .Sx \&Ux .
! 1102: .
1.63 kristaps 1103: .Ss \&Pa
1104: .Ss \&Pc
1105: .Ss \&Pf
1106: .Ss \&Po
1107: .Ss \&Pp
1108: .Ss \&Pq
1109: .Ss \&Qc
1110: .Ss \&Ql
1111: .Ss \&Qo
1112: .Ss \&Qq
1.64 kristaps 1113: .
1.63 kristaps 1114: .Ss \&Re
1115: Closes a
1116: .Sx \&Rs
1117: block. Does not have any tail arguments.
1.64 kristaps 1118: .
1.63 kristaps 1119: .Ss \&Rs
1120: Begins a bibliographic
1121: .Pq Dq reference
1122: block. Does not have any head arguments. The block macro and may only
1123: contain
1124: .Sx \&%A ,
1125: .Sx \&%B ,
1126: .Sx \&%C ,
1127: .Sx \&%D ,
1128: .Sx \&%I ,
1129: .Sx \&%J ,
1130: .Sx \&%N ,
1131: .Sx \&%O ,
1132: .Sx \&%P ,
1133: .Sx \&%Q ,
1134: .Sx \&%R ,
1135: .Sx \&%T ,
1136: and
1137: .Sx \&%V
1138: child macros (at least one must be specified).
1139: .Pp
1.64 kristaps 1140: Examples:
1.63 kristaps 1141: .Bd -literal -offset indent
1142: \&.Rs
1143: \&.%A J. E. Hopcroft
1144: \&.%A J. D. Ullman
1145: \&.%B Introduction to Automata Theory, Languages, and Computation
1146: \&.%I Addison-Wesley
1147: \&.%C Reading, Massachusettes
1148: \&.%D 1979
1149: \&.Re
1150: .Ed
1151: .Pp
1152: If an
1153: .Sx \&Rs
1154: block is used within a SEE ALSO section, a vertical space is asserted
1155: before the rendered output, else the block continues on the current
1156: line.
1.64 kristaps 1157: .
1.63 kristaps 1158: .Ss \&Rv
1159: .Ss \&Sc
1160: .Ss \&Sh
1161: .Ss \&Sm
1162: .Ss \&So
1163: .Ss \&Sq
1164: .Ss \&Ss
1165: .Ss \&St
1166: .Ss \&Sx
1167: .Ss \&Sy
1168: .Ss \&Tn
1169: .Ss \&Ud
1170: .Ss \&Ux
1.65 ! kristaps 1171: Format the UNIX name. Accepts no argument.
! 1172: .Pp
! 1173: Examples:
! 1174: .Bd -literal -offset indent
! 1175: \&.Ux
! 1176: .Ed
! 1177: .Pp
! 1178: See also
! 1179: .Sx \&At ,
! 1180: .Sx \&Bx ,
! 1181: .Sx \&Bsx ,
! 1182: .Sx \&Fx ,
! 1183: .Sx \&Nx ,
! 1184: and
! 1185: .Sx \&Ox .
! 1186: .
1.63 kristaps 1187: .Ss \&Va
1188: .Ss \&Vt
1189: .Ss \&Xc
1190: .Ss \&Xo
1191: .Ss \&Xr
1192: .Ss \&br
1193: .Ss \&sp
1194: .
1195: .
1.4 kristaps 1196: .Sh COMPATIBILITY
1.28 kristaps 1197: This section documents compatibility with other roff implementations, at
1.50 kristaps 1198: this time limited to
1.57 kristaps 1199: .Xr groff 1 .
1.50 kristaps 1200: The term
1.57 kristaps 1201: .Qq historic groff
1.50 kristaps 1202: refers to those versions before the
1.57 kristaps 1203: .Pa doc.tmac
1.50 kristaps 1204: file re-write
1.57 kristaps 1205: .Pq somewhere between 1.15 and 1.19 .
1206: .
1207: .Pp
1208: .Bl -dash -compact
1209: .It
1.61 kristaps 1210: Negative scaling units are now truncated to zero instead of creating
1211: interesting conditions, such as with
1212: .Sq \&sp -1i .
1213: Furthermore, the
1214: .Sq f
1215: scaling unit, while accepted, is rendered as the default unit.
1216: .It
1.48 kristaps 1217: In quoted literals, groff allowed pair-wise double-quotes to produce a
1218: standalone double-quote in formatted output. This idiosyncratic
1219: behaviour is no longer applicable.
1.57 kristaps 1220: .It
1.64 kristaps 1221: Display types
1222: .Sx \&Bd Fl center
1223: and
1224: .Fl right
1225: are aliases for
1226: .Fl left .
1.50 kristaps 1227: The
1.64 kristaps 1228: .Fl file Ar file
1229: argument is ignored. Since text is not right-justified,
1230: .Fl ragged
1231: and
1232: .Fl filled
1233: are aliases, as are
1234: .Fl literal
1235: and
1236: .Fl unfilled .
1.57 kristaps 1237: .It
1.35 kristaps 1238: Blocks of whitespace are stripped from both macro and free-form text
1239: lines (except when in literal mode), while groff would retain whitespace
1240: in free-form text lines.
1.57 kristaps 1241: .It
1.28 kristaps 1242: Historic groff has many un-callable macros. Most of these (excluding
1243: some block-level macros) are now callable, conforming to the
1244: non-historic groff version.
1.57 kristaps 1245: .It
1.50 kristaps 1246: The vertical bar
1.57 kristaps 1247: .Sq \(ba
1.28 kristaps 1248: made historic groff
1.57 kristaps 1249: .Qq go orbital
1.28 kristaps 1250: but is a proper delimiter in this implementation.
1.57 kristaps 1251: .It
1.64 kristaps 1252: .Sx \&It Fl nested
1.28 kristaps 1253: is assumed for all lists (it wasn't in historic groff): any list may be
1254: nested and
1.64 kristaps 1255: .Fl enum
1.4 kristaps 1256: lists will restart the sequence only for the sub-list.
1.57 kristaps 1257: .It
1.4 kristaps 1258: Some manuals use
1.64 kristaps 1259: .Sx \&Li
1.4 kristaps 1260: incorrectly by following it with a reserved character and expecting the
1261: delimiter to render. This is not supported.
1.57 kristaps 1262: .It
1.50 kristaps 1263: In groff, the
1.64 kristaps 1264: .Sx \&Fo
1.41 kristaps 1265: macro only produces the first parameter. This is no longer the case.
1.57 kristaps 1266: .El
1.56 kristaps 1267: .
1268: .
1.2 kristaps 1269: .Sh SEE ALSO
1.57 kristaps 1270: .Xr mandoc 1 ,
1271: .Xr mandoc_char 7
1.56 kristaps 1272: .
1273: .
1.2 kristaps 1274: .Sh AUTHORS
1275: The
1.57 kristaps 1276: .Nm
1.50 kristaps 1277: reference was written by
1.57 kristaps 1278: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.64 kristaps 1279: .\"
1280: .\" XXX: this really isn't the place for these caveats.
1281: .\" .
1282: .\" .
1283: .\" .Sh CAVEATS
1284: .\" There are many ambiguous parts of mdoc.
1285: .\" .
1286: .\" .Pp
1287: .\" .Bl -dash -compact
1288: .\" .It
1289: .\" .Sq \&Fa
1290: .\" should be
1291: .\" .Sq \&Va
1292: .\" as function arguments are variables.
1293: .\" .It
1294: .\" .Sq \&Ft
1295: .\" should be
1296: .\" .Sq \&Vt
1297: .\" as function return types are still types. Furthermore, the
1298: .\" .Sq \&Ft
1299: .\" should be removed and
1300: .\" .Sq \&Fo ,
1301: .\" which ostensibly follows it, should follow the same convention as
1302: .\" .Sq \&Va .
1303: .\" .It
1304: .\" .Sq \&Va
1305: .\" should formalise that only one or two arguments are acceptable: a
1306: .\" variable name and optional, preceding type.
1307: .\" .It
1308: .\" .Sq \&Fd
1309: .\" is ambiguous. It's commonly used to indicate an include file in the
1310: .\" synopsis section.
1311: .\" .Sq \&In
1312: .\" should be used, instead.
1313: .\" .It
1314: .\" Only the
1315: .\" .Sq \-literal
1316: .\" argument to
1317: .\" .Sq \&Bd
1318: .\" makes sense. The remaining ones should be removed.
1319: .\" .It
1320: .\" The
1321: .\" .Sq \&Xo
1322: .\" and
1323: .\" .Sq \&Xc
1324: .\" macros should be deprecated.
1325: .\" .It
1326: .\" The
1327: .\" .Sq \&Dt
1328: .\" macro lacks clarity. It should be absolutely clear which title will
1329: .\" render when formatting the manual page.
1330: .\" .It
1331: .\" A
1332: .\" .Sq \&Lx
1333: .\" should be provided for Linux (\(`a la
1334: .\" .Sq \&Ox ,
1335: .\" .Sq \&Nx
1336: .\" etc.).
1337: .\" .It
1338: .\" There's no way to refer to references in
1339: .\" .Sq \&Rs/Re
1340: .\" blocks.
1341: .\" .It
1342: .\" The \-split and \-nosplit dictates via
1343: .\" .Sq \&An
1344: .\" are re-set when entering and leaving the AUTHORS section.
1345: .\" .El
1346: .\" .
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