===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/mandoc/mandoc.1,v
retrieving revision 1.25
retrieving revision 1.26
diff -c -r1.25 -r1.26
*** src/usr.bin/mandoc/mandoc.1	2010/04/08 16:47:28	1.25
--- src/usr.bin/mandoc/mandoc.1	2010/04/13 06:52:12	1.26
***************
*** 1,4 ****
! .\"	$OpenBSD: mandoc.1,v 1.25 2010/04/08 16:47:28 jmc Exp $
  .\"
  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
  .\"
--- 1,4 ----
! .\"	$OpenBSD: mandoc.1,v 1.26 2010/04/13 06:52:12 jmc Exp $
  .\"
  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
  .\"
***************
*** 14,20 ****
  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  .\"
! .Dd $Mdocdate: April 8 2010 $
  .Dt MANDOC 1
  .Os
  .
--- 14,20 ----
  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  .\"
! .Dd $Mdocdate: April 13 2010 $
  .Dt MANDOC 1
  .Os
  .
***************
*** 26,38 ****
  .
  .Sh SYNOPSIS
  .Nm mandoc
! .Op Fl f Ns Ar option...
  .Op Fl m Ns Ar format
! .Op Fl O Ns Ar option...
  .Op Fl T Ns Ar output
! .Op Fl V
! .Op Fl W Ns Ar err...
! .Op Ar infile...
  .
  .
  .Sh DESCRIPTION
--- 26,38 ----
  .
  .Sh SYNOPSIS
  .Nm mandoc
! .Op Fl V
! .Op Fl f Ns Ar option
  .Op Fl m Ns Ar format
! .Op Fl O Ns Ar option
  .Op Fl T Ns Ar output
! .Op Fl W Ns Ar err
! .Op Ar file...
  .
  .
  .Sh DESCRIPTION
***************
*** 44,50 ****
  The arguments are as follows:
  .
  .Bl -tag -width Ds
! .It Fl f Ns Ar option...
  Comma-separated compiler options.
  See
  .Sx Compiler Options
--- 44,50 ----
  The arguments are as follows:
  .
  .Bl -tag -width Ds
! .It Fl f Ns Ar option
  Comma-separated compiler options.
  See
  .Sx Compiler Options
***************
*** 56,64 ****
  .Sx Input Formats
  for available formats.
  Defaults to
! .Fl m Ns Ar andoc .
  .
! .It Fl O Ns Ar option...
  Comma-separated output options.
  See
  .Sx Output Options
--- 56,64 ----
  .Sx Input Formats
  for available formats.
  Defaults to
! .Fl m Ns Cm andoc .
  .
! .It Fl O Ns Ar option
  Comma-separated output options.
  See
  .Sx Output Options
***************
*** 70,96 ****
  .Sx Output Formats
  for available formats.
  Defaults to
! .Fl T Ns Ar ascii .
  .
  .It Fl V
  Print version and exit.
  .
! .It Fl W Ns Ar err...
  Comma-separated warning options.
  Use
! .Fl W Ns Ar all
  to print warnings,
! .Fl W Ns Ar error
  for warnings to be considered errors and cause utility
  termination.
  Multiple
  .Fl W
  arguments may be comma-separated, such as
! .Fl W Ns Ar error,all .
  .
! .It Ar infile...
! Read input from zero or more
! .Ar infile .
  If unspecified, reads from stdin.
  If multiple files are specified,
  .Nm
--- 70,95 ----
  .Sx Output Formats
  for available formats.
  Defaults to
! .Fl T Ns Cm ascii .
  .
  .It Fl V
  Print version and exit.
  .
! .It Fl W Ns Ar err
  Comma-separated warning options.
  Use
! .Fl W Ns Cm all
  to print warnings,
! .Fl W Ns Cm error
  for warnings to be considered errors and cause utility
  termination.
  Multiple
  .Fl W
  arguments may be comma-separated, such as
! .Fl W Ns Cm error , Ns Cm all .
  .
! .It Ar file
! Read input from zero or more files.
  If unspecified, reads from stdin.
  If multiple files are specified,
  .Nm
***************
*** 105,113 ****
  or
  .Xr man 7
  text from stdin, implying
! .Fl m Ns Ar andoc ,
  and produces
! .Fl T Ns Ar ascii
  output.
  .
  .Pp
--- 104,112 ----
  or
  .Xr man 7
  text from stdin, implying
! .Fl m Ns Cm andoc ,
  and produces
! .Fl T Ns Cm ascii
  output.
  .
  .Pp
***************
*** 122,130 ****
  and
  .Xr man 7
  input with
! .Fl m Ns Ar doc
  and
! .Fl m Ns Ar an ,
  respectively.
  The
  .Xr mdoc 7
--- 121,129 ----
  and
  .Xr man 7
  input with
! .Fl m Ns Cm doc
  and
! .Fl m Ns Cm an ,
  respectively.
  The
  .Xr mdoc 7
***************
*** 136,142 ****
  .
  .Pp
  A third option,
! .Fl m Ns Ar andoc ,
  which is also the default, determines encoding on-the-fly: if the first
  non-comment macro is
  .Sq \&Dd
--- 135,141 ----
  .
  .Pp
  A third option,
! .Fl m Ns Cm andoc ,
  which is also the default, determines encoding on-the-fly: if the first
  non-comment macro is
  .Sq \&Dd
***************
*** 151,163 ****
  .Pp
  If multiple
  files are specified with
! .Fl m Ns Ar andoc ,
  each has its file-type determined this way.
  If multiple files are
  specified and
! .Fl m Ns Ar doc
  or
! .Fl m Ns Ar an
  is specified, then this format is used exclusively.
  .
  .
--- 150,162 ----
  .Pp
  If multiple
  files are specified with
! .Fl m Ns Cm andoc ,
  each has its file-type determined this way.
  If multiple files are
  specified and
! .Fl m Ns Cm doc
  or
! .Fl m Ns Cm an
  is specified, then this format is used exclusively.
  .
  .
***************
*** 170,201 ****
  .Sx OUTPUT ) :
  .
  .Bl -tag -width Ds
! .It Fl T Ns Ar ascii
  Produce 7-bit ASCII output, backspace-encoded for bold and underline
  styles.
  This is the default.
  See
  .Sx ASCII Output .
  .
! .It Fl T Ns Ar html
  Produce strict HTML-4.01 output, with a sane default style.
  See
  .Sx HTML Output .
  .
! .It Fl T Ns Ar xhtml
! Produce strict XHTML-1.0 output, with a sane default style.
! See
! .Sx XHTML Output .
! .
! .It Fl T Ns Ar tree
! Produce an indented parse tree.
! .
! .It Fl T Ns Ar lint
  Parse only: produce no output.
  Implies
! .Fl W Ns Ar all
  and
! .Fl f Ns Ar strict .
  .El
  .
  .Pp
--- 169,200 ----
  .Sx OUTPUT ) :
  .
  .Bl -tag -width Ds
! .It Fl T Ns Cm ascii
  Produce 7-bit ASCII output, backspace-encoded for bold and underline
  styles.
  This is the default.
  See
  .Sx ASCII Output .
  .
! .It Fl T Ns Cm html
  Produce strict HTML-4.01 output, with a sane default style.
  See
  .Sx HTML Output .
  .
! .It Fl T Ns Cm lint
  Parse only: produce no output.
  Implies
! .Fl W Ns Cm all
  and
! .Fl f Ns Cm strict .
! .
! .It Fl T Ns Cm tree
! Produce an indented parse tree.
! .
! .It Fl T Ns Cm xhtml
! Produce strict XHTML-1.0 output, with a sane default style.
! See
! .Sx XHTML Output .
  .El
  .
  .Pp
***************
*** 209,246 ****
  flag.
  .
  .Bl -tag -width Ds
! .It Fl f Ns Ar ign-scope
  When rewinding the scope of a block macro, forces the compiler to ignore
  scope violations.
  This can seriously mangle the resulting tree.
  .Pq mdoc only
  .
! .It Fl f Ns Ar ign-escape
! Ignore invalid escape sequences.
! This is the default, but the option can be used to override an earlier
! .Fl f Ns Ar strict .
  .
! .It Fl f Ns Ar no-ign-escape
! Don't ignore invalid escape sequences.
  .
! .It Fl f Ns Ar no-ign-macro
  Do not ignore unknown macros at the start of input lines.
  .
! .It Fl f Ns Ar no-ign-chars
! Do not ignore disallowed characters.
! .
! .It Fl f Ns Ar strict
  Implies
! .Fl f Ns Ar no-ign-escape ,
! .Fl f Ns Ar no-ign-macro
  and
! .Fl f Ns Ar no-ign-chars .
! .
! .It Fl f Ns Ar ign-errors
! When parsing multiple files, don't halt when one errors out.
! Useful with
! .Fl T Ns Ar lint
! over a large set of manuals passed on the command line.
  .El
  .
  .
--- 208,245 ----
  flag.
  .
  .Bl -tag -width Ds
! .It Fl f Ns Cm ign-errors
! When parsing multiple files, don't halt when one errors out.
! Useful with
! .Fl T Ns Cm lint
! over a large set of manuals passed on the command line.
! .
! .It Fl f Ns Cm ign-escape
! Ignore invalid escape sequences.
! This is the default, but the option can be used to override an earlier
! .Fl f Ns Cm strict .
! .
! .It Fl f Ns Cm ign-scope
  When rewinding the scope of a block macro, forces the compiler to ignore
  scope violations.
  This can seriously mangle the resulting tree.
  .Pq mdoc only
  .
! .It Fl f Ns Cm no-ign-chars
! Do not ignore disallowed characters.
  .
! .It Fl f Ns Cm no-ign-escape
! Do not ignore invalid escape sequences.
  .
! .It Fl f Ns Cm no-ign-macro
  Do not ignore unknown macros at the start of input lines.
  .
! .It Fl f Ns Cm strict
  Implies
! .Fl f Ns Cm no-ign-escape ,
! .Fl f Ns Cm no-ign-macro ,
  and
! .Fl f Ns Cm no-ign-chars .
  .El
  .
  .
***************
*** 249,263 ****
  .Fl T Ns Ar html
  and
  .Fl T Ns Ar xhtml
! accepts output options:
  .Bl -tag -width Ds
! .It Fl O Ns Ar style=style.css
! The file
! .Ar style.css
! is used for an external style-sheet.
! This must be a valid absolute or
! relative URI.
! .It Fl O Ns Ar includes=fmt
  The string
  .Ar fmt ,
  for example,
--- 248,256 ----
  .Fl T Ns Ar html
  and
  .Fl T Ns Ar xhtml
! accept output options:
  .Bl -tag -width Ds
! .It Fl O Ns Cm includes Ns = Ns Ar fmt
  The string
  .Ar fmt ,
  for example,
***************
*** 270,276 ****
  are replaced with the include filename.
  The default is not to present a
  hyperlink.
! .It Fl O Ns Ar man=fmt
  The string
  .Ar fmt ,
  for example,
--- 263,269 ----
  are replaced with the include filename.
  The default is not to present a
  hyperlink.
! .It Fl O Ns Cm man Ns = Ns Ar fmt
  The string
  .Ar fmt ,
  for example,
***************
*** 286,291 ****
--- 279,290 ----
  If no section is included, section 1 is assumed.
  The default is not to
  present a hyperlink.
+ .It Fl O Ns Cm style Ns = Ns Ar style.css
+ The file
+ .Ar style.css
+ is used for an external style-sheet.
+ This must be a valid absolute or
+ relative URI.
  .El
  .
  .
***************
*** 342,348 ****
  .
  .Ss ASCII Output
  Output produced by
! .Fl T Ns Ar ascii ,
  which is the default, is rendered in standard 7-bit ASCII documented in
  .Xr ascii 7 .
  .Pp
--- 341,347 ----
  .
  .Ss ASCII Output
  Output produced by
! .Fl T Ns Cm ascii ,
  which is the default, is rendered in standard 7-bit ASCII documented in
  .Xr ascii 7 .
  .Pp
***************
*** 367,373 ****
  .
  .Ss HTML Output
  Output produced by
! .Fl T Ns Ar html
  conforms to HTML-4.01 strict.
  .Pp
  Font styles and page structure are applied using CSS2.
--- 366,372 ----
  .
  .Ss HTML Output
  Output produced by
! .Fl T Ns Cm html
  conforms to HTML-4.01 strict.
  .Pp
  Font styles and page structure are applied using CSS2.
***************
*** 379,392 ****
  .Pa example.style.css
  file documents the range of styles applied to output and, if used, will
  cause rendered documents to appear as they do in
! .Fl T Ns Ar ascii .
  .Pp
  Special characters are rendered in decimal-encoded UTF-8.
  .
  .
  .Ss XHTML Output
  Output produced by
! .Fl T Ns Ar xhtml
  conforms to XHTML-1.0 strict.
  .Pp
  See
--- 378,391 ----
  .Pa example.style.css
  file documents the range of styles applied to output and, if used, will
  cause rendered documents to appear as they do in
! .Fl T Ns Cm ascii .
  .Pp
  Special characters are rendered in decimal-encoded UTF-8.
  .
  .
  .Ss XHTML Output
  Output produced by
! .Fl T Ns Cm xhtml
  conforms to XHTML-1.0 strict.
  .Pp
  See
***************
*** 399,418 ****
  To page manuals to the terminal:
  .
  .Pp
! .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
! .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
  .
  .Pp
  To produce HTML manuals with
  .Ar style.css
  as the style-sheet:
  .Pp
! .D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
  .Pp
  To check over a large set of manuals:
  .
  .Pp
! .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
  .
  .
  .Sh COMPATIBILITY
--- 398,417 ----
  To page manuals to the terminal:
  .
  .Pp
! .D1 $ mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
! .D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
  .
  .Pp
  To produce HTML manuals with
  .Ar style.css
  as the style-sheet:
  .Pp
! .D1 $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
  .Pp
  To check over a large set of manuals:
  .
  .Pp
! .Dl $ mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
  .
  .
  .Sh COMPATIBILITY
***************
*** 429,435 ****
  The
  .Sq \e~
  special character doesn't produce expected behaviour in
! .Fl T Ns Ar ascii .
  .
  .It
  The
--- 428,434 ----
  The
  .Sq \e~
  special character doesn't produce expected behaviour in
! .Fl T Ns Cm ascii .
  .
  .It
  The
***************
*** 439,445 ****
  macros of
  .Xr mdoc 7
  in
! .Fl T Ns Ar ascii
  are synonyms, as are \-filled and \-ragged.
  .
  .It
--- 438,444 ----
  macros of
  .Xr mdoc 7
  in
! .Fl T Ns Cm ascii
  are synonyms, as are \-filled and \-ragged.
  .
  .It
***************
*** 455,465 ****
  .Nm .
  .
  .It
! A list or display following
  .Sq \&Ss
  .Xr mdoc 7
  macro in
! .Fl T Ns Ar ascii
  does not assert a prior vertical break, just as it doesn't with
  .Sq \&Sh .
  .
--- 454,464 ----
  .Nm .
  .
  .It
! A list or display following the
  .Sq \&Ss
  .Xr mdoc 7
  macro in
! .Fl T Ns Cm ascii
  does not assert a prior vertical break, just as it doesn't with
  .Sq \&Sh .
  .
***************
*** 468,474 ****
  .Sq \&na
  .Xr man 7
  macro in
! .Fl T Ns Ar ascii
  has no effect.
  .
  .It
--- 467,473 ----
  .Sq \&na
  .Xr man 7
  macro in
! .Fl T Ns Cm ascii
  has no effect.
  .
  .It
***************
*** 532,562 ****
  .
  .Sh CAVEATS
  The
! .Fl T Ns Ar html
  and
! .Fl T Ns Ar xhtml
  CSS2 styling used for
! .Fl m Ns Ar doc
  input lists does not render properly in older browsers, such as Internet
  Explorer 6 and earlier.
  .
  .Pp
  In
! .Fl T Ns Ar html
  and
! .Fl T Ns Ar xhtml ,
  the maximum size of an element attribute is determined by
  .Dv BUFSIZ ,
  which is usually 1024 bytes.
  Be aware of this when setting long link
! formats, e.g.,
! .Fl O Ns Ar style=really/long/link .
  .
  .Pp
  The
! .Fl T Ns Ar html
  and
! .Fl T Ns Ar xhtml
  output modes don't render the
  .Sq \es
  font size escape documented in
--- 531,561 ----
  .
  .Sh CAVEATS
  The
! .Fl T Ns Cm html
  and
! .Fl T Ns Cm xhtml
  CSS2 styling used for
! .Fl m Ns Cm doc
  input lists does not render properly in older browsers, such as Internet
  Explorer 6 and earlier.
  .
  .Pp
  In
! .Fl T Ns Cm html
  and
! .Fl T Ns Cm xhtml ,
  the maximum size of an element attribute is determined by
  .Dv BUFSIZ ,
  which is usually 1024 bytes.
  Be aware of this when setting long link
! formats such as
! .Fl O Ns Cm style Ns = Ns Ar really/long/link .
  .
  .Pp
  The
! .Fl T Ns Cm html
  and
! .Fl T Ns Cm xhtml
  output modes don't render the
  .Sq \es
  font size escape documented in
***************
*** 566,587 ****
  .
  .Pp
  Nesting elements within next-line element scopes of
! .Fl m Ns Ar an ,
  such as
  .Sq br
  within an empty
  .Sq B ,
  will confuse
! .Fl T Ns Ar html
  and
! .Fl T Ns Ar xhtml
  and cause them to forget the formatting of the prior next-line scope.
  .
  .Pp
  The
  .Sq i
  macro in
! .Fl m Ns Ar an
  should italicise all subsequent text if a line argument is not provided.
  This behaviour is not implemented.
  .
--- 565,586 ----
  .
  .Pp
  Nesting elements within next-line element scopes of
! .Fl m Ns Cm an ,
  such as
  .Sq br
  within an empty
  .Sq B ,
  will confuse
! .Fl T Ns Cm html
  and
! .Fl T Ns Cm xhtml
  and cause them to forget the formatting of the prior next-line scope.
  .
  .Pp
  The
  .Sq i
  macro in
! .Fl m Ns Cm an
  should italicise all subsequent text if a line argument is not provided.
  This behaviour is not implemented.
  .