Update perlhist

[perl5.git] / autodoc.pl

diff --git a/autodoc.pl b/autodoc.pl
index 865ee08..2e6a1c3 100644 (file)
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -29,8 +29,8 @@ if (@ARGV) {
     chdir $workdir
         or die "Couldn't chdir to '$workdir': $!";
 }
-require 'regen/regen_lib.pl';
-require 'regen/embed_lib.pl';
+require './regen/regen_lib.pl';
+require './regen/embed_lib.pl';
 
 #
 # See database of global and static function prototypes in embed.fnc
@@ -110,11 +110,14 @@ HDR_DOC:
            my $docs = "";
 DOC:
            while (defined($doc = $get_next_line->())) {
-               last DOC if $doc =~ /^=\w+/;
+
+                # Other pod commands are considered part of the current
+                # function's docs, so can have lists, etc.
+                last DOC if $doc =~ /^=(cut|for\s+apidoc|head)/;
                if ($doc =~ m:^\*/$:) {
                    warn "=cut missing? $file:$line:$doc";;
                    last DOC;
-               }
+                }
                $docs .= $doc;
            }
            $docs = "\n$docs" if $docs and $docs !~ /^\n/;
@@ -263,7 +266,7 @@ removed without notice.\n\n$docs" if $flags =~ /x/;
 sub sort_helper {
     # Do a case-insensitive dictionary sort, with only alphabetics
     # significant, falling back to using everything for determinancy
-    return (uc($a =~ s/[[^:alpha]]//r) cmp uc($b =~ s/[[^:alpha]]//r))
+    return (uc($a =~ s/[[:^alpha:]]//r) cmp uc($b =~ s/[[:^alpha:]]//r))
            || uc($a) cmp uc($b)
            || $a cmp $b;
 }
@@ -352,7 +355,7 @@ open my $fh, '<', 'MANIFEST'
 while (my $line = <$fh>) {
     next unless my ($file) = $line =~ /^(\S+\.[ch])\t/;
 
-    open F, "< $file" or die "Cannot open $file for docs: $!\n";
+    open F, '<', $file or die "Cannot open $file for docs: $!\n";
     $curheader = "Functions in file $file\n";
     autodoc(\*F,$file);
     close F or die "Error closing $file: $!\n";
@@ -396,6 +399,11 @@ 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.
 
+In Perl, unlike C, a string of characters may generally contain embedded
+C<NUL> characters.  Sometimes in the documentation a Perl string is referred
+to as a "buffer" to distinguish it from a C string, but sometimes they are
+both just referred to as strings.
+
 Note that all Perl API global variables must be referenced with the C<PL_>
 prefix.  Again, those not listed here are not to be used by extension writers,
 and can be changed or removed without notice; same with macros.
@@ -407,6 +415,14 @@ whose ordinal numbers are in the range 0 - 127).
 And documentation and comments may still use the term ASCII, when
 sometimes in fact the entire range from 0 - 255 is meant.
 
+The non-ASCII characters below 256 can have various meanings, depending on
+various things.  (See, most notably, L<perllocale>.)  But usually the whole
+range can be referred to as ISO-8859-1.  Often, the term "Latin-1" (or
+"Latin1") is used as an equivalent for ISO-8859-1.  But some people treat
+"Latin1" as referring just to the characters in the range 128 through 255, or
+somethimes from 160 through 255.
+This documentation uses "Latin1" and "Latin-1" to refer to all 256 characters.
+
 Note that Perl can be compiled and run under either ASCII or EBCDIC (See
 L<perlebcdic>).  Most of the documentation (and even comments in the code)
 ignore the EBCDIC possibility.