Fixing issues listed in known_pod_issues.dat

p5pRT commented 11 years ago

Migrated from rt.perl.org#120093 (status was 'resolved')

Searchable as RT120093$

p5pRT commented 11 years ago

From @gideondsouza

Created by gideon@cpan.org

This is my first contribution to perl :)

As per the todo.pod I've gone through issues in known_pod_issues.dat and fixed all issues (27 in all) for perlembed.pod

Most of these had to do with extra spaces in verbatim sections. Some had to do with long code lines\, which I broke with a slash.

I've attached a patch in the attached commit. This patch only fixes perlembed.pod all in all\, I plan to send fixes for each pod as a separate patch.

Perl Info

``` Flags: category=docs severity=low Site configuration information for perl 5.12.4: Configured by _mdnsresponder at Wed Jun 20 13:42:53 PDT 2012. Summary of my perl5 (revision 5 version 12 subversion 4) configuration: Platform: osname=darwin, osvers=12.0, archname=darwin-thread-multi-2level uname='darwin b1026.apple.com 12.0 darwin kernel version 12.0.0: tue may 15 23:31:29 pdt 2012; root:xnu-2050.6.70~1release_x86_64 x86_64 ' config_args='-ds -e -Dprefix=/usr -Dccflags=-g -pipe -Dldflags= -Dman3ext=3pm -Duseithreads -Duseshrplib -Dinc_version_list=none -Dcc=clang' hint=recommended, useposix=true, d_sigaction=define useithreads=define, usemultiplicity=define useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef use64bitint=define, use64bitall=define, uselongdouble=undef usemymalloc=n, bincompat5005=undef Compiler: cc='clang', ccflags ='-arch i386 -arch x86_64 -g -pipe -fno-common -DPERL_DARWIN -fno-strict-aliasing -fstack-protector -I/usr/local/include', optimize='-Os', cppflags='-g -pipe -fno-common -DPERL_DARWIN -fno-strict-aliasing -fstack-protector -I/usr/local/include' ccversion='', gccversion='4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)', gccosandvers='' intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678 d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16 ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8 alignbytes=8, prototype=define Linker and Libraries: ld='clang -mmacosx-version-min=10.8', ldflags ='-arch i386 -arch x86_64 -fstack-protector -L/usr/local/lib' libpth=/usr/local/lib /usr/lib libs=-ldbm -ldl -lm -lutil -lc perllibs=-ldl -lm -lutil -lc libc=, so=dylib, useshrplib=true, libperl=libperl.dylib gnulibc_version='' Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=bundle, d_dlsymun=undef, ccdlflags=' ' cccdlflags=' ', lddlflags='-arch i386 -arch x86_64 -bundle -undefined dynamic_lookup -L/usr/local/lib -fstack-protector' Locally applied patches: /Library/Perl/Updates/ comes before system perl directories installprivlib and installarchlib points to the Updates directory @INC for perl 5.12.4: /Library/Perl/5.12/darwin-thread-multi-2level /Library/Perl/5.12 /Network/Library/Perl/5.12/darwin-thread-multi-2level /Network/Library/Perl/5.12 /Library/Perl/Updates/5.12.4/darwin-thread-multi-2level /Library/Perl/Updates/5.12.4 /System/Library/Perl/5.12/darwin-thread-multi-2level /System/Library/Perl/5.12 /System/Library/Perl/Extras/5.12/darwin-thread-multi-2level /System/Library/Perl/Extras/5.12 . Environment for perl 5.12.4: DYLD_LIBRARY_PATH (unset) HOME=/Users/gideon LANG (unset) LANGUAGE (unset) LC_CTYPE=UTF-8 LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=/Users/gideon/bin/Sencha/Cmd/3.0.2.288:/Users/gideon/perl5/perlbrew/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/Users/gideon/Documents/Coding/tools:/opt/X11/bin PERLBREW_BASHRC_VERSION=0.66 PERLBREW_HOME=/Users/gideon/.perlbrew PERLBREW_ROOT=/Users/gideon/perl5/perlbrew PERL_BADLANG (unset) SHELL=/bin/bash ```

p5pRT commented 11 years ago

From @gideondsouza

0001-Fixed-27-issues-in-perlembed.pod-reported-by-podchec.patch

```diff From df7758f285a4b508753433412ea9a79af0eaf00c Mon Sep 17 00:00:00 2001 From: Gideon Israel Dsouza Date: Thu, 3 Oct 2013 22:33:14 +0530 Subject: [PATCH] Fixed 27 issues in perlembed.pod reported by podcheck MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="------------1.7.12.4 (Apple Git-37)" This is a multi-part message in MIME format. --------------1.7.12.4 (Apple Git-37) Content-Type: text/plain; charset=UTF-8; format=fixed Content-Transfer-Encoding: 8bit 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. --- pod/perlembed.pod | 251 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 132 insertions(+), 119 deletions(-) --------------1.7.12.4 (Apple Git-37) Content-Type: text/x-patch; name="0001-Fixed-27-issues-in-perlembed.pod-reported-by-podchec.patch" Content-Transfer-Encoding: 8bit Content-Disposition: attachment; filename="0001-Fixed-27-issues-in-perlembed.pod-reported-by-podchec.patch" diff --git a/pod/perlembed.pod b/pod/perlembed.pod index 979c944..6e6852b 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -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 containing the essentials of embedding: - #include /* from the Perl distribution */ - #include /* from the Perl distribution */ + #include /* from the Perl distribution */ + #include /* 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 containing the essentials of embedding: perl_destruct(my_perl); perl_free(my_perl); PERL_SYS_TERM(); - } + } Notice that we don't use the C pointer. Normally handed to C as its final argument, C here is replaced by @@ -272,18 +272,18 @@ I). Those flags, and others, are discussed in L. I'll define the I subroutine in a file called I: - 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 @@ -315,41 +315,43 @@ extract variables for coercion into C types. The following program, I, executes three Perl strings, extracting an C from the first, a C from the second, and a C from the third. - #include - #include - - static PerlInterpreter *my_perl; - - 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_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 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))); - - perl_destruct(my_perl); - perl_free(my_perl); - PERL_SYS_TERM(); - } + #include + #include + + static PerlInterpreter *my_perl; + + 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_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 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))); + + perl_destruct(my_perl); + perl_free(my_perl); + PERL_SYS_TERM(); + } -All of those strange functions with I in their names help convert Perl scalars to C types. They're described in L and L. +All of those strange functions with I in their names help convert Perl +scalars to C types. They're described in L and L. If you compile and run I, you'll see the results of using I to create an C, I to create a C, and @@ -388,14 +390,15 @@ returns 1 if the string matches the pattern and 0 otherwise. Given a pointer to an C and an C<=~> operation (e.g., C or C), substitute() modifies the string -within the C as according to the operation, returning the number of substitutions -made. +within the C as according to the operation, returning the number of +substitutions made. SSize_t matches(SV *string, char *pattern, AV **matches); Given an C, a pattern, and a pointer to an empty C, matches() evaluates C<$string =~ $pattern> in a list context, and -fills in I with the array elements, returning the number of matches found. +fills in I with the array elements, returning the number of matches +found. Here's a sample program, I, that uses all three (long lines have been wrapped here): @@ -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 that contains all the perlguts necessary to push the two arguments into I and to pop the return value out. Take a deep breath... - #include - #include - - 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.*/ - } - - 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_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 ***/ - - perl_destruct(my_perl); - perl_free(my_perl); - PERL_SYS_TERM(); - } + #include + #include + + 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.*/ + } + + 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_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 ***/ + + perl_destruct(my_perl); + perl_free(my_perl); + PERL_SYS_TERM(); + } @@ -771,7 +777,9 @@ with L whenever possible. #include #include - /* 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 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 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 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 Is a Perl module (such as I) which itself uses a C or C++ library, -this probably happened: +that Is a Perl module (such as I) 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, 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 -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 to see how Perl does this: static void xs_init (pTHX); --------------1.7.12.4 (Apple Git-37)-- ```

Perl / perl5