=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.288 retrieving revision 1.296 diff -u -p -r1.288 -r1.296 --- mandoc/mdoc.7 2021/12/06 16:26:08 1.288 +++ mandoc/mdoc.7 2025/01/27 03:17:33 1.296 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.288 2021/12/06 16:26:08 schwarze Exp $ +.\" $Id: mdoc.7,v 1.296 2025/01/27 03:17:33 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze @@ -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: December 6 2021 $ +.Dd $Mdocdate: January 27 2025 $ .Dt MDOC 7 .Os .Sh NAME @@ -439,7 +439,7 @@ in the alphabetical .Bl -column "Brq, Bro, Brc" description .It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year .It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch -.It Ic \&Os Ta operating system version: Op Ar system Op Ar version +.It Ic \&Os Ta operating system footer: Op Ar footer text .It Ic \&Nm Ta document name (one argument) .It Ic \&Nd Ta document description (one line) .El @@ -1015,7 +1015,7 @@ A numbered list. No item heads can be specified. Formatted like .Fl bullet , -except that cardinal numbers are used in place of bullets, +except that ordinal numbers are used in place of bullets, starting at 1. .It Fl hang Like @@ -2074,31 +2074,28 @@ Examples: See also .Ic \&Oo . .Tg Os -.It Ic \&Os Op Ar system Op Ar version -Operating system version for display in the page footer. -This is the mandatory third macro of -any +.It Ic \&Os Op Ar footer text +The mandatory third macro of every .Nm file. +Usually, do not specify any arguments, +in particular not the operating system name and/or version. .Pp -The optional -.Ar system -parameter specifies the relevant operating system or environment. -It is suggested to leave it unspecified, in which case +If no argument is given, .Xr mandoc 1 -uses its +prints its .Fl Ios -argument or, if that isn't specified either, +argument in the page footer, or .Fa sysname and .Fa release as returned by -.Xr uname 3 . +.Xr uname 3 +by default. .Pp -Examples: -.Dl \&.Os -.Dl \&.Os KTH/CSC/TCS -.Dl \&.Os BSD 4.3 +Manual pages that are part of a portable software project can override +the default by giving the project name and version number as arguments, +but leaving it blank is never a bad choice. .Pp See also .Ic \&Dd @@ -2300,14 +2297,15 @@ Close single-quoted context opened by Begin a new section. For a list of conventional manual sections, see .Sx MANUAL STRUCTURE . -These sections should be used unless it's absolutely necessary that -custom sections be used. +Use the conventional sections where applicable. +For unusually long and complicated manual pages, +adding custom sections is occasionally useful. .Pp -Section names should be unique so that they may be keyed by +Avoid using macros inside the +.Ar TITLE LINE +and keep that line unique within the manual page, +such that it can be pointed to with .Ic \&Sx . -Although this macro is parsed, it should not consist of child node or it -may not be linked with -.Ic \&Sx . .Pp See also .Ic \&Pp , @@ -2356,11 +2354,11 @@ the conventional sections described in .Sx MANUAL STRUCTURE rarely have subsections. .Pp -Sub-section names should be unique so that they may be keyed by +Avoid using macros inside the +.Ar Title line +and keep that line unique within the manual page, +such that it can be pointed to with .Ic \&Sx . -Although this macro is parsed, it should not consist of child node or it -may not be linked with -.Ic \&Sx . .Pp See also .Ic \&Pp , @@ -2401,14 +2399,19 @@ The original C standard. .It \-isoC-99 .St -isoC-99 .br -The second major version of the C language standard. +Edition 2 of the C language standard. .Pp .It \-isoC-2011 .St -isoC-2011 .br -The third major version of the C language standard. +Edition 3 of the C language standard. +.Pp +.It \-isoC-2023 +.St -isoC-2023 +.br +Edition 5 of the C language standard. .El -.It POSIX.1 before the Single UNIX Specification +.It POSIX.1 before XPG4.2 .Pp .Bl -tag -width "-p1003.1g-2000" -compact .It \-p1003.1-88 @@ -2449,7 +2452,7 @@ Technical Corrigendum. .br Includes POSIX.1-1990, 1b, 1c, and 1i. .El -.It X/Open Portability Guide version 4 and related standards +.It X/Open Portability Guide before XPG4.2 .Pp .Bl -tag -width "-p1003.1g-2000" -compact .It \-xpg3 @@ -2476,7 +2479,7 @@ Updates to POSIX.2. .br Based on POSIX.1 and POSIX.2, published in 1992. .El -.It Single UNIX Specification version 1 and related standards +.It X/Open Portability Guide Issue 4 Version 2 and related standards .Pp .Bl -tag -width "-p1003.1g-2000" -compact .It \-susv1 @@ -2486,11 +2489,8 @@ Based on POSIX.1 and POSIX.2, published in 1992. .br This standard was published in 1994. It was used as the basis for UNIX 95 certification. -The following three refer to parts of it. +The following two refer to parts of it. .Pp -.It \-xsh4.2 -.St -xsh4.2 -.Pp .It \-xcurses4.2 .St -xcurses4.2 .Pp @@ -2504,13 +2504,14 @@ Networking APIs, including sockets. .br Published in 1995. .El -.It Single UNIX Specification version 2 and related standards +.It X/Open Portability Guide Issue 5 and related standards .Pp .Bl -tag -width "-p1003.1g-2000" -compact .It \-susv2 .St -susv2 +.br This Standard was published in 1997 -and is also called X/Open Portability Guide version 5. +and is also called X/Open Portability Guide Issue 5. It was used as the basis for UNIX 98 certification. The following refer to parts of it. .Pp @@ -2528,7 +2529,7 @@ The following refer to parts of it. .It \-xns5.2 .St -xns5.2 .El -.It Single UNIX Specification version 3 +.It POSIX Issue 6 .Pp .Bl -tag -width "-p1003.1-2001" -compact .It \-p1003.1-2001 @@ -2537,7 +2538,7 @@ The following refer to parts of it. .St -susv3 .br This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. -It is also called X/Open Portability Guide version 6. +It is also called X/Open Portability Guide Issue 6. It is used as the basis for UNIX 03 certification. .Pp .It \-p1003.1-2004 @@ -2545,7 +2546,7 @@ It is used as the basis for UNIX 03 certification. .br The second and last Technical Corrigendum. .El -.It Single UNIX Specification version 4 +.It POSIX Issues 7 and 8 .Pp .Bl -tag -width "-p1003.1g-2000" -compact .It \-p1003.1-2008 @@ -2553,9 +2554,19 @@ The second and last Technical Corrigendum. .It \-susv4 .St -susv4 .br -This standard is also called -X/Open Portability Guide version 7. +This standard is based on C99. +It is also called the +Open Group Standard Base Specifications, Issue 7. .El +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-2024 +.St -p1003.1-2024 +.br +This standard is based on C17. +It is also called the +Open Group Standard Base Specifications, Issue 8. +.El .It Other standards .Pp .Bl -tag -width "-p1003.1g-2000" -compact @@ -3012,7 +3023,7 @@ then the macro accepts an arbitrary number of argument .It Ic \&Fx Ta Yes Ta Yes Ta n .It Ic \&Hf Ta \&No Ta \&No Ta n .It Ic \&Ic Ta Yes Ta Yes Ta >0 -.It Ic \&In Ta \&No Ta \&No Ta 1 +.It Ic \&In Ta Yes Ta Yes Ta 1 .It Ic \&Lb Ta \&No Ta \&No Ta 1 .It Ic \&Li Ta Yes Ta Yes Ta >0 .It Ic \&Lk Ta Yes Ta Yes Ta >0