mdocml.1

   1 .\"     $OpenBSD: mdoc.template,v 1.10 2007/05/31 22:10:19 jmc Exp $
   2 .\"
   3 .\" The following requests are required for all man pages.
   4 .\"
   5 .\" Remove `\&' from the line below.
   6 .Dd $Mdocdate: November 30 2008 $
   7 .Dt mdocml 1
   8 .Os
   9 .\"
  10 .Sh NAME
  11 .Nm mdocml
  12 .Nd compile manpage source into mark-up language
  13 .\"
  14 .Sh SYNOPSIS
  15 .Nm mdocml
  16 .Op Fl vW
  17 .Op Fl f Ar filter
  18 .Op Fl o Ar outfile
  19 .Op Ar infile
  20 .\"
  21 .Sh DESCRIPTION
  22 The
  23 .Nm
  24 utility parses
  25 .Xr mdoc
  26 formatted manual source and passes results into the output filter
  27 dictated by
  28 .Fl f Ar filter .
  29 The only current output filter is
  30 .Ar validate ,
  31 the default.  The arguments are as follows:
  32 .Bl -tag -width "\-o outfile,"
  33 .It Sq Fl o Ar outfile ,
  34 Place output in
  35 .Ar outfile ,
  36 which may be
  37 .Qq \-
  38 for standard output.  The default is standard output.
  39 .It Ar infile
  40 Read input from
  41 .Ar infile ,
  42 which may be
  43 .Qq \-
  44 for standard input.  The default is standard input.
  45 .It Fl v
  46 Print messages (output depends on filter).
  47 .It Fl W
  48 Print warnings (output depends on filter).
  49 .El
  50 .Ss Validate Filter
  51 The validate filter, specified by
  52 .Fl f Ar validate ,
  53 is the default filter.  It produces no output, so specifying
  54 .Fl o Ar outfile
  55 results in an empty file.
  56 .\" The following requests should be uncommented and used where appropriate.
  57 .\" This next request is for sections 2, 3, and 9 function return values only.
  58 .\" .Sh RETURN VALUES
  59 .\" This next request is for sections 1, 6, 7 & 8 only.
  60 .\" .Sh ENVIRONMENT
  61 .\" .Sh FILES
  62 .\" .Sh EXAMPLES
  63 .\" This next request is for sections 1, 4, 6, and 8 only.
  64 .\" .Sh DIAGNOSTICS
  65 .\" The next request is for sections 2, 3, and 9 error and signal handling only.
  66 .\" .Sh ERRORS
  67 .Sh SEE ALSO
  68 .Xr groff 1 ,
  69 .Xr mdoc.samples 7 ,
  70 .Xr mdoc 7
  71 .\" .Sh STANDARDS
  72 .\" .Sh HISTORY
  73 .Sh AUTHORS
  74 The
  75 .Nm
  76 utility was written by
  77 .An Em Kristaps Dzonsons Aq kristaps@kth.se .
  78 .\"
  79 .Sh CAVEATS
  80 Most caveats of
  81 .Nm
  82 stem from ambiguities in
  83 .Xr mdoc 7
  84 or the necessary limitations of converting an ad hoc language into
  85 structured ones:
  86 .Bl -enum -compact -offset indent
  87 .It
  88 The engine doesn't understand
  89 .Sq \&Xo
  90 and
  91 .Sq \&Xc
  92 troff macros.
  93 .It
  94 All macro arguments may be quoted, instead of only some.
  95 .It
  96 Blank lines raise warnings.
  97 .It
  98 If terminating punctuation is found, then
  99 .Em all
 100 remaining tokens are flushed after line scope is closed, not just the
 101 last one.
 102 .El
 103 .\" .Sh BUGS