Re: [PATCH @14870] long C<=item>s and other pod->man->troff problems

Message-Id: <200202271225.MAA24806@tempest.npl.co.uk>

p4raw-id: //depot/perl@14892

9 files changed, 142 insertions, 48 deletions

diff --git a/README.cygwin b/README.cygwin
index d87c99ab13..a8289a1801 100644
--- a/README.cygwin
+++ b/README.cygwin
@@ -199,7 +199,8 @@ your Cygwin installation is up to date.
 
 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>
diff --git a/README.os2 b/README.os2
index ab501ba28c..8cc0ec7d40 100644
--- a/README.os2
+++ b/README.os2
@@ -733,7 +733,7 @@ Users of Emacs would appreciate it very much, especially with
 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).
diff --git a/ext/Time/HiRes/HiRes.pm b/ext/Time/HiRes/HiRes.pm
index 4e0f55fd8d..61f93b434f 100644
--- a/ext/Time/HiRes/HiRes.pm
+++ b/ext/Time/HiRes/HiRes.pm
@@ -117,7 +117,7 @@ unspecified, resulting in alarm-like behaviour.
 
 =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 @@ replacement for the C<alarm> provided with perl, see the EXAMPLES below.
 
 =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,
diff --git a/lib/CGI.pm b/lib/CGI.pm
index c07625df08..78bc931466 100644
--- a/lib/CGI.pm
+++ b/lib/CGI.pm
@@ -5759,6 +5759,7 @@ field.
 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 @@ Returns either the remote host name or IP address.
 if the former is unavailable.
 
 =item B<script_name()>
+
 Return the script name as a partial URL, for self-refering
 scripts.
 
diff --git a/lib/Math/BigInt.pm b/lib/Math/BigInt.pm
index cb199164ca..3f9e558b8d 100644
--- a/lib/Math/BigInt.pm
+++ b/lib/Math/BigInt.pm
@@ -2655,7 +2655,8 @@ If used on an object, it will set it to one:
 	$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
diff --git a/pod/perl561delta.pod b/pod/perl561delta.pod
index 1b9d7bba3e..ccd9c8d281 100644
--- a/pod/perl561delta.pod
+++ b/pod/perl561delta.pod
@@ -3444,7 +3444,9 @@ is executed:
 
 =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 @@ in 64-bit HP-UX.  The test attempts to create and connect to
 
 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
diff --git a/pod/perliol.pod b/pod/perliol.pod
index cde9be54b8..1c346e0965 100644
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -322,7 +322,9 @@ to change during one "get".)
 
 =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 @@ open().  For example if the layer is called APR, you will call:
 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 @@ flag is used it's up to the layer to validate the args.
 
 =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 @@ was un-expected).
 
 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 @@ can be re-provided to what ever is now above.
 
 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 @@ then push itself on top if that succeeds.
 
 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 @@ pushed. e.g. ":encoding(ascii)" would return an SvPV with value
 "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 @@ the case of the error.
 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 @@ provide "fast gets" methods.
 
 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 @@ then C<PerlIOBase_unread()> provides the function by pushing a "fake"
 
 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 @@ structure.
 
 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 @@ adjusted for data read from below but not actually consumed.
 
 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 @@ PerlIOBuf's buffer.
 
 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.
diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod
index 1accda426b..7fb473ebe5 100644
--- a/pod/perlunicode.pod
+++ b/pod/perlunicode.pod
@@ -692,7 +692,9 @@ numbers.  To use these numbers various encodings are needed.
 
 =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 @@ As you can see, the continuation bytes all begin with C<10>, and the
 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 @@ sequence of bytes 0xFF 0xFE is unambiguously "BOM, represented in
 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.
diff --git a/pod/perluniintro.pod b/pod/perluniintro.pod
index ee900bba1c..c94f3d289f 100644
--- a/pod/perluniintro.pod
+++ b/pod/perluniintro.pod
@@ -559,7 +559,9 @@ than ASCII 0 to 9 (and ASCII a to f for hexadecimal).
 
 =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 @@ is the old behaviour of C<chr()> where supplying an argument more
 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 @@ and its only defined function C<length()>:
     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 @@ encoded Unicode".  Without that the C<unpack("U*", ...)>
 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 @@ Any random collection of bytes isn't well-formed UTF-8.  You can
 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.