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