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