diff options
Diffstat (limited to 'tmac')
| -rwxr-xr-x | tmac/doc-common.new | 9 | ||||
| -rwxr-xr-x | tmac/groff_mdoc.reference.man | 178 | ||||
| -rwxr-xr-x | tmac/tmac.doc.new | 151 |
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] |