From 9e4d1b0536961501011dff6975bb1659921dd3c2 Mon Sep 17 00:00:00 2001 From: chromatic Date: Sat, 3 Dec 2011 17:18:07 -0800 Subject: [PATCH] Improved formatting of chapter 1. --- sections/context_philosophy.pod | 6 ++--- sections/expressivity.pod | 11 ++++---- sections/files.pod | 4 +-- sections/implicit_ideas.pod | 45 ++++++++++++++++----------------- sections/perldoc.pod | 20 +++++---------- 5 files changed, 38 insertions(+), 48 deletions(-) diff --git a/sections/context_philosophy.pod b/sections/context_philosophy.pod index 05e2a5fb..3d9d25b0 100644 --- a/sections/context_philosophy.pod +++ b/sections/context_philosophy.pod @@ -120,7 +120,7 @@ contain. Both of these calls to C occur in list context: my %results = ( - cheap_operation => $cheap_operation_results, + cheap_operation => $cheap_results, expensive_operation => find_chores(), # OOPS! ); @@ -138,7 +138,7 @@ Use the C operator to impose scalar context: my %results = ( - cheap_operation => $cheap_operation_results, + cheap_operation => $cheap_results, expensive_operation => B find_chores(), ); @@ -184,7 +184,7 @@ different, but they still compare the same: =begin programlisting my $alice = 'alice'; - say "Catastrophic crypto fail!" if $alice == 'Bob'; # OOPS + say "Catastrophic crypto fail!" if $alice == 'Bob'; =end programlisting diff --git a/sections/expressivity.pod b/sections/expressivity.pod index c8235f5f..d23de761 100644 --- a/sections/expressivity.pod +++ b/sections/expressivity.pod @@ -5,17 +5,16 @@ Z X X -When Larry Wall created Perl, his studies of linguistics and human languages -influenced his design. Notably, Perl allows you tremendous freedom to solve -your problems, depending on your group style, the available time, the expected +Larry Wall's his studies of linguistics and human languages influenced the +design of Perl. The language allows you tremendous freedom to solve your +problems, depending on your group style, the available time, the expected lifespan of the program, or even how creative you feel. You may write simple, straightforward code or integrate into larger, well-defined programs. You may select from multiple design paradigms, and you may eschew or embrace advanced features. -Where other languages might suggest that one enforced way to write any -operation is the right solution, Perl allows you to optimize for your most -important criteria. +Where other languages enforce one best way to write any code, Perl allows +I to decide what's most readable or useful or fun. X X diff --git a/sections/files.pod b/sections/files.pod index b1059e5d..7656b1a3 100644 --- a/sections/files.pod +++ b/sections/files.pod @@ -25,7 +25,7 @@ you C goes to C. This separation of output allows you to redirect useful output and errors to two different places--an output file and error logs, for example. -=begin sidebar +=begin tip The Many Names of C X> X> @@ -38,7 +38,7 @@ section. Any text which occurs after that token is available for reading from C. This is useful for short, self-contained programs. See C for more details. -=end sidebar +=end tip X> diff --git a/sections/implicit_ideas.pod b/sections/implicit_ideas.pod index b992a512..fb8c79ec 100644 --- a/sections/implicit_ideas.pod +++ b/sections/implicit_ideas.pod @@ -57,8 +57,8 @@ arguments: =begin programlisting - print; # prints $_ to the currently selected filehandle - say; # prints $_ to the currently selected filehandle + print; # prints $_ to the current filehandle + say; # prints $_ to the current filehandle, # with a trailing newline =end programlisting @@ -140,7 +140,8 @@ X> =begin programlisting - say 'Brunch time!' if grep { /pancake mix/ } @pantry; + say 'Brunch time!' + if grep { /pancake mix/ } @pantry; =end programlisting @@ -197,15 +198,13 @@ Use C<$_> as you would the word "it" in formal writing: sparingly, in small and X> -Perl 5.12 introduced the triple-dot (C<...>) operator. It's a complete -statement on its own which acts as a placeholder for code you intend to fill in -later. Perl will parse it as a complete statement, but will throw an exception -that you're trying to run unimplemented code if you try to run it. See -C for more details. +Perl 5.12 introduced the triple-dot (C<...>) operator as a placeholder for code +you intend to fill in later. Perl will parse it as a complete statement, but +will throw an exception that you're trying to run unimplemented code if you try +to run it. See C for more details. =end tip - =head2 The Default Array Variables Z @@ -253,6 +252,20 @@ command-line arguments to the program. Perl's array operations (including C and C) operate on C<@ARGV> implicitly outside of functions. You cannot use C<@_> when you mean C<@ARGV>. +=begin tip C + +X> +X> + +Perl's C<< <$fh> >> operator is the same as the C builtin. +C does the same thing as C<< <$fh> >>. As of Perl 5.10, a bare +C behaves just like C<< <> >>, so you can now use C +everywhere. For historic reasons, C<< <> >> is still more common, but consider +using C as a more readable alternative. You probably prefer C to C<< <*.html> >>, right? It's the same idea. + +=end tip + X C has one special case. If you read from the null filehandle C<< <> >>, @@ -277,20 +290,6 @@ concatenated string in scalar context. If the behavior of C sounds confusing, your instincts are correct. Perl 5 arguably should have separated "reverse a string" from "reverse a list". -=begin tip C - -X> -X> - -Perl's C<< <$fh> >> operator is the same as the C builtin. -C does the same thing as C<< <$fh> >>. As of Perl 5.10, a bare -C behaves just like C<< <> >>, so you can now use C -everywhere. For historic reasons, C<< <> >> is still more common, but consider -using C as a more readable alternative. You probably prefer C to C<< <*.html> >>, right? It's the same idea. - -=end tip - If you run it with a list of files: =begin screen diff --git a/sections/perldoc.pod b/sections/perldoc.pod index 58fedfc1..f5e29e2b 100644 --- a/sections/perldoc.pod +++ b/sections/perldoc.pod @@ -18,7 +18,7 @@ X X U hosts recent versions of the Perl documentation. -The U and U CPAN indexes provide +CPAN indexes at U and U provide documentation for all CPAN modules. Other Perl 5 distributions such as ActivePerl and Strawberry Perl provide local documentation in HTML formats. @@ -52,8 +52,11 @@ the form of the documentation is remarkably consistent. C displays the table of contents of the core documentation, and C displays the table of contents for Frequently Asked -Questions about Perl 5. Skimming these files will give you a great overview of -Perl 5. +Questions about Perl 5. C and C document +Perl's symbolic operators and syntactic constructs. C +explains the meanings of Perl's warning messages. C lists all +of Perl's symbolic variables. Skimming these files will give you a great +overview of Perl 5. =end tip @@ -79,14 +82,6 @@ displays the documentation for the variable which contains the current program's process id. Depending on your shell, you may have to quote the variable appropriately. -=begin tip Deciphering Code - -C and C document Perl's symbolic operators and -syntactic constructs. C explains the meanings of Perl's -warning messages. C lists all of Perl's symbolic variables. - -=end tip - The C<-l> option causes C to display the I to the documentation file rather than the contents of the documentationN file in addition to its F<.pm> file.>. @@ -104,6 +99,3 @@ Perl 5's documentation system is I, or I. C describes how POD works. Other POD tools include C, which validates the form of your POD, and C, which displays local POD as HTML through a minimal web server. - -X> -This book uses an extension of POD called C.