This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to podlators-1.19.
[perl5.git] / lib / Pod / Man.pm
index 7fc578b..0f0eaab 100644 (file)
@@ -1,7 +1,7 @@
 # Pod::Man -- Convert POD data to formatted *roff input.
-# $Id: Man.pm,v 1.30 2001/11/28 01:14:28 eagle Exp $
+# $Id: Man.pm,v 1.32 2002/01/02 09:02:24 eagle Exp $
 #
-# Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>
+# Copyright 1999, 2000, 2001, 2002 by Russ Allbery <rra@stanford.edu>
 #
 # This program is free software; you may redistribute it and/or modify it
 # under the same terms as Perl itself.
@@ -38,7 +38,7 @@ use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION);
 # Don't use the CVS revision as the version, since this module is also in Perl
 # core and too many things could munge CVS magic revision strings.  This
 # number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.30;
+$VERSION = 1.32;
 
 
 ##############################################################################
@@ -70,7 +70,6 @@ $PREAMBLE = <<'----END OF PREAMBLE----';
 ..
 .de Ve \" End verbatim text
 .ft R
-
 .fi
 ..
 .\" Set up some character translations and predefined strings.  \*(-- will
@@ -464,13 +463,13 @@ $_
 .\\"
 .IX Title "$name $section"
 .TH $name $section "$$self{date}" "$$self{release}" "$$self{center}"
-.UC
 ----END OF HEADER----
 
     # Initialize a few per-file variables.
     $$self{INDENT}    = 0;      # Current indentation level.
     $$self{INDENTS}   = [];     # Stack of indentations.
     $$self{INDEX}     = [];     # Index keys waiting to be printed.
+    $$self{IN_NAME}   = 0;      # Whether processing the NAME section.
     $$self{ITEMS}     = 0;      # The number of consecutive =items.
     $$self{SHIFTWAIT} = 0;      # Whether there is a shift waiting.
     $$self{SHIFTS}    = [];     # Stack of .RS shifts.
@@ -520,7 +519,7 @@ sub verbatim {
     s/^(\s*\S)/'\&' . $1/gme;
     $self->makespace;
     $self->output (".Vb $lines\n$_.Ve\n");
-    $$self{NEEDSPACE} = 0;
+    $$self{NEEDSPACE} = 1;
 }
 
 # Called for a regular text block.  Gets the paragraph, the line number, and a
@@ -639,9 +638,12 @@ sub sequence {
 
 # First level heading.  We can't output .IX in the NAME section due to a bug
 # in some versions of catman, so don't output a .IX for that section.  .SH
-# already uses small caps, so remove \s1 and \s-1.
+# already uses small caps, so remove \s1 and \s-1.  Maintain IN_NAME as
+# appropriate, but don't leave it set while calling parse() so as to not
+# override guesswork on section headings after NAME.
 sub cmd_head1 {
     my $self = shift;
+    $$self{IN_NAME} = 0;
     local $_ = $self->parse (@_);
     s/\s+$//;
     s/\\s-?\d//g;
@@ -653,6 +655,7 @@ sub cmd_head1 {
     $self->output ($self->switchquotes ('.SH', $self->mapfonts ($_)));
     $self->outindex (($_ eq 'NAME') ? () : ('Header', $_));
     $$self{NEEDSPACE} = 0;
+    $$self{IN_NAME} = ($_ eq 'NAME');
 }
 
 # Second level heading.
@@ -877,13 +880,24 @@ sub parse {
 # (not call guesswork on it), and a flag saying whether or not to clean some
 # things up for *roff, and returns the concatenation of all of the text
 # strings in that parse tree.  If the literal flag isn't true, guesswork()
-# will be called on all plain scalars in the parse tree.  Otherwise, just
-# escape backslashes in the normal case.  If collapse is being called on a C<>
-# code, $cleanup should be set to true and some additional cleanup will be
-# done.  Assumes that everything in the parse tree is either a scalar or a
-# reference to a scalar.
+# will be called on all plain scalars in the parse tree.  Otherwise, if
+# collapse is being called on a C<> code, $cleanup should be set to true and
+# some additional cleanup will be done.  Assumes that everything in the parse
+# tree is either a scalar or a reference to a scalar.
 sub collapse {
     my ($self, $ptree, $literal, $cleanup) = @_;
+
+    # If we're processing the NAME section, don't do normal guesswork.  This
+    # is because NAME lines are often extracted by utilities like catman that
+    # require plain text and don't understand *roff markup.  We still need to
+    # escape backslashes and hyphens for *roff (and catman expects \- instead
+    # of -).
+    if ($$self{IN_NAME}) {
+        $literal = 1;
+        $cleanup = 1;
+    }
+
+    # Do the collapse of the parse tree as described above.
     return join ('', map {
         if (ref $_) {
             join ('', @$_);
@@ -1369,7 +1383,7 @@ B<pod2man> by Tom Christiansen <tchrist@mox.perl.com>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2002 by Russ Allbery <rra@stanford.edu>.
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.