perlapi/perlintern: Note binary-compatibility-only entries

Some API elements exist only so that already-existing uses of them can
continue to use them without change.  Generally newer/shinier methods
have come along to accomplish the tasks these do, and new code should use
those newer methods.

It effectively is deprecated to use these for new code.

This commit changes perlapi and perlintern to highlight such elements as
not being wise to use going forward.  Also, we should feel no pressure
to add documention on how to use these elements.  The code that already
uses them probably already knows how to use them.  And if it isn't using
them properly, it would be advantageous to convert to use the shinier
method, instead of trying to figure out how to get the old one to work.

However, this change shows that some elements are wrongly marked as
being binary-compatibility only.  The list of these needs to examined,
and other commits made to remove that marking when appropriate.  The
list is contained in

http://nntp.perl.org/group/perl.perl5.porters/269936

Author: khwilliamson

autodoc.pl

@@ -77,11 +77,11 @@
                 qr/[aA bC dD eE fF Gh iI mM nN oO pP rR sS T uU vW xX y;#?]/xx;
 
 # Flags that don't apply to this program, like implementation details.
-my $irrelevant_flags_re = qr/[ab eE G iI P rR vX?]/xx;
+my $irrelevant_flags_re = qr/[a eE G iI P rR vX?]/xx;
 
 # Only certain flags dealing with what gets displayed, are acceptable for
 # apidoc_item
-my $item_flags_re = qr/[dD fF mM nN oO pT uU Wx;]/xx;
+my $item_flags_re = qr/[ b dD fF mM nN oO pT uU Wx; ]/xx;
 
 use constant {
               NOT_APIDOC         => -1,
@@ -1625,6 +1625,7 @@ ($fh, $section_name, $element_name, $docref)
     print $fh "\n=item C<${$_}->{name}>\n" for @items;
 
     my @where_froms;
+    my @bin_compat;
     my @deprecated;
     my @experimental;
     my @xrefs;
@@ -1642,8 +1643,15 @@ ($fh, $section_name, $element_name, $docref)
             # entry, so no X<> here.
             push @xrefs, $name unless $item->{flags} =~ /h/;
 
-            push @deprecated,   "C<$name>" if $item->{flags} =~ /D/;
-            push @experimental, "C<$name>" if $item->{flags} =~ /x/;
+            if ($item->{flags} =~ /D/) {
+                push @deprecated,   "C<$name>";
+            }
+            elsif ($item->{flags} =~ /b/) {
+                push @bin_compat,   "C<$name>";
+            }
+            elsif ($item->{flags} =~ /x/) {
+                push @experimental, "C<$name>";
+            }
         }
 
         # While we're going though the items, construct a nice list of where
@@ -1695,7 +1703,7 @@ ($fh, $section_name, $element_name, $docref)
     print $fh format_pod_indexes(\@xrefs);
     print $fh "\n" if @xrefs;
 
-    for my $which (\@deprecated, \@experimental) {
+    for my $which (\@deprecated, \@experimental, \@bin_compat) {
         next unless $which->@*;
 
         my $is;
@@ -1731,6 +1739,13 @@ ($fh, $section_name, $element_name, $docref)
                 new code; remove $it from existing code.
                 EOT
         }
+        elsif ($which == \@bin_compat) {
+            print $fh <<~"EOT";
+
+                C<B<DO NOT USE FOR NEW CODE!>>  $list $is retained only so
+                that existing applications that use $it don't have to change.
+                EOT
+        }
         else {
             print $fh <<~"EOT";
 
@@ -2696,7 +2711,7 @@ ($destpod)
 # documentation is missing
 
 for my $which (\%api, \%intern) {
-    my (@deprecated, @experimental, @missings);
+    my (@deprecated, @experimental, @missings, @bin_compat);
     for my $name (sort dictionary_order keys %elements) {
         my $element = $elements{$name};
 
@@ -2724,6 +2739,9 @@ ($destpod)
                 elsif ($element->{flags} =~ /x/) {
                     push @experimental, $name;
                 }
+                elsif ($element->{flags} =~ /b/) {
+                    push @bin_compat, $name;
+                }
                 else {
                     push @missings, $name;
                 }
@@ -2734,6 +2752,7 @@ ($destpod)
     $which->{missings}->@* = (
                                missings_hdr     => \@missings,
                                experimental_hdr => \@experimental,
+                               bin_compat_hdr   => \@bin_compat,
                                deprecated_hdr   => \@deprecated,
                              );
 }
@@ -2897,6 +2916,12 @@ ($destpod)
 |usable by you.
 _EOT_
 
+$api{bin_compat_hdr} = <<"_EOT_";
+|
+|Next are the API-flagged elements that are retained only so that code that
+|already uses them doesn't have to change.  DO NOT ADD ANY NEW USES FOR THESE.
+_EOT_
+
 $api{experimental_hdr} = <<"_EOT_";
 |
 |Next are the API-flagged elements that are considered experimental.  Using one
@@ -2949,9 +2974,15 @@ ($destpod)
 |This section lists the elements that are otherwise undocumented.  If you use
 |any of them, please consider creating and submitting documentation for it.
 |
-|Experimental and deprecated undocumented elements are listed separately at the
-|end.
+|Elements that are problematic to use (such as being experimental) are listed
+|separately at the end.
+|
+_EOT_
+
+$intern{bin_compat_hdr} = <<"_EOT_";
 |
+|Next are the elements that are retained only so that code that already uses
+|them doesn't have to change.  DO NOT ADD ANY NEW USES FOR THESE.
 _EOT_
 
 $intern{experimental_hdr} = <<"_EOT_";