This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Run podtidy on perlsource.pod
[perl5.git] / pod / perlsource.pod
index 4931015..16252eb 100644 (file)
@@ -10,89 +10,94 @@ 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.
+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:
+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.
+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.
+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.
+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.
+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.
+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.
+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/>.
+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.
+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 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.
+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.
+Tests for basic control structures, C<if/else>, C<while>, subroutines,
+etc.
 
 =item * F<t/comp/>
 
@@ -131,9 +136,9 @@ 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.
+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/>
 
@@ -149,9 +154,9 @@ A test suite for the s2p converter.
 
 =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
+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
@@ -166,18 +171,19 @@ intended to help porters work on Perl. Some of the highlights include:
 
 =item * F<check*>
 
-These are scripts which will check the source things like ANSI C violations,
-POD encoding issues, etc.
+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.
+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.
+Tidies a pod file. It's a good idea to run this on a pod file you've
+patched.
 
 =back
 
@@ -186,8 +192,8 @@ Tidies a pod file. It's a good idea to run this on a pod file you've patched.
 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.
+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>.
@@ -195,21 +201,22 @@ 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 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.
+The F<Cross> directory contains various files related to
+cross-compiling Perl. See F<Cross/README> for more details.
 
 =head2 F<AUTHORS>
 
-This file lists everyone who's contributed to Perl. If you submit a patch, you
-should add your name to this file as part of the patch.
+This file lists 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.
+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: