Annotation of mandoc/man.7, Revision 1.139
1.139 ! schwarze 1: .\" $Id: man.7,v 1.138 2018/08/16 23:43:37 schwarze Exp $
1.1 kristaps 2: .\"
1.115 schwarze 3: .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.139 ! schwarze 4: .\" Copyright (c) 2011-2015, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
! 5: .\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org>
1.122 schwarze 6: .\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
1.1 kristaps 7: .\"
8: .\" Permission to use, copy, modify, and distribute this software for any
1.10 kristaps 9: .\" purpose with or without fee is hereby granted, provided that the above
10: .\" copyright notice and this permission notice appear in all copies.
11: .\"
12: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
13: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
14: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
15: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
16: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
17: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 19: .\"
1.139 ! schwarze 20: .Dd $Mdocdate: August 16 2018 $
1.9 kristaps 21: .Dt MAN 7
1.1 kristaps 22: .Os
23: .Sh NAME
1.32 kristaps 24: .Nm man
1.111 schwarze 25: .Nd legacy formatting language for manual pages
1.1 kristaps 26: .Sh DESCRIPTION
1.111 schwarze 27: Traditionally, the
1.32 kristaps 28: .Nm man
1.111 schwarze 29: language has been used to write
1.32 kristaps 30: .Ux
1.111 schwarze 31: manuals for the
32: .Xr man 1
33: utility.
34: It supports limited control of presentational details like fonts,
35: indentation and spacing.
36: This reference document describes the structure of manual pages
37: and the syntax and usage of the man language.
1.32 kristaps 38: .Pp
39: .Bf -emphasis
1.20 kristaps 40: Do not use
1.32 kristaps 41: .Nm
1.111 schwarze 42: to write your manuals:
1.32 kristaps 43: .Ef
1.111 schwarze 44: It lacks support for semantic markup.
1.19 kristaps 45: Use the
1.32 kristaps 46: .Xr mdoc 7
1.1 kristaps 47: language, instead.
1.32 kristaps 48: .Pp
1.111 schwarze 49: In a
1.32 kristaps 50: .Nm
1.111 schwarze 51: document, lines beginning with the control character
1.32 kristaps 52: .Sq \&.
1.111 schwarze 53: are called
54: .Dq macro lines .
55: The first word is the macro name.
56: It usually consists of two capital letters.
57: For a list of available macros, see
58: .Sx MACRO OVERVIEW .
59: The words following the macro name are arguments to the macro.
60: .Pp
61: Lines not beginning with the control character are called
62: .Dq text lines .
63: They provide free-form text to be printed; the formatting of the text
64: depends on the respective processing context:
1.32 kristaps 65: .Bd -literal -offset indent
1.1 kristaps 66: \&.SH Macro lines change control state.
1.106 kristaps 67: Text lines are interpreted within the current state.
1.32 kristaps 68: .Ed
1.103 kristaps 69: .Pp
1.111 schwarze 70: Many aspects of the basic syntax of the
1.103 kristaps 71: .Nm
1.111 schwarze 72: language are based on the
73: .Xr roff 7
74: language; see the
75: .Em LANGUAGE SYNTAX
1.106 kristaps 76: and
1.111 schwarze 77: .Em MACRO SYNTAX
78: sections in the
79: .Xr roff 7
80: manual for details, in particular regarding
81: comments, escape sequences, whitespace, and quoting.
1.22 kristaps 82: .Sh MANUAL STRUCTURE
1.16 kristaps 83: Each
1.32 kristaps 84: .Nm
1.80 kristaps 85: document must contain the
1.39 kristaps 86: .Sx \&TH
1.68 kristaps 87: macro describing the document's section and title.
1.80 kristaps 88: It may occur anywhere in the document, although conventionally it
1.68 kristaps 89: appears as the first macro.
1.32 kristaps 90: .Pp
1.22 kristaps 91: Beyond
1.39 kristaps 92: .Sx \&TH ,
1.111 schwarze 93: at least one macro or text line must appear in the document.
1.100 kristaps 94: .Pp
95: The following is a well-formed skeleton
96: .Nm
97: file for a utility
98: .Qq progname :
1.32 kristaps 99: .Bd -literal -offset indent
1.100 kristaps 100: \&.TH PROGNAME 1 2009-10-10
1.22 kristaps 101: \&.SH NAME
1.124 schwarze 102: \efBprogname\efR \e(en one line about what it does
1.106 kristaps 103: \&.\e\(dq .SH LIBRARY
1.124 schwarze 104: \&.\e\(dq For sections 2, 3, and 9 only.
1.106 kristaps 105: \&.\e\(dq Not used in OpenBSD.
1.22 kristaps 106: \&.SH SYNOPSIS
1.124 schwarze 107: \efBprogname\efR [\efB\e-options\efR] \efIfile ...\efR
1.22 kristaps 108: \&.SH DESCRIPTION
1.124 schwarze 109: The \efBfoo\efR utility processes files ...
1.126 schwarze 110: \&.\e\(dq .Sh CONTEXT
111: \&.\e\(dq For section 9 functions only.
1.106 kristaps 112: \&.\e\(dq .SH IMPLEMENTATION NOTES
113: \&.\e\(dq Not used in OpenBSD.
114: \&.\e\(dq .SH RETURN VALUES
1.124 schwarze 115: \&.\e\(dq For sections 2, 3, and 9 function return values only.
1.106 kristaps 116: \&.\e\(dq .SH ENVIRONMENT
1.124 schwarze 117: \&.\e\(dq For sections 1, 6, 7, and 8 only.
1.106 kristaps 118: \&.\e\(dq .SH FILES
119: \&.\e\(dq .SH EXIT STATUS
1.124 schwarze 120: \&.\e\(dq For sections 1, 6, and 8 only.
1.106 kristaps 121: \&.\e\(dq .SH EXAMPLES
122: \&.\e\(dq .SH DIAGNOSTICS
1.124 schwarze 123: \&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
1.106 kristaps 124: \&.\e\(dq .SH ERRORS
1.124 schwarze 125: \&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
1.106 kristaps 126: \&.\e\(dq .SH SEE ALSO
1.124 schwarze 127: \&.\e\(dq .BR foobar ( 1 )
1.106 kristaps 128: \&.\e\(dq .SH STANDARDS
129: \&.\e\(dq .SH HISTORY
130: \&.\e\(dq .SH AUTHORS
131: \&.\e\(dq .SH CAVEATS
132: \&.\e\(dq .SH BUGS
133: \&.\e\(dq .SH SECURITY CONSIDERATIONS
134: \&.\e\(dq Not used in OpenBSD.
1.32 kristaps 135: .Ed
1.41 kristaps 136: .Pp
137: The sections in a
138: .Nm
1.68 kristaps 139: document are conventionally ordered as they appear above.
140: Sections should be composed as follows:
1.42 kristaps 141: .Bl -ohang -offset indent
142: .It Em NAME
1.68 kristaps 143: The name(s) and a short description of the documented material.
144: The syntax for this is generally as follows:
1.41 kristaps 145: .Pp
146: .D1 \efBname\efR \e(en description
1.42 kristaps 147: .It Em LIBRARY
1.41 kristaps 148: The name of the library containing the documented material, which is
1.68 kristaps 149: assumed to be a function in a section 2 or 3 manual.
150: For functions in the C library, this may be as follows:
1.41 kristaps 151: .Pp
152: .D1 Standard C Library (libc, -lc)
1.42 kristaps 153: .It Em SYNOPSIS
1.41 kristaps 154: Documents the utility invocation syntax, function call syntax, or device
1.55 kristaps 155: configuration.
1.41 kristaps 156: .Pp
157: For the first, utilities (sections 1, 6, and 8), this is
158: generally structured as follows:
159: .Pp
160: .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
161: .Pp
162: For the second, function calls (sections 2, 3, 9):
163: .Pp
1.44 kristaps 164: .D1 \&.B char *name(char *\efIarg\efR);
1.41 kristaps 165: .Pp
166: And for the third, configurations (section 4):
167: .Pp
1.44 kristaps 168: .D1 \&.B name* at cardbus ? function ?
1.41 kristaps 169: .Pp
1.55 kristaps 170: Manuals not in these sections generally don't need a
1.42 kristaps 171: .Em SYNOPSIS .
172: .It Em DESCRIPTION
1.55 kristaps 173: This expands upon the brief, one-line description in
1.42 kristaps 174: .Em NAME .
175: It usually contains a break-down of the options (if documenting a
176: command).
1.126 schwarze 177: .It Em CONTEXT
178: This section lists the contexts in which functions can be called in section 9.
179: The contexts are autoconf, process, or interrupt.
1.42 kristaps 180: .It Em IMPLEMENTATION NOTES
1.68 kristaps 181: Implementation-specific notes should be kept here.
182: This is useful when implementing standard functions that may have side
183: effects or notable algorithmic implications.
1.42 kristaps 184: .It Em RETURN VALUES
1.80 kristaps 185: This section documents the return values of functions in sections 2, 3, and 9.
1.42 kristaps 186: .It Em ENVIRONMENT
187: Documents any usages of environment variables, e.g.,
188: .Xr environ 7 .
189: .It Em FILES
1.68 kristaps 190: Documents files used.
1.78 schwarze 191: It's helpful to document both the file name and a short description of how
1.68 kristaps 192: the file is used (created, modified, etc.).
1.67 kristaps 193: .It Em EXIT STATUS
1.80 kristaps 194: This section documents the command exit status for
195: section 1, 6, and 8 utilities.
1.68 kristaps 196: Historically, this information was described in
1.67 kristaps 197: .Em DIAGNOSTICS ,
198: a practise that is now discouraged.
1.42 kristaps 199: .It Em EXAMPLES
1.68 kristaps 200: Example usages.
201: This often contains snippets of well-formed,
202: well-tested invocations.
1.80 kristaps 203: Make sure that examples work properly!
1.42 kristaps 204: .It Em DIAGNOSTICS
1.68 kristaps 205: Documents error conditions.
1.124 schwarze 206: In section 4 and 9 manuals, these are usually messages
207: printed by the kernel to the console and to the kernel log.
208: In section 1, 6, 7, and 8, these are usually messages
209: printed by userland programs to the standard error output.
210: .Pp
1.42 kristaps 211: Historically, this section was used in place of
212: .Em EXIT STATUS
213: for manuals in sections 1, 6, and 8; however, this practise is
214: discouraged.
215: .It Em ERRORS
1.124 schwarze 216: Documents
217: .Xr errno 2
218: settings in sections 2, 3, 4, and 9.
1.42 kristaps 219: .It Em SEE ALSO
1.68 kristaps 220: References other manuals with related topics.
221: This section should exist for most manuals.
1.44 kristaps 222: .Pp
223: .D1 \&.BR bar \&( 1 \&),
224: .Pp
225: Cross-references should conventionally be ordered
1.42 kristaps 226: first by section, then alphabetically.
227: .It Em STANDARDS
228: References any standards implemented or used, such as
229: .Pp
230: .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
231: .Pp
232: If not adhering to any standards, the
233: .Em HISTORY
234: section should be used.
235: .It Em HISTORY
1.81 schwarze 236: A brief history of the subject, including where support first appeared.
1.42 kristaps 237: .It Em AUTHORS
1.81 schwarze 238: Credits to the person or persons who wrote the code and/or documentation.
1.78 schwarze 239: Authors should generally be noted by both name and email address.
1.42 kristaps 240: .It Em CAVEATS
1.78 schwarze 241: Common misuses and misunderstandings should be explained
1.42 kristaps 242: in this section.
243: .It Em BUGS
1.80 kristaps 244: Known bugs, limitations, and work-arounds should be described
1.78 schwarze 245: in this section.
1.42 kristaps 246: .It Em SECURITY CONSIDERATIONS
247: Documents any security precautions that operators should consider.
1.41 kristaps 248: .El
1.110 schwarze 249: .Sh MACRO OVERVIEW
250: This overview is sorted such that macros of similar purpose are listed
251: together, to help find the best macro for any given purpose.
252: Deprecated macros are not included in the overview, but can be found
253: in the alphabetical reference below.
254: .Ss Page header and footer meta-data
255: .Bl -column "PP, LP, P" description
256: .It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
257: .It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
258: .It Sx UC Ta display BSD version in the page footer (<= 1 argument)
259: .El
260: .Ss Sections and paragraphs
261: .Bl -column "PP, LP, P" description
262: .It Sx SH Ta section header (one line)
263: .It Sx SS Ta subsection header (one line)
264: .It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
265: .It Sx RS , RE Ta reset the left margin: Op Ar width
266: .It Sx IP Ta indented paragraph: Op Ar head Op Ar width
267: .It Sx TP Ta tagged paragraph: Op Ar width
268: .It Sx HP Ta hanged paragraph: Op Ar width
1.118 schwarze 269: .It Sx PD Ta set vertical paragraph distance: Op Ar height
1.110 schwarze 270: .It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
271: .It Sx in Ta additional indent: Op Ar width
272: .El
273: .Ss Physical markup
274: .Bl -column "PP, LP, P" description
275: .It Sx B Ta boldface font
276: .It Sx I Ta italic font
277: .It Sx SB Ta small boldface font
278: .It Sx SM Ta small roman font
279: .It Sx BI Ta alternate between boldface and italic fonts
280: .It Sx BR Ta alternate between boldface and roman fonts
281: .It Sx IB Ta alternate between italic and boldface fonts
282: .It Sx IR Ta alternate between italic and roman fonts
283: .It Sx RB Ta alternate between roman and boldface fonts
284: .It Sx RI Ta alternate between roman and italic fonts
285: .El
1.111 schwarze 286: .Sh MACRO REFERENCE
1.22 kristaps 287: This section is a canonical reference to all macros, arranged
1.68 kristaps 288: alphabetically.
289: For the scoping of individual macros, see
1.32 kristaps 290: .Sx MACRO SYNTAX .
1.72 joerg 291: .Ss \&AT
292: Sets the volume for the footer for compatibility with man pages from
1.123 schwarze 293: .At
1.72 joerg 294: releases.
295: The optional arguments specify which release it is from.
1.39 kristaps 296: .Ss \&B
1.22 kristaps 297: Text is rendered in bold face.
1.44 kristaps 298: .Pp
299: See also
1.137 schwarze 300: .Sx \&I .
1.39 kristaps 301: .Ss \&BI
1.68 kristaps 302: Text is rendered alternately in bold face and italic.
303: Thus,
1.32 kristaps 304: .Sq .BI this word and that
1.22 kristaps 305: causes
1.32 kristaps 306: .Sq this
1.22 kristaps 307: and
1.32 kristaps 308: .Sq and
1.55 kristaps 309: to render in bold face, while
1.32 kristaps 310: .Sq word
1.22 kristaps 311: and
1.32 kristaps 312: .Sq that
1.68 kristaps 313: render in italics.
314: Whitespace between arguments is omitted in output.
1.44 kristaps 315: .Pp
316: Examples:
1.46 kristaps 317: .Pp
1.93 kristaps 318: .Dl \&.BI bold italic bold italic
1.44 kristaps 319: .Pp
320: The output of this example will be emboldened
321: .Dq bold
322: and italicised
323: .Dq italic ,
324: with spaces stripped between arguments.
325: .Pp
326: See also
327: .Sx \&IB ,
328: .Sx \&BR ,
329: .Sx \&RB ,
330: .Sx \&RI ,
331: and
332: .Sx \&IR .
1.39 kristaps 333: .Ss \&BR
1.22 kristaps 334: Text is rendered alternately in bold face and roman (the default font).
335: Whitespace between arguments is omitted in output.
1.44 kristaps 336: .Pp
337: See
338: .Sx \&BI
339: for an equivalent example.
340: .Pp
341: See also
342: .Sx \&BI ,
343: .Sx \&IB ,
344: .Sx \&RB ,
345: .Sx \&RI ,
346: and
347: .Sx \&IR .
1.39 kristaps 348: .Ss \&DT
1.135 schwarze 349: Restore the default tabulator positions.
350: They are at intervals of 0.5 inches.
351: This has no effect unless the tabulator positions were changed with the
352: .Xr roff 7
353: .Ic \&ta
354: request.
1.116 schwarze 355: .Ss \&EE
356: This is a non-standard GNU extension, included only for compatibility.
357: In
358: .Xr mandoc 1 ,
359: it does the same as
360: .Sx \&fi .
361: .Ss \&EX
362: This is a non-standard GNU extension, included only for compatibility.
363: In
364: .Xr mandoc 1 ,
365: it does the same as
366: .Sx \&nf .
1.39 kristaps 367: .Ss \&HP
1.23 kristaps 368: Begin a paragraph whose initial output line is left-justified, but
1.27 kristaps 369: subsequent output lines are indented, with the following syntax:
1.44 kristaps 370: .Bd -filled -offset indent
371: .Pf \. Sx \&HP
1.130 schwarze 372: .Op Ar width
1.32 kristaps 373: .Ed
1.44 kristaps 374: .Pp
375: The
1.130 schwarze 376: .Ar width
1.117 schwarze 377: argument is a
378: .Xr roff 7
379: scaling width.
1.44 kristaps 380: If specified, it's saved for later paragraph left-margins; if unspecified, the
381: saved or default width is used.
382: .Pp
383: See also
1.45 kristaps 384: .Sx \&IP ,
385: .Sx \&LP ,
386: .Sx \&P ,
387: .Sx \&PP ,
1.44 kristaps 388: and
1.45 kristaps 389: .Sx \&TP .
1.39 kristaps 390: .Ss \&I
1.22 kristaps 391: Text is rendered in italics.
1.44 kristaps 392: .Pp
393: See also
1.137 schwarze 394: .Sx \&B .
1.39 kristaps 395: .Ss \&IB
1.80 kristaps 396: Text is rendered alternately in italics and bold face.
397: Whitespace between arguments is omitted in output.
1.44 kristaps 398: .Pp
399: See
400: .Sx \&BI
401: for an equivalent example.
402: .Pp
403: See also
404: .Sx \&BI ,
405: .Sx \&BR ,
406: .Sx \&RB ,
407: .Sx \&RI ,
408: and
409: .Sx \&IR .
1.39 kristaps 410: .Ss \&IP
1.44 kristaps 411: Begin an indented paragraph with the following syntax:
412: .Bd -filled -offset indent
413: .Pf \. Sx \&IP
1.130 schwarze 414: .Op Ar head Op Ar width
1.32 kristaps 415: .Ed
1.44 kristaps 416: .Pp
417: The
1.130 schwarze 418: .Ar width
1.117 schwarze 419: argument is a
420: .Xr roff 7
421: scaling width defining the left margin.
1.44 kristaps 422: It's saved for later paragraph left-margins; if unspecified, the saved or
423: default width is used.
424: .Pp
425: The
1.130 schwarze 426: .Ar head
1.68 kristaps 427: argument is used as a leading term, flushed to the left margin.
428: This is useful for bulleted paragraphs and so on.
1.44 kristaps 429: .Pp
430: See also
1.45 kristaps 431: .Sx \&HP ,
432: .Sx \&LP ,
433: .Sx \&P ,
434: .Sx \&PP ,
1.44 kristaps 435: and
1.45 kristaps 436: .Sx \&TP .
1.39 kristaps 437: .Ss \&IR
1.22 kristaps 438: Text is rendered alternately in italics and roman (the default font).
439: Whitespace between arguments is omitted in output.
1.44 kristaps 440: .Pp
441: See
442: .Sx \&BI
443: for an equivalent example.
444: .Pp
445: See also
446: .Sx \&BI ,
447: .Sx \&IB ,
448: .Sx \&BR ,
449: .Sx \&RB ,
450: and
451: .Sx \&RI .
1.39 kristaps 452: .Ss \&LP
1.68 kristaps 453: Begin an undecorated paragraph.
454: The scope of a paragraph is closed by a subsequent paragraph,
455: sub-section, section, or end of file.
1.78 schwarze 456: The saved paragraph left-margin width is reset to the default.
1.44 kristaps 457: .Pp
458: See also
1.45 kristaps 459: .Sx \&HP ,
460: .Sx \&IP ,
461: .Sx \&P ,
462: .Sx \&PP ,
1.44 kristaps 463: and
1.45 kristaps 464: .Sx \&TP .
1.136 schwarze 465: .Ss \&ME
466: End a mailto block.
467: This is a non-standard GNU extension, included only for compatibility.
468: See
469: .Sx \&MT .
470: .Ss \&MT
471: Begin a mailto block.
472: This is a non-standard GNU extension, included only for compatibility.
473: It has the following syntax:
474: .Bd -literal -offset indent
475: .Pf \. Sx \&MT Ar address
476: link description to be shown
477: .Pf \. Sx ME
478: .Ed
1.113 kristaps 479: .Ss \&OP
480: Optional command-line argument.
1.114 schwarze 481: This is a non-standard GNU extension, included only for compatibility.
482: It has the following syntax:
1.113 kristaps 483: .Bd -filled -offset indent
484: .Pf \. Sx \&OP
1.130 schwarze 485: .Ar key Op Ar value
1.113 kristaps 486: .Ed
487: .Pp
488: The
1.130 schwarze 489: .Ar key
1.113 kristaps 490: is usually a command-line flag and
1.130 schwarze 491: .Ar value
1.113 kristaps 492: its argument.
1.39 kristaps 493: .Ss \&P
494: Synonym for
495: .Sx \&LP .
1.44 kristaps 496: .Pp
497: See also
1.45 kristaps 498: .Sx \&HP ,
499: .Sx \&IP ,
500: .Sx \&LP ,
501: .Sx \&PP ,
1.118 schwarze 502: and
503: .Sx \&TP .
504: .Ss \&PD
505: Specify the vertical space to be inserted before each new paragraph.
506: .br
507: The syntax is as follows:
508: .Bd -filled -offset indent
509: .Pf \. Sx \&PD
1.130 schwarze 510: .Op Ar height
1.118 schwarze 511: .Ed
512: .Pp
513: The
1.130 schwarze 514: .Ar height
1.118 schwarze 515: argument is a
516: .Xr roff 7
517: scaling width.
518: It defaults to
519: .Cm 1v .
520: If the unit is omitted,
521: .Cm v
522: is assumed.
523: .Pp
524: This macro affects the spacing before any subsequent instances of
525: .Sx \&HP ,
526: .Sx \&IP ,
527: .Sx \&LP ,
528: .Sx \&P ,
529: .Sx \&PP ,
530: .Sx \&SH ,
531: .Sx \&SS ,
1.44 kristaps 532: and
1.45 kristaps 533: .Sx \&TP .
1.39 kristaps 534: .Ss \&PP
535: Synonym for
536: .Sx \&LP .
1.44 kristaps 537: .Pp
538: See also
1.45 kristaps 539: .Sx \&HP ,
540: .Sx \&IP ,
541: .Sx \&LP ,
542: .Sx \&P ,
1.44 kristaps 543: and
1.45 kristaps 544: .Sx \&TP .
1.39 kristaps 545: .Ss \&RB
1.22 kristaps 546: Text is rendered alternately in roman (the default font) and bold face.
547: Whitespace between arguments is omitted in output.
1.44 kristaps 548: .Pp
549: See
550: .Sx \&BI
551: for an equivalent example.
552: .Pp
553: See also
554: .Sx \&BI ,
555: .Sx \&IB ,
556: .Sx \&BR ,
557: .Sx \&RI ,
558: and
559: .Sx \&IR .
1.39 kristaps 560: .Ss \&RE
1.30 kristaps 561: Explicitly close out the scope of a prior
1.39 kristaps 562: .Sx \&RS .
1.129 schwarze 563: The default left margin is restored to the state before that
1.102 kristaps 564: .Sx \&RS
565: invocation.
1.129 schwarze 566: .Pp
567: The syntax is as follows:
568: .Bd -filled -offset indent
569: .Pf \. Sx \&RE
570: .Op Ar level
571: .Ed
572: .Pp
573: Without an argument, the most recent
574: .Sx \&RS
575: block is closed out.
576: If
577: .Ar level
578: is 1, all open
579: .Sx \&RS
580: blocks are closed out.
581: Otherwise,
582: .Ar level No \(mi 1
583: nested
584: .Sx \&RS
585: blocks remain open.
1.39 kristaps 586: .Ss \&RI
1.22 kristaps 587: Text is rendered alternately in roman (the default font) and italics.
588: Whitespace between arguments is omitted in output.
1.44 kristaps 589: .Pp
590: See
591: .Sx \&BI
592: for an equivalent example.
593: .Pp
594: See also
595: .Sx \&BI ,
596: .Sx \&IB ,
597: .Sx \&BR ,
598: .Sx \&RB ,
599: and
600: .Sx \&IR .
1.39 kristaps 601: .Ss \&RS
1.102 kristaps 602: Temporarily reset the default left margin.
1.44 kristaps 603: This has the following syntax:
604: .Bd -filled -offset indent
1.102 kristaps 605: .Pf \. Sx \&RS
1.130 schwarze 606: .Op Ar width
1.32 kristaps 607: .Ed
1.44 kristaps 608: .Pp
609: The
1.130 schwarze 610: .Ar width
1.117 schwarze 611: argument is a
612: .Xr roff 7
613: scaling width.
1.55 kristaps 614: If not specified, the saved or default width is used.
1.102 kristaps 615: .Pp
616: See also
617: .Sx \&RE .
1.39 kristaps 618: .Ss \&SB
1.22 kristaps 619: Text is rendered in small size (one point smaller than the default font)
620: bold face.
1.39 kristaps 621: .Ss \&SH
1.68 kristaps 622: Begin a section.
623: The scope of a section is only closed by another section or the end of
624: file.
1.78 schwarze 625: The paragraph left-margin width is reset to the default.
1.39 kristaps 626: .Ss \&SM
1.22 kristaps 627: Text is rendered in small size (one point smaller than the default
628: font).
1.39 kristaps 629: .Ss \&SS
1.68 kristaps 630: Begin a sub-section.
631: The scope of a sub-section is closed by a subsequent sub-section,
632: section, or end of file.
1.78 schwarze 633: The paragraph left-margin width is reset to the default.
1.139 ! schwarze 634: .Ss \&SY
! 635: Begin a synopsis block with the following syntax:
! 636: .Bd -unfilled -offset indent
! 637: .Pf \. Sx \&SY Ar command
! 638: .Ar arguments
! 639: .Pf \. Sx \&YS
! 640: .Ed
! 641: .Pp
! 642: This is a non-standard GNU extension
! 643: and very rarely used even in GNU manual pages.
! 644: Formatting is similar to
! 645: .Sx \&IP .
1.39 kristaps 646: .Ss \&TH
1.128 schwarze 647: Sets the title of the manual page for use in the page header
648: and footer with the following syntax:
1.44 kristaps 649: .Bd -filled -offset indent
650: .Pf \. Sx \&TH
1.99 schwarze 651: .Ar title section date
652: .Op Ar source Op Ar volume
1.44 kristaps 653: .Ed
1.43 kristaps 654: .Pp
1.99 schwarze 655: Conventionally, the document
656: .Ar title
657: is given in all caps.
658: The recommended
659: .Ar date
660: format is
661: .Sy YYYY-MM-DD
662: as specified in the ISO-8601 standard;
663: if the argument does not conform, it is printed verbatim.
664: If the
665: .Ar date
666: is empty or not specified, the current date is used.
667: The optional
668: .Ar source
1.68 kristaps 669: string specifies the organisation providing the utility.
1.128 schwarze 670: When unspecified,
671: .Xr mandoc 1
672: uses its
673: .Fl Ios
674: argument.
1.68 kristaps 675: The
1.99 schwarze 676: .Ar volume
1.43 kristaps 677: string replaces the default rendered volume, which is dictated by the
678: manual section.
679: .Pp
680: Examples:
1.46 kristaps 681: .Pp
1.93 kristaps 682: .Dl \&.TH CVS 5 "1992-02-12" GNU
1.39 kristaps 683: .Ss \&TP
1.25 kristaps 684: Begin a paragraph where the head, if exceeding the indentation width, is
1.24 kristaps 685: followed by a newline; if not, the body follows on the same line after a
1.68 kristaps 686: buffer to the indentation width.
687: Subsequent output lines are indented.
1.44 kristaps 688: The syntax is as follows:
689: .Bd -filled -offset indent
690: .Pf \. Sx \&TP
1.130 schwarze 691: .Op Ar width
1.32 kristaps 692: .Ed
693: .Pp
1.44 kristaps 694: The
1.130 schwarze 695: .Ar width
1.117 schwarze 696: argument is a
697: .Xr roff 7
698: scaling width.
1.44 kristaps 699: If specified, it's saved for later paragraph left-margins; if
1.27 kristaps 700: unspecified, the saved or default width is used.
1.44 kristaps 701: .Pp
702: See also
1.45 kristaps 703: .Sx \&HP ,
704: .Sx \&IP ,
705: .Sx \&LP ,
706: .Sx \&P ,
1.44 kristaps 707: and
1.45 kristaps 708: .Sx \&PP .
1.138 schwarze 709: .Ss \&TQ
710: Like
711: .Sx \&TP ,
712: except that no vertical spacing is inserted before the paragraph.
713: This is a non-standard GNU extension and rarely used even by GNU
714: manual pages.
1.72 joerg 715: .Ss \&UC
716: Sets the volume for the footer for compatibility with man pages from
1.120 schwarze 717: .Bx
718: releases.
1.72 joerg 719: The optional first argument specifies which release it is from.
1.121 schwarze 720: .Ss \&UE
721: End a uniform resource identifier block.
722: This is a non-standard GNU extension, included only for compatibility.
723: See
724: .Sx \&UE .
725: .Ss \&UR
726: Begin a uniform resource identifier block.
727: This is a non-standard GNU extension, included only for compatibility.
728: It has the following syntax:
729: .Bd -literal -offset indent
730: .Pf \. Sx \&UR Ar uri
731: link description to be shown
732: .Pf \. Sx UE
733: .Ed
1.139 ! schwarze 734: .Ss \&YS
! 735: End a synopsis block started by
! 736: .Pf \. Sx SY .
! 737: This is a non-standard GNU extension.
1.39 kristaps 738: .Ss \&fi
1.22 kristaps 739: End literal mode begun by
1.39 kristaps 740: .Sx \&nf .
1.79 kristaps 741: .Ss \&in
742: Indent relative to the current indentation:
743: .Pp
1.130 schwarze 744: .D1 Pf \. Sx \&in Op Ar width
1.79 kristaps 745: .Pp
746: If
1.130 schwarze 747: .Ar width
1.79 kristaps 748: is signed, the new offset is relative.
749: Otherwise, it is absolute.
750: This value is reset upon the next paragraph, section, or sub-section.
1.39 kristaps 751: .Ss \&nf
1.22 kristaps 752: Begin literal mode: all subsequent free-form lines have their end of
1.68 kristaps 753: line boundaries preserved.
754: May be ended by
1.39 kristaps 755: .Sx \&fi .
1.101 kristaps 756: Literal mode is implicitly ended by
757: .Sx \&SH
758: or
759: .Sx \&SS .
1.111 schwarze 760: .Sh MACRO SYNTAX
761: The
762: .Nm
763: macros are classified by scope: line scope or block scope.
764: Line macros are only scoped to the current line (and, in some
765: situations, the subsequent line).
766: Block macros are scoped to the current line and subsequent lines until
767: closed by another block macro.
768: .Ss Line Macros
769: Line macros are generally scoped to the current line, with the body
770: consisting of zero or more arguments.
771: If a macro is scoped to the next line and the line arguments are empty,
772: the next line, which must be text, is used instead.
773: Thus:
774: .Bd -literal -offset indent
775: \&.I
776: foo
777: .Ed
778: .Pp
779: is equivalent to
780: .Sq \&.I foo .
781: If next-line macros are invoked consecutively, only the last is used.
782: If a next-line macro is followed by a non-next-line macro, an error is
1.134 schwarze 783: raised.
1.111 schwarze 784: .Pp
785: The syntax is as follows:
786: .Bd -literal -offset indent
787: \&.YO \(lBbody...\(rB
788: \(lBbody...\(rB
789: .Ed
790: .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
791: .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
792: .It Sx \&AT Ta <=1 Ta current Ta \&
793: .It Sx \&B Ta n Ta next-line Ta \&
794: .It Sx \&BI Ta n Ta current Ta \&
795: .It Sx \&BR Ta n Ta current Ta \&
796: .It Sx \&DT Ta 0 Ta current Ta \&
1.121 schwarze 797: .It Sx \&EE Ta 0 Ta current Ta compat
798: .It Sx \&EX Ta 0 Ta current Ta compat
1.111 schwarze 799: .It Sx \&I Ta n Ta next-line Ta \&
800: .It Sx \&IB Ta n Ta current Ta \&
801: .It Sx \&IR Ta n Ta current Ta \&
1.113 kristaps 802: .It Sx \&OP Ta 0, 1 Ta current Ta compat
1.121 schwarze 803: .It Sx \&PD Ta 1 Ta current Ta \&
1.111 schwarze 804: .It Sx \&RB Ta n Ta current Ta \&
805: .It Sx \&RI Ta n Ta current Ta \&
806: .It Sx \&SB Ta n Ta next-line Ta \&
807: .It Sx \&SM Ta n Ta next-line Ta \&
808: .It Sx \&TH Ta >1, <6 Ta current Ta \&
809: .It Sx \&UC Ta <=1 Ta current Ta \&
810: .It Sx \&fi Ta 0 Ta current Ta compat
811: .It Sx \&in Ta 1 Ta current Ta compat
812: .It Sx \&nf Ta 0 Ta current Ta compat
813: .El
814: .Pp
815: Macros marked as
816: .Qq compat
817: are included for compatibility with the significant corpus of existing
818: manuals that mix dialects of roff.
819: These macros should not be used for portable
820: .Nm
821: manuals.
822: .Ss Block Macros
823: Block macros comprise a head and body.
824: As with in-line macros, the head is scoped to the current line and, in
825: one circumstance, the next line (the next-line stipulations as in
826: .Sx Line Macros
827: apply here as well).
828: .Pp
829: The syntax is as follows:
830: .Bd -literal -offset indent
831: \&.YO \(lBhead...\(rB
832: \(lBhead...\(rB
833: \(lBbody...\(rB
834: .Ed
835: .Pp
836: The closure of body scope may be to the section, where a macro is closed
837: by
838: .Sx \&SH ;
839: sub-section, closed by a section or
840: .Sx \&SS ;
841: part, closed by a section, sub-section, or
842: .Sx \&RE ;
843: or paragraph, closed by a section, sub-section, part,
844: .Sx \&HP ,
845: .Sx \&IP ,
846: .Sx \&LP ,
847: .Sx \&P ,
848: .Sx \&PP ,
849: or
850: .Sx \&TP .
851: No closure refers to an explicit block closing macro.
852: .Pp
853: As a rule, block macros may not be nested; thus, calling a block macro
854: while another block macro scope is open, and the open scope is not
855: implicitly closed, is syntactically incorrect.
856: .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
857: .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
858: .It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
859: .It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
860: .It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
861: .It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
862: .It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
863: .It Sx \&RE Ta 0 Ta current Ta none Ta compat
864: .It Sx \&RS Ta 1 Ta current Ta part Ta compat
865: .It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
866: .It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
867: .It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
1.121 schwarze 868: .It Sx \&UE Ta 0 Ta current Ta none Ta compat
869: .It Sx \&UR Ta 1 Ta current Ta part Ta compat
1.111 schwarze 870: .El
871: .Pp
872: Macros marked
873: .Qq compat
874: are as mentioned in
875: .Sx Line Macros .
876: .Pp
877: If a block macro is next-line scoped, it may only be followed by in-line
878: macros for decorating text.
879: .Ss Font handling
880: In
881: .Nm
882: documents, both
883: .Sx Physical markup
884: macros and
885: .Xr roff 7
886: .Ql \ef
887: font escape sequences can be used to choose fonts.
888: In text lines, the effect of manual font selection by escape sequences
889: only lasts until the next macro invocation; in macro lines, it only lasts
890: until the end of the macro scope.
891: Note that macros like
892: .Sx \&BR
893: open and close a font scope for each argument.
1.1 kristaps 894: .Sh SEE ALSO
1.89 schwarze 895: .Xr man 1 ,
1.32 kristaps 896: .Xr mandoc 1 ,
1.98 kristaps 897: .Xr eqn 7 ,
1.89 schwarze 898: .Xr mandoc_char 7 ,
1.94 kristaps 899: .Xr mdoc 7 ,
900: .Xr roff 7 ,
901: .Xr tbl 7
1.78 schwarze 902: .Sh HISTORY
903: The
904: .Nm
905: language first appeared as a macro package for the roff typesetting
906: system in
907: .At v7 .
908: It was later rewritten by James Clark as a macro package for groff.
1.113 kristaps 909: Eric S. Raymond wrote the extended
910: .Nm
911: macros for groff in 2007.
1.78 schwarze 912: The stand-alone implementation that is part of the
913: .Xr mandoc 1
914: utility written by Kristaps Dzonsons appeared in
1.80 kristaps 915: .Ox 4.6 .
1.1 kristaps 916: .Sh AUTHORS
1.78 schwarze 917: This
1.32 kristaps 918: .Nm
1.23 kristaps 919: reference was written by
1.119 schwarze 920: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.1 kristaps 921: .Sh CAVEATS
1.68 kristaps 922: Do not use this language.
923: Use
1.32 kristaps 924: .Xr mdoc 7 ,
1.1 kristaps 925: instead.
CVSweb