Cope with another one of the many kinds of DocBook stupidity:

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index e3644f178ab6c6bb256629d0750e3b1cbd6a1066..df25d8cbe42bdf081f28b847d06ea4bc9ec8786c 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.249 2015/01/20 19:39:34 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.251 2015/02/15 17:57:45 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 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: January 20 2015 $
+.Dd $Mdocdate: February 15 2015 $

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


@@ -1758,17 +1758,18 @@ is preferred for displaying code; the
 .Sx \&Ic
 macro is used when referring to specific instructions.
 .Ss \&In
 .Sx \&Ic
 macro is used when referring to specific instructions.
 .Ss \&In

-An
-.Dq include
-file.
+The name of an include file.
+This macro is most often used in section 2, 3, and 9 manual pages.
+.Pp

 When invoked as the first macro on an input line in the
 .Em SYNOPSIS
 section, the argument is displayed in angle brackets
 and preceded by
 When invoked as the first macro on an input line in the
 .Em SYNOPSIS
 section, the argument is displayed in angle brackets
 and preceded by

-.Dq #include ,
+.Qq #include ,

 and a blank line is inserted in front if there is a preceding
 function declaration.
 and a blank line is inserted in front if there is a preceding
 function declaration.

-This is most often used in section 2, 3, and 9 manual pages.
+In other sections, it only encloses its argument in angle brackets
+and causes no line break.

 .Pp
 Examples:
 .Dl \&.In sys/types.h
 .Pp
 Examples:
 .Dl \&.In sys/types.h


@@ -3133,50 +3134,13 @@ Manually switching the font using the
 font escape sequences is never required.
 .Sh COMPATIBILITY
 This section provides an incomplete list of compatibility issues
 font escape sequences is never required.
 .Sh COMPATIBILITY
 This section provides an incomplete list of compatibility issues

-between mandoc and other troff implementations, at this time limited
-to GNU troff
+between mandoc and GNU troff

 .Pq Qq groff .
 .Pq Qq groff .

-The term
-.Qq historic groff
-refers to groff versions before 1.17,
-which featured a significant update of the
-.Pa doc.tmac
-file.
-.Pp
-Heirloom troff, the other significant troff implementation accepting
-\-mdoc, is similar to historic groff.

 .Pp
 The following problematic behaviour is found in groff:
 .Pp
 The following problematic behaviour is found in groff:

-.ds hist (Historic groff only.)

 .Pp
 .Bl -dash -compact
 .It
 .Pp
 .Bl -dash -compact
 .It

-Display macros
-.Po
-.Sx \&Bd ,
-.Sx \&Dl ,
-and
-.Sx \&D1
-.Pc
-may not be nested.
-\*[hist]
-.It
-.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 \&Bl Fl column
-does not recognise 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
 with non-standard arguments behaves very strangely.
 When there are three arguments, they are printed verbatim.
 .Sx \&Dd
 with non-standard arguments behaves very strangely.
 When there are three arguments, they are printed verbatim.


@@ -3185,53 +3149,6 @@ but without any arguments the string
 .Dq Epoch
 is printed.
 .It
 .Dq Epoch
 is printed.
 .It

-.Sx \&Fl
-does not print a dash for an empty argument.
-\*[hist]
-.It
-.Sx \&Fn
-does not start a new line unless invoked as the line macro in the
-.Em SYNOPSIS
-section.
-\*[hist]
-.It
-.Sx \&Fo
-with
-.Pf non- Sx \&Fa
-children causes inconsistent spacing between arguments.
-In mandoc, a single space is always inserted between arguments.
-.It
-.Sx \&Ft
-in the
-.Em SYNOPSIS
-causes inconsistent vertical spacing, depending on whether a prior
-.Sx \&Fn
-has been invoked.
-See
-.Sx \&Ft
-and
-.Sx \&Fn
-for the normalised behaviour in mandoc.
-.It
-.Sx \&In
-ignores additional arguments and is not treated specially in the
-.Em SYNOPSIS .
-\*[hist]
-.It
-.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 delimiter 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
 .Sx \&Lk
 only accepts a single link-name argument; the remainder is misformatted.
 .It


@@ -3245,19 +3162,6 @@ can only be called by other macros, but not at the beginning of a line.
 .Sx \&%C
 is not implemented (up to and including groff-1.22.2).
 .It
 .Sx \&%C
 is not implemented (up to and including groff-1.22.2).
 .It

-Historic groff only allows up to eight or nine arguments per macro input
-line, depending on the exact situation.
-Providing more arguments causes garbled output.
-The number of arguments on one input line is not limited with mandoc.
-.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 face
 and


@@ -3275,12 +3179,26 @@ The following features are unimplemented in mandoc:
 .Bl -dash -compact
 .It
 .Sx \&Bd
 .Bl -dash -compact
 .It
 .Sx \&Bd

-.Fl file Ar file .
+.Fl file Ar file
+is unsupported for security reasons.
+.It
+.Sx \&Bd
+.Fl filled
+does not adjust the right margin, but is an alias for
+.Sx \&Bd
+.Fl ragged .
+.It
+.Sx \&Bd
+.Fl literal
+does not use a literal font, but is an alias for
+.Sx \&Bd
+.Fl unfilled .

 .It
 .Sx \&Bd
 .Fl offset Cm center
 and
 .It
 .Sx \&Bd
 .Fl offset Cm center
 and

-.Fl offset Cm right .
+.Fl offset Cm right
+don't work.

 Groff does not implement centered and flush-right rendering either,
 but produces large indentations.
 .El
 Groff does not implement centered and flush-right rendering either,
 but produces large indentations.
 .El