1bbf21555SRichard Lowe.\" $Id: mdoc.7,v 1.287 2021/07/29 17:32:01 schwarze Exp $ 2bbf21555SRichard Lowe.\" 3bbf21555SRichard Lowe.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4bbf21555SRichard Lowe.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org> 5bbf21555SRichard Lowe.\" 6bbf21555SRichard Lowe.\" Permission to use, copy, modify, and distribute this software for any 7bbf21555SRichard Lowe.\" purpose with or without fee is hereby granted, provided that the above 8bbf21555SRichard Lowe.\" copyright notice and this permission notice appear in all copies. 9bbf21555SRichard Lowe.\" 10bbf21555SRichard Lowe.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11bbf21555SRichard Lowe.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12bbf21555SRichard Lowe.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13bbf21555SRichard Lowe.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14bbf21555SRichard Lowe.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15bbf21555SRichard Lowe.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16bbf21555SRichard Lowe.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17bbf21555SRichard Lowe.\" 18bbf21555SRichard Lowe.\" 19bbf21555SRichard Lowe.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> 20bbf21555SRichard Lowe.\" Copyright 2018 Nexenta Systems, Inc. 21bbf21555SRichard Lowe.\" 22*c55633c3SPeter Tribble.Dd March 30, 2022 23bbf21555SRichard Lowe.Dt MDOC 7 24bbf21555SRichard Lowe.Os 25bbf21555SRichard Lowe.Sh NAME 26bbf21555SRichard Lowe.Nm mdoc 27bbf21555SRichard Lowe.Nd semantic markup language for formatting manual pages 28bbf21555SRichard Lowe.Sh DESCRIPTION 29bbf21555SRichard LoweThe 30bbf21555SRichard Lowe.Nm mdoc 31bbf21555SRichard Lowelanguage supports authoring of manual pages for the 32bbf21555SRichard Lowe.Xr man 1 33bbf21555SRichard Loweutility by allowing semantic annotations of words, phrases, 34bbf21555SRichard Lowepage sections and complete manual pages. 35bbf21555SRichard LoweSuch annotations are used by formatting tools to achieve a uniform 36bbf21555SRichard Lowepresentation across all manuals written in 37bbf21555SRichard Lowe.Nm , 38bbf21555SRichard Loweand to support hyperlinking if supported by the output medium. 39bbf21555SRichard Lowe.Pp 40bbf21555SRichard LoweThis reference document describes the structure of manual pages 41bbf21555SRichard Loweand the syntax and usage of the 42bbf21555SRichard Lowe.Nm 43bbf21555SRichard Lowelanguage. 44bbf21555SRichard LoweThe reference implementation of a parsing and formatting tool is 45bbf21555SRichard Lowe.Xr mandoc 1 ; 46bbf21555SRichard Lowethe 47bbf21555SRichard Lowe.Sx COMPATIBILITY 48bbf21555SRichard Lowesection describes compatibility with other implementations. 49bbf21555SRichard Lowe.Pp 50bbf21555SRichard LoweIn an 51bbf21555SRichard Lowe.Nm 52bbf21555SRichard Lowedocument, lines beginning with the control character 53bbf21555SRichard Lowe.Sq \&. 54bbf21555SRichard Loweare called 55bbf21555SRichard Lowe.Dq macro lines . 56bbf21555SRichard LoweThe first word is the macro name. 57bbf21555SRichard LoweIt consists of two or three letters. 58bbf21555SRichard LoweMost macro names begin with a capital letter. 59bbf21555SRichard LoweFor a list of available macros, see 60bbf21555SRichard Lowe.Sx MACRO OVERVIEW . 61bbf21555SRichard LoweThe words following the macro name are arguments to the macro, optionally 62bbf21555SRichard Loweincluding the names of other, callable macros; see 63bbf21555SRichard Lowe.Sx MACRO SYNTAX 64bbf21555SRichard Lowefor details. 65bbf21555SRichard Lowe.Pp 66bbf21555SRichard LoweLines not beginning with the control character are called 67bbf21555SRichard Lowe.Dq text lines . 68bbf21555SRichard LoweThey provide free-form text to be printed; the formatting of the text 69bbf21555SRichard Lowedepends on the respective processing context: 70bbf21555SRichard Lowe.Bd -literal -offset indent 71bbf21555SRichard Lowe\&.Sh Macro lines change control state. 72bbf21555SRichard LoweText lines are interpreted within the current state. 73bbf21555SRichard Lowe.Ed 74bbf21555SRichard Lowe.Pp 75bbf21555SRichard LoweMany aspects of the basic syntax of the 76bbf21555SRichard Lowe.Nm 77bbf21555SRichard Lowelanguage are based on the 78bbf21555SRichard Lowe.Xr mandoc_roff 7 79bbf21555SRichard Lowelanguage; see the 80bbf21555SRichard Lowe.Em LANGUAGE SYNTAX 81bbf21555SRichard Loweand 82bbf21555SRichard Lowe.Em MACRO SYNTAX 83bbf21555SRichard Lowesections in the 84bbf21555SRichard Lowe.Xr mandoc_roff 7 85bbf21555SRichard Lowemanual for details, in particular regarding 86bbf21555SRichard Lowecomments, escape sequences, whitespace, and quoting. 87bbf21555SRichard LoweHowever, using 88bbf21555SRichard Lowe.Xr mandoc_roff 7 89bbf21555SRichard Lowerequests in 90bbf21555SRichard Lowe.Nm 91bbf21555SRichard Lowedocuments is discouraged; 92bbf21555SRichard Lowe.Xr mandoc 1 93bbf21555SRichard Lowesupports some of them merely for backward compatibility. 94bbf21555SRichard Lowe.Sh MANUAL STRUCTURE 95bbf21555SRichard LoweA well-formed 96bbf21555SRichard Lowe.Nm 97bbf21555SRichard Lowedocument consists of a document prologue followed by one or more 98bbf21555SRichard Lowesections. 99bbf21555SRichard Lowe.Pp 100bbf21555SRichard LoweThe prologue, which consists of the 101bbf21555SRichard Lowe.Ic \&Dd , 102bbf21555SRichard Lowe.Ic \&Dt , 103bbf21555SRichard Loweand 104bbf21555SRichard Lowe.Ic \&Os 105bbf21555SRichard Lowemacros in that order, is required for every document. 106bbf21555SRichard Lowe.Pp 107bbf21555SRichard LoweThe first section (sections are denoted by 108bbf21555SRichard Lowe.Ic \&Sh ) 109bbf21555SRichard Lowemust be the NAME section, consisting of at least one 110bbf21555SRichard Lowe.Ic \&Nm 111bbf21555SRichard Lowefollowed by 112bbf21555SRichard Lowe.Ic \&Nd . 113bbf21555SRichard Lowe.Pp 114bbf21555SRichard LoweFollowing that, convention dictates specifying at least the 115bbf21555SRichard Lowe.Em SYNOPSIS 116bbf21555SRichard Loweand 117bbf21555SRichard Lowe.Em DESCRIPTION 118bbf21555SRichard Lowesections, although this varies between manual sections. 119bbf21555SRichard Lowe.Pp 120bbf21555SRichard LoweThe following is a well-formed skeleton 121bbf21555SRichard Lowe.Nm 122bbf21555SRichard Lowefile for a utility 123bbf21555SRichard Lowe.Qq progname : 124bbf21555SRichard Lowe.Bd -literal -offset indent 125bbf21555SRichard Lowe\&.Dd Jan 1, 1970 126bbf21555SRichard Lowe\&.Dt PROGNAME section 127bbf21555SRichard Lowe\&.Os 128bbf21555SRichard Lowe\&.Sh NAME 129bbf21555SRichard Lowe\&.Nm progname 130bbf21555SRichard Lowe\&.Nd one line about what it does 131bbf21555SRichard Lowe\&.\e\(dq .Sh LIBRARY 132bbf21555SRichard Lowe\&.\e\(dq For sections 2, 3, and 9 only. 133bbf21555SRichard Lowe\&.Sh SYNOPSIS 134bbf21555SRichard Lowe\&.Nm progname 135bbf21555SRichard Lowe\&.Op Fl options 136bbf21555SRichard Lowe\&.Ar 137bbf21555SRichard Lowe\&.Sh DESCRIPTION 138bbf21555SRichard LoweThe 139bbf21555SRichard Lowe\&.Nm 140bbf21555SRichard Loweutility processes files ... 141bbf21555SRichard Lowe\&.\e\(dq .Sh IMPLEMENTATION NOTES 142bbf21555SRichard Lowe\&.\e\(dq .Sh RETURN VALUES 143bbf21555SRichard Lowe\&.\e\(dq For sections 2, 3, 7, and 9 only. 144bbf21555SRichard Lowe\&.\e\(dq .Sh CONTEXT 145bbf21555SRichard Lowe\&.\e\(dq For section 9 functions only. 146bbf21555SRichard Lowe\&.\e\(dq .Sh ENVIRONMENT 147bbf21555SRichard Lowe\&.\e\(dq For sections 1, 7, and 8. 148bbf21555SRichard Lowe\&.\e\(dq .Sh FILES 149bbf21555SRichard Lowe\&.\e\(dq .Sh EXIT STATUS 150bbf21555SRichard Lowe\&.\e\(dq For sections 1, 7, and 8. 151bbf21555SRichard Lowe\&.\e\(dq .Sh EXAMPLES 152bbf21555SRichard Lowe\&.\e\(dq .Sh DIAGNOSTICS 153bbf21555SRichard Lowe\&.\e\(dq .Sh ERRORS 154bbf21555SRichard Lowe\&.\e\(dq For sections 2, 3, 4, and 9 only. 155bbf21555SRichard Lowe\&.\e\(dq .Sh ARCHITECTURE 156bbf21555SRichard Lowe\&.\e\(dq .Sh CODE SET INDEPENDENCE 157bbf21555SRichard Lowe\&.\e\(dq For sections 1, 3, and 8 only. 158bbf21555SRichard Lowe\&.\e\(dq .Sh INTERFACE STABILITY 159bbf21555SRichard Lowe\&.\e\(dq .Sh MT-LEVEL 160bbf21555SRichard Lowe\&.\e\(dq For sections 2 and 3 only. 161bbf21555SRichard Lowe\&.\e\(dq .Sh SECURITY 162bbf21555SRichard Lowe\&.\e\(dq .Sh SEE ALSO 163bbf21555SRichard Lowe\&.\e\(dq .Xr foobar 1 164bbf21555SRichard Lowe\&.\e\(dq .Sh STANDARDS 165bbf21555SRichard Lowe\&.\e\(dq .Sh HISTORY 166bbf21555SRichard Lowe\&.\e\(dq .Sh AUTHORS 167bbf21555SRichard Lowe\&.\e\(dq .Sh CAVEATS 168bbf21555SRichard Lowe\&.\e\(dq .Sh BUGS 169bbf21555SRichard Lowe.Ed 170bbf21555SRichard Lowe.Pp 171bbf21555SRichard LoweThe sections in an 172bbf21555SRichard Lowe.Nm 173bbf21555SRichard Lowedocument are conventionally ordered as they appear above. 174bbf21555SRichard LoweSections should be composed as follows: 175bbf21555SRichard Lowe.Bl -ohang -offset Ds 176bbf21555SRichard Lowe.It Em NAME 177bbf21555SRichard LoweThe name(s) and a one line description of the documented material. 178bbf21555SRichard LoweThe syntax for this as follows: 179bbf21555SRichard Lowe.Bd -literal -offset indent 180bbf21555SRichard Lowe\&.Nm name0 , 181bbf21555SRichard Lowe\&.Nm name1 , 182bbf21555SRichard Lowe\&.Nm name2 183bbf21555SRichard Lowe\&.Nd a one line description 184bbf21555SRichard Lowe.Ed 185bbf21555SRichard Lowe.Pp 186bbf21555SRichard LoweMultiple 187bbf21555SRichard Lowe.Sq \&Nm 188bbf21555SRichard Lowenames should be separated by commas. 189bbf21555SRichard Lowe.Pp 190bbf21555SRichard LoweThe 191bbf21555SRichard Lowe.Ic \&Nm 192bbf21555SRichard Lowemacro(s) must precede the 193bbf21555SRichard Lowe.Ic \&Nd 194bbf21555SRichard Lowemacro. 195bbf21555SRichard Lowe.Pp 196bbf21555SRichard LoweSee 197bbf21555SRichard Lowe.Ic \&Nm 198bbf21555SRichard Loweand 199bbf21555SRichard Lowe.Ic \&Nd . 200bbf21555SRichard Lowe.It Em LIBRARY 201bbf21555SRichard LoweThe name of the library containing the documented material, which is 202bbf21555SRichard Loweassumed to be a function in a section 2, 3, or 9 manual. 203bbf21555SRichard LoweThe syntax for this is as follows: 204bbf21555SRichard Lowe.Bd -literal -offset indent 205bbf21555SRichard Lowe\&.Lb libarm 206bbf21555SRichard Lowe.Ed 207bbf21555SRichard Lowe.Pp 208bbf21555SRichard LoweSee 209bbf21555SRichard Lowe.Ic \&Lb . 210bbf21555SRichard Lowe.It Em SYNOPSIS 211bbf21555SRichard LoweDocuments the utility invocation syntax, function call syntax, or device 212bbf21555SRichard Loweconfiguration. 213bbf21555SRichard Lowe.Pp 214bbf21555SRichard LoweFor the first, utilities (sections 1 and 8), this is 215bbf21555SRichard Lowegenerally structured as follows: 216bbf21555SRichard Lowe.Bd -literal -offset indent 217bbf21555SRichard Lowe\&.Nm bar 218bbf21555SRichard Lowe\&.Op Fl v 219bbf21555SRichard Lowe\&.Op Fl o Ar file 220bbf21555SRichard Lowe\&.Op Ar 221bbf21555SRichard Lowe\&.Nm foo 222bbf21555SRichard Lowe\&.Op Fl v 223bbf21555SRichard Lowe\&.Op Fl o Ar file 224bbf21555SRichard Lowe\&.Op Ar 225bbf21555SRichard Lowe.Ed 226bbf21555SRichard Lowe.Pp 227bbf21555SRichard LoweCommands should be ordered alphabetically. 228bbf21555SRichard Lowe.Pp 229bbf21555SRichard LoweFor the second, function calls (sections 2, 3, 4I, 4P, 9): 230bbf21555SRichard Lowe.Bd -literal -offset indent 231bbf21555SRichard Lowe\&.In header.h 232bbf21555SRichard Lowe\&.Vt extern const char *global; 233bbf21555SRichard Lowe\&.Ft "char *" 234bbf21555SRichard Lowe\&.Fn foo "const char *src" 235bbf21555SRichard Lowe\&.Ft "char *" 236bbf21555SRichard Lowe\&.Fn bar "const char *src" 237bbf21555SRichard Lowe.Ed 238bbf21555SRichard Lowe.Pp 239bbf21555SRichard LoweOrdering of 240bbf21555SRichard Lowe.Ic \&In , 241bbf21555SRichard Lowe.Ic \&Vt , 242bbf21555SRichard Lowe.Ic \&Fn , 243bbf21555SRichard Loweand 244bbf21555SRichard Lowe.Ic \&Fo 245bbf21555SRichard Lowemacros should follow C header-file conventions. 246bbf21555SRichard Lowe.Pp 247bbf21555SRichard LoweAnd for the third, configurations (section 4D): 248bbf21555SRichard Lowe.Bd -literal -offset indent 249bbf21555SRichard Lowe\&.Pa /dev/device_node 250bbf21555SRichard Lowe.Ed 251bbf21555SRichard Lowe.Pp 252bbf21555SRichard LoweManuals not in these sections generally don't need a 253bbf21555SRichard Lowe.Em SYNOPSIS . 254bbf21555SRichard Lowe.Pp 255bbf21555SRichard LoweSome macros are displayed differently in the 256bbf21555SRichard Lowe.Em SYNOPSIS 257bbf21555SRichard Lowesection, particularly 258bbf21555SRichard Lowe.Ic \&Nm , 259bbf21555SRichard Lowe.Ic \&Cd , 260bbf21555SRichard Lowe.Ic \&Fd , 261bbf21555SRichard Lowe.Ic \&Fn , 262bbf21555SRichard Lowe.Ic \&Fo , 263bbf21555SRichard Lowe.Ic \&In , 264bbf21555SRichard Lowe.Ic \&Vt , 265bbf21555SRichard Loweand 266bbf21555SRichard Lowe.Ic \&Ft . 267bbf21555SRichard LoweAll of these macros are output on their own line. 268bbf21555SRichard LoweIf two such dissimilar macros are pairwise invoked (except for 269bbf21555SRichard Lowe.Ic \&Ft 270bbf21555SRichard Lowebefore 271bbf21555SRichard Lowe.Ic \&Fo 272bbf21555SRichard Loweor 273bbf21555SRichard Lowe.Ic \&Fn ) , 274bbf21555SRichard Lowethey are separated by a vertical space, unless in the case of 275bbf21555SRichard Lowe.Ic \&Fo , 276bbf21555SRichard Lowe.Ic \&Fn , 277bbf21555SRichard Loweand 278bbf21555SRichard Lowe.Ic \&Ft , 279bbf21555SRichard Lowewhich are always separated by vertical space. 280bbf21555SRichard Lowe.Pp 281bbf21555SRichard LoweWhen text and macros following an 282bbf21555SRichard Lowe.Ic \&Nm 283bbf21555SRichard Lowemacro starting an input line span multiple output lines, 284bbf21555SRichard Loweall output lines but the first will be indented to align 285bbf21555SRichard Lowewith the text immediately following the 286bbf21555SRichard Lowe.Ic \&Nm 287bbf21555SRichard Lowemacro, up to the next 288bbf21555SRichard Lowe.Ic \&Nm , 289bbf21555SRichard Lowe.Ic \&Sh , 290bbf21555SRichard Loweor 291bbf21555SRichard Lowe.Ic \&Ss 292bbf21555SRichard Lowemacro or the end of an enclosing block, whichever comes first. 293bbf21555SRichard Lowe.It Em DESCRIPTION 294bbf21555SRichard LoweThis begins with an expansion of the brief, one line description in 295bbf21555SRichard Lowe.Em NAME : 296bbf21555SRichard Lowe.Bd -literal -offset indent 297bbf21555SRichard LoweThe 298bbf21555SRichard Lowe\&.Nm 299bbf21555SRichard Loweutility does this, that, and the other. 300bbf21555SRichard Lowe.Ed 301bbf21555SRichard Lowe.Pp 302bbf21555SRichard LoweIt usually follows with a breakdown of the options (if documenting a 303bbf21555SRichard Lowecommand), such as: 304bbf21555SRichard Lowe.Bd -literal -offset indent 305bbf21555SRichard LoweThe options are as follows: 306bbf21555SRichard Lowe\&.Bl \-tag \-width Ds 307bbf21555SRichard Lowe\&.It Fl v 308bbf21555SRichard LowePrint verbose information. 309bbf21555SRichard Lowe\&.El 310bbf21555SRichard Lowe.Ed 311bbf21555SRichard Lowe.Pp 312bbf21555SRichard LoweList the options in alphabetical order, 313bbf21555SRichard Loweuppercase before lowercase for each letter and 314bbf21555SRichard Lowewith no regard to whether an option takes an argument. 315bbf21555SRichard LowePut digits in ascending order before all letter options. 316bbf21555SRichard Lowe.Pp 317bbf21555SRichard LoweManuals not documenting a command won't include the above fragment. 318bbf21555SRichard Lowe.Pp 319bbf21555SRichard LoweSince the 320bbf21555SRichard Lowe.Em DESCRIPTION 321bbf21555SRichard Lowesection usually contains most of the text of a manual, longer manuals 322bbf21555SRichard Loweoften use the 323bbf21555SRichard Lowe.Ic \&Ss 324bbf21555SRichard Lowemacro to form subsections. 325bbf21555SRichard LoweIn very long manuals, the 326bbf21555SRichard Lowe.Em DESCRIPTION 327bbf21555SRichard Lowemay be split into multiple sections, each started by an 328bbf21555SRichard Lowe.Ic \&Sh 329bbf21555SRichard Lowemacro followed by a non-standard section name, and each having 330bbf21555SRichard Loweseveral subsections, like in the present 331bbf21555SRichard Lowe.Nm 332bbf21555SRichard Lowemanual. 333bbf21555SRichard Lowe.It Em IMPLEMENTATION NOTES 334bbf21555SRichard LoweImplementation-specific notes should be kept here. 335bbf21555SRichard LoweThis is useful when implementing standard functions that may have side 336bbf21555SRichard Loweeffects or notable algorithmic implications. 337bbf21555SRichard Lowe.It Em RETURN VALUES 338bbf21555SRichard LoweThis section documents the 339bbf21555SRichard Lowereturn values of functions in sections 2, 3, and 9. 340bbf21555SRichard Lowe.Pp 341bbf21555SRichard LoweSee 342bbf21555SRichard Lowe.Ic \&Rv . 343bbf21555SRichard Lowe.It Em CONTEXT 344bbf21555SRichard LoweThis section lists the contexts in which functions can be called in section 9. 345bbf21555SRichard LoweThe contexts are user, kernel, or interrupt. 346bbf21555SRichard Lowe.It Em ENVIRONMENT 347bbf21555SRichard LoweLists the environment variables used by the utility, 348bbf21555SRichard Loweand explains the syntax and semantics of their values. 349bbf21555SRichard LoweThe 350bbf21555SRichard Lowe.Xr environ 7 351bbf21555SRichard Lowemanual provides examples of typical content and formatting. 352bbf21555SRichard Lowe.Pp 353bbf21555SRichard LoweSee 354bbf21555SRichard Lowe.Ic \&Ev . 355bbf21555SRichard Lowe.It Em FILES 356bbf21555SRichard LoweDocuments files used. 357bbf21555SRichard LoweIt's helpful to document both the file name and a short description of how 358bbf21555SRichard Lowethe file is used (created, modified, etc.). 359bbf21555SRichard Lowe.Pp 360bbf21555SRichard LoweSee 361bbf21555SRichard Lowe.Ic \&Pa . 362bbf21555SRichard Lowe.It Em EXIT STATUS 363bbf21555SRichard LoweThis section documents the 364bbf21555SRichard Lowecommand exit status for sections 1 and 8. 365bbf21555SRichard LoweHistorically, this information was described in 366bbf21555SRichard Lowe.Em DIAGNOSTICS , 367bbf21555SRichard Lowea practise that is now discouraged. 368bbf21555SRichard Lowe.Pp 369bbf21555SRichard LoweSee 370bbf21555SRichard Lowe.Ic \&Ex . 371bbf21555SRichard Lowe.It Em EXAMPLES 372bbf21555SRichard LoweExample usages. 373bbf21555SRichard LoweThis often contains snippets of well-formed, well-tested invocations. 374bbf21555SRichard LoweMake sure that examples work properly! 375bbf21555SRichard Lowe.It Em DIAGNOSTICS 376bbf21555SRichard LoweDocuments error and diagnostic messages displayed to the user or 377bbf21555SRichard Lowesent to logs. 378bbf21555SRichard LoweNote that exit status and return values should be documented in the 379bbf21555SRichard Lowe.Em EXIT STATUS 380bbf21555SRichard Loweand 381bbf21555SRichard Lowe.Em RETURN VALUES 382bbf21555SRichard Lowesections. 383bbf21555SRichard Lowe.Pp 384bbf21555SRichard LoweSee 385bbf21555SRichard Lowe.Ic \&Bl 386bbf21555SRichard Lowe.Fl diag . 387bbf21555SRichard Lowe.It Em ERRORS 388bbf21555SRichard LoweDocuments error handling in sections 2, 3, 7, and 9. 389bbf21555SRichard Lowe.Pp 390bbf21555SRichard LoweSee 391bbf21555SRichard Lowe.Ic \&Er . 392bbf21555SRichard Lowe.It Em ARCHITECTURE 393bbf21555SRichard LoweThis section is usually absent, but will be present when the 394bbf21555SRichard Loweinterface is specific to one or more architectures. 395bbf21555SRichard Lowe.It Em CODE SET INDEPENDENCE 396bbf21555SRichard LoweIndicates whether the interface operates correctly with various different 397bbf21555SRichard Lowecode sets. 398bbf21555SRichard LoweTrue independent code sets will support not only ASCII and Extended UNIX 399bbf21555SRichard LoweCodesets (EUC), but also other multi-byte encodings such as UTF-8 and GB2312. 400bbf21555SRichard Lowe.Pp 401bbf21555SRichard LoweGenerally there will be some limitations that are fairly standard. 402bbf21555SRichard LoweSee 403bbf21555SRichard Lowe.Xr standards 7 404bbf21555SRichard Lowefor more information about some of these. 405bbf21555SRichard LoweMost interfaces should support at least UTF-8 in addition to ASCII. 406bbf21555SRichard Lowe.It Em INTERFACE STABILITY 407bbf21555SRichard LoweIndicates the level of commitment to the interface. 408bbf21555SRichard LoweInterfaces can be described with in the following ways: 409bbf21555SRichard Lowe.Bl -tag -width Ds 410bbf21555SRichard Lowe.It Nm Standard 411bbf21555SRichard LoweIndicates that the interface is defined by one or more standards bodies. 412bbf21555SRichard LoweGenerally, changes to the interface will be carefully managed to conform 413bbf21555SRichard Loweto the relevant standards. 414bbf21555SRichard LoweThese interfaces are generally the most suitable for use in portable programs. 415bbf21555SRichard Lowe.It Nm Committed 416bbf21555SRichard LoweIndicates that the interface is intended to be preserved for the long-haul, and 417bbf21555SRichard Lowewill rarely, if ever change, and never without notification (barring 418bbf21555SRichard Loweextraordinary and extenuating circumstances). 419*c55633c3SPeter TribbleThese interfaces are preferred over other interfaces with the exception of 420bbf21555SRichard Lowe.Nm Standard 421bbf21555SRichard Loweinterfaces. 422bbf21555SRichard Lowe.It Nm Uncommitted 423bbf21555SRichard LoweIndicates that the interface may change. 424bbf21555SRichard LoweGenerally, changes to these interfaces should be infrequent, and some effort 425bbf21555SRichard Lowewill be made to address compatibility considerations when changing or removing 426bbf21555SRichard Lowesuch interfaces. 427bbf21555SRichard LoweHowever, there is no firm commitment to the preservation of the interface. 428bbf21555SRichard LoweMost often this is applied to interfaces where operational experience with the 429bbf21555SRichard Loweinterface is still limited and some need to change may be anticipated. 430bbf21555SRichard Lowe.Pp 431bbf21555SRichard LoweConsumers should expect to revalidate any 432bbf21555SRichard Lowe.Nm Uncommitted 433bbf21555SRichard Loweinterfaces when crossing release boundaries. 434bbf21555SRichard LoweProducts intended for use on many releases or intended to support compatibility 435bbf21555SRichard Lowewith future releases should avoid these interfaces. 436bbf21555SRichard Lowe.It Nm Volatile 437bbf21555SRichard LoweThe interface can change at any time for any reason. 438bbf21555SRichard LoweOften this relates to interfaces that are part of external software components 439bbf21555SRichard Lowethat are still evolving rapidly. 440bbf21555SRichard LoweConsumers should not expect that the interface (either binary or source level) 441bbf21555SRichard Lowewill be unchanged from one release to the next. 442bbf21555SRichard Lowe.It Nm Not-an-Interface 443bbf21555SRichard LoweDescribes something that is specifically not intended for programmatic 444bbf21555SRichard Loweconsumption. 445bbf21555SRichard LoweFor example, specific human-readable output, or the layout of graphical items on 446bbf21555SRichard Lowea user interface, may be described this way. 447bbf21555SRichard LoweGenerally programmatic alternatives to these will be available, and should be 448bbf21555SRichard Loweused when programmatic consumption is needed. 449bbf21555SRichard Lowe.It Nm Private 450bbf21555SRichard LoweThis is an internal interface. 451bbf21555SRichard LoweGenerally these interfaces should only be used within the project, and should 452bbf21555SRichard Lowenot be used by other programs or modules. 453bbf21555SRichard LoweThe interface can and will change without notice as the project needs, at any 454bbf21555SRichard Lowetime. 455bbf21555SRichard Lowe.Pp 456bbf21555SRichard LoweMost often, Private interfaces will lack any documentation whatsoever, and 457bbf21555SRichard Lowegenerally any undocumented interface can be assumed to be Private. 458bbf21555SRichard Lowe.It Nm Obsolete 459bbf21555SRichard LoweThe interface is not intended for use in new projects or programs, and may 460bbf21555SRichard Lowebe removed at a future date. 461bbf21555SRichard LoweThe 462bbf21555SRichard Lowe.Nm Obsolete 463bbf21555SRichard Loweword is a modifier that can 464bbf21555SRichard Lowebe applied to other commitment levels. 465bbf21555SRichard LoweFor example an 466bbf21555SRichard Lowe.Nm Obsolete Committed 467bbf21555SRichard Loweinterface is unlikely to be removed or changed, but nonetheless new use 468bbf21555SRichard Loweis discouraged (perhaps a better newer alternative is present). 469bbf21555SRichard Lowe.El 470bbf21555SRichard Lowe.It Em MT-LEVEL 471bbf21555SRichard LoweThis section describes considerations for the interface when used within 472bbf21555SRichard Loweprograms that use multiple threads. 473bbf21555SRichard LoweMore discussion of these considerations is made in the MT-Level section of 474bbf21555SRichard Lowe.Xr attributes 7 . 475bbf21555SRichard LoweThe interface can be described in the following ways. 476bbf21555SRichard Lowe.Bl -tag -width Ds 477bbf21555SRichard Lowe.It Nm Safe 478bbf21555SRichard LoweIndicates the interface is safe for use within multiple threads. 479bbf21555SRichard LoweThere may be additional caveats that apply, in which case those will be 480bbf21555SRichard Lowedescribed. 481bbf21555SRichard LoweNote that some interfaces have semantics which may affect other threads, but 482bbf21555SRichard Lowethese should be an intrinsic part of the interface rather than an unexpected 483bbf21555SRichard Loweside effect. 484bbf21555SRichard LoweFor example, closing a file in one thread will cause that file to be closed in 485bbf21555SRichard Loweall threads. 486bbf21555SRichard Lowe.It Nm Unsafe 487bbf21555SRichard LoweIndicates the interface is unsuitable for concurrent use within multiple 488bbf21555SRichard Lowethreads. 489bbf21555SRichard LoweA threaded application may still make use of the interface, but will be required 490bbf21555SRichard Loweto provide external synchronization means to ensure that only a single thread 491bbf21555SRichard Lowecalls the interface at a time. 492bbf21555SRichard Lowe.It Nm MT-Safe 493bbf21555SRichard LoweIndicates that the interface is not only safe for concurrent use, but is 494bbf21555SRichard Lowedesigned for such use. 495bbf21555SRichard LoweFor example, a 496bbf21555SRichard Lowe.Nm Safe 497bbf21555SRichard Loweinterface may make use of a global lock to provide safety, but at reduced 498bbf21555SRichard Loweinternal concurrency, whereas an 499bbf21555SRichard Lowe.Nm MT-Safe 500bbf21555SRichard Loweinterface will be designed to be efficient even when used concurrently. 501bbf21555SRichard Lowe.It Nm Async-Signal-Safe 502bbf21555SRichard LoweIndicates that the library is safe for use within a signal handler. 503bbf21555SRichard LoweAn 504bbf21555SRichard Lowe.Nm MT-Safe 505bbf21555SRichard Loweinterface can be made 506bbf21555SRichard Lowe.Nm Async-Signal-Safe 507bbf21555SRichard Loweby ensuring that it blocks signals when acquiring locks. 508bbf21555SRichard Lowe.It Nm Safe with Exceptions 509bbf21555SRichard LoweAs for 510bbf21555SRichard Lowe.Nm Safe 511bbf21555SRichard Lowebut with specific exceptions noted. 512bbf21555SRichard Lowe.It Nm MT-Safe with Exceptions 513bbf21555SRichard LoweAs for 514bbf21555SRichard Lowe.Nm MT-Safe 515bbf21555SRichard Lowebut with specific exceptions noted. 516bbf21555SRichard Lowe.El 517bbf21555SRichard Lowe.It Em SECURITY 518bbf21555SRichard LoweDocuments any security precautions that operators should consider. 519bbf21555SRichard Lowe.It Em SEE ALSO 520bbf21555SRichard LoweReferences other manuals with related topics. 521bbf21555SRichard LoweThis section should exist for most manuals. 522bbf21555SRichard LoweCross-references should conventionally be ordered first by section, then 523bbf21555SRichard Lowealphabetically (ignoring case). 524bbf21555SRichard Lowe.Pp 525bbf21555SRichard LoweReferences to other documentation concerning the topic of the manual page, 526bbf21555SRichard Lowefor example authoritative books or journal articles, may also be 527bbf21555SRichard Loweprovided in this section. 528bbf21555SRichard Lowe.Pp 529bbf21555SRichard LoweSee 530bbf21555SRichard Lowe.Ic \&Rs 531bbf21555SRichard Loweand 532bbf21555SRichard Lowe.Ic \&Xr . 533bbf21555SRichard Lowe.It Em STANDARDS 534bbf21555SRichard LoweReferences any standards implemented or used. 535bbf21555SRichard LoweIf not adhering to any standards, the 536bbf21555SRichard Lowe.Em HISTORY 537bbf21555SRichard Lowesection should be used instead. 538bbf21555SRichard Lowe.Pp 539bbf21555SRichard LoweSee 540bbf21555SRichard Lowe.Ic \&St . 541bbf21555SRichard Lowe.It Em HISTORY 542bbf21555SRichard LoweA brief history of the subject, including where it was first implemented, 543bbf21555SRichard Loweand when it was ported to or reimplemented for the operating system at hand. 544bbf21555SRichard Lowe.It Em AUTHORS 545bbf21555SRichard LoweCredits to the person or persons who wrote the code and/or documentation. 546bbf21555SRichard LoweAuthors should generally be noted by both name and email address. 547bbf21555SRichard Lowe.Pp 548bbf21555SRichard LoweSee 549bbf21555SRichard Lowe.Ic \&An . 550bbf21555SRichard Lowe.It Em CAVEATS 551bbf21555SRichard LoweCommon misuses and misunderstandings should be explained 552bbf21555SRichard Lowein this section. 553bbf21555SRichard Lowe.It Em BUGS 554bbf21555SRichard LoweKnown bugs, limitations, and work-arounds should be described 555bbf21555SRichard Lowein this section. 556bbf21555SRichard Lowe.El 557bbf21555SRichard Lowe.Sh MACRO OVERVIEW 558bbf21555SRichard LoweThis overview is sorted such that macros of similar purpose are listed 559bbf21555SRichard Lowetogether, to help find the best macro for any given purpose. 560bbf21555SRichard LoweDeprecated macros are not included in the overview, but can be found below 561bbf21555SRichard Lowein the alphabetical 562bbf21555SRichard Lowe.Sx MACRO REFERENCE . 563bbf21555SRichard Lowe.Ss Document preamble and NAME section macros 564bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 565bbf21555SRichard Lowe.It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year 566bbf21555SRichard Lowe.It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch 567bbf21555SRichard Lowe.It Ic \&Os Ta operating system version: Op Ar system Op Ar version 568bbf21555SRichard Lowe.It Ic \&Nm Ta document name (one argument) 569bbf21555SRichard Lowe.It Ic \&Nd Ta document description (one line) 570bbf21555SRichard Lowe.El 571bbf21555SRichard Lowe.Ss Sections and cross references 572bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 573bbf21555SRichard Lowe.It Ic \&Sh Ta section header (one line) 574bbf21555SRichard Lowe.It Ic \&Ss Ta subsection header (one line) 575bbf21555SRichard Lowe.It Ic \&Sx Ta internal cross reference to a section or subsection 576bbf21555SRichard Lowe.It Ic \&Xr Ta cross reference to another manual page: Ar name section 577bbf21555SRichard Lowe.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments 578bbf21555SRichard Lowe.It Ic \&Pp Ta start a text paragraph (no arguments) 579bbf21555SRichard Lowe.El 580bbf21555SRichard Lowe.Ss Displays and lists 581bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 582bbf21555SRichard Lowe.It Ic \&Bd , \&Ed Ta display block: 583bbf21555SRichard Lowe.Fl Ar type 584bbf21555SRichard Lowe.Op Fl offset Ar width 585bbf21555SRichard Lowe.Op Fl compact 586bbf21555SRichard Lowe.It Ic \&D1 Ta indented display (one line) 587bbf21555SRichard Lowe.It Ic \&Dl Ta indented literal display (one line) 588bbf21555SRichard Lowe.It Ic \&Ql Ta in-line literal display: Ql text 589bbf21555SRichard Lowe.It Ic \&Bl , \&El Ta list block: 590bbf21555SRichard Lowe.Fl Ar type 591bbf21555SRichard Lowe.Op Fl width Ar val 592bbf21555SRichard Lowe.Op Fl offset Ar val 593bbf21555SRichard Lowe.Op Fl compact 594bbf21555SRichard Lowe.It Ic \&It Ta list item (syntax depends on Fl Ar type ) 595bbf21555SRichard Lowe.It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists 596bbf21555SRichard Lowe.It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references) 597bbf21555SRichard Lowe.El 598bbf21555SRichard Lowe.Ss Spacing control 599bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 600bbf21555SRichard Lowe.It Ic \&Pf Ta prefix, no following horizontal space (one argument) 601bbf21555SRichard Lowe.It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments) 602bbf21555SRichard Lowe.It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments) 603bbf21555SRichard Lowe.It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off 604bbf21555SRichard Lowe.It Ic \&Bk , \&Ek Ta keep block: Fl words 605bbf21555SRichard Lowe.El 606bbf21555SRichard Lowe.Ss Semantic markup for command line utilities 607bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 608bbf21555SRichard Lowe.It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility 609bbf21555SRichard Lowe.It Ic \&Fl Ta command line options (flags) (>=0 arguments) 610bbf21555SRichard Lowe.It Ic \&Cm Ta command modifier (>0 arguments) 611bbf21555SRichard Lowe.It Ic \&Ar Ta command arguments (>=0 arguments) 612bbf21555SRichard Lowe.It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) 613bbf21555SRichard Lowe.It Ic \&Ic Ta internal or interactive command (>0 arguments) 614bbf21555SRichard Lowe.It Ic \&Ev Ta environmental variable (>0 arguments) 615bbf21555SRichard Lowe.It Ic \&Pa Ta file system path (>=0 arguments) 616bbf21555SRichard Lowe.El 617bbf21555SRichard Lowe.Ss Semantic markup for function libraries 618bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 619bbf21555SRichard Lowe.It Ic \&Lb Ta function library (one argument) 620bbf21555SRichard Lowe.It Ic \&In Ta include file (one argument) 621bbf21555SRichard Lowe.It Ic \&Fd Ta other preprocessor directive (>0 arguments) 622bbf21555SRichard Lowe.It Ic \&Ft Ta function type (>0 arguments) 623bbf21555SRichard Lowe.It Ic \&Fo , \&Fc Ta function block: Ar funcname 624bbf21555SRichard Lowe.It Ic \&Fn Ta function name: Ar funcname Op Ar argument ... 625bbf21555SRichard Lowe.It Ic \&Fa Ta function argument (>0 arguments) 626bbf21555SRichard Lowe.It Ic \&Vt Ta variable type (>0 arguments) 627bbf21555SRichard Lowe.It Ic \&Va Ta variable name (>0 arguments) 628bbf21555SRichard Lowe.It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments) 629bbf21555SRichard Lowe.It Ic \&Er Ta error constant (>0 arguments) 630bbf21555SRichard Lowe.It Ic \&Ev Ta environmental variable (>0 arguments) 631bbf21555SRichard Lowe.El 632bbf21555SRichard Lowe.Ss Various semantic markup 633bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 634bbf21555SRichard Lowe.It Ic \&An Ta author name (>0 arguments) 635bbf21555SRichard Lowe.It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name 636bbf21555SRichard Lowe.It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain 637bbf21555SRichard Lowe.It Ic \&Cd Ta kernel configuration declaration (>0 arguments) 638bbf21555SRichard Lowe.It Ic \&Ad Ta memory address (>0 arguments) 639bbf21555SRichard Lowe.It Ic \&Ms Ta mathematical symbol (>0 arguments) 640bbf21555SRichard Lowe.El 641bbf21555SRichard Lowe.Ss Physical markup 642bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 643bbf21555SRichard Lowe.It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments) 644bbf21555SRichard Lowe.It Ic \&Sy Ta boldface font (symbolic) (>0 arguments) 645bbf21555SRichard Lowe.It Ic \&No Ta return to roman font (normal) (>0 arguments) 646bbf21555SRichard Lowe.It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy 647bbf21555SRichard Lowe.El 648bbf21555SRichard Lowe.Ss Physical enclosures 649bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 650bbf21555SRichard Lowe.It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text 651bbf21555SRichard Lowe.It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text 652bbf21555SRichard Lowe.It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text 653bbf21555SRichard Lowe.It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text 654bbf21555SRichard Lowe.It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text 655bbf21555SRichard Lowe.It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text 656bbf21555SRichard Lowe.It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text 657bbf21555SRichard Lowe.It Ic \&Eo , \&Ec Ta generic enclosure 658bbf21555SRichard Lowe.El 659bbf21555SRichard Lowe.Ss Text production 660bbf21555SRichard Lowe.Bl -column "Brq, Bro, Brc" description 661bbf21555SRichard Lowe.It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ... 662bbf21555SRichard Lowe.It Ic \&Rv Fl std Ta standard function return values: Op Ar function ... 663bbf21555SRichard Lowe.It Ic \&St Ta reference to a standards document (one argument) 664bbf21555SRichard Lowe.It Ic \&At Ta At 665bbf21555SRichard Lowe.It Ic \&Bx Ta Bx 666bbf21555SRichard Lowe.It Ic \&Bsx Ta Bsx 667bbf21555SRichard Lowe.It Ic \&Nx Ta Nx 668bbf21555SRichard Lowe.It Ic \&Fx Ta Fx 669bbf21555SRichard Lowe.It Ic \&Ox Ta Ox 670bbf21555SRichard Lowe.It Ic \&Dx Ta Dx 671bbf21555SRichard Lowe.El 672bbf21555SRichard Lowe.Sh MACRO REFERENCE 673bbf21555SRichard LoweThis section is a canonical reference of all macros, arranged 674bbf21555SRichard Lowealphabetically. 675bbf21555SRichard LoweFor the scoping of individual macros, see 676bbf21555SRichard Lowe.Sx MACRO SYNTAX . 677bbf21555SRichard Lowe.Bl -tag -width 3n 678bbf21555SRichard Lowe.It Ic \&%A Ar first_name ... last_name 679bbf21555SRichard LoweAuthor name of an 680bbf21555SRichard Lowe.Ic \&Rs 681bbf21555SRichard Loweblock. 682bbf21555SRichard LoweMultiple authors should each be accorded their own 683bbf21555SRichard Lowe.Ic \%%A 684bbf21555SRichard Loweline. 685bbf21555SRichard LoweAuthor names should be ordered with full or abbreviated forename(s) 686bbf21555SRichard Lowefirst, then full surname. 687bbf21555SRichard Lowe.It Ic \&%B Ar title 688bbf21555SRichard LoweBook title of an 689bbf21555SRichard Lowe.Ic \&Rs 690bbf21555SRichard Loweblock. 691bbf21555SRichard LoweThis macro may also be used in a non-bibliographic context when 692bbf21555SRichard Lowereferring to book titles. 693bbf21555SRichard Lowe.It Ic \&%C Ar location 694bbf21555SRichard LowePublication city or location of an 695bbf21555SRichard Lowe.Ic \&Rs 696bbf21555SRichard Loweblock. 697bbf21555SRichard Lowe.It Ic \&%D Oo Ar month day , Oc Ar year 698bbf21555SRichard LowePublication date of an 699bbf21555SRichard Lowe.Ic \&Rs 700bbf21555SRichard Loweblock. 701bbf21555SRichard LoweProvide the full English name of the 702bbf21555SRichard Lowe.Ar month 703bbf21555SRichard Loweand all four digits of the 704bbf21555SRichard Lowe.Ar year . 705bbf21555SRichard Lowe.It Ic \&%I Ar name 706bbf21555SRichard LowePublisher or issuer name of an 707bbf21555SRichard Lowe.Ic \&Rs 708bbf21555SRichard Loweblock. 709bbf21555SRichard Lowe.It Ic \&%J Ar name 710bbf21555SRichard LoweJournal name of an 711bbf21555SRichard Lowe.Ic \&Rs 712bbf21555SRichard Loweblock. 713bbf21555SRichard Lowe.It Ic \&%N Ar number 714bbf21555SRichard LoweIssue number (usually for journals) of an 715bbf21555SRichard Lowe.Ic \&Rs 716bbf21555SRichard Loweblock. 717bbf21555SRichard Lowe.It Ic \&%O Ar line 718bbf21555SRichard LoweOptional information of an 719bbf21555SRichard Lowe.Ic \&Rs 720bbf21555SRichard Loweblock. 721bbf21555SRichard Lowe.It Ic \&%P Ar number 722bbf21555SRichard LoweBook or journal page number of an 723bbf21555SRichard Lowe.Ic \&Rs 724bbf21555SRichard Loweblock. 725bbf21555SRichard LoweConventionally, the argument starts with 726bbf21555SRichard Lowe.Ql p.\& 727bbf21555SRichard Lowefor a single page or 728bbf21555SRichard Lowe.Ql pp.\& 729bbf21555SRichard Lowefor a range of pages, for example: 730bbf21555SRichard Lowe.Pp 731bbf21555SRichard Lowe.Dl .%P pp. 42\e(en47 732bbf21555SRichard Lowe.It Ic \&%Q Ar name 733bbf21555SRichard LoweInstitutional author (school, government, etc.) of an 734bbf21555SRichard Lowe.Ic \&Rs 735bbf21555SRichard Loweblock. 736bbf21555SRichard LoweMultiple institutional authors should each be accorded their own 737bbf21555SRichard Lowe.Ic \&%Q 738bbf21555SRichard Loweline. 739bbf21555SRichard Lowe.It Ic \&%R Ar name 740bbf21555SRichard LoweTechnical report name of an 741bbf21555SRichard Lowe.Ic \&Rs 742bbf21555SRichard Loweblock. 743bbf21555SRichard Lowe.It Ic \&%T Ar title 744bbf21555SRichard LoweArticle title of an 745bbf21555SRichard Lowe.Ic \&Rs 746bbf21555SRichard Loweblock. 747bbf21555SRichard LoweThis macro may also be used in a non-bibliographical context when 748bbf21555SRichard Lowereferring to article titles. 749bbf21555SRichard Lowe.It Ic \&%U Ar protocol Ns :// Ns Ar path 750bbf21555SRichard LoweURI of reference document. 751bbf21555SRichard Lowe.It Ic \&%V Ar number 752bbf21555SRichard LoweVolume number of an 753bbf21555SRichard Lowe.Ic \&Rs 754bbf21555SRichard Loweblock. 755bbf21555SRichard Lowe.It Ic \&Ac 756bbf21555SRichard LoweClose an 757bbf21555SRichard Lowe.Ic \&Ao 758bbf21555SRichard Loweblock. 759bbf21555SRichard LoweDoes not have any tail arguments. 760bbf21555SRichard Lowe.Tg Ad 761bbf21555SRichard Lowe.It Ic \&Ad Ar address 762bbf21555SRichard LoweMemory address. 763bbf21555SRichard LoweDo not use this for postal addresses. 764bbf21555SRichard Lowe.Pp 765bbf21555SRichard LoweExamples: 766bbf21555SRichard Lowe.Dl \&.Ad [0,$] 767bbf21555SRichard Lowe.Dl \&.Ad 0x00000000 768bbf21555SRichard Lowe.Tg An 769bbf21555SRichard Lowe.It Ic \&An Fl split | nosplit | Ar first_name ... last_name 770bbf21555SRichard LoweAuthor name. 771bbf21555SRichard LoweCan be used both for the authors of the program, function, or driver 772bbf21555SRichard Lowedocumented in the manual, or for the authors of the manual itself. 773bbf21555SRichard LoweRequires either the name of an author or one of the following arguments: 774bbf21555SRichard Lowe.Pp 775bbf21555SRichard Lowe.Bl -tag -width "-nosplitX" -offset indent -compact 776bbf21555SRichard Lowe.It Fl split 777bbf21555SRichard LoweStart a new output line before each subsequent invocation of 778bbf21555SRichard Lowe.Ic \&An . 779bbf21555SRichard Lowe.It Fl nosplit 780bbf21555SRichard LoweThe opposite of 781bbf21555SRichard Lowe.Fl split . 782bbf21555SRichard Lowe.El 783bbf21555SRichard Lowe.Pp 784bbf21555SRichard LoweThe default is 785bbf21555SRichard Lowe.Fl nosplit . 786bbf21555SRichard LoweThe effect of selecting either of the 787bbf21555SRichard Lowe.Fl split 788bbf21555SRichard Lowemodes ends at the beginning of the 789bbf21555SRichard Lowe.Em AUTHORS 790bbf21555SRichard Lowesection. 791bbf21555SRichard LoweIn the 792bbf21555SRichard Lowe.Em AUTHORS 793bbf21555SRichard Lowesection, the default is 794bbf21555SRichard Lowe.Fl nosplit 795bbf21555SRichard Lowefor the first author listing and 796bbf21555SRichard Lowe.Fl split 797bbf21555SRichard Lowefor all other author listings. 798bbf21555SRichard Lowe.Pp 799bbf21555SRichard LoweExamples: 800bbf21555SRichard Lowe.Dl \&.An -nosplit 801bbf21555SRichard Lowe.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 802bbf21555SRichard Lowe.It Ic \&Ao Ar block 803bbf21555SRichard LoweBegin a block enclosed by angle brackets. 804bbf21555SRichard LoweDoes not have any head arguments. 805bbf21555SRichard LoweThis macro is almost never useful. 806bbf21555SRichard LoweSee 807bbf21555SRichard Lowe.Ic \&Aq 808bbf21555SRichard Lowefor more details. 809bbf21555SRichard Lowe.Tg Ap 810bbf21555SRichard Lowe.It Ic \&Ap 811bbf21555SRichard LoweInserts an apostrophe without any surrounding whitespace. 812bbf21555SRichard LoweThis is generally used as a grammatical device when referring to the verb 813bbf21555SRichard Loweform of a function. 814bbf21555SRichard Lowe.Pp 815bbf21555SRichard LoweExamples: 816bbf21555SRichard Lowe.Dl \&.Fn execve \&Ap d 817bbf21555SRichard Lowe.Tg Aq 818bbf21555SRichard Lowe.It Ic \&Aq Ar line 819bbf21555SRichard LoweEnclose the rest of the input line in angle brackets. 820bbf21555SRichard LoweThe only important use case is for email addresses. 821bbf21555SRichard LoweSee 822bbf21555SRichard Lowe.Ic \&Mt 823bbf21555SRichard Lowefor an example. 824bbf21555SRichard Lowe.Pp 825bbf21555SRichard LoweOccasionally, it is used for names of characters and keys, for example: 826bbf21555SRichard Lowe.Bd -literal -offset indent 827bbf21555SRichard LowePress the 828bbf21555SRichard Lowe\&.Aq escape 829bbf21555SRichard Lowekey to ... 830bbf21555SRichard Lowe.Ed 831bbf21555SRichard Lowe.Pp 832bbf21555SRichard LoweFor URIs, use 833bbf21555SRichard Lowe.Ic \&Lk 834bbf21555SRichard Loweinstead, and 835bbf21555SRichard Lowe.Ic \&In 836bbf21555SRichard Lowefor 837bbf21555SRichard Lowe.Dq #include 838bbf21555SRichard Lowedirectives. 839bbf21555SRichard LoweNever wrap 840bbf21555SRichard Lowe.Ic \&Ar 841bbf21555SRichard Lowein 842bbf21555SRichard Lowe.Ic \&Aq . 843bbf21555SRichard Lowe.Pp 844bbf21555SRichard LoweSince 845bbf21555SRichard Lowe.Ic \&Aq 846bbf21555SRichard Loweusually renders with non-ASCII characters in non-ASCII output modes, 847bbf21555SRichard Lowedo not use it where the ASCII characters 848bbf21555SRichard Lowe.Sq < 849bbf21555SRichard Loweand 850bbf21555SRichard Lowe.Sq > 851bbf21555SRichard Loweare required as syntax elements. 852bbf21555SRichard LoweInstead, use these characters directly in such cases, combining them 853bbf21555SRichard Lowewith the macros 854bbf21555SRichard Lowe.Ic \&Pf , 855bbf21555SRichard Lowe.Ic \&Ns , 856bbf21555SRichard Loweor 857bbf21555SRichard Lowe.Ic \&Eo 858bbf21555SRichard Loweas needed. 859bbf21555SRichard Lowe.Pp 860bbf21555SRichard LoweSee also 861bbf21555SRichard Lowe.Ic \&Ao . 862bbf21555SRichard Lowe.Tg Ar 863bbf21555SRichard Lowe.It Ic \&Ar Op Ar placeholder ... 864bbf21555SRichard LoweCommand arguments. 865bbf21555SRichard LoweIf an argument is not provided, the string 866bbf21555SRichard Lowe.Dq file ...\& 867bbf21555SRichard Loweis used as a default. 868bbf21555SRichard Lowe.Pp 869bbf21555SRichard LoweExamples: 870bbf21555SRichard Lowe.Dl ".Fl o Ar file" 871bbf21555SRichard Lowe.Dl ".Ar" 872bbf21555SRichard Lowe.Dl ".Ar arg1 , arg2 ." 873bbf21555SRichard Lowe.Pp 874bbf21555SRichard LoweThe arguments to the 875bbf21555SRichard Lowe.Ic \&Ar 876bbf21555SRichard Lowemacro are names and placeholders for command arguments; 877bbf21555SRichard Lowefor fixed strings to be passed verbatim as arguments, use 878bbf21555SRichard Lowe.Ic \&Fl 879bbf21555SRichard Loweor 880bbf21555SRichard Lowe.Ic \&Cm . 881bbf21555SRichard Lowe.Tg At 882bbf21555SRichard Lowe.It Ic \&At Op Ar version 883bbf21555SRichard LoweFormats an 884bbf21555SRichard Lowe.At 885bbf21555SRichard Loweversion. 886bbf21555SRichard LoweAccepts one optional argument: 887bbf21555SRichard Lowe.Pp 888bbf21555SRichard Lowe.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact 889bbf21555SRichard Lowe.It Cm v[1-7] | 32v 890bbf21555SRichard LoweA version of 891bbf21555SRichard Lowe.At . 892bbf21555SRichard Lowe.It Cm III 893bbf21555SRichard Lowe.At III . 894bbf21555SRichard Lowe.It Cm V | V.[1-4] 895bbf21555SRichard LoweA version of 896bbf21555SRichard Lowe.At V . 897bbf21555SRichard Lowe.El 898bbf21555SRichard Lowe.Pp 899bbf21555SRichard LoweNote that these arguments do not begin with a hyphen. 900bbf21555SRichard Lowe.Pp 901bbf21555SRichard LoweExamples: 902bbf21555SRichard Lowe.Dl \&.At 903bbf21555SRichard Lowe.Dl \&.At III 904bbf21555SRichard Lowe.Dl \&.At V.1 905bbf21555SRichard Lowe.Pp 906bbf21555SRichard LoweSee also 907bbf21555SRichard Lowe.Ic \&Bsx , 908bbf21555SRichard Lowe.Ic \&Bx , 909bbf21555SRichard Lowe.Ic \&Dx , 910bbf21555SRichard Lowe.Ic \&Fx , 911bbf21555SRichard Lowe.Ic \&Nx , 912bbf21555SRichard Loweand 913bbf21555SRichard Lowe.Ic \&Ox . 914bbf21555SRichard Lowe.It Ic \&Bc 915bbf21555SRichard LoweClose a 916bbf21555SRichard Lowe.Ic \&Bo 917bbf21555SRichard Loweblock. 918bbf21555SRichard LoweDoes not have any tail arguments. 919bbf21555SRichard Lowe.Tg Bd 920bbf21555SRichard Lowe.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact 921bbf21555SRichard LoweBegin a display block. 922bbf21555SRichard LoweDisplay blocks are used to select a different indentation and 923bbf21555SRichard Lowejustification than the one used by the surrounding text. 924bbf21555SRichard LoweThey may contain both macro lines and text lines. 925bbf21555SRichard LoweBy default, a display block is preceded by a vertical space. 926bbf21555SRichard Lowe.Pp 927bbf21555SRichard LoweThe 928bbf21555SRichard Lowe.Ar type 929bbf21555SRichard Lowemust be one of the following: 930bbf21555SRichard Lowe.Bl -tag -width 13n -offset indent 931bbf21555SRichard Lowe.It Fl centered 932bbf21555SRichard LoweProduce one output line from each input line, and center-justify each line. 933bbf21555SRichard LoweUsing this display type is not recommended; many 934bbf21555SRichard Lowe.Nm 935bbf21555SRichard Loweimplementations render it poorly. 936bbf21555SRichard Lowe.It Fl filled 937bbf21555SRichard LoweChange the positions of line breaks to fill each line, and left- and 938bbf21555SRichard Loweright-justify the resulting block. 939bbf21555SRichard Lowe.It Fl literal 940bbf21555SRichard LoweProduce one output line from each input line, 941bbf21555SRichard Loweand do not justify the block at all. 942bbf21555SRichard LowePreserve white space as it appears in the input. 943bbf21555SRichard LoweAlways use a constant-width font. 944bbf21555SRichard LoweUse this for displaying source code. 945bbf21555SRichard Lowe.It Fl ragged 946bbf21555SRichard LoweChange the positions of line breaks to fill each line, and left-justify 947bbf21555SRichard Lowethe resulting block. 948bbf21555SRichard Lowe.It Fl unfilled 949bbf21555SRichard LoweThe same as 950bbf21555SRichard Lowe.Fl literal , 951bbf21555SRichard Lowebut using the same font as for normal text, which is a variable width font 952bbf21555SRichard Loweif supported by the output device. 953bbf21555SRichard Lowe.El 954bbf21555SRichard Lowe.Pp 955bbf21555SRichard LoweThe 956bbf21555SRichard Lowe.Ar type 957bbf21555SRichard Lowemust be provided first. 958bbf21555SRichard LoweAdditional arguments may follow: 959bbf21555SRichard Lowe.Bl -tag -width 13n -offset indent 960bbf21555SRichard Lowe.It Fl offset Ar width 961bbf21555SRichard LoweIndent the display by the 962bbf21555SRichard Lowe.Ar width , 963bbf21555SRichard Lowewhich may be one of the following: 964bbf21555SRichard Lowe.Bl -item 965bbf21555SRichard Lowe.It 966bbf21555SRichard LoweOne of the pre-defined strings 967bbf21555SRichard Lowe.Cm indent , 968bbf21555SRichard Lowethe width of a standard indentation (six constant width characters); 969bbf21555SRichard Lowe.Cm indent-two , 970bbf21555SRichard Lowetwice 971bbf21555SRichard Lowe.Cm indent ; 972bbf21555SRichard Lowe.Cm left , 973bbf21555SRichard Lowewhich has no effect; 974bbf21555SRichard Lowe.Cm right , 975bbf21555SRichard Lowewhich justifies to the right margin; or 976bbf21555SRichard Lowe.Cm center , 977bbf21555SRichard Lowewhich aligns around an imagined center axis. 978bbf21555SRichard Lowe.It 979bbf21555SRichard LoweA macro invocation, which selects a predefined width 980bbf21555SRichard Loweassociated with that macro. 981bbf21555SRichard LoweThe most popular is the imaginary macro 982bbf21555SRichard Lowe.Ar \&Ds , 983bbf21555SRichard Lowewhich resolves to 984bbf21555SRichard Lowe.Sy 6n . 985bbf21555SRichard Lowe.It 986bbf21555SRichard LoweA scaling width as described in 987bbf21555SRichard Lowe.Xr mandoc_roff 7 . 988bbf21555SRichard Lowe.It 989bbf21555SRichard LoweAn arbitrary string, which indents by the length of this string. 990bbf21555SRichard Lowe.El 991bbf21555SRichard Lowe.Pp 992bbf21555SRichard LoweWhen the argument is missing, 993bbf21555SRichard Lowe.Fl offset 994bbf21555SRichard Loweis ignored. 995bbf21555SRichard Lowe.It Fl compact 996bbf21555SRichard LoweDo not assert vertical space before the display. 997bbf21555SRichard Lowe.El 998bbf21555SRichard Lowe.Pp 999bbf21555SRichard LoweExamples: 1000bbf21555SRichard Lowe.Bd -literal -offset indent 1001bbf21555SRichard Lowe\&.Bd \-literal \-offset indent \-compact 1002bbf21555SRichard Lowe Hello world. 1003bbf21555SRichard Lowe\&.Ed 1004bbf21555SRichard Lowe.Ed 1005bbf21555SRichard Lowe.Pp 1006bbf21555SRichard LoweSee also 1007bbf21555SRichard Lowe.Ic \&D1 1008bbf21555SRichard Loweand 1009bbf21555SRichard Lowe.Ic \&Dl . 1010bbf21555SRichard Lowe.Tg Bf 1011bbf21555SRichard Lowe.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy 1012bbf21555SRichard LoweChange the font mode for a scoped block of text. 1013bbf21555SRichard LoweThe 1014bbf21555SRichard Lowe.Fl emphasis 1015bbf21555SRichard Loweand 1016bbf21555SRichard Lowe.Cm \&Em 1017bbf21555SRichard Loweargument are equivalent, as are 1018bbf21555SRichard Lowe.Fl symbolic 1019bbf21555SRichard Loweand 1020bbf21555SRichard Lowe.Cm \&Sy , 1021bbf21555SRichard Loweand 1022bbf21555SRichard Lowe.Fl literal 1023bbf21555SRichard Loweand 1024bbf21555SRichard Lowe.Cm \&Li . 1025bbf21555SRichard LoweWithout an argument, this macro does nothing. 1026bbf21555SRichard LoweThe font mode continues until broken by a new font mode in a nested 1027bbf21555SRichard Lowescope or 1028bbf21555SRichard Lowe.Ic \&Ef 1029bbf21555SRichard Loweis encountered. 1030bbf21555SRichard Lowe.Pp 1031bbf21555SRichard LoweSee also 1032bbf21555SRichard Lowe.Ic \&Li , 1033bbf21555SRichard Lowe.Ic \&Ef , 1034bbf21555SRichard Lowe.Ic \&Em , 1035bbf21555SRichard Loweand 1036bbf21555SRichard Lowe.Ic \&Sy . 1037bbf21555SRichard Lowe.Tg Bk 1038bbf21555SRichard Lowe.It Ic \&Bk Fl words 1039bbf21555SRichard LoweFor each macro, keep its output together on the same output line, 1040bbf21555SRichard Loweuntil the end of the macro or the end of the input line is reached, 1041bbf21555SRichard Lowewhichever comes first. 1042bbf21555SRichard LoweLine breaks in text lines are unaffected. 1043bbf21555SRichard Lowe.Pp 1044bbf21555SRichard LoweThe 1045bbf21555SRichard Lowe.Fl words 1046bbf21555SRichard Loweargument is required; additional arguments are ignored. 1047bbf21555SRichard Lowe.Pp 1048bbf21555SRichard LoweThe following example will not break within each 1049bbf21555SRichard Lowe.Ic \&Op 1050bbf21555SRichard Lowemacro line: 1051bbf21555SRichard Lowe.Bd -literal -offset indent 1052bbf21555SRichard Lowe\&.Bk \-words 1053bbf21555SRichard Lowe\&.Op Fl f Ar flags 1054bbf21555SRichard Lowe\&.Op Fl o Ar output 1055bbf21555SRichard Lowe\&.Ek 1056bbf21555SRichard Lowe.Ed 1057bbf21555SRichard Lowe.Pp 1058bbf21555SRichard LoweBe careful in using over-long lines within a keep block! 1059bbf21555SRichard LoweDoing so will clobber the right margin. 1060bbf21555SRichard Lowe.Tg Bl 1061bbf21555SRichard Lowe.It Xo 1062bbf21555SRichard Lowe.Ic \&Bl 1063bbf21555SRichard Lowe.Fl Ns Ar type 1064bbf21555SRichard Lowe.Op Fl width Ar val 1065bbf21555SRichard Lowe.Op Fl offset Ar val 1066bbf21555SRichard Lowe.Op Fl compact 1067bbf21555SRichard Lowe.Op Ar col ... 1068bbf21555SRichard Lowe.Xc 1069bbf21555SRichard LoweBegin a list. 1070bbf21555SRichard LoweLists consist of items specified using the 1071bbf21555SRichard Lowe.Ic \&It 1072bbf21555SRichard Lowemacro, containing a head or a body or both. 1073bbf21555SRichard Lowe.Pp 1074bbf21555SRichard LoweThe list 1075bbf21555SRichard Lowe.Ar type 1076bbf21555SRichard Loweis mandatory and must be specified first. 1077bbf21555SRichard LoweThe 1078bbf21555SRichard Lowe.Fl width 1079bbf21555SRichard Loweand 1080bbf21555SRichard Lowe.Fl offset 1081bbf21555SRichard Lowearguments accept macro names as described for 1082bbf21555SRichard Lowe.Ic \&Bd 1083bbf21555SRichard Lowe.Fl offset , 1084bbf21555SRichard Lowescaling widths as described in 1085bbf21555SRichard Lowe.Xr mandoc_roff 7 , 1086bbf21555SRichard Loweor use the length of the given string. 1087bbf21555SRichard LoweThe 1088bbf21555SRichard Lowe.Fl offset 1089bbf21555SRichard Loweis a global indentation for the whole list, affecting both item heads 1090bbf21555SRichard Loweand bodies. 1091bbf21555SRichard LoweFor those list types supporting it, the 1092bbf21555SRichard Lowe.Fl width 1093bbf21555SRichard Loweargument requests an additional indentation of item bodies, 1094bbf21555SRichard Loweto be added to the 1095bbf21555SRichard Lowe.Fl offset . 1096bbf21555SRichard LoweUnless the 1097bbf21555SRichard Lowe.Fl compact 1098bbf21555SRichard Loweargument is specified, list entries are separated by vertical space. 1099bbf21555SRichard Lowe.Pp 1100bbf21555SRichard LoweA list must specify one of the following list types: 1101bbf21555SRichard Lowe.Bl -tag -width 12n -offset indent 1102bbf21555SRichard Lowe.It Fl bullet 1103bbf21555SRichard LoweNo item heads can be specified, but a bullet will be printed at the head 1104bbf21555SRichard Loweof each item. 1105bbf21555SRichard LoweItem bodies start on the same output line as the bullet 1106bbf21555SRichard Loweand are indented according to the 1107bbf21555SRichard Lowe.Fl width 1108bbf21555SRichard Loweargument. 1109bbf21555SRichard Lowe.It Fl column 1110bbf21555SRichard LoweA columnated list. 1111bbf21555SRichard LoweThe 1112bbf21555SRichard Lowe.Fl width 1113bbf21555SRichard Loweargument has no effect; instead, the string length of each argument 1114bbf21555SRichard Lowespecifies the width of one column. 1115bbf21555SRichard LoweIf the first line of the body of a 1116bbf21555SRichard Lowe.Fl column 1117bbf21555SRichard Lowelist is not an 1118bbf21555SRichard Lowe.Ic \&It 1119bbf21555SRichard Lowemacro line, 1120bbf21555SRichard Lowe.Ic \&It 1121bbf21555SRichard Lowecontexts spanning one input line each are implied until an 1122bbf21555SRichard Lowe.Ic \&It 1123bbf21555SRichard Lowemacro line is encountered, at which point items start being interpreted as 1124bbf21555SRichard Lowedescribed in the 1125bbf21555SRichard Lowe.Ic \&It 1126bbf21555SRichard Lowedocumentation. 1127bbf21555SRichard Lowe.It Fl dash 1128bbf21555SRichard LoweLike 1129bbf21555SRichard Lowe.Fl bullet , 1130bbf21555SRichard Loweexcept that dashes are used in place of bullets. 1131bbf21555SRichard Lowe.It Fl diag 1132bbf21555SRichard LoweLike 1133bbf21555SRichard Lowe.Fl inset , 1134bbf21555SRichard Loweexcept that item heads are not parsed for macro invocations. 1135bbf21555SRichard LoweMost often used in the 1136bbf21555SRichard Lowe.Em DIAGNOSTICS 1137bbf21555SRichard Lowesection with error constants in the item heads. 1138bbf21555SRichard Lowe.It Fl enum 1139bbf21555SRichard LoweA numbered list. 1140bbf21555SRichard LoweNo item heads can be specified. 1141bbf21555SRichard LoweFormatted like 1142bbf21555SRichard Lowe.Fl bullet , 1143bbf21555SRichard Loweexcept that cardinal numbers are used in place of bullets, 1144bbf21555SRichard Lowestarting at 1. 1145bbf21555SRichard Lowe.It Fl hang 1146bbf21555SRichard LoweLike 1147bbf21555SRichard Lowe.Fl tag , 1148bbf21555SRichard Loweexcept that the first lines of item bodies are not indented, but follow 1149bbf21555SRichard Lowethe item heads like in 1150bbf21555SRichard Lowe.Fl inset 1151bbf21555SRichard Lowelists. 1152bbf21555SRichard Lowe.It Fl hyphen 1153bbf21555SRichard LoweSynonym for 1154bbf21555SRichard Lowe.Fl dash . 1155bbf21555SRichard Lowe.It Fl inset 1156bbf21555SRichard LoweItem bodies follow items heads on the same line, using normal inter-word 1157bbf21555SRichard Lowespacing. 1158bbf21555SRichard LoweBodies are not indented, and the 1159bbf21555SRichard Lowe.Fl width 1160bbf21555SRichard Loweargument is ignored. 1161bbf21555SRichard Lowe.It Fl item 1162bbf21555SRichard LoweNo item heads can be specified, and none are printed. 1163bbf21555SRichard LoweBodies are not indented, and the 1164bbf21555SRichard Lowe.Fl width 1165bbf21555SRichard Loweargument is ignored. 1166bbf21555SRichard Lowe.It Fl ohang 1167bbf21555SRichard LoweItem bodies start on the line following item heads and are not indented. 1168bbf21555SRichard LoweThe 1169bbf21555SRichard Lowe.Fl width 1170bbf21555SRichard Loweargument is ignored. 1171bbf21555SRichard Lowe.It Fl tag 1172bbf21555SRichard LoweItem bodies are indented according to the 1173bbf21555SRichard Lowe.Fl width 1174bbf21555SRichard Loweargument. 1175bbf21555SRichard LoweWhen an item head fits inside the indentation, the item body follows 1176bbf21555SRichard Lowethis head on the same output line. 1177bbf21555SRichard LoweOtherwise, the body starts on the output line following the head. 1178bbf21555SRichard Lowe.El 1179bbf21555SRichard Lowe.Pp 1180bbf21555SRichard LoweLists may be nested within lists and displays. 1181bbf21555SRichard LoweNesting of 1182bbf21555SRichard Lowe.Fl column 1183bbf21555SRichard Loweand 1184bbf21555SRichard Lowe.Fl enum 1185bbf21555SRichard Lowelists may not be portable. 1186bbf21555SRichard Lowe.Pp 1187bbf21555SRichard LoweSee also 1188bbf21555SRichard Lowe.Ic \&El 1189bbf21555SRichard Loweand 1190bbf21555SRichard Lowe.Ic \&It . 1191bbf21555SRichard Lowe.It Ic \&Bo Ar block 1192bbf21555SRichard LoweBegin a block enclosed by square brackets. 1193bbf21555SRichard LoweDoes not have any head arguments. 1194bbf21555SRichard Lowe.Pp 1195bbf21555SRichard LoweExamples: 1196bbf21555SRichard Lowe.Bd -literal -offset indent -compact 1197bbf21555SRichard Lowe\&.Bo 1 , 1198bbf21555SRichard Lowe\&.Dv BUFSIZ \&Bc 1199bbf21555SRichard Lowe.Ed 1200bbf21555SRichard Lowe.Pp 1201bbf21555SRichard LoweSee also 1202bbf21555SRichard Lowe.Ic \&Bq . 1203bbf21555SRichard Lowe.Tg Bq 1204bbf21555SRichard Lowe.It Ic \&Bq Ar line 1205bbf21555SRichard LoweEncloses its arguments in square brackets. 1206bbf21555SRichard Lowe.Pp 1207bbf21555SRichard LoweExamples: 1208bbf21555SRichard Lowe.Dl \&.Bq 1 , \&Dv BUFSIZ 1209bbf21555SRichard Lowe.Pp 1210bbf21555SRichard Lowe.Em Remarks : 1211bbf21555SRichard Lowethis macro is sometimes abused to emulate optional arguments for 1212bbf21555SRichard Lowecommands; the correct macros to use for this purpose are 1213bbf21555SRichard Lowe.Ic \&Op , 1214bbf21555SRichard Lowe.Ic \&Oo , 1215bbf21555SRichard Loweand 1216bbf21555SRichard Lowe.Ic \&Oc . 1217bbf21555SRichard Lowe.Pp 1218bbf21555SRichard LoweSee also 1219bbf21555SRichard Lowe.Ic \&Bo . 1220bbf21555SRichard Lowe.It Ic \&Brc 1221bbf21555SRichard LoweClose a 1222bbf21555SRichard Lowe.Ic \&Bro 1223bbf21555SRichard Loweblock. 1224bbf21555SRichard LoweDoes not have any tail arguments. 1225bbf21555SRichard Lowe.It Ic \&Bro Ar block 1226bbf21555SRichard LoweBegin a block enclosed by curly braces. 1227bbf21555SRichard LoweDoes not have any head arguments. 1228bbf21555SRichard Lowe.Pp 1229bbf21555SRichard LoweExamples: 1230bbf21555SRichard Lowe.Bd -literal -offset indent -compact 1231bbf21555SRichard Lowe\&.Bro 1 , ... , 1232bbf21555SRichard Lowe\&.Va n \&Brc 1233bbf21555SRichard Lowe.Ed 1234bbf21555SRichard Lowe.Pp 1235bbf21555SRichard LoweSee also 1236bbf21555SRichard Lowe.Ic \&Brq . 1237bbf21555SRichard Lowe.Tg Brq 1238bbf21555SRichard Lowe.It Ic \&Brq Ar line 1239bbf21555SRichard LoweEncloses its arguments in curly braces. 1240bbf21555SRichard Lowe.Pp 1241bbf21555SRichard LoweExamples: 1242bbf21555SRichard Lowe.Dl \&.Brq 1 , ... , \&Va n 1243bbf21555SRichard Lowe.Pp 1244bbf21555SRichard LoweSee also 1245bbf21555SRichard Lowe.Ic \&Bro . 1246bbf21555SRichard Lowe.Tg Bsx 1247bbf21555SRichard Lowe.It Ic \&Bsx Op Ar version 1248bbf21555SRichard LoweFormat the 1249bbf21555SRichard Lowe.Bsx 1250bbf21555SRichard Loweversion provided as an argument, or a default value if 1251bbf21555SRichard Loweno argument is provided. 1252bbf21555SRichard Lowe.Pp 1253bbf21555SRichard LoweExamples: 1254bbf21555SRichard Lowe.Dl \&.Bsx 1.0 1255bbf21555SRichard Lowe.Dl \&.Bsx 1256bbf21555SRichard Lowe.Pp 1257bbf21555SRichard LoweSee also 1258bbf21555SRichard Lowe.Ic \&At , 1259bbf21555SRichard Lowe.Ic \&Bx , 1260bbf21555SRichard Lowe.Ic \&Dx , 1261bbf21555SRichard Lowe.Ic \&Fx , 1262bbf21555SRichard Lowe.Ic \&Nx , 1263bbf21555SRichard Loweand 1264bbf21555SRichard Lowe.Ic \&Ox . 1265bbf21555SRichard Lowe.It Ic \&Bt 1266bbf21555SRichard LoweSupported only for compatibility, do not use this in new manuals. 1267bbf21555SRichard LowePrints 1268bbf21555SRichard Lowe.Dq is currently in beta test. 1269bbf21555SRichard Lowe.Tg Bx 1270bbf21555SRichard Lowe.It Ic \&Bx Op Ar version Op Ar variant 1271bbf21555SRichard LoweFormat the 1272bbf21555SRichard Lowe.Bx 1273bbf21555SRichard Loweversion provided as an argument, or a default value if no 1274bbf21555SRichard Loweargument is provided. 1275bbf21555SRichard Lowe.Pp 1276bbf21555SRichard LoweExamples: 1277bbf21555SRichard Lowe.Dl \&.Bx 4.3 Tahoe 1278bbf21555SRichard Lowe.Dl \&.Bx 4.4 1279bbf21555SRichard Lowe.Dl \&.Bx 1280bbf21555SRichard Lowe.Pp 1281bbf21555SRichard LoweSee also 1282bbf21555SRichard Lowe.Ic \&At , 1283bbf21555SRichard Lowe.Ic \&Bsx , 1284bbf21555SRichard Lowe.Ic \&Dx , 1285bbf21555SRichard Lowe.Ic \&Fx , 1286bbf21555SRichard Lowe.Ic \&Nx , 1287bbf21555SRichard Loweand 1288bbf21555SRichard Lowe.Ic \&Ox . 1289bbf21555SRichard Lowe.Tg Cd 1290bbf21555SRichard Lowe.It Ic \&Cd Ar line 1291bbf21555SRichard LoweKernel configuration declaration. 1292bbf21555SRichard LoweIt is found in pages for 1293bbf21555SRichard Lowe.Bx 1294bbf21555SRichard Loweand not used here. 1295bbf21555SRichard Lowe.Pp 1296bbf21555SRichard LoweExamples: 1297bbf21555SRichard Lowe.Dl \&.Cd device le0 at scode? 1298bbf21555SRichard Lowe.Pp 1299bbf21555SRichard Lowe.Em Remarks : 1300bbf21555SRichard Lowethis macro is commonly abused by using quoted literals to retain 1301bbf21555SRichard Lowewhitespace and align consecutive 1302bbf21555SRichard Lowe.Ic \&Cd 1303bbf21555SRichard Lowedeclarations. 1304bbf21555SRichard LoweThis practise is discouraged. 1305bbf21555SRichard Lowe.Tg Cm 1306bbf21555SRichard Lowe.It Ic \&Cm Ar keyword ... 1307bbf21555SRichard LoweCommand modifiers. 1308bbf21555SRichard LoweTypically used for fixed strings passed as arguments to interactive 1309bbf21555SRichard Lowecommands, to commands in interpreted scripts, or to configuration 1310bbf21555SRichard Lowefile directives, unless 1311bbf21555SRichard Lowe.Ic \&Fl 1312bbf21555SRichard Loweis more appropriate. 1313bbf21555SRichard LoweAlso useful when specifying configuration options or keys. 1314bbf21555SRichard Lowe.Pp 1315bbf21555SRichard LoweExamples: 1316bbf21555SRichard Lowe.Dl ".Nm mt Fl f Ar device Cm rewind" 1317bbf21555SRichard Lowe.Dl ".Nm ps Fl o Cm pid , Ns Cm command" 1318bbf21555SRichard Lowe.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" 1319bbf21555SRichard Lowe.Dl ".Ic set Fl o Cm vi" 1320bbf21555SRichard Lowe.Dl ".Ic lookup Cm file bind" 1321bbf21555SRichard Lowe.Dl ".Ic permit Ar identity Op Cm as Ar target" 1322bbf21555SRichard Lowe.Tg D1 1323bbf21555SRichard Lowe.It Ic \&D1 Ar line 1324bbf21555SRichard LoweOne-line indented display. 1325bbf21555SRichard LoweThis is formatted by the default rules and is useful for simple indented 1326bbf21555SRichard Lowestatements. 1327bbf21555SRichard LoweIt is followed by a newline. 1328bbf21555SRichard Lowe.Pp 1329bbf21555SRichard LoweExamples: 1330bbf21555SRichard Lowe.Dl \&.D1 \&Fl abcdefgh 1331bbf21555SRichard Lowe.Pp 1332bbf21555SRichard LoweSee also 1333bbf21555SRichard Lowe.Ic \&Bd 1334bbf21555SRichard Loweand 1335bbf21555SRichard Lowe.Ic \&Dl . 1336bbf21555SRichard Lowe.It Ic \&Db 1337bbf21555SRichard LoweThis macro is obsolete. 1338bbf21555SRichard LoweNo replacement is needed. 1339bbf21555SRichard LoweIt is ignored by 1340bbf21555SRichard Lowe.Xr mandoc 1 1341bbf21555SRichard Loweand groff including its arguments. 1342bbf21555SRichard LoweIt was formerly used to toggle a debugging mode. 1343bbf21555SRichard Lowe.It Ic \&Dc 1344bbf21555SRichard LoweClose a 1345bbf21555SRichard Lowe.Ic \&Do 1346bbf21555SRichard Loweblock. 1347bbf21555SRichard LoweDoes not have any tail arguments. 1348bbf21555SRichard Lowe.Tg Dd 1349bbf21555SRichard Lowe.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year 1350bbf21555SRichard LoweDocument date for display in the page footer, 1351bbf21555SRichard Loweby convention the date of the last change. 1352bbf21555SRichard LoweThis is the mandatory first macro of any 1353bbf21555SRichard Lowe.Nm 1354bbf21555SRichard Lowemanual. 1355bbf21555SRichard Lowe.Pp 1356bbf21555SRichard LoweThe 1357bbf21555SRichard Lowe.Ar month 1358bbf21555SRichard Loweis the full English month name, the 1359bbf21555SRichard Lowe.Ar day 1360bbf21555SRichard Loweis an integer number, and the 1361bbf21555SRichard Lowe.Ar year 1362bbf21555SRichard Loweis the full four-digit year. 1363bbf21555SRichard Lowe.Pp 1364bbf21555SRichard LoweOther arguments are not portable; the 1365bbf21555SRichard Lowe.Xr mandoc 1 1366bbf21555SRichard Loweutility handles them as follows: 1367bbf21555SRichard Lowe.Bl -dash -offset 3n -compact 1368bbf21555SRichard Lowe.It 1369bbf21555SRichard LoweTo have the date automatically filled in by the 1370bbf21555SRichard Lowe.Ox 1371bbf21555SRichard Loweversion of 1372bbf21555SRichard Lowe.Xr cvs 1 , 1373bbf21555SRichard Lowethe special string 1374bbf21555SRichard Lowe.Dq $\&Mdocdate$ 1375bbf21555SRichard Lowecan be given as an argument. 1376bbf21555SRichard Lowe.It 1377bbf21555SRichard LoweThe traditional, purely numeric 1378bbf21555SRichard Lowe.Xr man 7 1379bbf21555SRichard Loweformat 1380bbf21555SRichard Lowe.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day 1381bbf21555SRichard Loweis accepted, too. 1382bbf21555SRichard Lowe.It 1383bbf21555SRichard LoweIf a date string cannot be parsed, it is used verbatim. 1384bbf21555SRichard Lowe.It 1385bbf21555SRichard LoweIf no date string is given, the current date is used. 1386bbf21555SRichard Lowe.El 1387bbf21555SRichard Lowe.Pp 1388bbf21555SRichard LoweExamples: 1389bbf21555SRichard Lowe.Dl \&.Dd $\&Mdocdate$ 1390bbf21555SRichard Lowe.Dl \&.Dd $\&Mdocdate: July 2 2018$ 1391bbf21555SRichard Lowe.Dl \&.Dd July 2, 2018 1392bbf21555SRichard Lowe.Pp 1393bbf21555SRichard LoweSee also 1394bbf21555SRichard Lowe.Ic \&Dt 1395bbf21555SRichard Loweand 1396bbf21555SRichard Lowe.Ic \&Os . 1397bbf21555SRichard Lowe.Tg Dl 1398bbf21555SRichard Lowe.It Ic \&Dl Ar line 1399bbf21555SRichard LoweOne-line indented display. 1400bbf21555SRichard LoweThis is formatted as literal text and is useful for commands and 1401bbf21555SRichard Loweinvocations. 1402bbf21555SRichard LoweIt is followed by a newline. 1403bbf21555SRichard Lowe.Pp 1404bbf21555SRichard LoweExamples: 1405bbf21555SRichard Lowe.Dl \&.Dl % mandoc mdoc.5 \e(ba less 1406bbf21555SRichard Lowe.Pp 1407bbf21555SRichard LoweSee also 1408bbf21555SRichard Lowe.Ic \&Ql , 1409bbf21555SRichard Lowe.Ic \&Bd Fl literal , 1410bbf21555SRichard Loweand 1411bbf21555SRichard Lowe.Ic \&D1 . 1412bbf21555SRichard Lowe.It Ic \&Do Ar block 1413bbf21555SRichard LoweBegin a block enclosed by double quotes. 1414bbf21555SRichard LoweDoes not have any head arguments. 1415bbf21555SRichard Lowe.Pp 1416bbf21555SRichard LoweExamples: 1417bbf21555SRichard Lowe.Bd -literal -offset indent -compact 1418bbf21555SRichard Lowe\&.Do 1419bbf21555SRichard LoweApril is the cruellest month 1420bbf21555SRichard Lowe\&.Dc 1421bbf21555SRichard Lowe\e(em T.S. Eliot 1422bbf21555SRichard Lowe.Ed 1423bbf21555SRichard Lowe.Pp 1424bbf21555SRichard LoweSee also 1425bbf21555SRichard Lowe.Ic \&Dq . 1426bbf21555SRichard Lowe.Tg Dq 1427bbf21555SRichard Lowe.It Ic \&Dq Ar line 1428bbf21555SRichard LoweEncloses its arguments in 1429bbf21555SRichard Lowe.Dq typographic 1430bbf21555SRichard Lowedouble-quotes. 1431bbf21555SRichard Lowe.Pp 1432bbf21555SRichard LoweExamples: 1433bbf21555SRichard Lowe.Bd -literal -offset indent -compact 1434bbf21555SRichard Lowe\&.Dq April is the cruellest month 1435bbf21555SRichard Lowe\e(em T.S. Eliot 1436bbf21555SRichard Lowe.Ed 1437bbf21555SRichard Lowe.Pp 1438bbf21555SRichard LoweSee also 1439bbf21555SRichard Lowe.Ic \&Qq , 1440bbf21555SRichard Lowe.Ic \&Sq , 1441bbf21555SRichard Loweand 1442bbf21555SRichard Lowe.Ic \&Do . 1443bbf21555SRichard Lowe.Tg Dt 1444bbf21555SRichard Lowe.It Ic \&Dt Ar TITLE section Op Ar arch 1445bbf21555SRichard LoweDocument title for display in the page header. 1446bbf21555SRichard LoweThis is the mandatory second macro of any 1447bbf21555SRichard Lowe.Nm 1448bbf21555SRichard Lowefile. 1449bbf21555SRichard Lowe.Pp 1450bbf21555SRichard LoweIts arguments are as follows: 1451bbf21555SRichard Lowe.Bl -tag -width section -offset 2n 1452bbf21555SRichard Lowe.It Ar TITLE 1453bbf21555SRichard LoweThe document's title (name), defaulting to 1454bbf21555SRichard Lowe.Dq UNTITLED 1455bbf21555SRichard Loweif unspecified. 1456bbf21555SRichard LoweTo achieve a uniform appearance of page header lines, 1457bbf21555SRichard Loweit should by convention be all caps. 1458bbf21555SRichard Lowe.It Ar SECTION 1459bbf21555SRichard LoweThe manual section. 1460bbf21555SRichard LoweIt should correspond to the manual's filename suffix and defaults to 1461bbf21555SRichard Lowethe empty string if unspecified. 1462bbf21555SRichard LoweThis field is optional. 1463bbf21555SRichard LoweTo achieve a uniform appearance of page header lines, 1464bbf21555SRichard Loweit should by convention be all caps. 1465bbf21555SRichard Lowe.It Ar arch 1466bbf21555SRichard LoweThis specifies the machine architecture a manual page applies to, 1467bbf21555SRichard Lowewhere relevant. 1468bbf21555SRichard Lowe.El 1469bbf21555SRichard Lowe.It Ic \&Dv 1470bbf21555SRichard LoweDefined variables such as preprocessor constants, constant symbols, 1471bbf21555SRichard Loweenumeration values, and so on. 1472bbf21555SRichard Lowe.Pp 1473bbf21555SRichard LoweExamples: 1474bbf21555SRichard Lowe.Dl \&.Dv NULL 1475bbf21555SRichard Lowe.Dl \&.Dv BUFSIZ 1476bbf21555SRichard Lowe.Dl \&.Dv STDOUT_FILENO 1477bbf21555SRichard Lowe.Pp 1478bbf21555SRichard LoweSee also 1479bbf21555SRichard Lowe.Ic \&Er 1480bbf21555SRichard Loweand 1481bbf21555SRichard Lowe.Ic \&Ev 1482bbf21555SRichard Lowefor special-purpose constants, 1483bbf21555SRichard Lowe.Ic \&Va 1484bbf21555SRichard Lowefor variable symbols, and 1485bbf21555SRichard Lowe.Ic \&Fd 1486bbf21555SRichard Lowefor listing preprocessor variable definitions in the 1487bbf21555SRichard Lowe.Em SYNOPSIS . 1488bbf21555SRichard Lowe.Tg Dx 1489bbf21555SRichard Lowe.It Ic \&Dx Op Ar version 1490bbf21555SRichard LoweFormat the 1491bbf21555SRichard Lowe.Dx 1492bbf21555SRichard Loweversion provided as an argument, or a default 1493bbf21555SRichard Lowevalue if no argument is provided. 1494bbf21555SRichard Lowe.Pp 1495bbf21555SRichard LoweExamples: 1496bbf21555SRichard Lowe.Dl \&.Dx 2.4.1 1497bbf21555SRichard Lowe.Dl \&.Dx 1498bbf21555SRichard Lowe.Pp 1499bbf21555SRichard LoweSee also 1500bbf21555SRichard Lowe.Ic \&At , 1501bbf21555SRichard Lowe.Ic \&Bsx , 1502bbf21555SRichard Lowe.Ic \&Bx , 1503bbf21555SRichard Lowe.Ic \&Fx , 1504bbf21555SRichard Lowe.Ic \&Nx , 1505bbf21555SRichard Loweand 1506bbf21555SRichard Lowe.Ic \&Ox . 1507bbf21555SRichard Lowe.It Ic \&Ec Op Ar closing_delimiter 1508bbf21555SRichard LoweClose a scope started by 1509bbf21555SRichard Lowe.Ic \&Eo . 1510bbf21555SRichard Lowe.Pp 1511bbf21555SRichard LoweThe 1512bbf21555SRichard Lowe.Ar closing_delimiter 1513bbf21555SRichard Loweargument is used as the enclosure tail, for example, specifying \e(rq 1514bbf21555SRichard Lowewill emulate 1515bbf21555SRichard Lowe.Ic \&Dc . 1516bbf21555SRichard Lowe.It Ic \&Ed 1517bbf21555SRichard LoweEnd a display context started by 1518bbf21555SRichard Lowe.Ic \&Bd . 1519bbf21555SRichard Lowe.It Ic \&Ef 1520bbf21555SRichard LoweEnd a font mode context started by 1521bbf21555SRichard Lowe.Ic \&Bf . 1522bbf21555SRichard Lowe.It Ic \&Ek 1523bbf21555SRichard LoweEnd a keep context started by 1524bbf21555SRichard Lowe.Ic \&Bk . 1525bbf21555SRichard Lowe.It Ic \&El 1526bbf21555SRichard LoweEnd a list context started by 1527bbf21555SRichard Lowe.Ic \&Bl . 1528bbf21555SRichard LoweSee also 1529bbf21555SRichard Lowe.Ic \&It . 1530bbf21555SRichard Lowe.Tg Em 1531bbf21555SRichard Lowe.It Ic \&Em Ar word ... 1532bbf21555SRichard LoweRequest an italic font. 1533bbf21555SRichard LoweIf the output device does not provide that, underline. 1534bbf21555SRichard Lowe.Pp 1535bbf21555SRichard LoweThis is most often used for stress emphasis (not to be confused with 1536bbf21555SRichard Loweimportance, see 1537bbf21555SRichard Lowe.Ic \&Sy ) . 1538bbf21555SRichard LoweIn the rare cases where none of the semantic markup macros fit, 1539bbf21555SRichard Loweit can also be used for technical terms and placeholders, except 1540bbf21555SRichard Lowethat for syntax elements, 1541bbf21555SRichard Lowe.Ic \&Sy 1542bbf21555SRichard Loweand 1543bbf21555SRichard Lowe.Ic \&Ar 1544bbf21555SRichard Loweare preferred, respectively. 1545bbf21555SRichard Lowe.Pp 1546bbf21555SRichard LoweExamples: 1547bbf21555SRichard Lowe.Bd -literal -compact -offset indent 1548bbf21555SRichard LoweSelected lines are those 1549bbf21555SRichard Lowe\&.Em not 1550bbf21555SRichard Lowematching any of the specified patterns. 1551bbf21555SRichard LoweSome of the functions use a 1552bbf21555SRichard Lowe\&.Em hold space 1553bbf21555SRichard Loweto save the pattern space for subsequent retrieval. 1554bbf21555SRichard Lowe.Ed 1555bbf21555SRichard Lowe.Pp 1556bbf21555SRichard LoweSee also 1557bbf21555SRichard Lowe.Ic \&No , 1558bbf21555SRichard Lowe.Ic \&Ql , 1559bbf21555SRichard Loweand 1560bbf21555SRichard Lowe.Ic \&Sy . 1561bbf21555SRichard Lowe.It Ic \&En Ar word ... 1562bbf21555SRichard LoweThis macro is obsolete. 1563bbf21555SRichard LoweUse 1564bbf21555SRichard Lowe.Ic \&Eo 1565bbf21555SRichard Loweor any of the other enclosure macros. 1566bbf21555SRichard Lowe.Pp 1567bbf21555SRichard LoweIt encloses its argument in the delimiters specified by the last 1568bbf21555SRichard Lowe.Ic \&Es 1569bbf21555SRichard Lowemacro. 1570bbf21555SRichard Lowe.Tg Eo 1571bbf21555SRichard Lowe.It Ic \&Eo Op Ar opening_delimiter 1572bbf21555SRichard LoweAn arbitrary enclosure. 1573bbf21555SRichard LoweThe 1574bbf21555SRichard Lowe.Ar opening_delimiter 1575bbf21555SRichard Loweargument is used as the enclosure head, for example, specifying \e(lq 1576bbf21555SRichard Lowewill emulate 1577bbf21555SRichard Lowe.Ic \&Do . 1578bbf21555SRichard Lowe.Tg Er 1579bbf21555SRichard Lowe.It Ic \&Er Ar identifier ... 1580bbf21555SRichard LoweError constants for definitions of the 1581bbf21555SRichard Lowe.Va errno 1582bbf21555SRichard Lowelibc global variable. 1583bbf21555SRichard LoweThis is most often used in section 2 and 3 manual pages. 1584bbf21555SRichard Lowe.Pp 1585bbf21555SRichard LoweExamples: 1586bbf21555SRichard Lowe.Dl \&.Er EPERM 1587bbf21555SRichard Lowe.Dl \&.Er ENOENT 1588bbf21555SRichard Lowe.Pp 1589bbf21555SRichard LoweSee also 1590bbf21555SRichard Lowe.Ic \&Dv 1591bbf21555SRichard Lowefor general constants. 1592bbf21555SRichard Lowe.It Ic \&Es Ar opening_delimiter closing_delimiter 1593bbf21555SRichard LoweThis macro is obsolete. 1594bbf21555SRichard LoweUse 1595bbf21555SRichard Lowe.Ic \&Eo 1596bbf21555SRichard Loweor any of the other enclosure macros. 1597bbf21555SRichard Lowe.Pp 1598bbf21555SRichard LoweIt takes two arguments, defining the delimiters to be used by subsequent 1599bbf21555SRichard Lowe.Ic \&En 1600bbf21555SRichard Lowemacros. 1601bbf21555SRichard Lowe.Tg Ev 1602bbf21555SRichard Lowe.It Ic \&Ev Ar identifier ... 1603bbf21555SRichard LoweEnvironmental variables such as those specified in 1604bbf21555SRichard Lowe.Xr environ 7 . 1605bbf21555SRichard Lowe.Pp 1606bbf21555SRichard LoweExamples: 1607bbf21555SRichard Lowe.Dl \&.Ev DISPLAY 1608bbf21555SRichard Lowe.Dl \&.Ev PATH 1609bbf21555SRichard Lowe.Pp 1610bbf21555SRichard LoweSee also 1611bbf21555SRichard Lowe.Ic \&Dv 1612bbf21555SRichard Lowefor general constants. 1613bbf21555SRichard Lowe.Tg Ex 1614bbf21555SRichard Lowe.It Ic \&Ex Fl std Op Ar utility ... 1615bbf21555SRichard LoweInsert a standard sentence regarding command exit values of 0 on success 1616bbf21555SRichard Loweand >0 on failure. 1617bbf21555SRichard LoweThis is most often used in section 1 and 8 manual pages. 1618bbf21555SRichard Lowe.Pp 1619bbf21555SRichard LoweIf 1620bbf21555SRichard Lowe.Ar utility 1621bbf21555SRichard Loweis not specified, the document's name set by 1622bbf21555SRichard Lowe.Ic \&Nm 1623bbf21555SRichard Loweis used. 1624bbf21555SRichard LoweMultiple 1625bbf21555SRichard Lowe.Ar utility 1626bbf21555SRichard Lowearguments are treated as separate utilities. 1627bbf21555SRichard Lowe.Pp 1628bbf21555SRichard LoweSee also 1629bbf21555SRichard Lowe.Ic \&Rv . 1630bbf21555SRichard Lowe.Tg Fa 1631bbf21555SRichard Lowe.It Ic \&Fa Ar argument ... 1632bbf21555SRichard LoweFunction argument or parameter. 1633bbf21555SRichard LoweEach argument may be a name and a type (recommended for the 1634bbf21555SRichard Lowe.Em SYNOPSIS 1635bbf21555SRichard Lowesection), a name alone (for function invocations), 1636bbf21555SRichard Loweor a type alone (for function prototypes). 1637bbf21555SRichard LoweIf both a type and a name are given or if the type consists of multiple 1638bbf21555SRichard Lowewords, all words belonging to the same function argument have to be 1639bbf21555SRichard Lowegiven in a single argument to the 1640bbf21555SRichard Lowe.Ic \&Fa 1641bbf21555SRichard Lowemacro. 1642bbf21555SRichard Lowe.Pp 1643bbf21555SRichard LoweThis macro is also used to specify the field name of a structure. 1644bbf21555SRichard Lowe.Pp 1645bbf21555SRichard LoweMost often, the 1646bbf21555SRichard Lowe.Ic \&Fa 1647bbf21555SRichard Lowemacro is used in the 1648bbf21555SRichard Lowe.Em SYNOPSIS 1649bbf21555SRichard Lowewithin 1650bbf21555SRichard Lowe.Ic \&Fo 1651bbf21555SRichard Loweblocks when documenting multi-line function prototypes. 1652bbf21555SRichard LoweIf invoked with multiple arguments, the arguments are separated by a 1653bbf21555SRichard Lowecomma. 1654bbf21555SRichard LoweFurthermore, if the following macro is another 1655bbf21555SRichard Lowe.Ic \&Fa , 1656bbf21555SRichard Lowethe last argument will also have a trailing comma. 1657bbf21555SRichard Lowe.Pp 1658bbf21555SRichard LoweExamples: 1659bbf21555SRichard Lowe.Dl \&.Fa \(dqconst char *p\(dq 1660bbf21555SRichard Lowe.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq 1661bbf21555SRichard Lowe.Dl \&.Fa \(dqchar *\(dq size_t 1662bbf21555SRichard Lowe.Pp 1663bbf21555SRichard LoweSee also 1664bbf21555SRichard Lowe.Ic \&Fo . 1665bbf21555SRichard Lowe.It Ic \&Fc 1666bbf21555SRichard LoweEnd a function context started by 1667bbf21555SRichard Lowe.Ic \&Fo . 1668bbf21555SRichard Lowe.Tg Fd 1669bbf21555SRichard Lowe.It Ic \&Fd Pf # Ar directive Op Ar argument ... 1670bbf21555SRichard LowePreprocessor directive, in particular for listing it in the 1671bbf21555SRichard Lowe.Em SYNOPSIS . 1672bbf21555SRichard LoweHistorically, it was also used to document include files. 1673bbf21555SRichard LoweThe latter usage has been deprecated in favour of 1674bbf21555SRichard Lowe.Ic \&In . 1675bbf21555SRichard Lowe.Pp 1676bbf21555SRichard LoweExamples: 1677bbf21555SRichard Lowe.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler 1678bbf21555SRichard Lowe.Dl \&.Fd #define SIO_MAXNFDS 1679bbf21555SRichard Lowe.Dl \&.Fd #ifdef FS_DEBUG 1680bbf21555SRichard Lowe.Dl \&.Ft void 1681bbf21555SRichard Lowe.Dl \&.Fn dbg_open \(dqconst char *\(dq 1682bbf21555SRichard Lowe.Dl \&.Fd #endif 1683bbf21555SRichard Lowe.Pp 1684bbf21555SRichard LoweSee also 1685bbf21555SRichard Lowe.Sx MANUAL STRUCTURE , 1686bbf21555SRichard Lowe.Ic \&In , 1687bbf21555SRichard Loweand 1688bbf21555SRichard Lowe.Ic \&Dv . 1689bbf21555SRichard Lowe.Tg Fl 1690bbf21555SRichard Lowe.It Ic \&Fl Op Ar word ... 1691bbf21555SRichard LoweCommand-line flag or option. 1692bbf21555SRichard LoweUsed when listing arguments to command-line utilities. 1693bbf21555SRichard LoweFor each argument, prints an ASCII hyphen-minus character 1694bbf21555SRichard Lowe.Sq \- , 1695bbf21555SRichard Loweimmediately followed by the argument. 1696bbf21555SRichard LoweIf no arguments are provided, a hyphen-minus is printed followed by a space. 1697bbf21555SRichard LoweIf the argument is a macro, a hyphen-minus is prefixed 1698bbf21555SRichard Loweto the subsequent macro output. 1699bbf21555SRichard Lowe.Pp 1700bbf21555SRichard LoweExamples: 1701bbf21555SRichard Lowe.Dl ".Nm du Op Fl H | L | P" 1702bbf21555SRichard Lowe.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" 1703bbf21555SRichard Lowe.Dl ".Nm route Cm add Fl inet Ar destination gateway" 1704bbf21555SRichard Lowe.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile" 1705bbf21555SRichard Lowe.Dl ".Nm aucat Fl o Fl" 1706bbf21555SRichard Lowe.Dl ".Nm kill Fl Ar signal_number" 1707bbf21555SRichard Lowe.Pp 1708bbf21555SRichard LoweFor GNU-sytle long options, escaping the additional hyphen-minus is not 1709bbf21555SRichard Lowestrictly required, but may be safer with future versions of GNU troff; see 1710bbf21555SRichard Lowe.Xr mandoc_char 7 1711bbf21555SRichard Lowefor details. 1712bbf21555SRichard Lowe.Pp 1713bbf21555SRichard LoweSee also 1714bbf21555SRichard Lowe.Ic \&Cm . 1715bbf21555SRichard Lowe.Tg Fn 1716bbf21555SRichard Lowe.It Ic \&Fn Ar funcname Op Ar argument ... 1717bbf21555SRichard LoweA function name. 1718bbf21555SRichard Lowe.Pp 1719bbf21555SRichard LoweFunction arguments are surrounded in parenthesis and 1720bbf21555SRichard Loweare delimited by commas. 1721bbf21555SRichard LoweIf no arguments are specified, blank parenthesis are output. 1722bbf21555SRichard LoweIn the 1723bbf21555SRichard Lowe.Em SYNOPSIS 1724bbf21555SRichard Lowesection, this macro starts a new output line, 1725bbf21555SRichard Loweand a blank line is automatically inserted between function definitions. 1726bbf21555SRichard Lowe.Pp 1727bbf21555SRichard LoweExamples: 1728bbf21555SRichard Lowe.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq 1729bbf21555SRichard Lowe.Dl \&.Fn funcname \(dqint arg0\(dq 1730bbf21555SRichard Lowe.Dl \&.Fn funcname arg0 1731bbf21555SRichard Lowe.Bd -literal -offset indent 1732bbf21555SRichard Lowe\&.Ft functype 1733bbf21555SRichard Lowe\&.Fn funcname 1734bbf21555SRichard Lowe.Ed 1735bbf21555SRichard Lowe.Pp 1736bbf21555SRichard LoweWhen referring to a function documented in another manual page, use 1737bbf21555SRichard Lowe.Ic \&Xr 1738bbf21555SRichard Loweinstead. 1739bbf21555SRichard LoweSee also 1740bbf21555SRichard Lowe.Sx MANUAL STRUCTURE , 1741bbf21555SRichard Lowe.Ic \&Fo , 1742bbf21555SRichard Loweand 1743bbf21555SRichard Lowe.Ic \&Ft . 1744bbf21555SRichard Lowe.Tg Fo 1745bbf21555SRichard Lowe.It Ic \&Fo Ar funcname 1746bbf21555SRichard LoweBegin a function block. 1747bbf21555SRichard LoweThis is a multi-line version of 1748bbf21555SRichard Lowe.Ic \&Fn . 1749bbf21555SRichard Lowe.Pp 1750bbf21555SRichard LoweInvocations usually occur in the following context: 1751bbf21555SRichard Lowe.Bd -ragged -offset indent 1752bbf21555SRichard Lowe.Pf \. Ic \&Ft Ar functype 1753bbf21555SRichard Lowe.br 1754bbf21555SRichard Lowe.Pf \. Ic \&Fo Ar funcname 1755bbf21555SRichard Lowe.br 1756bbf21555SRichard Lowe.Pf \. Ic \&Fa Qq Ar argtype Ar argname 1757bbf21555SRichard Lowe.br 1758bbf21555SRichard Lowe\&.\.\. 1759bbf21555SRichard Lowe.br 1760bbf21555SRichard Lowe.Pf \. Ic \&Fc 1761bbf21555SRichard Lowe.Ed 1762bbf21555SRichard Lowe.Pp 1763bbf21555SRichard LoweA 1764bbf21555SRichard Lowe.Ic \&Fo 1765bbf21555SRichard Lowescope is closed by 1766bbf21555SRichard Lowe.Ic \&Fc . 1767bbf21555SRichard Lowe.Pp 1768bbf21555SRichard LoweSee also 1769bbf21555SRichard Lowe.Sx MANUAL STRUCTURE , 1770bbf21555SRichard Lowe.Ic \&Fa , 1771bbf21555SRichard Lowe.Ic \&Fc , 1772bbf21555SRichard Loweand 1773bbf21555SRichard Lowe.Ic \&Ft . 1774bbf21555SRichard Lowe.It Ic \&Fr Ar number 1775bbf21555SRichard LoweThis macro is obsolete. 1776bbf21555SRichard LoweNo replacement markup is needed. 1777bbf21555SRichard Lowe.Pp 1778bbf21555SRichard LoweIt was used to show numerical function return values in an italic font. 1779bbf21555SRichard Lowe.Tg Ft 1780bbf21555SRichard Lowe.It Ic \&Ft Ar functype 1781bbf21555SRichard LoweA function type. 1782bbf21555SRichard Lowe.Pp 1783bbf21555SRichard LoweIn the 1784bbf21555SRichard Lowe.Em SYNOPSIS 1785bbf21555SRichard Lowesection, a new output line is started after this macro. 1786bbf21555SRichard Lowe.Pp 1787bbf21555SRichard LoweExamples: 1788bbf21555SRichard Lowe.Dl \&.Ft int 1789bbf21555SRichard Lowe.Bd -literal -offset indent -compact 1790bbf21555SRichard Lowe\&.Ft functype 1791bbf21555SRichard Lowe\&.Fn funcname 1792bbf21555SRichard Lowe.Ed 1793bbf21555SRichard Lowe.Pp 1794bbf21555SRichard LoweSee also 1795bbf21555SRichard Lowe.Sx MANUAL STRUCTURE , 1796bbf21555SRichard Lowe.Ic \&Fn , 1797bbf21555SRichard Loweand 1798bbf21555SRichard Lowe.Ic \&Fo . 1799bbf21555SRichard Lowe.Tg Fx 1800bbf21555SRichard Lowe.It Ic \&Fx Op Ar version 1801bbf21555SRichard LoweFormat the 1802bbf21555SRichard Lowe.Fx 1803bbf21555SRichard Loweversion provided as an argument, or a default value 1804bbf21555SRichard Loweif no argument is provided. 1805bbf21555SRichard Lowe.Pp 1806bbf21555SRichard LoweExamples: 1807bbf21555SRichard Lowe.Dl \&.Fx 7.1 1808bbf21555SRichard Lowe.Dl \&.Fx 1809bbf21555SRichard Lowe.Pp 1810bbf21555SRichard LoweSee also 1811bbf21555SRichard Lowe.Ic \&At , 1812bbf21555SRichard Lowe.Ic \&Bsx , 1813bbf21555SRichard Lowe.Ic \&Bx , 1814bbf21555SRichard Lowe.Ic \&Dx , 1815bbf21555SRichard Lowe.Ic \&Nx , 1816bbf21555SRichard Loweand 1817bbf21555SRichard Lowe.Ic \&Ox . 1818bbf21555SRichard Lowe.It Ic \&Hf Ar filename 1819bbf21555SRichard LoweThis macro is not implemented in 1820bbf21555SRichard Lowe.Xr mandoc 1 . 1821bbf21555SRichard LoweIt was used to include the contents of a (header) file literally. 1822bbf21555SRichard Lowe.Tg Ic 1823bbf21555SRichard Lowe.It Ic \&Ic Ar keyword ... 1824bbf21555SRichard LoweInternal or interactive command, or configuration instruction 1825bbf21555SRichard Lowein a configuration file. 1826bbf21555SRichard LoweSee also 1827bbf21555SRichard Lowe.Ic \&Cm . 1828bbf21555SRichard Lowe.Pp 1829bbf21555SRichard LoweExamples: 1830bbf21555SRichard Lowe.Dl \&.Ic :wq 1831bbf21555SRichard Lowe.Dl \&.Ic hash 1832bbf21555SRichard Lowe.Dl \&.Ic alias 1833bbf21555SRichard Lowe.Pp 1834bbf21555SRichard LoweNote that using 1835bbf21555SRichard Lowe.Ic \&Ql , 1836bbf21555SRichard Lowe.Ic \&Dl , 1837bbf21555SRichard Loweor 1838bbf21555SRichard Lowe.Ic \&Bd Fl literal 1839bbf21555SRichard Loweis preferred for displaying code samples; the 1840bbf21555SRichard Lowe.Ic \&Ic 1841bbf21555SRichard Lowemacro is used when referring to an individual command name. 1842bbf21555SRichard Lowe.Tg In 1843bbf21555SRichard Lowe.It Ic \&In Ar filename 1844bbf21555SRichard LoweThe name of an include file. 1845bbf21555SRichard LoweThis macro is most often used in section 2, 3, and 9 manual pages. 1846bbf21555SRichard Lowe.Pp 1847bbf21555SRichard LoweWhen invoked as the first macro on an input line in the 1848bbf21555SRichard Lowe.Em SYNOPSIS 1849bbf21555SRichard Lowesection, the argument is displayed in angle brackets 1850bbf21555SRichard Loweand preceded by 1851bbf21555SRichard Lowe.Qq #include , 1852bbf21555SRichard Loweand a blank line is inserted in front if there is a preceding 1853bbf21555SRichard Lowefunction declaration. 1854bbf21555SRichard LoweIn other sections, it only encloses its argument in angle brackets 1855bbf21555SRichard Loweand causes no line break. 1856bbf21555SRichard Lowe.Pp 1857bbf21555SRichard LoweExamples: 1858bbf21555SRichard Lowe.Dl \&.In sys/types.h 1859bbf21555SRichard Lowe.Pp 1860bbf21555SRichard LoweSee also 1861bbf21555SRichard Lowe.Sx MANUAL STRUCTURE . 1862bbf21555SRichard Lowe.Tg It 1863bbf21555SRichard Lowe.It Ic \&It Op Ar head 1864bbf21555SRichard LoweA list item. 1865bbf21555SRichard LoweThe syntax of this macro depends on the list type. 1866bbf21555SRichard Lowe.Pp 1867bbf21555SRichard LoweLists 1868bbf21555SRichard Loweof type 1869bbf21555SRichard Lowe.Fl hang , 1870bbf21555SRichard Lowe.Fl ohang , 1871bbf21555SRichard Lowe.Fl inset , 1872bbf21555SRichard Loweand 1873bbf21555SRichard Lowe.Fl diag 1874bbf21555SRichard Lowehave the following syntax: 1875bbf21555SRichard Lowe.Pp 1876bbf21555SRichard Lowe.D1 Pf \. Ic \&It Ar args 1877bbf21555SRichard Lowe.Pp 1878bbf21555SRichard LoweLists of type 1879bbf21555SRichard Lowe.Fl bullet , 1880bbf21555SRichard Lowe.Fl dash , 1881bbf21555SRichard Lowe.Fl enum , 1882bbf21555SRichard Lowe.Fl hyphen 1883bbf21555SRichard Loweand 1884bbf21555SRichard Lowe.Fl item 1885bbf21555SRichard Lowehave the following syntax: 1886bbf21555SRichard Lowe.Pp 1887bbf21555SRichard Lowe.D1 Pf \. Ic \&It 1888bbf21555SRichard Lowe.Pp 1889bbf21555SRichard Lowewith subsequent lines interpreted within the scope of the 1890bbf21555SRichard Lowe.Ic \&It 1891bbf21555SRichard Loweuntil either a closing 1892bbf21555SRichard Lowe.Ic \&El 1893bbf21555SRichard Loweor another 1894bbf21555SRichard Lowe.Ic \&It . 1895bbf21555SRichard Lowe.Pp 1896bbf21555SRichard LoweThe 1897bbf21555SRichard Lowe.Fl tag 1898bbf21555SRichard Lowelist has the following syntax: 1899bbf21555SRichard Lowe.Pp 1900bbf21555SRichard Lowe.D1 Pf \. Ic \&It Op Cm args 1901bbf21555SRichard Lowe.Pp 1902bbf21555SRichard LoweSubsequent lines are interpreted as with 1903bbf21555SRichard Lowe.Fl bullet 1904bbf21555SRichard Loweand family. 1905bbf21555SRichard LoweThe line arguments correspond to the list's left-hand side; body 1906bbf21555SRichard Lowearguments correspond to the list's contents. 1907bbf21555SRichard Lowe.Pp 1908bbf21555SRichard LoweThe 1909bbf21555SRichard Lowe.Fl column 1910bbf21555SRichard Lowelist is the most complicated. 1911bbf21555SRichard LoweIts syntax is as follows: 1912bbf21555SRichard Lowe.Pp 1913bbf21555SRichard Lowe.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... 1914bbf21555SRichard Lowe.D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ... 1915bbf21555SRichard Lowe.Pp 1916bbf21555SRichard LoweThe arguments consist of one or more lines of text and macros 1917bbf21555SRichard Lowerepresenting a complete table line. 1918bbf21555SRichard LoweCells within the line are delimited by the special 1919bbf21555SRichard Lowe.Ic \&Ta 1920bbf21555SRichard Loweblock macro or by literal tab characters. 1921bbf21555SRichard Lowe.Pp 1922bbf21555SRichard LoweUsing literal tabs is strongly discouraged because they are very 1923bbf21555SRichard Lowehard to use correctly and 1924bbf21555SRichard Lowe.Nm 1925bbf21555SRichard Lowecode using them is very hard to read. 1926bbf21555SRichard LoweIn particular, a blank character is syntactically significant 1927bbf21555SRichard Lowebefore and after the literal tab character. 1928bbf21555SRichard LoweIf a word precedes or follows the tab without an intervening blank, 1929bbf21555SRichard Lowethat word is never interpreted as a macro call, but always output 1930bbf21555SRichard Loweliterally. 1931bbf21555SRichard Lowe.Pp 1932bbf21555SRichard LoweThe tab cell delimiter may only be used within the 1933bbf21555SRichard Lowe.Ic \&It 1934bbf21555SRichard Loweline itself; on following lines, only the 1935bbf21555SRichard Lowe.Ic \&Ta 1936bbf21555SRichard Lowemacro can be used to delimit cells, and portability requires that 1937bbf21555SRichard Lowe.Ic \&Ta 1938bbf21555SRichard Loweis called by other macros: some parsers do not recognize it when 1939bbf21555SRichard Loweit appears as the first macro on a line. 1940bbf21555SRichard Lowe.Pp 1941bbf21555SRichard LoweNote that quoted strings may span tab-delimited cells on an 1942bbf21555SRichard Lowe.Ic \&It 1943bbf21555SRichard Loweline. 1944bbf21555SRichard LoweFor example, 1945bbf21555SRichard Lowe.Pp 1946bbf21555SRichard Lowe.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; 1947bbf21555SRichard Lowe.Pp 1948bbf21555SRichard Lowewill preserve the whitespace before both commas, 1949bbf21555SRichard Lowebut not the whitespace before the semicolon. 1950bbf21555SRichard Lowe.Pp 1951bbf21555SRichard LoweSee also 1952bbf21555SRichard Lowe.Ic \&Bl . 1953bbf21555SRichard Lowe.Tg Lb 1954bbf21555SRichard Lowe.It Ic \&Lb Cm lib Ns Ar name 1955bbf21555SRichard LoweSpecify a library. 1956bbf21555SRichard Lowe.Pp 1957bbf21555SRichard LoweThe 1958bbf21555SRichard Lowe.Ar name 1959bbf21555SRichard Loweparameter may be a system library, such as 1960bbf21555SRichard Lowe.Cm z 1961bbf21555SRichard Loweor 1962bbf21555SRichard Lowe.Cm pam , 1963bbf21555SRichard Lowein which case a small library description is printed next to the linker 1964bbf21555SRichard Loweinvocation; or a custom library, in which case the library name is 1965bbf21555SRichard Loweprinted in quotes. 1966bbf21555SRichard LoweThis is most commonly used in the 1967bbf21555SRichard Lowe.Em SYNOPSIS 1968bbf21555SRichard Lowesection as described in 1969bbf21555SRichard Lowe.Sx MANUAL STRUCTURE . 1970bbf21555SRichard Lowe.Pp 1971bbf21555SRichard LoweExamples: 1972bbf21555SRichard Lowe.Dl \&.Lb libz 1973bbf21555SRichard Lowe.Dl \&.Lb libmandoc 1974bbf21555SRichard Lowe.Tg Li 1975bbf21555SRichard Lowe.It Ic \&Li Ar word ... 1976bbf21555SRichard LoweRequest a typewriter (literal) font. 1977bbf21555SRichard LoweDeprecated because on terminal output devices, this is usually 1978bbf21555SRichard Loweindistinguishable from normal text. 1979bbf21555SRichard LoweFor literal displays, use 1980bbf21555SRichard Lowe.Ic \&Ql Pq in-line , 1981bbf21555SRichard Lowe.Ic \&Dl Pq single line , 1982bbf21555SRichard Loweor 1983bbf21555SRichard Lowe.Ic \&Bd Fl literal Pq multi-line 1984bbf21555SRichard Loweinstead. 1985bbf21555SRichard Lowe.Tg Lk 1986bbf21555SRichard Lowe.It Ic \&Lk Ar uri Op Ar display_name 1987bbf21555SRichard LoweFormat a hyperlink. 1988bbf21555SRichard Lowe.Pp 1989bbf21555SRichard LoweExamples: 1990bbf21555SRichard Lowe.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq 1991bbf21555SRichard Lowe.Dl \&.Lk https://bsd.lv 1992bbf21555SRichard Lowe.Pp 1993bbf21555SRichard LoweSee also 1994bbf21555SRichard Lowe.Ic \&Mt . 1995bbf21555SRichard Lowe.It Ic \&Lp 1996bbf21555SRichard LoweDeprecated synonym for 1997bbf21555SRichard Lowe.Ic \&Pp . 1998bbf21555SRichard Lowe.Tg Ms 1999bbf21555SRichard Lowe.It Ic \&Ms Ar name 2000bbf21555SRichard LoweDisplay a mathematical symbol. 2001bbf21555SRichard Lowe.Pp 2002bbf21555SRichard LoweExamples: 2003bbf21555SRichard Lowe.Dl \&.Ms sigma 2004bbf21555SRichard Lowe.Dl \&.Ms aleph 2005bbf21555SRichard Lowe.Tg Mt 2006bbf21555SRichard Lowe.It Ic \&Mt Ar localpart Ns @ Ns Ar domain 2007bbf21555SRichard LoweFormat a 2008bbf21555SRichard Lowe.Dq mailto: 2009bbf21555SRichard Lowehyperlink. 2010bbf21555SRichard Lowe.Pp 2011bbf21555SRichard LoweExamples: 2012bbf21555SRichard Lowe.Dl \&.Mt discuss@manpages.bsd.lv 2013bbf21555SRichard Lowe.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 2014bbf21555SRichard Lowe.Tg Nd 2015bbf21555SRichard Lowe.It Ic \&Nd Ar line 2016bbf21555SRichard LoweA one line description of the manual's content. 2017bbf21555SRichard LoweThis is the mandatory last macro of the 2018bbf21555SRichard Lowe.Em NAME 2019bbf21555SRichard Lowesection and not appropriate for other sections. 2020bbf21555SRichard Lowe.Pp 2021bbf21555SRichard LoweExamples: 2022bbf21555SRichard Lowe.Dl Pf . Ic \&Nd mdoc language reference 2023bbf21555SRichard Lowe.Dl Pf . Ic \&Nd format and display UNIX manuals 2024bbf21555SRichard Lowe.Pp 2025bbf21555SRichard LoweThe 2026bbf21555SRichard Lowe.Ic \&Nd 2027bbf21555SRichard Lowemacro technically accepts child macros and terminates with a subsequent 2028bbf21555SRichard Lowe.Ic \&Sh 2029bbf21555SRichard Loweinvocation. 2030bbf21555SRichard LoweDo not assume this behaviour: some 2031bbf21555SRichard Lowe.Xr whatis 1 2032bbf21555SRichard Lowedatabase generators are not smart enough to parse more than the line 2033bbf21555SRichard Lowearguments and will display macros verbatim. 2034bbf21555SRichard Lowe.Pp 2035bbf21555SRichard LoweSee also 2036bbf21555SRichard Lowe.Ic \&Nm . 2037bbf21555SRichard Lowe.Tg Nm 2038bbf21555SRichard Lowe.It Ic \&Nm Op Ar name 2039bbf21555SRichard LoweThe name of the manual page, or \(em in particular in section 1 2040bbf21555SRichard Lowepages \(em of an additional command or feature documented in 2041bbf21555SRichard Lowethe manual page. 2042bbf21555SRichard LoweWhen first invoked, the 2043bbf21555SRichard Lowe.Ic \&Nm 2044bbf21555SRichard Lowemacro expects a single argument, the name of the manual page. 2045bbf21555SRichard LoweUsually, the first invocation happens in the 2046bbf21555SRichard Lowe.Em NAME 2047bbf21555SRichard Lowesection of the page. 2048bbf21555SRichard LoweThe specified name will be remembered and used whenever the macro is 2049bbf21555SRichard Lowecalled again without arguments later in the page. 2050bbf21555SRichard LoweThe 2051bbf21555SRichard Lowe.Ic \&Nm 2052bbf21555SRichard Lowemacro uses 2053bbf21555SRichard Lowe.Sx Block full-implicit 2054bbf21555SRichard Lowesemantics when invoked as the first macro on an input line in the 2055bbf21555SRichard Lowe.Em SYNOPSIS 2056bbf21555SRichard Lowesection; otherwise, it uses ordinary 2057bbf21555SRichard Lowe.Sx In-line 2058bbf21555SRichard Lowesemantics. 2059bbf21555SRichard Lowe.Pp 2060bbf21555SRichard LoweExamples: 2061bbf21555SRichard Lowe.Bd -literal -offset indent 2062bbf21555SRichard Lowe\&.Sh SYNOPSIS 2063bbf21555SRichard Lowe\&.Nm cat 2064bbf21555SRichard Lowe\&.Op Fl benstuv 2065bbf21555SRichard Lowe\&.Op Ar 2066bbf21555SRichard Lowe.Ed 2067bbf21555SRichard Lowe.Pp 2068bbf21555SRichard LoweIn the 2069bbf21555SRichard Lowe.Em SYNOPSIS 2070bbf21555SRichard Loweof section 2, 3 and 9 manual pages, use the 2071bbf21555SRichard Lowe.Ic \&Fn 2072bbf21555SRichard Lowemacro rather than 2073bbf21555SRichard Lowe.Ic \&Nm 2074bbf21555SRichard Loweto mark up the name of the manual page. 2075bbf21555SRichard Lowe.Tg No 2076bbf21555SRichard Lowe.It Ic \&No Ar word ... 2077bbf21555SRichard LoweNormal text. 2078bbf21555SRichard LoweCloses the scope of any preceding in-line macro. 2079bbf21555SRichard LoweWhen used after physical formatting macros like 2080bbf21555SRichard Lowe.Ic \&Em 2081bbf21555SRichard Loweor 2082bbf21555SRichard Lowe.Ic \&Sy , 2083bbf21555SRichard Loweswitches back to the standard font face and weight. 2084bbf21555SRichard LoweCan also be used to embed plain text strings in macro lines 2085bbf21555SRichard Loweusing semantic annotation macros. 2086bbf21555SRichard Lowe.Pp 2087bbf21555SRichard LoweExamples: 2088bbf21555SRichard Lowe.Dl ".Em italic , Sy bold , No and roman" 2089bbf21555SRichard Lowe.Bd -literal -offset indent 2090bbf21555SRichard Lowe\&.Sm off 2091bbf21555SRichard Lowe\&.Cm :C No / Ar pattern No / Ar replacement No / 2092bbf21555SRichard Lowe\&.Sm on 2093bbf21555SRichard Lowe.Ed 2094bbf21555SRichard Lowe.Pp 2095bbf21555SRichard LoweSee also 2096bbf21555SRichard Lowe.Ic \&Em , 2097bbf21555SRichard Lowe.Ic \&Ql , 2098bbf21555SRichard Loweand 2099bbf21555SRichard Lowe.Ic \&Sy . 2100bbf21555SRichard Lowe.Tg Ns 2101bbf21555SRichard Lowe.It Ic \&Ns 2102bbf21555SRichard LoweSuppress a space between the output of the preceding macro 2103bbf21555SRichard Loweand the following text or macro. 2104bbf21555SRichard LoweFollowing invocation, input is interpreted as normal text 2105bbf21555SRichard Lowejust like after an 2106bbf21555SRichard Lowe.Ic \&No 2107bbf21555SRichard Lowemacro. 2108bbf21555SRichard Lowe.Pp 2109bbf21555SRichard LoweThis has no effect when invoked at the start of a macro line. 2110bbf21555SRichard Lowe.Pp 2111bbf21555SRichard LoweExamples: 2112bbf21555SRichard Lowe.Dl ".Ar name Ns = Ns Ar value" 2113bbf21555SRichard Lowe.Dl ".Cm :M Ns Ar pattern" 2114bbf21555SRichard Lowe.Dl ".Fl o Ns Ar output" 2115bbf21555SRichard Lowe.Pp 2116bbf21555SRichard LoweSee also 2117bbf21555SRichard Lowe.Ic \&No 2118bbf21555SRichard Loweand 2119bbf21555SRichard Lowe.Ic \&Sm . 2120bbf21555SRichard Lowe.Tg Nx 2121bbf21555SRichard Lowe.It Ic \&Nx Op Ar version 2122bbf21555SRichard LoweFormat the 2123bbf21555SRichard Lowe.Nx 2124bbf21555SRichard Loweversion provided as an argument, or a default value if 2125bbf21555SRichard Loweno argument is provided. 2126bbf21555SRichard Lowe.Pp 2127bbf21555SRichard LoweExamples: 2128bbf21555SRichard Lowe.Dl \&.Nx 5.01 2129bbf21555SRichard Lowe.Dl \&.Nx 2130bbf21555SRichard Lowe.Pp 2131bbf21555SRichard LoweSee also 2132bbf21555SRichard Lowe.Ic \&At , 2133bbf21555SRichard Lowe.Ic \&Bsx , 2134bbf21555SRichard Lowe.Ic \&Bx , 2135bbf21555SRichard Lowe.Ic \&Dx , 2136bbf21555SRichard Lowe.Ic \&Fx , 2137bbf21555SRichard Loweand 2138bbf21555SRichard Lowe.Ic \&Ox . 2139bbf21555SRichard Lowe.It Ic \&Oc 2140bbf21555SRichard LoweClose multi-line 2141bbf21555SRichard Lowe.Ic \&Oo 2142bbf21555SRichard Lowecontext. 2143bbf21555SRichard Lowe.It Ic \&Oo Ar block 2144bbf21555SRichard LoweMulti-line version of 2145bbf21555SRichard Lowe.Ic \&Op . 2146bbf21555SRichard Lowe.Pp 2147bbf21555SRichard LoweExamples: 2148bbf21555SRichard Lowe.Bd -literal -offset indent -compact 2149bbf21555SRichard Lowe\&.Oo 2150bbf21555SRichard Lowe\&.Op Fl flag Ns Ar value 2151bbf21555SRichard Lowe\&.Oc 2152bbf21555SRichard Lowe.Ed 2153bbf21555SRichard Lowe.Tg Op 2154bbf21555SRichard Lowe.It Ic \&Op Ar line 2155bbf21555SRichard LoweOptional part of a command line. 2156bbf21555SRichard LowePrints the argument(s) in brackets. 2157bbf21555SRichard LoweThis is most often used in the 2158bbf21555SRichard Lowe.Em SYNOPSIS 2159bbf21555SRichard Lowesection of section 1 and 8 manual pages. 2160bbf21555SRichard Lowe.Pp 2161bbf21555SRichard LoweExamples: 2162bbf21555SRichard Lowe.Dl \&.Op \&Fl a \&Ar b 2163bbf21555SRichard Lowe.Dl \&.Op \&Ar a | b 2164bbf21555SRichard Lowe.Pp 2165bbf21555SRichard LoweSee also 2166bbf21555SRichard Lowe.Ic \&Oo . 2167bbf21555SRichard Lowe.Tg Os 2168bbf21555SRichard Lowe.It Ic \&Os Op Ar system Op Ar version 2169bbf21555SRichard LoweOperating system version for display in the page footer. 2170bbf21555SRichard LoweThis is the mandatory third macro of 2171bbf21555SRichard Loweany 2172bbf21555SRichard Lowe.Nm 2173bbf21555SRichard Lowefile. 2174bbf21555SRichard Lowe.Pp 2175bbf21555SRichard LoweThe optional 2176bbf21555SRichard Lowe.Ar system 2177bbf21555SRichard Loweparameter specifies the relevant operating system or environment. 2178bbf21555SRichard LoweIt is suggested to leave it unspecified, in which case 2179bbf21555SRichard Lowe.Xr mandoc 1 2180bbf21555SRichard Loweuses its 2181bbf21555SRichard Lowe.Fl Ios 2182bbf21555SRichard Loweargument or, if that isn't specified either, 2183bbf21555SRichard Lowe.Fa sysname 2184bbf21555SRichard Loweand 2185bbf21555SRichard Lowe.Fa release 2186bbf21555SRichard Loweas returned by 2187*c55633c3SPeter Tribble.Xr uname 2 . 2188bbf21555SRichard Lowe.Pp 2189bbf21555SRichard LoweExamples: 2190bbf21555SRichard Lowe.Dl \&.Os 2191bbf21555SRichard Lowe.Dl \&.Os KTH/CSC/TCS 2192bbf21555SRichard Lowe.Dl \&.Os BSD 4.3 2193bbf21555SRichard Lowe.Pp 2194bbf21555SRichard LoweSee also 2195bbf21555SRichard Lowe.Ic \&Dd 2196bbf21555SRichard Loweand 2197bbf21555SRichard Lowe.Ic \&Dt . 2198bbf21555SRichard Lowe.It Ic \&Ot Ar functype 2199bbf21555SRichard LoweThis macro is obsolete. 2200bbf21555SRichard LoweUse 2201bbf21555SRichard Lowe.Ic \&Ft 2202bbf21555SRichard Loweinstead; with 2203bbf21555SRichard Lowe.Xr mandoc 1 , 2204bbf21555SRichard Loweboth have the same effect. 2205bbf21555SRichard Lowe.Pp 2206bbf21555SRichard LoweHistorical 2207bbf21555SRichard Lowe.Nm 2208bbf21555SRichard Lowepackages described it as 2209bbf21555SRichard Lowe.Dq "old function type (FORTRAN)" . 2210bbf21555SRichard Lowe.Tg Ox 2211bbf21555SRichard Lowe.It Ic \&Ox Op Ar version 2212bbf21555SRichard LoweFormat the 2213bbf21555SRichard Lowe.Ox 2214bbf21555SRichard Loweversion provided as an argument, or a default value 2215bbf21555SRichard Loweif no argument is provided. 2216bbf21555SRichard Lowe.Pp 2217bbf21555SRichard LoweExamples: 2218bbf21555SRichard Lowe.Dl \&.Ox 4.5 2219bbf21555SRichard Lowe.Dl \&.Ox 2220bbf21555SRichard Lowe.Pp 2221bbf21555SRichard LoweSee also 2222bbf21555SRichard Lowe.Ic \&At , 2223bbf21555SRichard Lowe.Ic \&Bsx , 2224bbf21555SRichard Lowe.Ic \&Bx , 2225bbf21555SRichard Lowe.Ic \&Dx , 2226bbf21555SRichard Lowe.Ic \&Fx , 2227bbf21555SRichard Loweand 2228bbf21555SRichard Lowe.Ic \&Nx . 2229bbf21555SRichard Lowe.Tg Pa 2230bbf21555SRichard Lowe.It Ic \&Pa Ar name ... 2231bbf21555SRichard LoweAn absolute or relative file system path, or a file or directory name. 2232bbf21555SRichard LoweIf an argument is not provided, the character 2233bbf21555SRichard Lowe.Sq \(ti 2234bbf21555SRichard Loweis used as a default. 2235bbf21555SRichard Lowe.Pp 2236bbf21555SRichard LoweExamples: 2237bbf21555SRichard Lowe.Dl \&.Pa /usr/bin/mandoc 2238bbf21555SRichard Lowe.Dl \&.Pa /usr/share/man/man5/mdoc.5 2239bbf21555SRichard Lowe.Pp 2240bbf21555SRichard LoweSee also 2241bbf21555SRichard Lowe.Ic \&Lk . 2242bbf21555SRichard Lowe.It Ic \&Pc 2243bbf21555SRichard LoweClose parenthesised context opened by 2244bbf21555SRichard Lowe.Ic \&Po . 2245bbf21555SRichard Lowe.Tg Pf 2246bbf21555SRichard Lowe.It Ic \&Pf Ar prefix macro Op Ar argument ... 2247bbf21555SRichard LoweRemoves the space between its argument and the following macro. 2248bbf21555SRichard LoweIt is equivalent to: 2249bbf21555SRichard Lowe.Pp 2250bbf21555SRichard Lowe.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... 2251bbf21555SRichard Lowe.Pp 2252bbf21555SRichard LoweThe 2253bbf21555SRichard Lowe.Ar prefix 2254bbf21555SRichard Loweargument is not parsed for macro names or delimiters, 2255bbf21555SRichard Lowebut used verbatim as if it were escaped. 2256bbf21555SRichard Lowe.Pp 2257bbf21555SRichard LoweExamples: 2258bbf21555SRichard Lowe.Dl ".Pf $ Ar variable_name" 2259bbf21555SRichard Lowe.Dl ".Pf . Ar macro_name" 2260bbf21555SRichard Lowe.Dl ".Pf 0x Ar hex_digits" 2261bbf21555SRichard Lowe.Pp 2262bbf21555SRichard LoweSee also 2263bbf21555SRichard Lowe.Ic \&Ns 2264bbf21555SRichard Loweand 2265bbf21555SRichard Lowe.Ic \&Sm . 2266bbf21555SRichard Lowe.It Ic \&Po Ar block 2267bbf21555SRichard LoweMulti-line version of 2268bbf21555SRichard Lowe.Ic \&Pq . 2269bbf21555SRichard Lowe.Tg Pp 2270bbf21555SRichard Lowe.It Ic \&Pp 2271bbf21555SRichard LoweBreak a paragraph. 2272bbf21555SRichard LoweThis will assert vertical space between prior and subsequent macros 2273bbf21555SRichard Loweand/or text. 2274bbf21555SRichard Lowe.Pp 2275bbf21555SRichard LoweParagraph breaks are not needed before or after 2276bbf21555SRichard Lowe.Ic \&Sh 2277bbf21555SRichard Loweor 2278bbf21555SRichard Lowe.Ic \&Ss 2279bbf21555SRichard Lowemacros or before displays 2280bbf21555SRichard Lowe.Pq Ic \&Bd Ar line 2281bbf21555SRichard Loweor lists 2282bbf21555SRichard Lowe.Pq Ic \&Bl 2283bbf21555SRichard Loweunless the 2284bbf21555SRichard Lowe.Fl compact 2285bbf21555SRichard Loweflag is given. 2286bbf21555SRichard Lowe.Tg Pq 2287bbf21555SRichard Lowe.It Ic \&Pq Ar line 2288bbf21555SRichard LoweParenthesised enclosure. 2289bbf21555SRichard Lowe.Pp 2290bbf21555SRichard LoweSee also 2291bbf21555SRichard Lowe.Ic \&Po . 2292bbf21555SRichard Lowe.It Ic \&Qc 2293bbf21555SRichard LoweClose quoted context opened by 2294bbf21555SRichard Lowe.Ic \&Qo . 2295bbf21555SRichard Lowe.Tg Ql 2296bbf21555SRichard Lowe.It Ic \&Ql Ar line 2297bbf21555SRichard LoweIn-line literal display. 2298bbf21555SRichard LoweThis can be used for complete command invocations and for multi-word 2299bbf21555SRichard Lowecode examples when an indented display is not desired. 2300bbf21555SRichard Lowe.Pp 2301bbf21555SRichard LoweSee also 2302bbf21555SRichard Lowe.Ic \&Dl 2303bbf21555SRichard Loweand 2304bbf21555SRichard Lowe.Ic \&Bd 2305bbf21555SRichard Lowe.Fl literal . 2306bbf21555SRichard Lowe.It Ic \&Qo Ar block 2307bbf21555SRichard LoweMulti-line version of 2308bbf21555SRichard Lowe.Ic \&Qq . 2309bbf21555SRichard Lowe.Tg Qq 2310bbf21555SRichard Lowe.It Ic \&Qq Ar line 2311bbf21555SRichard LoweEncloses its arguments in 2312bbf21555SRichard Lowe.Qq typewriter 2313bbf21555SRichard Lowedouble-quotes. 2314bbf21555SRichard LoweConsider using 2315bbf21555SRichard Lowe.Ic \&Dq . 2316bbf21555SRichard Lowe.Pp 2317bbf21555SRichard LoweSee also 2318bbf21555SRichard Lowe.Ic \&Dq , 2319bbf21555SRichard Lowe.Ic \&Sq , 2320bbf21555SRichard Loweand 2321bbf21555SRichard Lowe.Ic \&Qo . 2322bbf21555SRichard Lowe.It Ic \&Re 2323bbf21555SRichard LoweClose an 2324bbf21555SRichard Lowe.Ic \&Rs 2325bbf21555SRichard Loweblock. 2326bbf21555SRichard LoweDoes not have any tail arguments. 2327bbf21555SRichard Lowe.Tg Rs 2328bbf21555SRichard Lowe.It Ic \&Rs 2329bbf21555SRichard LoweBegin a bibliographic 2330bbf21555SRichard Lowe.Pq Dq reference 2331bbf21555SRichard Loweblock. 2332bbf21555SRichard LoweDoes not have any head arguments. 2333bbf21555SRichard LoweThe block macro may only contain 2334bbf21555SRichard Lowe.Ic \&%A , 2335bbf21555SRichard Lowe.Ic \&%B , 2336bbf21555SRichard Lowe.Ic \&%C , 2337bbf21555SRichard Lowe.Ic \&%D , 2338bbf21555SRichard Lowe.Ic \&%I , 2339bbf21555SRichard Lowe.Ic \&%J , 2340bbf21555SRichard Lowe.Ic \&%N , 2341bbf21555SRichard Lowe.Ic \&%O , 2342bbf21555SRichard Lowe.Ic \&%P , 2343bbf21555SRichard Lowe.Ic \&%Q , 2344bbf21555SRichard Lowe.Ic \&%R , 2345bbf21555SRichard Lowe.Ic \&%T , 2346bbf21555SRichard Lowe.Ic \&%U , 2347bbf21555SRichard Loweand 2348bbf21555SRichard Lowe.Ic \&%V 2349bbf21555SRichard Lowechild macros (at least one must be specified). 2350bbf21555SRichard Lowe.Pp 2351bbf21555SRichard LoweExamples: 2352bbf21555SRichard Lowe.Bd -literal -offset indent -compact 2353bbf21555SRichard Lowe\&.Rs 2354bbf21555SRichard Lowe\&.%A J. E. Hopcroft 2355bbf21555SRichard Lowe\&.%A J. D. Ullman 2356bbf21555SRichard Lowe\&.%B Introduction to Automata Theory, Languages, and Computation 2357bbf21555SRichard Lowe\&.%I Addison-Wesley 2358bbf21555SRichard Lowe\&.%C Reading, Massachusetts 2359bbf21555SRichard Lowe\&.%D 1979 2360bbf21555SRichard Lowe\&.Re 2361bbf21555SRichard Lowe.Ed 2362bbf21555SRichard Lowe.Pp 2363bbf21555SRichard LoweIf an 2364bbf21555SRichard Lowe.Ic \&Rs 2365bbf21555SRichard Loweblock is used within a SEE ALSO section, a vertical space is asserted 2366bbf21555SRichard Lowebefore the rendered output, else the block continues on the current 2367bbf21555SRichard Loweline. 2368bbf21555SRichard Lowe.Tg Rv 2369bbf21555SRichard Lowe.It Ic \&Rv Fl std Op Ar function ... 2370bbf21555SRichard LoweInsert a standard sentence regarding a function call's return value of 0 2371bbf21555SRichard Loweon success and \-1 on error, with the 2372bbf21555SRichard Lowe.Va errno 2373bbf21555SRichard Lowelibc global variable set on error. 2374bbf21555SRichard Lowe.Pp 2375bbf21555SRichard LoweIf 2376bbf21555SRichard Lowe.Ar function 2377bbf21555SRichard Loweis not specified, the document's name set by 2378bbf21555SRichard Lowe.Ic \&Nm 2379bbf21555SRichard Loweis used. 2380bbf21555SRichard LoweMultiple 2381bbf21555SRichard Lowe.Ar function 2382bbf21555SRichard Lowearguments are treated as separate functions. 2383bbf21555SRichard Lowe.Pp 2384bbf21555SRichard LoweSee also 2385bbf21555SRichard Lowe.Ic \&Ex . 2386bbf21555SRichard Lowe.It Ic \&Sc 2387bbf21555SRichard LoweClose single-quoted context opened by 2388bbf21555SRichard Lowe.Ic \&So . 2389bbf21555SRichard Lowe.Tg Sh 2390bbf21555SRichard Lowe.It Ic \&Sh Ar TITLE LINE 2391bbf21555SRichard LoweBegin a new section. 2392bbf21555SRichard LoweFor a list of conventional manual sections, see 2393bbf21555SRichard Lowe.Sx MANUAL STRUCTURE . 2394bbf21555SRichard LoweThese sections should be used unless it's absolutely necessary that 2395bbf21555SRichard Lowecustom sections be used. 2396bbf21555SRichard Lowe.Pp 2397bbf21555SRichard LoweSection names should be unique so that they may be keyed by 2398bbf21555SRichard Lowe.Ic \&Sx . 2399bbf21555SRichard LoweAlthough this macro is parsed, it should not consist of child node or it 2400bbf21555SRichard Lowemay not be linked with 2401bbf21555SRichard Lowe.Ic \&Sx . 2402bbf21555SRichard Lowe.Pp 2403bbf21555SRichard LoweSee also 2404bbf21555SRichard Lowe.Ic \&Pp , 2405bbf21555SRichard Lowe.Ic \&Ss , 2406bbf21555SRichard Loweand 2407bbf21555SRichard Lowe.Ic \&Sx . 2408bbf21555SRichard Lowe.Tg Sm 2409bbf21555SRichard Lowe.It Ic \&Sm Op Cm on | off 2410bbf21555SRichard LoweSwitches the spacing mode for output generated from macros. 2411bbf21555SRichard Lowe.Pp 2412bbf21555SRichard LoweBy default, spacing is 2413bbf21555SRichard Lowe.Cm on . 2414bbf21555SRichard LoweWhen switched 2415bbf21555SRichard Lowe.Cm off , 2416bbf21555SRichard Loweno white space is inserted between macro arguments and between the 2417bbf21555SRichard Loweoutput generated from adjacent macros, but text lines 2418bbf21555SRichard Lowestill get normal spacing between words and sentences. 2419bbf21555SRichard Lowe.Pp 2420bbf21555SRichard LoweWhen called without an argument, the 2421bbf21555SRichard Lowe.Ic \&Sm 2422bbf21555SRichard Lowemacro toggles the spacing mode. 2423bbf21555SRichard LoweUsing this is not recommended because it makes the code harder to read. 2424bbf21555SRichard Lowe.It Ic \&So Ar block 2425bbf21555SRichard LoweMulti-line version of 2426bbf21555SRichard Lowe.Ic \&Sq . 2427bbf21555SRichard Lowe.Tg Sq 2428bbf21555SRichard Lowe.It Ic \&Sq Ar line 2429bbf21555SRichard LoweEncloses its arguments in 2430bbf21555SRichard Lowe.Sq typewriter 2431bbf21555SRichard Lowesingle-quotes. 2432bbf21555SRichard Lowe.Pp 2433bbf21555SRichard LoweSee also 2434bbf21555SRichard Lowe.Ic \&Dq , 2435bbf21555SRichard Lowe.Ic \&Qq , 2436bbf21555SRichard Loweand 2437bbf21555SRichard Lowe.Ic \&So . 2438bbf21555SRichard Lowe.Tg Ss 2439bbf21555SRichard Lowe.It Ic \&Ss Ar Title line 2440bbf21555SRichard LoweBegin a new subsection. 2441bbf21555SRichard LoweUnlike with 2442bbf21555SRichard Lowe.Ic \&Sh , 2443bbf21555SRichard Lowethere is no convention for the naming of subsections. 2444bbf21555SRichard LoweExcept 2445bbf21555SRichard Lowe.Em DESCRIPTION , 2446bbf21555SRichard Lowethe conventional sections described in 2447bbf21555SRichard Lowe.Sx MANUAL STRUCTURE 2448bbf21555SRichard Lowerarely have subsections. 2449bbf21555SRichard Lowe.Pp 2450bbf21555SRichard LoweSub-section names should be unique so that they may be keyed by 2451bbf21555SRichard Lowe.Ic \&Sx . 2452bbf21555SRichard LoweAlthough this macro is parsed, it should not consist of child node or it 2453bbf21555SRichard Lowemay not be linked with 2454bbf21555SRichard Lowe.Ic \&Sx . 2455bbf21555SRichard Lowe.Pp 2456bbf21555SRichard LoweSee also 2457bbf21555SRichard Lowe.Ic \&Pp , 2458bbf21555SRichard Lowe.Ic \&Sh , 2459bbf21555SRichard Loweand 2460bbf21555SRichard Lowe.Ic \&Sx . 2461bbf21555SRichard Lowe.Tg St 2462bbf21555SRichard Lowe.It Ic \&St Fl Ns Ar abbreviation 2463bbf21555SRichard LoweReplace an abbreviation for a standard with the full form. 2464bbf21555SRichard LoweThe following standards are recognised. 2465bbf21555SRichard LoweWhere multiple lines are given without a blank line in between, 2466bbf21555SRichard Lowethey all refer to the same standard, and using the first form 2467bbf21555SRichard Loweis recommended. 2468bbf21555SRichard Lowe.Bl -tag -width 1n 2469bbf21555SRichard Lowe.It C language standards 2470bbf21555SRichard Lowe.Pp 2471bbf21555SRichard Lowe.Bl -tag -width "-p1003.1g-2000" -compact 2472bbf21555SRichard Lowe.It \-ansiC 2473bbf21555SRichard Lowe.St -ansiC 2474bbf21555SRichard Lowe.It \-ansiC-89 2475bbf21555SRichard Lowe.St -ansiC-89 2476bbf21555SRichard Lowe.It \-isoC 2477bbf21555SRichard Lowe.St -isoC 2478bbf21555SRichard Lowe.It \-isoC-90 2479bbf21555SRichard Lowe.St -isoC-90 2480bbf21555SRichard Lowe.br 2481bbf21555SRichard LoweThe original C standard. 2482bbf21555SRichard Lowe.Pp 2483bbf21555SRichard Lowe.It \-isoC-amd1 2484bbf21555SRichard Lowe.St -isoC-amd1 2485bbf21555SRichard Lowe.Pp 2486bbf21555SRichard Lowe.It \-isoC-tcor1 2487bbf21555SRichard Lowe.St -isoC-tcor1 2488bbf21555SRichard Lowe.Pp 2489bbf21555SRichard Lowe.It \-isoC-tcor2 2490bbf21555SRichard Lowe.St -isoC-tcor2 2491bbf21555SRichard Lowe.Pp 2492bbf21555SRichard Lowe.It \-isoC-99 2493bbf21555SRichard Lowe.St -isoC-99 2494bbf21555SRichard Lowe.br 2495bbf21555SRichard LoweThe second major version of the C language standard. 2496bbf21555SRichard Lowe.Pp 2497bbf21555SRichard Lowe.It \-isoC-2011 2498bbf21555SRichard Lowe.St -isoC-2011 2499bbf21555SRichard Lowe.br 2500bbf21555SRichard LoweThe third major version of the C language standard. 2501bbf21555SRichard Lowe.El 2502bbf21555SRichard Lowe.It POSIX.1 before the Single UNIX Specification 2503bbf21555SRichard Lowe.Pp 2504bbf21555SRichard Lowe.Bl -tag -width "-p1003.1g-2000" -compact 2505bbf21555SRichard Lowe.It \-p1003.1-88 2506bbf21555SRichard Lowe.St -p1003.1-88 2507bbf21555SRichard Lowe.It \-p1003.1 2508bbf21555SRichard Lowe.St -p1003.1 2509bbf21555SRichard Lowe.br 2510bbf21555SRichard LoweThe original POSIX standard, based on ANSI C. 2511bbf21555SRichard Lowe.Pp 2512bbf21555SRichard Lowe.It \-p1003.1-90 2513bbf21555SRichard Lowe.St -p1003.1-90 2514bbf21555SRichard Lowe.It \-iso9945-1-90 2515bbf21555SRichard Lowe.St -iso9945-1-90 2516bbf21555SRichard Lowe.br 2517bbf21555SRichard LoweThe first update of POSIX.1. 2518bbf21555SRichard Lowe.Pp 2519bbf21555SRichard Lowe.It \-p1003.1b-93 2520bbf21555SRichard Lowe.St -p1003.1b-93 2521bbf21555SRichard Lowe.It \-p1003.1b 2522bbf21555SRichard Lowe.St -p1003.1b 2523bbf21555SRichard Lowe.br 2524bbf21555SRichard LoweReal-time extensions. 2525bbf21555SRichard Lowe.Pp 2526bbf21555SRichard Lowe.It \-p1003.1c-95 2527bbf21555SRichard Lowe.St -p1003.1c-95 2528bbf21555SRichard Lowe.br 2529bbf21555SRichard LowePOSIX thread interfaces. 2530bbf21555SRichard Lowe.Pp 2531bbf21555SRichard Lowe.It \-p1003.1i-95 2532bbf21555SRichard Lowe.St -p1003.1i-95 2533bbf21555SRichard Lowe.br 2534bbf21555SRichard LoweTechnical Corrigendum. 2535bbf21555SRichard Lowe.Pp 2536bbf21555SRichard Lowe.It \-p1003.1-96 2537bbf21555SRichard Lowe.St -p1003.1-96 2538bbf21555SRichard Lowe.It \-iso9945-1-96 2539bbf21555SRichard Lowe.St -iso9945-1-96 2540bbf21555SRichard Lowe.br 2541bbf21555SRichard LoweIncludes POSIX.1-1990, 1b, 1c, and 1i. 2542bbf21555SRichard Lowe.El 2543bbf21555SRichard Lowe.It X/Open Portability Guide version 4 and related standards 2544bbf21555SRichard Lowe.Pp 2545bbf21555SRichard Lowe.Bl -tag -width "-p1003.1g-2000" -compact 2546bbf21555SRichard Lowe.It \-xpg3 2547bbf21555SRichard Lowe.St -xpg3 2548bbf21555SRichard Lowe.br 2549bbf21555SRichard LoweAn XPG4 precursor, published in 1989. 2550bbf21555SRichard Lowe.Pp 2551bbf21555SRichard Lowe.It \-p1003.2 2552bbf21555SRichard Lowe.St -p1003.2 2553bbf21555SRichard Lowe.It \-p1003.2-92 2554bbf21555SRichard Lowe.St -p1003.2-92 2555bbf21555SRichard Lowe.It \-iso9945-2-93 2556bbf21555SRichard Lowe.St -iso9945-2-93 2557bbf21555SRichard Lowe.br 2558bbf21555SRichard LoweAn XCU4 precursor. 2559bbf21555SRichard Lowe.Pp 2560bbf21555SRichard Lowe.It \-p1003.2a-92 2561bbf21555SRichard Lowe.St -p1003.2a-92 2562bbf21555SRichard Lowe.br 2563bbf21555SRichard LoweUpdates to POSIX.2. 2564bbf21555SRichard Lowe.Pp 2565bbf21555SRichard Lowe.It \-xpg4 2566bbf21555SRichard Lowe.St -xpg4 2567bbf21555SRichard Lowe.br 2568bbf21555SRichard LoweBased on POSIX.1 and POSIX.2, published in 1992. 2569bbf21555SRichard Lowe.El 2570bbf21555SRichard Lowe.It Single UNIX Specification version 1 and related standards 2571bbf21555SRichard Lowe.Pp 2572bbf21555SRichard Lowe.Bl -tag -width "-p1003.1g-2000" -compact 2573bbf21555SRichard Lowe.It \-susv1 2574bbf21555SRichard Lowe.St -susv1 2575bbf21555SRichard Lowe.It \-xpg4.2 2576bbf21555SRichard Lowe.St -xpg4.2 2577bbf21555SRichard Lowe.br 2578bbf21555SRichard LoweThis standard was published in 1994. 2579bbf21555SRichard LoweIt was used as the basis for UNIX 95 certification. 2580bbf21555SRichard LoweThe following three refer to parts of it. 2581bbf21555SRichard Lowe.Pp 2582bbf21555SRichard Lowe.It \-xsh4.2 2583bbf21555SRichard Lowe.St -xsh4.2 2584bbf21555SRichard Lowe.Pp 2585bbf21555SRichard Lowe.It \-xcurses4.2 2586bbf21555SRichard Lowe.St -xcurses4.2 2587bbf21555SRichard Lowe.Pp 2588bbf21555SRichard Lowe.It \-p1003.1g-2000 2589bbf21555SRichard Lowe.St -p1003.1g-2000 2590bbf21555SRichard Lowe.br 2591bbf21555SRichard LoweNetworking APIs, including sockets. 2592bbf21555SRichard Lowe.Pp 2593bbf21555SRichard Lowe.It \-svid4 2594bbf21555SRichard Lowe.St -svid4 , 2595bbf21555SRichard Lowe.br 2596bbf21555SRichard LowePublished in 1995. 2597bbf21555SRichard Lowe.El 2598bbf21555SRichard Lowe.It Single UNIX Specification version 2 and related standards 2599bbf21555SRichard Lowe.Pp 2600bbf21555SRichard Lowe.Bl -tag -width "-p1003.1g-2000" -compact 2601bbf21555SRichard Lowe.It \-susv2 2602bbf21555SRichard Lowe.St -susv2 2603bbf21555SRichard LoweThis Standard was published in 1997 2604bbf21555SRichard Loweand is also called X/Open Portability Guide version 5. 2605bbf21555SRichard LoweIt was used as the basis for UNIX 98 certification. 2606bbf21555SRichard LoweThe following refer to parts of it. 2607bbf21555SRichard Lowe.Pp 2608bbf21555SRichard Lowe.It \-xbd5 2609bbf21555SRichard Lowe.St -xbd5 2610bbf21555SRichard Lowe.Pp 2611bbf21555SRichard Lowe.It \-xsh5 2612bbf21555SRichard Lowe.St -xsh5 2613bbf21555SRichard Lowe.Pp 2614bbf21555SRichard Lowe.It \-xcu5 2615bbf21555SRichard Lowe.St -xcu5 2616bbf21555SRichard Lowe.Pp 2617bbf21555SRichard Lowe.It \-xns5 2618bbf21555SRichard Lowe.St -xns5 2619bbf21555SRichard Lowe.It \-xns5.2 2620bbf21555SRichard Lowe.St -xns5.2 2621bbf21555SRichard Lowe.El 2622bbf21555SRichard Lowe.It Single UNIX Specification version 3 2623bbf21555SRichard Lowe.Pp 2624bbf21555SRichard Lowe.Bl -tag -width "-p1003.1-2001" -compact 2625bbf21555SRichard Lowe.It \-p1003.1-2001 2626bbf21555SRichard Lowe.St -p1003.1-2001 2627bbf21555SRichard Lowe.It \-susv3 2628bbf21555SRichard Lowe.St -susv3 2629bbf21555SRichard Lowe.br 2630bbf21555SRichard LoweThis standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. 2631bbf21555SRichard LoweIt is also called X/Open Portability Guide version 6. 2632bbf21555SRichard LoweIt is used as the basis for UNIX 03 certification. 2633bbf21555SRichard Lowe.Pp 2634bbf21555SRichard Lowe.It \-p1003.1-2004 2635bbf21555SRichard Lowe.St -p1003.1-2004 2636bbf21555SRichard Lowe.br 2637bbf21555SRichard LoweThe second and last Technical Corrigendum. 2638bbf21555SRichard Lowe.El 2639bbf21555SRichard Lowe.It Single UNIX Specification version 4 2640bbf21555SRichard Lowe.Pp 2641bbf21555SRichard Lowe.Bl -tag -width "-p1003.1g-2000" -compact 2642bbf21555SRichard Lowe.It \-p1003.1-2008 2643bbf21555SRichard Lowe.St -p1003.1-2008 2644bbf21555SRichard Lowe.It \-susv4 2645bbf21555SRichard Lowe.St -susv4 2646bbf21555SRichard Lowe.br 2647bbf21555SRichard LoweThis standard is also called 2648bbf21555SRichard LoweX/Open Portability Guide version 7. 2649bbf21555SRichard Lowe.El 2650bbf21555SRichard Lowe.It Other standards 2651bbf21555SRichard Lowe.Pp 2652bbf21555SRichard Lowe.Bl -tag -width "-p1003.1g-2000" -compact 2653bbf21555SRichard Lowe.It \-ieee754 2654bbf21555SRichard Lowe.St -ieee754 2655bbf21555SRichard Lowe.br 2656bbf21555SRichard LoweFloating-point arithmetic. 2657bbf21555SRichard Lowe.Pp 2658bbf21555SRichard Lowe.It \-iso8601 2659bbf21555SRichard Lowe.St -iso8601 2660bbf21555SRichard Lowe.br 2661bbf21555SRichard LoweRepresentation of dates and times, published in 1988. 2662bbf21555SRichard Lowe.Pp 2663bbf21555SRichard Lowe.It \-iso8802-3 2664bbf21555SRichard Lowe.St -iso8802-3 2665bbf21555SRichard Lowe.br 2666bbf21555SRichard LoweEthernet local area networks. 2667bbf21555SRichard Lowe.Pp 2668bbf21555SRichard Lowe.It \-ieee1275-94 2669bbf21555SRichard Lowe.St -ieee1275-94 2670bbf21555SRichard Lowe.El 2671bbf21555SRichard Lowe.El 2672bbf21555SRichard Lowe.Tg Sx 2673bbf21555SRichard Lowe.It Ic \&Sx Ar Title line 2674bbf21555SRichard LoweReference a section or subsection in the same manual page. 2675bbf21555SRichard LoweThe referenced section or subsection name must be identical to the 2676bbf21555SRichard Loweenclosed argument, including whitespace. 2677bbf21555SRichard Lowe.Pp 2678bbf21555SRichard LoweExamples: 2679bbf21555SRichard Lowe.Dl \&.Sx MANUAL STRUCTURE 2680bbf21555SRichard Lowe.Pp 2681bbf21555SRichard LoweSee also 2682bbf21555SRichard Lowe.Ic \&Sh 2683bbf21555SRichard Loweand 2684bbf21555SRichard Lowe.Ic \&Ss . 2685bbf21555SRichard Lowe.Tg Sy 2686bbf21555SRichard Lowe.It Ic \&Sy Ar word ... 2687bbf21555SRichard LoweRequest a boldface font. 2688bbf21555SRichard Lowe.Pp 2689bbf21555SRichard LoweThis is most often used to indicate importance or seriousness (not to be 2690bbf21555SRichard Loweconfused with stress emphasis, see 2691bbf21555SRichard Lowe.Ic \&Em ) . 2692bbf21555SRichard LoweWhen none of the semantic macros fit, it is also adequate for syntax 2693bbf21555SRichard Loweelements that have to be given or that appear verbatim. 2694bbf21555SRichard Lowe.Pp 2695bbf21555SRichard LoweExamples: 2696bbf21555SRichard Lowe.Bd -literal -compact -offset indent 2697bbf21555SRichard Lowe\&.Sy Warning : 2698bbf21555SRichard LoweIf 2699bbf21555SRichard Lowe\&.Sy s 2700bbf21555SRichard Loweappears in the owner permissions, set-user-ID mode is set. 2701bbf21555SRichard LoweThis utility replaces the former 2702bbf21555SRichard Lowe\&.Sy dumpdir 2703bbf21555SRichard Loweprogram. 2704bbf21555SRichard Lowe.Ed 2705bbf21555SRichard Lowe.Pp 2706bbf21555SRichard LoweSee also 2707bbf21555SRichard Lowe.Ic \&Em , 2708bbf21555SRichard Lowe.Ic \&No , 2709bbf21555SRichard Loweand 2710bbf21555SRichard Lowe.Ic \&Ql . 2711bbf21555SRichard Lowe.Tg Ta 2712bbf21555SRichard Lowe.It Ic \&Ta 2713bbf21555SRichard LoweTable cell separator in 2714bbf21555SRichard Lowe.Ic \&Bl Fl column 2715bbf21555SRichard Lowelists; can only be used below 2716bbf21555SRichard Lowe.Ic \&It . 2717bbf21555SRichard Lowe.Tg Tg 2718bbf21555SRichard Lowe.It Ic \&Tg Op Ar term 2719bbf21555SRichard LoweAnnounce that the next input line starts a definition of the 2720bbf21555SRichard Lowe.Ar term . 2721bbf21555SRichard LoweThis macro must appear alone on its own input line. 2722bbf21555SRichard LoweThe argument defaults to the first argument of the first macro 2723bbf21555SRichard Loweon the next line. 2724bbf21555SRichard LoweThe argument may not contain whitespace characters, not even when it is quoted. 2725bbf21555SRichard LoweThis macro is a 2726bbf21555SRichard Lowe.Xr mandoc 1 2727bbf21555SRichard Loweextension and is typically ignored by other formatters. 2728bbf21555SRichard Lowe.Pp 2729bbf21555SRichard LoweWhen viewing terminal output with 2730bbf21555SRichard Lowe.Xr less 1 , 2731bbf21555SRichard Lowethe interactive 2732bbf21555SRichard Lowe.Ic :t 2733bbf21555SRichard Lowecommand can be used to go to the definition of the 2734bbf21555SRichard Lowe.Ar term 2735bbf21555SRichard Loweas described for the 2736bbf21555SRichard Lowe.Ev MANPAGER 2737bbf21555SRichard Lowevariable in 2738bbf21555SRichard Lowe.Xr man 1 ; 2739bbf21555SRichard Lowewhen producing HTML output, a fragment identifier 2740bbf21555SRichard Lowe.Pq Ic id No attribute 2741bbf21555SRichard Loweis generated, to be used for deep linking to this place of the document. 2742bbf21555SRichard Lowe.Pp 2743bbf21555SRichard LoweIn most cases, adding a 2744bbf21555SRichard Lowe.Ic \&Tg 2745bbf21555SRichard Lowemacro would be redundant because 2746bbf21555SRichard Lowe.Xr mandoc 1 2747bbf21555SRichard Loweis able to automatically tag most definitions. 2748bbf21555SRichard LoweThis macro is intended for cases where automatic tagging of a 2749bbf21555SRichard Lowe.Ar term 2750bbf21555SRichard Loweis unsatisfactory, for example if a definition is not tagged 2751bbf21555SRichard Loweautomatically (false negative) or if places are tagged that do 2752bbf21555SRichard Lowenot define the 2753bbf21555SRichard Lowe.Ar term 2754bbf21555SRichard Lowe(false positives). 2755bbf21555SRichard LoweWhen there is at least one 2756bbf21555SRichard Lowe.Ic \&Tg 2757bbf21555SRichard Lowemacro for a 2758bbf21555SRichard Lowe.Ar term , 2759bbf21555SRichard Loweno other places are automatically marked as definitions of that 2760bbf21555SRichard Lowe.Ar term . 2761bbf21555SRichard Lowe.It Ic \&Tn Ar word ... 2762bbf21555SRichard LoweSupported only for compatibility, do not use this in new manuals. 2763bbf21555SRichard LoweEven though the macro name 2764bbf21555SRichard Lowe.Pq Dq tradename 2765bbf21555SRichard Lowesuggests a semantic function, historic usage is inconsistent, mostly 2766bbf21555SRichard Loweusing it as a presentation-level macro to request a small caps font. 2767bbf21555SRichard Lowe.It Ic \&Ud 2768bbf21555SRichard LoweSupported only for compatibility, do not use this in new manuals. 2769bbf21555SRichard LowePrints out 2770bbf21555SRichard Lowe.Dq currently under development. 2771bbf21555SRichard Lowe.It Ic \&Ux 2772bbf21555SRichard LoweSupported only for compatibility, do not use this in new manuals. 2773bbf21555SRichard LowePrints out 2774bbf21555SRichard Lowe.Dq Ux . 2775bbf21555SRichard Lowe.Tg Va 2776bbf21555SRichard Lowe.It Ic \&Va Oo Ar type Oc Ar identifier ... 2777bbf21555SRichard LoweA variable name. 2778bbf21555SRichard Lowe.Pp 2779bbf21555SRichard LoweExamples: 2780bbf21555SRichard Lowe.Dl \&.Va foo 2781bbf21555SRichard Lowe.Dl \&.Va const char *bar ; 2782bbf21555SRichard Lowe.Pp 2783bbf21555SRichard LoweFor function arguments and parameters, use 2784bbf21555SRichard Lowe.Ic \&Fa 2785bbf21555SRichard Loweinstead. 2786bbf21555SRichard LoweFor declarations of global variables in the 2787bbf21555SRichard Lowe.Em SYNOPSIS 2788bbf21555SRichard Lowesection, use 2789bbf21555SRichard Lowe.Ic \&Vt . 2790bbf21555SRichard Lowe.Tg Vt 2791bbf21555SRichard Lowe.It Ic \&Vt Ar type Op Ar identifier 2792bbf21555SRichard LoweA variable type. 2793bbf21555SRichard Lowe.Pp 2794bbf21555SRichard LoweThis is also used for indicating global variables in the 2795bbf21555SRichard Lowe.Em SYNOPSIS 2796bbf21555SRichard Lowesection, in which case a variable name is also specified. 2797bbf21555SRichard LoweNote that it accepts 2798bbf21555SRichard Lowe.Sx Block partial-implicit 2799bbf21555SRichard Lowesyntax when invoked as the first macro on an input line in the 2800bbf21555SRichard Lowe.Em SYNOPSIS 2801bbf21555SRichard Lowesection, else it accepts ordinary 2802bbf21555SRichard Lowe.Sx In-line 2803bbf21555SRichard Lowesyntax. 2804bbf21555SRichard LoweIn the former case, this macro starts a new output line, 2805bbf21555SRichard Loweand a blank line is inserted in front if there is a preceding 2806bbf21555SRichard Lowefunction definition or include directive. 2807bbf21555SRichard Lowe.Pp 2808bbf21555SRichard LoweExamples: 2809bbf21555SRichard Lowe.Dl \&.Vt unsigned char 2810bbf21555SRichard Lowe.Dl \&.Vt extern const char * const sys_signame[] \&; 2811bbf21555SRichard Lowe.Pp 2812bbf21555SRichard LoweFor parameters in function prototypes, use 2813bbf21555SRichard Lowe.Ic \&Fa 2814bbf21555SRichard Loweinstead, for function return types 2815bbf21555SRichard Lowe.Ic \&Ft , 2816bbf21555SRichard Loweand for variable names outside the 2817bbf21555SRichard Lowe.Em SYNOPSIS 2818bbf21555SRichard Lowesection 2819bbf21555SRichard Lowe.Ic \&Va , 2820bbf21555SRichard Loweeven when including a type with the name. 2821bbf21555SRichard LoweSee also 2822bbf21555SRichard Lowe.Sx MANUAL STRUCTURE . 2823bbf21555SRichard Lowe.It Ic \&Xc 2824bbf21555SRichard LoweClose a scope opened by 2825bbf21555SRichard Lowe.Ic \&Xo . 2826bbf21555SRichard Lowe.It Ic \&Xo Ar block 2827bbf21555SRichard LoweExtend the header of an 2828bbf21555SRichard Lowe.Ic \&It 2829bbf21555SRichard Lowemacro or the body of a partial-implicit block macro 2830bbf21555SRichard Lowebeyond the end of the input line. 2831bbf21555SRichard LoweThis macro originally existed to work around the 9-argument limit 2832bbf21555SRichard Loweof historic 2833bbf21555SRichard Lowe.Xr mandoc_roff 7 . 2834bbf21555SRichard Lowe.Tg Xr 2835bbf21555SRichard Lowe.It Ic \&Xr Ar name section 2836bbf21555SRichard LoweLink to another manual 2837bbf21555SRichard Lowe.Pq Qq cross-reference . 2838bbf21555SRichard Lowe.Pp 2839bbf21555SRichard LoweCross reference the 2840bbf21555SRichard Lowe.Ar name 2841bbf21555SRichard Loweand 2842bbf21555SRichard Lowe.Ar section 2843bbf21555SRichard Lowenumber of another man page. 2844bbf21555SRichard Lowe.Pp 2845bbf21555SRichard LoweExamples: 2846bbf21555SRichard Lowe.Dl \&.Xr mandoc 1 2847bbf21555SRichard Lowe.Dl \&.Xr mandoc 1 \&; 2848bbf21555SRichard Lowe.Dl \&.Xr mandoc 1 \&Ns s behaviour 2849bbf21555SRichard Lowe.El 2850bbf21555SRichard Lowe.Sh MACRO SYNTAX 2851bbf21555SRichard LoweThe syntax of a macro depends on its classification. 2852bbf21555SRichard LoweIn this section, 2853bbf21555SRichard Lowe.Sq \-arg 2854bbf21555SRichard Lowerefers to macro arguments, which may be followed by zero or more 2855bbf21555SRichard Lowe.Sq parm 2856bbf21555SRichard Loweparameters; 2857bbf21555SRichard Lowe.Sq \&Yo 2858bbf21555SRichard Loweopens the scope of a macro; and if specified, 2859bbf21555SRichard Lowe.Sq \&Yc 2860bbf21555SRichard Lowecloses it out. 2861bbf21555SRichard Lowe.Pp 2862bbf21555SRichard LoweThe 2863bbf21555SRichard Lowe.Em Callable 2864bbf21555SRichard Lowecolumn indicates that the macro may also be called by passing its name 2865bbf21555SRichard Loweas an argument to another macro. 2866bbf21555SRichard LoweFor example, 2867bbf21555SRichard Lowe.Sq \&.Op \&Fl O \&Ar file 2868bbf21555SRichard Loweproduces 2869bbf21555SRichard Lowe.Sq Op Fl O Ar file . 2870bbf21555SRichard LoweTo prevent a macro call and render the macro name literally, 2871bbf21555SRichard Loweescape it by prepending a zero-width space, 2872bbf21555SRichard Lowe.Sq \e& . 2873bbf21555SRichard LoweFor example, 2874bbf21555SRichard Lowe.Sq \&Op \e&Fl O 2875bbf21555SRichard Loweproduces 2876bbf21555SRichard Lowe.Sq Op \&Fl O . 2877bbf21555SRichard LoweIf a macro is not callable but its name appears as an argument 2878bbf21555SRichard Loweto another macro, it is interpreted as opaque text. 2879bbf21555SRichard LoweFor example, 2880bbf21555SRichard Lowe.Sq \&.Fl \&Sh 2881bbf21555SRichard Loweproduces 2882bbf21555SRichard Lowe.Sq Fl \&Sh . 2883bbf21555SRichard Lowe.Pp 2884bbf21555SRichard LoweThe 2885bbf21555SRichard Lowe.Em Parsed 2886bbf21555SRichard Lowecolumn indicates whether the macro may call other macros by receiving 2887bbf21555SRichard Lowetheir names as arguments. 2888bbf21555SRichard LoweIf a macro is not parsed but the name of another macro appears 2889bbf21555SRichard Loweas an argument, it is interpreted as opaque text. 2890bbf21555SRichard Lowe.Pp 2891bbf21555SRichard LoweThe 2892bbf21555SRichard Lowe.Em Scope 2893bbf21555SRichard Lowecolumn, if applicable, describes closure rules. 2894bbf21555SRichard Lowe.Ss Block full-explicit 2895bbf21555SRichard LoweMulti-line scope closed by an explicit closing macro. 2896bbf21555SRichard LoweAll macros contains bodies; only 2897bbf21555SRichard Lowe.Ic \&Bf 2898bbf21555SRichard Loweand 2899bbf21555SRichard Lowe.Pq optionally 2900bbf21555SRichard Lowe.Ic \&Bl 2901bbf21555SRichard Lowecontain a head. 2902bbf21555SRichard Lowe.Bd -literal -offset indent 2903bbf21555SRichard Lowe\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2904bbf21555SRichard Lowe\(lBbody...\(rB 2905bbf21555SRichard Lowe\&.Yc 2906bbf21555SRichard Lowe.Ed 2907bbf21555SRichard Lowe.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent 2908bbf21555SRichard Lowe.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2909bbf21555SRichard Lowe.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed 2910bbf21555SRichard Lowe.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef 2911bbf21555SRichard Lowe.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek 2912bbf21555SRichard Lowe.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El 2913bbf21555SRichard Lowe.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd 2914bbf21555SRichard Lowe.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf 2915bbf21555SRichard Lowe.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk 2916bbf21555SRichard Lowe.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl 2917bbf21555SRichard Lowe.El 2918bbf21555SRichard Lowe.Ss Block full-implicit 2919bbf21555SRichard LoweMulti-line scope closed by end-of-file or implicitly by another macro. 2920bbf21555SRichard LoweAll macros have bodies; some 2921bbf21555SRichard Lowe.Po 2922bbf21555SRichard Lowe.Ic \&It Fl bullet , 2923bbf21555SRichard Lowe.Fl hyphen , 2924bbf21555SRichard Lowe.Fl dash , 2925bbf21555SRichard Lowe.Fl enum , 2926bbf21555SRichard Lowe.Fl item 2927bbf21555SRichard Lowe.Pc 2928bbf21555SRichard Lowedon't have heads; only one 2929bbf21555SRichard Lowe.Po 2930bbf21555SRichard Lowe.Ic \&It 2931bbf21555SRichard Lowein 2932bbf21555SRichard Lowe.Ic \&Bl Fl column 2933bbf21555SRichard Lowe.Pc 2934bbf21555SRichard Lowehas multiple heads. 2935bbf21555SRichard Lowe.Bd -literal -offset indent 2936bbf21555SRichard Lowe\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 2937bbf21555SRichard Lowe\(lBbody...\(rB 2938bbf21555SRichard Lowe.Ed 2939bbf21555SRichard Lowe.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent 2940bbf21555SRichard Lowe.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2941bbf21555SRichard Lowe.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El 2942bbf21555SRichard Lowe.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh 2943bbf21555SRichard Lowe.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss 2944bbf21555SRichard Lowe.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh 2945bbf21555SRichard Lowe.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss 2946bbf21555SRichard Lowe.El 2947bbf21555SRichard Lowe.Pp 2948bbf21555SRichard LoweNote that the 2949bbf21555SRichard Lowe.Ic \&Nm 2950bbf21555SRichard Lowemacro is a 2951bbf21555SRichard Lowe.Sx Block full-implicit 2952bbf21555SRichard Lowemacro only when invoked as the first macro 2953bbf21555SRichard Lowein a 2954bbf21555SRichard Lowe.Em SYNOPSIS 2955bbf21555SRichard Lowesection line, else it is 2956bbf21555SRichard Lowe.Sx In-line . 2957bbf21555SRichard Lowe.Ss Block partial-explicit 2958bbf21555SRichard LoweLike block full-explicit, but also with single-line scope. 2959bbf21555SRichard LoweEach has at least a body and, in limited circumstances, a head 2960bbf21555SRichard Lowe.Po 2961bbf21555SRichard Lowe.Ic \&Fo , 2962bbf21555SRichard Lowe.Ic \&Eo 2963bbf21555SRichard Lowe.Pc 2964bbf21555SRichard Loweand/or tail 2965bbf21555SRichard Lowe.Pq Ic \&Ec . 2966bbf21555SRichard Lowe.Bd -literal -offset indent 2967bbf21555SRichard Lowe\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2968bbf21555SRichard Lowe\(lBbody...\(rB 2969bbf21555SRichard Lowe\&.Yc \(lBtail...\(rB 2970bbf21555SRichard Lowe 2971bbf21555SRichard Lowe\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ 2972bbf21555SRichard Lowe\(lBbody...\(rB \&Yc \(lBtail...\(rB 2973bbf21555SRichard Lowe.Ed 2974bbf21555SRichard Lowe.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2975bbf21555SRichard Lowe.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2976bbf21555SRichard Lowe.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao 2977bbf21555SRichard Lowe.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac 2978bbf21555SRichard Lowe.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo 2979bbf21555SRichard Lowe.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc 2980bbf21555SRichard Lowe.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro 2981bbf21555SRichard Lowe.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc 2982bbf21555SRichard Lowe.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do 2983bbf21555SRichard Lowe.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc 2984bbf21555SRichard Lowe.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo 2985bbf21555SRichard Lowe.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec 2986bbf21555SRichard Lowe.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo 2987bbf21555SRichard Lowe.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc 2988bbf21555SRichard Lowe.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo 2989bbf21555SRichard Lowe.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc 2990bbf21555SRichard Lowe.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po 2991bbf21555SRichard Lowe.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc 2992bbf21555SRichard Lowe.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo 2993bbf21555SRichard Lowe.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc 2994bbf21555SRichard Lowe.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs 2995bbf21555SRichard Lowe.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re 2996bbf21555SRichard Lowe.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So 2997bbf21555SRichard Lowe.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc 2998bbf21555SRichard Lowe.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo 2999bbf21555SRichard Lowe.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc 3000bbf21555SRichard Lowe.El 3001bbf21555SRichard Lowe.Ss Block partial-implicit 3002bbf21555SRichard LoweLike block full-implicit, but with single-line scope closed by the 3003bbf21555SRichard Loweend of the line. 3004bbf21555SRichard Lowe.Bd -literal -offset indent 3005bbf21555SRichard Lowe\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB 3006bbf21555SRichard Lowe.Ed 3007bbf21555SRichard Lowe.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent 3008bbf21555SRichard Lowe.It Em Macro Ta Em Callable Ta Em Parsed 3009bbf21555SRichard Lowe.It Ic \&Aq Ta Yes Ta Yes 3010bbf21555SRichard Lowe.It Ic \&Bq Ta Yes Ta Yes 3011bbf21555SRichard Lowe.It Ic \&Brq Ta Yes Ta Yes 3012bbf21555SRichard Lowe.It Ic \&D1 Ta \&No Ta \&Yes 3013bbf21555SRichard Lowe.It Ic \&Dl Ta \&No Ta Yes 3014bbf21555SRichard Lowe.It Ic \&Dq Ta Yes Ta Yes 3015bbf21555SRichard Lowe.It Ic \&En Ta Yes Ta Yes 3016bbf21555SRichard Lowe.It Ic \&Op Ta Yes Ta Yes 3017bbf21555SRichard Lowe.It Ic \&Pq Ta Yes Ta Yes 3018bbf21555SRichard Lowe.It Ic \&Ql Ta Yes Ta Yes 3019bbf21555SRichard Lowe.It Ic \&Qq Ta Yes Ta Yes 3020bbf21555SRichard Lowe.It Ic \&Sq Ta Yes Ta Yes 3021bbf21555SRichard Lowe.It Ic \&Vt Ta Yes Ta Yes 3022bbf21555SRichard Lowe.El 3023bbf21555SRichard Lowe.Pp 3024bbf21555SRichard LoweNote that the 3025bbf21555SRichard Lowe.Ic \&Vt 3026bbf21555SRichard Lowemacro is a 3027bbf21555SRichard Lowe.Sx Block partial-implicit 3028bbf21555SRichard Loweonly when invoked as the first macro 3029bbf21555SRichard Lowein a 3030bbf21555SRichard Lowe.Em SYNOPSIS 3031bbf21555SRichard Lowesection line, else it is 3032bbf21555SRichard Lowe.Sx In-line . 3033bbf21555SRichard Lowe.Ss Special block macro 3034bbf21555SRichard LoweThe 3035bbf21555SRichard Lowe.Ic \&Ta 3036bbf21555SRichard Lowemacro can only be used below 3037bbf21555SRichard Lowe.Ic \&It 3038bbf21555SRichard Lowein 3039bbf21555SRichard Lowe.Ic \&Bl Fl column 3040bbf21555SRichard Lowelists. 3041bbf21555SRichard LoweIt delimits blocks representing table cells; 3042bbf21555SRichard Lowethese blocks have bodies, but no heads. 3043bbf21555SRichard Lowe.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 3044bbf21555SRichard Lowe.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 3045bbf21555SRichard Lowe.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It 3046bbf21555SRichard Lowe.El 3047bbf21555SRichard Lowe.Ss In-line 3048bbf21555SRichard LoweClosed by the end of the line, fixed argument lengths, 3049bbf21555SRichard Loweand/or subsequent macros. 3050bbf21555SRichard LoweIn-line macros have only text children. 3051bbf21555SRichard LoweIf a number (or inequality) of arguments is 3052bbf21555SRichard Lowe.Pq n , 3053bbf21555SRichard Lowethen the macro accepts an arbitrary number of arguments. 3054bbf21555SRichard Lowe.Bd -literal -offset indent 3055bbf21555SRichard Lowe\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB 3056bbf21555SRichard Lowe 3057bbf21555SRichard Lowe\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... 3058bbf21555SRichard Lowe 3059bbf21555SRichard Lowe\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN 3060bbf21555SRichard Lowe.Ed 3061bbf21555SRichard Lowe.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent 3062bbf21555SRichard Lowe.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments 3063bbf21555SRichard Lowe.It Ic \&%A Ta \&No Ta \&No Ta >0 3064bbf21555SRichard Lowe.It Ic \&%B Ta \&No Ta \&No Ta >0 3065bbf21555SRichard Lowe.It Ic \&%C Ta \&No Ta \&No Ta >0 3066bbf21555SRichard Lowe.It Ic \&%D Ta \&No Ta \&No Ta >0 3067bbf21555SRichard Lowe.It Ic \&%I Ta \&No Ta \&No Ta >0 3068bbf21555SRichard Lowe.It Ic \&%J Ta \&No Ta \&No Ta >0 3069bbf21555SRichard Lowe.It Ic \&%N Ta \&No Ta \&No Ta >0 3070bbf21555SRichard Lowe.It Ic \&%O Ta \&No Ta \&No Ta >0 3071bbf21555SRichard Lowe.It Ic \&%P Ta \&No Ta \&No Ta >0 3072bbf21555SRichard Lowe.It Ic \&%Q Ta \&No Ta \&No Ta >0 3073bbf21555SRichard Lowe.It Ic \&%R Ta \&No Ta \&No Ta >0 3074bbf21555SRichard Lowe.It Ic \&%T Ta \&No Ta \&No Ta >0 3075bbf21555SRichard Lowe.It Ic \&%U Ta \&No Ta \&No Ta >0 3076bbf21555SRichard Lowe.It Ic \&%V Ta \&No Ta \&No Ta >0 3077bbf21555SRichard Lowe.It Ic \&Ad Ta Yes Ta Yes Ta >0 3078bbf21555SRichard Lowe.It Ic \&An Ta Yes Ta Yes Ta >0 3079bbf21555SRichard Lowe.It Ic \&Ap Ta Yes Ta Yes Ta 0 3080bbf21555SRichard Lowe.It Ic \&Ar Ta Yes Ta Yes Ta n 3081bbf21555SRichard Lowe.It Ic \&At Ta Yes Ta Yes Ta 1 3082bbf21555SRichard Lowe.It Ic \&Bsx Ta Yes Ta Yes Ta n 3083bbf21555SRichard Lowe.It Ic \&Bt Ta \&No Ta \&No Ta 0 3084bbf21555SRichard Lowe.It Ic \&Bx Ta Yes Ta Yes Ta n 3085bbf21555SRichard Lowe.It Ic \&Cd Ta Yes Ta Yes Ta >0 3086bbf21555SRichard Lowe.It Ic \&Cm Ta Yes Ta Yes Ta >0 3087bbf21555SRichard Lowe.It Ic \&Db Ta \&No Ta \&No Ta 1 3088bbf21555SRichard Lowe.It Ic \&Dd Ta \&No Ta \&No Ta n 3089bbf21555SRichard Lowe.It Ic \&Dt Ta \&No Ta \&No Ta n 3090bbf21555SRichard Lowe.It Ic \&Dv Ta Yes Ta Yes Ta >0 3091bbf21555SRichard Lowe.It Ic \&Dx Ta Yes Ta Yes Ta n 3092bbf21555SRichard Lowe.It Ic \&Em Ta Yes Ta Yes Ta >0 3093bbf21555SRichard Lowe.It Ic \&Er Ta Yes Ta Yes Ta >0 3094bbf21555SRichard Lowe.It Ic \&Es Ta Yes Ta Yes Ta 2 3095bbf21555SRichard Lowe.It Ic \&Ev Ta Yes Ta Yes Ta >0 3096bbf21555SRichard Lowe.It Ic \&Ex Ta \&No Ta \&No Ta n 3097bbf21555SRichard Lowe.It Ic \&Fa Ta Yes Ta Yes Ta >0 3098bbf21555SRichard Lowe.It Ic \&Fd Ta \&No Ta \&No Ta >0 3099bbf21555SRichard Lowe.It Ic \&Fl Ta Yes Ta Yes Ta n 3100bbf21555SRichard Lowe.It Ic \&Fn Ta Yes Ta Yes Ta >0 3101bbf21555SRichard Lowe.It Ic \&Fr Ta Yes Ta Yes Ta >0 3102bbf21555SRichard Lowe.It Ic \&Ft Ta Yes Ta Yes Ta >0 3103bbf21555SRichard Lowe.It Ic \&Fx Ta Yes Ta Yes Ta n 3104bbf21555SRichard Lowe.It Ic \&Hf Ta \&No Ta \&No Ta n 3105bbf21555SRichard Lowe.It Ic \&Ic Ta Yes Ta Yes Ta >0 3106bbf21555SRichard Lowe.It Ic \&In Ta \&No Ta \&No Ta 1 3107bbf21555SRichard Lowe.It Ic \&Lb Ta \&No Ta \&No Ta 1 3108bbf21555SRichard Lowe.It Ic \&Li Ta Yes Ta Yes Ta >0 3109bbf21555SRichard Lowe.It Ic \&Lk Ta Yes Ta Yes Ta >0 3110bbf21555SRichard Lowe.It Ic \&Lp Ta \&No Ta \&No Ta 0 3111bbf21555SRichard Lowe.It Ic \&Ms Ta Yes Ta Yes Ta >0 3112bbf21555SRichard Lowe.It Ic \&Mt Ta Yes Ta Yes Ta >0 3113bbf21555SRichard Lowe.It Ic \&Nm Ta Yes Ta Yes Ta n 3114bbf21555SRichard Lowe.It Ic \&No Ta Yes Ta Yes Ta >0 3115bbf21555SRichard Lowe.It Ic \&Ns Ta Yes Ta Yes Ta 0 3116bbf21555SRichard Lowe.It Ic \&Nx Ta Yes Ta Yes Ta n 3117bbf21555SRichard Lowe.It Ic \&Os Ta \&No Ta \&No Ta n 3118bbf21555SRichard Lowe.It Ic \&Ot Ta Yes Ta Yes Ta >0 3119bbf21555SRichard Lowe.It Ic \&Ox Ta Yes Ta Yes Ta n 3120bbf21555SRichard Lowe.It Ic \&Pa Ta Yes Ta Yes Ta n 3121bbf21555SRichard Lowe.It Ic \&Pf Ta Yes Ta Yes Ta 1 3122bbf21555SRichard Lowe.It Ic \&Pp Ta \&No Ta \&No Ta 0 3123bbf21555SRichard Lowe.It Ic \&Rv Ta \&No Ta \&No Ta n 3124bbf21555SRichard Lowe.It Ic \&Sm Ta \&No Ta \&No Ta <2 3125bbf21555SRichard Lowe.It Ic \&St Ta \&No Ta Yes Ta 1 3126bbf21555SRichard Lowe.It Ic \&Sx Ta Yes Ta Yes Ta >0 3127bbf21555SRichard Lowe.It Ic \&Sy Ta Yes Ta Yes Ta >0 3128bbf21555SRichard Lowe.It Ic \&Tg Ta \&No Ta \&No Ta <2 3129bbf21555SRichard Lowe.It Ic \&Tn Ta Yes Ta Yes Ta >0 3130bbf21555SRichard Lowe.It Ic \&Ud Ta \&No Ta \&No Ta 0 3131bbf21555SRichard Lowe.It Ic \&Ux Ta Yes Ta Yes Ta n 3132bbf21555SRichard Lowe.It Ic \&Va Ta Yes Ta Yes Ta n 3133bbf21555SRichard Lowe.It Ic \&Vt Ta Yes Ta Yes Ta >0 3134bbf21555SRichard Lowe.It Ic \&Xr Ta Yes Ta Yes Ta 2 3135bbf21555SRichard Lowe.El 3136bbf21555SRichard Lowe.Ss Delimiters 3137bbf21555SRichard LoweWhen a macro argument consists of one single input character 3138bbf21555SRichard Loweconsidered as a delimiter, the argument gets special handling. 3139bbf21555SRichard LoweThis does not apply when delimiters appear in arguments containing 3140bbf21555SRichard Lowemore than one character. 3141bbf21555SRichard LoweConsequently, to prevent special handling and just handle it 3142bbf21555SRichard Lowelike any other argument, a delimiter can be escaped by prepending 3143bbf21555SRichard Lowea zero-width space 3144bbf21555SRichard Lowe.Pq Sq \e& . 3145bbf21555SRichard LoweIn text lines, delimiters never need escaping, but may be used 3146bbf21555SRichard Loweas normal punctuation. 3147bbf21555SRichard Lowe.Pp 3148bbf21555SRichard LoweFor many macros, when the leading arguments are opening delimiters, 3149bbf21555SRichard Lowethese delimiters are put before the macro scope, 3150bbf21555SRichard Loweand when the trailing arguments are closing delimiters, 3151bbf21555SRichard Lowethese delimiters are put after the macro scope. 3152bbf21555SRichard LoweSpacing is suppressed after opening delimiters 3153bbf21555SRichard Loweand before closing delimiters. 3154bbf21555SRichard LoweFor example, 3155bbf21555SRichard Lowe.Pp 3156bbf21555SRichard Lowe.D1 Pf \. \&Aq "( [ word ] ) ." 3157bbf21555SRichard Lowe.Pp 3158bbf21555SRichard Lowerenders as: 3159bbf21555SRichard Lowe.Pp 3160bbf21555SRichard Lowe.D1 Aq ( [ word ] ) . 3161bbf21555SRichard Lowe.Pp 3162bbf21555SRichard LoweOpening delimiters are: 3163bbf21555SRichard Lowe.Pp 3164bbf21555SRichard Lowe.Bl -tag -width Ds -offset indent -compact 3165bbf21555SRichard Lowe.It \&( 3166bbf21555SRichard Loweleft parenthesis 3167bbf21555SRichard Lowe.It \&[ 3168bbf21555SRichard Loweleft bracket 3169bbf21555SRichard Lowe.El 3170bbf21555SRichard Lowe.Pp 3171bbf21555SRichard LoweClosing delimiters are: 3172bbf21555SRichard Lowe.Pp 3173bbf21555SRichard Lowe.Bl -tag -width Ds -offset indent -compact 3174bbf21555SRichard Lowe.It \&. 3175bbf21555SRichard Loweperiod 3176bbf21555SRichard Lowe.It \&, 3177bbf21555SRichard Lowecomma 3178bbf21555SRichard Lowe.It \&: 3179bbf21555SRichard Lowecolon 3180bbf21555SRichard Lowe.It \&; 3181bbf21555SRichard Lowesemicolon 3182bbf21555SRichard Lowe.It \&) 3183bbf21555SRichard Loweright parenthesis 3184bbf21555SRichard Lowe.It \&] 3185bbf21555SRichard Loweright bracket 3186bbf21555SRichard Lowe.It \&? 3187bbf21555SRichard Lowequestion mark 3188bbf21555SRichard Lowe.It \&! 3189bbf21555SRichard Loweexclamation mark 3190bbf21555SRichard Lowe.El 3191bbf21555SRichard Lowe.Pp 3192bbf21555SRichard LoweNote that even a period preceded by a backslash 3193bbf21555SRichard Lowe.Pq Sq \e.\& 3194bbf21555SRichard Lowegets this special handling; use 3195bbf21555SRichard Lowe.Sq \e&.\& 3196bbf21555SRichard Loweto prevent that. 3197bbf21555SRichard Lowe.Pp 3198bbf21555SRichard LoweMany in-line macros interrupt their scope when they encounter 3199bbf21555SRichard Lowedelimiters, and resume their scope when more arguments follow that 3200bbf21555SRichard Loweare not delimiters. 3201bbf21555SRichard LoweFor example, 3202bbf21555SRichard Lowe.Pp 3203bbf21555SRichard Lowe.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" 3204bbf21555SRichard Lowe.Pp 3205bbf21555SRichard Lowerenders as: 3206bbf21555SRichard Lowe.Pp 3207bbf21555SRichard Lowe.D1 Fl a ( b | c \*(Ba d ) e 3208bbf21555SRichard Lowe.Pp 3209bbf21555SRichard LoweThis applies to both opening and closing delimiters, 3210bbf21555SRichard Loweand also to the middle delimiter, which does not suppress spacing: 3211bbf21555SRichard Lowe.Pp 3212bbf21555SRichard Lowe.Bl -tag -width Ds -offset indent -compact 3213bbf21555SRichard Lowe.It \&| 3214bbf21555SRichard Lowevertical bar 3215bbf21555SRichard Lowe.El 3216bbf21555SRichard Lowe.Pp 3217bbf21555SRichard LoweAs a special case, the predefined string \e*(Ba is handled and rendered 3218bbf21555SRichard Lowein the same way as a plain 3219bbf21555SRichard Lowe.Sq \&| 3220bbf21555SRichard Lowecharacter. 3221bbf21555SRichard LoweUsing this predefined string is not recommended in new manuals. 3222bbf21555SRichard Lowe.Pp 3223bbf21555SRichard LoweAppending a zero-width space 3224bbf21555SRichard Lowe.Pq Sq \e& 3225bbf21555SRichard Loweto the end of an input line is also useful to prevent the interpretation 3226bbf21555SRichard Loweof a trailing period, exclamation or question mark as the end of a 3227bbf21555SRichard Lowesentence, for example when an abbreviation happens to occur 3228bbf21555SRichard Loweat the end of a text or macro input line. 3229bbf21555SRichard Lowe.Ss Font handling 3230bbf21555SRichard LoweIn 3231bbf21555SRichard Lowe.Nm 3232bbf21555SRichard Lowedocuments, usage of semantic markup is recommended in order to have 3233bbf21555SRichard Loweproper fonts automatically selected; only when no fitting semantic markup 3234bbf21555SRichard Loweis available, consider falling back to 3235bbf21555SRichard Lowe.Sx Physical markup 3236bbf21555SRichard Lowemacros. 3237bbf21555SRichard LoweWhenever any 3238bbf21555SRichard Lowe.Nm 3239bbf21555SRichard Lowemacro switches the 3240bbf21555SRichard Lowe.Xr mandoc_roff 7 3241bbf21555SRichard Lowefont mode, it will automatically restore the previous font when exiting 3242bbf21555SRichard Loweits scope. 3243bbf21555SRichard LoweManually switching the font using the 3244bbf21555SRichard Lowe.Xr mandoc_roff 7 3245bbf21555SRichard Lowe.Ql \ef 3246bbf21555SRichard Lowefont escape sequences is never required. 3247bbf21555SRichard Lowe.Sh COMPATIBILITY 3248bbf21555SRichard LoweThis section provides an incomplete list of compatibility issues 3249bbf21555SRichard Lowebetween mandoc and GNU troff 3250bbf21555SRichard Lowe.Pq Qq groff . 3251bbf21555SRichard Lowe.Pp 3252bbf21555SRichard LoweThe following problematic behaviour is found in groff: 3253bbf21555SRichard Lowe.Pp 3254bbf21555SRichard Lowe.Bl -dash -compact 3255bbf21555SRichard Lowe.It 3256bbf21555SRichard Lowe.Ic \&Pa 3257bbf21555SRichard Lowedoes not format its arguments when used in the FILES section under 3258bbf21555SRichard Lowecertain list types. 3259bbf21555SRichard Lowe.It 3260bbf21555SRichard Lowe.Ic \&Ta 3261bbf21555SRichard Lowecan only be called by other macros, but not at the beginning of a line. 3262bbf21555SRichard Lowe.It 3263bbf21555SRichard Lowe.Sq \ef 3264bbf21555SRichard Lowe.Pq font face 3265bbf21555SRichard Loweand 3266bbf21555SRichard Lowe.Sq \eF 3267bbf21555SRichard Lowe.Pq font family face 3268bbf21555SRichard Lowe.Sx Text Decoration 3269bbf21555SRichard Loweescapes behave irregularly when specified within line-macro scopes. 3270bbf21555SRichard Lowe.It 3271bbf21555SRichard LoweNegative scaling units return to prior lines. 3272bbf21555SRichard LoweInstead, mandoc truncates them to zero. 3273bbf21555SRichard Lowe.El 3274bbf21555SRichard Lowe.Pp 3275bbf21555SRichard LoweThe following features are unimplemented in mandoc: 3276bbf21555SRichard Lowe.Pp 3277bbf21555SRichard Lowe.Bl -dash -compact 3278bbf21555SRichard Lowe.It 3279bbf21555SRichard Lowe.Ic \&Bd Fl file Ar file 3280bbf21555SRichard Loweis unsupported for security reasons. 3281bbf21555SRichard Lowe.It 3282bbf21555SRichard Lowe.Ic \&Bd 3283bbf21555SRichard Lowe.Fl filled 3284bbf21555SRichard Lowedoes not adjust the right margin, but is an alias for 3285bbf21555SRichard Lowe.Ic \&Bd 3286bbf21555SRichard Lowe.Fl ragged . 3287bbf21555SRichard Lowe.It 3288bbf21555SRichard Lowe.Ic \&Bd 3289bbf21555SRichard Lowe.Fl literal 3290bbf21555SRichard Lowedoes not use a literal font, but is an alias for 3291bbf21555SRichard Lowe.Ic \&Bd 3292bbf21555SRichard Lowe.Fl unfilled . 3293bbf21555SRichard Lowe.It 3294bbf21555SRichard Lowe.Ic \&Bd 3295bbf21555SRichard Lowe.Fl offset Cm center 3296bbf21555SRichard Loweand 3297bbf21555SRichard Lowe.Fl offset Cm right 3298bbf21555SRichard Lowedon't work. 3299bbf21555SRichard LoweGroff does not implement centered and flush-right rendering either, 3300bbf21555SRichard Lowebut produces large indentations. 3301bbf21555SRichard Lowe.El 3302bbf21555SRichard Lowe.Sh SEE ALSO 3303bbf21555SRichard Lowe.Xr man 1 , 3304bbf21555SRichard Lowe.Xr mandoc 1 , 3305bbf21555SRichard Lowe.Xr eqn 7 , 3306bbf21555SRichard Lowe.Xr man 7 , 3307bbf21555SRichard Lowe.Xr mandoc_char 7 , 3308bbf21555SRichard Lowe.Xr mandoc_roff 7 , 3309bbf21555SRichard Lowe.Xr tbl 7 3310bbf21555SRichard Lowe.Pp 3311bbf21555SRichard LoweThe web page 3312bbf21555SRichard Lowe.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" 3313bbf21555SRichard Loweprovides a few tutorial-style pages for beginners, an extensive style 3314bbf21555SRichard Loweguide for advanced authors, and an alphabetic index helping to choose 3315bbf21555SRichard Lowethe best macros for various kinds of content. 3316bbf21555SRichard Lowe.Pp 3317bbf21555SRichard LoweThe manual page 3318bbf21555SRichard Lowe.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(4)" 3319bbf21555SRichard Lowecontained in the 3320bbf21555SRichard Lowe.Dq groff 3321bbf21555SRichard Lowepackage documents exactly the same language in a somewhat different style. 3322bbf21555SRichard Lowe.Sh HISTORY 3323bbf21555SRichard LoweThe 3324bbf21555SRichard Lowe.Nm 3325bbf21555SRichard Lowelanguage first appeared as a troff macro package in 3326bbf21555SRichard Lowe.Bx 4.4 . 3327bbf21555SRichard LoweIt was later significantly updated by Werner Lemberg and Ruslan Ermilov 3328bbf21555SRichard Lowein groff-1.17. 3329bbf21555SRichard LoweThe standalone implementation that is part of the 3330bbf21555SRichard Lowe.Xr mandoc 1 3331bbf21555SRichard Loweutility written by Kristaps Dzonsons appeared in 3332bbf21555SRichard Lowe.Ox 4.6 . 3333bbf21555SRichard Lowe.Sh AUTHORS 3334bbf21555SRichard LoweThe 3335bbf21555SRichard Lowe.Nm 3336bbf21555SRichard Lowereference was written by 3337bbf21555SRichard Lowe.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 3338