diff options
Diffstat (limited to 'lib/Pod/Man.pm')
| -rw-r--r-- | lib/Pod/Man.pm | 115 |
1 files changed, 63 insertions, 52 deletions
diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm index 00b1f1b5a0..9af59bb527 100644 --- a/lib/Pod/Man.pm +++ b/lib/Pod/Man.pm @@ -36,10 +36,7 @@ use POSIX qw(strftime); @ISA = qw(Pod::Simple); -# 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 = '2.17'; +$VERSION = '2.18'; # Set the debugging level. If someone has inserted a debug function into this # class already, use that. Otherwise, use any Pod::Simple debug function @@ -72,7 +69,9 @@ sub new { my $class = shift; my $self = $class->SUPER::new; - # Tell Pod::Simple to handle S<> by automatically inserting . + # Tell Pod::Simple not to handle S<> by automatically inserting . + # Note that this messes up Unicode output by embedding explicit ISO 8859-1 + # non-breaking spaces that we have to clean up later. $self->nbsp_for_S (1); # Tell Pod::Simple to keep whitespace whenever possible. @@ -363,6 +362,13 @@ sub format_text { $text =~ s/([^\x00-\x7F])/$ESCAPES{ord ($1)} || "X"/eg; } + # For Unicode output, unconditionally remap ISO 8859-1 non-breaking spaces + # to the correct code point. This is really a bug in Pod::Simple to be + # embedding ISO 8859-1 characters in the output stream that we see. + if ($$self{utf8} && ASCII) { + $text =~ s/\xA0/\xC2\xA0/g; + } + # Ensure that *roff doesn't convert literal quotes to UTF-8 single quotes, # but don't mess up our accept escapes. if ($literal) { @@ -849,7 +855,7 @@ sub devise_date { # module, but this order is correct for both Solaris and Linux. sub preamble { my ($self, $name, $section, $date) = @_; - my $preamble = $self->preamble_template; + my $preamble = $self->preamble_template (!$$self{utf8}); # Build the index line and make sure that it will be syntactically valid. my $index = "$name $section"; @@ -1023,7 +1029,7 @@ sub cmd_head1 { sub cmd_head2 { my ($self, $attrs, $text) = @_; $text = $self->heading_common ($text, $$attrs{start_line}); - $self->output ($self->switchquotes ('.Sh', $self->mapfonts ($text))); + $self->output ($self->switchquotes ('.SS', $self->mapfonts ($text))); $self->outindex ('Subsection', $text); $$self{NEEDSPACE} = 0; return ''; @@ -1271,7 +1277,7 @@ sub parse_from_filehandle { # results are pretty poor. # # This only works in an ASCII world. What to do in a non-ASCII world is very -# unclear. +# unclear -- hopefully we can assume UTF-8 and just leave well enough alone. @ESCAPES{0xA0 .. 0xFF} = ( "\\ ", undef, undef, undef, undef, undef, undef, undef, undef, undef, undef, undef, undef, "\\%", undef, undef, @@ -1297,19 +1303,13 @@ sub parse_from_filehandle { ############################################################################## # The following is the static preamble which starts all *roff output we -# generate. It's completely static except for the font to use as a -# fixed-width font, which is designed by @CFONT@, and the left and right -# quotes to use for C<> text, designated by @LQOUTE@ and @RQUOTE@. +# generate. Most is static except for the font to use as a fixed-width font, +# which is designed by @CFONT@, and the left and right quotes to use for C<> +# text, designated by @LQOUTE@ and @RQUOTE@. However, the second part, which +# defines the accent marks, is only used if $escapes is set to true. sub preamble_template { - return <<'----END OF PREAMBLE----'; -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\&\\$1\fR -.PP -.. + my ($self, $accents) = @_; + my $preamble = <<'----END OF PREAMBLE----'; .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp @@ -1353,7 +1353,7 @@ sub preamble_template { .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ @@ -1367,6 +1367,10 @@ sub preamble_template { . de IX .. .\} +----END OF PREAMBLE---- + + if ($accents) { + $preamble .= <<'----END OF PREAMBLE----' .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -1431,6 +1435,8 @@ sub preamble_template { .rm #[ #] #H #V #F C ----END OF PREAMBLE---- #`# for cperl-mode + } + return $preamble; } ############################################################################## @@ -1444,6 +1450,10 @@ __END__ Pod::Man - Convert POD data to formatted *roff input +=for stopwords +en em ALLCAPS teeny fixedbold fixeditalic fixedbolditalic utf8 UTF-8 +Allbery Sean Burke Ossanna + =head1 SYNOPSIS use Pod::Man; @@ -1476,23 +1486,23 @@ section 1 unless the file ended in C<.pm> in which case it defaults to section 3, to a centered title of "User Contributed Perl Documentation", to a centered footer of the Perl version it is run with, and to a left-hand footer of the modification date of its input (or the current date if given -STDIN for input). +C<STDIN> for input). Pod::Man assumes that your *roff formatters have a fixed-width font named -CW. If yours is called something else (like CR), use the C<fixed> option to -specify it. This generally only matters for troff output for printing. -Similarly, you can set the fonts used for bold, italic, and bold italic -fixed-width output. - -Besides the obvious pod conversions, Pod::Man also takes care of formatting -func(), func(3), and simple variable references like $foo or @bar so you -don't have to use code escapes for them; complex expressions like -C<$fred{'stuff'}> will still need to be escaped, though. It also translates -dashes that aren't used as hyphens into en dashes, makes long dashes--like -this--into proper em dashes, fixes "paired quotes," makes C++ look right, -puts a little space between double underbars, makes ALLCAPS a teeny bit -smaller in B<troff>, and escapes stuff that *roff treats as special so that -you don't have to. +C<CW>. If yours is called something else (like C<CR>), use the C<fixed> +option to specify it. This generally only matters for troff output for +printing. Similarly, you can set the fonts used for bold, italic, and +bold italic fixed-width output. + +Besides the obvious pod conversions, Pod::Man also takes care of +formatting func(), func(3), and simple variable references like $foo or +@bar so you don't have to use code escapes for them; complex expressions +like C<$fred{'stuff'}> will still need to be escaped, though. It also +translates dashes that aren't used as hyphens into en dashes, makes long +dashes--like this--into proper em dashes, fixes "paired quotes," makes C++ +look right, puts a little space between double underscores, makes ALLCAPS +a teeny bit smaller in B<troff>, and escapes stuff that *roff treats as +special so that you don't have to. The recognized options to new() are as follows. All options take a single argument. @@ -1508,31 +1518,32 @@ Documentation". Sets the left-hand footer. By default, the modification date of the input file will be used, or the current date if stat() can't find that file (the -case if the input is from STDIN), and the date will be formatted as -YYYY-MM-DD. +case if the input is from C<STDIN>), and the date will be formatted as +C<YYYY-MM-DD>. =item fixed -The fixed-width font to use for vertabim text and code. Defaults to CW. -Some systems may want CR instead. Only matters for B<troff> output. +The fixed-width font to use for verbatim text and code. Defaults to +C<CW>. Some systems may want C<CR> instead. Only matters for B<troff> +output. =item fixedbold -Bold version of the fixed-width font. Defaults to CB. Only matters for -B<troff> output. +Bold version of the fixed-width font. Defaults to C<CB>. Only matters +for B<troff> output. =item fixeditalic Italic version of the fixed-width font (actually, something of a misnomer, since most fixed-width fonts only have an oblique version, not an italic -version). Defaults to CI. Only matters for B<troff> output. +version). Defaults to C<CI>. Only matters for B<troff> output. =item fixedbolditalic Bold italic (probably actually oblique) version of the fixed-width font. -Pod::Man doesn't assume you have this, and defaults to CB. Some systems -(such as Solaris) have this font available as CX. Only matters for B<troff> -output. +Pod::Man doesn't assume you have this, and defaults to C<CB>. Some +systems (such as Solaris) have this font available as C<CX>. Only matters +for B<troff> output. =item name @@ -1574,8 +1585,8 @@ formats, 5 for miscellaneous information, and 7 for devices. Still others use 1m instead of 8, or some mix of both. About the only section numbers that are reliably consistent are 1, 2, and 3. -By default, section 1 will be used unless the file ends in .pm in which case -section 3 will be selected. +By default, section 1 will be used unless the file ends in C<.pm> in which +case section 3 will be selected. =item utf8 @@ -1596,8 +1607,8 @@ behavior. =back The standard Pod::Simple method parse_file() takes one argument naming the -POD file to read from. By default, the output is sent to STDOUT, but this -can be changed with the output_fd() method. +POD file to read from. By default, the output is sent to C<STDOUT>, but +this can be changed with the output_fd() method. The standard Pod::Simple method parse_from_file() takes up to two arguments, the first being the input file to read POD from and the second @@ -1674,8 +1685,8 @@ mine). =head1 COPYRIGHT AND LICENSE -Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 -by Russ Allbery <rra@stanford.edu>. +Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 +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. |