/[groff]/groff/tmac/groff_man.man
ViewVC logotype

Diff of /groff/tmac/groff_man.man

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.22 by wlemb, Sat Jul 3 12:47:00 2004 UTC revision 1.23 by bwarken, Sat Aug 27 18:41:41 2005 UTC
# Line 1  Line 1 
1  .ig  .ig
2  Copyright (C) 1999-2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.  Copyright (C) 1999-2000, 2001, 2002, 2003, 2004
3    Free Software Foundation, Inc.
4    
5  Permission is granted to make and distribute verbatim copies of  Permission is granted to make and distribute verbatim copies of this
6  this manual provided the copyright notice and this permission notice  manual provided the copyright notice and this permission notice are
7  are preserved on all copies.  preserved on all copies.
8    
9  Permission is granted to copy and distribute modified versions of this  Permission is granted to copy and distribute modified versions of this
10  manual under the conditions for verbatim copying, provided that the  manual under the conditions for verbatim copying, provided that the
# Line 63  groff_man \- groff `man' macros to suppo Line 64  groff_man \- groff `man' macros to suppo
64  .  .
65  The  The
66  .B man  .B man
67  macros used to generate man pages with  macros used to generate
68    .I \%man\~pages
69    with
70  .I groff  .I groff
71  were written by James Clark.  were written by James Clark.
72    .
73  This document provides a brief summary of the use of each macro in that  This document provides a brief summary of the use of each macro in that
74  package.  package.
75  .  .
# Line 76  package. Line 80  package.
80  .  .
81  The  The
82  .B man  .B man
83  macros understand the following command line options (which define various  macros understand the following command line options (which define
84  registers).  various registers).
85  .  .
86  .TP  .TP
87  .B \-rcR=1  .B \-rcR=1
88  This option (the default if in nroff mode) will create a single, very long  This option (the default if in nroff mode) will create a single, very
89  page instead of multiple pages.  long page instead of multiple pages.
90    .
91  Say  Say
92  .B \-rcR=0  .B \-rcR=0
93  to disable it.  to disable it.
# Line 95  pages continuously, rather than starting Line 100  pages continuously, rather than starting
100  .TP  .TP
101  .B \-rD1  .B \-rD1
102  Double-sided printing.  Double-sided printing.
103    .
104  Footers for even and odd pages are formatted differently.  Footers for even and odd pages are formatted differently.
105  .  .
106  .TP  .TP
107  .BI \-rFT= dist  .BI \-rFT= dist
108  Set distance of the footer relative to the bottom of the page if negative  Set distance of the footer relative to the bottom of the page if
109  or relative to the top if positive.  negative or relative to the top if positive.
110    .
111  The default is -0.5i.  The default is -0.5i.
112  .  .
113  .TP  .TP
# Line 130  consistent indentation. Line 137  consistent indentation.
137  .TP  .TP
138  .BI \-rLL= line-length  .BI \-rLL= line-length
139  Set line length.  Set line length.
140  If this option is not given, the line length defaults to 78n in nroff mode  .
141  and 6.5i in troff mode.  If this option is not given, the line length defaults to 78n in
142    .I nroff
143    mode and 6.5i in
144    .I troff
145    mode.
146  .  .
147  .TP  .TP
148  .BI \-rLT= title-length  .BI \-rLT= title-length
149  Set title length.  Set title length.
150  If this option is not given, the title length defaults to the line length.  .
151    If this option is not given, the title length defaults to the line
152    length.
153  .  .
154  .TP  .TP
155  .BI \-rP nnn  .BI \-rP nnn
# Line 167  number pages as Line 180  number pages as
180  .IR nnn b,  .IR nnn b,
181  .IR nnn c,  .IR nnn c,
182  etc.  etc.
183  For example, the option `\-rX2' will produce the following page numbers:  .
184  1, 2, 2a, 2b, 2c, etc.  For example, the option `\-rX2' will produce the following page
185    numbers: 1, 2, 2a, 2b, 2c, etc.
186  .  .
187  .  .
188  .\" -----------------------------------------------------------------  .\" -----------------------------------------------------------------
# Line 176  For example, the option `\-rX2' will pro Line 190  For example, the option `\-rX2' will pro
190  .SH USAGE  .SH USAGE
191  .  .
192  This section describes the available macros for manual pages.  This section describes the available macros for manual pages.
193  For further customization, put additional macros and requests into the file  .
194    For further customization, put additional macros and requests into the
195    file
196  .B man.local  .B man.local
197  which will be loaded immediately after the  which will be loaded immediately after the
198  .B man  .B man
# Line 184  package. Line 200  package.
200  .  .
201  .TP  .TP
202  .BI .TH " title section \fB[\fPextra1\fB]\fP \fB[\fPextra2\fB]\fP \fB[\fPextra3\fB]"  .BI .TH " title section \fB[\fPextra1\fB]\fP \fB[\fPextra2\fB]\fP \fB[\fPextra3\fB]"
203  Set the title of the man page to  Set the title of the
204    .I \man\~page
205    to
206  .I title  .I title
207  and the section to  and the section to
208  .IR section ,  .IR section ,
209  which must take on a value between 1 and\ 8.  which must take on a value between 1 and\ 8.
210    .
211  The value  The value
212  .I section  .I section
213  may also have a string appended, e.g. `.pm', to indicate a specific  may also have a string appended, e.g. `.pm', to indicate a specific
214  subsection of the man pages.  subsection of the
215    .IR \%man\~pages .
216  Both  Both
217  .I title  .I title
218  and  and
# Line 214  is centered in the header line. Line 234  is centered in the header line.
234  For HTML output, headers and footers are completely supressed.  For HTML output, headers and footers are completely supressed.
235  .  .
236  .IP  .IP
237  Additionally, this macro starts a new page; the new line number is\ 1 again  Additionally, this macro starts a new page; the new line number is\ 1
238  (except if the `-rC1' option is given on the command line) -- this feature  again (except if the `-rC1' option is given on the command line) --
239  is intended only for formatting multiple man pages; a single man page should  this feature is intended only for formatting multiple
240  contain exactly one  .IR \%man\~pages ;
241    a single
242    .I \%man\~page
243    should contain exactly one
244  .B TH  .B TH
245  macro at the beginning of the file.  macro at the beginning of the file.
246  .  .
247  .TP  .TP
248  .BI ".SH [" "text for a heading" ]  .BI ".SH [" "text for a heading" ]
249  Set up an unnumbered section heading sticking out to the left.  Set up an unnumbered section heading sticking out to the left.
250    .
251  Prints out all the text following  Prints out all the text following
252  .B SH  .B SH
253  up to the end of the line (or the text in the next input line if there is  up to the end of the line (or the text in the next input line if there
254  no argument to  is no argument to
255  .BR SH )  .BR SH )
256  in bold face  in bold face
257  (or the font specified by the string  (or the font specified by the string
258  .BR HF ),  .BR HF ),
259  one size larger than the base document size.  one size larger than the base document size.
260  Additionally, the left margin and the indentation for the following text  .
261  is reset to the default values.  Additionally, the left margin and the indentation for the following
262    text is reset to the default values.
263  .  .
264  .TP  .TP
265  .BI ".SS [" "text for a heading" ]  .BI ".SS [" "text for a heading" ]
266  Set up a secondary, unnumbered section heading.  Set up a secondary, unnumbered section heading.
267    .
268  Prints out all the text following  Prints out all the text following
269  .B SS  .B SS
270  up to the end of the line (or the text in the next input line if there is  up to the end of the line (or the text in the next input line if there
271  no argument to  is no argument to
272  .BR SS )  .BR SS )
273  in bold face  in bold face
274  (or the font specified by the string  (or the font specified by the string
275  .BR HF ),  .BR HF ),
276  at the same size as the base document size.  at the same size as the base document size.
277  Additionally, the left margin and the indentation for the following text  .
278  is reset to the default values.  Additionally, the left margin and the indentation for the following
279    text is reset to the default values.
280  .  .
281  .TP  .TP
282  .BI ".TP [" nnn ]  .BI ".TP [" nnn ]
283  Set up an indented paragraph with label.  Set up an indented paragraph with label.
284    .
285  The indentation is set to  The indentation is set to
286  .I nnn  .I nnn
287  if that argument is supplied (the default unit is `n' if omitted), otherwise  if that argument is supplied (the default unit is `n' if omitted),
288  it is set to the previous indentation value specified with  otherwise it is set to the previous indentation value specified with
289  .BR TP ,  .BR TP ,
290  .BR IP ,  .BR IP ,
291  or  or
# Line 265  or Line 293  or
293  (or to the default value if none of them have been used yet).  (or to the default value if none of them have been used yet).
294  .  .
295  .IP  .IP
296  The first input line of text following this macro is interpreted as a string  The first input line of text following this macro is interpreted as a
297  to be printed flush-left, as it is appropriate for a label.  string to be printed flush-left, as it is appropriate for a label.
298  It is not interpreted as part of a paragraph, so there is no attempt to fill  .
299  the first line with text from the following input lines.  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.
301    .
302  Nevertheless, if the label is not as wide as the indentation the  Nevertheless, if the label is not as wide as the indentation the
303  paragraph starts at the same line (but indented), continuing on the  paragraph starts at the same line (but indented), continuing on the
304  following lines.  following lines.
305    .
306  If the label is wider than the indentation the descriptive part of the  If the label is wider than the indentation the descriptive part of the
307  paragraph begins on the line following the label, entirely indented.  paragraph begins on the line following the label, entirely indented.
308  Note that neither font shape nor font size of the label is set to a default  .
309  value; on the other hand, the rest of the text will have default font  Note that neither font shape nor font size of the label is set to a
310  settings.  default value; on the other hand, the rest of the text will have
311    default font settings.
312  .  .
313  .IP  .IP
314  The  The
# Line 290  macro is the macro used for the explanat Line 322  macro is the macro used for the explanat
322  .TQ  .TQ
323  .B .P  .B .P
324  These macros are mutual aliases.  These macros are mutual aliases.
325    .
326  Any of them causes a line break at the current position, followed by a  Any of them causes a line break at the current position, followed by a
327  vertical space downwards by the amount specified by the  vertical space downwards by the amount specified by the
328  .B PD  .B PD
329  macro.  macro.
330  The font size and shape are reset to the default value (10pt resp. Roman).  .
331    The font size and shape are reset to the default value (10pt
332    resp. Roman).
333    .
334  Finally, the current left margin and the indentation are restored.  Finally, the current left margin and the indentation are restored.
335  .  .
336  .TP  .TP
# Line 302  Finally, the current left margin and the Line 338  Finally, the current left margin and the
338  Set up an indented paragraph, using  Set up an indented paragraph, using
339  .I designator  .I designator
340  as a tag to mark its beginning.  as a tag to mark its beginning.
341    .
342  The indentation is set to  The indentation is set to
343  .I nnn  .I nnn
344  if that argument is supplied (the default unit is `n' if omitted), otherwise  if that argument is supplied (the default unit is `n' if omitted),
345  it is set to the previous indentation value specified with  otherwise it is set to the previous indentation value specified with
346  .BR TP ,  .BR TP ,
347  .BR IP ,  .BR IP ,
348  or  or
349  .B HP  .B HP
350  (or to the default value if none of them have been used yet).  (or to the default value if none of them have been used yet).
351  Font size and face of the paragraph (but not the designator) are reset to  .
352  its default values.  Font size and face of the paragraph (but not the designator) are reset
353    to its default values.
354  .  .
355  .IP  .IP
356  To start an indented paragraph with a particular indentation but without a  To start an indented paragraph with a particular indentation but
357  designator, use `""' (two doublequotes) as the second argument.  without a designator, use `""' (two doublequotes) as the second
358    argument.
359  .  .
360  .IP  .IP
361  For example, the following paragraphs were all set up with bullets as the  For example, the following paragraphs were all set up with bullets as
362  designator, using `.IP\ \\(bu\ 4'.  the designator, using `.IP\ \\(bu\ 4'.
363    .
364  The whole block has been enclosed with `.RS' and `.RE' to set the left  The whole block has been enclosed with `.RS' and `.RE' to set the left
365  margin temporarily to the current indentation value.  margin temporarily to the current indentation value.
366  .  .
# Line 333  package to format lists. Line 373  package to format lists.
373  .IP \(bu 4  .IP \(bu 4
374  .B HP  .B HP
375  is another.  is another.
376    .
377  This macro produces a paragraph with a left hanging indentation.  This macro produces a paragraph with a left hanging indentation.
378  .IP \(bu 4  .IP \(bu 4
379  .B TP  .B TP
380  is another.  is another.
381  This macro produces an unindented label followed by an indented paragraph.  .
382    This macro produces an unindented label followed by an indented
383    paragraph.
384  .RE  .RE
385  .  .
386  .TP  .TP
387  .BI ".HP [" nnn ]  .BI ".HP [" nnn ]
388  Set up a paragraph with hanging left indentation.  Set up a paragraph with hanging left indentation.
389    .
390  The indentation is set to  The indentation is set to
391  .I nnn  .I nnn
392  if that argument is supplied (the default unit is `n' if omitted), otherwise  if that argument is supplied (the default unit is `n' if omitted),
393  it is set to the previous indentation value specified with  otherwise it is set to the previous indentation value specified with
394  .BR TP ,  .BR TP ,
395  .BR IP ,  .BR IP ,
396  or  or
397  .B HP  .B HP
398  (or to the default value if none of them have been used yet).  (or to the default value if none of them have been used yet).
399    .
400  Font size and face are reset to its default values.  Font size and face are reset to its default values.
401  The following paragraph illustrates the effect of this macro with hanging  .
402  indentation set to\ 4 (enclosed by `.RS' and `.RE' to set the left margin temporarily to  The following paragraph illustrates the effect of this macro with
403  the current indentation):  hanging indentation set to\ 4 (enclosed by
404    .B .RS
405    and
406    .B .RE
407    to set the left margin temporarily to the current indentation):
408  .  .
409  .RS  .RS
410  .HP 4  .HP 4
411  This is a paragraph following an invocation of the  This is a paragraph following an invocation of the
412  .B HP  .B HP
413  macro.  macro.
414  As you can see, it produces a paragraph where all lines but the first are  .
415  indented.  As you can see, it produces a paragraph where all lines but the first
416    are indented.
417  .RE  .RE
418  .  .
419  .TP  .TP
420  .BI ".RS [" nnn ]  .BI ".RS [" nnn ]
421  This macro moves the left margin to the right by the value  This macro moves the left margin to the right by the value
422  .I nnn  .I nnn
423  if specified (default unit is `n'); otherwise it is set to the previous  if specified (default unit is `n'); otherwise it is set to the
424  indentation value specified with  previous indentation value specified with
425  .BR TP ,  .BR TP ,
426  .BR IP ,  .BR IP ,
427  or  or
428  .B HP  .B HP
429  (or to the default value if none of them have been used yet).  (or to the default value if none of them have been used yet).
430    .
431  The indentation value is then set to the default.  The indentation value is then set to the default.
432  .  .
433  .IP  .IP
# Line 389  macro can be nested. Line 440  macro can be nested.
440  This macro moves the left margin back to level  This macro moves the left margin back to level
441  .IR nnn ,  .IR nnn ,
442  restoring the previous left margin.  restoring the previous left margin.
443    .
444  If no argument is given, it moves one level back.  If no argument is given, it moves one level back.
445    .
446  The first level (i.e., no call to  The first level (i.e., no call to
447  .B RS  .B RS
448  yet) has number\ 1, and each call to  yet) has number\ 1, and each call to
# Line 397  yet) has number\ 1, and each call to Line 450  yet) has number\ 1, and each call to
450  increases the level by\ 1.  increases the level by\ 1.
451  .  .
452  .PP  .PP
453  To summarize, the following macros cause a line break with the insertion of  To summarize, the following macros cause a line break with the
454  vertical space (which amount can be changed with the  insertion of vertical space (which amount can be changed with the
455  .B PD  .B PD
456  macro):  macro):
457  .BR SH ,  .BR SH ,
# Line 435  appear in boldface font, one point size Line 488  appear in boldface font, one point size
488  .  .
489  .TP  .TP
490  .BI ".BI " text  .BI ".BI " text
491  Causes text on the same line to appear alternately in bold face and italic.  Causes text on the same line to appear alternately in bold face and
492    italic.
493    .
494  The text must be on the same line as the macro call.  The text must be on the same line as the macro call.
495    .
496  Thus  Thus
497  .RS  .RS
498  .IP  .IP
# Line 449  appears in italics. Line 505  appears in italics.
505  .TP  .TP
506  .BI ".IB " text  .BI ".IB " text
507  Causes text to appear alternately in italic and bold face.  Causes text to appear alternately in italic and bold face.
508    .
509  The text must be on the same line as the macro call.  The text must be on the same line as the macro call.
510  .  .
511  .TP  .TP
512  .BI ".RI " text  .BI ".RI " text
513  Causes text on the same line to appear alternately in roman and italic.  Causes text on the same line to appear alternately in roman and
514    italic.
515    .
516  The text must be on the same line as the macro call.  The text must be on the same line as the macro call.
517  .  .
518  .TP  .TP
519  .BI ".IR " text  .BI ".IR " text
520  Causes text on the same line to appear alternately in italic and roman.  Causes text on the same line to appear alternately in italic and
521    roman.
522    .
523  The text must be on the same line as the macro call.  The text must be on the same line as the macro call.
524  .  .
525  .TP  .TP
526  .BI ".BR " text  .BI ".BR " text
527  Causes text on the same line to appear alternately in bold face and roman.  Causes text on the same line to appear alternately in bold face and
528    roman.
529    .
530  The text must be on the same line as the macro call.  The text must be on the same line as the macro call.
531  .  .
532  .TP  .TP
533  .BI ".RB " text  .BI ".RB " text
534  Causes text on the same line to appear alternately in roman and bold face.  Causes text on the same line to appear alternately in roman and bold
535    face.
536    .
537  The text must be on the same line as the macro call.  The text must be on the same line as the macro call.
538  .  .
539  .TP  .TP
# Line 476  The text must be on the same line as the Line 541  The text must be on the same line as the
541  Causes  Causes
542  .I text  .I text
543  to appear in bold face.  to appear in bold face.
544    .
545  If no text is present on the line where the macro is called the text  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.  of the next input line appears in bold face.
547  .  .
# Line 484  of the next input line appears in bold f Line 550  of the next input line appears in bold f
550  Causes  Causes
551  .I text  .I text
552  to appear in italic.  to appear in italic.
553    .
554  If no text is present on the line where the macro is called the text  If no text is present on the line where the macro is called the text
555  of the next input line appears in italic.  of the next input line appears in italic.
556  .  .
# Line 492  of the next input line appears in italic Line 559  of the next input line appears in italic
559  .  .
560  .SH "MISCELLANEOUS"  .SH "MISCELLANEOUS"
561  .  .
562  The default indentation is 7.2n in troff mode and 7n in nroff mode except for  The default indentation is 7.2n in troff mode and 7n in nroff mode
563    except for
564  .B grohtml  .B grohtml
565  which ignores indentation.  which ignores indentation.
566  .  .
567  .TP  .TP
568  .B .DT  .B .DT
569  Set tabs every 0.5 inches.  Set tabs every 0.5 inches.
570    .
571  Since this macro is always called during a  Since this macro is always called during a
572  .B TH  .B TH
573  request, it makes sense to call it only if the tab positions have been  request, it makes sense to call it only if the tab positions have been
# Line 507  changed. Line 576  changed.
576  .TP  .TP
577  .BI ".PD [" nnn ]  .BI ".PD [" nnn ]
578  Adjust the empty space before a new paragraph or section.  Adjust the empty space before a new paragraph or section.
579    .
580  The optional argument gives the amount of space (default unit is `v');  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  without parameter, the value is reset to its default value (1\ line in
582  nroff mode, 0.4v\ otherwise).  nroff mode, 0.4v\ otherwise).
583    .
584  This affects the macros  This affects the macros
585  .BR SH ,  .BR SH ,
586  .BR SS ,  .BR SS ,
# Line 525  and Line 596  and
596  .  .
597  .TP  .TP
598  .BI ".AT [" system " [" release ]]  .BI ".AT [" system " [" release ]]
599  Alter the footer for use with AT&T manpages.  Alter the footer for use with \f[CR]AT&T\f[]
600    .IR \%man\~pages .
601  This command exists only for compatibility; don't use it.  This command exists only for compatibility; don't use it.
602  See the groff info manual for more.  .
603    See the
604    .I groff
605    info manual for more.
606  .  .
607  .TP  .TP
608  .BI ".UC [" version ]  .BI ".UC [" version ]
609  Alter the footer for use with BSD manpages.  Alter the footer for use with \f[CR]BSD\f[]
610    .IR \%man\~pages .
611  This command exists only for compatibility; don't use it.  This command exists only for compatibility; don't use it.
612  See the groff info manual for more.  .
613    See the
614    .I groff
615    info manual for more.
616  .  .
617  .TP  .TP
618  .B ".PT"  .B ".PT"
619  Print the header string.  Print the header string.
620    .
621  Redefine this macro to get control of the header.  Redefine this macro to get control of the header.
622  .  .
623  .TP  .TP
624  .B ".BT"  .B ".BT"
625  Print the footer string.  Print the footer string.
626    .
627  Redefine this macro to get control of the footer.  Redefine this macro to get control of the footer.
628  .  .
629  .PP  .PP
# Line 564  The `trademark' sign. Line 645  The `trademark' sign.
645  .TQ  .TQ
646  .B \e*(rq  .B \e*(rq
647  Left and right quote.  Left and right quote.
648    .
649  This is equal to `\e(lq' and `\e(rq', respectively.  This is equal to `\e(lq' and `\e(rq', respectively.
650  .  .
651  .TP  .TP
652  .B \e*(HF  .B \e*(HF
653  The typeface used to print headings and subheadings.  The typeface used to print headings and subheadings.
654    .
655  The default is `B'.  The default is `B'.
656  .  .
657  .PP  .PP
# Line 576  If a preprocessor like Line 659  If a preprocessor like
659  .B @g@tbl  .B @g@tbl
660  or  or
661  .B @g@eqn  .B @g@eqn
662  is needed, it has become usage to make the first line of the man page look  is needed, it has become usage to make the first line of the
663  like this:  .I \%man\~page
664    look like this:
665  .PP  .PP
666  .RS  .RS
667  .BI .\e"\  word  .BI .\e"\  word
# Line 636  requests, one can, in principle, supplem Line 720  requests, one can, in principle, supplem
720  macros with individual  macros with individual
721  .I groff  .I groff
722  requests where necessary.  requests where necessary.
723  See the groff info pages for a complete reference of all requests.  .
724    See the
725    .I groff
726    info pages for a complete reference of all requests.
727  .  .
728  .PP  .PP
729  .BR @g@tbl (@MAN1EXT@),  .BR @g@tbl (@MAN1EXT@),
730  .BR @g@eqn (@MAN1EXT@),  .BR @g@eqn (@MAN1EXT@),
731  .BR @g@refer (@MAN1EXT@),  .BR @g@refer (@MAN1EXT@),
732  .BR man (1)  .BR man (1),
733    .BR man (7),
734  .  .
735  .  .
736  .\" -----------------------------------------------------------------  .\" -----------------------------------------------------------------
737  .  .
738  .SH AUTHOR  .SH AUTHOR
739  .  .
740  This manual page was originally written for the Debian GNU/Linux system by  This manual page was originally written for the Debian GNU/Linux
741  Susan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg  system by Susan G. Kleinmann <sgk@debian.org>, corrected and updated
742  <wl@gnu.org>, and is now part of the GNU troff distribution.  by Werner Lemberg <wl@gnu.org>, and is now part of the GNU troff
743    distribution.
744  .  .
745  .\" Local Variables:  .\" Local Variables:
746  .\" mode: nroff  .\" mode: nroff

Legend:
Removed from v.1.22  
changed lines
  Added in v.1.23

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26