This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
autodoc.pl: escape POD
[perl5.git] / autodoc.pl
index cf82639..788dc35 100644 (file)
@@ -273,6 +273,11 @@ sub sort_helper {
 
 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);
@@ -315,17 +320,13 @@ around to documenting it.  In the latter case, you will be asked to submit a
 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";
     }
@@ -383,83 +384,83 @@ foreach (sort keys %missing) {
 # deprecated.
 my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[MD]/ && !$docs{api}{$_}, keys %funcflags;
 output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
-=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.
-
+|=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
@@ -467,29 +468,29 @@ my @missing_guts =
  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