maint: introduce LintMan to aid on tracking/updating values

Allow tagging the documentation with a `#define` value that could
be then updated programmatically.

Update the value for MAX_NAME_SIZE in pcre2limits.3 that was missing
since ced3b0f (Increase name length to 128, 2024-03-11) and while
at it, improve on its description and a tag for a related variable.

For completeness, add also a tag to the same value in pcre2pattern.3
and the configuration for VMS that was missing since 6c670c7
(Update overlooked cmake update of name size to 128, 2024-03-11)

Author: carenas

doc/pcre2limits.3

@@ -47,8 +47,13 @@ when PCRE2 is built; if not, the default is set to 250. An application can
 change this limit by calling pcre2_set_parens_nest_limit() to set the limit in
 a compile context.
 .P
-The maximum length of name for a named capture group is 32 code units, and the
-maximum number of such groups is 10000.
+The maximum length of the name for a named capture group as well as the number
+of such groups is configurable at build time. The maximum length of the name
+defaults to
+.\" DEFINE MAX_NAME_SIZE
+128 code units, and the maximum number of such groups to
+.\" DEFINE MAX_NAME_COUNT
+10000.
 .P
 The maximum length of a name in a (*MARK), (*PRUNE), (*SKIP), or (*THEN) verb
 is 255 code units for the 8-bit library and 65535 code units for the 16-bit and

doc/pcre2pattern.3

@@ -2015,8 +2015,9 @@ the naming of capture groups. This feature was not added to Perl until release
 using the Python syntax. PCRE2 supports both the Perl and the Python syntax.
 .P
 In PCRE2, a capture group can be named in one of three ways: (?<name>...) or
-(?'name'...) as in Perl, or (?P<name>...) as in Python. Names may be up to 128
-code units long. When PCRE2_UTF is not set, they may contain only ASCII
+(?'name'...) as in Perl, or (?P<name>...) as in Python. Names may be up to
+.\" DEFINE MAX_NAME_SIZE
+128 code units long. When PCRE2_UTF is not set, they may contain only ASCII
 alphanumeric characters and underscores, but must start with a non-digit. When
 PCRE2_UTF is set, the syntax of group names is extended to allow any Unicode
 letter or Unicode decimal digit. In other words, group names must match one of

maint/CheckMan

@@ -39,6 +39,7 @@ while (scalar(@ARGV) > 0)
             ^\.P\s*$| 
             ^\.PP\s*$| 
             ^\.\\"(?:\ HREF)?\s*$|
+            ^\.\\"\sDEFINE\s\w+$|
             ^\.\\"\sHTML\s<a\shref="[^"]+?">\s*$|
             ^\.\\"\sHTML\s<a\sname="[^"]+?"><\/a>\s*$|
             ^\.\\"\s<\/a>\s*$|

maint/LintMan

@@ -0,0 +1,66 @@
+#!/usr/bin/perl
+
+use warnings;
+use strict;
+use Getopt::Long;
+use vars qw /$opt_verbose/;
+
+# A script to scan PCRE2's man pages to check for values that might need to
+# be updatd to match the code.
+#
+# It updates numerical values after \" DEFINE <name> or errors if name is
+# not found.
+
+my $file;
+my %defs;
+
+foreach $file ("../src/config.h")
+  {
+  open (INCLUDE, $file) or die "Failed to open include $file\n";
+
+  while (<INCLUDE>)
+    {
+    next unless /^#define ([[:upper:]_\d]+)\s+(\d+)/a;
+    $defs{$1} = $2;
+    }
+
+  close(INCLUDE);
+  }
+
+GetOptions("verbose");
+while (scalar(@ARGV) > 0)
+  {
+  $file = shift @ARGV;
+
+  open my $fh, "+<", $file or die "Failed to open $file\n";
+
+  my @lines = <$fh>;
+  my $updated = 0;
+
+  foreach my $index (0 .. $#lines)
+    {
+    if ($lines[$index] =~ /^\.\\"\sDEFINE\s([[:upper:]_\d]+)$/a)
+      {
+      my $l = $index + 1;
+      die "Invalid DEFINE line $l of $file\n" unless defined $lines[$l];
+
+      my $key = $1;
+      die "Bad DEFINE key $key line $l of $file\n" unless exists $defs{$key};
+
+      my $value = $defs{$key};
+      if ($lines[$index + 1] !~ /^$value\b/)
+        {
+        $updated += $lines[$index + 1] =~ s/^\d+/$value/a;
+        print "Updated $key in $file to $value\n" if $opt_verbose;
+        }
+      }
+    }
+
+  if ($updated > 0)
+    {
+    seek($fh, 0, 0);
+    print $fh @lines;
+    truncate($fh, tell($fh));
+    }
+  close($fh);
+  }

maint/README

@@ -60,6 +60,10 @@ GenerateUcpTables.py
   GenerateCommon.py and Unicode data files. The generated file contains tables
   for looking up Unicode property names.
 
+LintMan
+  A Perl script to check and update magic numbers in the documentation that
+  correspond to configurable settings in the codebase.
+
 manifest-*
   Data files used to verify the contents of the distribution tarball and
   `make install` file lists.

vms/configure.com

@@ -905,7 +905,7 @@ sure both macros are undefined; an emulation function will then be used. */
 #define PCRE2_EXPORT
 #define LINK_SIZE 2
 #define MAX_NAME_COUNT 10000
-#define MAX_NAME_SIZE 32
+#define MAX_NAME_SIZE 128
 #define MATCH_LIMIT 10000000
 #define HEAP_LIMIT 20000000
 #define NEWLINE_DEFAULT 2