Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
GROFF_MAN(7)							  GROFF_MAN(7)

NAME
       groff_man - groff `man' macros to support generation of man pages

SYNOPSIS
       groff -man [ options... ] [ files... ]
       groff -m	man [ options... ] [ files... ]

DESCRIPTION
       The  man	 macros	 used to generate man pages with groff were written by
       James Clark.  This document provides a brief summary of the use of each
       macro in	that package.

OPTIONS
       The  man	 macros	 understand  the following command line	options	(which
       define various registers).

       -rcR=1 This option (the default if in nroff mode) will create a single,
	      very long	page instead of	multiple pages.	 Say -rcR=0 to disable
	      it.

       -rC1   If more than one manual page is given on the command line,  num-
	      ber the pages continuously, rather than starting each at 1.

       -rD1   Double-sided  printing.  Footers for even	and odd	pages are for-
	      matted differently.

       -rFT=dist
	      Set distance of the footer relative to the bottom	of the page if
	      negative	or  relative  to  the top if positive.	The default is
	      -0.5i.

       -rHY=flags
	      Set hyphenation flags.  Possible values are 1 to hyphenate with-
	      out  restrictions,  2 to	not hyphenate the last word on a page,
	      4	to not hyphenate the last two characters of a word,  and  8 to
	      not  hyphenate the first two characters of a word.  These	values
	      are additive; the	default	is 14.

       -rIN=width
	      Set body text indentation	to  width.   The  default  is  7n  for
	      nroff,  7.2n  for	troff.	For nroff, this	value should always be
	      an integer multiple of unit `n' to get consistent	indentation.

       -rLL=line-length
	      Set line length.	If this	option is not given, the  line	length
	      defaults to 78n in nroff mode and	6.5i in	troff mode.

       -rLT=title-length
	      Set title	length.	 If this option	is not given, the title	length
	      defaults to the line length.

       -rPnnn Enumeration of pages will	start with nnn rather than with	1.

       -rSxx  Base document font size is xx points (xx can be 10,  11,	or 12)
	      rather than 10 points.

       -rSN=width
	      Set sub-subheading indentation to	width.	The default is 3n.

       -rXnnn After  page nnn,	number	pages  as  nnna, nnnb, nnnc, etc.  For
	      example, the option `-rX2' will produce the following page  num-
	      bers: 1, 2, 2a, 2b, 2c, etc.

USAGE
       This section describes the available macros for manual pages.  For fur-
       ther customization, put additional macros and requests  into  the  file
       man.local which will be loaded immediately after	the man	package.

       .TH title section [extra1] [extra2] [extra3]
	      Set  the	title of the man page to title and the section to sec-
	      tion, which must take on a value between	1  and 8.   The	 value
	      section may also have a string appended, e.g. `.pm', to indicate
	      a	specific subsection of the man pages.  Both title and  section
	      are  positioned  at  the left and	right in the header line (with
	      section in parentheses immediately appended  to  title.	extra1
	      will  be	positioned  in	the middle of the footer line.	extra2
	      will be positioned at the	left in	the footer  line  (or  at  the
	      left on even pages and at	the right on odd pages if double-sided
	      printing is active).  extra3 is centered in the header line.

	      For HTML output, headers and footers are completely supressed.

	      Additionally, this macro starts a	new page; the new line	number
	      is 1  again (except if the `-rC1'	option is given	on the command
	      line) -- this feature is intended	only for  formatting  multiple
	      man pages; a single man page should contain exactly one TH macro
	      at the beginning of the file.

       .SH [text for a heading]
	      Set up an	unnumbered section heading sticking out	to  the	 left.
	      Prints  out  all the text	following SH up	to the end of the line
	      (or the text in the next input line if there is no  argument  to
	      SH)  in  bold face (or the font specified	by the string HF), one
	      size larger than the base	document size.	Additionally, the left
	      margin  and  the	indentation for	the following text is reset to
	      the default values.

       .SS [text for a heading]
	      Set up a secondary, unnumbered section heading.  Prints out  all
	      the  text	following SS up	to the end of the line (or the text in
	      the next input line if there is no argument to SS) in bold  face
	      (or  the	font  specified	by the string HF), at the same size as
	      the base document	size.  Additionally, the left margin  and  the
	      indentation  for the following text is reset to the default val-
	      ues.

       .TP [nnn]
	      Set up an	indented paragraph with	label.	The indentation	is set
	      to  nnn if that argument is supplied (the	default	unit is	`n' if
	      omitted),	otherwise it is	set to the previous indentation	 value
	      specified	with TP, IP, or	HP (or to the default value if none of
	      them have	been used yet).

	      The first	input line of text following this macro	is interpreted
	      as a string to be	printed	flush-left, as it is appropriate for a
	      label.  It is not	interpreted as part of a paragraph,  so	 there
	      is  no attempt to	fill the first line with text from the follow-
	      ing input	lines.	Nevertheless, if the label is not as  wide  as
	      the  indentation	the  paragraph	starts	at  the	same line (but
	      indented), continuing on the following lines.  If	the  label  is
	      wider than the indentation the descriptive part of the paragraph
	      begins on	the line following the label, entirely indented.  Note
	      that  neither  font shape	nor font size of the label is set to a
	      default value; on	the other hand,	the rest of the	text will have
	      default font settings.

	      The TP macro is the macro	used for the explanations you are just
	      reading.

       .LP
       .PP
       .P     These macros are mutual aliases.	Any  of	 them  causes  a  line
	      break  at	 the  current  position,  followed by a	vertical space
	      downwards	by the amount specified	by the	PD  macro.   The  font
	      size  and	 shape	are  reset  to	the  default value (10pt resp.
	      Roman).  Finally,	the current left margin	 and  the  indentation
	      are restored.

       .IP [designator]	[nnn]
	      Set  up an indented paragraph, using designator as a tag to mark
	      its beginning.  The indentation is set to	nnn if	that  argument
	      is  supplied  (the default unit is `n' if	omitted), otherwise it
	      is set to	the previous indentation value specified with TP,  IP,
	      or  HP  (or  to the default value	if none	of them	have been used
	      yet).  Font size and face	of the paragraph (but not the designa-
	      tor) are reset to	its default values.

	      To start an indented paragraph with a particular indentation but
	      without a	designator, use	`""' (two doublequotes)	as the	second
	      argument.

	      For  example, the	following paragraphs were all set up with bul-
	      lets as the designator, using `.IP \(bu 4'.  The whole block has
	      been enclosed with `.RS' and `.RE' to set	the left margin	tempo-
	      rarily to	the current indentation	value.

	      o	  IP is	one of the three macros	used in	 the  man  package  to
		  format lists.

	      o	  HP  is another.  This	macro produces a paragraph with	a left
		  hanging indentation.

	      o	  TP is	another.  This macro produces an unindented label fol-
		  lowed	by an indented paragraph.

       .HP [nnn]
	      Set  up a	paragraph with hanging left indentation.  The indenta-
	      tion is set to nnn if that argument  is  supplied	 (the  default
	      unit  is	`n'  if	 omitted), otherwise it	is set to the previous
	      indentation value	specified with	TP,  IP,  or  HP  (or  to  the
	      default  value  if  none of them have been used yet).  Font size
	      and face are reset to its	default	values.	 The  following	 para-
	      graph illustrates	the effect of this macro with hanging indenta-
	      tion set to 4 (enclosed by `.RS' and `.RE' to set	the left  mar-
	      gin temporarily to the current indentation):

	      This is a	paragraph following an invocation of the HP macro.  As
		  you can see, it produces a paragraph where all lines but the
		  first	are indented.

       .RS [nnn]
	      This  macro  moves the left margin to the	right by the value nnn
	      if specified (default unit is `n'); otherwise it is set  to  the
	      previous	indentation  value specified with TP, IP, or HP	(or to
	      the default value	if none	of them	 have  been  used  yet).   The
	      indentation value	is then	set to the default.

	      Calls to the RS macro can	be nested.

       .RE [nnn]
	      This  macro  moves  the left margin back to level	nnn, restoring
	      the previous left	margin.	 If no argument	is given, it moves one
	      level  back.  The	first level (i.e., no call to RS yet) has num-
	      ber 1, and each call to RS increases the level by	1.

       To summarize, the following macros cause	a line break with  the	inser-
       tion of vertical	space (which amount can	be changed with	the PD macro):
       SH, SS, TP, LP (PP, P), IP, and HP.  The	macros RS and RE also cause  a
       break but no insertion of vertical space.

MACROS TO SET FONTS
       The standard font is Roman; the default text size is 10 point.

       .SM [text]
	      Causes  the  text	on the same line or the	text on	the next input
	      line to appear in	a font that is one point size smaller than the
	      default font.

       .SB [text]
	      Causes  the  text	on the same line or the	text on	the next input
	      line to appear in	boldface font, one point size smaller than the
	      default font.

       .BI text
	      Causes  text on the same line to appear alternately in bold face
	      and italic.  The text must be on the  same  line	as  the	 macro
	      call.  Thus

		     .BI this "word and" that

	      would  cause  `this'  and	 `that'	 to appear in bold face, while
	      `word and' appears in italics.

       .IB text
	      Causes text to appear alternately	in italic and bold face.   The
	      text must	be on the same line as the macro call.

       .RI text
	      Causes  text on the same line to appear alternately in roman and
	      italic.  The text	must be	on the same line as the	macro call.

       .IR text
	      Causes text on the same line to appear alternately in italic and
	      roman.  The text must be on the same line	as the macro call.

       .BR text
	      Causes  text on the same line to appear alternately in bold face
	      and roman.  The text must	be on the same line as the macro call.

       .RB text
	      Causes  text on the same line to appear alternately in roman and
	      bold face.  The text must	be on the same line as the macro call.

       .B [text]
	      Causes  text  to	appear in bold face.  If no text is present on
	      the line where the macro is called the text of  the  next	 input
	      line appears in bold face.

       .I [text]
	      Causes  text  to appear in italic.  If no	text is	present	on the
	      line where the macro is called the text of the next  input  line
	      appears in italic.

MISCELLANEOUS
       The  default  indentation  is  7.2n  in troff mode and 7n in nroff mode
       except for grohtml which	ignores	indentation.

       .DT    Set tabs every 0.5 inches.  Since	this macro  is	always	called
	      during  a	 TH request, it	makes sense to call it only if the tab
	      positions	have been changed.

       .PD [nnn]
	      Adjust the empty space before a new paragraph or	section.   The
	      optional	argument  gives	 the  amount of	space (default unit is
	      `v'); without parameter, the value is reset to its default value
	      (1 line in nroff mode, 0.4v otherwise).  This affects the	macros
	      SH, SS, TP, LP (resp. PP and P), IP, and HP.

       .AT [system [release]]
	      Alter the	footer for  use	 with  AT&T  manpages.	 This  command
	      exists only for compatibility; don't use it.  See	the groff info
	      manual for more.

       .UC [version]
	      Alter the	footer for use with BSD	manpages.  This	command	exists
	      only for compatibility; don't use	it.  See the groff info	manual
	      for more.

       .PT    Print the	header string.	Redefine this macro to get control  of
	      the header.

       .BT    Print  the footer	string.	 Redefine this macro to	get control of
	      the footer.

       The following strings are defined:

       \*S    Switch back to the default font size.

       \*R    The `registered' sign.

       \*(Tm  The `trademark' sign.

       \*(lq
       \*(rq  Left and right quote.  This  is  equal  to  `\(lq'  and  `\(rq',
	      respectively.

       \*(HF  The  typeface  used  to  print  headings	and  subheadings.  The
	      default is `B'.

       If a preprocessor like tbl or eqn is needed, it	has  become  usage  to
       make the	first line of the man page look	like this:

	      .\" word

       Note  the single	space character	after the double quote.	 word consists
       of letters for the needed preprocessors:	`e' for	eqn,  `r'  for	refer,
       and  `t'	 for tbl.  Modern implementations of the man program read this
       first line and automatically call the right preprocessor(s).

FILES
       man.tmac
       an.tmac
	      These are	wrapper	files to call andoc.tmac.

       andoc.tmac
	      This file	checks whether the man	macros	or  the	 mdoc  package
	      should be	used.

       an-old.tmac
	      All man macros are contained in this file.

       man.local
	      Local changes and	customizations should be put into this file.

SEE ALSO
       Since  the  man macros consist of groups	of groff requests, one can, in
       principle, supplement the functionality of the man macros with individ-
       ual  groff  requests  where  necessary.	See the	groff info pages for a
       complete	reference of all requests.

       tbl(1), eqn(1), refer(1), man(1)

AUTHOR
       This manual page	was originally written for the Debian GNU/Linux	system
       by Susan	G. Kleinmann <sgk@debian.org>, corrected and updated by	Werner
       Lemberg <wl@gnu.org>, and is now	part of	the GNU	troff distribution.

Groff Version 1.19		  1 May	2003			  GROFF_MAN(7)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USAGE | MACROS TO SET FONTS | MISCELLANEOUS | FILES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=man&sektion=7&manpath=FreeBSD+5.2-RELEASE>

home | help