mdocml.1

   1 .\"
   2 .Dd $Mdocdate: December 10 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 v
  13 .Op Fl W Ns Ar err...
  14 .Op Fl f Ar filter
  15 .Op Fl o Ar outfile
  16 .Op Ar infile
  17 .\"
  18 .Sh DESCRIPTION
  19 The
  20 .Nm
  21 utility parses mdoc formatted manual source and passes results into an
  22 output filter.  The current output filters are
  23 .Fl f Ar html
  24 and
  25 .Fl f Ar xml .
  26 By default,
  27 .Nm
  28 only validates its input. This may be explicitly directed with
  29 .Fl f Ar noop .
  30 Arguments common to all filters follow:
  31 .Bl -tag -width "\-o outfile"
  32 .It Fl f Ar filter
  33 The output filter name.
  34 .It Fl o Ar outfile
  35 Write output to
  36 .Ar outfile ,
  37 which may be
  38 .Dq \-
  39 for stdout.  This is meaningless for
  40 .Fl f Ar noop .
  41 .It Fl W Ns Ar err...
  42 Print warning messages.  If set to
  43 .Fl W Ns Ar all ,
  44 all warnings are printed; if
  45 .Fl W Ns Ar error ,
  46 warnings are considered errors and cause utility termination.  Multiple
  47 .Fl W
  48 arguments may be comma-separated, such as
  49 .Fl W Ns Ar error,all .
  50 .It Fl v
  51 Make warning and error messages verbose.
  52 .It Ar infile
  53 Read input from
  54 .Ar infile ,
  55 which may be
  56 .Dq \-
  57 for stdin.
  58 .El
  59 .Pp
  60 By default,
  61 .Nm
  62 reads from stdin and writes to stdout.
  63 .Pp
  64 .Ex -std mdocml
  65 .\"
  66 .Ss Noop Filter
  67 The default noop
  68 .Dq validating
  69 filter simply validates its input; it produces no output beyond error
  70 and warning messages.
  71 .\"
  72 .Ss XML Filter
  73 The XML filter, specified by
  74 .Fl f Ar xml ,
  75 produces correctly-formatted XML output.  This filter has no additional
  76 arguments.
  77 .Pp
  78 The XML filter creates an XML document where element names are their respective
  79 roff macro names.  Each element name has an associated
  80 namespace, which is one of
  81 .Dq block ,
  82 .Dq head ,
  83 .Dq body ,
  84 or
  85 .Dq inline ,
  86 corresponding to the display mode of a node.  The document root is
  87 always the
  88 .Dq mdoc
  89 element, in the default namespace; the
  90 .Dq head
  91 namespace is for block headers (such as
  92 .Sq .Ss
  93 and
  94 .Sq .Sh ) ;
  95 the
  96 .Dq body
  97 namespace is for block bodies; and the
  98 .Dq inline
  99 namespace is for in-line elements (such as
 100 .Sq .Em ) .
 101 .\"
 102 .Ss HTML Filter
 103 The HTML filter, specified by
 104 .Fl f Ar html ,
 105 accepts the following filter-specific arguments:
 106 .Bl -tag -width "\-c css"
 107 .It Fl c Ar css
 108 The CSS file location, which defaults to
 109 .Ar mdocml.css .
 110 .It Fl e
 111 Whether to embed the CSS file into the HTML prologue.
 112 .El
 113 .Pp
 114 By default, the HTML filter produces HTML-4.01 strict mark-up.  The
 115 default CSS document styles the page as it would appear in a terminal
 116 window.
 117 .\"
 118 .Sh EXAMPLES
 119 To produce an HTML4-strict document
 120 .Pa mdocml.html
 121 for
 122 .Pa mdocml.1
 123 with the default, embedded style-sheet:
 124 .Pp
 125 .D1 % mdocml -fhtml -e -o mdocml.html mdocml.1
 126 .Pp
 127 To create an XML document on standard output from
 128 .Pa mdocml.1
 129 with the default namespace identifiers
 130 .Li head ,
 131 .Li body ,
 132 .Li block
 133 and
 134 .Li inline :
 135 .Pp
 136 .D1 % mdocml -Wall,error -fxml mdocml.1
 137 .Pp
 138 The previous example will also halt on input document warnings.
 139 .\"
 140 .Sh SEE ALSO
 141 .Xr groff 1 ,
 142 .Xr mdoc.samples 7 ,
 143 .Xr mdoc 7
 144 .\" .Sh STANDARDS
 145 .\" .Sh HISTORY
 146 .Sh AUTHORS
 147 The
 148 .Nm
 149 utility was written by
 150 .An Kristaps Dzonsons Aq kristaps@kth.se .
 151 .\"
 152 .Sh CAVEATS
 153 Most caveats of
 154 .Nm
 155 stem from ambiguities in
 156 .Xr mdoc 7
 157 or the necessary limitations of converting an ad hoc language into
 158 structured ones:
 159 .Bl -enum -compact -offset indent
 160 .It
 161 The engine doesn't understand the
 162 .Sq \&No ,
 163 .Sq \&Db ,
 164 .Sq \&Xc ,
 165 and
 166 .Sq \&Xo
 167 mdoc macros.
 168 .It
 169 All macro arguments may be quoted, instead of only some.
 170 .It
 171 Blank lines raise errors.
 172 .It
 173 If terminating punctuation is found, then
 174 .Em all
 175 remaining tokens are flushed after line scope is closed, not just the
 176 last one.
 177 .El
 178 .Pp
 179 The roff engine in
 180 .Nm
 181 produces text in-line; thus, output may already be partially written by
 182 the time an error is encountered.
 183 .\" .Sh BUGS