=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.122 retrieving revision 1.130 diff -u -p -r1.122 -r1.130 --- mandoc/mdoc.7 2010/06/07 11:01:15 1.122 +++ mandoc/mdoc.7 2010/07/04 22:04:04 1.130 @@ -1,6 +1,7 @@ -.\" $Id: mdoc.7,v 1.122 2010/06/07 11:01:15 kristaps Exp $ +.\" $Id: mdoc.7,v 1.130 2010/07/04 22:04:04 schwarze Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons +.\" Copyright (c) 2009, 2010 Kristaps Dzonsons +.\" Copyright (c) 2010 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,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: June 7 2010 $ +.Dd $Mdocdate: July 4 2010 $ .Dt MDOC 7 .Os .Sh NAME @@ -55,7 +56,7 @@ Text following a 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" , -is also ignored. Macro lines with only a control charater and optionally +is also ignored. Macro lines with only a control character and optionally whitespace are stripped from input. .Ss Reserved Characters Within a macro line, the following characters are reserved: @@ -167,7 +168,7 @@ also defined a set of package-specific .Dq predefined strings , which, like .Sx Special Characters , -demark special output characters and strings by way of input codes. +mark special output characters and strings by way of input codes. Predefined strings are escaped with the slash-asterisk, .Sq \e* : single-character @@ -471,13 +472,26 @@ dissimilar macros are pair-wise invoked (except for before .Sx \&Fo or -.Sx \&Fn ) , +.Sx \&Fn ) , they are separated by a vertical space, unless in the case of .Sx \&Fo , .Sx \&Fn , and .Sx \&Ft , which are always separated by vertical space. +.Pp +When text and macros following an +.Sx \&Nm +macro starting an input line span multiple output lines, +all output lines but the first will be indented to align +with the text immediately following the +.Sx \&Nm +macro, up to the next +.Sx \&Nm , +.Sx \&Sx , +or +.Sx \&Ss +macro or the end of an enclosing block, whichever comes first. .It Em DESCRIPTION This expands upon the brief, one-line description in .Em NAME . @@ -672,9 +686,20 @@ has multiple heads. .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh +.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss .It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh .It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss .El +.Pp +Note that the +.Sx \&Nm +macro is a +.Sx Block full-implicit +macro only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . .Ss Block partial-explicit Like block full-explicit, but also with single-line scope. Each has at least a body and, in limited circumstances, a head @@ -973,7 +998,7 @@ See also .Sx \&Aq . .Ss \&Ap Inserts an apostrophe without any surrounding white-space. -This is generally used as a grammatic device when referring to the verb +This is generally used as a grammatical device when referring to the verb form of a function: .Bd -literal -offset indent \&.Fn execve Ap d @@ -1094,10 +1119,7 @@ As a scaling unit following the syntax described in As the calculated string length of the opaque string. .El .Pp -If unset, it will revert to the value of -.Ar 8n -as described in -.Sx Scaling Widths . +If not provided an argument, it will be ignored. .It Fl compact Do not assert a vertical space before the block. .It Fl file Ar file @@ -1118,7 +1140,62 @@ See also and .Sx \&Dl . .Ss \&Bf +Change the font mode for a scoped block of text. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bf +.Oo +.Fl emphasis | literal | symbolic | +.Cm \&Em | \&Li | \&Sy +.Oc +.Ed +.Pp +The +.Fl emphasis +and +.Cm \&Em +argument are equivalent, as are +.Fl symbolic +and +.Cm \&Sy, +and +.Fl literal +and +.Cm \&Li . +Without an argument, this macro does nothing. +The font mode continues until broken by a new font mode in a nested +scope or +.Sx \&Ef +is encountered. +.Pp +See also +.Sx \&Li , +.Sx \&Ef , +and +.Sx \&Sy . .Ss \&Bk +Begins a keep block, containing a collection of macros or text +to be kept together in the output. +One argument is required; additional arguments are ignored. +Currently, the only argument implemented is +.Fl words , +requesting to keep together all words of the contained text +on the same output line. +A +.Fl lines +argument to keep together all lines of the contained text +on the same page has been desired for a long time, +but has never been implemented. +.Pp +Examples: +.Bd -literal -offset indent +\&.Bk \-words +\&.Op o Ar output_file +\&.Ek +.Ed +.Pp +See also +.Sx \&Ek . .Ss \&Bl Begins a list composed of one or more list entries. A list is associated with a type, which is a required argument. @@ -1591,7 +1668,11 @@ and .Ss \&Ec .Ss \&Ed .Ss \&Ef +Ends a font mode context started by +.Sx \&Bf . .Ss \&Ek +Ends a keep context started by +.Sx \&Bk . .Ss \&El Ends a list context started by .Sx \&Bl . @@ -1879,7 +1960,7 @@ line itself. Subsequent this, only the .Sq \&Ta pseudo-macro may be used to delimit phrases. -Furthermore, note that quoted sections propogate over tab-delimited +Furthermore, note that quoted sections propagate over tab-delimited phrases on an .Sx \&It , for example, @@ -1940,6 +2021,42 @@ Examples: .D1 \&.Mt discuss@manpages.bsd.lv .Ss \&Nd .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 +the manual page. +When first invoked, the +.Sx \&Nm +macro expects a single argument, the name of the manual page. +Usually, the first invocation happens in the +.Em NAME +section of the page. +The specified name will be remembered and used whenever the macro is +called again without arguments later in the page. +The +.Sx \&Nm +macro uses +.Sx Block full-implicit +semantics when invoked as the first macro on an input line in the +.Em SYNOPSIS +section; otherwise, it uses ordinary +.Sx In-line +semantics. +.Pp +Examples: +.Bd -literal -offset indent +\&.Sh SYNOPSIS +\&.Nm cat +\&.Op Fl benstuv +\&.Op Ar +.Ed +.Pp +In the +.Em SYNOPSIS +of section 2, 3 and 9 manual pages, use the +.Sx \&Fn +macro rather than +.Sx \&Nm +to mark up the name of the manual page. .Ss \&No .Ss \&Ns .Ss \&Nx @@ -2102,7 +2219,7 @@ This is also used for indicating global variables in t section, in which case a variable name is also specified. Note that it accepts .Sx Block partial-implicit -syntax when invoked as the first macro in the +syntax when invoked as the first macro in the .Em SYNOPSIS section, else it accepts ordinary .Sx In-line @@ -2169,6 +2286,9 @@ Heirloom troff, the other significant troff implementa .Pp .Bl -dash -compact .It +Old groff fails to assert a newline before +.Sx \&Bd Fl ragged compact . +.It groff behaves inconsistently when encountering .Pf non- Sx \&Fa children of @@ -2185,7 +2305,7 @@ and .Sx \&Fn in the .Em SYNOPSIS : -at times newline(s) are suppressed dependong on whether a prior +at times newline(s) are suppressed depending on whether a prior .Sx \&Fn has been invoked. In mandoc, this is not the case. @@ -2243,16 +2363,15 @@ In quoted literals, groff allowed pair-wise double-quo standalone double-quote in formatted output. This idiosyncratic behaviour is not applicable in mandoc. .It -Display types +Display offsets .Sx \&Bd -.Fl center +.Fl offset Ar center and -.Fl right -are aliases for -.Fl left -in manodc. Furthermore, the +.Fl offset Ar right +are disregarded in mandoc. +Furthermore, the .Fl file Ar file -argument is ignored. +argument is not supported in mandoc. Lastly, since text is not right-justified in mandoc (or even groff), .Fl ragged and