# 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.8 2000/10/10 02:14:31 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.08;
############################################################################
# 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\|
.\}
.rm #[ #] #H #V #F C
----END OF PREAMBLE----
-
+#`# for cperl-mode
+
# This table is taken nearly verbatim from Tom Christiansen's pod2man. It
# assumes that the standard preamble has already been printed, since that's
# what defines all of the accent marks. Note that some of these are quoted
'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
s/^([.\'\\])/\\&$1/mg;
$_;
}
-
+
# Given a command and a single argument that may or may not contain double
# quotes, handle double-quote formatting for it. If there are no double
# quotes, just return the command followed by the argument in double quotes.
# Translate a font string into an escape.
sub toescape { (length ($_[0]) > 1 ? '\f(' : '\f') . $_[0] }
-
+
############################################################################
# Initialization
############################################################################
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{ITEMS} = 0; # The number of consecutive =items.
$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;
- $self->$command (@_);
+ return if ($$self{EXCLUDE} && $command ne 'end');
+ if ($self->can ('cmd_' . $command)) {
+ $command = 'cmd_' . $command;
+ $self->$command (@_);
+ } else {
+ my ($text, $line, $paragraph) = @_;
+ my $file;
+ ($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
1 while s/^(.*?)(\t+)/$1 . ' ' x (length ($2) * 8 - length ($1) % 8)/me;
s/\\/\\e/g;
s/^(\s*\S)/'\&' . $1/gme;
- $self->makespace if $$self{NEEDSPACE};
+ $self->makespace;
$self->output (".Vb $lines\n$_.Ve\n");
$$self{NEEDSPACE} = 0;
}
>
(
,?\s+(and\s+)? # Allow lots of them, conjuncted.
- L<
+ L<
/
( [:\w]+ ( \(\) )? )
>
# scalars as well as scalars and does the right thing with them.
$text = $self->parse ($text, @_);
$text =~ s/\n\s*$/\n/;
- $self->makespace if $$self{NEEDSPACE};
+ $self->makespace;
$self->output (protect $self->mapfonts ($text));
$self->outindex;
$$self{NEEDSPACE} = 1;
my $tmp = $self->buildlink ($_);
return bless \ "$tmp", 'Pod::Man::String';
}
-
+
# Whitespace protection replaces whitespace with "\ ".
if ($command eq 'S') {
s/\s+/\\ /g;
local $_ = $self->parse (@_);
s/\s+$//;
s/\\s-?\d//g;
+ if ($$self{ITEMS} > 1) {
+ $$self{ITEMS} = 0;
+ $self->output (".PD\n");
+ }
$self->output (switchquotes ('.SH', $self->mapfonts ($_)));
$self->outindex (($_ eq 'NAME') ? () : ('Header', $_));
$$self{NEEDSPACE} = 0;
my $self = shift;
local $_ = $self->parse (@_);
s/\s+$//;
+ if ($$self{ITEMS} > 1) {
+ $$self{ITEMS} = 0;
+ $self->output (".PD\n");
+ }
$self->output (switchquotes ('.Sh', $self->mapfonts ($_)));
$self->outindex ('Subsection', $_);
$$self{NEEDSPACE} = 0;
my $index;
if (/\w/ && !/^\w[.\)]\s*$/) {
$index = $_;
- $index =~ s/^\s*[-*+o.]?\s*//;
+ $index =~ s/^\s*[-*+o.]?(?:\s+|\Z)//;
}
s/^\*(\s|\Z)/\\\(bu$1/;
if ($$self{WEIRDINDENT}) {
$$self{WEIRDINDENT} = 0;
}
$_ = $self->mapfonts ($_);
+ $self->output (".PD 0\n") if ($$self{ITEMS} == 1);
$self->output (switchquotes ('.Ip', $_, $$self{INDENT}));
$self->outindex ($index ? ('Item', $index) : ());
$$self{NEEDSPACE} = 0;
+ $$self{ITEMS}++;
}
# Begin a block for a particular translator. Setting VERBATIM triggers
$self->parse_text ({ -expand_seq => 'sequence',
-expand_ptree => 'collapse' }, @_);
}
-
+
# Takes a parse tree and a flag saying whether or not to treat it as literal
# text (not call guesswork on it), and returns the concatenation of all of
# the text strings in that parse tree. If the literal flag isn't true,
# Make vertical whitespace.
sub makespace {
my $self = shift;
- $self->output ($$self{INDENT} > 0 ? ".Sp\n" : ".PP\n");
+ $self->output (".PD\n") if ($$self{ITEMS} > 1);
+ $$self{ITEMS} = 0;
+ $self->output ($$self{INDENT} > 0 ? ".Sp\n" : ".PP\n")
+ if $$self{NEEDSPACE};
}
# Output any pending index entries, and optionally an index entry given as
(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
(W) The POD source contained a non-standard interior sequence (something of
the form C<XE<lt>E<gt>>) that Pod::Man didn't know about. It was ignored.
+=item %s: Unknown command paragraph "%s" on line %d.
+
+(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 Unmatched =back
(W) Pod::Man encountered a C<=back> command that didn't correspond to an
projects / p5sagit/p5-mst-13.2.git / blobdiff