Annotation of src/usr.bin/mandoc/mdoc.7, Revision 1.13
1.13 ! schwarze 1: .\" $Id: mdoc.7,v 1.12 2009/08/22 15:44:02 schwarze Exp $
1.1 kristaps 2: .\"
1.2 schwarze 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.2 schwarze 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.2 schwarze 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.9 schwarze 16: .\"
1.13 ! schwarze 17: .Dd $Mdocdate: August 22 2009 $
1.2 schwarze 18: .Dt MDOC 7
1.1 kristaps 19: .Os
1.8 schwarze 20: .\" SECTION---------------------------------------------
1.1 kristaps 21: .Sh NAME
22: .Nm mdoc
23: .Nd mdoc language reference
1.8 schwarze 24: .\" SECTION---------------------------------------------
1.1 kristaps 25: .Sh DESCRIPTION
26: The
27: .Nm mdoc
1.9 schwarze 28: language is used to format
29: .Bx
1.1 kristaps 30: .Ux
1.8 schwarze 31: manuals. In this reference document, we describe its syntax, structure,
32: and usage. Our reference implementation is
1.3 schwarze 33: .Xr mandoc 1 .
34: The
35: .Sx COMPATIBILITY
1.9 schwarze 36: section describes compatibility with
1.3 schwarze 37: .Xr groff 1 .
1.8 schwarze 38: .\" PARAGRAPH------------
1.1 kristaps 39: .Pp
40: An
41: .Nm
42: document follows simple rules: lines beginning with the control
1.9 schwarze 43: character
1.1 kristaps 44: .Sq \.
45: are parsed for macros. Other lines are interpreted within the scope of
46: prior macros:
1.8 schwarze 47: .Bd -literal -offset indent
1.1 kristaps 48: \&.Sh Macro lines change control state.
49: Other lines are interpreted within the current state.
50: .Ed
1.8 schwarze 51: .\" SECTION---------------------------------------------
1.9 schwarze 52: .Sh LANGUAGE SYNTAX
1.1 kristaps 53: .Nm
54: documents may contain only graphable 7-bit ASCII characters, the space
1.8 schwarze 55: character, and, in certain circumstances, the tab character. All
56: manuals must have
57: .Ux
1.9 schwarze 58: line terminators.
1.8 schwarze 59: .\" SUB-SECTION----------------------
1.4 schwarze 60: .Ss Comments
1.8 schwarze 61: Text following a
62: .Sq \e" ,
63: whether in a macro or free-form text line, is ignored to the end of
64: line. A macro line with only a control character and comment escape,
65: .Sq \&.\e" ,
66: is also ignored.
67: .\" SUB-SECTION----------------------
1.1 kristaps 68: .Ss Reserved Characters
69: Within a macro line, the following characters are reserved:
1.8 schwarze 70: .Bl -tag -width Ds -offset indent -compact
1.1 kristaps 71: .It \&.
72: .Pq period
73: .It \&,
74: .Pq comma
75: .It \&:
76: .Pq colon
77: .It \&;
78: .Pq semicolon
79: .It \&(
80: .Pq left-parenthesis
81: .It \&)
82: .Pq right-parenthesis
83: .It \&[
84: .Pq left-bracket
85: .It \&]
86: .Pq right-bracket
87: .It \&?
88: .Pq question
89: .It \&!
1.9 schwarze 90: .Pq exclamation
1.3 schwarze 91: .It \&|
1.9 schwarze 92: .Pq vertical bar
1.1 kristaps 93: .El
1.8 schwarze 94: .\" PARAGRAPH------------
1.1 kristaps 95: .Pp
96: Use of reserved characters is described in
1.8 schwarze 97: .Sx MACRO SYNTAX .
98: For general use in macro lines, these characters must either be escaped
99: with a non-breaking space
1.1 kristaps 100: .Pq Sq \e&
1.9 schwarze 101: or, if applicable, an appropriate escape sequence used.
1.8 schwarze 102: .\" SUB-SECTION----------------------
1.1 kristaps 103: .Ss Special Characters
1.8 schwarze 104: Special characters may occur in both macro and free-form lines.
105: Sequences begin with the escape character
1.1 kristaps 106: .Sq \e
1.9 schwarze 107: followed by either an open-parenthesis
1.1 kristaps 108: .Sq \&(
109: for two-character sequences; an open-bracket
110: .Sq \&[
111: for n-character sequences (terminated at a close-bracket
112: .Sq \&] ) ;
1.8 schwarze 113: or a single one-character sequence. See
1.13 ! schwarze 114: .Xr mandoc_char 7
1.9 schwarze 115: for a complete list. Examples include
116: .Sq \e(em
117: .Pq em-dash
118: and
1.8 schwarze 119: .Sq \ee
120: .Pq back-slash .
1.13 ! schwarze 121: .\" SUB-SECTION----------------------
! 122: .Ss Text Decoration
! 123: Terms may be text-decorated using the
1.7 schwarze 124: .Sq \ef
1.8 schwarze 125: escape followed by an indicator: B (bold), I, (italic), or P and R
1.13 ! schwarze 126: (Roman, or reset). This form is not recommended for
! 127: .Nm ,
! 128: which encourages semantic, not presentation, annotation.
! 129: .\" SUB-SECTION----------------------
! 130: .Ss Predefined Strings
! 131: Historically,
! 132: .Xr groff 1
! 133: also defined a set of package-specific
! 134: .Dq predefined strings ,
! 135: which, like
! 136: .Sx Special Characters ,
! 137: demark special output characters and strings by way of input codes.
! 138: Predefined strings are escaped with the slash-asterisk,
! 139: .Sq \e* :
! 140: single-character
! 141: .Sq \e*X ,
! 142: two-character
! 143: .Sq \e*(XX ,
! 144: and N-character
! 145: .Sq \e*[N] .
! 146: See
! 147: .Xr mandoc_char 7
! 148: for a complete list. Examples include
! 149: .Sq \e*(Am
! 150: .Pq ampersand
! 151: and
! 152: .Sq \e*(Ba
! 153: .Pq vertical bar .
1.8 schwarze 154: .\" SUB-SECTION----------------------
1.7 schwarze 155: .Ss Whitespace
1.9 schwarze 156: In non-literal free-form lines, consecutive blocks of whitespace are
157: pruned from input and added later in the output filter, if applicable:
158: .Bd -literal -offset indent
159: These spaces are pruned from input.
160: \&.Bd \-literal
161: These are not.
162: \&.Ed
163: .Ed
164: .\" PARAGRAPH------------
165: .Pp
166: In macro lines, whitespace delimits arguments and is discarded. If
167: arguments are quoted, whitespace within the quotes is retained.
1.8 schwarze 168: .\" PARAGRAPH------------
169: .Pp
1.9 schwarze 170: Blank lines are only permitted within literal contexts, as are lines
171: containing only whitespace. Tab characters are only acceptable when
172: delimiting
1.8 schwarze 173: .Sq \&Bl \-column
1.9 schwarze 174: or when in a literal context.
175: .\" SUB-SECTION----------------------
176: .Ss Quotation
177: Macro arguments may be quoted with a double-quote to group
178: space-delimited terms or to retain blocks of whitespace. A quoted
179: argument begins with a double-quote preceded by whitespace. The next
180: double-quote not pair-wise adjacent to another double-quote terminates
181: the literal, regardless of surrounding whitespace.
182: .\" PARAGRAPH------------
183: .Pp
184: This produces tokens
185: .Sq a" ,
186: .Sq b c ,
187: .Sq de ,
188: and
189: .Sq fg" .
190: Note that any quoted term, be it argument or macro, is indiscriminately
191: considered literal text. Thus, the following produces
192: .Sq \&Em a :
193: .Bd -literal -offset indent
194: \&.Em "Em a"
195: .Ed
196: .\" PARAGRAPH------------
197: .Pp
198: In free-form mode, quotes are regarded as opaque text.
1.8 schwarze 199: .\" SECTION---------------------------------------------
200: .Sh MANUAL STRUCTURE
1.6 schwarze 201: Each
202: .Nm
1.9 schwarze 203: document must begin with a document prologue, containing, in order,
1.8 schwarze 204: .Sq \&Dd ,
205: .Sq \&Dt ,
1.6 schwarze 206: and
1.9 schwarze 207: .Sq \&Os ,
208: then the NAME section containing at least one
209: .Sq \&Nm
210: followed by
211: .Sq \&Nd :
1.8 schwarze 212: .Bd -literal -offset indent
213: \&.Dd $\&Mdocdate$
214: \&.Dt mdoc 7
215: \&.Os
216: \&.Sh NAME
217: \&.Nm mdoc
218: \&.Nd mdoc language reference
219: .Ed
220: .\" PARAGRAPH------------
221: .Pp
222: Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
1.9 schwarze 223: but non-compulsory.
1.8 schwarze 224: .\" SECTION---------------------------------------------
225: .Sh MACRO SYNTAX
1.9 schwarze 226: Every line beginning with the control character
1.8 schwarze 227: .Sq \.
1.9 schwarze 228: is processed for macros, two- or three-character sequences.
1.8 schwarze 229: .\" PARAGRAPH------------
1.6 schwarze 230: .Pp
1.9 schwarze 231: The syntax of a macro depends on its classification. In this section,
232: .Sq \-arg
1.8 schwarze 233: refers to macro arguments, which may be followed by zero or more
234: .Sq parm
235: parameters;
236: .Sq \&Yo
237: opens the scope of a macro; and if specified,
238: .Sq \&Yc
239: closes it out.
240: .\" PARAGRAPH------------
1.1 kristaps 241: .Pp
1.8 schwarze 242: The
243: .Em Callable
244: column indicates that the macro may be called subsequent to the initial
1.9 schwarze 245: line-macro. The
246: .Em Parsable
1.8 schwarze 247: column indicates whether the macro may be followed by further
248: (ostensibly callable) macros. The
249: .Em Scope
250: column, if applicable, describes closure rules.
251: .\" SUB-SECTION----------------------
252: .Ss Block full-explicit
253: Multi-line scope closed by an explicit closing macro. All macros
254: contains bodies; only
255: .Pq Sq \&Bf
256: contains a head.
257: .Bd -literal -offset indent
1.9 schwarze 258: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
259: \(lBbody...\(rB
1.1 kristaps 260: \&.Yc
261: .Ed
1.8 schwarze 262: .\" PARAGRAPH------------
1.1 kristaps 263: .Pp
1.8 schwarze 264: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
265: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
266: .It \&Bd Ta \&No Ta \&No Ta closed by \&Ed
1.9 schwarze 267: .It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
268: .It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
269: .It \&Bl Ta \&No Ta \&No Ta closed by \&El
1.8 schwarze 270: .It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
271: .It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
272: .It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
1.9 schwarze 273: .It \&El Ta \&No Ta \&No Ta opened by \&Bl
1.8 schwarze 274: .El
275: .\" SUB-SECTION----------------------
1.1 kristaps 276: .Ss Block full-implicit
1.8 schwarze 277: Multi-line scope closed by end-of-file or implicitly by another macro.
1.9 schwarze 278: All macros have bodies; some
1.1 kristaps 279: .Po
1.9 schwarze 280: .Sq \&It \-bullet ,
281: .Sq \-hyphen ,
1.1 kristaps 282: .Sq \-dash ,
283: .Sq \-enum ,
1.9 schwarze 284: .Sq \-item
1.1 kristaps 285: .Pc
1.9 schwarze 286: don't have heads, while
1.8 schwarze 287: .Sq \&It \-column
288: may have multiple heads.
289: .Bd -literal -offset indent
1.9 schwarze 290: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
291: \(lBbody...\(rB
1.8 schwarze 292: .Ed
293: .\" PARAGRAPH------------
1.1 kristaps 294: .Pp
1.8 schwarze 295: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
296: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.9 schwarze 297: .It \&It Ta \&No Ta Yes Ta closed by \&It, \&El
1.8 schwarze 298: .It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
299: .It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
300: .It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss
1.1 kristaps 301: .El
1.8 schwarze 302: .\" SUB-SECTION----------------------
303: .Ss Block partial-explicit
304: Like block full-explicit, but also with single-line scope. Each
1.9 schwarze 305: has at least a body and, in limited circumstances, a head
1.8 schwarze 306: .Pq So \&Fo Sc , So \&Eo Sc
1.9 schwarze 307: and/or tail
1.8 schwarze 308: .Pq So \&Ec Sc .
309: .Bd -literal -offset indent
1.9 schwarze 310: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
311: \(lBbody...\(rB
312: \&.Yc \(lBtail...\(rB
1.8 schwarze 313:
314: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
1.9 schwarze 315: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.8 schwarze 316: .Ed
317: .\" PARAGRAPH------------
1.1 kristaps 318: .Pp
1.8 schwarze 319: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
1.1 kristaps 320: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.9 schwarze 321: .It \&Ac Ta Yes Ta Yes Ta opened by \&Ao
1.8 schwarze 322: .It \&Ao Ta Yes Ta Yes Ta closed by \&Ac
323: .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
324: .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
1.9 schwarze 325: .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
326: .It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
327: .It \&Dc Ta Yes Ta Yes Ta opened by \&Do
1.8 schwarze 328: .It \&Do Ta Yes Ta Yes Ta closed by \&Dc
1.9 schwarze 329: .It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
330: .It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
331: .It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
332: .It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
1.8 schwarze 333: .It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
334: .It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
1.9 schwarze 335: .It \&Pc Ta Yes Ta Yes Ta closed by \&Po
336: .It \&Po Ta Yes Ta Yes Ta opened by \&Pc
1.8 schwarze 337: .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo
338: .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc
339: .It \&Re Ta \&No Ta \&No Ta opened by \&Rs
340: .It \&Rs Ta \&No Ta \&No Ta closed by \&Re
1.9 schwarze 341: .It \&Sc Ta Yes Ta Yes Ta opened by \&So
342: .It \&So Ta Yes Ta Yes Ta closed by \&Sc
343: .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
344: .It \&Xo Ta Yes Ta Yes Ta closed by \&Xc
1.1 kristaps 345: .El
1.8 schwarze 346: .\" SUB-SECTION----------------------
1.1 kristaps 347: .Ss Block partial-implicit
1.9 schwarze 348: Like block full-implicit, but with single-line scope closed by
349: .Sx Reserved Characters
1.8 schwarze 350: or end of line.
351: .Bd -literal -offset indent
352: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
353: .Ed
354: .\" PARAGRAPH------------
1.1 kristaps 355: .Pp
1.8 schwarze 356: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
1.1 kristaps 357: .It Em Macro Ta Em Callable Ta Em Parsable
1.8 schwarze 358: .It \&Aq Ta Yes Ta Yes
359: .It \&Bq Ta Yes Ta Yes
1.9 schwarze 360: .It \&Brq Ta Yes Ta Yes
361: .It \&D1 Ta \&No Ta \&Yes
362: .It \&Dl Ta \&No Ta Yes
1.8 schwarze 363: .It \&Dq Ta Yes Ta Yes
1.9 schwarze 364: .It \&Op Ta Yes Ta Yes
1.8 schwarze 365: .It \&Pq Ta Yes Ta Yes
1.9 schwarze 366: .It \&Ql Ta Yes Ta Yes
1.8 schwarze 367: .It \&Qq Ta Yes Ta Yes
368: .It \&Sq Ta Yes Ta Yes
369: .El
370: .\" SUB-SECTION----------------------
371: .Ss In-line
1.9 schwarze 372: Closed by
1.8 schwarze 373: .Sx Reserved Characters ,
374: end of line, fixed argument lengths, and/or subsequent macros. In-line
375: macros have only text children. If a number (or inequality) of
1.1 kristaps 376: arguments is
1.9 schwarze 377: .Pq n ,
1.1 kristaps 378: then the macro accepts an arbitrary number of arguments.
1.8 schwarze 379: .Bd -literal -offset indent
380: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
381:
382: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
383:
384: \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
385: .Ed
386: .\" PARAGRAPH------------
1.1 kristaps 387: .Pp
1.8 schwarze 388: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
1.1 kristaps 389: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.8 schwarze 390: .It \&%A Ta \&No Ta \&No Ta >0
391: .It \&%B Ta \&No Ta \&No Ta >0
392: .It \&%C Ta \&No Ta \&No Ta >0
393: .It \&%D Ta \&No Ta \&No Ta >0
394: .It \&%I Ta \&No Ta \&No Ta >0
395: .It \&%J Ta \&No Ta \&No Ta >0
396: .It \&%N Ta \&No Ta \&No Ta >0
397: .It \&%O Ta \&No Ta \&No Ta >0
398: .It \&%P Ta \&No Ta \&No Ta >0
399: .It \&%R Ta \&No Ta \&No Ta >0
400: .It \&%T Ta \&No Ta \&No Ta >0
401: .It \&%V Ta \&No Ta \&No Ta >0
1.9 schwarze 402: .It \&Ad Ta Yes Ta Yes Ta n
403: .It \&An Ta Yes Ta Yes Ta n
404: .It \&Ap Ta Yes Ta Yes Ta 0
405: .It \&Ar Ta Yes Ta Yes Ta n
1.8 schwarze 406: .It \&At Ta Yes Ta Yes Ta 1
407: .It \&Bsx Ta Yes Ta Yes Ta n
1.9 schwarze 408: .It \&Bt Ta \&No Ta \&No Ta 0
1.8 schwarze 409: .It \&Bx Ta Yes Ta Yes Ta n
1.10 schwarze 410: .It \&Cd Ta Yes Ta Yes Ta >0
1.9 schwarze 411: .It \&Cm Ta Yes Ta Yes Ta n
1.8 schwarze 412: .It \&Db Ta \&No Ta \&No Ta 1
1.9 schwarze 413: .It \&Dd Ta \&No Ta \&No Ta >0
414: .It \&Dt Ta \&No Ta \&No Ta n
415: .It \&Dv Ta Yes Ta Yes Ta n
416: .It \&Dx Ta Yes Ta Yes Ta n
1.8 schwarze 417: .It \&Em Ta Yes Ta Yes Ta >0
1.9 schwarze 418: .It \&En Ta \&No Ta \&No Ta 0
419: .It \&Er Ta Yes Ta Yes Ta >0
420: .It \&Es Ta \&No Ta \&No Ta 0
421: .It \&Ev Ta Yes Ta Yes Ta n
422: .It \&Ex Ta \&No Ta \&No Ta 0
423: .It \&Fa Ta Yes Ta Yes Ta n
424: .It \&Fd Ta \&No Ta \&No Ta >0
425: .It \&Fl Ta Yes Ta Yes Ta n
426: .It \&Fn Ta Yes Ta Yes Ta >0
427: .It \&Fr Ta \&No Ta \&No Ta n
428: .It \&Ft Ta Yes Ta Yes Ta n
1.8 schwarze 429: .It \&Fx Ta Yes Ta Yes Ta n
1.9 schwarze 430: .It \&Hf Ta \&No Ta \&No Ta n
431: .It \&Ic Ta Yes Ta Yes Ta >0
432: .It \&In Ta \&No Ta \&No Ta n
433: .It \&Lb Ta \&No Ta \&No Ta 1
434: .It \&Li Ta Yes Ta Yes Ta n
435: .It \&Lk Ta Yes Ta Yes Ta n
436: .It \&Lp Ta \&No Ta \&No Ta 0
1.8 schwarze 437: .It \&Ms Ta Yes Ta Yes Ta >0
1.9 schwarze 438: .It \&Mt Ta Yes Ta Yes Ta >0
439: .It \&Nm Ta Yes Ta Yes Ta n
1.8 schwarze 440: .It \&No Ta Yes Ta Yes Ta 0
441: .It \&Ns Ta Yes Ta Yes Ta 0
442: .It \&Nx Ta Yes Ta Yes Ta n
1.9 schwarze 443: .It \&Os Ta \&No Ta \&No Ta n
444: .It \&Ot Ta \&No Ta \&No Ta n
1.8 schwarze 445: .It \&Ox Ta Yes Ta Yes Ta n
1.9 schwarze 446: .It \&Pa Ta Yes Ta Yes Ta n
1.8 schwarze 447: .It \&Pf Ta \&No Ta Yes Ta 1
1.9 schwarze 448: .It \&Pp Ta \&No Ta \&No Ta 0
449: .It \&Rv Ta \&No Ta \&No Ta 0
1.8 schwarze 450: .It \&Sm Ta \&No Ta \&No Ta 1
1.9 schwarze 451: .It \&St Ta \&No Ta Yes Ta 1
1.8 schwarze 452: .It \&Sx Ta Yes Ta Yes Ta >0
453: .It \&Sy Ta Yes Ta Yes Ta >0
454: .It \&Tn Ta Yes Ta Yes Ta >0
1.9 schwarze 455: .It \&Ud Ta \&No Ta \&No Ta 0
1.8 schwarze 456: .It \&Ux Ta Yes Ta Yes Ta n
1.9 schwarze 457: .It \&Va Ta Yes Ta Yes Ta n
458: .It \&Vt Ta Yes Ta Yes Ta >0
459: .It \&Xr Ta Yes Ta Yes Ta >0, <3
460: .It \&br Ta \&No Ta \&No Ta 0
461: .It \&sp Ta \&No Ta \&No Ta 1
1.1 kristaps 462: .El
1.8 schwarze 463: .\" SECTION---------------------------------------------
1.1 kristaps 464: .Sh COMPATIBILITY
1.3 schwarze 465: This section documents compatibility with other roff implementations, at
1.9 schwarze 466: this time limited to
1.3 schwarze 467: .Xr groff 1 .
1.9 schwarze 468: The term
1.3 schwarze 469: .Qq historic groff
1.9 schwarze 470: refers to those versions before the
1.3 schwarze 471: .Pa doc.tmac
1.9 schwarze 472: file re-write
1.3 schwarze 473: .Pq somewhere between 1.15 and 1.19 .
1.8 schwarze 474: .\" PARAGRAPH------------
1.1 kristaps 475: .Pp
476: .Bl -dash -compact
1.12 schwarze 477: .\" LIST-ITEM
478: .It
479: The POSIX.1
480: .Sq \&St
481: macro produce
482: .Dq POSIX
483: instead of
484: .Dq POSIX.1 .
1.11 schwarze 485: .\" LIST-ITEM
486: .It
487: The
488: .Sq \-split
489: or
490: .Sq \-nosplit
491: argument to
492: .Sq \&An
493: applies to the whole document, not just to the current section as it
494: does in groff.
1.1 kristaps 495: .\" LIST-ITEM
496: .It
1.9 schwarze 497: In quoted literals, groff allowed pair-wise double-quotes to produce a
498: standalone double-quote in formatted output. This idiosyncratic
499: behaviour is no longer applicable.
500: .\" LIST-ITEM
501: .It
502: The
503: .Sq \&sp
504: macro does not accept negative numbers.
505: .\" LIST-ITEM
506: .It
1.7 schwarze 507: Blocks of whitespace are stripped from both macro and free-form text
508: lines (except when in literal mode), while groff would retain whitespace
509: in free-form text lines.
510: .\" LIST-ITEM
511: .It
1.3 schwarze 512: Historic groff has many un-callable macros. Most of these (excluding
513: some block-level macros) are now callable, conforming to the
514: non-historic groff version.
515: .\" LIST-ITEM
516: .It
1.9 schwarze 517: The vertical bar
1.7 schwarze 518: .Sq \(ba
1.3 schwarze 519: made historic groff
520: .Qq go orbital
521: but is a proper delimiter in this implementation.
1.1 kristaps 522: .\" LIST-ITEM
523: .It
1.9 schwarze 524: .Sq \&It \-nested
1.3 schwarze 525: is assumed for all lists (it wasn't in historic groff): any list may be
526: nested and
1.1 kristaps 527: .Sq \-enum
528: lists will restart the sequence only for the sub-list.
529: .\" LIST-ITEM
530: .It
1.9 schwarze 531: .Sq \&It \-column
1.3 schwarze 532: syntax where column widths may be preceded by other arguments (instead
1.1 kristaps 533: of proceeded) is not supported.
534: .\" LIST-ITEM
535: .It
1.9 schwarze 536: The
537: .Sq \&At
1.1 kristaps 538: macro only accepts a single parameter.
539: .\" LIST-ITEM
540: .It
541: Some manuals use
1.9 schwarze 542: .Sq \&Li
1.1 kristaps 543: incorrectly by following it with a reserved character and expecting the
544: delimiter to render. This is not supported.
545: .\" LIST-ITEM
546: .It
1.9 schwarze 547: In groff, the
548: .Sq \&Fo
1.8 schwarze 549: macro only produces the first parameter. This is no longer the case.
1.1 kristaps 550: .El
1.8 schwarze 551: .\" SECTION---------------------------------------------
1.1 kristaps 552: .Sh SEE ALSO
553: .Xr mandoc 1 ,
554: .Xr mandoc_char 7
1.8 schwarze 555: .\" SECTION---------------------------------------------
1.1 kristaps 556: .Sh AUTHORS
557: The
558: .Nm
1.9 schwarze 559: reference was written by
1.2 schwarze 560: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.8 schwarze 561: .\" SECTION---------------------------------------------
1.1 kristaps 562: .Sh CAVEATS
1.2 schwarze 563: There are many ambiguous parts of mdoc.
1.8 schwarze 564: .\" PARAGRAPH------------
1.1 kristaps 565: .Pp
566: .Bl -dash -compact
567: .\" LIST-ITEM
568: .It
1.9 schwarze 569: .Sq \&Fa
570: should be
571: .Sq \&Va
1.1 kristaps 572: as function arguments are variables.
573: .\" LIST-ITEM
574: .It
1.9 schwarze 575: .Sq \&Ft
1.1 kristaps 576: should be
1.9 schwarze 577: .Sq \&Vt
1.1 kristaps 578: as function return types are still types. Furthermore, the
1.9 schwarze 579: .Sq \&Ft
1.1 kristaps 580: should be removed and
1.9 schwarze 581: .Sq \&Fo ,
1.1 kristaps 582: which ostensibly follows it, should follow the same convention as
1.9 schwarze 583: .Sq \&Va .
1.1 kristaps 584: .\" LIST-ITEM
585: .It
1.9 schwarze 586: .Sq \&Va
1.1 kristaps 587: should formalise that only one or two arguments are acceptable: a
1.2 schwarze 588: variable name and optional, preceding type.
1.1 kristaps 589: .\" LIST-ITEM
590: .It
1.9 schwarze 591: .Sq \&Fd
1.1 kristaps 592: is ambiguous. It's commonly used to indicate an include file in the
1.9 schwarze 593: synopsis section.
594: .Sq \&In
1.1 kristaps 595: should be used, instead.
596: .\" LIST-ITEM
597: .It
598: Only the
599: .Sq \-literal
600: argument to
1.9 schwarze 601: .Sq \&Bd
1.1 kristaps 602: makes sense. The remaining ones should be removed.
603: .\" LIST-ITEM
604: .It
1.9 schwarze 605: The
606: .Sq \&Xo
1.1 kristaps 607: and
1.9 schwarze 608: .Sq \&Xc
1.1 kristaps 609: macros should be deprecated.
610: .\" LIST-ITEM
611: .It
612: The
1.9 schwarze 613: .Sq \&Dt
1.1 kristaps 614: macro lacks clarity. It should be absolutely clear which title will
615: render when formatting the manual page.
616: .\" LIST-ITEM
617: .It
618: A
1.9 schwarze 619: .Sq \&Lx
620: should be provided for Linux (\(`a la
621: .Sq \&Ox ,
622: .Sq \&Nx
1.1 kristaps 623: etc.).
624: .\" LIST-ITEM
625: .It
626: There's no way to refer to references in
1.9 schwarze 627: .Sq \&Rs/Re
1.1 kristaps 628: blocks.
1.6 schwarze 629: .\" LIST-ITEM
630: .It
1.13 ! schwarze 631: The \-split and \-nosplit dictates via
1.9 schwarze 632: .Sq \&An
1.13 ! schwarze 633: are re-set when entering and leaving the AUTHORS section.
1.1 kristaps 634: .El
![[BACK]](/icons/back.gif){kind=icon}
Return to mdoc.7 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc