mdocml.1

   1 .\"
   2 .Dd $Mdocdate: December 2 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 or
  55 .Qq inline ,
  56 corresponding to the display mode of a node.  The document root is
  57 always the
  58 .Qq mdoc
  59 element, in the default namespace.
  60 .\" This next request is for sections 1, 6, 7 & 8 only.
  61 .\" .Sh ENVIRONMENT
  62 .\"
  63 .Sh SEE ALSO
  64 .Xr groff 1 ,
  65 .Xr mdoc.samples 7 ,
  66 .Xr mdoc 7
  67 .\" .Sh STANDARDS
  68 .\" .Sh HISTORY
  69 .Sh AUTHORS
  70 The
  71 .Nm
  72 utility was written by
  73 .An Em Kristaps Dzonsons Aq kristaps@kth.se .
  74 .\"
  75 .Sh CAVEATS
  76 Most caveats of
  77 .Nm
  78 stem from ambiguities in
  79 .Xr mdoc 7
  80 or the necessary limitations of converting an ad hoc language into
  81 structured ones:
  82 .Bl -enum -compact -offset indent
  83 .It
  84 The engine doesn't understand the
  85 .Sq \&Xo ,
  86 .Sq \&Xc ,
  87 .Sq \&No ,
  88 .Sq \&Db ,
  89 .Sq \&Sm ,
  90 .Sq \&Xc ,
  91 and
  92 .Sq \&Xo
  93 mdoc macros.
  94 .It
  95 All macro arguments may be quoted, instead of only some.
  96 .It
  97 Blank lines raise errors.
  98 .It
  99 If terminating punctuation is found, then
 100 .Em all
 101 remaining tokens are flushed after line scope is closed, not just the
 102 last one.
 103 .El
 104 .Pp
 105 The roff engine in
 106 .Nm
 107 produces text in-line; thus, output may already be partially written by
 108 the time an error is encountered.
 109 .\" .Sh BUGS