mdocml.1

   1 .\"
   2 .Dd $Mdocdate: December 8 2008 $
   3 .Dt mdocml 1 alpha
   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 vW
  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 current output filters are
  22 .Ar html
  23 and
  24 .Ar xml ,
  25 the default.  Arguments common to all filters follow:
  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 .Dq \-
  34 for stdout.
  35 .It Fl W
  36 Print warnings to stderr.
  37 .It Fl v
  38 Make warning and error messages verbose.
  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 By default,
  48 .Nm
  49 reads from stdin and writes to stdout using the xml filter.
  50 .Pp
  51 .Ex -std mdocml
  52 .\"
  53 .Ss XML Filter
  54 The XML filter, specified by
  55 .Fl f Ar xml ,
  56 is the default filter.  This filter has no additional arguments.
  57 .Pp
  58 The XML filter creates an XML document where element names are their respective
  59 roff macro names.  Each element name has an associated
  60 namespace, which is one of
  61 .Dq block ,
  62 .Dq head ,
  63 .Dq body ,
  64 or
  65 .Dq inline ,
  66 corresponding to the display mode of a node.  The document root is
  67 always the
  68 .Dq mdoc
  69 element, in the default namespace; the
  70 .Dq head
  71 namespace is for block headers (such as
  72 .Sq .Ss
  73 and
  74 .Sq .Sh ) ;
  75 the
  76 .Dq body
  77 namespace is for block bodies; and the
  78 .Dq inline
  79 namespace is for in-line elements (such as
  80 .Sq .Em ) .
  81 .Ss HTML Filter
  82 The HTML filter, specified by
  83 .Fl f Ar html ,
  84 accepts the following filter-specific arguments:
  85 .Bl -tag -width "\-c css"
  86 .It Fl c Ar css
  87 The CSS file location, which defaults to
  88 .Ar mdocml.css .
  89 .It Fl e
  90 Whether to embed the CSS file into the HTML prologue.
  91 .El
  92 .\"
  93 .Sh EXAMPLES
  94 To produce an HTML4-strict document
  95 .Pa mdocml.html
  96 for
  97 .Pa mdocml.1
  98 with the default, embedded style-sheet:
  99 .Pp
 100 .D1 % mdocml -fhtml -e -o mdocml.html mdocml.1
 101 .Pp
 102 To create an XML document on standard output from
 103 .Pa mdocml.1
 104 with the default namespace identifiers
 105 .Li head ,
 106 .Li body ,
 107 .Li block
 108 and
 109 .Li inline :
 110 .Pp
 111 .D1 % mdocml mdocml.1
 112 .\"
 113 .Sh SEE ALSO
 114 .Xr groff 1 ,
 115 .Xr mdoc.samples 7 ,
 116 .Xr mdoc 7
 117 .\" .Sh STANDARDS
 118 .\" .Sh HISTORY
 119 .Sh AUTHORS
 120 The
 121 .Nm
 122 utility was written by
 123 .An Kristaps Dzonsons Aq kristaps@kth.se .
 124 .\"
 125 .Sh CAVEATS
 126 Most caveats of
 127 .Nm
 128 stem from ambiguities in
 129 .Xr mdoc 7
 130 or the necessary limitations of converting an ad hoc language into
 131 structured ones:
 132 .Bl -enum -compact -offset indent
 133 .It
 134 The engine doesn't understand the
 135 .Sq \&No ,
 136 .Sq \&Db ,
 137 .Sq \&Xc ,
 138 and
 139 .Sq \&Xo
 140 mdoc macros.
 141 .It
 142 All macro arguments may be quoted, instead of only some.
 143 .It
 144 Blank lines raise errors.
 145 .It
 146 If terminating punctuation is found, then
 147 .Em all
 148 remaining tokens are flushed after line scope is closed, not just the
 149 last one.
 150 .El
 151 .Pp
 152 The roff engine in
 153 .Nm
 154 produces text in-line; thus, output may already be partially written by
 155 the time an error is encountered.
 156 .\" .Sh BUGS