1 files changed, 41 insertions, 17 deletions
diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7
index 8ddaa643721..78f7aaec91f 100644
--- a/share/man/man7/mdoc.7
+++ b/share/man/man7/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.7,v 1.157 2017/07/20 16:22:39 schwarze Exp $
+.\"	$OpenBSD: mdoc.7,v 1.158 2017/10/23 13:52:33 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013-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 20 2017 $
+.Dd $Mdocdate: October 23 2017 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -674,12 +674,10 @@ Examples:
 .Ss \&Ao
 Begin a block enclosed by angle brackets.
 Does not have any head arguments.
-.Pp
-Examples:
-.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
-.Pp
-See also
-.Sx \&Aq .
+This macro is almost never useful.
+See
+.Sx \&Aq
+for more details.
 .Ss \&Ap
 Inserts an apostrophe without any surrounding whitespace.
 This is generally used as a grammatical device when referring to the verb
@@ -689,19 +687,45 @@ Examples:
 .Dl \&.Fn execve \&Ap d
 .Ss \&Aq
 Encloses its arguments in angle brackets.
+The only important use case is for email addresses.
+See
+.Sx \&Mt
+for an example.
 .Pp
-Examples:
-.Dl \&.Fl -key= \&Ns \&Aq \&Ar val
+Occasionally, it is used for names of characters and keys, for example:
+.Bd -literal -offset indent
+Press the
+\&.Aq escape
+key to ...
+.Ed
 .Pp
-.Em Remarks :
-this macro is often abused for rendering URIs, which should instead use
+For URIs, use
 .Sx \&Lk
+instead, and
+.Sx \&In
+for
+.Dq #include
+directives.
+Never wrap
+.Sx \&Ar
+in
+.Sx \&Aq .
+.Pp
+Since
+.Sx \&Aq
+usually renders with non-ASCII characters in non-ASCII output modes,
+do not use it where the ASCII characters
+.Sq <
+and
+.Sq >
+are required as syntax elements.
+Instead, use these characters directly in such cases, combining them
+with the macros
+.Sx \&Pf ,
+.Sx \&Ns ,
 or
-.Sx \&Mt ,
-or to note pre-processor
-.Dq Li #include
-statements, which should use
-.Sx \&In .
+.Sx \&Eo
+as needed.
 .Pp
 See also
 .Sx \&Ao .