Integrate:

[ 25111]
Subject: [patch hv.h doc] HvNAME
From: Stas Bekman <stas@stason.org>
Date: Fri, 08 Jul 2005 13:52:13 +0300
Message-ID: <42CE5ADD.3020003@stason.org>

Subject: Re: [patch hv.h doc] HvNAME
From: Nicholas Clark <nick@ccl4.org>
Date: Sat, 9 Jul 2005 15:23:51 +0100
Message-ID: <20050709142351.GT15833@plum.flirble.org>

[ 26739]
Subject: Re: [perl #38181] Default IO Layer is ignored in 3-argument open call
From: SADAHIRO Tomoyuki <bqw10602@nifty.com>
Date: Mon, 09 Jan 2006 01:29:30 +0900
Message-Id: <20060109012103.F20A.BQW10602@nifty.com>

[ 26749]
Subject:  [PATCH] identifiers always in main (was: defining a _ function breaks File::Find)
From:  Xavier Noria <fxn@hashref.com>
Date:  Sun, 23 Oct 2005 09:47:37 +0200
Message-Id:  <D3867DED-313E-4D39-A85F-1178FE7F7A5E@hashref.com>

clarify which variables are always forced into main::

[ 26750]
Revert change 26749

[ 26756]
Subject: [patch] more about embed.fnc in perlguts
From: Jim Cromie <jim.cromie@gmail.com>
Date: Sun, 08 Jan 2006 11:35:46 -0700
Message-ID: <43C15B82.9090309@gmail.com>

(with a few nits)

[ 26762]
Remove stale date.
p4raw-link: @26762 on //depot/perl: b77de8c7a7a97830b8f0702cd830d615db2a1523
p4raw-link: @26756 on //depot/perl: 1aa6ea502f811472fe5fb23153ef6b09b3f470ec
p4raw-link: @26750 on //depot/perl: 1fcb18de6aa4bd3b565067cad38df0ca202f89d0
p4raw-link: @26749 on //depot/perl: 09e04a353e352e671b21e072d112d97d0ff3b125
p4raw-link: @26739 on //depot/perl: 6d5e88a0347ef2c76da06c6ba6c6643e226cbccf
p4raw-link: @25111 on //depot/perl: 9282b5fd39e8a661d98cf18601205217ba4caf3d

p4raw-id: //depot/maint-5.8/perl@26775
p4raw-integrated: from //depot/perl@26771 'copy in' pod/perlembed.pod
	(@21897..) 'merge in' lib/open.pm (@25925..) pod/perlfunc.pod
	(@26571..) pod/perlguts.pod (@26735..)
p4raw-integrated: from //depot/perl@26756 'merge in' embed.fnc
	(@26530..)
p4raw-integrated: from //depot/perl@26749 'edit in' pod/perlvar.pod
	(@25780..)
p4raw-integrated: from //depot/perl@25111 'merge in' hv.h (@24895..)

diff --git a/embed.fnc b/embed.fnc
index 7e288fa..f588aa3 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -11,7 +11,7 @@
 :      d               function has documentation with its source
 :      s               static function, should have an S_ prefix in
 :                      source file; for macros (m), suffix the usage
-:                      example with a semicolon
+:                      example with a semicolon
 :      n               has no implicit interpreter/thread context argument
 :      p               function has a Perl_ prefix
 :      f               function takes printf style format string, varargs
@@ -28,6 +28,7 @@
 :      R               Return value must not be ignored.
 :      P               pure function: no effects except the return value;
 :                      return value depends only on parms and/or globals
+: (see also L<perlguts/Internal Functions> for those flags.)
 :
 : Pointer parameters that must not be passed NULLs should be prefixed with NN.
 :

diff --git a/hv.h b/hv.h
index 28fa300..70a68e9 100644 (file)
--- a/hv.h
+++ b/hv.h
@@ -124,7 +124,8 @@ Null HV pointer.
 =head1 Hash Manipulation Functions
 
 =for apidoc Am|char*|HvNAME|HV* stash
-Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
+Returns the package name of a stash, or NULL if C<stash> isn't a stash.
+See C<SvSTASH>, C<CvSTASH>.
 
 =for apidoc Am|void*|HeKEY|HE* he
 Returns the actual pointer stored in the key slot of the hash entry. The

diff --git a/lib/open.pm b/lib/open.pm
index 960de77..673f617 100644 (file)
--- a/lib/open.pm
+++ b/lib/open.pm
@@ -168,9 +168,8 @@ The C<open> pragma serves as one of the interfaces to declare default
 "layers" (also known as "disciplines") for all I/O. Any two-argument
 open(), readpipe() (aka qx//) and similar operators found within the
 lexical scope of this pragma will use the declared defaults.
-Three-argument opens are not affected by this pragma since there you
-(can) explicitly specify the layers and are supposed to know what you
-are doing.
+Even three-argument opens may be affected by this pragma
+when they don't specify IO layers in MODE.
 
 With the C<IN> subpragma you can declare the default layers
 of input streams, and with the C<OUT> subpragma you can declare
@@ -179,7 +178,7 @@ you can control both input and output streams simultaneously.
 
 If you have a legacy encoding, you can use the C<:encoding(...)> tag.
 
-if you want to set your encoding layers based on your
+If you want to set your encoding layers based on your
 locale environment variables, you can use the C<:locale> tag.
 For example:
 

diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 2a31500..38211e5 100644 (file)
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -1118,8 +1118,6 @@ Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
 have used this model for Oracle, Netscape and Internet Information
 Server Perl plugins.
 
-July 22, 1998
-
 =head1 COPYRIGHT
 
 Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant.  All

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 78da295..7e64505 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3065,9 +3065,9 @@ L<PerlIO> for more details). For example
   open(FH, "<:utf8", "file")
 
 will open the UTF-8 encoded file containing Unicode characters,
-see L<perluniintro>. (Note that if layers are specified in the
-three-arg form then default layers set by the C<open> pragma are
-ignored.)
+see L<perluniintro>. Note that if layers are specified in the
+three-arg form then default layers stored in ${^OPEN} (see L<perlvar>;
+usually set by the B<open> pragma or the switch B<-CioD>) are ignored.
 
 Open returns nonzero upon success, the undefined value otherwise.  If
 the C<open> involved a pipe, the return value happens to be the pid of

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 52fb9d5..0f62f1c 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -126,11 +126,11 @@ Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len),
 len);>. It might work with your compiler, but it won't work for everyone.
 Break this sort of statement up into separate assignments:
 
-       SV *s;
-       STRLEN len;
-       char * ptr;
-       ptr = SvPV(s, len);
-       foo(ptr, len);
+    SV *s;
+    STRLEN len;
+    char * ptr;
+    ptr = SvPV(s, len);
+    foo(ptr, len);
 
 If you want to know if the scalar value is TRUE, you can use:
 
@@ -2135,16 +2135,18 @@ after that are the arguments. The first column is a set of flags:
 
 =item A
 
-This function is a part of the public API.
+This function is a part of the public API. All such functions should also
+have 'd', very few do not.
 
 =item p
 
-This function has a C<Perl_> prefix; i.e. it is defined as C<Perl_av_fetch>
+This function has a C<Perl_> prefix; i.e. it is defined as
+C<Perl_av_fetch>.
 
 =item d
 
 This function has documentation using the C<apidoc> feature which we'll
-look at in a second.
+look at in a second.  Some functions have 'd' but not 'A'; docs are good.
 
 =back
 
@@ -2154,12 +2156,13 @@ Other available flags are:
 
 =item s
 
-This is a static function and is defined as C<S_whatever>, and usually
-called within the sources as C<whatever(...)>.
+This is a static function and is defined as C<STATIC S_whatever>, and
+usually called within the sources as C<whatever(...)>.
 
 =item n
 
-This does not use C<aTHX_> and C<pTHX> to pass interpreter context. (See
+This does not need a interpreter context, so the definition has no
+C<pTHX>, and it follows that callers don't use C<aTHX>.  (See
 L<perlguts/Background and PERL_IMPLICIT_CONTEXT>.)
 
 =item r
@@ -2204,6 +2207,10 @@ This function is visible to extensions included in the Perl core.
 Binary backward compatibility; this function is a macro but also has
 a C<Perl_> implementation (which is exported).
 
+=item others
+
+See the comments at the top of C<embed.fnc> for others.
+
 =back
 
 If you edit F<embed.pl> or F<embed.fnc>, you will need to run
@@ -2514,7 +2521,7 @@ define your own ops. This is primarily to allow the building of
 interpreters for other languages in the Perl core, but it also allows
 optimizations through the creation of "macro-ops" (ops which perform the
 functions of multiple ops which are usually executed together, such as
-C<gvsv, gvsv, add>.) 
+C<gvsv, gvsv, add>.)
 
 This feature is implemented as a new op type, C<OP_CUSTOM>. The Perl
 core does not "know" anything special about this op type, and so it will