mdocml.1

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