diff options
| -rw-r--r-- | share/man/man7/mdoc.7 | 58 |
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 . |