-.\" $Id: man.7,v 1.91 2010/12/06 15:31:19 kristaps Exp $
+.\" $Id: man.7,v 1.101 2011/07/03 22:57:32 kristaps Exp $
.\"
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: December 6 2010 $
+.Dd $Mdocdate: July 3 2011 $
.Dt MAN 7
.Os
.Sh NAME
.Nm
documents may contain only graphable 7-bit ASCII characters, the
space character, and the tab character.
-All manuals must have
-.Ux
-line termination.
.Pp
Blank lines are acceptable; where found, the output will assert a
vertical space.
+.Pp
+If the first character of a line is a space, that line is printed
+with a leading newline.
.Ss Comments
Text following a
.Sq \e\*q ,
.Pp
In macro lines, whitespace delimits arguments and is discarded.
If arguments are quoted, whitespace within the quotes is retained.
-.Ss Dates
-The
-.Sx \&TH
-macro is the only
-.Nm
-macro that requires a date.
-The form for this date is the ISO-8601
-standard
-.Cm YYYY-MM-DD .
.Ss Scaling Widths
Many macros support scaled widths for their arguments, such as
stipulating a two-inch paragraph indentation with the following:
Beyond
.Sx \&TH ,
at least one macro or text node must appear in the document.
-Documents are generally structured as follows:
+.Pp
+The following is a well-formed skeleton
+.Nm
+file for a utility
+.Qq progname :
.Bd -literal -offset indent
-\&.TH FOO 1 2009-10-10
+\&.TH PROGNAME 1 2009-10-10
\&.SH NAME
-\efBfoo\efR \e(en a description goes here
+\efBprogname\efR \e(en a description goes here
\&.\e\*q .SH LIBRARY
\&.\e\*q For sections 2 & 3 only.
\&.\e\*q Not used in OpenBSD.
\&.SH SYNOPSIS
-\efBfoo\efR [\efB\e-options\efR] arguments...
+\efBprogname\efR [\efB\e-options\efR] arguments...
\&.SH DESCRIPTION
The \efBfoo\efR utility processes files...
\&.\e\*q .SH IMPLEMENTATION NOTES
\&.\ \ \ PP
.Ed
.Pp
+To include space characters in macro arguments, arguments may be quoted;
+see the
+.Sq MACRO SYNTAX
+section in the
+.Xr roff 7
+manual for details.
+.Pp
The
.Nm
macros are classified by scope: line scope or block scope.
.It Sx \&br Ta 0 Ta current Ta compat
.It Sx \&fi Ta 0 Ta current Ta compat
.It Sx \&ft Ta 1 Ta current Ta compat
-.It Sx \&i Ta n Ta current Ta compat
.It Sx \&in Ta 1 Ta current Ta compat
.It Sx \&na Ta 0 Ta current Ta compat
.It Sx \&nf Ta 0 Ta current Ta compat
-.It Sx \&r Ta 0 Ta current Ta compat
.It Sx \&sp Ta 1 Ta current Ta compat
.El
.Pp
Text is rendered in bold face.
.Pp
See also
-.Sx \&I ,
-.Sx \&R ,
-.Sx \&b ,
-.Sx \&i ,
+.Sx \&I
and
-.Sx \&r .
+.Sx \&R .
.Ss \&BI
Text is rendered alternately in bold face and italic.
Thus,
.Pp
Examples:
.Pp
-.D1 \&.BI bold italic bold italic
+.Dl \&.BI bold italic bold italic
.Pp
The output of this example will be emboldened
.Dq bold
Text is rendered in italics.
.Pp
See also
-.Sx \&B ,
-.Sx \&R ,
-.Sx \&b ,
-.Sx \&i ,
+.Sx \&B
and
-.Sx \&r .
+.Sx \&R .
.Ss \&IB
Text is rendered alternately in italics and bold face.
Whitespace between arguments is omitted in output.
Text is rendered in roman (the default font).
.Pp
See also
-.Sx \&I ,
-.Sx \&B ,
-.Sx \&b ,
-.Sx \&i ,
+.Sx \&I
and
-.Sx \&r .
+.Sx \&B .
.Ss \&RB
Text is rendered alternately in roman (the default font) and bold face.
Whitespace between arguments is omitted in output.
Sets the title of the manual page with the following syntax:
.Bd -filled -offset indent
.Pf \. Sx \&TH
-.Cm title section
-.Op Cm date Op Cm source Op Cm volume
+.Ar title section date
+.Op Ar source Op Ar volume
.Ed
.Pp
-At least the upper-case document
-.Cm title
-and the manual
-.Cm section
-arguments must be provided.
-The
-.Cm date
-argument should be formatted as described in
-.Sx Dates ,
-but will be printed verbatim if it is not.
-If the date is not specified, the current date is used.
-The
-.Cm source
+Conventionally, the document
+.Ar title
+is given in all caps.
+The recommended
+.Ar date
+format is
+.Sy YYYY-MM-DD
+as specified in the ISO-8601 standard;
+if the argument does not conform, it is printed verbatim.
+If the
+.Ar date
+is empty or not specified, the current date is used.
+The optional
+.Ar source
string specifies the organisation providing the utility.
The
-.Cm volume
+.Ar volume
string replaces the default rendered volume, which is dictated by the
manual section.
.Pp
Examples:
.Pp
-.D1 \&.TH CVS 5 "1992-02-12" GNU
+.Dl \&.TH CVS 5 "1992-02-12" GNU
.Ss \&TP
Begin a paragraph where the head, if exceeding the indentation width, is
followed by a newline; if not, the body follows on the same line after a
See
.Sx Text Decoration
for a listing of available font modes.
-.Ss \&i
-Italicise arguments.
-Synonym for
-.Sx \&I .
-.Pp
-See also
-.Sx \&B ,
-.Sx \&I ,
-.Sx \&R .
-.Sx \&b ,
-and
-.Sx \&r .
.Ss \&in
Indent relative to the current indentation:
.Pp
line boundaries preserved.
May be ended by
.Sx \&fi .
-.Ss \&r
-Fonts and styles (bold face, italics) reset to roman (default font).
-.Pp
-See also
-.Sx \&B ,
-.Sx \&I ,
-.Sx \&R ,
-.Sx \&b ,
-and
-.Sx \&i .
+Literal mode is implicitly ended by
+.Sx \&SH
+or
+.Sx \&SS .
.Ss \&sp
Insert vertical spaces into output with the following syntax:
.Bd -filled -offset indent
.Sh SEE ALSO
.Xr man 1 ,
.Xr mandoc 1 ,
+.Xr eqn 7 ,
.Xr mandoc_char 7 ,
-.Xr mdoc 7
+.Xr mdoc 7 ,
+.Xr roff 7 ,
+.Xr tbl 7
.Sh HISTORY
The
.Nm
git.ckatri.com / mandoc.git / blobdiff