Print this page
Latest round of fixes per RM and AL. Fix bugs found in man.c.
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/man.5
+++ new/usr/src/man/man5/man.5
1 -.\"
2 -.\" Permission to use, copy, modify, and distribute this software for any
3 -.\" purpose with or without fee is hereby granted, provided that the above
4 -.\" copyright notice and this permission notice appear in all copies.
5 -.\"
6 -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
7 -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
8 -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
9 -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
10 -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
11 -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
12 -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
13 -.\"
14 -.\"
15 -.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
16 -.\" Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
17 -.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
18 -.\"
19 -.Dd Jan 3, 2012
1 +.\" Copyright (c) 1995, Sun Microsystems, Inc.
2 +.\" 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.
3 +.\" 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.
4 +.\" 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]
5 +.Dd "Jul 19, 2014"
20 6 .Dt MAN 5
21 7 .Os
22 8 .Sh NAME
23 9 .Nm man
24 -.Nd legacy formatting language for manual pages
10 +.Nd macros to format Reference Manual pages
11 +.Sh SYNOPSIS
12 +.Nm mandoc
13 +.Fl T Ar man
14 +.Ar
15 +.Nm nroff
16 +.Fl man
17 +.Ar
18 +.Nm troff
19 +.Fl man
20 +.Ar
25 21 .Sh DESCRIPTION
26 -Traditionally, the
27 -.Nm man
28 -language has been used to write
29 -.Ux
30 -manuals for the
22 +These macros are used to lay out the reference pages in this manual. Note: if
23 +.Ar file
24 +contains format input for a preprocessor, the commands shown
25 +above must be piped through the appropriate preprocessor. This is handled
26 +automatically by the
31 27 .Xr man 1
32 -utility.
33 -It supports limited control of presentational details like fonts,
34 -indentation and spacing.
35 -This reference document describes the structure of manual pages
36 -and the syntax and usage of the man language.
28 +command. See the
29 +.Sx Conventions
30 +section.
31 +.Lp
32 +Any text argument
33 +.Ar t
34 +may be zero to six words. Quotes may be used to
35 +include SPACE characters in a
36 +.Qq word .
37 +If
38 +.Ar text
39 +is empty, the special
40 +treatment is applied to the next input line with text to be printed. In this
41 +way
42 +.Nm \&.I
43 +may be used to italicize a whole line, or
44 +.Nm \&.SB
45 +may be used to make small bold letters.
46 +.Lp
47 +A prevailing indent distance is remembered between successive indented
48 +paragraphs, and is reset to default value upon reaching a non-indented
49 +paragraph. Default units for indents
50 +.Nm i
51 +are ens.
52 +.Lp
53 +Type font and size are reset to default values before each paragraph, and after
54 +processing font and size setting macros.
37 55 .Pp
38 -.Bf -emphasis
39 -Do not use
40 -.Nm
41 -to write your manuals:
42 -.Ef
43 -It lacks support for semantic markup.
44 -Use the
45 -.Xr mdoc 5
46 -language, instead.
47 -.Pp
48 -In a
49 -.Nm
50 -document, lines beginning with the control character
51 -.Sq \&.
52 -are called
53 -.Dq macro lines .
54 -The first word is the macro name.
55 -It usually consists of two capital letters.
56 -For a list of available macros, see
57 -.Sx MACRO OVERVIEW .
58 -The words following the macro name are arguments to the macro.
59 -.Pp
60 -Lines not beginning with the control character are called
61 -.Dq text lines .
62 -They provide free-form text to be printed; the formatting of the text
63 -depends on the respective processing context:
64 -.Bd -literal -offset indent
65 -\&.SH Macro lines change control state.
66 -Text lines are interpreted within the current state.
67 -.Ed
68 -.Pp
69 -Many aspects of the basic syntax of the
70 -.Nm
71 -language are based on the
72 -.Xr roff 5
73 -language; see the
74 -.Em LANGUAGE SYNTAX
75 -and
76 -.Em MACRO SYNTAX
77 -sections in the
78 -.Xr roff 5
79 -manual for details, in particular regarding
80 -comments, escape sequences, whitespace, and quoting.
81 -.Sh MANUAL STRUCTURE
82 -Each
83 -.Nm
84 -document must contain the
85 -.Sx \&TH
86 -macro describing the document's section and title.
87 -It may occur anywhere in the document, although conventionally it
88 -appears as the first macro.
89 -.Pp
90 -Beyond
91 -.Sx \&TH ,
92 -at least one macro or text line must appear in the document.
93 -.Pp
94 -The following is a well-formed skeleton
95 -.Nm
96 -file for a utility
97 -.Qq progname :
98 -.Bd -literal -offset indent
99 -\&.TH PROGNAME 1 "Oct 10, 2009"
100 -\&.SH NAME
101 -\efBprogname\efR \e(en a description goes here
102 -\&.\e\(dq .SH LIBRARY
103 -\&.\e\(dq For sections 2 & 3 only.
104 -\&.SH SYNOPSIS
105 -\efBprogname\efR [\efB\e-options\efR] arguments...
106 -\&.SH DESCRIPTION
107 -The \efBfoo\efR utility processes files...
108 -\&.\e\(dq .SH IMPLEMENTATION NOTES
109 -\&.\e\(dq .SH RETURN VALUES
110 -\&.\e\(dq For sections 2, 3, & 9 only.
111 -\&.\e\(dq .SH ENVIRONMENT
112 -\&.\e\(dq For sections 1, 1M, 5, & 6 only.
113 -\&.\e\(dq .SH FILES
114 -\&.\e\(dq .SH EXIT STATUS
115 -\&.\e\(dq For sections 1, 1M, & 6 only.
116 -\&.\e\(dq .SH EXAMPLES
117 -\&.\e\(dq .SH DIAGNOSTICS
118 -\&.\e\(dq For sections 1, 1M, 5, 6, & 7 only.
119 -\&.\e\(dq .SH ERRORS
120 -\&.\e\(dq For sections 2, 3, & 9 only.
121 -\&.\e\(dq .SH SEE ALSO
122 -\&.\e\(dq .BR foo ( 1 )
123 -\&.\e\(dq .SH STANDARDS
124 -\&.\e\(dq .SH HISTORY
125 -\&.\e\(dq .SH AUTHORS
126 -\&.\e\(dq .SH CAVEATS
127 -\&.\e\(dq .SH BUGS
128 -\&.\e\(dq .SH SECURITY CONSIDERATIONS
129 -.Ed
130 -.Pp
131 -The sections in a
132 -.Nm
133 -document are conventionally ordered as they appear above.
134 -Sections should be composed as follows:
135 -.Bl -ohang -offset indent
136 -.It Em NAME
137 -The name(s) and a short description of the documented material.
138 -The syntax for this is generally as follows:
139 -.Pp
140 -.D1 \efBname\efR \e(en description
141 -.It Em LIBRARY
142 -The name of the library containing the documented material, which is
143 -assumed to be a function in a section 2 or 3 manual.
144 -For functions in the C library, this may be as follows:
145 -.Pp
146 -.D1 Standard C Library (libc, -lc)
147 -.It Em SYNOPSIS
148 -Documents the utility invocation syntax, function call syntax, or device
149 -configuration.
150 -.Pp
151 -For the first, utilities (sections 1, 1M, and 6), this is
152 -generally structured as follows:
153 -.Pp
154 -.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
155 -.Pp
156 -For the second, function calls (sections 2, 3, 9):
157 -.Pp
158 -.D1 \&.B char *name(char *\efIarg\efR);
159 -.Pp
160 -And for the third, configurations (section 7):
161 -.Pp
162 -.D1 \&.B name* at cardbus ? function ?
163 -.Pp
164 -Manuals not in these sections generally don't need a
165 -.Em SYNOPSIS .
166 -.It Em DESCRIPTION
167 -This expands upon the brief, one-line description in
168 -.Em NAME .
169 -It usually contains a break-down of the options (if documenting a
170 -command).
171 -.It Em IMPLEMENTATION NOTES
172 -Implementation-specific notes should be kept here.
173 -This is useful when implementing standard functions that may have side
174 -effects or notable algorithmic implications.
175 -.It Em RETURN VALUES
176 -This section documents the return values of functions in sections 2, 3, and 9.
177 -.It Em ENVIRONMENT
178 -Documents any usages of environment variables, e.g.,
179 -.Xr environ 5 .
180 -.It Em FILES
181 -Documents files used.
182 -It's helpful to document both the file name and a short description of how
183 -the file is used (created, modified, etc.).
184 -.It Em EXIT STATUS
185 -This section documents the command exit status for
186 -section 1, 6, and 8 utilities.
187 -Historically, this information was described in
188 -.Em DIAGNOSTICS ,
189 -a practise that is now discouraged.
190 -.It Em EXAMPLES
191 -Example usages.
192 -This often contains snippets of well-formed,
193 -well-tested invocations.
194 -Make sure that examples work properly!
195 -.It Em DIAGNOSTICS
196 -Documents error conditions.
197 -This is most useful in section 4 manuals.
198 -Historically, this section was used in place of
199 -.Em EXIT STATUS
200 -for manuals in sections 1, 6, and 8; however, this practise is
201 -discouraged.
202 -.It Em ERRORS
203 -Documents error handling in sections 2, 3, and 9.
204 -.It Em SEE ALSO
205 -References other manuals with related topics.
206 -This section should exist for most manuals.
207 -.Pp
208 -.D1 \&.BR bar \&( 1 \&),
209 -.Pp
210 -Cross-references should conventionally be ordered
211 -first by section, then alphabetically.
212 -.It Em STANDARDS
213 -References any standards implemented or used, such as
214 -.Pp
215 -.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
216 -.Pp
217 -If not adhering to any standards, the
218 -.Em HISTORY
219 -section should be used.
220 -.It Em HISTORY
221 -A brief history of the subject, including where support first appeared.
222 -.It Em AUTHORS
223 -Credits to the person or persons who wrote the code and/or documentation.
224 -Authors should generally be noted by both name and email address.
225 -.It Em CAVEATS
226 -Common misuses and misunderstandings should be explained
227 -in this section.
228 -.It Em BUGS
229 -Known bugs, limitations, and work-arounds should be described
230 -in this section.
231 -.It Em SECURITY CONSIDERATIONS
232 -Documents any security precautions that operators should consider.
56 +These strings are predefined by
57 +.Nm -man :
58 +.Bl -tag -width Ds
59 +.It Nm \e*R
60 +.Sq \(rg ,
61 +.Sq (Reg)
62 +in
63 +.Nm nroff .
64 +.It Nm \e*S
65 +Change to default type size.
233 66 .El
234 -.Sh MACRO OVERVIEW
235 -This overview is sorted such that macros of similar purpose are listed
236 -together, to help find the best macro for any given purpose.
237 -Deprecated macros are not included in the overview, but can be found
238 -in the alphabetical reference below.
239 -.Ss Page header and footer meta-data
240 -.Bl -column "PP, LP, P" description
241 -.It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
242 -.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
243 -.It Sx UC Ta display BSD version in the page footer (<= 1 argument)
67 +.Sh "Requests"
68 +* n.t.l. = next text line; p.i. = prevailing indent
69 +.Bl -column ".TH n s d f m" "Cause " "t=n.t.l.*" "Explanation " -offset Ds
70 +.It Sy Request Sy Cause Sy "If No" Sy Explanation
71 +.It "" Sy Break Sy "Argument" ""
72 +.It Nm \&.B Ar "t" no Ar t Ns =n.t.l.* Text is in bold font.
73 +.It Nm \&.BI Ar t no Ar t Ns =n.t.l. Join words, alternating bold and italic.
74 +.It Nm \&.BR Ar t no Ar t Ns =n.t.l. Join words, alternating bold and roman.
75 +.It Nm \&.DT no Li \&.5i 1i... Restore default tabs.
76 +.It Nm \&.HP Ar i yes Ar i Ns =p.i.* "Begin paragraph with hanging indent. Set prevailing indent to" Ar i .
77 +.It Nm \&.I Ar t no Ar t Ns =n.t.l. Text is italic.
78 +.It Nm \&.IB Ar t no Ar t Ns =n.t.l. Join words, altenrating italic and bold.
79 +.It Nm \&.IP Ar x Ar i yes Ar x Ns ="" Same as
80 +.Nm \&.TP
81 +with tag
82 +.Ar x .
83 +.It Nm \&.IR Ar t no Ar t Ns =n.t.l. Join words, alternating italic and roman.
84 +.It Nm \&.IX Ar t no - Index macro, not used (obsolete).
85 +.It Nm \&.LP yes - Begin left-aligned paragraph. Set prevailing indent to .5i.
86 +.It Nm \&.P yes - Same as
87 +.Nm \&.LP .
88 +.It Nm \&.PD Ar d no Ar d Ns =.4v Set vertical distance between paragraphs.
89 +.It Nm \&.PP yes - Same as
90 +.Nm \&.LP .
91 +.It Nm \&.RE yes - End of relative indent. Restores prevailing indent.
92 +.It Nm \&.RB Ar t no Ar t Ns =n.t.l. Join words, alternating roman and bold.
93 +.It Nm \&.RI Ar t no Ar t Ns =n.t.l. Join words, alternating roman and italic.
94 +.It Nm \&.RS Ar i yes Ar i Ns =p.i. Start relative indent, increase indent by Ar i .
95 +Sets prevailing indent to .5i for nested indents.
96 +.It Nm \&.SB Ar t no - Reduce size of text by 1 point, make text bold.
97 +.It Nm \&.SH Ar t yes - Section Heading.
98 +.It Nm \&.SM Ar t no Ar t Ns =n.t.l. Reduce size of text by 1 point.
99 +.It Nm \&.SS Ar t yes Ar t Ns =n.t.l. Section Subheading.
100 +.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.
101 +.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
102 +.Ar i .
103 +.It Nm \&.TX Ar t p no - Resolve the title abbreviation Ar t ; No join to punctuation mark (or text) Ar p .
244 104 .El
245 -.Ss Sections and paragraphs
246 -.Bl -column "PP, LP, P" description
247 -.It Sx SH Ta section header (one line)
248 -.It Sx SS Ta subsection header (one line)
249 -.It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
250 -.It Sx RS , RE Ta reset the left margin: Op Ar width
251 -.It Sx IP Ta indented paragraph: Op Ar head Op Ar width
252 -.It Sx TP Ta tagged paragraph: Op Ar width
253 -.It Sx HP Ta hanged paragraph: Op Ar width
254 -.It Sx \&br Ta force output line break in text mode (no arguments)
255 -.It Sx \&sp Ta force vertical space: Op Ar height
256 -.It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
257 -.It Sx in Ta additional indent: Op Ar width
258 -.El
259 -.Ss Physical markup
260 -.Bl -column "PP, LP, P" description
261 -.It Sx B Ta boldface font
262 -.It Sx I Ta italic font
263 -.It Sx R Ta roman (default) font
264 -.It Sx SB Ta small boldface font
265 -.It Sx SM Ta small roman font
266 -.It Sx BI Ta alternate between boldface and italic fonts
267 -.It Sx BR Ta alternate between boldface and roman fonts
268 -.It Sx IB Ta alternate between italic and boldface fonts
269 -.It Sx IR Ta alternate between italic and roman fonts
270 -.It Sx RB Ta alternate between roman and boldface fonts
271 -.It Sx RI Ta alternate between roman and italic fonts
272 -.El
273 -.Ss Semantic markup
274 -.Bl -column "PP, LP, P" description
275 -.It Sx OP Ta optional arguments
276 -.El
277 -.Sh MACRO REFERENCE
278 -This section is a canonical reference to all macros, arranged
279 -alphabetically.
280 -For the scoping of individual macros, see
281 -.Sx MACRO SYNTAX .
282 -.Ss \&AT
283 -Sets the volume for the footer for compatibility with man pages from
284 -.Tn AT&T UNIX
285 -releases.
286 -The optional arguments specify which release it is from.
287 -.Ss \&B
288 -Text is rendered in bold face.
289 -.Pp
290 -See also
291 -.Sx \&I
292 -and
293 -.Sx \&R .
294 -.Ss \&BI
295 -Text is rendered alternately in bold face and italic.
296 -Thus,
297 -.Sq .BI this word and that
298 -causes
299 -.Sq this
300 -and
301 -.Sq and
302 -to render in bold face, while
303 -.Sq word
304 -and
305 -.Sq that
306 -render in italics.
307 -Whitespace between arguments is omitted in output.
308 -.Pp
309 -Examples:
310 -.Pp
311 -.Dl \&.BI bold italic bold italic
312 -.Pp
313 -The output of this example will be emboldened
314 -.Dq bold
315 -and italicised
316 -.Dq italic ,
317 -with spaces stripped between arguments.
318 -.Pp
319 -See also
320 -.Sx \&IB ,
321 -.Sx \&BR ,
322 -.Sx \&RB ,
323 -.Sx \&RI ,
324 -and
325 -.Sx \&IR .
326 -.Ss \&BR
327 -Text is rendered alternately in bold face and roman (the default font).
328 -Whitespace between arguments is omitted in output.
329 -.Pp
330 -See
331 -.Sx \&BI
332 -for an equivalent example.
333 -.Pp
334 -See also
335 -.Sx \&BI ,
336 -.Sx \&IB ,
337 -.Sx \&RB ,
338 -.Sx \&RI ,
339 -and
340 -.Sx \&IR .
341 -.Ss \&DT
342 -Has no effect.
343 -Included for compatibility.
344 -.Ss \&HP
345 -Begin a paragraph whose initial output line is left-justified, but
346 -subsequent output lines are indented, with the following syntax:
347 -.Bd -filled -offset indent
348 -.Pf \. Sx \&HP
349 -.Op Cm width
350 -.Ed
351 -.Pp
352 -The
353 -.Cm width
354 -argument must conform to
355 -.Sx Scaling Widths .
356 -If specified, it's saved for later paragraph left-margins; if unspecified, the
357 -saved or default width is used.
358 -.Pp
359 -See also
360 -.Sx \&IP ,
361 -.Sx \&LP ,
362 -.Sx \&P ,
363 -.Sx \&PP ,
364 -and
365 -.Sx \&TP .
366 -.Ss \&I
367 -Text is rendered in italics.
368 -.Pp
369 -See also
370 -.Sx \&B
371 -and
372 -.Sx \&R .
373 -.Ss \&IB
374 -Text is rendered alternately in italics and bold face.
375 -Whitespace between arguments is omitted in output.
376 -.Pp
377 -See
378 -.Sx \&BI
379 -for an equivalent example.
380 -.Pp
381 -See also
382 -.Sx \&BI ,
383 -.Sx \&BR ,
384 -.Sx \&RB ,
385 -.Sx \&RI ,
386 -and
387 -.Sx \&IR .
388 -.Ss \&IP
389 -Begin an indented paragraph with the following syntax:
390 -.Bd -filled -offset indent
391 -.Pf \. Sx \&IP
392 -.Op Cm head Op Cm width
393 -.Ed
394 -.Pp
395 -The
396 -.Cm width
397 -argument defines the width of the left margin and is defined by
398 -.Sx Scaling Widths .
399 -It's saved for later paragraph left-margins; if unspecified, the saved or
400 -default width is used.
401 -.Pp
402 -The
403 -.Cm head
404 -argument is used as a leading term, flushed to the left margin.
405 -This is useful for bulleted paragraphs and so on.
406 -.Pp
407 -See also
408 -.Sx \&HP ,
409 -.Sx \&LP ,
410 -.Sx \&P ,
411 -.Sx \&PP ,
412 -and
413 -.Sx \&TP .
414 -.Ss \&IR
415 -Text is rendered alternately in italics and roman (the default font).
416 -Whitespace between arguments is omitted in output.
417 -.Pp
418 -See
419 -.Sx \&BI
420 -for an equivalent example.
421 -.Pp
422 -See also
423 -.Sx \&BI ,
424 -.Sx \&IB ,
425 -.Sx \&BR ,
426 -.Sx \&RB ,
427 -and
428 -.Sx \&RI .
429 -.Ss \&LP
430 -Begin an undecorated paragraph.
431 -The scope of a paragraph is closed by a subsequent paragraph,
432 -sub-section, section, or end of file.
433 -The saved paragraph left-margin width is reset to the default.
434 -.Pp
435 -See also
436 -.Sx \&HP ,
437 -.Sx \&IP ,
438 -.Sx \&P ,
439 -.Sx \&PP ,
440 -and
441 -.Sx \&TP .
442 -.Ss \&OP
443 -Optional command-line argument.
444 -This has the following syntax:
445 -.Bd -filled -offset indent
446 -.Pf \. Sx \&OP
447 -.Cm key Op Cm value
448 -.Ed
449 -.Pp
450 -The
451 -.Cm key
452 -is usually a command-line flag and
453 -.Cm value
454 -its argument.
455 -.Ss \&P
456 -Synonym for
457 -.Sx \&LP .
458 -.Pp
459 -See also
460 -.Sx \&HP ,
461 -.Sx \&IP ,
462 -.Sx \&LP ,
463 -.Sx \&PP ,
464 -and
465 -.Sx \&TP .
466 -.Ss \&PP
467 -Synonym for
468 -.Sx \&LP .
469 -.Pp
470 -See also
471 -.Sx \&HP ,
472 -.Sx \&IP ,
473 -.Sx \&LP ,
474 -.Sx \&P ,
475 -and
476 -.Sx \&TP .
477 -.Ss \&R
478 -Text is rendered in roman (the default font).
479 -.Pp
480 -See also
481 -.Sx \&I
482 -and
483 -.Sx \&B .
484 -.Ss \&RB
485 -Text is rendered alternately in roman (the default font) and bold face.
486 -Whitespace between arguments is omitted in output.
487 -.Pp
488 -See
489 -.Sx \&BI
490 -for an equivalent example.
491 -.Pp
492 -See also
493 -.Sx \&BI ,
494 -.Sx \&IB ,
495 -.Sx \&BR ,
496 -.Sx \&RI ,
497 -and
498 -.Sx \&IR .
499 -.Ss \&RE
500 -Explicitly close out the scope of a prior
501 -.Sx \&RS .
502 -The default left margin is restored to the state of the original
503 -.Sx \&RS
504 -invocation.
505 -.Ss \&RI
506 -Text is rendered alternately in roman (the default font) and italics.
507 -Whitespace between arguments is omitted in output.
508 -.Pp
509 -See
510 -.Sx \&BI
511 -for an equivalent example.
512 -.Pp
513 -See also
514 -.Sx \&BI ,
515 -.Sx \&IB ,
516 -.Sx \&BR ,
517 -.Sx \&RB ,
518 -and
519 -.Sx \&IR .
520 -.Ss \&RS
521 -Temporarily reset the default left margin.
522 -This has the following syntax:
523 -.Bd -filled -offset indent
524 -.Pf \. Sx \&RS
525 -.Op Cm width
526 -.Ed
527 -.Pp
528 -The
529 -.Cm width
530 -argument must conform to
531 -.Sx Scaling Widths .
532 -If not specified, the saved or default width is used.
533 -.Pp
534 -See also
535 -.Sx \&RE .
536 -.Ss \&SB
537 -Text is rendered in small size (one point smaller than the default font)
538 -bold face.
539 -.Ss \&SH
540 -Begin a section.
541 -The scope of a section is only closed by another section or the end of
542 -file.
543 -The paragraph left-margin width is reset to the default.
544 -.Ss \&SM
545 -Text is rendered in small size (one point smaller than the default
546 -font).
547 -.Ss \&SS
548 -Begin a sub-section.
549 -The scope of a sub-section is closed by a subsequent sub-section,
550 -section, or end of file.
551 -The paragraph left-margin width is reset to the default.
552 -.Ss \&TH
553 -Sets the title of the manual page with the following syntax:
554 -.Bd -filled -offset indent
555 -.Pf \. Sx \&TH
556 -.Ar title section date
557 -.Op Ar source Op Ar volume
558 -.Ed
559 -.Pp
560 -Conventionally, the document
561 -.Ar title
562 -is given in all caps.
563 -The recommended
564 -.Ar date
565 -format is
566 -.Sy YYYY-MM-DD
567 -as specified in the ISO-8601 standard;
568 -if the argument does not conform, it is printed verbatim.
569 -If the
570 -.Ar date
571 -is empty or not specified, the current date is used.
572 -The optional
573 -.Ar source
574 -string specifies the organisation providing the utility.
575 -The
576 -.Ar volume
577 -string replaces the default rendered volume, which is dictated by the
578 -manual section.
579 -.Pp
580 -Examples:
581 -.Pp
582 -.Dl \&.TH CVS 5 "1992-02-12" GNU
583 -.Ss \&TP
584 -Begin a paragraph where the head, if exceeding the indentation width, is
585 -followed by a newline; if not, the body follows on the same line after a
586 -buffer to the indentation width.
587 -Subsequent output lines are indented.
588 -The syntax is as follows:
589 -.Bd -filled -offset indent
590 -.Pf \. Sx \&TP
591 -.Op Cm width
592 -.Ed
593 -.Pp
594 -The
595 -.Cm width
596 -argument must conform to
597 -.Sx Scaling Widths .
598 -If specified, it's saved for later paragraph left-margins; if
599 -unspecified, the saved or default width is used.
600 -.Pp
601 -See also
602 -.Sx \&HP ,
603 -.Sx \&IP ,
604 -.Sx \&LP ,
605 -.Sx \&P ,
606 -and
607 -.Sx \&PP .
608 -.Ss \&UC
609 -Sets the volume for the footer for compatibility with man pages from
610 -BSD releases.
611 -The optional first argument specifies which release it is from.
612 -.Ss \&br
613 -Breaks the current line.
614 -Consecutive invocations have no further effect.
615 -.Pp
616 -See also
617 -.Sx \&sp .
618 -.Ss \&fi
619 -End literal mode begun by
620 -.Sx \&nf .
621 -.Ss \&ft
622 -Change the current font mode.
623 -See
624 -.Sx Text Decoration
625 -for a listing of available font modes.
626 -.Ss \&in
627 -Indent relative to the current indentation:
628 -.Pp
629 -.D1 Pf \. Sx \&in Op Cm width
630 -.Pp
631 -If
632 -.Cm width
633 -is signed, the new offset is relative.
634 -Otherwise, it is absolute.
635 -This value is reset upon the next paragraph, section, or sub-section.
636 -.Ss \&na
637 -Don't align to the right margin.
638 -.Ss \&nf
639 -Begin literal mode: all subsequent free-form lines have their end of
640 -line boundaries preserved.
641 -May be ended by
642 -.Sx \&fi .
643 -Literal mode is implicitly ended by
644 -.Sx \&SH
645 -or
646 -.Sx \&SS .
647 -.Ss \&sp
648 -Insert vertical spaces into output with the following syntax:
649 -.Bd -filled -offset indent
650 -.Pf \. Sx \&sp
651 -.Op Cm height
652 -.Ed
653 -.Pp
654 -Insert
655 -.Cm height
656 -spaces, which must conform to
657 -.Sx Scaling Widths .
658 -If 0, this is equivalent to the
659 -.Sx \&br
660 -macro.
661 -Defaults to 1, if unspecified.
662 -.Pp
663 -See also
664 -.Sx \&br .
665 -.Sh MACRO SYNTAX
666 -The
105 +.Ss "Conventions"
106 +When formatting a manual page,
667 107 .Nm
668 -macros are classified by scope: line scope or block scope.
669 -Line macros are only scoped to the current line (and, in some
670 -situations, the subsequent line).
671 -Block macros are scoped to the current line and subsequent lines until
672 -closed by another block macro.
673 -.Ss Line Macros
674 -Line macros are generally scoped to the current line, with the body
675 -consisting of zero or more arguments.
676 -If a macro is scoped to the next line and the line arguments are empty,
677 -the next line, which must be text, is used instead.
678 -Thus:
679 -.Bd -literal -offset indent
680 -\&.I
681 -foo
682 -.Ed
683 -.Pp
684 -is equivalent to
685 -.Sq \&.I foo .
686 -If next-line macros are invoked consecutively, only the last is used.
687 -If a next-line macro is followed by a non-next-line macro, an error is
688 -raised, except for
689 -.Sx \&br ,
690 -.Sx \&sp ,
691 -and
692 -.Sx \&na .
693 -.Pp
694 -The syntax is as follows:
695 -.Bd -literal -offset indent
696 -\&.YO \(lBbody...\(rB
697 -\(lBbody...\(rB
698 -.Ed
699 -.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
700 -.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
701 -.It Sx \&AT Ta <=1 Ta current Ta \&
702 -.It Sx \&B Ta n Ta next-line Ta \&
703 -.It Sx \&BI Ta n Ta current Ta \&
704 -.It Sx \&BR Ta n Ta current Ta \&
705 -.It Sx \&DT Ta 0 Ta current Ta \&
706 -.It Sx \&I Ta n Ta next-line Ta \&
707 -.It Sx \&IB Ta n Ta current Ta \&
708 -.It Sx \&IR Ta n Ta current Ta \&
709 -.It Sx \&OP Ta 0, 1 Ta current Ta compat
710 -.It Sx \&R Ta n Ta next-line Ta \&
711 -.It Sx \&RB Ta n Ta current Ta \&
712 -.It Sx \&RI Ta n Ta current Ta \&
713 -.It Sx \&SB Ta n Ta next-line Ta \&
714 -.It Sx \&SM Ta n Ta next-line Ta \&
715 -.It Sx \&TH Ta >1, <6 Ta current Ta \&
716 -.It Sx \&UC Ta <=1 Ta current Ta \&
717 -.It Sx \&br Ta 0 Ta current Ta compat
718 -.It Sx \&fi Ta 0 Ta current Ta compat
719 -.It Sx \&ft Ta 1 Ta current Ta compat
720 -.It Sx \&in Ta 1 Ta current Ta compat
721 -.It Sx \&na Ta 0 Ta current Ta compat
722 -.It Sx \&nf Ta 0 Ta current Ta compat
723 -.It Sx \&sp Ta 1 Ta current Ta compat
108 +examines the first line to determine
109 +whether it requires special processing. For example a first line consisting of:
110 +.Lp
111 +.Dl \&'\e" t
112 +.Lp
113 +indicates that the manual page must be run through the
114 +.Xr tbl 1
115 +preprocessor.
116 +.Lp
117 +A typical manual page for a command or function is laid out as follows:
118 +.Bl -tag -width ".SH RETURN VALUES"
119 +.
120 +.It Nm \&.TH Ar title Op "1-9"
121 +.
122 +The name of the command or function, which serves as the title of the manual
123 +page. This is followed by the number of the section in which it appears.
124 +.
125 +.It Nm SH NAME
126 +.
127 +The name, or list of names, by which the command is called, followed by a dash
128 +and then a one-line summary of the action performed. All in roman font, this
129 +section contains no
130 +.Xr troff 1
131 +commands or escapes, and no macro requests.
132 +It is used to generate the database used by the
133 +.Xr whatis 1
134 +command.
135 +.
136 +.It Nm SH SYNOPSIS
137 +.Bl -tag -width "Functions:"
138 +.It Sy Commands:
139 +The syntax of the command and its arguments, as typed on the command line.
140 +When in boldface, a word must be typed exactly as printed. When in italics, a
141 +word can be replaced with an argument that you supply. References to bold or
142 +italicized items are not capitalized in other sections, even when they begin a
143 +sentence.
144 +.Lp
145 +Syntactic symbols appear in roman face:
146 +.Bl -tag -width " "
147 +.It Op " "
148 +An argument, when surrounded by brackets is optional.
149 +.It |
150 +Arguments separated by a vertical bar are exclusive. You can supply only one
151 +item from such a list.
152 +.It \&.\|.\|.
153 +Arguments followed by an ellipsis can be repeated. When an ellipsis follows a
154 +bracketed set, the expression within the brackets can be repeated.
724 155 .El
725 -.Pp
726 -Macros marked as
727 -.Qq compat
728 -are included for compatibility with the significant corpus of existing
729 -manuals that mix dialects of roff.
730 -These macros should not be used for portable
731 -.Nm
732 -manuals.
733 -.Ss Block Macros
734 -Block macros comprise a head and body.
735 -As with in-line macros, the head is scoped to the current line and, in
736 -one circumstance, the next line (the next-line stipulations as in
737 -.Sx Line Macros
738 -apply here as well).
739 -.Pp
740 -The syntax is as follows:
741 -.Bd -literal -offset indent
742 -\&.YO \(lBhead...\(rB
743 -\(lBhead...\(rB
744 -\(lBbody...\(rB
745 -.Ed
746 -.Pp
747 -The closure of body scope may be to the section, where a macro is closed
748 -by
749 -.Sx \&SH ;
750 -sub-section, closed by a section or
751 -.Sx \&SS ;
752 -part, closed by a section, sub-section, or
753 -.Sx \&RE ;
754 -or paragraph, closed by a section, sub-section, part,
755 -.Sx \&HP ,
756 -.Sx \&IP ,
757 -.Sx \&LP ,
758 -.Sx \&P ,
759 -.Sx \&PP ,
760 -or
761 -.Sx \&TP .
762 -No closure refers to an explicit block closing macro.
763 -.Pp
764 -As a rule, block macros may not be nested; thus, calling a block macro
765 -while another block macro scope is open, and the open scope is not
766 -implicitly closed, is syntactically incorrect.
767 -.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
768 -.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
769 -.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
770 -.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
771 -.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
772 -.It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
773 -.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
774 -.It Sx \&RE Ta 0 Ta current Ta none Ta compat
775 -.It Sx \&RS Ta 1 Ta current Ta part Ta compat
776 -.It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
777 -.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
778 -.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
156 +.It Sy Functions:
157 +If required, the data declaration, or
158 +.Li #include
159 +directive, is shown first,
160 +followed by the function declaration. Otherwise, the function declaration is
161 +shown.
779 162 .El
780 -.Pp
781 -Macros marked
782 -.Qq compat
783 -are as mentioned in
784 -.Sx Line Macros .
785 -.Pp
786 -If a block macro is next-line scoped, it may only be followed by in-line
787 -macros for decorating text.
788 -.Ss Font handling
789 -In
790 -.Nm
791 -documents, both
792 -.Sx Physical markup
793 -macros and
794 -.Xr roff 5
795 -.Ql \ef
796 -font escape sequences can be used to choose fonts.
797 -In text lines, the effect of manual font selection by escape sequences
798 -only lasts until the next macro invocation; in macro lines, it only lasts
799 -until the end of the macro scope.
800 -Note that macros like
801 -.Sx \&BR
802 -open and close a font scope for each argument.
803 -.Sh COMPATIBILITY
804 -This section documents areas of questionable portability between
805 -implementations of the
806 -.Nm
807 -language.
808 -.Pp
809 -.Bl -dash -compact
810 -.It
811 -Do not depend on
812 -.Sx \&SH
813 -or
814 -.Sx \&SS
815 -to close out a literal context opened with
816 -.Sx \&nf .
817 -This behaviour may not be portable.
818 -.It
819 -In quoted literals, GNU troff allowed pair-wise double-quotes to produce
820 -a standalone double-quote in formatted output.
821 -It is not known whether this behaviour is exhibited by other formatters.
822 -.It
823 -troff suppresses a newline before
824 -.Sq \(aq
825 -macro output; in mandoc, it is an alias for the standard
826 -.Sq \&.
827 -control character.
828 -.It
829 -The
830 -.Sq \eh
831 -.Pq horizontal position ,
832 -.Sq \ev
833 -.Pq vertical position ,
834 -.Sq \em
835 -.Pq text colour ,
836 -.Sq \eM
837 -.Pq text filling colour ,
838 -.Sq \ez
839 -.Pq zero-length character ,
840 -.Sq \ew
841 -.Pq string length ,
842 -.Sq \ek
843 -.Pq horizontal position marker ,
844 -.Sq \eo
845 -.Pq text overstrike ,
846 -and
847 -.Sq \es
848 -.Pq text size
849 -escape sequences are all discarded in mandoc.
850 -.It
851 -The
852 -.Sq \ef
853 -scaling unit is accepted by mandoc, but rendered as the default unit.
854 -.It
855 -The
856 -.Sx \&sp
857 -macro does not accept negative values in mandoc.
858 -In GNU troff, this would result in strange behaviour.
859 -.It
860 -In page header lines, GNU troff versions up to and including 1.21
861 -only print
862 -.Ar volume
863 -names explicitly specified in the
864 -.Sx \&TH
865 -macro; mandoc and newer groff print the default volume name
866 -corresponding to the
867 -.Ar section
868 -number when no
869 -.Ar volume
870 -is given, like in
871 -.Xr mdoc 5 .
163 +.
164 +.It Nm \&.SH DESCRIPTION
165 +.
166 +A narrative overview of the command or function's external behavior. This
167 +includes how it interacts with files or data, and how it handles the standard
168 +input, standard output and standard error. Internals and implementation details
169 +are normally omitted. This section attempts to provide a succinct overview in
170 +answer to the question, "what does it do?"
171 +.Lp
172 +Literal text from the synopsis appears in constant width, as do literal
173 +filenames and references to items that appear elsewhere in the reference
174 +manuals. Arguments are italicized.
175 +.Lp
176 +If a command interprets either subcommands or an input grammar, its command
177 +interface or input grammar is normally described in a
178 +.Nm USAGE
179 +section, which follows the
180 +.Nm OPTIONS
181 +section. The
182 +.Nm DESCRIPTION
183 +section only
184 +describes the behavior of the command itself, not that of subcommands.
185 +.
186 +.It Nm \&.SH OPTIONS
187 +.
188 +The list of options along with a description of how each affects the command's
189 +operation.
190 +.
191 +.It Nm \&.SH RETURN VALUES
192 +.
193 +A list of the values the library routine will return to the calling program
194 +and the conditions that cause these values to be returned.
195 +.
196 +.It Nm \&.SH EXIT STATUS
197 +.
198 +A list of the values the utility will return to the calling program or shell,
199 +and the conditions that cause these values to be returned.
200 +.
201 +.It Nm \&.SH FILES
202 +.
203 +A list of files associated with the command or function.
204 +.
205 +.It Nm \&.SH SEE ALSO
206 +.
207 +A comma-separated list of related manual pages, followed by references to other
208 +published materials.
209 +.
210 +.It Nm \&.SH DIAGNOSTICS
211 +.
212 +A list of diagnostic messages and an explanation of each.
213 +.
214 +.It Nm \&.SH BUGS
215 +.
216 +A description of limitations, known defects, and possible problems associated
217 +with the command or function.
872 218 .El
873 -.Pp
219 +.Sh FILES
220 +.Pa /usr/share/man/whatis
221 +.Sh NOTES
874 222 The
875 -.Sx OP
876 -macro is part of the extended
877 223 .Nm
878 -macro set, and may not be portable to non-GNU troff implementations.
224 +package should not be used for new documentation. The
225 +.Xr mdoc 5 ,
226 +package is preferred, as it uses semantic markup rather than physical markup.
227 +.Sh CODE SET INDEPENDENCE
228 +When processed with
229 +.Xr mandoc 1 ,
230 +this package is Code Set Independent. However, when processed with
231 +legacy tools such as
232 +.Xr nroff 1
233 +and
234 +.Xr troff 1 ,
235 +the use of multi-byte characters may not be supported.
879 236 .Sh INTERFACE STABILITY
880 -.Nm "Obsolete Committed" .
237 +.Nm Obsolete Committed .
238 +The
239 +.Xr mdoc 5
240 +package should be used instead.
881 241 .Sh SEE ALSO
242 +.Xr eqn 1 ,
882 243 .Xr man 1 ,
883 244 .Xr mandoc 1 ,
884 -.Xr eqn 5 ,
885 -.Xr mandoc_char 5 ,
245 +.Xr nroff 1 ,
246 +.Xr troff 1 ,
247 +.Xr tbl 1 ,
248 +.Xr whatis 1 ,
886 249 .Xr mdoc 5 ,
887 -.Xr roff 5 ,
888 -.Xr tbl 5
889 -.Sh HISTORY
890 -The
891 -.Nm
892 -language first appeared as a macro package for the roff typesetting
893 -system in
894 -.At v7 .
895 -It was later rewritten by James Clark as a macro package for groff.
896 -Eric S. Raymond wrote the extended
897 -.Nm
898 -macros for groff in 2007.
899 -The stand-alone implementation that is part of the
900 -.Xr mandoc 1
901 -utility written by Kristaps Dzonsons appeared in
902 -.Ox 4.6 .
903 -.Sh AUTHORS
904 -This
905 -.Nm
906 -reference was written by
907 -.An Kristaps Dzonsons ,
908 -.Mt kristaps@bsd.lv .
909 -.Sh CAVEATS
910 -Do not use this language.
911 -Use
912 -.Xr mdoc 5 ,
913 -instead.
250 +.Rs
251 +.%A Dale Dougherty and Tim O'Reilly
252 +.%B Unix Text Processing
253 +.Re
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX