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.33

-version 1.14, 2008/12/02 00:10:37
+version 1.33, 2009/02/21 15:34:46
 Line 2
 Line 2
 Line 2
  .Dd $Mdocdate$
  .Dt mdocml 1
  .Os
- .\"
+ .\" SECTION
  .Sh NAME
  .Nm mdocml
- .Nd compile manpage source into mark-up language
+ .Nd mdoc macro compiler
- .\"
+ .\" SECTION
  .Sh SYNOPSIS
  .Nm mdocml
- .Op Fl W
+ .Op Fl f Ns Ar filter
- .Op Fl f Ar filter
+ .Op Fl v
- .Op Fl o Ar outfile
+ .Op Fl W Ns Ar err...
  .Op Ar infile
- .\"
+ .\" SECTION
  .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 scan, parse, validate and output mdoc-macro documents.
- the default.  The arguments are as follows:
+ Arguments follow:
- .Bl -tag -width "\-o outfile"
+ .Bl -tag -width "\-Werr... "
- .It Fl f Ar filter
+ .\" ITEM
- The output filter name.
+ .It Fl f Ns Ar filter
- .It Fl o Ar outfile
+ Pipe the parsed syntax tree into an output filter.  May be either
- Write output to
+ .Ar tree
- .Ar outfile ,
+ for the parse tree or
- which may be
+ .Ar term
- .Qq \-
+ for a terminal-encoded, formatted manual page.
- for stdout.
+ .\" ITEM
- .It Fl W
+ .It Fl v
- Print warnings to stderr.
+ Print verbose parsing output.
+ .\" ITEM
+ .It Fl W Ns Ar err...
+ Print warning messages.  May be set to
+ .Fl W Ns Ar all
+ for all warnings,
+ .Ar compat
+ for groff/troff-compatibility warnings, or
+ .Ar syntax
+ for syntax warnings.  If
+ .Fl W Ns Ar error
+ is specified, warnings are considered errors and cause utility
+ termination.  Multiple
+ .Fl W
+ arguments may be comma-separated, such as
+ .Fl W Ns Ar error,all .
+ .\" ITEM
  .It Ar infile
  Read input from
  .Ar infile ,
  which may be
- .Qq \-
+ .Dq \-
  for stdin.
  .El
+ .\" PARAGRAPH
  .Pp
+ Parsing and validation rules are drawn entirely from the
+ .Xr mdoc 7
+ and
+ .Xr mdoc.samples 7
+ manuals.
+ .\" PARAGRAPH
+ .Pp
  By default,
  .Nm
- reads from stdin and writes to stdout using the xml filter.
+ reads from stdin and only validates its input.
- .\"
+ .\" PARAGRAPH
- .Ss XML Filter
+ .Pp
- The XML filter, specified by
+ .Ex -std mdocml
- .Fl f Ar xml ,
+ .\" PARAGRAPH
- is the default filter.  It creates an XML document where element names are
+ .Pp
- their respective roff macro names.  Each element name has an associated
+ .Nm
- namespace, which is one of
+ is
- .Qq block
+ .Ud
- or
+ .\" SECTION
- .Qq inline ,
+ .Sh EXAMPLES
- corresponding to the display mode of a node.  The document root is
+ To validate this manual page:
- always the
+ .\" PARAGRAPH
- .Qq mdoc
+ .Pp
- element, in the default namespace.
+ .D1 % mdocml \-Wall,error mdocml.1
- .\" This next request is for sections 1, 6, 7 & 8 only.
+ .\" SECTION
- .\" .Sh ENVIRONMENT
- .\"
  .Sh SEE ALSO
  .Xr groff 1 ,
  .Xr mdoc.samples 7 ,
- .Xr mdoc 7
+ .Xr mdoc 7 ,
- .\" .Sh STANDARDS
+ .Xr mdoc 3
- .\" .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 .
- .\"
+ .\" SECTION
  .Sh CAVEATS
- Most caveats of
+ See
- .Nm
+ .Xr mdoc 3
- stem from ambiguities in
+ for a list of bugs, caveats, and incomplete macros.
- .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 the
- .Sq \&Xo ,
- .Sq \&Xc ,
- .Sq \&No ,
- .Sq \&Db ,
- .Sq \&Sm ,
- .Sq \&Xc ,
- and
- .Sq \&Xo
- mdoc macros.
- .It
- All macro arguments may be quoted, instead of only some.
- .It
- Blank lines raise errors.
- .It
- 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