Fixed 27 issues in perlembed.pod reported by podcheck

Fixed mostly lines exceeding 80 characters by decreasing leading
space in verbatim lines to one space. Also fixed long code lines
with a slash and line break.

Add Gideon Israel Dsouza to list of Perl authors.

For: RT #120093

1 files changed, 123 insertions, 110 deletions

diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 979c944670..4560ecc786 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -20,7 +20,7 @@ Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
 
 =item B<Use Perl from Perl?>
 
-Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require> 
+Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
 and L<perlfunc/use>.
 
 =item B<Use C from C?>
@@ -77,7 +77,7 @@ Using Perl modules, which themselves use C libraries, from your C program
 
 Embedding Perl under Win32
 
-=back 
+=back
 
 =head2 Compiling your C program
 
@@ -125,7 +125,7 @@ L<Adding a Perl interpreter to your C program>, on my Linux box:
     -L/usr/local/lib/perl5/i586-linux/5.003/CORE
     -o interp interp.c -lperl -lm
 
-(That's all one line.)  On my DEC Alpha running old 5.003_05, the 
+(That's all one line.)  On my DEC Alpha running old 5.003_05, the
 incantation is a bit different:
 
     % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
@@ -176,13 +176,13 @@ In a sense, perl (the C program) is a good example of embedding Perl
 included in the source distribution.  Here's a bastardized, non-portable
 version of I<miniperlmain.c> containing the essentials of embedding:
 
-    #include <EXTERN.h>               /* from the Perl distribution     */
-    #include <perl.h>                 /* from the Perl distribution     */
+ #include <EXTERN.h>               /* from the Perl distribution     */
+ #include <perl.h>                 /* from the Perl distribution     */
 
-    static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/
+ static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/
 
-    int main(int argc, char **argv, char **env)
-    {
+ int main(int argc, char **argv, char **env)
+ {
 	PERL_SYS_INIT3(&argc,&argv,&env);
         my_perl = perl_alloc();
         perl_construct(my_perl);
@@ -192,7 +192,7 @@ version of I<miniperlmain.c> containing the essentials of embedding:
         perl_destruct(my_perl);
         perl_free(my_perl);
 	PERL_SYS_TERM();
-    }
+ }
 
 Notice that we don't use the C<env> pointer.  Normally handed to
 C<perl_parse> as its final argument, C<env> here is replaced by
@@ -272,24 +272,24 @@ I<G_DISCARD>).  Those flags, and others, are discussed in L<perlcall>.
 
 I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
 
-    print "I shan't be printed.";
+ print "I shan't be printed.";
 
-    sub showtime {
-        print time;
-    }
-
-Simple enough.  Now compile and run:
+ sub showtime {
+     print time;
+ }
 
-    % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
+Simple enough. Now compile and run:
 
-    % showtime showtime.pl
-    818284590
+ % cc -o showtime showtime.c \
+     `perl -MExtUtils::Embed -e ccopts -e ldopts`
+ % showtime showtime.pl
+ 818284590
 
 yielding the number of seconds that elapsed between January 1, 1970
 (the beginning of the Unix epoch), and the moment I began writing this
 sentence.
 
-In this particular case we don't have to call I<perl_run>, as we set 
+In this particular case we don't have to call I<perl_run>, as we set
 the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
 perl_destruct.
 
@@ -315,41 +315,43 @@ extract variables for coercion into C types.  The following program,
 I<string.c>, executes three Perl strings, extracting an C<int> from
 the first, a C<float> from the second, and a C<char *> from the third.
 
-   #include <EXTERN.h>
-   #include <perl.h>
+ #include <EXTERN.h>
+ #include <perl.h>
 
-   static PerlInterpreter *my_perl;
+ static PerlInterpreter *my_perl;
 
-   main (int argc, char **argv, char **env)
-   {
-       char *embedding[] = { "", "-e", "0" };
+ main (int argc, char **argv, char **env)
+ {
+     char *embedding[] = { "", "-e", "0" };
 
-       PERL_SYS_INIT3(&argc,&argv,&env);
-       my_perl = perl_alloc();
-       perl_construct( my_perl );
+     PERL_SYS_INIT3(&argc,&argv,&env);
+     my_perl = perl_alloc();
+     perl_construct( my_perl );
 
-       perl_parse(my_perl, NULL, 3, embedding, NULL);
-       PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
-       perl_run(my_perl);
+     perl_parse(my_perl, NULL, 3, embedding, NULL);
+     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+     perl_run(my_perl);
 
-       /** Treat $a as an integer **/
-       eval_pv("$a = 3; $a **= 2", TRUE);
-       printf("a = %d\n", SvIV(get_sv("a", 0)));
+     /** Treat $a as an integer **/
+     eval_pv("$a = 3; $a **= 2", TRUE);
+     printf("a = %d\n", SvIV(get_sv("a", 0)));
 
-       /** Treat $a as a float **/
-       eval_pv("$a = 3.14; $a **= 2", TRUE);
-       printf("a = %f\n", SvNV(get_sv("a", 0)));
+     /** Treat $a as a float **/
+     eval_pv("$a = 3.14; $a **= 2", TRUE);
+     printf("a = %f\n", SvNV(get_sv("a", 0)));
 
-       /** Treat $a as a string **/
-       eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
-       printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
+     /** Treat $a as a string **/
+     eval_pv(
+       "$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
+     printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
 
-       perl_destruct(my_perl);
-       perl_free(my_perl);
-       PERL_SYS_TERM();
-   }
+     perl_destruct(my_perl);
+     perl_free(my_perl);
+     PERL_SYS_TERM();
+ }
 
-All of those strange functions with I<sv> in their names help convert Perl scalars to C types.  They're described in L<perlguts> and L<perlapi>.
+All of those strange functions with I<sv> in their names help convert Perl
+scalars to C types.  They're described in L<perlguts> and L<perlapi>.
 
 If you compile and run I<string.c>, you'll see the results of using
 I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
@@ -388,14 +390,15 @@ returns 1 if the string matches the pattern and 0 otherwise.
 
 Given a pointer to an C<SV> and an C<=~> operation (e.g.,
 C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string
-within the C<SV> as according to the operation, returning the number of substitutions
-made.
+within the C<SV> as according to the operation, returning the number of
+substitutions made.
 
    SSize_t matches(SV *string, char *pattern, AV **matches);
 
 Given an C<SV>, a pattern, and a pointer to an empty C<AV>,
 matches() evaluates C<$string =~ $pattern> in a list context, and
-fills in I<matches> with the array elements, returning the number of matches found.
+fills in I<matches> with the array elements, returning the number of matches
+found.
 
 Here's a sample program, I<match.c>, that uses all three (long lines have
 been wrapped here):
@@ -406,8 +409,8 @@ been wrapped here):
  static PerlInterpreter *my_perl;
 
  /** my_eval_sv(code, error_check)
- ** kinda like eval_sv(), 
- ** but we pop the return value off the stack 
+ ** kinda like eval_sv(),
+ ** but we pop the return value off the stack
  **/
  SV* my_eval_sv(SV *sv, I32 croak_on_error)
  {
@@ -450,7 +453,8 @@ been wrapped here):
 
  /** substitute(string, pattern)
  **
- ** Used for =~ operations that modify their left-hand side (s/// and tr///)
+ ** Used for =~ operations that
+ ** modify their left-hand side (s/// and tr///)
  **
  ** Returns the number of successful matches, and
  ** modifies the input string if there were any.
@@ -535,7 +539,8 @@ been wrapped here):
      printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
 
      for (i = 0; i < num_matches; i++)
- 	printf("match: %s\n", SvPV_nolen(*av_fetch(match_list, i, FALSE)));
+         printf("match: %s\n",
+                  SvPV_nolen(*av_fetch(match_list, i, FALSE)));
      printf("\n");
 
      /** Remove all vowels from text **/
@@ -560,22 +565,23 @@ been wrapped here):
 
 which produces the output (again, long lines have been wrapped here)
 
-   match: Text contains the word 'quarter'.
+  match: Text contains the word 'quarter'.
 
-   match: Text doesn't contain the word 'eighth'.
+  match: Text doesn't contain the word 'eighth'.
 
-   matches: m/(wi..)/g found 2 matches...
-   match: will
-   match: with
+  matches: m/(wi..)/g found 2 matches...
+  match: will
+  match: with
 
-   substitute: s/[aeiou]//gi...139 substitutions made.
-   Now text is: Whn h s t  cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
-   Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
-   qrtr, bt h hs n d *wht*.  H fmbls thrgh hs rd sqzy chngprs nd gvs th by
-   thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt.  Th by gvs
-   hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
+  substitute: s/[aeiou]//gi...139 substitutions made.
+  Now text is: Whn h s t  cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
+  Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt
+  bck qrtr, bt h hs n d *wht*.  H fmbls thrgh hs rd sqzy chngprs nd
+  gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct
+  mnt.  Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s
+  hs prz. -RCHH
 
-   substitute: s/Perl/C...No substitution made.
+  substitute: s/Perl/C...No substitution made.
 
 =head2 Fiddling with the Perl stack from your C program
 
@@ -610,48 +616,48 @@ I<PerlPower()> that contains all the perlguts necessary to push the
 two arguments into I<expo()> and to pop the return value out.  Take a
 deep breath...
 
-    #include <EXTERN.h>
-    #include <perl.h>
+ #include <EXTERN.h>
+ #include <perl.h>
 
-    static PerlInterpreter *my_perl;
+ static PerlInterpreter *my_perl;
 
-    static void
-    PerlPower(int a, int b)
-    {
-      dSP;                            /* initialize stack pointer      */
-      ENTER;                          /* everything created after here */
-      SAVETMPS;                       /* ...is a temporary variable.   */
-      PUSHMARK(SP);                   /* remember the stack pointer    */
-      XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
-      XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
-      PUTBACK;                      /* make local stack pointer global */
-      call_pv("expo", G_SCALAR);      /* call the function             */
-      SPAGAIN;                        /* refresh stack pointer         */
-                                    /* pop the return value from stack */
-      printf ("%d to the %dth power is %d.\n", a, b, POPi);
-      PUTBACK;
-      FREETMPS;                       /* free that return value        */
-      LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
-    }
+ static void
+ PerlPower(int a, int b)
+ {
+   dSP;                            /* initialize stack pointer      */
+   ENTER;                          /* everything created after here */
+   SAVETMPS;                       /* ...is a temporary variable.   */
+   PUSHMARK(SP);                   /* remember the stack pointer    */
+   XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
+   XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
+   PUTBACK;                      /* make local stack pointer global */
+   call_pv("expo", G_SCALAR);      /* call the function             */
+   SPAGAIN;                        /* refresh stack pointer         */
+                                 /* pop the return value from stack */
+   printf ("%d to the %dth power is %d.\n", a, b, POPi);
+   PUTBACK;
+   FREETMPS;                       /* free that return value        */
+   LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
+ }
 
-    int main (int argc, char **argv, char **env)
-    {
-      char *my_argv[] = { "", "power.pl" };
+ int main (int argc, char **argv, char **env)
+ {
+   char *my_argv[] = { "", "power.pl" };
 
-      PERL_SYS_INIT3(&argc,&argv,&env);
-      my_perl = perl_alloc();
-      perl_construct( my_perl );
+   PERL_SYS_INIT3(&argc,&argv,&env);
+   my_perl = perl_alloc();
+   perl_construct( my_perl );
 
-      perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
-      PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
-      perl_run(my_perl);
+   perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
+   PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
+   perl_run(my_perl);
 
-      PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/
+   PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/
 
-      perl_destruct(my_perl);
-      perl_free(my_perl);
-      PERL_SYS_TERM();
-    }
+   perl_destruct(my_perl);
+   perl_free(my_perl);
+   PERL_SYS_TERM();
+ }
 
 
 
@@ -771,7 +777,9 @@ with L<perlfunc/my> whenever possible.
  #include <EXTERN.h>
  #include <perl.h>
 
- /* 1 = clean out filename's symbol table after each request, 0 = don't */
+ /* 1 = clean out filename's symbol table after each request,
+    0 = don't
+ */
  #ifndef DO_CLEAN
  #define DO_CLEAN 0
  #endif
@@ -795,7 +803,8 @@ with L<perlfunc/my> whenever possible.
      }
      perl_construct(my_perl);
 
-     PL_origalen = 1; /* don't let $0 assignment update the proctitle or embedding[0] */
+     PL_origalen = 1; /* don't let $0 assignment update the
+                         proctitle or embedding[0] */
      exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
      PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
      if(!exitstatus) {
@@ -805,7 +814,8 @@ with L<perlfunc/my> whenever possible.
               fgets(filename, BUFFER_SIZE, stdin)) {
 
             filename[strlen(filename)-1] = '\0'; /* strip \n */
-            /* call the subroutine, passing it the filename as an argument */
+            /* call the subroutine,
+                     passing it the filename as an argument */
             args[0] = filename;
             call_argv("Embed::Persistent::eval_file",
                            G_DISCARD | G_EVAL, args);
@@ -825,7 +835,8 @@ with L<perlfunc/my> whenever possible.
 
 Now compile:
 
- % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
+ % cc -o persistent persistent.c \
+        `perl -MExtUtils::Embed -e ccopts -e ldopts`
 
 Here's an example script file:
 
@@ -983,7 +994,8 @@ the more esoteric perl_clone()).
 
 Compile as usual:
 
- % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
+ % cc -o multiplicity multiplicity.c \
+  `perl -MExtUtils::Embed -e ccopts -e ldopts`
 
 Run it, Run it:
 
@@ -991,11 +1003,12 @@ Run it, Run it:
  Hi, I'm one_perl
  Hi, I'm two_perl
 
-=head2 Using Perl modules, which themselves use C libraries, from your C program
+=head2 Using Perl modules, which themselves use C libraries, from your C
+program
 
 If you've played with the examples above and tried to embed a script
-that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
-this probably happened:
+that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++
+library, this probably happened:
 
 
  Can't load module Socket, dynamic loading not available in this perl.
@@ -1011,9 +1024,9 @@ calling I<perl_parse()>, handing it NULL for the second argument:
 
  perl_parse(my_perl, NULL, argc, my_argv, NULL);
 
-That's where the glue code can be inserted to create the initial contact between
-Perl and linked C/C++ routines.  Let's take a look some pieces of I<perlmain.c>
-to see how Perl does this:
+That's where the glue code can be inserted to create the initial contact
+between Perl and linked C/C++ routines. Let's take a look some pieces of
+I<perlmain.c> to see how Perl does this:
 
  static void xs_init (pTHX);