[perl5.git] / autodoc.pl

#!/usr/bin/perl -w
# 
# Unconditionally regenerate:
#
#    pod/perlintern.pod
#    pod/perlapi.pod
#
# from information stored in
#
#    embed.fnc
#    plus all the .c and .h files listed in MANIFEST
#
# Has an optional arg, which is the directory to chdir to before reading
# MANIFEST and *.[ch].
#
# This script is normally invoked as part of 'make all', but is also
# called from from regen.pl.

use strict;

#
# See database of global and static function prototypes in embed.fnc
# This is used to generate prototype headers under various configurations,
# export symbols lists for different platforms, and macros to provide an
# implicit interpreter context argument.
#

my %docs;
my %funcflags;
my %macro = (
	     ax => 1,
	     items => 1,
	     ix => 1,
	     svtype => 1,
	    );
my %missing;

my $curheader = "Unknown section";

sub autodoc ($$) { # parse a file and extract documentation info
    my($fh,$file) = @_;
    my($in, $doc, $line);
FUNC:
    while (defined($in = <$fh>)) {
	if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ &&
	    ($file ne 'embed.h' || $file ne 'proto.h')) {
	    $macro{$1} = $file;
	    next FUNC;
	}
        if ($in=~ /^=head1 (.*)/) {
            $curheader = $1;
            next FUNC;
        }
	$line++;
	if ($in =~ /^=for\s+apidoc\s+(.*?)\s*\n/) {
	    my $proto = $1;
	    $proto = "||$proto" unless $proto =~ /\|/;
	    my($flags, $ret, $name, @args) = split /\|/, $proto;
	    my $docs = "";
DOC:
	    while (defined($doc = <$fh>)) {
		$line++;
		last DOC if $doc =~ /^=\w+/;
		if ($doc =~ m:^\*/$:) {
		    warn "=cut missing? $file:$line:$doc";;
		    last DOC;
		}
		$docs .= $doc;
	    }
	    $docs = "\n$docs" if $docs and $docs !~ /^\n/;

	    # Check the consistency of the flags
	    my ($embed_where, $inline_where);
	    my ($embed_may_change, $inline_may_change);

	    my $docref = delete $funcflags{$name};
	    if ($docref and %$docref) {
		$embed_where = $docref->{flags} =~ /A/ ? 'api' : 'guts';
		$embed_may_change = $docref->{flags} =~ /M/;
	    } else {
		$missing{$name} = $file;
	    }
	    if ($flags =~ /m/) {
		$inline_where = $flags =~ /A/ ? 'api' : 'guts';
		$inline_may_change = $flags =~ /x/;

		if (defined $embed_where && $inline_where ne $embed_where) {
		    warn "Function '$name' inconsistency: embed.fnc says $embed_where, Pod says $inline_where";
		}

		if (defined $embed_may_change
		    && $inline_may_change ne $embed_may_change) {
		    my $message = "Function '$name' inconsistency: ";
		    if ($embed_may_change) {
			$message .= "embed.fnc says 'may change', Pod does not";
		    } else {
			$message .= "Pod says 'may change', embed.fnc does not";
		    }
		    warn $message;
		}
	    } elsif (!defined $embed_where) {
		warn "Unable to place $name!\n";
		next;
	    } else {
		$inline_where = $embed_where;
		$flags .= 'x' if $embed_may_change;
		@args = @{$docref->{args}};
		$ret = $docref->{retval};
	    }

	    $docs{$inline_where}{$curheader}{$name}
		= [$flags, $docs, $ret, $file, @args];

	    if (defined $doc) {
		if ($doc =~ /^=(?:for|head)/) {
		    $in = $doc;
		    redo FUNC;
		}
	    } else {
		warn "$file:$line:$in";
	    }
	}
    }
}

sub docout ($$$) { # output the docs for one function
    my($fh, $name, $docref) = @_;
    my($flags, $docs, $ret, $file, @args) = @$docref;
    $name =~ s/\s*$//;

    $docs .= "NOTE: this function is experimental and may change or be
removed without notice.\n\n" if $flags =~ /x/;
    $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
	if $flags =~ /p/;
    $docs .= "NOTE: this function must be explicitly called as Perl_$name with an aTHX_ parameter.\n\n"
        if $flags =~ /o/;

    print $fh "=item $name\nX<$name>\n$docs";

    if ($flags =~ /U/) { # no usage
	# nothing
    } elsif ($flags =~ /s/) { # semicolon ("dTHR;")
	print $fh "\t\t$name;\n\n";
    } elsif ($flags =~ /n/) { # no args
	print $fh "\t$ret\t$name\n\n";
    } elsif ($flags =~ /o/) { # no #define foo Perl_foo
        print $fh "\t$ret\tPerl_$name";
        print $fh "(" . (@args ? "pTHX_ " : "pTHX");
        print $fh join(", ", @args) . ")\n\n";
    } else { # full usage
	print $fh "\t$ret\t$name";
	print $fh "(" . join(", ", @args) . ")";
	print $fh "\n\n";
    }
    print $fh "=for hackers\nFound in file $file\n\n";
}

sub output {
    my ($podname, $header, $dochash, $missing, $footer) = @_;
    my $filename = "pod/$podname.pod";
    open my $fh, '>', $filename or die "Can't open $filename: $!";

    print $fh <<"_EOH_", $header;
-*- buffer-read-only: t -*-

!!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
This file is built by $0 extracting documentation from the C source
files.

_EOH_

    my $key;
    # case insensitive sort, with fallback for determinacy
    for $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$dochash) {
	my $section = $dochash->{$key}; 
	print $fh "\n=head1 $key\n\n=over 8\n\n";
	# Again, fallback for determinacy
	for my $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$section) {
	    docout($fh, $key, $section->{$key});
	}
	print $fh "\n=back\n";
    }

    if (@$missing) {
        print $fh "\n=head1 Undocumented functions\n\n";
	print $fh "These functions are currently undocumented:\n\n=over\n\n";
	for my $missing (sort @$missing) {
	    print $fh "=item $missing\nX<$missing>\n\n";
	}
	print $fh "=back\n\n";
    }

    print $fh $footer, <<'_EOF_';
=cut

 ex: set ro:
_EOF_

    close $fh or die "Can't close $filename: $!";
}

if (@ARGV) {
    my $workdir = shift;
    chdir $workdir
        or die "Couldn't chdir to '$workdir': $!";
}

open IN, "embed.fnc" or die $!;

while (<IN>) {
    chomp;
    next if /^:/;
    while (s|\\\s*$||) {
	$_ .= <IN>;
	chomp;
    }
    s/\s+$//;
    next if /^\s*(#|$)/;

    my ($flags, $retval, $func, @args) = split /\s*\|\s*/, $_;

    next unless $func;

    s/\b(NN|NULLOK)\b\s+//g for @args;
    $func =~ s/\t//g; # clean up fields from embed.pl
    $retval =~ s/\t//;

    $funcflags{$func} = {
			 flags => $flags,
			 retval => $retval,
			 args => \@args,
			};
}

my $file;
# glob() picks up docs from extra .c or .h files that may be in unclean
# development trees.
my $MANIFEST = do {
  local ($/, *FH);
  open FH, "MANIFEST" or die "Can't open MANIFEST: $!";
  <FH>;
};

for $file (($MANIFEST =~ /^(\S+\.c)\t/gm), ($MANIFEST =~ /^(\S+\.h)\t/gm)) {
    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";
}

for (sort keys %funcflags) {
    next unless $funcflags{$_}{flags} =~ /d/;
    warn "no docs for $_\n"
}

foreach (sort keys %missing) {
    next if $macro{$_};
    # Heuristics for known not-a-function macros:
    next if /^[A-Z]/;
    next if /^dj?[A-Z]/;

    warn "Function '$_', documented in $missing{$_}, not listed in embed.fnc";
}

# walk table providing an array of components in each line to
# subroutine, printing the result

my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && !$docs{api}{$_}, keys %funcflags;
output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
=head1 NAME

perlapi - autogenerated documentation for the perl public API

=head1 DESCRIPTION
X<Perl API> X<API> X<api>

This file contains the documentation of the perl public API generated by
embed.pl, specifically a listing of functions, macros, flags, and variables
that may be used by extension writers.  The interfaces of any functions that
are not listed here are subject to change without notice.  For this reason,
blindly using functions listed in proto.h is to be avoided when writing
extensions.

Note that all Perl API global variables must be referenced with the C<PL_>
prefix.  Some macros are provided for compatibility with the older,
unadorned names, but this support may be disabled in a future release.

Perl was originally written to handle US-ASCII only (that is characters
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.

Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
or ASCII.  Most of the documentation (and even comments in the code)
ignore the EBCDIC possibility.  
For almost all purposes the differences are transparent.
As an example, under EBCDIC,
instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
whenever this documentation refers to C<utf8>
(and variants of that name, including in function names),
it also (essentially transparently) means C<UTF-EBCDIC>.
But the ordinals of characters differ between ASCII, EBCDIC, and
the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
than in UTF-8.

Also, on some EBCDIC machines, functions that are documented as operating on
US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all
256 characters in the EBCDIC range, not just the subset corresponding to
US-ASCII.

The listing below is alphabetical, case insensitive.

_EOB_

=head1 AUTHORS

Until May 1997, this document was maintained by Jeff Okamoto
<okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.

With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
Stephen McCamant, and Gurusamy Sarathy.

API Listing originally by Dean Roehrich <roehrich@cray.com>.

Updated to be autogenerated from comments in the source by Benjamin Stuhl.

=head1 SEE ALSO

L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern>

_EOE_

my @missing_guts = grep $funcflags{$_}{flags} !~ /A/ && !$docs{guts}{$_}, keys %funcflags;

output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END');
=head1 NAME

perlintern - autogenerated documentation of purely B<internal>
		 Perl functions

=head1 DESCRIPTION
X<internal Perl functions> X<interpreter functions>

This file is the autogenerated documentation of functions in the
Perl interpreter that are documented using Perl's internal documentation
format but are not marked as part of the Perl API. In other words,
B<they are not for use in extensions>!

END

=head1 AUTHORS

The autodocumentation system was originally added to the Perl core by
Benjamin Stuhl. Documentation is by whoever was kind enough to
document their functions.

=head1 SEE ALSO

L<perlguts>, L<perlapi>

END
Commit	Line	Data
94bdecf9	1	#!/usr/bin/perl -w
6294c161 DM	2	#
	3	# Unconditionally regenerate:
	4	#
	5	# pod/perlintern.pod
	6	# pod/perlapi.pod
	7	#
	8	# from information stored in
	9	#
	10	# embed.fnc
	11	# plus all the .c and .h files listed in MANIFEST
	12	#
	13	# Has an optional arg, which is the directory to chdir to before reading
	14	# MANIFEST and *.[ch].
	15	#
	16	# This script is normally invoked as part of 'make all', but is also
	17	# called from from regen.pl.
94bdecf9	18
56a0c332	19	use strict;
a64c954a	20
94bdecf9	21	#
346f75ff	22	# See database of global and static function prototypes in embed.fnc
94bdecf9 JH	23	# This is used to generate prototype headers under various configurations,
	24	# export symbols lists for different platforms, and macros to provide an
	25	# implicit interpreter context argument.
	26	#
	27
6a235718	28	my %docs;
5ce57792 NC	29	my %funcflags;
	30	my %macro = (
	31	ax => 1,
	32	items => 1,
	33	ix => 1,
	34	svtype => 1,
	35	);
	36	my %missing;
94bdecf9 JH	37
	38	my $curheader = "Unknown section";
	39
	40	sub autodoc ($$) { # parse a file and extract documentation info
	41	my($fh,$file) = @_;
	42	my($in, $doc, $line);
	43	FUNC:
	44	while (defined($in = <$fh>)) {
5ce57792 NC	45	if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ &&
	46	($file ne 'embed.h' \|\| $file ne 'proto.h')) {
	47	$macro{$1} = $file;
	48	next FUNC;
	49	}
94bdecf9 JH	50	if ($in=~ /^=head1 (.*)/) {
	51	$curheader = $1;
	52	next FUNC;
	53	}
	54	$line++;
78c9d763	55	if ($in =~ /^=for\s+apidoc\s+(.?)\s\n/) {
94bdecf9 JH	56	my $proto = $1;
	57	$proto = "\|\|$proto" unless $proto =~ /\\|/;
	58	my($flags, $ret, $name, @args) = split /\\|/, $proto;
	59	my $docs = "";
	60	DOC:
	61	while (defined($doc = <$fh>)) {
94bdecf9 JH	62	$line++;
	63	last DOC if $doc =~ /^=\w+/;
	64	if ($doc =~ m:^\*/$:) {
	65	warn "=cut missing? $file:$line:$doc";;
	66	last DOC;
	67	}
	68	$docs .= $doc;
	69	}
	70	$docs = "\n$docs" if $docs and $docs !~ /^\n/;
5ce57792 NC	71
	72	# Check the consistency of the flags
	73	my ($embed_where, $inline_where);
	74	my ($embed_may_change, $inline_may_change);
	75
	76	my $docref = delete $funcflags{$name};
	77	if ($docref and %$docref) {
	78	$embed_where = $docref->{flags} =~ /A/ ? 'api' : 'guts';
	79	$embed_may_change = $docref->{flags} =~ /M/;
	80	} else {
	81	$missing{$name} = $file;
94bdecf9	82	}
5ce57792 NC	83	if ($flags =~ /m/) {
	84	$inline_where = $flags =~ /A/ ? 'api' : 'guts';
	85	$inline_may_change = $flags =~ /x/;
	86
	87	if (defined $embed_where && $inline_where ne $embed_where) {
	88	warn "Function '$name' inconsistency: embed.fnc says $embed_where, Pod says $inline_where";
	89	}
	90
	91	if (defined $embed_may_change
	92	&& $inline_may_change ne $embed_may_change) {
	93	my $message = "Function '$name' inconsistency: ";
	94	if ($embed_may_change) {
	95	$message .= "embed.fnc says 'may change', Pod does not";
	96	} else {
	97	$message .= "Pod says 'may change', embed.fnc does not";
	98	}
	99	warn $message;
	100	}
	101	} elsif (!defined $embed_where) {
	102	warn "Unable to place $name!\n";
	103	next;
	104	} else {
	105	$inline_where = $embed_where;
	106	$flags .= 'x' if $embed_may_change;
	107	@args = @{$docref->{args}};
	108	$ret = $docref->{retval};
94bdecf9	109	}
5ce57792 NC	110
	111	$docs{$inline_where}{$curheader}{$name}
	112	= [$flags, $docs, $ret, $file, @args];
	113
94bdecf9	114	if (defined $doc) {
e509e693	115	if ($doc =~ /^=(?:for\|head)/) {
94bdecf9 JH	116	$in = $doc;
	117	redo FUNC;
	118	}
	119	} else {
	120	warn "$file:$line:$in";
	121	}
	122	}
	123	}
	124	}
	125
	126	sub docout ($$$) { # output the docs for one function
	127	my($fh, $name, $docref) = @_;
	128	my($flags, $docs, $ret, $file, @args) = @$docref;
d8c40edc	129	$name =~ s/\s*$//;
94bdecf9 JH	130
	131	$docs .= "NOTE: this function is experimental and may change or be
	132	removed without notice.\n\n" if $flags =~ /x/;
	133	$docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
	134	if $flags =~ /p/;
5afac1eb BM	135	$docs .= "NOTE: this function must be explicitly called as Perl_$name with an aTHX_ parameter.\n\n"
5afac1eb BM	136	if $flags =~ /o/;
94bdecf9	137
d8c40edc	138	print $fh "=item $name\nX<$name>\n$docs";
94bdecf9 JH	139
	140	if ($flags =~ /U/) { # no usage
	141	# nothing
	142	} elsif ($flags =~ /s/) { # semicolon ("dTHR;")
	143	print $fh "\t\t$name;\n\n";
	144	} elsif ($flags =~ /n/) { # no args
	145	print $fh "\t$ret\t$name\n\n";
5afac1eb BM	146	} elsif ($flags =~ /o/) { # no #define foo Perl_foo
	147	print $fh "\t$ret\tPerl_$name";
	148	print $fh "(" . (@args ? "pTHX_ " : "pTHX");
	149	print $fh join(", ", @args) . ")\n\n";
94bdecf9 JH	150	} else { # full usage
	151	print $fh "\t$ret\t$name";
	152	print $fh "(" . join(", ", @args) . ")";
	153	print $fh "\n\n";
	154	}
	155	print $fh "=for hackers\nFound in file $file\n\n";
	156	}
	157
7b73ff98	158	sub output {
5a0155e6	159	my ($podname, $header, $dochash, $missing, $footer) = @_;
7b73ff98 NC	160	my $filename = "pod/$podname.pod";
	161	open my $fh, '>', $filename or die "Can't open $filename: $!";
	162
	163	print $fh <<"_EOH_", $header;
e0492643 NC	164	-- buffer-read-only: t --
	165
	166	!!!!!!! DO NOT EDIT THIS FILE !!!!!!!
	167	This file is built by $0 extracting documentation from the C source
	168	files.
	169
	170	_EOH_
e0492643	171
7b73ff98 NC	172	my $key;
	173	# case insensitive sort, with fallback for determinacy
	174	for $key (sort { uc($a) cmp uc($b) \|\| $a cmp $b } keys %$dochash) {
	175	my $section = $dochash->{$key};
	176	print $fh "\n=head1 $key\n\n=over 8\n\n";
	177	# Again, fallback for determinacy
	178	for my $key (sort { uc($a) cmp uc($b) \|\| $a cmp $b } keys %$section) {
	179	docout($fh, $key, $section->{$key});
	180	}
	181	print $fh "\n=back\n";
	182	}
	183
5a0155e6	184	if (@$missing) {
a23e6e20	185	print $fh "\n=head1 Undocumented functions\n\n";
5a0155e6 TC	186	print $fh "These functions are currently undocumented:\n\n=over\n\n";
	187	for my $missing (sort @$missing) {
	188	print $fh "=item $missing\nX<$missing>\n\n";
	189	}
	190	print $fh "=back\n\n";
	191	}
	192
7b73ff98	193	print $fh $footer, <<'_EOF_';
e0492643 NC	194	=cut
e0492643 NC	195
3f98fbb3	196	ex: set ro:
e0492643	197	_EOF_
7b73ff98 NC	198
7b73ff98 NC	199	close $fh or die "Can't close $filename: $!";
e0492643 NC	200	}
e0492643 NC	201
cd093254 MM	202	if (@ARGV) {
	203	my $workdir = shift;
	204	chdir $workdir
	205	or die "Couldn't chdir to '$workdir': $!";
	206	}
	207
bc350081 NC	208	open IN, "embed.fnc" or die $!;
bc350081 NC	209
bc350081 NC	210	while (<IN>) {
	211	chomp;
	212	next if /^:/;
	213	while (s\|\\\s*$\|\|) {
	214	$_ .= <IN>;
	215	chomp;
	216	}
	217	s/\s+$//;
	218	next if /^\s*(#\|$)/;
	219
	220	my ($flags, $retval, $func, @args) = split /\s\\|\s/, $_;
	221
bc350081 NC	222	next unless $func;
	223
	224	s/\b(NN\|NULLOK)\b\s+//g for @args;
	225	$func =~ s/\t//g; # clean up fields from embed.pl
	226	$retval =~ s/\t//;
	227
5ce57792 NC	228	$funcflags{$func} = {
	229	flags => $flags,
	230	retval => $retval,
	231	args => \@args,
	232	};
	233	}
	234
	235	my $file;
	236	# glob() picks up docs from extra .c or .h files that may be in unclean
	237	# development trees.
	238	my $MANIFEST = do {
	239	local ($/, *FH);
	240	open FH, "MANIFEST" or die "Can't open MANIFEST: $!";
	241	<FH>;
	242	};
	243
	244	for $file (($MANIFEST =~ /^(\S+\.c)\t/gm), ($MANIFEST =~ /^(\S+\.h)\t/gm)) {
	245	open F, "< $file" or die "Cannot open $file for docs: $!\n";
	246	$curheader = "Functions in file $file\n";
	247	autodoc(\*F,$file);
	248	close F or die "Error closing $file: $!\n";
	249	}
	250
	251	for (sort keys %funcflags) {
	252	next unless $funcflags{$_}{flags} =~ /d/;
	253	warn "no docs for $_\n"
bc350081	254	}
94bdecf9	255
5ce57792 NC	256	foreach (sort keys %missing) {
	257	next if $macro{$_};
	258	# Heuristics for known not-a-function macros:
	259	next if /^[A-Z]/;
	260	next if /^dj?[A-Z]/;
	261
	262	warn "Function '$_', documented in $missing{$_}, not listed in embed.fnc";
94bdecf9 JH	263	}
94bdecf9 JH	264
5ce57792 NC	265	# walk table providing an array of components in each line to
	266	# subroutine, printing the result
	267
5a0155e6 TC	268	my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && !$docs{api}{$_}, keys %funcflags;
5a0155e6 TC	269	output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
94bdecf9 JH	270	=head1 NAME
	271
	272	perlapi - autogenerated documentation for the perl public API
	273
	274	=head1 DESCRIPTION
d8c40edc	275	X<Perl API> X<API> X<api>
94bdecf9 JH	276
	277	This file contains the documentation of the perl public API generated by
	278	embed.pl, specifically a listing of functions, macros, flags, and variables
	279	that may be used by extension writers. The interfaces of any functions that
	280	are not listed here are subject to change without notice. For this reason,
	281	blindly using functions listed in proto.h is to be avoided when writing
	282	extensions.
	283
	284	Note that all Perl API global variables must be referenced with the C<PL_>
	285	prefix. Some macros are provided for compatibility with the older,
	286	unadorned names, but this support may be disabled in a future release.
	287
2bbc8d55 SP	288	Perl was originally written to handle US-ASCII only (that is characters
	289	whose ordinal numbers are in the range 0 - 127).
	290	And documentation and comments may still use the term ASCII, when
	291	sometimes in fact the entire range from 0 - 255 is meant.
	292
	293	Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
	294	or ASCII. Most of the documentation (and even comments in the code)
	295	ignore the EBCDIC possibility.
	296	For almost all purposes the differences are transparent.
	297	As an example, under EBCDIC,
	298	instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
	299	whenever this documentation refers to C<utf8>
	300	(and variants of that name, including in function names),
	301	it also (essentially transparently) means C<UTF-EBCDIC>.
	302	But the ordinals of characters differ between ASCII, EBCDIC, and
	303	the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
	304	than in UTF-8.
	305
	306	Also, on some EBCDIC machines, functions that are documented as operating on
	307	US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all
	308	256 characters in the EBCDIC range, not just the subset corresponding to
	309	US-ASCII.
	310
	311	The listing below is alphabetical, case insensitive.
94bdecf9 JH	312
	313	_EOB_
	314
94bdecf9 JH	315	=head1 AUTHORS
	316
	317	Until May 1997, this document was maintained by Jeff Okamoto
	318	<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
	319
	320	With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
	321	Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
	322	Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
	323	Stephen McCamant, and Gurusamy Sarathy.
	324
	325	API Listing originally by Dean Roehrich <roehrich@cray.com>.
	326
	327	Updated to be autogenerated from comments in the source by Benjamin Stuhl.
	328
	329	=head1 SEE ALSO
	330
b92fc6c1	331	L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern>
94bdecf9 JH	332
	333	_EOE_
	334
5a0155e6 TC	335	my @missing_guts = grep $funcflags{$_}{flags} !~ /A/ && !$docs{guts}{$_}, keys %funcflags;
	336
	337	output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END');
94bdecf9 JH	338	=head1 NAME
	339
	340	perlintern - autogenerated documentation of purely B<internal>
	341	Perl functions
	342
	343	=head1 DESCRIPTION
d8c40edc	344	X<internal Perl functions> X<interpreter functions>
94bdecf9 JH	345
	346	This file is the autogenerated documentation of functions in the
	347	Perl interpreter that are documented using Perl's internal documentation
	348	format but are not marked as part of the Perl API. In other words,
	349	B<they are not for use in extensions>!
	350
	351	END
	352
94bdecf9 JH	353	=head1 AUTHORS
	354
	355	The autodocumentation system was originally added to the Perl core by
	356	Benjamin Stuhl. Documentation is by whoever was kind enough to
	357	document their functions.
	358
	359	=head1 SEE ALSO
	360
b92fc6c1	361	L<perlguts>, L<perlapi>
94bdecf9 JH	362
94bdecf9 JH	363	END