diff options
35 files changed, 104 insertions, 107 deletions
diff --git a/pod/perl5004delta.pod b/pod/perl5004delta.pod index 572c2b5a6f..c83f3e6afd 100644 --- a/pod/perl5004delta.pod +++ b/pod/perl5004delta.pod @@ -195,8 +195,8 @@ A bug in previous versions may have failed to detect some insecure conditions when taint checks are turned on. (Taint checks are used in setuid or setgid scripts, or when explicitly turned on with the C<-T> invocation option.) Although it's unlikely, this may cause a -previously-working script to now fail -- which should be construed -as a blessing, since that indicates a potentially-serious security +previously-working script to now fail, which should be construed +as a blessing since that indicates a potentially-serious security hole was just plugged. The new restrictions when tainting include: @@ -246,7 +246,7 @@ your interpreters. File handles are now stored internally as type IO::Handle. The FileHandle module is still supported for backwards compatibility, but -it is now merely a front end to the IO::* modules -- specifically, +it is now merely a front end to the IO::* modules, specifically IO::Handle, IO::Seekable, and IO::File. We suggest, but do not require, that you use the IO::* modules in new code. @@ -1214,8 +1214,8 @@ or a hash slice, such as (W) The pattern match (//), substitution (s///), and transliteration (tr///) operators work on scalar values. If you apply one of them to an array -or a hash, it will convert the array or hash to a scalar value -- the -length of an array, or the population info of a hash -- and then work on +or a hash, it will convert the array or hash to a scalar value (the +length of an array or the population info of a hash) and then work on that scalar value. This is probably not what you meant to do. See L<perlfunc/grep> and L<perlfunc/map> for alternatives. diff --git a/pod/perl5005delta.pod b/pod/perl5005delta.pod index 6420f87fa9..cabdf9eb7c 100644 --- a/pod/perl5005delta.pod +++ b/pod/perl5005delta.pod @@ -766,7 +766,7 @@ only with arrays that have a hash reference at index 0. (F) You said something like C<< local $ar->{'key'} >>, where $ar is a reference to a pseudo-hash. That hasn't been implemented yet, but you can get a similar effect by localizing the corresponding array -element directly -- C<< local $ar->[$ar->[0]{'key'}] >>. +element directly: C<< local $ar->[$ar->[0]{'key'}] >>. =item Can't use %%! because Errno.pm is not available diff --git a/pod/perl571delta.pod b/pod/perl571delta.pod index d25bee0646..be36e04406 100644 --- a/pod/perl571delta.pod +++ b/pod/perl571delta.pod @@ -935,7 +935,7 @@ machines (Perl's malloc is mostly tuned for space). Many new tests have been added. The most notable is probably the lib/1_compile: it is very notable because running it takes quite a -long time -- it test compiles all the Perl modules in the distribution. +long time. It test compiles all the Perl modules in the distribution. Please be patient. =head1 Known Problems diff --git a/pod/perlboot.pod b/pod/perlboot.pod index cf8e51843a..a6b256a0fc 100644 --- a/pod/perlboot.pod +++ b/pod/perlboot.pod @@ -442,7 +442,7 @@ variations. Now, what about data? -=head2 A horse is a horse, of course of course -- or is it? +=head2 A horse is a horse, of course of course, or is it? Let's start with the code for the C<Animal> class and the C<Horse> class: diff --git a/pod/perlcall.pod b/pod/perlcall.pod index 06f3aa33c7..359e097a18 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -1889,8 +1889,8 @@ The idea is that the calling context only needs to be created and destroyed once, and the sub can be called arbitrarily many times in between. -It is usual to pass parameters using global variables -- typically -$_ for one parameter, or $a and $b for two parameters -- rather +It is usual to pass parameters using global variables (typically +$_ for one parameter, or $a and $b for two parameters) rather than via @_. (It is possible to use the @_ mechanism if you know what you're doing, though there is as yet no supported API for it. It's also inherently slower.) diff --git a/pod/perldata.pod b/pod/perldata.pod index 3c1a95e2c4..bc564e650d 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -633,9 +633,9 @@ key/value pairs. That's why it's good to use references sometimes. It is often more readable to use the C<< => >> operator between key/value pairs. The C<< => >> operator is mostly just a more visually distinctive synonym for a comma, but it also arranges for its left-hand operand to be -interpreted as a string -- if it's a bareword that would be a legal simple -identifier (C<< => >> doesn't quote compound identifiers, that contain -double colons). This makes it nice for initializing hashes: +interpreted as a string if it's a bareword that would be a legal simple +identifier. C<< => >> doesn't quote compound identifiers, that contain +double colons. This makes it nice for initializing hashes: %map = ( red => 0x00f, diff --git a/pod/perldbmfilter.pod b/pod/perldbmfilter.pod index f145b8aa1b..e58ce2013b 100644 --- a/pod/perldbmfilter.pod +++ b/pod/perldbmfilter.pod @@ -61,7 +61,7 @@ When each filter is called by Perl, a local copy of C<$_> will contain the key or value to be filtered. Filtering is achieved by modifying the contents of C<$_>. The return code from the filter is ignored. -=head2 An Example -- the NULL termination problem. +=head2 An Example: the NULL termination problem. DBM Filters are useful for a class of problems where you I<always> want to make the same transformation to all keys, all values or both. @@ -118,7 +118,7 @@ self-explanatory. Both "fetch" filters remove the terminating NULL, and both "store" filters add a terminating NULL. -=head2 Another Example -- Key is a C int. +=head2 Another Example: Key is a C int. Here is another real-life example. By default, whenever Perl writes to a DBM database it always writes the key and value as strings. So when @@ -154,7 +154,7 @@ Here is a DBM Filter that does it: The code above uses DB_File, but again it will work with any of the DBM modules. -This time only two filters have been used -- we only need to manipulate +This time only two filters have been used; we only need to manipulate the contents of the key, so it wasn't necessary to install any value filters. diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 34935ef236..9403e551ee 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -115,8 +115,8 @@ which 'splits' output into two streams, such as (W misc) The pattern match (C<//>), substitution (C<s///>), and transliteration (C<tr///>) operators work on scalar values. If you apply one of them to an array or a hash, it will convert the array or hash to -a scalar value -- the length of an array, or the population info of a -hash -- and then work on that scalar value. This is probably not what +a scalar value (the length of an array, or the population info of a +hash) and then work on that scalar value. This is probably not what you meant to do. See L<perlfunc/grep> and L<perlfunc/map> for alternatives. diff --git a/pod/perldoc.pod b/pod/perldoc.pod index 92404395c5..883a618460 100644 --- a/pod/perldoc.pod +++ b/pod/perldoc.pod @@ -165,7 +165,7 @@ might be more (or less) convenient, depending on what shell you use. =item B<-X> -Use an index if it is present -- the B<-X> option looks for an entry +Use an index if it is present. The B<-X> option looks for an entry whose basename matches the name given on the command line in the file C<$Config{archlib}/pod.idx>. The F<pod.idx> file should contain fully qualified filenames, one per line. @@ -243,7 +243,7 @@ plain text or unformatted pod.) One useful value for C<PERLDOC_PAGER> is C<less -+C -E>. Having PERLDOCDEBUG set to a positive integer will make perldoc emit -even more descriptive output than the C<-v> switch does -- the higher the +even more descriptive output than the C<-v> switch does; the higher the number, the more it emits. diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 8428fe300e..5a68341a6d 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -786,7 +786,7 @@ to survive its use on the stack you need not do any mortalization. If you are not sure then doing an C<SvREFCNT_inc> and C<sv_2mortal>, or making a C<sv_mortalcopy> is safer. -The mortal routines are not just for SVs -- AVs and HVs can be +The mortal routines are not just for SVs; AVs and HVs can be made mortal by passing their address (type-casted to C<SV*>) to the C<sv_2mortal> or C<sv_mortalcopy> routines. @@ -1624,11 +1624,10 @@ and C<dXSTARG>. =head2 Scratchpads The question remains on when the SVs which are I<target>s for opcodes -are created. The answer is that they are created when the current unit -- -a subroutine or a file (for opcodes for statements outside of -subroutines) -- is compiled. During this time a special anonymous Perl -array is created, which is called a scratchpad for the current -unit. +are created. The answer is that they are created when the current +unit--a subroutine or a file (for opcodes for statements outside of +subroutines)--is compiled. During this time a special anonymous Perl +array is created, which is called a scratchpad for the current unit. A scratchpad keeps SVs which are lexicals for the current unit and are targets for opcodes. One can deduce that an SV lives on a scratchpad diff --git a/pod/perlhack.pod b/pod/perlhack.pod index fb9bdb85b1..ef59ebad49 100644 --- a/pod/perlhack.pod +++ b/pod/perlhack.pod @@ -1267,8 +1267,8 @@ C<-Wstrict-prototypes> =back The C<-Wtraditional> is another example of the annoying tendency of -gcc to bundle a lot of warnings under one switch -- it would be -impossible to deploy in practice because it would complain a lot -- but +gcc to bundle a lot of warnings under one switch (it would be +impossible to deploy in practice because it would complain a lot) but it does contain some warnings that would be beneficial to have available on their own, such as the warning about string constants inside macros containing the macro arguments: this behaved differently pre-ANSI @@ -2178,7 +2178,7 @@ in L<perlguts>. The following are common causes of compilation and/or execution failures, not common to Perl as such. The C FAQ is good bedtime reading. Please test your changes with as many C compilers and -platforms as possible -- we will, anyway, and it's nice to save +platforms as possible; we will, anyway, and it's nice to save oneself from public embarrassment. If using gcc, you can add the C<-std=c89> option which will hopefully @@ -2681,25 +2681,25 @@ Third Degree greatly slows down the execution: seconds become minutes, minutes become hours. For example as of Perl 5.8.1, the ext/Encode/t/Unicode.t takes extraordinarily long to complete under e.g. Purify, Third Degree, and valgrind. Under valgrind it takes more -than six hours, even on a snappy computer-- the said test must be +than six hours, even on a snappy computer. The said test must be doing something that is quite unfriendly for memory debuggers. If you don't feel like waiting, that you can simply kill away the perl process. B<NOTE 2>: To minimize the number of memory leak false alarms (see -L</PERL_DESTRUCT_LEVEL> for more information), you have to have -environment variable PERL_DESTRUCT_LEVEL set to 2. The F<TEST> -and harness scripts do that automatically. But if you are running -some of the tests manually-- for csh-like shells: +L</PERL_DESTRUCT_LEVEL> for more information), you have to set the +environment variable PERL_DESTRUCT_LEVEL to 2. + +For csh-like shells: setenv PERL_DESTRUCT_LEVEL 2 -and for Bourne-type shells: +For Bourne-type shells: PERL_DESTRUCT_LEVEL=2 export PERL_DESTRUCT_LEVEL -or in Unixy environments you can also use the C<env> command: +In Unixy environments you can also use the C<env> command: env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ... diff --git a/pod/perlintro.pod b/pod/perlintro.pod index 9973fd62c1..2f5f85eef2 100644 --- a/pod/perlintro.pod +++ b/pod/perlintro.pod @@ -188,7 +188,7 @@ of elements in the array: if (@animals < 5) { ... } The elements we're getting from the array start with a C<$> because -we're getting just a single value out of the array -- you ask for a scalar, +we're getting just a single value out of the array; you ask for a scalar, you get a scalar. To get multiple values from an array: @@ -443,7 +443,7 @@ before 99). ! not (C<and>, C<or> and C<not> aren't just in the above table as descriptions -of the operators -- they're also supported as operators in their own +of the operators. They're also supported as operators in their own right. They're more readable than the C-style operators, but have different precedence to C<&&> and friends. Check L<perlop> for more detail.) diff --git a/pod/perlipc.pod b/pod/perlipc.pod index 25b310bb7b..4f6c0f0484 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -316,8 +316,8 @@ The pragmatic approach was to say "I know the risks, but prefer the convenience", and to do anything you wanted in your signal handler, and be prepared to clean up core dumps now and again. -In Perl 5.7.3 and later to avoid these problems signals are -"deferred"-- that is when the signal is delivered to the process by +Perl 5.7.3 and later avoid these problems by "deferring" signals. +That is, when the signal is delivered to the process by the system (to the C code that implements Perl) a flag is set, and the handler returns immediately. Then at strategic "safe" points in the Perl interpreter (e.g. when it is about to execute a new opcode) the diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod index 45a7f5ffba..835914e486 100644 --- a/pod/perllexwarn.pod +++ b/pod/perllexwarn.pod @@ -91,7 +91,7 @@ a block of code. You might expect this to be enough to do the trick: } When this code is run with the B<-w> flag, a warning will be produced -for the C<$a> line -- C<"Reversed += operator">. +for the C<$a> line: C<"Reversed += operator">. The problem is that Perl has both compile-time and run-time warnings. To disable compile-time warnings you need to rewrite the code like this: @@ -177,7 +177,7 @@ will work unchanged. =item 2. -The B<-w> flag just sets the global C<$^W> variable as in 5.005 -- this +The B<-w> flag just sets the global C<$^W> variable as in 5.005. This means that any legacy code that currently relies on manipulating C<$^W> to control warning behavior will still work as is. diff --git a/pod/perlmod.pod b/pod/perlmod.pod index 4a7c62dfd0..eaa8ba91db 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -134,7 +134,7 @@ refer to the same scalar value. This means that the following code: } Would print '1', because C<$foo> holds a reference to the I<original> -C<$bar> -- the one that was stuffed away by C<local()> and which will be +C<$bar>. The one that was stuffed away by C<local()> and which will be restored when the block ends. Because variables are accessed through the typeglob, you can use C<*foo = *bar> to create an alias which can be localized. (But be aware that this means you can't have a separate @@ -267,7 +267,7 @@ these code blocks by name. A C<BEGIN> code block is executed as soon as possible, that is, the moment it is completely defined, even before the rest of the containing file (or string) is parsed. You may have multiple C<BEGIN> blocks within a file (or -eval'ed string) -- they will execute in order of definition. Because a C<BEGIN> +eval'ed string); they will execute in order of definition. Because a C<BEGIN> code block executes immediately, it can pull in definitions of subroutines and such from other files in time to be visible to the rest of the compile and run time. Once a C<BEGIN> has run, it is immediately undefined and any diff --git a/pod/perlmodinstall.pod b/pod/perlmodinstall.pod index 0229385e94..a7b74be9df 100644 --- a/pod/perlmodinstall.pod +++ b/pod/perlmodinstall.pod @@ -49,7 +49,7 @@ Here's how to perform each step for each operating system. This is might have come with your module! Also note that these instructions are tailored for installing the -module into your system's repository of Perl modules -- but you can +module into your system's repository of Perl modules, but you can install modules into any directory you wish. For instance, where I say C<perl Makefile.PL>, you can substitute C<perl Makefile.PL PREFIX=/my/perl_directory> to install the modules into @@ -110,7 +110,7 @@ Make sure you have the appropriate permissions to install the module in your Perl 5 library directory. Often, you'll need to be root. That's all you need to do on Unix systems with dynamic linking. -Most Unix systems have dynamic linking -- if yours doesn't, or if for +Most Unix systems have dynamic linking. If yours doesn't, or if for another reason you have a statically-linked perl, B<and> the module requires compilation, you'll need to build a new Perl binary that includes the module. Again, you'll probably need to be root. @@ -145,7 +145,7 @@ http://search.cpan.org/dist/dmake/ Does the module require compilation (i.e. does it have files that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now officially tough for you, because you have to compile the module -yourself -- no easy feat on Windows. You'll need a compiler such as +yourself (no easy feat on Windows). You'll need a compiler such as Visual C++. Alternatively, you can download a pre-built PPM package from ActiveState. http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/ diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod index a5e332e533..dfe5662f94 100644 --- a/pod/perlmodstyle.pod +++ b/pod/perlmodstyle.pod @@ -679,7 +679,7 @@ and the tests should also be available to people installing the modules For Module::Build you would use the C<make test> equivalent C<perl Build test>. The importance of these tests is proportional to the alleged stability of a -module -- a module which purports to be stable or which hopes to achieve wide +module. A module which purports to be stable or which hopes to achieve wide use should adhere to as strict a testing regime as possible. Useful modules to help you write tests (with minimum impact on your diff --git a/pod/perlobj.pod b/pod/perlobj.pod index 6d335e5410..fdecd84a68 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -350,8 +350,8 @@ Usually Perl gets it right, but when it doesn't you get a function call compiled as a method, or vice versa. This can introduce subtle bugs that are hard to detect. -For example, a call to a method C<new> in indirect notation -- as C++ -programmers are wont to make -- can be miscompiled into a subroutine +For example, a call to a method C<new> in indirect notation (as C++ +programmers are wont to make) can be miscompiled into a subroutine call if there's already a C<new> function in scope. You'd end up calling the current package's C<new> as a subroutine, rather than the desired class's method. The compiler tries to cheat by remembering diff --git a/pod/perlop.pod b/pod/perlop.pod index 028c808160..d36b090d47 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -1286,7 +1286,7 @@ The last example should print: Notice that the final match matched C<q> instead of C<p>, which a match without the C<\G> anchor would have done. Also note that the final match -did not update C<pos> -- C<pos> is only updated on a C</g> match. If the +did not update C<pos>. C<pos> is only updated on a C</g> match. If the final match did indeed match C<p>, it's a good bet that you're running an older (pre-5.6.0) Perl. @@ -1806,7 +1806,7 @@ must be sure there is a newline after it; otherwise, Perl will give the warning B<Can't find string terminator "END" anywhere before EOF...>. Additionally, the quoting rules for the end of string identifier are not -related to Perl's quoting rules -- C<q()>, C<qq()>, and the like are not +related to Perl's quoting rules. C<q()>, C<qq()>, and the like are not supported in place of C<''> and C<"">, and the only interpolation is for backslashing the quoting character: @@ -2070,7 +2070,7 @@ which are processed further. X<regexp, parse> Previous steps were performed during the compilation of Perl code, -but this one happens at run time--although it may be optimized to +but this one happens at run time, although it may be optimized to be calculated at compile time if appropriate. After preprocessing described above, and possibly after evaluation if concatenation, joining, casing translation, or metaquoting are involved, the @@ -2229,7 +2229,7 @@ is equivalent to the following Perl-like pseudo code: except that it isn't so cumbersome to say, and will actually work. It really does shift the @ARGV array and put the current filename into the $ARGV variable. It also uses filehandle I<ARGV> -internally--<> is just a synonym for <ARGV>, which +internally. <> is just a synonym for <ARGV>, which is magical. (The pseudo code above doesn't work because it treats <ARGV> as non-magical.) diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 2f4e5c5954..826dea54dc 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -155,7 +155,7 @@ Don't put "=headI<n>" commands inside an "=over" ... "=back" region. And perhaps most importantly, keep the items consistent: either use "=item *" for all of them, to produce bullets; or use "=item 1.", "=item 2.", etc., to produce numbered lists; or use "=item foo", -"=item bar", etc. -- namely, things that look nothing like bullets or +"=item bar", etc.--namely, things that look nothing like bullets or numbers. If you start with bullets or numbers, stick with them, as @@ -708,8 +708,8 @@ that could cause odd formatting. Older translators might add wording around an LE<lt>E<gt> link, so that C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example. So you shouldn't write things like C<the LE<lt>fooE<gt> -documentation>, if you want the translated document to read sensibly --- instead write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or +documentation>, if you want the translated document to read sensibly. +Instead, write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the link comes out. diff --git a/pod/perlpodspec.pod b/pod/perlpodspec.pod index da62a35ea0..b7c3122f02 100644 --- a/pod/perlpodspec.pod +++ b/pod/perlpodspec.pod @@ -30,7 +30,7 @@ it implicates that such an option I<may> be provided. =head1 Pod Definitions -Pod is embedded in files, typically Perl source files -- although you +Pod is embedded in files, typically Perl source files, although you can write a file that's nothing but Pod. A B<line> in a file consists of zero or more non-newline characters, @@ -49,7 +49,7 @@ A B<non-blank line> is a line containing one or more characters other than space or tab (and terminated by a newline or end-of-file). (I<Note:> Many older Pod parsers did not accept a line consisting of -spaces/tabs and then a newline as a blank line -- the only lines they +spaces/tabs and then a newline as a blank line. The only lines they considered blank were lines consisting of I<no characters at all>, terminated by a newline.) @@ -70,7 +70,7 @@ etc.). Pod content is contained in B<Pod blocks>. A Pod block starts with a line that matches <m/\A=[a-zA-Z]/>, and continues up to the next line -that matches C<m/\A=cut/> -- or up to the end of the file, if there is +that matches C<m/\A=cut/> or up to the end of the file if there is no C<m/\A=cut/> line. =for comment @@ -132,7 +132,7 @@ I<Some> command paragraphs allow formatting codes in their content In other words, the Pod processing handler for "head1" will apply the same processing to "Did You Remember to CE<lt>use strict;>?" that it -would to an ordinary paragraph -- i.e., formatting codes (like +would to an ordinary paragraph (i.e., formatting codes like "CE<lt>...>") are parsed and presumably formatted appropriately, and whitespace in the form of literal spaces and/or tabs is not significant. @@ -415,7 +415,7 @@ formatting code. Examples: B<< $foo->bar(); >> With this syntax, the whitespace character(s) after the "CE<lt><<" -and before the ">>" (or whatever letter) are I<not> renderable -- they +and before the ">>" (or whatever letter) are I<not> renderable. They do not signify whitespace, are merely part of the formatting codes themselves. That is, these are all synonymous: @@ -1121,14 +1121,14 @@ link text. Note that link text may contain formatting.) =item Second: -The possibly inferred link-text -- i.e., if there was no real link +The possibly inferred link-text; i.e., if there was no real link text, then this is the text that we'll infer in its place. (E.g., for "LE<lt>Getopt::Std>", the inferred link text is "Getopt::Std".) =item Third: The name or URL, or undef if none. (E.g., in "LE<lt>Perl -Functions|perlfunc>", the name -- also sometimes called the page -- +Functions|perlfunc>", the name (also sometimes called the page) is "perlfunc". In "LE<lt>/CAVEATS>", the name is undef.) =item Fourth: @@ -1302,9 +1302,8 @@ for formatting or for EE<lt>...> escapes, as in: L<B<ummE<234>stuff>|...> For C<LE<lt>...E<gt>> codes without a "name|" part, only -C<EE<lt>...E<gt>> and C<ZE<lt>E<gt>> codes may occur -- no -other formatting codes. That is, authors should not use -"C<LE<lt>BE<lt>Foo::BarE<gt>E<gt>>". +C<EE<lt>...E<gt>> and C<ZE<lt>E<gt>> codes may occur. That is, +authors should not use "C<LE<lt>BE<lt>Foo::BarE<gt>E<gt>>". Note, however, that formatting codes and ZE<lt>>'s can occur in any and all parts of an LE<lt>...> (i.e., in I<name>, I<section>, I<text>, @@ -1874,7 +1873,7 @@ currently open region has the formatname "inner", not "outer". (It just happens that "outer" is the format name of a higher-up region.) This is an error. Processors must by default report this as an error, and may halt processing the document containing that error. A corollary of this is that -regions cannot "overlap" -- i.e., the latter block above does not represent +regions cannot "overlap". That is, the latter block above does not represent a region called "outer" which contains X and Y, overlapping a region called "inner" which contains Y and Z. But because it is invalid (as all apparently overlapping regions would be), it doesn't represent that, or diff --git a/pod/perlport.pod b/pod/perlport.pod index 1bcc477f9b..87b2b27406 100644 --- a/pod/perlport.pod +++ b/pod/perlport.pod @@ -452,7 +452,7 @@ Don't count on per-program environment variables, or per-program current directories. Don't count on specific values of C<$!>, neither numeric nor -especially the strings values-- users may switch their locales causing +especially the strings values. Users may switch their locales causing error messages to be translated into their languages. If you can trust a POSIXish environment, you can portably use the symbols defined by the Errno module, like ENOENT. And don't trust on the values of C<$!> @@ -518,13 +518,13 @@ Don't assume that you can ping hosts and get replies. Don't assume that any particular port (service) will respond. -Don't assume that Sys::Hostname (or any other API or command) -returns either a fully qualified hostname or a non-qualified hostname: -it all depends on how the system had been configured. Also remember -things like DHCP and NAT-- the hostname you get back might not be very -useful. +Don't assume that Sys::Hostname (or any other API or command) returns +either a fully qualified hostname or a non-qualified hostname: it all +depends on how the system had been configured. Also remember that for +things such as DHCP and NAT, the hostname you get back might not be +very useful. -All the above "don't":s may look daunting, and they are -- but the key +All the above "don't":s may look daunting, and they are, but the key is to degrade gracefully if one cannot reach the particular network service one wants. Croaking or hanging do not look very professional. @@ -706,8 +706,8 @@ more efficient that the first. =head2 Security Most multi-user platforms provide basic levels of security, usually -implemented at the filesystem level. Some, however, do -not-- unfortunately. Thus the notion of user id, or "home" directory, +implemented at the filesystem level. Some, however, unfortunately do +not. Thus the notion of user id, or "home" directory, or even the state of being logged-in, may be unrecognizable on many platforms. If you write programs that are security-conscious, it is usually best to know what type of system you will be running @@ -721,7 +721,7 @@ their semantics might be different. (From security viewpoint testing for permissions before attempting to do something is silly anyway: if one tries this, there is potential -for race conditions-- someone or something might change the +for race conditions. Someone or something might change the permissions between the permissions check and the actual operation. Just try the operation.) diff --git a/pod/perlrebackslash.pod b/pod/perlrebackslash.pod index b7a6bdc299..3d3a76f58e 100644 --- a/pod/perlrebackslash.pod +++ b/pod/perlrebackslash.pod @@ -392,7 +392,7 @@ contain a hyphen, so there is no ambiguity. =head2 Assertions -Assertions are conditions that have to be true -- they don't actually +Assertions are conditions that have to be true; they don't actually match parts of the substring. There are six assertions that are written as backslash sequences. diff --git a/pod/perlreguts.pod b/pod/perlreguts.pod index 17adf78336..ec1c243f8a 100644 --- a/pod/perlreguts.pod +++ b/pod/perlreguts.pod @@ -685,7 +685,7 @@ that is a permissive version of Unicode's UTF-8 encoding[2]. This uses single bytes to represent characters from the ASCII character set, and sequences of two or more bytes for all other characters. (See L<perlunitut> for more information about the relationship between UTF-8 and perl's -encoding, utf8 -- the difference isn't important for this discussion.) +encoding, utf8. The difference isn't important for this discussion.) No matter how you look at it, Unicode support is going to be a pain in a regex engine. Tricks that might be fine when you have 256 possible diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index 46fbf66718..cc303b1b57 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -833,7 +833,7 @@ original commit in the new commit message. =head1 GRAFTS The perl history contains one mistake which was not caught in the -conversion -- a merge was recorded in the history between blead and +conversion: a merge was recorded in the history between blead and maint-5.10 where no merge actually occurred. Due to the nature of git, this is now impossible to fix in the public repository. You can remove this mis-merge locally by adding the following line to your diff --git a/pod/perlreref.pod b/pod/perlreref.pod index eb3933ae9b..f7d01b8e9b 100644 --- a/pod/perlreref.pod +++ b/pod/perlreref.pod @@ -178,7 +178,7 @@ All are zero-width assertions. =head2 QUANTIFIERS -Quantifiers are greedy by default -- match the B<longest> leftmost. +Quantifiers are greedy by default and match the B<longest> leftmost. Maximal Minimal Possessive Allowed range ------- ------- ---------- ------------- @@ -194,7 +194,7 @@ The possessive forms (new in Perl 5.10) prevent backtracking: what gets matched by a pattern with a possessive quantifier will not be backtracked into, even if that causes the whole match to fail. -There is no quantifier {,n} -- that gets understood as a literal string. +There is no quantifier C<{,n}>. That's interpreted as a literal string. =head2 EXTENDED CONSTRUCTS diff --git a/pod/perlretut.pod b/pod/perlretut.pod index a6ad2101e5..f9a43515c1 100644 --- a/pod/perlretut.pod +++ b/pod/perlretut.pod @@ -734,7 +734,7 @@ match). Closely associated with the matching variables C<$1>, C<$2>, ... are the I<backreferences> C<\1>, C<\2>,... Backreferences are simply matching variables that can be used I<inside> a regexp. This is a -really nice feature -- what matches later in a regexp is made to depend on +really nice feature; what matches later in a regexp is made to depend on what matched earlier in the regexp. Suppose we wanted to look for doubled words in a text, like 'the the'. The following regexp finds all 3-letter doubles with a space in between: @@ -787,10 +787,10 @@ tempted to use it as a part of some other pattern: print "bad line: '$line'\n"; } -But this doesn't match -- at least not the way one might expect. Only +But this doesn't match, at least not the way one might expect. Only after inserting the interpolated C<$a99a> and looking at the resulting full text of the regexp is it obvious that the backreferences have -backfired -- the subexpression C<(\w+)> has snatched number 1 and +backfired. The subexpression C<(\w+)> has snatched number 1 and demoted the groups in C<$a99a> by one rank. This can be avoided by using relative backreferences: @@ -1059,7 +1059,7 @@ satisfied. =back -As we have seen above, Principle 0 overrides the others -- the regexp +As we have seen above, Principle 0 overrides the others. The regexp will be matched as early as possible, with the other principles determining how the regexp matches at that earliest character position. @@ -2487,8 +2487,8 @@ example: # but _does_ print Hmm. What happened here? If you've been following along, you know that -the above pattern should be effectively (almost) the same as the last one -- -enclosing the d in a character class isn't going to change what it +the above pattern should be effectively (almost) the same as the last one; +enclosing the C<d> in a character class isn't going to change what it matches. So why does the first not print while the second one does? The answer lies in the optimizations the regex engine makes. In the first diff --git a/pod/perlrun.pod b/pod/perlrun.pod index bc9d9bc641..fb886b89ef 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -1280,7 +1280,7 @@ See L<perlipc/"Deferred Signals (Safe Signals)">. X<PERL_UNICODE> Equivalent to the B<-C> command-line switch. Note that this is not -a boolean variable-- setting this to C<"1"> is not the right way to +a boolean variable. Setting this to C<"1"> is not the right way to "enable Unicode" (whatever that would mean). You can use C<"0"> to "disable Unicode", though (or alternatively unset PERL_UNICODE in your shell before starting Perl). See the description of the C<-C> diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod index 63dcb841e4..6468aa826b 100644 --- a/pod/perlthrtut.pod +++ b/pod/perlthrtut.pod @@ -109,7 +109,7 @@ looking for implementation details you're going to be either disappointed or confused. Possibly both. This is not to say that Perl threads are completely different from -everything that's ever come before -- they're not. Perl's threading +everything that's ever come before. They're not. Perl's threading model owes a lot to other thread models, especially POSIX. Just as Perl is not C, though, Perl threads are not POSIX threads. So if you find yourself looking for mutexes, or thread priorities, it's time to @@ -161,7 +161,7 @@ make threaded programming easier. =head2 Basic Thread Support -Thread support is a Perl compile-time option -- it's something that's +Thread support is a Perl compile-time option. It's something that's turned on or off when Perl is built at your site, rather than when your programs are compiled. If your Perl wasn't compiled with thread support enabled, then any attempt to use threads will fail. @@ -1003,7 +1003,7 @@ all the variables and data of the parent thread has to be taken. Thus, thread creation can be quite expensive, both in terms of memory usage and time spent in creation. The ideal way to reduce these costs is to have a relatively short number of long-lived threads, all created fairly early -on -- before the base thread has accumulated too much data. Of course, this +on (before the base thread has accumulated too much data). Of course, this may not always be possible, so compromises have to be made. However, after a thread has been created, its performance and extra memory usage should be little different than ordinary code. @@ -1049,9 +1049,8 @@ Whether various library calls are thread-safe is outside the control of Perl. Calls often suffering from not being thread-safe include: C<localtime()>, C<gmtime()>, functions fetching user, group and network information (such as C<getgrent()>, C<gethostent()>, -C<getnetent()> and so on), C<readdir()>, -C<rand()>, and C<srand()> -- in general, calls that depend on some global -external state. +C<getnetent()> and so on), C<readdir()>, C<rand()>, and C<srand()>. In +general, calls that depend on some global external state. If the system Perl is compiled in has thread-safe variants of such calls, they will be used. Beyond that, Perl is at the mercy of diff --git a/pod/perltie.pod b/pod/perltie.pod index 0323e32261..370f644209 100644 --- a/pod/perltie.pod +++ b/pod/perltie.pod @@ -134,8 +134,8 @@ X<STORE> This method will be triggered every time the tied variable is set (assigned). Beyond its self reference, it also expects one (and only one) -argument--the new value the user is trying to assign. Don't worry about -returning a value from STORE -- the semantic of assignment returning the +argument: the new value the user is trying to assign. Don't worry about +returning a value from STORE; the semantic of assignment returning the assigned value is implemented with FETCH. sub STORE { @@ -1078,7 +1078,7 @@ This is the output when it is executed: So far so good. Those of you who have been paying attention will have spotted that the tied object hasn't been used so far. So lets add an extra method to the Remember class to allow comments to be included in -the file -- say, something like this: +the file; say, something like this: sub comment { my $self = shift; diff --git a/pod/perltoot.pod b/pod/perltoot.pod index 5180306688..0d8648bdd5 100644 --- a/pod/perltoot.pod +++ b/pod/perltoot.pod @@ -797,7 +797,7 @@ to do that. There's a bit of package data used in the constructor, but the reference to this is stored on the object itself and all other methods access package data via that reference, so we should be ok. -What do we mean by the Person::new() function -- isn't that actually +What do we mean by the Person::new() function? Isn't that actually a method? Well, in principle, yes. A method is just a function that expects as its first argument a class name (package) or object (blessed reference). Person::new() is the function that both the diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod index 50a2843441..042e421ccd 100644 --- a/pod/perlunicode.pod +++ b/pod/perlunicode.pod @@ -31,7 +31,7 @@ To indicate that Perl source itself is in UTF-8, use C<use utf8;>. The regular expression compiler produces polymorphic opcodes. That is, the pattern adapts to the data and automatically switches to the Unicode character scheme when presented with data that is internally encoded in -UTF-8 -- or instead uses a traditional byte scheme when presented with +UTF-8, or instead uses a traditional byte scheme when presented with byte data. =item C<use utf8> still needed to enable UTF-8/UTF-EBCDIC in scripts @@ -857,7 +857,7 @@ two (or more) classes. END } -It's important to remember not to use "&" for the first set -- that +It's important to remember not to use "&" for the first set; that would be intersecting with nothing (resulting in an empty set). =head2 User-Defined Case Mappings diff --git a/pod/perluniintro.pod b/pod/perluniintro.pod index 6d11bb7a2e..24f1fb2284 100644 --- a/pod/perluniintro.pod +++ b/pod/perluniintro.pod @@ -155,8 +155,8 @@ character set. Otherwise, it uses UTF-8. A user of Perl does not normally need to know nor care how Perl happens to encode its internal strings, but it becomes relevant when -outputting Unicode strings to a stream without a PerlIO layer -- one with -the "default" encoding. In such a case, the raw bytes used internally +outputting Unicode strings to a stream without a PerlIO layer (one with +the "default" encoding). In such a case, the raw bytes used internally (the native character set or UTF-8, as appropriate for each string) will be used, and a "Wide character" warning will be issued if those strings contain a character beyond 0x00FF. diff --git a/pod/perlxs.pod b/pod/perlxs.pod index 5ad24d8aa3..5f773bbac3 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -1945,7 +1945,7 @@ and the module version number. =item typedef my_cxt_t -This struct typedef I<must> always be called C<my_cxt_t> -- the other +This struct typedef I<must> always be called C<my_cxt_t>. The other C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name. Declare a typedef named C<my_cxt_t> that is a structure that contains @@ -1964,7 +1964,7 @@ of C<my_cxt_t>. The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct. -It I<must> be called exactly once -- typically in a BOOT: section. If you +It I<must> be called exactly once, typically in a BOOT: section. If you are maintaining multiple interpreters, it should be called once in each interpreter instance, except for interpreters cloned from existing ones. (But see C<MY_CXT_CLONE> below.) diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod index 090b14a9e7..62bef3b0c5 100644 --- a/pod/perlxstut.pod +++ b/pod/perlxstut.pod @@ -865,7 +865,7 @@ However, to help ease understanding, it is suggested that you place a "&" next to the variable name and away from the variable type), and place a "*" near the variable type, but away from the variable name (as in the call to foo above). By doing so, it is easy to understand exactly what -will be passed to the C function -- it will be whatever is in the "last +will be passed to the C function; it will be whatever is in the "last column". You should take great pains to try to pass the function the type of variable |