Clarified EXIT STATUS sections. Discussed among schwarze@, Thomas, and

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index af90052a110ccab375958a07faca36e5cbcde990..1f94e32808fc67f38e2b667c60ee22827262f939 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.143 2010/08/06 17:07:11 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.158 2010/09/04 17:22:41 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: August 6 2010 $
+.Dd $Mdocdate: September 4 2010 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -28,9 +28,11 @@ language is used to format
 .Bx
 .Ux
 manuals.
 .Bx
 .Ux
 manuals.

-In this reference document, we describe its syntax, structure, and
+This reference document describes its syntax, structure, and

 usage.
 usage.

-Our reference implementation is mandoc; the
+The reference implementation is
+.Xr mandoc 1 ;
+the

 .Sx COMPATIBILITY
 section describes compatibility with other troff \-mdoc implementations.
 .Pp
 .Sx COMPATIBILITY
 section describes compatibility with other troff \-mdoc implementations.
 .Pp


@@ -61,7 +63,7 @@ line.
 A macro line with only a control character and comment escape,
 .Sq \&.\e\*q ,
 is also ignored.
 A macro line with only a control character and comment escape,
 .Sq \&.\e\*q ,
 is also ignored.

-Macro lines with only a control character and optionally whitespace are
+Macro lines with only a control character and optional whitespace are

 stripped from input.
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:
 stripped from input.
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:


@@ -107,7 +109,7 @@ for two-character sequences; an open-bracket
 .Sq \&[
 for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;
 .Sq \&[
 for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;

-or a single one-character sequence.
+or a single one character sequence.

 See
 .Xr mandoc_char 7
 for a complete list.
 See
 .Xr mandoc_char 7
 for a complete list.


@@ -120,7 +122,7 @@ and
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef

-escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+escape followed by an indicator: B (bold), I (italic), R (Roman), or P

 (revert to previous mode):
 .Pp
 .D1 \efBbold\efR \efIitalic\efP
 (revert to previous mode):
 .Pp
 .D1 \efBbold\efR \efIitalic\efP


@@ -147,7 +149,7 @@ recommended for
 which encourages semantic annotation.
 .Ss Predefined Strings
 Historically,
 which encourages semantic annotation.
 .Ss Predefined Strings
 Historically,

-.Xr groff 1
+troff

 also defined a set of package-specific
 .Dq predefined strings ,
 which, like
 also defined a set of package-specific
 .Dq predefined strings ,
 which, like


@@ -172,7 +174,7 @@ and
 .Pq vertical bar .
 .Ss Whitespace
 Whitespace consists of the space character.
 .Pq vertical bar .
 .Ss Whitespace
 Whitespace consists of the space character.

-In free-form lines, whitespace is preserved within a line; un-escaped
+In free-form lines, whitespace is preserved within a line; unescaped

 trailing spaces are stripped from input (unless in a literal context).
 Blank free-form lines, which may include whitespace, are only permitted
 within literal contexts.
 trailing spaces are stripped from input (unless in a literal context).
 Blank free-form lines, which may include whitespace, are only permitted
 within literal contexts.


@@ -183,7 +185,7 @@ If arguments are quoted, whitespace within the quotes is retained.
 Macro arguments may be quoted with double-quotes to group
 space-delimited terms or to retain blocks of whitespace.
 A quoted argument begins with a double-quote preceded by whitespace.
 Macro arguments may be quoted with double-quotes to group
 space-delimited terms or to retain blocks of whitespace.
 A quoted argument begins with a double-quote preceded by whitespace.

-The next double-quote not pair-wise adjacent to another double-quote
+The next double-quote not pairwise adjacent to another double-quote

 terminates the literal, regardless of surrounding whitespace.
 .Pp
 Note that any quoted text, even if it would cause a macro invocation
 terminates the literal, regardless of surrounding whitespace.
 .Pp
 Note that any quoted text, even if it would cause a macro invocation


@@ -276,7 +278,7 @@ is necessarily non-portable across output media.
 See
 .Sx COMPATIBILITY .
 .Ss Sentence Spacing
 See
 .Sx COMPATIBILITY .
 .Ss Sentence Spacing

-When composing a manual, make sure that your sentences end at the end of
+When composing a manual, make sure that sentences end at the end of

 a line.
 By doing so, front-ends will be able to apply the proper amount of
 spacing after the end of sentence (unescaped) period, exclamation mark,
 a line.
 By doing so, front-ends will be able to apply the proper amount of
 spacing after the end of sentence (unescaped) period, exclamation mark,


@@ -288,7 +290,8 @@ delimiters (
 .Sq \&" ) .
 .Pp
 The proper spacing is also intelligently preserved if a sentence ends at
 .Sq \&" ) .
 .Pp
 The proper spacing is also intelligently preserved if a sentence ends at

-the boundary of a macro line, e.g.,
+the boundary of a macro line.
+For example:

 .Pp
 .D1 \&Xr mandoc 1 \.
 .D1 \&Fl T \&Ns \&Cm ascii \.
 .Pp
 .D1 \&Xr mandoc 1 \.
 .D1 \&Fl T \&Ns \&Cm ascii \.


@@ -328,8 +331,9 @@ file:
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here
 \&.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 .Sh LIBRARY

+\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.

 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options


@@ -339,18 +343,18 @@ The
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES

-\&.\e\*q The next is for sections 2, 3, & 9 only.

 \&.\e\*q .Sh RETURN VALUES
 \&.\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 .Sh ENVIRONMENT

+\&.\e\*q For sections 1, 6, 7, & 8 only.

 \&.\e\*q .Sh FILES
 \&.\e\*q .Sh FILES

-\&.\e\*q The next is for sections 1 & 8 only.

 \&.\e\*q .Sh EXIT STATUS
 \&.\e\*q .Sh EXIT STATUS

+\&.\e\*q For sections 1, 6 & 8 only.

 \&.\e\*q .Sh EXAMPLES
 \&.\e\*q .Sh EXAMPLES

-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.

 \&.\e\*q .Sh DIAGNOSTICS
 \&.\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 .Sh ERRORS

+\&.\e\*q For sections 2, 3, & 9 only.

 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS
 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS


@@ -359,21 +363,22 @@ utility processes files ...
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS

+\&.\e\*q Not used in OpenBSD.

 .Ed
 .Pp
 .Ed
 .Pp

-The sections in a
+The sections in an

 .Nm
 document are conventionally ordered as they appear above.
 Sections should be composed as follows:
 .Bl -ohang -offset Ds
 .It Em NAME
 .Nm
 document are conventionally ordered as they appear above.
 Sections should be composed as follows:
 .Bl -ohang -offset Ds
 .It Em NAME

-The name(s) and a one-line description of the documented material.
+The name(s) and a one line description of the documented material.

 The syntax for this as follows:
 .Bd -literal -offset indent
 The syntax for this as follows:
 .Bd -literal -offset indent

-\&.Nm name0
-\&.Nm name1
+\&.Nm name0 ,
+\&.Nm name1 ,

 \&.Nm name2
 \&.Nm name2

-\&.Nd a one-line description
+\&.Nd a one line description

 .Ed
 .Pp
 The
 .Ed
 .Pp
 The


@@ -415,8 +420,8 @@ generally structured as follows:
 .Pp
 For the second, function calls (sections 2, 3, 9):
 .Bd -literal -offset indent
 .Pp
 For the second, function calls (sections 2, 3, 9):
 .Bd -literal -offset indent

-\&.Vt extern const char *global;

 \&.In header.h
 \&.In header.h

+\&.Vt extern const char *global;

 \&.Ft "char *"
 \&.Fn foo "const char *src"
 \&.Ft "char *"
 \&.Ft "char *"
 \&.Fn foo "const char *src"
 \&.Ft "char *"


@@ -445,7 +450,7 @@ section, particularly
 and
 .Sx \&Ft .
 All of these macros are output on their own line.
 and
 .Sx \&Ft .
 All of these macros are output on their own line.

-If two such dissimilar macros are pair-wise invoked (except for
+If two such dissimilar macros are pairwise invoked (except for

 .Sx \&Ft
 before
 .Sx \&Fo
 .Sx \&Ft
 before
 .Sx \&Fo


@@ -471,9 +476,9 @@ or
 .Sx \&Ss
 macro or the end of an enclosing block, whichever comes first.
 .It Em DESCRIPTION
 .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
+This expands upon the brief, one line description in

 .Em NAME .
 .Em NAME .

-It usually contains a break-down of the options (if documenting a
+It usually contains a breakdown of the options (if documenting a

 command), such as:
 .Bd -literal -offset indent
 The arguments are as follows:
 command), such as:
 .Bd -literal -offset indent
 The arguments are as follows:


@@ -489,10 +494,8 @@ Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side
 effects or notable algorithmic implications.
 .It Em RETURN VALUES
 This is useful when implementing standard functions that may have side
 effects or notable algorithmic implications.
 .It Em RETURN VALUES

-This section is the dual of
-.Em EXIT STATUS ,
-which is used for commands.
-It documents the return values of functions in sections 2, 3, and 9.
+This section documents the
+return values of functions in sections 2, 3, and 9.

 .Pp
 See
 .Sx \&Rv .
 .Pp
 See
 .Sx \&Rv .


@@ -513,10 +516,8 @@ the file is used (created, modified, etc.).
 See
 .Sx \&Pa .
 .It Em EXIT STATUS
 See
 .Sx \&Pa .
 .It Em EXIT STATUS

-Command exit status for section 1, 6, and 8 manuals.
-This section is the dual of
-.Em RETURN VALUES ,
-which is used for functions.
+This section documents the
+command exit status for section 1, 6, and 8 utilities.

 Historically, this information was described in
 .Em DIAGNOSTICS ,
 a practise that is now discouraged.
 Historically, this information was described in
 .Em DIAGNOSTICS ,
 a practise that is now discouraged.


@@ -526,7 +527,7 @@ See
 .It Em EXAMPLES
 Example usages.
 This often contains snippets of well-formed, well-tested invocations.
 .It Em EXAMPLES
 Example usages.
 This often contains snippets of well-formed, well-tested invocations.

-Make doubly sure that your examples work properly!
+Make sure that examples work properly!

 .It Em DIAGNOSTICS
 Documents error conditions.
 This is most useful in section 4 manuals.
 .It Em DIAGNOSTICS
 Documents error conditions.
 This is most useful in section 4 manuals.


@@ -571,7 +572,7 @@ See
 Common misuses and misunderstandings should be explained
 in this section.
 .It Em BUGS
 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.
 in this section.
 .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.


@@ -769,7 +770,7 @@ If a number (or inequality) of arguments is
 .Pq n ,
 then the macro accepts an arbitrary number of arguments.
 .Bd -literal -offset indent
 .Pq n ,
 then the macro accepts an arbitrary number of arguments.
 .Bd -literal -offset indent

-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB

 
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
 
 
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
 


@@ -877,10 +878,6 @@ referring to book titles.
 Publication city or location of an
 .Sx \&Rs
 block.
 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
 .Ss \&%D
 Publication date of an
 .Sx \&Rs


@@ -1159,7 +1156,7 @@ and
 argument are equivalent, as are
 .Fl symbolic
 and
 argument are equivalent, as are
 .Fl symbolic
 and

-.Cm \&Sy,
+.Cm \&Sy ,

 and
 .Fl literal
 and
 and
 .Fl literal
 and


@@ -1393,7 +1390,7 @@ and
 .Sx \&Ux .
 .Ss \&Bt
 Prints
 .Sx \&Ux .
 .Ss \&Bt
 Prints

-.Dq is currently in beta test.
+.Dq is currently in beta test .

 .Ss \&Bx
 Format the BSD version provided as an argument, or a default value if no
 argument is provided.
 .Ss \&Bx
 Format the BSD version provided as an argument, or a default value if no
 argument is provided.


@@ -1925,7 +1922,9 @@ See also
 and
 .Sx \&Fo .
 .Ss \&Fx
 and
 .Sx \&Fo .
 .Ss \&Fx

-Format the FreeBSD version provided as an argument, or a default value
+Format the
+.Fx
+version provided as an argument, or a default value

 if no argument is provided.
 .Pp
 Examples:
 if no argument is provided.
 .Pp
 Examples:


@@ -1954,7 +1953,7 @@ Examples:
 .D1 \&.Ic alias
 .Pp
 Note that using
 .D1 \&.Ic alias
 .Pp
 Note that using

-.Sx \&Bd No Fl literal
+.Sx \&Bd Fl literal

 or
 .Sx \&D1
 is preferred for displaying code; the
 or
 .Sx \&D1
 is preferred for displaying code; the


@@ -2098,7 +2097,7 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:
 .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
 .D1 \&.Lk http://bsd.lv
 .Pp
 See also


@@ -2126,7 +2125,7 @@ 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.
+A one line description of the manual's content.

 This may only be invoked in the
 .Em SYNOPSIS
 section subsequent the
 This may only be invoked in the
 .Em SYNOPSIS
 section subsequent the


@@ -2206,7 +2205,9 @@ See also
 and
 .Sx \&Sm .
 .Ss \&Nx
 and
 .Sx \&Sm .
 .Ss \&Nx

-Format the NetBSD version provided as an argument, or a default value if
+Format the
+.Nx
+version provided as an argument, or a default value if

 no argument is provided.
 .Pp
 Examples:
 no argument is provided.
 .Pp
 Examples:


@@ -2278,7 +2279,9 @@ Unknown usage.
 .Em Remarks :
 this macro has been deprecated.
 .Ss \&Ox
 .Em Remarks :
 this macro has been deprecated.
 .Ss \&Ox

-Format the OpenBSD version provided as an argument, or a default value
+Format the
+.Ox
+version provided as an argument, or a default value

 if no argument is provided.
 .Pp
 Examples:
 if no argument is provided.
 .Pp
 Examples:


@@ -2598,7 +2601,7 @@ Examples:
 .D1 \&.Tn IBM
 .Ss \&Ud
 Prints out
 .D1 \&.Tn IBM
 .Ss \&Ud
 Prints out

-.Dq currently under development.
+.Dq currently under development .

 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.


@@ -2671,7 +2674,7 @@ is followed by non-punctuation, an
 .Sx \&Ns
 is inserted into the token stream.
 This behaviour is for compatibility with
 .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
 .Pp
 Examples:
 .D1 \&.Xr mandoc 1


@@ -2714,151 +2717,170 @@ file re-write
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
 .Pp
 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
 .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
 .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
 .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
 .It

-groff behaves inconsistently when encountering
-.Pf non- Sx \&Fa
-children of

 .Sx \&Fo
 .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
 .It

-groff behaves inconsistently when encountering

 .Sx \&Ft
 .Sx \&Ft

-and
-.Sx \&Fn

 in the
 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.
 .Sx \&Fn
 has been invoked.

-In mandoc, this is not the case.

 See
 .Sx \&Ft
 and
 .Sx \&Fn
 See
 .Sx \&Ft
 and
 .Sx \&Fn

-for the normalised behaviour.
+for the normalised behaviour in mandoc.

 .It
 .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
 .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
 .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
 .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
+.Sx \&Lk
+only accepts a single link-name argument; the remainder is misformatted.

 .It
 .It

-In groff, the

 .Sx \&Pa
 .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.
 certain list types.

-mandoc does.

 .It
 .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
+.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
 .It

-groff behaves irregularly when specifying

 .Sq \ef
 .Sq \ef

+.Pq font face
+and
+.Sq \ef
+.Pq font family face

 .Sx Text Decoration
 .Sx Text Decoration

-within line-macro scopes.
-mandoc follows a consistent system.
+escapes behave irregularly when specified within line-macro scopes.

 .It
 .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
 .It

-In quoted literals, groff allowed pair-wise 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
 .It

-Display offsets

 .Sx \&Bd
 .Fl offset Ar center
 and
 .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 .
-.It
-Historic groff has many un-callable macros.
-Most of these (excluding some block-level macros) are now callable.
+.Fl offset Ar right .
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.

 .It
 .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
 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
 .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 mandoc 1 ,
 .Xr mandoc_char 7
 .El
 .Sh SEE ALSO
 .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
 .Sh AUTHORS
 The
 .Nm