Below DIAGNOSTICS, document the SYSERR message level;

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index b91d086e29e8595b019359337ed06fd678233f38..745dd504ed61e08fac1d746076dd3faecdb3a79c 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,6 +1,7 @@
-.\"    $Id: mandoc.1,v 1.39 2009/10/03 15:08:09 kristaps Exp $
+.\"    $Id: mandoc.1,v 1.105 2014/06/23 22:03:30 schwarze Exp $

 .\"
 .\"

-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
+.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>

 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -14,79 +15,29 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: October 3 2009 $
+.Dd $Mdocdate: June 23 2014 $

 .Dt MANDOC 1
 .Os
 .Dt MANDOC 1
 .Os

-.
-.

 .Sh NAME
 .Nm mandoc
 .Nd format and display UNIX manuals
 .Sh NAME
 .Nm mandoc
 .Nd format and display UNIX manuals

-.
-.

 .Sh SYNOPSIS
 .Nm mandoc
 .Sh SYNOPSIS
 .Nm mandoc

-.Op Fl f Ns Ar option...
+.Op Fl V
+.Sm off
+.Op Fl I Cm os Li = Ar name
+.Sm on

 .Op Fl m Ns Ar format
 .Op Fl m Ns Ar format

-.Op Fl o Ns Ar option...
+.Op Fl O Ns Ar option

 .Op Fl T Ns Ar output
 .Op Fl T Ns Ar output

-.Op Fl V
-.Op Fl W Ns Ar err...
-.Op Ar infile...
-.
-.
+.Op Fl W Ns Ar level
+.Op Ar

 .Sh DESCRIPTION
 The
 .Nm
 utility formats
 .Ux
 .Sh DESCRIPTION
 The
 .Nm
 utility formats
 .Ux

-manual pages for display.  The arguments are as follows:
-.
-.Bl -tag -width Ds
-.It Fl f Ns Ar option...
-Comma-separated compiler options.  See
-.Sx Compiler Options
-for details.
-.
-.It Fl m Ns Ar format
-Input format.  See
-.Sx Input Formats
-for available formats.  Defaults to
-.Fl m Ns Ar andoc .
-.
-.It Fl o Ns Ar format
-Comma-separated output options.  See
-.Sx Output Options
-for details.
-.
-.It Fl T Ns Ar output
-Output format.  See
-.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
-will halt with the first failed parse.
-.El
-.
+manual pages for display.

 .Pp
 By default,
 .Nm
 .Pp
 By default,
 .Nm


@@ -95,56 +46,82 @@ reads
 or
 .Xr man 7
 text from stdin, implying
 or
 .Xr man 7
 text from stdin, implying

-.Fl m Ns Ar andoc ,
-and prints 78-column backspace-encoded output to stdout as if
-.Fl T Ns Ar ascii
-were provided.
-.
-.Pp
-.Ex -std mandoc
-.
-.
-.Ss Punctuation and Spacing
-If punctuation is set apart from words, such as in the phrase
-.Dq to be \&, or not to be ,
-it's processed by
-.Nm
-according to the following rules:  opening punctuation
-.Po
-.Sq \&( ,
-.Sq \&[ ,
-and
-.Sq \&{
-.Pc
-is not followed by a space; closing punctuation
-.Po
-.Sq \&. ,
-.Sq \&, ,
-.Sq \&; ,
-.Sq \&: ,
-.Sq \&? ,
-.Sq \&! ,
-.Sq \&) ,
-.Sq \&]
-and
-.Sq \&}
-.Pc
-is not preceded by whitespace.
-.
+.Fl m Ns Cm andoc ,
+and produces
+.Fl T Ns Cm ascii
+output.

 .Pp
 .Pp

-If the input is
-.Xr mdoc 7 ,
-these rules are also applied to macro arguments when appropriate.
-.
+The arguments are as follows:
+.Bl -tag -width Ds
+.Sm off
+.It Fl I Cm os Li = Ar name
+.Sm on
+Override the default operating system
+.Ar name
+for the
+.Xr mdoc 7
+.Sq \&Os
+macro.
+.It Fl m Ns Ar format
+Input format.
+See
+.Sx Input Formats
+for available formats.
+Defaults to
+.Fl m Ns Cm andoc .
+.It Fl O Ns Ar option
+Comma-separated output options.
+.It Fl T Ns Ar output
+Output format.
+See
+.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 level
+Specify the minimum message
+.Ar level
+to be reported on the standard error output and to affect the exit status.
+The
+.Ar level
+can be
+.Cm warning ,
+.Cm error ,
+or
+.Cm fatal .
+The default is
+.Fl W Ns Cm fatal ;
+.Fl W Ns Cm all
+is an alias for
+.Fl W Ns Cm warning .
+See
+.Sx EXIT STATUS
+and
+.Sx DIAGNOSTICS
+for details.

 .Pp
 .Pp

-White-space, in non-literal (normal) mode, is stripped from input and
-replaced on output by a single space.  Thus, if you wish to preserve multiple
-spaces, they must be space-escaped or used in a literal display mode, e.g.,
-.Sq \&Bd \-literal
-in
-.Xr mdoc 7 .
-.
-.
+The special option
+.Fl W Ns Cm stop
+tells
+.Nm
+to exit after parsing a file that causes warnings or errors of at least
+the requested level.
+No formatted output will be produced from that file.
+If both a
+.Ar level
+and
+.Cm stop
+are requested, they can be joined with a comma, for example
+.Fl W Ns Cm error , Ns Cm stop .
+.It Ar file
+Read input from zero or more files.
+If unspecified, reads from stdin.
+If multiple files are specified,
+.Nm
+will halt with the first failed parse.
+.El

 .Ss Input Formats
 The
 .Nm
 .Ss Input Formats
 The
 .Nm


@@ -153,20 +130,20 @@ utility accepts
 and
 .Xr man 7
 input with
 and
 .Xr man 7
 input with

-.Fl m Ns Ar doc
+.Fl m Ns Cm doc

 and
 and

-.Fl m Ns Ar an ,
-respectively.  The
+.Fl m Ns Cm an ,
+respectively.
+The

 .Xr mdoc 7
 format is
 .Em strongly
 recommended;
 .Xr man 7
 should only be used for legacy manuals.
 .Xr mdoc 7
 format is
 .Em strongly
 recommended;
 .Xr man 7
 should only be used for legacy manuals.

-.

 .Pp
 A third option,
 .Pp
 A third option,

-.Fl m Ns Ar andoc ,
+.Fl m Ns Cm andoc ,

 which is also the default, determines encoding on-the-fly: if the first
 non-comment macro is
 .Sq \&Dd
 which is also the default, determines encoding on-the-fly: if the first
 non-comment macro is
 .Sq \&Dd


@@ -177,204 +154,534 @@ the
 parser is used; otherwise, the
 .Xr man 7
 parser is used.
 parser is used; otherwise, the
 .Xr man 7
 parser is used.

-.

 .Pp
 If multiple
 files are specified with
 .Pp
 If multiple
 files are specified with

-.Fl m Ns Ar andoc ,
-each has its file-type determined this way.  If multiple files are
+.Fl m Ns Cm andoc ,
+each has its file-type determined this way.
+If multiple files are

 specified and
 specified and

-.Fl m Ns Ar doc
+.Fl m Ns Cm doc

 or
 or

-.Fl m Ns Ar an
+.Fl m Ns Cm an

 is specified, then this format is used exclusively.
 is specified, then this format is used exclusively.

-.
-.

 .Ss Output Formats
 The
 .Nm
 utility accepts the following
 .Fl T
 .Ss Output Formats
 The
 .Nm
 utility accepts the following
 .Fl T

-arguments:
-.
-.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.
-.
-.It Fl T Ns Ar html
-Produce strict HTML-4.01 output, with a sane default style.
-.
-.It Fl T Ns Ar tree
-Produce an indented parse tree.
-.
-.It Fl T Ns Ar lint
+arguments, which correspond to output modes:
+.Bl -tag -width "-Tlocale"
+.It Fl T Ns Cm ascii
+Produce 7-bit ASCII output.
+This is the default.
+See
+.Sx ASCII Output .
+.It Fl T Ns Cm html
+Produce strict CSS1/HTML-4.01 output.
+See
+.Sx HTML Output .
+.It Fl T Ns Cm lint

 Parse only: produce no output.
 Parse only: produce no output.

+Implies
+.Fl W Ns Cm warning .
+.It Fl T Ns Cm locale
+Encode output using the current locale.
+See
+.Sx Locale Output .
+.It Fl T Ns Cm man
+Produce
+.Xr man 7
+format output.
+See
+.Sx Man Output .
+.It Fl T Ns Cm pdf
+Produce PDF output.
+See
+.Sx PDF Output .
+.It Fl T Ns Cm ps
+Produce PostScript output.
+See
+.Sx PostScript Output .
+.It Fl T Ns Cm tree
+Produce an indented parse tree.
+.It Fl T Ns Cm utf8
+Encode output in the UTF\-8 multi-byte format.
+See
+.Sx UTF\-8 Output .
+.It Fl T Ns Cm xhtml
+Produce strict CSS1/XHTML-1.0 output.
+See
+.Sx XHTML Output .

 .El
 .El

-.

 .Pp
 If multiple input files are specified, these will be processed by the
 corresponding filter in-order.
 .Pp
 If multiple input files are specified, these will be processed by the
 corresponding filter in-order.

-.
-.
-.Ss Compiler Options
-Default compiler behaviour may be overridden with the
-.Fl f
-flag.
-.
+.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
+Font styles are applied by using back-spaced encoding such that an
+underlined character
+.Sq c
+is rendered as
+.Sq _ Ns \e[bs] Ns c ,
+where
+.Sq \e[bs]
+is the back-space character number 8.
+Emboldened characters are rendered as
+.Sq c Ns \e[bs] Ns c .
+.Pp
+The special characters documented in
+.Xr mandoc_char 7
+are rendered best-effort in an ASCII equivalent.
+If no equivalent is found,
+.Sq \&?
+is used instead.
+.Pp
+Output width is limited to 78 visible columns unless literal input lines
+exceed this limit.
+.Pp
+The following
+.Fl O
+arguments are accepted:

 .Bl -tag -width Ds
 .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 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
-Don't halt when encountering parse errors.  Useful with
-.Fl T Ns Ar lint
-over a large set of manuals passed on the command line.
+.It Cm indent Ns = Ns Ar indent
+The left margin for normal text is set to
+.Ar indent
+blank characters instead of the default of five for
+.Xr mdoc 7
+and seven for
+.Xr man 7 .
+Increasing this is not recommended; it may result in degraded formatting,
+for example overfull lines or ugly line breaks.
+.It Cm width Ns = Ns Ar width
+The output width is set to
+.Ar width ,
+which will normalise to \(>=60.

 .El
 .El

-.
-.Ss Output Options
-For the time being, only
-.Fl T Ns Ar html
-is the only mode with output options:
+.Ss HTML Output
+Output produced by
+.Fl T Ns Cm html
+conforms to HTML-4.01 strict.
+.Pp
+The
+.Pa example.style.css
+file documents style-sheet classes available for customising output.
+If a style-sheet is not specified with
+.Fl O Ns Ar style ,
+.Fl T Ns Cm html
+defaults to simple output readable in any graphical or text-based web
+browser.
+.Pp
+Special characters are rendered in decimal-encoded UTF\-8.
+.Pp
+The following
+.Fl O
+arguments are accepted:

 .Bl -tag -width Ds
 .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 man=fmt
+.It Cm fragment
+Omit the
+.Aq !DOCTYPE
+declaration and the
+.Aq html ,
+.Aq head ,
+and
+.Aq body
+elements and only emit the subtree below the
+.Aq body
+element.
+The
+.Cm style
+argument will be ignored.
+This is useful when embedding manual content within existing documents.
+.It Cm includes Ns = Ns Ar fmt

 The string
 .Ar fmt ,
 The string
 .Ar fmt ,

-for example, 
+for example,
+.Ar ../src/%I.html ,
+is used as a template for linked header files (usually via the
+.Sq \&In
+macro).
+Instances of
+.Sq \&%I
+are replaced with the include filename.
+The default is not to present a
+hyperlink.
+.It Cm man Ns = Ns Ar fmt
+The string
+.Ar fmt ,
+for example,

 .Ar ../html%S/%N.%S.html ,
 is used as a template for linked manuals (usually via the
 .Sq \&Xr
 .Ar ../html%S/%N.%S.html ,
 is used as a template for linked manuals (usually via the
 .Sq \&Xr

-macro).  The default is
-.Ar %N.%S.html .
+macro).
+Instances of
+.Sq \&%N
+and
+.Sq %S
+are replaced with the linked manual's name and section, respectively.
+If no section is included, section 1 is assumed.
+The default is not to
+present a hyperlink.
+.It 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
+.Ss Locale Output
+Locale-depending output encoding is triggered with
+.Fl T Ns Cm locale .
+This option is not available on all systems: systems without locale
+support, or those whose internal representation is not natively UCS-4,
+will fall back to
+.Fl T Ns Cm ascii .
+See
+.Sx ASCII Output
+for font style specification and available command-line arguments.
+.Ss Man Output
+Translate input format into
+.Xr man 7
+output format.
+This is useful for distributing manual sources to legacy systems
+lacking
+.Xr mdoc 7
+formatters.
+.Pp
+If
+.Xr mdoc 7
+is passed as input, it is translated into
+.Xr man 7 .
+If the input format is
+.Xr man 7 ,
+the input is copied to the output, expanding any
+.Xr roff 7
+.Sq so
+requests.
+The parser is also run, and as usual, the
+.Fl W
+level controls which
+.Sx DIAGNOSTICS
+are displayed before copying the input to the output.
+.Ss PDF Output
+PDF-1.1 output may be generated by
+.Fl T Ns Cm pdf .
+See
+.Sx PostScript Output
+for
+.Fl O
+arguments and defaults.
+.Ss PostScript Output
+PostScript
+.Qq Adobe-3.0
+Level-2 pages may be generated by
+.Fl T Ns Cm ps .
+Output pages default to letter sized and are rendered in the Times font
+family, 11-point.
+Margins are calculated as 1/9 the page length and width.
+Line-height is 1.4m.
+.Pp
+Special characters are rendered as in
+.Sx ASCII Output .
+.Pp
+The following
+.Fl O
+arguments are accepted:
+.Bl -tag -width Ds
+.It Cm paper Ns = Ns Ar name
+The paper size
+.Ar name
+may be one of
+.Ar a3 ,
+.Ar a4 ,
+.Ar a5 ,
+.Ar legal ,
+or
+.Ar letter .
+You may also manually specify dimensions as
+.Ar NNxNN ,
+width by height in millimetres.
+If an unknown value is encountered,
+.Ar letter
+is used.
+.El
+.Ss UTF\-8 Output
+Use
+.Fl T Ns Cm utf8
+to force a UTF\-8 locale.
+See
+.Sx Locale Output
+for details and options.
+.Ss XHTML Output
+Output produced by
+.Fl T Ns Cm xhtml
+conforms to XHTML-1.0 strict.
+.Pp
+See
+.Sx HTML Output
+for details; beyond generating XHTML tags instead of HTML tags, these
+output modes are identical.
+.Sh EXIT STATUS
+The
+.Nm
+utility exits with one of the following values, controlled by the message
+.Ar level
+associated with the
+.Fl W
+option:
+.Pp
+.Bl -tag -width Ds -compact
+.It 0
+No warnings or errors occurred, or those that did were ignored because
+they were lower than the requested
+.Ar level .
+.It 2
+At least one warning occurred, but no error, and
+.Fl W Ns Cm warning
+was specified.
+.It 3
+At least one parsing error occurred, but no fatal error, and
+.Fl W Ns Cm error
+or
+.Fl W Ns Cm warning
+was specified.
+.It 4
+A fatal parsing error occurred.
+.It 5
+Invalid command line arguments were specified.
+No input files have been read.
+.It 6
+An operating system error occurred, for example memory exhaustion or an
+error accessing input files.
+Such errors cause
+.Nm
+to exit at once, possibly in the middle of parsing or formatting a file.

 .El
 .El

-.
+.Pp
+Note that selecting
+.Fl T Ns Cm lint
+output mode implies
+.Fl W Ns Cm warning .

 .Sh EXAMPLES
 To page manuals to the terminal:
 .Sh EXAMPLES
 To page manuals to the terminal:

-.

 .Pp
 .Pp

-.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
-.D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
-.
+.Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
+.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less

 .Pp
 .Pp

-To produce HTML manuals with 
-.Pa http://localhost/
-as the base URI:
+To produce HTML manuals with
+.Ar style.css
+as the style-sheet:

 .Pp
 .Pp

-.D1 % mandoc \-Thtml -obase=http://localhost/ mdoc.7 > mdoc.7.html
+.Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html

 .Pp
 To check over a large set of manuals:
 .Pp
 To check over a large set of manuals:

-.

 .Pp
 .Pp

-.Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
-.
-.
+.Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
+.Pp
+To produce a series of PostScript manuals for A4 paper:
+.Pp
+.Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
+.Pp
+Convert a modern
+.Xr mdoc 7
+manual to the older
+.Xr man 7
+format, for use on systems lacking an
+.Xr mdoc 7
+parser:
+.Pp
+.Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
+.Sh DIAGNOSTICS
+Standard error messages reporting parsing errors are prefixed by
+.Pp
+.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level :
+.Pp
+where the fields have the following meanings:
+.Bl -tag -width "column"
+.It Ar file
+The name of the input file causing the message.
+.It Ar line
+The line number in that input file.
+Line numbering starts at 1.
+.It Ar column
+The column number in that input file.
+Column numbering starts at 1.
+If the issue is caused by a word, the column number usually
+points to the first character of the word.
+.It Ar level
+The message level, printed in capital letters.
+.El
+.Pp
+The
+.Ar line
+and
+.Ar column
+fields are omitted when meaningless.
+.Pp
+Message levels have the following meanings:
+.Bl -tag -width "warning"
+.It Cm syserr
+Opening or reading an input file failed, so the parser cannot
+even be started and no output is produced from that input file.
+.It Cm fatal
+The parser is unable to parse a given input file at all.
+No formatted output is produced from that input file.
+.It Cm error
+An input file contains syntax that cannot be safely interpreted,
+either because it is invalid or because
+.Nm
+does not implement it yet.
+By discarding part of the input or inserting missing tokens,
+the parser is able to continue, and the error does not prevent
+generation of formatted output, but typically, preparing that
+output involves information loss, broken document structure
+or unintended formatting.
+.It Cm warning
+An input file uses obsolete, discouraged or non-portable syntax.
+All the same, the meaning of the input is unambiguous and a correct
+rendering can be produced.
+Documents causing warnings may render poorly when using other
+formatting tools instead of
+.Nm .
+.El
+.Pp
+Messages of the
+.Cm warning
+and
+.Cm error
+levels are hidden unless their level, or a lower level, is requested using a
+.Fl W
+option or
+.Fl T Ns Cm lint
+output mode.
+.Pp
+The
+.Nm
+utility may also print messages related to invalid command line arguments
+or operating system errors, for example when memory is exhausted.
+Such messages may not carry the prefix described above.

 .Sh COMPATIBILITY
 This section summarises
 .Nm
 .Sh COMPATIBILITY
 This section summarises
 .Nm

-compatibility with
-.Xr groff 1 .
+compatibility with GNU troff.

 Each input and output format is separately noted.
 Each input and output format is separately noted.

-.
-.
-.Ss ASCII output
+.Ss ASCII Compatibility

 .Bl -bullet -compact
 .It
 .Bl -bullet -compact
 .It

-The 
-.Sq \e~
-special character doesn't produce expected behaviour in 
-.Fl T Ns Ar ascii .
-.
+Unrenderable unicode codepoints specified with
+.Sq \e[uNNNN]
+escapes are printed as
+.Sq \&?
+in mandoc.
+In GNU troff, these raise an error.

 .It
 .It

-The 
+The

 .Sq \&Bd \-literal
 .Sq \&Bd \-literal

-and 
+and

 .Sq \&Bd \-unfilled
 macros of
 .Xr mdoc 7
 in
 .Sq \&Bd \-unfilled
 macros of
 .Xr mdoc 7
 in

-.Fl T Ns Ar ascii
+.Fl T Ns Cm ascii

 are synonyms, as are \-filled and \-ragged.
 are synonyms, as are \-filled and \-ragged.

-.

 .It
 .It

-In 
-.Xr groff 1 ,
-the
+In historic GNU troff, the

 .Sq \&Pa
 .Xr mdoc 7
 macro does not underline when scoped under an
 .Sq \&It
 .Sq \&Pa
 .Xr mdoc 7
 macro does not underline when scoped under an
 .Sq \&It

-in the FILES section.  This behaves correctly in
+in the FILES section.
+This behaves correctly in

 .Nm .
 .Nm .

-.

 .It
 .It

-A list or display following
+A list or display following the

 .Sq \&Ss
 .Xr mdoc 7
 macro in
 .Sq \&Ss
 .Xr mdoc 7
 macro in

-.Fl T Ns Ar ascii
+.Fl T Ns Cm ascii

 does not assert a prior vertical break, just as it doesn't with
 .Sq \&Sh .
 does not assert a prior vertical break, just as it doesn't with
 .Sq \&Sh .

-.

 .It
 The
 .Sq \&na
 .Xr man 7
 macro in
 .It
 The
 .Sq \&na
 .Xr man 7
 macro in

-.Fl T Ns Ar ascii
+.Fl T Ns Cm ascii

 has no effect.
 has no effect.

-.

 .It
 Words aren't hyphenated.
 .It
 Words aren't hyphenated.

-.
+.El
+.Ss HTML/XHTML Compatibility
+.Bl -bullet -compact
+.It
+The
+.Sq \efP
+escape will revert the font to the previous
+.Sq \ef
+escape, not to the last rendered decoration, which is now dictated by
+CSS instead of hard-coded.
+It also will not span past the current scope,
+for the same reason.
+Note that in
+.Sx ASCII Output
+mode, this will work fine.

 .It
 .It

-In normal mode (not a literal block), blocks of spaces aren't preserved,
-so double spaces following sentence closure are reduced to a single space;
-.Xr groff 1
-retains spaces.
-.
+The
+.Xr mdoc 7
+.Sq \&Bl \-hang
+and
+.Sq \&Bl \-tag
+list types render similarly (no break following overreached left-hand
+side) due to the expressive constraints of HTML.

 .It
 .It

-Sentences are unilaterally monospaced.
+The
+.Xr man 7
+.Sq IP
+and
+.Sq TP
+lists render similarly.

 .El
 .El

-.\" SECTION

 .Sh SEE ALSO
 .Sh SEE ALSO

+.Xr eqn 7 ,
+.Xr man 7 ,

 .Xr mandoc_char 7 ,
 .Xr mdoc 7 ,
 .Xr mandoc_char 7 ,
 .Xr mdoc 7 ,

-.Xr man 7
-.
+.Xr roff 7 ,
+.Xr tbl 7

 .Sh AUTHORS
 The
 .Nm
 utility was written by
 .Sh AUTHORS
 The
 .Nm
 utility was written by

-.An Kristaps Dzonsons Aq kristaps@kth.se .
-.
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

 .Sh CAVEATS
 In
 .Sh CAVEATS
 In

-.Fl T Ns Ar html ,
+.Fl T Ns Cm html
+and
+.Fl T Ns Cm xhtml ,

 the maximum size of an element attribute is determined by
 .Dv BUFSIZ ,
 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 with
-.Fl o Ns Ar man=fmt .
+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
+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 \(aq
+control character is an alias for the standard macro control character
+and does not emit a line-break as stipulated in GNU troff.