mdocml.1

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