gbranden pushed a commit to branch master
in repository groff.
commit b161e50e93f126b9c8aa194b2d85728b5b5ad508
Author: G. Branden Robinson <[email protected]>
AuthorDate: Fri Jul 17 13:20:17 2026 -0500
[grog]: Add undocumented debugging mode.
* src/utils/grog/grog.pl: New global scalar `debugging` of Boolean sense
tracks debugging state. Initialize false.
(debug): New subroutine emits diagnostic message only if
debugging is enabled.
(process_arguments): Check for `--debug` command-line option.
(interpret_line, infer_man_or_ms_package, [main]): Report debugging
information of interest.
Feature prompted by surprising diagnosis of Lesk's "Notes on the IBM C
Compiler." memo as a _me_(7) document instead of the more correct
_ms_(7). The misdiagnosis appears to be due to the inadvertent
downcasing of some _ms_(7) macro calls, `IP` and `TP` in the source
document. (There are other problems with the document, including a
fascinating crime against the CSTR #49 specification of _tbl_ input that
no contemporary implementation supports, and perhaps only Lesk himself
knew about, being that program's author.) See
<https://www.tuhs.org/pipermail/tuhs/2026-July/034010.html> ff.
---
ChangeLog | 22 ++++++++++++++++++++++
src/utils/grog/grog.pl | 26 ++++++++++++++++++++++++--
2 files changed, 46 insertions(+), 2 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 7c6c18765..ffb1d269f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,25 @@
+2026-07-17 G. Branden Robinson <[email protected]>
+
+ * src/utils/grog/grog.pl: Add undocumented debugging mode. New
+ global scalar `debugging` of Boolean sense tracks debugging
+ state. Initialize false.
+ (debug): New subroutine emits diagnostic message only if
+ debugging is enabled.
+ (process_arguments): Check for `--debug` command-line option.
+ (interpret_line, infer_man_or_ms_package, [main]): Report
+ debugging information of interest.
+
+ Feature prompted by surprising diagnosis of Lesk's "Notes on the
+ IBM C Compiler." memo as a _me_(7) document instead of the more
+ correct _ms_(7). The misdiagnosis appears to be due to the
+ inadvertent downcasing of some _ms_(7) macro calls, `IP` and
+ `TP` in the source document. (There are other problems with the
+ document, including a fascinating crime against the CSTR #49
+ specification of _tbl_ input that no contemporary implementation
+ supports, and perhaps only Lesk himself knew about, being that
+ program's author.) See
+ <https://www.tuhs.org/pipermail/tuhs/2026-July/034010.html> ff.
+
2026-07-16 G. Branden Robinson <[email protected]>
* doc/doc.am (doc/webpage.html): Restore `$(DOC_GNU_EPS)` as
diff --git a/src/utils/grog/grog.pl b/src/utils/grog/grog.pl
index 075c03201..76a42a081 100644
--- a/src/utils/grog/grog.pl
+++ b/src/utils/grog/grog.pl
@@ -66,6 +66,7 @@ my $have_seen_first_macro_call = 0;
# man(7) and ms(7) use many of the same macro names; do extra checking.
my $man_score = 0;
my $ms_score = 0;
+my $debugging = 0;
my $had_inference_problem = 0;
my $had_processing_problem = 0;
@@ -85,6 +86,14 @@ sub gripe {
}
+sub debug {
+ if ($debugging) {
+ my $text = shift;
+ print STDERR "$program_name: debug: $text\n";
+ }
+}
+
+
sub process_arguments {
my $no_more_options = 0;
my $delayed_option = '';
@@ -140,7 +149,9 @@ sub process_arguments {
version() if ($arg eq '-v' || $arg eq '--version');
usage(0) if ($arg eq '-h' || $arg eq '--help');
- if ($arg =~ '^--.') {
+ if ($arg eq '--debug') {
+ $debugging = 1;
+ } elsif ($arg =~ '^--.') {
fail("unrecognized grog option '$arg'; ignored");
usage(1);
next;
@@ -216,6 +227,7 @@ sub interpret_line {
# is redefined, we could delete it from the relevant lists and
# hashes.
if ($line =~ /\\\" Automatically generated by Pod::Man/) {
+ debug("Pod::Man document detected: juicing \$man_score");
$man_score += 100;
}
@@ -350,6 +362,7 @@ sub interpret_line {
# What remains must be a macro name.
my $macro = $command;
+ debug("incrementing \$score{$macro}");
$score{$macro}++;
@@ -363,6 +376,7 @@ sub interpret_line {
# We can put one thumb on the scale, however.
if ((!$have_seen_first_macro_call) && ($macro eq 'TH')) {
# TH as the first call in a document screams man(7).
+ debug("first macro call is 'TH': juicing \$man_score");
$man_score += 100;
}
@@ -561,6 +575,9 @@ sub infer_man_or_ms_package {
$ms_score += $score{$key};
}
+ debug("\$man_score = $man_score");
+ debug("\$ms_score = $ms_score");
+
if (!$ms_score && !$man_score) {
# The input may be a "raw" roff document; this is not a problem,
# but it does mean no package was inferred.
@@ -710,7 +727,12 @@ read_input();
if ($have_any_valid_operands) {
infer_preprocessors();
- infer_man_or_ms_package() if (scalar @inferred_main_package != 1);
+ if (scalar @inferred_main_package != 1) {
+ infer_man_or_ms_package();
+ } else {
+ debug("skipping man vs. ms disambiguation; already inferred package"
+ . " '@inferred_main_package'");
+ }
construct_command();
}
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
