"sys/param.h is for kernel interface programs.

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 37d6ade28205f63f7579f8827f816999ef96b7e5..d7bd066d58bd7698ee917a29ed6d321113645b9d 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.149 2010/08/09 00:07:51 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.155 2010/08/24 14:03:46 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 9 2010 $
+.Dd $Mdocdate: August 24 2010 $

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


@@ -2715,159 +2715,168 @@ 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

-groff only accepts a single
-.Sq \&Lk
-link-name argument; the remainder is misformatted.
+.Sx \&At
+with unknown arguments produces no output at all.
+\*[hist]
+Newer groff and mandoc print
+.Qq AT&T UNIX
+and the arguments.

 .It
 .It

-The
-.Sq \&%C
-macro is not implemented in groff.
+.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
 .It

-An empty
-.Sq \&Dd
-macro in groff prints
+.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.
-.It
-Historic groff does not break before an
-.Sx \&Fn
-when not invoked as the line macro in the
-.Em SYNOPSIS
-section.
+for the normalised behaviour in mandoc.

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

-The comment syntax
-.Sq \e\."
-is no longer accepted.
+.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
 .It

-groff behaves irregularly when specifying
+.Sq \(ba
+(vertical bar) is not fully supported as a delimiter.
+\*[hist]
+.It
+.Sq \ef
+.Pq font face
+and

 .Sq \ef
 .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 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
 .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.
-.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.
+.Fl offset Ar right .
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.

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

 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