Annotation of mandoc/man.7, Revision 1.13
1.13 ! kristaps 1: .\" $Id: man.7,v 1.12 2009/06/11 07:26:35 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
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
1.13 ! kristaps 73: .Ss Comments
! 74: Anything following a
! 75: .Sq \e"
! 76: delimiter is considered a comment (unless the
! 77: .Sq \e
! 78: itself has been escaped) and is ignored to the end of line.
! 79: Furthermore, a macro line with only a control character
! 80: .Sq \. ,
! 81: optionally followed by whitespace, is ignored.
! 82: .\" SUB-SECTION
1.1 kristaps 83: .Ss Special Characters
84: Special character sequences begin with the escape character
1.2 kristaps 85: .Sq \e
1.1 kristaps 86: followed by either an open-parenthesis
87: .Sq \&(
88: for two-character sequences; an open-bracket
89: .Sq \&[
90: for n-character sequences (terminated at a close-bracket
91: .Sq \&] ) ;
92: or a single one-character sequence.
93: .Pp
94: Characters may alternatively be escaped by a slash-asterisk,
1.2 kristaps 95: .Sq \e* ,
1.1 kristaps 96: with the same combinations as described above. This form is deprecated.
97: .\" SECTION
98: .Sh STRUCTURE
1.2 kristaps 99: Macros are one to three three characters in length and begin with a
1.4 kristaps 100: control character ,
101: .Sq \&. ,
1.2 kristaps 102: at the beginning of the line. An arbitrary amount of whitespace may
103: sit between the control character and the macro name. Thus,
1.4 kristaps 104: .Sq \&.PP
1.2 kristaps 105: and
106: .Sq \&.\ \ \ \&PP
107: are equivalent.
108: .Pp
1.4 kristaps 109: All
110: .Nm
111: macros follow the same structural rules:
112: .Bd -literal -offset indent
113: \&.YO \(lBbody...\(rB
1.1 kristaps 114: .Ed
115: .Pp
116: The
117: .Dq body
118: consists of zero or more arguments to the macro.
1.4 kristaps 119: .Pp
120: .Nm
121: has a primitive notion of multi-line scope for the following macros:
122: .Sq \&.TM ,
123: .Sq \&.SM ,
124: .Sq \&.SB ,
125: .Sq \&.BI ,
126: .Sq \&.IB ,
127: .Sq \&.BR ,
128: .Sq \&.RB ,
129: .Sq \&.R ,
130: .Sq \&.B ,
131: .Sq \&.I ,
132: .Sq \&.IR
133: and
134: .Sq \&.RI .
135: When these macros are invoked without arguments, the subsequent line is
136: considered a continuation of the macro. Thus:
137: .Bd -literal -offset indent
138: \&.RI
139: foo
140: .Ed
141: .Pp
1.5 kristaps 142: is equivalent to
1.8 kristaps 143: .Sq \&.RI foo .
1.5 kristaps 144: If two consecutive lines exhibit the latter behaviour,
145: an error is raised. Thus, the following is not acceptable:
1.4 kristaps 146: .Bd -literal -offset indent
147: \&.RI
148: \&.I
149: Hello, world.
150: .Ed
151: .Pp
152: The
153: .Sq \&.TP
1.5 kristaps 154: macro is similar, but does not need an empty argument line to trigger
155: the behaviour.
1.1 kristaps 156: .\" PARAGRAPH
157: .Sh MACROS
158: This section contains a complete list of all
159: .Nm
1.5 kristaps 160: macros and corresponding number of arguments.
1.1 kristaps 161: .Pp
1.4 kristaps 162: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1 kristaps 163: .It Em Macro Ta Em Arguments
1.4 kristaps 164: .It \&.TH Ta >1, <6
165: .It \&.SH Ta >0
166: .It \&.SS Ta >0
1.1 kristaps 167: .It \&.TP Ta n
1.4 kristaps 168: .It \&.LP Ta 0
169: .It \&.PP Ta 0
170: .It \&.P Ta 0
171: .It \&.IP Ta <3
172: .It \&.HP Ta <2
1.1 kristaps 173: .It \&.SM Ta n
174: .It \&.SB Ta n
175: .It \&.BI Ta n
176: .It \&.IB Ta n
177: .It \&.BR Ta n
178: .It \&.RB Ta n
179: .It \&.R Ta n
180: .It \&.B Ta n
181: .It \&.I Ta n
182: .It \&.IR Ta n
1.3 kristaps 183: .It \&.RI Ta n
1.1 kristaps 184: .El
1.7 kristaps 185: .Pp
186: Although not historically part of the
187: .Nm
188: system, the following macros are also supported:
189: .Pp
190: .Bl -column "MacroX" "Arguments" -compact -offset indent
191: .It Em Macro Ta Em Arguments
192: .It \&.br Ta 0
1.8 kristaps 193: .It \&.i Ta n
1.7 kristaps 194: .El
1.8 kristaps 195: .Pp
196: These follow the same calling conventions as the above
197: .Nm
198: macros.
1.1 kristaps 199: .\" SECTION
200: .Sh SEE ALSO
1.6 kristaps 201: .Xr mandoc 1 ,
202: .Xr mandoc_char 7
1.1 kristaps 203: .\" SECTION
204: .Sh AUTHORS
205: The
206: .Nm
207: utility was written by
1.12 kristaps 208: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 209: .\" SECTION
210: .Sh CAVEATS
211: Do not use this language. Use
212: .Xr mdoc 7 ,
213: instead.
CVSweb