Annotation of mandoc/man.7, Revision 1.7
1.7 ! kristaps 1: .\" $Id: man.7,v 1.6 2009/03/27 14:56:15 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the
7: .\" above copyright notice and this permission notice appear in all
8: .\" copies.
9: .\"
10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17: .\" PERFORMANCE OF THIS SOFTWARE.
18: .\"
19: .Dd $Mdocdate$
20: .Dt man 7
21: .Os
22: .\" SECTION
23: .Sh NAME
24: .Nm man
25: .Nd man language reference
26: .\" SECTION
27: .Sh DESCRIPTION
28: The
29: .Nm man
30: language was historically used to format
31: .Ux
32: manuals. In this reference document, we describe the syntax and
33: structure of the
34: .Nm
35: language.
36: .Pp
1.4 kristaps 37: .Em \&Do not ever
1.1 kristaps 38: use
39: .Nm
40: to write your manuals. Use the
41: .Xr mdoc 7
42: language, instead.
43: .\" PARAGRAPH
44: .Pp
45: An
46: .Nm
47: document follows simple rules: lines beginning with the control
48: character
1.2 kristaps 49: .Sq \&.
1.1 kristaps 50: are parsed for macros. Other lines are interpreted within the scope of
51: prior macros:
1.4 kristaps 52: .Bd -literal -offset indent
1.1 kristaps 53: \&.SH Macro lines change control state.
54: Other lines are interpreted within the current state.
55: .Ed
56: .\" SECTION
57: .Sh INPUT ENCODING
58: .Nm
59: documents may contain only graphable 7-bit ASCII characters and the
60: space character
61: .Sq \ .
62: All manuals must have
1.5 kristaps 63: .Ux
1.1 kristaps 64: .Sq \en
65: line termination.
66: .Pp
1.5 kristaps 67: Blank lines are acceptable; where found, the output will assert a
1.1 kristaps 68: vertical space.
1.4 kristaps 69: .Pp
70: The
71: .Sq \ec
72: escape is common in historical
73: .Nm
74: documents; if encountered at the end of a word, it ensures that the
75: subsequent word isn't off-set by whitespace.
1.1 kristaps 76: .\" SUB-SECTION
77: .Ss Special Characters
78: Special character sequences begin with the escape character
1.2 kristaps 79: .Sq \e
1.1 kristaps 80: followed by either an open-parenthesis
81: .Sq \&(
82: for two-character sequences; an open-bracket
83: .Sq \&[
84: for n-character sequences (terminated at a close-bracket
85: .Sq \&] ) ;
86: or a single one-character sequence.
87: .Pp
88: Characters may alternatively be escaped by a slash-asterisk,
1.2 kristaps 89: .Sq \e* ,
1.1 kristaps 90: with the same combinations as described above. This form is deprecated.
91: .\" SECTION
92: .Sh STRUCTURE
1.2 kristaps 93: Macros are one to three three characters in length and begin with a
1.4 kristaps 94: control character ,
95: .Sq \&. ,
1.2 kristaps 96: at the beginning of the line. An arbitrary amount of whitespace may
97: sit between the control character and the macro name. Thus,
1.4 kristaps 98: .Sq \&.PP
1.2 kristaps 99: and
100: .Sq \&.\ \ \ \&PP
101: are equivalent.
102: .Pp
1.4 kristaps 103: All
104: .Nm
105: macros follow the same structural rules:
106: .Bd -literal -offset indent
107: \&.YO \(lBbody...\(rB
1.1 kristaps 108: .Ed
109: .Pp
110: The
111: .Dq body
112: consists of zero or more arguments to the macro.
1.4 kristaps 113: .Pp
114: .Nm
115: has a primitive notion of multi-line scope for the following macros:
116: .Sq \&.TM ,
117: .Sq \&.SM ,
118: .Sq \&.SB ,
119: .Sq \&.BI ,
120: .Sq \&.IB ,
121: .Sq \&.BR ,
122: .Sq \&.RB ,
123: .Sq \&.R ,
124: .Sq \&.B ,
125: .Sq \&.I ,
126: .Sq \&.IR
127: and
128: .Sq \&.RI .
129: When these macros are invoked without arguments, the subsequent line is
130: considered a continuation of the macro. Thus:
131: .Bd -literal -offset indent
132: \&.RI
133: foo
134: .Ed
135: .Pp
1.5 kristaps 136: is equivalent to
137: .Sq \&.RI foo .
138: If two consecutive lines exhibit the latter behaviour,
139: an error is raised. Thus, the following is not acceptable:
1.4 kristaps 140: .Bd -literal -offset indent
141: \&.RI
142: \&.I
143: Hello, world.
144: .Ed
145: .Pp
146: The
147: .Sq \&.TP
1.5 kristaps 148: macro is similar, but does not need an empty argument line to trigger
149: the behaviour.
1.1 kristaps 150: .\" PARAGRAPH
151: .Sh MACROS
152: This section contains a complete list of all
153: .Nm
1.5 kristaps 154: macros and corresponding number of arguments.
1.1 kristaps 155: .Pp
1.4 kristaps 156: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1 kristaps 157: .It Em Macro Ta Em Arguments
1.4 kristaps 158: .It \&.TH Ta >1, <6
159: .It \&.SH Ta >0
160: .It \&.SS Ta >0
1.1 kristaps 161: .It \&.TP Ta n
1.4 kristaps 162: .It \&.LP Ta 0
163: .It \&.PP Ta 0
164: .It \&.P Ta 0
165: .It \&.IP Ta <3
166: .It \&.HP Ta <2
1.1 kristaps 167: .It \&.SM Ta n
168: .It \&.SB Ta n
169: .It \&.BI Ta n
170: .It \&.IB Ta n
171: .It \&.BR Ta n
172: .It \&.RB Ta n
173: .It \&.R Ta n
174: .It \&.B Ta n
175: .It \&.I Ta n
176: .It \&.IR Ta n
1.3 kristaps 177: .It \&.RI Ta n
1.1 kristaps 178: .El
1.7 ! kristaps 179: .Pp
! 180: Although not historically part of the
! 181: .Nm
! 182: system, the following macros are also supported:
! 183: .Pp
! 184: .Bl -column "MacroX" "Arguments" -compact -offset indent
! 185: .It Em Macro Ta Em Arguments
! 186: .It \&.br Ta 0
! 187: .El
1.1 kristaps 188: .\" SECTION
189: .Sh SEE ALSO
1.6 kristaps 190: .Xr mandoc 1 ,
191: .Xr mandoc_char 7
1.1 kristaps 192: .\" SECTION
193: .Sh AUTHORS
194: The
195: .Nm
196: utility was written by
197: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
198: .\" SECTION
199: .Sh CAVEATS
200: Do not use this language. Use
201: .Xr mdoc 7 ,
202: instead.
CVSweb