2 Copyright (C) 1999-2000, 2001, 2002, 2003, 2004, 2005, 2007, 2008, 2009
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
22 .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
25 .\" ----------------------------------------------------------------
29 groff_man \- groff `man' macros to support generation of man pages
32 .\" -----------------------------------------------------------------
50 .\" -----------------------------------------------------------------
56 macros used to generate
60 were written by James Clark.
62 This document provides a brief summary of the use of each macro in that
66 .\" -----------------------------------------------------------------
72 macros understand the following command line options (which define
77 This option (the default if in nroff mode) creates a single, very
78 long page instead of multiple pages.
86 If more than one manual page is given on the command line, number the
87 pages continuously, rather than starting each at\~1.
91 Double-sided printing.
93 Footers for even and odd pages are formatted differently.
97 Set distance of the footer relative to the bottom of the page if
98 negative or relative to the top if positive.
100 The default is -0.5i.
104 Set hyphenation flags.
106 Possible values are 1\~to hyphenate without restrictions, 2\~to not
107 hyphenate the last word on a page, 4\~to not hyphenate the last two
108 characters of a word, and 8\~to not hyphenate the first two characters
111 These values are additive; the default is\~14.
115 Set body text indentation to
117 The default is 7n for
123 this value should always be an integer multiple of unit `n' to get
124 consistent indentation.
127 .BI \-rLL= line-length
130 If this option is not given,
131 the line length is set to respect any value set by a prior `.ll' request,
134 be in effect when the `.TH' macro is invoked),
135 if this differs from the built\-in default for the formatter;
136 otherwise it defaults to 78n in
143 Note that the use of a `.ll' request to initialize the line length
144 is supported for backward compatibility with some versions of the
147 direct initialization of the `LL' register should
149 be preferred to the use of such a request.
150 In particular, note that a `.ll\ 65n' request does
157 default initialization to 78n prevails),
159 the `-rLL=65n' option, or an equivalent `.nr\ LL\ 65n'
160 request preceding the use of the `TH' macro,
162 set a line length of 65n.
165 .BI \-rLT= title-length
168 If this option is not given, the title length defaults to the line
173 Enumeration of pages start with
179 Base document font size is
183 can be 10, 11, or\~12) rather than 10\~points.
187 Set sub-subheading indentation to
201 For example, the option `\-rX2' produces the following page
202 numbers: 1, 2, 2a, 2b, 2c, etc.
205 .\" -----------------------------------------------------------------
209 This section describes the available macros for manual pages.
211 For further customization, put additional macros and requests into the
214 which is loaded immediately after the
219 .BI .TH " title section \fR[\fPextra1\fR]\fP \fR[\fPextra2\fR]\fP \fR[\fPextra3\fR]"
226 which must take on a value between 1 and\~8.
230 may also have a string appended, e.g. `.pm', to indicate a specific
237 are positioned at the left and right in the header line (with
239 in parentheses immediately appended to
242 is positioned in the middle of the footer line.
244 is positioned at the left in the footer line (or at the left on
245 even pages and at the right on odd pages if double-sided printing is
248 is centered in the header line.
251 For HTML output, headers and footers are completely suppressed.
254 Additionally, this macro starts a new page; the new line number is\~1
255 again (except if the `-rC1' option is given on the command line) --
256 this feature is intended only for formatting multiple
260 should contain exactly one
262 macro at the beginning of the file.
265 .BI .SH " \fR[\fPtext for a heading\fR]\fP"
266 Set up an unnumbered section heading sticking out to the left.
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 one size larger than the base document size.
278 Additionally, the left margin and the indentation for the following
279 text is reset to the default values.
282 .BI .SS " \fR[\fPtext for a heading\fR]\fP"
283 Set up a secondary, unnumbered section heading.
285 Prints out all the text following
287 up to the end of the line (or the text in the next input line if there
291 (or the font specified by the string
293 at the same size as the base document size.
295 Additionally, the left margin and the indentation for the following
296 text is reset to the default values.
299 .BI .TP " \fR[\fPnnn\fR]\fP"
300 Set up an indented paragraph with label.
302 The indentation is set to
304 if that argument is supplied (the default unit is `n' if omitted),
305 otherwise it is set to the previous indentation value specified with
310 (or to the default value if none of them have been used yet).
313 The first input line of text following this macro is interpreted as a
314 string to be printed flush-left, as it is appropriate for a label.
316 It is not interpreted as part of a paragraph, so there is no attempt
317 to fill the first line with text from the following input lines.
319 Nevertheless, if the label is not as wide as the indentation the
320 paragraph starts at the same line (but indented), continuing on the
323 If the label is wider than the indentation the descriptive part of the
324 paragraph begins on the line following the label, entirely indented.
326 Note that neither font shape nor font size of the label is set to a
327 default value; on the other hand, the rest of the text has default
333 macro is the macro used for the explanations you are just reading.
339 macro sets up header continuation for a .TP macro.
341 With it, you can stack up any number of labels (such as in a
342 glossary, or list of commands) before beginning the indented
345 For an example, look just past the next paragraph.
348 This macro is not defined on legacy Unix systems running classic
351 To be certain your page will be portable to those systems,
352 copy its definition from the
364 These macros are mutual aliases.
366 Any of them causes a line break at the current position, followed by a
367 vertical space downwards by the amount specified by the
371 The font size and shape are reset to the default value (normally 10pt
374 Finally, the current left margin and the indentation are restored.
377 .BI .IP " \fR[\fPdesignator\fR]\fP \fR[\fPnnn\fR]\fP"
378 Set up an indented paragraph, using
380 as a tag to mark its beginning.
382 The indentation is set to
384 if that argument is supplied (the default unit is `n' if omitted),
385 otherwise it is set to the previous indentation value specified with
390 (or to the default value if none of them have been used yet).
392 Font size and face of the paragraph (but not the designator) are reset
393 to its default values.
396 To start an indented paragraph with a particular indentation but
397 without a designator, use `""' (two doublequotes) as the second
401 For example, the following paragraphs were all set up with bullets as
402 the designator, using `.IP\ \\(bu\ 4'.
404 The whole block has been enclosed with `.RS' and `.RE' to set the left
405 margin temporarily to the current indentation value.
410 is one of the three macros used in the
412 package to format lists.
418 This macro produces a paragraph with a left hanging indentation.
424 This macro produces an unindented label followed by an indented
429 .BI .HP " \fR[\fPnnn\fR]\fP"
430 Set up a paragraph with hanging left indentation.
432 The indentation is set to
434 if that argument is supplied (the default unit is `n' if omitted),
435 otherwise it is set to the previous indentation value specified with
440 (or to the default value if none of them have been used yet).
442 Font size and face are reset to its default values.
444 The following paragraph illustrates the effect of this macro with
445 hanging indentation set to\~4 (enclosed by
449 to set the left margin temporarily to the current indentation):
453 This is a paragraph following an invocation of the
457 As you can see, it produces a paragraph where all lines but the first
462 Use of this presentation-level macro is deprecated.
464 While it is universally portable to legacy Unix systems, a hanging
465 indentation cannot be expressed naturally under HTML, and many
466 HTML-based manual viewers simply interpret it as a starter for a
469 Thus, any information or distinction you tried to express with the
470 indentation may be lost.
473 .BI .RS " \fR[\fPnnn\fR]\fP"
474 This macro moves the left margin to the right by the value
476 if specified (default unit is `n'); otherwise it is set to the
477 previous indentation value specified with
482 (or to the default value if none of them have been used yet).
484 The indentation value is then set to the default.
492 .BI .RE " \fR[\fPnnn\fR]\fP"
493 This macro moves the left margin back to level
495 restoring the previous left margin.
497 If no argument is given, it moves one level back.
499 The first level (i.e., no call to
501 yet) has number\~1, and each call to
503 increases the level by\~1.
513 filling is disabled and the font is set to constant-width.
515 This is useful for formatting code, command, and
516 configuration-file examples.
520 macro restores the previous font.
523 These macros are defined on many (but not all) legacy Unix systems
524 running classic troff.
526 To be certain your page will be portable to those systems, copy
527 their definitions from the
534 To summarize, the following macros cause a line break with the
535 insertion of vertical space (which amount can be changed with the
554 also cause a break but no insertion of vertical space.
557 .\" -----------------------------------------------------------------
559 .SH "MACROS TO SET FONTS"
561 The standard font is Roman; the default text size is 10\~point.
564 .BI .SM " \fR[\fPtext\fR]\fP"
565 Causes the text on the same line or the text on the next input line to
566 appear in a font that is one point size smaller than the default font.
569 .BI .SB " \fR[\fPtext\fR]\fP"
570 Causes the text on the same line or the text on the next input line to
571 appear in boldface font, one point size smaller than the default font.
575 Causes text on the same line to appear alternately in bold face and
578 The text must be on the same line as the macro call.
584 \&.BI this "word and" that
587 would cause `this' and `that' to appear in bold face, while `word and'
593 Causes text to appear alternately in italic and bold face.
595 The text must be on the same line as the macro call.
599 Causes text on the same line to appear alternately in roman and
602 The text must be on the same line as the macro call.
606 Causes text on the same line to appear alternately in italic and
609 The text must be on the same line as the macro call.
613 Causes text on the same line to appear alternately in bold face and
616 The text must be on the same line as the macro call.
620 Causes text on the same line to appear alternately in roman and bold
623 The text must be on the same line as the macro call.
626 .BI .B " \fR[\fPtext\fR]\fP"
629 to appear in bold face.
631 If no text is present on the line where the macro is called the text
632 of the next input line appears in bold face.
635 .BI .I " \fR[\fPtext\fR]\fP"
640 If no text is present on the line where the macro is called the text
641 of the next input line appears in italic.
644 .\" -----------------------------------------------------------------
646 .SH "MACROS TO DESCRIBE HYPERLINKS AND EMAIL ADDRESSES"
648 The following macros are not defined on legacy Unix systems
649 running classic troff.
651 To be certain your page will be portable to those systems, copy
652 their definitions from the
659 Using these macros helps ensure that you get hyperlinks when your
660 manual page is rendered in a browser or other program that is
666 .BI .UE " \fR[\fPpunctuation\fR]\fP"
667 Wrap a World Wide Web hyperlink.
671 is the URL; thereafter, lines until
673 are collected and used as the link text.
677 macro is pasted to the end of the text.
679 On a device that is not a browser,
685 \&.UR http://\e:randomsite.org/\e:fubar
693 usually displays like this: \[lq]this is a link to some random
694 site <http://\:randomsite.org/\:fubar>, given as an example\[rq].
699 to insert hyphenless breakpoints is a groff extension and can
705 .BI .ME " \fR[\fPpunctuation\fR]\fP"
706 Wrap an email address.
710 is the address; text following, until
712 is a name to be associated with the address.
716 macro is pasted to the end of the link text.
718 On a device that is not a browser,
724 \&.UR fred.foonly@\e:fubar.net
732 usually displays like this: \[lq]contact Fred Foonly
733 <fred.foonly@\:fubar.net> for more information\[rq].
738 to insert hyphenless breakpoints is a groff extension and can
742 .\" -----------------------------------------------------------------
744 .SH "MACROS TO DESCRIBE COMMAND SYNOPSES"
746 The following macros are not defined on legacy Unix systems
747 running classic troff.
749 To be certain your page will be portable to those systems, copy their
757 These macros are a convenience for authors.
758 They also assist automated translation tools and help browsers in
759 recognizing command synopses and treating them differently from
766 Takes a single argument, the name of a command.
768 Text following, until closed by
770 is set with a hanging indentation with the width of
774 This produces the traditional look of a Unix command synopsis.
778 Describe an optional command argument.
780 The arguments of this macro are set surrounded by option braces
781 in the default Roman font; the first argument is printed with
782 a bold face, while the second argument is typeset as italic.
786 This macro restores normal indentation at the end of a command
790 Here is a real example:
795 \&.OP \e-abcegiklpstzCEGNRSUVXZ
817 produces the following output:
822 .OP \-abcegiklpstzCEGNRSUVXZ
844 If necessary, you might use
846 requests to control line breaking.
848 You can insert plain text as well; this looks like the traditional
849 (unornamented) syntax for a required command argument or filename.
852 .\" -----------------------------------------------------------------
856 The default indentation is 7.2n in troff mode and 7n in nroff mode
859 which ignores indentation.
863 Set tabs every 0.5\~inches.
865 Since this macro is always called during a
867 request, it makes sense to call it only if the tab positions have been
871 Use of this presentation-level macro is deprecated.
873 It translates poorly to HTML, under which exact whitespace control
874 and tabbing are not readily available.
876 Thus, information or distinctions that you use
878 to express are likely to be lost.
880 If you feel tempted to use it, you should probably be composing a
882 .BR @g@tbl (@MAN1DIR@)
886 .BI .PD " \fR[\fPnnn\fR]\fP"
887 Adjust the empty space before a new paragraph or section.
889 The optional argument gives the amount of space (default unit is `v');
890 without parameter, the value is reset to its default value (1\~line in
891 nroff mode, 0.4v\~otherwise).
893 This affects the macros
907 Use of this presentation-level macro is deprecated.
909 It translates poorly to HTML, under which exact control of
910 inter-paragraph spacing is not readily available.
912 Thus, information or distinctions that you use
914 to express are likely to be lost.
917 .BI .AT " \fR[\fPsystem \fR[\fPrelease\fR]]\fP"
918 Alter the footer for use with \f[CR]AT&T\f[]
920 This command exists only for compatibility; don't use it.
924 info manual for more.
927 .BI .UC " \fR[\fPversion\fR]\fP"
928 Alter the footer for use with \f[CR]BSD\f[]
930 This command exists only for compatibility; don't use it.
934 info manual for more.
938 Print the header string.
940 Redefine this macro to get control of the header.
944 Print the footer string.
946 Redefine this macro to get control of the footer.
949 The following strings are defined:
953 Switch back to the default font size.
957 The `registered' sign.
961 The `trademark' sign.
967 Left and right quote.
969 This is equal to `\e(lq' and `\e(rq', respectively.
973 The typeface used to print headings and subheadings.
978 If a preprocessor like
982 is needed, it has become usage to make the first line of the
992 Note the single space character after the double quote.
994 consists of letters for the needed preprocessors: `e' for
1000 Modern implementations of the
1002 program read this first line and automatically call the right
1006 .\" -----------------------------------------------------------------
1008 .SH "PORTABILITY AND TROFF REQUESTS"
1012 macros consist of groups of
1014 requests, one can, in principle, supplement the functionality of the
1016 macros with individual
1018 requests where necessary.
1022 info pages for a complete reference of all requests.
1025 Note, however, that using raw troff requests is likely to make your
1026 page render poorly on the (increasingly common) class of viewers that
1029 Troff requests make implicit assumptions about things like character
1030 and page sizes that may break in an HTML environment; also, many of
1031 these viewers don't interpret the full troff vocabulary, a problem
1032 which can lead to portions of your text being silently dropped.
1035 For portability to modern viewers, it is best to write your page
1036 entirely in the requests described on this page.
1038 Further, it is best to completely avoid those we have described as
1039 `presentation-level'
1046 The macros we have described as extensions
1048 .BR .SY / .OP / .YS ,
1052 should be used with caution, as they may not yet be built in to
1053 some viewer that is important to your audience.
1055 If in doubt, copy the implementation onto your page.
1058 .\" -----------------------------------------------------------------
1066 These are wrapper files to call
1071 Use this file in case you don't know whether the
1075 package should be used.
1076 Multiple man pages (in either format) can be handled.
1082 macros are contained in this file.
1086 The extension macro definitions for
1095 are contained in this file.
1097 It is written in classic troff, and released for free re-use,
1098 and not copylefted; manual page authors concerned about
1099 portability to legacy Unix systems are encouraged to copy these
1100 definitions into their pages, and maintainers of troff
1101 or its workalikes are encouraged to re-use them.
1105 Local changes and customizations should be put into this file.
1108 .\" -----------------------------------------------------------------
1113 .BR @g@tbl (@MAN1EXT@),
1114 .BR @g@eqn (@MAN1EXT@),
1115 .BR @g@refer (@MAN1EXT@),
1121 .\" -----------------------------------------------------------------
1125 This manual page was originally written for the Debian GNU/Linux
1131 It was corrected and updated by
1136 The extension macros were documented (and partly designed) by
1140 he also wrote the portability advice.
1142 .\" Local Variables:
mneumann's projects / dragonfly.git / blob