Print this page 
9718 update mandoc to 1.14.4
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man5/mdoc.5
          +++ new/usr/src/man/man5/mdoc.5
   1      -.\"     $Id: mdoc.7,v 1.269 2017/07/20 16:24:53 schwarze Exp $
        1 +.\"     $Id: mdoc.7,v 1.271 2018/07/28 18:34:15 schwarze Exp $
   2    2  .\"
   3    3  .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
   4      -.\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze <schwarze@openbsd.org>
        4 +.\" Copyright (c) 2010, 2011, 2013-2018 Ingo Schwarze <schwarze@openbsd.org>
   5    5  .\"
   6    6  .\" Permission to use, copy, modify, and distribute this software for any
   7    7  .\" purpose with or without fee is hereby granted, provided that the above
   8    8  .\" copyright notice and this permission notice appear in all copies.
   9    9  .\"
  10   10  .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11   11  .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12   12  .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13   13  .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14   14  .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15   15  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16   16  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17   17  .\"
  18   18  .\"
  19   19  .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  20      -.\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
       20 +.\" Copyright 2018 Nexenta Systems, Inc.
  21   21  .\"
  22      -.Dd $Mdocdate: July 20 2017 $
       22 +.Dd $Mdocdate: July 28 2018 $
  23   23  .Dt MDOC 5
  24   24  .Os
  25   25  .Sh NAME
  26   26  .Nm mdoc
  27   27  .Nd semantic markup language for formatting manual pages
  28   28  .Sh DESCRIPTION
  29   29  The
  30   30  .Nm mdoc
  31   31  language supports authoring of manual pages for the
  32   32  .Xr man 1
↓ open down ↓ 759 lines elided ↑ open up ↑ 
 792  792  for the first author listing and
 793  793  .Fl split
 794  794  for all other author listings.
 795  795  .Pp
 796  796  Examples:
 797  797  .Dl \&.An -nosplit
 798  798  .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
 799  799  .Ss \&Ao
 800  800  Begin a block enclosed by angle brackets.
 801  801  Does not have any head arguments.
 802      -.Pp
 803      -Examples:
 804      -.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
 805      -.Pp
 806      -See also
 807      -.Sx \&Aq .
      802 +This macro is almost never useful.
      803 +See
      804 +.Sx \&Aq
      805 +for more details.
 808  806  .Ss \&Ap
 809  807  Inserts an apostrophe without any surrounding whitespace.
 810  808  This is generally used as a grammatical device when referring to the verb
 811  809  form of a function.
 812  810  .Pp
 813  811  Examples:
 814  812  .Dl \&.Fn execve \&Ap d
 815  813  .Ss \&Aq
 816  814  Encloses its arguments in angle brackets.
      815 +The only important use case is for email addresses.
      816 +See
      817 +.Sx \&Mt
      818 +for an example.
 817  819  .Pp
 818      -Examples:
 819      -.Dl \&.Fl -key= \&Ns \&Aq \&Ar val
      820 +Occasionally, it is used for names of characters and keys, for example:
      821 +.Bd -literal -offset indent
      822 +Press the
      823 +\&.Aq escape
      824 +key to ...
      825 +.Ed
 820  826  .Pp
 821      -.Em Remarks :
 822      -this macro is often abused for rendering URIs, which should instead use
      827 +For URIs, use
 823  828  .Sx \&Lk
      829 +instead, and
      830 +.Sx \&In
      831 +for
      832 +.Dq #include
      833 +directives.
      834 +Never wrap
      835 +.Sx \&Ar
      836 +in
      837 +.Sx \&Aq .
      838 +.Pp
      839 +Since
      840 +.Sx \&Aq
      841 +usually renders with non-ASCII characters in non-ASCII output modes,
      842 +do not use it where the ASCII characters
      843 +.Sq <
      844 +and
      845 +.Sq >
      846 +are required as syntax elements.
      847 +Instead, use these characters directly in such cases, combining them
      848 +with the macros
      849 +.Sx \&Pf ,
      850 +.Sx \&Ns ,
 824  851  or
 825      -.Sx \&Mt ,
 826      -or to note pre-processor
 827      -.Dq Li #include
 828      -statements, which should use
 829      -.Sx \&In .
      852 +.Sx \&Eo
      853 +as needed.
 830  854  .Pp
 831  855  See also
 832  856  .Sx \&Ao .
 833  857  .Ss \&Ar
 834  858  Command arguments.
 835  859  If an argument is not provided, the string
 836  860  .Dq file ...\&
 837  861  is used as a default.
 838  862  .Pp
 839  863  Examples:
↓ open down ↓ 488 lines elided ↑ open up ↑ 
1328 1352  .Nm
1329 1353  manual.
1330 1354  Its syntax is as follows:
1331 1355  .Pp
1332 1356  .D1 Pf \. Sx \&Dd Ar month day , year
1333 1357  .Pp
1334 1358  The
1335 1359  .Ar month
1336 1360  is the full English month name, the
1337 1361  .Ar day
1338      -is an optionally zero-padded numeral, and the
     1362 +is an integer number, and the
1339 1363  .Ar year
1340 1364  is the full four-digit year.
1341 1365  .Pp
1342 1366  Other arguments are not portable; the
1343 1367  .Xr mandoc 1
1344 1368  utility handles them as follows:
1345 1369  .Bl -dash -offset 3n -compact
1346 1370  .It
1347 1371  To have the date automatically filled in by the
1348 1372  .Ox
↓ open down ↓ 9 lines elided ↑ open up ↑ 
1358 1382  .Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
1359 1383  is accepted, too.
1360 1384  .It
1361 1385  If a date string cannot be parsed, it is used verbatim.
1362 1386  .It
1363 1387  If no date string is given, the current date is used.
1364 1388  .El
1365 1389  .Pp
1366 1390  Examples:
1367 1391  .Dl \&.Dd $\&Mdocdate$
1368      -.Dl \&.Dd $\&Mdocdate: July 21 2007$
1369      -.Dl \&.Dd July 21, 2007
     1392 +.Dl \&.Dd $\&Mdocdate: July 2 2018$
     1393 +.Dl \&.Dd July 2, 2018
1370 1394  .Pp
1371 1395  See also
1372 1396  .Sx \&Dt
1373 1397  and
1374 1398  .Sx \&Os .
1375 1399  .Ss \&Dl
1376 1400  One-line indented display.
1377 1401  This is formatted as literal text and is useful for commands and
1378 1402  invocations.
1379 1403  It is followed by a newline.
↓ open down ↓ 1932 lines elided ↑ open up ↑ 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX