mdocml.1

   1 .\"
   2 .Dd $Mdocdate: December 3 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 mdoc formatted manual source and passes results into an
  21 output filter.  The only current output filter is
  22 .Ar xml ,
  23 the default.  The arguments are as follows:
  24 .Bl -tag -width "\-o outfile"
  25 .It Fl f Ar filter
  26 The output filter name.
  27 .It Fl o Ar outfile
  28 Write output to
  29 .Ar outfile ,
  30 which may be
  31 .Qq \-
  32 for stdout.
  33 .It Fl W
  34 Print warnings to stderr.
  35 .It Ar infile
  36 Read input from
  37 .Ar infile ,
  38 which may be
  39 .Qq \-
  40 for stdin.
  41 .El
  42 .Pp
  43 By default,
  44 .Nm
  45 reads from stdin and writes to stdout using the xml filter.
  46 .\"
  47 .Ss XML Filter
  48 The XML filter, specified by
  49 .Fl f Ar xml ,
  50 is the default filter.  It creates an XML document where element names are
  51 their respective roff macro names.  Each element name has an associated
  52 namespace, which is one of
  53 .Qq block ,
  54 .Qq head ,
  55 .Qq body ,
  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 \&No ,
  90 .Sq \&Db ,
  91 .Sq \&Xc ,
  92 and
  93 .Sq \&Xo
  94 mdoc macros.
  95 .It
  96 All macro arguments may be quoted, instead of only some.
  97 .It
  98 Blank lines raise errors.
  99 .It
 100 If terminating punctuation is found, then
 101 .Em all
 102 remaining tokens are flushed after line scope is closed, not just the
 103 last one.
 104 .El
 105 .Pp
 106 The roff engine in
 107 .Nm
 108 produces text in-line; thus, output may already be partially written by
 109 the time an error is encountered.
 110 .\" .Sh BUGS