document new SEE ALSO .Xr warnings

2 files changed, 17 insertions, 1 deletions

diff --git a/demandoc.1 b/demandoc.1
index 2a16c7ad..8d3d2c7a 100644
--- a/demandoc.1
+++ b/demandoc.1
@@ -92,7 +92,7 @@ This is accomplished as follows (assuming British spelling):
 .Dl $ demandoc -w file.1 | spell -b
 .Sh SEE ALSO
 .Xr mandoc 1 ,
-.Xr man 7
+.Xr man 7 ,
 .Xr mdoc 7
 .Sh HISTORY
 .Nm
diff --git a/mandoc.1 b/mandoc.1
index d8a936f8..ebb7df57 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -766,6 +766,22 @@ The same standard section title occurs more than once.
 .Pq mdoc
 A standard section header occurs in a section of the manual
 where it normally isn't useful.
+.It Sy "unusual Xr order"
+.Pq mdoc
+In the SEE ALSO section, an
+.Ic \&Xr
+macro with a lower section number follows one with a higher number,
+or two
+.Ic \&Xr
+macros refering to the same section are out of alphabetical order.
+.It Sy "unusual Xr punctuation"
+.Pq mdoc
+In the SEE ALSO section, punctuation between two
+.Ic \&Xr
+macros differs from a single comma, or there is trailing punctuation
+after the last
+.Ic \&Xr
+macro.
 .It Sy "AUTHORS section without An macro"
 .Pq mdoc
 An AUTHORS sections contains no