diff -ur texi.orig/perl.texi texi/perl.texi --- texi.orig/perl.texi Wed May 28 16:02:46 1997 +++ texi/perl.texi Sat Jun 21 14:38:45 1997 @@ -20,14 +20,15 @@ [ @strong{-hv} ] [ -V[:@emph{configvar}] [ @strong{-cw} ] [ -d[:@emph{debugger}] ] [ -D[@emph{number/list}] [ @strong{-pna} ] [ -F@emph{pattern} ] [ -l[@emph{octal}] ] [ -0[@emph{octal}] - [ -I@emph{dir} ] [ -m[-]@emph{module} ] [ -M[-]@emph{@'module@dots{}@'} + [ -I@emph{dir} ] [ -m[-]@emph{module} ] [ -M[-]@emph{'module@dots{}'} [ -P [ -S [ -x[@emph{dir}] [ -i[@emph{extension}] - [ -e @emph{@'command@'} ] [ @strong{--} ] [ @emph{programfile} ] [ @emph{argument} ]@dots{} + [ -e @emph{'command'} ] [ @strong{--} ] [ @emph{programfile} ] [ @emph{argument} ]@dots{} @end iftex +This manual generated from pod files included in 5.004_1 distribution. For ease of access, the Perl manual has been split up into a number of sections: diff -ur texi.orig/perlcall.texi texi/perlcall.texi --- texi.orig/perlcall.texi Wed May 28 15:30:26 1997 +++ texi/perlcall.texi Wed Jun 18 11:22:31 1997 @@ -40,7 +40,7 @@ Before you launch yourself head first into the rest of this document, it would be a good idea to have read the following two documents - -@xref{perlxs,Perlxs}, and @xref{perlguts,Perlguts},. +@xref{perlxs,Perlxs}, and @xref{perlguts,Perlguts}. @unnumberedsec THE PERL_CALL FUNCTIONS Although this stuff is easier to explain using examples, you first need @@ -2023,7 +2023,7 @@ can be mixed in with all the previous examples we@'ve shown. @unnumberedsec SEE ALSO -@xref{perlxs,Perlxs}, @xref{perlguts,Perlguts},, @xref{perlembed,Perlembed}, +@xref{perlxs,Perlxs}, @xref{perlguts,Perlguts}, @xref{perlembed,Perlembed}, @unnumberedsec AUTHOR Paul Marquess <@file{pmarquess@@bfsec.bt.co.uk}> diff -ur texi.orig/perldata.texi texi/perldata.texi --- texi.orig/perldata.texi Wed May 28 15:46:55 1997 +++ texi/perldata.texi Wed Jun 18 10:53:45 1997 @@ -215,7 +215,7 @@ @example @@whatever = (); -$#whatever = $[ - 1; +$#whatever = -1; @end example If you evaluate a named array in a scalar context, it returns the length of @@ -665,5 +665,5 @@ Another way to create local filehandles is with IO::Handle and its ilk, see the bottom of @samp{open()}, @xref{perlfunc,Perlfunc}. -See @xref{perlref,Perlref}, @xref{perlsub,Perlsub},, and @samp{"Symbol Tables"}, @xref{perlmod,Perlmod}, for more +See @xref{perlref,Perlref}, @xref{perlsub,Perlsub}, and @samp{"Symbol Tables"}, @xref{perlmod,Perlmod}, for more discussion on typeglobs. diff -ur texi.orig/perldebug.texi texi/perldebug.texi --- texi.orig/perldebug.texi Wed May 28 15:30:26 1997 +++ texi/perldebug.texi Wed Jun 18 10:59:59 1997 @@ -308,7 +308,7 @@ affects printing of return value after @code{r} command. @item @code{ornaments} -affects screen appearance of the command line (see @samp{Term::Readline} in this node). +affects screen appearance of the command line (see @samp{Term::ReadLine} in this node). @item @code{frame} affects printing messages on entry and exit from subroutines. If diff -ur texi.orig/perldiag.texi texi/perldiag.texi --- texi.orig/perldiag.texi Wed May 28 15:30:27 1997 +++ texi/perldiag.texi Wed Jun 18 10:49:19 1997 @@ -659,6 +659,10 @@ (W) The @@ISA array contained the name of another package that doesn@'t seem to exist. +@item Can@'t make list assignment to \%ENV on this system +@kindex Can@'t make list assignment to \%ENV on this system +(F) List assignment to %ENV is not supported on some systems, notably VMS. + @item Can@'t mktemp() @kindex Can@'t mktemp() (F) The mktemp() routine failed for some reason while trying to process @@ -925,7 +929,7 @@ @item Deep recursion on subroutine "%s" @kindex Deep recursion on subroutine "%s" (W) This subroutine has called itself (directly or indirectly) 100 -times than it has returned. This probably indicates an infinite +times more than it has returned. This probably indicates an infinite recursion, unless you@'re writing strange benchmark programs, in which case it indicates something else. @@ -1469,7 +1473,7 @@ importing took place, it may for example be that your operating system does not support that particular constant. Hopefully you did use an explicit import list for the constants you expect to see, please see -@samp{use}, @xref{perlfunc,Perlfunc}, and @samp{import}, @xref{perlfunc,Perlfunc},. While an explicit import list +@samp{use}, @xref{perlfunc,Perlfunc}, and @samp{import}, @xref{perlfunc,Perlfunc}. While an explicit import list would probably have caught this error earlier it naturally does not remedy the fact that your operating system still does not support that constant. Maybe you have a typo in the constants of the symbol import @@ -2196,7 +2200,7 @@ @item setruid() not implemented @kindex setruid() not implemented -(F) You tried to assign to C<$>, and your operating system doesn@'t support +(F) You tried to assign to C<$<>, and your operating system doesn@'t support the setruid() system call (or equivalent), or at least Configure didn@'t think so. @@ -2290,9 +2294,11 @@ @item substr outside of string @kindex substr outside of string -(W) You tried to reference a substr() that pointed outside of a string. -That is, the absolute value of the offset was larger than the length of -the string. See @samp{substr}, @xref{perlfunc,Perlfunc}. +(S),(W) You tried to reference a substr() that pointed outside of a +string. That is, the absolute value of the offset was larger than the +length of the string. See @samp{substr}, @xref{perlfunc,Perlfunc}. This warning is +mandatory if substr is used in an lvalue context (as the left hand side +of an assignment or as a subroutine argument for example). @item suidperl is no longer needed since %s @kindex suidperl is no longer needed since %s diff -ur texi.orig/perlembed.texi texi/perlembed.texi --- texi.orig/perlembed.texi Wed May 28 15:30:27 1997 +++ texi/perlembed.texi Wed Jun 18 10:49:19 1997 @@ -8,7 +8,7 @@ @table @asis @item @strong{Use C from Perl?} -Read @xref{perlcall,Perlcall}, and @xref{perlxs,Perlxs},. +Read @xref{perlcall,Perlcall}, and @xref{perlxs,Perlxs}. @item @strong{Use a Unix program from Perl?} Read about back-quotes and about system and exec in @xref{perlfunc,Perlfunc}. @@ -27,7 +27,7 @@ @unnumberedsubsec ROADMAP @samp{Compiling your C program} in this node -There@'s one example in each of the eight sections: +There@'s one example in each of the nine sections: @samp{Adding a Perl interpreter to your C program} in this node @@ -45,8 +45,7 @@ @samp{Using Perl modules, which themselves use C libraries, from your C program} in this node -This documentation is Unix specific; if you have information about how -to embed Perl on other platforms, please send e-mail to <@file{orwant@@tpj.com}>. +@samp{Embedding Perl under Win32} in this node @unnumberedsubsec Compiling your C program If you have trouble compiling the scripts in this documentation, @@ -295,7 +294,7 @@ @unnumberedsubsec Evaluating a Perl statement from your C program Perl provides two API functions to evaluate pieces of Perl code. -These are @samp{perl_eval_sv()}, @xref{perlguts,Perlguts}, and @samp{perl_eval_pv()}, @xref{perlguts,Perlguts},. +These are @samp{perl_eval_sv()}, @xref{perlguts,Perlguts}, and @samp{perl_eval_pv()}, @xref{perlguts,Perlguts}. Arguably, these are the only routines you@'ll ever need to execute snippets of Perl code from within your C program. Your code can be @@ -1032,6 +1031,47 @@ @end example Consult @xref{perlxs,Perlxs}, and @xref{perlguts,Perlguts}, for more details. + +@unnumberedsec Embedding Perl under Win32 +At the time of this writing, there are two versions of Perl which run +under Win32. Interfacing to Activeware@'s Perl library is quite +different from the examples in this documentation, as significant +changes were made to the internal Perl API. However, it is possible +to embed Activeware@'s Perl runtime, see the Perl for Win32 FAQ: +http://www.perl.com/perl/faq/win32/Perl_for_Win32_FAQ.html + +With the "official" Perl version 5.004 or higher, all the examples +within this documentation will compile and run untouched, although, +the build process is slightly different between Unix and Win32. + +For starters, backticks don@'t work under the Win32 native command shell! +The ExtUtils::Embed kit on CPAN ships with a script called +@strong{genmake}, which generates a simple makefile to build a program from +a single C source file. It can be used like so: + + +@example +C:\ExtUtils-Embed\eg> perl genmake interp.c +C:\ExtUtils-Embed\eg> nmake +C:\ExtUtils-Embed\eg> interp -e "print qq@{I@'m embedded in Win32!\n@}" +@end example + +You may wish to use a more robust environment such as the MS Developer +stdio. In this case, to generate perlxsi.c run: + + +@example +perl -MExtUtils::Embed -e xsinit +@end example + +Create a new project, Insert -> Files into Project: perlxsi.c, perl.lib, +and your own source files, e.g. interp.c. Typically you@'ll find +perl.lib in @strong{C:\perl\lib\CORE}, if not, you should see the @strong{CORE} +directory relative to @code{perl -V:archlib}. +The studio will also need this path so it knows where to find Perl +include files. This path can be added via the Tools -> Options -> +Directories menu. Finnally, select Build -> Build interp.exe and +you@'re ready to go! @unnumberedsec MORAL You can sometimes @emph{write faster code} in C, but diff -ur texi.orig/perlfaq.texi texi/perlfaq.texi --- texi.orig/perlfaq.texi Wed May 28 15:30:27 1997 +++ texi/perlfaq.texi Wed Jun 18 10:53:45 1997 @@ -136,7 +136,7 @@ @item 25/March/97 Added more info to the binary distribution section of @xref{perlfaq2,Perlfaq2}. -Added Net::Telnet to @xref{perlfaq6,Perlfaq6}. Fixed typos in @xref{perlfaq8,Perlfaq8},. Added +Added Net::Telnet to @xref{perlfaq6,Perlfaq6}. Fixed typos in @xref{perlfaq8,Perlfaq8}. Added mail sending example to @xref{perlfaq9,Perlfaq9}. Added Merlyn@'s columns to @xref{perlfaq2,Perlfaq2}. diff -ur texi.orig/perlfaq2.texi texi/perlfaq2.texi --- texi.orig/perlfaq2.texi Wed May 28 15:30:27 1997 +++ texi/perlfaq2.texi Wed Jun 18 10:49:19 1997 @@ -443,7 +443,7 @@ @unnumberedsubsec How do I learn about object-oriented Perl programming? @xref{perltoot,Perltoot}, (distributed with 5.004 or later) is a good place to start. -Also, @xref{perlobj,Perlobj}, @xref{perlref,Perlref},, and @xref{perlmod,Perlmod}, are useful references, +Also, @xref{perlobj,Perlobj}, @xref{perlref,Perlref}, and @xref{perlmod,Perlmod}, are useful references, while @xref{perlbot,Perlbot}, has some excellent tips and tricks. @unnumberedsec AUTHOR AND COPYRIGHT diff -ur texi.orig/perlfaq3.texi texi/perlfaq3.texi --- texi.orig/perlfaq3.texi Wed May 28 15:30:27 1997 +++ texi/perlfaq3.texi Wed Jun 18 10:53:45 1997 @@ -457,8 +457,8 @@ @unnumberedsubsec Where can I learn about linking C with Perl? [h2xs, xsubpp] If you want to call C from Perl, start with @xref{perlxstut,Perlxstut}, -moving on to @xref{perlxs,Perlxs}, @samp{xsubpp} in this node, and @xref{perlguts,Perlguts},. If you want to -call Perl from C, then read @xref{perlembed,Perlembed}, @xref{perlcall,Perlcall},, and +moving on to @xref{perlxs,Perlxs}, @samp{xsubpp} in this node, and @xref{perlguts,Perlguts}. If you want to +call Perl from C, then read @xref{perlembed,Perlembed}, @xref{perlcall,Perlcall}, and @xref{perlguts,Perlguts}. Don@'t forget that you can learn a lot from looking at how the authors of existing extension modules wrote their code and solved their problems. diff -ur texi.orig/perlfaq4.texi texi/perlfaq4.texi --- texi.orig/perlfaq4.texi Wed May 28 15:30:27 1997 +++ texi/perlfaq4.texi Wed Jun 18 11:23:30 1997 @@ -432,7 +432,7 @@ If you want to represent quotation marks inside a quotation-mark-delimited field, escape them with backslashes (eg, -C<"like \"this\""). Unescaping them is a task addressed earlier in +@code{"like \"this\""}. Unescaping them is a task addressed earlier in this section. Alternatively, the Text::ParseWords module (part of the standard perl @@ -1199,7 +1199,7 @@ @unnumberedsubsec How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays? Use references (documented in @xref{perlref,Perlref},). Examples of complex data -structures are given in @xref{perldsc,Perldsc}, and @xref{perllol,Perllol},. Examples of +structures are given in @xref{perldsc,Perldsc}, and @xref{perllol,Perllol}. Examples of structures and object-oriented classes are in @xref{perltoot,Perltoot}. @unnumberedsubsec How can I use a reference as a hash key? diff -ur texi.orig/perlfaq7.texi texi/perlfaq7.texi --- texi.orig/perlfaq7.texi Wed May 28 15:30:28 1997 +++ texi/perlfaq7.texi Wed Jun 18 10:53:45 1997 @@ -246,7 +246,7 @@ @unnumberedsubsec How do I create a class? See @xref{perltoot,Perltoot}, for an introduction to classes and objects, as well as -@xref{perlobj,Perlobj}, and @xref{perlbot,Perlbot},. +@xref{perlobj,Perlobj}, and @xref{perlbot,Perlbot}. @unnumberedsubsec How can I tell if a variable is tainted? See @samp{"Laundering and Detecting Tainted Data"}, @xref{perlsec,Perlsec}. Here@'s an diff -ur texi.orig/perlfaq8.texi texi/perlfaq8.texi --- texi.orig/perlfaq8.texi Wed May 28 15:44:25 1997 +++ texi/perlfaq8.texi Wed Jun 18 10:53:46 1997 @@ -892,359 +892,3 @@ @unnumberedsec AUTHOR AND COPYRIGHT Copyright (c) 1997 Tom Christiansen and Nathan Torkington. All rights reserved. See @xref{perlfaq,Perlfaq}, for distribution information. - END-of-perlfaq8.pod -echo x - perlfaq9.pod -sed @'s/^X//@' >perlfaq9.pod << @'END-of-perlfaq9.pod@' -=head1 NAME - -perlfaq9 - Networking ($Revision: 1.17 $, $Date: 1997/04/24 22:44:29 $) - -@unnumberedsec DESCRIPTION -This section deals with questions related to networking, the internet, -and a few on the web. - -@unnumberedsubsec My CGI script runs from the command line but not the browser. Can you help me fix it? -Sure, but you probably can@'t afford our contracting rates :-) - -Seriously, if you can demonstrate that you@'ve read the following FAQs -and that your problem isn@'t something simple that can be easily -answered, you@'ll probably receive a courteous and useful reply to your -question if you post it on comp.infosystems.www.authoring.cgi (if it@'s -something to do with HTTP, HTML, or the CGI protocols). Questions that -appear to be Perl questions but are really CGI ones that are posted to -comp.lang.perl.misc may not be so well received. - -The useful FAQs are: - - -@example -http://www.perl.com/perl/faq/idiots-guide.html -http://www3.pair.com/webthing/docs/cgi/faqs/cgifaq.shtml -http://www.perl.com/perl/faq/perl-cgi-faq.html -http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html -http://www.boutell.com/faq/ -@end example - -@unnumberedsubsec How do I remove HTML from a string? -The most correct way (albeit not the fastest) is to use HTML::Parse -from CPAN (part of the libwww-perl distribution, which is a must-have -module for all web hackers). - -Many folks attempt a simple-minded regular expression approach, like -C//g>, but that fails in many cases because the tags -may continue over line breaks, they may contain quoted angle-brackets, -or HTML comment may be present. Plus folks forget to convert -entities, like @code{<} for example. - -Here@'s one "simple-minded" approach, that works for most files: - - -@example -#!/usr/bin/perl -p0777 -s/<(?:[^>@'"]*|([@'"]).*?\1)*>//gs -@end example - -If you want a more complete solution, see the 3-stage striphtml -program in -http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/striphtml.gz -. - -@unnumberedsubsec How do I extract URLs? -A quick but imperfect approach is - - -@example -#!/usr/bin/perl -n00 -# qxurl - tchrist@@perl.com -print "$2\n" while m@{ - < \s* - A \s+ HREF \s* = \s* (["@']) (.*?) \1 - \s* > -@}gsix; -@end example - -This version does not adjust relative URLs, understand alternate -bases, deal with HTML comments, deal with HREF and NAME attributes in -the same tag, or accept URLs themselves as arguments. It also runs -about 100x faster than a more "complete" solution using the LWP suite -of modules, such as the -http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/xurl.gz -program. - -@unnumberedsubsec How do I download a file from the user@'s machine? How do I open a file on another machine? -In the context of an HTML form, you can use what@'s known as -@strong{multipart/form-data} encoding. The CGI.pm module (available from -CPAN) supports this in the start_multipart_form() method, which isn@'t -the same as the startform() method. - -@unnumberedsubsec How do I make a pop-up menu in HTML? -Use the B<