Remove "experimental" tag from statistics_info () (issue#134)

Changes

@@ -1,3 +1,6 @@
+1.646 - 2024-09-19, H.Merijn Brand
+    * Remove "experimental" tag from statistics_info () (issue#134)
+
 1.645 - 2024-09-03, H.Merijn Brand
 
     * Move developer tests to xt/

DBI.pm

@@ -15,7 +15,7 @@ use warnings;
 
 our ($XS_VERSION, $VERSION);
 BEGIN {
-$VERSION = "1.645"; # ==> ALSO update the version in the pod text below!
+$VERSION = "1.646"; # ==> ALSO update the version in the pod text below!
 $XS_VERSION = $VERSION;
 $VERSION =~ tr/_//d;
 }
@@ -147,7 +147,7 @@ sure that your issue isn't related to the driver you're using.
 
 =head2 NOTES
 
-This is the DBI specification that corresponds to DBI version 1.645
+This is the DBI specification that corresponds to DBI version 1.646
 (see L<DBI::Changes> for details).
 
 The DBI is evolving at a steady pace, so it's good to check that
@@ -5438,8 +5438,6 @@ See also L</"Catalog Methods"> and L</"Standards Reference Information">.
 
 =head3 C<statistics_info>
 
-B<Warning:> This method is experimental and may change.
-
   $sth = $dbh->statistics_info( $catalog, $schema, $table, $unique_only, $quick );
 
   # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

doc/DBI.3

@@ -58,7 +58,7 @@
 .\" ========================================================================
 .\"
 .IX Title "DBI 3"
-.TH DBI 3 2024-09-03 "perl v5.40.0" "User Contributed Perl Documentation"
+.TH DBI 3 2024-09-19 "perl v5.40.0" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -190,7 +190,7 @@ page for your driver. Only submit a bug report against the DBI itself if you\*(A
 sure that your issue isn\*(Aqt related to the driver you\*(Aqre using.
 .SS NOTES
 .IX Subsection "NOTES"
-This is the DBI specification that corresponds to DBI version 1.644
+This is the DBI specification that corresponds to DBI version 1.646
 (see DBI::Changes for details).
 .PP
 The DBI is evolving at a steady pace, so it\*(Aqs good to check that
@@ -3838,8 +3838,6 @@ See also "Catalog Methods" and "Standards Reference Information".
 \fR\f(CI\*(C`statistics_info\*(C'\fR\fI\fR
 .IX Subsection "statistics_info"
 .PP
-\&\fBWarning:\fR This method is experimental and may change.
-.PP
 .Vb 1
 \&  $sth = $dbh\->statistics_info( $catalog, $schema, $table, $unique_only, $quick );
 \&

doc/DBI.html

@@ -422,7 +422,7 @@ <h3 id="Reporting-a-Bug">Reporting a Bug</h3>
 
 <h2 id="NOTES">NOTES</h2>
 
-<p>This is the DBI specification that corresponds to DBI version 1.644 (see <a>DBI::Changes</a> for details).</p>
+<p>This is the DBI specification that corresponds to DBI version 1.646 (see <a>DBI::Changes</a> for details).</p>
 
 <p>The DBI is evolving at a steady pace, so it&#39;s good to check that you have the latest copy.</p>
 
@@ -2604,8 +2604,6 @@ <h3 id="foreign_key_info"><code>foreign_key_info</code></h3>
 
 <h3 id="statistics_info"><code>statistics_info</code></h3>
 
-<p><b>Warning:</b> This method is experimental and may change.</p>
-
 <pre><code>$sth = $dbh-&gt;statistics_info( $catalog, $schema, $table, $unique_only, $quick );
 
 # then $sth-&gt;fetchall_arrayref or $sth-&gt;fetchall_hashref etc</code></pre>

doc/DBI.md

@@ -126,7 +126,7 @@ sure that your issue isn't related to the driver you're using.
 
 ## NOTES
 
-This is the DBI specification that corresponds to DBI version 1.644
+This is the DBI specification that corresponds to DBI version 1.646
 (see [DBI::Changes](https://metacpan.org/pod/DBI%3A%3AChanges) for details).
 
 The DBI is evolving at a steady pace, so it's good to check that
@@ -3389,8 +3389,6 @@ See also ["Catalog Methods"](#catalog-methods) and ["Standards Reference Informa
 
 ### `statistics_info`
 
-**Warning:** This method is experimental and may change.
-
     $sth = $dbh->statistics_info( $catalog, $schema, $table, $unique_only, $quick );
 
     # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

doc/DBI::Changes.3

@@ -73,6 +73,10 @@ Move developer tests to xt/
 Make Changes match CPAN::Changes::Spec and regen DBI::Changes from that
 .IP \(bu 2
 Fixes for modern gcc i.c.w. recent perl (Daniël)
+.IP \(bu 2
+Small code & doc cleanups for recent perl
+.IP \(bu 2
+See TODO in \`perldoc DBI\` to see where you can help with documentation!
 .SS "Changes in DBI 1.644 \- 23 Aug 2024"
 .IX Subsection "Changes in DBI 1.644 - 23 Aug 2024"
 .Vb 10

doc/DBI::Changes.html

@@ -172,6 +172,12 @@ <h2 id="Changes-in-DBI-1.645---03-Sep-2024">Changes in DBI 1.645 - 03 Sep 2024</
 </li>
 <li><p>Fixes for modern gcc i.c.w. recent perl (Dani&euml;l)</p>
 
+</li>
+<li><p>Small code &amp; doc cleanups for recent perl</p>
+
+</li>
+<li><p>See TODO in `perldoc DBI` to see where you can help with documentation!</p>
+
 </li>
 </ul>
 

doc/DBI::Changes.md

@@ -6,7 +6,9 @@ DBI::Changes - List of significant changes to the DBI
 
 - Move developer tests to xt/
 - Make Changes match CPAN::Changes::Spec and regen DBI::Changes from that
-- Fixes for modern gcc i.c.w. recent perl (Daniël)
+- Fixes for modern gcc i.c.w. recent perl (Daniël)
+- Small code & doc cleanups for recent perl
+- See TODO in \`perldoc DBI\` to see where you can help with documentation!
 
 ## Changes in DBI 1.644 - 23 Aug 2024
 
@@ -15,9 +17,9 @@ DBI::Changes - List of significant changes to the DBI
     Fix CVE-2014-10401 and CVE-2014-10402 - f_dir might not exist in DBD::File connections
         thanks to Jens Rehsack & H.Merijn Brand
     Do not check gccversion on clang
-        thanks to Daniël van Eeden
+        thanks to Daniël van Eeden
     Upgrade GIMME to GIMME_V
-        thanks to Daniël van Eeden
+        thanks to Daniël van Eeden
     Do not check with JSON::XS with perl-5.022 and later
         thanks to H.Merijn Brand
     Makefile.PL allows gcc-10 and up now
@@ -39,11 +41,11 @@ DBI::Changes - List of significant changes to the DBI
     Fix potentially calling newSV(0) in malloc_using_sv()
         thanks to Pali
     Fix order of XS preparse() ps_accept and ps_return argument names
-        thanks to Petr Písař
+        thanks to Petr Písař
     Fix a potential NULL profile dereference in dbi_profile()
-        thanks to Petr Písař
+        thanks to Petr Písař
     Fix a buffer overflow on an overlong DBD class name
-        thanks to Petr Písař
+        thanks to Petr Písař
 
     Remove remnants of support for perl <= v5.8.0
         thanks to Pali and H.Merijn Brand
@@ -233,7 +235,7 @@ which was made possible by the generosity of many sponsors:
     Changed $sth->{TYPE} to be NUMERIC in DBD::File drivers as per the
         DBI docs. Note TYPE_NAME is now also available. [H.Merijn Brand]
     Fixed compilation error on bleadperl due DEFSV no longer being an lvalue
-        [Dagfinn Ilmari Mannsåker]
+        [Dagfinn Ilmari Mannsåker]
 
     Added docs for escaping placeholders using a backslash.
     Added docs for get_info(9000) indicating ability to escape placeholders.
@@ -323,7 +325,7 @@ There was no DBI 1.629 release.
     Change DBI's docs to refer to git not svn [H.Merijn Brand]
     Clarify bind_col TYPE attribute is sticky [Martin J. Evans]
     Fixed reference to $sth in selectall_arrayref docs RT#84873
-    Spelling fixes [Ville Skyttä]
+    Spelling fixes [Ville Skyttä]
     Changed $VERSIONs to hardcoded strings [H.Merijn Brand]
 
 ## Changes in DBI 1.627 - 16 May 2013
@@ -425,9 +427,9 @@ There was no DBI 1.629 release.
     Optimized driver access to handle data thanks to Dave Mitchell.
       Dave's work on these optimizations was sponsored by Booking.com.
     Optimized fetchall_arrayref with hash slice thanks
-      to Dagfinn Ilmari Mannsåker. RT#76520
+      to Dagfinn Ilmari Mannsåker. RT#76520
     Allow renaming columns in fetchall_arrayref hash slices
-      thanks to Dagfinn Ilmari Mannsåker. RT#76572
+      thanks to Dagfinn Ilmari Mannsåker. RT#76572
     Reserved snmp_ and tree_ for DBD::SNMP and DBD::TreeData
 
 ## Changes in DBI 1.618 (svn rev 15170) - 25 Feb 2012
@@ -475,7 +477,7 @@ There was no DBI 1.629 release.
     Added some more fetchall_arrayref(..., $maxrows) tests (Tim Bunce)
     Clarified docs for fetchall_arrayref called on an inactive handle.
     Clarified docs for clone method (Tim Bunce)
-    Added note to DBI::Profile about async queries (Marcel Grünauer).
+    Added note to DBI::Profile about async queries (Marcel Grünauer).
     Reserved spatialite_ as a driver prefix for DBD::Spatialite
     Reserved mo_ as a driver prefix for DBD::MO
     Updated link to the SQL Reunion 95 docs, RT69577 (Ash Daminato)
@@ -1106,7 +1108,7 @@ Jens Rehsack, Martin J. Evans, and H.Merijn Brand for all their contributions.
 
     Fixed DBI::ProxyServer to not create pid files by default.
       References: Ubuntu Security Notice USN-70-1, CAN-2005-0077
-      Thanks to Javier Fernández-Sanguino Peña from the
+      Thanks to Javier Fernández-Sanguino Peña from the
       Debian Security Audit Project, and Jonathan Leffler.
     Fixed some tests to work with older Test::More versions.
     Fixed setting $DBI::err/errstr in DBI::PurePerl.

make-doc.pl

@@ -3,7 +3,7 @@
 use 5.040000;
 use warnings;
 
-our $VERSION = "0.02 - 20240825";
+our $VERSION = "0.03 - 20240904";
 our $CMD = $0 =~ s{.*/}{}r;
 
 sub usage {
@@ -21,11 +21,14 @@ sub usage {
     "v|verbose:1"	=> \(my $opt_v = 0),
     ) or usage (1);
 
+-d "doc" or mkdir "doc", 0775;
+
 my @pm = sort "DBI.pm",
 	(glob "lib/*/*.pm"),
 	(glob "lib/*/*/*.pm"),
 	(glob "lib/*/*/*/*.pm");
 
+my %enc;
 eval { require Pod::Checker; };
 if ($@) {
     warn "Cannot convert pod to markdown: $@\n";
@@ -34,8 +37,10 @@ sub usage {
     my $fail = 0;
     foreach my $pm (@pm) {
 	open my $eh, ">", \my $err;
-	my $ok = Pod::Checker->new ()->parse_from_file ($pm, $eh);
+	my $pc = Pod::Checker->new ();
+	my $ok = $pc->parse_from_file ($pm, $eh);
 	close $eh;
+	$enc{$pm} = $pc->{encoding};
 	$err && $err =~ m/\S/ or next;
 	if ($pm eq "lib/DBI/ProfileData.pm") {
 	    # DBI::Profile has 7 warnings on empty previous paragraphs
@@ -59,17 +64,13 @@ sub usage {
     foreach my $pm (@pm) {
 	my $md = $pm =~ s{^lib/}{}r =~ s{/}{::}gr =~ s{\.pm$}{.md}r =~ s{^}{doc/}r;
 	printf STDERR "%-43s <- %s\n", $md, $pm if $opt_v;
-	open my $ph, "<:bytes", $pm;
-	open my $mh, ">:bytes", \my $m;
+	my $enc = $enc{$pm} ? "encoding($enc{$pm})" : "bytes";
+	say "$pm ($enc)" if $opt_v > 1;
+	open my $ph, "<:$enc", $pm;
 	my $p = Pod::Markdown->new ();
-	my @w;
-	{   local $SIG{__WARN__} = sub { push @w => $_ };
-	    $p->output_fh  ($mh);
-	    $p->parse_file ($ph);
-	    }
-	warn $_ for grep { length and ! m/^Wide character in print/ } @w;
+	$p->output_string (\my $m);
+	$p->parse_file ($ph);
 	close $ph;
-	close $mh;
 
 	$m && $m =~ m/\S/ or next;
 	if (open my $old, "<:encoding(utf-8)", $md) {
@@ -106,6 +107,7 @@ sub usage {
 	print $oh $h;
 	close $oh;
 	}
+    unlink "pod2htmd.tmp";
     }
 
 eval { require Pod::Man; };