This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlfunc: Document fallback to "top" format
authorFather Chrysostomos <sprout@cpan.org>
Mon, 10 Jun 2013 07:18:07 +0000 (00:18 -0700)
committerFather Chrysostomos <sprout@cpan.org>
Mon, 10 Jun 2013 07:19:17 +0000 (00:19 -0700)
perl 4’s perl.man says this:

By default the top‐of‐page format is "top", but it may be set to the
format of your choice by assigning the name to the $^ variable.

This is still the case, but is completely undocumented in perl 5.

In perl 5 the presence of a <FILEHANDLE_NAME>_TOP format will over-
ride "top", as will $^, but "top" is still checked for in the
absence of those.

This should be documented.  One thing I do mention here that perl 4
omits is that it is "top" in the current package.

I also tweaked the wording of the preceding sentence.

pod/perlfunc.pod

index d386245..9be5931 100644 (file)
@@ -9056,9 +9056,11 @@ explicitly by assigning the name of the format to the C<$~> variable.
 
 Top of form processing is handled automatically:  if there is insufficient
 room on the current page for the formatted record, the page is advanced by
-writing a form feed, a special top-of-page format is used to format the new
+writing a form feed and a special top-of-page
+format is used to format the new
 page header before the record is written.  By default, the top-of-page
-format is the name of the filehandle with "_TOP" appended.  This would be a
+format is the name of the filehandle with "_TOP" appended, or "top"
+in the current package if the former does not exist.  This would be a
 problem with autovivified filehandles, but it may be dynamically set to the
 format of your choice by assigning the name to the C<$^> variable while
 that filehandle is selected.  The number of lines remaining on the current