1.\" $OpenBSD: mdoc.7,v 1.41 2009/04/23 15:37:14 sobrado 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 $Mdocdate: April 23 2009 $ 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.Pp 72.It Li "\&.Dd $\&Mdocdate$" 73Expands to document date. 74.It Li "\&.Dt " Ar "DOCUMENT_TITLE [section] [volume]" 75Title, in upper case. 76.It Li "\&.Os " Ar "OPERATING_SYSTEM [version/release]" 77Operating system 78.Pq Tn BSD . 79.El 80.Ss Page Layout Macros 81Section headers, paragraph breaks, lists and displays. 82.Bl -tag -width flag -compact 83.It Li \&.Sh 84Section Headers. 85Valid headers, in the order of presentation: 86.Bl -tag -width "RETURN VALUES" -compact 87.It Ar NAME 88Name section. 89Should include the 90.Ql \&.Nm 91or 92.Ql \&.Fn 93and the 94.Ql \&.Nd 95macros. 96.It Ar SYNOPSIS 97Usage. 98All 99.Ql \&.Nm 100macros must be given an argument. 101.It Ar DESCRIPTION 102General description, including any options, operands, or other parameters. 103.It Ar RETURN VALUES 104Sections two, three, and nine function calls. 105.It Ar ENVIRONMENT 106Describe environment variables. 107.It Ar FILES 108Files associated with the subject, with short descriptions. 109.It Ar EXAMPLES 110Examples and suggestions. 111.It Ar DIAGNOSTICS 112Sections one, four, six, and eight diagnostics. 113.It Ar ERRORS 114Sections two, three, and nine error and signal handling. 115.It Ar SEE ALSO 116Cross references and citations. 117.It Ar STANDARDS 118Conformance to standards if applicable. 119.It Ar HISTORY 120A brief history of the subject, including where support first appeared. 121.It Ar AUTHORS 122Credit to the person or persons who wrote the code and/or documentation. 123.It Ar CAVEATS 124Explanations of common misuses, i.e., security considerations for certain 125library functions. 126.It Ar BUGS 127Gotchas and caveats. 128.It Ar other 129Customized headers may be added at the author's discretion. 130.El 131.It Li \&.Ss 132Subsection Headers. 133.It Li \&.Pp 134Paragraph Break. 135Vertical space (one line). 136.It Li \&.D1 137(D-one) Display-one. 138Indent and display one text line. 139.It Li \&.Dl 140(D-ell) Display-one literal. 141Indent and display one line of literal text. 142.It Li \&.Bd 143Begin-display block. 144Display options: 145.Bl -tag -width "xoffset string " -compact 146.It Fl ragged 147Unjustified (ragged edges). 148.It Fl unfilled 149Unfilled, unjustified. 150.It Fl filled 151Filled, and if 152.Xr troff 1 , 153also justified. 154.It Fl literal 155Literal text or code. 156.It Fl file Ar name 157Read in named 158.Ar file 159and display. 160.It Fl offset Ar string 161Offset display. 162Acceptable 163.Ar string 164values: 165.Bl -tag -width indent-two -compact 166.It Ar left 167Align block on left (default). 168.It Ar center 169Approximate center margin. 170.It Ar indent 171Six constant width spaces (a tab). 172.It Ar indent-two 173Two tabs. 174.It Ar right 175Left aligns block 2 inches from 176right. 177.It Ar xx Ns Cm n 178Where 179.Ar xx 180is a number from 181.No \&4 Ns Cm n 182to 183.No \&9\&9 Ns Cm n . 184.It Ar Aa 185Where 186.Ar Aa 187is a callable macro name. 188.It Ar string 189The width of 190.Ar string 191is used. 192.El 193.El 194.It Li \&.Ed 195End-display (matches \&.Bd). 196.It Li \&.Bl 197Begin-list. 198Create lists or columns. 199Options: 200.Bl -tag -width flag -compact 201.It Em List-types 202.Bl -column "xbullet " -compact 203.It Fl bullet Ta "Bullet Item List" 204.It Fl dash Ta "Dash Item List" 205.It Fl hyphen Ta "(as per" Fl dash ")" 206.It Fl item Ta "Unlabeled List" 207.It Fl enum Ta "Enumerated List" 208.It Fl tag Ta "Tag Labeled List" 209.It Fl diag Ta "Diagnostic List" 210.It Fl hang Ta "Hanging Labeled List" 211.It Fl ohang Ta "Overhanging Labeled List" 212.It Fl inset Ta "Inset or Run-on Labeled List" 213.It Fl column Ta "Multiple Columns" 214.El 215.It Em List-parameters 216.Bl -tag -width "xcompact " -compact 217.It Fl offset 218(All lists.) See 219.Ql \&.Bd 220begin-display above. 221.It Fl width 222.Pf ( Fl tag 223and 224.Fl hang 225lists only.) 226This parameter is effectively required for 227.Fl tag 228lists. 229.It Fl compact 230(All lists.) 231Suppresses blank lines. 232.El 233.El 234.It Li \&.El 235End-list. 236.It Li \&.It 237List item. 238.El 239.Sh MANUAL AND GENERAL TEXT DOMAIN MACROS 240The manual and general text domain macros are special in that 241most of them are parsed for callable macros 242for example: 243.Bl -tag -width ".Op Fl s Ar filex" -offset indent 244.It Li "\&.Op Fl s Ar file" 245Produces 246.Op Fl s Ar file 247.El 248.Pp 249In this example, the option enclosure macro 250.Ql \&.Op 251is parsed, and calls the callable content macro 252.Ql \&Fl 253which operates on the argument 254.Ql s 255and then calls the callable content macro 256.Ql \&Ar 257which operates on the argument 258.Ql file . 259Some macros may be callable but are not parsed, or vice versa. 260These macros are indicated in the 261.Em parsed 262and 263.Em callable 264columns below. 265.Pp 266Unless stated, manual domain macros share a common syntax: 267.Pp 268.Dl \&.Va argument [\ .\ ,\ ;\ :\ ?\ !\ (\ )\ [\ ]\ argument \...\ ] 269.Pp 270.Sy Note : 271Opening and closing 272punctuation characters are only recognized as such if they are presented 273one at a time. 274The string 275.Ql ")," 276is not recognized as punctuation and will be output with a leading whitespace 277and in whatever font the calling macro uses. 278The 279argument list 280.Ql "] ) ," 281is recognized as three sequential closing punctuation characters 282and a leading white space is not output between the characters 283and the previous argument (if any). 284The special meaning of a punctuation character may be escaped 285with the string 286.Ql \e& . 287For example the following string, 288.Bl -tag -width "&.Ar file1\ , file2\ , file3\ )\ ." -offset indent 289.It Li "\&.Ar file1\ , file2\ , file3\ )\ ." 290Produces 291.Ar file1 , file2 , file3 ) . 292.El 293.Ss Manual Domain Macros 294.Bl -column "Name" "Parsed" "Callable" -compact 295.It Em Name Parsed Callable Description 296.It Li \&Ad Ta Yes Ta Yes Ta Address. "(This macro may be deprecated.)" 297.It Li \&An Ta Yes Ta \&No Ta "Author name." 298.It Li \&Ar Ta Yes Ta Yes Ta "Command line argument." 299.It Li \&Cd Ta \&No Ta \&No Ta "Configuration declaration." 300.It Li \&Cm Ta Yes Ta Yes Ta "Command line argument modifier." 301.It Li \&Dv Ta Yes Ta Yes Ta "Defined variable (source code)." 302.It Li \&Er Ta Yes Ta Yes Ta "Error number (source code)." 303.It Li \&Ev Ta Yes Ta Yes Ta "Environment variable." 304.It Li \&Ex Ta \&No Ta \&No Ta "Exit values." 305.It Li \&Fa Ta Yes Ta Yes Ta "Function argument." 306.It Li \&Fd Ta \&No Ta \&No Ta "Function declaration." 307.It Li \&Fl Ta Yes Ta Yes Ta "Flags." 308.It Li \&Fn Ta Yes Ta Yes Ta "Function call (also .Fo and .Fc)." 309.It Li \&Ft Ta Yes Ta Yes Ta "Function type." 310.It Li \&Ic Ta Yes Ta Yes Ta "Interactive command." 311.It Li \&In Ta \&No Ta \&No Ta "Include header file." 312.It Li \&Li Ta Yes Ta Yes Ta "Literal text." 313.It Li \&Nd Ta \&No Ta \&No Ta "Name description." 314.It Li \&Nm Ta Yes Ta Yes Ta "Command name." 315.It Li \&Op Ta Yes Ta Yes Ta "Option (also .Oo and .Oc)." 316.It Li \&Ot Ta Yes Ta Yes Ta "Old style function type (Fortran only)." 317.It Li \&Pa Ta Yes Ta Yes Ta "Pathname or file name." 318.It Li \&Rv Ta \&No Ta \&No Ta "Return values." 319.It Li \&St Ta Yes Ta Yes Ta "Standards (see below)." 320.It Li \&Va Ta Yes Ta Yes Ta "Variable name." 321.It Li \&Vt Ta Yes Ta Yes Ta "Variable type." 322.It Li \&Xr Ta Yes Ta Yes Ta "Manual Page Cross Reference." 323.El 324.Pp 325The known standards for the St macro are: 326.Bd -ragged -offset 5n 327-p1003.1-88, -p1003.1-90, -p1003.1-96, -p1003.1-2001, -p1003.1-2004, 328-p1003.1-2008, -p1003.1, -p1003.1b, -p1003.1b-93, -p1003.1c-95, -p1003.1g-2000, 329-p1003.2-92, -p1003.2-95, -p1003.2, -p1387.2, -isoC-90, -isoC-amd1, 330-isoC-tcor1, -isoC-tcor2, isoC-99, -ansiC, -ansiC-89, -ansiC-99, -ieee754, 331-iso8802-3, -xpg3, -xpg4, -xpg4.2, -xpg4.3, -xbd5, -xcu5, -xsh5, -xns5, 332-xns5.2d2.0, -xcurses4.2, -susv2, -susv3, and -svid4. 333.Ed 334.Ss General Text Domain Macros 335.Bl -column "Name" "Parsed" "Callable" -compact 336.It Em "Name Parsed Callable Description" 337.It Li \&%A Ta Yes Ta \&No Ta "Reference author." 338.It Li \&%B Ta Yes Ta Yes Ta "Reference book title." 339.It Li \&%\&D Ta \&No Ta \&No Ta "Reference date." 340.It Li \&%I Ta Yes Ta Yes Ta "Issuer/Publisher name." 341.It Li \&%J Ta Yes Ta Yes Ta "Reference journal title." 342.It Li \&%N Ta \&No Ta \&No Ta "Reference issue number." 343.It Li \&%\&O Ta \&No Ta \&No Ta "Reference optional information." 344.It Li \&%P Ta \&No Ta \&No Ta "Reference page number(s)." 345.It Li \&%R Ta \&No Ta \&No Ta "Reference report Name." 346.It Li \&%T Ta Yes Ta Yes Ta "Reference article title." 347.It Li \&%V Ta \&No Ta \&No Ta "Reference volume." 348.It Li \&Ac Ta Yes Ta Yes Ta "Angle close quote." 349.It Li \&Ao Ta Yes Ta Yes Ta "Angle open quote." 350.It Li \&Aq Ta Yes Ta Yes Ta "Angle quote." 351.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX." 352.It Li \&Bc Ta Yes Ta Yes Ta "Bracket close quote." 353.It Li \&Bf Ta \&No Ta \&No Ta "Begin font mode." 354.It Li \&Bo Ta Yes Ta Yes Ta "Bracket open quote." 355.It Li \&Bq Ta Yes Ta Yes Ta "Bracket quote." 356.It Li \&Bsx Ta Yes Ta \&No Ta "BSDI BSD/OS." 357.It Li \&Bx Ta Yes Ta \&No Ta BSD . 358.It Li \&Db Ta \&No Ta \&No Ta "Debug (default is \\*qoff\\*q)." 359.It Li \&Dc Ta Yes Ta Yes Ta "Double close quote." 360.It Li \&Do Ta Yes Ta Yes Ta "Double open quote." 361.It Li \&Dq Ta Yes Ta Yes Ta "Double quote." 362.It Li \&Ec Ta Yes Ta Yes Ta "Enclose string close quote." 363.It Li \&Ef Ta \&No Ta \&No Ta "End font mode." 364.It Li \&Em Ta Yes Ta Yes Ta "Emphasis (traditional English)." 365.It Li \&Eo Ta Yes Ta Yes Ta "Enclose string open quote." 366.It Li \&Fx Ta Yes Ta \&No Ta FreeBSD . 367.It Li \&Ms Ta Yes Ta \&No Ta "Mathematical symbol." 368.It Li \&No Ta Yes Ta Yes Ta "Normal text (no-op)." 369.It Li \&Ns Ta Yes Ta Yes Ta "No space." 370.It Li \&Nx Ta Yes Ta \&No Ta NetBSD . 371.It Li \&Ox Ta Yes Ta \&No Ta OpenBSD . 372.It Li \&Pc Ta Yes Ta Yes Ta "Parenthesis close quote." 373.It Li \&Pf Ta Yes Ta \&No Ta "Prefix string." 374.It Li \&Po Ta Yes Ta Yes Ta "Parenthesis open quote." 375.It Li \&Pq Ta Yes Ta Yes Ta "Parentheses quote." 376.It Li \&Qc Ta Yes Ta Yes Ta "Straight double close quote." 377.It Li \&Ql Ta Yes Ta Yes Ta "Quoted literal." 378.It Li \&Qo Ta Yes Ta Yes Ta "Straight double open quote." 379.It Li \&Qq Ta Yes Ta Yes Ta "Straight double quote." 380.It Li \&Re Ta \&No Ta \&No Ta "Reference end." 381.It Li \&Rs Ta \&No Ta \&No Ta "Reference start." 382.It Li \&Sc Ta Yes Ta Yes Ta "Single close quote." 383.It Li \&So Ta Yes Ta Yes Ta "Single open quote." 384.It Li \&Sq Ta Yes Ta Yes Ta "Single quote." 385.It Li \&Sm Ta \&No Ta \&No Ta "Space mode (default is \\*qon\\*q)." 386.It Li \&Sx Ta Yes Ta Yes Ta "Section Cross Reference." 387.It Li \&Sy Ta Yes Ta Yes Ta "Symbolic (traditional English)." 388.It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)." 389.It Li \&Ux Ta Yes Ta \&No Ta UNIX . 390.It Li \&Xc Ta Yes Ta Yes Ta "Extend argument list close." 391.It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list open." 392.El 393.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header" 394.Pp 395Macro names ending in 396.Ql q 397quote remaining items on the argument list. 398Macro names ending in 399.Ql o 400begin a quote which may span more than one line of input and 401are close quoted with the matching macro name ending in 402.Ql c . 403Enclosure macros may be nested and are limited to 404eight arguments. 405.Pp 406Note: the extended argument list macros 407.Pf ( Ql \&.Xo , 408.Ql \&.Xc ) 409and the function enclosure macros 410.Pf ( Ql \&.Fo , 411.Ql \&.Fc ) 412are irregular. 413The extended list macros are used when the number of macro arguments 414would exceed the 415.Xr troff 1 416limitation of nine arguments. 417.Sh FILES 418.Bl -tag -width "/usr/share/misc/mdoc.template" -compact 419.It Pa tmac.doc 420manual macro package 421.It Pa tmac.doc-common 422common structural macros and definitions 423.It Pa tmac.doc-ditroff 424site dependent 425.Xr troff 1 426style file 427.It Pa tmac.doc-nroff 428site dependent 429.Xr nroff 1 430style file 431.It Pa tmac.doc-syms 432special defines 433.It Pa /usr/share/misc/mdoc.template 434template for writing a man page 435.El 436.Sh SEE ALSO 437.Xr groff 1 , 438.Xr man 1 , 439.Xr nroff 1 , 440.Xr troff 1 , 441.Xr mdoc.samples 7 442