diff options
Diffstat (limited to 'usr/src/man/man5/mdoc.5')
| -rw-r--r-- | usr/src/man/man5/mdoc.5 | 68 |
1 files changed, 46 insertions, 22 deletions
diff --git a/usr/src/man/man5/mdoc.5 b/usr/src/man/man5/mdoc.5 index 97146f0c9b..4bddad05a1 100644 --- a/usr/src/man/man5/mdoc.5 +++ b/usr/src/man/man5/mdoc.5 @@ -1,7 +1,7 @@ -.\" $Id: mdoc.7,v 1.269 2017/07/20 16:24:53 schwarze Exp $ +.\" $Id: mdoc.7,v 1.271 2018/07/28 18:34:15 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2010, 2011, 2013-2018 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -17,9 +17,9 @@ .\" .\" .\" Copyright 2014 Garrett D'Amore <garrett@damore.org> -.\" Copyright 2015 Nexenta Systems, Inc. All rights reserved. +.\" Copyright 2018 Nexenta Systems, Inc. .\" -.Dd $Mdocdate: July 20 2017 $ +.Dd $Mdocdate: July 28 2018 $ .Dt MDOC 5 .Os .Sh NAME @@ -799,12 +799,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 @@ -814,19 +812,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 . @@ -1335,7 +1359,7 @@ The .Ar month is the full English month name, the .Ar day -is an optionally zero-padded numeral, and the +is an integer number, and the .Ar year is the full four-digit year. .Pp @@ -1365,8 +1389,8 @@ If no date string is given, the current date is used. .Pp Examples: .Dl \&.Dd $\&Mdocdate$ -.Dl \&.Dd $\&Mdocdate: July 21 2007$ -.Dl \&.Dd July 21, 2007 +.Dl \&.Dd $\&Mdocdate: July 2 2018$ +.Dl \&.Dd July 2, 2018 .Pp See also .Sx \&Dt |