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