mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.269 and 1.270

-version 1.269, 2017/07/20 16:24:53
+version 1.270, 2017/10/23 13:54:41
 Line 674  Examples:
 Line 674  Examples:
 Line 674  Examples:
  .Ss \&Ao
  Begin a block enclosed by angle brackets.
  Does not have any head arguments.
- .Pp
+ This macro is almost never useful.
- Examples:
+ See
- .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
+ .Sx \&Aq
- .Pp
+ for more details.
- See also
- .Sx \&Aq .
  .Ss \&Ap
  Inserts an apostrophe without any surrounding whitespace.
  This is generally used as a grammatical device when referring to the verb
-Line 689  Examples:
+Line 687  Examples:
 Line 689  Examples:
 Line 687  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:
+ Occasionally, it is used for names of characters and keys, for example:
- .Dl \&.Fl -key= \&Ns \&Aq \&Ar val
+ .Bd -literal -offset indent
+ Press the
+ \&.Aq escape
+ key to ...
+ .Ed
  .Pp
- .Em Remarks :
+ For URIs, use
- this macro is often abused for rendering URIs, which should instead 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 ,
+ .Sx \&Eo
- or to note pre-processor
+ as needed.
- .Dq Li #include
- statements, which should use
- .Sx \&In .
  .Pp
  See also
  .Sx \&Ao .

CVSweb