From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from kerhand.co.uk (_smtpd@82-69-137-214.dsl.in-addr.zen.co.uk [82.69.137.214]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o72J0WXq019676 for ; Mon, 2 Aug 2010 15:00:33 -0400 (EDT) Received: from localhost (1000@localhost [IPv6:::1]) by kerhand.co.uk (OpenSMTPD) with ESMTP id usz0Ln6i for ; Mon, 2 Aug 2010 20:00:05 +0100 (BST) Date: Mon, 2 Aug 2010 20:00:05 +0100 From: Jason McIntyre To: discuss@mdocml.bsd.lv Subject: mdoc.7 tweaks Message-ID: <20100802190029.GA20950@bramka.kerhand.co.uk> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.4.2.3i hi. this page makes my head hurt ;( i cannot do a diff for too many things here, so this diff: *) corrects a few obvious mistakes *) adopts some of the changes i proposed for man(7) *) uses Sy for macros instead of Sx. we could use something else but not, please, Sx. *) uses Sx for section names. *) tries to cut down just a little on the awful tendency to stick a hyphen between two words. one issue: formatting the page with groff: mdoc.7:773: warning: can't find special character `lb' mdoc.7:773: warning: can't find special character `rb' and the offending text: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb anyway, this is a start. jmc Index: mdoc.7 =================================================================== RCS file: /cvs/src/share/man/man7/mdoc.7,v retrieving revision 1.45 diff -u -r1.45 mdoc.7 --- mdoc.7 1 Aug 2010 20:47:52 -0000 1.45 +++ mdoc.7 2 Aug 2010 18:57:33 -0000 @@ -28,10 +28,12 @@ .Bx .Ux manuals. -In this reference document, we describe its syntax, structure, and +This reference document describes its syntax, structure, and usage. -Our reference implementation is mandoc; the -.Sx COMPATIBILITY +The reference implementation is +.Xr mandoc 1 ; +the +.Sy COMPATIBILITY section describes compatibility with other troff \-mdoc implementations. .Pp An @@ -61,7 +63,7 @@ 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 optionally whitespace are +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: @@ -107,7 +109,7 @@ .Sq \&[ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; -or a single one-character sequence. +or a single one character sequence. See .Xr mandoc_char 7 for a complete list. @@ -120,7 +122,7 @@ .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 +escape followed by an indicator: B (bold), I (italic), R (Roman), or P (revert to previous mode): .Pp .D1 \efBbold\efR \efIitalic\efP @@ -130,8 +132,8 @@ 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 , +.Sy \&Bf +.Sy \&Sy , in-scope invocations of .Sq \ef are only valid within the font scope of the macro. @@ -172,7 +174,7 @@ .Pq vertical bar . .Ss Whitespace Whitespace consists of the space character. -In free-form lines, whitespace is preserved within a line; un-escaped +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. @@ -183,7 +185,7 @@ 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 pair-wise adjacent to another double-quote +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 @@ -276,7 +278,7 @@ See .Sx COMPATIBILITY . .Ss Sentence Spacing -When composing a manual, make sure that your sentences end at the end of +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, @@ -288,7 +290,8 @@ .Sq \&" ) . .Pp The proper spacing is also intelligently preserved if a sentence ends at -the boundary of a macro line, e.g., +the boundary of a macro line. +For example: .Pp .D1 \&Xr mandoc 1 \. .D1 \&Fl T \&Ns \&Cm ascii \. @@ -299,23 +302,25 @@ sections. .Pp The prologue, which consists of the -.Sx \&Dd , -.Sx \&Dt , +.Sy \&Dd , +.Sy \&Dt , and -.Sx \&Os +.Sy \&Os macros in that order, is required for every document. .Pp The first section (sections are denoted by -.Sx \&Sh ) -must be the NAME section, consisting of at least one -.Sx \&Nm +.Sy \&Sh ) +must be the +.Sx NAME +section, consisting of at least one +.Sy \&Nm followed by -.Sx \&Nd . +.Sy \&Nd . .Pp Following that, convention dictates specifying at least the -.Em SYNOPSIS +.Sx SYNOPSIS and -.Em DESCRIPTION +.Sx DESCRIPTION sections, although this varies between manual sections. .Pp The following is a well-formed skeleton @@ -361,32 +366,32 @@ \&.\e\*q .Sh SECURITY CONSIDERATIONS .Ed .Pp -The sections in a +The sections in an .Nm document are conventionally ordered as they appear above. Sections should be composed as follows: .Bl -ohang -offset Ds -.It Em NAME -The name(s) and a one-line description of the documented material. +.It Sx NAME +The name(s) and a one line description of the documented material. The syntax for this as follows: .Bd -literal -offset indent -\&.Nm name0 -\&.Nm name1 +\&.Nm name0 , +\&.Nm name1 , \&.Nm name2 -\&.Nd a one-line description +\&.Nd a one line description .Ed .Pp The -.Sx \&Nm +.Sy \&Nm macro(s) must precede the -.Sx \&Nd +.Sy \&Nd macro. .Pp See -.Sx \&Nm +.Sy \&Nm and -.Sx \&Nd . -.It Em LIBRARY +.Sy \&Nd . +.It Sx 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. The syntax for this is as follows: @@ -395,8 +400,8 @@ .Ed .Pp See -.Sx \&Lb . -.It Em SYNOPSIS +.Sy \&Lb . +.It Sx SYNOPSIS Documents the utility invocation syntax, function call syntax, or device configuration. .Pp @@ -430,50 +435,50 @@ .Ed .Pp Manuals not in these sections generally don't need a -.Em SYNOPSIS . +.Sx SYNOPSIS . .Pp Some macros are displayed differently in the -.Em SYNOPSIS +.Sx SYNOPSIS section, particularly -.Sx \&Nm , -.Sx \&Cd , -.Sx \&Fd , -.Sx \&Fn , -.Sx \&Fo , -.Sx \&In , -.Sx \&Vt , +.Sy \&Nm , +.Sy \&Cd , +.Sy \&Fd , +.Sy \&Fn , +.Sy \&Fo , +.Sy \&In , +.Sy \&Vt , and -.Sx \&Ft . +.Sy \&Ft . All of these macros are output on their own line. -If two such dissimilar macros are pair-wise invoked (except for -.Sx \&Ft +If two such dissimilar macros are pairwise invoked (except for +.Sy \&Ft before -.Sx \&Fo +.Sy \&Fo or -.Sx \&Fn ) , +.Sy \&Fn ) , they are separated by a vertical space, unless in the case of -.Sx \&Fo , -.Sx \&Fn , +.Sy \&Fo , +.Sy \&Fn , and -.Sx \&Ft , +.Sy \&Ft , which are always separated by vertical space. .Pp When text and macros following an -.Sx \&Nm +.Sy \&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 +.Sy \&Nm macro, up to the next -.Sx \&Nm , -.Sx \&Sh , +.Sy \&Nm , +.Sy \&Sh , or -.Sx \&Ss +.Sy \&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 break-down of the options (if documenting a +.It Sx DESCRIPTION +This expands upon the brief, one line description in +.Sx NAME . +It usually contains a breakdown of the options (if documenting a command), such as: .Bd -literal -offset indent The arguments are as follows: @@ -484,19 +489,17 @@ .Ed .Pp Manuals not documenting a command won't include the above fragment. -.It Em IMPLEMENTATION NOTES +.It Sx IMPLEMENTATION NOTES Implementation-specific notes should be kept here. This is useful when implementing standard functions that may have side effects or notable algorithmic implications. -.It Em RETURN VALUES -This section is the dual of -.Em EXIT STATUS , -which is used for commands. -It documents the return values of functions in sections 2, 3, and 9. +.It Sx RETURN VALUES +This section documents the +return values of functions in sections 2, 3, and 9. .Pp See -.Sx \&Rv . -.It Em ENVIRONMENT +.Sy \&Rv . +.It Sx ENVIRONMENT Lists the environment variables used by the utility, and explains the syntax and semantics of their values. The @@ -504,76 +507,74 @@ manual provides examples of typical content and formatting. .Pp See -.Sx \&Ev . -.It Em FILES +.Sy \&Ev . +.It Sx 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 . -.It Em EXIT STATUS -Command exit status for section 1, 6, and 8 manuals. -This section is the dual of -.Em RETURN VALUES , -which is used for functions. +.Sy \&Pa . +.It Sx EXIT STATUS +This section documents the +command exit status for section 1, 6, and 8 utilities. Historically, this information was described in -.Em DIAGNOSTICS , +.Sx DIAGNOSTICS , a practise that is now discouraged. .Pp See -.Sx \&Ex . -.It Em EXAMPLES +.Sy \&Ex . +.It Sx EXAMPLES Example usages. This often contains snippets of well-formed, well-tested invocations. -Make doubly sure that your examples work properly! -.It Em DIAGNOSTICS +Make sure that examples work properly! +.It Sx DIAGNOSTICS Documents error conditions. This is most useful in section 4 manuals. Historically, this section was used in place of -.Em EXIT STATUS +.Sx EXIT STATUS for manuals in sections 1, 6, and 8; however, this practise is discouraged. .Pp See -.Sx \&Bl +.Sy \&Bl .Fl diag . -.It Em ERRORS +.It Sx ERRORS Documents error handling in sections 2, 3, and 9. .Pp See -.Sx \&Er . -.It Em SEE ALSO +.Sy \&Er . +.It Sx 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. .Pp See -.Sx \&Xr . -.It Em STANDARDS +.Sy \&Xr . +.It Sx STANDARDS References any standards implemented or used. If not adhering to any standards, the -.Em HISTORY +.Sx HISTORY section should be used instead. .Pp See -.Sx \&St . -.It Em HISTORY +.Sy \&St . +.It Sx HISTORY A brief history of the subject, including where support first appeared. -.It Em AUTHORS +.It Sx 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 . -.It Em CAVEATS +.Sy \&An . +.It Sx CAVEATS Common misuses and misunderstandings should be explained in this section. -.It Em BUGS +.It Sx BUGS Known bugs, limitations and work-arounds should be described in this section. -.It Em SECURITY CONSIDERATIONS +.It Sx SECURITY CONSIDERATIONS Documents any security precautions that operators should consider. .El .Sh MACRO SYNTAX @@ -623,7 +624,7 @@ .Ss Block full-explicit Multi-line scope closed by an explicit closing macro. All macros contains bodies; only -.Sx \&Bf +.Sy \&Bf contains a head. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB @@ -633,20 +634,20 @@ .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 +.It Sy \&Bd Ta \&No Ta \&No Ta closed by Sy \&Ed +.It Sy \&Bf Ta \&No Ta \&No Ta closed by Sy \&Ef +.It Sy \&Bk Ta \&No Ta \&No Ta closed by Sy \&Ek +.It Sy \&Bl Ta \&No Ta \&No Ta closed by Sy \&El +.It Sy \&Ed Ta \&No Ta \&No Ta opened by Sy \&Bd +.It Sy \&Ef Ta \&No Ta \&No Ta opened by Sy \&Bf +.It Sy \&Ek Ta \&No Ta \&No Ta opened by Sy \&Bk +.It Sy \&El Ta \&No Ta \&No Ta opened by Sy \&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 -.Sx \&It Fl bullet , +.Sy \&It Fl bullet , .Fl hyphen , .Fl dash , .Fl enum , @@ -654,9 +655,9 @@ .Pc don't have heads; only one .Po -.Sx \&It +.Sy \&It in -.Sx \&Bl Fl column +.Sy \&Bl Fl column .Pc has multiple heads. .Bd -literal -offset indent @@ -666,31 +667,31 @@ .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 +.It Sy \&It Ta \&No Ta Yes Ta closed by Sy \&It , Sy \&El +.It Sy \&Nd Ta \&No Ta \&No Ta closed by Sy \&Sh +.It Sy \&Nm Ta \&No Ta Yes Ta closed by Sy \&Nm , Sy \&Sh , Sy \&Ss +.It Sy \&Sh Ta \&No Ta \&No Ta closed by Sy \&Sh +.It Sy \&Ss Ta \&No Ta \&No Ta closed by Sy \&Sh , Sy \&Ss .El .Pp Note that the -.Sx \&Nm +.Sy \&Nm macro is a -.Sx Block full-implicit +.Sy Block full-implicit macro only when invoked as the first macro in a -.Em SYNOPSIS +.Sx SYNOPSIS section line, else it is -.Sx In-line . +.Sy 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 +.Sy \&Fo , +.Sy \&Eo .Pc and/or tail -.Pq Sx \&Ec . +.Pq Sy \&Ec . .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \(lBbody...\(rB @@ -702,34 +703,34 @@ .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 +.It Sy \&Ac Ta Yes Ta Yes Ta opened by Sy \&Ao +.It Sy \&Ao Ta Yes Ta Yes Ta closed by Sy \&Ac +.It Sy \&Bc Ta Yes Ta Yes Ta closed by Sy \&Bo +.It Sy \&Bo Ta Yes Ta Yes Ta opened by Sy \&Bc +.It Sy \&Brc Ta Yes Ta Yes Ta opened by Sy \&Bro +.It Sy \&Bro Ta Yes Ta Yes Ta closed by Sy \&Brc +.It Sy \&Dc Ta Yes Ta Yes Ta opened by Sy \&Do +.It Sy \&Do Ta Yes Ta Yes Ta closed by Sy \&Dc +.It Sy \&Ec Ta Yes Ta Yes Ta opened by Sy \&Eo +.It Sy \&Eo Ta Yes Ta Yes Ta closed by Sy \&Ec +.It Sy \&Fc Ta Yes Ta Yes Ta opened by Sy \&Fo +.It Sy \&Fo Ta \&No Ta \&No Ta closed by Sy \&Fc +.It Sy \&Oc Ta Yes Ta Yes Ta closed by Sy \&Oo +.It Sy \&Oo Ta Yes Ta Yes Ta opened by Sy \&Oc +.It Sy \&Pc Ta Yes Ta Yes Ta closed by Sy \&Po +.It Sy \&Po Ta Yes Ta Yes Ta opened by Sy \&Pc +.It Sy \&Qc Ta Yes Ta Yes Ta opened by Sy \&Oo +.It Sy \&Qo Ta Yes Ta Yes Ta closed by Sy \&Oc +.It Sy \&Re Ta \&No Ta \&No Ta opened by Sy \&Rs +.It Sy \&Rs Ta \&No Ta \&No Ta closed by Sy \&Re +.It Sy \&Sc Ta Yes Ta Yes Ta opened by Sy \&So +.It Sy \&So Ta Yes Ta Yes Ta closed by Sy \&Sc +.It Sy \&Xc Ta Yes Ta Yes Ta opened by Sy \&Xo +.It Sy \&Xo Ta Yes Ta Yes Ta closed by Sy \&Xc .El .Ss Block partial-implicit Like block full-implicit, but with single-line scope closed by -.Sx Reserved Characters +.Sy Reserved Characters or end of line. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB @@ -737,32 +738,32 @@ .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 +.It Sy \&Aq Ta Yes Ta Yes +.It Sy \&Bq Ta Yes Ta Yes +.It Sy \&Brq Ta Yes Ta Yes +.It Sy \&D1 Ta \&No Ta \&Yes +.It Sy \&Dl Ta \&No Ta Yes +.It Sy \&Dq Ta Yes Ta Yes +.It Sy \&Op Ta Yes Ta Yes +.It Sy \&Pq Ta Yes Ta Yes +.It Sy \&Ql Ta Yes Ta Yes +.It Sy \&Qq Ta Yes Ta Yes +.It Sy \&Sq Ta Yes Ta Yes +.It Sy \&Vt Ta Yes Ta Yes .El .Pp Note that the -.Sx \&Vt +.Sy \&Vt macro is a -.Sx Block partial-implicit +.Sy Block partial-implicit only when invoked as the first macro in a -.Em SYNOPSIS +.Sx SYNOPSIS section line, else it is -.Sx In-line . +.Sy In-line . .Ss In-line Closed by -.Sx Reserved Characters , +.Sy 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 @@ -778,80 +779,80 @@ .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 +.It Sy \&%A Ta \&No Ta \&No Ta >0 +.It Sy \&%B Ta \&No Ta \&No Ta >0 +.It Sy \&%C Ta \&No Ta \&No Ta >0 +.It Sy \&%D Ta \&No Ta \&No Ta >0 +.It Sy \&%I Ta \&No Ta \&No Ta >0 +.It Sy \&%J Ta \&No Ta \&No Ta >0 +.It Sy \&%N Ta \&No Ta \&No Ta >0 +.It Sy \&%O Ta \&No Ta \&No Ta >0 +.It Sy \&%P Ta \&No Ta \&No Ta >0 +.It Sy \&%Q Ta \&No Ta \&No Ta >0 +.It Sy \&%R Ta \&No Ta \&No Ta >0 +.It Sy \&%T Ta \&No Ta \&No Ta >0 +.It Sy \&%U Ta \&No Ta \&No Ta >0 +.It Sy \&%V Ta \&No Ta \&No Ta >0 +.It Sy \&Ad Ta Yes Ta Yes Ta n +.It Sy \&An Ta Yes Ta Yes Ta n +.It Sy \&Ap Ta Yes Ta Yes Ta 0 +.It Sy \&Ar Ta Yes Ta Yes Ta n +.It Sy \&At Ta Yes Ta Yes Ta 1 +.It Sy \&Bsx Ta Yes Ta Yes Ta n +.It Sy \&Bt Ta \&No Ta \&No Ta 0 +.It Sy \&Bx Ta Yes Ta Yes Ta n +.It Sy \&Cd Ta Yes Ta Yes Ta >0 +.It Sy \&Cm Ta Yes Ta Yes Ta n +.It Sy \&Db Ta \&No Ta \&No Ta 1 +.It Sy \&Dd Ta \&No Ta \&No Ta n +.It Sy \&Dt Ta \&No Ta \&No Ta n +.It Sy \&Dv Ta Yes Ta Yes Ta n +.It Sy \&Dx Ta Yes Ta Yes Ta n +.It Sy \&Em Ta Yes Ta Yes Ta >0 +.It Sy \&En Ta \&No Ta \&No Ta 0 +.It Sy \&Er Ta Yes Ta Yes Ta >0 +.It Sy \&Es Ta \&No Ta \&No Ta 0 +.It Sy \&Ev Ta Yes Ta Yes Ta n +.It Sy \&Ex Ta \&No Ta \&No Ta n +.It Sy \&Fa Ta Yes Ta Yes Ta n +.It Sy \&Fd Ta \&No Ta \&No Ta >0 +.It Sy \&Fl Ta Yes Ta Yes Ta n +.It Sy \&Fn Ta Yes Ta Yes Ta >0 +.It Sy \&Fr Ta \&No Ta \&No Ta n +.It Sy \&Ft Ta Yes Ta Yes Ta n +.It Sy \&Fx Ta Yes Ta Yes Ta n +.It Sy \&Hf Ta \&No Ta \&No Ta n +.It Sy \&Ic Ta Yes Ta Yes Ta >0 +.It Sy \&In Ta \&No Ta \&No Ta n +.It Sy \&Lb Ta \&No Ta \&No Ta 1 +.It Sy \&Li Ta Yes Ta Yes Ta n +.It Sy \&Lk Ta Yes Ta Yes Ta n +.It Sy \&Lp Ta \&No Ta \&No Ta 0 +.It Sy \&Ms Ta Yes Ta Yes Ta >0 +.It Sy \&Mt Ta Yes Ta Yes Ta >0 +.It Sy \&Nm Ta Yes Ta Yes Ta n +.It Sy \&No Ta Yes Ta Yes Ta 0 +.It Sy \&Ns Ta Yes Ta Yes Ta 0 +.It Sy \&Nx Ta Yes Ta Yes Ta n +.It Sy \&Os Ta \&No Ta \&No Ta n +.It Sy \&Ot Ta \&No Ta \&No Ta n +.It Sy \&Ox Ta Yes Ta Yes Ta n +.It Sy \&Pa Ta Yes Ta Yes Ta n +.It Sy \&Pf Ta Yes Ta Yes Ta 1 +.It Sy \&Pp Ta \&No Ta \&No Ta 0 +.It Sy \&Rv Ta \&No Ta \&No Ta n +.It Sy \&Sm Ta \&No Ta \&No Ta 1 +.It Sy \&St Ta \&No Ta Yes Ta 1 +.It Sy \&Sx Ta Yes Ta Yes Ta >0 +.It Sy \&Sy Ta Yes Ta Yes Ta >0 +.It Sy \&Tn Ta Yes Ta Yes Ta >0 +.It Sy \&Ud Ta \&No Ta \&No Ta 0 +.It Sy \&Ux Ta Yes Ta Yes Ta n +.It Sy \&Va Ta Yes Ta Yes Ta n +.It Sy \&Vt Ta Yes Ta Yes Ta >0 +.It Sy \&Xr Ta Yes Ta Yes Ta >0 +.It Sy \&br Ta \&No Ta \&No Ta 0 +.It Sy \&sp Ta \&No Ta \&No Ta 1 .El .Sh REFERENCE This section is a canonical reference of all macros, arranged @@ -860,22 +861,22 @@ .Sx MACRO SYNTAX . .Ss \&%A Author name of an -.Sx \&Rs +.Sy \&Rs block. Multiple authors should each be accorded their own -.Sx \%%A +.Sy \%%A line. Author names should be ordered with full or abbreviated forename(s) first, then full surname. .Ss \&%B Book title of an -.Sx \&Rs +.Sy \&Rs block. This macro may also be used in a non-bibliographic context when referring to book titles. .Ss \&%C Publication city or location of an -.Sx \&Rs +.Sy \&Rs block. .Pp .Em Remarks : @@ -883,44 +884,44 @@ .Xr groff 1 . .Ss \&%D Publication date of an -.Sx \&Rs +.Sy \&Rs block. This should follow the reduced or canonical form syntax described in -.Sx Dates . +.Sy Dates . .Ss \&%I Publisher or issuer name of an -.Sx \&Rs +.Sy \&Rs block. .Ss \&%J Journal name of an -.Sx \&Rs +.Sy \&Rs block. .Ss \&%N Issue number (usually for journals) of an -.Sx \&Rs +.Sy \&Rs block. .Ss \&%O Optional information of an -.Sx \&Rs +.Sy \&Rs block. .Ss \&%P Book or journal page number of an -.Sx \&Rs +.Sy \&Rs block. .Ss \&%Q Institutional author (school, government, etc.) of an -.Sx \&Rs +.Sy \&Rs block. Multiple institutional authors should each be accorded their own -.Sx \&%Q +.Sy \&%Q line. .Ss \&%R Technical report name of an -.Sx \&Rs +.Sy \&Rs block. .Ss \&%T Article title of an -.Sx \&Rs +.Sy \&Rs block. This macro may also be used in a non-bibliographical context when referring to article titles. @@ -928,11 +929,11 @@ URI of reference document. .Ss \&%V Volume number of an -.Sx \&Rs +.Sy \&Rs block. .Ss \&Ac Close an -.Sx \&Ao +.Sy \&Ao block. Does not have any tail arguments. .Ss \&Ad @@ -949,7 +950,7 @@ .Bl -tag -width "-nosplitX" -offset indent -compact .It Fl split Start a new output line before each subsequent invocation of -.Sx \&An . +.Sy \&An . .It Fl nosplit The opposite of .Fl split . @@ -981,7 +982,7 @@ .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac .Pp See also -.Sx \&Aq . +.Sy \&Aq . .Ss \&Ap Inserts an apostrophe without any surrounding whitespace. This is generally used as a grammatical device when referring to the verb @@ -997,16 +998,16 @@ .Pp .Em Remarks : this macro is often abused for rendering URIs, which should instead use -.Sx \&Lk +.Sy \&Lk or -.Sx \&Mt , +.Sy \&Mt , or to note pre-processor .Dq Li #include statements, which should use -.Sx \&In . +.Sy \&In . .Pp See also -.Sx \&Ao . +.Sy \&Ao . .Ss \&Ar Command arguments. If an argument is not provided, the string @@ -1037,17 +1038,17 @@ .D1 \&.At V.1 .Pp See also -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , -.Sx \&Ox , +.Sy \&Bsx , +.Sy \&Bx , +.Sy \&Dx , +.Sy \&Fx , +.Sy \&Nx , +.Sy \&Ox , and -.Sx \&Ux . +.Sy \&Ux . .Ss \&Bc Close a -.Sx \&Bo +.Sy \&Bo block. Does not have any tail arguments. .Ss \&Bd @@ -1138,9 +1139,9 @@ .Ed .Pp See also -.Sx \&D1 +.Sy \&D1 and -.Sx \&Dl . +.Sy \&Dl . .Ss \&Bf Change the font mode for a scoped block of text. Its syntax is as follows: @@ -1159,7 +1160,7 @@ argument are equivalent, as are .Fl symbolic and -.Cm \&Sy, +.Cm \&Sy , and .Fl literal and @@ -1167,15 +1168,15 @@ 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 +.Sy \&Ef is encountered. .Pp See also -.Sx \&Li , -.Sx \&Ef , -.Sx \&Em , +.Sy \&Li , +.Sy \&Ef , +.Sy \&Em , and -.Sx \&Sy . +.Sy \&Sy . .Ss \&Bk Keep the output generated from each macro input line together on one single output line. @@ -1189,7 +1190,7 @@ argument is required; additional arguments are ignored. .Pp The following example will not break within each -.Sx \&Op +.Sy \&Op macro line: .Bd -literal -offset indent \&.Bk \-words @@ -1203,7 +1204,7 @@ .Ss \&Bl Begin a list. Lists consist of items started by the -.Sx \&It +.Sy \&It macro, containing a head or a body or both. The list syntax is as follows: .Bd -ragged -offset indent @@ -1258,14 +1259,14 @@ If the first line of the body of a .Fl column list is not an -.Sx \&It +.Sy \&It macro line, -.Sx \&It +.Sy \&It contexts spanning one input line each are implied until an -.Sx \&It +.Sy \&It macro line is encountered, at which point items start being interpreted as described in the -.Sx \&It +.Sy \&It documentation. .It Fl dash Like @@ -1318,9 +1319,9 @@ .El .Pp See also -.Sx \&El +.Sy \&El and -.Sx \&It . +.Sy \&It . .Ss \&Bo Begin a block enclosed by square brackets. Does not have any head arguments. @@ -1332,7 +1333,7 @@ .Ed .Pp See also -.Sx \&Bq . +.Sy \&Bq . .Ss \&Bq Encloses its arguments in square brackets. .Pp @@ -1342,16 +1343,16 @@ .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 , +.Sy \&Op , +.Sy \&Oo , and -.Sx \&Oc . +.Sy \&Oc . .Pp See also -.Sx \&Bo . +.Sy \&Bo . .Ss \&Brc Close a -.Sx \&Bro +.Sy \&Bro block. Does not have any tail arguments. .Ss \&Bro @@ -1365,7 +1366,7 @@ .Ed .Pp See also -.Sx \&Brq . +.Sy \&Brq . .Ss \&Brq Encloses its arguments in curly braces. .Pp @@ -1373,7 +1374,7 @@ .D1 \&.Brq 1 , ... , \&Va n .Pp See also -.Sx \&Bro . +.Sy \&Bro . .Ss \&Bsx Format the BSD/OS version provided as an argument, or a default value if no argument is provided. @@ -1383,17 +1384,17 @@ .D1 \&.Bsx .Pp See also -.Sx \&At , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , -.Sx \&Ox , +.Sy \&At , +.Sy \&Bx , +.Sy \&Dx , +.Sy \&Fx , +.Sy \&Nx , +.Sy \&Ox , and -.Sx \&Ux . +.Sy \&Ux . .Ss \&Bt Prints -.Dq is currently in beta test. +.Dq is currently in beta test . .Ss \&Bx Format the BSD version provided as an argument, or a default value if no argument is provided. @@ -1403,14 +1404,14 @@ .D1 \&.Bx .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , -.Sx \&Ox , +.Sy \&At , +.Sy \&Bsx , +.Sy \&Dx , +.Sy \&Fx , +.Sy \&Nx , +.Sy \&Ox , and -.Sx \&Ux . +.Sy \&Ux . .Ss \&Cd Kernel configuration declaration. This denotes strings accepted by @@ -1422,7 +1423,7 @@ .Em Remarks : this macro is commonly abused by using quoted literals to retain whitespace and align consecutive -.Sx \&Cd +.Sy \&Cd declarations. This practise is discouraged. .Ss \&Cm @@ -1434,7 +1435,7 @@ .D1 \&.Cm ControlMaster .Pp See also -.Sx \&Fl . +.Sy \&Fl . .Ss \&D1 One-line indented display. This is formatted by the default rules and is useful for simple indented @@ -1445,9 +1446,9 @@ .D1 \&.D1 \&Fl abcdefgh .Pp See also -.Sx \&Bd +.Sy \&Bd and -.Sx \&Dl . +.Sy \&Dl . .Ss \&Db Switch debugging mode. Its syntax is as follows: @@ -1458,7 +1459,7 @@ .Xr mandoc 1 . .Ss \&Dc Close a -.Sx \&Do +.Sy \&Do block. Does not have any tail arguments. .Ss \&Dd @@ -1477,7 +1478,7 @@ which signifies the current manual revision date dictated by .Xr cvs 1 , or instead a valid canonical date as specified by -.Sx Dates . +.Sy Dates . If a date does not conform or is empty, the current date is used. .Pp Examples: @@ -1486,9 +1487,9 @@ .D1 \&.Dd July 21, 2007 .Pp See also -.Sx \&Dt +.Sy \&Dt and -.Sx \&Os . +.Sy \&Os . .Ss \&Dl One-line intended display. This is formatted as literal text and is useful for commands and @@ -1499,9 +1500,9 @@ .D1 \&.Dl % mandoc mdoc.7 \e(ba less .Pp See also -.Sx \&Bd +.Sy \&Bd and -.Sx \&D1 . +.Sy \&D1 . .Ss \&Do Begin a block enclosed by double quotes. Does not have any head arguments. @@ -1515,7 +1516,7 @@ .Ed .Pp See also -.Sx \&Dq . +.Sy \&Dq . .Ss \&Dq Encloses its arguments in .Dq typographic @@ -1528,10 +1529,10 @@ .Ed .Pp See also -.Sx \&Qq , -.Sx \&Sq , +.Sy \&Qq , +.Sy \&Sq , and -.Sx \&Do . +.Sy \&Do . .Ss \&Dt Document title. This is the mandatory second macro of any @@ -1668,9 +1669,9 @@ .D1 \&.Dt FOO 9 i386 .Pp See also -.Sx \&Dd +.Sy \&Dd and -.Sx \&Os . +.Sy \&Os . .Ss \&Dv Defined variables such as preprocessor constants. .Pp @@ -1679,7 +1680,7 @@ .D1 \&.Dv STDOUT_FILENO .Pp See also -.Sx \&Er . +.Sy \&Er . .Ss \&Dx Format the DragonFly BSD version provided as an argument, or a default value if no argument is provided. @@ -1689,17 +1690,17 @@ .D1 \&.Dx .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Fx , -.Sx \&Nx , -.Sx \&Ox , +.Sy \&At , +.Sy \&Bsx , +.Sy \&Bx , +.Sy \&Fx , +.Sy \&Nx , +.Sy \&Ox , and -.Sx \&Ux . +.Sy \&Ux . .Ss \&Ec Close a scope started by -.Sx \&Eo . +.Sy \&Eo . Its syntax is as follows: .Pp .D1 Pf \. Sx \&Ec Op Ar TERM @@ -1708,24 +1709,24 @@ .Ar TERM argument is used as the enclosure tail, for example, specifying \e(rq will emulate -.Sx \&Dc . +.Sy \&Dc . .Ss \&Ed End a display context started by -.Sx \&Bd . +.Sy \&Bd . .Ss \&Ef End a font mode context started by -.Sx \&Bf . +.Sy \&Bf . .Ss \&Ek End a keep context started by -.Sx \&Bk . +.Sy \&Bk . .Ss \&El End a list context started by -.Sx \&Bl . +.Sy \&Bl . .Pp See also -.Sx \&Bl +.Sy \&Bl and -.Sx \&It . +.Sy \&It . .Ss \&Em Denotes text that should be emphasised. Note that this is a presentation term and should not be used for @@ -1736,10 +1737,10 @@ .D1 \&.Em Remarks : .Pp See also -.Sx \&Bf , -.Sx \&Sy , +.Sy \&Bf , +.Sy \&Sy , and -.Sx \&Li . +.Sy \&Li . .Ss \&En This macro is obsolete and not implemented in .Xr mandoc 1 . @@ -1753,7 +1754,7 @@ .Ar TERM argument is used as the enclosure head, for example, specifying \e(lq will emulate -.Sx \&Do . +.Sy \&Do . .Ss \&Er Display error constants. .Pp @@ -1762,7 +1763,7 @@ .D1 \&.Er ENOENT .Pp See also -.Sx \&Dv . +.Sy \&Dv . .Ss \&Es This macro is obsolete and not implemented. .Ss \&Ev @@ -1781,11 +1782,11 @@ When .Ar utility is not specified, the document's name set by -.Sx \&Nm +.Sy \&Nm is used. .Pp See also -.Sx \&Rv . +.Sy \&Rv . .Ss \&Fa Function argument. Its syntax is as follows: @@ -1798,16 +1799,16 @@ This may be invoked for names with or without the corresponding type. It is also used to specify the field name of a structure. Most often, the -.Sx \&Fa +.Sy \&Fa macro is used in the .Em SYNOPSIS within -.Sx \&Fo +.Sy \&Fo section 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 , +.Sy \&Fa , the last argument will also have a trailing comma. .Pp Examples: @@ -1816,20 +1817,20 @@ .D1 \&.Fa foo .Pp See also -.Sx \&Fo . +.Sy \&Fo . .Ss \&Fc End a function context started by -.Sx \&Fo . +.Sy \&Fo . .Ss \&Fd Historically used to document include files. This usage has been deprecated in favour of -.Sx \&In . +.Sy \&In . Do not use this macro. .Pp See also .Sx MANUAL STRUCTURE and -.Sx \&In . +.Sy \&In . .Ss \&Fl Command-line flag. Used when listing arguments to command-line utilities. @@ -1847,7 +1848,7 @@ .D1 \&.Op \&Fl o \&Ns \&Ar file .Pp See also -.Sx \&Cm . +.Sy \&Cm . .Ss \&Fn A function name. Its syntax is as follows: @@ -1874,11 +1875,11 @@ See also .Sx MANUAL STRUCTURE and -.Sx \&Ft . +.Sy \&Ft . .Ss \&Fo Begin a function block. This is a multi-line version of -.Sx \&Fn . +.Sy \&Fn . Its syntax is as follows: .Pp .D1 Pf \. Sx \&Fo Cm funcname @@ -1897,15 +1898,15 @@ .Ed .Pp A -.Sx \&Fo +.Sy \&Fo scope is closed by .Pp See also .Sx MANUAL STRUCTURE , -.Sx \&Fa , -.Sx \&Fc , +.Sy \&Fa , +.Sy \&Fc , and -.Sx \&Ft . +.Sy \&Ft . .Ss \&Ft A function type. Its syntax is as follows: @@ -1921,11 +1922,13 @@ .Pp See also .Sx MANUAL STRUCTURE , -.Sx \&Fn , +.Sy \&Fn , and -.Sx \&Fo . +.Sy \&Fo . .Ss \&Fx -Format the FreeBSD version provided as an argument, or a default value +Format the +.Fx +version provided as an argument, or a default value if no argument is provided. .Pp Examples: @@ -1933,20 +1936,20 @@ .D1 \&.Fx .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Nx , -.Sx \&Ox , +.Sy \&At , +.Sy \&Bsx , +.Sy \&Bx , +.Sy \&Dx , +.Sy \&Nx , +.Sy \&Ox , and -.Sx \&Ux . +.Sy \&Ux . .Ss \&Hf This macro is obsolete and not implemented. .Ss \&Ic Designate an internal or interactive command. This is similar to -.Sx \&Cm +.Sy \&Cm but used for instructions rather than values. .Pp Examples: @@ -1954,11 +1957,11 @@ .D1 \&.Ic alias .Pp Note that using -.Sx \&Bd No Fl literal +.Sy \&Bd Fl literal or -.Sx \&D1 +.Sy \&D1 is preferred for displaying code; the -.Sx \&Ic +.Sy \&Ic macro is used when referring to specific instructions. .Ss \&In An @@ -2003,11 +2006,11 @@ .D1 Pf \. Sx \&It .Pp with subsequent lines interpreted within the scope of the -.Sx \&It +.Sy \&It until either a closing -.Sx \&El +.Sy \&El or another -.Sx \&It . +.Sy \&It . .Pp The .Fl tag @@ -2035,21 +2038,21 @@ .Sq \&Ta pseudo-macro. Lines subsequent the -.Sx \&It +.Sy \&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 +.Sy \&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 , +.Sy \&It , for example, .Pp .D1 .It \(dqcol1 ; col2 ;\(dq \&; @@ -2057,7 +2060,7 @@ will preserve the semicolon whitespace except for the last. .Pp See also -.Sx \&Bl . +.Sy \&Bl . .Ss \&Lb Specify a library. The syntax is as follows: @@ -2087,10 +2090,10 @@ stylistically decorating technical terms. .Pp See also -.Sx \&Bf , -.Sx \&Sy , +.Sy \&Bf , +.Sy \&Sy , and -.Sx \&Em . +.Sy \&Em . .Ss \&Lk Format a hyperlink. Its syntax is as follows: @@ -2102,10 +2105,10 @@ .D1 \&.Lk http://bsd.lv .Pp See also -.Sx \&Mt . +.Sy \&Mt . .Ss \&Lp Synonym for -.Sx \&Pp . +.Sy \&Pp . .Ss \&Ms Display a mathematical symbol. Its syntax is as follows: @@ -2126,11 +2129,11 @@ Examples: .D1 \&.Mt discuss@manpages.bsd.lv .Ss \&Nd -A one-line description of the manual's content. +A one line description of the manual's content. This may only be invoked in the .Em SYNOPSIS section subsequent the -.Sx \&Nm +.Sy \&Nm macro. .Pp Examples: @@ -2138,9 +2141,9 @@ .D1 \&.Sx \&Nd format and display UNIX manuals .Pp The -.Sx \&Nd +.Sy \&Nd macro technically accepts child macros and terminates with a subsequent -.Sx \&Sh +.Sy \&Sh invocation. Do not assume this behaviour: some .Xr whatis 1 @@ -2148,13 +2151,13 @@ arguments and will display macros verbatim. .Pp See also -.Sx \&Nm . +.Sy \&Nm . .Ss \&Nm 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 +.Sy \&Nm macro expects a single argument, the name of the manual page. Usually, the first invocation happens in the .Em NAME @@ -2162,13 +2165,13 @@ The specified name will be remembered and used whenever the macro is called again without arguments later in the page. The -.Sx \&Nm +.Sy \&Nm macro uses -.Sx Block full-implicit +.Sy Block full-implicit semantics when invoked as the first macro on an input line in the .Em SYNOPSIS section; otherwise, it uses ordinary -.Sx In-line +.Sy In-line semantics. .Pp Examples: @@ -2182,9 +2185,9 @@ In the .Em SYNOPSIS of section 2, 3 and 9 manual pages, use the -.Sx \&Fn +.Sy \&Fn macro rather than -.Sx \&Nm +.Sy \&Nm to mark up the name of the manual page. .Ss \&No A @@ -2202,11 +2205,13 @@ .D1 \&.Fl o \&Ns \&Ar output .Pp See also -.Sx \&No +.Sy \&No and -.Sx \&Sm . +.Sy \&Sm . .Ss \&Nx -Format the NetBSD version provided as an argument, or a default value if +Format the +.Nx +version provided as an argument, or a default value if no argument is provided. .Pp Examples: @@ -2214,21 +2219,21 @@ .D1 \&.Nx .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Ox , +.Sy \&At , +.Sy \&Bsx , +.Sy \&Bx , +.Sy \&Dx , +.Sy \&Fx , +.Sy \&Ox , and -.Sx \&Ux . +.Sy \&Ux . .Ss \&Oc Close multi-line -.Sx \&Oo +.Sy \&Oo context. .Ss \&Oo Multi-line version of -.Sx \&Op . +.Sy \&Op . .Pp Examples: .Bd -literal -offset indent -compact @@ -2246,7 +2251,7 @@ .D1 \&.Op \&Ar a | b .Pp See also -.Sx \&Oo . +.Sy \&Oo . .Ss \&Os Document operating system version. This is the mandatory third macro of @@ -2269,16 +2274,18 @@ .D1 \&.Os BSD 4.3 .Pp See also -.Sx \&Dd +.Sy \&Dd and -.Sx \&Dt . +.Sy \&Dt . .Ss \&Ot Unknown usage. .Pp .Em Remarks : this macro has been deprecated. .Ss \&Ox -Format the OpenBSD version provided as an argument, or a default value +Format the +.Ox +version provided as an argument, or a default value if no argument is provided. .Pp Examples: @@ -2286,14 +2293,14 @@ .D1 \&.Ox .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , +.Sy \&At , +.Sy \&Bsx , +.Sy \&Bx , +.Sy \&Dx , +.Sy \&Fx , +.Sy \&Nx , and -.Sx \&Ux . +.Sy \&Ux . .Ss \&Pa A file-system path. .Pp @@ -2302,10 +2309,10 @@ .D1 \&.Pa /usr/share/man/man7/mdoc.7 .Pp See also -.Sx \&Lk . +.Sy \&Lk . .Ss \&Pc Close parenthesised context opened by -.Sx \&Po . +.Sy \&Po . .Ss \&Pf Removes the space .Pq Dq prefix @@ -2322,7 +2329,7 @@ .D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix .Ss \&Po Multi-line version of -.Sx \&Pq . +.Sy \&Pq . .Ss \&Pp Break a paragraph. This will assert vertical space between prior and subsequent macros @@ -2331,34 +2338,34 @@ Parenthesised enclosure. .Pp See also -.Sx \&Po . +.Sy \&Po . .Ss \&Qc Close quoted context opened by -.Sx \&Qo . +.Sy \&Qo . .Ss \&Ql Format a single-quoted literal. See also -.Sx \&Qq +.Sy \&Qq and -.Sx \&Sq . +.Sy \&Sq . .Ss \&Qo Multi-line version of -.Sx \&Qq . +.Sy \&Qq . .Ss \&Qq Encloses its arguments in .Dq typewriter double-quotes. Consider using -.Sx \&Dq . +.Sy \&Dq . .Pp See also -.Sx \&Dq , -.Sx \&Sq , +.Sy \&Dq , +.Sy \&Sq , and -.Sx \&Qo . +.Sy \&Qo . .Ss \&Re Close an -.Sx \&Rs +.Sy \&Rs block. Does not have any tail arguments. .Ss \&Rs @@ -2367,21 +2374,21 @@ 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 , +.Sy \&%A , +.Sy \&%B , +.Sy \&%C , +.Sy \&%D , +.Sy \&%I , +.Sy \&%J , +.Sy \&%N , +.Sy \&%O , +.Sy \&%P , +.Sy \&%Q , +.Sy \&%R , +.Sy \&%T , +.Sy \&%U , and -.Sx \&%V +.Sy \&%V child macros (at least one must be specified). .Pp Examples: @@ -2397,7 +2404,7 @@ .Ed .Pp If an -.Sx \&Rs +.Sy \&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. @@ -2410,14 +2417,14 @@ If .Ar function is not provided, the document's name as stipulated by the first -.Sx \&Nm +.Sy \&Nm is provided. .Pp See also -.Sx \&Ex . +.Sy \&Ex . .Ss \&Sc Close single-quoted context opened by -.Sx \&So . +.Sy \&So . .Ss \&Sh Begin a new section. For a list of conventional manual sections, see @@ -2426,13 +2433,13 @@ custom sections be used. .Pp Section names should be unique so that they may be keyed by -.Sx \&Sx . +.Sy \&Sx . .Pp See also -.Sx \&Pp , -.Sx \&Ss , +.Sy \&Pp , +.Sy \&Ss , and -.Sx \&Sx . +.Sy \&Sx . .Ss \&Sm Switches the spacing mode for output generated from macros. Its syntax is as follows: @@ -2448,34 +2455,34 @@ still get normal spacing between words and sentences. .Ss \&So Multi-line version of -.Sx \&Sq . +.Sy \&Sq . .Ss \&Sq Encloses its arguments in .Dq typewriter single-quotes. .Pp See also -.Sx \&Dq , -.Sx \&Qq , +.Sy \&Dq , +.Sy \&Qq , and -.Sx \&So . +.Sy \&So . .Ss \&Ss Begin a new sub-section. Unlike with -.Sx \&Sh , +.Sy \&Sh , there's no convention for sub-sections. Conventional sections, as described in .Sx MANUAL STRUCTURE , rarely have sub-sections. .Pp Sub-section names should be unique so that they may be keyed by -.Sx \&Sx . +.Sy \&Sx . .Pp See also -.Sx \&Pp , -.Sx \&Sh , +.Sy \&Pp , +.Sy \&Sh , and -.Sx \&Sx . +.Sy \&Sx . .Ss \&St Replace an abbreviation for a standard with the full form. The following standards are recognised: @@ -2587,10 +2594,10 @@ stylistically decorating technical terms. .Pp See also -.Sx \&Bf , -.Sx \&Li , +.Sy \&Bf , +.Sy \&Li , and -.Sx \&Em . +.Sy \&Em . .Ss \&Tn Format a tradename. .Pp @@ -2598,7 +2605,7 @@ .D1 \&.Tn IBM .Ss \&Ud Prints out -.Dq currently under development. +.Dq currently under development . .Ss \&Ux Format the UNIX name. Accepts no argument. @@ -2607,14 +2614,14 @@ .D1 \&.Ux .Pp See also -.Sx \&At , -.Sx \&Bsx , -.Sx \&Bx , -.Sx \&Dx , -.Sx \&Fx , -.Sx \&Nx , +.Sy \&At , +.Sy \&Bsx , +.Sy \&Bx , +.Sy \&Dx , +.Sy \&Fx , +.Sy \&Nx , and -.Sx \&Ox . +.Sy \&Ox . .Ss \&Va A variable name. .Pp @@ -2627,15 +2634,15 @@ .Em SYNOPSIS section, in which case a variable name is also specified. Note that it accepts -.Sx Block partial-implicit +.Sy Block partial-implicit syntax when invoked as the first macro in the .Em SYNOPSIS section, else it accepts ordinary -.Sx In-line +.Sy In-line syntax. .Pp Note that this should not be confused with -.Sx \&Ft , +.Sy \&Ft , which is used for function return types. .Pp Examples: @@ -2645,10 +2652,10 @@ See also .Sx MANUAL STRUCTURE and -.Sx \&Va . +.Sy \&Va . .Ss \&Xc Close a scope opened by -.Sx \&Xo . +.Sy \&Xo . .Ss \&Xo Open an extension scope. This macro originally existed to extend the 9-argument limit of troff; @@ -2668,7 +2675,7 @@ If .Cm section is followed by non-punctuation, an -.Sx \&Ns +.Sy \&Ns is inserted into the token stream. This behaviour is for compatibility with .Xr groff 1 . @@ -2683,7 +2690,7 @@ historical manuals. .Pp Consider using -.Sx \&Pp +.Sy \&Pp in the event of natural paragraph breaks. .Ss \&sp Emits vertical space. @@ -2698,7 +2705,7 @@ argument must be formatted as described in .Sx Scaling Widths . If unspecified, -.Sx \&sp +.Sy \&sp asserts a single vertical space. .Sh COMPATIBILITY This section documents compatibility between mandoc and other other @@ -2726,12 +2733,12 @@ font decoration escapes are all discarded in mandoc. .It Old groff fails to assert a newline before -.Sx \&Bd Fl ragged compact . +.Sy \&Bd Fl ragged compact . .It groff behaves inconsistently when encountering .Pf non- Sx \&Fa children of -.Sx \&Fo +.Sy \&Fo regarding spacing between arguments. In mandoc, this is not the case: each argument is consistently followed by a single space and the trailing @@ -2739,29 +2746,29 @@ suppresses prior spacing. .It groff behaves inconsistently when encountering -.Sx \&Ft +.Sy \&Ft and -.Sx \&Fn +.Sy \&Fn in the .Em SYNOPSIS : at times newline(s) are suppressed depending on whether a prior -.Sx \&Fn +.Sy \&Fn has been invoked. In mandoc, this is not the case. See -.Sx \&Ft +.Sy \&Ft and -.Sx \&Fn +.Sy \&Fn for the normalised behaviour. .It Historic groff does not break before an -.Sx \&Fn +.Sy \&Fn when not invoked as the line macro in the .Em SYNOPSIS section. .It Historic groff formats the -.Sx \&In +.Sy \&In badly: trailing arguments are trashed and .Em SYNOPSIS is not specially treated. @@ -2776,19 +2783,19 @@ is no longer accepted. .It In groff, the -.Sx \&Pa +.Sy \&Pa macro does not format its arguments when used in the FILES section under certain list types. mandoc does. .It Historic groff does not print a dash for empty -.Sx \&Fl +.Sy \&Fl arguments. mandoc and newer groff implementations do. .It groff behaves irregularly when specifying .Sq \ef -.Sx Text Decoration +.Sy Text Decoration within line-macro scopes. mandoc follows a consistent system. .It @@ -2798,12 +2805,12 @@ .Sq f scaling unit, while accepted, is rendered as the default unit. .It -In quoted literals, groff allowed pair-wise double-quotes to produce a +In quoted literals, groff allowed pairwise double-quotes to produce a standalone double-quote in formatted output. This idiosyncratic behaviour is not applicable in mandoc. .It Display offsets -.Sx \&Bd +.Sy \&Bd .Fl offset Ar center and .Fl offset Ar right @@ -2829,31 +2836,31 @@ .Qq go orbital but has been a proper delimiter since then. .It -.Sx \&It Fl nested +.Sy \&It Fl nested is assumed for all lists (it wasn't in historic groff): any list may be nested and .Fl enum lists will restart the sequence only for the sub-list. .It Some manuals use -.Sx \&Li +.Sy \&Li incorrectly by following it with a reserved character and expecting the delimiter to render. This is not supported in mandoc. .It In groff, the -.Sx \&Cd , -.Sx \&Er , -.Sx \&Ex , +.Sy \&Cd , +.Sy \&Er , +.Sy \&Ex , and -.Sx \&Rv +.Sy \&Rv macros were stipulated only to occur in certain manual sections. mandoc does not have these restrictions. .It Newer groff and mandoc print .Qq AT&T UNIX prior to unknown arguments of -.Sx \&At ; +.Sy \&At ; older groff did nothing. .El .Sh SEE ALSO -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv