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

FreeBSD Manual Pages

  
 
  

home | help
GROFF_MAN(7)	       Miscellaneous Information Manual		  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 de-
       fine various registers).

       -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 78n in nroff mode and	6.5i in	troff mode.

       -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.

       -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.

       -rXnnn After page nnn, number pages as nnna, nnnb, nnnc,	etc.  For  ex-
	      ample,  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]
	      Sets  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 (resp.	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]
	      Sets  up an unnumbered section heading sticking out to the left.
	      Prints out all the text following	SH up to the end of  the  line
	      (resp.  the  text	in the next input line if there	is no argument
	      to SH) in	bold face, one size  larger  than  the	base  document
	      size.   Additionally,  the left margin for the following text is
	      reset to its default value.

       .SS [text for a heading]
	      Sets up an secondary, unnumbered section	heading.   Prints  out
	      all  the	text following SS up to	the end	of the line (resp. the
	      text in the next input line if there is no argument  to  SS)  in
	      bold  face,  at  the same	size as	the base document size.	 Addi-
	      tionally,	the left margin	for the	following text is reset	to its
	      default value.

       .TP [nnn]
	      Sets 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 default indentation
	      value.  The first	input line of text following this macro	is in-
	      terpreted	as a string to be printed flush-left, as it is	appro-
	      priate  for  a  label.  It is not	interpreted as part of a para-
	      graph, so	there is no attempt to fill the	first line  with  text
	      from  the	 following input lines.	 Nevertheless, if the label is
	      not as wide as the indentation, then the paragraph starts	at the
	      same line	(but indented),	continuing on the following lines.  If
	      the label	is wider than the indentation,	then  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.  Ro-
	      man).  Finally, the current left margin is restored.

       .IP [designator]	[nnn]
	      Sets up an indented paragraph, using designator as a tag to mark
	      its  beginning.	The indentation	is set to nnn if that argument
	      is supplied (default unit	is `n'), otherwise the default	inden-
	      tation  value is used.  Font size	and face of the	paragraph (but
	      not the designator) 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	 argu-
	      ment.

	      For  example, the	following paragraphs were all set up with bul-
	      lets as the designator, using `.IP \(bu 4':

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

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

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

       .HP [nnn]
	      Sets up a	paragraph with hanging left indentation.  The indenta-
	      tion is set to nnn if that argument is supplied (default unit is
	      `n'), otherwise the default indentation  value  is  used.	  Font
	      size  and	 face  are reset to its	default	values.	 The following
	      paragraph	illustrates the	effect of this macro with hanging  in-
	      dentation	set to 4:

	      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 the	default	inden-
	      tation value is used.  Calls to the RS macro can be nested.

       .RE [nnn]
	      This macro moves the left	margin back to level nnn; if no	 argu-
	      ment  is given, it moves one level back.	The first level	(i.e.,
	      no call to RS yet) has number 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.  Finally, the	macros SH, SS,
       LP (PP, P), and RS reset	the indentation	to its default value.

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, then 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, then the text of the next	 input
	      line appears in italic.

MISCELLANEOUS
       The  default indentation	is 7.2n	for all	output devices except for gro-
       html which ignores indentation.

       .DT    Sets 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]
	      Adjusts the empty	space before a new paragraph (resp.  section).
	      The  optional  argument gives the	amount of space	(default units
	      are `v');	without	parameter, the value is	reset to  its  default
	      value  (1	line  for  tty devices,	0.4v otherwise).  This affects
	      the macros SH, SS, TP, LP	(resp. PP and P), IP, and HP.

       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',  re-
	      spectively.

       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.  A complete	list of	these requests
       is available on the WWW at

		http://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html

       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.18.1	       05 September 2002		  GROFF_MAN(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=groff_man&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>

home | help