From: Jarkko Hietaniemi Date: Sun, 10 Sep 2000 14:32:53 +0000 (+0000) Subject: Upgrade to podlators-1.03 (Pod::Man 1.07 and Pod::Text 2.05), X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ab1f1d91718d3ea14ab3ebc4fc169516f655f3d7;p=p5sagit%2Fp5-mst-13.2.git Upgrade to podlators-1.03 (Pod::Man 1.07 and Pod::Text 2.05), by Russ Allbery. p4raw-id: //depot/perl@7047 --- diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm index 7c71681..8484cd5 100644 --- a/lib/Pod/Man.pm +++ b/lib/Pod/Man.pm @@ -1,5 +1,5 @@ # Pod::Man -- Convert POD data to formatted *roff input. -# $Id: Man.pm,v 1.4 2000/04/26 04:03:41 eagle Exp $ +# $Id: Man.pm,v 1.7 2000/09/03 09:22:57 eagle Exp $ # # Copyright 1999, 2000 by Russ Allbery # @@ -38,7 +38,7 @@ use vars qw(@ISA %ESCAPES $PREAMBLE $VERSION); # 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.04; +$VERSION = 1.07; ############################################################################ @@ -47,8 +47,10 @@ $VERSION = 1.04; # 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@. $PREAMBLE should -# therefore be run through s/\@CFONT\@//g before output. +# fixed-width font, which is designed by @CFONT@, and the left and right +# quotes to use for C<> text, designated by @LQOUTE@ and @RQUOTE@. +# $PREAMBLE should therefore be run through s/\@CFONT\@//g before +# output. $PREAMBLE = <<'----END OF PREAMBLE----'; .de Sh \" Subsection heading .br @@ -93,8 +95,8 @@ $PREAMBLE = <<'----END OF PREAMBLE----'; . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" -. ds C` ` -. ds C' ' +. ds C` @LQUOTE@ +. ds C' @RQUOTE@ 'br\} .el\{\ . ds -- \|\(em\| @@ -194,7 +196,7 @@ $PREAMBLE = <<'----END OF PREAMBLE----'; 'lt' => '<', # left chevron, less-than 'gt' => '>', # right chevron, greater-than 'quot' => '"', # double quote - 'sol' => '/', # solidus + 'sol' => '/', # solidus (forward slash) 'verbar' => '|', # vertical bar 'Aacute' => "A\\*'", # capital A, acute accent @@ -325,7 +327,8 @@ sub initialize { for (qw/fixed fixedbold fixeditalic fixedbolditalic/) { if (defined $$self{$_}) { if (length ($$self{$_}) < 1 || length ($$self{$_}) > 2) { - croak "roff font should be 1 or 2 chars, not `$$self{$_}'"; + croak qq(roff font should be 1 or 2 chars,) + . qq( not "$$self{$_}"); } } else { $$self{$_} = ''; @@ -370,6 +373,26 @@ sub initialize { $$self{$_} =~ s/\"/\"\"/g if $$self{$_}; } + # Figure out what quotes we'll be using for C<> text. + $$self{quotes} ||= "'"; + if ($$self{quotes} eq 'none') { + $$self{LQUOTE} = $$self{RQUOTE} = ''; + } elsif (length ($$self{quotes}) == 1) { + $$self{LQUOTE} = $$self{RQUOTE} = $$self{quotes}; + } elsif ($$self{quotes} =~ /^(.)(.)$/ + || $$self{quotes} =~ /^(..)(..)$/) { + $$self{LQUOTE} = $1; + $$self{RQUOTE} = $2; + } else { + croak qq(Invalid quote specification "$$self{quotes}"); + } + + # Double the first quote; note that this should not be s///g as two + # double quotes is represented in *roff as three double quotes, not + # four. Weird, I know. + $$self{LQUOTE} =~ s/\"/\"\"/; + $$self{RQUOTE} =~ s/\"/\"\"/; + $$self{INDENT} = 0; # Current indentation level. $$self{INDENTS} = []; # Stack of indentations. $$self{INDEX} = []; # Index keys waiting to be printed. @@ -377,9 +400,7 @@ sub initialize { $self->SUPER::initialize; } -# For each document we process, output the preamble first. Note that the -# fixed width font is a global default; once we interpolate it into the -# PREAMBLE, it ain't ever changing. Maybe fix this later. +# For each document we process, output the preamble first. sub begin_pod { my $self = shift; @@ -425,15 +446,18 @@ sub begin_pod { } # Now, print out the preamble and the title. - $PREAMBLE =~ s/\@CFONT\@/$$self{fixed}/; - chomp $PREAMBLE; + local $_ = $PREAMBLE; + s/\@CFONT\@/$$self{fixed}/; + s/\@LQUOTE\@/$$self{LQUOTE}/; + s/\@RQUOTE\@/$$self{RQUOTE}/; + chomp $_; print { $self->output_handle } <<"----END OF HEADER----"; .\\" Automatically generated by Pod::Man version $VERSION .\\" @{[ scalar localtime ]} .\\" .\\" Standard preamble: .\\" ====================================================================== -$PREAMBLE +$_ .\\" ====================================================================== .\\" .IX Title "$name $section" @@ -460,19 +484,17 @@ sub command { my $self = shift; my $command = shift; return if $command eq 'pod'; - return if ($$self{EXCLUDE} && $command ne 'end'); - $command = 'cmd_' . $command; - unless ($self -> can ($command)) { - my $com = substr $command => 4; - my ($file, $line) = $_ [2] -> file_line; - (my $text = $_ [0]) =~ s/\n+\z//g; - $text = " $text" if $text =~ /^\S/; - warn qq {$file: Unknown command paragraph "=$com${text}"}, - qq { on line $line.\n}; - return; - } - else { + return if ($$self{EXCLUDE} && $command ne 'end'); + if ($self->can ('cmd_' . $command)) { + $command = 'cmd_' . $command; $self->$command (@_); + } else { + my ($text, $line, $paragraph) = @_; + my ($file, $line) = $paragraph->file_line; + $text =~ s/\n+\z//; + $text = " $text" if ($text =~ /^\S/); + warn qq($file:$line: Unknown command paragraph "=$command$text"\n); + return; } } @@ -1114,6 +1136,18 @@ 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 troff(1) output. +=item quotes + +Sets the quote marks used to surround CE> text. If the value is a +single character, it is used as both the left and right quote; if it is two +characters, the first character is used as the left quote and the second as +the right quoted; and if it is four characters, the first two are used as +the left quote and the second two as the right quote. + +This may also be set to the special value C, in which case no quote +marks are added around CE> text (but the font is still changed for troff +output). + =item release Set the centered footer. By default, this is the version of Perl you run @@ -1150,7 +1184,7 @@ details. =over 4 -=item roff font should be 1 or 2 chars, not `%s' +=item roff font should be 1 or 2 chars, not "%s" (F) You specified a *roff font (using C, C, etc.) that wasn't either one or two characters. Pod::Man doesn't support *roff fonts @@ -1163,6 +1197,16 @@ versions of nroff(1) and troff(1) don't either). unable to parse. You should never see this error message; it probably indicates a bug in Pod::Man. +=item Invalid quote specification "%s" + +(F) The quote specification given (the quotes option to the constructor) was +invalid. A quote specification must be one, two, or four characters long. + +=item %s:%d: Unknown command paragraph "%s". + +(W) The POD source contained a non-standard command paragraph (something of +the form C<=command args>) that Pod::Man didn't know about. It was ignored. + =item Unknown escape EE%sE (W) The POD source contained an CE> escape that Pod::Man didn't diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm index 47dcee5..29d0dba 100644 --- a/lib/Pod/Text.pm +++ b/lib/Pod/Text.pm @@ -1,5 +1,5 @@ # Pod::Text -- Convert POD data to formatted ASCII text. -# $Id: Text.pm,v 2.4 2000/03/17 00:17:08 eagle Exp $ +# $Id: Text.pm,v 2.5 2000/09/03 09:23:29 eagle Exp $ # # Copyright 1999, 2000 by Russ Allbery # @@ -37,7 +37,7 @@ use vars qw(@ISA @EXPORT %ESCAPES $VERSION); # 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.04; +$VERSION = 2.05; ############################################################################ @@ -53,7 +53,7 @@ $VERSION = 2.04; 'lt' => '<', # left chevron, less-than 'gt' => '>', # right chevron, greater-than 'quot' => '"', # double quote - 'sol' => '/', # solidus + 'sol' => '/', # solidus (forward slash) 'verbar' => '|', # vertical bar "Aacute" => "\xC1", # capital A, acute accent @@ -172,6 +172,20 @@ sub initialize { $$self{sentence} = 0 unless defined $$self{sentence}; $$self{width} = 76 unless defined $$self{width}; + # Figure out what quotes we'll be using for C<> text. + $$self{quotes} ||= "'"; + if ($$self{quotes} eq 'none') { + $$self{LQUOTE} = $$self{RQUOTE} = ''; + } elsif (length ($$self{quotes}) == 1) { + $$self{LQUOTE} = $$self{RQUOTE} = $$self{quotes}; + } elsif ($$self{quotes} =~ /^(.)(.)$/ + || $$self{quotes} =~ /^(..)(..)$/) { + $$self{LQUOTE} = $1; + $$self{RQUOTE} = $2; + } else { + croak qq(Invalid quote specification "$$self{quotes}"); + } + $$self{INDENTS} = []; # Stack of indentations. $$self{MARGIN} = $$self{indent}; # Current left margin in spaces. @@ -193,8 +207,17 @@ sub command { return if $command eq 'pod'; return if ($$self{EXCLUDE} && $command ne 'end'); $self->item ("\n") if defined $$self{ITEM}; - $command = 'cmd_' . $command; - $self->$command (@_); + if ($self->can ('cmd_' . $command)) { + $command = 'cmd_' . $command; + $self->$command (@_); + } else { + my ($text, $line, $paragraph) = @_; + my ($file, $line) = $paragraph->file_line; + $text =~ s/\n+\z//; + $text = " $text" if ($text =~ /^\S/); + warn qq($file:$line: Unknown command paragraph "=$command$text"\n); + return; + } } # Called for a verbatim paragraph. Gets the paragraph, the line number, and @@ -419,9 +442,11 @@ sub cmd_for { # The simple formatting ones. These are here mostly so that subclasses can # override them and do more complicated things. sub seq_b { return $_[0]{alt} ? "``$_[1]''" : $_[1] } -sub seq_c { return $_[0]{alt} ? "``$_[1]''" : "`$_[1]'" } sub seq_f { return $_[0]{alt} ? "\"$_[1]\"" : $_[1] } sub seq_i { return '*' . $_[1] . '*' } +sub seq_c { + return $_[0]{alt} ? "``$_[1]''" : "$_[0]{LQUOTE}$_[1]$_[0]{RQUOTE}" +} # The complicated one. Handle links. Since this is plain text, we can't # actually make any real links, so this is all to figure out what text we @@ -592,13 +617,14 @@ sub pod2text { # means we need to turn the first argument into a file handle. Magic # open will handle the <&STDIN case automagically. if (defined $_[1]) { + my @fhs = @_; local *IN; - unless (open (IN, $_[0])) { - croak ("Can't open $_[0] for reading: $!\n"); + unless (open (IN, $fhs[0])) { + croak ("Can't open $fhs[0] for reading: $!\n"); return; } - $_[0] = \*IN; - return $parser->parse_from_filehandle (@_); + $fhs[0] = \*IN; + return $parser->parse_from_filehandle (@fhs); } else { return $parser->parse_from_file (@_); } @@ -664,6 +690,17 @@ it's the expected formatting for manual pages; if you're formatting arbitrary text documents, setting this to true may result in more pleasing output. +=item quotes + +Sets the quote marks used to surround CE> text. If the value is a +single character, it is used as both the left and right quote; if it is two +characters, the first character is used as the left quote and the second as +the right quoted; and if it is four characters, the first two are used as +the left quote and the second two as the right quote. + +This may also be set to the special value C, in which case no quote +marks are added around CE> text. + =item sentence If set to a true value, Pod::Text will assume that each sentence ends in two @@ -699,6 +736,16 @@ indicates a bug in Pod::Text; you should never see it. (F) Pod::Text was invoked via the compatibility mode pod2text() interface and the input file it was given could not be opened. +=item Invalid quote specification "%s" + +(F) The quote specification given (the quotes option to the constructor) was +invalid. A quote specification must be one, two, or four characters long. + +=item %s:%d: Unknown command paragraph "%s". + +(W) The POD source contained a non-standard command paragraph (something of +the form C<=command args>) that Pod::Man didn't know about. It was ignored. + =item Unknown escape: %s (W) The POD source contained an CE> escape that Pod::Text didn't diff --git a/pod/pod2man.PL b/pod/pod2man.PL index bf35cff..4c5831b 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -36,7 +36,7 @@ $Config{startperl} print OUT <<'!NO!SUBS!'; # pod2man -- Convert POD data to formatted *roff input. -# $Id: pod2man.PL,v 1.2 2000/03/16 21:08:23 eagle Exp $ +# $Id: pod2man.PL,v 1.3 2000/09/03 09:20:52 eagle Exp $ # # Copyright 1999, 2000 by Russ Allbery # @@ -63,7 +63,8 @@ my %options; Getopt::Long::config ('bundling_override'); GetOptions (\%options, 'section|s=s', 'release|r=s', 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s', - 'fixedbolditalic=s', 'official|o', 'lax|l', 'help|h') or exit 1; + 'fixedbolditalic=s', 'official|o', 'quotes|q=s', 'lax|l', + 'help|h') or exit 1; pod2usage (0) if $options{help}; # Official sets --center, but don't override things explicitly set. @@ -86,8 +87,8 @@ pod2man - Convert POD data to formatted *roff input pod2man [B<--section>=I] [B<--release>=I] [B<--center>=I] [B<--date>=I] [B<--fixed>=I] [B<--fixedbold>=I] [B<--fixeditalic>=I] -[B<--fixedbolditalic>=I] [B<--official>] [B<--lax>] [I -[I]] +[B<--fixedbolditalic>=I] [B<--official>] [B<--lax>] +[B<--quotes>=I] [I [I]] pod2man B<--help> @@ -173,6 +174,19 @@ POD checking functionality is not yet implemented in Pod::Man. Set the default header to indicate that this page is part of the standard Perl release, if B<--center> is not also given. +=item B<-q> I, B<--quotes>=I + +Sets the quote marks used to surround CE> text to I. If +I is a single character, it is used as both the left and right +quote; if I is two characters, the first character is used as the +left quote and the second as the right quoted; and if I is four +characters, the first two are used as the left quote and the second two as +the right quote. + +I may also be set to the special value C, in which case no +quote marks are added around CE> text (but the font is still changed for +troff output). + =item B<-r>, B<--release> Set the centered footer. By default, this is the version of Perl you run diff --git a/pod/pod2text.PL b/pod/pod2text.PL index c5460ae..b4965cb 100644 --- a/pod/pod2text.PL +++ b/pod/pod2text.PL @@ -75,7 +75,8 @@ my %options; $options{sentence} = 0; Getopt::Long::config ('bundling'); GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i', - 'loose|l', 'sentence|s', 'termcap|t', 'width|w=i') or exit 1; + 'loose|l', 'quotes|q=s', 'sentence|s', 'termcap|t', + 'width|w=i') or exit 1; pod2usage (1) if $options{help}; # Figure out what formatter we're going to use. -c overrides -t. @@ -103,7 +104,8 @@ pod2text - Convert POD data to formatted ASCII text =head1 SYNOPSIS -pod2text [B<-aclst>] [B<-i> I] [B<-w> I] [I [I]] +pod2text [B<-aclst>] [B<-i> I] [B<-q> I] [B<-w> I] +[I [I]] pod2text B<-h> @@ -148,6 +150,18 @@ printed after C<=head1>, although one is still printed after C<=head2>, because this is the expected formatting for manual pages; if you're formatting arbitrary text documents, using this option is recommended. +=item B<-q> I, B<--quotes>=I + +Sets the quote marks used to surround CE> text to I. If +I is a single character, it is used as both the left and right +quote; if I is two characters, the first character is used as the +left quote and the second as the right quoted; and if I is four +characters, the first two are used as the left quote and the second two as +the right quote. + +I may also be set to the special value C, in which case no +quote marks are added around CE> text. + =item B<-s>, B<--sentence> Assume each sentence ends with two spaces and try to preserve that spacing.