doc patches from Tom Christiansen <tchrist@chthon.perl.com> (via PM)

	Date: Mon, 13 Jul 1998 19:09:09 -0600
	Message-Id: <199807140109.TAA04678@chthon.perl.com>
	Subject: perlmod.pod patch
	--
	Date: Mon, 13 Jul 1998 18:37:07 -0600
	Message-Id: <199807140037.SAA04556@chthon.perl.com>
	Subject: perlbook.pod patch

p4raw-id: //depot/perl@1484

2 files changed, 20 insertions, 40 deletions

diff --git a/pod/perlbook.pod b/pod/perlbook.pod
index 0ff2cd5a05..76763cd8be 100644
--- a/pod/perlbook.pod
+++ b/pod/perlbook.pod
@@ -4,39 +4,13 @@ perlbook - Perl book information
 
 =head1 DESCRIPTION
 
-You can order Perl books from O'Reilly & Associates, 1-800-998-9938.
-Local/overseas is +1 707 829 0515.  If you can locate an O'Reilly
-order form, you can also fax to +1 707 829 0104.  If you're
-web-connected, you can even mosey on over to http://www.ora.com/ for
-an online order form.
-
-I<Programming Perl, Second Edition> is a reference work that covers
-nearly all of Perl; I<Learning Perl, Second Edition> is a tutorial that
-covers the most frequently used subset of the language; and I<Advanced
-Perl Programming> is an in-depth study of complex topics including the
-internals of perl.  You might also check out the very handy, inexpensive,
-and compact I<Perl 5 Desktop Reference>, especially when the thought of
-lugging the 676-page Camel around doesn't make much sense.  I<Mastering
-Regular Expressions>, by Jeffrey Friedl, is a reference work that covers
-the art and implementation of regular expressions in various languages
-including Perl.  Currently published quarterly by Jon Orwant, I<The Perl
-Journal> is the first and only periodical devoted to All Things Perl.
-See http://www.tpj.com/ for information.
-
-    Programming Perl, Second Edition (the Camel Book):
-	ISBN 1-56592-149-6	(English)
-
-    Learning Perl, Second Edition (the Llama Book):
-	ISBN 1-56592-284-0      (English)
-
-    Learning Perl on Win32 Systems (the Gecko Book):
-	ISBN 1-56592-324-3      (English)
-
-    Advanced Perl Programming (the Panther Book):
-	ISBN 1-56592-220-4	(English)
-
-    Perl 5 Desktop Reference (the reference card):
-	ISBN 1-56592-187-9	(brief English)
-
-    Mastering Regular Expressions (the Hip Owl Book):
-	ISBN 1-56592-257-3      (English)
+The Camel Book, officially known as I<Programming Perl, Second Edition>,
+by Larry Wall et al, is the definitive reference work covering nearly
+all of Perl.  You can order it and other Perl books from O'Reilly &
+Associates, 1-800-998-9938.  Local/overseas is +1 707 829 0515.  If you
+can locate an O'Reilly order form, you can also fax to +1 707 829 0104.
+If you're web-connected, you can even mosey on over to http://www.ora.com/
+for an online order form.
+
+Other Perl books from various publishers and authors 
+can be found listed in L<perlfaq3>.
diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index 2a0f6fecb6..6da31dee3c 100644
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -26,10 +26,16 @@ packages by prefixing the identifier with the package name and a double
 colon: C<$Package::Variable>.  If the package name is null, the C<main>
 package is assumed.  That is, C<$::sail> is equivalent to C<$main::sail>.
 
-(The old package delimiter was a single quote, but double colon
-is now the preferred delimiter, in part because it's more readable
-to humans, and in part because it's more readable to B<emacs> macros.
-It also makes C++ programmers feel like they know what's going on.)
+The old package delimiter was a single quote, but double colon is now the
+preferred delimiter, in part because it's more readable to humans, and
+in part because it's more readable to B<emacs> macros.  It also makes C++
+programmers feel like they know what's going on--as opposed to using the
+single quote as separator, which was there to make Ada programmers feel
+like they knew what's going on.  Because the old-fashioned syntax is still
+supported for backwards compatibility, if you try to use a string like
+C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
+the $s variable in package C<owner>, which is probably not what you meant.
+Use braces to disambiguate, as in C<"This is ${owner}'s house">.
 
 Packages may be nested inside other packages: C<$OUTER::INNER::var>.  This
 implies nothing about the order of name lookups, however.  All symbols