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
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/;
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/;
- $flags .= 'D' if $docref->{flags} =~ /D/;
+ my $embed_docref = delete $funcflags{$name};
+ if ($embed_docref and %$embed_docref) {
+ $embed_where = $embed_docref->{flags} =~ /A/ ? 'api' : 'guts';
+ $embed_may_change = $embed_docref->{flags} =~ /M/;
+ $flags .= 'D' if $embed_docref->{flags} =~ /D/;
} else {
$missing{$name} = $file;
}
} else {
$inline_where = $embed_where;
$flags .= 'x' if $embed_may_change;
- @args = @{$docref->{args}};
- $ret = $docref->{retval};
+ @args = @{$embed_docref->{args}};
+ $ret = $embed_docref->{retval};
}
if (exists $docs{$inline_where}{$curheader}{$name}) {
sub output {
my ($podname, $header, $dochash, $missing, $footer) = @_;
+ #
+ # strip leading '|' from each line which had been used to hide
+ # pod from pod checkers.
+ s/^\|//gm for $header, $footer;
+
my $fh = open_new("pod/$podname.pod", undef,
{by => "$0 extracting documentation",
from => 'the C source files'}, 1);
patch to document the function. Once your patch is accepted, it will indicate
that the interface is stable (unless it is explicitly marked otherwise) and
usable by you.
-
-=over
-
_EOB_
The following functions are currently undocumented. If you use one of
them, you may wish to consider creating and submitting documentation for
it.
-
-=over
-
_EOB_
+ print $fh "\n=over\n\n";
+
for my $missing (sort @$missing) {
print $fh "=item $missing\nX<$missing>\n\n";
}
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";
# deprecated.
my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[MD]/ && !$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
-F<embed.pl>, specifically a listing of functions, macros, flags, and variables
-that may be used by extension writers. L<At the end|/Undocumented functions>
-is a list of functions which have yet to be documented. The interfaces of
-those 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.
-
-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.
-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.
-
-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 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.
-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 a different
-number of bytes than in UTF-8.
-
-The listing below is alphabetical, case insensitive.
-
+|=encoding UTF-8
+|
+|=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
+|F<embed.pl>, specifically a listing of functions, macros, flags, and variables
+|that may be used by extension writers. L<At the end|/Undocumented functions>
+|is a list of functions which have yet to be documented. The interfaces of
+|those 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.
+|
+|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.
+|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.
+|
+|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.
+|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 a different
+|number of bytes than in UTF-8.
+|
+|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>
-
+|
+|=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_
# List of non-static internal functions
grep $funcflags{$_}{flags} !~ /[As]/ && !$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>!
-
+|=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>
-
+|
+|=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
https://perl5.git.perl.org / perl5.git / blobdiff