gno/usr.bin/nroff/man.7

.\" man(7) manpage by rosenkra@convex.com (Bill Rosenkranz, 7/22/90)
.\"          modifications by Devin Reade, 18 March 97
.\"
.\" $Id: man.7,v 1.4 1998/01/27 16:02:18 gdr-ftp Exp $
.\"
.TH MAN 7 "19 October 1997" GNO "Miscellaneous"
.SH NAME
man - nroff macro package for manual pages
.SH SYNOPSIS
.BR nroff
.BR -man
.IR file ...
.SH DESCRIPTION
These macros are used to lay out reference pages for manuals.
.PP
Any text argument
.I t
may be zero to six words.
Quotes may be used to include blanks in a 'word'.
Text
can be empty, but unlike normal Unix macros, the next line is not used.
.PP
A prevailing indent distance is remembered between successive
indented paragraphs, and is reset to default value upon
reaching a non-indented paragraph (i.e. at .SH or .SS).
In contrast with normal Unix procedure, all indents (tabs) are 8 spaces
instead of 5.
This can be changed by modifying tmac.an.
.SH "REQUEST SUMMARY"
.nf
.cc +
Request        Cause    Explanation
               Break?

.B t ...       no	Text \fIt\fR and subsequent arguments
			are bold.  Quote to imbed blanks.
			There is no intervening space.
.I t ...       no	Text \fIt\fR and subsequent arguments
			are italic.  Quote to imbed blanks.
			There is no intervening space.
.R t ...       no	Text \fIt\fR and subsequent arguments
			are roman.  Quote to imbed blanks.
			There is no intervening space.
.BR t ...      no	Alternate bold and roman fonts for
			specified arguments.  There is no
			intervening space.
.RB t ...      no	Alternate roman and bold fonts for
			specified arguments.  There is no
			intervening space.
.IR t ...      no	Alternate italic and roman fonts for
			specified arguments.  There is no
			intervening space.
.RI t ...      no	Alternate roman and italic fonts for
			specified arguments.  There is no
			intervening space.
.LP            yes      Begin paragraph. Set prevailing
                        indent to 8.
.PP            yes      Same as .LP.
.IP x          yes      Set prevailing indent to 8. Begin
                        indented paragraph with hanging tag
                        given by first argument. Tag \fIx\fR is
                        always placed on a separate line.
.TP x          yes	Same as .IP.  Note that this is a deviation from
			normal Unix usage.  This macro should be avoided
			until it is fixed.
.HP            yes	Indented paragraph without tag.
.RE            yes      End of relative indent. Set prevailing
                        indent to amount of starting .RS.
.RP x          yes      Like .IP, but use relative indent. Must
                        end the section with .RE.
.RS            yes      Start relative indent, move left margin
                        in distance 8.
.SH t          yes      Subhead. Quote to imbed blanks.
.SS t          yes      Subsection. Quote to imbed blanks. No
                        indent for \fBt\fR.
.TH n s d v c  yes      Begin page named \fIn\fR of chapter number \fIs\fR.
			\fId\fR is the date of the most recent change
			or the current date (prefixed by
			"\fBPrinted:\fR") if not specified.  \fIv\fR is the
			version number, or \fBGNO\fR if not specified.
			\fIc\fR is the chapter name.  If \fIc\fR is not
			specified, it is derived based on the
			value of \fIs\fR.
                        Sets prevailing indent and tabs to 8.
.EX            no	Exit now, leaving no extra space the
			end of the document.

+cc .
.fi
.ne 8
.SH EXAMPLE
The following illustrates some of the requests available
with this macro package:
.RS
.nf
.cc +

.\\\|" this is a comment
.TH DEMO 1 "\\\|*\|(DA" "Version 1.0" "Commands Manual"
.SH NAME
demo - show how to use -man package  \\\|" this is a comment
.SH SYNOPSIS
demo [options] file [...]
.SH DESCRIPTION
This is a test for showing how to use the
.I nroff(1)
man package.
It shows how to use .TH, .SH, .PP, .I, and .IP commands.
.PP
This will be a new paragraph.
You can also use normal
.I nroff(1)
commands in the text.
.SS NROFF COMMANDS:
.IP '\\\\\|"'
This is the comment command.
Note how you have to quote this sucker!
You'll probably never have to write an
.I nroff(1)
manpage, so don't worry about it.
.IP nf
No fill mode (the normal mode is fill mode where things
get justified right and left).
.IP fi
Re-enter fill mode.
.IP br
Break line here no matter what.
.IP sp
Vertical space (also causes a break to occur).
.sp
Note that to continue an indent and make a new paragraph (as
is the case here), just put in a space (.sp).
.PP
Now we should be at a new paragraph.

+cc .
.fi
.RE
.ne 8
Executing 'nroff -man demo.man' results in the following output:
.RS
.nf
.cc +

DEMO (1)                Commands Manual                DEMO (1)

NAME
     demo - show how to use -man package

SYNOPSIS
     demo [options] file [...]

DESCRIPTION
     This is a test  for  showing  how  to  use the nroff(1)
     man package.    It  shows how to use .TH, .SH, .PP, .I,
     and .IP commands.

     This will be a new paragraph.  You can also use  normal
     nroff(1) commands in the text.

     NROFF COMMANDS:

     \\\|"
          This is the comment command.  Note how you have to
          quote this  sucker!  You'll probably never have to
          write an nroff(1)  manpage,  so  don't worry about
          it.

     nf
          No  fill  mode (the normal mode is fill mode where
          things get justified right and left).

     fi
          Re-enter fill mode.

     br
          Break line here no matter what.

     sp
          Vertical space (also causes a break to occur).

          Note that to continue an indent  and  make  a  new
          paragraph  (as  is  the  case here), just put in a
          space (.sp).

     Now we should be at a new paragraph.

Version 1.0             23:33:57 2/25/90                       1


+cc .
.fi
.RE
.ne 8
.SH CONVENTIONS
A typical manual page for a command or function is laid out as follows:
.sp
.RS
.SS ".TH TITLE [1-8]"
The name of the command or function in upper-case,
which serves as the title of the manual page.
This is followed by the number of the section in which it appears.
.SS ".SH NAME"
name - one-line summary
.PP
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 whatis(1) database.
.SS ".SH SYNOPSIS"
Commands:
.sp
.RS
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 text that you supply.
Syntactic symbols appear in roman face:
.RP "[ ]"
An argument, when surrounded by brackets is optional.
.RE
.RP |
Arguments separated by a vertical bar are exclusive.
You can supply only item from such a list.
.RE
.RP ...
Arguments followed by an elipsis can be repeated.
When an elipsis follows a bracketed set, the expression within the
brackets can be repeated.
.RE
.RE
.sp
Functions:
.sp
.RS
If required, the data declaration, or #include directive, is shown first,
followed by the function declaration.
Otherwise, the function declaration is shown.
.RE
.SS ".SH DESCRIPTION"
A narrative description of the command or function in detail, including
how it interacts with files or data, and how it handles the standard
input, standard output and standard error.
.PP
Filenames, and references to commands or functions described elswhere
in the manual, are italicised.
The names of options, variables and other literal terms are
in boldface.
.SS ".SH OPTIONS"
The list of options along with a description of how each affects the
commands operation.
.SS ".SH FILES"
A list of files associated with the command or function.
.SS '.SH "SEE ALSO"'
A comma-separated list of related manual pages, followed by references
to other published materials.
This section contains no troff(1) escapes or commands, and no macro requests.
.SS ".SH DIAGNOSTICS"
A list of diagnostic messages and an explanation of each.
.SS ".SH NOTES"
Any additional notes such as installation-dependent functionality.
.SS ".SH BUGS"
A description of limitations, known defects, and possible problems
associated with the command or function.
.SS ".SH AUTHOR"
The program's author and any pertinent release info.
.SS ".SH VERSION"
The program's current version number and release date.
.RE
.SH AUTHOR
.nf
Adapted for Atari ST (TOS) and Minix by Bill Rosenkranz

net:    rosenkra@convex.com
CIS:    71460,17
GENIE:  W.ROSENKRANZ
.fi
.SH FILES
\fB/usr/lib/tmac/tmac.an\fR \- the macro library
.SH SEE ALSO
nroff(1), man(1)