Annotation of src/usr.bin/mandoc/man.7, Revision 1.2
1.2 ! schwarze 1: .\" $Id: man.7,v 1.12 2009/06/11 07:26:35 kristaps 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: .\"
17: .Dd $Mdocdate$
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
55: documents may contain only graphable 7-bit ASCII characters and the
56: space character
57: .Sq \ .
58: All manuals must have
59: .Ux
60: .Sq \en
61: line termination.
62: .Pp
63: Blank lines are acceptable; where found, the output will assert a
64: vertical space.
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.
72: .\" SUB-SECTION
73: .Ss Special Characters
74: Special character sequences begin with the escape character
75: .Sq \e
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,
85: .Sq \e* ,
86: with the same combinations as described above. This form is deprecated.
87: .\" SECTION
88: .Sh STRUCTURE
89: Macros are one to three three characters in length and begin with a
90: control character ,
91: .Sq \&. ,
92: at the beginning of the line. An arbitrary amount of whitespace may
93: sit between the control character and the macro name. Thus,
94: .Sq \&.PP
95: and
96: .Sq \&.\ \ \ \&PP
97: are equivalent.
98: .Pp
99: All
100: .Nm
101: macros follow the same structural rules:
102: .Bd -literal -offset indent
103: \&.YO \(lBbody...\(rB
104: .Ed
105: .Pp
106: The
107: .Dq body
108: consists of zero or more arguments to the macro.
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
132: is equivalent to
133: .Sq \&.RI foo .
134: If two consecutive lines exhibit the latter behaviour,
135: an error is raised. Thus, the following is not acceptable:
136: .Bd -literal -offset indent
137: \&.RI
138: \&.I
139: Hello, world.
140: .Ed
141: .Pp
142: The
143: .Sq \&.TP
144: macro is similar, but does not need an empty argument line to trigger
145: the behaviour.
146: .\" PARAGRAPH
147: .Sh MACROS
148: This section contains a complete list of all
149: .Nm
150: macros and corresponding number of arguments.
151: .Pp
152: .Bl -column "MacroX" "Arguments" -compact -offset indent
153: .It Em Macro Ta Em Arguments
154: .It \&.TH Ta >1, <6
155: .It \&.SH Ta >0
156: .It \&.SS Ta >0
157: .It \&.TP Ta n
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
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
173: .It \&.RI Ta n
174: .El
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
183: .It \&.i Ta n
184: .El
185: .Pp
186: These follow the same calling conventions as the above
187: .Nm
188: macros.
189: .\" SECTION
190: .Sh SEE ALSO
191: .Xr mandoc 1 ,
192: .Xr mandoc_char 7
193: .\" SECTION
194: .Sh AUTHORS
195: The
196: .Nm
197: utility was written by
1.2 ! schwarze 198: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 199: .\" SECTION
200: .Sh CAVEATS
201: Do not use this language. Use
202: .Xr mdoc 7 ,
203: instead.
![[BACK]](/icons/back.gif){kind=icon}
Return to man.7 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc