unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



man(5)								       man(5)



NAME

  man, man.page	- The man macro	packages for reference pages

SYNOPSIS

  tbl file... |	neqn | nroff  -h  [options] -man  |  ...

  tbl file... |	neqn | nroff  -h  [options] -man.page  |  ...

OPTIONS

  -h  Uses output tabs during horizontal spacing to speed output and reduce
      output character count.  Tab settings are	assumed	to be every eight
      nominal character	widths.

  -nN Numbers the first	generated page as N.

      Ignored by the man macros	for nroff output. Ignored for *troff output
      unless -rpS is also specified.

  -rlN
      Turns on line double-spacing mode	if N is	greater	than 0.

  -rnN
      Numbers the first	generated page as N.  Page numbers always print	on
      the outside end of the page footer.

      Ignored by the man macros	for nroff output.

  -rpS
      Sets the section number to S.  Section numbers appear in output page
      footers as S-N (chapter-page-number).

      Page numbers always print	on the outside end of the page footer. Start-
      ing page number defaults to "1" unless -nN or -rnN is also specified.

      Ignored by the man macros	for nroff output.

  -rv2
      Prints crop marks.  Only for use with *troff formatters.

DESCRIPTION

  The man macro	package	is used	to format reference pages for unpaginated
  viewing, or for printing on ASCII printers.  The man macro package is	the
  default. The reference pages installed on the	base system are	formatted by
  the man and the catman commands, using the man macro package.

  The man.page macro package is	used to	format reference manual	pages for
  paginated ASCII output.


  The file argument is the name	of the reference page source file.

  The page width is 77 columns when formatted by the nroff command and the
  man or man.page macro	packages. The output is	paginated when formatted by
  the nroff command and	the man.page macro package, with page numbers appear-
  ing at the bottom right of each output page.

  Macros


  The following	describes the macros in	the man	and man.page macro packages.

  Note that some of the	macro descriptions contain information about *troff
  output.  This	is provided for	completeness, only.  Compaq does not supply
  or support any *troff	formatters.

  Any text argument can	range from zero	to six words. Quotation	marks (" ")
  can be used to include blanks	in words.  If text is not specified, special
  treatment is applied to the next input line that has text to be printed. In
  this way, .I can be used to italicize	a whole	line or	.SM followed by	.B to
  make small bold letters.

  A prevailing indent distance is remembered between successive	indented
  paragraphs, and is reset to a	default	value upon reaching a nonindented
  paragraph.  Default units for	indents	i are ens (an en is 1 nroff character
  or 1/2 em space in the current point size).

  Typeface and size are	reset to default values	before each paragraph, and
  after	processing font	and size setting macros.

  .AT [	3|4|5 ]	[ number ]
      For *troff output	only.  Specifies the text string to be printed as the
      inside page footer.  No argument,	or the argument	3, specifies the text
      "7th Edition." The argument 4 specifies the text "System III." The
      argument 5 specifies the text "System V."	The argument 5 followed	by a
      number argument specifies	the text "System V Release number."

  .B [ text... ]
      Sets text	text in	boldface.  If no text is specified, only the next
      source text line is set in boldface.

  .BI word1 word2 [ words... ]
      Sets word1 in boldface, word2 in an italic typeface, and then alter-
      nates between these two fonts for	the remaining words, up	to six words.
      Blanks between words are stripped	unless the string is enclosed in quo-
      tation marks (" ").

  .BR word1 word2 [ words... ]
      Sets word1 in boldface, word2 in a roman typeface, and then alternates
      between these two	fonts for the remaining	words, up to six words.
      Blanks between words are stripped	unless the string is enclosed in quo-
      tation marks (" ").

  .CM [	number ]
      For *troff output	only.  Specifies the text string to be printed as the
      inside page footer.  No argument,	or the number 1, specifies the text
      "1st Carnegie-Mellon Update." The	number 2 specifies the text "2nd
      Carnegie-Mellon Update." The number 3 specifies the text "3rd
      Carnegie-Mellon Update." Any whole number	n above	3 specifies the	text
      "nth Carnegie-Mellon Update."

  .CT character
      Prints the keyboard control character indicator <CTRL/character>.	For
      example, .CT A prints as <CTRL/A>.

  .CW Sets text	in a constant width font until another font change is
      encountered.

  .De Ends an unfilled display block (started by .Ds).	Also ends automatic
      centering, if it was in effect.

  .DE Ends an unfilled display block (started by .DS) and restores the left
      margin to	the previous position.

  .Ds Starts an	unfilled display block.	 Text between .Ds and .De is printed
      in a roman typeface, with	`no fill' mode (no wrapping and	blank lines
      allowed) in effect. The display block is set flush left.

  .DS Starts a display block with `no fill' mode (no wrapping and blank	lines
      allowed) in effect. The display block is shifted right .5	inch for
      nroff and	four picas for *troff formatters.

  .DT Restores default tabs.  Default tabs are set to every 8 ens for nroff
      and to every .5 inches for *troff	text formatters, starting with .5i,
      1i, ... .

  .EE Ends an example and restores basic text defaults and indents.

  .EX [	i ]
      Starts an	example.  Text between .EX and .EE is printed in a constant
      width font with `no fill'	mode (no wrapping and blank lines allowed) in
      effect. The example is set flush left unless an indent i is specified.
      Units of i are ens.

  .G [ text... ]
      Sets text	in a sans-serif	typeface.  If no text is specified, only the
      next source text line is set in a	sans-serif typeface.

  .GB [	words... ]
      Sets text	in a sans-serif	bold typeface.	If no text is specified, only
      the next source text line	is set in a sans-serif bold typeface.

  .GL [	text...	]
      Sets text	in a sans-serif	italic typeface.  If no	text is	specified,
      only the next source text	line is	set in a sans-serif italic typeface.

  .HP [	i ]
      Begins a paragraph with a	hanging	indent of i ens.

  .I [ text... ]
      Sets text	in an italic typeface.	If no text is specified, only the
      next source text line is set in an italic	typeface.

  .I1 word
      Sets a temporary indent to the length of the specified word.

  .I2 word
      Reverses one line	and then sets a	temporary indent to the	length of the
      specified	word.

  .IB word1 word2 [ words... ]
      Sets word1 in an italic typeface,	word2 in boldface, and then alter-
      nates between these two fonts for	the remaining words, up	to six words.
      Blanks between words are stripped	unless the string is enclosed in quo-
      tation marks (" ").

  .IP x	[ i ]
      Sets the prevailing indent to i.	Then begins the	indented paragraph
      with a hanging tag given by the next text	line.  If the tag does not
      fit, the macro places the	next text on a separate	line. Tag x appears
      in bold typeface.

  .IR word1 word2 [ words... ]
      Sets word1 in an italic typeface,	word2 in a roman typeface, and then
      alternates between these two fonts for the remaining words, up to	six
      words.  Blanks between words are stripped	unless the string is enclosed
      in quotation marks (" ").

  .MS reference_page section_subsection	[ punctuation ]
      Sets reference_page immediately followed by section_subsection in
      parentheses followed by optional punctuation, using fonts	that distin-
      guish this reference page	reference from ordinary	text.  For example,
      man(5).

  .NE Ends a note. Also	cancels	automatic centering if it was in effect.

  .NT [	header1	] [ C ]

  .NT [	C ] [ header2 ]
      Starts a note.  If no arguments are specified, the default header	for
      the note is `Note'. If the first argument	is the letter `C', all text
      in the note is centered, for the next 99 text lines or until the .NE
      macro is called, whichever comes first. If the first argument is not
      `C', it becomes the header of the	note, even if header2 is also speci-
      fied. The	header2	argument becomes the header of the note	if the first
      argument is `C'.

  .PD [	v ]
      Sets the interparagraph distance to v vertical spaces.  Resets the dis-
      tance to the default value if v is omitted.

  .PN x	[ y ]
      Sets x in	an italic or constant width typeface (depending	on the *roff
      formatter	type) and then reverts to the previous typeface. The optional
      argument y is appended to	x with no space, but printed in	the previous
      typeface.	The x argument is usually a path name; y is usually punctua-
      tion.

  .Pn x	y [ z ]
      Sets x in	the current typeface, sets y in	an italic or constant width
      typeface (depending on the *roff formatter type) and appends it to x,
      and finally reverts to the previous typeface.  The optional argument z
      is appended to y,	but printed in the previous typeface.  Spaces are
      removed between x, y, and	z, unless quotation marks (" ")	are used to
      enclose strings with spaces. The x argument is usually a fixed path
      name; y is usually a variable path name; and z is	usually	punctuation.

  .PP Starts a block paragraph.	 Sets the prevailing indent to .5i for nroff
      and four picas for *troff	text formatters.

  .R  Sets the text in a roman typeface	until another font change is encoun-
      tered. Also ends nroff underline mode if it was in effect.

  .RB word1 word2 [ words... ]
      Sets word1 in a roman typeface, word2 in boldface, and then alternates
      between these two	fonts for the remaining	words, up to six words.
      Blanks between words are stripped	unless the string is enclosed in quo-
      tation marks (" ").

  .RE [	k ]
      Returns to the kth relative right	shift indent level.  (Restores the
      left margin to the position prior	to the kth .RS call).  Specifying k=0
      is equivalent to specifying k=1.	If k is	omitted, .RE restores the
      left margin to the most recent previous position.	When k=1 or 0, the
      default .RS indent increment is restored.

  .RI word1 word2 [ words... ]
      Sets word1 in a roman typeface, word2 in an italic typeface, and then
      alternates between these two fonts for the remaining words, up to	six
      words.  Blanks between words are stripped	unless the string is enclosed
      in quotation marks (" ").

  .RN Prints the return	character indicator, <RETURN>.

  .RS [	i ]
      Shifts the left margin to	the right (relatively) the amount of i ens.
      The .RS macro calls can be nested	up to nine levels.  If i is not
      specified	for the	first .RS call,	the relative right shift increases .5
      inch for nroff and four picas for	*troff text formatters.	Nested .RS
      calls increment the relative indent by i ens, or by .2 inch for nroff,
      or by 2 picas for	*troff text formatters.

  .SH text
      Creates a	section	header.

  .SM [	text ]
      Sets text	to be two points smaller than the current point	size.  If no
      text is specified, only the next source text line	is set in the smaller
      point size.

  .SS text
      Creates a	subsection header.

  .TH n	c[s] [fc] [fl] [hc] [o]	[a]
      Begins a new reference page and sets the page title.  Also sets up
      headers and footers for printed output pages, sets up all	defaults and
      traps, and calls the .DT and .PD macros.	The title appears as a header
      on all pages of the formatted reference page. The	n argument is the
      reference	page name.  The	c argument is the primary section number or
      letter. The s argument is	the subsection,	if any.	 The fc	argument is
      optional and specifies the text for the page foot	center.	The fl argu-
      ment is optional and specifies the text for the page foot	left. The hc
      argument is optional and specifies the text for the page head center.
      The o argument is	optional and can be used for "origin" information;
      for example, "Free Software Foundation" or "X11R5." The a	argument is
      optional and can be used to specify the machine architecture, for	exam-
      ple "RISC."

      Fields n,	c, and s appear	together at the	top of each output page	(see
      the top of this page for an example). These fields are displayed at
      both the top left	and right of the screen, or printed page. Fields fc
      and fl are in effect only	with the man.page macro	package, or when
      using a *troff formatter.	 Field hc appears at the top center of each
      output page. Field o, the	"origin" label,	appears	under the reference
      page name	and section number, at the top left and	right sides of the
      screen, or printed page. Field a appears under the "origin" label, or
      under the	reference page name and	section	number if there	is no "ori-
      gin" label, at the top left and right sides of the screen, or printed
      page.

      The last five fields are optional.  To skip a field, specify a pair of
      quotation	marks ("") in the field	to be skipped.

  .TP [	i ]
      Sets the prevailing indent to i.	Then begins the	indented paragraph
      with a hanging tag given by the next text	line.  If the tag does not
      fit, the macro places the	next text on a separate	line.

  .UC [	3|4|5|6|7 ]
      For *troff output	only.  Specifies the text string to be printed as the
      inside page footer.  No argument,	or the number 3, specifies the text
      "3rd Berkeley Distribution." The number 4	specifies the text "4th
      Berkeley Distribution." The number 5 specifies the text "4.2 Berkeley
      Distribution." The number	6 specifies the	text "4.3 Berkeley
      Distribution." The number	7 specifies the	text "4.4 Berkeley Distribu-
      tion."

  .VE End a vertical margin bar.

  .VS [	4 ]
      Starts a vertical	margin bar, if `4' is specified; otherwise, the	macro
      does nothing.

  Macros That Cause Line Breaks


  The following	macros cause line breaks:

  De   DE   Ds	 DS   EE   EX
  HP   IP   PP	 RE   SH   SS
  TH   TP

  Macros That Need Text	Lines


  The following	macros affect the following line of text if they are speci-
  fied in the input without arguments:

  B    BI   BR	 G    GB   GL
  I    IB   IR	 RI   RB   SH
  SS   SM

  Defaults


  Automatic hyphenation	is turned on. However, last lines (ones	that will
  cause	a trap)	are not	hyphenated and the last	and first two characters of a
  word are not split off.

  Characters printed from the Special Font are artificially bolded by three
  units	whenever the current font is `3'.

  The default page width is 77 columns for nroff output	and 8.5	inches for
  output generated by *troff text formatters.  For nroff output, section
  headers and page headers are output flush left, primary paragraphs are
  indented two columns,	and the	maximum	line length is a total of 77 columns
  for an effective right margin	of .3 inches.  This allows for printing	on A4
  paper. Left and right	page margins are 7.5 picas when	*troff text for-
  matters are used.

  The default page length is unlimited (unpaginated) for nroff output with
  the man macros, and is 66 lines long for nroff with the man.page macros.
  The default page length is 11	inches for output generated by *troff text
  formatters.

  The .TH macro	sets up	the following defaults:

    +  Text is set in "noadjust" mode; the right margin	is ragged.

    +  The default interparagraph distance is 1v for nroff and .5v for *troff
       text formatters.

    +  The basic text indent is	two columns for	nroff and four picas for
       *troff text formatters, from the	left margin.

    +  The maximum text	line length is 7.5 inches for nroff and	36 picas for
       *troff text formatters.

    +  Sets tab	stops every 8 ens for nroff and	every .5 inches	for *troff
       text formatters.

    +  The basic text point size is 11 points, with line spacing set to	12
       points.

    +  The basic text font is "R" (a roman typeface).

    +  Reference page headers, section headers,	and subsection headers are
       set in a	sans-serif bold	typeface for *troff formatters.

  There	are no page footers for	nroff output with the man macros.  Page
  footers are printed when using *troff	formatters, and	when using the
  man.page macros with either nroff or *troff.

  The default page number, when	footers	are printed, has the format:

       name(c[s])-pg

  where:

  name
      is the .TH n argument

  c[s]
      is the .TH c[s] argument (section[subsection])

  pg  is the current page number

  By default, the page number prints on	the right side of the page foot.

  When printing	multiple pages,	the page number	is reset to "1"	at the start
  of each new reference	page.

RESTRICTIONS

  Predefined Registers


  The following	registers are predefined by the	man macro packages and should
  not be changed:

  PO  Page offset and page margin

  IN  Left margin indent relative to the section headers

  LL  Line length including IN

  PL  Page length

  The register `l' is predefined when you specify the *roff -rl	option.	Its
  default value	is 0.  The man command does not	use this option.

  The register `n' is predefined when you specify the *roff -rn	option.	 Its
  default value	is 0.  The man command does not	use this option.

  The register `p' is predefined when you specify the *roff -rp	option.	Its
  default value	is 0.  The man command does not	use this option.

  The register `v' is predefined when you specify the *roff -rv	option.	 Its
  default value	is 0.  The man command does not	use this option.








  Reserved Registers


  The following	registers are reserved for internal use	by the man and
  man.page macro packages:

  A1   d    DX	 EX   l	   m
  p    p#   PF	 pg   pn   v
  y

  In addition, registers beginning with	the characters `)', `]', and `}' are
  also reserved	for internal use.

  Registers predefined by the nroff, neqn, and tbl commands, and the *eqn and
  *troff text preprocessors and	formatters should not be redefined.

  Predefined Strings


  The following	strings	are predefined by the man macro	package	and should
  not be changed:

  lq  "	if nroff, " if *troff

  rq  "	if nroff, " if *troff

  S   Command string to	change type size to 10 points.

  Reserved Strings and Macros


  The following	string and macro names are reserved for	internal use by	the
  man and man.page macro packages:

  ##   A1   BD	 BK   CD   D
  HB   HH   ID	 LD   NO   NX
  P    TB   UF	 ya   yn   yl
  ys

  In addition, names beginning with the	characters `)',	`]', and `}' are also
  reserved for internal	use.

  Names	predefined by the nroff, neqn, and tbl commands, and the *eqn and
  *troff text preprocessors and	formatters should not be redefined.

  .TH Macro Restrictions


  Section numbers should only be those listed in the man(1) reference page as
  recognized by	the man	command.

  Sections 5, 6, and the single-letter sections	listed in the man(1) refer-
  ence page normally do	not have subsections, so none should be	specified.

  Subsections ".z" and ".Z" are	not valid and should never be used.

  For nroff output, keep the size of the reference page	name, including	its
  section and subsection, to a maximum of 38 characters	to prevent overprint-
  ing in the reference page header.  Similarly,	restrict the size of the o
  and a	fields to a maximum of 38 characters. If the hc	field is used, reduce
  the size of the name,	section, and subsection	fields by the size of the hc
  field	+ 1.

  The maximum sizes for	the reference page name, o and a fields, are much
  shorter if the reference page	is formatted with a *troff formatter.







  The NAME Section


  The catman command assumes the NAME section of a reference page has the
  following format:

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

  There	should be at least one space after any comma and only one space	fol-
  lowing the "hyphen" (-).  A "backslash hyphen" (\-) may also be used to
  produce a longer dash. Avoid using macros or other markup to code informa-
  tion in the NAME section. The	explanatory text should	be brief. The catman
  command combines information in the NAME section with	parameters of the .TH
  macro	to create an entry in a	database searched by the apropos, man, and
  whatis commands.

PORTABILITY CONSIDERATIONS

  The Tru64 UNIX man macro packages contain extensions and enhancements	bor-
  rowed	from other macro packages.  If you need	to write portable reference
  pages, you should not	use the	following macros:

  AT   CM   CT	 CW   De   Ds
  EE   EX   G	 GB   GL   I1
  I2   LP   MS	 NE   NT   PN
  Pn   R    RN	 UC   UF

  The .LP macro	is obsolete, but is provided for backward compatibility	with
  other	vendors.

  The .TH macro	permits	the use	of the percent (%) character in	any of its
  fields.  The presence	of the percent character may cause problems for	other
  implementations of this macro.

  The width of the nroff output	is 77 columns, with a 2-column indent, for an
  effective maximum line length	of 75 columns. On other	systems, the width of
  the nroff output may be only 65 columns, with	a 5-column indent, for an
  effective maximum line length	of 60 columns.	Avoid creating tables and
  no-fill text that require the	full 75	columns	available. Plan	for a maximum
  line length of 60 columns, instead.

FILES

  /usr/share/lib/tmac/tmac.an
      The man macro package interface

  /usr/share/lib/tmac/tmac.an.new
      The primary man macros package

  /usr/share/lib/tmac/tmac.an6n
      Old BSD V6 man macros for	nroff

  /usr/share/lib/tmac/tmac.an6t
      Old BSD V6 man macros for	troff

  /usr/share/lib/tmac/tmac.an.page
      The man.page macro package interface

  /usr/share/lib/tmac/tman.an.new.page
      The primary man.page macros package






SEE ALSO

  Commands: checkeq(1),	man(1),	neqn(1), nroff(1), tbl(1), catman(8)

  Files: rsml(5)