2 Copyright (C) 1999-2000, 2001, 2002, 2003, 2004
3 Free Software Foundation, Inc.
5 Permission is granted to make and distribute verbatim copies of this
6 manual provided the copyright notice and this permission notice are
7 preserved on all copies.
9 Permission is granted to copy and distribute modified versions of this
10 manual under the conditions for verbatim copying, provided that the
11 entire resulting derived work is distributed under the terms of a
12 permission notice identical to this one.
14 Permission is granted to copy and distribute translations of this
15 manual into another language, under the above conditions for modified
16 versions, except that this permission notice may be included in
17 translations approved by the Free Software Foundation instead of in
28 .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
31 .\" -----------------------------------------------------------------
35 groff_man \- groff `man' macros to support generation of man pages
38 .\" -----------------------------------------------------------------
61 .\" -----------------------------------------------------------------
67 macros used to generate
71 were written by James Clark.
73 This document provides a brief summary of the use of each macro in that
77 .\" -----------------------------------------------------------------
83 macros understand the following command line options (which define
88 This option (the default if in nroff mode) will create a single, very
89 long page instead of multiple pages.
97 If more than one manual page is given on the command line, number the
98 pages continuously, rather than starting each at\ 1.
102 Double-sided printing.
104 Footers for even and odd pages are formatted differently.
108 Set distance of the footer relative to the bottom of the page if
109 negative or relative to the top if positive.
111 The default is -0.5i.
115 Set hyphenation flags.
117 Possible values are 1\ to hyphenate without restrictions, 2\ to not
118 hyphenate the last word on a page, 4\ to not hyphenate the last two
119 characters of a word, and 8\ to not hyphenate the first two characters
122 These values are additive; the default is\ 14.
126 Set body text indentation to
128 The default is 7n for
134 this value should always be an integer multiple of unit `n' to get
135 consistent indentation.
138 .BI \-rLL= line-length
141 If this option is not given, the line length defaults to 78n in
148 .BI \-rLT= title-length
151 If this option is not given, the title length defaults to the line
156 Enumeration of pages will start with
162 Base document font size is
166 can be 10, 11, or\ 12) rather than 10\ points.
170 Set sub-subheading indentation to
184 For example, the option `\-rX2' will produce the following page
185 numbers: 1, 2, 2a, 2b, 2c, etc.
188 .\" -----------------------------------------------------------------
192 This section describes the available macros for manual pages.
194 For further customization, put additional macros and requests into the
197 which will be loaded immediately after the
202 .BI .TH " title section \fB[\fPextra1\fB]\fP \fB[\fPextra2\fB]\fP \fB[\fPextra3\fB]"
209 which must take on a value between 1 and\ 8.
213 may also have a string appended, e.g. `.pm', to indicate a specific
220 are positioned at the left and right in the header line (with
222 in parentheses immediately appended to
225 will be positioned in the middle of the footer line.
227 will be positioned at the left in the footer line (or at the left on
228 even pages and at the right on odd pages if double-sided printing is
231 is centered in the header line.
234 For HTML output, headers and footers are completely supressed.
237 Additionally, this macro starts a new page; the new line number is\ 1
238 again (except if the `-rC1' option is given on the command line) --
239 this feature is intended only for formatting multiple
243 should contain exactly one
245 macro at the beginning of the file.
248 .BI ".SH [" "text for a heading" ]
249 Set up an unnumbered section heading sticking out to the left.
251 Prints out all the text following
253 up to the end of the line (or the text in the next input line if there
257 (or the font specified by the string
259 one size larger than the base document size.
261 Additionally, the left margin and the indentation for the following
262 text is reset to the default values.
265 .BI ".SS [" "text for a heading" ]
266 Set up a secondary, unnumbered section heading.
268 Prints out all the text following
270 up to the end of the line (or the text in the next input line if there
274 (or the font specified by the string
276 at the same size as the base document size.
278 Additionally, the left margin and the indentation for the following
279 text is reset to the default values.
283 Set up an indented paragraph with label.
285 The indentation is set to
287 if that argument is supplied (the default unit is `n' if omitted),
288 otherwise it is set to the previous indentation value specified with
293 (or to the default value if none of them have been used yet).
296 The first input line of text following this macro is interpreted as a
297 string to be printed flush-left, as it is appropriate for a label.
299 It is not interpreted as part of a paragraph, so there is no attempt
300 to fill the first line with text from the following input lines.
302 Nevertheless, if the label is not as wide as the indentation the
303 paragraph starts at the same line (but indented), continuing on the
306 If the label is wider than the indentation the descriptive part of the
307 paragraph begins on the line following the label, entirely indented.
309 Note that neither font shape nor font size of the label is set to a
310 default value; on the other hand, the rest of the text will have
311 default font settings.
316 macro is the macro used for the explanations you are just reading.
324 These macros are mutual aliases.
326 Any of them causes a line break at the current position, followed by a
327 vertical space downwards by the amount specified by the
331 The font size and shape are reset to the default value (10pt
334 Finally, the current left margin and the indentation are restored.
337 .BI ".IP [" designator "] [" nnn ]
338 Set up an indented paragraph, using
340 as a tag to mark its beginning.
342 The indentation is set to
344 if that argument is supplied (the default unit is `n' if omitted),
345 otherwise it is set to the previous indentation value specified with
350 (or to the default value if none of them have been used yet).
352 Font size and face of the paragraph (but not the designator) are reset
353 to its default values.
356 To start an indented paragraph with a particular indentation but
357 without a designator, use `""' (two doublequotes) as the second
361 For example, the following paragraphs were all set up with bullets as
362 the designator, using `.IP\ \\(bu\ 4'.
364 The whole block has been enclosed with `.RS' and `.RE' to set the left
365 margin temporarily to the current indentation value.
370 is one of the three macros used in the
372 package to format lists.
377 This macro produces a paragraph with a left hanging indentation.
382 This macro produces an unindented label followed by an indented
388 Set up a paragraph with hanging left indentation.
390 The indentation is set to
392 if that argument is supplied (the default unit is `n' if omitted),
393 otherwise it is set to the previous indentation value specified with
398 (or to the default value if none of them have been used yet).
400 Font size and face are reset to its default values.
402 The following paragraph illustrates the effect of this macro with
403 hanging indentation set to\ 4 (enclosed by
407 to set the left margin temporarily to the current indentation):
411 This is a paragraph following an invocation of the
415 As you can see, it produces a paragraph where all lines but the first
421 This macro moves the left margin to the right by the value
423 if specified (default unit is `n'); otherwise it is set to the
424 previous indentation value specified with
429 (or to the default value if none of them have been used yet).
431 The indentation value is then set to the default.
440 This macro moves the left margin back to level
442 restoring the previous left margin.
444 If no argument is given, it moves one level back.
446 The first level (i.e., no call to
448 yet) has number\ 1, and each call to
450 increases the level by\ 1.
453 To summarize, the following macros cause a line break with the
454 insertion of vertical space (which amount can be changed with the
470 also cause a break but no insertion of vertical space.
473 .\" -----------------------------------------------------------------
475 .SH "MACROS TO SET FONTS"
477 The standard font is Roman; the default text size is 10\ point.
481 Causes the text on the same line or the text on the next input line to
482 appear in a font that is one point size smaller than the default font.
486 Causes the text on the same line or the text on the next input line to
487 appear in boldface font, one point size smaller than the default font.
491 Causes text on the same line to appear alternately in bold face and
494 The text must be on the same line as the macro call.
499 \&.BI this "word and" that
501 would cause `this' and `that' to appear in bold face, while `word and'
507 Causes text to appear alternately in italic and bold face.
509 The text must be on the same line as the macro call.
513 Causes text on the same line to appear alternately in roman and
516 The text must be on the same line as the macro call.
520 Causes text on the same line to appear alternately in italic and
523 The text must be on the same line as the macro call.
527 Causes text on the same line to appear alternately in bold face and
530 The text must be on the same line as the macro call.
534 Causes text on the same line to appear alternately in roman and bold
537 The text must be on the same line as the macro call.
543 to appear in bold face.
545 If no text is present on the line where the macro is called the text
546 of the next input line appears in bold face.
554 If no text is present on the line where the macro is called the text
555 of the next input line appears in italic.
558 .\" -----------------------------------------------------------------
562 The default indentation is 7.2n in troff mode and 7n in nroff mode
565 which ignores indentation.
569 Set tabs every 0.5 inches.
571 Since this macro is always called during a
573 request, it makes sense to call it only if the tab positions have been
578 Adjust the empty space before a new paragraph or section.
580 The optional argument gives the amount of space (default unit is `v');
581 without parameter, the value is reset to its default value (1\ line in
582 nroff mode, 0.4v\ otherwise).
584 This affects the macros
598 .BI ".AT [" system " [" release ]]
599 Alter the footer for use with \f[CR]AT&T\f[]
601 This command exists only for compatibility; don't use it.
605 info manual for more.
608 .BI ".UC [" version ]
609 Alter the footer for use with \f[CR]BSD\f[]
611 This command exists only for compatibility; don't use it.
615 info manual for more.
619 Print the header string.
621 Redefine this macro to get control of the header.
625 Print the footer string.
627 Redefine this macro to get control of the footer.
630 The following strings are defined:
633 Switch back to the default font size.
637 The `registered' sign.
641 The `trademark' sign.
647 Left and right quote.
649 This is equal to `\e(lq' and `\e(rq', respectively.
653 The typeface used to print headings and subheadings.
658 If a preprocessor like
662 is needed, it has become usage to make the first line of the
670 Note the single space character after the double quote.
672 consists of letters for the needed preprocessors: `e' for
678 Modern implementations of the
680 program read this first line and automatically call the right
684 .\" -----------------------------------------------------------------
691 These are wrapper files to call
695 This file checks whether the
699 package should be used.
704 macros are contained in this file.
707 Local changes and customizations should be put into this file.
710 .\" -----------------------------------------------------------------
716 macros consist of groups of
718 requests, one can, in principle, supplement the functionality of the
720 macros with individual
722 requests where necessary.
726 info pages for a complete reference of all requests.
729 .BR @g@tbl (@MAN1EXT@),
730 .BR @g@eqn (@MAN1EXT@),
731 .BR @g@refer (@MAN1EXT@),
736 .\" -----------------------------------------------------------------
740 This manual page was originally written for the Debian GNU/Linux
741 system by Susan G. Kleinmann <sgk@debian.org>, corrected and updated
742 by Werner Lemberg <wl@gnu.org>, and is now part of the GNU troff