internal update

3 files changed, 22 insertions, 316 deletions

diff --git a/tmac/doc-common.new b/tmac/doc-common.new
index 3d6e88b3..35cd790c 100755
--- a/tmac/doc-common.new
+++ b/tmac/doc-common.new
@@ -151,12 +151,6 @@
 .nr Xo 1
 .nr Xr 10n
 .
-.\" identification strings for argument types (used for debugging)
-.ds doc-debug-1 macro
-.ds doc-debug-2 string
-.ds doc-debug-3 closing punctuation or suffix
-.ds doc-debug-4 opening punctuation or suffix
-.
 .
 .\" requests which must be processed after the closing delimiter of `Op'
 .\" and friends
@@ -888,7 +882,6 @@
 .
 .de Rd
 .  tm MDOC GLOBAL REGISTER DUMP
-.  tm doc-debug == \n[doc-debug]
 .  tm doc-macro-name == `\*[doc-macro-name]'
 .  tm doc-arg-limit == \n[doc-arg-limit]
 .  tm doc-num-args == \n[doc-num-args]
@@ -918,7 +911,7 @@
 .  tm doc-space-mode == \n[doc-space-mode]
 .  tm doc-have-space == \n[doc-have-space]
 .  tm doc-have-slot == \n[doc-have-slot]
-.  tm doc-keep-type == `\*[doc-keep-type]'
+.  tm doc-keep-type == \n[doc-keep-type]
 .  tm doc-display-depth == \n[doc-display-depth]
 .  tm doc-is-compact == \n[doc-is-compact]
 .
diff --git a/tmac/groff_mdoc.reference.man b/tmac/groff_mdoc.reference.man
index 385782d8..692dc666 100755
--- a/tmac/groff_mdoc.reference.man
+++ b/tmac/groff_mdoc.reference.man
@@ -3618,6 +3618,9 @@ The documentation in the
 source file describes it as
 .Dq old function type (fortran) .
 .
+.It Li .Sm
+To be written.
+.
 .It Li .Ud
 prints
 .
@@ -3697,168 +3700,21 @@ extension).
 \#
 .Sh DIAGNOSTICS
 .
-The debugging facilities for
+The debugging macro
+.Ql .Db
+available in previous versions of
 .Nm \-mdoc
-are limited, but can help detect subtle errors such
-as the collision of an argument name with an internal
-register or macro name.
-(A what?)
-A register is an arithmetic storage class for
-.Xr troff
-with a one or two character name.
-All registers internal to
-.Nm \-mdoc
-for
-.Xr troff
-and
-.Xr ditroff
-are two characters and
-of the form <upper_case><lower_case> such as
-.Ql \&Ar ,
-<lower_case><upper_case> as
-.Ql \&aR
-or
-<upper or lower letter><digit> as
-.Ql \&C\&1 .
-And adding to the muddle,
-.Xr troff
-has its own internal registers all of which are either
-two lower case characters or a dot plus a letter or meta-character
-character.
-In one of the introduction examples, it was shown how to
-prevent the interpretation of a macro name with the escape sequence
-.Ql \e& .
-This is sufficient for the internal register names also.
-.Pp
-.\" Every callable macro name has a corresponding register
-.\" of the same name (<upper_case><lower_case>).
-.\" There are also specific registers which have
-.\" been used for stacks and arrays and are listed in the
-.\" .Sx Appendix .
-.\" .Bd -ragged -offset 4n
-.\" [A-Z][a-z]	registers corresponding to macro names (example ``Ar'')
-.\" [a-z][A-Z]	registers corresponding to macro names (example ``aR'')
-.\" C[0-9]		argument types (example C1)
-.\" O[0-9]		offset stack (displays)
-.\" h[0-9]		horizontal spacing stack (lists)
-.\" o[0-9]		offset (stack) (lists)
-.\" t[0-9]		tag stack (lists)
-.\" v[0-9]		vertical spacing stack (lists)
-.\" w[0-9]		width tag/label stack
-.\" .Ed
-.\" .Pp
-If a non-escaped register name is given in the argument list of a request
-unpredictable behavior will occur.
-In general, any time huge portions
-of text do not appear where expected in the output, or small strings
-such as list tags disappear, chances are there is a misunderstanding
-about an argument type in the argument list.
-Your mother never intended for you to remember this evil stuff -- so here
-is a way to find out whether or not your arguments are valid: The
-.Ql \&.Db
-(debug)
-macro displays the interpretation of the argument list for most
-macros.
-Macros such as the
-.Ql \&.Pp
-(paragraph)
-macro do not contain debugging information.
-All of the callable macros do,
-and it is strongly advised whenever in doubt,
-turn on the
-.Ql \&.Db
-macro.
-.Pp
-.Dl Usage: \&.Db [on | off]
-.Pp
-An example of a portion of text with
-the debug macro placed above and below an
-artificially created problem (a flag argument
-.Ql \&aC
-which should be
-.Ql \e&aC
-in order to work):
-.
-.Bd -literal -offset indent
-\&.Db on
-\&.Op Fl aC Ar file )
-\&.Db off
-.Ed
-.Pp
-The resulting output:
-.
-.Bd -literal -offset indent
-DEBUGGING ON
-DEBUG(argv) MACRO: `.Op'  Line #: 2
-	Argc: 1  Argv: `Fl'  Length: 2
-	Space: `'  Class: Executable
-	Argc: 2  Argv: `aC'  Length: 2
-	Space: `'  Class: Executable
-	Argc: 3  Argv: `Ar'  Length: 2
-	Space: `'  Class: Executable
-	Argc: 4  Argv: `file'  Length: 4
-	Space: ` '  Class: String
-	Argc: 5  Argv: `)'  Length: 1
-	Space: ` '  Class: Closing Punctuation or suffix
-	MACRO REQUEST: .Op Fl aC Ar file )
-DEBUGGING OFF
-.Ed
-.Pp
-The first line of information tells the name of the calling
-macro, here
-.Ql \&.Op ,
-and the line number it appears on.
-If one or more files are involved
-(especially if text from another file is included) the line number
-may be bogus.
-If there is only one file, it should be accurate.
-The second line gives the argument count, the argument
-.Pq Ql \&Fl
-and its length.
-If the length of an argument is two characters, the
-argument is tested to see if it is executable (unfortunately, any
-register which contains a non-zero value appears executable).
-The third line gives the space allotted for a class, and the
-class type.
-The problem here is the argument aC should not be
-executable.
-The four types of classes are string, executable, closing
-punctuation and opening punctuation.
-The last line shows the entire
-argument list as it was read.
-In this next example, the offending
-.Ql \&aC
-is escaped:
-.
-.Bd -literal -offset indent
-\&.Db on
-\&.Em An escaped \e&aC
-\&.Db off
-.Ed
-.
-.Bd -literal -offset indent
-DEBUGGING ON
-DEBUG(fargv) MACRO: `.Em'  Line #: 2
-	Argc: 1  Argv: `An'  Length: 2
-	Space: ` '  Class: String
-	Argc: 2  Argv: `escaped'  Length: 7
-	Space: ` '  Class: String
-	Argc: 3  Argv: `aC'  Length: 2
-	Space: ` '  Class: String
-	MACRO REQUEST: .Em An escaped &aC
-DEBUGGING OFF
-.Ed
-.Pp
-The argument
-.Ql \e&aC
-shows up with the same length of 2 as the
-.Ql \e&
-sequence produces a zero width, but a register
-named
-.Ql \e&aC
-was not found and the type classified as string.
-.Pp
-Other diagnostics consist of usage statements and are self explanatory.
+has been removed since
+.Tn GNU
+.Xr troff 1
+provides better facilities to check parameters; additionally, many error and
+warning messages have been added to this macro package, making it both more
+robust and verbose.
+.Pp
+The only remaining debugging macro is
+.Ql .Rd
+which yields a register dump of all global registers and strings.
+A normal user will never need it.
 .
 .
 .Sh "FORMATTING WITH GROFF, TROFF, AND NROFF"
diff --git a/tmac/tmac.doc.new b/tmac/tmac.doc.new
index e65e5acc..02400a19 100755
--- a/tmac/tmac.doc.new
+++ b/tmac/tmac.doc.new
@@ -71,49 +71,11 @@
 .eo
 .
 .
-.\" NS doc-inline-debug user register (bool)
-.\" NS   inline debug mode (inline if 1, to stderr if 0 (default))
-.
-.if !r doc-inline-debug .nr doc-inline-debug 0
-.
-.
-.\" NS doc-debug global register (bool)
-.\" NS   debug mode (1 if active, 0 otherwise (default))
-.
-.nr doc-debug 0
-.
-.
 .\" NS Db macro
-.\" NS   start/stop debug mode (`.Db'/`.Db on'/`.Db off')
-.\" NS
-.\" NS   without argument, toggle debug status
-.\" NS
-.\" NS modifies:
-.\" NS   doc-debug
+.\" NS   defunct
 .
 .de Db
-.  ie \n[.$] \{\
-.    ie "\$1"on" \{\
-.      tm DEBUGGING ON
-.      nr doc-debug 1
-.    \}
-.    el \{\
-.      ie "\$1"off" \{\
-.        tm DEBUGGING OFF
-.        nr doc-debug 0
-.      \}
-.      el \
-.        tm Usage: .Db [on | off] (#\n[.c])
-.  \}\}
-.  el \{\
-.    ie \n[doc-debug] \{\
-.      tm DEBUGGING OFF
-.      nr doc-debug 0
-.    \}
-.    el \{\
-.      tm DEBUGGING ON
-.      nr doc-debug 1
-.  \}\}
+.  tm mdoc error: .Db defunct (#\n[.c])
 ..
 .
 .
@@ -210,60 +172,9 @@
 .  nr doc-type\n[doc-arg-limit] \n[doc-arg-type]
 .  doc-set-spacing-\n[doc-arg-type]
 .
-.  if \n[doc-debug] \{\
-.    ds doc-str-dpa \*[doc-debug-\n[doc-arg-type]]
-.
-.    ie \n[doc-inline-debug] \{\
-.      br
-.      nr doc-reg-dpa \n[.i]u
-.      in -\n[doc-reg-dpa]u
-.
-.      if (\n[doc-arg-limit] == 1) \{\
-.        nop \f[B]DEBUG(doc-parse-args) MACRO:\f[P] `.\*[doc-macro-name]'
-.        nop \) \f[B]Line #:\f[P] \n[.c]
-.      \}
-.      nop \t\f[B]Argc:\f[P] \n[doc-arg-limit]
-.      nop \ \f[B]Argv:\f[P] `\*[doc-arg\n[doc-arg-limit]]'
-.      nop \ \f[B]Length:\f[P] \n[doc-width]
-.      nop \t\f[B]Space:\f[P] `\*[doc-space\n[doc-arg-limit]]'
-.      nop \ \f[B]Type:\f[P] \*[doc-str-dpa]
-.    \}
-.    el \{\
-.      if (\n[doc-arg-limit] == 1) \{\
-.        tmc "DEBUG (doc-parse-args)
-.        tm1 " MACRO: `.\*[doc-macro-name]'  Line #: \n[.c]
-.      \}
-.      tmc "  Argc: \n[doc-arg-limit]
-.      tmc "  Argv: `\*[doc-arg\n[doc-arg-limit]]'
-.      tm1 "  Length: \n[doc-width]
-.      tmc "  Space: `\*[doc-space\n[doc-arg-limit]]'
-.      tm1 "  Type: \*[doc-str-dpa]
-.  \}\}
-.
 .  \" check whether we have processed the last parameter
-.  ie (\n[.$] == 1) \{\
+.  ie (\n[.$] == 1) \
 .    nr doc-arg-ptr 0
-.
-.    if \n[doc-debug] \{\
-.      nr doc-reg-dpa1 1
-.
-.      ie \n[doc-inline-debug] \{\
-.        nop MACRO REQUEST: \t.\*[doc-macro-name]
-.        while (\n[doc-reg-dpa1] <= \n[doc-arg-limit]) \{\
-.          nop "\*[doc-arg\n[doc-reg-dpa1]]"
-.          nr doc-reg-dpa1 +1
-.        \}
-.        br
-.        in \n[doc-reg-dpa]u
-.      \}
-.      el \{\
-.        tmc "  MACRO REQUEST: .\*[doc-macro-name]
-.        while (\n[doc-reg-dpa1] <= \n[doc-arg-limit]) \{\
-.          tmc " "\*[doc-arg\n[doc-reg-dpa1]]"
-.          nr doc-reg-dpa1 +1
-.        \}
-.        tm
-.  \}\}\}
 .  el \{\
 .    shift
 .    doc-parse-args \$@
@@ -304,62 +215,10 @@
 .  nr doc-type\n[doc-arg-limit] \n[doc-arg-type]
 .  doc-set-spacing-\n[doc-arg-type]
 .
-.  if \n[doc-debug] \{\
-.    ds doc-str-dpav \*[doc-debug-\n[doc-arg-type]]
-.
-.    ie \n[doc-inline-debug] \{\
-.      br
-.      nr doc-reg-dpav \n[.i]u
-.      in -\n[doc-reg-dpav]u
-.
-.      if (\n[doc-arg-limit] == 1) \{\
-.        nop \f[B]DEBUG(doc-parse-arg-vector)
-.        nop MACRO:\f[P] `.\*[doc-macro-name]'
-.        nop \) \f[B]Line #:\f[P] \n[.c]
-.      \}
-.      nop \t\f[B]Argc:\f[P] \n[doc-arg-limit]
-.      nop \ \f[B]Argv:\f[P] `\*[doc-arg\n[doc-arg-limit]]'
-.      nop \ \f[B]Length:\f[P] \n[doc-width]
-.      nop \t\f[B]Space:\f[P] `\*[doc-space\n[doc-arg-limit]]'
-.      nop \ \f[B]Type:\f[P] \*[doc-str-dpav]
-.    \}
-.    el \{\
-.      if (\n[doc-arg-limit] == 1) \{\
-.        tmc "DEBUG(doc-parse-arg-vector)
-.        tm1 " MACRO: `.\*[doc-macro-name]'  Line #: \n[.c]
-.      \}
-.      tmc "  Argc: \n[doc-arg-limit]
-.      tmc "  Argv: `\*[doc-arg\n[doc-arg-limit]]'
-.      tm1 "  Length: \n[doc-width]
-.      tmc "  Space: `\*[doc-space\n[doc-arg-limit]]'
-.      tm1 "  Type: \*[doc-str-dpav]
-.  \}\}
-.
 .  ie (\n[doc-num-args] == 1) \{\
 .    nr doc-arg-ptr 0
-.
 .    nr doc-num-args 0
-.
-.    if \n[doc-debug] \{\
-.      nr doc-reg-dpav1 1
-.
-.      ie \n[doc-inline-debug] \{\
-.        nop \tMACRO REQUEST: .\*[doc-macro-name]
-.        while (\n[doc-reg-dpav1] <= \n[doc-arg-limit]) \{\
-.          nop "\*[doc-arg\n[doc-reg-dpav1]]"
-.          nr doc-reg-dpav1 +1
-.        \}
-.        br
-.        in \n[doc-reg-dpav]u
-.      \}
-.      el \{\
-.        tmc "  MACRO REQUEST: .\*[doc-macro-name]
-.        while (\n[doc-reg-dpav1] <= \n[doc-arg-limit]) \{\
-.          tmc " "\*[doc-arg\n[doc-reg-dpav1]]"
-.          nr doc-reg-dpav1 +1
-.        \}
-.        tm
-.  \}\}\}
+.  \}
 .  el \{\
 .    nr doc-num-args -1
 .    doc-parse-arg-vector
@@ -3358,7 +3217,6 @@
 .\" NS   doc-reg-dsgv
 .
 .de doc-save-global-vars
-.  nr doc-debug-saved \n[doc-debug]
 .  ds doc-macro-name-saved "\*[doc-macro-name]
 .  nr doc-arg-limit-saved \n[doc-arg-limit]
 .  nr doc-num-args-saved \n[doc-num-args]
@@ -3497,7 +3355,6 @@
 .\" NS   doc-reg-drgv
 .
 .de doc-restore-global-vars
-.  nr doc-debug \n[doc-debug-saved]
 .  ds doc-macro-name "\*[doc-macro-name-saved]
 .  nr doc-arg-limit \n[doc-arg-limit-saved]
 .  nr doc-num-args \n[doc-num-args-saved]