Annotation of mandoc/man.7, Revision 1.22
1.22 ! kristaps 1: .\" $Id: man.7,v 1.21 2009/07/27 12:35:53 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
20: .\" SECTION
21: .Sh NAME
22: .Nm man
23: .Nd man language reference
24: .\" SECTION
25: .Sh DESCRIPTION
26: The
27: .Nm man
1.20 kristaps 28: language was historically used to format
1.1 kristaps 29: .Ux
1.19 kristaps 30: manuals. This reference document describes its syntax, structure, and
31: usage.
1.1 kristaps 32: .Pp
1.20 kristaps 33: .Bf -emphasis
34: Do not use
1.1 kristaps 35: .Nm
1.20 kristaps 36: to write your manuals.
1.19 kristaps 37: .Ef
38: Use the
1.1 kristaps 39: .Xr mdoc 7
40: language, instead.
41: .\" PARAGRAPH
42: .Pp
43: An
44: .Nm
45: document follows simple rules: lines beginning with the control
1.20 kristaps 46: character
1.2 kristaps 47: .Sq \&.
1.1 kristaps 48: are parsed for macros. Other lines are interpreted within the scope of
49: prior macros:
1.4 kristaps 50: .Bd -literal -offset indent
1.1 kristaps 51: \&.SH Macro lines change control state.
52: Other lines are interpreted within the current state.
53: .Ed
54: .\" SECTION
55: .Sh INPUT ENCODING
56: .Nm
1.14 kristaps 57: documents may contain only graphable 7-bit ASCII characters, the
1.19 kristaps 58: space character, and the tabs character. All manuals must have
1.5 kristaps 59: .Ux
1.20 kristaps 60: line termination.
1.1 kristaps 61: .Pp
1.5 kristaps 62: Blank lines are acceptable; where found, the output will assert a
1.1 kristaps 63: vertical space.
1.4 kristaps 64: .Pp
65: The
66: .Sq \ec
67: escape is common in historical
68: .Nm
69: documents; if encountered at the end of a word, it ensures that the
70: subsequent word isn't off-set by whitespace.
1.1 kristaps 71: .\" SUB-SECTION
1.13 kristaps 72: .Ss Comments
1.21 kristaps 73: Text following a
1.22 ! kristaps 74: .Sq \e\*" ,
1.21 kristaps 75: whether in a macro or free-form text line, is ignored to the end of
76: line. A macro line with only a control character and comment escape,
77: .Sq \&.\e" ,
1.22 ! kristaps 78: is also ignored. Macro lines with only a control charater and
! 79: optionally whitespace are stripped from input.
1.13 kristaps 80: .\" SUB-SECTION
1.1 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.2 kristaps 84: .Sq \e
1.20 kristaps 85: followed by either an open-parenthesis
1.1 kristaps 86: .Sq \&(
87: for two-character sequences; an open-bracket
88: .Sq \&[
89: for n-character sequences (terminated at a close-bracket
90: .Sq \&] ) ;
1.21 kristaps 91: or a single one-character sequence. See
92: .Xr mandoc_char 7
93: for a complete list. Examples include
94: .Sq \e(em
95: .Pq em-dash
96: and
97: .Sq \ee
98: .Pq back-slash .
99: .\" SUB-SECTION----------------------
100: .Ss Text Decoration
101: Terms may be text-decorated using the
1.18 kristaps 102: .Sq \ef
1.21 kristaps 103: escape followed by an indicator: B (bold), I, (italic), or P and R
104: (Roman, or reset).
105: .\" SUB-SECTION----------------------
1.17 kristaps 106: .Ss Whitespace
107: Unless specifically escaped, consecutive blocks of whitespace are pruned
108: from input. These are later re-added, if applicable, by a front-end
109: utility such as
110: .Xr mandoc 1 .
1.1 kristaps 111: .\" SECTION
1.22 ! kristaps 112: .Sh MANUAL STRUCTURE
1.16 kristaps 113: Each
114: .Nm
115: document must contain contains at least the
1.22 ! kristaps 116: .Sq \&TH
1.16 kristaps 117: macro describing the document's section and title. It may occur
118: anywhere in the document, although conventionally, it appears as the
119: first macro.
120: .Pp
1.22 ! kristaps 121: Beyond
! 122: .Sq \&TH ,
! 123: at least one macro or text node must appear in the document. Documents
! 124: are generally structured as follows:
! 125: .Bd -literal -offset indent
! 126: \&.TH FOO 1 "13 Aug 2009"
! 127: \&.
! 128: \&.SH NAME
! 129: foo \e- a description goes here
! 130: \&.
! 131: \&.SH SYNOPSIS
! 132: \efBfoo\efR [\efB\e-options\efR] arguments...
! 133: \&.
! 134: \&.SH DESCRIPTION
! 135: The \efBfoo\efR utility does...
! 136: \&.
! 137: \&.\e\*q .SH RETURN VALUES
! 138: \&.\e\*q .SH ENVIRONMENT
! 139: \&.\e\*q .SH FILES
! 140: \&.\e\*q .SH EXAMPLES
! 141: \&.\e\*q .SH DIAGNOSTICS
! 142: \&.\e\*q .SH ERRORS
! 143: \&.\e\*q .SH SEE ALSO
! 144: \&.\e\*q \efBbar\efR(1)
! 145: \&.\e\*q .SH STANDARDS
! 146: \&.\e\*q .SH HISTORY
! 147: \&.\e\*q .SH AUTHORS
! 148: \&.\e\*q .SH CAVEATS
! 149: \&.\e\*q .SH BUGS
! 150: .Ed
1.16 kristaps 151: .\" SECTION
1.22 ! kristaps 152: .Sh MACRO SYNTAX
1.2 kristaps 153: Macros are one to three three characters in length and begin with a
1.4 kristaps 154: control character ,
155: .Sq \&. ,
1.2 kristaps 156: at the beginning of the line. An arbitrary amount of whitespace may
157: sit between the control character and the macro name. Thus,
1.4 kristaps 158: .Sq \&.PP
1.2 kristaps 159: and
160: .Sq \&.\ \ \ \&PP
161: are equivalent.
162: .Pp
1.1 kristaps 163: The
1.4 kristaps 164: .Nm
1.22 ! kristaps 165: macros are classified by scope: line scope or block scope. Line-scoped
! 166: macros are only scoped to the current line (and, in some situations,
! 167: the subsequent line). Block macros are scoped to the current line and
! 168: subsequent lines until closed by another block macro.
! 169: .\" SUBSECTION
! 170: .Ss Line Macros
! 171: Line-macros are scoped to the current line, with the body consisting of
! 172: zero or more arguments. If a macro is next-line scoped and the line
! 173: arguments are empty, the next line is used instead. Thus:
1.20 kristaps 174: .Bd -literal -offset indent
175: \&.RI
1.4 kristaps 176: foo
177: .Ed
1.22 ! kristaps 178: .\" PARAGRAPH
1.4 kristaps 179: .Pp
1.20 kristaps 180: is equivalent to
1.8 kristaps 181: .Sq \&.RI foo .
1.22 ! kristaps 182: .\" PARAGRAPH
! 183: Consecutive next-line invocations are disallowed.
1.20 kristaps 184: .Bd -literal -offset indent
1.22 ! kristaps 185: \&.YO \(lBbody...\(rB
! 186: \(lBbody...\(rB
1.4 kristaps 187: .Ed
1.22 ! kristaps 188: .\" PARAGRAPH
1.4 kristaps 189: .Pp
1.22 ! kristaps 190: .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
! 191: .It Em Macro Ta Em Arguments Ta Em Scope
! 192: .It \&B Ta n Ta next-line
! 193: .It \&BI Ta n Ta current
! 194: .It \&BR Ta n Ta current
! 195: .It \&I Ta n Ta next-line
! 196: .It \&IB Ta n Ta current
! 197: .It \&IR Ta n Ta current
! 198: .It \&R Ta n Ta next-line
! 199: .It \&RB Ta n Ta current
! 200: .It \&RI Ta n Ta current
! 201: .It \&SB Ta n Ta next-line
! 202: .It \&SM Ta n Ta next-line
! 203: .It \&TH Ta >1, <6 Ta current
! 204: .It \&br Ta 0 Ta current
! 205: .It \&fi Ta 0 Ta current
! 206: .It \&i Ta n Ta current
! 207: .It \&na Ta 0 Ta current
! 208: .It \&nf Ta 0 Ta current
! 209: .It \&r Ta 0 Ta current
! 210: .It \&sp Ta 1 Ta current
1.1 kristaps 211: .El
1.22 ! kristaps 212: .\" PARAGRAPH
1.7 kristaps 213: .Pp
1.22 ! kristaps 214: The lower-case
! 215: .Sq \&br ,
! 216: .Sq \&fi ,
! 217: .Sq \&i ,
! 218: .Sq \&na ,
! 219: .Sq \&nf ,
! 220: .Sq \&r ,
! 221: and
! 222: .Sq \&sp
! 223: macros aren't historically part of
1.7 kristaps 224: .Nm
1.22 ! kristaps 225: and should not be used. They're included for compatibility.
! 226: .\" SUBSECTION
! 227: .Ss Block Macros
! 228: Block macros are comprised of a head and body. The head is scoped to
! 229: the current line and, in one circumstance, the next line; the body is
! 230: scoped to subsequent lines and is closed out by a subsequent block macro
! 231: invocation.
! 232: .Bd -literal -offset indent
! 233: \&.YO \(lBhead...\(rB
! 234: \(lBhead...\(rB
! 235: \(lBbody...\(rB
! 236: .Ed
! 237: .\" PARAGRAPH
! 238: .Pp
! 239: If a block macro is next-line scoped, it may only be followed by in-line
! 240: macros (excluding
! 241: .Sq na ,
! 242: .Sq sp ,
! 243: .Sq nf ,
! 244: .Sq fi ,
! 245: and
! 246: .Sq TH ) .
! 247: .\" PARAGRAPH
1.7 kristaps 248: .Pp
1.22 ! kristaps 249: .Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent
! 250: .It Em Macro Ta Em Arguments Ta Em Scope
! 251: .It \&HP Ta <2 Ta current
! 252: .It \&IP Ta <3 Ta current
! 253: .It \&LP Ta 0 Ta current
! 254: .It \&P Ta 0 Ta current
! 255: .It \&PP Ta 0 Ta current
! 256: .It \&SH Ta >0 Ta current
! 257: .It \&SS Ta >0 Ta current
! 258: .It \&TP Ta n Ta next-line
1.7 kristaps 259: .El
1.22 ! kristaps 260: .\" SECTION
! 261: .Sh REFERENCE
! 262: This section is a canonical reference to all macros, arranged
! 263: alphabetically. For the scoping of individual macros, see
! 264: .Sx MACRO SYNTAX .
! 265: .Bl -tag -width Ds -offset indent
! 266: .It \&B
! 267: Text is rendered in bold face.
! 268: .It \&BI
! 269: Text is rendered alternately in bold face and italic. Thus,
! 270: .Sq \&.BI this word and that
! 271: causes
! 272: .Sq this
! 273: and
! 274: .Sq and
! 275: to render in bold face, while
! 276: .Sq word
! 277: and
! 278: .Sq that
! 279: render in italics. Whitespace between arguments is omitted in output.
! 280: .It \&BR
! 281: Text is rendered alternately in bold face and roman (the default font).
! 282: Whitespace between arguments is omitted in output.
! 283: .It \&HP
! 284: .\" TODO.
! 285: .It \&I
! 286: Text is rendered in italics.
! 287: .It \&IB
! 288: Text is rendered alternately in italics and bold face. Whitespace
! 289: between arguments is omitted in output.
! 290: .It \&IP
! 291: .\" TODO.
! 292: .It \&IR
! 293: Text is rendered alternately in italics and roman (the default font).
! 294: Whitespace between arguments is omitted in output.
! 295: .It \&LP, \&P, \&PP
! 296: Begin an undecorated paragraph. The scope of a paragraph is closed by a
! 297: subsequent paragraph, sub-section, section, or end of file.
! 298: .It \&R
! 299: Text is rendered in roman (the default font).
! 300: .It \&RB
! 301: Text is rendered alternately in roman (the default font) and bold face.
! 302: Whitespace between arguments is omitted in output.
! 303: .It \&RI
! 304: Text is rendered alternately in roman (the default font) and italics.
! 305: Whitespace between arguments is omitted in output.
! 306: .It \&SB
! 307: Text is rendered in small size (one point smaller than the default font)
! 308: bold face.
! 309: .It \&SH
! 310: Begin a section. The scope of a section is only closed by another
! 311: section or the end of file.
! 312: .It \&SM
! 313: Text is rendered in small size (one point smaller than the default
! 314: font).
! 315: .It \&SS
! 316: Begin a sub-section. The scope of a sub-section is closed by a
! 317: subsequent sub-section, section, or end of file.
! 318: .It \&TH
! 319: Sets the title of the manual page with the following syntax:
! 320: .Bd -literal -offset indent
! 321: \&.TH title section date source volume
! 322: .Ed
1.8 kristaps 323: .Pp
1.22 ! kristaps 324: At least the
! 325: .Va title
! 326: and
! 327: .Va section
! 328: arguments must be provided. The
! 329: .Va date
! 330: argument should be formatted as
! 331: .Qq %b [%d] %Y
! 332: format, described in
! 333: .Xr strptime 3 .
! 334: The
! 335: .Va source
! 336: string specifies the organisation providing the utility. The
! 337: .Va volume
! 338: replaces the default rendered volume as dictated by the manual section.
! 339: .It \&TP
! 340: .\" TODO.
! 341: .It \&br
! 342: Breaks the current line. Consecutive invocations have no further effect.
! 343: .\" TODO.
! 344: .It \&fi
! 345: End literal mode begun by
! 346: .Sq \&nf .
! 347: .It \&i
! 348: Italicise arguments. If no arguments are specified, all subsequent text
! 349: is italicised.
! 350: .It \&na
! 351: No alignment to the right margin.
! 352: .It \&nf
! 353: Begin literal mode: all subsequent free-form lines have their end of
! 354: line boundaries preserved. May be ended by
! 355: .Sq \&fi .
! 356: .It \&r
! 357: Fonts and styles (bold face, italics) reset to roman (default font).
! 358: .It \&sp
! 359: Insert n spaces, where n is the macro's positive numeric argument. If
! 360: 0, this is equivalent to the
! 361: .Sq br
! 362: macro.
! 363: .El
1.1 kristaps 364: .\" SECTION
1.18 kristaps 365: .Sh COMPATIBILITY
366: See
367: .Xr mdoc 7
368: for groff compatibility notes.
369: .\" SECTION
1.1 kristaps 370: .Sh SEE ALSO
1.6 kristaps 371: .Xr mandoc 1 ,
372: .Xr mandoc_char 7
1.1 kristaps 373: .\" SECTION
374: .Sh AUTHORS
375: The
376: .Nm
1.20 kristaps 377: utility was written by
1.12 kristaps 378: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 379: .\" SECTION
380: .Sh CAVEATS
381: Do not use this language. Use
382: .Xr mdoc 7 ,
383: instead.
CVSweb