2 Copyright (C) 1999-2000, 2001, 2002, 2003 Free Software Foundation, Inc.
4 Permission is granted to make and distribute verbatim copies of
5 this manual provided the copyright notice and this permission notice
6 are preserved on all copies.
8 Permission is granted to copy and distribute modified versions of this
9 manual under the conditions for verbatim copying, provided that the
10 entire resulting derived work is distributed under the terms of a
11 permission notice identical to this one.
13 Permission is granted to copy and distribute translations of this
14 manual into another language, under the above conditions for modified
15 versions, except that this permission notice may be included in
16 translations approved by the Free Software Foundation instead of in
27 .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
30 .\" -----------------------------------------------------------------
34 groff_man \- groff `man' macros to support generation of man pages
37 .\" -----------------------------------------------------------------
60 .\" -----------------------------------------------------------------
66 macros used to generate man pages with
68 were written by James Clark.
69 This document provides a brief summary of the use of each macro in that
73 .\" -----------------------------------------------------------------
79 macros understand the following command line options (which define various
84 This option (the default if in nroff mode) will create a single, very long
85 page instead of multiple pages.
92 If more than one manual page is given on the command line, number the
93 pages continuously, rather than starting each at\ 1.
97 Double-sided printing.
98 Footers for even and odd pages are formatted differently.
102 Set distance of the footer relative to the bottom of the page if negative
103 or relative to the top if positive.
104 The default is -0.5i.
108 Set hyphenation flags.
110 Possible values are 1\ to hyphenate without restrictions, 2\ to not
111 hyphenate the last word on a page, 4\ to not hyphenate the last two
112 characters of a word, and 8\ to not hyphenate the first two characters
115 These values are additive; the default is\ 14.
119 Set body text indentation to
121 The default is 7n for
127 this value should always be an integer multiple of unit `n' to get
128 consistent indentation.
131 .BI \-rLL= line-length
133 If this option is not given, the line length defaults to 78n in nroff mode
134 and 6.5i in troff mode.
137 .BI \-rLT= title-length
139 If this option is not given, the title length defaults to the line length.
143 Enumeration of pages will start with
149 Base document font size is
153 can be 10, 11, or\ 12) rather than 10\ points.
157 Set sub-subheading indentation to
170 For example, the option `\-rX2' will produce the following page numbers:
171 1, 2, 2a, 2b, 2c, etc.
174 .\" -----------------------------------------------------------------
178 This section describes the available macros for manual pages.
179 For further customization, put additional macros and requests into the file
181 which will be loaded immediately after the
186 .BI .TH " title section " [ extra1 "] [" extra2 "] [" extra3 ]
187 Set the title of the man page to
191 which must take on a value between 1 and\ 8.
194 may also have a string appended, e.g. `.pm', to indicate a specific
195 subsection of the man pages.
200 are positioned at the left and right in the header line (with
202 in parentheses immediately appended to
205 will be positioned in the middle of the footer line.
207 will be positioned at the left in the footer line (or at the left on
208 even pages and at the right on odd pages if double-sided printing is
211 is centered in the header line.
214 For HTML output, headers and footers are completely supressed.
217 Additionally, this macro starts a new page; the new line number is\ 1 again
218 (except if the `-rC1' option is given on the command line) -- this feature
219 is intended only for formatting multiple man pages; a single man page should
222 macro at the beginning of the file.
225 .BI ".SH [" "text for a heading" ]
226 Set up an unnumbered section heading sticking out to the left.
227 Prints out all the text following
229 up to the end of the line (or the text in the next input line if there is
233 (or the font specified by the string
235 one size larger than the base document size.
236 Additionally, the left margin and the indentation for the following text
237 is reset to the default values.
240 .BI ".SS [" "text for a heading" ]
241 Set up a secondary, unnumbered section heading.
242 Prints out all the text following
244 up to the end of the line (or the text in the next input line if there is
248 (or the font specified by the string
250 at the same size as the base document size.
251 Additionally, the left margin and the indentation for the following text
252 is reset to the default values.
256 Set up an indented paragraph with label.
257 The indentation is set to
259 if that argument is supplied (the default unit is `n' if omitted), otherwise
260 it is set to the previous indentation value specified with
265 (or to the default value if none of them have been used yet).
268 The first input line of text following this macro is interpreted as a string
269 to be printed flush-left, as it is appropriate for a label.
270 It is not interpreted as part of a paragraph, so there is no attempt to fill
271 the first line with text from the following input lines.
272 Nevertheless, if the label is not as wide as the indentation the
273 paragraph starts at the same line (but indented), continuing on the
275 If the label is wider than the indentation the descriptive part of the
276 paragraph begins on the line following the label, entirely indented.
277 Note that neither font shape nor font size of the label is set to a default
278 value; on the other hand, the rest of the text will have default font
284 macro is the macro used for the explanations you are just reading.
292 These macros are mutual aliases.
293 Any of them causes a line break at the current position, followed by a
294 vertical space downwards by the amount specified by the
297 The font size and shape are reset to the default value (10pt resp. Roman).
298 Finally, the current left margin and the indentation are restored.
301 .BI ".IP [" designator "] [" nnn ]
302 Set up an indented paragraph, using
304 as a tag to mark its beginning.
305 The indentation is set to
307 if that argument is supplied (the default unit is `n' if omitted), otherwise
308 it is set to the previous indentation value specified with
313 (or to the default value if none of them have been used yet).
314 Font size and face of the paragraph (but not the designator) are reset to
318 To start an indented paragraph with a particular indentation but without a
319 designator, use `""' (two doublequotes) as the second argument.
322 For example, the following paragraphs were all set up with bullets as the
323 designator, using `.IP\ \\(bu\ 4'.
324 The whole block has been enclosed with `.RS' and `.RE' to set the left
325 margin temporarily to the current indentation value.
330 is one of the three macros used in the
332 package to format lists.
336 This macro produces a paragraph with a left hanging indentation.
340 This macro produces an unindented label followed by an indented paragraph.
345 Set up a paragraph with hanging left indentation.
346 The indentation is set to
348 if that argument is supplied (the default unit is `n' if omitted), otherwise
349 it is set to the previous indentation value specified with
354 (or to the default value if none of them have been used yet).
355 Font size and face are reset to its default values.
356 The following paragraph illustrates the effect of this macro with hanging
357 indentation set to\ 4 (enclosed by `.RS' and `.RE' to set the left margin temporarily to
358 the current indentation):
362 This is a paragraph following an invocation of the
365 As you can see, it produces a paragraph where all lines but the first are
371 This macro moves the left margin to the right by the value
373 if specified (default unit is `n'); otherwise it is set to the previous
374 indentation value specified with
379 (or to the default value if none of them have been used yet).
380 The indentation value is then set to the default.
389 This macro moves the left margin back to level
391 restoring the previous left margin.
392 If no argument is given, it moves one level back.
393 The first level (i.e., no call to
395 yet) has number\ 1, and each call to
397 increases the level by\ 1.
400 To summarize, the following macros cause a line break with the insertion of
401 vertical space (which amount can be changed with the
417 also cause a break but no insertion of vertical space.
420 .\" -----------------------------------------------------------------
422 .SH "MACROS TO SET FONTS"
424 The standard font is Roman; the default text size is 10\ point.
428 Causes the text on the same line or the text on the next input line to
429 appear in a font that is one point size smaller than the default font.
433 Causes the text on the same line or the text on the next input line to
434 appear in boldface font, one point size smaller than the default font.
438 Causes text on the same line to appear alternately in bold face and italic.
439 The text must be on the same line as the macro call.
443 \&.BI this "word and" that
445 would cause `this' and `that' to appear in bold face, while `word and'
451 Causes text to appear alternately in italic and bold face.
452 The text must be on the same line as the macro call.
456 Causes text on the same line to appear alternately in roman and italic.
457 The text must be on the same line as the macro call.
461 Causes text on the same line to appear alternately in italic and roman.
462 The text must be on the same line as the macro call.
466 Causes text on the same line to appear alternately in bold face and roman.
467 The text must be on the same line as the macro call.
471 Causes text on the same line to appear alternately in roman and bold face.
472 The text must be on the same line as the macro call.
478 to appear in bold face.
479 If no text is present on the line where the macro is called the text
480 of the next input line appears in bold face.
487 If no text is present on the line where the macro is called the text
488 of the next input line appears in italic.
491 .\" -----------------------------------------------------------------
495 The default indentation is 7.2n in troff mode and 7n in nroff mode except for
497 which ignores indentation.
501 Set tabs every 0.5 inches.
502 Since this macro is always called during a
504 request, it makes sense to call it only if the tab positions have been
509 Adjust the empty space before a new paragraph or section.
510 The optional argument gives the amount of space (default unit is `v');
511 without parameter, the value is reset to its default value (1\ line in
512 nroff mode, 0.4v\ otherwise).
513 This affects the macros
527 .BI ".AT [" system " [" release ]]
528 Alter the footer for use with AT&T manpages.
529 This command exists only for compatibility; don't use it.
530 See the groff info manual for more.
533 .BI ".UC [" version ]
534 Alter the footer for use with BSD manpages.
535 This command exists only for compatibility; don't use it.
536 See the groff info manual for more.
540 Print the header string.
541 Redefine this macro to get control of the header.
545 Print the footer string.
546 Redefine this macro to get control of the footer.
549 The following strings are defined:
552 Switch back to the default font size.
556 The `registered' sign.
560 The `trademark' sign.
566 Left and right quote.
567 This is equal to `\e(lq' and `\e(rq', respectively.
571 The typeface used to print headings and subheadings.
575 If a preprocessor like
579 is needed, it has become usage to make the first line of the man page look
586 Note the single space character after the double quote.
588 consists of letters for the needed preprocessors: `e' for
594 Modern implementations of the
596 program read this first line and automatically call the right
600 .\" -----------------------------------------------------------------
607 These are wrapper files to call
611 This file checks whether the
615 package should be used.
620 macros are contained in this file.
623 Local changes and customizations should be put into this file.
626 .\" -----------------------------------------------------------------
632 macros consist of groups of
634 requests, one can, in principle, supplement the functionality of the
636 macros with individual
638 requests where necessary.
639 See the groff info pages for a complete reference of all requests.
642 .BR @g@tbl (@MAN1EXT@),
643 .BR @g@eqn (@MAN1EXT@),
644 .BR @g@refer (@MAN1EXT@),
648 .\" -----------------------------------------------------------------
652 This manual page was originally written for the Debian GNU/Linux system by
653 Susan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg
654 <wl@gnu.org>, and is now part of the GNU troff distribution.