Annotation of mandoc/man.7, Revision 1.5
1.5 ! kristaps 1: .\" $Id: man.7,v 1.4 2009/03/26 16:23:22 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: .Pp
1.2 kristaps 92: The
93: .Xr mdoc 7
94: contains a table of all available escapes.
1.1 kristaps 95: .\" SECTION
96: .Sh STRUCTURE
1.2 kristaps 97: Macros are one to three three characters in length and begin with a
1.4 kristaps 98: control character ,
99: .Sq \&. ,
1.2 kristaps 100: at the beginning of the line. An arbitrary amount of whitespace may
101: sit between the control character and the macro name. Thus,
1.4 kristaps 102: .Sq \&.PP
1.2 kristaps 103: and
104: .Sq \&.\ \ \ \&PP
105: are equivalent.
106: .Pp
1.4 kristaps 107: All
108: .Nm
109: macros follow the same structural rules:
110: .Bd -literal -offset indent
111: \&.YO \(lBbody...\(rB
1.1 kristaps 112: .Ed
113: .Pp
114: The
115: .Dq body
116: consists of zero or more arguments to the macro.
1.4 kristaps 117: .Pp
118: .Nm
119: has a primitive notion of multi-line scope for the following macros:
120: .Sq \&.TM ,
121: .Sq \&.SM ,
122: .Sq \&.SB ,
123: .Sq \&.BI ,
124: .Sq \&.IB ,
125: .Sq \&.BR ,
126: .Sq \&.RB ,
127: .Sq \&.R ,
128: .Sq \&.B ,
129: .Sq \&.I ,
130: .Sq \&.IR
131: and
132: .Sq \&.RI .
133: When these macros are invoked without arguments, the subsequent line is
134: considered a continuation of the macro. Thus:
135: .Bd -literal -offset indent
136: \&.RI
137: foo
138: .Ed
139: .Pp
1.5 ! kristaps 140: is equivalent to
! 141: .Sq \&.RI foo .
! 142: If two consecutive lines exhibit the latter behaviour,
! 143: an error is raised. Thus, the following is not acceptable:
1.4 kristaps 144: .Bd -literal -offset indent
145: \&.RI
146: \&.I
147: Hello, world.
148: .Ed
149: .Pp
150: The
151: .Sq \&.TP
1.5 ! kristaps 152: macro is similar, but does not need an empty argument line to trigger
! 153: the behaviour.
1.1 kristaps 154: .\" PARAGRAPH
155: .Sh MACROS
156: This section contains a complete list of all
157: .Nm
1.5 ! kristaps 158: macros and corresponding number of arguments.
1.1 kristaps 159: .Pp
1.4 kristaps 160: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1 kristaps 161: .It Em Macro Ta Em Arguments
1.4 kristaps 162: .It \&.TH Ta >1, <6
163: .It \&.SH Ta >0
164: .It \&.SS Ta >0
1.1 kristaps 165: .It \&.TP Ta n
1.4 kristaps 166: .It \&.LP Ta 0
167: .It \&.PP Ta 0
168: .It \&.P Ta 0
169: .It \&.IP Ta <3
170: .It \&.HP Ta <2
1.1 kristaps 171: .It \&.SM Ta n
172: .It \&.SB Ta n
173: .It \&.BI Ta n
174: .It \&.IB Ta n
175: .It \&.BR Ta n
176: .It \&.RB Ta n
177: .It \&.R Ta n
178: .It \&.B Ta n
179: .It \&.I Ta n
180: .It \&.IR Ta n
1.3 kristaps 181: .It \&.RI Ta n
1.1 kristaps 182: .El
183: .\" SECTION
184: .Sh SEE ALSO
185: .Xr mandoc 1
186: .\" SECTION
187: .Sh AUTHORS
188: The
189: .Nm
190: utility was written by
191: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
192: .\" SECTION
193: .Sh CAVEATS
194: Do not use this language. Use
195: .Xr mdoc 7 ,
196: instead.
CVSweb