Change 14892 by jhi@alpha on 2002/02/27 13:41:14
Subject: Re: [PATCH @14870] long C<=item>s and other pod->man->troff problems
From: Robin Barker <[EMAIL PROTECTED]>
Date: Wed, 27 Feb 2002 12:25:30 GMT
Message-Id: <[EMAIL PROTECTED]>
Affected files ...
.... //depot/perl/README.cygwin#19 edit
.... //depot/perl/README.os2#25 edit
.... //depot/perl/ext/Time/HiRes/HiRes.pm#11 edit
.... //depot/perl/lib/CGI.pm#33 edit
.... //depot/perl/lib/Math/BigInt.pm#36 edit
.... //depot/perl/pod/perl561delta.pod#6 edit
.... //depot/perl/pod/perliol.pod#12 edit
.... //depot/perl/pod/perlunicode.pod#75 edit
.... //depot/perl/pod/perluniintro.pod#21 edit
Differences ...
==== //depot/perl/README.cygwin#19 (text) ====
Index: perl/README.cygwin
--- perl/README.cygwin.~1~ Wed Feb 27 06:45:06 2002
+++ perl/README.cygwin Wed Feb 27 06:45:06 2002
@@ -199,7 +199,8 @@
I<gcc> supports long doubles (12 bytes). However, several additional
long double math functions are necessary to use them within Perl
-(I<{atan2,cos,exp,floor,fmod,frexp,isnan,log,modf,pow,sin,sqrt}l,strtold>).
+(I<{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l,
+strtold>).
These are B<not> yet available with Cygwin.
=item * C<-Dusethreads>
==== //depot/perl/README.os2#25 (text) ====
Index: perl/README.os2
--- perl/README.os2.~1~ Wed Feb 27 06:45:06 2002
+++ perl/README.os2 Wed Feb 27 06:45:06 2002
@@ -733,7 +733,7 @@
C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
or, alternately, prebuilt info pages.
-=head2 F<.PDF> files
+=head2 F<PDF> files
for C<Acrobat> are available on CPAN (for slightly old version of
perl).
==== //depot/perl/ext/Time/HiRes/HiRes.pm#11 (text) ====
Index: perl/ext/Time/HiRes/HiRes.pm
--- perl/ext/Time/HiRes/HiRes.pm.~1~ Wed Feb 27 06:45:06 2002
+++ perl/ext/Time/HiRes/HiRes.pm Wed Feb 27 06:45:06 2002
@@ -117,7 +117,7 @@
=item tv_interval
-S<tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )>
+C<tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )>
Returns the floating seconds between the two times, which should have
been returned by gettimeofday(). If the second argument is omitted,
@@ -166,7 +166,7 @@
=item setitimer
-S<setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )>
+C<setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )>
Start up an interval timer: after a certain time, a signal is arrives,
and more may keep arriving at certain intervals. To disable a timer,
==== //depot/perl/lib/CGI.pm#33 (text) ====
Index: perl/lib/CGI.pm
--- perl/lib/CGI.pm.~1~ Wed Feb 27 06:45:06 2002
+++ perl/lib/CGI.pm Wed Feb 27 06:45:06 2002
@@ -5759,6 +5759,7 @@
The second argument (-src) is also required and specifies the URL
=item 3.
+
The third option (-align, optional) is an alignment type, and may be
TOP, BOTTOM or MIDDLE
@@ -6192,6 +6193,7 @@
if the former is unavailable.
=item B<script_name()>
+
Return the script name as a partial URL, for self-refering
scripts.
==== //depot/perl/lib/Math/BigInt.pm#36 (text) ====
Index: perl/lib/Math/BigInt.pm
--- perl/lib/Math/BigInt.pm.~1~ Wed Feb 27 06:45:06 2002
+++ perl/lib/Math/BigInt.pm Wed Feb 27 06:45:06 2002
@@ -2655,7 +2655,8 @@
$x->bone(); # +1
$x->bone('-'); # -1
-=head2
is_one()/is_zero()/is_nan()/is_positive()/is_negative()/is_inf()/is_odd()/is_even()/is_int()
+=head2 is_one() / is_zero() / is_nan() / is_positive() / is_negative() /
+is_inf() / is_odd() / is_even() / is_int()
$x->is_zero(); # true if arg is +0
$x->is_nan(); # true if arg is NaN
==== //depot/perl/pod/perl561delta.pod#6 (text) ====
Index: perl/pod/perl561delta.pod
--- perl/pod/perl561delta.pod.~1~ Wed Feb 27 06:45:06 2002
+++ perl/pod/perl561delta.pod Wed Feb 27 06:45:06 2002
@@ -3444,7 +3444,9 @@
=over
-=item 64-bit builds
+=item
+
+64-bit builds
Subtest #15 of lib/b.t may fail under 64-bit builds on platforms such
as HP-UX PA64 and Linux IA64. The issue is still being investigated.
@@ -3457,21 +3459,27 @@
Note that 64-bit support is still experimental.
-=item Failure of Thread tests
+=item
+
+Failure of Thread tests
The subtests 19 and 20 of lib/thr5005.t test are known to fail due to
fundamental problems in the 5.005 threading implementation. These are
not new failures--Perl 5.005_0x has the same bugs, but didn't have these
tests. (Note that support for 5.005-style threading remains experimental.)
-=item NEXTSTEP 3.3 POSIX test failure
+=item
+
+NEXTSTEP 3.3 POSIX test failure
In NEXTSTEP 3.3p2 the implementation of the strftime(3) in the
operating system libraries is buggy: the %j format numbers the days of
a month starting from zero, which, while being logical to programmers,
will cause the subtests 19 to 27 of the lib/posix test may fail.
-=item Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc
+=item
+
+Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc
If compiled with gcc 2.95 the lib/sdbm test will fail (dump core).
The cure is to use the vendor cc, it comes with the operating system
==== //depot/perl/pod/perliol.pod#12 (text) ====
Index: perl/pod/perliol.pod
--- perl/pod/perliol.pod.~1~ Wed Feb 27 06:45:06 2002
+++ perl/pod/perliol.pod Wed Feb 27 06:45:06 2002
@@ -322,7 +322,9 @@
=over 4
-=item char * name;
+=item name
+
+ char * name;
The name of the layer whose open() method Perl should invoke on
open(). For example if the layer is called APR, you will call:
@@ -332,13 +334,17 @@
and Perl knows that it has to invoke the PerlIOAPR_open() method
implemented by the APR layer.
-=item Size_t size;
+=item size
+
+ Size_t size;
The size of the per-instance data structure, e.g.:
sizeof(PerlIOAPR)
-=item IV kind;
+=item kind
+
+ IV kind;
XXX: explain all the available flags here
@@ -360,7 +366,9 @@
=back
-=item IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
+=item Pushed
+
+ IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
The only absolutely mandatory method. Called when the layer is pushed
onto the stack. The C<mode> argument may be NULL if this occurs
@@ -374,7 +382,9 @@
Returns 0 on success. On failure returns -1 and should set errno.
-=item IV (*Popped)(pTHX_ PerlIO *f);
+=item Popped
+
+ IV (*Popped)(pTHX_ PerlIO *f);
Called when the layer is popped from the stack. A layer will normally
be popped after C<Close()> is called. But a layer can be popped
@@ -387,7 +397,9 @@
Returns 0 on success and failure.
-=item PerlIO * (*Open)(...);
+=item Open
+
+ PerlIO * (*Open)(...);
The C<Open()> method has lots of arguments because it combines the
functions of perl's C<open>, C<PerlIO_open>, perl's C<sysopen>,
@@ -443,7 +455,10 @@
Returns C<NULL> on failure.
-=item SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
+=item Getarg
+
+ SV * (*Getarg)(pTHX_ PerlIO *f,
+ CLONE_PARAMS *param, int flags);
Optional. If present should return an SV * representing the string
argument passed to the layer when it was
@@ -451,7 +466,9 @@
"ascii". (I<param> and I<flags> arguments can be ignored in most
cases)
-=item IV (*Fileno)(pTHX_ PerlIO *f);
+=item Fileno
+
+ IV (*Fileno)(pTHX_ PerlIO *f);
Returns the Unix/Posix numeric file descriptor for the handle. Normally
C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
@@ -463,13 +480,18 @@
XXX: two possible results end up in -1, one is an error the other is
not.
-=item PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags)
+=item Dup
+
+ PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
+ CLONE_PARAMS *param, int flags);
XXX: not documented
Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.
-=item SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
+=item Read
+
+ SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
Basic read operation.
@@ -479,7 +501,10 @@
Returns actual bytes read, or -1 on an error.
-=item SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
+=item Unread
+
+ SSize_t (*Unread)(pTHX_ PerlIO *f,
+ const void *vbuf, Size_t count);
A superset of stdio's C<ungetc()>. Should arrange for future reads to
see the bytes in C<vbuf>. If there is no obviously better implementation
@@ -488,27 +513,35 @@
Returns the number of unread chars.
-=item SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
+=item Write
+
+ SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
Basic write operation.
Returns bytes written or -1 on an error.
-=item IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
+=item Seek
+
+ IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
Position the file pointer. Should normally call its own C<Flush>
method and then the C<Seek> method of next layer down.
Returns 0 on success, -1 on failure.
-=item Off_t (*Tell)(pTHX_ PerlIO *f);
+=item Tell
+
+ Off_t (*Tell)(pTHX_ PerlIO *f);
Return the file pointer. May be based on layers cached concept of
position to avoid overhead.
Returns -1 on failure to get the file pointer.
-=item IV (*Close)(pTHX_ PerlIO *f);
+=item Close
+
+ IV (*Close)(pTHX_ PerlIO *f);
Close the stream. Should normally call C<PerlIOBase_close()> to flush
itself and close layers below, and then deallocate any data structures
@@ -517,7 +550,9 @@
Returns 0 on success, -1 on failure.
-=item IV (*Flush)(pTHX_ PerlIO *f);
+=item Flush
+
+ IV (*Flush)(pTHX_ PerlIO *f);
Should make stream's state consistent with layers below. That is, any
buffered write data should be written, and file position of lower layers
@@ -526,7 +561,9 @@
Returns 0 on success, -1 on failure.
-=item IV (*Fill)(pTHX_ PerlIO *f);
+=item Fill
+
+ IV (*Fill)(pTHX_ PerlIO *f);
The buffer for this layer should be filled (for read) from layer
below. When you "subclass" PerlIOBuf layer, you want to use its
@@ -535,47 +572,66 @@
Returns 0 on success, -1 on failure.
-=item IV (*Eof)(pTHX_ PerlIO *f);
+=item Eof
+
+ IV (*Eof)(pTHX_ PerlIO *f);
Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
-=item IV (*Error)(pTHX_ PerlIO *f);
+=item Error
+
+ IV (*Error)(pTHX_ PerlIO *f);
Return error indicator. C<PerlIOBase_error()> is normally sufficient.
Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
0 otherwise.
-=item void (*Clearerr)(pTHX_ PerlIO *f);
+=item Clearerr
+
+ void (*Clearerr)(pTHX_ PerlIO *f);
Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()>
to set the C<PERLIO_F_XXXXX> flags, which may suffice.
-=item void (*Setlinebuf)(pTHX_ PerlIO *f);
+=item Setlinebuf
+
+ void (*Setlinebuf)(pTHX_ PerlIO *f);
Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
PERLIO_F_LINEBUF flag and is normally sufficient.
-=item STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
+=item Get_base
+
+ STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
Allocate (if not already done so) the read buffer for this layer and
return pointer to it. Return NULL on failure.
-=item Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
+=item Get_bufsiz
+
+ Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
Return the number of bytes that last C<Fill()> put in the buffer.
-=item STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
+=item Get_ptr
+
+ STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
Return the current read pointer relative to this layer's buffer.
-=item SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
+=item Get_cnt
+
+ SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
Return the number of bytes left to be read in the current buffer.
-=item void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
+=item Set_ptrcnt
+
+ void (*Set_ptrcnt)(pTHX_ PerlIO *f,
+ STDCHAR *ptr, SSize_t cnt);
Adjust the read pointer and count of bytes to match C<ptr> and/or C<cnt>.
The application (or layer above) must ensure they are consistent.
==== //depot/perl/pod/perlunicode.pod#75 (text) ====
Index: perl/pod/perlunicode.pod
--- perl/pod/perlunicode.pod.~1~ Wed Feb 27 06:45:06 2002
+++ perl/pod/perlunicode.pod Wed Feb 27 06:45:06 2002
@@ -692,7 +692,9 @@
=over 4
-=item UTF-8
+=item
+
+UTF-8
UTF-8 is a variable-length (1 to 6 bytes, current character allocations
require 4 bytes), byteorder independent encoding. For ASCII, UTF-8 is
@@ -723,11 +725,15 @@
leading bits of the start byte tells how many bytes the are in the
encoded character.
-=item UTF-EBCDIC
+=item
+
+UTF-EBCDIC
Like UTF-8, but EBCDIC-safe, as UTF-8 is ASCII-safe.
-=item UTF-16, UTF-16BE, UTF16-LE, Surrogates, and BOMs (Byte Order Marks)
+=item
+
+UTF-16, UTF-16BE, UTF16-LE, Surrogates, and BOMs (Byte Order Marks)
(The followings items are mostly for reference, Perl doesn't
use them internally.)
@@ -778,20 +784,26 @@
little-endian format" and cannot be "0xFFFE, represented in big-endian
format".
-=item UTF-32, UTF-32BE, UTF32-LE
+=item
+
+UTF-32, UTF-32BE, UTF32-LE
The UTF-32 family is pretty much like the UTF-16 family, expect that
the units are 32-bit, and therefore the surrogate scheme is not
needed. The BOM signatures will be 0x00 0x00 0xFE 0xFF for BE and
0xFF 0xFE 0x00 0x00 for LE.
-=item UCS-2, UCS-4
+=item
+
+UCS-2, UCS-4
Encodings defined by the ISO 10646 standard. UCS-2 is a 16-bit
encoding, UCS-4 is a 32-bit encoding. Unlike UTF-16, UCS-2
is not extensible beyond 0xFFFF, because it does not use surrogates.
-=item UTF-7
+=item
+
+UTF-7
A seven-bit safe (non-eight-bit) encoding, useful if the
transport/storage is not eight-bit safe. Defined by RFC 2152.
==== //depot/perl/pod/perluniintro.pod#21 (text) ====
Index: perl/pod/perluniintro.pod
--- perl/pod/perluniintro.pod.~1~ Wed Feb 27 06:45:06 2002
+++ perl/pod/perluniintro.pod Wed Feb 27 06:45:06 2002
@@ -559,7 +559,9 @@
=over 4
-=item Will My Old Scripts Break?
+=item
+
+Will My Old Scripts Break?
Very probably not. Unless you are generating Unicode characters
somehow, any old behaviour should be preserved. About the only
@@ -568,13 +570,17 @@
than 255 produced a character modulo 255 (for example, C<chr(300)>
was equal to C<chr(45)>).
-=item How Do I Make My Scripts Work With Unicode?
+=item
+
+How Do I Make My Scripts Work With Unicode?
Very little work should be needed since nothing changes until you
somehow generate Unicode data. The greatest trick will be getting
input as Unicode, and for that see the earlier I/O discussion.
-=item How Do I Know Whether My String Is In Unicode?
+=item
+
+How Do I Know Whether My String Is In Unicode?
You shouldn't care. No, you really shouldn't. If you have
to care (beyond the cases described above), it means that we
@@ -603,7 +609,9 @@
use bytes;
print length($unicode), "\n"; # will print 2 (the 0xC4 0x80 of the UTF-8)
-=item How Do I Detect Data That's Not Valid In a Particular Encoding
+=item
+
+How Do I Detect Data That's Not Valid In a Particular Encoding?
Use the C<Encode> package to try converting it.
For example,
@@ -626,7 +634,9 @@
would accept also data like C<chr(0xFF>), similarly to the
C<pack> as we saw earlier.
-=item How Do I Convert Binary Data Into a Particular Encoding, Or Vice Versa?
+=item
+
+How Do I Convert Binary Data Into a Particular Encoding, Or Vice Versa?
This probably isn't as useful as you might think.
Normally, you shouldn't need to.
@@ -679,12 +689,16 @@
use C<unpack("C*", $string)> for the former, and you can create
well-formed Unicode data by C<pack("U*", 0xff, ...)>.
-=item How Do I Display Unicode? How Do I Input Unicode?
+=item
+
+How Do I Display Unicode? How Do I Input Unicode?
See http://www.hclrss.demon.co.uk/unicode/ and
http://www.cl.cam.ac.uk/~mgk25/unicode.html
-=item How Does Unicode Work With Traditional Locales?
+=item
+
+How Does Unicode Work With Traditional Locales?
In Perl, not very well. Avoid using locales through the C<locale>
pragma. Use only one or the other.
End of Patch.
