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