1 .\" Copyright (c) 1998.
2 .\" The FreeBSD Project. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39 .Nd quick reference guide for the
49 package is a set of macros used to format
55 is deprecated and the more expressive
57 package is recommended in its place.
61 macros are named using one or two upper case alphabetic characters.
64 convention, each macro request starts with a
66 as the first character of a line. Arguments to macro requests
67 expecting printable text may consist of zero to six words. Some macros will
68 process the next input line if no arguments are supplied. For
71 request on a line by itself will cause the next input line to be set
73 Whitespace characters may be embedded in an argument by enclosing
74 it in quotes. Type font and size are reset to their defaults before
75 each paragraph and after processing font size and face changing macros.
77 The prevailing indent distance is remembered between successive
78 indented paragraphs and is reset to the default on reaching a
79 non-indented paragraph. Default units for indents are
84 program is conventionally used to format and display manual pages. If
85 the first line of the manual page source starts with the literal string
87 .\" " bring emacs's font-lock mode back in sync ...
88 then the remaining letters on the line indicate preprocessors that
89 need to be run prior to formatting with
91 Supported preprocessing directives are:
92 .Bl -column "Letter" "Preprocessor" -offset indent
93 .It Em Letter Ta Em Preprocessor
101 .Ss Available Strings
104 package has the following predefined strings:
105 .Bl -column "String" "XXXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
106 .It Em String Ta Em Description
107 .It "\e*R" Ta "registration symbol"
108 .It "\e*S" Ta "change to default font size"
109 .It "\e*(Tm" Ta "trademark symbol"
110 .It "\e*(lq" Ta "left quote"
111 .It "\e*(rq" Ta "right quote"
115 The available macros are presented in alphabetical order.
116 .Bl -tag -width "XXX XX"
120 using a bold face. Does not cause a line break. If no
121 arguments are given the next text line is processed.
122 .It ".BI" Op Ar words
125 alternating bold and italic faces. Does not cause a line break. If
126 no arguments are given the next text line is processed.
127 .It ".BR" Op Ar words
130 alternating bold and roman faces. Does not cause a line break. If no
131 arguments are given the next text line is processed.
133 restore the default tab spacing of 0.5 inches. Does not cause a line
135 .It ".HP" Op Ar indent
136 Begin a paragraph with a hanging indent and sets the prevailing indent
139 This request forces a line break. If
141 is not specified, the value of the prevailing indent is used.
145 using an italic face. Does not cause a line break. If no
146 arguments are given the next text line is processed.
147 .It ".IB" Op Ar words
150 alternating italic and bold faces. Does not cause a line break. If no
151 arguments are given the next text line is processed.
152 .It ".IP" Op Ar tag Op Ar indent
153 Begin an indented paragraph with tag
155 and prevailing indent set to
159 is not specified it is taken to be the null string
163 is not specified it is taken to be the prevailing indent.
164 .It ".IR" Op Ar words
167 alternating italic and roman faces.
168 Does not cause a line break. If no
169 arguments are given the next text line is processed.
171 begin a left-aligned paragraph. The prevailing indent is set to the
172 default. This request forces a line break.
175 .It ".PD" Op Ar distance
176 set the vertical distance between paragraphs to
180 is not specified a value of 0.4v is used.
184 end of a relative indent (see \&.RS below). This request forces a
185 line break and restores the prevailing indent to its previous value.
186 .It ".RB" Op Ar words
189 alternating roman and bold faces. Does not cause a line break. If no
190 arguments are given the next text line is processed.
191 .It ".RI" Op Ar words
194 alternating roman and italic faces. Does not cause a line break. If no
195 arguments are given the next text line is processed.
196 .It ".RS" Op Ar indent
197 start a relative indent, increasing the indentation by
201 is not specified, the value of the prevailing indent is used.
202 .It ".SB" Op Ar words
205 using a bold face after reducing the font size by 1 point.
206 Does not cause a line break. If no arguments are given the next text
208 .It ".SH" Op Ar words
209 specifies a section heading. This request forces a line break.
210 It resets the prevailing indent and margins to their defaults.
211 .It ".SM" Op Ar words
214 after reducing the font size by 1 point. Does not cause a line break.
215 If no arguments are given the next text line is processed.
216 .It ".SS" Op Ar words
217 specifies a section subheading. This request forces a line
218 break. If no arguments are given the next text line is processed.
219 It resets the prevailing indent and margins to their defaults.
220 .It ".TH" Ar name Ar section Ar date Xo
221 .Op Ar footer Op Ar center
229 is the date of the most recent change. If present,
231 specifies the left page footer text and
233 specifies the center header text. This request must the very first
234 request in the manual page.
235 .It ".TP" Op Ar indent
236 begin an indented paragraph with the tag specified in the next text
239 is given, it specifies the new value of the prevailing indent.
240 This request forces a line break.
243 Most manual pages follow the general structure outlined below:
244 .Bl -tag -width ".SH NAME"
245 .It ".TH" Ar title Op Ar section-number
246 The very first macro request in a manual page has to be the \&.TH
247 request which establishes the name and title of the manual page. The
248 \&.TH request also establishes the number of the manual page section.
250 The name, or list of names, by which the command is called, followed
251 by a dash and a one-line summary of the action performed. This
252 section should not contain any
254 commands or escapes, or any macro requests. This section is used to
255 generate the database used by the
259 A brief summary of the usage of the command or function being
261 .Bl -tag -width "Commands"
263 The syntax of the command and its arguments as would be typed on the
264 command line. Words that have to be typed exactly as printed are to
265 be presented in bold face. Arguments are indicated by the use of an
266 italic face. Arguments and command names so indicated should not be
267 capitalized, even when starting a sentence.
269 Syntactic symbols used should appear in roman face:
270 .Bl -tag -width "XXX"
272 square brackets are used to indicate optional arguments.
274 vertical bars are used to indicate a one of many exclusive choice.
275 Only one item from a list separated by vertical bars is to be selected.
277 an ellipsis following an argument is used to indicate that the
278 arguments can be repeated. When an ellipsis follows a bracketed set,
279 the expression within the brackets can be repeated.
282 Required data declarations or
284 directives are to be shown first, followed by the function declaration.
286 .It ".SH DESCRIPTION"
287 An overview of the command or functions external behavior, including
288 its interactions with files or data, how standard input, standard
289 output and standard error are handled. Internals and implementation
290 details are not normally specified. The question answered by this
291 section is "what does it do?" or "what is it for?".
293 Literal text, filenames and references to items that appear elsewhere
294 in the reference manuals should be presented using a constant width
296 Arguments should be presented using an italic face.
298 The list of options together with a description of how each affects
299 the commands operation.
301 This section is optional and contains a detailed description of the
302 subcommands and input grammar understood by the command.
303 .It ".SH RETURN VALUES"
304 The list of return values a library routine could return to the caller,
305 with the conditions that cause these values to be returned.
306 .It ".SH EXIT STATUS"
307 The list of values returned as the exit status of the command, with
308 the conditions that cause these values to be returned.
310 The list of files associated with the command or function.
312 A comma separated list of related manual pages followed by references
313 to other published documentation.
314 .It ".SH DIAGNOSTICS"
315 A list of diagnostic messages with corresponding explanations.
317 Known defects and limitations, if any.
320 .Bl -tag -width "/usr/share/tmac/tmac.groff_an"
321 .It "/usr/share/tmac/tmac.an"
322 Initial file defining the
325 .It "/usr/share/tmac/tmac.groff_an"
327 source for macro definitions.
328 .It "/usr/share/tmac/man.local"
329 local modifications to the
343 This manual page was written by
344 .An Joseph Koshy Aq jkoshy@FreeBSD.org .