autodoc.pl: Improve the SEE ALSO section

This harvests all the pods linked to by perlapi/perlintern and puts them
in the SEE ALSO section

1 files changed, 17 insertions, 29 deletions

diff --git a/autodoc.pl b/autodoc.pl
index 1816297afc..30a1b6d2fa 100644
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -36,28 +36,7 @@ if (@ARGV) {
 require './regen/regen_lib.pl';
 require './regen/embed_lib.pl';
 
-my @specialized_docs = sort qw( perlguts
-                                perlxs
-                                perlxstut
-                                perlclib
-                                warnings
-                                perlapio
-                                perlcall
-                                perlfilter
-                                perlmroapi
-                                config.h
-                              );
-sub name_in_pod($) {
-    my $name = shift;
-    return "F<$name>" if $name =~ /\./;
-    return "L<$name>";
-}
-my $other_places_api = join " ",    map { name_in_pod($_) } sort @specialized_docs, 'perlintern';
-my $other_places_intern = join " ", map { name_in_pod($_) } sort @specialized_docs, 'perlapi';
-
-@specialized_docs = map { name_in_pod($_) } sort @specialized_docs;
-$specialized_docs[-1] =~ s/^/and /;
-my $specialized_docs = join ", ", @specialized_docs;
+my %described_elsewhere;
 
 #
 # See database of global and static function prototypes in embed.fnc
@@ -211,6 +190,9 @@ EOS
                 my $podname = $file =~ s!.*/!!r;    # Rmv directory name(s)
                 $podname =~ s/\.pod//;
                 $docs .= "Described in L<$podname>.\n\n";
+
+                # Keep track of all the pod files that we refer to.
+                push $described_elsewhere{$podname}->@*, $podname;
             }
             else {
               DOC:
@@ -472,6 +454,10 @@ foreach (sort keys %missing) {
 my @missing_api = grep $funcflags{$_}{flags} =~ /A/
                     && $funcflags{$_}{flags} !~ /[xD]/
                     && !$docs{api}{$_}, keys %funcflags;
+
+my $other_places = join ", ", map { "L<$_>" } sort sort_helper qw( perlclib perlxs),
+                                                               keys %described_elsewhere;
+
 output('perlapi', <<"_EOB_", $docs{api}, \@missing_api, <<"_EOE_");
 |=encoding UTF-8
 |
@@ -484,16 +470,18 @@ output('perlapi', <<"_EOB_", $docs{api}, \@missing_api, <<"_EOE_");
 |
 |This file contains most of the documentation of the perl public API, as
 |generated by F<embed.pl>.  Specifically, it is a listing of functions,
-|macros, flags, and variables that may be used by extension writers.  Some
-|specialized items are instead documented in $specialized_docs.
+|macros, flags, and variables that may be used by extension writers.  Besides
+|L<perlintern> and F<config.h>, some items are listed here as being actually
+|documented in another pod.
 |
 |L<At the end|/Undocumented functions> is a list of functions which have yet
 |to be documented.  Patches welcome!  The interfaces of these are subject to
 |change without notice.
 |
-|Anything not listed here is not part of the public API, and should not be
-|used by extension writers at all.  For these reasons, blindly using functions
-|listed in proto.h is to be avoided when writing extensions.
+|Anything not listed here or in the other mentioned pods is not part of the
+|public API, and should not be used by extension writers at all.  For these
+|reasons, blindly using functions listed in F<proto.h> is to be avoided when
+|writing extensions.
 |
 |In Perl, unlike C, a string of characters may generally contain embedded
 |C<NUL> characters.  Sometimes in the documentation a Perl string is referred
@@ -552,7 +540,7 @@ _EOB_
 |
 |=head1 SEE ALSO
 |
-$other_places_api
+|F<config.h>, L<perlintern>, $other_places
 _EOE_
 
 # List of non-static internal functions
@@ -583,5 +571,5 @@ _EOB_
 |
 |=head1 SEE ALSO
 |
-$other_places_intern
+|F<config.h>, L<perlapi>, $other_places
 _EOE_