Annotation of mandoc/mdoc.7, Revision 1.63
1.63 ! kristaps 1: .\" $Id: mdoc.7,v 1.62 2009/10/18 19:01:24 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.57 kristaps 273: .Sq \&Dd ,
274: .Sq \&Dt ,
1.33 kristaps 275: and
1.57 kristaps 276: .Sq \&Os ,
1.46 kristaps 277: then the NAME section containing at least one
1.57 kristaps 278: .Sq \&Nm
1.50 kristaps 279: followed by
1.57 kristaps 280: .Sq \&Nd :
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
334: sit between the control character and the macro name. Thus,
1.57 kristaps 335: .Sq \&.Pp
1.56 kristaps 336: and
1.57 kristaps 337: .Sq \&.\ \ \ \&Pp
1.56 kristaps 338: are equivalent. Macro names are two or three characters in length.
1.57 kristaps 339: .
340: .Pp
1.46 kristaps 341: The syntax of a macro depends on its classification. In this section,
1.57 kristaps 342: .Sq \-arg
1.43 kristaps 343: refers to macro arguments, which may be followed by zero or more
1.57 kristaps 344: .Sq parm
1.43 kristaps 345: parameters;
1.57 kristaps 346: .Sq \&Yo
1.43 kristaps 347: opens the scope of a macro; and if specified,
1.57 kristaps 348: .Sq \&Yc
1.43 kristaps 349: closes it out.
1.57 kristaps 350: .
351: .Pp
1.43 kristaps 352: The
1.57 kristaps 353: .Em Callable
1.43 kristaps 354: column indicates that the macro may be called subsequent to the initial
1.55 kristaps 355: line-macro. If a macro is not callable, then its invocation after the
356: initial line macro is interpreted as opaque text, such that
1.60 kristaps 357: .Sq \&.Fl \&Sh
1.55 kristaps 358: produces
1.60 kristaps 359: .Sq Fl \&Sh .
1.57 kristaps 360: .
361: .Pp
1.55 kristaps 362: The
1.57 kristaps 363: .Em Parsable
1.43 kristaps 364: column indicates whether the macro may be followed by further
1.55 kristaps 365: (ostensibly callable) macros. If a macro is not parsable, subsequent
366: macro invocations on the line will be interpreted as opaque text.
1.57 kristaps 367: .
368: .Pp
1.55 kristaps 369: The
1.57 kristaps 370: .Em Scope
1.43 kristaps 371: column, if applicable, describes closure rules.
1.56 kristaps 372: .
373: .
1.57 kristaps 374: .Ss Block full-explicit
1.43 kristaps 375: Multi-line scope closed by an explicit closing macro. All macros
376: contains bodies; only
1.57 kristaps 377: .Pq Sq \&Bf
1.43 kristaps 378: contains a head.
1.57 kristaps 379: .Bd -literal -offset indent
1.50 kristaps 380: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
381: \(lBbody...\(rB
1.43 kristaps 382: \&.Yc
1.57 kristaps 383: .Ed
384: .
385: .Pp
386: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
387: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
388: .It \&Bd Ta \&No Ta \&No Ta closed by \&Ed
389: .It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
390: .It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
391: .It \&Bl Ta \&No Ta \&No Ta closed by \&El
392: .It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
393: .It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
394: .It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
395: .It \&El Ta \&No Ta \&No Ta opened by \&Bl
396: .El
1.56 kristaps 397: .
398: .
1.57 kristaps 399: .Ss Block full-implicit
1.43 kristaps 400: Multi-line scope closed by end-of-file or implicitly by another macro.
1.50 kristaps 401: All macros have bodies; some
1.57 kristaps 402: .Po
403: .Sq \&It \-bullet ,
404: .Sq \-hyphen ,
405: .Sq \-dash ,
406: .Sq \-enum ,
407: .Sq \-item
408: .Pc
1.50 kristaps 409: don't have heads, while
1.57 kristaps 410: .Sq \&It \-column
1.43 kristaps 411: may have multiple heads.
1.57 kristaps 412: .Bd -literal -offset indent
1.50 kristaps 413: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
414: \(lBbody...\(rB
1.57 kristaps 415: .Ed
1.56 kristaps 416: .
1.57 kristaps 417: .Pp
418: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
419: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
420: .It \&It Ta \&No Ta Yes Ta closed by \&It, \&El
421: .It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
422: .It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
423: .It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss
424: .El
1.56 kristaps 425: .
1.57 kristaps 426: .
427: .Ss Block partial-explicit
1.43 kristaps 428: Like block full-explicit, but also with single-line scope. Each
1.50 kristaps 429: has at least a body and, in limited circumstances, a head
1.57 kristaps 430: .Pq So \&Fo Sc , So \&Eo Sc
1.50 kristaps 431: and/or tail
1.57 kristaps 432: .Pq So \&Ec Sc .
433: .Bd -literal -offset indent
1.50 kristaps 434: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
435: \(lBbody...\(rB
436: \&.Yc \(lBtail...\(rB
1.2 kristaps 437:
1.43 kristaps 438: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
1.50 kristaps 439: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.57 kristaps 440: .Ed
441: .
442: .Pp
443: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
444: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.63 ! kristaps 445: .It \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
! 446: .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
1.57 kristaps 447: .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
448: .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
449: .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
450: .It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
451: .It \&Dc Ta Yes Ta Yes Ta opened by \&Do
452: .It \&Do Ta Yes Ta Yes Ta closed by \&Dc
453: .It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
454: .It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
455: .It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
456: .It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
457: .It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
458: .It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
459: .It \&Pc Ta Yes Ta Yes Ta closed by \&Po
460: .It \&Po Ta Yes Ta Yes Ta opened by \&Pc
461: .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo
462: .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc
1.63 ! kristaps 463: .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
! 464: .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
1.57 kristaps 465: .It \&Sc Ta Yes Ta Yes Ta opened by \&So
466: .It \&So Ta Yes Ta Yes Ta closed by \&Sc
467: .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
468: .It \&Xo Ta Yes Ta Yes Ta closed by \&Xc
469: .El
1.56 kristaps 470: .
471: .
1.57 kristaps 472: .Ss Block partial-implicit
1.50 kristaps 473: Like block full-implicit, but with single-line scope closed by
1.57 kristaps 474: .Sx Reserved Characters
1.43 kristaps 475: or end of line.
1.57 kristaps 476: .Bd -literal -offset indent
1.43 kristaps 477: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
1.57 kristaps 478: .Ed
1.56 kristaps 479: .
1.57 kristaps 480: .Pp
481: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
482: .It Em Macro Ta Em Callable Ta Em Parsable
483: .It \&Aq Ta Yes Ta Yes
484: .It \&Bq Ta Yes Ta Yes
485: .It \&Brq Ta Yes Ta Yes
486: .It \&D1 Ta \&No Ta \&Yes
487: .It \&Dl Ta \&No Ta Yes
488: .It \&Dq Ta Yes Ta Yes
489: .It \&Op Ta Yes Ta Yes
490: .It \&Pq Ta Yes Ta Yes
491: .It \&Ql Ta Yes Ta Yes
492: .It \&Qq Ta Yes Ta Yes
493: .It \&Sq Ta Yes Ta Yes
494: .El
1.56 kristaps 495: .
1.57 kristaps 496: .
497: .Ss In-line
1.50 kristaps 498: Closed by
1.57 kristaps 499: .Sx Reserved Characters ,
1.43 kristaps 500: end of line, fixed argument lengths, and/or subsequent macros. In-line
501: macros have only text children. If a number (or inequality) of
1.3 kristaps 502: arguments is
1.57 kristaps 503: .Pq n ,
1.3 kristaps 504: then the macro accepts an arbitrary number of arguments.
1.57 kristaps 505: .Bd -literal -offset indent
1.43 kristaps 506: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
507:
508: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
509:
510: \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
1.57 kristaps 511: .Ed
512: .
513: .Pp
514: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
515: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.63 ! kristaps 516: .It Sx \&%A Ta \&No Ta \&No Ta >0
! 517: .It Sx \&%B Ta \&No Ta \&No Ta >0
! 518: .It Sx \&%C Ta \&No Ta \&No Ta >0
! 519: .It Sx \&%D Ta \&No Ta \&No Ta >0
! 520: .It Sx \&%I Ta \&No Ta \&No Ta >0
! 521: .It Sx \&%J Ta \&No Ta \&No Ta >0
! 522: .It Sx \&%N Ta \&No Ta \&No Ta >0
! 523: .It Sx \&%O Ta \&No Ta \&No Ta >0
! 524: .It Sx \&%P Ta \&No Ta \&No Ta >0
! 525: .It Sx \&%R Ta \&No Ta \&No Ta >0
! 526: .It Sx \&%T Ta \&No Ta \&No Ta >0
! 527: .It Sx \&%V Ta \&No Ta \&No Ta >0
1.57 kristaps 528: .It \&Ad Ta Yes Ta Yes Ta n
529: .It \&An Ta Yes Ta Yes Ta n
530: .It \&Ap Ta Yes Ta Yes Ta 0
531: .It \&Ar Ta Yes Ta Yes Ta n
532: .It \&At Ta Yes Ta Yes Ta 1
533: .It \&Bsx Ta Yes Ta Yes Ta n
534: .It \&Bt Ta \&No Ta \&No Ta 0
535: .It \&Bx Ta Yes Ta Yes Ta n
536: .It \&Cd Ta Yes Ta Yes Ta >0
537: .It \&Cm Ta Yes Ta Yes Ta n
538: .It \&Db Ta \&No Ta \&No Ta 1
539: .It \&Dd Ta \&No Ta \&No Ta >0
540: .It \&Dt Ta \&No Ta \&No Ta n
541: .It \&Dv Ta Yes Ta Yes Ta n
542: .It \&Dx Ta Yes Ta Yes Ta n
543: .It \&Em Ta Yes Ta Yes Ta >0
544: .It \&En Ta \&No Ta \&No Ta 0
545: .It \&Er Ta Yes Ta Yes Ta >0
546: .It \&Es Ta \&No Ta \&No Ta 0
547: .It \&Ev Ta Yes Ta Yes Ta n
1.58 kristaps 548: .It \&Ex Ta \&No Ta \&No Ta n
1.57 kristaps 549: .It \&Fa Ta Yes Ta Yes Ta n
550: .It \&Fd Ta \&No Ta \&No Ta >0
551: .It \&Fl Ta Yes Ta Yes Ta n
552: .It \&Fn Ta Yes Ta Yes Ta >0
553: .It \&Fr Ta \&No Ta \&No Ta n
554: .It \&Ft Ta Yes Ta Yes Ta n
555: .It \&Fx Ta Yes Ta Yes Ta n
556: .It \&Hf Ta \&No Ta \&No Ta n
557: .It \&Ic Ta Yes Ta Yes Ta >0
558: .It \&In Ta \&No Ta \&No Ta n
559: .It \&Lb Ta \&No Ta \&No Ta 1
560: .It \&Li Ta Yes Ta Yes Ta n
561: .It \&Lk Ta Yes Ta Yes Ta n
562: .It \&Lp Ta \&No Ta \&No Ta 0
563: .It \&Ms Ta Yes Ta Yes Ta >0
564: .It \&Mt Ta Yes Ta Yes Ta >0
565: .It \&Nm Ta Yes Ta Yes Ta n
566: .It \&No Ta Yes Ta Yes Ta 0
567: .It \&Ns Ta Yes Ta Yes Ta 0
568: .It \&Nx Ta Yes Ta Yes Ta n
569: .It \&Os Ta \&No Ta \&No Ta n
570: .It \&Ot Ta \&No Ta \&No Ta n
571: .It \&Ox Ta Yes Ta Yes Ta n
572: .It \&Pa Ta Yes Ta Yes Ta n
573: .It \&Pf Ta \&No Ta Yes Ta 1
574: .It \&Pp Ta \&No Ta \&No Ta 0
1.58 kristaps 575: .It \&Rv Ta \&No Ta \&No Ta n
1.57 kristaps 576: .It \&Sm Ta \&No Ta \&No Ta 1
577: .It \&St Ta \&No Ta Yes Ta 1
578: .It \&Sx Ta Yes Ta Yes Ta >0
579: .It \&Sy Ta Yes Ta Yes Ta >0
580: .It \&Tn Ta Yes Ta Yes Ta >0
581: .It \&Ud Ta \&No Ta \&No Ta 0
582: .It \&Ux Ta Yes Ta Yes Ta n
583: .It \&Va Ta Yes Ta Yes Ta n
584: .It \&Vt Ta Yes Ta Yes Ta >0
585: .It \&Xr Ta Yes Ta Yes Ta >0, <3
586: .It \&br Ta \&No Ta \&No Ta 0
587: .It \&sp Ta \&No Ta \&No Ta 1
588: .El
1.56 kristaps 589: .
590: .
1.63 ! kristaps 591: .Sh REFERENCE
! 592: This section is a canonical reference of all macros, arranged
! 593: alphabetically. For the scoping of individual macros, see
! 594: .Sx MACRO SYNTAX .
! 595: .
! 596: .Ss \&%A
! 597: Author name of an
! 598: .Sx \&Rs
! 599: block. Multiple authors should each be accorded their own
! 600: .Sq \%%A
! 601: line.
! 602: .Pp
! 603: Author names should be ordered with full or abbreviated forename(s)
! 604: first, then full surname.
! 605: .Ss \&%B
! 606: Book title of an
! 607: .Sx \&Rs
! 608: block. This macro may also be used in a non-bibliographic context when
! 609: referring to book titles.
! 610: .Ss \&%C
! 611: Publication city or location of an
! 612: .Sx \&Rs
! 613: block.
! 614: .Pp
! 615: .Em Compatibility remark :
! 616: this macro is not implemented in
! 617: .Xr groff 1 .
! 618: .Ss \&%D
! 619: Publication date of an
! 620: .Sx \&Rs
! 621: block. This should follow the canonical syntax for
! 622: .Sx Dates .
! 623: .Ss \&%I
! 624: Publisher or issuer name of an
! 625: .Sx \&Rs
! 626: block.
! 627: .Ss \&%J
! 628: Journal name of an
! 629: .Sx \&Rs
! 630: block.
! 631: .Ss \&%N
! 632: Issue number (usually for journals) of an
! 633: .Sx \&Rs
! 634: block.
! 635: .Ss \&%O
! 636: Optional information of an
! 637: .Sx \&Rs
! 638: block.
! 639: .Ss \&%P
! 640: Book or journal page number of an
! 641: .Sx \&Rs
! 642: block.
! 643: .Ss \&%Q
! 644: Institutional author (school, government, etc.) of an
! 645: .Sx \&Rs
! 646: block. Multiple institutional authors should each be accorded their own
! 647: .Sq \&%Q
! 648: line.
! 649: .Ss \&%R
! 650: Technical report name of an
! 651: .Sx \&Rs
! 652: block.
! 653: .Ss \&%T
! 654: Article title of an
! 655: .Sx \&Rs
! 656: block. This macro may also be used in a non-bibliographical context
! 657: when referring to article titles.
! 658: .Ss \&%V
! 659: Volume number of an
! 660: .Sx \&Rs
! 661: block.
! 662: .Ss \&Ac
! 663: Closes an
! 664: .Sx \&Ao
! 665: block. Does not have any tail arguments.
! 666: .Ss \&Ad
! 667: Address construct: usually in the context of an computational address in
! 668: memory, not a physical (post) address.
! 669: .Pp
! 670: Example:
! 671: .Bd -literal -offset indent
! 672: \&.Ad [0,$]
! 673: \&.Ad 0x00000000
! 674: .Ed
! 675: .Ss \&An
! 676: .Ss \&Ao
! 677: Begins a block enclosed by angled brackets. Does not have any head
! 678: arguments.
! 679: .Pp
! 680: Example:
! 681: .Bd -literal -offset indent
! 682: \&.Fl -key= Ns Ao Ar val Ac
! 683: .Ed
! 684: .Pp
! 685: Note that, although this is overwhelmingly used to note URIs, the
! 686: .Sx \&Lk
! 687: and
! 688: .Sx \&Mt
! 689: macros are better suited for this purpose.
! 690: .Ss \&Ap
! 691: .Ss \&Aq
! 692: .Ss \&Ar
! 693: .Ss \&At
! 694: .Ss \&Bc
! 695: .Ss \&Bd
! 696: .Ss \&Bf
! 697: .Ss \&Bk
! 698: .Ss \&Bl
! 699: .Ss \&Bo
! 700: .Ss \&Bq
! 701: .Ss \&Brc
! 702: .Ss \&Bro
! 703: .Ss \&Brq
! 704: .Ss \&Bsx
! 705: .Ss \&Bt
! 706: .Ss \&Bx
! 707: .Ss \&Cd
! 708: .Ss \&Cm
! 709: .Ss \&D1
! 710: .Ss \&Db
! 711: .Ss \&Dc
! 712: .Ss \&Dd
! 713: .Ss \&Dl
! 714: .Ss \&Do
! 715: .Ss \&Dq
! 716: .Ss \&Dt
! 717: .Ss \&Dv
! 718: .Ss \&Dx
! 719: .Ss \&Ec
! 720: .Ss \&Ed
! 721: .Ss \&Ef
! 722: .Ss \&Ek
! 723: .Ss \&El
! 724: .Ss \&Em
! 725: .Ss \&En
! 726: .Ss \&Eo
! 727: .Ss \&Er
! 728: .Ss \&Es
! 729: .Ss \&Ev
! 730: .Ss \&Ex
! 731: .Ss \&Fa
! 732: .Ss \&Fc
! 733: .Ss \&Fd
! 734: .Ss \&Fl
! 735: .Ss \&Fn
! 736: .Ss \&Fo
! 737: .Ss \&Fr
! 738: .Ss \&Ft
! 739: .Ss \&Fx
! 740: .Ss \&Hf
! 741: .Ss \&Ic
! 742: .Ss \&In
! 743: .Ss \&It
! 744: .Ss \&Lb
! 745: .Ss \&Li
! 746: .Ss \&Lk
! 747: .Ss \&Lp
! 748: .Ss \&Ms
! 749: .Ss \&Mt
! 750: .Ss \&Nd
! 751: .Ss \&Nm
! 752: .Ss \&No
! 753: .Ss \&Ns
! 754: .Ss \&Nx
! 755: .Ss \&Oc
! 756: .Ss \&Oo
! 757: .Ss \&Op
! 758: .Ss \&Os
! 759: .Ss \&Ot
! 760: .Ss \&Ox
! 761: .Ss \&Pa
! 762: .Ss \&Pc
! 763: .Ss \&Pf
! 764: .Ss \&Po
! 765: .Ss \&Pp
! 766: .Ss \&Pq
! 767: .Ss \&Qc
! 768: .Ss \&Ql
! 769: .Ss \&Qo
! 770: .Ss \&Qq
! 771: .Ss \&Re
! 772: Closes a
! 773: .Sx \&Rs
! 774: block. Does not have any tail arguments.
! 775: .Ss \&Rs
! 776: Begins a bibliographic
! 777: .Pq Dq reference
! 778: block. Does not have any head arguments. The block macro and may only
! 779: contain
! 780: .Sx \&%A ,
! 781: .Sx \&%B ,
! 782: .Sx \&%C ,
! 783: .Sx \&%D ,
! 784: .Sx \&%I ,
! 785: .Sx \&%J ,
! 786: .Sx \&%N ,
! 787: .Sx \&%O ,
! 788: .Sx \&%P ,
! 789: .Sx \&%Q ,
! 790: .Sx \&%R ,
! 791: .Sx \&%T ,
! 792: and
! 793: .Sx \&%V
! 794: child macros (at least one must be specified).
! 795: .Pp
! 796: Example:
! 797: .Bd -literal -offset indent
! 798: \&.Rs
! 799: \&.%A J. E. Hopcroft
! 800: \&.%A J. D. Ullman
! 801: \&.%B Introduction to Automata Theory, Languages, and Computation
! 802: \&.%I Addison-Wesley
! 803: \&.%C Reading, Massachusettes
! 804: \&.%D 1979
! 805: \&.Re
! 806: .Ed
! 807: .Pp
! 808: If an
! 809: .Sx \&Rs
! 810: block is used within a SEE ALSO section, a vertical space is asserted
! 811: before the rendered output, else the block continues on the current
! 812: line.
! 813: .Ss \&Rv
! 814: .Ss \&Sc
! 815: .Ss \&Sh
! 816: .Ss \&Sm
! 817: .Ss \&So
! 818: .Ss \&Sq
! 819: .Ss \&Ss
! 820: .Ss \&St
! 821: .Ss \&Sx
! 822: .Ss \&Sy
! 823: .Ss \&Tn
! 824: .Ss \&Ud
! 825: .Ss \&Ux
! 826: .Ss \&Va
! 827: .Ss \&Vt
! 828: .Ss \&Xc
! 829: .Ss \&Xo
! 830: .Ss \&Xr
! 831: .Ss \&br
! 832: .Ss \&sp
! 833: .
! 834: .
1.4 kristaps 835: .Sh COMPATIBILITY
1.28 kristaps 836: This section documents compatibility with other roff implementations, at
1.50 kristaps 837: this time limited to
1.57 kristaps 838: .Xr groff 1 .
1.50 kristaps 839: The term
1.57 kristaps 840: .Qq historic groff
1.50 kristaps 841: refers to those versions before the
1.57 kristaps 842: .Pa doc.tmac
1.50 kristaps 843: file re-write
1.57 kristaps 844: .Pq somewhere between 1.15 and 1.19 .
845: .
846: .Pp
847: .Bl -dash -compact
848: .It
1.61 kristaps 849: Negative scaling units are now truncated to zero instead of creating
850: interesting conditions, such as with
851: .Sq \&sp -1i .
852: Furthermore, the
853: .Sq f
854: scaling unit, while accepted, is rendered as the default unit.
855: .It
1.51 kristaps 856: The
1.57 kristaps 857: .Sq \-split
1.51 kristaps 858: or
1.57 kristaps 859: .Sq \-nosplit
1.51 kristaps 860: argument to
1.57 kristaps 861: .Sq \&An
1.51 kristaps 862: applies to the whole document, not just to the current section as it
863: does in groff.
1.57 kristaps 864: .It
1.48 kristaps 865: In quoted literals, groff allowed pair-wise double-quotes to produce a
866: standalone double-quote in formatted output. This idiosyncratic
867: behaviour is no longer applicable.
1.57 kristaps 868: .It
1.50 kristaps 869: The
1.57 kristaps 870: .Sq \&sp
1.45 kristaps 871: macro does not accept negative numbers.
1.57 kristaps 872: .It
1.35 kristaps 873: Blocks of whitespace are stripped from both macro and free-form text
874: lines (except when in literal mode), while groff would retain whitespace
875: in free-form text lines.
1.57 kristaps 876: .It
1.28 kristaps 877: Historic groff has many un-callable macros. Most of these (excluding
878: some block-level macros) are now callable, conforming to the
879: non-historic groff version.
1.57 kristaps 880: .It
1.50 kristaps 881: The vertical bar
1.57 kristaps 882: .Sq \(ba
1.28 kristaps 883: made historic groff
1.57 kristaps 884: .Qq go orbital
1.28 kristaps 885: but is a proper delimiter in this implementation.
1.57 kristaps 886: .It
887: .Sq \&It \-nested
1.28 kristaps 888: is assumed for all lists (it wasn't in historic groff): any list may be
889: nested and
1.57 kristaps 890: .Sq \-enum
1.4 kristaps 891: lists will restart the sequence only for the sub-list.
1.57 kristaps 892: .It
893: .Sq \&It \-column
1.21 kristaps 894: syntax where column widths may be preceded by other arguments (instead
1.4 kristaps 895: of proceeded) is not supported.
1.57 kristaps 896: .It
1.50 kristaps 897: The
1.57 kristaps 898: .Sq \&At
1.4 kristaps 899: macro only accepts a single parameter.
1.57 kristaps 900: .It
1.4 kristaps 901: Some manuals use
1.57 kristaps 902: .Sq \&Li
1.4 kristaps 903: incorrectly by following it with a reserved character and expecting the
904: delimiter to render. This is not supported.
1.57 kristaps 905: .It
1.50 kristaps 906: In groff, the
1.57 kristaps 907: .Sq \&Fo
1.41 kristaps 908: macro only produces the first parameter. This is no longer the case.
1.57 kristaps 909: .El
1.56 kristaps 910: .
911: .
1.2 kristaps 912: .Sh SEE ALSO
1.57 kristaps 913: .Xr mandoc 1 ,
914: .Xr mandoc_char 7
1.56 kristaps 915: .
916: .
1.2 kristaps 917: .Sh AUTHORS
918: The
1.57 kristaps 919: .Nm
1.50 kristaps 920: reference was written by
1.57 kristaps 921: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.56 kristaps 922: .
923: .
1.5 kristaps 924: .Sh CAVEATS
1.28 kristaps 925: There are many ambiguous parts of mdoc.
1.57 kristaps 926: .
927: .Pp
928: .Bl -dash -compact
929: .It
930: .Sq \&Fa
1.50 kristaps 931: should be
1.57 kristaps 932: .Sq \&Va
1.5 kristaps 933: as function arguments are variables.
1.57 kristaps 934: .It
935: .Sq \&Ft
1.5 kristaps 936: should be
1.57 kristaps 937: .Sq \&Vt
1.5 kristaps 938: as function return types are still types. Furthermore, the
1.57 kristaps 939: .Sq \&Ft
1.5 kristaps 940: should be removed and
1.57 kristaps 941: .Sq \&Fo ,
1.5 kristaps 942: which ostensibly follows it, should follow the same convention as
1.57 kristaps 943: .Sq \&Va .
944: .It
945: .Sq \&Va
1.5 kristaps 946: should formalise that only one or two arguments are acceptable: a
1.21 kristaps 947: variable name and optional, preceding type.
1.57 kristaps 948: .It
949: .Sq \&Fd
1.5 kristaps 950: is ambiguous. It's commonly used to indicate an include file in the
1.50 kristaps 951: synopsis section.
1.57 kristaps 952: .Sq \&In
1.5 kristaps 953: should be used, instead.
1.57 kristaps 954: .It
1.5 kristaps 955: Only the
1.57 kristaps 956: .Sq \-literal
1.5 kristaps 957: argument to
1.57 kristaps 958: .Sq \&Bd
1.5 kristaps 959: makes sense. The remaining ones should be removed.
1.57 kristaps 960: .It
1.50 kristaps 961: The
1.57 kristaps 962: .Sq \&Xo
1.5 kristaps 963: and
1.57 kristaps 964: .Sq \&Xc
1.5 kristaps 965: macros should be deprecated.
1.57 kristaps 966: .It
1.5 kristaps 967: The
1.57 kristaps 968: .Sq \&Dt
1.5 kristaps 969: macro lacks clarity. It should be absolutely clear which title will
970: render when formatting the manual page.
1.57 kristaps 971: .It
1.6 kristaps 972: A
1.57 kristaps 973: .Sq \&Lx
1.50 kristaps 974: should be provided for Linux (\(`a la
1.57 kristaps 975: .Sq \&Ox ,
976: .Sq \&Nx
1.6 kristaps 977: etc.).
1.57 kristaps 978: .It
1.14 kristaps 979: There's no way to refer to references in
1.57 kristaps 980: .Sq \&Rs/Re
1.14 kristaps 981: blocks.
1.57 kristaps 982: .It
1.54 kristaps 983: The \-split and \-nosplit dictates via
1.57 kristaps 984: .Sq \&An
1.54 kristaps 985: are re-set when entering and leaving the AUTHORS section.
1.57 kristaps 986: .El
1.56 kristaps 987: .
CVSweb