=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.131 retrieving revision 1.135 diff -u -p -r1.131 -r1.135 --- mandoc/mdoc.7 2010/07/05 13:12:32 1.131 +++ mandoc/mdoc.7 2010/07/16 21:09:39 1.135 @@ -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 .\" Copyright (c) 2010 Ingo Schwarze @@ -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. .\" -.Dd $Mdocdate: July 5 2010 $ +.Dd $Mdocdate: July 16 2010 $ .Dt MDOC 7 .Os .Sh NAME @@ -52,10 +52,10 @@ manuals must have 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 @@ -1178,27 +1178,29 @@ See also 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: @@ -1716,6 +1718,7 @@ Examples: .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: @@ -1737,6 +1740,7 @@ Examples: 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 . @@ -1910,7 +1914,24 @@ See also 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 @@ -2049,6 +2070,8 @@ Examples: See also .Sx \&Mt . .Ss \&Lp +Synonym for +.Sx \&Pp . .Ss \&Ms .Ss \&Mt Format a @@ -2061,6 +2084,29 @@ Its syntax is as follows: 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 @@ -2099,6 +2145,12 @@ macro rather than .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 @@ -2118,8 +2170,30 @@ See also 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 @@ -2168,11 +2242,43 @@ See also 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 @@ -2226,6 +2332,18 @@ line. .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 @@ -2253,6 +2371,11 @@ See also 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