*.pod changes based on the FAQ

After the faqqing dust has settled, it looks like a couple of the
things in the FAQ aren't mentioned in the pods and should be.  I came
up with a list of possible changes, and have implemented all but:
 - Need a discussion of optimising for speed/size, including compiling,
   autosplitting, etc.
 - The buffering discussion from part5 belongs somewhere.
 - The explanation of C<..> in perlop is confusing.  Then again, C<..> is
   confusing.

p5p-msgid: 199703171650.JAA02655@elara.frii.com

8 files changed, 227 insertions, 5 deletions

diff --git a/pod/perldata.pod b/pod/perldata.pod
index 1878f4a5fa..b56f425f18 100644
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -247,6 +247,11 @@ The usual Unix backslash rules apply for making characters such as
 newline, tab, etc., as well as some more exotic forms.  See
 L<perlop/Quote and Quotelike Operators> for a list.
 
+Octal or hex representations in string literals (eg, '0xffff') are not
+automatically converted to their integer representation.  The hex()
+and oct() functions make these conversions for you.  See
+L<perlfunc/hex> and L<perlfunc/oct> for more details.
+
 You can also embed newlines directly in your strings, i.e., they can end
 on a different line than they begin.  This is nice, but if you forget
 your trailing quote, the error will not be reported until Perl finds
@@ -440,6 +445,11 @@ put the list in parentheses to avoid ambiguity.  Examples:
     # A "reverse comma operator".
     return (pop(@foo),pop(@foo))[0];
 
+C<undef> can be assigned to.  This is useful for throwing away some of
+the return values of a function:
+
+    ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
+
 Lists may be assigned to if and only if each element of the list
 is legal to assign to:
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index eb7276a3b4..0372ee35ee 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1437,8 +1437,10 @@ Returns the socket option requested, or undefined if there is an error.
 =item glob
 
 Returns the value of EXPR with filename expansions such as a shell
-would do.  This is the internal function implementing the <*.c>
-operator, except it's easier to use.  If EXPR is omitted, $_ is used.
+would do.  This is the internal function implementing the
+C<E<lt>*.cE<gt>> operator, except it's easier to use.  If EXPR is
+omitted, $_ is used.  The E<lt>E<gt> operator is discussed in more
+detail in L<perlop/"I/O Operators">.
 
 =item gmtime EXPR
 
diff --git a/pod/perlipc.pod b/pod/perlipc.pod
index d289ad380c..ab4a912bc6 100644
--- a/pod/perlipc.pod
+++ b/pod/perlipc.pod
@@ -258,6 +258,57 @@ handle.  Consider:
     print FH "bang\n";
     close FH;
 
+=head2 Filehandles
+
+Both the main process and the child process share the same STDIN,
+STDOUT and STDERR filehandles.  If both processes try to access them
+at once, strange things can happen.  You may want to close or reopen
+the filehandles for the child.  You can get around this by opening
+your pipe with open(), but on some systems this means that the child
+process cannot outlive the parent.
+
+=head2 Background Processes
+
+You can run a command in the background with:
+
+    system("cmd&");
+
+The command's STDOUT and STDERR (and possibly STDIN, depending on your
+shell) will be the same as the parent's.  You won't need to catch
+SIGCHLD because of the double-fork taking place (see below for more
+details).
+
+=head2 Complete Dissociation of Child from Parent
+
+In some cases (starting server processes, for instance) you'll want to
+complete dissociate the child process from the parent.  The following
+process is reported to work on most Unixish systems.  Non-Unix users
+should check their Your_OS::Process module for other solutions.
+
+=over 4
+
+=item *
+
+Open /dev/tty and use the the TIOCNOTTY ioctl on it.  See L<tty(4)>
+for details.
+
+=item *
+
+Change directory to /
+
+=item *
+
+Reopen STDIN, STDOUT, and STDERR so they're not connected to the old
+tty.
+
+=item *
+
+Background yourself like this:
+
+    fork && exit;
+
+=back
+
 =head2 Safe Pipe Opens
 
 Another interesting approach to IPC is making your single program go
@@ -428,6 +479,14 @@ setting C<$AF_INET = 2>, you know you're in for big trouble:  An
 immeasurably superior approach is to use the C<Socket> module, which more
 reliably grants access to various constants and functions you'll need.
 
+If you're not writing a server/client for an existing protocol like
+NNTP or SMTP, you should give some thought to how your server will
+know when the client has finished talking, and vice-versa.  Most
+protocols are based on one-line messages and responses (so one party
+knows the other has finished when a "\n" is received) or multiline
+messages and responses that end with a period on an empty line
+("\n.\n" terminates a message/response).
+
 =head2 Internet TCP Clients and Servers
 
 Use Internet-domain sockets when you want to do client-server
diff --git a/pod/perlop.pod b/pod/perlop.pod
index 71794fa759..17c3c05541 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -1190,3 +1190,23 @@ for them.  By default, their results are interpreted as unsigned
 integers.  However, if C<use integer> is in effect, their results are
 interpreted as signed integers.  For example, C<~0> usually evaluates
 to a large integral value.  However, C<use integer; ~0> is -1.
+
+=head2 Floating-point Arithmetic
+
+While C<use integer> provides integer-only arithmetic, there is no
+similar ways to provide rounding or truncation at a certain number of
+decimal places.  For rounding to a certain number of digits, sprintf()
+or printf() is usually the easiest route.
+
+The POSIX module (part of the standard perl distribution) implements
+ceil(), floor(), and a number of other mathematical and trigonometric
+functions.  The Math::Complex module (part of the standard perl
+distribution) defines a number of mathematical functions that can also
+work on real numbers.  Math::Complex not as efficient as POSIX, but
+POSIX can't work with complex numbers.
+
+Rounding in financial applications can have serious implications, and
+the rounding method used should be specified precisely.  In these
+cases, it probably pays not to trust whichever system rounding is
+being used by Perl, but to instead implement the rounding function you
+need yourself.
diff --git a/pod/perlre.pod b/pod/perlre.pod
index cb3ce032d0..e4ee3032b2 100644
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -9,9 +9,10 @@ description of how to I<use> regular expressions in matching
 operations, plus various examples of the same, see C<m//> and C<s///> in
 L<perlop>.
 
-The matching operations can
-have various modifiers, some of which relate to the interpretation of
-the regular expression inside.  These are:
+The matching operations can have various modifiers.  The modifiers
+which relate to the interpretation of the regular expression inside
+are listed below.  For the modifiers that alter the behaviour of the
+operation, see L<perlop/"m//"> and L<perlop/"s//">.
 
 =over 4
 
@@ -214,6 +215,17 @@ everything after the matched string.  Examples:
 	$seconds = $3;
     }
 
+Once perl sees that you need one of C<$&>, C<$`> or C<$'> anywhere in
+the program, it has to provide them on each and every pattern match.
+This can slow your program down.  The same mechanism that handles
+these provides for the use of $1, $2, etc., so you pay the same price
+for each regexp that contains capturing parentheses. But if you never
+use $&, etc., in your script, then regexps I<without> capturing
+parentheses won't be penalized. So avoid $&, $', and $` if you can,
+but if you can't (and some algorithms really appreciate them), once
+you've used them once, use them at will, because you've already paid
+the price.
+
 You will note that all backslashed metacharacters in Perl are
 alphanumeric, such as C<\b>, C<\w>, C<\n>.  Unlike some other regular expression
 languages, there are no backslashed symbols that aren't alphanumeric.
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index f90e642d40..88cba6ec2b 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -87,6 +87,87 @@ If the script is syntactically correct, it is executed.  If the script
 runs off the end without hitting an exit() or die() operator, an implicit
 C<exit(0)> is provided to indicate successful completion.
 
+=head2 #! and quoting on non-Unix systems
+
+Unix's #! technique can be simulated on other systems:
+
+=over 4
+
+=item OS/2
+
+Put
+
+    extproc perl -S -your_switches
+
+as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's
+`extproc' handling).
+
+=item DOS
+
+Create a batch file to run your script, and codify it in
+C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source
+distribution for more information).
+
+=item Win95/NT
+
+The Win95/NT installation, when using the Activeware port of Perl,
+will modify the Registry to associate the .pl extension with the perl
+interpreter.  If you install another port, or (eventually) build your
+own Win95/NT Perl using WinGCC, then you'll have to modify the
+Registry yourself.
+
+=item Macintosh
+
+Macintosh perl scripts will have the the appropriate Creator and
+Type, so that double-clicking them will invoke the perl application.
+
+=back
+
+Command-interpreters on non-Unix systems have rather different ideas
+on quoting than Unix shells.  You'll need to learn the special
+characters in your command-interpreter (C<*>, C<\> and C<"> are
+common) and how to protect whitespace and these characters to run
+one-liners (see C<-e> below).
+
+On some systems, you may have to change single-quotes to double ones,
+which you must I<NOT> do on Unix or Plan9 systems.  You might also
+have to change a single % to a %%.
+
+For example:
+
+    # Unix
+    perl -e 'print "Hello world\n"'
+
+    # DOS, etc.
+    perl -e "print \"Hello world\n\""
+
+    # Mac
+    print "Hello world\n"
+     (then Run "Myscript" or Shift-Command-R)
+
+    # VMS
+    perl -e "print ""Hello world\n"""
+
+The problem is that none of this is reliable: it depends on the command
+tirely possible neither works.  If 4DOS was the command shell, I'd
+probably have better luck like this:
+
+  perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
+
+CMD.EXE in Windows NT slipped a lot of standard Unix functionality in
+when nobody was looking, but just try to find documentation for its
+quoting rules.
+
+Under the Mac, it depends which environment you are using.  The MacPerl
+shell, or MPW, is much like Unix shells in its support for several
+quoting variants, except that it makes free use of the Mac's non-ASCII
+characters as control characters.
+
+I'm afraid that there is no general solution to all of this.  It is a
+mess, pure and simple.
+
+[Some of this answer was contributed by Kenneth Albanowski.]
+
 =head2 Switches
 
 A single-character switch may be combined with the following switch, if
diff --git a/pod/perlsec.pod b/pod/perlsec.pod
index 6089431a2a..0d72cf0ca6 100644
--- a/pod/perlsec.pod
+++ b/pod/perlsec.pod
@@ -287,3 +287,38 @@ SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition.
 Prior to release 5.003 of Perl, a bug in the code of B<suidperl> could
 introduce a security hole in systems compiled with strict POSIX
 compliance.
+
+=head2 Protecting Your Programs
+
+There are a number of ways to hide the source to your Perl programs,
+with varying levels of "security".
+
+First of all, however, you I<can't> take away read permission, because
+the source code has to be readable in order to be compiled and
+interpreted.  (That doesn't mean that a CGI script's source is
+readable by people on the web, though.)  So you have to leave the
+permissions at the socially friendly 0755 level.
+
+Some people regard this as a security problem.  If your program does
+insecure things, and relies on people not knowing how to exploit those
+insecurities, it is not secure.  It is often possible for someone to
+determine the insecure things and exploit them without viewing the
+source.  Security through obscurity, the name for hiding your bugs
+instead of fixing them, is little security indeed.
+
+You can try using encryption via source filters (Filter::* from CPAN).
+But crackers might be able to decrypt it.  You can try using the
+byte-code compiler and interpreter described below, but crackers might
+be able to de-compile it.  You can try using the native-code compiler
+described below, but crackers might be able to disassemble it.  These
+pose varying degrees of difficulty to people wanting to get at your
+code, but none can definitively conceal it (this is true of every
+language, not just Perl).
+
+If you're concerned about people profiting from your code, then the
+bottom line is that nothing but a restrictive licence will give you
+legal security.  License your software and pepper it with threatening
+statements like "This is unpublished proprietary software of XYZ Corp.
+Your access to it does not give you permission to use it blah blah
+blah."  You should see a lawyer to be sure your licence's wording will
+stand up in court.
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index d072d25df9..47503b339b 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -213,6 +213,9 @@ delimit line boundaries when quoting poetry.)
     $_ = <FH>; 		# whole file now here
     s/\n[ \t]+/ /g;
 
+Remember: the value of $/ is a string, not a regexp.  AWK has to be
+better for something :-)
+
 =item autoflush HANDLE EXPR
 
 =item $OUTPUT_AUTOFLUSH