-.\" $Id: mdoc.7,v 1.131 2010/07/05 13:12:32 kristaps Exp $
+.\" $Id: mdoc.7,v 1.135 2010/07/16 21:09:39 kristaps Exp $
.\"
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: July 5 2010 $
+.Dd $Mdocdate: July 16 2010 $
.Dt MDOC 7
.Os
.Sh NAME
line terminators.
.Ss Comments
Text following a
-.Sq \e" ,
+.Sq \e\*q ,
whether in a macro or free-form text line, is ignored to the end of
line. A macro line with only a control character and comment escape,
-.Sq \&.\e" ,
+.Sq \&.\e\*q ,
is also ignored. Macro lines with only a control character and optionally
whitespace are stripped from input.
.Ss Reserved Characters
and
.Sx \&Sy .
.Ss \&Bk
-Begins a keep block, containing a collection of macros or text
-to be kept together in the output.
+Begins a collection of macros or text not breaking the line.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Bk Fl words
.Pp
-Currently, the only argument implemented is
-.Fl words ,
-requesting to keep together all words of the contained text
-on the same output line.
Subsequent arguments are ignored.
+The
+.Fl words
+argument is required.
.Pp
-Examples:
+Each line within a keep block is kept intact, so the following example
+will not break within each
+.Sx \&Op
+macro line:
.Bd -literal -offset indent
\&.Bk \-words
-\&.Op o Ar output_file
+\&.Op Fl f Ar flags
+\&.Op Fl o Ar output
\&.Ek
.Ed
.Pp
-See also
-.Sx \&Ek .
+Be careful in using over-long lines within a keep block!
+Doing so will clobber the right margin.
.Ss \&Bl
Begins a list composed of one or more list entries.
Its syntax is as follows:
.D1 \&.Em Warnings!
.D1 \&.Em Remarks :
.Ss \&En
+This macro is obsolete and not implemented.
.Ss \&Eo
An arbitrary enclosure.
Its syntax is as follows:
See also
.Sx \&Dv .
.Ss \&Es
+This macro is obsolete and not implemented.
.Ss \&Ev
Environmental variables such as those specified in
.Xr environ 7 .
and
.Sx \&Ux .
.Ss \&Hf
+This macro is obsolete and not implemented.
.Ss \&Ic
+Designate an internal or interactive command.
+This is similar to
+.Sx \&Cm
+but used for instructions rather than values.
+.Pp
+Examples:
+.D1 \&.Ic hash
+.D1 \&.Ic alias
+.Pp
+Note that using
+.Sx \&Bd No Fl literal
+or
+.Sx \&D1
+is preferred for displaying code; the
+.Sx \&Ic
+macro is used when referring to specific instructions.
.Ss \&In
An
.Qq include
See also
.Sx \&Mt .
.Ss \&Lp
+Synonym for
+.Sx \&Pp .
.Ss \&Ms
.Ss \&Mt
Format a
Examples:
.D1 \&.Mt discuss@manpages.bsd.lv
.Ss \&Nd
+A one-line description of the manual's content.
+This may only be invoked in the
+.Em SYNOPSIS
+section subsequent the
+.Sx \&Nm
+macro.
+.Pp
+Examples:
+.D1 \&.Sx \&Nd mdoc language reference
+.D1 \&.Sx \&Nd format and display UNIX manuals
+.Pp
+The
+.Sx \&Nd
+macro technically accepts child macros and terminates with a subsequent
+.Sx \&Sh
+invocation.
+Do not assume this behaviour: some
+.Xr whatis 1
+database generators are not smart enough to parse more than the line
+arguments and will display macros verbatim.
+.Pp
+See also
+.Sx \&Nm .
.Ss \&Nm
The name of the manual page, or \(em in particular in section 1, 6,
and 8 pages \(em of an additional command or feature documented in
.Sx \&Nm
to mark up the name of the manual page.
.Ss \&No
+A
+.Qq noop
+macro used to terminate prior macro contexts.
+.Pp
+Examples:
+.D1 \&.Sx \&Fl ab \&No cd \&Fl ef
.Ss \&Ns
.Ss \&Nx
Format the NetBSD version provided as an argument, or a default value if
and
.Sx \&Ux .
.Ss \&Oc
+Closes multi-line
+.Sx \&Oo
+context.
.Ss \&Oo
+Multi-line version of
+.Sx \&Op .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Oo
+\&.Op Fl flag Ns Ar value
+\&.Oc
+.Ed
.Ss \&Op
+Command-line option.
+Used when listing options to command-line utilities.
+Prints the argument(s) in brackets.
+.Pp
+Examples:
+.D1 \&.Op \&Fl a \&Ar b
+.D1 \&.Op \&Ar a | b
+.Pp
+See also
+.Sx \&Oo .
.Ss \&Os
Document operating system version.
This is the mandatory third macro of
and
.Sx \&Ux .
.Ss \&Pa
+A file-system path.
+.Pp
+Examples:
+.D1 \&.Pa /usr/bin/mandoc
+.D1 \&.Pa /usr/share/man/man7/mdoc.7
+.Pp
+See also
+.Sx \&Lk .
.Ss \&Pc
+Close parenthesised context opened by
+.Sx \&Po .
.Ss \&Pf
+Removes the space
+.Pq Qq prefix
+between its arguments.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. \&Pf Cm prefix suffix
+.Pp
+The
+.Cm suffix
+argument may be a macro.
+.Pp
+Examples:
+.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix
.Ss \&Po
+Multi-line version of
+.Sx \&Pq .
.Ss \&Pp
+Break a paragraph.
+This will assert vertical space between prior and subsequent macros
+and/or text.
.Ss \&Pq
+Parenthesised enclosure.
+.Pp
+See also
+.Sx \&Po .
.Ss \&Qc
.Ss \&Ql
.Ss \&Qo
.Ss \&Sc
.Ss \&Sh
.Ss \&Sm
+Switches the spacing mode for output generated from macros.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Sm Cm on | off
+.Pp
+By default, spacing is
+.Cm on .
+When switched
+.Cm off ,
+no white space is inserted between macro arguments and between the
+output generated from adjacent macros, but free-form text lines
+still get normal spacing between words and sentences.
.Ss \&So
.Ss \&Sq
.Ss \&Ss
and
.Sx \&Ox .
.Ss \&Va
+A variable name.
+.Pp
+Examples:
+.D1 \&.Va foo
+.D1 \&.Va const char *bar ;
.Ss \&Vt
A variable type.
This is also used for indicating global variables in the
git.ckatri.com / mandoc.git / blobdiff