=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.162 retrieving revision 1.292 diff -u -p -r1.162 -r1.292 --- mandoc/mdoc.7 2010/10/24 14:49:35 1.162 +++ mandoc/mdoc.7 2024/06/17 15:37:37 1.292 @@ -1,7 +1,7 @@ -.\" $Id: mdoc.7,v 1.162 2010/10/24 14:49:35 schwarze Exp $ +.\" $Id: mdoc.7,v 1.292 2024/06/17 15:37:37 schwarze Exp $ .\" -.\" Copyright (c) 2009, 2010 Kristaps Dzonsons -.\" Copyright (c) 2010 Ingo Schwarze +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons +.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -15,286 +15,78 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: October 24 2010 $ +.Dd $Mdocdate: June 17 2024 $ .Dt MDOC 7 .Os .Sh NAME .Nm mdoc -.Nd mdoc language reference +.Nd semantic markup language for formatting manual pages .Sh DESCRIPTION The .Nm mdoc -language is used to format -.Bx -.Ux -manuals. -This reference document describes its syntax, structure, and -usage. -The reference implementation is +language supports authoring of manual pages for the +.Xr man 1 +utility by allowing semantic annotations of words, phrases, +page sections and complete manual pages. +Such annotations are used by formatting tools to achieve a uniform +presentation across all manuals written in +.Nm , +and to support hyperlinking if supported by the output medium. +.Pp +This reference document describes the structure of manual pages +and the syntax and usage of the +.Nm +language. +The reference implementation of a parsing and formatting tool is .Xr mandoc 1 ; the .Sx COMPATIBILITY -section describes compatibility with other troff \-mdoc implementations. +section describes compatibility with other implementations. .Pp -An +In an .Nm -document follows simple rules: lines beginning with the control -character -.Sq \. -are parsed for macros. -Other lines are interpreted within the scope of -prior macros: +document, lines beginning with the control character +.Sq \&. +are called +.Dq macro lines . +The first word is the macro name. +It consists of two or three letters. +Most macro names begin with a capital letter. +For a list of available macros, see +.Sx MACRO OVERVIEW . +The words following the macro name are arguments to the macro, optionally +including the names of other, callable macros; see +.Sx MACRO SYNTAX +for details. +.Pp +Lines not beginning with the control character are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context: .Bd -literal -offset indent \&.Sh Macro lines change control state. -Other lines are interpreted within the current state. +Text lines are interpreted within the current state. .Ed -.Sh LANGUAGE SYNTAX -.Nm -documents may contain only graphable 7-bit ASCII characters, the space -character, and, in certain circumstances, the tab character. -All manuals must have -.Ux -line terminators. -.Ss Comments -Text following a -.Sq \e\*q , -whether in a macro or free-form text line, is ignored to the end of -line. -A macro line with only a control character and comment escape, -.Sq \&.\e\*q , -is also ignored. -Macro lines with only a control character and optional whitespace are -stripped from input. -.Ss Reserved Characters -Within a macro line, the following characters are reserved: .Pp -.Bl -tag -width Ds -offset indent -compact -.It \&. -.Pq period -.It \&, -.Pq comma -.It \&: -.Pq colon -.It \&; -.Pq semicolon -.It \&( -.Pq left-parenthesis -.It \&) -.Pq right-parenthesis -.It \&[ -.Pq left-bracket -.It \&] -.Pq right-bracket -.It \&? -.Pq question -.It \&! -.Pq exclamation -.It \&| -.Pq vertical bar -.El -.Pp -Use of reserved characters is described in -.Sx MACRO SYNTAX . -For general use in macro lines, these characters can either be escaped -with a non-breaking space -.Pq Sq \e& -or, if applicable, an appropriate escape sequence can be used. -.Ss Special Characters -Special characters may occur in both macro and free-form lines. -Sequences begin with the escape character -.Sq \e -followed by either an open-parenthesis -.Sq \&( -for two-character sequences; an open-bracket -.Sq \&[ -for n-character sequences (terminated at a close-bracket -.Sq \&] ) ; -or a single one character sequence. -See -.Xr mandoc_char 7 -for a complete list. -Examples include -.Sq \e(em -.Pq em-dash +Many aspects of the basic syntax of the +.Nm +language are based on the +.Xr roff 7 +language; see the +.Em LANGUAGE SYNTAX and -.Sq \ee -.Pq back-slash . -.Ss Text Decoration -Terms may be text-decorated using the -.Sq \ef -escape followed by an indicator: B (bold), I (italic), R (Roman), or P -(revert to previous mode): -.Pp -.D1 \efBbold\efR \efIitalic\efP -.Pp -A numerical representation 3, 2, or 1 (bold, italic, and Roman, -respectively) may be used instead. -A text decoration is valid within -the current font scope only: if a macro opens a font scope alongside -its own scope, such as -.Sx \&Bf -.Cm \&Sy , -in-scope invocations of -.Sq \ef -are only valid within the font scope of the macro. -If -.Sq \ef -is specified outside of any font scope, such as in unenclosed, free-form -text, it will affect the remainder of the document. -.Pp -Note this form is -.Em not -recommended for -.Nm , -which encourages semantic annotation. -.Ss Predefined Strings -Historically, -troff -also defined a set of package-specific -.Dq predefined strings , -which, like -.Sx Special Characters , -mark special output characters and strings by way of input codes. -Predefined strings are escaped with the slash-asterisk, -.Sq \e* : -single-character -.Sq \e*X , -two-character -.Sq \e*(XX , -and N-character -.Sq \e*[N] . -See -.Xr mandoc_char 7 -for a complete list. -Examples include -.Sq \e*(Am -.Pq ampersand -and -.Sq \e*(Ba -.Pq vertical bar . -.Ss Whitespace -Whitespace consists of the space character. -In free-form lines, whitespace is preserved within a line; unescaped -trailing spaces are stripped from input (unless in a literal context). -Blank free-form lines, which may include whitespace, are only permitted -within literal contexts. -.Pp -In macro lines, whitespace delimits arguments and is discarded. -If arguments are quoted, whitespace within the quotes is retained. -.Ss Quotation -Macro arguments may be quoted with double-quotes to group -space-delimited terms or to retain blocks of whitespace. -A quoted argument begins with a double-quote preceded by whitespace. -The next double-quote not pairwise adjacent to another double-quote -terminates the literal, regardless of surrounding whitespace. -.Pp -Note that any quoted text, even if it would cause a macro invocation -when unquoted, is considered literal text. -Thus, the following produces -.Sq Op "Fl a" : -.Bd -literal -offset indent -\&.Op "Fl a" -.Ed -.Pp -In free-form mode, quotes are regarded as opaque text. -.Ss Dates -There are several macros in +.Em MACRO SYNTAX +sections in the +.Xr roff 7 +manual for details, in particular regarding +comments, escape sequences, whitespace, and quoting. +However, using +.Xr roff 7 +requests in .Nm -that require a date argument. -The canonical form for dates is the American format: -.Pp -.D1 Cm Month Day , Year -.Pp -The -.Cm Day -value is an optionally zero-padded numeral. -The -.Cm Month -value is the full month name. -The -.Cm Year -value is the full four-digit year. -.Pp -Reduced form dates are broken-down canonical form dates: -.Pp -.D1 Cm Month , Year -.D1 Cm Year -.Pp -Some examples of valid dates follow: -.Pp -.D1 "May, 2009" Pq reduced form -.D1 "2009" Pq reduced form -.D1 "May 20, 2009" Pq canonical form -.Ss Scaling Widths -Many macros support scaled widths for their arguments, such as -stipulating a two-inch list indentation with the following: -.Bd -literal -offset indent -\&.Bl -tag -width 2i -.Ed -.Pp -The syntax for scaled widths is -.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , -where a decimal must be preceded or proceeded by at least one digit. -Negative numbers, while accepted, are truncated to zero. -The following scaling units are accepted: -.Pp -.Bl -tag -width Ds -offset indent -compact -.It c -centimetre -.It i -inch -.It P -pica (~1/6 inch) -.It p -point (~1/72 inch) -.It f -synonym for -.Sq u -.It v -default vertical span -.It m -width of rendered -.Sq m -.Pq em -character -.It n -width of rendered -.Sq n -.Pq en -character -.It u -default horizontal span -.It M -mini-em (~1/100 em) -.El -.Pp -Using anything other than -.Sq m , -.Sq n , -.Sq u , -or -.Sq v -is necessarily non-portable across output media. -See -.Sx COMPATIBILITY . -.Ss Sentence Spacing -When composing a manual, make sure that sentences end at the end of -a line. -By doing so, front-ends will be able to apply the proper amount of -spacing after the end of sentence (unescaped) period, exclamation mark, -or question mark followed by zero or more non-sentence closing -delimiters ( -.Ns Sq \&) , -.Sq \&] , -.Sq \&' , -.Sq \&" ) . -.Pp -The proper spacing is also intelligently preserved if a sentence ends at -the boundary of a macro line. -For example: -.Pp -.D1 \&Xr mandoc 1 \. -.D1 \&Fl T \&Ns \&Cm ascii \. +documents is discouraged; +.Xr mandoc 1 +supports some of them merely for backward compatibility. .Sh MANUAL STRUCTURE A well-formed .Nm @@ -302,18 +94,18 @@ document consists of a document prologue followed by o sections. .Pp The prologue, which consists of the -.Sx \&Dd , -.Sx \&Dt , +.Ic \&Dd , +.Ic \&Dt , and -.Sx \&Os +.Ic \&Os macros in that order, is required for every document. .Pp The first section (sections are denoted by -.Sx \&Sh ) +.Ic \&Sh ) must be the NAME section, consisting of at least one -.Sx \&Nm +.Ic \&Nm followed by -.Sx \&Nd . +.Ic \&Nd . .Pp Following that, convention dictates specifying at least the .Em SYNOPSIS @@ -323,48 +115,51 @@ sections, although this varies between manual sections .Pp The following is a well-formed skeleton .Nm -file: +file for a utility +.Qq progname : .Bd -literal -offset indent \&.Dd $\&Mdocdate$ -\&.Dt mdoc 7 +\&.Dt PROGNAME section \&.Os \&.Sh NAME -\&.Nm foo -\&.Nd a description goes here -\&.\e\*q .Sh LIBRARY -\&.\e\*q For sections 2, 3, & 9 only. -\&.\e\*q Not used in OpenBSD. +\&.Nm progname +\&.Nd one line about what it does +\&.\e\(dq .Sh LIBRARY +\&.\e\(dq For sections 2, 3, and 9 only. +\&.\e\(dq Not used in OpenBSD. \&.Sh SYNOPSIS -\&.Nm foo +\&.Nm progname \&.Op Fl options \&.Ar \&.Sh DESCRIPTION The \&.Nm utility processes files ... -\&.\e\*q .Sh IMPLEMENTATION NOTES -\&.\e\*q Not used in OpenBSD. -\&.\e\*q .Sh RETURN VALUES -\&.\e\*q For sections 2, 3, & 9 only. -\&.\e\*q .Sh ENVIRONMENT -\&.\e\*q For sections 1, 6, 7, & 8 only. -\&.\e\*q .Sh FILES -\&.\e\*q .Sh EXIT STATUS -\&.\e\*q For sections 1, 6, & 8 only. -\&.\e\*q .Sh EXAMPLES -\&.\e\*q .Sh DIAGNOSTICS -\&.\e\*q For sections 1, 4, 6, 7, & 8 only. -\&.\e\*q .Sh ERRORS -\&.\e\*q For sections 2, 3, & 9 only. -\&.\e\*q .Sh SEE ALSO -\&.\e\*q .Xr foobar 1 -\&.\e\*q .Sh STANDARDS -\&.\e\*q .Sh HISTORY -\&.\e\*q .Sh AUTHORS -\&.\e\*q .Sh CAVEATS -\&.\e\*q .Sh BUGS -\&.\e\*q .Sh SECURITY CONSIDERATIONS -\&.\e\*q Not used in OpenBSD. +\&.\e\(dq .Sh CONTEXT +\&.\e\(dq For section 9 functions only. +\&.\e\(dq .Sh IMPLEMENTATION NOTES +\&.\e\(dq Not used in OpenBSD. +\&.\e\(dq .Sh RETURN VALUES +\&.\e\(dq For sections 2, 3, and 9 function return values only. +\&.\e\(dq .Sh ENVIRONMENT +\&.\e\(dq For sections 1, 6, 7, and 8 only. +\&.\e\(dq .Sh FILES +\&.\e\(dq .Sh EXIT STATUS +\&.\e\(dq For sections 1, 6, and 8 only. +\&.\e\(dq .Sh EXAMPLES +\&.\e\(dq .Sh DIAGNOSTICS +\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. +\&.\e\(dq .Sh ERRORS +\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. +\&.\e\(dq .Sh SEE ALSO +\&.\e\(dq .Xr foobar 1 +\&.\e\(dq .Sh STANDARDS +\&.\e\(dq .Sh HISTORY +\&.\e\(dq .Sh AUTHORS +\&.\e\(dq .Sh CAVEATS +\&.\e\(dq .Sh BUGS +\&.\e\(dq .Sh SECURITY CONSIDERATIONS +\&.\e\(dq Not used in OpenBSD. .Ed .Pp The sections in an @@ -382,16 +177,20 @@ The syntax for this as follows: \&.Nd a one line description .Ed .Pp +Multiple +.Sq \&Nm +names should be separated by commas. +.Pp The -.Sx \&Nm +.Ic \&Nm macro(s) must precede the -.Sx \&Nd +.Ic \&Nd macro. .Pp See -.Sx \&Nm +.Ic \&Nm and -.Sx \&Nd . +.Ic \&Nd . .It Em LIBRARY The name of the library containing the documented material, which is assumed to be a function in a section 2, 3, or 9 manual. @@ -401,7 +200,7 @@ The syntax for this is as follows: .Ed .Pp See -.Sx \&Lb . +.Ic \&Lb . .It Em SYNOPSIS Documents the utility invocation syntax, function call syntax, or device configuration. @@ -409,16 +208,18 @@ configuration. For the first, utilities (sections 1, 6, and 8), this is generally structured as follows: .Bd -literal -offset indent -\&.Nm foo +\&.Nm bar \&.Op Fl v \&.Op Fl o Ar file \&.Op Ar -\&.Nm bar +\&.Nm foo \&.Op Fl v \&.Op Fl o Ar file \&.Op Ar .Ed .Pp +Commands should be ordered alphabetically. +.Pp For the second, function calls (sections 2, 3, 9): .Bd -literal -offset indent \&.In header.h @@ -429,10 +230,18 @@ For the second, function calls (sections 2, 3, 9): \&.Fn bar "const char *src" .Ed .Pp +Ordering of +.Ic \&In , +.Ic \&Vt , +.Ic \&Fn , +and +.Ic \&Fo +macros should follow C header-file conventions. +.Pp And for the third, configurations (section 4): .Bd -literal -offset indent -\&.Cd \*qit* at isa? port 0x2e\*q -\&.Cd \*qit* at isa? port 0x4e\*q +\&.Cd \(dqit* at isa? port 0x2e\(dq +\&.Cd \(dqit* at isa? port 0x4e\(dq .Ed .Pp Manuals not in these sections generally don't need a @@ -441,55 +250,84 @@ Manuals not in these sections generally don't need a Some macros are displayed differently in the .Em SYNOPSIS section, particularly -.Sx \&Nm , -.Sx \&Cd , -.Sx \&Fd , -.Sx \&Fn , -.Sx \&Fo , -.Sx \&In , -.Sx \&Vt , +.Ic \&Nm , +.Ic \&Cd , +.Ic \&Fd , +.Ic \&Fn , +.Ic \&Fo , +.Ic \&In , +.Ic \&Vt , and -.Sx \&Ft . +.Ic \&Ft . All of these macros are output on their own line. If two such dissimilar macros are pairwise invoked (except for -.Sx \&Ft +.Ic \&Ft before -.Sx \&Fo +.Ic \&Fo or -.Sx \&Fn ) , +.Ic \&Fn ) , they are separated by a vertical space, unless in the case of -.Sx \&Fo , -.Sx \&Fn , +.Ic \&Fo , +.Ic \&Fn , and -.Sx \&Ft , +.Ic \&Ft , which are always separated by vertical space. .Pp When text and macros following an -.Sx \&Nm +.Ic \&Nm macro starting an input line span multiple output lines, all output lines but the first will be indented to align with the text immediately following the -.Sx \&Nm +.Ic \&Nm macro, up to the next -.Sx \&Nm , -.Sx \&Sh , +.Ic \&Nm , +.Ic \&Sh , or -.Sx \&Ss +.Ic \&Ss macro or the end of an enclosing block, whichever comes first. .It Em DESCRIPTION -This expands upon the brief, one line description in -.Em NAME . -It usually contains a breakdown of the options (if documenting a +This begins with an expansion of the brief, one line description in +.Em NAME : +.Bd -literal -offset indent +The +\&.Nm +utility does this, that, and the other. +.Ed +.Pp +It usually follows with a breakdown of the options (if documenting a command), such as: .Bd -literal -offset indent -The arguments are as follows: +The options are as follows: \&.Bl \-tag \-width Ds \&.It Fl v Print verbose information. \&.El .Ed .Pp +List the options in alphabetical order, +uppercase before lowercase for each letter and +with no regard to whether an option takes an argument. +Put digits in ascending order before all letter options. +.Pp Manuals not documenting a command won't include the above fragment. +.Pp +Since the +.Em DESCRIPTION +section usually contains most of the text of a manual, longer manuals +often use the +.Ic \&Ss +macro to form subsections. +In very long manuals, the +.Em DESCRIPTION +may be split into multiple sections, each started by an +.Ic \&Sh +macro followed by a non-standard section name, and each having +several subsections, like in the present +.Nm +manual. +.It Em CONTEXT +This section lists the contexts in which functions can be called in section 9. +The contexts are autoconf, process, or interrupt. .It Em IMPLEMENTATION NOTES Implementation-specific notes should be kept here. This is useful when implementing standard functions that may have side @@ -499,7 +337,7 @@ This section documents the return values of functions in sections 2, 3, and 9. .Pp See -.Sx \&Rv . +.Ic \&Rv . .It Em ENVIRONMENT Lists the environment variables used by the utility, and explains the syntax and semantics of their values. @@ -508,14 +346,14 @@ The manual provides examples of typical content and formatting. .Pp See -.Sx \&Ev . +.Ic \&Ev . .It Em FILES Documents files used. It's helpful to document both the file name and a short description of how the file is used (created, modified, etc.). .Pp See -.Sx \&Pa . +.Ic \&Pa . .It Em EXIT STATUS This section documents the command exit status for section 1, 6, and 8 utilities. @@ -524,35 +362,47 @@ Historically, this information was described in a practise that is now discouraged. .Pp See -.Sx \&Ex . +.Ic \&Ex . .It Em EXAMPLES Example usages. This often contains snippets of well-formed, well-tested invocations. Make sure that examples work properly! .It Em DIAGNOSTICS -Documents error conditions. -This is most useful in section 4 manuals. +Documents error messages. +In section 4 and 9 manuals, these are usually messages printed by the +kernel to the console and to the kernel log. +In section 1, 6, 7, and 8, these are usually messages printed by +userland programs to the standard error output. +.Pp Historically, this section was used in place of .Em EXIT STATUS for manuals in sections 1, 6, and 8; however, this practise is discouraged. .Pp See -.Sx \&Bl +.Ic \&Bl .Fl diag . .It Em ERRORS -Documents error handling in sections 2, 3, and 9. +Documents +.Xr errno 2 +settings in sections 2, 3, 4, and 9. .Pp See -.Sx \&Er . +.Ic \&Er . .It Em SEE ALSO References other manuals with related topics. This section should exist for most manuals. Cross-references should conventionally be ordered first by section, then -alphabetically. +alphabetically (ignoring case). .Pp +References to other documentation concerning the topic of the manual page, +for example authoritative books or journal articles, may also be +provided in this section. +.Pp See -.Sx \&Xr . +.Ic \&Rs +and +.Ic \&Xr . .It Em STANDARDS References any standards implemented or used. If not adhering to any standards, the @@ -560,15 +410,16 @@ If not adhering to any standards, the section should be used instead. .Pp See -.Sx \&St . +.Ic \&St . .It Em HISTORY -A brief history of the subject, including where support first appeared. +A brief history of the subject, including where it was first implemented, +and when it was ported to or reimplemented for the operating system at hand. .It Em AUTHORS Credits to the person or persons who wrote the code and/or documentation. Authors should generally be noted by both name and email address. .Pp See -.Sx \&An . +.Ic \&An . .It Em CAVEATS Common misuses and misunderstandings should be explained in this section. @@ -578,376 +429,228 @@ in this section. .It Em SECURITY CONSIDERATIONS Documents any security precautions that operators should consider. .El -.Sh MACRO SYNTAX -Macros are one to three three characters in length and begin with a -control character, -.Sq \&. , -at the beginning of the line. -An arbitrary amount of whitespace may sit between the control character -and the macro name. -Thus, the following are equivalent: -.Bd -literal -offset indent -\&.Pp -\&.\ \ \ \&Pp -.Ed -.Pp -The syntax of a macro depends on its classification. -In this section, -.Sq \-arg -refers to macro arguments, which may be followed by zero or more -.Sq parm -parameters; -.Sq \&Yo -opens the scope of a macro; and if specified, -.Sq \&Yc -closes it out. -.Pp -The -.Em Callable -column indicates that the macro may be called subsequent to the initial -line-macro. -If a macro is not callable, then its invocation after the initial line -macro is interpreted as opaque text, such that -.Sq \&.Fl \&Sh -produces -.Sq Fl \&Sh . -.Pp -The -.Em Parsed -column indicates whether the macro may be followed by further -(ostensibly callable) macros. -If a macro is not parsed, subsequent macro invocations on the line -will be interpreted as opaque text. -.Pp -The -.Em Scope -column, if applicable, describes closure rules. -.Ss Block full-explicit -Multi-line scope closed by an explicit closing macro. -All macros contains bodies; only -.Sx \&Bf -contains a head. -.Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB -\(lBbody...\(rB -\&.Yc -.Ed -.Pp -.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX" -.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope -.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed -.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef -.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek -.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El -.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd -.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf -.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk -.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl +.Sh MACRO OVERVIEW +This overview is sorted such that macros of similar purpose are listed +together, to help find the best macro for any given purpose. +Deprecated macros are not included in the overview, but can be found below +in the alphabetical +.Sx MACRO REFERENCE . +.Ss Document preamble and NAME section macros +.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 footer: Op Ar footer text +.It Ic \&Nm Ta document name (one argument) +.It Ic \&Nd Ta document description (one line) .El -.Ss Block full-implicit -Multi-line scope closed by end-of-file or implicitly by another macro. -All macros have bodies; some -.Po -.Sx \&It Fl bullet , -.Fl hyphen , -.Fl dash , -.Fl enum , -.Fl item -.Pc -don't have heads; only one -.Po -.Sx \&It -in -.Sx \&Bl Fl column -.Pc -has multiple heads. -.Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB -\(lBbody...\(rB -.Ed -.Pp -.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope -.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El -.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh -.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss -.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh -.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss +.Ss Sections and cross references +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Sh Ta section header (one line) +.It Ic \&Ss Ta subsection header (one line) +.It Ic \&Sx Ta internal cross reference to a section or subsection +.It Ic \&Xr Ta cross reference to another manual page: Ar name section +.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments +.It Ic \&Pp Ta start a text paragraph (no arguments) .El -.Pp -Note that the -.Sx \&Nm -macro is a -.Sx Block full-implicit -macro only when invoked as the first macro -in a -.Em SYNOPSIS -section line, else it is -.Sx In-line . -.Ss Block partial-explicit -Like block full-explicit, but also with single-line scope. -Each has at least a body and, in limited circumstances, a head -.Po -.Sx \&Fo , -.Sx \&Eo -.Pc -and/or tail -.Pq Sx \&Ec . -.Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB -\(lBbody...\(rB -\&.Yc \(lBtail...\(rB - -\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ -\(lBbody...\(rB \&Yc \(lBtail...\(rB -.Ed -.Pp -.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent -.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope -.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao -.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac -.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo -.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc -.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro -.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc -.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do -.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc -.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo -.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec -.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo -.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc -.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo -.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc -.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po -.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc -.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo -.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc -.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs -.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re -.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So -.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc -.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo -.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc +.Ss Displays and lists +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Bd , \&Ed Ta display block: +.Fl Ar type +.Op Fl offset Ar width +.Op Fl compact +.It Ic \&D1 Ta indented display (one line) +.It Ic \&Dl Ta indented literal display (one line) +.It Ic \&Ql Ta in-line literal display: Ql text +.It Ic \&Bl , \&El Ta list block: +.Fl Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.It Ic \&It Ta list item (syntax depends on Fl Ar type ) +.It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists +.It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references) .El -.Ss Block partial-implicit -Like block full-implicit, but with single-line scope closed by -.Sx Reserved Characters -or end of line. -.Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB -.Ed -.Pp -.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent -.It Em Macro Ta Em Callable Ta Em Parsed -.It Sx \&Aq Ta Yes Ta Yes -.It Sx \&Bq Ta Yes Ta Yes -.It Sx \&Brq Ta Yes Ta Yes -.It Sx \&D1 Ta \&No Ta \&Yes -.It Sx \&Dl Ta \&No Ta Yes -.It Sx \&Dq Ta Yes Ta Yes -.It Sx \&Op Ta Yes Ta Yes -.It Sx \&Pq Ta Yes Ta Yes -.It Sx \&Ql Ta Yes Ta Yes -.It Sx \&Qq Ta Yes Ta Yes -.It Sx \&Sq Ta Yes Ta Yes -.It Sx \&Vt Ta Yes Ta Yes +.Ss Spacing control +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Pf Ta prefix, no following horizontal space (one argument) +.It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments) +.It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments) +.It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off +.It Ic \&Bk , \&Ek Ta keep block: Fl words .El -.Pp -Note that the -.Sx \&Vt -macro is a -.Sx Block partial-implicit -only when invoked as the first macro -in a -.Em SYNOPSIS -section line, else it is -.Sx In-line . -.Ss In-line -Closed by -.Sx Reserved Characters , -end of line, fixed argument lengths, and/or subsequent macros. -In-line macros have only text children. -If a number (or inequality) of arguments is -.Pq n , -then the macro accepts an arbitrary number of arguments. -.Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB - -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... - -\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN -.Ed -.Pp -.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent -.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments -.It Sx \&%A Ta \&No Ta \&No Ta >0 -.It Sx \&%B Ta \&No Ta \&No Ta >0 -.It Sx \&%C Ta \&No Ta \&No Ta >0 -.It Sx \&%D Ta \&No Ta \&No Ta >0 -.It Sx \&%I Ta \&No Ta \&No Ta >0 -.It Sx \&%J Ta \&No Ta \&No Ta >0 -.It Sx \&%N Ta \&No Ta \&No Ta >0 -.It Sx \&%O Ta \&No Ta \&No Ta >0 -.It Sx \&%P Ta \&No Ta \&No Ta >0 -.It Sx \&%Q Ta \&No Ta \&No Ta >0 -.It Sx \&%R Ta \&No Ta \&No Ta >0 -.It Sx \&%T Ta \&No Ta \&No Ta >0 -.It Sx \&%U Ta \&No Ta \&No Ta >0 -.It Sx \&%V Ta \&No Ta \&No Ta >0 -.It Sx \&Ad Ta Yes Ta Yes Ta n -.It Sx \&An Ta Yes Ta Yes Ta n -.It Sx \&Ap Ta Yes Ta Yes Ta 0 -.It Sx \&Ar Ta Yes Ta Yes Ta n -.It Sx \&At Ta Yes Ta Yes Ta 1 -.It Sx \&Bsx Ta Yes Ta Yes Ta n -.It Sx \&Bt Ta \&No Ta \&No Ta 0 -.It Sx \&Bx Ta Yes Ta Yes Ta n -.It Sx \&Cd Ta Yes Ta Yes Ta >0 -.It Sx \&Cm Ta Yes Ta Yes Ta n -.It Sx \&Db Ta \&No Ta \&No Ta 1 -.It Sx \&Dd Ta \&No Ta \&No Ta n -.It Sx \&Dt Ta \&No Ta \&No Ta n -.It Sx \&Dv Ta Yes Ta Yes Ta n -.It Sx \&Dx Ta Yes Ta Yes Ta n -.It Sx \&Em Ta Yes Ta Yes Ta >0 -.It Sx \&En Ta \&No Ta \&No Ta 0 -.It Sx \&Er Ta Yes Ta Yes Ta >0 -.It Sx \&Es Ta \&No Ta \&No Ta 0 -.It Sx \&Ev Ta Yes Ta Yes Ta n -.It Sx \&Ex Ta \&No Ta \&No Ta n -.It Sx \&Fa Ta Yes Ta Yes Ta n -.It Sx \&Fd Ta \&No Ta \&No Ta >0 -.It Sx \&Fl Ta Yes Ta Yes Ta n -.It Sx \&Fn Ta Yes Ta Yes Ta >0 -.It Sx \&Fr Ta \&No Ta \&No Ta n -.It Sx \&Ft Ta Yes Ta Yes Ta n -.It Sx \&Fx Ta Yes Ta Yes Ta n -.It Sx \&Hf Ta \&No Ta \&No Ta n -.It Sx \&Ic Ta Yes Ta Yes Ta >0 -.It Sx \&In Ta \&No Ta \&No Ta n -.It Sx \&Lb Ta \&No Ta \&No Ta 1 -.It Sx \&Li Ta Yes Ta Yes Ta n -.It Sx \&Lk Ta Yes Ta Yes Ta n -.It Sx \&Lp Ta \&No Ta \&No Ta 0 -.It Sx \&Ms Ta Yes Ta Yes Ta >0 -.It Sx \&Mt Ta Yes Ta Yes Ta >0 -.It Sx \&Nm Ta Yes Ta Yes Ta n -.It Sx \&No Ta Yes Ta Yes Ta 0 -.It Sx \&Ns Ta Yes Ta Yes Ta 0 -.It Sx \&Nx Ta Yes Ta Yes Ta n -.It Sx \&Os Ta \&No Ta \&No Ta n -.It Sx \&Ot Ta \&No Ta \&No Ta n -.It Sx \&Ox Ta Yes Ta Yes Ta n -.It Sx \&Pa Ta Yes Ta Yes Ta n -.It Sx \&Pf Ta Yes Ta Yes Ta 1 -.It Sx \&Pp Ta \&No Ta \&No Ta 0 -.It Sx \&Rv Ta \&No Ta \&No Ta n -.It Sx \&Sm Ta \&No Ta \&No Ta 1 -.It Sx \&St Ta \&No Ta Yes Ta 1 -.It Sx \&Sx Ta Yes Ta Yes Ta >0 -.It Sx \&Sy Ta Yes Ta Yes Ta >0 -.It Sx \&Tn Ta Yes Ta Yes Ta >0 -.It Sx \&Ud Ta \&No Ta \&No Ta 0 -.It Sx \&Ux Ta Yes Ta Yes Ta n -.It Sx \&Va Ta Yes Ta Yes Ta n -.It Sx \&Vt Ta Yes Ta Yes Ta >0 -.It Sx \&Xr Ta Yes Ta Yes Ta >0 -.It Sx \&br Ta \&No Ta \&No Ta 0 -.It Sx \&sp Ta \&No Ta \&No Ta 1 +.Ss Semantic markup for command line utilities +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility +.It Ic \&Fl Ta command line options (flags) (>=0 arguments) +.It Ic \&Cm Ta command modifier (>0 arguments) +.It Ic \&Ar Ta command arguments (>=0 arguments) +.It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) +.It Ic \&Ic Ta internal or interactive command (>0 arguments) +.It Ic \&Ev Ta environmental variable (>0 arguments) +.It Ic \&Pa Ta file system path (>=0 arguments) .El -.Sh REFERENCE +.Ss Semantic markup for function libraries +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Lb Ta function library (one argument) +.It Ic \&In Ta include file (one argument) +.It Ic \&Fd Ta other preprocessor directive (>0 arguments) +.It Ic \&Ft Ta function type (>0 arguments) +.It Ic \&Fo , \&Fc Ta function block: Ar funcname +.It Ic \&Fn Ta function name: Ar funcname Op Ar argument ... +.It Ic \&Fa Ta function argument (>0 arguments) +.It Ic \&Vt Ta variable type (>0 arguments) +.It Ic \&Va Ta variable name (>0 arguments) +.It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments) +.It Ic \&Er Ta error constant (>0 arguments) +.It Ic \&Ev Ta environmental variable (>0 arguments) +.El +.Ss Various semantic markup +.Bl -column "Brq, Bro, Brc" description +.It Ic \&An Ta author name (>0 arguments) +.It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name +.It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain +.It Ic \&Cd Ta kernel configuration declaration (>0 arguments) +.It Ic \&Ad Ta memory address (>0 arguments) +.It Ic \&Ms Ta mathematical symbol (>0 arguments) +.El +.Ss Physical markup +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments) +.It Ic \&Sy Ta boldface font (symbolic) (>0 arguments) +.It Ic \&No Ta return to roman font (normal) (>0 arguments) +.It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy +.El +.Ss Physical enclosures +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text +.It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text +.It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text +.It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text +.It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text +.It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text +.It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text +.It Ic \&Eo , \&Ec Ta generic enclosure +.El +.Ss Text production +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ... +.It Ic \&Rv Fl std Ta standard function return values: Op Ar function ... +.It Ic \&St Ta reference to a standards document (one argument) +.It Ic \&At Ta At +.It Ic \&Bx Ta Bx +.It Ic \&Bsx Ta Bsx +.It Ic \&Nx Ta Nx +.It Ic \&Fx Ta Fx +.It Ic \&Ox Ta Ox +.It Ic \&Dx Ta Dx +.El +.Sh MACRO REFERENCE This section is a canonical reference of all macros, arranged alphabetically. For the scoping of individual macros, see .Sx MACRO SYNTAX . -.Ss \&%A +.Bl -tag -width 3n +.It Ic \&%A Ar first_name ... last_name Author name of an -.Sx \&Rs +.Ic \&Rs block. Multiple authors should each be accorded their own -.Sx \%%A +.Ic \%%A line. Author names should be ordered with full or abbreviated forename(s) first, then full surname. -.Ss \&%B +.It Ic \&%B Ar title Book title of an -.Sx \&Rs +.Ic \&Rs block. This macro may also be used in a non-bibliographic context when referring to book titles. -.Ss \&%C +.It Ic \&%C Ar location Publication city or location of an -.Sx \&Rs +.Ic \&Rs block. -.Ss \&%D +.It Ic \&%D Oo Ar month day , Oc Ar year Publication date of an -.Sx \&Rs +.Ic \&Rs block. -This should follow the reduced or canonical form syntax described in -.Sx Dates . -.Ss \&%I +Provide the full English name of the +.Ar month +and all four digits of the +.Ar year . +.It Ic \&%I Ar name Publisher or issuer name of an -.Sx \&Rs +.Ic \&Rs block. -.Ss \&%J +.It Ic \&%J Ar name Journal name of an -.Sx \&Rs +.Ic \&Rs block. -.Ss \&%N +.It Ic \&%N Ar number Issue number (usually for journals) of an -.Sx \&Rs +.Ic \&Rs block. -.Ss \&%O +.It Ic \&%O Ar line Optional information of an -.Sx \&Rs +.Ic \&Rs block. -.Ss \&%P +.It Ic \&%P Ar number Book or journal page number of an -.Sx \&Rs +.Ic \&Rs block. -.Ss \&%Q +Conventionally, the argument starts with +.Ql p.\& +for a single page or +.Ql pp.\& +for a range of pages, for example: +.Pp +.Dl .%P pp. 42\e(en47 +.It Ic \&%Q Ar name Institutional author (school, government, etc.) of an -.Sx \&Rs +.Ic \&Rs block. Multiple institutional authors should each be accorded their own -.Sx \&%Q +.Ic \&%Q line. -.Ss \&%R +.It Ic \&%R Ar name Technical report name of an -.Sx \&Rs +.Ic \&Rs block. -.Ss \&%T +.It Ic \&%T Ar title Article title of an -.Sx \&Rs +.Ic \&Rs block. This macro may also be used in a non-bibliographical context when referring to article titles. -.Ss \&%U +.It Ic \&%U Ar protocol Ns :// Ns Ar path URI of reference document. -.Ss \&%V +.It Ic \&%V Ar number Volume number of an -.Sx \&Rs +.Ic \&Rs block. -.Ss \&Ac +.It Ic \&Ac Close an -.Sx \&Ao +.Ic \&Ao block. Does not have any tail arguments. -.Ss \&Ad +.Tg Ad +.It Ic \&Ad Ar address Memory address. Do not use this for postal addresses. .Pp Examples: -.D1 \&.Ad [0,$] -.D1 \&.Ad 0x00000000 -.Ss \&An +.Dl \&.Ad [0,$] +.Dl \&.Ad 0x00000000 +.Tg An +.It Ic \&An Fl split | nosplit | Ar first_name ... last_name Author name. +Can be used both for the authors of the program, function, or driver +documented in the manual, or for the authors of the manual itself. Requires either the name of an author or one of the following arguments: .Pp .Bl -tag -width "-nosplitX" -offset indent -compact .It Fl split Start a new output line before each subsequent invocation of -.Sx \&An . +.Ic \&An . .It Fl nosplit The opposite of .Fl split . @@ -969,61 +672,101 @@ for the first author listing and for all other author listings. .Pp Examples: -.D1 \&.An -nosplit -.D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv -.Ss \&Ao +.Dl \&.An -nosplit +.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv +.It Ic \&Ao Ar block Begin a block enclosed by angle brackets. Does not have any head arguments. -.Pp -Examples: -.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac -.Pp -See also -.Sx \&Aq . -.Ss \&Ap +This macro is almost never useful. +See +.Ic \&Aq +for more details. +.Tg Ap +.It Ic \&Ap Inserts an apostrophe without any surrounding whitespace. This is generally used as a grammatical device when referring to the verb form of a function. .Pp Examples: -.D1 \&.Fn execve \&Ap d -.Ss \&Aq -Encloses its arguments in angle brackets. +.Dl \&.Fn execve \&Ap d +.Tg Aq +.It Ic \&Aq Ar line +Enclose the rest of the input line in angle brackets. +The only important use case is for email addresses. +See +.Ic \&Mt +for an example. .Pp -Examples: -.D1 \&.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 -.Sx \&Lk +For URIs, use +.Ic \&Lk +instead, and +.Ic \&In +for +.Dq #include +directives. +Never wrap +.Ic \&Ar +in +.Ic \&Aq . +.Pp +Since +.Ic \&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 +.Ic \&Pf , +.Ic \&Ns , or -.Sx \&Mt , -or to note pre-processor -.Dq Li #include -statements, which should use -.Sx \&In . +.Ic \&Eo +as needed. .Pp See also -.Sx \&Ao . -.Ss \&Ar +.Ic \&Ao . +.Tg Ar +.It Ic \&Ar Op Ar placeholder ... Command arguments. If an argument is not provided, the string .Dq file ...\& is used as a default. .Pp Examples: -.D1 \&.Fl o \&Ns \&Ar file1 -.D1 \&.Ar -.D1 \&.Ar arg1 , arg2 . -.Ss \&At -Formats an AT&T version. +.Dl ".Fl o Ar file" +.Dl ".Ar" +.Dl ".Ar arg1 , arg2 ." +.Pp +The arguments to the +.Ic \&Ar +macro are names and placeholders for command arguments; +for fixed strings to be passed verbatim as arguments, use +.Ic \&Fl +or +.Ic \&Cm . +.Tg At +.It Ic \&At Op Ar version +Formats an +.At +version. Accepts one optional argument: .Pp .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact .It Cm v[1-7] | 32v A version of .At . -.It Cm V[.[1-4]]? +.It Cm III +.At III . +.It Cm V | V.[1-4] A version of .At V . .El @@ -1031,36 +774,29 @@ A version of Note that these arguments do not begin with a hyphen. .Pp Examples: -.D1 \&.At -.D1 \&.At V.1 +.Dl \&.At +.Dl \&.At III +.Dl \&.At V.1 .Pp See also -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , -.Sx \&Ox , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , and -.Sx \&Ux . -.Ss \&Bc +.Ic \&Ox . +.It Ic \&Bc Close a -.Sx \&Bo +.Ic \&Bo block. Does not have any tail arguments. -.Ss \&Bd +.Tg Bd +.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact Begin a display block. -Its syntax is as follows: -.Bd -ragged -offset indent -.Pf \. Sx \&Bd -.Fl Ns Ar type -.Op Fl offset Ar width -.Op Fl compact -.Ed -.Pp Display blocks are used to select a different indentation and justification than the one used by the surrounding text. -They may contain both macro lines and free-form text lines. +They may contain both macro lines and text lines. By default, a display block is preceded by a vertical space. .Pp The @@ -1068,21 +804,27 @@ The must be one of the following: .Bl -tag -width 13n -offset indent .It Fl centered -Centre-justify each line. +Produce one output line from each input line, and center-justify each line. Using this display type is not recommended; many .Nm implementations render it poorly. .It Fl filled -Left- and right-justify the block. +Change the positions of line breaks to fill each line, and left- and +right-justify the resulting block. .It Fl literal -Do not justify the block at all. -Preserve white space and newlines as they appear in the input, including -if it follows a macro. +Produce one output line from each input line, +and do not justify the block at all. +Preserve white space as it appears in the input. +Always use a constant-width font. +Use this for displaying source code. .It Fl ragged -Only left-justify the block. +Change the positions of line breaks to fill each line, and left-justify +the resulting block. .It Fl unfilled -An alias for -.Fl literal . +The same as +.Fl literal , +but using the same font as for normal text, which is a variable width font +if supported by the output device. .El .Pp The @@ -1098,7 +840,7 @@ which may be one of the following: .It One of the pre-defined strings .Cm indent , -the width of standard indentation; +the width of a standard indentation (six constant width characters); .Cm indent-two , twice .Cm indent ; @@ -1107,7 +849,7 @@ which has no effect; .Cm right , which justifies to the right margin; or .Cm center , -which aligns around an imagined centre axis. +which aligns around an imagined center axis. .It A macro invocation, which selects a predefined width associated with that macro. @@ -1116,8 +858,8 @@ The most popular is the imaginary macro which resolves to .Sy 6n . .It -A width using the syntax described in -.Sx Scaling Widths . +A scaling width as described in +.Xr roff 7 . .It An arbitrary string, which indents by the length of this string. .El @@ -1137,20 +879,12 @@ Examples: .Ed .Pp See also -.Sx \&D1 +.Ic \&D1 and -.Sx \&Dl . -.Ss \&Bf +.Ic \&Dl . +.Tg Bf +.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy Change the font mode for a scoped block of text. -Its syntax is as follows: -.Bd -ragged -offset indent -.Pf \. Sx \&Bf -.Oo -.Fl emphasis | literal | symbolic | -.Cm \&Em | \&Li | \&Sy -.Oc -.Ed -.Pp The .Fl emphasis and @@ -1166,29 +900,28 @@ and Without an argument, this macro does nothing. The font mode continues until broken by a new font mode in a nested scope or -.Sx \&Ef +.Ic \&Ef is encountered. .Pp See also -.Sx \&Li , -.Sx \&Ef , -.Sx \&Em , +.Ic \&Li , +.Ic \&Ef , +.Ic \&Em , and -.Sx \&Sy . -.Ss \&Bk -Keep the output generated from each macro input line together -on one single output line. -Line breaks in free-form text lines are unaffected. -The syntax is as follows: +.Ic \&Sy . +.Tg Bk +.It Ic \&Bk Fl words +For each macro, keep its output together on the same output line, +until the end of the macro or the end of the input line is reached, +whichever comes first. +Line breaks in text lines are unaffected. .Pp -.D1 Pf \. Sx \&Bk Fl words -.Pp The .Fl words argument is required; additional arguments are ignored. .Pp The following example will not break within each -.Sx \&Op +.Ic \&Op macro line: .Bd -literal -offset indent \&.Bk \-words @@ -1199,20 +932,19 @@ macro line: .Pp Be careful in using over-long lines within a keep block! Doing so will clobber the right margin. -.Ss \&Bl -Begin a list. -Lists consist of items started by the -.Sx \&It -macro, containing a head or a body or both. -The list syntax is as follows: -.Bd -ragged -offset indent -.Pf \. Sx \&Bl +.Tg Bl +.It Xo +.Ic \&Bl .Fl Ns Ar type .Op Fl width Ar val .Op Fl offset Ar val .Op Fl compact -.Op HEAD ... -.Ed +.Op Ar col ... +.Xc +Begin a list. +Lists consist of items specified using the +.Ic \&It +macro, containing a head or a body or both. .Pp The list .Ar type @@ -1221,8 +953,11 @@ The .Fl width and .Fl offset -arguments accept -.Sx Scaling Widths +arguments accept macro names as described for +.Ic \&Bd +.Fl offset , +scaling widths as described in +.Xr roff 7 , or use the length of the given string. The .Fl offset @@ -1250,21 +985,19 @@ argument. A columnated list. The .Fl width -argument has no effect; instead, each argument specifies the width -of one column, using either the -.Sx Scaling Widths -syntax or the string length of the argument. +argument has no effect; instead, the string length of each argument +specifies the width of one column. If the first line of the body of a .Fl column list is not an -.Sx \&It +.Ic \&It macro line, -.Sx \&It +.Ic \&It contexts spanning one input line each are implied until an -.Sx \&It +.Ic \&It macro line is encountered, at which point items start being interpreted as described in the -.Sx \&It +.Ic \&It documentation. .It Fl dash Like @@ -1274,12 +1007,15 @@ except that dashes are used in place of bullets. Like .Fl inset , except that item heads are not parsed for macro invocations. -.\" but with additional formatting to the head. +Most often used in the +.Em DIAGNOSTICS +section with error constants in the item heads. .It Fl enum 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 @@ -1316,11 +1052,18 @@ this head on the same output line. Otherwise, the body starts on the output line following the head. .El .Pp +Lists may be nested within lists and displays. +Nesting of +.Fl column +and +.Fl enum +lists may not be portable. +.Pp See also -.Sx \&El +.Ic \&El and -.Sx \&It . -.Ss \&Bo +.Ic \&It . +.It Ic \&Bo Ar block Begin a block enclosed by square brackets. Does not have any head arguments. .Pp @@ -1331,29 +1074,30 @@ Examples: .Ed .Pp See also -.Sx \&Bq . -.Ss \&Bq +.Ic \&Bq . +.Tg Bq +.It Ic \&Bq Ar line Encloses its arguments in square brackets. .Pp Examples: -.D1 \&.Bq 1 , \&Dv BUFSIZ +.Dl \&.Bq 1 , \&Dv BUFSIZ .Pp .Em Remarks : this macro is sometimes abused to emulate optional arguments for commands; the correct macros to use for this purpose are -.Sx \&Op , -.Sx \&Oo , +.Ic \&Op , +.Ic \&Oo , and -.Sx \&Oc . +.Ic \&Oc . .Pp See also -.Sx \&Bo . -.Ss \&Brc +.Ic \&Bo . +.It Ic \&Brc Close a -.Sx \&Bro +.Ic \&Bro block. Does not have any tail arguments. -.Ss \&Bro +.It Ic \&Bro Ar block Begin a block enclosed by curly braces. Does not have any head arguments. .Pp @@ -1364,144 +1108,182 @@ Examples: .Ed .Pp See also -.Sx \&Brq . -.Ss \&Brq +.Ic \&Brq . +.Tg Brq +.It Ic \&Brq Ar line Encloses its arguments in curly braces. .Pp Examples: -.D1 \&.Brq 1 , ... , \&Va n +.Dl \&.Brq 1 , ... , \&Va n .Pp See also -.Sx \&Bro . -.Ss \&Bsx -Format the BSD/OS version provided as an argument, or a default value if +.Ic \&Bro . +.Tg Bsx +.It Ic \&Bsx Op Ar version +Format the +.Bsx +version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Bsx 1.0 -.D1 \&.Bsx +.Dl \&.Bsx 1.0 +.Dl \&.Bsx .Pp See also -.Sx \&At , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , -.Sx \&Ox , +.Ic \&At , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , and -.Sx \&Ux . -.Ss \&Bt +.Ic \&Ox . +.It Ic \&Bt +Supported only for compatibility, do not use this in new manuals. Prints -.Dq is currently in beta test . -.Ss \&Bx -Format the BSD version provided as an argument, or a default value if no +.Dq is currently in beta test. +.Tg Bx +.It Ic \&Bx Op Ar version Op Ar variant +Format the +.Bx +version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Bx 4.4 -.D1 \&.Bx +.Dl \&.Bx 4.3 Tahoe +.Dl \&.Bx 4.4 +.Dl \&.Bx .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , -.Sx \&Ox , +.Ic \&At , +.Ic \&Bsx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , and -.Sx \&Ux . -.Ss \&Cd +.Ic \&Ox . +.Tg Cd +.It Ic \&Cd Ar line Kernel configuration declaration. This denotes strings accepted by .Xr config 8 . +It is most often used in section 4 manual pages. .Pp Examples: -.D1 \&.Cd device le0 at scode? +.Dl \&.Cd device le0 at scode? .Pp .Em Remarks : this macro is commonly abused by using quoted literals to retain whitespace and align consecutive -.Sx \&Cd +.Ic \&Cd declarations. This practise is discouraged. -.Ss \&Cm +.Tg Cm +.It Ic \&Cm Ar keyword ... Command modifiers. -Useful when specifying configuration options or keys. +Typically used for fixed strings passed as arguments to interactive +commands, to commands in interpreted scripts, or to configuration +file directives, unless +.Ic \&Fl +is more appropriate. .Pp Examples: -.D1 \&.Cm ControlPath -.D1 \&.Cm ControlMaster -.Pp -See also -.Sx \&Fl . -.Ss \&D1 +.Dl ".Nm mt Fl f Ar device Cm rewind" +.Dl ".Nm ps Fl o Cm pid , Ns Cm command" +.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" +.Dl ".Ic set Fl o Cm vi" +.Dl ".Ic lookup Cm file bind" +.Dl ".Ic permit Ar identity Op Cm as Ar target" +.Tg D1 +.It Ic \&D1 Ar line One-line indented display. This is formatted by the default rules and is useful for simple indented statements. It is followed by a newline. .Pp Examples: -.D1 \&.D1 \&Fl abcdefgh +.Dl \&.D1 \&Fl abcdefgh .Pp See also -.Sx \&Bd +.Ic \&Bd and -.Sx \&Dl . -.Ss \&Db -Switch debugging mode. -Its syntax is as follows: -.Pp -.D1 Pf \. Sx \&Db Cm on | off -.Pp -This macro is ignored by -.Xr mandoc 1 . -.Ss \&Dc +.Ic \&Dl . +.It Ic \&Db +This macro is obsolete. +No replacement is needed. +It is ignored by +.Xr mandoc 1 +and groff including its arguments. +It was formerly used to toggle a debugging mode. +.It Ic \&Dc Close a -.Sx \&Do +.Ic \&Do block. Does not have any tail arguments. -.Ss \&Dd -Document date. +.Tg Dd +.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year +Document date for display in the page footer, +by convention the date of the last change. This is the mandatory first macro of any .Nm manual. -Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Dd Op Ar date -.Pp The -.Ar date -may be either -.Ar $\&Mdocdate$ , -which signifies the current manual revision date dictated by +.Ar month +is the full English month name, the +.Ar day +is an integer number, and the +.Ar year +is the full four-digit year. +.Pp +Other arguments are not portable; the +.Xr mandoc 1 +utility handles them as follows: +.Bl -dash -offset 3n -compact +.It +To have the date automatically filled in by the +.Ox +version of .Xr cvs 1 , -or instead a valid canonical date as specified by -.Sx Dates . -If a date does not conform or is empty, the current date is used. +the special string +.Dq $\&Mdocdate$ +can be given as an argument. +.It +The traditional, purely numeric +.Xr man 7 +format +.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day +is accepted, too. +.It +If a date string cannot be parsed, it is used verbatim. +.It +If no date string is given, the current date is used. +.El .Pp Examples: -.D1 \&.Dd $\&Mdocdate$ -.D1 \&.Dd $\&Mdocdate: July 21 2007$ -.D1 \&.Dd July 21, 2007 +.Dl \&.Dd $\&Mdocdate$ +.Dl \&.Dd $\&Mdocdate: July 2 2018$ +.Dl \&.Dd July 2, 2018 .Pp See also -.Sx \&Dt +.Ic \&Dt and -.Sx \&Os . -.Ss \&Dl -One-line intended display. +.Ic \&Os . +.Tg Dl +.It Ic \&Dl Ar line +One-line indented display. This is formatted as literal text and is useful for commands and invocations. It is followed by a newline. .Pp Examples: -.D1 \&.Dl % mandoc mdoc.7 \e(ba less +.Dl \&.Dl % mandoc mdoc.7 \e(ba less .Pp See also -.Sx \&Bd +.Ic \&Ql , +.Ic \&Bd Fl literal , and -.Sx \&D1 . -.Ss \&Do +.Ic \&D1 . +.It Ic \&Do Ar block Begin a block enclosed by double quotes. Does not have any head arguments. .Pp @@ -1514,8 +1296,9 @@ April is the cruellest month .Ed .Pp See also -.Sx \&Dq . -.Ss \&Dq +.Ic \&Dq . +.Tg Dq +.It Ic \&Dq Ar line Encloses its arguments in .Dq typographic double-quotes. @@ -1527,396 +1310,391 @@ Examples: .Ed .Pp See also -.Sx \&Qq , -.Sx \&Sq , +.Ic \&Qq , +.Ic \&Sq , and -.Sx \&Do . -.Ss \&Dt -Document title. +.Ic \&Do . +.Tg Dt +.It Ic \&Dt Ar TITLE section Op Ar arch +Document title for display in the page header. This is the mandatory second macro of any .Nm file. -Its syntax is as follows: -.Bd -ragged -offset indent -.Pf \. Sx \&Dt -.Oo -.Ar title -.Oo -.Ar section -.Op Ar volume | arch -.Oc -.Oc -.Ed .Pp Its arguments are as follows: -.Bl -tag -width Ds -offset Ds -.It Ar title +.Bl -tag -width section -offset 2n +.It Ar TITLE The document's title (name), defaulting to -.Dq UNKNOWN +.Dq UNTITLED if unspecified. -It should be capitalised. +To achieve a uniform appearance of page header lines, +it should by convention be all caps. .It Ar section The manual section. This may be one of -.Ar 1 -.Pq utilities , -.Ar 2 -.Pq system calls , -.Ar 3 -.Pq libraries , -.Ar 3p -.Pq Perl libraries , -.Ar 4 -.Pq devices , -.Ar 5 -.Pq file formats , -.Ar 6 -.Pq games , -.Ar 7 -.Pq miscellaneous , -.Ar 8 -.Pq system utilities , -.Ar 9 -.Pq kernel functions , -.Ar X11 -.Pq X Window System , -.Ar X11R6 -.Pq X Window System , -.Ar unass -.Pq unassociated , -.Ar local -.Pq local system , -.Ar draft -.Pq draft manual , +.Cm 1 +.Pq General Commands , +.Cm 2 +.Pq System Calls , +.Cm 3 +.Pq Library Functions , +.Cm 3p +.Pq Perl Library , +.Cm 4 +.Pq Device Drivers , +.Cm 5 +.Pq File Formats , +.Cm 6 +.Pq Games , +.Cm 7 +.Pq Miscellaneous Information , +.Cm 8 +.Pq System Manager's Manual , or -.Ar paper -.Pq paper . +.Cm 9 +.Pq Kernel Developer's Manual . It should correspond to the manual's filename suffix and defaults to -.Dq 1 -if unspecified. -.It Ar volume -This overrides the volume inferred from -.Ar section . -This field is optional, and if specified, must be one of -.Ar USD -.Pq users' supplementary documents , -.Ar PS1 -.Pq programmers' supplementary documents , -.Ar AMD -.Pq administrators' supplementary documents , -.Ar SMM -.Pq system managers' manuals , -.Ar URM -.Pq users' reference manuals , -.Ar PRM -.Pq programmers' reference manuals , -.Ar KM -.Pq kernel manuals , -.Ar IND -.Pq master index , -.Ar MMI -.Pq master index , -.Ar LOCAL -.Pq local manuals , -.Ar LOC -.Pq local manuals , -or -.Ar CON -.Pq contributed manuals . +the empty string if unspecified. .It Ar arch -This specifies a specific relevant architecture. -If -.Ar volume -is not provided, it may be used in its place, else it may be used -subsequent that. -It, too, is optional. -It must be one of -.Ar alpha , -.Ar amd64 , -.Ar amiga , -.Ar arc , -.Ar arm , -.Ar armish , -.Ar aviion , -.Ar hp300 , -.Ar hppa , -.Ar hppa64 , -.Ar i386 , -.Ar landisk , -.Ar loongson , -.Ar luna88k , -.Ar mac68k , -.Ar macppc , -.Ar mips64 , -.Ar mvme68k , -.Ar mvme88k , -.Ar mvmeppc , -.Ar pmax , -.Ar sgi , -.Ar socppc , -.Ar sparc , -.Ar sparc64 , -.Ar sun3 , -.Ar vax , +This specifies the machine architecture a manual page applies to, +where relevant, for example +.Cm alpha , +.Cm amd64 , +.Cm i386 , or -.Ar zaurus . +.Cm sparc64 . +The list of valid architectures varies by operating system. .El .Pp Examples: -.D1 \&.Dt FOO 1 -.D1 \&.Dt FOO 4 KM -.D1 \&.Dt FOO 9 i386 +.Dl \&.Dt FOO 1 +.Dl \&.Dt FOO 9 i386 .Pp See also -.Sx \&Dd +.Ic \&Dd and -.Sx \&Os . -.Ss \&Dv -Defined variables such as preprocessor constants. +.Ic \&Os . +.Tg Dv +.It Ic \&Dv Ar identifier ... +Defined variables such as preprocessor constants, constant symbols, +enumeration values, and so on. .Pp Examples: -.D1 \&.Dv BUFSIZ -.D1 \&.Dv STDOUT_FILENO +.Dl \&.Dv NULL +.Dl \&.Dv BUFSIZ +.Dl \&.Dv STDOUT_FILENO .Pp See also -.Sx \&Er . -.Ss \&Dx -Format the DragonFly BSD version provided as an argument, or a default +.Ic \&Er +and +.Ic \&Ev +for special-purpose constants, +.Ic \&Va +for variable symbols, and +.Ic \&Fd +for listing preprocessor variable definitions in the +.Em SYNOPSIS . +.Tg Dx +.It Ic \&Dx Op Ar version +Format the +.Dx +version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Dx 2.4.1 -.D1 \&.Dx +.Dl \&.Dx 2.4.1 +.Dl \&.Dx .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Fx , -.Sx \&Nx , -.Sx \&Ox , +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Fx , +.Ic \&Nx , and -.Sx \&Ux . -.Ss \&Ec +.Ic \&Ox . +.It Ic \&Ec Op Ar closing_delimiter Close a scope started by -.Sx \&Eo . -Its syntax is as follows: +.Ic \&Eo . .Pp -.D1 Pf \. Sx \&Ec Op Ar TERM -.Pp The -.Ar TERM +.Ar closing_delimiter argument is used as the enclosure tail, for example, specifying \e(rq will emulate -.Sx \&Dc . -.Ss \&Ed +.Ic \&Dc . +.It Ic \&Ed End a display context started by -.Sx \&Bd . -.Ss \&Ef +.Ic \&Bd . +.It Ic \&Ef End a font mode context started by -.Sx \&Bf . -.Ss \&Ek +.Ic \&Bf . +.It Ic \&Ek End a keep context started by -.Sx \&Bk . -.Ss \&El +.Ic \&Bk . +.It Ic \&El End a list context started by -.Sx \&Bl . -.Pp +.Ic \&Bl . See also -.Sx \&Bl +.Ic \&It . +.Tg Em +.It Ic \&Em Ar word ... +Request an italic font. +If the output device does not provide that, underline. +.Pp +This is most often used for stress emphasis (not to be confused with +importance, see +.Ic \&Sy ) . +In the rare cases where none of the semantic markup macros fit, +it can also be used for technical terms and placeholders, except +that for syntax elements, +.Ic \&Sy and -.Sx \&It . -.Ss \&Em -Denotes text that should be emphasised. -Note that this is a presentation term and should not be used for -stylistically decorating technical terms. +.Ic \&Ar +are preferred, respectively. .Pp Examples: -.D1 \&.Em Warnings! -.D1 \&.Em Remarks : +.Bd -literal -compact -offset indent +Selected lines are those +\&.Em not +matching any of the specified patterns. +Some of the functions use a +\&.Em hold space +to save the pattern space for subsequent retrieval. +.Ed .Pp See also -.Sx \&Bf , -.Sx \&Sy , +.Ic \&No , +.Ic \&Ql , and -.Sx \&Li . -.Ss \&En -This macro is obsolete and not implemented in -.Xr mandoc 1 . -.Ss \&Eo -An arbitrary enclosure. -Its syntax is as follows: +.Ic \&Sy . +.It Ic \&En Ar word ... +This macro is obsolete. +Use +.Ic \&Eo +or any of the other enclosure macros. .Pp -.D1 Pf \. Sx \&Eo Op Ar TERM -.Pp +It encloses its argument in the delimiters specified by the last +.Ic \&Es +macro. +.Tg Eo +.It Ic \&Eo Op Ar opening_delimiter +An arbitrary enclosure. The -.Ar TERM +.Ar opening_delimiter argument is used as the enclosure head, for example, specifying \e(lq will emulate -.Sx \&Do . -.Ss \&Er -Display error constants. +.Ic \&Do . +.Tg Er +.It Ic \&Er Ar identifier ... +Error constants for definitions of the +.Va errno +libc global variable. +This is most often used in section 2 and 3 manual pages. .Pp Examples: -.D1 \&.Er EPERM -.D1 \&.Er ENOENT +.Dl \&.Er EPERM +.Dl \&.Er ENOENT .Pp See also -.Sx \&Dv . -.Ss \&Es -This macro is obsolete and not implemented. -.Ss \&Ev +.Ic \&Dv +for general constants. +.It Ic \&Es Ar opening_delimiter closing_delimiter +This macro is obsolete. +Use +.Ic \&Eo +or any of the other enclosure macros. +.Pp +It takes two arguments, defining the delimiters to be used by subsequent +.Ic \&En +macros. +.Tg Ev +.It Ic \&Ev Ar identifier ... Environmental variables such as those specified in .Xr environ 7 . .Pp Examples: -.D1 \&.Ev DISPLAY -.D1 \&.Ev PATH -.Ss \&Ex -Insert a standard sentence regarding exit values. -Its syntax is as follows: +.Dl \&.Ev DISPLAY +.Dl \&.Ev PATH .Pp -.D1 Pf \. Sx \&Ex Fl std Op Ar utility +See also +.Ic \&Dv +for general constants. +.Tg Ex +.It Ic \&Ex Fl std Op Ar utility ... +Insert a standard sentence regarding command exit values of 0 on success +and >0 on failure. +This is most often used in section 1, 6, and 8 manual pages. .Pp -When +If .Ar utility is not specified, the document's name set by -.Sx \&Nm +.Ic \&Nm is used. +Multiple +.Ar utility +arguments are treated as separate utilities. .Pp See also -.Sx \&Rv . -.Ss \&Fa -Function argument. -Its syntax is as follows: -.Bd -ragged -offset indent -.Pf \. Sx \&Fa -.Op Cm argtype -.Cm argname -.Ed +.Ic \&Rv . +.Tg Fa +.It Ic \&Fa Ar argument ... +Function argument or parameter. +Each argument may be a name and a type (recommended for the +.Em SYNOPSIS +section), a name alone (for function invocations), +or a type alone (for function prototypes). +If both a type and a name are given or if the type consists of multiple +words, all words belonging to the same function argument have to be +given in a single argument to the +.Ic \&Fa +macro. .Pp -This may be invoked for names with or without the corresponding type. -It is also used to specify the field name of a structure. +This macro is also used to specify the field name of a structure. +.Pp Most often, the -.Sx \&Fa +.Ic \&Fa macro is used in the .Em SYNOPSIS within -.Sx \&Fo -section when documenting multi-line function prototypes. +.Ic \&Fo +blocks when documenting multi-line function prototypes. If invoked with multiple arguments, the arguments are separated by a comma. Furthermore, if the following macro is another -.Sx \&Fa , +.Ic \&Fa , the last argument will also have a trailing comma. .Pp Examples: -.D1 \&.Fa \(dqconst char *p\(dq -.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq -.D1 \&.Fa foo +.Dl \&.Fa \(dqconst char *p\(dq +.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq +.Dl \&.Fa \(dqchar *\(dq size_t .Pp See also -.Sx \&Fo . -.Ss \&Fc +.Ic \&Fo . +.It Ic \&Fc End a function context started by -.Sx \&Fo . -.Ss \&Fd -Historically used to document include files. -This usage has been deprecated in favour of -.Sx \&In . -Do not use this macro. +.Ic \&Fo . +.Tg Fd +.It Ic \&Fd Pf # Ar directive Op Ar argument ... +Preprocessor directive, in particular for listing it in the +.Em SYNOPSIS . +Historically, it was also used to document include files. +The latter usage has been deprecated in favour of +.Ic \&In . .Pp +Examples: +.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler +.Dl \&.Fd #define SIO_MAXNFDS +.Dl \&.Fd #ifdef FS_DEBUG +.Dl \&.Ft void +.Dl \&.Fn dbg_open \(dqconst char *\(dq +.Dl \&.Fd #endif +.Pp See also -.Sx MANUAL STRUCTURE +.Sx MANUAL STRUCTURE , +.Ic \&In , and -.Sx \&In . -.Ss \&Fl -Command-line flag. +.Ic \&Dv . +.Tg Fl +.It Ic \&Fl Op Ar word ... +Command-line flag or option. Used when listing arguments to command-line utilities. -Prints a fixed-width hyphen -.Sq \- -directly followed by each argument. -If no arguments are provided, a hyphen is printed followed by a space. -If the argument is a macro, a hyphen is prefixed to the subsequent macro -output. +For each argument, prints an ASCII hyphen-minus character +.Sq \- , +immediately followed by the argument. +If no arguments are provided, a hyphen-minus is printed followed by a space. +If the argument is a macro, a hyphen-minus is prefixed +to the subsequent macro output. .Pp Examples: -.D1 \&.Fl a b c -.D1 \&.Fl \&Pf a b -.D1 \&.Fl -.D1 \&.Op \&Fl o \&Ns \&Ar file +.Dl ".Nm du Op Fl H | L | P" +.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" +.Dl ".Nm route Cm add Fl inet Ar destination gateway" +.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile" +.Dl ".Nm aucat Fl o Fl" +.Dl ".Nm kill Fl Ar signal_number" .Pp +For GNU-style long options, escaping the additional hyphen-minus is not +strictly required, but may be safer with future versions of GNU troff; see +.Xr mandoc_char 7 +for details. +.Pp See also -.Sx \&Cm . -.Ss \&Fn +.Ic \&Cm . +.Tg Fn +.It Ic \&Fn Ar funcname Op Ar argument ... A function name. -Its syntax is as follows: -.Bd -ragged -offset indent -.Pf \. Ns Sx \&Fn -.Op Cm functype -.Cm funcname -.Op Oo Cm argtype Oc Cm argname -.Ed .Pp Function arguments are surrounded in parenthesis and are delimited by commas. If no arguments are specified, blank parenthesis are output. +In the +.Em SYNOPSIS +section, this macro starts a new output line, +and a blank line is automatically inserted between function definitions. .Pp Examples: -.D1 \&.Fn "int funcname" "int arg0" "int arg1" -.D1 \&.Fn funcname "int arg0" -.D1 \&.Fn funcname arg0 -.Bd -literal -offset indent -compact +.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq +.Dl \&.Fn funcname \(dqint arg0\(dq +.Dl \&.Fn funcname arg0 +.Bd -literal -offset indent \&.Ft functype \&.Fn funcname .Ed .Pp -When referring to a function documented in another manual page, -.Sx \&Xr -is usually preferable. +When referring to a function documented in another manual page, use +.Ic \&Xr +instead. See also -.Sx MANUAL STRUCTURE +.Sx MANUAL STRUCTURE , +.Ic \&Fo , and -.Sx \&Ft . -.Ss \&Fo +.Ic \&Ft . +.Tg Fo +.It Ic \&Fo Ar funcname Begin a function block. This is a multi-line version of -.Sx \&Fn . -Its syntax is as follows: +.Ic \&Fn . .Pp -.D1 Pf \. Sx \&Fo Cm funcname -.Pp Invocations usually occur in the following context: .Bd -ragged -offset indent -.Pf \. Sx \&Ft Cm functype +.Pf \. Ic \&Ft Ar functype .br -.Pf \. Sx \&Fo Cm funcname +.Pf \. Ic \&Fo Ar funcname .br -.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname +.Pf \. Ic \&Fa Qq Ar argtype Ar argname .br -\.\.\. +\&.\.\. .br -.Pf \. Sx \&Fc +.Pf \. Ic \&Fc .Ed .Pp A -.Sx \&Fo +.Ic \&Fo scope is closed by +.Ic \&Fc . .Pp See also .Sx MANUAL STRUCTURE , -.Sx \&Fa , -.Sx \&Fc , +.Ic \&Fa , +.Ic \&Fc , and -.Sx \&Ft . -.Ss \&Ft +.Ic \&Ft . +.It Ic \&Fr Ar number +This macro is obsolete. +No replacement markup is needed. +.Pp +It was used to show numerical function return values in an italic font. +.Tg Ft +.It Ic \&Ft Ar functype A function type. -Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ft Cm functype +In the +.Em SYNOPSIS +section, a new output line is started after this macro. .Pp Examples: -.D1 \&.Ft int +.Dl \&.Ft int .Bd -literal -offset indent -compact \&.Ft functype \&.Fn funcname @@ -1924,64 +1702,74 @@ Examples: .Pp See also .Sx MANUAL STRUCTURE , -.Sx \&Fn , +.Ic \&Fn , and -.Sx \&Fo . -.Ss \&Fx +.Ic \&Fo . +.Tg Fx +.It Ic \&Fx Op Ar version Format the .Fx version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Fx 7.1 -.D1 \&.Fx +.Dl \&.Fx 7.1 +.Dl \&.Fx .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Nx , -.Sx \&Ox , +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Nx , and -.Sx \&Ux . -.Ss \&Hf -This macro is obsolete and not implemented. -.Ss \&Ic -Designate an internal or interactive command. -This is similar to -.Sx \&Cm -but used for instructions rather than values. +.Ic \&Ox . +.It Ic \&Hf Ar filename +This macro is not implemented in +.Xr mandoc 1 . +It was used to include the contents of a (header) file literally. +.Tg Ic +.It Ic \&Ic Ar keyword ... +Internal or interactive command, or configuration instruction +in a configuration file. +See also +.Ic \&Cm . .Pp Examples: -.D1 \&.Ic hash -.D1 \&.Ic alias +.Dl \&.Ic :wq +.Dl \&.Ic hash +.Dl \&.Ic alias .Pp Note that using -.Sx \&Bd Fl literal +.Ic \&Ql , +.Ic \&Dl , or -.Sx \&D1 -is preferred for displaying code; the -.Sx \&Ic -macro is used when referring to specific instructions. -.Ss \&In -An -.Dq include -file. -In the +.Ic \&Bd Fl literal +is preferred for displaying code samples; the +.Ic \&Ic +macro is used when referring to an individual command name. +.Tg In +.It Ic \&In Ar filename +The name of an include file. +This macro is most often used in section 2, 3, and 9 manual pages. +.Pp +When invoked as the first macro on an input line in the .Em SYNOPSIS -section (only if invoked as the line macro), the first argument is -preceded by -.Dq #include , -the arguments is enclosed in angle brackets. +section, the argument is displayed in angle brackets +and preceded by +.Qq #include , +and a blank line is inserted in front if there is a preceding +function declaration. +In other sections, it only encloses its argument in angle brackets +and causes no line break. .Pp Examples: -.D1 \&.In sys/types +.Dl \&.In sys/types.h .Pp See also .Sx MANUAL STRUCTURE . -.Ss \&It +.Tg It +.It Ic \&It Op Ar head A list item. The syntax of this macro depends on the list type. .Pp @@ -1994,7 +1782,7 @@ and .Fl diag have the following syntax: .Pp -.D1 Pf \. Sx \&It Cm args +.D1 Pf \. Ic \&It Ar args .Pp Lists of type .Fl bullet , @@ -2005,20 +1793,20 @@ and .Fl item have the following syntax: .Pp -.D1 Pf \. Sx \&It +.D1 Pf \. Ic \&It .Pp with subsequent lines interpreted within the scope of the -.Sx \&It +.Ic \&It until either a closing -.Sx \&El +.Ic \&El or another -.Sx \&It . +.Ic \&It . .Pp The .Fl tag list has the following syntax: .Pp -.D1 Pf \. Sx \&It Op Cm args +.D1 Pf \. Ic \&It Op Cm args .Pp Subsequent lines are interpreted as with .Fl bullet @@ -2031,50 +1819,56 @@ The list is the most complicated. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&It Op Cm args +.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... +.D1 Pf \. Ic \&It Ar cell Op Ar cell ... .Pp -The -.Cm args -are phrases, a mix of macros and text corresponding to a line column, -delimited by tabs or the special -.Sq \&Ta -pseudo-macro. -Lines subsequent the -.Sx \&It -are interpreted within the scope of the last phrase. -Calling the pseudo-macro -.Sq \&Ta -will open a new phrase scope (this must occur on a macro line to be -interpreted as a macro). -Note that the tab phrase delimiter may only be used within the -.Sx \&It -line itself. -Subsequent this, only the -.Sq \&Ta -pseudo-macro may be used to delimit phrases. -Furthermore, note that quoted sections propagate over tab-delimited -phrases on an -.Sx \&It , -for example, +The arguments consist of one or more lines of text and macros +representing a complete table line. +Cells within the line are delimited by the special +.Ic \&Ta +block macro or by literal tab characters. .Pp -.D1 .It \(dqcol1 ; col2 ;\(dq \&; +Using literal tabs is strongly discouraged because they are very +hard to use correctly and +.Nm +code using them is very hard to read. +In particular, a blank character is syntactically significant +before and after the literal tab character. +If a word precedes or follows the tab without an intervening blank, +that word is never interpreted as a macro call, but always output +literally. .Pp -will preserve the semicolon whitespace except for the last. +The tab cell delimiter may only be used within the +.Ic \&It +line itself; on following lines, only the +.Ic \&Ta +macro can be used to delimit cells, and portability requires that +.Ic \&Ta +is called by other macros: some parsers do not recognize it when +it appears as the first macro on a line. .Pp +Note that quoted strings may span tab-delimited cells on an +.Ic \&It +line. +For example, +.Pp +.Dl .It \(dqcol1 ,\& col2 ,\(dq \&; +.Pp +will preserve the whitespace before both commas, +but not the whitespace before the semicolon. +.Pp See also -.Sx \&Bl . -.Ss \&Lb +.Ic \&Bl . +.Tg Lb +.It Ic \&Lb Cm lib Ns Ar name Specify a library. -The syntax is as follows: .Pp -.D1 Pf \. Sx \&Lb Cm library -.Pp The -.Cm library +.Ar name parameter may be a system library, such as -.Cm libz +.Cm z or -.Cm libpam , +.Cm pam , in which case a small library description is printed next to the linker invocation; or a custom library, in which case the library name is printed in quotes. @@ -2084,68 +1878,63 @@ section as described in .Sx MANUAL STRUCTURE . .Pp Examples: -.D1 \&.Lb libz -.D1 \&.Lb mdoc -.Ss \&Li -Denotes text that should be in a literal font mode. -Note that this is a presentation term and should not be used for -stylistically decorating technical terms. -.Pp -See also -.Sx \&Bf , -.Sx \&Sy , -and -.Sx \&Em . -.Ss \&Lk +.Dl \&.Lb libz +.Dl \&.Lb libmandoc +.Tg Li +.It Ic \&Li Ar word ... +Request a typewriter (literal) font. +Deprecated because on terminal output devices, this is usually +indistinguishable from normal text. +For literal displays, use +.Ic \&Ql Pq in-line , +.Ic \&Dl Pq single line , +or +.Ic \&Bd Fl literal Pq multi-line +instead. +.Tg Lk +.It Ic \&Lk Ar uri Op Ar display_name Format a hyperlink. -Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Lk Cm uri Op Cm name -.Pp Examples: -.D1 \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q -.D1 \&.Lk http://bsd.lv +.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq +.Dl \&.Lk https://bsd.lv .Pp See also -.Sx \&Mt . -.Ss \&Lp -Synonym for -.Sx \&Pp . -.Ss \&Ms +.Ic \&Mt . +.It Ic \&Lp +Deprecated synonym for +.Ic \&Pp . +.Tg Ms +.It Ic \&Ms Ar name Display a mathematical symbol. -Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ms Cm symbol -.Pp Examples: -.D1 \&.Ms sigma -.D1 \&.Ms aleph -.Ss \&Mt +.Dl \&.Ms sigma +.Dl \&.Ms aleph +.Tg Mt +.It Ic \&Mt Ar localpart Ns @ Ns Ar domain Format a .Dq mailto: hyperlink. -Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Mt Cm address -.Pp Examples: -.D1 \&.Mt discuss@manpages.bsd.lv -.Ss \&Nd +.Dl \&.Mt discuss@manpages.bsd.lv +.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv +.Tg Nd +.It Ic \&Nd Ar line A one line description of the manual's content. -This may only be invoked in the -.Em SYNOPSIS -section subsequent the -.Sx \&Nm -macro. +This is the mandatory last macro of the +.Em NAME +section and not appropriate for other sections. .Pp Examples: -.D1 \&.Sx \&Nd mdoc language reference -.D1 \&.Sx \&Nd format and display UNIX manuals +.Dl Pf . Ic \&Nd mdoc language reference +.Dl Pf . Ic \&Nd format and display UNIX manuals .Pp The -.Sx \&Nd +.Ic \&Nd macro technically accepts child macros and terminates with a subsequent -.Sx \&Sh +.Ic \&Sh invocation. Do not assume this behaviour: some .Xr whatis 1 @@ -2153,13 +1942,14 @@ database generators are not smart enough to parse more arguments and will display macros verbatim. .Pp See also -.Sx \&Nm . -.Ss \&Nm +.Ic \&Nm . +.Tg Nm +.It Ic \&Nm Op Ar name The name of the manual page, or \(em in particular in section 1, 6, and 8 pages \(em of an additional command or feature documented in the manual page. When first invoked, the -.Sx \&Nm +.Ic \&Nm macro expects a single argument, the name of the manual page. Usually, the first invocation happens in the .Em NAME @@ -2167,7 +1957,7 @@ section of the page. The specified name will be remembered and used whenever the macro is called again without arguments later in the page. The -.Sx \&Nm +.Ic \&Nm macro uses .Sx Block full-implicit semantics when invoked as the first macro on an input line in the @@ -2187,55 +1977,81 @@ Examples: In the .Em SYNOPSIS of section 2, 3 and 9 manual pages, use the -.Sx \&Fn +.Ic \&Fn macro rather than -.Sx \&Nm +.Ic \&Nm to mark up the name of the manual page. -.Ss \&No -A -.Dq noop -macro used to terminate prior macro contexts. +.Tg No +.It Ic \&No Ar word ... +Normal text. +Closes the scope of any preceding in-line macro. +When used after physical formatting macros like +.Ic \&Em +or +.Ic \&Sy , +switches back to the standard font face and weight. +Can also be used to embed plain text strings in macro lines +using semantic annotation macros. .Pp Examples: -.D1 \&.Sx \&Fl ab \&No cd \&Fl ef -.Ss \&Ns -Suppress a space. -Following invocation, text is interpreted as free-form text until a -macro is encountered. +.Dl ".Em italic , Sy bold , No and roman" +.Bd -literal -offset indent +\&.Sm off +\&.Cm :C No / Ar pattern No / Ar replacement No / +\&.Sm on +.Ed .Pp +See also +.Ic \&Em , +.Ic \&Ql , +and +.Ic \&Sy . +.Tg Ns +.It Ic \&Ns +Suppress a space between the output of the preceding macro +and the following text or macro. +Following invocation, input is interpreted as normal text +just like after an +.Ic \&No +macro. +.Pp +This has no effect when invoked at the start of a macro line. +.Pp Examples: -.D1 \&.Fl o \&Ns \&Ar output +.Dl ".Ar name Ns = Ns Ar value" +.Dl ".Cm :M Ns Ar pattern" +.Dl ".Fl o Ns Ar output" .Pp See also -.Sx \&No +.Ic \&No and -.Sx \&Sm . -.Ss \&Nx +.Ic \&Sm . +.Tg Nx +.It Ic \&Nx Op Ar version Format the .Nx version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Nx 5.01 -.D1 \&.Nx +.Dl \&.Nx 5.01 +.Dl \&.Nx .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Ox , +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , and -.Sx \&Ux . -.Ss \&Oc +.Ic \&Ox . +.It Ic \&Oc Close multi-line -.Sx \&Oo +.Ic \&Oo context. -.Ss \&Oo +.It Ic \&Oo Ar block Multi-line version of -.Sx \&Op . +.Ic \&Op . .Pp Examples: .Bd -literal -offset indent -compact @@ -2243,154 +2059,199 @@ Examples: \&.Op Fl flag Ns Ar value \&.Oc .Ed -.Ss \&Op -Command-line option. -Used when listing options to command-line utilities. +.Tg Op +.It Ic \&Op Ar line +Optional part of a command line. Prints the argument(s) in brackets. +This is most often used in the +.Em SYNOPSIS +section of section 1 and 8 manual pages. .Pp Examples: -.D1 \&.Op \&Fl a \&Ar b -.D1 \&.Op \&Ar a | b +.Dl \&.Op \&Fl a \&Ar b +.Dl \&.Op \&Ar a | b .Pp See also -.Sx \&Oo . -.Ss \&Os -Document operating system version. -This is the mandatory third macro of -any +.Ic \&Oo . +.Tg Os +.It Ic \&Os Op Ar footer text +The mandatory third macro of every .Nm file. -Its syntax is as follows: +Usually, do not specify any arguments, +in particular not the operating system name and/or version. .Pp -.D1 Pf \. Sx \&Os Op Cm system Op Cm version +If no argument is given, +.Xr mandoc 1 +prints its +.Fl Ios +argument in the page footer, or +.Fa sysname +and +.Fa release +as returned by +.Xr uname 3 +by default. .Pp -The optional -.Cm system -parameter specifies the relevant operating system or environment. -Left unspecified, it defaults to the local operating system version. -This is the suggested form. +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 -Examples: -.D1 \&.Os -.D1 \&.Os KTH/CSC/TCS -.D1 \&.Os BSD 4.3 -.Pp See also -.Sx \&Dd +.Ic \&Dd and -.Sx \&Dt . -.Ss \&Ot -Unknown usage. +.Ic \&Dt . +.It Ic \&Ot Ar functype +This macro is obsolete. +Use +.Ic \&Ft +instead; with +.Xr mandoc 1 , +both have the same effect. .Pp -.Em Remarks : -this macro has been deprecated. -.Ss \&Ox +Historical +.Nm +packages described it as +.Dq "old function type (FORTRAN)" . +.Tg Ox +.It Ic \&Ox Op Ar version Format the .Ox version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Ox 4.5 -.D1 \&.Ox +.Dl \&.Ox 4.5 +.Dl \&.Ox .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , and -.Sx \&Ux . -.Ss \&Pa -A file-system path. +.Ic \&Nx . +.Tg Pa +.It Ic \&Pa Ar name ... +An absolute or relative file system path, or a file or directory name. +If an argument is not provided, the character +.Sq \(ti +is used as a default. .Pp Examples: -.D1 \&.Pa /usr/bin/mandoc -.D1 \&.Pa /usr/share/man/man7/mdoc.7 +.Dl \&.Pa /usr/bin/mandoc +.Dl \&.Pa /usr/share/man/man7/mdoc.7 .Pp See also -.Sx \&Lk . -.Ss \&Pc +.Ic \&Lk . +.It Ic \&Pc Close parenthesised context opened by -.Sx \&Po . -.Ss \&Pf -Removes the space -.Pq Dq prefix -between its arguments. -Its syntax is as follows: +.Ic \&Po . +.Tg Pf +.It Ic \&Pf Ar prefix macro Op Ar argument ... +Removes the space between its argument and the following macro. +It is equivalent to: .Pp -.D1 Pf \. \&Pf Cm prefix suffix +.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... .Pp The -.Cm suffix -argument may be a macro. +.Ar prefix +argument is not parsed for macro names or delimiters, +but used verbatim as if it were escaped. .Pp Examples: -.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix -.Ss \&Po +.Dl ".Pf $ Ar variable_name" +.Dl ".Pf . Ar macro_name" +.Dl ".Pf 0x Ar hex_digits" +.Pp +See also +.Ic \&Ns +and +.Ic \&Sm . +.It Ic \&Po Ar block Multi-line version of -.Sx \&Pq . -.Ss \&Pp +.Ic \&Pq . +.Tg Pp +.It Ic \&Pp Break a paragraph. This will assert vertical space between prior and subsequent macros and/or text. -.Ss \&Pq +.Pp +Paragraph breaks are not needed before or after +.Ic \&Sh +or +.Ic \&Ss +macros or before displays +.Pq Ic \&Bd Ar line +or lists +.Pq Ic \&Bl +unless the +.Fl compact +flag is given. +.Tg Pq +.It Ic \&Pq Ar line Parenthesised enclosure. .Pp See also -.Sx \&Po . -.Ss \&Qc +.Ic \&Po . +.It Ic \&Qc Close quoted context opened by -.Sx \&Qo . -.Ss \&Ql -Format a single-quoted literal. +.Ic \&Qo . +.Tg Ql +.It Ic \&Ql Ar line +In-line literal display. +This can be used for complete command invocations and for multi-word +code examples when an indented display is not desired. +.Pp See also -.Sx \&Qq +.Ic \&Dl and -.Sx \&Sq . -.Ss \&Qo +.Ic \&Bd +.Fl literal . +.It Ic \&Qo Ar block Multi-line version of -.Sx \&Qq . -.Ss \&Qq +.Ic \&Qq . +.Tg Qq +.It Ic \&Qq Ar line Encloses its arguments in -.Dq typewriter +.Qq typewriter double-quotes. Consider using -.Sx \&Dq . +.Ic \&Dq . .Pp See also -.Sx \&Dq , -.Sx \&Sq , +.Ic \&Dq , +.Ic \&Sq , and -.Sx \&Qo . -.Ss \&Re +.Ic \&Qo . +.It Ic \&Re Close an -.Sx \&Rs +.Ic \&Rs block. Does not have any tail arguments. -.Ss \&Rs +.Tg Rs +.It Ic \&Rs Begin a bibliographic .Pq Dq reference block. Does not have any head arguments. The block macro may only contain -.Sx \&%A , -.Sx \&%B , -.Sx \&%C , -.Sx \&%D , -.Sx \&%I , -.Sx \&%J , -.Sx \&%N , -.Sx \&%O , -.Sx \&%P , -.Sx \&%Q , -.Sx \&%R , -.Sx \&%T , -.Sx \&%U , +.Ic \&%A , +.Ic \&%B , +.Ic \&%C , +.Ic \&%D , +.Ic \&%I , +.Ic \&%J , +.Ic \&%N , +.Ic \&%O , +.Ic \&%P , +.Ic \&%Q , +.Ic \&%R , +.Ic \&%T , +.Ic \&%U , and -.Sx \&%V +.Ic \&%V child macros (at least one must be specified). .Pp Examples: @@ -2400,34 +2261,39 @@ Examples: \&.%A J. D. Ullman \&.%B Introduction to Automata Theory, Languages, and Computation \&.%I Addison-Wesley -\&.%C Reading, Massachusettes +\&.%C Reading, Massachusetts \&.%D 1979 \&.Re .Ed .Pp If an -.Sx \&Rs +.Ic \&Rs block is used within a SEE ALSO section, a vertical space is asserted before the rendered output, else the block continues on the current line. -.Ss \&Rv -Inserts text regarding a function call's return value. -This macro must consist of the -.Fl std -argument followed by an optional -.Ar function . +.Tg Rv +.It Ic \&Rv Fl std Op Ar function ... +Insert a standard sentence regarding a function call's return value of 0 +on success and \-1 on error, with the +.Va errno +libc global variable set on error. +.Pp If .Ar function -is not provided, the document's name as stipulated by the first -.Sx \&Nm -is provided. +is not specified, the document's name set by +.Ic \&Nm +is used. +Multiple +.Ar function +arguments are treated as separate functions. .Pp See also -.Sx \&Ex . -.Ss \&Sc +.Ic \&Ex . +.It Ic \&Sc Close single-quoted context opened by -.Sx \&So . -.Ss \&Sh +.Ic \&So . +.Tg Sh +.It Ic \&Sh Ar TITLE LINE Begin a new section. For a list of conventional manual sections, see .Sx MANUAL STRUCTURE . @@ -2435,392 +2301,882 @@ These sections should be used unless it's absolutely n custom sections be used. .Pp Section names should be unique so that they may be keyed by -.Sx \&Sx . +.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 -.Sx \&Pp , -.Sx \&Ss , +.Ic \&Pp , +.Ic \&Ss , and -.Sx \&Sx . -.Ss \&Sm +.Ic \&Sx . +.Tg Sm +.It Ic \&Sm Op Cm on | off Switches the spacing mode for output generated from macros. -Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Sm Cm on | off -.Pp By default, spacing is .Cm on . When switched .Cm off , no white space is inserted between macro arguments and between the -output generated from adjacent macros, but free-form text lines +output generated from adjacent macros, but text lines still get normal spacing between words and sentences. -.Ss \&So +.Pp +When called without an argument, the +.Ic \&Sm +macro toggles the spacing mode. +Using this is not recommended because it makes the code harder to read. +.It Ic \&So Ar block Multi-line version of -.Sx \&Sq . -.Ss \&Sq +.Ic \&Sq . +.Tg Sq +.It Ic \&Sq Ar line Encloses its arguments in -.Dq typewriter +.Sq typewriter single-quotes. .Pp See also -.Sx \&Dq , -.Sx \&Qq , +.Ic \&Dq , +.Ic \&Qq , and -.Sx \&So . -.Ss \&Ss -Begin a new sub-section. +.Ic \&So . +.Tg Ss +.It Ic \&Ss Ar Title line +Begin a new subsection. Unlike with -.Sx \&Sh , -there's no convention for sub-sections. -Conventional sections, as described in -.Sx MANUAL STRUCTURE , -rarely have sub-sections. +.Ic \&Sh , +there is no convention for the naming of subsections. +Except +.Em DESCRIPTION , +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 -.Sx \&Sx . +.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 -.Sx \&Pp , -.Sx \&Sh , +.Ic \&Pp , +.Ic \&Sh , and -.Sx \&Sx . -.Ss \&St +.Ic \&Sx . +.Tg St +.It Ic \&St Fl Ns Ar abbreviation Replace an abbreviation for a standard with the full form. -The following standards are recognised: +The following standards are recognised. +Where multiple lines are given without a blank line in between, +they all refer to the same standard, and using the first form +is recommended. +.Bl -tag -width 1n +.It C language standards .Pp -.Bl -tag -width "-p1003.1g-2000X" -compact -.It \-p1003.1-88 -.St -p1003.1-88 -.It \-p1003.1-90 -.St -p1003.1-90 -.It \-p1003.1-96 -.St -p1003.1-96 -.It \-p1003.1-2001 -.St -p1003.1-2001 -.It \-p1003.1-2004 -.St -p1003.1-2004 -.It \-p1003.1-2008 -.St -p1003.1-2008 -.It \-p1003.1 -.St -p1003.1 -.It \-p1003.1b -.St -p1003.1b -.It \-p1003.1b-93 -.St -p1003.1b-93 -.It \-p1003.1c-95 -.St -p1003.1c-95 -.It \-p1003.1g-2000 -.St -p1003.1g-2000 -.It \-p1003.1i-95 -.St -p1003.1i-95 -.It \-p1003.2-92 -.St -p1003.2-92 -.It \-p1003.2a-92 -.St -p1003.2a-92 -.It \-p1387.2-95 -.St -p1387.2-95 -.It \-p1003.2 -.St -p1003.2 -.It \-p1387.2 -.St -p1387.2 +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-ansiC +.St -ansiC +.It \-ansiC-89 +.St -ansiC-89 .It \-isoC .St -isoC .It \-isoC-90 .St -isoC-90 +.br +The original C standard. +.Pp .It \-isoC-amd1 .St -isoC-amd1 +.Pp .It \-isoC-tcor1 .St -isoC-tcor1 +.Pp .It \-isoC-tcor2 .St -isoC-tcor2 +.Pp .It \-isoC-99 .St -isoC-99 +.br +The second major version of the C language standard. +.Pp +.It \-isoC-2011 +.St -isoC-2011 +.br +The third major version of the C language standard. +.El +.It POSIX.1 before the Single UNIX Specification +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-88 +.St -p1003.1-88 +.It \-p1003.1 +.St -p1003.1 +.br +The original POSIX standard, based on ANSI C. +.Pp +.It \-p1003.1-90 +.St -p1003.1-90 .It \-iso9945-1-90 .St -iso9945-1-90 +.br +The first update of POSIX.1. +.Pp +.It \-p1003.1b-93 +.St -p1003.1b-93 +.It \-p1003.1b +.St -p1003.1b +.br +Real-time extensions. +.Pp +.It \-p1003.1c-95 +.St -p1003.1c-95 +.br +POSIX thread interfaces. +.Pp +.It \-p1003.1i-95 +.St -p1003.1i-95 +.br +Technical Corrigendum. +.Pp +.It \-p1003.1-96 +.St -p1003.1-96 .It \-iso9945-1-96 .St -iso9945-1-96 -.It \-iso9945-2-93 -.St -iso9945-2-93 -.It \-ansiC -.St -ansiC -.It \-ansiC-89 -.St -ansiC-89 -.It \-ansiC-99 -.St -ansiC-99 -.It \-ieee754 -.St -ieee754 -.It \-iso8802-3 -.St -iso8802-3 -.It \-ieee1275-94 -.St -ieee1275-94 +.br +Includes POSIX.1-1990, 1b, 1c, and 1i. +.El +.It X/Open Portability Guide version 4 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact .It \-xpg3 .St -xpg3 +.br +An XPG4 precursor, published in 1989. +.Pp +.It \-p1003.2 +.St -p1003.2 +.It \-p1003.2-92 +.St -p1003.2-92 +.It \-iso9945-2-93 +.St -iso9945-2-93 +.br +An XCU4 precursor. +.Pp +.It \-p1003.2a-92 +.St -p1003.2a-92 +.br +Updates to POSIX.2. +.Pp .It \-xpg4 .St -xpg4 +.br +Based on POSIX.1 and POSIX.2, published in 1992. +.El +.It Single UNIX Specification version 1 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-susv1 +.St -susv1 .It \-xpg4.2 .St -xpg4.2 -.St -xpg4.3 +.br +This standard was published in 1994. +It was used as the basis for UNIX 95 certification. +The following two refer to parts of it. +.Pp +.It \-xcurses4.2 +.St -xcurses4.2 +.Pp +.It \-p1003.1g-2000 +.St -p1003.1g-2000 +.br +Networking APIs, including sockets. +.Pp +.It \-svid4 +.St -svid4 , +.br +Published in 1995. +.El +.It Single UNIX Specification version 2 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-susv2 +.St -susv2 +This Standard was published in 1997 +and is also called X/Open Portability Guide version 5. +It was used as the basis for UNIX 98 certification. +The following refer to parts of it. +.Pp .It \-xbd5 .St -xbd5 -.It \-xcu5 -.St -xcu5 +.Pp .It \-xsh5 .St -xsh5 +.Pp +.It \-xcu5 +.St -xcu5 +.Pp .It \-xns5 .St -xns5 .It \-xns5.2 .St -xns5.2 -.It \-xns5.2d2.0 -.St -xns5.2d2.0 -.It \-xcurses4.2 -.St -xcurses4.2 -.It \-susv2 -.St -susv2 +.El +.It Single UNIX Specification version 3 +.Pp +.Bl -tag -width "-p1003.1-2001" -compact +.It \-p1003.1-2001 +.St -p1003.1-2001 .It \-susv3 .St -susv3 -.It \-svid4 -.St -svid4 +.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 used as the basis for UNIX 03 certification. +.Pp +.It \-p1003.1-2004 +.St -p1003.1-2004 +.br +The second and last Technical Corrigendum. .El -.Ss \&Sx -Reference a section or sub-section. -The referenced section or sub-section name must be identical to the +.It POSIX issues 7 and 8 +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-2008 +.St -p1003.1-2008 +.It \-susv4 +.St -susv4 +.br +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 +.It \-ieee754 +.St -ieee754 +.br +Floating-point arithmetic. +.Pp +.It \-iso8601 +.St -iso8601 +.br +Representation of dates and times, published in 1988. +.Pp +.It \-iso8802-3 +.St -iso8802-3 +.br +Ethernet local area networks. +.Pp +.It \-ieee1275-94 +.St -ieee1275-94 +.El +.El +.Tg Sx +.It Ic \&Sx Ar Title line +Reference a section or subsection in the same manual page. +The referenced section or subsection name must be identical to the enclosed argument, including whitespace. .Pp Examples: -.D1 \&.Sx MANUAL STRUCTURE -.Ss \&Sy -Format enclosed arguments in symbolic -.Pq Dq boldface . -Note that this is a presentation term and should not be used for -stylistically decorating technical terms. +.Dl \&.Sx MANUAL STRUCTURE .Pp See also -.Sx \&Bf , -.Sx \&Li , +.Ic \&Sh and -.Sx \&Em . -.Ss \&Tn -Format a tradename. +.Ic \&Ss . +.Tg Sy +.It Ic \&Sy Ar word ... +Request a boldface font. .Pp -Examples: -.D1 \&.Tn IBM -.Ss \&Ud -Prints out -.Dq currently under development . -.Ss \&Ux -Format the UNIX name. -Accepts no argument. +This is most often used to indicate importance or seriousness (not to be +confused with stress emphasis, see +.Ic \&Em ) . +When none of the semantic macros fit, it is also adequate for syntax +elements that have to be given or that appear verbatim. .Pp Examples: -.D1 \&.Ux +.Bd -literal -compact -offset indent +\&.Sy Warning : +If +\&.Sy s +appears in the owner permissions, set-user-ID mode is set. +This utility replaces the former +\&.Sy dumpdir +program. +.Ed .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , +.Ic \&Em , +.Ic \&No , and -.Sx \&Ox . -.Ss \&Va +.Ic \&Ql . +.Tg Ta +.It Ic \&Ta +Table cell separator in +.Ic \&Bl Fl column +lists; can only be used below +.Ic \&It . +.Tg Tg +.It Ic \&Tg Op Ar term +Announce that the next input line starts a definition of the +.Ar term . +This macro must appear alone on its own input line. +The argument defaults to the first argument of the first macro +on the next line. +The argument may not contain whitespace characters, not even when it is quoted. +This macro is a +.Xr mandoc 1 +extension and is typically ignored by other formatters. +.Pp +When viewing terminal output with +.Xr less 1 , +the interactive +.Ic :t +command can be used to go to the definition of the +.Ar term +as described for the +.Ev MANPAGER +variable in +.Xr man 1 ; +when producing HTML output, a fragment identifier +.Pq Ic id No attribute +is generated, to be used for deep linking to this place of the document. +.Pp +In most cases, adding a +.Ic \&Tg +macro would be redundant because +.Xr mandoc 1 +is able to automatically tag most definitions. +This macro is intended for cases where automatic tagging of a +.Ar term +is unsatisfactory, for example if a definition is not tagged +automatically (false negative) or if places are tagged that do +not define the +.Ar term +(false positives). +When there is at least one +.Ic \&Tg +macro for a +.Ar term , +no other places are automatically marked as definitions of that +.Ar term . +.It Ic \&Tn Ar word ... +Supported only for compatibility, do not use this in new manuals. +Even though the macro name +.Pq Dq tradename +suggests a semantic function, historic usage is inconsistent, mostly +using it as a presentation-level macro to request a small caps font. +.It Ic \&Ud +Supported only for compatibility, do not use this in new manuals. +Prints out +.Dq currently under development. +.It Ic \&Ux +Supported only for compatibility, do not use this in new manuals. +Prints out +.Dq Ux . +.Tg Va +.It Ic \&Va Oo Ar type Oc Ar identifier ... A variable name. .Pp Examples: -.D1 \&.Va foo -.D1 \&.Va const char *bar ; -.Ss \&Vt +.Dl \&.Va foo +.Dl \&.Va const char *bar ; +.Pp +For function arguments and parameters, use +.Ic \&Fa +instead. +For declarations of global variables in the +.Em SYNOPSIS +section, use +.Ic \&Vt . +.Tg Vt +.It Ic \&Vt Ar type Op Ar identifier A variable type. +.Pp This is also used for indicating global variables in the .Em SYNOPSIS section, in which case a variable name is also specified. Note that it accepts .Sx Block partial-implicit -syntax when invoked as the first macro in the +syntax when invoked as the first macro on an input line in the .Em SYNOPSIS section, else it accepts ordinary .Sx In-line syntax. +In the former case, this macro starts a new output line, +and a blank line is inserted in front if there is a preceding +function definition or include directive. .Pp -Note that this should not be confused with -.Sx \&Ft , -which is used for function return types. -.Pp Examples: -.D1 \&.Vt unsigned char -.D1 \&.Vt extern const char * const sys_signame[] \&; +.Dl \&.Vt unsigned char +.Dl \&.Vt extern const char * const sys_signame[] \&; .Pp +For parameters in function prototypes, use +.Ic \&Fa +instead, for function return types +.Ic \&Ft , +and for variable names outside the +.Em SYNOPSIS +section +.Ic \&Va , +even when including a type with the name. See also -.Sx MANUAL STRUCTURE -and -.Sx \&Va . -.Ss \&Xc +.Sx MANUAL STRUCTURE . +.It Ic \&Xc Close a scope opened by -.Sx \&Xo . -.Ss \&Xo -Open an extension scope. -This macro originally existed to extend the 9-argument limit of troff; -since this limit has been lifted, the macro has been deprecated. -.Ss \&Xr +.Ic \&Xo . +.It Ic \&Xo Ar block +Extend the header of an +.Ic \&It +macro or the body of a partial-implicit block macro +beyond the end of the input line. +This macro originally existed to work around the 9-argument limit +of historic +.Xr roff 7 . +.Tg Xr +.It Ic \&Xr Ar name section Link to another manual .Pq Qq cross-reference . -Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Xr Cm name section -.Pp -The -.Cm name +Cross reference the +.Ar name and -.Cm section -are the name and section of the linked manual. -If -.Cm section -is followed by non-punctuation, an -.Sx \&Ns -is inserted into the token stream. -This behaviour is for compatibility with -GNU troff. +.Ar section +number of another man page. .Pp Examples: -.D1 \&.Xr mandoc 1 -.D1 \&.Xr mandoc 1 \&; -.D1 \&.Xr mandoc 1 \&Ns s behaviour -.Ss \&br -Emits a line-break. -This macro should not be used; it is implemented for compatibility with -historical manuals. +.Dl \&.Xr mandoc 1 +.Dl \&.Xr mandoc 1 \&; +.Dl \&.Xr mandoc 1 \&Ns s behaviour +.El +.Sh MACRO SYNTAX +The syntax of a macro depends on its classification. +In this section, +.Sq \-arg +refers to macro arguments, which may be followed by zero or more +.Sq parm +parameters; +.Sq \&Yo +opens the scope of a macro; and if specified, +.Sq \&Yc +closes it out. .Pp -Consider using -.Sx \&Pp -in the event of natural paragraph breaks. -.Ss \&sp -Emits vertical space. -This macro should not be used; it is implemented for compatibility with -historical manuals. -Its syntax is as follows: +The +.Em Callable +column indicates that the macro may also be called by passing its name +as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a zero-width space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . +If a macro is not callable but its name appears as an argument +to another macro, it is interpreted as opaque text. +For example, +.Sq \&.Fl \&Sh +produces +.Sq Fl \&Sh . .Pp -.D1 Pf \. Sx \&sp Op Cm height +The +.Em Parsed +column indicates whether the macro may call other macros by receiving +their names as arguments. +If a macro is not parsed but the name of another macro appears +as an argument, it is interpreted as opaque text. .Pp The -.Cm height -argument must be formatted as described in -.Sx Scaling Widths . -If unspecified, -.Sx \&sp -asserts a single vertical space. +.Em Scope +column, if applicable, describes closure rules. +.Ss Block full-explicit +Multi-line scope closed by an explicit closing macro. +All macros contains bodies; only +.Ic \&Bf +and +.Pq optionally +.Ic \&Bl +contain a head. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed +.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef +.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek +.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El +.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd +.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf +.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk +.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl +.El +.Ss Block full-implicit +Multi-line scope closed by end-of-file or implicitly by another macro. +All macros have bodies; some +.Po +.Ic \&It Fl bullet , +.Fl hyphen , +.Fl dash , +.Fl enum , +.Fl item +.Pc +don't have heads; only one +.Po +.Ic \&It +in +.Ic \&Bl Fl column +.Pc +has multiple heads. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB +\(lBbody...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El +.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh +.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss +.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh +.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss +.El +.Pp +Note that the +.Ic \&Nm +macro is a +.Sx Block full-implicit +macro only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Block partial-explicit +Like block full-explicit, but also with single-line scope. +Each has at least a body and, in limited circumstances, a head +.Po +.Ic \&Fo , +.Ic \&Eo +.Pc +and/or tail +.Pq Ic \&Ec . +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB + +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ +\(lBbody...\(rB \&Yc \(lBtail...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao +.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac +.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo +.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc +.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro +.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc +.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do +.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc +.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo +.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec +.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo +.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc +.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo +.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc +.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po +.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc +.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo +.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc +.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs +.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re +.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So +.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc +.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo +.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc +.El +.Ss Block partial-implicit +Like block full-implicit, but with single-line scope closed by the +end of the line. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed +.It Ic \&Aq Ta Yes Ta Yes +.It Ic \&Bq Ta Yes Ta Yes +.It Ic \&Brq Ta Yes Ta Yes +.It Ic \&D1 Ta \&No Ta \&Yes +.It Ic \&Dl Ta \&No Ta Yes +.It Ic \&Dq Ta Yes Ta Yes +.It Ic \&En Ta Yes Ta Yes +.It Ic \&Op Ta Yes Ta Yes +.It Ic \&Pq Ta Yes Ta Yes +.It Ic \&Ql Ta Yes Ta Yes +.It Ic \&Qq Ta Yes Ta Yes +.It Ic \&Sq Ta Yes Ta Yes +.It Ic \&Vt Ta Yes Ta Yes +.El +.Pp +Note that the +.Ic \&Vt +macro is a +.Sx Block partial-implicit +only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Special block macro +The +.Ic \&Ta +macro can only be used below +.Ic \&It +in +.Ic \&Bl Fl column +lists. +It delimits blocks representing table cells; +these blocks have bodies, but no heads. +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It +.El +.Ss In-line +Closed by the end of the line, fixed argument lengths, +and/or subsequent macros. +In-line macros have only text children. +If a number (or inequality) of arguments is +.Pq n , +then the macro accepts an arbitrary number of arguments. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments +.It Ic \&%A Ta \&No Ta \&No Ta >0 +.It Ic \&%B Ta \&No Ta \&No Ta >0 +.It Ic \&%C Ta \&No Ta \&No Ta >0 +.It Ic \&%D Ta \&No Ta \&No Ta >0 +.It Ic \&%I Ta \&No Ta \&No Ta >0 +.It Ic \&%J Ta \&No Ta \&No Ta >0 +.It Ic \&%N Ta \&No Ta \&No Ta >0 +.It Ic \&%O Ta \&No Ta \&No Ta >0 +.It Ic \&%P Ta \&No Ta \&No Ta >0 +.It Ic \&%Q Ta \&No Ta \&No Ta >0 +.It Ic \&%R Ta \&No Ta \&No Ta >0 +.It Ic \&%T Ta \&No Ta \&No Ta >0 +.It Ic \&%U Ta \&No Ta \&No Ta >0 +.It Ic \&%V Ta \&No Ta \&No Ta >0 +.It Ic \&Ad Ta Yes Ta Yes Ta >0 +.It Ic \&An Ta Yes Ta Yes Ta >0 +.It Ic \&Ap Ta Yes Ta Yes Ta 0 +.It Ic \&Ar Ta Yes Ta Yes Ta n +.It Ic \&At Ta Yes Ta Yes Ta 1 +.It Ic \&Bsx Ta Yes Ta Yes Ta n +.It Ic \&Bt Ta \&No Ta \&No Ta 0 +.It Ic \&Bx Ta Yes Ta Yes Ta n +.It Ic \&Cd Ta Yes Ta Yes Ta >0 +.It Ic \&Cm Ta Yes Ta Yes Ta >0 +.It Ic \&Db Ta \&No Ta \&No Ta 1 +.It Ic \&Dd Ta \&No Ta \&No Ta n +.It Ic \&Dt Ta \&No Ta \&No Ta n +.It Ic \&Dv Ta Yes Ta Yes Ta >0 +.It Ic \&Dx Ta Yes Ta Yes Ta n +.It Ic \&Em Ta Yes Ta Yes Ta >0 +.It Ic \&Er Ta Yes Ta Yes Ta >0 +.It Ic \&Es Ta Yes Ta Yes Ta 2 +.It Ic \&Ev Ta Yes Ta Yes Ta >0 +.It Ic \&Ex Ta \&No Ta \&No Ta n +.It Ic \&Fa Ta Yes Ta Yes Ta >0 +.It Ic \&Fd Ta \&No Ta \&No Ta >0 +.It Ic \&Fl Ta Yes Ta Yes Ta n +.It Ic \&Fn Ta Yes Ta Yes Ta >0 +.It Ic \&Fr Ta Yes Ta Yes Ta >0 +.It Ic \&Ft Ta Yes Ta Yes Ta >0 +.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 \&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 +.It Ic \&Lp Ta \&No Ta \&No Ta 0 +.It Ic \&Ms Ta Yes Ta Yes Ta >0 +.It Ic \&Mt Ta Yes Ta Yes Ta >0 +.It Ic \&Nm Ta Yes Ta Yes Ta n +.It Ic \&No Ta Yes Ta Yes Ta >0 +.It Ic \&Ns Ta Yes Ta Yes Ta 0 +.It Ic \&Nx Ta Yes Ta Yes Ta n +.It Ic \&Os Ta \&No Ta \&No Ta n +.It Ic \&Ot Ta Yes Ta Yes Ta >0 +.It Ic \&Ox Ta Yes Ta Yes Ta n +.It Ic \&Pa Ta Yes Ta Yes Ta n +.It Ic \&Pf Ta Yes Ta Yes Ta 1 +.It Ic \&Pp Ta \&No Ta \&No Ta 0 +.It Ic \&Rv Ta \&No Ta \&No Ta n +.It Ic \&Sm Ta \&No Ta \&No Ta <2 +.It Ic \&St Ta \&No Ta Yes Ta 1 +.It Ic \&Sx Ta Yes Ta Yes Ta >0 +.It Ic \&Sy Ta Yes Ta Yes Ta >0 +.It Ic \&Tg Ta \&No Ta \&No Ta <2 +.It Ic \&Tn Ta Yes Ta Yes Ta >0 +.It Ic \&Ud Ta \&No Ta \&No Ta 0 +.It Ic \&Ux Ta Yes Ta Yes Ta n +.It Ic \&Va Ta Yes Ta Yes Ta n +.It Ic \&Vt Ta Yes Ta Yes Ta >0 +.It Ic \&Xr Ta Yes Ta Yes Ta 2 +.El +.Ss Delimiters +When a macro argument consists of one single input character +considered as a delimiter, the argument gets special handling. +This does not apply when delimiters appear in arguments containing +more than one character. +Consequently, to prevent special handling and just handle it +like any other argument, a delimiter can be escaped by prepending +a zero-width space +.Pq Sq \e& . +In text lines, delimiters never need escaping, but may be used +as normal punctuation. +.Pp +For many macros, when the leading arguments are opening delimiters, +these delimiters are put before the macro scope, +and when the trailing arguments are closing delimiters, +these delimiters are put after the macro scope. +Spacing is suppressed after opening delimiters +and before closing delimiters. +For example, +.Pp +.D1 Pf \. \&Aq "( [ word ] ) ." +.Pp +renders as: +.Pp +.D1 Aq ( [ word ] ) . +.Pp +Opening delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&( +left parenthesis +.It \&[ +left bracket +.El +.Pp +Closing delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&. +period +.It \&, +comma +.It \&: +colon +.It \&; +semicolon +.It \&) +right parenthesis +.It \&] +right bracket +.It \&? +question mark +.It \&! +exclamation mark +.El +.Pp +Note that even a period preceded by a backslash +.Pq Sq \e.\& +gets this special handling; use +.Sq \e&.\& +to prevent that. +.Pp +Many in-line macros interrupt their scope when they encounter +delimiters, and resume their scope when more arguments follow that +are not delimiters. +For example, +.Pp +.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" +.Pp +renders as: +.Pp +.D1 Fl a ( b | c \*(Ba d ) e +.Pp +This applies to both opening and closing delimiters, +and also to the middle delimiter, which does not suppress spacing: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&| +vertical bar +.El +.Pp +As a special case, the predefined string \e*(Ba is handled and rendered +in the same way as a plain +.Sq \&| +character. +Using this predefined string is not recommended in new manuals. +.Pp +Appending a zero-width space +.Pq Sq \e& +to the end of an input line is also useful to prevent the interpretation +of a trailing period, exclamation or question mark as the end of a +sentence, for example when an abbreviation happens to occur +at the end of a text or macro input line. +.Ss Font handling +In +.Nm +documents, usage of semantic markup is recommended in order to have +proper fonts automatically selected; only when no fitting semantic markup +is available, consider falling back to +.Sx Physical markup +macros. +Whenever any +.Nm +macro switches the +.Xr roff 7 +font mode, it will automatically restore the previous font when exiting +its scope. +Manually switching the font using the +.Xr roff 7 +.Ql \ef +font escape sequences is never required. .Sh COMPATIBILITY -This section documents compatibility between mandoc and other other -troff implementations, at this time limited to GNU troff +This section provides an incomplete list of compatibility issues +between mandoc and GNU troff .Pq Qq groff . -The term -.Qq historic groff -refers to groff versions before the -.Pa doc.tmac -file re-write -.Pq somewhere between 1.15 and 1.19 . .Pp -Heirloom troff, the other significant troff implementation accepting -\-mdoc, is similar to historic groff. -.Pp The following problematic behaviour is found in groff: -.ds hist (Historic groff only.) .Pp .Bl -dash -compact .It -.Sx \&At -with unknown arguments produces no output at all. -\*[hist] -Newer groff and mandoc print -.Qq AT&T UNIX -and the arguments. -.It -.Sx \&Bd Fl column -does not recognize trailing punctuation characters when they immediately -precede tabulator characters, but treats them as normal text and -outputs a space before them. -.It -.Sx \&Bd Fl ragged compact -does not start a new line. -\*[hist] -.It -.Sx \&Dd -without an argument prints -.Dq Epoch . -In mandoc, it resolves to the current date. -.It -.Sx \&Fl -does not print a dash for an empty argument. -\*[hist] -.It -.Sx \&Fn -does not start a new line unless invoked as the line macro in the -.Em SYNOPSIS -section. -\*[hist] -.It -.Sx \&Fo -with -.Pf non- Sx \&Fa -children causes inconsistent spacing between arguments. -In mandoc, a single space is always inserted between arguments. -.It -.Sx \&Ft -in the -.Em SYNOPSIS -causes inconsistent vertical spacing, depending on whether a prior -.Sx \&Fn -has been invoked. -See -.Sx \&Ft -and -.Sx \&Fn -for the normalised behaviour in mandoc. -.It -.Sx \&In -ignores additional arguments and is not treated specially in the -.Em SYNOPSIS . -\*[hist] -.It -.Sx \&It -sometimes requires a -.Fl nested -flag. -\*[hist] -In new groff and mandoc, any list may be nested by default and -.Fl enum -lists will restart the sequence only for the sub-list. -.It -.Sx \&Li -followed by a reserved character is incorrectly used in some manuals -instead of properly quoting that character, which sometimes works with -historic groff. -.It -.Sx \&Lk -only accepts a single link-name argument; the remainder is misformatted. -.It -.Sx \&Pa +.Ic \&Pa does not format its arguments when used in the FILES section under certain list types. .It -.Sx \&Ta +.Ic \&Ta can only be called by other macros, but not at the beginning of a line. .It -.Sx \&%C -is not implemented. -.It -Historic groff has many un-callable macros. -Most of these (excluding some block-level macros) are callable -in new groff and mandoc. -.It -.Sq \(ba -(vertical bar) is not fully supported as a delimiter. -\*[hist] -.It .Sq \ef .Pq font face and -.Sq \ef +.Sq \eF .Pq font family face .Sx Text Decoration escapes behave irregularly when specified within line-macro scopes. @@ -2833,50 +3189,49 @@ The following features are unimplemented in mandoc: .Pp .Bl -dash -compact .It -.Sx \&Bd -.Fl file Ar file . +.Ic \&Bd Fl file Ar file +is unsupported for security reasons. .It -.Sx \&Bd -.Fl offset Ar center +.Ic \&Bd +.Fl filled +does not adjust the right margin, but is an alias for +.Ic \&Bd +.Fl ragged . +.It +.Ic \&Bd +.Fl literal +does not use a literal font, but is an alias for +.Ic \&Bd +.Fl unfilled . +.It +.Ic \&Bd +.Fl offset Cm center and -.Fl offset Ar right . +.Fl offset Cm right +don't work. Groff does not implement centered and flush-right rendering either, but produces large indentations. -.It -The -.Sq \eh -.Pq horizontal position , -.Sq \ev -.Pq vertical position , -.Sq \em -.Pq text colour , -.Sq \eM -.Pq text filling colour , -.Sq \ez -.Pq zero-length character , -.Sq \ew -.Pq string length , -.Sq \ek -.Pq horizontal position marker , -.Sq \eo -.Pq text overstrike , -and -.Sq \es -.Pq text size -escape sequences are all discarded in mandoc. -.It -The -.Sq \ef -scaling unit is accepted by mandoc, but rendered as the default unit. -.It -In quoted literals, groff allows pairwise double-quotes to produce a -standalone double-quote in formatted output. -This is not supported by mandoc. .El .Sh SEE ALSO .Xr man 1 , .Xr mandoc 1 , -.Xr mandoc_char 7 +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr roff 7 , +.Xr tbl 7 +.Pp +The web page +.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" +provides a few tutorial-style pages for beginners, an extensive style +guide for advanced authors, and an alphabetic index helping to choose +the best macros for various kinds of content. +.Pp +The manual page +.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)" +contained in the +.Dq groff +package documents exactly the same language in a somewhat different style. .Sh HISTORY The .Nm @@ -2892,4 +3247,4 @@ utility written by Kristaps Dzonsons appeared in The .Nm reference was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .