-.\" $Id: man.7,v 1.83 2010/08/24 12:18:48 kristaps Exp $
+.\" $Id: man.7,v 1.105 2011/08/18 08:58:43 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: August 24 2010 $
+.Dd $Mdocdate: August 18 2011 $
.Dt MAN 7
.Os
.Sh NAME
\&.SH Macro lines change control state.
Other lines are interpreted within the current state.
.Ed
-.Sh INPUT ENCODING
+.Sh LANGUAGE SYNTAX
.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.
+The back-space character
+.Sq \e
+indicates the start of an escape sequence for
+.Sx Comments ,
+.Sx Predefined Strings ,
+and
+.Sx Special Characters .
.Ss Comments
-Text following a
+Text following an escaped double-quote
.Sq \e\*q ,
-whether in a macro or free-form text line, is ignored to the end of
+whether in a macro or text line, is ignored to the end of
line.
-A macro line with only a control character and comment escape,
-.Sq \&.\e\*q ,
+A macro line beginning with a control character and comment escape
+.Sq \&.\e\*q
is also ignored.
-Macro lines with only a control character and optionally whitespace are
+Furthermore,
+macro lines with only a control character and optional trailing
+whitespace are
stripped from input.
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+\&.\e\*q This is a comment line.
+\&.\e\*q The next line is ignored:
+\&.
+\&.Em Emphasis \e\*q This is also a comment.
+.Ed
.Ss Special Characters
-Special characters may occur in both macro and free-form lines.
+Special characters are used to encode special glyphs and are rendered
+differently across output media.
+They may occur in both macro and text lines.
Sequences begin with the escape character
.Sq \e
followed by either an open-parenthesis
.Sq \&[
for n-character sequences (terminated at a close-bracket
.Sq \&] ) ;
-or a single one-character sequence.
+or a single one character sequence.
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It \e(em
+em dash
+.It \ee
+backslash
+.El
+.Pp
See
.Xr mandoc_char 7
for a complete list.
-Examples include
-.Sq \e(em
-.Pq em-dash
-and
-.Sq \ee
-.Pq back-slash .
.Ss Text Decoration
Terms may be text-decorated using the
.Sq \ef
-escape followed by an indicator: B (bold), I (italic), R (Roman), or P
+escape followed by an indicator: B (bold), I (italic), R (regular), or P
(revert to previous mode):
-.Pp
-.D1 \efBbold\efR \efIitalic\efP
-.Pp
-A numerical representation 3, 2, or 1 (bold, italic, and Roman,
+A numerical representation 3, 2, or 1 (bold, italic, and regular,
respectively) may be used instead.
A text decoration is only valid, if specified in free-form text, until
the next macro invocation; if specified within a macro, it's only valid
The
.Sq \ef
attribute is forgotten when entering or exiting a macro block.
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It \efBbold\efR
+write in bold, then switch to regular
+.It \efIitalic\efP
+write in italic, then return to previous
+.El
+.Ss Predefined Strings
+Predefined strings, like
+.Sx Special Characters ,
+mark special output glyphs.
+Predefined strings are escaped with the slash-asterisk,
+.Sq \e* :
+single-character
+.Sq \e*X ,
+two-character
+.Sq \e*(XX ,
+and N-character
+.Sq \e*[N] .
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It \e*(Am
+ampersand
+.It \e*(Ba
+vertical bar
+.El
+.Pp
+These strings are set using
+.Xr roff 7 ,
+although
+.Nm
+consists of several pre-set escapes listed in
+.Xr mandoc_char 7 .
.Ss Whitespace
Whitespace consists of the space character.
-In free-form lines, whitespace is preserved within a line; unescaped
-trailing spaces are stripped from input (unless in a literal context).
-Blank free-form lines, which may include spaces, are permitted and
-rendered as an empty line.
-.Pp
+In text lines, whitespace is preserved within a line.
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:
-.Bd -literal -offset indent
-\&.HP 2i
-.Ed
.Pp
-The syntax for scaled widths is
-.Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,
+Unescaped trailing spaces are stripped from text line input unless in a
+literal context.
+In general, trailing whitespace on any input line is discouraged for
+reasons of portability.
+In the rare case that a blank character is needed at the end of an
+input line, it may be forced by
+.Sq \e\ \e& .
+.Pp
+If the first character of a text line is a space, that line is printed
+with a leading newline.
+.Ss Quotation
+Macro arguments may be quoted with double-quotes; in this case,
+whitespace within the quotes is retained as part of the argument.
+.Pp
+A quoted argument begins with a double-quote preceded by whitespace.
+The next double-quote not pairwise adjacent to another double-quote
+terminates the literal, regardless of surrounding whitespace.
+.Pp
+In unquoted arguments, space characters can alternatively be included
+by preceding them with a backslash
+.Pq Sq \e\~ ,
+but quoting is usually better for clarity.
+.Pp
+Note that any quoted text, even if it would cause a macro invocation
+when unquoted, is considered literal text.
+.Pp
+In text lines, quotes are regarded as opaque text.
+.Ss Scaling Widths
+Many macros support scaled widths for their arguments.
+The syntax for a scaled width is
+.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
where a decimal must be preceded or proceeded by at least one digit.
Negative numbers, while accepted, are truncated to zero.
+.Pp
The following scaling units are accepted:
.Pp
.Bl -tag -width Ds -offset indent -compact
or
.Sq v
is necessarily non-portable across output media.
+See
+.Sx COMPATIBILITY .
.Pp
If a scaling unit is not provided, the numerical value is interpreted
under the default rules of
for vertical spaces and
.Sq u
for horizontal ones.
-.Em Note :
-this differs from
-.Xr mdoc 7 ,
-which, if a unit is not provided, will instead interpret the string as
-literal text.
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It \&.HP 2i
+two-inch tagged list indentation
+.Pq see Sx \&HP
+.It \&.sp 2v
+two vertical spaces
+.Pq see Sx \&sp
+.El
.Ss Sentence Spacing
-When composing a manual, make sure that sentences end at the end of
-a line.
-By doing so, front-ends will be able to apply the proper amount of
+Sentences should terminate at the end of an input line.
+By doing this, a formatter will be able to apply the proper amount of
spacing after the end of sentence (unescaped) period, exclamation mark,
or question mark followed by zero or more non-sentence closing
delimiters
.Sq \&' ,
.Sq \&"
.Pc .
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+Do not end sentences mid-line like this. Instead,
+end a sentence like this.
+A new sentence gets a new line.
+.Ed
.Sh MANUAL STRUCTURE
Each
.Nm
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
-\&.\e\*q The next is for sections 2 & 3 only.
+\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
-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.
\&.\e\*q .SH RETURN VALUES
-\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.
\&.\e\*q .SH ENVIRONMENT
+\&.\e\*q For sections 1, 6, 7, & 8 only.
\&.\e\*q .SH FILES
-\&.\e\*q The next is for sections 1 & 8 only.
\&.\e\*q .SH EXIT STATUS
+\&.\e\*q For sections 1, 6, & 8 only.
\&.\e\*q .SH EXAMPLES
-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
\&.\e\*q .SH DIAGNOSTICS
-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q For sections 1, 4, 6, 7, & 8 only.
\&.\e\*q .SH ERRORS
+\&.\e\*q For sections 2, 3, & 9 only.
\&.\e\*q .SH SEE ALSO
\&.\e\*q .BR foo ( 1 )
\&.\e\*q .SH STANDARDS
\&.\e\*q .SH CAVEATS
\&.\e\*q .SH BUGS
\&.\e\*q .SH SECURITY CONSIDERATIONS
+\&.\e\*q Not used in OpenBSD.
.Ed
.Pp
The sections in a
\&.\ \ \ 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 \&I Ta n Ta next-line Ta \&
.It Sx \&IB Ta n Ta current Ta \&
.It Sx \&IR Ta n Ta current Ta \&
-.\" .It Sx \&PD Ta n Ta current Ta compat
.It Sx \&R Ta n Ta next-line Ta \&
.It Sx \&RB Ta n Ta current Ta \&
.It Sx \&RI Ta n Ta current Ta \&
.It Sx \&UC Ta <=1 Ta current Ta \&
.It Sx \&br Ta 0 Ta current Ta compat
.It Sx \&fi Ta 0 Ta current Ta compat
-.It Sx \&i Ta n Ta current Ta compat
+.It Sx \&ft Ta 1 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
-.\" .It Sx \&Sp Ta <1 Ta current Ta compat
-.\" .It Sx \&Vb Ta <1 Ta current Ta compat
-.\" .It Sx \&Ve Ta 0 Ta current Ta compat
.El
.Pp
Macros marked as
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.
.Ss \&RE
Explicitly close out the scope of a prior
.Sx \&RS .
+The default left margin is restored to the state of the original
+.Sx \&RS
+invocation.
.Ss \&RI
Text is rendered alternately in roman (the default font) and italics.
Whitespace between arguments is omitted in output.
and
.Sx \&IR .
.Ss \&RS
-Begin a part setting the left margin.
-The left margin controls the offset, following an initial indentation,
-to un-indented text such as that of
-.Sx \&PP .
+Temporarily reset the default left margin.
This has the following syntax:
.Bd -filled -offset indent
-.Pf \. Sx \&Rs
+.Pf \. Sx \&RS
.Op Cm width
.Ed
.Pp
argument must conform to
.Sx Scaling Widths .
If not specified, the saved or default width is used.
+.Pp
+See also
+.Sx \&RE .
.Ss \&SB
Text is rendered in small size (one point smaller than the default font)
bold face.
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
.Sx \&P ,
and
.Sx \&PP .
-.\" .
-.\" .
-.\" .Ss \&PD
-.\" Has no effect. Included for compatibility.
-.\" .
-.\" .
.Ss \&UC
Sets the volume for the footer for compatibility with man pages from
BSD releases.
.Ss \&fi
End literal mode begun by
.Sx \&nf .
-.Ss \&i
-Italicise arguments.
-Synonym for
-.Sx \&I .
-.Pp
-See also
-.Sx \&B ,
-.Sx \&I ,
-.Sx \&R .
-.Sx \&b ,
-and
-.Sx \&r .
+.Ss \&ft
+Change the current font mode.
+See
+.Sx Text Decoration
+for a listing of available font modes.
.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
.Pp
See also
.Sx \&br .
-.\" .Ss \&Sp
-.\" A synonym for
-.\" .Sx \&sp
-.\" .Cm 0.5v .
-.\" .
-.\" .Ss \&Vb
-.\" A synonym for
-.\" .Sx \&nf .
-.\" Accepts an argument (the height of the formatted space) which is
-.\" disregarded.
-.\" .
-.\" .Ss \&Ve
-.\" A synonym for
-.\" .Sx \&fi .
-.\" .
.Sh COMPATIBILITY
This section documents areas of questionable portability between
implementations of the
.Pq text filling colour ,
.Sq \ez
.Pq zero-length character ,
+.Sq \ew
+.Pq string length ,
+.Sq \ek
+.Pq horizontal position marker ,
+.Sq \eo
+.Pq text overstrike ,
and
.Sq \es
.Pq text size
-.Sx Text Decoration
-escapes are all discarded in mandoc.
+escape sequences are all discarded in mandoc.
.It
The
.Sq \ef
In GNU troff, this would result in strange behaviour.
.El
.Sh SEE ALSO
+.Xr man 1 ,
.Xr mandoc 1 ,
-.Xr mandoc_char 7
+.Xr eqn 7 ,
+.Xr mandoc_char 7 ,
+.Xr mdoc 7 ,
+.Xr roff 7 ,
+.Xr tbl 7
.Sh HISTORY
The
.Nm
This
.Nm
reference was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .
.Sh CAVEATS
Do not use this language.
Use
git.ckatri.com / mandoc.git / blobdiff