diff options
Diffstat (limited to 'lib/Pod')
-rw-r--r-- | lib/Pod/Checker.pm | 6 | ||||
-rw-r--r-- | lib/Pod/Functions.pm | 20 | ||||
-rw-r--r-- | lib/Pod/Html.pm | 1 | ||||
-rw-r--r-- | lib/Pod/Man.pm | 155 | ||||
-rw-r--r-- | lib/Pod/Select.pm | 18 | ||||
-rw-r--r-- | lib/Pod/Text.pm | 32 | ||||
-rw-r--r-- | lib/Pod/Text/Color.pm | 9 | ||||
-rw-r--r-- | lib/Pod/Text/Overstrike.pm | 160 | ||||
-rw-r--r-- | lib/Pod/Text/Termcap.pm | 9 |
9 files changed, 344 insertions, 66 deletions
diff --git a/lib/Pod/Checker.pm b/lib/Pod/Checker.pm index 37ed68f873..35d0186a99 100644 --- a/lib/Pod/Checker.pm +++ b/lib/Pod/Checker.pm @@ -150,8 +150,8 @@ C<"">. =item * Unknown command "I<CMD>" An invalid POD command has been found. Valid are C<=head1>, C<=head2>, -C<=over>, C<=item>, C<=back>, C<=begin>, C<=end>, C<=for>, C<=pod>, -C<=cut> +C<=head3>, C<=head4>, C<=over>, C<=item>, C<=back>, C<=begin>, C<=end>, +C<=for>, C<=pod>, C<=cut> =item * Unknown interior-sequence "I<SEQ>" @@ -355,6 +355,8 @@ my %VALID_COMMANDS = ( 'cut' => 1, 'head1' => 1, 'head2' => 1, + 'head3' => 1, + 'head4' => 1, 'over' => 1, 'back' => 1, 'item' => 1, diff --git a/lib/Pod/Functions.pm b/lib/Pod/Functions.pm index 44619d53d8..960b847394 100644 --- a/lib/Pod/Functions.pm +++ b/lib/Pod/Functions.pm @@ -2,12 +2,16 @@ package Pod::Functions; #:vi:set ts=20 +our $VERSION = '1.00'; + require Exporter; @ISA = qw(Exporter); @EXPORT = qw(%Kinds %Type %Flavor %Type_Description @Type_Order); -%Type_Description = ( +our(%Kinds, %Type, %Flavor); + +our %Type_Description = ( 'ARRAY' => 'Functions for real @ARRAYs', 'Binary' => 'Functions for fixed length data or records', 'File' => 'Functions for filehandles, files, or directories', @@ -30,7 +34,7 @@ require Exporter; 'Namespace' => 'Keywords altering or affecting scoping of identifiers', ); -@Type_Order = qw{ +our @Type_Order = qw{ String Regexp Math @@ -57,20 +61,20 @@ while (<DATA>) { chomp; s/#.*//; next unless $_; - ($name, $type, $text) = split " ", $_, 3; + my($name, $type, $text) = split " ", $_, 3; $Type{$name} = $type; $Flavor{$name} = $text; - for $type ( split /[,\s]+/, $type ) { - push @{$Kinds{$type}}, $name; + for my $t ( split /[,\s]+/, $type ) { + push @{$Kinds{$t}}, $name; } } close DATA; unless (caller) { - foreach $type ( @Type_Order ) { - $list = join(", ", sort @{$Kinds{$type}}); - $typedesc = $Type_Description{$type} . ":"; + foreach my $type ( @Type_Order ) { + my $list = join(", ", sort @{$Kinds{$type}}); + my $typedesc = $Type_Description{$type} . ":"; write; } } diff --git a/lib/Pod/Html.pm b/lib/Pod/Html.pm index f70a42bccc..43168231f3 100644 --- a/lib/Pod/Html.pm +++ b/lib/Pod/Html.pm @@ -12,7 +12,6 @@ use Config; use Cwd; use File::Spec::Unix; use Getopt::Long; -use Pod::Functions; use locale; # make \w work right in non-ASCII lands diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm index 0fdb6d0360..84c8f6671b 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.8 2000/10/10 02:14:31 eagle Exp $ +# $Id: Man.pm,v 1.12 2000/12/25 12:56:12 eagle Exp $ # # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu> # @@ -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.08; +$VERSION = 1.12; ############################################################################ @@ -279,33 +279,6 @@ sub protect { $_; } -# 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. -# If there are double quotes, use an if statement to test for nroff, and for -# nroff output the command followed by the argument in double quotes with -# embedded double quotes doubled. For other formatters, remap paired double -# quotes to `` and ''. -sub switchquotes { - my $command = shift; - local $_ = shift; - my $extra = shift; - s/\\\*\([LR]\"/\"/g; - if (/\"/) { - s/\"/\"\"/g; - my $troff = $_; - $troff =~ s/\"\"([^\"]*)\"\"/\`\`$1\'\'/g; - s/\"/\"\"/g if $extra; - $troff =~ s/\"/\"\"/g if $extra; - $_ = qq("$_") . ($extra ? " $extra" : ''); - $troff = qq("$troff") . ($extra ? " $extra" : ''); - return ".if n $command $_\n.el $command $troff\n"; - } else { - $_ = qq("$_") . ($extra ? " $extra" : ''); - return "$command $_\n"; - } -} - # Translate a font string into an escape. sub toescape { (length ($_[0]) > 1 ? '\f(' : '\f') . $_[0] } @@ -568,7 +541,7 @@ sub textblock { $text = $self->parse ($text, @_); $text =~ s/\n\s*$/\n/; $self->makespace; - $self->output (protect $self->mapfonts ($text)); + $self->output (protect $self->textmapfonts ($text)); $self->outindex; $$self{NEEDSPACE} = 1; } @@ -661,7 +634,7 @@ sub cmd_head1 { $$self{ITEMS} = 0; $self->output (".PD\n"); } - $self->output (switchquotes ('.SH', $self->mapfonts ($_))); + $self->output ($self->switchquotes ('.SH', $self->mapfonts ($_))); $self->outindex (($_ eq 'NAME') ? () : ('Header', $_)); $$self{NEEDSPACE} = 0; } @@ -675,11 +648,41 @@ sub cmd_head2 { $$self{ITEMS} = 0; $self->output (".PD\n"); } - $self->output (switchquotes ('.Sh', $self->mapfonts ($_))); + $self->output ($self->switchquotes ('.Sh', $self->mapfonts ($_))); $self->outindex ('Subsection', $_); $$self{NEEDSPACE} = 0; } +# Third level heading. +sub cmd_head3 { + my $self = shift; + local $_ = $self->parse (@_); + s/\s+$//; + if ($$self{ITEMS} > 1) { + $$self{ITEMS} = 0; + $self->output (".PD\n"); + } + $self->makespace; + $self->output ($self->switchquotes ('.I', $self->mapfonts ($_))); + $self->outindex ('Subsection', $_); + $$self{NEEDSPACE} = 1; +} + +# Fourth level heading. +sub cmd_head4 { + my $self = shift; + local $_ = $self->parse (@_); + s/\s+$//; + if ($$self{ITEMS} > 1) { + $$self{ITEMS} = 0; + $self->output (".PD\n"); + } + $self->makespace; + $self->output ($self->textmapfonts ($_) . "\n"); + $self->outindex ('Subsection', $_); + $$self{NEEDSPACE} = 1; +} + # Start a list. For indents after the first, wrap the outside indent in .RS # so that hanging paragraph tags will be correct. sub cmd_over { @@ -736,9 +739,9 @@ sub cmd_item { $self->output (".RE\n"); $$self{WEIRDINDENT} = 0; } - $_ = $self->mapfonts ($_); + $_ = $self->textmapfonts ($_); $self->output (".PD 0\n") if ($$self{ITEMS} == 1); - $self->output (switchquotes ('.Ip', $_, $$self{INDENT})); + $self->output ($self->switchquotes ('.Ip', $_, $$self{INDENT})); $self->outindex ($index ? ('Item', $index) : ()); $$self{NEEDSPACE} = 0; $$self{ITEMS}++; @@ -844,18 +847,52 @@ sub buildlink { # At this point, we'll have embedded font codes of the form \f(<font>[SE] # where <font> is one of B, I, or F. Turn those into the right font start -# or end codes. B<someI<thing> else> should map to \fBsome\f(BIthing\fB -# else\fR. The old pod2man didn't get this right; the second \fB was \fR, -# so nested sequences didn't work right. We take care of this by using -# variables as a combined pointer to our current font sequence, and set each -# to the number of current nestings of start tags for that font. Use them -# as a vector to look up what font sequence to use. +# or end codes. The old pod2man didn't get B<someI<thing> else> right; +# after I<> it switched back to normal text rather than bold. We take care +# of this by using variables as a combined pointer to our current font +# sequence, and set each to the number of current nestings of start tags for +# that font. Use them as a vector to look up what font sequence to use. +# +# \fP changes to the previous font, but only one previous font is kept. We +# don't know what the outside level font is; normally it's R, but if we're +# inside a heading it could be something else. So arrange things so that +# the outside font is always the "previous" font and end with \fP instead of +# \fR. Idea from Zack Weinberg. sub mapfonts { my $self = shift; local $_ = shift; my ($fixed, $bold, $italic) = (0, 0, 0); my %magic = (F => \$fixed, B => \$bold, I => \$italic); + my $last = '\fR'; + s { \\f\((.)(.) } { + my $sequence = ''; + my $f; + if ($last ne '\fR') { $sequence = '\fP' } + ${ $magic{$1} } += ($2 eq 'S') ? 1 : -1; + $f = $$self{FONTS}{($fixed && 1) . ($bold && 1) . ($italic && 1)}; + if ($f eq $last) { + ''; + } else { + if ($f ne '\fR') { $sequence .= $f } + $last = $f; + $sequence; + } + }gxe; + $_; +} + +# Unfortunately, there is a bug in Solaris 2.6 nroff (not present in GNU +# groff) where the sequence \fB\fP\f(CW\fP leaves the font set to B rather +# than R, presumably because \f(CW doesn't actually do a font change. To +# work around this, use a separate textmapfonts for text blocks where the +# default font is always R and only use the smart mapfonts for headings. +sub textmapfonts { + my $self = shift; + local $_ = shift; + + my ($fixed, $bold, $italic) = (0, 0, 0); + my %magic = (F => \$fixed, B => \$bold, I => \$italic); s { \\f\((.)(.) } { ${ $magic{$1} } += ($2 eq 'S') ? 1 : -1; $$self{FONTS}{($fixed && 1) . ($bold && 1) . ($italic && 1)}; @@ -1020,6 +1057,44 @@ sub outindex { # Output text to the output device. sub output { print { $_[0]->output_handle } $_[1] } +# 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. +# If there are double quotes, use an if statement to test for nroff, and for +# nroff output the command followed by the argument in double quotes with +# embedded double quotes doubled. For other formatters, remap paired double +# quotes to LQUOTE and RQUOTE. +sub switchquotes { + my $self = shift; + my $command = shift; + local $_ = shift; + my $extra = shift; + s/\\\*\([LR]\"/\"/g; + + # We also have to deal with \*C` and \*C', which are used to add the + # quotes around C<> text, since they may expand to " and if they do this + # confuses the .SH macros and the like no end. Expand them ourselves. + # If $extra is set, we're dealing with =item, which in most nroff macro + # sets requires an extra level of quoting of double quotes. + my $c_is_quote = ($$self{LQUOTE} =~ /\"/) || ($$self{RQUOTE} =~ /\"/); + if (/\"/ || ($c_is_quote && /\\\*\(C[\'\`]/)) { + s/\"/\"\"/g; + my $troff = $_; + $troff =~ s/\"\"([^\"]*)\"\"/\`\`$1\'\'/g; + s/\\\*\(C\`/$$self{LQUOTE}/g; + s/\\\*\(C\'/$$self{RQUOTE}/g; + $troff =~ s/\\\*\(C[\'\`]//g; + s/\"/\"\"/g if $extra; + $troff =~ s/\"/\"\"/g if $extra; + $_ = qq("$_") . ($extra ? " $extra" : ''); + $troff = qq("$troff") . ($extra ? " $extra" : ''); + return ".if n $command $_\n.el $command $troff\n"; + } else { + $_ = qq("$_") . ($extra ? " $extra" : ''); + return "$command $_\n"; + } +} + __END__ .\" These are some extra bits of roff that I don't want to lose track of diff --git a/lib/Pod/Select.pm b/lib/Pod/Select.pm index d86d823350..e7c820f350 100644 --- a/lib/Pod/Select.pm +++ b/lib/Pod/Select.pm @@ -109,33 +109,39 @@ Some example section specifications follow. =over 4 -=item +=item * + Match the C<NAME> and C<SYNOPSIS> sections and all of their subsections: C<NAME|SYNOPSIS> -=item +=item * + Match only the C<Question> and C<Answer> subsections of the C<DESCRIPTION> section: C<DESCRIPTION/Question|Answer> -=item +=item * + Match the C<Comments> subsection of I<all> sections: C</Comments> -=item +=item * + Match all subsections of C<DESCRIPTION> I<except> for C<Comments>: C<DESCRIPTION/!Comments> -=item +=item * + Match the C<DESCRIPTION> section but do I<not> match any of its subsections: C<DESCRIPTION/!.+> -=item +=item * + Match all top level sections but none of their subsections: C</!.+> diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm index 5a7bab8f2a..5f2dae049a 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.6 2000/10/10 02:13:17 eagle Exp $ +# $Id: Text.pm,v 2.7 2000/11/19 04:47:50 eagle Exp $ # # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu> # @@ -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.06; +$VERSION = 2.07; ############################################################################ @@ -173,7 +173,7 @@ sub initialize { $$self{width} = 76 unless defined $$self{width}; # Figure out what quotes we'll be using for C<> text. - $$self{quotes} ||= "'"; + $$self{quotes} ||= '"'; if ($$self{quotes} eq 'none') { $$self{LQUOTE} = $$self{RQUOTE} = ''; } elsif (length ($$self{quotes}) == 1) { @@ -376,6 +376,32 @@ sub cmd_head2 { } } +# Third level heading. +sub cmd_head3 { + my $self = shift; + local $_ = shift; + s/\s+$//; + $_ = $self->interpolate ($_, shift); + if ($$self{alt}) { + $self->output ("\n= $_ =\n\n"); + } else { + $self->output (' ' x ($$self{indent} * 2 / 3 + 0.5) . $_ . "\n\n"); + } +} + +# Third level heading. +sub cmd_head4 { + my $self = shift; + local $_ = shift; + s/\s+$//; + $_ = $self->interpolate ($_, shift); + if ($$self{alt}) { + $self->output ("\n- $_ -\n\n"); + } else { + $self->output (' ' x ($$self{indent} * 3 / 4 + 0.5) . $_ . "\n\n"); + } +} + # Start a list. sub cmd_over { my $self = shift; diff --git a/lib/Pod/Text/Color.pm b/lib/Pod/Text/Color.pm index 10e1d9fa30..e943216d88 100644 --- a/lib/Pod/Text/Color.pm +++ b/lib/Pod/Text/Color.pm @@ -1,5 +1,5 @@ # Pod::Text::Color -- Convert POD data to formatted color ASCII text -# $Id: Color.pm,v 0.5 1999/09/20 10:15:16 eagle Exp $ +# $Id: Color.pm,v 0.6 2000/12/25 12:52:39 eagle Exp $ # # Copyright 1999 by Russ Allbery <rra@stanford.edu> # @@ -26,8 +26,11 @@ use vars qw(@ISA $VERSION); @ISA = qw(Pod::Text); -# Use the CVS revision of this file as its version number. -($VERSION = (split (' ', q$Revision: 0.5 $ ))[1]) =~ s/\.(\d)$/.0$1/; +# 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 = 0.06; ############################################################################ diff --git a/lib/Pod/Text/Overstrike.pm b/lib/Pod/Text/Overstrike.pm new file mode 100644 index 0000000000..c9f0789d06 --- /dev/null +++ b/lib/Pod/Text/Overstrike.pm @@ -0,0 +1,160 @@ +# Pod::Text::Overstrike -- Convert POD data to formatted overstrike text +# $Id: Overstrike.pm,v 1.1 2000/12/25 12:51:23 eagle Exp $ +# +# Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000 +# (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>) +# +# This program is free software; you can redistribute it and/or modify it +# under the same terms as Perl itself. +# +# This was written because the output from: +# +# pod2text Text.pm > plain.txt; less plain.txt +# +# is not as rich as the output from +# +# pod2man Text.pm | nroff -man > fancy.txt; less fancy.txt +# +# and because both Pod::Text::Color and Pod::Text::Termcap are not device +# independent. + +############################################################################ +# Modules and declarations +############################################################################ + +package Pod::Text::Overstrike; + +require 5.004; + +use Pod::Text (); + +use strict; +use vars qw(@ISA $VERSION); + +@ISA = qw(Pod::Text); + +# 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.01; + + +############################################################################ +# Overrides +############################################################################ + +# Make level one headings bold, overridding any existing formatting. +sub cmd_head1 { + my $self = shift; + local $_ = shift; + s/\s+$//; + s/(.)\cH\1//g; + s/_\cH//g; + s/(.)/$1\b$1/g; + $self->SUPER::cmd_head1 ($_); +} + +# Make level two headings bold, overriding any existing formatting. +sub cmd_head2 { + my $self = shift; + local $_ = shift; + s/\s+$//; + s/(.)\cH\1//g; + s/_\cH//g; + s/(.)/$1\b$1/g; + $self->SUPER::cmd_head2 ($_); +} + +# Make level three headings underscored, overriding any existing formatting. +sub cmd_head3 { + my $self = shift; + local $_ = shift; + s/\s+$//; + s/(.)\cH\1//g; + s/_\cH//g; + s/(.)/_\b$1/g; + $self->SUPER::cmd_head3 ($_); +} + +# Fix the various interior sequences. +sub seq_b { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/$1\b$1/g; $_ } +sub seq_f { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/_\b$1/g; $_ } +sub seq_i { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/_\b$1/g; $_ } + +# We unfortunately have to override the wrapping code here, since the normal +# wrapping code gets really confused by all the escape sequences. +sub wrap { + my $self = shift; + local $_ = shift; + my $output = ''; + my $spaces = ' ' x $$self{MARGIN}; + my $width = $$self{width} - $$self{MARGIN}; + while (length > $width) { + if (s/^((?:(?:[^\n]\cH)?[^\n]){0,$width})\s+// + || s/^((?:(?:[^\n]\cH)?[^\n]){$width})//) { + $output .= $spaces . $1 . "\n"; + } else { + last; + } + } + $output .= $spaces . $_; + $output =~ s/\s+$/\n\n/; + $output; +} + +############################################################################ +# Module return value and documentation +############################################################################ + +1; +__END__ + +=head1 NAME + +Pod::Text::Overstrike - Convert POD data to formatted overstrike text + +=head1 SYNOPSIS + + use Pod::Text::Overstrike; + my $parser = Pod::Text::Overstrike->new (sentence => 0, width => 78); + + # Read POD from STDIN and write to STDOUT. + $parser->parse_from_filehandle; + + # Read POD from file.pod and write to file.txt. + $parser->parse_from_file ('file.pod', 'file.txt'); + +=head1 DESCRIPTION + +Pod::Text::Overstrike is a simple subclass of Pod::Text that highlights +output text using overstrike sequences, in a manner similar to nroff. +Characters in bold text are overstruck (character, backspace, character) and +characters in underlined text are converted to overstruck underscores +(underscore, backspace, character). This format was originally designed for +hardcopy terminals and/or lineprinters, yet is readable on softcopy (CRT) +terminals. + +Overstruck text is best viewed by page-at-a-time programs that take +advantage of the terminal's B<stand-out> and I<underline> capabilities, such +as the less program on Unix. + +Apart from the overstrike, it in all ways functions like Pod::Text. See +L<Pod::Text> for details and available options. + +=head1 BUGS + +Currently, the outermost formatting instruction wins, so for example +underlined text inside a region of bold text is displayed as simply bold. +There may be some better approach possible. + +=head1 SEE ALSO + +L<Pod::Text|Pod::Text>, L<Pod::Parser|Pod::Parser> + +=head1 AUTHOR + +Joe Smith E<lt>Joe.Smith@inwap.comE<gt>, using the framework created by Russ +Allbery E<lt>rra@stanford.eduE<gt>. + +=cut diff --git a/lib/Pod/Text/Termcap.pm b/lib/Pod/Text/Termcap.pm index 7e89ec61be..333852a425 100644 --- a/lib/Pod/Text/Termcap.pm +++ b/lib/Pod/Text/Termcap.pm @@ -1,5 +1,5 @@ # Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes. -# $Id: Termcap.pm,v 0.4 1999/09/20 10:17:45 eagle Exp $ +# $Id: Termcap.pm,v 1.0 2000/12/25 12:52:48 eagle Exp $ # # Copyright 1999 by Russ Allbery <rra@stanford.edu> # @@ -27,8 +27,11 @@ use vars qw(@ISA $VERSION); @ISA = qw(Pod::Text); -# Use the CVS revision of this file as its version number. -($VERSION = (split (' ', q$Revision: 0.4 $ ))[1]) =~ s/\.(\d)$/.0$1/; +# 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.00; ############################################################################ |