mdocml.1

   1 .\"
   2 .Dd $Mdocdate: January 16 2009 $
   3 .Dt mdocml 1
   4 .Os
   5 .\"
   6 .Sh NAME
   7 .Nm mdocml
   8 .Nd mdoc macro compiler
   9 .\"
  10 .Sh SYNOPSIS
  11 .Nm mdocml
  12 .Op Fl v
  13 .Op Fl W Ns Ar err...
  14 .Op Ar infile
  15 .\"
  16 .Sh DESCRIPTION
  17 The
  18 .Nm
  19 utility interfaces the
  20 .Xr mdoc 3
  21 library to validate and parse mdoc-macro documents.  Arguments follow:
  22 .Bl -tag -width "\-Werr... "
  23 .It Fl W Ns Ar err...
  24 Print warning messages.  May be set to
  25 .Fl W Ns Ar all
  26 for all warnings,
  27 .Ar compat
  28 for groff/troff-compatibility warnings, or
  29 .Ar syntax
  30 for syntax warnings.  If
  31 .Fl W Ns Ar error
  32 is specified, warnings are considered errors and cause utility
  33 termination.  Multiple
  34 .Fl W
  35 arguments may be comma-separated, such as
  36 .Fl W Ns Ar error,all .
  37 .It Fl v
  38 Print verbose parsing output.
  39 .It Ar infile
  40 Read input from
  41 .Ar infile ,
  42 which may be
  43 .Dq \-
  44 for stdin.
  45 .El
  46 .Pp
  47 Parsing and validation rules are drawn entirely from the
  48 .Xr mdoc 7
  49 and
  50 .Xr mdoc.samples 7
  51 manuals.
  52 .Pp
  53 By default,
  54 .Nm
  55 reads from stdin, writes messages to stdout, and writes errors and
  56 warnings to stderr.
  57 .Pp
  58 .Ex -std mdocml
  59 .\"
  60 .Sh EXAMPLES
  61 To validate this manual page:
  62 .Pp
  63 .D1 % mdocml \-Wall,error mdocml.1
  64 .\"
  65 .Sh SEE ALSO
  66 .Xr groff 1 ,
  67 .Xr mdoc.samples 7 ,
  68 .Xr mdoc 7 ,
  69 .Xr mdoc 3
  70 .\" .Sh STANDARDS
  71 .\" .Sh HISTORY
  72 .Sh AUTHORS
  73 The
  74 .Nm
  75 utility was written by
  76 .An Kristaps Dzonsons Aq kristaps@kth.se .
  77 .\"
  78 .Sh CAVEATS
  79 The most glaring short-coming of
  80 .Nm
  81 is that it doesn't yet support the
  82 .Sq \&Xc
  83 and
  84 .Sq \&Xo
  85 macros when used to extend the line arguments to
  86 .Sq \&It ;
  87 in effect, trampling the body section.  We note that this is explicitly
  88 discouraged in
  89 .Xr mdoc.samples 7 ,
  90 but in practice used quite often.
  91 .\" .Sh BUGS