From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from localhost (fantadrom.bsd.lv [local])
	by fantadrom.bsd.lv (OpenSMTPD) with ESMTPA id 3128f05a
	for <source@mandoc.bsd.lv>;
	Mon, 23 Oct 2017 08:55:12 -0500 (EST)
Date: Mon, 23 Oct 2017 08:55:12 -0500 (EST)
Message-Id: <3260882547294137816.enqueue@fantadrom.bsd.lv>
X-Mailinglist: mandoc-source
Reply-To: source@mandoc.bsd.lv
MIME-Version: 1.0
From: schwarze@mandoc.bsd.lv
To: source@mandoc.bsd.lv
Subject: mandoc: Modernize documentation of .Ao and .Aq.
X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/
Content-Type: text/plain; charset=utf-8

Log Message:
-----------
Modernize documentation of .Ao and .Aq.

I looked through our whole tree and failed to find a single use 
that is really convincing, except those with .Mt.  Putting it around
character and key names is somewhat widespread and maybe acceptable,
even if hardly useful.                           

So for now, delete the bogus examples and explain what these macros
are really used for.  Discourage the most common abuses.

Triggered by a question from Raf Czlonka <rczlonka at gmail dot com>.

Modified Files:
--------------
    mandoc:
        mdoc.7

Revision Data
-------------
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc.7,v
retrieving revision 1.269
retrieving revision 1.270
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.269 -r1.270
--- mdoc.7
+++ mdoc.7
@@ -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 .
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv