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.7 and 1.27

-version 1.7, 2008/11/28 11:21:12
+version 1.27, 2009/01/16 14:04:26
 Line 1
 Line 1
 Line 1
- .\"     $OpenBSD$
  .\"
- .\" The following requests are required for all man pages.
- .\"
- .\" Remove `\&' from the line below.
  .Dd $Mdocdate$
  .Dt mdocml 1
  .Os
  .\"
  .Sh NAME
  .Nm mdocml
- .Nd compile manpage source into mark-up language
+ .Nd mdoc macro compiler
  .\"
  .Sh SYNOPSIS
  .Nm mdocml
- .Op Fl vW
+ .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
+ utility interfaces the
- .Xr mdoc
+ .Xr mdoc 3
- formatted manual source and passes results into the output filter
+ library to validate and parse mdoc-macro documents.  Arguments follow:
- dictated by
+ .Bl -tag -width "\-Werr... "
- .Fl f Ar filter .
+ .It Fl W Ns Ar err...
- The only current output filter is
+ Print warning messages.  May be set to
- .Ar validate ,
+ .Fl W Ns Ar all
- the default.  The arguments are as follows:
+ for all warnings,
- .Bl -tag -width "\-o outfile"
+ .Ar compat
- .It Fl o Ar outfile
+ for groff/troff-compatibility warnings, or
- Place output in
+ .Ar syntax
- .Ar outfile ,
+ for syntax warnings.  If
- which may be
+ .Fl W Ns Ar error
- .Qq \-
+ is specified, warnings are considered errors and cause utility
- for standard output.  The default is standard output.
+ 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 standard input.  The default is standard input.
+ for stdin.
- .It Fl v
- Print messages (output depends on filter).
- .It Fl W
- Print warnings (output depends on filter).
  .El
- .Ss Validate Filter
+ .Pp
- The validate filter, specified by
+ Parsing and validation rules are drawn entirely from the
- .Fl f Ar validate ,
+ .Xr mdoc 7
- is the default filter.  It produces no output, so specifying
+ and
- .Fl o Ar outfile
+ .Xr mdoc.samples 7
- results in an empty file.
+ manuals.
- .\" The following requests should be uncommented and used where appropriate.
+ .Pp
- .\" This next request is for sections 2, 3, and 9 function return values only.
+ By default,
- .\" .Sh RETURN VALUES
+ .Nm
- .\" This next request is for sections 1, 6, 7 & 8 only.
+ reads from stdin, writes messages to stdout, and writes errors and
- .\" .Sh ENVIRONMENT
+ warnings to stderr.
- .\" .Sh FILES
+ .Pp
- .\" .Sh EXAMPLES
+ .Ex -std mdocml
- .\" This next request is for sections 1, 4, 6, and 8 only.
+ .\"
- .\" .Sh DIAGNOSTICS
+ .Sh EXAMPLES
- .\" The next request is for sections 2, 3, and 9 error and signal handling only.
+ To validate this manual page:
- .\" .Sh ERRORS
+ .Pp
+ .D1 % mdocml \-Wall,error mdocml.1
+ .\"
  .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
-Line 77  utility was written by
+Line 76  utility was written by
 Line 77  utility was written by
 Line 76  utility was written by
  .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
- or the necessary limitations of converting an ad hoc language into
- structured ones:
- .Bl -enum -compact -offset indent
- .It
- The engine doesn't understand
- .Sq \&Xo
- and
  .Sq \&Xc
- troff macros.
+ and
- .It
+ .Sq \&Xo
- All macro arguments may be quoted, instead of only some.
+ macros when used to extend the line arguments to
- .It
+ .Sq \&It ;
- Blank lines raise warnings.
+ in effect, trampling the body section.  We note that this is explicitly
- .It
+ discouraged in
- Non-ascii characters may cause issues.
+ .Xr mdoc.samples 7 ,
- .El
+ but in practice used quite often.
  .\" .Sh BUGS

CVSweb