perlguts: nits

This fixes a few typos, adds a few clarifications, and fixes too wide
verbatim lines

1 files changed, 94 insertions, 78 deletions

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 40b66ca960..9a4d6d4cad 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -59,7 +59,8 @@ the NUL) bytes of storage allocated, accessible via SvPVX.  In both cases
 the SV has value undef.
 
     SV *sv = newSV(0);   /* no storage allocated  */
-    SV *sv = newSV(10);  /* 10 (+1) bytes of uninitialised storage allocated  */
+    SV *sv = newSV(10);  /* 10 (+1) bytes of uninitialised storage
+                          * allocated */
 
 To change the value of an I<already-existing> SV, there are eight routines:
 
@@ -69,7 +70,8 @@ To change the value of an I<already-existing> SV, there are eight routines:
     void  sv_setpv(SV*, const char*);
     void  sv_setpvn(SV*, const char*, STRLEN)
     void  sv_setpvf(SV*, const char*, ...);
-    void  sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool *);
+    void  sv_vsetpvfn(SV*, const char*, STRLEN, va_list *,
+                                                    SV **, I32, bool *);
     void  sv_setsv(SV*, SV*);
 
 Notice that you can choose to specify the length of the string to be
@@ -77,7 +79,8 @@ assigned by using C<sv_setpvn>, C<newSVpvn>, or C<newSVpv>, or you may
 allow Perl to calculate the length by using C<sv_setpv> or by specifying
 0 as the second argument to C<newSVpv>.  Be warned, though, that Perl will
 determine the string's length by using C<strlen>, which depends on the
-string terminating with a NUL character.
+string terminating with a NUL character, and not otherwise containing
+NULs.
 
 The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
 formatted output becomes the value.
@@ -144,7 +147,7 @@ Perl to allocate more memory for your SV, you can use the macro
 which will determine if more memory needs to be allocated.  If so, it will
 call the function C<sv_grow>.  Note that C<SvGROW> can only increase, not
 decrease, the allocated memory of an SV and that it does not automatically
-add a byte for the a trailing NUL (perl's own string functions typically do
+add space for the trailing NUL byte (perl's own string functions typically do
 C<SvGROW(sv, len + 1)>).
 
 If you have an SV and want to know what kind of data Perl thinks is stored
@@ -173,7 +176,8 @@ you can use the following functions:
     void  sv_catpv(SV*, const char*);
     void  sv_catpvn(SV*, const char*, STRLEN);
     void  sv_catpvf(SV*, const char*, ...);
-    void  sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
+    void  sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **,
+                                                             I32, bool);
     void  sv_catsv(SV*, SV*);
 
 The first function calculates the length of the string to be appended by
@@ -416,7 +420,7 @@ Like their AV counterparts, C<hv_clear> deletes all the entries in the hash
 table but does not actually delete the hash table.  The C<hv_undef> deletes
 both the entries and the hash table itself.
 
-Perl keeps the actual data in linked list of structures with a typedef of HE.
+Perl keeps the actual data in a linked list of structures with a typedef of HE.
 These contain the actual key and value pointers (plus extra administrative
 overhead).  The key is a string pointer; the value is an C<SV*>.  However,
 once you have an C<HE*>, to get the actual key and value, use the routines
@@ -559,7 +563,7 @@ new undefined value using the C<newSV> function, for example:
 =head2 References
 
 References are a special type of scalar that point to other data types
-(including references).
+(including other references).
 
 To create a reference, use either of the following functions:
 
@@ -639,11 +643,12 @@ is non-null.
 
 	SV* sv_setref_pv(SV* rv, const char* classname, void* pv);
 
-The following function copies string into an SV whose reference is C<rv>.
+The following function copies a string into an SV whose reference is C<rv>.
 Set length to 0 to let Perl calculate the string length.  SV is blessed if
 C<classname> is non-null.
 
-	SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN length);
+    SV* sv_setref_pvn(SV* rv, const char* classname, char* pv,
+                                                         STRLEN length);
 
 The following function tests whether the SV is blessed into the specified
 class.  It does not check inheritance relationships.
@@ -916,7 +921,7 @@ Note this is current as of patchlevel 0, and could change at any time.
 
 Perl adds magic to an SV using the sv_magic function:
 
-    void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
+  void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
 
 The C<sv> argument is a pointer to the SV that is to acquire a new magical
 feature.
@@ -989,7 +994,8 @@ routine types:
     int  (*svt_clear)(SV* sv, MAGIC* mg);
     int  (*svt_free)(SV* sv, MAGIC* mg);
 
-    int  (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv, const char *name, I32 namlen);
+    int  (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv,
+                                          const char *name, I32 namlen);
     int  (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param);
     int  (*svt_local)(SV *nsv, MAGIC *mg);
 
@@ -999,17 +1005,18 @@ currently 32 types.  These different structures contain pointers to various
 routines that perform additional actions depending on which function is
 being called.
 
-    Function pointer    Action taken
-    ----------------    ------------
-    svt_get             Do something before the value of the SV is retrieved.
-    svt_set             Do something after the SV is assigned a value.
-    svt_len             Report on the SV's length.
-    svt_clear           Clear something the SV represents.
-    svt_free            Free any extra storage associated with the SV.
+   Function pointer    Action taken
+   ----------------    ------------
+   svt_get             Do something before the value of the SV is
+                       retrieved.
+   svt_set             Do something after the SV is assigned a value.
+   svt_len             Report on the SV's length.
+   svt_clear           Clear something the SV represents.
+   svt_free            Free any extra storage associated with the SV.
 
-    svt_copy            copy tied variable magic to a tied element
-    svt_dup             duplicate a magic structure during thread cloning
-    svt_local           copy magic to local value during 'local'
+   svt_copy            copy tied variable magic to a tied element
+   svt_dup             duplicate a magic structure during thread cloning
+   svt_local           copy magic to local value during 'local'
 
 For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
 to an C<mg_type> of C<PERL_MAGIC_sv>) contains:
@@ -1031,61 +1038,68 @@ to change.
 
 The current kinds of Magic Virtual Tables are:
 
-    mg_type
-    (old-style char and macro)   MGVTBL          Type of magic
-    --------------------------   ------          -------------
-    \0 PERL_MAGIC_sv             vtbl_sv         Special scalar variable
-    #  PERL_MAGIC_arylen         vtbl_arylen     Array length ($#ary)
-    %  PERL_MAGIC_rhash          (none)          extra data for restricted
-                                                 hashes
-    .  PERL_MAGIC_pos            vtbl_pos        pos() lvalue
-    :  PERL_MAGIC_symtab         (none)          extra data for symbol tables
-    <  PERL_MAGIC_backref        vtbl_backref    for weak ref data
-    @  PERL_MAGIC_arylen_p       (none)          to move arylen out of XPVAV
-    A  PERL_MAGIC_overload       vtbl_amagic     %OVERLOAD hash
-    a  PERL_MAGIC_overload_elem  vtbl_amagicelem %OVERLOAD hash element
-    B  PERL_MAGIC_bm             vtbl_regexp     Boyer-Moore 
-                                                 (fast string search)
-    c  PERL_MAGIC_overload_table vtbl_ovrld      Holds overload table 
-                                                 (AMT) on stash
-    D  PERL_MAGIC_regdata        vtbl_regdata    Regex match position data 
-                                                 (@+ and @- vars)
-    d  PERL_MAGIC_regdatum       vtbl_regdatum   Regex match position data
-                                                 element
-    E  PERL_MAGIC_env            vtbl_env        %ENV hash
-    e  PERL_MAGIC_envelem        vtbl_envelem    %ENV hash element
-    f  PERL_MAGIC_fm             vtbl_regdata    Formline ('compiled' format)
-    G  PERL_MAGIC_study          vtbl_regdata    study()ed string
-    g  PERL_MAGIC_regex_global   vtbl_mglob      m//g target
-    H  PERL_MAGIC_hints          vtbl_hints      %^H hash
-    h  PERL_MAGIC_hintselem      vtbl_hintselem  %^H hash element
-    I  PERL_MAGIC_isa            vtbl_isa        @ISA array
-    i  PERL_MAGIC_isaelem        vtbl_isaelem    @ISA array element
-    k  PERL_MAGIC_nkeys          vtbl_nkeys      scalar(keys()) lvalue
-    L  PERL_MAGIC_dbfile         (none)          Debugger %_<filename
-    l  PERL_MAGIC_dbline         vtbl_dbline     Debugger %_<filename element
-    N  PERL_MAGIC_shared         (none)          Shared between threads
-    n  PERL_MAGIC_shared_scalar  (none)          Shared between threads
-    o  PERL_MAGIC_collxfrm       vtbl_collxfrm   Locale transformation
-    P  PERL_MAGIC_tied           vtbl_pack       Tied array or hash
-    p  PERL_MAGIC_tiedelem       vtbl_packelem   Tied array or hash element
-    q  PERL_MAGIC_tiedscalar     vtbl_packelem   Tied scalar or handle
-    r  PERL_MAGIC_qr             vtbl_regexp     precompiled qr// regex
-    S  PERL_MAGIC_sig            (none)          %SIG hash
-    s  PERL_MAGIC_sigelem        vtbl_sigelem    %SIG hash element
-    t  PERL_MAGIC_taint          vtbl_taint      Taintedness
-    U  PERL_MAGIC_uvar           vtbl_uvar       Available for use by extensions
-    u  PERL_MAGIC_uvar_elem      (none)          Reserved for use by extensions
-    V  PERL_MAGIC_vstring        (none)          SV was vstring literal
-    v  PERL_MAGIC_vec            vtbl_vec        vec() lvalue
-    w  PERL_MAGIC_utf8           vtbl_utf8       Cached UTF-8 information
-    x  PERL_MAGIC_substr         vtbl_substr     substr() lvalue
-    y  PERL_MAGIC_defelem        vtbl_defelem    Shadow "foreach" iterator
-                                                 variable / smart parameter
-                                                 vivification
-    ]  PERL_MAGIC_checkcall      (none)          inlining/mutation of call to
-                                                 this CV
-    ~  PERL_MAGIC_ext            (none)          Available for use by extensions
+ mg_type
+ (old-style char and macro)   MGVTBL          Type of magic
+ --------------------------   ------          -------------
+ \0 PERL_MAGIC_sv             vtbl_sv         Special scalar variable
+ #  PERL_MAGIC_arylen         vtbl_arylen     Array length ($#ary)
+ %  PERL_MAGIC_rhash          (none)          extra data for restricted
+                                              hashes
+ .  PERL_MAGIC_pos            vtbl_pos        pos() lvalue
+ :  PERL_MAGIC_symtab         (none)          extra data for symbol
+                                              tables
+ <  PERL_MAGIC_backref        vtbl_backref    for weak ref data
+ @  PERL_MAGIC_arylen_p       (none)          to move arylen out of
+                                              XPVAV
+ A  PERL_MAGIC_overload       vtbl_amagic     %OVERLOAD hash
+ a  PERL_MAGIC_overload_elem  vtbl_amagicelem %OVERLOAD hash element
+ B  PERL_MAGIC_bm             vtbl_regexp     Boyer-Moore 
+                                              (fast string search)
+ c  PERL_MAGIC_overload_table vtbl_ovrld      Holds overload table 
+                                              (AMT) on stash
+ D  PERL_MAGIC_regdata        vtbl_regdata    Regex match position data 
+                                              (@+ and @- vars)
+ d  PERL_MAGIC_regdatum       vtbl_regdatum   Regex match position data
+                                              element
+ E  PERL_MAGIC_env            vtbl_env        %ENV hash
+ e  PERL_MAGIC_envelem        vtbl_envelem    %ENV hash element
+ f  PERL_MAGIC_fm             vtbl_regdata    Formline ('compiled'
+                                              format)
+ G  PERL_MAGIC_study          vtbl_regdata    study()ed string
+ g  PERL_MAGIC_regex_global   vtbl_mglob      m//g target
+ H  PERL_MAGIC_hints          vtbl_hints      %^H hash
+ h  PERL_MAGIC_hintselem      vtbl_hintselem  %^H hash element
+ I  PERL_MAGIC_isa            vtbl_isa        @ISA array
+ i  PERL_MAGIC_isaelem        vtbl_isaelem    @ISA array element
+ k  PERL_MAGIC_nkeys          vtbl_nkeys      scalar(keys()) lvalue
+ L  PERL_MAGIC_dbfile         (none)          Debugger %_<filename
+ l  PERL_MAGIC_dbline         vtbl_dbline     Debugger %_<filename
+                                              element
+ N  PERL_MAGIC_shared         (none)          Shared between threads
+ n  PERL_MAGIC_shared_scalar  (none)          Shared between threads
+ o  PERL_MAGIC_collxfrm       vtbl_collxfrm   Locale transformation
+ P  PERL_MAGIC_tied           vtbl_pack       Tied array or hash
+ p  PERL_MAGIC_tiedelem       vtbl_packelem   Tied array or hash element
+ q  PERL_MAGIC_tiedscalar     vtbl_packelem   Tied scalar or handle
+ r  PERL_MAGIC_qr             vtbl_regexp     precompiled qr// regex
+ S  PERL_MAGIC_sig            (none)          %SIG hash
+ s  PERL_MAGIC_sigelem        vtbl_sigelem    %SIG hash element
+ t  PERL_MAGIC_taint          vtbl_taint      Taintedness
+ U  PERL_MAGIC_uvar           vtbl_uvar       Available for use by
+                                              extensions
+ u  PERL_MAGIC_uvar_elem      (none)          Reserved for use by
+                                              extensions
+ V  PERL_MAGIC_vstring        (none)          SV was vstring literal
+ v  PERL_MAGIC_vec            vtbl_vec        vec() lvalue
+ w  PERL_MAGIC_utf8           vtbl_utf8       Cached UTF-8 information
+ x  PERL_MAGIC_substr         vtbl_substr     substr() lvalue
+ y  PERL_MAGIC_defelem        vtbl_defelem    Shadow "foreach" iterator
+                                              variable / smart parameter
+                                              vivification
+ ]  PERL_MAGIC_checkcall      (none)          inlining/mutation of call
+                                              to this CV
+ ~  PERL_MAGIC_ext            (none)          Available for use by
+                                              extensions
 
 
 When an uppercase and lowercase letter both exist in the table, then the
@@ -1172,7 +1186,8 @@ since their implementation handles 'get' magic.
 
 =head2 Finding Magic
 
-    MAGIC *mg_find(SV *sv, int type); /* Finds the magic pointer of that type */
+    MAGIC *mg_find(SV *sv, int type); /* Finds the magic pointer of that
+                                       * type */
 
 This routine returns a pointer to a C<MAGIC> structure stored in the SV.
 If the SV does not have that magical feature, C<NULL> is returned. If the
@@ -1475,7 +1490,8 @@ L</Reference Counts and Mortality>):
     PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
     PUSHs(sv_2mortal(newSVnv(a_double)))
     PUSHs(sv_2mortal(newSVpv("Some String",0)))
-    /* Although the last example is better written as the more efficient: */
+    /* Although the last example is better written as the more
+     * efficient: */
     PUSHs(newSVpvs_flags("Some String", SVs_TEMP))
 
 And now the Perl program calling C<tzname>, the two values will be assigned