In perl.git, the branch blead has been updated
<http://perl5.git.perl.org/perl.git/commitdiff/3b4ebcdeb3132ee8faad40b1e8840396055eded7?hp=80f78a716c4ffd9e5c37ebecec28c544e3af2c3f>
- Log -----------------------------------------------------------------
commit 3b4ebcdeb3132ee8faad40b1e8840396055eded7
Author: Jesse Vincent <je...@bestpractical.com>
Date: Thu Dec 9 15:45:50 2010 -0500
First draft of a documentation policy.
M pod/perlpolicy.pod
commit 72033c146ee0c87fbac69435dcc2e0b91a2465c8
Author: Jesse Vincent <je...@bestpractical.com>
Date: Thu Dec 9 15:15:56 2010 -0500
Slightly update perl.pod's "DESCRIPTION"
M pod/perl.pod
commit a8ebcfe95ec8b1154af89ff11cafe446ac5f2dab
Author: Jesse Vincent <je...@bestpractical.com>
Date: Thu Dec 9 15:11:45 2010 -0500
Don't explicitly talk about our support for DBM files as a feature.
It's not 1995 anymore.
M pod/perl.pod
commit 478dea908977793a08f93d8380aa5d6d47501927
Author: Jesse Vincent <je...@bestpractical.com>
Date: Thu Dec 9 15:10:15 2010 -0500
remove more a2p/s2p from perl.pod
M pod/perl.pod
commit 26dfceb05d7e2ca8bd36fa88ced2f85e50accad2
Author: Jesse Vincent <je...@bestpractical.com>
Date: Thu Dec 9 15:07:51 2010 -0500
Remove a now-inaccurate statement about setuid scripts
M pod/perl.pod
commit 9ef3b85fb7eb5182857d0323451548cf3339b325
Author: Jesse Vincent <je...@bestpractical.com>
Date: Thu Dec 9 15:07:19 2010 -0500
Remove a paragraph from perl.pod pimping it as a sed/awk replacement.
M pod/perl.pod
commit 883fe89561e0fcac4c196d2dc8b053fcc30afdd2
Author: Jesse Vincent <je...@bestpractical.com>
Date: Thu Dec 9 15:05:41 2010 -0500
Wordsmithing of Abigail's prose.
M pod/perlintro.pod
commit 4f7b12953fa23d3b88826a080aeb30262d2e7886
Author: Abigail <abig...@abigail.be>
Date: Thu Dec 9 14:48:25 2010 -0500
Added a statement about the examples in perl's documentation
M pod/perlintro.pod
-----------------------------------------------------------------------
Summary of changes:
pod/perl.pod | 28 ++++++++++------------------
pod/perlintro.pod | 19 +++++++++++++++++++
pod/perlpolicy.pod | 46 ++++++++++++++++++++++++++++++++++++++++++----
3 files changed, 71 insertions(+), 22 deletions(-)
diff --git a/pod/perl.pod b/pod/perl.pod
index 4c7c586..fcab79e 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -263,12 +263,15 @@ often point out exactly where the trouble is.
Perl officially stands for Practical Extraction and Report Language,
except when it doesn't.
-Perl is a language optimized for scanning arbitrary
+Perl was originally a language optimized for scanning arbitrary
text files, extracting information from those text files, and printing
-reports based on that information. It's also a good language for many
-system management tasks. The language is intended to be practical
-(easy to use, efficient, complete) rather than beautiful (tiny,
-elegant, minimal).
+reports based on that information. It quickly became a good language
+for many system management tasks. Over the years, Perl has grown into
+a general-purpose progammming language. It's widely used for everything
+from quick "one-liners" to full-scale application development.
+
+The language is intended to be practical (easy to use, efficient,
+complete) rather than beautiful (tiny, elegant, minimal).
Perl combines (in the author's opinion, anyway) some of the best
features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
@@ -282,16 +285,8 @@ unlimited depth. And the tables used by hashes (sometimes
called
"associative arrays") grow as necessary to prevent degraded
performance. Perl can use sophisticated pattern matching techniques to
scan large amounts of data quickly. Although optimized for
-scanning text, Perl can also deal with binary data, and can make dbm
-files look like hashes. Setuid Perl scripts are safer than C programs
-through a dataflow tracing mechanism that prevents many stupid
-security holes.
-
-If you have a problem that would ordinarily use B<sed> or B<awk> or
-B<sh>, but it exceeds their capabilities or must run a little faster,
-and you don't want to write the silly thing in C, then Perl may be for
-you. There are also translators to turn your B<sed> and B<awk>
-scripts into Perl scripts.
+scanning text, Perl also has many excellent tools for slicing
+and dicing binary data.
But wait, there's more...
@@ -405,9 +400,6 @@ Perl developers, please write to perl-tha...@perl.org .
=head1 SEE ALSO
- a2p awk to perl translator
- s2p sed to perl translator
-
http://www.perl.org/ the Perl homepage
http://www.perl.com/ Perl articles (O'Reilly)
http://www.cpan.org/ the Comprehensive Perl Archive
diff --git a/pod/perlintro.pod b/pod/perlintro.pod
index c47274b..2d0076a 100644
--- a/pod/perlintro.pod
+++ b/pod/perlintro.pod
@@ -22,6 +22,25 @@ Throughout this document you'll see references to other
parts of the
Perl documentation. You can read that documentation using the C<perldoc>
command or whatever method you're using to read this document.
+Throughout Perl's documentation, you'll find numerous examples intended
+to help explain the discussed features. Please keep in mind that many
+of them are code fragments rather than complete programs.
+
+These examples often reflect the style and preference of the author of
+that piece of the documentation, and may be briefer than a corresponding
+line of code in a real program. Except where otherwise noted, you
+should assume that C<use strict> and C<use warnings> statements
+appear earlier in the "program", and that any variables used have
+already been declared, even if those declarations have been omitted
+to make the example easier to read.
+
+Do note that the examples have been written by many different authors over
+a period of several decades. Styles and techniques will therefore differ,
+although some effort has been made to not vary styles too widely in the
+same sections. Do not consider one style to be better than others - "There
+Is More Than One Way Of Doing It" is one Perl's mottos. After all, in your
+journey as a programmer, you are likely to encounter different styles.
+
=head2 What is Perl?
Perl is a general-purpose programming language originally developed for
diff --git a/pod/perlpolicy.pod b/pod/perlpolicy.pod
index 5b63051..dbf70ec 100644
--- a/pod/perlpolicy.pod
+++ b/pod/perlpolicy.pod
@@ -20,7 +20,7 @@ As a volunteer organization, the commitments we make are
heavily dependent
on the goodwill and hard work of individuals who have no obligation to
contribute to Perl.
-That being said, we value Perl's stabilty and security and have long
+That being said, we value Perl's stability and security and have long
had an unwritten covenant with the broader Perl community to support
and maintain releases of Perl.
@@ -86,7 +86,7 @@ nearly impossible.
Lately, ignoring or actively opposing compatibility with earlier versions
of Perl has come into vogue. Sometimes, a change is proposed which
wants to usurp syntax which previously had another meaning. Sometimes,
-a change wants to improve previously-crazy semantics.
+a change wants to improve previously-crazy semaintics.
Down this road lies madness.
@@ -154,7 +154,7 @@ an experimental feature useful and want to help shape its
future.
=item deprecated
If something in the Perl core is marked as B<deprecated>, we may remove it
-from thecore in the next stable release series, though we may not. As of
+from the core in the next stable release series, though we may not. As of
Perl 5.12, deprecated features and modules warn the user as they're used.
If you use a deprecated feature and believe that its removal from the Perl
core would be a mistake, please contact the perl5-porters mailinglist and
@@ -377,7 +377,45 @@ necessary, and certainly no more drastic measure should be
used until
every avenue of communication and discussion has failed.
+=head1 DOCUMENTATION
+
+Perl's documentation is an important resource for our users. It's
+incredibly important for Perl's documentation to be reasonably coherent
+and to accurately reflect the current implementation.
+
+Just as P5P collectively maintains the codebase, we collectively
+maintain the documentation. Writing a particular bit of documentation
+doesn't give an author control of the future of that documentation.
+At the same time, just as source code changes should match the style
+of their surrounding blocks, so should documentation changes.
+
+Examples in documentation should be illustrative of the concept
+they're explaining. Sometimes, the best way to show how a
+language feature works is with a small program the reader can
+run without modification. More often, examples will consist
+of a snippet of code containing only the "important" bits.
+The definition of "important" varies from snippet to snippet.
+Sometimes it's important to declare C<use strict;> and C<use warnings;>,
+initialize all variables and fully catch every error condition.
+More often than not, though, those things obscure the lesson
+the example was intended to teach.
+
+As Perl is developed by a global team of volunteers, our
+documentation often contains spellings which look funny
+to I<somebody>. Choice of American/British/Other spellings
+is left as an exercise for the author of each bit of
+documentation. When patching documentation, try to emulate
+the documentation around you, rather than changing the existing
+prose.
+
+In general, documentation should describe what Perl does "now" rather
+than what it used to do. It's perfectly reasonable to include notes
+in documentation about how behaviour has changed from previous releases,
+but, with the exception of perlfaq, documentation isn't "dual-life" --
+it doesn't need to fully describe how all old versions used to work.
+
+
=head1 CREDITS
-Social Contract about Contributed Modules originally by Russ Allbery
E<lt>r...@stanford.edue<gt> and the perl5-porters.
+"Social Contract about Contributed Modules" originally by Russ Allbery
E<lt>r...@stanford.edue<gt> and the perl5-porters.
--
Perl5 Master Repository
