Annotation of mandoc/man.7, Revision 1.2
1.2 ! kristaps 1: .\" $Id: man.7,v 1.1 2009/03/23 16:02:56 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
37: .Em \&Do not
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:
52: .Bd -literal -offset XXX
53: \&.SH Macro lines change control state.
54: Other lines are interpreted within the current state.
55: .Ed
56: .\" PARAGRAPH
57: .Pp
58: Macros are character sequences whose structural rules are described
59: later in this document.
60: .\" SECTION
61: .Sh INPUT ENCODING
62: .Nm
63: documents may contain only graphable 7-bit ASCII characters and the
64: space character
65: .Sq \ .
66: All manuals must have
67: .Sq \en
68: line termination.
69: .Pp
70: Blank lines are acceptable; where found, the output will also assert a
71: vertical space.
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: .Pp
1.2 ! kristaps 88: The
! 89: .Xr mdoc 7
! 90: contains a table of all available escapes.
1.1 kristaps 91: .\" SECTION
92: .Sh STRUCTURE
1.2 ! kristaps 93: Macros are one to three three characters in length and begin with a
! 94: control character
! 95: .Sq \&.
! 96: at the beginning of the line. An arbitrary amount of whitespace may
! 97: sit between the control character and the macro name. Thus,
! 98: .Sq \&PP
! 99: and
! 100: .Sq \&.\ \ \ \&PP
! 101: are equivalent.
! 102: .Pp
! 103: All follow the same
! 104: structural rules:
1.1 kristaps 105: .Bd -literal -offset XXXX
106: \&.Yo \(lBbody...\(rB
107: .Ed
108: .Pp
109: The
110: .Dq body
111: consists of zero or more arguments to the macro.
112: .\" PARAGRAPH
113: .Sh MACROS
114: This section contains a complete list of all
115: .Nm
116: macros, arranged alphabetically, with the number of arguments.
117: .Pp
118: .Bl -column "MacroX" "Arguments" -compact -offset XXXX
119: .It Em Macro Ta Em Arguments
120: .It \&.TH Ta >0
121: .It \&.SH Ta n
122: .It \&.SS Ta n
123: .It \&.TP Ta n
124: .It \&.LP Ta n
125: .It \&.PP Ta n
126: .It \&.P Ta n
127: .It \&.IP Ta n
128: .It \&.HP Ta n
129: .It \&.SM Ta n
130: .It \&.SB Ta n
131: .It \&.BI Ta n
132: .It \&.IB Ta n
133: .It \&.BR Ta n
134: .It \&.RB Ta n
135: .It \&.R Ta n
136: .It \&.B Ta n
137: .It \&.I Ta n
138: .It \&.IR Ta n
139: .El
140: .\" SECTION
141: .Sh SEE ALSO
142: .Xr mandoc 1
143: .\" SECTION
144: .Sh AUTHORS
145: The
146: .Nm
147: utility was written by
148: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
149: .\" SECTION
150: .Sh CAVEATS
151: Do not use this language. Use
152: .Xr mdoc 7 ,
153: instead.
CVSweb