+.Ss In-line
+In-line macros have only text children. If a number (or inequality) of
+arguments is
+.Pq n ,
+then the macro accepts an arbitrary number of arguments.
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
+.It \&.Dd Ta \&No Ta \&No Ta >0
+.It \&.Dt Ta \&No Ta \&No Ta n
+.It \&.Os Ta \&No Ta \&No Ta n
+.It \&.Pp Ta \&No Ta \&No Ta 0
+.It \&.Ad Ta Yes Ta Yes Ta n
+.It \&.An Ta Yes Ta Yes Ta n
+.It \&.Ar Ta Yes Ta Yes Ta n
+.It \&.Cd Ta Yes Ta \&No Ta >0
+.It \&.Cm Ta Yes Ta Yes Ta n
+.It \&.Dv Ta Yes Ta Yes Ta n
+.It \&.Er Ta Yes Ta Yes Ta >0
+.It \&.Ev Ta Yes Ta Yes Ta n
+.It \&.Ex Ta \&No Ta \&No Ta 0
+.It \&.Fa Ta Yes Ta Yes Ta n
+.It \&.Fd Ta \&No Ta \&No Ta >0
+.It \&.Fl Ta Yes Ta Yes Ta n
+.It \&.Fn Ta Yes Ta Yes Ta >0
+.It \&.Ft Ta Yes Ta Yes Ta n
+.It \&.Ic Ta Yes Ta Yes Ta >0
+.It \&.In Ta \&No Ta \&No Ta n
+.It \&.Li Ta Yes Ta Yes Ta n
+.It \&.Nd Ta \&No Ta \&No Ta n
+.It \&.Nm Ta Yes Ta Yes Ta n
+.It \&.Ot Ta \&No Ta \&No Ta n
+.It \&.Pa Ta Yes Ta Yes Ta n
+.It \&.Rv Ta \&No Ta \&No Ta 0
+.It \&.St Ta \&No Ta Yes Ta 1
+.It \&.Va Ta Yes Ta Yes Ta n
+.It \&.Vt Ta Yes Ta Yes Ta >0
+.It \&.Xr Ta Yes Ta Yes Ta >0, <3
+.It \&.%A Ta \&No Ta \&No Ta >0
+.It \&.%B Ta \&No Ta \&No Ta >0
+.It \&.%C Ta \&No Ta \&No Ta >0
+.It \&.%D Ta \&No Ta \&No Ta >0
+.It \&.%I Ta \&No Ta \&No Ta >0
+.It \&.%J Ta \&No Ta \&No Ta >0
+.It \&.%N Ta \&No Ta \&No Ta >0
+.It \&.%O Ta \&No Ta \&No Ta >0
+.It \&.%P Ta \&No Ta \&No Ta >0
+.It \&.%R Ta \&No Ta \&No Ta >0
+.It \&.%T Ta \&No Ta \&No Ta >0
+.It \&.%V Ta \&No Ta \&No Ta >0
+.It \&.At Ta Yes Ta Yes Ta 1
+.It \&.Bsx Ta Yes Ta Yes Ta n
+.It \&.Bx Ta Yes Ta Yes Ta n
+.It \&.Db Ta \&No Ta \&No Ta 1
+.It \&.Em Ta Yes Ta Yes Ta >0
+.It \&.Fx Ta Yes Ta Yes Ta n
+.It \&.Ms Ta Yes Ta Yes Ta >0
+.It \&.No Ta Yes Ta Yes Ta 0
+.It \&.Ns Ta Yes Ta Yes Ta 0
+.It \&.Nx Ta Yes Ta Yes Ta n
+.It \&.Ox Ta Yes Ta Yes Ta n
+.It \&.Pf Ta \&No Ta Yes Ta 1
+.It \&.Sm Ta \&No Ta \&No Ta 1
+.It \&.Sx Ta Yes Ta Yes Ta >0
+.It \&.Sy Ta Yes Ta Yes Ta >0
+.It \&.Tn Ta Yes Ta Yes Ta >0
+.It \&.Ux Ta Yes Ta Yes Ta n
+.It \&.Dx Ta Yes Ta Yes Ta n
+.It \&.Bt Ta \&No Ta \&No Ta 0
+.It \&.Hf Ta \&No Ta \&No Ta n
+.It \&.Fr Ta \&No Ta \&No Ta n
+.It \&.Ud Ta \&No Ta \&No Ta 0
+.It \&.Lb Ta \&No Ta \&No Ta 1
+.It \&.Ap Ta Yes Ta Yes Ta 0
+.It \&.Lp Ta \&No Ta \&No Ta 0
+.It \&.Lk Ta Yes Ta Yes Ta n
+.It \&.Mt Ta Yes Ta Yes Ta >0
+.It \&.Es Ta \&No Ta \&No Ta 0
+.It \&.En Ta \&No Ta \&No Ta 0
+.El
+.Pp
+The
+.Sq \&.Ot ,
+.Sq \&.Fr ,
+.Sq \&.Es
+and
+.Sq \&.En ,
+macros are obsolete.
+.\" SECTION
+.Sh COMPATIBILITY
+This section documents compatibility with other roff implementations, at
+this time limited to
+.Xr groff 1 .
+The term
+.Qq historic groff
+refers to those versions before the
+.Pa doc.tmac
+file re-write
+.Pq somewhere between 1.15 and 1.19 .
+.Pp
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+Historic groff has many un-callable macros. Most of these (excluding
+some block-level macros) are now callable, conforming to the
+non-historic groff version.
+.\" LIST-ITEM
+.It
+The vertical bar
+.Sq \(Ba
+made historic groff
+.Qq go orbital
+but is a proper delimiter in this implementation.
+.\" LIST-ITEM
+.It
+.Sq \&.It \-nested
+is assumed for all lists (it wasn't in historic groff): any list may be
+nested and
+.Sq \-enum
+lists will restart the sequence only for the sub-list.
+.\" LIST-ITEM
+.It
+.Sq \&.It \-column
+syntax where column widths may be preceded by other arguments (instead
+of proceeded) is not supported.
+.\" LIST-ITEM
+.It
+The
+.Sq \&.At
+macro only accepts a single parameter.
+.\" LIST-ITEM
+.It
+Some manuals use
+.Sq \&.Li
+incorrectly by following it with a reserved character and expecting the
+delimiter to render. This is not supported.
+.\" LIST-ITEM
+.It
+If an special-character control character
+.Sq \e
+is escaped, it will
+obviously not render the sequence. Even newer versions of groff seem to
+dither on this.
+.El
+.\" SECTION
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr mandoc_char 7
+.\" SECTION
+.Sh AUTHORS
+The
+.Nm
+utility was written by
+.An Kristaps Dzonsons Aq kristaps@kth.se .
+.\" SECTION
+.Sh CAVEATS
+There are many ambiguous parts of mdoc.
+.Pp
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+.Sq \&.Fa
+should be
+.Sq \&.Va
+as function arguments are variables.
+.\" LIST-ITEM
+.It
+.Sq \&.Ft
+should be
+.Sq \&.Vt
+as function return types are still types. Furthermore, the
+.Sq \&.Ft
+should be removed and
+.Sq \&.Fo ,
+which ostensibly follows it, should follow the same convention as
+.Sq \&.Va .
+.\" LIST-ITEM
+.It
+.Sq \&.Va
+should formalise that only one or two arguments are acceptable: a
+variable name and optional, preceding type.
+.\" LIST-ITEM
+.It
+.Sq \&.Fd
+is ambiguous. It's commonly used to indicate an include file in the
+synopsis section.
+.Sq \&.In
+should be used, instead.
+.\" LIST-ITEM
+.It
+Only the
+.Sq \-literal
+argument to
+.Sq \&.Bd
+makes sense. The remaining ones should be removed.
+.\" LIST-ITEM
+.It
+The
+.Sq \&.Xo
+and
+.Sq \&.Xc
+macros should be deprecated.
+.\" LIST-ITEM
+.It
+The
+.Sq \&.Dt
+macro lacks clarity. It should be absolutely clear which title will
+render when formatting the manual page.
+.\" LIST-ITEM
+.It
+A
+.Sq \&.Lx
+should be provided for Linux (\(`a la
+.Sq \&.Ox ,
+.Sq \&.Nx
+etc.).
+.\" LIST-ITEM
+.It
+There's no way to refer to references in
+.Sq \&.Rs/.Re
+blocks.
git.ckatri.com / mandoc.git / blobdiff