1.\" Copyright (c) 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)mdoc.7 1.1 (Berkeley) 08/05/91 7.\" 8.Dd 9.Os 10.Dt MDOC 7 11.Sh NAME 12.Nm mdoc 13.Nd Quick reference guide for the 14.Nm \-mdoc 15macro package 16.Sh SYNOPSIS 17.Nm groff 18.Fl m Ns Ar doc 19.Ar files ... 20.Sh DESCRIPTION 21The 22.Nm \-mdoc 23package is a set of manual page domain content-based macros 24used to format the 25.Bx 26man pages. 27The macro names and their meanings are 28listed below for quick reference; for 29a detailed explanation on using the package, 30see the tutorial sampler 31.Xr mdoc.samples 7 . 32.Pp 33The macros are described in three domain groups, the first 34domain includes the structural and the physical page layout macros. 35The second group contains the manual domain 36content macros which differentiate the 37.Nm -\mdoc 38package from other 39.Xr troff 40formatting packages. 41The manual page domain specific content macros 42are a subset of the day to day language 43used to describe 44.Bx 45commands, functions, devices and files. 46The third group consists of general text 47domain macros which apply to other types of documentation 48as well as manual pages. 49.Sh PAGE STRUCTURAL DOMAIN 50.Ss Title Macros 51To create a valid manual page, these three macros 52required in the order they are presented: 53.Bl -tag -width ".Os OPERATING_SYSTEM [version/release]" -compact 54.It Sy \&.Dd Ar "Month day, year" 55Document date. 56.It Sy \&.Dt Ar "DOCUMENT_TITLE [section] [volume]" 57Title, in upper case. 58.It Sy \&.Os Ar "OPERATING_SYSTEM [version/release]" 59Operating system 60.Pq Tn BSD . 61.El 62.Ss Page Layout Macros 63Section eaders, paragraph breaks, lists and displays. 64.Bl -tag -width flag -compact 65.It Sy \&.Sh Ar HEADER 66Section Header Macro. 67Valid headers, in the order of presentation: 68.Bl -tag -width "RETURN VALUES" -compact 69.It Ar NAME 70Name section, should include the 71.Ql \&.Nm 72or 73.Ql \&.Fn 74and the 75.Ql \&.Nd 76macros. 77.It Ar SYNOPSIS 78Usage. 79.It Ar DESCRIPTION 80General description, should include 81options and parameters. 82.It Ar RETURN VALUES 83Sections two and three function calls. 84.It Ar ENVIRONMENT 85Describe environment variables. 86.It Ar FILES 87Files associated with the subject. 88.It Ar EXAMPLES 89Examples and suggestions. 90.It Ar DIAGNOSTICS 91Normally used for section four device interface diagnostics. 92.It Ar ERRORS 93Sections two and three error and signal 94handling. 95.It Ar SEE ALSO 96Cross references and citations. 97.It Ar STANDARDS 98Conformance to standards if applicable. 99.It Ar HISTORY 100If a standard is not applicable, the history 101of the subject should be given. 102.It Ar BUGS 103Gotchas and caveats. 104.It Ar other 105Customized headers may be added at 106the authors discretion. 107.El 108.It Sy \&.Ss 109Subsection Headers. 110.It Sy \&.Pp 111Paragraph Break. 112Vertical space (one line). 113.It Sy \&.D1 114(D-one) Display-one 115Indent and display one text line. 116.It Sy \&.Dl 117(D-ell) Display-one literal. 118Indent and display one line of literal text. 119.It Sy \&.Bd 120Begin-display of text across one or more lines. 121Requires the end-display macro 122.Ql \&.Ed . 123.Pp 124Display options: 125.Bl -tag -width "xoffset string" -compact 126.It Fl ragged 127Unjustified (ragged edges). 128.It Fl filled 129Justified. 130.It Fl literal 131Literal text or code. 132.It Fl file Ar name 133Read in named 134.Ar file 135and display. 136.It Fl offset Ar string 137Offset (indent) display by the 138width of 139.Ar string 140(or value of register name). 141Known values: 142.Pp 143.Bl -tag -width indent-two -compact 144.It Ar left 145Align block on current left margin (default). 146.It Ar center 147Approximate center margin. 148.It Ar indent 149Six constant width spaces (a tab). 150.It Ar indent-two 151Twelve constant width spaces (two tabs). 152.It Ar right 153Left aligns block about 2 inches from 154right side of page. 155.El 156.El 157.It Sy \&.Ed 158End-display (matches \&.Bd). 159.It Sy \&.Bl 160Begin-list. 161Create lists or columns. 162.Pp 163.Bl -tag -width flag -compact 164.It Ar List-types 165.Bl -column xbullet -compact 166.It Fl bullet Ta "Bullet Item List" 167.It Fl item Ta "Unlabled List" 168.It Fl enum Ta "Enumerated List" 169.It Fl tag Ta "Tag Labeled List" 170.It Fl diag Ta "Diagnostic List" 171.It Fl hang Ta "Hanging Labeled List" 172.It Fl ohang Ta "Overhanging Labeled List" 173.It Fl inset Ta "Inset or Run-on Labeled List" 174.El 175.It List-parameters 176.Bl -tag -width xcompact -compact 177.It Fl offset Ar indent 178(All lists.) 179Offset or indent by 180.Ar indent . 181The 182.Ar indent 183may be expressed as a scaled number 184(12n), a string, a register name or 185the string 186.Li indent 187which represents a tab. 188.It Fl width Ar string 189.Pf ( Fl tag 190and 191.Fl hang 192lists only.) 193The label width is set to the constant width of 194.Ar string . 195The 196.Fl width 197option may be a scaled number 198(20n), a string, 199a register name or the 200string 201.Li indent 202which represents a tab. 203.It Fl compact 204(All lists.) 205Suppresses the insertion of a blank line at the beginning 206of a display and in between each item. 207.It Sy \&.El 208End-list. 209.It Sy \&.It 210List item. 211.El 212.El 213.Sh MANUAL AND GENERAL TEXT DOMAIN MACROS 214The manual and general text domain macros are special in that 215most of them are parsed for callable macros 216for example: 217.Bd -literal -offset indent 218\&.Op Fl s Ar file 219.Ed 220.Pp 221In this example, the option enclosure macro 222.Ql \&.Op 223is parsed, and calls the callable content macro 224.Ql \&Fl 225which operates on the argument 226.Ql s 227and then calls the callable content macro 228.Ql \&Ar 229which operates on the argument 230.Ql file . 231The result is: 232.Pp 233.Dl Op Fl s Ar file 234.Pp 235Some macros may be callable, but are not parsed and vice versa. 236These macros are indicated in the 237.Em parsed 238and 239.Em callable columns below. 240.Pp 241Unless stated, manual page domain macros share a common syntax: 242.Pp 243.Dl \&.Va argument [\ .\ ,\ ;\ :\ (\ )\ [\ ]\ argument \...\ ] 244.Pp 245Macros may be given up to nine arguments. 246.Sy Note : 247Opening and closing 248punctuation characters are only recognized as such if they are presented 249one at a time. 250The string 251.Ql ")," 252is not recognized as punctuation and will be output with a leading white 253space and in what ever font the calling macro uses. 254The 255the argument list 256.Ql "] ) ," 257is recognized as three sequential closing punctuation characters 258and a leading white space is not output between the characters 259and the previous argument (if any). 260The special meaning of a punctuation character may be escaped 261with the string 262.Ql \e& . 263For example the following string, 264.Pp 265.Dl \&.Ar file1\ , file2\ , file3\ )\ . 266.Pp 267Produces 268.Pp 269.D1 .Ar file1 , file2 , file3 ) . 270.Ss Manual Domain Macros 271.Bl -column "Name" "Parsed" Callable" 272.It Em Name Parsed Callable Description 273.It Sy \&Ad Ta Yes Ta Yes Ta Address. "(This macro may be deprecated.)" 274.It Sy \&Ar Ta Yes Ta Yes Ta "Command line argument." 275.It Sy \&Cd Ta \&No Ta \&No Ta "Configuration declaration (section four only)." 276.It Sy \&Cm Ta Yes Ta Yes Ta "Command line argument modifier." 277.It Sy \&Dv Ta Yes Ta Yes Ta "Defined variable (source code)." 278.It Sy \&Er Ta Yes Ta Yes Ta "Error number (source code)." 279.It Sy \&Ev Ta Yes Ta Yes Ta "Environment variable." 280.It Sy \&Fa Ta Yes Ta Yes Ta "Function argument." 281.It Sy \&Fd Ta Yes Ta Yes Ta "Function declaration." 282.It Sy \&Fn Ta Yes Ta Yes Ta "Function call (also .Fo and .Fc)." 283.It Sy \&Ic Ta Yes Ta Yes Ta "Interactive command." 284.It Sy \&Li Ta Yes Ta Yes Ta "Literal text." 285.It Sy \&Nm Ta Yes Ta Yes Ta "Command name." 286.It Sy \&Op Ta Yes Ta Yes Ta "Option (also .Oo and .Oc)." 287.It Sy \&Ot Ta Yes Ta Yes Ta "Old style function type (Fortran only)." 288.It Sy \&Pa Ta Yes Ta Yes Ta "Pathname or file name." 289.It Sy \&St Ta Yes Ta Yes Ta "Standards (-p1003.2, -p1003.1 or -ansiC)" 290.It Sy \&Va Ta Yes Ta Yes Ta "Variable name." 291.It Sy \&Vt Ta Yes Ta Yes Ta "Variable type (Fortran only)." 292.It Sy \&Xr Ta Yes Ta Yes Ta "Manual Page Cross Reference." 293.El 294.Ss General Text Domain Macros 295.Bl -column "Name" "Parsed" Callable" 296.It Em "Name Parsed Callable Description" 297.It Sy \&%A Ta Yes Ta \&No Ta "Reference author." 298.It Sy \&%B Ta Yes Ta Yes Ta "Reference book title." 299.It Sy \&%\&C Ta \&No Ta \&No Ta "Reference place of publishing (city)." 300.It Sy \&%\&D Ta \&No Ta \&No Ta "Reference date." 301.It Sy \&%J Ta Yes Ta Yes Ta "Reference journal title." 302.It Sy \&%N Ta \&No Ta \&No Ta "Reference issue number." 303.It Sy \&%\&O Ta \&No Ta \&No Ta "Reference optional information." 304.It Sy \&%P Ta \&No Ta \&No Ta "Reference page number(s)." 305.It Sy \&%R Ta \&No Ta \&No Ta "Reference report Name." 306.It Sy \&%T Ta Yes Ta Yes Ta "Reference article title." 307.It Sy \&%V Ta \&No Ta \&No Ta "Reference volume." 308.It Sy \&Ac Ta Yes Ta Yes Ta "Angle close quote." 309.It Sy \&Ao Ta Yes Ta Yes Ta "Angle open quote." 310.It Sy \&Aq Ta Yes Ta Yes Ta "Angle quote." 311.It Sy \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX" 312.It Sy \&Bc Ta Yes Ta Yes Ta "Bracket close quote." 313.It Sy \&Bf Ta \&No Ta \&No Ta "Begin font mode." 314.It Sy \&Bo Ta Yes Ta Yes Ta "Bracket open quote." 315.It Sy \&Bq Ta Yes Ta Yes Ta "Bracket quote." 316.It Sy \&Bx Ta Yes Ta Yes Ta Bx . 317.It Sy \&Db Ta \&No Ta \&No Ta "Debug (default is off)" 318.It Sy \&Dc Ta Yes Ta Yes Ta "Double close quote." 319.It Sy \&Do Ta Yes Ta Yes Ta "Double open quote." 320.It Sy \&Dq Ta Yes Ta Yes Ta "Double quote." 321.It Sy \&Ec Ta Yes Ta Yes Ta "Enclose string close quote." 322.It Sy \&Ef Ta \&No Ta \&No Ta "End font mode." 323.It Sy \&Em Ta Yes Ta Yes Ta "Emphasis (traditional English)." 324.It Sy \&Eo Ta Yes Ta Yes Ta "Enclose string open quote." 325.It Sy \&No Ta Yes Ta Yes Ta "Normal text (no-op)." 326.It Sy \&Ns Ta Yes Ta Yes Ta "No space." 327.It Sy \&Pc Ta Yes Ta Yes Ta "Parenthesis close quote." 328.It Sy \&Pf Ta Yes Ta \&No Ta "Prefix string." 329.It Sy \&Po Ta Yes Ta Yes Ta "Parenthesis open quote." 330.It Sy \&Pq Ta Yes Ta Yes Ta "Parentheses quote." 331.It Sy \&Qc Ta Yes Ta Yes Ta "Strait Double close quote." 332.It Sy \&Ql Ta Yes Ta Yes Ta "Quoted literal." 333.It Sy \&Qo Ta Yes Ta Yes Ta "Strait Double open quote." 334.It Sy \&Qq Ta Yes Ta Yes Ta "Strait Double quote." 335.It Sy \&Re Ta \&No Ta \&No Ta "Reference start." 336.It Sy \&Rs Ta \&No Ta \&No Ta "Reference start." 337.It Sy \&Sc Ta Yes Ta Yes Ta "Single close quote." 338.It Sy \&So Ta Yes Ta Yes Ta "Single open quote." 339.It Sy \&Sq Ta Yes Ta Yes Ta "Single quote." 340.It Sy \&Sm Ta \&No Ta \&No Ta "Space mode (default is \\*qon\\*q)" 341.It Sy \&Sx Ta Yes Ta Yes Ta "Section Cross Reference." 342.It Sy \&Sy Ta Yes Ta Yes Ta "Symbolic (traditional English)." 343.It Sy \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)." 344.It Sy \&Ux Ta Yes Ta Yes Ta Ux 345.It Sy \&Xc Ta Yes Ta Yes Ta "Extend argument list close." 346.It Sy \&Xo Ta Yes Ta Yes Ta "Extend argument list close." 347.El 348.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header" 349.Pp 350Macro names ending in 351.Ql q 352quote remaining items on the argument list. 353Macro names ending in 354.Ql o 355begin a quote which may span more than one line of input and 356are close quoted with the matching macro name ending in 357.Ql c . 358Enclosure macros may be nested. 359.Pp 360Note: the extended argument list macros 361.Pf ( Ql \&.Xo , 362.Ql \&.Xc ) 363and the function enclosure macros 364.Pf ( Ql \&.Fo , 365.Ql \&.Fc ) 366are irregular. 367The extended list macros are used when the number of macro arguments 368would exceed the 369.Xr troff 370limitation of nine arguments. 371.Sh CONFIGURATION 372For site specific configuration of the macro package, 373see the file 374.Pa /usr/src/share/tmac/README . 375.Sh FILES 376.Bl -tag -width "tmac.doc-ditroff" -compact 377.It Pa tmac.doc 378Manual and general text domain macros. 379.It Pa tmac.doc-common 380Shared structural macros (between nroff/troff/groff). 381.It Pa tmac.doc-nroff 382Site dependent nroff style file. 383.It Pa tmac.doc-ditroff 384Site dependent groff/troff/ditroff style file. 385.It Pa tmac.doc-syms 386Special defines (such as the standards macro). 387.El 388.Sh SEE ALSO 389.Xr mdoc.samples 7 390.Sh HISTORY 391The 392.Nm \-mdoc 393macro package is 394.Ud . 395