mdocml.1

   1 .\"
   2 .Dd $Mdocdate: December 1 2008 $
   3 .Dt mdocml 1
   4 .Os
   5 .\"
   6 .Sh NAME
   7 .Nm mdocml
   8 .Nd compile manpage source into mark-up language
   9 .\"
  10 .Sh SYNOPSIS
  11 .Nm mdocml
  12 .Op Fl W
  13 .Op Fl f Ar filter
  14 .Op Fl o Ar outfile
  15 .Op Ar infile
  16 .\"
  17 .Sh DESCRIPTION
  18 The
  19 .Nm
  20 utility parses
  21 .Xr mdoc
  22 formatted manual source and passes results into an output filter.  The
  23 only current output filter is
  24 .Ar xml ,
  25 the default.  The arguments are as follows:
  26 .Bl -tag -width "\-o outfile"
  27 .It Fl f Ar filter
  28 The output filter name.
  29 .It Fl o Ar outfile
  30 Write output to
  31 .Ar outfile ,
  32 which may be
  33 .Qq \-
  34 for stdout.
  35 .It Fl W
  36 Print warnings to stderr.
  37 .It Ar infile
  38 Read input from
  39 .Ar infile ,
  40 which may be
  41 .Qq \-
  42 for stdin.
  43 .El
  44 .Pp
  45 By default,
  46 .Nm
  47 reads from stdin and writes to stdout using the xml filter.
  48 .\"
  49 .Ss XML Filter
  50 The XML filter, specified by
  51 .Fl f Ar xml ,
  52 is the default filter.  It creates an XML document where element names are
  53 their respective roff macro names.  Each element name has an associated
  54 namespace, which is one of
  55 .Qq block
  56 or
  57 .Qq inline ,
  58 corresponding to the display mode of a node.  The document root is
  59 always the
  60 .Qq mdoc
  61 element, in the default namespace.
  62 .\" This next request is for sections 1, 6, 7 & 8 only.
  63 .\" .Sh ENVIRONMENT
  64 .\"
  65 .Sh SEE ALSO
  66 .Xr groff 1 ,
  67 .Xr mdoc.samples 7 ,
  68 .Xr mdoc 7
  69 .\" .Sh STANDARDS
  70 .\" .Sh HISTORY
  71 .Sh AUTHORS
  72 The
  73 .Nm
  74 utility was written by
  75 .An Em Kristaps Dzonsons Aq kristaps@kth.se .
  76 .\"
  77 .Sh CAVEATS
  78 Most caveats of
  79 .Nm
  80 stem from ambiguities in
  81 .Xr mdoc 7
  82 or the necessary limitations of converting an ad hoc language into
  83 structured ones:
  84 .Bl -enum -compact -offset indent
  85 .It
  86 The engine doesn't understand the
  87 .Sq \&Xo ,
  88 .Sq \&Xc ,
  89 .Sq \&Ns ,
  90 .Sq \&No ,
  91 .Sq \&Db ,
  92 .Sq \&Sm ,
  93 .Sq \&Xc ,
  94 and
  95 .Sq \&Xo
  96 mdoc macros.
  97 .It
  98 All macro arguments may be quoted, instead of only some.
  99 .It
 100 Blank lines raise errors.
 101 .It
 102 If terminating punctuation is found, then
 103 .Em all
 104 remaining tokens are flushed after line scope is closed, not just the
 105 last one.
 106 .El
 107 .\" .Sh BUGS