man(5)							Standards, Environments, and Macros						    man(5)

NAME

       man - macros to format Reference Manual pages

SYNOPSIS

       nroff -man filename...

       troff  -man filename...

DESCRIPTION

       These  macros  are used to lay out the reference pages in this manual. Note: if filename contains format input for a preprocessor, the com-
       mands shown above must be piped through the appropriate preprocessor. This is handled automatically by the man(1) command. See  the  ``Con-
       ventions'' section.

       Any  text  argument  t may be zero to six words. Quotes may be used to include SPACE characters in a "word".  If text is empty, the special
       treatment is applied to the next input line with text to be printed. In this way .I may be used to italicize a whole line, or  .SB  may	be
       used to make small bold letters.

       A  prevailing  indent  distance	is  remembered	between successive indented paragraphs, and is reset to default value upon reaching a non-
       indented paragraph.  Default units for indents i are ens.

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

       These strings are predefined by -man:

       *R     `(R)', `(Reg)' in nroff.

       *S     Change to default type size.

   Requests
       * n.t.l. = next text line; p.i. = prevailing indent

	  Request	 Cause	      If no		       Explanation
			 Break	     Argument
	   .B t 	   no	    t=n.t.l.*		  Text is in bold font.
	   .BI t	   no	     t=n.t.l.	 Join words, alternating bold and italic.
	   .BR t	   no	     t=n.t.l.	 Join words, alternating bold and roman.
	    .DT 	   no	    .5i 1i...		  Restore default tabs.
	   .HP i	  yes	     i=p.i.*	 Begin paragraph with hanging indent. Set
						 prevailing indent to i.
	   .I t 	   no	     t=n.t.l.		     Text is italic.
	   .IB t	   no	     t=n.t.l.	 Join words, alternating italic and bold.
	  .IP x i	  yes	       x=""		 Same as .TP with tag x.
	   .IR t	   no	     t=n.t.l.	 Join	words,	 alternating  italic  and
						 roman.
	   .IX t	   no		-	  Index macro, for SunSoft internal use.
	    .LP 	  yes		-	 Begin left-aligned paragraph.	Set  pre-
						 vailing indent to .5i.
	    .P		  yes		-		       Same as .LP.
	   .PD d	   no	      d=.4v	 Set   vertical  distance  between  para-
						 graphs.

	    .PP 	  yes		-		       Same as .LP.
	    .RE 	  yes		-	 End of relative  indent.  Restores  pre-
						 vailing indent.
	   .RB t	   no	     t=n.t.l.	 Join words, alternating roman and bold.
	   .RI t	   no	     t=n.t.l.	 Join	words,	 alternating   roman  and
						 italic.
	   .RS i	  yes	      i=p.i.	 Start relative indent,  increase  indent
						 by  i. Sets prevailing indent to .5i for
						 nested indents.
	   .SB t	   no		-	 Reduce size of text  by  1  point,  make
						 text bold.
	   .SH t	  yes		-		     Section Heading.
	   .SM t	   no	     t=n.t.l.	     Reduce size of text by 1 point.
	   .SS t	  yes	     t=n.t.l.		   Section Subheading.
       .TH n s d f m	  yes		-	 Begin reference page n, of of section s;
						 d is the date of the most recent change.
						 If present, f is the left page footer; m
						 is the main page (center) header.   Sets
						 prevailing indent and tabs to .5i.
	   .TP i	  yes	      i=p.i.	 Begin	indented  paragraph, with the tag
						 given on the next text  line.	Set  pre-
						 vailing indent to i.
	  .TX t p	   no		-	 Resolve  the  title abbreviation t; join
						 to punctuation mark (or text) p.

   Conventions
       When formatting a manual page, man examines the first line to determine whether it requires special processing. For example  a  first  line
       consisting of:

       '" t

       indicates that the manual page must be run through the tbl(1) preprocessor.

       A typical manual page for a command or function is laid out as follows:

       .TH title [1-9]	      The name of the command or function, which serves as the title of the manual page. This is followed by the number of
			      the section in which it appears.

       .SH NAME 	      The name, or list of names, by which the command is called, followed by a dash and then a one-line  summary  of  the
			      action  performed.  All in roman font, this section contains no troff(1) commands or escapes, and no macro requests.
			      It is used to generate the windex database, which is used by the	whatis(1) command.

       .SH SYNOPSIS
			      Commands:    The syntax of the command and its arguments, as typed on the command line.  When in	boldface,  a  word
					   must  be  typed  exactly as printed.  When in italics, a word can be replaced with an argument that you
					   supply. References to bold or italicized items are not capitalized in other sections,  even	when  they
					   begin a sentence.

					   Syntactic symbols appear in roman face:

					   [ ]		An argument, when surrounded by brackets is optional.

					   |		Arguments  separated  by  a  vertical bar are exclusive. You can supply only one item from
							such a list.

					   ...		Arguments followed by an ellipsis can be repeated. When an ellipsis  follows  a  bracketed
							set, the expression within the brackets can be repeated.

			      Functions:    If	required,  the	data declaration, or #include directive, is shown first, followed by the  function
					    declaration. Otherwise, the function declaration is shown.

       .SH DESCRIPTION	      A narrative overview of the command or function's external behavior. This includes how it interacts  with  files	or
			      data,  and  how  it  handles  the  standard  input, standard output and standard error. Internals and implementation
			      details are normally omitted. This section attempts to provide a succinct overview in answer to the question,  "what
			      does it do?"

			      Literal  text  from  the	synopsis  appears  in constant width, as do literal filenames and references to items that
			      appear elsewhere in the  reference manuals. Arguments are italicized.

			      If a command interprets either subcommands or an input grammar, its command interface or input grammar  is  normally
			      described in a USAGE section, which follows the OPTIONS section.	The  DESCRIPTION section only describes the behav-
			      ior of the command itself, not that of subcommands.

       .SH OPTIONS	      The list of options along with a description of how each affects the command's operation.

       .SH RETURN VALUES      A list of the values the library routine will return to the calling  program and the  conditions	that  cause  these
			      values to be returned.

       .SH EXIT STATUS	      A  list  of the values the utility will return to the calling  program or shell, and the conditions that cause these
			      values to be  returned.

       .SH FILES	      A list of files associated with the command or function.

       .SH SEE ALSO	      A comma-separated list of related manual pages, followed by references to other published materials.

       .SH DIAGNOSTICS	      A list of diagnostic messages and an explanation of each.

       .SH BUGS 	      A description of limitations, known defects, and possible problems associated with the command or function.

FILES

       /usr/share/lib/tmac/an

       /usr/share/man/windex

SEE ALSO

       man(1), nroff(1), troff(1), whatis(1)

       Dale Dougherty and   Tim O'Reilly, Unix Text Processing

SunOS 5.11							    30 Jan 1995 							    man(5)