1.\" Copyright 2015 Nexenta Systems, Inc. All rights reserved. 2.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> 3.\" Copyright (c) 1995, Sun Microsystems, Inc. 4.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 5.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 6.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 7.Dd "Feb 18, 2015" 8.Dt MAN 5 9.Os 10.Sh NAME 11.Nm man 12.Nd macros to format Reference Manual pages 13.Sh SYNOPSIS 14.Nm mandoc 15.Fl T Ar man 16.Ar 17.Nm nroff 18.Fl man 19.Ar 20.Nm troff 21.Fl man 22.Ar 23.Sh DESCRIPTION 24These macros are used to lay out the reference pages in this manual. Note: if 25.Ar file 26contains format input for a preprocessor, the commands shown 27above must be piped through the appropriate preprocessor. This is handled 28automatically by the 29.Xr man 1 30command. See the 31.Sx Conventions 32section. 33.Lp 34Any text argument 35.Ar t 36may be zero to six words. Quotes may be used to 37include SPACE characters in a 38.Qq word . 39If 40.Ar text 41is empty, the special 42treatment is applied to the next input line with text to be printed. In this 43way 44.Nm \&.I 45may be used to italicize a whole line, or 46.Nm \&.SB 47may be used to make small bold letters. 48.Lp 49A prevailing indent distance is remembered between successive indented 50paragraphs, and is reset to default value upon reaching a non-indented 51paragraph. Default units for indents 52.Nm i 53are ens. 54.Lp 55Type font and size are reset to default values before each paragraph, and after 56processing font and size setting macros. 57.Pp 58These strings are predefined by 59.Nm -man : 60.Bl -tag -width Ds 61.It Nm \e*R 62.Sq \(rg , 63.Sq (Reg) 64in 65.Nm nroff . 66.It Nm \e*S 67Change to default type size. 68.El 69.Sh "Requests" 70* n.t.l. = next text line; p.i. = prevailing indent 71.Bl -column ".TH n s d f m" "Cause " "t=n.t.l.*" "Explanation " -offset Ds 72.It Sy Request Sy Cause Sy "If No" Sy Explanation 73.It "" Sy Break Sy "Argument" "" 74.It Nm \&.B Ar "t" no Ar t Ns =n.t.l.* Text is in bold font. 75.It Nm \&.BI Ar t no Ar t Ns =n.t.l. Join words, alternating bold and italic. 76.It Nm \&.BR Ar t no Ar t Ns =n.t.l. Join words, alternating bold and roman. 77.It Nm \&.DT no Li \&.5i 1i... Restore default tabs. 78.It Nm \&.HP Ar i yes Ar i Ns =p.i.* "Begin paragraph with hanging indent. Set prevailing indent to" Ar i . 79.It Nm \&.I Ar t no Ar t Ns =n.t.l. Text is italic. 80.It Nm \&.IB Ar t no Ar t Ns =n.t.l. Join words, altenrating italic and bold. 81.It Nm \&.IP Ar x Ar i yes Ar x Ns ="" Same as 82.Nm \&.TP 83with tag 84.Ar x . 85.It Nm \&.IR Ar t no Ar t Ns =n.t.l. Join words, alternating italic and roman. 86.It Nm \&.IX Ar t no - Index macro, not used (obsolete). 87.It Nm \&.LP yes - Begin left-aligned paragraph. Set prevailing indent to .5i. 88.It Nm \&.P yes - Same as 89.Nm \&.LP . 90.It Nm \&.PD Ar d no Ar d Ns =.4v Set vertical distance between paragraphs. 91.It Nm \&.PP yes - Same as 92.Nm \&.LP . 93.It Nm \&.RE yes - End of relative indent. Restores prevailing indent. 94.It Nm \&.RB Ar t no Ar t Ns =n.t.l. Join words, alternating roman and bold. 95.It Nm \&.RI Ar t no Ar t Ns =n.t.l. Join words, alternating roman and italic. 96.It Nm \&.RS Ar i yes Ar i Ns =p.i. Start relative indent, increase indent by Ar i . 97Sets prevailing indent to .5i for nested indents. 98.It Nm \&.SB Ar t no - Reduce size of text by 1 point, make text bold. 99.It Nm \&.SH Ar t yes - Section Heading. 100.It Nm \&.SM Ar t no Ar t Ns =n.t.l. Reduce size of text by 1 point. 101.It Nm \&.SS Ar t yes Ar t Ns =n.t.l. Section Subheading. 102.It Nm \&.TH Ar n s d f m yes - Begin reference page Ar n , No of section Ar s ; Ar d No is the date of the most recent change. If present, Ar f No is the left page footer; Ar m No is the main page (center) header. Sets prevailing indent and tabs to .5i. 103.It Nm \&.TP Ar i yes Ar i Ns =p.i. Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to 104.Ar i . 105.It Nm \&.TX Ar t p no - Resolve the title abbreviation Ar t ; No join to punctuation mark (or text) Ar p . 106.El 107.Ss "Conventions" 108When formatting a manual page, 109.Nm 110examines the first line to determine 111whether it requires special processing. For example a first line consisting of: 112.Lp 113.Dl \&'\e" t 114.Lp 115indicates that the manual page must be run through the 116.Xr tbl 1 117preprocessor. 118.Lp 119A typical manual page for a command or function is laid out as follows: 120.Bl -tag -width ".SH RETURN VALUES" 121. 122.It Nm \&.TH Ar title Op "1-9" 123. 124The name of the command or function, which serves as the title of the manual 125page. This is followed by the number of the section in which it appears. 126. 127.It Nm \&.SH NAME 128. 129The name, or list of names, by which the command is called, followed by a dash 130and then a one-line summary of the action performed. All in roman font, this 131section contains no 132.Xr troff 1 133commands or escapes, and no macro requests. 134It is used to generate the database used by the 135.Xr whatis 1 136command. 137. 138.It Nm \&.SH SYNOPSIS 139.Bl -tag -width "Functions:" 140.It Sy Commands: 141The syntax of the command and its arguments, as typed on the command line. 142When in boldface, a word must be typed exactly as printed. When in italics, a 143word can be replaced with an argument that you supply. References to bold or 144italicized items are not capitalized in other sections, even when they begin a 145sentence. 146.Lp 147Syntactic symbols appear in roman face: 148.Bl -tag -width " " 149.It Op " " 150An argument, when surrounded by brackets is optional. 151.It | 152Arguments separated by a vertical bar are exclusive. You can supply only one 153item from such a list. 154.It \&.\|.\|. 155Arguments followed by an ellipsis can be repeated. When an ellipsis follows a 156bracketed set, the expression within the brackets can be repeated. 157.El 158.It Sy Functions: 159If required, the data declaration, or 160.Li #include 161directive, is shown first, 162followed by the function declaration. Otherwise, the function declaration is 163shown. 164.El 165. 166.It Nm \&.SH DESCRIPTION 167. 168A narrative overview of the command or function's external behavior. This 169includes how it interacts with files or data, and how it handles the standard 170input, standard output and standard error. Internals and implementation details 171are normally omitted. This section attempts to provide a succinct overview in 172answer to the question, "what does it do?" 173.Lp 174Literal text from the synopsis appears in constant width, as do literal 175filenames and references to items that appear elsewhere in the reference 176manuals. Arguments are italicized. 177.Lp 178If a command interprets either subcommands or an input grammar, its command 179interface or input grammar is normally described in a 180.Nm USAGE 181section, which follows the 182.Nm OPTIONS 183section. The 184.Nm DESCRIPTION 185section only 186describes the behavior of the command itself, not that of subcommands. 187. 188.It Nm \&.SH OPTIONS 189. 190The list of options along with a description of how each affects the command's 191operation. 192. 193.It Nm \&.SH RETURN VALUES 194. 195A list of the values the library routine will return to the calling program 196and the conditions that cause these values to be returned. 197. 198.It Nm \&.SH EXIT STATUS 199. 200A list of the values the utility will return to the calling program or shell, 201and the conditions that cause these values to be returned. 202. 203.It Nm \&.SH FILES 204. 205A list of files associated with the command or function. 206. 207.It Nm \&.SH SEE ALSO 208. 209A comma-separated list of related manual pages, followed by references to other 210published materials. 211. 212.It Nm \&.SH DIAGNOSTICS 213. 214A list of diagnostic messages and an explanation of each. 215. 216.It Nm \&.SH BUGS 217. 218A description of limitations, known defects, and possible problems associated 219with the command or function. 220.El 221.Sh FILES 222.Pa /usr/share/man/whatis 223.Sh NOTES 224The 225.Nm 226package should not be used for new documentation. The 227.Xr mdoc 5 , 228package is preferred, as it uses semantic markup rather than physical markup. 229.Sh CODE SET INDEPENDENCE 230When processed with 231.Xr mandoc 1 , 232this package is Code Set Independent. However, when processed with 233legacy tools such as 234.Xr nroff 1 235and 236.Xr troff 1 , 237the use of multi-byte characters may not be supported. 238.Sh INTERFACE STABILITY 239.Sy Obsolete Committed . 240The 241.Xr mdoc 5 242package should be used instead. 243.Sh SEE ALSO 244.Xr eqn 1 , 245.Xr man 1 , 246.Xr mandoc 1 , 247.Xr nroff 1 , 248.Xr troff 1 , 249.Xr tbl 1 , 250.Xr whatis 1 , 251.Xr mdoc 5 252.Rs 253.%A Dale Dougherty and Tim O'Reilly 254.%B Unix Text Processing 255.Re 256