===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.210
retrieving revision 1.211
diff -u -p -r1.210 -r1.211
--- mandoc/mandoc.1	2017/07/01 09:47:30	1.210
+++ mandoc/mandoc.1	2017/07/02 15:31:59	1.211
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.210 2017/07/01 09:47:30 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.211 2017/07/02 15:31:59 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 1 2017 $
+.Dd $Mdocdate: July 2 2017 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -1097,6 +1097,24 @@ 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 "cross reference to self"
+.Pq mdoc
+An
+.Ic \&Xr
+macro refers to a name and section matching the section of the present
+manual page and a name mentioned in an
+.Ic \&Nm
+macro in the NAME or SYNOPSIS section, or in an
+.Ic \&Fn
+or
+.Ic \&Fo
+macro in the SYNOPSIS.
+Consider using
+.Ic \&Nm
+or
+.Ic \&Fn
+instead of
+.Ic \&Xr .
 .It Sy "unusual Xr order"
 .Pq mdoc
 In the SEE ALSO section, an