Text ending in a full stop, exclamation mark or question mark

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index b28c43216feb300bc6d5f5dc86a94c6ace24c390..59eee39eccc72bce267a03586c367456a5af24d8 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $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>
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" 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
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -52,10 +52,10 @@ manuals must have
 line terminators.
 .Ss Comments
 Text following a
 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,
 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
 is also ignored.  Macro lines with only a control character and optionally
 whitespace are stripped from input.
 .Ss Reserved Characters


@@ -1178,27 +1178,29 @@ See also
 and
 .Sx \&Sy .
 .Ss \&Bk
 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
 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.
 Subsequent arguments are ignored.

+The
+.Fl words
+argument is required.

 .Pp
 .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
 .Bd -literal -offset indent
 \&.Bk \-words

-\&.Op o Ar output_file
+\&.Op Fl f Ar flags
+\&.Op Fl o Ar output

 \&.Ek
 .Ed
 .Pp
 \&.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:
 .Ss \&Bl
 Begins a list composed of one or more list entries.
 Its syntax is as follows:


@@ -1716,6 +1718,7 @@ Examples:
 .D1 \&.Em Warnings!
 .D1 \&.Em Remarks :
 .Ss \&En
 .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:
 .Ss \&Eo
 An arbitrary enclosure.
 Its syntax is as follows:


@@ -1737,6 +1740,7 @@ Examples:
 See also
 .Sx \&Dv .
 .Ss \&Es
 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 .
 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .


@@ -1910,7 +1914,24 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Hf
 and
 .Sx \&Ux .
 .Ss \&Hf

+This macro is obsolete and not implemented.

 .Ss \&Ic
 .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
 .Ss \&In
 An
 .Qq include


@@ -2049,6 +2070,8 @@ Examples:
 See also
 .Sx \&Mt .
 .Ss \&Lp
 See also
 .Sx \&Mt .
 .Ss \&Lp

+Synonym for
+.Sx \&Pp .

 .Ss \&Ms
 .Ss \&Mt
 Format a
 .Ss \&Ms
 .Ss \&Mt
 Format a


@@ -2061,6 +2084,29 @@ Its syntax is as follows:
 Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
 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
 .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


@@ -2099,6 +2145,12 @@ macro rather than
 .Sx \&Nm
 to mark up the name of the manual page.
 .Ss \&No
 .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
 .Ss \&Ns
 .Ss \&Nx
 Format the NetBSD version provided as an argument, or a default value if


@@ -2118,8 +2170,30 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Oc
 and
 .Sx \&Ux .
 .Ss \&Oc

+Closes multi-line
+.Sx \&Oo
+context.

 .Ss \&Oo
 .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
 .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
 .Ss \&Os
 Document operating system version.
 This is the mandatory third macro of


@@ -2168,11 +2242,43 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Pa
 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
 .Ss \&Pc

+Close parenthesised context opened by
+.Sx \&Po .

 .Ss \&Pf
 .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
 .Ss \&Po

+Multi-line version of
+.Sx \&Pq .

 .Ss \&Pp
 .Ss \&Pp

+Break a paragraph.
+This will assert vertical space between prior and subsequent macros
+and/or text.

 .Ss \&Pq
 .Ss \&Pq

+Parenthesised enclosure.
+.Pp
+See also
+.Sx \&Po .

 .Ss \&Qc
 .Ss \&Ql
 .Ss \&Qo
 .Ss \&Qc
 .Ss \&Ql
 .Ss \&Qo


@@ -2226,6 +2332,18 @@ line.
 .Ss \&Sc
 .Ss \&Sh
 .Ss \&Sm
 .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
 .Ss \&So
 .Ss \&Sq
 .Ss \&Ss


@@ -2253,6 +2371,11 @@ See also
 and
 .Sx \&Ox .
 .Ss \&Va
 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
 .Ss \&Vt
 A variable type.
 This is also used for indicating global variables in the