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