.\" $Id$
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the
.\" above copyright notice and this permission notice appear in all
.\" copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\" 
.Dd $Mdocdate$
.Dt man 7
.Os
.\" SECTION
.Sh NAME
.Nm man
.Nd man language reference
.\" SECTION
.Sh DESCRIPTION
The
.Nm man
language was historically used to format 
.Ux
manuals.  In this reference document, we describe the syntax and
structure of the 
.Nm
language.
.Pp
.Em \&Do not
use 
.Nm
to write your manuals.  Use the
.Xr mdoc 7
language, instead.
.\" PARAGRAPH
.Pp
An
.Nm
document follows simple rules:  lines beginning with the control
character 
.Sq \&.
are parsed for macros.  Other lines are interpreted within the scope of
prior macros:
.Bd -literal -offset XXX
\&.SH Macro lines change control state.
Other lines are interpreted within the current state.
.Ed
.\" PARAGRAPH
.Pp
Macros are character sequences whose structural rules are described
later in this document.
.\" SECTION
.Sh INPUT ENCODING
.Nm
documents may contain only graphable 7-bit ASCII characters and the
space character
.Sq \  .
All manuals must have
.Sq \en
line termination.  
.Pp
Blank lines are acceptable; where found, the output will also assert a
vertical space.
.\" SUB-SECTION
.Ss Special Characters
Special character sequences begin with the escape character
.Sq \e
followed by either an open-parenthesis 
.Sq \&(
for two-character sequences; an open-bracket
.Sq \&[
for n-character sequences (terminated at a close-bracket
.Sq \&] ) ;
or a single one-character sequence.
.Pp
Characters may alternatively be escaped by a slash-asterisk,
.Sq \e* ,
with the same combinations as described above.  This form is deprecated.  
.Pp
The 
.Xr mdoc 7
contains a table of all available escapes.
.\" SECTION
.Sh STRUCTURE
Macros are one to three three characters in length and begin with a
control character 
.Sq \&.
at the beginning of the line.  An arbitrary amount of whitespace may
sit between the control character and the macro name.  Thus,
.Sq \&PP
and
.Sq \&.\ \ \ \&PP
are equivalent.
.Pp
All follow the same
structural rules:
.Bd -literal -offset XXXX
\&.Yo \(lBbody...\(rB 
.Ed
.Pp
The
.Dq body
consists of zero or more arguments to the macro.
.\" PARAGRAPH
.Sh MACROS
This section contains a complete list of all 
.Nm
macros, arranged alphabetically, with the number of arguments.
.Pp
.Bl -column "MacroX" "Arguments" -compact -offset XXXX
.It Em Macro Ta Em Arguments
.It \&.TH    Ta    >0
.It \&.SH    Ta    n
.It \&.SS    Ta    n
.It \&.TP    Ta    n
.It \&.LP    Ta    n
.It \&.PP    Ta    n
.It \&.P     Ta    n
.It \&.IP    Ta    n
.It \&.HP    Ta    n
.It \&.SM    Ta    n
.It \&.SB    Ta    n
.It \&.BI    Ta    n
.It \&.IB    Ta    n
.It \&.BR    Ta    n
.It \&.RB    Ta    n
.It \&.R     Ta    n
.It \&.B     Ta    n
.It \&.I     Ta    n
.It \&.IR    Ta    n
.El
.\" SECTION
.Sh SEE ALSO
.Xr mandoc 1
.\" SECTION
.Sh AUTHORS
The
.Nm
utility was written by 
.An Kristaps Dzonsons Aq kristaps@openbsd.org .
.\" SECTION
.Sh CAVEATS
Do not use this language.  Use
.Xr mdoc 7 ,
instead.