mandoc/mdocml.1 - diff

Return to mdocml.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/Attic/mdocml.1 between version 1.14 and 1.27

-version 1.14, 2008/12/02 00:10:37
+version 1.27, 2009/01/16 14:04:26
 Line 5
 Line 5
 Line 5
  .\"
  .Sh NAME
  .Nm mdocml
- .Nd compile manpage source into mark-up language
+ .Nd mdoc macro compiler
  .\"
  .Sh SYNOPSIS
  .Nm mdocml
- .Op Fl W
+ .Op Fl v
- .Op Fl f Ar filter
+ .Op Fl W Ns Ar err...
- .Op Fl o Ar outfile
  .Op Ar infile
  .\"
  .Sh DESCRIPTION
  The
  .Nm
- utility parses mdoc formatted manual source and passes results into an
+ utility interfaces the
- output filter.  The only current output filter is
+ .Xr mdoc 3
- .Ar xml ,
+ library to validate and parse mdoc-macro documents.  Arguments follow:
- the default.  The arguments are as follows:
+ .Bl -tag -width "\-Werr... "
- .Bl -tag -width "\-o outfile"
+ .It Fl W Ns Ar err...
- .It Fl f Ar filter
+ Print warning messages.  May be set to
- The output filter name.
+ .Fl W Ns Ar all
- .It Fl o Ar outfile
+ for all warnings,
- Write output to
+ .Ar compat
- .Ar outfile ,
+ for groff/troff-compatibility warnings, or
- which may be
+ .Ar syntax
- .Qq \-
+ for syntax warnings.  If
- for stdout.
+ .Fl W Ns Ar error
- .It Fl W
+ is specified, warnings are considered errors and cause utility
- Print warnings to stderr.
+ termination.  Multiple
+ .Fl W
+ arguments may be comma-separated, such as
+ .Fl W Ns Ar error,all .
+ .It Fl v
+ Print verbose parsing output.
  .It Ar infile
  Read input from
  .Ar infile ,
  which may be
- .Qq \-
+ .Dq \-
  for stdin.
  .El
  .Pp
+ Parsing and validation rules are drawn entirely from the
+ .Xr mdoc 7
+ and
+ .Xr mdoc.samples 7
+ manuals.
+ .Pp
  By default,
  .Nm
- reads from stdin and writes to stdout using the xml filter.
+ reads from stdin, writes messages to stdout, and writes errors and
+ warnings to stderr.
+ .Pp
+ .Ex -std mdocml
+ .\"
+ .Sh EXAMPLES
+ To validate this manual page:
+ .Pp
+ .D1 % mdocml \-Wall,error mdocml.1
  .\"
- .Ss XML Filter
- The XML filter, specified by
- .Fl f Ar xml ,
- is the default filter.  It creates an XML document where element names are
- their respective roff macro names.  Each element name has an associated
- namespace, which is one of
- .Qq block
- or
- .Qq inline ,
- corresponding to the display mode of a node.  The document root is
- always the
- .Qq mdoc
- element, in the default namespace.
- .\" This next request is for sections 1, 6, 7 & 8 only.
- .\" .Sh ENVIRONMENT
- .\"
  .Sh SEE ALSO
  .Xr groff 1 ,
  .Xr mdoc.samples 7 ,
- .Xr mdoc 7
+ .Xr mdoc 7 ,
+ .Xr mdoc 3
  .\" .Sh STANDARDS
  .\" .Sh HISTORY
  .Sh AUTHORS
  The
  .Nm
  utility was written by
- .An Em Kristaps Dzonsons Aq kristaps@kth.se .
+ .An Kristaps Dzonsons Aq kristaps@kth.se .
  .\"
  .Sh CAVEATS
- Most caveats of
+ The most glaring short-coming of
  .Nm
- stem from ambiguities in
+ is that it doesn't yet support the
- .Xr mdoc 7
+ .Sq \&Xc
- or the necessary limitations of converting an ad hoc language into
- structured ones:
- .Bl -enum -compact -offset indent
- .It
- The engine doesn't understand the
- .Sq \&Xo ,
- .Sq \&Xc ,
- .Sq \&No ,
- .Sq \&Db ,
- .Sq \&Sm ,
- .Sq \&Xc ,
  and
  .Sq \&Xo
- mdoc macros.
+ macros when used to extend the line arguments to
- .It
+ .Sq \&It ;
- All macro arguments may be quoted, instead of only some.
+ in effect, trampling the body section.  We note that this is explicitly
- .It
+ discouraged in
- Blank lines raise errors.
+ .Xr mdoc.samples 7 ,
- .It
+ but in practice used quite often.
- If terminating punctuation is found, then
- .Em all
- remaining tokens are flushed after line scope is closed, not just the
- last one.
- .El
- .Pp
- The roff engine in
- .Nm
- produces text in-line; thus, output may already be partially written by
- the time an error is encountered.
  .\" .Sh BUGS

CVSweb