1 .\"     $Id: mdoc.7,v 1.269 2017/07/20 16:24:53 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .\"
  19 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  20 .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
  21 .\"
  22 .Dd $Mdocdate: July 20 2017 $
  23 .Dt MDOC 5
  24 .Os
  25 .Sh NAME
  26 .Nm mdoc
  27 .Nd semantic markup language for formatting manual pages
  28 .Sh DESCRIPTION
  29 The
  30 .Nm mdoc
  31 language supports authoring of manual pages for the
  32 .Xr man 1
  33 utility by allowing semantic annotations of words, phrases,
  34 page sections and complete manual pages.
  35 Such annotations are used by formatting tools to achieve a uniform
  36 presentation across all manuals written in
  37 .Nm ,
  38 and to support hyperlinking if supported by the output medium.
  39 .Pp
  40 This reference document describes the structure of manual pages
  41 and the syntax and usage of the
  42 .Nm

 782 .Fl nosplit .
 783 The effect of selecting either of the
 784 .Fl split
 785 modes ends at the beginning of the
 786 .Em AUTHORS
 787 section.
 788 In the
 789 .Em AUTHORS
 790 section, the default is
 791 .Fl nosplit
 792 for the first author listing and
 793 .Fl split
 794 for all other author listings.
 795 .Pp
 796 Examples:
 797 .Dl \&.An -nosplit
 798 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
 799 .Ss \&Ao
 800 Begin a block enclosed by angle brackets.
 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 .
 808 .Ss \&Ap
 809 Inserts an apostrophe without any surrounding whitespace.
 810 This is generally used as a grammatical device when referring to the verb
 811 form of a function.
 812 .Pp
 813 Examples:
 814 .Dl \&.Fn execve \&Ap d
 815 .Ss \&Aq
 816 Encloses its arguments in angle brackets.




 817 .Pp
 818 Examples:
 819 .Dl \&.Fl -key= \&Ns \&Aq \&Ar val




 820 .Pp
 821 .Em Remarks :
 822 this macro is often abused for rendering URIs, which should instead use
 823 .Sx \&Lk






















 824 or
 825 .Sx \&Mt ,
 826 or to note pre-processor
 827 .Dq Li #include
 828 statements, which should use
 829 .Sx \&In .
 830 .Pp
 831 See also
 832 .Sx \&Ao .
 833 .Ss \&Ar
 834 Command arguments.
 835 If an argument is not provided, the string
 836 .Dq file ...\&
 837 is used as a default.
 838 .Pp
 839 Examples:
 840 .Dl ".Fl o Ar file"
 841 .Dl ".Ar"
 842 .Dl ".Ar arg1 , arg2 ."
 843 .Pp
 844 The arguments to the
 845 .Sx \&Ar
 846 macro are names and placeholders for command arguments;
 847 for fixed strings to be passed verbatim as arguments, use
 848 .Sx \&Fl
 849 or

1318 and groff including its arguments.
1319 It was formerly used to toggle a debugging mode.
1320 .Ss \&Dc
1321 Close a
1322 .Sx \&Do
1323 block.
1324 Does not have any tail arguments.
1325 .Ss \&Dd
1326 Document date for display in the page footer.
1327 This is the mandatory first macro of any
1328 .Nm
1329 manual.
1330 Its syntax is as follows:
1331 .Pp
1332 .D1 Pf \. Sx \&Dd Ar month day , year
1333 .Pp
1334 The
1335 .Ar month
1336 is the full English month name, the
1337 .Ar day
1338 is an optionally zero-padded numeral, and the
1339 .Ar year
1340 is the full four-digit year.
1341 .Pp
1342 Other arguments are not portable; the
1343 .Xr mandoc 1
1344 utility handles them as follows:
1345 .Bl -dash -offset 3n -compact
1346 .It
1347 To have the date automatically filled in by the
1348 .Ox
1349 version of
1350 .Xr cvs 1 ,
1351 the special string
1352 .Dq $\&Mdocdate$
1353 can be given as an argument.
1354 .It
1355 The traditional, purely numeric
1356 .Xr man 5
1357 format
1358 .Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
1359 is accepted, too.
1360 .It
1361 If a date string cannot be parsed, it is used verbatim.
1362 .It
1363 If no date string is given, the current date is used.
1364 .El
1365 .Pp
1366 Examples:
1367 .Dl \&.Dd $\&Mdocdate$
1368 .Dl \&.Dd $\&Mdocdate: July 21 2007$
1369 .Dl \&.Dd July 21, 2007
1370 .Pp
1371 See also
1372 .Sx \&Dt
1373 and
1374 .Sx \&Os .
1375 .Ss \&Dl
1376 One-line indented display.
1377 This is formatted as literal text and is useful for commands and
1378 invocations.
1379 It is followed by a newline.
1380 .Pp
1381 Examples:
1382 .Dl \&.Dl % mandoc mdoc.5 \e(ba less
1383 .Pp
1384 See also
1385 .Sx \&Ql ,
1386 .Sx \&Bd
1387 .Fl literal ,
1388 and
1389 .Sx \&D1 .

   1 .\"     $Id: mdoc.7,v 1.271 2018/07/28 18:34:15 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2010, 2011, 2013-2018 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .\"
  19 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  20 .\" Copyright 2018 Nexenta Systems, Inc.
  21 .\"
  22 .Dd $Mdocdate: July 28 2018 $
  23 .Dt MDOC 5
  24 .Os
  25 .Sh NAME
  26 .Nm mdoc
  27 .Nd semantic markup language for formatting manual pages
  28 .Sh DESCRIPTION
  29 The
  30 .Nm mdoc
  31 language supports authoring of manual pages for the
  32 .Xr man 1
  33 utility by allowing semantic annotations of words, phrases,
  34 page sections and complete manual pages.
  35 Such annotations are used by formatting tools to achieve a uniform
  36 presentation across all manuals written in
  37 .Nm ,
  38 and to support hyperlinking if supported by the output medium.
  39 .Pp
  40 This reference document describes the structure of manual pages
  41 and the syntax and usage of the
  42 .Nm

 782 .Fl nosplit .
 783 The effect of selecting either of the
 784 .Fl split
 785 modes ends at the beginning of the
 786 .Em AUTHORS
 787 section.
 788 In the
 789 .Em AUTHORS
 790 section, the default is
 791 .Fl nosplit
 792 for the first author listing and
 793 .Fl split
 794 for all other author listings.
 795 .Pp
 796 Examples:
 797 .Dl \&.An -nosplit
 798 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
 799 .Ss \&Ao
 800 Begin a block enclosed by angle brackets.
 801 Does not have any head arguments.
 802 This macro is almost never useful.
 803 See
 804 .Sx \&Aq
 805 for more details.


 806 .Ss \&Ap
 807 Inserts an apostrophe without any surrounding whitespace.
 808 This is generally used as a grammatical device when referring to the verb
 809 form of a function.
 810 .Pp
 811 Examples:
 812 .Dl \&.Fn execve \&Ap d
 813 .Ss \&Aq
 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.
 819 .Pp
 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
 826 .Pp
 827 For URIs, use

 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 ,
 851 or
 852 .Sx \&Eo
 853 as needed.



 854 .Pp
 855 See also
 856 .Sx \&Ao .
 857 .Ss \&Ar
 858 Command arguments.
 859 If an argument is not provided, the string
 860 .Dq file ...\&
 861 is used as a default.
 862 .Pp
 863 Examples:
 864 .Dl ".Fl o Ar file"
 865 .Dl ".Ar"
 866 .Dl ".Ar arg1 , arg2 ."
 867 .Pp
 868 The arguments to the
 869 .Sx \&Ar
 870 macro are names and placeholders for command arguments;
 871 for fixed strings to be passed verbatim as arguments, use
 872 .Sx \&Fl
 873 or

1342 and groff including its arguments.
1343 It was formerly used to toggle a debugging mode.
1344 .Ss \&Dc
1345 Close a
1346 .Sx \&Do
1347 block.
1348 Does not have any tail arguments.
1349 .Ss \&Dd
1350 Document date for display in the page footer.
1351 This is the mandatory first macro of any
1352 .Nm
1353 manual.
1354 Its syntax is as follows:
1355 .Pp
1356 .D1 Pf \. Sx \&Dd Ar month day , year
1357 .Pp
1358 The
1359 .Ar month
1360 is the full English month name, the
1361 .Ar day
1362 is an integer number, and the
1363 .Ar year
1364 is the full four-digit year.
1365 .Pp
1366 Other arguments are not portable; the
1367 .Xr mandoc 1
1368 utility handles them as follows:
1369 .Bl -dash -offset 3n -compact
1370 .It
1371 To have the date automatically filled in by the
1372 .Ox
1373 version of
1374 .Xr cvs 1 ,
1375 the special string
1376 .Dq $\&Mdocdate$
1377 can be given as an argument.
1378 .It
1379 The traditional, purely numeric
1380 .Xr man 5
1381 format
1382 .Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
1383 is accepted, too.
1384 .It
1385 If a date string cannot be parsed, it is used verbatim.
1386 .It
1387 If no date string is given, the current date is used.
1388 .El
1389 .Pp
1390 Examples:
1391 .Dl \&.Dd $\&Mdocdate$
1392 .Dl \&.Dd $\&Mdocdate: July 2 2018$
1393 .Dl \&.Dd July 2, 2018
1394 .Pp
1395 See also
1396 .Sx \&Dt
1397 and
1398 .Sx \&Os .
1399 .Ss \&Dl
1400 One-line indented display.
1401 This is formatted as literal text and is useful for commands and
1402 invocations.
1403 It is followed by a newline.
1404 .Pp
1405 Examples:
1406 .Dl \&.Dl % mandoc mdoc.5 \e(ba less
1407 .Pp
1408 See also
1409 .Sx \&Ql ,
1410 .Sx \&Bd
1411 .Fl literal ,
1412 and
1413 .Sx \&D1 .