===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/mandoc/mandoc.1,v
retrieving revision 1.134
retrieving revision 1.135
diff -u -r1.134 -r1.135
--- src/usr.bin/mandoc/mandoc.1	2017/07/01 09:47:23	1.134
+++ src/usr.bin/mandoc/mandoc.1	2017/07/02 15:31:48	1.135
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mandoc.1,v 1.134 2017/07/01 09:47:23 schwarze Exp $
+.\"	$OpenBSD: mandoc.1,v 1.135 2017/07/02 15:31:48 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 @@
 .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