plan9/plan9ish.h Plan9 port: Plan9-specific C header file
plan9/setup.rc Plan9 port: script for easy build+install
plan9/versnum Plan9 port: script to print version number
-pod/buildtoc Update files based on pod.lst
-pod.lst List the pods and their roles
+pod/buildtoc Generate pod/perltoc.pod and pod/roffitall
pod/Makefile.SH generate Makefile which makes pods into something else
pod/perl5004delta.pod Perl changes in version 5.004
pod/perl5005delta.pod Perl changes in version 5.005
Porting/newtests-perldelta.pl Generate Perldelta stub for newly added tests
Porting/perldelta_template.pod Template for creating new perldelta.pod files
Porting/perlhist_calculate.pl Perform calculations to update perlhist
-Porting/pod_lib.pl Code for handling pod.lst
+Porting/pod_lib.pl Code for handling generated pods
Porting/pod_rules.pl generate lists of pod files for Makefiles
Porting/podtidy Reformat pod using Pod::Tidy
Porting/pumpkin.pod Guidelines and hints for Perl maintainers
Porting/release_managers_guide.pod
Porting/release_schedule.pod
Porting/bump-perl-version
- pod.lst
pp_ctl.c
);
my @SKIP_DIRS = qw(
write_or_die('pod/perldelta.pod', $newdelta);
git_add_modified('pod/perldelta.pod');
-$filename = 'pod.lst';
+$filename = 'pod/perl.pod';
my $pod_master = slurp_or_die($filename);
-$pod_master =~ s{^(\s*perl5)($old_major$old_minor)(delta\s+Perl changes in version )(5\.\d+\.\d+)(.*)}
- {$1 . $new_major . $new_minor .$3 . "5.$new_major.$new_minor" . $5 . "\n" .
+$pod_master =~ s{^(\s*perl5)($was_major$was_minor)(delta\s+Perl changes in version )(5\.\d+\.\d+)(.*)}
+ {$1 . $old_major . $old_minor .$3 . "5.$old_major.$old_minor" . $5 . "\n" .
"$1$2$3$4$5"}me
or die "Can't find perldelta line in $filename";
my @want =
$contents =~ /perldelta - what is new for perl v(5)\.(\d+)\.(\d+)\n/;
die "Can't extract version from $filename" unless @want;
- $state{delta_target} = join '', 'perl', @want, 'delta.pod';
+ my $delta_leaf = join '', 'perl', @want, 'delta';
+ $state{delta_target} = "$delta_leaf.pod";
$state{delta_version} = \@want;
# This way round so that keys can act as a MANIFEST skip list
# with sources being in the same directory.
$state{copies}{$state{delta_target}} = $source;
+ # The default flags if none explicitly set for the current file.
+ my $current_flags = '';
+ my (%flag_set, @paths);
- # process pod.lst
- my $master = open_or_die('pod.lst');
+ my $master = open_or_die('pod/perl.pod');
+
+ while (<$master>) {
+ last if /^=begin buildtoc$/;
+ }
+ die "Can't find '=begin buildtoc':" if eof $master;
+
+ while (<$master>) {
+ next if /^$/ or /^#/;
+ last if /^=end buildtoc/;
+ my ($command, @args) = split ' ';
+ if ($command eq 'flag') {
+ # For the named pods, use these flags, instead of $current_flags
+ my $flags = shift @args;
+ my_die("Malformed flag $flags")
+ unless $flags =~ /\A=([a-z]*)\z/;
+ $flag_set{$_} = $1 foreach @args;
+ } elsif ($command eq 'path') {
+ # If the pod's name matches the regex, prepend the given path.
+ my_die("Malformed path for /$args[0]/")
+ unless @args == 2;
+ push @paths, [qr/\A$args[0]\z/, $args[1]];
+ } elsif ($command eq 'aux') {
+ # The contents of perltoc.pod's "AUXILIARY DOCUMENTATION" section
+ $state{aux}{$_} = '' foreach @args;
+ } else {
+ my_die("Unknown buildtoc command '$command'");
+ }
+ }
foreach (<$master>) {
- next if /^\#/;
-
- # At least one upper case letter somewhere in the first group
- if (/^(\S+)\s(.*)/ && $1 =~ tr/h//) {
- # it's a heading
- my $flags = $1;
- $flags =~ tr/h//d;
- my %flags = (header => 1);
- $flags{toc_omit} = 1 if $flags =~ tr/o//d;
- $flags{aux} = 1 if $flags =~ tr/a//d;
- my_die "Unknown flag found in heading line: $_" if length $flags;
-
- push @{$state{master}}, [\%flags, $2];
- } elsif (/^(\S*)\s+(\S+)\s+(.*)/) {
- # it's a section
- my ($flags, $podname, $desc) = ($1, $2, $3);
- my $filename = "${podname}.pod";
- $filename = "pod/${filename}" if $filename !~ m{/};
-
- my %flags = (indent => 0);
- $flags{indent} = $1 if $flags =~ s/(\d+)//;
+ next if /^$/ or /^#/;
+ next if /^=head2/;
+ last if /^=for buildtoc __END__$/;
+
+ if (my ($action, $flags) = /^=for buildtoc flag ([-+])([a-z]+)/) {
+ if ($action eq '+') {
+ $current_flags .= $flags;
+ } else {
+ my_die("Attempt to unset [$flags] failed - flags are '$current_flags")
+ unless $current_flags =~ s/[\Q$flags\E]//g;
+ }
+ } elsif (my ($leafname, $desc) = /^\s+(\S+)\s+(.*)/) {
+ my $podname = $leafname;
+ my $filename = "pod/$podname.pod";
+ foreach (@paths) {
+ my ($re, $path) = @$_;
+ if ($leafname =~ $re) {
+ $podname = $path . $leafname;
+ $filename = "$podname.pod";
+ last;
+ }
+ }
+
+ # Keep this compatible with pre-5.10
+ my $flags = delete $flag_set{$leafname};
+ $flags = $current_flags unless defined $flags;
+
+ my %flags;
$flags{toc_omit} = 1 if $flags =~ tr/o//d;
- $flags{aux} = 1 if $flags =~ tr/a//d;
- $flags{perlpod_omit} = "$podname.pod" eq $state{delta_target};
$state{generated}{"$podname.pod"}++ if $flags =~ tr/g//d;
$readme =~ s/^perl//;
$state{readmes}{$readme} = $desc;
$flags{readme} = 1;
- } elsif ($flags{aux}) {
- $state{aux}{$podname} = $desc;
} else {
$state{pods}{$podname} = $desc;
}
my_die "Unknown flag found in section line: $_" if length $flags;
- my ($leafname) = $podname =~ m!([^/]+)$!;
push @{$state{master}},
[\%flags, $podname, $filename, $desc, $leafname];
- } elsif (/^$/) {
- push @{$state{master}}, undef;
+
+ if ($podname eq 'perldelta') {
+ local $" = '.';
+ my $delta_desc = "Perl changes in version @want";
+ push @{$state{master}},
+ [{}, $state{delta_target}, "pod/$state{delta_target}",
+ $delta_desc, $delta_leaf];
+ $state{pods}{$delta_leaf} = $delta_desc;
+ }
+
} else {
- my_die "Malformed line: $_" if $1 =~ tr/A-Z//;
+ my_die("Malformed line: $_");
}
}
- close $master or my_die "close pod.lst: $!";
+ close $master or my_die("close pod/perl.pod: $!");
+
+ my_die("perl.pod sets flags for unknown pods: "
+ . join ' ', sort keys %flag_set)
+ if keys %flag_set;
+
+ # This "structure" is identical to the array reference generated by the
+ # previous code from pod.lst. It's likely that it can be simplified.
+ push @{$state{master}},
+ [{aux => 1, toc_omit => 1}, $_, "pod/$_.pod", '', $_]
+ foreach sort keys %{$state{aux}}
}
sub get_pod_metadata {
# Sanity cross check
- my (%disk_pods, %manipods, %manireadmes, %perlpods);
+ my (%disk_pods, %manipods, %manireadmes);
my (%cpanpods, %cpanpods_leaf);
my (%our_pods);
}
close $mani or my_die "close MANIFEST: $!\n";
- my $perlpod = open_or_die('pod/perl.pod');
- while (<$perlpod>) {
- if (/^For ease of access, /../^\(If you're intending /) {
- if (/^\s+(perl\S*)\s+\w/) {
- ++$perlpods{"$1.pod"};
- }
- }
- }
- close $perlpod or my_die "close perlpod: $!\n";
- my_die "could not find the pod listing of perl.pod\n"
- unless %perlpods;
-
# Are we running before known generated files have been generated?
# (eg in a clean checkout)
my %not_yet_there;
if !$BuildFiles{'MANIFEST'} # Ignore if we're rebuilding MANIFEST
&& !$manipods{$i} && !$manireadmes{$i} && !$state{copies}{$i}
&& !$state{generated}{$i} && !$cpanpods{$i};
- push @inconsistent, "$0: $i exists but is unknown by perl.pod\n"
- if !$BuildFiles{'perl.pod'} # Ignore if we're rebuilding perl.pod
- && !$perlpods{$i} && !exists $state{copies}{$i}
- && !$cpanpods{$i} && !$ignoredpods{$i};
}
foreach my $i (sort keys %our_pods) {
push @inconsistent, "$0: $i is known by buildtoc but does not exist\n"
if $state{generated}{$i};
}
}
- unless ($BuildFiles{'perl.pod'}) {
- # Again, ignore these if we're about to rebuild perl.pod
- foreach my $i (sort keys %perlpods) {
- push @inconsistent, "$0: $i is known by perl.pod but does not exist\n"
- unless $disk_pods{$i} or $BuildFiles{$i} or $cpanpods_leaf{$i}
- or $not_yet_there{$i};
- }
- }
&$callback(@inconsistent);
return \%state;
}
use Getopt::Long;
use Carp;
-# Generate the sections of files listed in %Targets from pod.lst
+# Generate the sections of files listed in %Targets from pod/perl.pod
# Mostly these are rules in Makefiles
#
# --verbose gives slightly more output
# --build-all tries to build everything
# --build-foo updates foo as follows
# --showfiles shows the files to be changed
-# --test exit if perl.pod, pod.lst, MANIFEST are consistent, and regenerated
+# --test exit if perl.pod, MANIFEST are consistent, and regenerated
# files are up to date, die otherwise.
%Targets = (
manifest => 'MANIFEST',
- perlpod => 'pod/perl.pod',
vms => 'vms/descrip_mms.template',
nmake => 'win32/Makefile',
dmake => 'win32/makefile.mk',
})
: get_pod_metadata(1, sub { warn @_ if @_ }, values %Build);
-sub generate_perlpod {
- my @output;
- my $maxlength = 0;
- foreach (@{$state->{master}}) {
- my $flags = $_->[0];
- next if $flags->{aux};
- next if $flags->{perlpod_omit};
-
- if (@$_ == 2) {
- # Heading
- push @output, "=head2 $_->[1]\n";
- } elsif (@$_ == 5) {
- # Section
- my $start = " " x (4 + $flags->{indent}) . $_->[4];
- $maxlength = length $start if length ($start) > $maxlength;
- push @output, [$start, $_->[3]];
- } elsif (@$_ == 0) {
- # blank line
- push @output, "\n";
- } else {
- my_die "Illegal length " . scalar @$_;
- }
- }
- # want at least 2 spaces padding
- $maxlength += 2;
- $maxlength = ($maxlength + 3) & ~3;
- # sprintf gives $1.....$2 where ... are spaces:
- return unexpand (map {ref $_ ? sprintf "%-${maxlength}s%s\n", @$_ : $_}
- @output);
-}
-
sub generate_manifest {
# Annoyingly, unexpand doesn't consider it good form to replace a single
# space before a tab with a tab
sub do_manifest {
my ($name, $prev) = @_;
my @manifest =
- grep {! m!^pod/[^.]+\.pod.*!}
+ grep {! m!^pod/[^. \t]+\.pod.*!}
grep {! m!^README\.(\S+)! || $state->{ignore}{$1}} split "\n", $prev;
join "\n", (
# Dictionary order - fold and handle non-word chars as nothing
# shut up used only once warning
*do_dmake = *do_dmake = \&do_nmake;
-sub do_perlpod {
- my ($name, $pod) = @_;
-
- unless ($pod =~ s{(For\ ease\ of\ access,\ .*\n)
- (?:\s+[a-z]{4,}.*\n # fooo
- |=head.*\n # =head foo
- |\s*\n # blank line
- )+
- }
- {$1 . join "", &generate_perlpod}mxe) {
- my_die "Failed to insert amendments in do_perlpod";
- }
- $pod;
-}
-
sub do_podmak {
my ($name, $body) = @_;
foreach my $variable (qw(pod man html tex)) {
$ git rm perldelta515*.pod
All mention to them should also be removed. Currently the files that
-need to be edited for this task are F<MANIFEST>, F<pod.list>,
+need to be edited for this task are F<MANIFEST>,
F<pod/perl.pod>, and F<win32/pod.mak> (including C<.man>, C<.html>, and
C<.tex> entries for each removed pod).
$ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod # for example
$ git add pod/perl5101delta.pod
-Edit F<pod.lst> to add an entry for the file, e.g.:
+Edit F<pod/perl.pod> to add an entry for the file, e.g.:
perl5101delta Perl changes in version 5.10.1
pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
- pod/perltoc.pod pod.lst Porting/Glossary pod/perlgit.pod
+ pod/perltoc.pod Porting/Glossary pod/perlgit.pod
Porting/checkAUTHORS.pl
dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
mktables has many checks to warn you if there are unexpected or novel things
that it doesn't know how to handle.
-pod.lst should be changed so that it gives the new name (which includes the
+perl.pod should be changed so that it gives the new name (which includes the
Unicode release number) for perluniprops.pod
Module::CoreList should be changed to include the new release
+++ /dev/null
-# h - Header
-# o - Omit from toc
-# r - top level READMEs to be copied/symlinked
-# g - other autogenerated pods
-# a - for auxiliary documentation
-# number - indent by
-
-h Overview
-
- perl Perl overview (this section)
- perlintro Perl introduction for beginners
-go perltoc Perl documentation table of contents
-
-h Tutorials
-
- perlreftut Perl references short introduction
- perldsc Perl data structures intro
- perllol Perl data structures: arrays of arrays
-
- perlrequick Perl regular expressions quick start
- perlretut Perl regular expressions tutorial
-
- perlootut Perl OO tutorial for beginners
-
- perlperf Perl Performance and Optimization Techniques
-
- perlstyle Perl style guide
-
- perlcheat Perl cheat sheet
- perltrap Perl traps for the unwary
- perldebtut Perl debugging tutorial
-
- cpan/perlfaq/lib/perlfaq Perl frequently asked questions
-2 cpan/perlfaq/lib/perlfaq1 General Questions About Perl
-2 cpan/perlfaq/lib/perlfaq2 Obtaining and Learning about Perl
-2 cpan/perlfaq/lib/perlfaq3 Programming Tools
-2 cpan/perlfaq/lib/perlfaq4 Data Manipulation
-2 cpan/perlfaq/lib/perlfaq5 Files and Formats
-2 cpan/perlfaq/lib/perlfaq6 Regexes
-2 cpan/perlfaq/lib/perlfaq7 Perl Language Issues
-2 cpan/perlfaq/lib/perlfaq8 System Interaction
-2 cpan/perlfaq/lib/perlfaq9 Networking
-
-h Reference Manual
-
- perlsyn Perl syntax
- perldata Perl data structures
- perlop Perl operators and precedence
- perlsub Perl subroutines
- perlfunc Perl built-in functions
-2 perlopentut Perl open() tutorial
-2 perlpacktut Perl pack() and unpack() tutorial
- perlpod Perl plain old documentation
- perlpodspec Perl plain old documentation format specification
- perlpodstyle Perl POD style guide
- perlrun Perl execution and options
- perldiag Perl diagnostic messages
- perllexwarn Perl warnings and their control
- perldebug Perl debugging
- perlvar Perl predefined variables
- perlre Perl regular expressions, the rest of the story
- perlrebackslash Perl regular expression backslash sequences
- perlrecharclass Perl regular expression character classes
- perlreref Perl regular expressions quick reference
- perlref Perl references, the rest of the story
- perlform Perl formats
- perlobj Perl objects
- perltie Perl objects hidden behind simple variables
-2 perldbmfilter Perl DBM filters
-
- perlipc Perl interprocess communication
- perlfork Perl fork() information
- perlnumber Perl number semantics
-
- perlthrtut Perl threads tutorial
-
- perlport Perl portability guide
- perllocale Perl locale support
- perluniintro Perl Unicode introduction
- perlunicode Perl Unicode support
- perlunifaq Perl Unicode FAQ
-g perluniprops Index of Unicode Version 6.0.0 properties in Perl
- perlunitut Perl Unicode tutorial
- perlebcdic Considerations for running Perl on EBCDIC platforms
-
- perlsec Perl security
-
- perlmod Perl modules: how they work
-g perlmodlib Perl modules: how to write and use
- perlmodstyle Perl modules: how to write modules with style
- perlmodinstall Perl modules: how to install from CPAN
- perlnewmod Perl modules: preparing a new module for distribution
- perlpragma Perl modules: writing a user pragma
-
- perlutil utilities packaged with the Perl distribution
-
- perlfilter Perl source filters
-
- perldtrace Perl's support for DTrace
-
- cpan/perlfaq/lib/perlglossary Perl Glossary
-
-h Internals and C Language Interface
-
- perlembed Perl ways to embed perl in your C or C++ application
- perldebguts Perl debugging guts and tips
- dist/ExtUtils-ParseXS/lib/perlxstut Perl XS tutorial
- dist/ExtUtils-ParseXS/lib/perlxs Perl XS application programming interface
- perlclib Internal replacements for standard C library functions
- perlguts Perl internal functions for those doing extensions
- perlcall Perl calling conventions from C
- perlmroapi Perl method resolution plugin interface
- perlreapi Perl regular expression plugin interface
- perlreguts Perl regular expression engine internals
-
-g perlapi Perl API listing (autogenerated)
-g perlintern Perl internal functions (autogenerated)
- perliol C API for Perl's implementation of IO in Layers
- perlapio Perl internal IO abstraction interface
-
- perlhack Perl hackers guide
- perlsource Guide to the Perl source tree
- perlinterp Overview of the Perl interpreter source and how it works
- perlhacktut Walk through the creation of a simple C code patch
- perlhacktips Tips for Perl core C code hacking
- perlpolicy Perl development policies
- perlgit Using git with the Perl repository
-
-h Miscellaneous
-
- perlbook Perl book information
- perlcommunity Perl community information
- perltodo Perl things to do
-
- dist/Pod-Perldoc/lib/perldoc Look up Perl documentation in Pod format
-
- perlhist Perl history records
- perldelta Perl changes since previous version
- perl5157delta Perl changes in version 5.15.7
- perl5156delta Perl changes in version 5.15.6
- perl5155delta Perl changes in version 5.15.5
- perl5154delta Perl changes in version 5.15.4
- perl5153delta Perl changes in version 5.15.3
- perl5152delta Perl changes in version 5.15.2
- perl5151delta Perl changes in version 5.15.1
- perl5150delta Perl changes in version 5.15.0
- perl5142delta Perl changes in version 5.14.2
- perl5141delta Perl changes in version 5.14.1
- perl5140delta Perl changes in version 5.14.0
- perl5124delta Perl changes in version 5.12.4
- perl5123delta Perl changes in version 5.12.3
- perl5122delta Perl changes in version 5.12.2
- perl5121delta Perl changes in version 5.12.1
- perl5120delta Perl changes in version 5.12.0
- perl5101delta Perl changes in version 5.10.1
- perl5100delta Perl changes in version 5.10.0
- perl589delta Perl changes in version 5.8.9
- perl588delta Perl changes in version 5.8.8
- perl587delta Perl changes in version 5.8.7
- perl586delta Perl changes in version 5.8.6
- perl585delta Perl changes in version 5.8.5
- perl584delta Perl changes in version 5.8.4
- perl583delta Perl changes in version 5.8.3
- perl582delta Perl changes in version 5.8.2
- perl581delta Perl changes in version 5.8.1
- perl58delta Perl changes in version 5.8.0
- perl561delta Perl changes in version 5.6.1
- perl56delta Perl changes in version 5.6
- perl5005delta Perl changes in version 5.005
- perl5004delta Perl changes in version 5.004
-
- perlexperiment A listing of experimental features in Perl
-
- perlartistic Perl Artistic License
- perlgpl GNU General Public License
-
-ho Language-Specific
-
-ro perlcn Perl for Simplified Chinese (in EUC-CN)
-ro perljp Perl for Japanese (in EUC-JP)
-ro perlko Perl for Korean (in EUC-KR)
-ro perltw Perl for Traditional Chinese (in Big5)
-
-h Platform-Specific
-
-r perlaix Perl notes for AIX
-r perlamiga Perl notes for AmigaOS
-r perlbeos Perl notes for BeOS
-r perlbs2000 Perl notes for POSIX-BC BS2000
-r perlce Perl notes for WinCE
-r perlcygwin Perl notes for Cygwin
-r perldgux Perl notes for DG/UX
-r perldos Perl notes for DOS
-r perlepoc Perl notes for EPOC
-r perlfreebsd Perl notes for FreeBSD
-r perlhaiku Perl notes for Haiku
-r perlhpux Perl notes for HP-UX
-r perlhurd Perl notes for Hurd
-r perlirix Perl notes for Irix
-r perllinux Perl notes for Linux
-r perlmacos Perl notes for Mac OS (Classic)
-r perlmacosx Perl notes for Mac OS X
-r perlmpeix Perl notes for MPE/iX
-r perlnetware Perl notes for NetWare
-r perlopenbsd Perl notes for OpenBSD
-r perlos2 Perl notes for OS/2
-r perlos390 Perl notes for OS/390
-r perlos400 Perl notes for OS/400
-r perlplan9 Perl notes for Plan 9
-r perlqnx Perl notes for QNX
-r perlriscos Perl notes for RISC OS
-r perlsolaris Perl notes for Solaris
-r perlsymbian Perl notes for Symbian
-r perltru64 Perl notes for Tru64
-r perluts Perl notes for UTS
-r perlvmesa Perl notes for VM/ESA
- perlvms Perl notes for VMS
-r perlvos Perl notes for Stratus VOS
-r perlwin32 Perl notes for Windows
-
-oh Stubs for Deleted Documents
-
- perlboot
- perlbot
- perltooc
- perltoot
-
-aoh Auxiliary Documentation
-
-ao a2p
-ao c2ph
-ao h2ph
-ao h2xs
-ao perlbug
-ao pl2pm
-ao pod2html
-ao pod2man
-ao s2p
-ao splain
-ao xsubpp
For ease of access, the Perl manual has been split up into several sections.
+=begin buildtoc
+
+# This section is parsed by Porting/pod_lib.pl for use by pod/buildtoc etc
+
+flag =g perluniprops perlmodlib perlapi perlintern
+flag =go perltoc
+flag =ro perlcn perljp perlko perltw
+flag = perlvms
+
+path perlfaq.* cpan/perlfaq/lib/
+path perlglossary cpan/perlfaq/lib/
+path perlxs(?:tut)? dist/ExtUtils-ParseXS/lib/
+path perldoc dist/Pod-Perldoc/lib/
+
+aux a2p c2ph h2ph h2xs perlbug pl2pm pod2html pod2man s2p splain xsubpp
+
+=end buildtoc
+
=head2 Overview
perl Perl overview (this section)
=head2 Language-Specific
+=for buildtoc flag +r
+
perlcn Perl for Simplified Chinese (in EUC-CN)
perljp Perl for Japanese (in EUC-JP)
perlko Perl for Korean (in EUC-KR)
perlvos Perl notes for Stratus VOS
perlwin32 Perl notes for Windows
+=for buildtoc flag -r
+
=head2 Stubs for Deleted Documents
perlboot
perltooc
perltoot
+=for buildtoc __END__
On a Unix-like system, these documentation files will usually also be
available as manpages for use with the F<man> program.
https://perl5.git.perl.org / perl5.git / commitdiff