4 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
6 Copyright (C) 1999 - 2008
7 Free Software Foundation, Inc.
9 Permission is granted to make and distribute verbatim copies of this
10 manual provided the copyright notice and this permission notice are
11 preserved on all copies.
13 Permission is granted to copy and distribute modified versions of this
14 manual under the conditions for verbatim copying, provided that the
15 entire resulting derived work is distributed under the terms of a
16 permission notice identical to this one.
18 Permission is granted to copy and distribute translations of this
19 manual into another language, under the above conditions for modified
20 versions, except that this permission notice may be included in
21 translations approved by the Free Software Foundation instead of in
25 .TH @U_ROFF@_MAN @MAN7EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
30 @L_ROFF@_man \- @T_ROFF@ `man' macros to support generation of man pages
41 .SY "@L_ROFF@\ \-m\ man"
53 macros used to generate
57 were written by James Clark (for GNU troff).
58 This document provides a brief summary of the use of each macro in that
66 macros understand the following command line options (which define
71 This option (the default if in nroff mode) creates a single, very
72 long page instead of multiple pages.
79 If more than one manual page is given on the command line, number the
80 pages continuously, rather than starting each at\~1.
84 Double-sided printing.
85 Footers for even and odd pages are formatted differently.
89 Set distance of the footer relative to the bottom of the page if
90 negative or relative to the top if positive.
95 Set hyphenation flags.
96 Possible values are 1\~to hyphenate without restrictions, 2\~to not
97 hyphenate the last word on a page, 4\~to not hyphenate the last two
98 characters of a word, and 8\~to not hyphenate the first two characters
100 These values are additive; the default is\~14.
104 Set body text indentation to
106 The default is 7n for
112 this value should always be an integer multiple of unit `n' to get
113 consistent indentation.
116 .BI \-rLL= line-length
118 If this option is not given,
119 the line length is set to respect any value set by a prior `.ll' request,
122 be in effect when the `.TH' macro is invoked),
123 if this differs from the built\-in default for the formatter;
124 otherwise it defaults to 78n in
131 Note that the use of a `.ll' request to initialize the line length
132 is supported for backward compatibility with some versions of the
135 direct initialization of the `LL' register should
137 be preferred to the use of such a request.
138 In particular, note that a `.ll\ 65n' request does
145 default initialization to 78n prevails),
147 the `-rLL=65n' option, or an equivalent `.nr\ LL\ 65n'
148 request preceding the use of the `TH' macro,
150 set a line length of 65n.
153 .BI \-rLT= title-length
155 If this option is not given, the title length defaults to the line
160 Enumeration of pages start with
166 Base document font size is
170 can be 10, 11, or\~12) rather than 10\~points.
174 Set sub-subheading indentation to
187 For example, the option `\-rX2' produces the following page
188 numbers: 1, 2, 2a, 2b, 2c, etc.
193 This section describes the available macros for manual pages.
194 For further customization, put additional macros and requests into the
197 which is loaded immediately after the
202 .BI .TH " title section \fR[\fPextra1\fR]\fP \fR[\fPextra2\fR]\fP \fR[\fPextra3\fR]"
209 which must take on a value between 1 and\~8.
212 may also have a string appended, e.g. `.pm', to indicate a specific
219 are positioned at the left and right in the header line (with
221 in parentheses immediately appended to
224 is positioned in the middle of the footer line.
226 is positioned at the left in the footer line (or at the left on
227 even pages and at the right on odd pages if double-sided printing is
230 is centered in the header line.
233 For HTML output, headers and footers are completely suppressed.
236 Additionally, this macro starts a new page; the new line number is\~1
237 again (except if the `-rC1' option is given on the command line) --
238 this feature is intended only for formatting multiple
242 should contain exactly one
244 macro at the beginning of the file.
247 .BI .SH " \fR[\fPtext for a heading\fR]\fP"
248 Set up an unnumbered section heading sticking out to the left.
249 Prints out all the text following
251 up to the end of the line (or the text in the next input line if there
255 (or the font specified by the string
257 one size larger than the base document size.
258 Additionally, the left margin and the indentation for the following
259 text is reset to the default values.
262 .BI .SS " \fR[\fPtext for a heading\fR]\fP"
263 Set up a secondary, unnumbered section heading.
264 Prints out all the text following
266 up to the end of the line (or the text in the next input line if there
270 (or the font specified by the string
272 at the same size as the base document size.
273 Additionally, the left margin and the indentation for the following
274 text is reset to the default values.
277 .BI .TP " \fR[\fPnnn\fR]\fP"
278 Set up an indented paragraph with label.
279 The indentation is set to
281 if that argument is supplied (the default unit is `n' if omitted),
282 otherwise it is set to the previous indentation value specified with
287 (or to the default value if none of them have been used yet).
290 The first input line of text following this macro is interpreted as a
291 string to be printed flush-left, as it is appropriate for a label.
292 It is not interpreted as part of a paragraph, so there is no attempt
293 to fill the first line with text from the following input lines.
294 Nevertheless, if the label is not as wide as the indentation the
295 paragraph starts at the same line (but indented), continuing on the
297 If the label is wider than the indentation the descriptive part of the
298 paragraph begins on the line following the label, entirely indented.
299 Note that neither font shape nor font size of the label is set to a
300 default value; on the other hand, the rest of the text has default
306 macro is the macro used for the explanations you are just reading.
312 macro sets up header continuation for a .TP macro.
313 With it, you can stack up any number of labels (such as in a
314 glossary, or list of commands) before beginning the indented
316 For an example, look just past the next paragraph.
319 This macro is not defined on legacy Unix systems running classic
321 To be certain your page will be portable to those systems,
322 copy its definition from the
334 These macros are mutual aliases.
335 Any of them causes a line break at the current position, followed by a
336 vertical space downwards by the amount specified by the
339 The font size and shape are reset to the default value (normally 10pt
341 Finally, the current left margin and the indentation are restored.
344 .BI .IP " \fR[\fPdesignator\fR]\fP \fR[\fPnnn\fR]\fP"
345 Set up an indented paragraph, using
347 as a tag to mark its beginning.
348 The indentation is set to
350 if that argument is supplied (the default unit is `n' if omitted),
351 otherwise it is set to the previous indentation value specified with
356 (or to the default value if none of them have been used yet).
357 Font size and face of the paragraph (but not the designator) are reset
358 to its default values.
361 To start an indented paragraph with a particular indentation but
362 without a designator, use `""' (two doublequotes) as the second
366 For example, the following paragraphs were all set up with bullets as
367 the designator, using `.IP\ \\(bu\ 4'.
368 The whole block has been enclosed with `.RS' and `.RE' to set the left
369 margin temporarily to the current indentation value.
374 is one of the three macros used in the
376 package to format lists.
381 This macro produces a paragraph with a left hanging indentation.
386 This macro produces an unindented label followed by an indented
391 .BI .HP " \fR[\fPnnn\fR]\fP"
392 Set up a paragraph with hanging left indentation.
393 The indentation is set to
395 if that argument is supplied (the default unit is `n' if omitted),
396 otherwise it is set to the previous indentation value specified with
401 (or to the default value if none of them have been used yet).
402 Font size and face are reset to its default values.
403 The following paragraph illustrates the effect of this macro with
404 hanging indentation set to\~4 (enclosed by
408 to set the left margin temporarily to the current indentation):
412 This is a paragraph following an invocation of the
415 As you can see, it produces a paragraph where all lines but the first
420 Use of this presentation-level macro is deprecated.
421 While it is universally portable to legacy Unix systems, a hanging
422 indentation cannot be expressed naturally under HTML, and many
423 HTML-based manual viewers simply interpret it as a starter for a
425 Thus, any information or distinction you tried to express with the
426 indentation may be lost.
429 .BI .RS " \fR[\fPnnn\fR]\fP"
430 This macro moves the left margin to the right by the value
432 if specified (default unit is `n'); otherwise it is set to the
433 previous indentation value specified with
438 (or to the default value if none of them have been used yet).
439 The indentation value is then set to the default.
447 .BI .RE " \fR[\fPnnn\fR]\fP"
448 This macro moves the left margin back to level
450 restoring the previous left margin.
451 If no argument is given, it moves one level back.
452 The first level (i.e., no call to
454 yet) has number\~1, and each call to
456 increases the level by\~1.
465 filling is disabled and the font is set to constant-width.
466 This is useful for formatting code, command, and
467 configuration-file examples.
470 macro restores the previous font.
473 These macros are defined on many (but not all) legacy Unix systems
474 running classic troff.
475 To be certain your page will be portable to those systems, copy
476 their definitions from the
483 To summarize, the following macros cause a line break with the
484 insertion of vertical space (which amount can be changed with the
503 also cause a break but no insertion of vertical space.
506 .SH "MACROS TO SET FONTS"
508 The standard font is Roman; the default text size is 10\~point.
511 .BI .SM " \fR[\fPtext\fR]\fP"
512 Causes the text on the same line or the text on the next input line to
513 appear in a font that is one point size smaller than the default font.
516 .BI .SB " \fR[\fPtext\fR]\fP"
517 Causes the text on the same line or the text on the next input line to
518 appear in boldface font, one point size smaller than the default font.
522 Causes text on the same line to appear alternately in bold face and
524 The text must be on the same line as the macro call.
529 \&.BI this "word and" that
532 would cause `this' and `that' to appear in bold face, while `word and'
538 Causes text to appear alternately in italic and bold face.
539 The text must be on the same line as the macro call.
543 Causes text on the same line to appear alternately in roman and
545 The text must be on the same line as the macro call.
549 Causes text on the same line to appear alternately in italic and
551 The text must be on the same line as the macro call.
555 Causes text on the same line to appear alternately in bold face and
557 The text must be on the same line as the macro call.
561 Causes text on the same line to appear alternately in roman and bold
563 The text must be on the same line as the macro call.
566 .BI .B " \fR[\fPtext\fR]\fP"
569 to appear in bold face.
570 If no text is present on the line where the macro is called the text
571 of the next input line appears in bold face.
574 .BI .I " \fR[\fPtext\fR]\fP"
578 If no text is present on the line where the macro is called the text
579 of the next input line appears in italic.
582 .SH "MACROS TO DESCRIBE HYPERLINKS AND EMAIL ADDRESSES"
584 The following macros are not defined on legacy Unix systems
585 running classic troff.
586 To be certain your page will be portable to those systems, copy
587 their definitions from the
594 Using these macros helps ensure that you get hyperlinks when your
595 manual page is rendered in a browser or other program that is
601 .BI .UE " \fR[\fPpunctuation\fR]\fP"
602 Wrap a World Wide Web hyperlink.
605 is the URL; thereafter, lines until
607 are collected and used as the link text.
610 macro is pasted to the end of the text.
611 On a device that is not a browser,
617 \&.UR http://\e:randomsite.org/\e:fubar
625 usually displays like this: \[lq]this is a link to some random
626 site <http://\:randomsite.org/\:fubar>, given as an example\[rq].
631 to insert hyphenless breakpoints is a groff extension and can
637 .BI .ME " \fR[\fPpunctuation\fR]\fP"
638 Wrap an email address.
641 is the address; text following, until
643 is a name to be associated with the address.
646 macro is pasted to the end of the link text.
647 On a device that is not a browser,
653 \&.UR fred.foonly@\e:fubar.net
661 usually displays like this: \[lq]contact Fred Foonly
662 <fred.foonly@\:fubar.net> for more information\[rq].
667 to insert hyphenless breakpoints is a groff extension and can
671 .SH "MACROS TO DESCRIBE COMMAND SYNOPSES"
673 The following macros are not defined on legacy Unix systems
674 running classic troff.
675 To be certain your page will be portable to those systems, copy their
683 These macros are a convenience for authors.
684 They also assist automated translation tools and help browsers in
685 recognizing command synopses and treating them differently from
691 Takes a single argument, the name of a command.
692 Text following, until closed by
694 is set with a hanging indentation with the width of
697 This produces the traditional look of a Unix command synopsis.
701 Describe an optional command argument.
702 The arguments of this macro are set surrounded by option braces
703 in the default Roman font; the first argument is printed with
704 a bold face, while the second argument is typeset as italic.
708 This macro restores normal indentation at the end of a command
712 Here is a real example:
725 produces the following output:
738 If necessary, you might use
740 requests to control line breaking.
741 You can insert plain text as well; this looks like the traditional
742 (unornamented) syntax for a required command argument or filename.
747 The default indentation is 7.2n in troff mode and 7n in nroff mode
750 which ignores indentation.
754 Set tabs every 0.5\~inches.
755 Since this macro is always called during a
757 request, it makes sense to call it only if the tab positions have been
761 Use of this presentation-level macro is deprecated.
762 It translates poorly to HTML, under which exact whitespace control
763 and tabbing are not readily available.
764 Thus, information or distinctions that you use
766 to express are likely to be lost.
767 If you feel tempted to use it, you should probably be composing a
769 .BR @L_PRE_TBL@ (@MAN1DIR@)
773 .BI .PD " \fR[\fPnnn\fR]\fP"
774 Adjust the empty space before a new paragraph or section.
775 The optional argument gives the amount of space (default unit is `v');
776 without parameter, the value is reset to its default value (1\~line in
777 nroff mode, 0.4v\~otherwise).
778 This affects the macros
792 Use of this presentation-level macro is deprecated.
793 It translates poorly to HTML, under which exact control of
794 inter-paragraph spacing is not readily available.
795 Thus, information or distinctions that you use
797 to express are likely to be lost.
800 .BI .AT " \fR[\fPsystem \fR[\fPrelease\fR]]\fP"
801 Alter the footer for use with \f[CR]AT&T\f[]
803 This command exists only for compatibility; don't use it.
806 .BI .UC " \fR[\fPversion\fR]\fP"
807 Alter the footer for use with \f[CR]BSD\f[]
809 This command exists only for compatibility; don't use it.
813 Print the header string.
814 Redefine this macro to get control of the header.
818 Print the footer string.
819 Redefine this macro to get control of the footer.
822 The following strings are defined:
826 Switch back to the default font size.
830 The `registered' sign.
834 The `trademark' sign.
840 Left and right quote.
841 This is equal to `\e(lq' and `\e(rq', respectively.
845 The typeface used to print headings and subheadings.
849 If a preprocessor like
853 is needed, it has become usage to make the first line of the
863 Note the single space character after the double quote.
865 consists of letters for the needed preprocessors: `e' for
871 Modern implementations of the
873 program read this first line and automatically call the right
877 .SH "PORTABILITY AND TROFF REQUESTS"
881 macros consist of groups of troff requests, one can, in principle,
882 supplement the functionality of the
884 macros with individual troff requests where necessary.
887 Note, however, that using raw troff requests is likely to make your
888 page render poorly on the (increasingly common) class of viewers that
890 Troff requests make implicit assumptions about things like character
891 and page sizes that may break in an HTML environment; also, many of
892 these viewers don't interpret the full troff vocabulary, a problem
893 which can lead to portions of your text being silently dropped.
902 These are wrapper files to call
907 Use this file in case you don't know whether the
911 package should be used.
912 Multiple man pages (in either format) can be handled.
918 macros are contained in this file.
922 The extension macro definitions for
931 are contained in this file.
932 It is written in classic troff, and released for free re-use,
933 and not copylefted; manual page authors concerned about
934 portability to legacy Unix systems are encouraged to copy these
935 definitions into their pages, and maintainers of troff
936 or its workalikes are encouraged to re-use them.
940 Local changes and customizations should be put into this file.
945 .BR @L_P_TBL@ (@MAN1EXT@),
946 .BR @L_P_EQN@ (@MAN1EXT@),
947 .BR @L_P_REFER@ (@MAN1EXT@),
950 .BR @L_ROFF@_mdoc (7)
955 This manual page was originally written for the Debian GNU/Linux
960 It was corrected and updated by
964 The extension macros were documented (and partly designed) by