=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.144 retrieving revision 1.162 diff -u -p -r1.144 -r1.162 --- mandoc/mdoc.7 2010/08/06 17:09:58 1.144 +++ mandoc/mdoc.7 2010/10/24 14:49:35 1.162 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.144 2010/08/06 17:09:58 schwarze Exp $ +.\" $Id: mdoc.7,v 1.162 2010/10/24 14:49:35 schwarze 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: August 6 2010 $ +.Dd $Mdocdate: October 24 2010 $ .Dt MDOC 7 .Os .Sh NAME @@ -149,7 +149,7 @@ recommended for which encourages semantic annotation. .Ss Predefined Strings Historically, -.Xr groff 1 +troff also defined a set of package-specific .Dq predefined strings , which, like @@ -331,8 +331,9 @@ file: \&.Sh NAME \&.Nm foo \&.Nd a description goes here -\&.\e\*q The next is for sections 2, 3, & 9 only. \&.\e\*q .Sh LIBRARY +\&.\e\*q For sections 2, 3, & 9 only. +\&.\e\*q Not used in OpenBSD. \&.Sh SYNOPSIS \&.Nm foo \&.Op Fl options @@ -342,18 +343,19 @@ The \&.Nm 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 .Xr foobar 1 \&.\e\*q .Sh STANDARDS @@ -362,6 +364,7 @@ utility processes files ... \&.\e\*q .Sh CAVEATS \&.\e\*q .Sh BUGS \&.\e\*q .Sh SECURITY CONSIDERATIONS +\&.\e\*q Not used in OpenBSD. .Ed .Pp The sections in an @@ -418,8 +421,8 @@ generally structured as follows: .Pp For the second, function calls (sections 2, 3, 9): .Bd -literal -offset indent -\&.Vt extern const char *global; \&.In header.h +\&.Vt extern const char *global; \&.Ft "char *" \&.Fn foo "const char *src" \&.Ft "char *" @@ -570,7 +573,7 @@ See Common misuses and misunderstandings should be explained in this section. .It Em BUGS -Known bugs, limitations and work-arounds should be described +Known bugs, limitations, and work-arounds should be described in this section. .It Em SECURITY CONSIDERATIONS Documents any security precautions that operators should consider. @@ -876,10 +879,6 @@ referring to book titles. Publication city or location of an .Sx \&Rs block. -.Pp -.Em Remarks : -this macro is not implemented in -.Xr groff 1 . .Ss \&%D Publication date of an .Sx \&Rs @@ -1077,7 +1076,8 @@ implementations render it poorly. Left- and right-justify the block. .It Fl literal Do not justify the block at all. -Preserve white space as it appears in the input. +Preserve white space and newlines as they appear in the input, including +if it follows a macro. .It Fl ragged Only left-justify the block. .It Fl unfilled @@ -1647,6 +1647,7 @@ It must be one of .Ar luna88k , .Ar mac68k , .Ar macppc , +.Ar mips64 , .Ar mvme68k , .Ar mvme88k , .Ar mvmeppc , @@ -1870,6 +1871,9 @@ Examples: \&.Fn funcname .Ed .Pp +When referring to a function documented in another manual page, +.Sx \&Xr +is usually preferable. See also .Sx MANUAL STRUCTURE and @@ -2099,7 +2103,7 @@ Its syntax is as follows: .D1 Pf \. Sx \&Lk Cm uri Op Cm name .Pp Examples: -.D1 \&.Lk http://bsd.lv "The BSD.lv Project" +.D1 \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q .D1 \&.Lk http://bsd.lv .Pp See also @@ -2676,7 +2680,7 @@ is followed by non-punctuation, an .Sx \&Ns is inserted into the token stream. This behaviour is for compatibility with -.Xr groff 1 . +GNU troff. .Pp Examples: .D1 \&.Xr mandoc 1 @@ -2719,151 +2723,171 @@ file re-write Heirloom troff, the other significant troff implementation accepting \-mdoc, is similar to historic groff. .Pp +The following problematic behaviour is found in groff: +.ds hist (Historic groff only.) +.Pp .Bl -dash -compact .It -An empty -.Sq \&Dd -macro in groff prints +.Sx \&At +with unknown arguments produces no output at all. +\*[hist] +Newer groff and mandoc print +.Qq AT&T UNIX +and the arguments. +.It +.Sx \&Bd Fl column +does not recognize trailing punctuation characters when they immediately +precede tabulator characters, but treats them as normal text and +outputs a space before them. +.It +.Sx \&Bd Fl ragged compact +does not start a new line. +\*[hist] +.It +.Sx \&Dd +without an argument prints .Dq Epoch . In mandoc, it resolves to the current date. .It -The \es (font size), \em (font colour), and \eM (font filling colour) -font decoration escapes are all discarded in mandoc. +.Sx \&Fl +does not print a dash for an empty argument. +\*[hist] .It -Old groff fails to assert a newline before -.Sx \&Bd Fl ragged compact . +.Sx \&Fn +does not start a new line unless invoked as the line macro in the +.Em SYNOPSIS +section. +\*[hist] .It -groff behaves inconsistently when encountering -.Pf non- Sx \&Fa -children of .Sx \&Fo -regarding spacing between arguments. -In mandoc, this is not the case: each argument is consistently followed -by a single space and the trailing -.Sq \&) -suppresses prior spacing. +with +.Pf non- Sx \&Fa +children causes inconsistent spacing between arguments. +In mandoc, a single space is always inserted between arguments. .It -groff behaves inconsistently when encountering .Sx \&Ft -and -.Sx \&Fn in the -.Em SYNOPSIS : -at times newline(s) are suppressed depending on whether a prior +.Em SYNOPSIS +causes inconsistent vertical spacing, depending on whether a prior .Sx \&Fn has been invoked. -In mandoc, this is not the case. See .Sx \&Ft and .Sx \&Fn -for the normalised behaviour. +for the normalised behaviour in mandoc. .It -Historic groff does not break before an -.Sx \&Fn -when not invoked as the line macro in the -.Em SYNOPSIS -section. -.It -Historic groff formats the .Sx \&In -badly: trailing arguments are trashed and -.Em SYNOPSIS -is not specially treated. +ignores additional arguments and is not treated specially in the +.Em SYNOPSIS . +\*[hist] .It -groff does not accept the -.Sq \&Ta -pseudo-macro as a line macro. -mandoc does. +.Sx \&It +sometimes requires a +.Fl nested +flag. +\*[hist] +In new groff and mandoc, any list may be nested by default and +.Fl enum +lists will restart the sequence only for the sub-list. .It -The comment syntax -.Sq \e\." -is no longer accepted. +.Sx \&Li +followed by a reserved character is incorrectly used in some manuals +instead of properly quoting that character, which sometimes works with +historic groff. .It -In groff, the +.Sx \&Lk +only accepts a single link-name argument; the remainder is misformatted. +.It .Sx \&Pa -macro does not format its arguments when used in the FILES section under +does not format its arguments when used in the FILES section under certain list types. -mandoc does. .It -Historic groff does not print a dash for empty -.Sx \&Fl -arguments. -mandoc and newer groff implementations do. +.Sx \&Ta +can only be called by other macros, but not at the beginning of a line. .It -groff behaves irregularly when specifying +.Sx \&%C +is not implemented. +.It +Historic groff has many un-callable macros. +Most of these (excluding some block-level macros) are callable +in new groff and mandoc. +.It +.Sq \(ba +(vertical bar) is not fully supported as a delimiter. +\*[hist] +.It .Sq \ef +.Pq font face +and +.Sq \ef +.Pq font family face .Sx Text Decoration -within line-macro scopes. -mandoc follows a consistent system. +escapes behave irregularly when specified within line-macro scopes. .It -In mandoc, negative scaling units are truncated to zero; groff would -move to prior lines. -Furthermore, the -.Sq f -scaling unit, while accepted, is rendered as the default unit. +Negative scaling units return to prior lines. +Instead, mandoc truncates them to zero. +.El +.Pp +The following features are unimplemented in mandoc: +.Pp +.Bl -dash -compact .It -In quoted literals, groff allowed pairwise double-quotes to produce a -standalone double-quote in formatted output. -This idiosyncratic behaviour is not applicable in mandoc. +.Sx \&Bd +.Fl file Ar file . .It -Display offsets .Sx \&Bd .Fl offset Ar center and -.Fl offset Ar right -are disregarded in mandoc. -Furthermore, troff specifies a -.Fl file Ar file -argument that is not supported in mandoc. -Lastly, since text is not right-justified in mandoc (or even groff), -.Fl ragged -and -.Fl filled -are aliases, as are -.Fl literal -and -.Fl unfilled . +.Fl offset Ar right . +Groff does not implement centered and flush-right rendering either, +but produces large indentations. .It -Historic groff has many un-callable macros. -Most of these (excluding some block-level macros) are now callable. -.It -The vertical bar -.Sq \(ba -made historic groff -.Qq go orbital -but has been a proper delimiter since then. -.It -.Sx \&It Fl nested -is assumed for all lists (it wasn't in historic groff): any list may be -nested and -.Fl enum -lists will restart the sequence only for the sub-list. -.It -Some manuals use -.Sx \&Li -incorrectly by following it with a reserved character and expecting the -delimiter to render. -This is not supported in mandoc. -.It -In groff, the -.Sx \&Cd , -.Sx \&Er , -.Sx \&Ex , +The +.Sq \eh +.Pq horizontal position , +.Sq \ev +.Pq vertical position , +.Sq \em +.Pq text colour , +.Sq \eM +.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 -.Sx \&Rv -macros were stipulated only to occur in certain manual sections. -mandoc does not have these restrictions. +.Sq \es +.Pq text size +escape sequences are all discarded in mandoc. .It -Newer groff and mandoc print -.Qq AT&T UNIX -prior to unknown arguments of -.Sx \&At ; -older groff did nothing. +The +.Sq \ef +scaling unit is accepted by mandoc, but rendered as the default unit. +.It +In quoted literals, groff allows pairwise double-quotes to produce a +standalone double-quote in formatted output. +This is not supported by mandoc. .El .Sh SEE ALSO +.Xr man 1 , .Xr mandoc 1 , .Xr mandoc_char 7 +.Sh HISTORY +The +.Nm +language first appeared as a troff macro package in +.Bx 4.4 . +It was later significantly updated by Werner Lemberg and Ruslan Ermilov +in groff-1.17. +The standalone implementation that is part of the +.Xr mandoc 1 +utility written by Kristaps Dzonsons appeared in +.Ox 4.6 . .Sh AUTHORS The .Nm