Bunch of doc patches from Stas; plus regen.

Subject: [doc patch] perl.c's pod api entry
Date: Mon, 10 Mar 2003 12:35:52 +1100
Message-ID: <3E6BEBF8.80402@stason.org>

Subject: Re: [patch] perlguts.pod
From: Stas Bekman <stas@stason.org>
Date: Mon, 10 Mar 2003 12:38:57 +1100
Message-ID: <3E6BECB1.7050009@stason.org>

Subject: Re: [PATCH ext/DynaLoader/DynaLoader_pm.PL] doc fix: s/dl_loadflags/dl_load_flags/
From: Stas Bekman <stas@stason.org>
Date: Mon, 10 Mar 2003 12:41:46 +1100
Message-ID: <3E6BED5A.801@stason.org>

Subject: Re: [patch] perlapi.pod fix
From: Stas Bekman <stas@stason.org>
Date: Mon, 10 Mar 2003 12:43:33 +1100
Message-ID: <3E6BEDC5.6010405@stason.org>

Subject: Re: [docs patch] replace gets() with fgets() in example
From: Stas Bekman <stas@stason.org>
Date: Mon, 10 Mar 2003 12:45:41 +1100
Message-ID: <3E6BEE45.9030901@stason.org>

Subject: [doc patch] perlrun.pod
From: Stas Bekman <stas@stason.org>
Date: Mon, 10 Mar 2003 14:49:59 +1100
Message-ID: <3E6C0B67.4050606@stason.org>

p4raw-id: //depot/perl@18873

7 files changed, 43 insertions, 18 deletions

diff --git a/ext/DynaLoader/DynaLoader_pm.PL b/ext/DynaLoader/DynaLoader_pm.PL
index 05fe3f7c65..d6dfef8694 100644
--- a/ext/DynaLoader/DynaLoader_pm.PL
+++ b/ext/DynaLoader/DynaLoader_pm.PL
@@ -769,11 +769,11 @@ Apache and mod_perl built with the APXS mechanism.
 Linux, and is a common choice when providing a "wrapper" on other
 mechanisms as is done in the OS/2 port.)
 
-=item dl_loadflags()
+=item dl_load_flags()
 
 Syntax:
 
-    $flags = dl_loadflags $modulename;
+    $flags = dl_load_flags $modulename;
 
 Designed to be a method call, and to be overridden by a derived class
 (i.e. a class which has DynaLoader in its @ISA).  The definition in
diff --git a/handy.h b/handy.h
index c16ba471ff..18e907f14f 100644
--- a/handy.h
+++ b/handy.h
@@ -25,6 +25,7 @@
 
 =for apidoc AmU||Nullch 
 Null character pointer.
+
 =for apidoc AmU||Nullsv
 Null SV pointer.
 
diff --git a/perl.c b/perl.c
index b6386b93e8..52cf4a7938 100644
--- a/perl.c
+++ b/perl.c
@@ -2083,7 +2083,7 @@ Perl_eval_pv(pTHX_ const char *p, I32 croak_on_error)
 
 Tells Perl to C<require> the file named by the string argument.  It is
 analogous to the Perl code C<eval "require '$file'">.  It's even
-implemented that way; consider using Perl_load_module instead.
+implemented that way; consider using load_module instead.
 
 =cut */
 
diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 5945becc84..d31ec00250 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -687,7 +687,7 @@ Found in file perl.c
 
 Tells Perl to C<require> the file named by the string argument.  It is
 analogous to the Perl code C<eval "require '$file'">.  It's even
-implemented that way; consider using Perl_load_module instead.
+implemented that way; consider using load_module instead.
 
 NOTE: the perl_ form of this function is deprecated.
 
@@ -915,6 +915,7 @@ Found in file hv.h
 =item Nullch
 
 Null character pointer.
+
 =for hackers
 Found in file handy.h
 
@@ -4237,6 +4238,25 @@ Like C<sv_setpvf>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
+=item sv_setpviv
+
+Copies an integer into the given SV, also updating its string value.
+Does not handle 'set' magic.  See C<sv_setpviv_mg>.
+
+	void	sv_setpviv(SV* sv, IV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpviv_mg
+
+Like C<sv_setpviv>, but also handles 'set' magic.
+
+	void	sv_setpviv_mg(SV *sv, IV iv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_setpvn
 
 Copies a string into an SV.  The C<len> parameter indicates the number of
diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 484884ea06..7d00c6473a 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -750,6 +750,8 @@ with L<perlfunc/my> whenever possible.
  #define DO_CLEAN 0
  #endif
 
+ #define BUFFER_SIZE 1024
+
  static PerlInterpreter *my_perl = NULL;
 
  int
@@ -757,7 +759,7 @@ with L<perlfunc/my> whenever possible.
  {
      char *embedding[] = { "", "persistent.pl" };
      char *args[] = { "", DO_CLEAN, NULL };
-     char filename [1024];
+     char filename[BUFFER_SIZE];
      int exitstatus = 0;
      STRLEN n_a;
 
@@ -772,8 +774,10 @@ with L<perlfunc/my> whenever possible.
      if(!exitstatus) {
         exitstatus = perl_run(my_perl);
 
-        while(printf("Enter file name: ") && gets(filename)) {
+        while(printf("Enter file name: ") &&
+              fgets(filename, BUFFER_SIZE, stdin)) {
 
+            filename[strlen(filename)-1] = '\0'; /* strip \n */
             /* call the subroutine, passing it the filename as an argument */
             args[0] = filename;
             call_argv("Embed::Persistent::eval_file",
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 61e93d78ba..83ed068604 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -1799,7 +1799,7 @@ A public function (i.e. part of the internal API, but not necessarily
 sanctioned for use in extensions) begins like this:
 
   void
-  Perl_sv_setsv(pTHX_ SV* dsv, SV* ssv)
+  Perl_sv_setiv(pTHX_ SV* dsv, IV num)
 
 C<pTHX_> is one of a number of macros (in perl.h) that hide the
 details of the interpreter's context.  THX stands for "thread", "this",
@@ -1818,19 +1818,19 @@ macro without the trailing underscore is used when there are no additional
 explicit arguments.
 
 When a core function calls another, it must pass the context.  This
-is normally hidden via macros.  Consider C<sv_setsv>.  It expands into
+is normally hidden via macros.  Consider C<sv_setiv>.  It expands into
 something like this:
 
-    ifdef PERL_IMPLICIT_CONTEXT
-      define sv_setsv(a,b)      Perl_sv_setsv(aTHX_ a, b)
+    #ifdef PERL_IMPLICIT_CONTEXT
+      #define sv_setiv(a,b)      Perl_sv_setiv(aTHX_ a, b)
       /* can't do this for vararg functions, see below */
-    else
-      define sv_setsv           Perl_sv_setsv
-    endif
+    #else
+      #define sv_setiv           Perl_sv_setiv
+    #endif
 
 This works well, and means that XS authors can gleefully write:
 
-    sv_setsv(foo, bar);
+    sv_setiv(foo, bar);
 
 and still have it work under all the modes Perl could have been
 compiled with.
@@ -1874,16 +1874,16 @@ with extensions: whenever XSUB.h is #included, it redefines the aTHX
 and aTHX_ macros to call a function that will return the context.
 Thus, something like:
 
-        sv_setsv(asv, bsv);
+        sv_setiv(sv, num);
 
 in your extension will translate to this when PERL_IMPLICIT_CONTEXT is
 in effect:
 
-        Perl_sv_setsv(Perl_get_context(), asv, bsv);
+        Perl_sv_setiv(Perl_get_context(), sv, num);
 
 or to this otherwise:
 
-        Perl_sv_setsv(asv, bsv);
+        Perl_sv_setiv(sv, num);
 
 You have to do nothing new in your extension to get this; since
 the Perl library provides Perl_get_context(), it will all just
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 7c5b6ba448..bb403b8d49 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -311,7 +311,7 @@ disable all the above Unicode features.
 The read-only magic variable C<${^UNICODE}> reflects the numeric value
 of this setting.  This is variable is set during Perl startup and is
 thereafter read-only.  If you want runtime effects, use the three-arg
-open() (see L<perlfunc/open), the two-arg binmode() (see L<perlfunc/binmode>),
+open() (see L<perlfunc/open>), the two-arg binmode() (see L<perlfunc/binmode>),
 and the C<open> pragma (see L<open>).
 
 (In Perls earlier than 5.8.1 the C<-C> switch was a Win32-only switch