| blob | 985014ebedecf812acf45ab60c093dfc47f89dc4 |
1 .ig
2 Copyright (C) 1999-2000, 2001, 2002, 2003, 2004, 2005
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
18 the original English.
19 ..
20 .
21 .de TQ
22 . br
23 . ns
24 . TP \\$1
25 ..
26 .
27 .
28 .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
29 .
30 .
31 .\" -----------------------------------------------------------------
32 .
33 .SH NAME
34 .
35 groff_man \- groff `man' macros to support generation of man pages
36 .
37 .
38 .\" -----------------------------------------------------------------
39 .
40 .SH SYNOPSIS
41 .
42 .B groff
43 .B \-man
44 [
45 .IR options .\|.\|.\&
46 ]
47 [
48 .IR files .\|.\|.\&
49 ]
50 .br
51 .B groff
52 .B \-m\ man
53 [
54 .IR options .\|.\|.\&
55 ]
56 [
57 .IR files .\|.\|.\&
58 ]
59 .
60 .
61 .\" -----------------------------------------------------------------
62 .
63 .SH DESCRIPTION
64 .
65 The
66 .B man
67 macros used to generate
68 .I \%man\~pages
69 with
70 .I groff
71 were written by James Clark.
72 .
73 This document provides a brief summary of the use of each macro in that
74 package.
75 .
76 .
77 .\" -----------------------------------------------------------------
78 .
79 .SH OPTIONS
80 .
81 The
82 .B man
83 macros understand the following command line options (which define
84 various registers).
85 .
86 .TP
87 .B \-rcR=1
88 This option (the default if in nroff mode) will create a single, very
89 long page instead of multiple pages.
90 .
91 Say
92 .B \-rcR=0
93 to disable it.
94 .
95 .TP
96 .B \-rC1
97 If more than one manual page is given on the command line, number the
98 pages continuously, rather than starting each at\ 1.
99 .
100 .TP
101 .B \-rD1
102 Double-sided printing.
103 .
104 Footers for even and odd pages are formatted differently.
105 .
106 .TP
107 .BI \-rFT= dist
108 Set distance of the footer relative to the bottom of the page if
109 negative or relative to the top if positive.
110 .
111 The default is -0.5i.
112 .
113 .TP
114 .BI \-rHY= flags
115 Set hyphenation flags.
116 .
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
120 of a word.
121 .
122 These values are additive; the default is\ 14.
123 .
124 .TP
125 .BI \-rIN= width
126 Set body text indentation to
127 .IR width .
128 The default is 7n for
129 .IR nroff ,
130 7.2n for
131 .IR troff .
132 For
133 .IR nroff ,
134 this value should always be an integer multiple of unit `n' to get
135 consistent indentation.
136 .
137 .TP
138 .BI \-rLL= line-length
139 Set line length.
140 .
141 If this option is not given,
142 the line length is set to respect any value set by a prior `.ll' request,
143 (which
144 .I must
145 be in effect when the `.TH' macro is invoked),
146 if this differs from the built\-in default for the formatter;
147 otherwise it defaults to 78n in
148 .I nroff
149 mode and 6.5i in
150 .I troff
151 mode.
152 .
153 .IP
154 Note that the use of a `.ll' request to initialize the line length
155 is supported for backward compatibility with some versions of the
156 .B man
157 program;
158 direct initialization of the `LL' register should
159 .I always
160 be preferred to the use of such a request.
161 In particular, note that a `.ll\ 65n' request will
162 .I not
163 preserve the normal
164 .I nroff
165 default line length,
166 (the
167 .B man
168 default initialization to 78n will prevail),
169 whereas,
170 the `-rLL=65n' option, or an equivalent `.nr\ LL\ 65n'
171 request preceding the use of the `TH' macro,
172 .I will
173 set a line length of 65n.
174 .
175 .TP
176 .BI \-rLT= title-length
177 Set title length.
178 .
179 If this option is not given, the title length defaults to the line
180 length.
181 .
182 .TP
183 .BI \-rP nnn
184 Enumeration of pages will start with
185 .I nnn
186 rather than with\ 1.
187 .
188 .TP
189 .BI \-rS xx
190 Base document font size is
191 .I xx
192 points
193 .RI ( xx
194 can be 10, 11, or\ 12) rather than 10\ points.
195 .
196 .TP
197 .BI \-rSN= width
198 Set sub-subheading indentation to
199 .IR width .
200 The default is 3n.
201 .
202 .TP
203 .BI \-rX nnn
204 After page\ \c
205 .IR nnn ,
206 number pages as
207 .IR nnn a,
208 .IR nnn b,
209 .IR nnn c,
210 etc.
211 .
212 For example, the option `\-rX2' will produce the following page
213 numbers: 1, 2, 2a, 2b, 2c, etc.
214 .
215 .
216 .\" -----------------------------------------------------------------
217 .
218 .SH USAGE
219 .
220 This section describes the available macros for manual pages.
221 .
222 For further customization, put additional macros and requests into the
223 file
224 .B man.local
225 which will be loaded immediately after the
226 .B man
227 package.
228 .
229 .TP
230 .BI .TH " title section \fB[\fPextra1\fB]\fP \fB[\fPextra2\fB]\fP \fB[\fPextra3\fB]"
231 Set the title of the
232 .I \man\~page
233 to
234 .I title
235 and the section to
236 .IR section ,
237 which must take on a value between 1 and\ 8.
238 .
239 The value
240 .I section
241 may also have a string appended, e.g. `.pm', to indicate a specific
242 subsection of the
243 .IR \%man\~pages .
244 Both
245 .I title
246 and
247 .I section
248 are positioned at the left and right in the header line (with
249 .I section
250 in parentheses immediately appended to
251 .IR title .
252 .I extra1
253 will be positioned in the middle of the footer line.
254 .I extra2
255 will be positioned at the left in the footer line (or at the left on
256 even pages and at the right on odd pages if double-sided printing is
257 active).
258 .I extra3
259 is centered in the header line.
260 .
261 .IP
262 For HTML output, headers and footers are completely supressed.
263 .
264 .IP
265 Additionally, this macro starts a new page; the new line number is\ 1
266 again (except if the `-rC1' option is given on the command line) --
267 this feature is intended only for formatting multiple
268 .IR \%man\~pages ;
269 a single
270 .I \%man\~page
271 should contain exactly one
272 .B TH
273 macro at the beginning of the file.
274 .
275 .TP
276 .BI ".SH [" "text for a heading" ]
277 Set up an unnumbered section heading sticking out to the left.
278 .
279 Prints out all the text following
280 .B SH
281 up to the end of the line (or the text in the next input line if there
282 is no argument to
283 .BR SH )
284 in bold face
285 (or the font specified by the string
286 .BR HF ),
287 one size larger than the base document size.
288 .
289 Additionally, the left margin and the indentation for the following
290 text is reset to the default values.
291 .
292 .TP
293 .BI ".SS [" "text for a heading" ]
294 Set up a secondary, unnumbered section heading.
295 .
296 Prints out all the text following
297 .B SS
298 up to the end of the line (or the text in the next input line if there
299 is no argument to
300 .BR SS )
301 in bold face
302 (or the font specified by the string
303 .BR HF ),
304 at the same size as the base document size.
305 .
306 Additionally, the left margin and the indentation for the following
307 text is reset to the default values.
308 .
309 .TP
310 .BI ".TP [" nnn ]
311 Set up an indented paragraph with label.
312 .
313 The indentation is set to
314 .I nnn
315 if that argument is supplied (the default unit is `n' if omitted),
316 otherwise it is set to the previous indentation value specified with
317 .BR TP ,
318 .BR IP ,
319 or
320 .B HP
321 (or to the default value if none of them have been used yet).
322 .
323 .IP
324 The first input line of text following this macro is interpreted as a
325 string to be printed flush-left, as it is appropriate for a label.
326 .
327 It is not interpreted as part of a paragraph, so there is no attempt
328 to fill the first line with text from the following input lines.
329 .
330 Nevertheless, if the label is not as wide as the indentation the
331 paragraph starts at the same line (but indented), continuing on the
332 following lines.
333 .
334 If the label is wider than the indentation the descriptive part of the
335 paragraph begins on the line following the label, entirely indented.
336 .
337 Note that neither font shape nor font size of the label is set to a
338 default value; on the other hand, the rest of the text will have
339 default font settings.
340 .
341 .IP
342 The
343 .B TP
344 macro is the macro used for the explanations you are just reading.
345 .
346 .TP
347 .B .LP
348 .TQ
349 .B .PP
350 .TQ
351 .B .P
352 These macros are mutual aliases.
353 .
354 Any of them causes a line break at the current position, followed by a
355 vertical space downwards by the amount specified by the
356 .B PD
357 macro.
358 .
359 The font size and shape are reset to the default value (10pt
360 resp. Roman).
361 .
362 Finally, the current left margin and the indentation are restored.
363 .
364 .TP
365 .BI ".IP [" designator "] [" nnn ]
366 Set up an indented paragraph, using
367 .I designator
368 as a tag to mark its beginning.
369 .
370 The indentation is set to
371 .I nnn
372 if that argument is supplied (the default unit is `n' if omitted),
373 otherwise it is set to the previous indentation value specified with
374 .BR TP ,
375 .BR IP ,
376 or
377 .B HP
378 (or to the default value if none of them have been used yet).
379 .
380 Font size and face of the paragraph (but not the designator) are reset
381 to its default values.
382 .
383 .IP
384 To start an indented paragraph with a particular indentation but
385 without a designator, use `""' (two doublequotes) as the second
386 argument.
387 .
388 .IP
389 For example, the following paragraphs were all set up with bullets as
390 the designator, using `.IP\ \\(bu\ 4'.
391 .
392 The whole block has been enclosed with `.RS' and `.RE' to set the left
393 margin temporarily to the current indentation value.
394 .
395 .RS
396 .IP \(bu 4
397 .B IP
398 is one of the three macros used in the
399 .B man
400 package to format lists.
401 .IP \(bu 4
402 .B HP
403 is another.
404 .
405 This macro produces a paragraph with a left hanging indentation.
406 .IP \(bu 4
407 .B TP
408 is another.
409 .
410 This macro produces an unindented label followed by an indented
411 paragraph.
412 .RE
413 .
414 .TP
415 .BI ".HP [" nnn ]
416 Set up a paragraph with hanging left indentation.
417 .
418 The indentation is set to
419 .I nnn
420 if that argument is supplied (the default unit is `n' if omitted),
421 otherwise it is set to the previous indentation value specified with
422 .BR TP ,
423 .BR IP ,
424 or
425 .B HP
426 (or to the default value if none of them have been used yet).
427 .
428 Font size and face are reset to its default values.
429 .
430 The following paragraph illustrates the effect of this macro with
431 hanging indentation set to\ 4 (enclosed by
432 .B .RS
433 and
434 .B .RE
435 to set the left margin temporarily to the current indentation):
436 .
437 .RS
438 .HP 4
439 This is a paragraph following an invocation of the
440 .B HP
441 macro.
442 .
443 As you can see, it produces a paragraph where all lines but the first
444 are indented.
445 .RE
446 .
447 .TP
448 .BI ".RS [" nnn ]
449 This macro moves the left margin to the right by the value
450 .I nnn
451 if specified (default unit is `n'); otherwise it is set to the
452 previous indentation value specified with
453 .BR TP ,
454 .BR IP ,
455 or
456 .B HP
457 (or to the default value if none of them have been used yet).
458 .
459 The indentation value is then set to the default.
460 .
461 .IP
462 Calls to the
463 .B RS
464 macro can be nested.
465 .
466 .TP
467 .BI ".RE [" nnn ]
468 This macro moves the left margin back to level
469 .IR nnn ,
470 restoring the previous left margin.
471 .
472 If no argument is given, it moves one level back.
473 .
474 The first level (i.e., no call to
475 .B RS
476 yet) has number\ 1, and each call to
477 .B RS
478 increases the level by\ 1.
479 .
480 .PP
481 To summarize, the following macros cause a line break with the
482 insertion of vertical space (which amount can be changed with the
483 .B PD
484 macro):
485 .BR SH ,
486 .BR SS ,
487 .BR TP ,
488 .B LP
489 .RB ( PP ,
490 .BR P ),
491 .BR IP ,
492 and
493 .BR HP .
494 The macros
495 .B RS
496 and
497 .B RE
498 also cause a break but no insertion of vertical space.
499 .
500 .
501 .\" -----------------------------------------------------------------
502 .
503 .SH "MACROS TO SET FONTS"
504 .
505 The standard font is Roman; the default text size is 10\ point.
506 .
507 .TP
508 .BI ".SM [" text ]
509 Causes the text on the same line or the text on the next input line to
510 appear in a font that is one point size smaller than the default font.
511 .
512 .TP
513 .BI ".SB [" text ]
514 Causes the text on the same line or the text on the next input line to
515 appear in boldface font, one point size smaller than the default font.
516 .
517 .TP
518 .BI ".BI " text
519 Causes text on the same line to appear alternately in bold face and
520 italic.
521 .
522 The text must be on the same line as the macro call.
523 .
524 Thus
525 .RS
526 .IP
527 \&.BI this "word and" that
528 .PP
529 would cause `this' and `that' to appear in bold face, while `word and'
530 appears in italics.
531 .RE
532 .
533 .TP
534 .BI ".IB " text
535 Causes text to appear alternately in italic and bold face.
536 .
537 The text must be on the same line as the macro call.
538 .
539 .TP
540 .BI ".RI " text
541 Causes text on the same line to appear alternately in roman and
542 italic.
543 .
544 The text must be on the same line as the macro call.
545 .
546 .TP
547 .BI ".IR " text
548 Causes text on the same line to appear alternately in italic and
549 roman.
550 .
551 The text must be on the same line as the macro call.
552 .
553 .TP
554 .BI ".BR " text
555 Causes text on the same line to appear alternately in bold face and
556 roman.
557 .
558 The text must be on the same line as the macro call.
559 .
560 .TP
561 .BI ".RB " text
562 Causes text on the same line to appear alternately in roman and bold
563 face.
564 .
565 The text must be on the same line as the macro call.
566 .
567 .TP
568 .BI ".B [" text ]
569 Causes
570 .I text
571 to appear in bold face.
572 .
573 If no text is present on the line where the macro is called the text
574 of the next input line appears in bold face.
575 .
576 .TP
577 .BI ".I [" text ]
578 Causes
579 .I text
580 to appear in italic.
581 .
582 If no text is present on the line where the macro is called the text
583 of the next input line appears in italic.
584 .
585 .
586 .\" -----------------------------------------------------------------
587 .
588 .SH "MISCELLANEOUS"
589 .
590 The default indentation is 7.2n in troff mode and 7n in nroff mode
591 except for
592 .B grohtml
593 which ignores indentation.
594 .
595 .TP
596 .B .DT
597 Set tabs every 0.5 inches.
598 .
599 Since this macro is always called during a
600 .B TH
601 request, it makes sense to call it only if the tab positions have been
602 changed.
603 .
604 .TP
605 .BI ".PD [" nnn ]
606 Adjust the empty space before a new paragraph or section.
607 .
608 The optional argument gives the amount of space (default unit is `v');
609 without parameter, the value is reset to its default value (1\ line in
610 nroff mode, 0.4v\ otherwise).
611 .
612 This affects the macros
613 .BR SH ,
614 .BR SS ,
615 .BR TP ,
616 .B LP
617 (resp.\&
618 .B PP
619 and
620 .BR P ),
621 .BR IP ,
622 and
623 .BR HP .
624 .
625 .TP
626 .BI ".AT [" system " [" release ]]
627 Alter the footer for use with \f[CR]AT&T\f[]
628 .IR \%man\~pages .
629 This command exists only for compatibility; don't use it.
630 .
631 See the
632 .I groff
633 info manual for more.
634 .
635 .TP
636 .BI ".UC [" version ]
637 Alter the footer for use with \f[CR]BSD\f[]
638 .IR \%man\~pages .
639 This command exists only for compatibility; don't use it.
640 .
641 See the
642 .I groff
643 info manual for more.
644 .
645 .TP
646 .B ".PT"
647 Print the header string.
648 .
649 Redefine this macro to get control of the header.
650 .
651 .TP
652 .B ".BT"
653 Print the footer string.
654 .
655 Redefine this macro to get control of the footer.
656 .
657 .PP
658 The following strings are defined:
659 .TP
660 .B \e*S
661 Switch back to the default font size.
662 .
663 .TP
664 .B \e*R
665 The `registered' sign.
666 .
667 .TP
668 .B \e*(Tm
669 The `trademark' sign.
670 .
671 .TP
672 .B \e*(lq
673 .TQ
674 .B \e*(rq
675 Left and right quote.
676 .
677 This is equal to `\e(lq' and `\e(rq', respectively.
678 .
679 .TP
680 .B \e*(HF
681 The typeface used to print headings and subheadings.
682 .
683 The default is `B'.
684 .
685 .PP
686 If a preprocessor like
687 .B @g@tbl
688 or
689 .B @g@eqn
690 is needed, it has become usage to make the first line of the
691 .I \%man\~page
692 look like this:
693 .PP
694 .RS
695 .BI .\e"\ word
696 .RE
697 .PP
698 Note the single space character after the double quote.
699 .I word
700 consists of letters for the needed preprocessors: `e' for
701 .BR @g@eqn ,
702 `r' for
703 .BR @g@refer ,
704 and `t' for
705 .BR @g@tbl .
706 Modern implementations of the
707 .B man
708 program read this first line and automatically call the right
709 preprocessor(s).
710 .
711 .
712 .\" -----------------------------------------------------------------
713 .
714 .SH FILES
715 .TP
716 .B man.tmac
717 .TQ
718 .B an.tmac
719 These are wrapper files to call
720 .BR andoc.tmac .
721 .TP
722 .B andoc.tmac
723 This file checks whether the
724 .B man
725 macros or the
726 .B mdoc
727 package should be used.
728 .TP
729 .B an-old.tmac
730 All
731 .B man
732 macros are contained in this file.
733 .TP
734 .B man.local
735 Local changes and customizations should be put into this file.
736 .
737 .
738 .\" -----------------------------------------------------------------
739 .
740 .SH "SEE ALSO"
741 .
742 Since the
743 .B man
744 macros consist of groups of
745 .I groff
746 requests, one can, in principle, supplement the functionality of the
747 .B man
748 macros with individual
749 .I groff
750 requests where necessary.
751 .
752 See the
753 .I groff
754 info pages for a complete reference of all requests.
755 .
756 .PP
757 .BR @g@tbl (@MAN1EXT@),
758 .BR @g@eqn (@MAN1EXT@),
759 .BR @g@refer (@MAN1EXT@),
760 .BR man (1),
761 .BR man (7),
762 .
763 .
764 .\" -----------------------------------------------------------------
765 .
766 .SH AUTHOR
767 .
768 This manual page was originally written for the Debian GNU/Linux
769 system by Susan G. Kleinmann <sgk@debian.org>, corrected and updated
770 by Werner Lemberg <wl@gnu.org>, and is now part of the GNU troff
771 distribution.
772 .
773 .\" Local Variables:
774 .\" mode: nroff
775 .\" End: