Major revision of perlhack and perlrepository

The existing perlhack is huge and takes a long time to get to key
information like "how to submit a patch". It also contains a massive
amount of (very useful) detail on the Perl interpreter, debugging,
portability issues, and so on.

Some parts of perlhack are just obsolete. For example, Larry really
isn't deeply involved on p5p any more.

Meanwhile, perlrepository _also_ contains a lot of useful information
on patching Perl, as well as a small git tutorial focused on working
with the Perl repository.

Taken together, the two documents overlap and conflict with each other.

This commit does the following:

== Reconcile conflicts and overlaps, remove obsolete information

I've separated out distinct pieces of information and organized them
into individual pod files. More on that below. I've also removed anything
that was obviously out of date.

== Make it easier for casual contributors to contribute.

The perlhack document now gets to "how to make a patch" very quickly. My
assumption is that most contributors to Perl are doing something small,
like fixing pod, adding a test, etc.

The documentation aimed at people doing more extensive hacking is still
there, but it's been moved so that it comes at the end of the document
or has been moved to another document.

I've made an effort to cross-reference the various documents so that
nothing gets lost.

== Get to the point

The perlhack document had a lot of discussion of general Perl culture.
I've trimmed a lot of this and moved some of it so it comes later.

== Per-file summary

=== perlrepository.pod

This is gone. Some of its content is now in perlhack. This includes
the bits on writing good commit messages, how (and where) to submit a
patch, etc.

The rest is now called perlgit, and is _only_ a git how-to.

=== perlhack.pod

This has been cut down quite a bit.

I changed the opening so it starts with a quick guide to submitting
small patches.

The document covers bug reporting, the p5p list, a quick how-to on
getting the source (including git, gitweb, and rsync), and a lot of
general information on patching perl and running tests.

Much of this material was already present, but I've done a fair amount
of editing for modernization and clarity.

Most of the information specific to C-level hacking has been moved to
other documents.

=== perlsource.pod

This is a guide to the Perl source tree. Most of the content was extracted
from perlhack. I've edited existing content and added details on some
parts of the tree that weren't covered.

=== perlinterp.pod

This is a tour of the Perl interpreter source and a walkthrough of
how it works that originally lived in perlhack. This has received very
little editing.

=== perlhacktut.pod

This is a walkthrough of creating a sample patch to the C core code that
originally lived in perlhack. This has received very little editing.

=== perlhacktips.pod

The perlhack document contained a lot of useful information on low-level
hacking details like debugging, compilation issues, portability, etc.
This has received very little editing.

I did remove some bits on ancient stuff related to Tru64 and IRIX.

1 files changed, 216 insertions, 0 deletions

diff --git a/pod/perlsource.pod b/pod/perlsource.pod
new file mode 100644
index 0000000000..94ceec00bd
--- /dev/null
+++ b/pod/perlsource.pod
@@ -0,0 +1,216 @@
+=encoding utf8
+
+=for comment
+Consistent formatting of this file is achieved with:
+  perl ./Porting/podtidy pod/perlsource.pod
+
+=head1 NAME
+
+perlsource - A guide to the Perl source tree
+
+=head1 DESCRIPTION
+
+This document describes the layout of the Perl source tree. If you're hacking
+on the Perl core, this will help you find what you're looking for.
+
+=head1 FINDING YOUR WAY AROUND
+
+The Perl source tree is big. Here's some of the thing you'll find in it:
+
+=head2 C code
+
+The C source code and header files mostly live in the root of the source
+tree. There are a few platform-specific directories which contain C code. In
+addition, some of the modules shipped with Perl include C or XS code.
+
+See L<perlinterp> for more details on the files that make up the Perl
+interpreter, as well as details on how it works.
+
+=head2 Core modules
+
+Modules shipped as part of the Perl core live in four subdirectories. Two of
+these directories contain modules that live in the core, and two contain
+modules that can also be released separately on CPAN. Modules which can be
+released on cpan are known as "dual-life" modules.
+
+=over 4
+
+=item * F<lib/>
+
+This directory contains pure-Perl modules which are only released as part of
+the core. This directory contains I<all> of the modules and their tests,
+unlike other core modules.
+
+=item * F<ext/>
+
+This directory contains XS-using modules which are only released as part of
+the core. These modules generally have their F<Makefile.PL> and are laid out
+more like a typical CPAN module.
+
+=item * F<dist/>
+
+This directory is for dual-life modules where the blead source is
+canonical. Note that some modules in this directory may not yet have been
+released separately on CPAN.
+
+=item * F<cpan/>
+
+This directory contains dual-life modules where the CPAN module is
+canonical. Do not patch these modules directly! Changes to these modules
+should be submitted to the maintainer of the CPAN module. Once those changes
+are applied and released, the new version of the module will be incorporated
+into the core.
+
+=back
+
+For some dual-life modules, it has not yet been determined if the CPAN version
+or the blead source is canonical. Until that is done, those modules should be
+in F<cpan/>.
+
+=head2 Tests
+
+The Perl core has an extensive test suite. If you add new tests (or new
+modules with tests), you may need to update the F<t/TEST> file so that the
+tests are run.
+
+=over 4
+
+=item * Module tests
+
+Tests for core modules in the F<lib/> directory are right next to the module
+itself. For example, we have F<lib/strict.pm> and F<lib/strict.t>.
+
+Tests for modules in F<ext/> and the dual-life modules are in F<t/>
+subdirectories for each module, like a standard CPAN distribution.
+
+=item * F<t/base/>
+
+Tests for the absolute basic functionality of Perl. This includes C<if>, basic
+file reads and writes, simple regexes, etc. These are run first in the test
+suite and if any of them fail, something is I<really> broken.
+
+=item * F<t/cmd/>
+
+Tests for basic control structures, C<if/else>, C<while>,
+subroutines, etc.
+
+=item * F<t/comp/>
+
+Tests for basic issues of how Perl parses and compiles itself.
+
+=item * F<t/io/>
+
+Tests for built-in IO functions, including command line arguments.
+
+=item * F<t/mro/>
+
+Tests for perl's method resolution order implementations (see L<mro>).
+
+=item * F<t/op/>
+
+Tests for perl's built in functions that don't fit into any of the
+other directories.
+
+=item * F<t/re/>
+
+Tests for regex related functions or behaviour. (These used to live in
+t/op).
+
+=item * F<t/run/>
+
+Tests for features of how perl actually runs, including exit codes and
+handling of PERL* environment variables.
+
+=item * F<t/uni/>
+
+Tests for the core support of Unicode.
+
+=item * F<t/win32/>
+
+Windows-specific tests.
+
+=item * F<t/porting/>
+
+Tests the state of the source tree for various common errors. For example, it
+tests that everyone who is listed in the git log has a corresponding entry in
+the F<AUTHORS> file.
+
+=item * F<t/lib/>
+
+The old home for the module tests, you shouldn't put anything new in
+here. There are still some bits and pieces hanging around in here that
+need to be moved. Perhaps you could move them?  Thanks!
+
+=item * F<t/x2p>
+
+A test suite for the s2p converter.
+
+=back
+
+=head2 Documentation
+
+All of the core documentation intended for end users lives in
+F<pod/>. Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/>
+usually have their own documentation, either in the F<Module.pm> file or an
+accompanying F<Module.pod> file.
+
+Finally, documentation intended for core Perl developers lives in the
+F<Porting/> directory.
+
+=head2 Hacking toolks and documentation
+
+The F<Porting> directory contains a grab bag of code and documentation
+intended to help porters work on Perl. Some of the highlights include:
+
+=over 4
+
+=item * F<check*>
+
+These are scripts which will check the source things like ANSI C violations,
+POD encoding issues, etc.
+
+=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm>
+
+These files contain information on who maintains which modules. Run C<perl
+Porting/Maintainers -M Module::Name> to find out more information about a
+dual-life module.
+
+=item * F<podtidy>
+
+Tidies a pod file. It's a good idea to run this on a pod file you've patched.
+
+=back
+
+=head2 Build system
+
+The Perl build system starts with the F<Configure> script in the root
+directory.
+
+Platform-specific pieces of the build system also live in platform-specific
+directories like F<win32/>, F<vms/>, etc.
+
+The F<Configure> script is ultimately responsible for generating a
+F<Makefile>.
+
+The build system that Perl uses is called metaconfig. This system is
+maintained separately from the Perl core.
+
+The metaconfig system has its own git repository. Please see its README file
+in L<http://perl5.git.perl.org/metaconfig.git/> for more details.
+
+The F<Cross> directory contains various files related to cross-compiling
+Perl. See F<Cross/README> for more details.
+
+=head2 F<AUTHORS>
+
+This file everyone who's contributed to Perl. If you submit a patch, you
+should add your name to this file as part of the patch.
+
+=head2 F<MANIFEST>
+
+The F<MANIFEST> file in the root of the source tree contains a list of every
+file in the Perl core, as well as a brief description of each file.
+
+You can get an overview of all the files with this command:
+
+  % perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST