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

FreeBSD Manual Pages


home | help
man(5)			      File Formats Manual			man(5)

       man - macros for	formatting manpages


       [option]... [file]...

       The  macros  are	 used by the and commands (see man(1) and nroff(1)) --
       and are usable by (see third-party documentation) -- to format the  on-
       line versions of	manpages found in and other related reference manuals.
       The command calls

   man and nroff Defaults
       The default page	size is	85 characters by  66  lines  (8.5x11  inches),
       with  a	75-character  by 60-line text area.  Hyphenation is turned off
       and paragraphs are left-adjusted, ragged-right.

   troff Defaults
       The default page	size is	8.5x11 inches with a  6.5x10-inch  text	 area.
       The  type size is 10 points and the vertical line spacing is 12 points.
       Hyphenation is turned on	and paragraphs are justified left and right.

   Other Defaults
       Type font and size are reset to default values  before  each  paragraph
       and  after  processing  font-  and  size-setting	macros such as and Tab
       stops are neither used nor set by any macro except and  The  macro  in-
       vokes (see below).

       The  following  options	can be specified for or	They are not permitted
       for the command.

       Reduce the dimensions for
		 to a page size	of 6x9	inches	with  a	 4.75x8.375-inch  text
		 area,	the type size to 9 points, and the vertical line spac-
		 ing to	10 points.  This option	is ignored by

       Set certain parameters  to  values  appropriate	for  certain  Versatec
		 line  length to 82 characters (ens); page length to 84	lines;
		 underlining inhibited.	 Do not	confuse	this option  with  the
		 option	 of  the command, which	is available on	some operating
		 systems, but not on HP-UX.

   Summary of Macros, Strings, and Numbers
       The defined macros, strings, and	numbers	are summarized	here  and  de-
       scribed in detail in the	following subsections.

       Set	 text in bold.
       Set	 words alternately in bold and constant-width.
       Set	 words alternately in bold and italics.
       Set	 words alternately in bold and roman.
       Set	 text in constant-width.
       Set	 words alternately in constant-width and bold.
       Identify	command	name.
       Set	 words alternately in constant-width and italics.
       Set	 words alternately in constant-width and roman.
       Identify	citation title.
       Restore default tab settings.
       Identify	emphasis.
       Identify	error name.
       Identify	environment variable name.
       Identify	glossary term.
       Begin paragraph with hanging indent.
       Set	 text in italics.
       Set	 words alternately in italics and bold.
       Set	 words alternately in italics and constant-width.
       Begin indented paragraph	with optional tag.
       Set	 words alternately in italics and roman.
       Identify	keycap.
       Begin normal paragraph.
       Set interparagraph spacing.
       Use Bell	System proprietary subfooters.
       Begin normal paragraph.
       Set	 words alternately in roman and	bold.
       Set	 words alternately in roman and	constant-width.
       End relative margin indent.
       Set	 words alternately in roman and	italics.
       Start relative margin indent.
       Identify	return value.
       Insert third level header.
       Identify	system constant	name.
       Insert section header.
       Print	 text one point	smaller.
       Insert subsection header.
       Start new manpage and define page headers and footers.
       Begin tagged paragraph.
       Registered trademark.
       Change to default type size.
       Left text margin; default margin	indent and paragraph indent.
       Line length, including
       Interparagraph distance.

   Macro Parameters
       All  macro  parameters are positional and can be	omitted, starting from
       the right.  Each	parameter is a word, as	described below.

       mi	 Margin	increment.  This is the	amount by which	the left  text
		 margin	 will  be increased.  If it is omitted,	it defaults to
		 basic units The default measure for mi	is ens The  left  text
		 margin's base value is

       in	 Paragraph indent.  This is the	amount by which	indented lines
		 of a paragraph	will be	indented.  If it is  omitted,  it  de-
		 faults	 to  the value that was	established by the most	recent
		 paragraph macro: explicitly or	default	by or implicitly by or
		 The default measure for in is ens

       text	 Consists of zero to six words.	 If text is empty, the special
		 treatment is applied to the next line containing text	to  be
		 printed.  For example,	can be used to italicize a whole line,
		 or followed by	to make	small bold text.

       word	 A string of characters	separated by spaces (not  tabs).   Use
		 quotation   marks  ([word])  to  include  spaces  in  a  word
		 (string string) or to specify a null word ().	(The nonbreak-
		 ing, nonpaddable space	is not a separating space.)

   Header Macros
       Set the title and entry heading.
		 t1, s2, c3, n4, and a5	are words.

		 t1   Entry title.

		 s2   Section  number.	 t1 is combined	with s2	in parentheses
		      to form the top left- and	righthand corners of the  page

		 c3   Extra  commentary, such as "Optional Software Required".
		      It is placed at the center of the	 bottom	 line  in  the
		      two- or three-line page heading space.

		 n4   Other  notations,	 such as "Series 300/400 Only".	 It is
		      centered between the title and section on	the first page
		      heading line.

		 a5   Support  for alternate naming, such as a FORTRAN routine
		      name corresponding to a C	function name specified	in t1.

		 The resulting output is in the	form:

		 t1(s2)			      n4		       t1(s2)
		 a5							   a5

       Place section head
		 text, such as here.  Section headings start at	the left  mar-
		 gin.  Since they are normally all uppercase, they are printed
		 a point-size smaller in

       Place subsection	head
		 text, such as here.  Subsection headings  start  between  the
		 left margin and the normal text indent.

       Place third-level head
		 text,	such  as subhead, here.	 Third-level headings start at
		 the normal text indent.

   Paragraph Macros
       Begin a block paragraph.
		 Reset in to  "cancelling"  any	 value	set  by	 previous  and

       Begin a paragraph with hanging indent.
		 The  text  begins at the current margin.  The second and fol-
		 lowing	output lines are indented.

       Begin an	indented paragraph with	hanging	tag.
		 The next input	line that contains text	to be printed is taken
		 as  the  tag.	 The tag begins	at the current margin.	If the
		 tag fits in the indent, the paragraph text begins at the  in-
		 dent  position	 on the	same line.  If the tag does not	fit in
		 the indent, the paragraph text	begins at the indent  position
		 on the	next line.

       Same as	 with  tag t.  Often used to get an indented paragraph without
		 a tag.

       Increase	the current left margin	by
		 mi.  If mi is omitted,	it defaults to the  current  value  of
		 in.   Set  the	paragraph indent, in, for the new margin level
		 to You	can specify up to nine increment levels.   Margin  in-
		 crements  can	be  backed out with the	macro and are reset to
		 the base margin by the	and header macros.

       Return to the
		 kth left margin setting (initially, k=1; k=0 is equivalent to
		 k=1).	 If k is omitted, return to the	previous margin	value.
		 The paragraph indent, in, is restored to  the	value  it  had
		 prior to the corresponding macro.

       Set the interparagraph distance to
		 pd vertical spaces.  If pd is omitted,	set the	interparagraph
		 distance to the default value:	1 line in 0.4 line in The mea-
		 sure for pd is	vertical line spaces

   Font	Macros
       Set	 text in bold.

       Set	 text in constant-width	font.  See the WARNINGS	section.

       Set	 text in italic.

       (There  is no (roman) macro, but	you can	use one	of the combinations if
       need be.)

		 a in font X with b in font Y and alternate  these  two	 fonts
		 for up	to six words.  The font	letters	X and Y	can be (bold),
		 (constant-width), (italic), and  (roman),  in	the  following

		 For more about	constant-width font, see the WARNINGS section.

       Make	 text one point	smaller	than the default point size.  This has
		 no effect in

   Special Macros
       These macros identify common text elements in manpages.	 They  aid  in
       providing  consistent  font usage in the	HP style and in	improving con-
       version to other	formatting systems.

       The first parameter is set in an	appropriate font or format.  The  sec-
       ond  parameter,	punctuation,  is set in	roman font and is provided for
       concatenated punctuation.  The two parameters are concatenated as  with
       the font	macros.

		 is  a command name, usually defined in	a section 1 or 1M man-
		 page, such as It is displayed in constant-width font.

		 is the	name of	a document, such as It is displayed  in	 ital-
		 ics.  (Use the	standard macro for manpage references.)

       emphasis	 is  a	word or	phrase that you	want to	emphasize, such	as Use
		 emphasis sparingly.  It is displayed in  italics.   (Use  the
		 standard macro	for variable names.)

       errorname is an error name that corresponds to a	value assigned to by a
		 function and described	in the ERRORS section  of  a  manpage.
		 It  is	 displayed in roman, enclosed in square	brackets.  For
		 example, is displayed as

		 is the	name of	an environmental variable, such	as It is  dis-
		 played	in constant-width font.

       glossterm is a glossary term, or	a term that you	are defining for later
		 use in	the manpage, such as It	is displayed in	bold.

       keycap	 is the	name of	a keyboard key,	such as	 It  is	 displayed  in

		 is a numerical	return value of	a function or exit status of a
		 command, usually as defined in	a RETURN VALUE or EXIT	STATUS
		 section.   It	is generally used for number expressions, such
		 as and	but not	for word descriptions, such as "nonzero".   It
		 is displayed in constant-width	font.

		 is an operating system	constant name, such as It is displayed
		 in constant-width font.  See getconf(1).

   Other Macros
       Restore default tab settings:
		 every 5 ens in	every 3.6 ems in

       Produce Bell System proprietary subfooters.

		 sf	produces


       The following string references are defined:

       Registered Trademark symbol:
		 displayed as in and using the inline macro in

       Change to default type size.
		 This is executed as a inline macro.

       Trademark indicator, TM,	displayed as a superscript if possible.

       The following number references are defined:

       Left text margin	indent relative	to section heads
		 and default value for mi and in: 5 ens	in 3.6 ems in  is  ex-
		 pressed in basic units

       Line length including
		 75  characters	 in 6.5	inches in Also see the Options subsec-
		 tion.	is expressed in	basic units

       Current interparagraph distance.
		 Set by	is expressed in	vertical line spaces

       and use a number	of scale indicators to qualify horizontal and vertical
       measurements.   Many  macro  parameters	have default units of measure.
       Because all assignments to numeric variables  are  converted  to	 basic
       units it	is important to	take care in assigning and referencing values.

	      Scale				   Basic Units
	      Indicator	  Measure		nroff	   troff
	      c		  centimeter		240/2.54   D/2.54
	      i		  inch			240	   D
	      m		  em			C	   p*S
	      n		  en = em/2		C	   p*S/2
	      p		  point	= 1/72 inch	240/72	   D/72
	      P		  pica = 1/6 inch	240/6	   D/6
	      u		  basic	unit		1	   1
	      v		  vertical line	space	V	   V

	      C	     Character width of	output device.
	      D	     Dots per inch (dpi) of output device.
	      S	     Current type size in points.
	      V	     Current vertical line spacing in basic units.

   Font	Conventions
       Entries in the HP-UX Reference use the following	font conventions:

	      roman	     Regular typeface.

	      italic	     Used for variables	and other words	that represent
			     an	argument that may take on  a  user-defined  or
			     variable value.  Also used	for emphasis.

	      boldface	     Used  primarily  in headings and occasionally for
			     terms when	first introduced  or  when  being  de-

	      Used for all literals that are typed exactly as shown when used
			     as	 keyboard commands or command-line options, in
			     programs, etc.

   Page	Footers
       The strings used	in the page footer are initialized by the macro.   de-
       faults  to  a nonprinting (null)	string.	 defaults to the date the man-
       page is formatted, as in	In HP manpages,	is set to  the	company	 name,
       "Hewlett-Packard	 Company"; is set to release information, as in	"HP-UX
       Release 10.10: November 1995".

       This arrangement	enables	users and third-party  software	 suppliers  to
       directly	control	the contents of	the left- and right-hand fields	of the
       footer line for use in displaying company name, release version,	 etc.,
       as  desired  when creating their	own manual entries.  is	printed	on the
       left, is	printed	on the right, and the page number is  printed  in  the
       center.	 These	strings	 can be	defined	anywhere after the macro call,
       provided	they appear before the end of the first	 page.	 For  example,
       the following source file segment:

       produces	a footer with text in the form:

	      XYZ Company		 - 1 -	     Release 2.3: May 1996

       The preprocessor	(see tbl(1)) can be used to insert tables in manpages.
       The macros allow	you to use the standard	macros:	and They do  not  sup-
       port the	macro extensions, and (see mm(5)).

       In  general,  avoid  using  the macros within a table, particularly the
       font macros, which can produce peculiar and unpredictable results.  Use
       the  intrinsic  macros instead.	For example, to	specify	bold type, use
       the in-line macro or, more generally, To	insert horizontal blank	lines,
       you  can	 use  the or macro, depending on which one preceded the	table,
       but you must then avoid using  the  and	table  format  specifications.
       Otherwise, indentation will be erratic.

       HP no longer uses the NAME section to prepare the Table of Contents and
       Index for the printed manual.  Instead, that information	 is  coded  as
       comments	 at  the  end  of each manpage source file where it can	be ac-
       cessed by various tools and programs as desired.	 The NAME  section  is
       still used for the database, as described below.

       The  macro  package used	to print the HP-UX Reference increases the in-
       terword spaces (to eliminate ambiguity) in the section of each entry.

       In addition to the macros,  strings,  and  number  registers  mentioned
       above,  a  number of internal macros, strings, and number registers are
       defined.	 These include

	 o  The	names predefined by the	processor.

	 o  The	macro

	 o  The	number register

	 o  Macro, string, and number names in the forms and  where  x	stands
	    for	some alphanumeric character,

	 o  Macro,  string, and	number names in	the form XY, where X and Y are
	    capital letters.

       uses only three fonts: roman, italic, and bold, designated as font  po-
       sitions	1,  2, and 3, respectively.  The constant-width	font macros in
       the macro package simulate a constant-width font	with  the  bold	 font,
       since all output	is constant width or typewriter	format.

       To  use a true constant-width font with change the corresponding	font 3
       specification in	each constant-width font macro to font 4 and  mount  a
       constant-width font in position 4 using a request, as in:

   The whatis Database
       The  NAME  section  of each manpage is processed	by (see	catman(1M)) to
       create an entry in the database,	which is used by the  and  options  of
       the  command.   processes  the  lines of	the NAME section into a	single
       line in the format:

	      name[, name]... -	explanatory-text

       Hyphens (typed as or en-dashes and em-dashes are	treated	 equivalently.
       The  last space-hyphen-space in the line	becomes	the dividing point be-
       tween names and explanatory text.


		     Called by
	      Sources the macros in Other macro	files can be specified here to
	      accommodate manpages with	additional macro requirements.

		     File of strings from manpage NAME sections,
	      created by and used by the and options.

       col(1), man(1), neqn(1),	nroff(1), tbl(1), catman(1M), mm(5).



Want to link to this manual page? Use this URL:

home | help