by Russ Allbery.
p4raw-id: //depot/perl@7047
# 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 <rra@stanford.edu>
#
# 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;
############################################################################
# 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\@/<font>/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\@/<font>/g before
+# output.
$PREAMBLE = <<'----END OF PREAMBLE----';
.de Sh \" Subsection heading
.br
. 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\|
'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
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{$_} = '';
$$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.
$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;
}
# 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"
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;
}
}
(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<lt>> 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<none>, in which case no quote
+marks are added around CE<lt>> 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
=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<fixed>, C<fixedbold>, etc.) that
wasn't either one or two characters. Pod::Man doesn't support *roff fonts
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<lt>%sE<gt>
(W) The POD source contained an C<EE<lt>E<gt>> escape that Pod::Man didn't
# 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 <rra@stanford.edu>
#
# 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;
############################################################################
'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
$$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.
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
# 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
# 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 (@_);
}
arbitrary text documents, setting this to true may result in more pleasing
output.
+=item quotes
+
+Sets the quote marks used to surround CE<lt>> 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<none>, in which case no quote
+marks are added around CE<lt>> text.
+
=item sentence
If set to a true value, Pod::Text will assume that each sentence ends in two
(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 C<EE<lt>E<gt>> escape that Pod::Text didn't
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 <rra@stanford.edu>
#
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.
pod2man [B<--section>=I<manext>] [B<--release>=I<version>]
[B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>]
[B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
-[B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>] [I<input>
-[I<output>]]
+[B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>]
+[B<--quotes>=I<quotes>] [I<input> [I<output>]]
pod2man B<--help>
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<quotes>, B<--quotes>=I<quotes>
+
+Sets the quote marks used to surround CE<lt>> text to I<quotes>. If
+I<quotes> is a single character, it is used as both the left and right
+quote; if I<quotes> is two characters, the first character is used as the
+left quote and the second as the right quoted; and if I<quotes> is four
+characters, the first two are used as the left quote and the second two as
+the right quote.
+
+I<quotes> may also be set to the special value C<none>, in which case no
+quote marks are added around CE<lt>> 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
$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.
=head1 SYNOPSIS
-pod2text [B<-aclst>] [B<-i> I<indent>] [B<-w> I<width>] [I<input> [I<output>]]
+pod2text [B<-aclst>] [B<-i> I<indent>] [B<-q> I<quotes>] [B<-w> I<width>]
+[I<input> [I<output>]]
pod2text B<-h>
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<quotes>, B<--quotes>=I<quotes>
+
+Sets the quote marks used to surround CE<lt>> text to I<quotes>. If
+I<quotes> is a single character, it is used as both the left and right
+quote; if I<quotes> is two characters, the first character is used as the
+left quote and the second as the right quoted; and if I<quotes> is four
+characters, the first two are used as the left quote and the second two as
+the right quote.
+
+I<quotes> may also be set to the special value C<none>, in which case no
+quote marks are added around CE<lt>> text.
+
=item B<-s>, B<--sentence>
Assume each sentence ends with two spaces and try to preserve that spacing.
projects / p5sagit/p5-mst-13.2.git / commitdiff