From 6a737689ceb3a73b0708cc7fb7c9e3ada3396803 Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Fri, 23 Feb 2018 18:53:49 +0000
Subject: [PATCH] clarify documentation of macro keys

---
 usr.bin/mandoc/apropos.1 | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/usr.bin/mandoc/apropos.1 b/usr.bin/mandoc/apropos.1
index 6867ea418de..4452881e781 100644
--- a/usr.bin/mandoc/apropos.1
+++ b/usr.bin/mandoc/apropos.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: apropos.1,v 1.38 2017/07/04 23:38:49 schwarze Exp $
+.\"	$OpenBSD: apropos.1,v 1.39 2018/02/23 18:53:49 schwarze Exp $
 .\"
 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2011, 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 4 2017 $
+.Dd $Mdocdate: February 23 2018 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
@@ -328,6 +328,29 @@ Text production:
 .It Li \&Ox Ta Ox No version reference
 .It Li \&Dx Ta Dx No version reference
 .El
+.Pp
+In general, macro keys are supposed to yield complete results without
+expecting the user to consider actual macro usage.
+For example, results include:
+.Pp
+.Bl -tag -width 3n -offset 3n -compact
+.It Li \&Fa
+function arguments appearing on
+.Ic \&Fn
+lines
+.It Li \&Fn
+fuction names marked up with
+.Ic \&Fo
+macros
+.It Li \&In
+include file names marked up with
+.Ic \&Fd
+macros
+.It Li \&Vt
+types appearing as function return types and
+.It \&
+types appearing in function arguments in the SYNOPSIS
+.El
 .Sh ENVIRONMENT
 .Bl -tag -width MANPAGER
 .It Ev MANPAGER
-- 
2.20.1