Annotation of mandoc/man.7, Revision 1.52
1.52 ! kristaps 1: .\" $Id: man.7,v 1.51 2009/11/12 08:00:21 kristaps Exp $
1.1 kristaps 2: .\"
1.11 kristaps 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.10 kristaps 6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 16: .\"
17: .Dd $Mdocdate$
1.9 kristaps 18: .Dt MAN 7
1.1 kristaps 19: .Os
1.28 kristaps 20: .
21: .
1.1 kristaps 22: .Sh NAME
1.32 kristaps 23: .Nm man
24: .Nd man language reference
1.28 kristaps 25: .
26: .
1.1 kristaps 27: .Sh DESCRIPTION
28: The
1.32 kristaps 29: .Nm man
1.20 kristaps 30: language was historically used to format
1.32 kristaps 31: .Ux
1.19 kristaps 32: manuals. This reference document describes its syntax, structure, and
33: usage.
1.32 kristaps 34: .
35: .Pp
36: .Bf -emphasis
1.20 kristaps 37: Do not use
1.32 kristaps 38: .Nm
1.20 kristaps 39: to write your manuals.
1.32 kristaps 40: .Ef
1.19 kristaps 41: Use the
1.32 kristaps 42: .Xr mdoc 7
1.1 kristaps 43: language, instead.
1.32 kristaps 44: .
45: .Pp
1.1 kristaps 46: An
1.32 kristaps 47: .Nm
1.1 kristaps 48: document follows simple rules: lines beginning with the control
1.20 kristaps 49: character
1.32 kristaps 50: .Sq \&.
1.1 kristaps 51: are parsed for macros. Other lines are interpreted within the scope of
52: prior macros:
1.32 kristaps 53: .Bd -literal -offset indent
1.1 kristaps 54: \&.SH Macro lines change control state.
55: Other lines are interpreted within the current state.
1.32 kristaps 56: .Ed
1.28 kristaps 57: .
58: .
1.1 kristaps 59: .Sh INPUT ENCODING
1.32 kristaps 60: .Nm
1.14 kristaps 61: documents may contain only graphable 7-bit ASCII characters, the
1.19 kristaps 62: space character, and the tabs character. All manuals must have
1.32 kristaps 63: .Ux
1.20 kristaps 64: line termination.
1.32 kristaps 65: .
66: .Pp
1.5 kristaps 67: Blank lines are acceptable; where found, the output will assert a
1.1 kristaps 68: vertical space.
1.32 kristaps 69: .
1.28 kristaps 70: .
1.32 kristaps 71: .Ss Comments
1.21 kristaps 72: Text following a
1.32 kristaps 73: .Sq \e\*" ,
1.21 kristaps 74: whether in a macro or free-form text line, is ignored to the end of
75: line. A macro line with only a control character and comment escape,
1.32 kristaps 76: .Sq \&.\e" ,
1.44 kristaps 77: is also ignored. Macro lines with only a control character and
1.22 kristaps 78: optionally whitespace are stripped from input.
1.28 kristaps 79: .
80: .
1.32 kristaps 81: .Ss Special Characters
1.21 kristaps 82: Special characters may occur in both macro and free-form lines.
83: Sequences begin with the escape character
1.32 kristaps 84: .Sq \e
1.20 kristaps 85: followed by either an open-parenthesis
1.32 kristaps 86: .Sq \&(
1.1 kristaps 87: for two-character sequences; an open-bracket
1.32 kristaps 88: .Sq \&[
1.1 kristaps 89: for n-character sequences (terminated at a close-bracket
1.32 kristaps 90: .Sq \&] ) ;
1.21 kristaps 91: or a single one-character sequence. See
1.32 kristaps 92: .Xr mandoc_char 7
1.21 kristaps 93: for a complete list. Examples include
1.32 kristaps 94: .Sq \e(em
95: .Pq em-dash
1.21 kristaps 96: and
1.32 kristaps 97: .Sq \ee
98: .Pq back-slash .
1.28 kristaps 99: .
100: .
1.32 kristaps 101: .Ss Text Decoration
1.21 kristaps 102: Terms may be text-decorated using the
1.32 kristaps 103: .Sq \ef
1.47 kristaps 104: escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
1.48 kristaps 105: (revert to previous mode):
106: .Pp
107: .D1 \efBbold\efR \efIitalic\efP
108: .Pp
109: A numerical representation 3, 2, or 1 (bold, italic, and Roman,
1.50 kristaps 110: respectively) may be used instead. A text decoration is only valid, if
111: specified in free-form text, until the next macro invocation; if
112: specified within a macro, it's only valid until the macro closes scope.
1.48 kristaps 113: .Pp
114: Text may also be sized with the
115: .Sq \es
116: escape, whose syntax is one of
117: .Sq \es+-n
118: for one-digit numerals;
119: .Sq \es(+-nn
120: or
121: .Sq \es+-(nn
122: for two-digit numerals; and
123: .Sq \es[+-N] ,
124: .Sq \es+-[N] ,
125: .Sq \es'+-N' ,
126: or
127: .Sq \es+-'N'
128: for arbitrary-digit numerals:
129: .Pp
130: .D1 \es+1bigger\es-1
131: .D1 \es[+10]much bigger\es[-10]
132: .D1 \es+(10much bigger\es-(10
133: .D1 \es+'100'much much bigger\es-'100'
1.49 kristaps 134: .Pp
135: Both
136: .Sq \es
137: and
138: .Sq \ef
139: attributes are forgotten when exiting a subsequent (or current) macro
140: invocation.
1.28 kristaps 141: .
142: .
1.32 kristaps 143: .Ss Whitespace
1.17 kristaps 144: Unless specifically escaped, consecutive blocks of whitespace are pruned
145: from input. These are later re-added, if applicable, by a front-end
146: utility such as
1.32 kristaps 147: .Xr mandoc 1 .
1.28 kristaps 148: .
1.44 kristaps 149: .
1.43 kristaps 150: .Ss Dates
151: The
152: .Sx \&TH
153: macro is the only
154: .Nm
155: macro that requires a date. The form for this date is the ISO-8601
156: standard
157: .Cm YYYY-MM-DD .
158: .
159: .
1.38 kristaps 160: .Ss Scaling Widths
161: Many macros support scaled widths for their arguments, such as
162: stipulating a two-inch paragraph indentation with the following:
163: .Bd -literal -offset indent
164: \&.HP 2i
165: .Ed
166: .
167: .Pp
168: The syntax for scaled widths is
169: .Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,
170: where a decimal must be preceded or proceeded by at least one digit.
171: Negative numbers, while accepted, are truncated to zero. The following
172: scaling units are accepted:
173: .
174: .Pp
175: .Bl -tag -width Ds -offset indent -compact
176: .It c
177: centimetre
178: .It i
179: inch
180: .It P
181: pica (~1/6 inch)
182: .It p
183: point (~1/72 inch)
184: .It f
185: synonym for
186: .Sq u
187: .It v
188: default vertical span
189: .It m
190: width of rendered
191: .Sq m
192: .Pq em
193: character
194: .It n
195: width of rendered
196: .Sq n
197: .Pq en
198: character
199: .It u
200: default horizontal span
201: .It M
202: mini-em (~1/100 em)
203: .El
204: .Pp
205: Using anything other than
206: .Sq m ,
207: .Sq n ,
208: .Sq u ,
209: or
210: .Sq v
1.44 kristaps 211: is necessarily non-portable across output media.
1.38 kristaps 212: .
213: .Pp
214: If a scaling unit is not provided, the numerical value is interpreted
215: under the default rules of
216: .Sq v
217: for vertical spaces and
218: .Sq u
219: for horizontal ones.
220: .Em Note :
221: this differs from
222: .Xr mdoc 7 ,
223: which, if a unit is not provided, will instead interpret the string as
224: literal text.
225: .
1.28 kristaps 226: .
1.22 kristaps 227: .Sh MANUAL STRUCTURE
1.16 kristaps 228: Each
1.32 kristaps 229: .Nm
1.16 kristaps 230: document must contain contains at least the
1.39 kristaps 231: .Sx \&TH
1.16 kristaps 232: macro describing the document's section and title. It may occur
233: anywhere in the document, although conventionally, it appears as the
234: first macro.
1.32 kristaps 235: .
236: .Pp
1.22 kristaps 237: Beyond
1.39 kristaps 238: .Sx \&TH ,
1.22 kristaps 239: at least one macro or text node must appear in the document. Documents
240: are generally structured as follows:
1.32 kristaps 241: .Bd -literal -offset indent
1.43 kristaps 242: \&.TH FOO 1 2009-10-10
1.22 kristaps 243: \&.
244: \&.SH NAME
1.29 kristaps 245: \efBfoo\efR \e(en a description goes here
1.33 kristaps 246: \&.\e\*q The next is for sections 2 & 3 only.
247: \&.\e\*q .SH LIBRARY
1.22 kristaps 248: \&.
249: \&.SH SYNOPSIS
250: \efBfoo\efR [\efB\e-options\efR] arguments...
251: \&.
252: \&.SH DESCRIPTION
1.33 kristaps 253: The \efBfoo\efR utility processes files...
1.22 kristaps 254: \&.
1.33 kristaps 255: \&.\e\*q .SH IMPLEMENTATION NOTES
256: \&.\e\*q The next is for sections 1 & 8 only.
257: \&.\e\*q .SH EXIT STATUS
258: \&.\e\*q The next is for sections 2, 3, & 9 only.
1.22 kristaps 259: \&.\e\*q .SH RETURN VALUES
1.33 kristaps 260: \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
1.22 kristaps 261: \&.\e\*q .SH ENVIRONMENT
262: \&.\e\*q .SH FILES
263: \&.\e\*q .SH EXAMPLES
1.33 kristaps 264: \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
1.22 kristaps 265: \&.\e\*q .SH DIAGNOSTICS
1.33 kristaps 266: \&.\e\*q The next is for sections 2, 3, & 9 only.
1.22 kristaps 267: \&.\e\*q .SH ERRORS
268: \&.\e\*q .SH SEE ALSO
1.42 kristaps 269: \&.\e\*q .BR foo ( 1 )
1.22 kristaps 270: \&.\e\*q .SH STANDARDS
271: \&.\e\*q .SH HISTORY
272: \&.\e\*q .SH AUTHORS
273: \&.\e\*q .SH CAVEATS
274: \&.\e\*q .SH BUGS
1.33 kristaps 275: \&.\e\*q .SH SECURITY CONSIDERATIONS
1.32 kristaps 276: .Ed
1.41 kristaps 277: .Pp
278: The sections in a
279: .Nm
280: document are conventionally ordered as they appear above. Sections
281: should be composed as follows:
1.42 kristaps 282: .Bl -ohang -offset indent
283: .It Em NAME
1.41 kristaps 284: The name(s) and a short description of the documented material. The
285: syntax for this is generally as follows:
286: .Pp
287: .D1 \efBname\efR \e(en description
1.42 kristaps 288: .It Em LIBRARY
1.41 kristaps 289: The name of the library containing the documented material, which is
290: assumed to be a function in a section 2 or 3 manual. For functions in
291: the C library, this may be as follows:
292: .Pp
293: .D1 Standard C Library (libc, -lc)
1.42 kristaps 294: .It Em SYNOPSIS
1.41 kristaps 295: Documents the utility invocation syntax, function call syntax, or device
296: configuration.
297: .Pp
298: For the first, utilities (sections 1, 6, and 8), this is
299: generally structured as follows:
300: .Pp
301: .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
302: .Pp
303: For the second, function calls (sections 2, 3, 9):
304: .Pp
1.44 kristaps 305: .D1 \&.B char *name(char *\efIarg\efR);
1.41 kristaps 306: .Pp
307: And for the third, configurations (section 4):
308: .Pp
1.44 kristaps 309: .D1 \&.B name* at cardbus ? function ?
1.41 kristaps 310: .Pp
1.42 kristaps 311: Manuals not in these sections generally don't need a
312: .Em SYNOPSIS .
313: .It Em DESCRIPTION
314: This expands upon the brief, one-line description in
315: .Em NAME .
316: It usually contains a break-down of the options (if documenting a
317: command).
318: .It Em IMPLEMENTATION NOTES
1.41 kristaps 319: Implementation-specific notes should be kept here. This is useful when
320: implementing standard functions that may have side effects or notable
321: algorithmic implications.
1.42 kristaps 322: .It Em EXIT STATUS
323: Command exit status for section 1, 6, and 8 manuals. This section is
324: the dual of
325: .Em RETURN VALUES ,
326: which is used for functions. Historically, this information was
327: described in
328: .Em DIAGNOSTICS ,
329: a practise that is now discouraged.
330: .
331: .It Em RETURN VALUES
332: This section is the dual of
333: .Em EXIT STATUS ,
334: which is used for commands. It documents the return values of functions
335: in sections 2, 3, and 9.
336: .
337: .It Em ENVIRONMENT
338: Documents any usages of environment variables, e.g.,
339: .Xr environ 7 .
340: .
341: .It Em FILES
342: Documents files used. It's helpful to document both the file and a
343: short description of how the file is used (created, modified, etc.).
344: .
345: .It Em EXAMPLES
346: Example usages. This often contains snippets of well-formed,
347: well-tested invocations. Make doubly sure that your examples work
1.44 kristaps 348: properly!
1.42 kristaps 349: .
350: .It Em DIAGNOSTICS
351: Documents error conditions. This is most useful in section 4 manuals.
352: Historically, this section was used in place of
353: .Em EXIT STATUS
354: for manuals in sections 1, 6, and 8; however, this practise is
355: discouraged.
356: .
357: .It Em ERRORS
358: Documents error handling in sections 2, 3, and 9.
359: .
360: .It Em SEE ALSO
361: References other manuals with related topics. This section should exist
1.44 kristaps 362: for most manuals.
363: .Pp
364: .D1 \&.BR bar \&( 1 \&),
365: .Pp
366: Cross-references should conventionally be ordered
1.42 kristaps 367: first by section, then alphabetically.
368: .
369: .It Em STANDARDS
370: References any standards implemented or used, such as
371: .Pp
372: .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
373: .Pp
374: If not adhering to any standards, the
375: .Em HISTORY
376: section should be used.
377: .
378: .It Em HISTORY
379: The history of any manual without a
380: .Em STANDARDS
381: section should be described in this section.
382: .
383: .It Em AUTHORS
384: Credits to authors, if applicable, should appear in this section.
385: Authors should generally be noted by both name and an e-mail address.
386: .
387: .It Em CAVEATS
388: Explanations of common misuses and misunderstandings should be explained
389: in this section.
390: .
391: .It Em BUGS
392: Extant bugs should be described in this section.
393: .
394: .It Em SECURITY CONSIDERATIONS
395: Documents any security precautions that operators should consider.
396: .
1.41 kristaps 397: .El
1.28 kristaps 398: .
399: .
1.22 kristaps 400: .Sh MACRO SYNTAX
1.2 kristaps 401: Macros are one to three three characters in length and begin with a
1.4 kristaps 402: control character ,
1.32 kristaps 403: .Sq \&. ,
1.2 kristaps 404: at the beginning of the line. An arbitrary amount of whitespace may
1.39 kristaps 405: sit between the control character and the macro name. Thus, the
406: following are equivalent:
407: .Bd -literal -offset indent
408: \&.PP
409: \&.\ \ \ PP
410: .Ed
1.32 kristaps 411: .
412: .Pp
1.1 kristaps 413: The
1.32 kristaps 414: .Nm
1.30 kristaps 415: macros are classified by scope: line scope or block scope. Line
1.22 kristaps 416: macros are only scoped to the current line (and, in some situations,
417: the subsequent line). Block macros are scoped to the current line and
418: subsequent lines until closed by another block macro.
1.28 kristaps 419: .
420: .
1.32 kristaps 421: .Ss Line Macros
1.30 kristaps 422: Line macros are generally scoped to the current line, with the body
423: consisting of zero or more arguments. If a macro is scoped to the next
424: line and the line arguments are empty, the next line is used instead,
425: else the general syntax is used. Thus:
1.32 kristaps 426: .Bd -literal -offset indent
1.30 kristaps 427: \&.I
1.4 kristaps 428: foo
1.32 kristaps 429: .Ed
430: .
431: .Pp
1.20 kristaps 432: is equivalent to
1.32 kristaps 433: .Sq \&.I foo .
1.44 kristaps 434: If next-line macros are invoked consecutively, only the last is used; in
435: other words, if a next-line macro is preceded by a block macro, it is
436: ignored.
1.32 kristaps 437: .Bd -literal -offset indent
1.22 kristaps 438: \&.YO \(lBbody...\(rB
439: \(lBbody...\(rB
1.32 kristaps 440: .Ed
441: .
442: .Pp
443: .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
444: .It Em Macro Ta Em Arguments Ta Em Scope
1.39 kristaps 445: .It Sx \&B Ta n Ta next-line
446: .It Sx \&BI Ta n Ta current
447: .It Sx \&BR Ta n Ta current
448: .It Sx \&DT Ta 0 Ta current
449: .It Sx \&I Ta n Ta next-line
450: .It Sx \&IB Ta n Ta current
451: .It Sx \&IR Ta n Ta current
1.40 kristaps 452: .It Sx \&PD Ta n Ta current
1.39 kristaps 453: .It Sx \&R Ta n Ta next-line
454: .It Sx \&RB Ta n Ta current
455: .It Sx \&RI Ta n Ta current
456: .It Sx \&SB Ta n Ta next-line
457: .It Sx \&SM Ta n Ta next-line
458: .It Sx \&TH Ta >1, <6 Ta current
459: .It Sx \&UC Ta n Ta current
460: .It Sx \&br Ta 0 Ta current
461: .It Sx \&fi Ta 0 Ta current
462: .It Sx \&i Ta n Ta current
463: .It Sx \&na Ta 0 Ta current
464: .It Sx \&nf Ta 0 Ta current
465: .It Sx \&r Ta 0 Ta current
466: .It Sx \&sp Ta 1 Ta current
1.32 kristaps 467: .El
468: .
469: .Pp
1.31 kristaps 470: The
1.40 kristaps 471: .Sx \&PD ,
1.39 kristaps 472: .Sx \&RS ,
473: .Sx \&RE ,
474: .Sx \&UC ,
475: .Sx \&br ,
476: .Sx \&fi ,
477: .Sx \&i ,
478: .Sx \&na ,
479: .Sx \&nf ,
480: .Sx \&r ,
1.22 kristaps 481: and
1.39 kristaps 482: .Sx \&sp
1.36 kristaps 483: macros should not be used. They're included for compatibility.
1.28 kristaps 484: .
485: .
1.32 kristaps 486: .Ss Block Macros
1.30 kristaps 487: Block macros are comprised of a head and body. Like for in-line macros,
488: the head is scoped to the current line and, in one circumstance, the
489: next line; the body is scoped to subsequent lines and is closed out by a
490: subsequent block macro invocation.
1.32 kristaps 491: .Bd -literal -offset indent
1.22 kristaps 492: \&.YO \(lBhead...\(rB
493: \(lBhead...\(rB
494: \(lBbody...\(rB
1.32 kristaps 495: .Ed
496: .
497: .Pp
1.30 kristaps 498: The closure of body scope may be to the section, where a macro is closed
499: by
1.39 kristaps 500: .Sx \&SH ;
1.30 kristaps 501: sub-section, closed by a section or
1.39 kristaps 502: .Sx \&SS ;
1.30 kristaps 503: part, closed by a section, sub-section, or
1.39 kristaps 504: .Sx \&RE ;
1.30 kristaps 505: or paragraph, closed by a section, sub-section, part,
1.39 kristaps 506: .Sx \&HP ,
507: .Sx \&IP ,
508: .Sx \&LP ,
509: .Sx \&P ,
510: .Sx \&PP ,
1.30 kristaps 511: or
1.39 kristaps 512: .Sx \&TP .
1.30 kristaps 513: No closure refers to an explicit block closing macro.
1.32 kristaps 514: .
515: .Pp
516: .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent
517: .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope
1.39 kristaps 518: .It Sx \&HP Ta <2 Ta current Ta paragraph
519: .It Sx \&IP Ta <3 Ta current Ta paragraph
520: .It Sx \&LP Ta 0 Ta current Ta paragraph
521: .It Sx \&P Ta 0 Ta current Ta paragraph
522: .It Sx \&PP Ta 0 Ta current Ta paragraph
523: .It Sx \&RE Ta 0 Ta current Ta none
524: .It Sx \&RS Ta 1 Ta current Ta part
525: .It Sx \&SH Ta >0 Ta next-line Ta section
526: .It Sx \&SS Ta >0 Ta next-line Ta sub-section
527: .It Sx \&TP Ta n Ta next-line Ta paragraph
1.32 kristaps 528: .El
529: .
530: .Pp
1.22 kristaps 531: If a block macro is next-line scoped, it may only be followed by in-line
532: macros (excluding
1.39 kristaps 533: .Sx \&DT ,
1.40 kristaps 534: .Sx \&PD ,
1.39 kristaps 535: .Sx \&TH ,
536: .Sx \&UC ,
537: .Sx \&br ,
538: .Sx \&na ,
539: .Sx \&sp ,
540: .Sx \&nf ,
1.22 kristaps 541: and
1.39 kristaps 542: .Sx \&fi ) .
1.28 kristaps 543: .
544: .
1.22 kristaps 545: .Sh REFERENCE
546: This section is a canonical reference to all macros, arranged
547: alphabetically. For the scoping of individual macros, see
1.32 kristaps 548: .Sx MACRO SYNTAX .
1.28 kristaps 549: .
1.44 kristaps 550: .
1.39 kristaps 551: .Ss \&B
1.22 kristaps 552: Text is rendered in bold face.
1.44 kristaps 553: .Pp
554: See also
555: .Sx \&I ,
556: .Sx \&R ,
557: .Sx \&b ,
558: .Sx \&i ,
559: and
560: .Sx \&r .
561: .
562: .
1.39 kristaps 563: .Ss \&BI
1.22 kristaps 564: Text is rendered alternately in bold face and italic. Thus,
1.32 kristaps 565: .Sq .BI this word and that
1.22 kristaps 566: causes
1.32 kristaps 567: .Sq this
1.22 kristaps 568: and
1.32 kristaps 569: .Sq and
1.22 kristaps 570: to render in bold face, while
1.32 kristaps 571: .Sq word
1.22 kristaps 572: and
1.32 kristaps 573: .Sq that
1.22 kristaps 574: render in italics. Whitespace between arguments is omitted in output.
1.44 kristaps 575: .Pp
576: Examples:
1.46 kristaps 577: .Pp
578: .D1 \&.BI bold italic bold italic
1.44 kristaps 579: .Pp
580: The output of this example will be emboldened
581: .Dq bold
582: and italicised
583: .Dq italic ,
584: with spaces stripped between arguments.
585: .Pp
586: See also
587: .Sx \&IB ,
588: .Sx \&BR ,
589: .Sx \&RB ,
590: .Sx \&RI ,
591: and
592: .Sx \&IR .
593: .
594: .
1.39 kristaps 595: .Ss \&BR
1.22 kristaps 596: Text is rendered alternately in bold face and roman (the default font).
597: Whitespace between arguments is omitted in output.
1.44 kristaps 598: .Pp
599: See
600: .Sx \&BI
601: for an equivalent example.
602: .Pp
603: See also
604: .Sx \&BI ,
605: .Sx \&IB ,
606: .Sx \&RB ,
607: .Sx \&RI ,
608: and
609: .Sx \&IR .
610: .
611: .
1.39 kristaps 612: .Ss \&DT
1.36 kristaps 613: Has no effect. Included for compatibility.
1.44 kristaps 614: .
615: .
1.39 kristaps 616: .Ss \&HP
1.23 kristaps 617: Begin a paragraph whose initial output line is left-justified, but
1.27 kristaps 618: subsequent output lines are indented, with the following syntax:
1.44 kristaps 619: .Bd -filled -offset indent
620: .Pf \. Sx \&HP
621: .Op Cm width
1.32 kristaps 622: .Ed
1.44 kristaps 623: .Pp
624: The
625: .Cm width
626: argument must conform to
627: .Sx Scaling Widths .
628: If specified, it's saved for later paragraph left-margins; if unspecified, the
629: saved or default width is used.
630: .Pp
631: See also
1.45 kristaps 632: .Sx \&IP ,
633: .Sx \&LP ,
634: .Sx \&P ,
635: .Sx \&PP ,
1.44 kristaps 636: and
1.45 kristaps 637: .Sx \&TP .
1.44 kristaps 638: .
1.32 kristaps 639: .
1.39 kristaps 640: .Ss \&I
1.22 kristaps 641: Text is rendered in italics.
1.44 kristaps 642: .Pp
643: See also
644: .Sx \&B ,
645: .Sx \&R ,
646: .Sx \&b ,
647: .Sx \&i ,
648: and
649: .Sx \&r .
650: .
651: .
1.39 kristaps 652: .Ss \&IB
1.22 kristaps 653: Text is rendered alternately in italics and bold face. Whitespace
654: between arguments is omitted in output.
1.44 kristaps 655: .Pp
656: See
657: .Sx \&BI
658: for an equivalent example.
659: .Pp
660: See also
661: .Sx \&BI ,
662: .Sx \&BR ,
663: .Sx \&RB ,
664: .Sx \&RI ,
665: and
666: .Sx \&IR .
667: .
668: .
1.39 kristaps 669: .Ss \&IP
1.44 kristaps 670: Begin an indented paragraph with the following syntax:
671: .Bd -filled -offset indent
672: .Pf \. Sx \&IP
673: .Op Cm head Op Cm width
1.32 kristaps 674: .Ed
1.44 kristaps 675: .Pp
676: The
677: .Cm width
678: argument defines the width of the left margin and is defined by
679: .Sx Scaling Widths ,
680: It's saved for later paragraph left-margins; if unspecified, the saved or
681: default width is used.
682: .Pp
683: The
684: .Cm head
685: argument is used as a leading term, flushed to the left margin. This is
686: useful for bulleted paragraphs and so on.
687: .Pp
688: See also
1.45 kristaps 689: .Sx \&HP ,
690: .Sx \&LP ,
691: .Sx \&P ,
692: .Sx \&PP ,
1.44 kristaps 693: and
1.45 kristaps 694: .Sx \&TP .
1.44 kristaps 695: .
1.32 kristaps 696: .
1.39 kristaps 697: .Ss \&IR
1.22 kristaps 698: Text is rendered alternately in italics and roman (the default font).
699: Whitespace between arguments is omitted in output.
1.44 kristaps 700: .Pp
701: See
702: .Sx \&BI
703: for an equivalent example.
704: .Pp
705: See also
706: .Sx \&BI ,
707: .Sx \&IB ,
708: .Sx \&BR ,
709: .Sx \&RB ,
710: and
711: .Sx \&RI .
712: .
713: .
1.39 kristaps 714: .Ss \&LP
1.22 kristaps 715: Begin an undecorated paragraph. The scope of a paragraph is closed by a
1.27 kristaps 716: subsequent paragraph, sub-section, section, or end of file. The saved
717: paragraph left-margin width is re-set to the default.
1.44 kristaps 718: .Pp
719: See also
1.45 kristaps 720: .Sx \&HP ,
721: .Sx \&IP ,
722: .Sx \&P ,
723: .Sx \&PP ,
1.44 kristaps 724: and
1.45 kristaps 725: .Sx \&TP .
1.44 kristaps 726: .
727: .
1.39 kristaps 728: .Ss \&P
729: Synonym for
730: .Sx \&LP .
1.44 kristaps 731: .Pp
732: See also
1.45 kristaps 733: .Sx \&HP ,
734: .Sx \&IP ,
735: .Sx \&LP ,
736: .Sx \&PP ,
1.44 kristaps 737: and
1.45 kristaps 738: .Sx \&TP .
1.44 kristaps 739: .
740: .
1.39 kristaps 741: .Ss \&PP
742: Synonym for
743: .Sx \&LP .
1.44 kristaps 744: .Pp
745: See also
1.45 kristaps 746: .Sx \&HP ,
747: .Sx \&IP ,
748: .Sx \&LP ,
749: .Sx \&P ,
1.44 kristaps 750: and
1.45 kristaps 751: .Sx \&TP .
1.44 kristaps 752: .
753: .
1.39 kristaps 754: .Ss \&R
1.22 kristaps 755: Text is rendered in roman (the default font).
1.44 kristaps 756: .Pp
757: See also
758: .Sx \&I ,
759: .Sx \&B ,
760: .Sx \&b ,
761: .Sx \&i ,
762: and
763: .Sx \&r .
764: .
765: .
1.39 kristaps 766: .Ss \&RB
1.22 kristaps 767: Text is rendered alternately in roman (the default font) and bold face.
768: Whitespace between arguments is omitted in output.
1.44 kristaps 769: .Pp
770: See
771: .Sx \&BI
772: for an equivalent example.
773: .Pp
774: See also
775: .Sx \&BI ,
776: .Sx \&IB ,
777: .Sx \&BR ,
778: .Sx \&RI ,
779: and
780: .Sx \&IR .
781: .
782: .
1.39 kristaps 783: .Ss \&RE
1.30 kristaps 784: Explicitly close out the scope of a prior
1.39 kristaps 785: .Sx \&RS .
1.44 kristaps 786: .
787: .
1.39 kristaps 788: .Ss \&RI
1.22 kristaps 789: Text is rendered alternately in roman (the default font) and italics.
790: Whitespace between arguments is omitted in output.
1.44 kristaps 791: .Pp
792: See
793: .Sx \&BI
794: for an equivalent example.
795: .Pp
796: See also
797: .Sx \&BI ,
798: .Sx \&IB ,
799: .Sx \&BR ,
800: .Sx \&RB ,
801: and
802: .Sx \&IR .
803: .
804: .
1.39 kristaps 805: .Ss \&RS
1.30 kristaps 806: Begin a part setting the left margin. The left margin controls the
807: offset, following an initial indentation, to un-indented text such as
808: that of
1.39 kristaps 809: .Sx \&PP .
1.44 kristaps 810: This has the following syntax:
811: .Bd -filled -offset indent
812: .Pf \. Sx \&Rs
813: .Op Cm width
1.32 kristaps 814: .Ed
1.44 kristaps 815: .Pp
816: The
817: .Cm width
818: argument must conform to
819: .Sx Scaling Widths .
820: If not specified, the saved or default width is used.
821: .
1.32 kristaps 822: .
1.39 kristaps 823: .Ss \&SB
1.22 kristaps 824: Text is rendered in small size (one point smaller than the default font)
825: bold face.
1.44 kristaps 826: .
827: .
1.39 kristaps 828: .Ss \&SH
1.22 kristaps 829: Begin a section. The scope of a section is only closed by another
1.27 kristaps 830: section or the end of file. The paragraph left-margin width is re-set
831: to the default.
1.44 kristaps 832: .
833: .
1.39 kristaps 834: .Ss \&SM
1.22 kristaps 835: Text is rendered in small size (one point smaller than the default
836: font).
1.44 kristaps 837: .
838: .
1.39 kristaps 839: .Ss \&SS
1.22 kristaps 840: Begin a sub-section. The scope of a sub-section is closed by a
1.27 kristaps 841: subsequent sub-section, section, or end of file. The paragraph
842: left-margin width is re-set to the default.
1.44 kristaps 843: .
844: .
1.39 kristaps 845: .Ss \&TH
1.22 kristaps 846: Sets the title of the manual page with the following syntax:
1.44 kristaps 847: .Bd -filled -offset indent
848: .Pf \. Sx \&TH
849: .Cm title section
850: .Op Cm date Op Cm source Op Cm volume
851: .Ed
1.43 kristaps 852: .Pp
853: At least the upper-case document title
854: .Cm title
855: and numeric manual section
1.44 kristaps 856: .Cm section
1.43 kristaps 857: arguments must be provided. The
858: .Cm date
859: argument should be formatted as described in
860: .Sx Dates :
861: if it does not conform, the current date is used instead. The
1.44 kristaps 862: .Cm source
1.43 kristaps 863: string specifies the organisation providing the utility. The
1.44 kristaps 864: .Cm volume
1.43 kristaps 865: string replaces the default rendered volume, which is dictated by the
866: manual section.
867: .Pp
868: Examples:
1.46 kristaps 869: .Pp
870: .D1 \&.TH CVS 5 "1992-02-12" GNU
1.32 kristaps 871: .
1.44 kristaps 872: .
1.39 kristaps 873: .Ss \&TP
1.25 kristaps 874: Begin a paragraph where the head, if exceeding the indentation width, is
1.24 kristaps 875: followed by a newline; if not, the body follows on the same line after a
1.25 kristaps 876: buffer to the indentation width. Subsequent output lines are indented.
1.44 kristaps 877: The syntax is as follows:
878: .Bd -filled -offset indent
879: .Pf \. Sx \&TP
880: .Op Cm width
1.32 kristaps 881: .Ed
882: .Pp
1.44 kristaps 883: The
884: .Cm width
885: argument must conform to
886: .Sx Scaling Widths .
887: If specified, it's saved for later paragraph left-margins; if
1.27 kristaps 888: unspecified, the saved or default width is used.
1.44 kristaps 889: .Pp
890: See also
1.45 kristaps 891: .Sx \&HP ,
892: .Sx \&IP ,
893: .Sx \&LP ,
894: .Sx \&P ,
1.44 kristaps 895: and
1.45 kristaps 896: .Sx \&PP .
1.44 kristaps 897: .
898: .
1.40 kristaps 899: .Ss \&PD
900: Has no effect. Included for compatibility.
1.44 kristaps 901: .
902: .
1.39 kristaps 903: .Ss \&UC
1.37 kristaps 904: Has no effect. Included for compatibility.
1.44 kristaps 905: .
906: .
1.39 kristaps 907: .Ss \&br
1.22 kristaps 908: Breaks the current line. Consecutive invocations have no further effect.
1.44 kristaps 909: .Pp
910: See also
911: .Sx \&sp .
912: .
913: .
1.39 kristaps 914: .Ss \&fi
1.22 kristaps 915: End literal mode begun by
1.39 kristaps 916: .Sx \&nf .
1.44 kristaps 917: .
918: .
1.39 kristaps 919: .Ss \&i
1.51 kristaps 920: Italicise arguments. Synonym for
921: .Sx \&I .
1.44 kristaps 922: .Pp
923: See also
924: .Sx \&B ,
925: .Sx \&I ,
926: .Sx \&R .
927: .Sx \&b ,
928: and
929: .Sx \&r .
930: .
931: .
1.39 kristaps 932: .Ss \&na
1.36 kristaps 933: Don't align to the right margin.
1.44 kristaps 934: .
935: .
1.39 kristaps 936: .Ss \&nf
1.22 kristaps 937: Begin literal mode: all subsequent free-form lines have their end of
938: line boundaries preserved. May be ended by
1.39 kristaps 939: .Sx \&fi .
1.44 kristaps 940: .
941: .
1.39 kristaps 942: .Ss \&r
1.22 kristaps 943: Fonts and styles (bold face, italics) reset to roman (default font).
1.44 kristaps 944: .Pp
945: See also
946: .Sx \&B ,
947: .Sx \&I ,
948: .Sx \&R ,
949: .Sx \&b ,
950: and
951: .Sx \&i .
952: .
953: .
1.39 kristaps 954: .Ss \&sp
1.44 kristaps 955: Insert vertical spaces into output with the following syntax:
956: .Bd -filled -offset indent
957: .Pf \. Sx \&sp
958: .Op Cm height
959: .Ed
960: .Pp
961: Insert
962: .Cm height
963: spaces, which must conform to
964: .Sx Scaling Widths .
965: If 0, this is equivalent to the
1.39 kristaps 966: .Sx \&br
1.44 kristaps 967: macro. Defaults to 1, if unspecified.
968: .Pp
969: See also
970: .Sx \&br .
1.28 kristaps 971: .
972: .
1.18 kristaps 973: .Sh COMPATIBILITY
1.23 kristaps 974: This section documents compatibility with other roff implementations, at
975: this time limited to
1.32 kristaps 976: .Xr groff 1 .
1.51 kristaps 977: .Pp
978: .Bl -dash -compact
979: .It
980: The
981: .Xr groff 1
982: .Sx \&i
983: macro will italicise all subsequent text if a line argument is not
984: provided. This behaviour is not implemented.
1.32 kristaps 985: .It
1.23 kristaps 986: In quoted literals, groff allowed pair-wise double-quotes to produce a
987: standalone double-quote in formatted output. This idiosyncratic
988: behaviour is no longer applicable.
1.32 kristaps 989: .It
1.23 kristaps 990: The
1.51 kristaps 991: .Sx \&sp
1.23 kristaps 992: macro does not accept negative numbers.
1.32 kristaps 993: .It
1.23 kristaps 994: Blocks of whitespace are stripped from both macro and free-form text
995: lines (except when in literal mode), while groff would retain whitespace
996: in free-form text lines.
1.32 kristaps 997: .El
1.28 kristaps 998: .
999: .
1.1 kristaps 1000: .Sh SEE ALSO
1.32 kristaps 1001: .Xr mandoc 1 ,
1002: .Xr mandoc_char 7
1.28 kristaps 1003: .
1004: .
1.1 kristaps 1005: .Sh AUTHORS
1006: The
1.32 kristaps 1007: .Nm
1.23 kristaps 1008: reference was written by
1.32 kristaps 1009: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.28 kristaps 1010: .
1011: .
1.1 kristaps 1012: .Sh CAVEATS
1013: Do not use this language. Use
1.32 kristaps 1014: .Xr mdoc 7 ,
1.1 kristaps 1015: instead.
1.28 kristaps 1016: .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to man.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc