From: Joseph S. Myers Date: Fri, 20 Sep 1996 14:08:33 +0000 (+0100) Subject: Pod typos, pod2man bugs, and miscellaneous installation comments X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e52f39a2da9ded67c5b268b2013619140e55f0c6;p=p5sagit%2Fp5-mst-13.2.git Pod typos, pod2man bugs, and miscellaneous installation comments Here is a patch for various typos and other defects in the Perl 5.003_05 pods, including the pods embedded in library modules. Bugs found in pod2man The following bugs were noticed, and some fixed: 1. Where a L<> link extends over more than one line, pod2man does not treat it as a link but displays it literally, and so these have been rearranged to place the link on one line. This is the only bug worked around. [Fixed; the rearrangements, which were done beforehand, remain in some cases, but are no longer necessary, and pod paragraphs can now be safely reformatted to whatever width is desired in the pod, without breaking links.] 2. It seems to swallow spaces after certain links: for example, part of the "open" entry in the perlfunc manpage comes out as "the \f(CWbinmode\fR entry elsewhere in this documentfor tips", the source having been "L for tips". [Fixed.] 3. 'L', in perlsub.pod, comes out as '\fI/"Pass by Reference\fR', that is, with an initial '/"'. 4. If a pod line begins with ".", nothing is done to prevent [tng]roff from treating it as a [tng]roff instruction. 5. When the paragraph below =head1 NAME has more than one line, this confuses pod2man: so in the case of Term::Readline, the manpage begins with a stray line 'no real package is found, substitutes stubs instead of basic functions."'. Of course, it would be better to fix pod2man; I hope that the new Pod modules, when ready, will not have these defects. --- diff --git a/pod/pod2man.PL b/pod/pod2man.PL index 85c98c5..a4a3c25 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -198,7 +198,7 @@ Who wrote it (or AUTHORS if multiple). =item HISTORY Programs derived from other sources sometimes have this, or -you might keep a modification long here. +you might keep a modification log here. =back @@ -248,7 +248,7 @@ not having a NAME is a fatal. =item Unknown escape: %s in %s (W) An unknown HTML entity (probably for an 8-bit character) was given via -a CE> directive. Besides amp, lt, gt, and quot, recognized +a CE> directive. Besides amp, lt, gt, and quot, recognized entities are Aacute, aacute, Acirc, acirc, AElig, aelig, Agrave, agrave, Aring, aring, Atilde, atilde, Auml, auml, Ccedil, ccedil, Eacute, eacute, Ecirc, ecirc, Egrave, egrave, ETH, eth, Euml, euml, Iacute, iacute, Icirc, @@ -273,7 +273,7 @@ C<=head1>, C<=head2>, C<=item>, C<=over>, C<=back>, or C<=cut>. If you would like to print out a lot of man page continuously, you probably want to set the C and D registers to set contiguous page -numbering and even/odd paging, at least one some versions of man(7). +numbering and even/odd paging, at least on some versions of man(7). Settting the F register will get you some additional experimental indexing: @@ -390,6 +390,7 @@ $name = @ARGV ? $ARGV[0] : ""; $Filename = $name; $name = uc($name) if $section =~ /^1/; $name =~ s/\.[^.]*$//; +$name =~ s(/)(::)g; # translate Getopt/Long to Getopt::Long, etc. if ($name ne 'something') { FCHECK: { @@ -755,7 +756,7 @@ while (<>) { ? "the section on I<$2> in the I<$1> manpage" : "the section on I<$2>" } - }gex; + }gesx; # s in case it goes over multiple lines, so . matches \n s/Z<>/\\&/g; @@ -1004,7 +1005,7 @@ sub internal_lrefs { } $retstr .= " entr" . ( @items > 1 ? "ies" : "y" ) - . " elsewhere in this document"; + . " elsewhere in this document "; # terminal space to avoid words running together (pattern used strips terminal spaces) return $retstr;