1.\" $OpenBSD: mdoc.7,v 1.28 2003/07/21 11:50:54 jmc Exp $ 2.\" 3.\" Copyright (c) 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)mdoc.7 8.2 (Berkeley) 12/30/93 31.\" 32.Dd December 30, 1993 33.Dt MDOC 7 34.Os 35.Sh NAME 36.Nm mdoc 37.Nd quick reference guide for the 38.Nm \-mdoc 39macro package 40.Sh SYNOPSIS 41.Nm nroff 42.Fl T Ns Ar Name 43.Fl mandoc 44.Ar file 45.Sh DESCRIPTION 46The 47.Nm \-mdoc 48package is a set of content-based and domain-based macros 49used to format the 50.Bx 51man pages. 52The macro names and their meanings are 53listed below for quick reference; for 54a detailed explanation on using the package, 55see the tutorial sampler 56.Xr mdoc.samples 7 . 57.Pp 58The macros are described in two groups. 59The first includes the structural and physical page layout macros. 60The second contains the manual and general text domain 61macros which differentiate the 62.Nm -\mdoc 63package from other 64.Xr troff 1 65formatting packages. 66.Sh PAGE STRUCTURE DOMAIN 67.Ss Title Macros 68To create a valid manual page, these three macros, in this order, 69are required: 70.Bl -tag -width "xxxx.Os OPERATINGxSYSTEM [version/release]" -compact 71.It Li "\&.Dd " Ar "Month day, year" 72Document date. 73.It Li "\&.Dt " Ar "DOCUMENT_TITLE [section] [volume]" 74Title, in upper case. 75.It Li "\&.Os " Ar "OPERATING_SYSTEM [version/release]" 76Operating system 77.Pq Tn BSD . 78.El 79.Ss Page Layout Macros 80Section headers, paragraph breaks, lists and displays. 81.Bl -tag -width flag -compact 82.It Li \&.Sh 83Section Headers. 84Valid headers, in the order of presentation: 85.Bl -tag -width "RETURN VALUES" -compact 86.It Ar NAME 87Name section. 88Should include the 89.Ql \&.Nm 90or 91.Ql \&.Fn 92and the 93.Ql \&.Nd 94macros. 95.It Ar SYNOPSIS 96Usage. 97All 98.Ql \&.Nm 99macros must be given an argument. 100.It Ar DESCRIPTION 101General description, including any options, operands, or other parameters. 102.It Ar RETURN VALUES 103Sections two and three function calls. 104.It Ar ENVIRONMENT 105Describe environment variables. 106.It Ar FILES 107Files associated with the subject, with short descriptions. 108.It Ar EXAMPLES 109Examples and suggestions. 110.It Ar DIAGNOSTICS 111Section four device interface diagnostics. 112.It Ar ERRORS 113Sections two and three error and signal handling. 114.It Ar SEE ALSO 115Cross references and citations. 116.It Ar STANDARDS 117Conformance to standards if applicable. 118.It Ar HISTORY 119A brief history of the subject, including where support first appeared. 120.It Ar AUTHORS 121Credit to the person or persons who wrote the code and/or documentation. 122.It Ar CAVEATS 123Explanations of common misuses, i.e., security considerations for certain 124library functions. 125.It Ar BUGS 126Gotchas and caveats. 127.It Ar other 128Customized headers may be added at the author's discretion. 129.El 130.It Li \&.Ss 131Subsection Headers. 132.It Li \&.Pp 133Paragraph Break. 134Vertical space (one line). 135.It Li \&.D1 136(D-one) Display-one 137Indent and display one text line. 138.It Li \&.Dl 139(D-ell) Display-one literal. 140Indent and display one line of literal text. 141.It Li \&.Bd 142Begin-display block. 143Display options: 144.Bl -tag -width "xoffset string " -compact 145.It Fl ragged 146Unjustified (ragged edges). 147.It Fl unfilled 148Unfilled, unjustified. 149.It Fl filled 150Filled, and if 151.Xr troff 1 , 152also justified. 153.It Fl literal 154Literal text or code. 155.It Fl file Ar name 156Read in named 157.Ar file 158and display. 159.It Fl offset Ar string 160Offset display. 161Acceptable 162.Ar string 163values: 164.Bl -tag -width indent-two -compact 165.It Ar left 166Align block on left (default). 167.It Ar center 168Approximate center margin. 169.It Ar indent 170Six constant width spaces (a tab). 171.It Ar indent-two 172Two tabs. 173.It Ar right 174Left aligns block 2 inches from 175right. 176.It Ar xx Ns Cm n 177Where 178.Ar xx 179is a number from 180.No \&4 Ns Cm n 181to 182.No \&9\&9 Ns Cm n . 183.It Ar Aa 184Where 185.Ar Aa 186is a callable macro name. 187.It Ar string 188The width of 189.Ar string 190is used. 191.El 192.El 193.It Li \&.Ed 194End-display (matches \&.Bd). 195.It Li \&.Bl 196Begin-list. 197Create lists or columns. 198Options: 199.Bl -tag -width flag -compact 200.It Em List-types 201.Bl -column "xbullet " -compact 202.It Fl bullet Ta "Bullet Item List" 203.It Fl dash Ta "Dash Item List" 204.It Fl hyphen Ta "(as per" Fl dash ")" 205.It Fl item Ta "Unlabeled List" 206.It Fl enum Ta "Enumerated List" 207.It Fl tag Ta "Tag Labeled List" 208.It Fl diag Ta "Diagnostic List" 209.It Fl hang Ta "Hanging Labeled List" 210.It Fl ohang Ta "Overhanging Labeled List" 211.It Fl inset Ta "Inset or Run-on Labeled List" 212.It Fl column Ta "Multiple Columns" 213.El 214.It Em List-parameters 215.Bl -tag -width "xcompact " -compact 216.It Fl offset 217(All lists.) See 218.Ql \&.Bd 219begin-display above. 220.It Fl width 221.Pf ( Fl tag 222and 223.Fl hang 224lists only.) 225This parameter is effectively required for 226.Fl tag 227lists. 228.It Fl compact 229(All lists.) 230Suppresses blank lines. 231.El 232.El 233.It Li \&.El 234End-list. 235.It Li \&.It 236List item. 237.El 238.Sh MANUAL AND GENERAL TEXT DOMAIN MACROS 239The manual and general text domain macros are special in that 240most of them are parsed for callable macros 241for example: 242.Bl -tag -width ".Op Fl s Ar filex" -offset indent 243.It Li "\&.Op Fl s Ar file" 244Produces 245.Op Fl s Ar file 246.El 247.Pp 248In this example, the option enclosure macro 249.Ql \&.Op 250is parsed, and calls the callable content macro 251.Ql \&Fl 252which operates on the argument 253.Ql s 254and then calls the callable content macro 255.Ql \&Ar 256which operates on the argument 257.Ql file . 258Some macros may be callable but are not parsed, or vice versa. 259These macros are indicated in the 260.Em parsed 261and 262.Em callable 263columns below. 264.Pp 265Unless stated, manual domain macros share a common syntax: 266.Pp 267.Dl \&.Va argument [\ .\ ,\ ;\ :\ (\ )\ [\ ]\ argument \...\ ] 268.Pp 269.Sy Note : 270Opening and closing 271punctuation characters are only recognized as such if they are presented 272one at a time. 273The string 274.Ql ")," 275is not recognized as punctuation and will be output with a leading whitespace 276and in whatever font the calling macro uses. 277The 278argument list 279.Ql "] ) ," 280is recognized as three sequential closing punctuation characters 281and a leading white space is not output between the characters 282and the previous argument (if any). 283The special meaning of a punctuation character may be escaped 284with the string 285.Ql \e& . 286For example the following string, 287.Bl -tag -width "&.Ar file1\ , file2\ , file3\ )\ ." -offset indent 288.It Li "\&.Ar file1\ , file2\ , file3\ )\ ." 289Produces 290.Ar file1 , file2 , file3 ) . 291.El 292.Ss Manual Domain Macros 293.Bl -column "Name" "Parsed" "Callable" -compact 294.It Em Name Parsed Callable Description 295.It Li \&Ad Ta Yes Ta Yes Ta Address. "(This macro may be deprecated.)" 296.It Li \&An Ta Yes Ta \&No Ta "Author name." 297.It Li \&Ar Ta Yes Ta Yes Ta "Command line argument." 298.It Li \&Cd Ta \&No Ta \&No Ta "Configuration declaration (section four only)." 299.It Li \&Cm Ta Yes Ta Yes Ta "Command line argument modifier." 300.It Li \&Dv Ta Yes Ta Yes Ta "Defined variable (source code)." 301.It Li \&Er Ta Yes Ta Yes Ta "Error number (source code)." 302.It Li \&Ev Ta Yes Ta Yes Ta "Environment variable." 303.It Li \&Fa Ta Yes Ta Yes Ta "Function argument." 304.It Li \&Fd Ta \&No Ta \&No Ta "Function declaration." 305.It Li \&Fl Ta Yes Ta Yes Ta "Flags." 306.It Li \&Fn Ta Yes Ta Yes Ta "Function call (also .Fo and .Fc)." 307.It Li \&Ft Ta Yes Ta Yes Ta "Function type." 308.It Li \&Ic Ta Yes Ta Yes Ta "Interactive command." 309.It Li \&Li Ta Yes Ta Yes Ta "Literal text." 310.It Li \&Nd Ta \&No Ta \&No Ta "Command description." 311.It Li \&Nm Ta Yes Ta Yes Ta "Command name." 312.It Li \&Op Ta Yes Ta Yes Ta "Option (also .Oo and .Oc)." 313.It Li \&Ot Ta Yes Ta Yes Ta "Old style function type (Fortran only)." 314.It Li \&Pa Ta Yes Ta Yes Ta "Pathname or file name." 315.It Li \&St Ta Yes Ta Yes Ta "Standards (see below)." 316.It Li \&Va Ta Yes Ta Yes Ta "Variable name." 317.It Li \&Vt Ta Yes Ta Yes Ta "Variable type (Fortran only)." 318.It Li \&Xr Ta Yes Ta Yes Ta "Manual Page Cross Reference." 319.El 320.Pp 321The known standards for the St macro are: 322.Bd -ragged -offset 4n 323-p1003.1-88, -p1003.1-90, -p1003.1-01, -p1003.1, -p1003.1b, -p1003.1b-93, 324-p1003.1c-95, -p1003.1-96, -p1003.2-92, -p1003.2, -p1387.2-95, -p1387.2, 325-ansiC, -ansiC-89, -ansiC-99, -ieee754, -iso8802-3, -xpg3, -xpg4, -xpg4.2, 326-xpg4.3, -xbd5, -xcu5, -xsh5, -xns5, -xns5.2d2.0, -xcurses4.2, -susv2, and 327-susv3. 328.Ed 329.Ss General Text Domain Macros 330.Bl -column "Name" "Parsed" "Callable" -compact 331.It Em "Name Parsed Callable Description" 332.It Li \&%A Ta Yes Ta \&No Ta "Reference author." 333.It Li \&%B Ta Yes Ta Yes Ta "Reference book title." 334.It Li \&%\&D Ta \&No Ta \&No Ta "Reference date." 335.It Li \&%I Ta Yes Ta Yes Ta "Issuer/Publisher name." 336.It Li \&%J Ta Yes Ta Yes Ta "Reference journal title." 337.It Li \&%N Ta \&No Ta \&No Ta "Reference issue number." 338.It Li \&%\&O Ta \&No Ta \&No Ta "Reference optional information." 339.It Li \&%P Ta \&No Ta \&No Ta "Reference page number(s)." 340.It Li \&%R Ta \&No Ta \&No Ta "Reference report Name." 341.It Li \&%T Ta Yes Ta Yes Ta "Reference article title." 342.It Li \&%V Ta \&No Ta \&No Ta "Reference volume." 343.It Li \&Ac Ta Yes Ta Yes Ta "Angle close quote." 344.It Li \&Ao Ta Yes Ta Yes Ta "Angle open quote." 345.It Li \&Aq Ta Yes Ta Yes Ta "Angle quote." 346.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX." 347.It Li \&Bc Ta Yes Ta Yes Ta "Bracket close quote." 348.It Li \&Bf Ta \&No Ta \&No Ta "Begin font mode." 349.It Li \&Bo Ta Yes Ta Yes Ta "Bracket open quote." 350.It Li \&Bq Ta Yes Ta Yes Ta "Bracket quote." 351.It Li \&Bsx Ta Yes Ta \&No Ta "BSDI BSD/OS." 352.It Li \&Bx Ta Yes Ta \&No Ta BSD . 353.It Li \&Db Ta \&No Ta \&No Ta "Debug (default is \\*qoff\\*q)." 354.It Li \&Dc Ta Yes Ta Yes Ta "Double close quote." 355.It Li \&Do Ta Yes Ta Yes Ta "Double open quote." 356.It Li \&Dq Ta Yes Ta Yes Ta "Double quote." 357.It Li \&Ec Ta Yes Ta Yes Ta "Enclose string close quote." 358.It Li \&Ef Ta \&No Ta \&No Ta "End font mode." 359.It Li \&Em Ta Yes Ta Yes Ta "Emphasis (traditional English)." 360.It Li \&Eo Ta Yes Ta Yes Ta "Enclose string open quote." 361.It Li \&Fx Ta \&No Ta \&No Ta FreeBSD . 362.It Li \&Ms Ta Yes Ta \&No Ta "Mathematical symbol." 363.It Li \&No Ta Yes Ta Yes Ta "Normal text (no-op)." 364.It Li \&Ns Ta Yes Ta Yes Ta "No space." 365.It Li \&Nx Ta \&No Ta \&No Ta NetBSD . 366.It Li \&Ox Ta \&No Ta \&No Ta OpenBSD . 367.It Li \&Pc Ta Yes Ta Yes Ta "Parenthesis close quote." 368.It Li \&Pf Ta Yes Ta \&No Ta "Prefix string." 369.It Li \&Po Ta Yes Ta Yes Ta "Parenthesis open quote." 370.It Li \&Pq Ta Yes Ta Yes Ta "Parentheses quote." 371.It Li \&Qc Ta Yes Ta Yes Ta "Straight double close quote." 372.It Li \&Ql Ta Yes Ta Yes Ta "Quoted literal." 373.It Li \&Qo Ta Yes Ta Yes Ta "Straight double open quote." 374.It Li \&Qq Ta Yes Ta Yes Ta "Straight double quote." 375.It Li \&Re Ta \&No Ta \&No Ta "Reference end." 376.It Li \&Rs Ta \&No Ta \&No Ta "Reference start." 377.It Li \&Sc Ta Yes Ta Yes Ta "Single close quote." 378.It Li \&So Ta Yes Ta Yes Ta "Single open quote." 379.It Li \&Sq Ta Yes Ta Yes Ta "Single quote." 380.It Li \&Sm Ta \&No Ta \&No Ta "Space mode (default is \\*qon\\*q)." 381.It Li \&Sx Ta Yes Ta Yes Ta "Section Cross Reference." 382.It Li \&Sy Ta Yes Ta Yes Ta "Symbolic (traditional English)." 383.It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)." 384.It Li \&Ux Ta Yes Ta \&No Ta UNIX . 385.It Li \&Xc Ta Yes Ta Yes Ta "Extend argument list close." 386.It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list open." 387.El 388.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header" 389.Pp 390Macro names ending in 391.Ql q 392quote remaining items on the argument list. 393Macro names ending in 394.Ql o 395begin a quote which may span more than one line of input and 396are close quoted with the matching macro name ending in 397.Ql c . 398Enclosure macros may be nested and are limited to 399eight arguments. 400.Pp 401Note: the extended argument list macros 402.Pf ( Ql \&.Xo , 403.Ql \&.Xc ) 404and the function enclosure macros 405.Pf ( Ql \&.Fo , 406.Ql \&.Fc ) 407are irregular. 408The extended list macros are used when the number of macro arguments 409would exceed the 410.Xr troff 1 411limitation of nine arguments. 412.Sh FILES 413.Bl -tag -width "tmac.doc-ditroff" -compact 414.It Pa tmac.doc 415manual and general text domain macros 416.It Pa tmac.doc-common 417common structural macros and definitions 418.It Pa tmac.doc-nroff 419site dependent 420.Xr nroff 1 421style file 422.It Pa tmac.doc-ditroff 423site dependent 424.Xr troff 1 425style file 426.It Pa tmac.doc-syms 427special defines (such as the standards macro) 428.El 429.Sh SEE ALSO 430.Xr mdoc.samples 7 431