Some POD patches for PerlIO and PerlIO::var
authorLanning, Scott <lannings@who.int>
Sun, 25 Jan 2009 17:55:25 +0000 (18:55 +0100)
committerRafael Garcia-Suarez <rgarciasuarez@gmail.com>
Sun, 25 Jan 2009 17:55:25 +0000 (18:55 +0100)
Mostly just grammar.

ext/PerlIO/via/via.pm
lib/PerlIO.pm

index 6ff804e..66aa974 100644 (file)
@@ -60,66 +60,65 @@ some level of "compatibility" with TIEHANDLE classes it is passed last.
 
 =over 4
 
-=item $class->PUSHED([$mode[,$fh]])
+=item $class->PUSHED([$mode,[$fh]])
 
 Should return an object or the class, or -1 on failure.  (Compare
 TIEHANDLE.)  The arguments are an optional mode string ("r", "w",
 "w+", ...) and a filehandle for the PerlIO layer below.  Mandatory.
 
-When layer is pushed as part of an C<open> call, C<PUSHED> will be called
-I<before> the actual open occurs whether than be via C<OPEN>, C<SYSOPEN>,
-C<FDOPEN> or by letting lower layer do the open.
+When the layer is pushed as part of an C<open> call, C<PUSHED> will be called
+I<before> the actual open occurs, whether that be via C<OPEN>, C<SYSOPEN>,
+C<FDOPEN> or by letting lower layer do the open.
 
 =item $obj->POPPED([$fh])
 
-Optional - layer is about to be removed.
+Optional - called when the layer is about to be removed.
 
 =item $obj->UTF8($bellowFlag,[$fh])
 
 Optional - if present it will be called immediately after PUSHED has
-returned. It should return true value if the layer expects data to be
-UTF-8 encoded. If it returns true result is as if caller had done
+returned. It should return true value if the layer expects data to be
+UTF-8 encoded. If it returns true, the result is as if the caller had done
 
    ":via(YourClass):utf8"
 
-If not present of it it returns false, then stream is left with
-flag clear.
+If not present or if it returns false, then the stream is left with
+the UTF-8 flag clear.
 The I<$bellowFlag> argument will be true if there is a layer below
 and that layer was expecting UTF-8.
 
+=item $obj->OPEN($path,$mode,[$fh])
 
-=item $obj->OPEN($path,$mode[,$fh])
-
-Optional - if not present lower layer does open.
-If present called for normal opens after layer is pushed.
+Optional - if not present a lower layer does the open.
+If present, called for normal opens after the layer is pushed.
 This function is subject to change as there is no easy way
-to get lower layer to do open and then regain control.
+to get a lower layer to do the open and then regain control.
 
-=item $obj->BINMODE([,$fh])
+=item $obj->BINMODE([$fh])
 
-Optional - if not available layer is popped on binmode($fh) or when C<:raw>
-is pushed. If present it should return 0 on success -1 on error and undef
+Optional - if not present the layer is popped on binmode($fh) or when C<:raw>
+is pushed. If present it should return 0 on success, -1 on error, or undef
 to pop the layer.
 
-=item $obj->FDOPEN($fd[,$fh])
+=item $obj->FDOPEN($fd,[$fh])
 
-Optional - if not present lower layer does open.
-If present called for opens which pass a numeric file
-descriptor after layer is pushed.
+Optional - if not present a lower layer does the open.
+If present, called after the layer is pushed for opens which pass
+a numeric file descriptor.
 This function is subject to change as there is no easy way
-to get lower layer to do open and then regain control.
+to get a lower layer to do the open and then regain control.
 
-=item $obj->SYSOPEN($path,$imode,$perm,[,$fh])
+=item $obj->SYSOPEN($path,$imode,$perm,[$fh])
 
-Optional - if not present lower layer does open.
-If present called for sysopen style opens which pass a numeric mode
-and permissions after layer is pushed.
+Optional - if not present a lower layer does the open.
+If present, called after the layer is pushed for sysopen style opens
+which pass a numeric mode and permissions.
 This function is subject to change as there is no easy way
-to get lower layer to do open and then regain control.
+to get a lower layer to do the open and then regain control.
 
 =item $obj->FILENO($fh)
 
-Returns a numeric value for Unix-like file descriptor. Return -1 if
+Returns a numeric value for a Unix-like file descriptor. Returns -1 if
 there isn't one.  Optional.  Default is fileno($fh).
 
 =item $obj->READ($buffer,$len,$fh)
@@ -129,12 +128,12 @@ equal to $len).  Optional.  Default is to use FILL instead.
 
 =item $obj->WRITE($buffer,$fh)
 
-Returns the number of octets from buffer that have been successfully written.
+Returns the number of octets from $buffer that have been successfully written.
 
 =item $obj->FILL($fh)
 
 Should return a string to be placed in the buffer.  Optional. If not
-provided must provide READ or reject handles open for reading in
+provided, must provide READ or reject handles open for reading in
 PUSHED.
 
 =item $obj->CLOSE($fh)
@@ -155,7 +154,7 @@ Optional.  Default to be determined.
 
 =item $obj->UNREAD($buffer,$fh)
 
-Returns the number of octets from buffer that have been successfully
+Returns the number of octets from $buffer that have been successfully
 saved to be returned on future FILL/READ calls.  Optional.  Default is
 to push data into a temporary layer above this one.
 
@@ -179,7 +178,7 @@ to signal error (die?) is worked out.
 
 =item $obj->EOF($fh)
 
-Optional. Returns end-of-file state. Default is function of return
+Optional. Returns end-of-file state. Default is a function of the return
 value of FILL or READ.
 
 =back
@@ -188,7 +187,7 @@ value of FILL or READ.
 
 Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers
 implemented in Perl.  To give you an idea how simple the implementation of
-a PerlIO layer can look, as simple example is included here.
+a PerlIO layer can look, a simple example is included here.
 
 =head2 Example - a Hexadecimal Handle
 
@@ -229,7 +228,7 @@ Given the following module, PerlIO::via::Hex :
     1;
 
 The following code opens up an output handle that will convert any
-output to hexadecimal dump of the output bytes: for example "A" will
+output to hexadecimal dump of the output bytes: for example "A" will
 be converted to "41" (on ASCII-based machines, on EBCDIC platforms
 the "A" will become "c1")
 
index 1b80507..980df2c 100644 (file)
@@ -71,7 +71,7 @@ UNIX/POSIX numeric file descriptor calls
 
 Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc.  Note
 that as this is "real" stdio it will ignore any layers beneath it and
-got straight to the operating system via the C library as usual.
+go straight to the operating system via the C library as usual.
 
 =item :perlio
 
@@ -108,16 +108,16 @@ Based on the C<:perlio> layer.
 =item :mmap
 
 A layer which implements "reading" of files by using C<mmap()> to
-make (whole) file appear in the process's address space, and then
+make (whole) file appear in the process's address space, and then
 using that as PerlIO's "buffer". This I<may> be faster in certain
 circumstances for large files, and may result in less physical memory
 use when multiple processes are reading the same file.
 
 Files which are not C<mmap()>-able revert to behaving like the C<:perlio>
-layer. Writes also behave like C<:perlio> layer as C<mmap()> for write
+layer. Writes also behave like the C<:perlio> layer, as C<mmap()> for write
 needs extra house-keeping (to extend the file) which negates any advantage.
 
-The C<:mmap> layer will not exist if platform does not support C<mmap()>.
+The C<:mmap> layer will not exist if the platform does not support C<mmap()>.
 
 =item :utf8
 
@@ -140,38 +140,38 @@ and then read it back in.
        close(F);
 
 Note that this layer does not validate byte sequences. For reading
-input, using C<:encoding(utf8)> instead of bare C<:utf8>, is strongly
+input, using C<:encoding(utf8)> instead of bare C<:utf8> is strongly
 recommended.
 
 =item :bytes
 
-This is the inverse of C<:utf8> layer. It turns off the flag
+This is the inverse of the C<:utf8> layer. It turns off the flag
 on the layer below so that data read from it is considered to
-be "octets" i.e. characters in range 0..255 only. Likewise
+be "octets" i.e. characters in the range 0..255 only. Likewise
 on output perl will warn if a "wide" character is written
 to a such a stream.
 
 =item :raw
 
 The C<:raw> layer is I<defined> as being identical to calling
-C<binmode($fh)> - the stream is made suitable for passing binary data
+C<binmode($fh)> - the stream is made suitable for passing binary data,
 i.e. each byte is passed as-is. The stream will still be
 buffered.
 
 In Perl 5.6 and some books the C<:raw> layer (previously sometimes also
 referred to as a "discipline") is documented as the inverse of the
 C<:crlf> layer. That is no longer the case - other layers which would
-alter binary nature of the stream are also disabled.  If you want UNIX
+alter the binary nature of the stream are also disabled.  If you want UNIX
 line endings on a platform that normally does CRLF translation, but still
-want UTF-8 or encoding defaults the appropriate thing to do is to add
-C<:perlio> to PERLIO environment variable.
+want UTF-8 or encoding defaults, the appropriate thing to do is to add
+C<:perlio> to the PERLIO environment variable.
 
 The implementation of C<:raw> is as a pseudo-layer which when "pushed"
 pops itself and then any layers which do not declare themselves as suitable
 for binary data. (Undoing :utf8 and :crlf are implemented by clearing
 flags rather than popping layers but that is an implementation detail.)
 
-As a consequence of the fact that C<:raw> normally pops layers
+As a consequence of the fact that C<:raw> normally pops layers,
 it usually only makes sense to have it as the only or first element in
 a layer specification.  When used as the first element it provides
 a known base on which to build e.g.
@@ -198,8 +198,8 @@ A more elegant (and safer) interface is needed.
 
 =item :win32
 
-On Win32 platforms this I<experimental> layer uses native "handle" IO
-rather than unix-like numeric file descriptor layer. Known to be
+On Win32 platforms this I<experimental> layer uses the native "handle" IO
+rather than the unix-like numeric file descriptor layer. Known to be
 buggy as of perl 5.8.2.
 
 =back
@@ -215,7 +215,7 @@ in Perl using the latter) come with the Perl distribution.
 =item :encoding
 
 Use C<:encoding(ENCODING)> either in open() or binmode() to install
-a layer that does transparently character set and encoding transformations,
+a layer that transparently does character set and encoding transformations,
 for example from Shift-JIS to Unicode.  Note that under C<stdio>
 an C<:encoding> also enables C<:utf8>.  See L<PerlIO::encoding>
 for more information.
@@ -236,10 +236,10 @@ To get a binary stream an alternate method is to use:
     open($fh,"whatever")
     binmode($fh);
 
-this has advantage of being backward compatible with how such things have
+this has the advantage of being backward compatible with how such things have
 had to be coded on some platforms for years.
 
-To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>)
+To get an unbuffered stream specify an unbuffered layer (e.g. C<:unix>)
 in the open call:
 
     open($fh,"<:unix",$path)
@@ -254,7 +254,7 @@ translation for text files then the default layers are :
 (The low level "unix" layer may be replaced by a platform specific low
 level layer.)
 
-Otherwise if C<Configure> found out how to do "fast" IO using system's
+Otherwise if C<Configure> found out how to do "fast" IO using the system's
 stdio, then the default layers are:
 
   unix stdio
@@ -275,7 +275,7 @@ This can be used to see the effect of/bugs in the various layers e.g.
   PERLIO=stdio  ./perl harness
   PERLIO=perlio ./perl harness
 
-For the various value of PERLIO see L<perlrun/PERLIO>.
+For the various values of PERLIO see L<perlrun/PERLIO>.
 
 =head2 Querying the layers of filehandles
 
@@ -289,7 +289,7 @@ system and on the Perl version, and both the compile-time and
 runtime configurations of Perl.
 
 The following table summarizes the default layers on UNIX-like and
-DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>:
+DOS-like platforms and depending on the setting of C<$ENV{PERLIO}>:
 
  PERLIO     UNIX-like                   DOS-like
  ------     ---------                   --------
@@ -301,8 +301,8 @@ DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>:
  # [1] "stdio" if Configure found out how to do "fast stdio" (depends
  # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio"
 
-By default the layers from the input side of the filehandle is
-returned, to get the output side use the optional C<output> argument:
+By default the layers from the input side of the filehandle are
+returned; to get the output side, use the optional C<output> argument:
 
    my @layers = PerlIO::get_layers($fh, output => 1);
 
@@ -318,10 +318,10 @@ You are supposed to use open() and binmode() to manipulate the stack.
 
 B<Implementation details follow, please close your eyes.>
 
-The arguments to layers are by default returned in parenthesis after
+The arguments to layers are by default returned in parentheses after
 the name of the layer, and certain layers (like C<utf8>) are not real
-layers but instead flags on real layers: to get all of these returned
-separately use the optional C<details> argument:
+layers but instead flags on real layers; to get all of these returned
+separately, use the optional C<details> argument:
 
    my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);