1N/A# Pod::Text::Overstrike -- Convert POD data to formatted overstrike text
1N/A# $Id: Overstrike.pm,v 1.10 2002/08/04 03:35:01 eagle Exp $
1N/A#
1N/A# Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
1N/A# (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
1N/A#
1N/A# This program is free software; you may redistribute it and/or modify it
1N/A# under the same terms as Perl itself.
1N/A#
1N/A# This was written because the output from:
1N/A#
1N/A# pod2text Text.pm > plain.txt; less plain.txt
1N/A#
1N/A# is not as rich as the output from
1N/A#
1N/A# pod2man Text.pm | nroff -man > fancy.txt; less fancy.txt
1N/A#
1N/A# and because both Pod::Text::Color and Pod::Text::Termcap are not device
1N/A# independent.
1N/A
1N/A##############################################################################
1N/A# Modules and declarations
1N/A##############################################################################
1N/A
1N/Apackage Pod::Text::Overstrike;
1N/A
1N/Arequire 5.004;
1N/A
1N/Ause Pod::Text ();
1N/A
1N/Ause strict;
1N/Ause vars qw(@ISA $VERSION);
1N/A
1N/A@ISA = qw(Pod::Text);
1N/A
1N/A# Don't use the CVS revision as the version, since this module is also in Perl
1N/A# core and too many things could munge CVS magic revision strings. This
1N/A# number should ideally be the same as the CVS revision in podlators, however.
1N/A$VERSION = 1.10;
1N/A
1N/A
1N/A##############################################################################
1N/A# Overrides
1N/A##############################################################################
1N/A
1N/A# Make level one headings bold, overridding any existing formatting.
1N/Asub cmd_head1 {
1N/A my ($self, $text, $line) = @_;
1N/A $text =~ s/\s+$//;
1N/A $text = $self->strip_format ($self->interpolate ($text, $line));
1N/A $text =~ s/(.)/$1\b$1/g;
1N/A $self->SUPER::cmd_head1 ($text);
1N/A}
1N/A
1N/A# Make level two headings bold, overriding any existing formatting.
1N/Asub cmd_head2 {
1N/A my ($self, $text, $line) = @_;
1N/A $text =~ s/\s+$//;
1N/A $text = $self->strip_format ($self->interpolate ($text, $line));
1N/A $text =~ s/(.)/$1\b$1/g;
1N/A $self->SUPER::cmd_head2 ($text);
1N/A}
1N/A
1N/A# Make level three headings underscored, overriding any existing formatting.
1N/Asub cmd_head3 {
1N/A my ($self, $text, $line) = @_;
1N/A $text =~ s/\s+$//;
1N/A $text = $self->strip_format ($self->interpolate ($text, $line));
1N/A $text =~ s/(.)/_\b$1/g;
1N/A $self->SUPER::cmd_head3 ($text);
1N/A}
1N/A
1N/A# Level four headings look like level three headings.
1N/Asub cmd_head4 {
1N/A my ($self, $text, $line) = @_;
1N/A $text =~ s/\s+$//;
1N/A $text = $self->strip_format ($self->interpolate ($text, $line));
1N/A $text =~ s/(.)/_\b$1/g;
1N/A $self->SUPER::cmd_head4 ($text);
1N/A}
1N/A
1N/A# The common code for handling all headers. We have to override to avoid
1N/A# interpolating twice and because we don't want to honor alt.
1N/Asub heading {
1N/A my ($self, $text, $line, $indent, $marker) = @_;
1N/A $self->item ("\n\n") if defined $$self{ITEM};
1N/A $text .= "\n" if $$self{loose};
1N/A my $margin = ' ' x ($$self{margin} + $indent);
1N/A $self->output ($margin . $text . "\n");
1N/A}
1N/A
1N/A# Fix the various formatting codes.
1N/Asub seq_b { local $_ = strip_format (@_); s/(.)/$1\b$1/g; $_ }
1N/Asub seq_f { local $_ = strip_format (@_); s/(.)/_\b$1/g; $_ }
1N/Asub seq_i { local $_ = strip_format (@_); s/(.)/_\b$1/g; $_ }
1N/A
1N/A# Output any included code in bold.
1N/Asub output_code {
1N/A my ($self, $code) = @_;
1N/A $code =~ s/(.)/$1\b$1/g;
1N/A $self->output ($code);
1N/A}
1N/A
1N/A# We unfortunately have to override the wrapping code here, since the normal
1N/A# wrapping code gets really confused by all the backspaces.
1N/Asub wrap {
1N/A my $self = shift;
1N/A local $_ = shift;
1N/A my $output = '';
1N/A my $spaces = ' ' x $$self{MARGIN};
1N/A my $width = $$self{width} - $$self{MARGIN};
1N/A while (length > $width) {
1N/A # This regex represents a single character, that's possibly underlined
1N/A # or in bold (in which case, it's three characters; the character, a
1N/A # backspace, and a character). Use [^\n] rather than . to protect
1N/A # against odd settings of $*.
1N/A my $char = '(?:[^\n][\b])?[^\n]';
1N/A if (s/^((?>$char){0,$width})(?:\Z|\s+)//) {
1N/A $output .= $spaces . $1 . "\n";
1N/A } else {
1N/A last;
1N/A }
1N/A }
1N/A $output .= $spaces . $_;
1N/A $output =~ s/\s+$/\n\n/;
1N/A $output;
1N/A}
1N/A
1N/A##############################################################################
1N/A# Utility functions
1N/A##############################################################################
1N/A
1N/A# Strip all of the formatting from a provided string, returning the stripped
1N/A# version.
1N/Asub strip_format {
1N/A my ($self, $text) = @_;
1N/A $text =~ s/(.)[\b]\1/$1/g;
1N/A $text =~ s/_[\b]//g;
1N/A return $text;
1N/A}
1N/A
1N/A##############################################################################
1N/A# Module return value and documentation
1N/A##############################################################################
1N/A
1N/A1;
1N/A__END__
1N/A
1N/A=head1 NAME
1N/A
1N/APod::Text::Overstrike - Convert POD data to formatted overstrike text
1N/A
1N/A=head1 SYNOPSIS
1N/A
1N/A use Pod::Text::Overstrike;
1N/A my $parser = Pod::Text::Overstrike->new (sentence => 0, width => 78);
1N/A
1N/A # Read POD from STDIN and write to STDOUT.
1N/A $parser->parse_from_filehandle;
1N/A
1N/A # Read POD from file.pod and write to file.txt.
1N/A $parser->parse_from_file ('file.pod', 'file.txt');
1N/A
1N/A=head1 DESCRIPTION
1N/A
1N/APod::Text::Overstrike is a simple subclass of Pod::Text that highlights
1N/Aoutput text using overstrike sequences, in a manner similar to nroff.
1N/ACharacters in bold text are overstruck (character, backspace, character) and
1N/Acharacters in underlined text are converted to overstruck underscores
1N/A(underscore, backspace, character). This format was originally designed for
1N/Ahardcopy terminals and/or lineprinters, yet is readable on softcopy (CRT)
1N/Aterminals.
1N/A
1N/AOverstruck text is best viewed by page-at-a-time programs that take
1N/Aadvantage of the terminal's B<stand-out> and I<underline> capabilities, such
1N/Aas the less program on Unix.
1N/A
1N/AApart from the overstrike, it in all ways functions like Pod::Text. See
1N/AL<Pod::Text> for details and available options.
1N/A
1N/A=head1 BUGS
1N/A
1N/ACurrently, the outermost formatting instruction wins, so for example
1N/Aunderlined text inside a region of bold text is displayed as simply bold.
1N/AThere may be some better approach possible.
1N/A
1N/A=head1 SEE ALSO
1N/A
1N/AL<Pod::Text>, L<Pod::Parser>
1N/A
1N/AThe current version of this module is always available from its web site at
1N/AL<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
1N/APerl core distribution as of 5.6.0.
1N/A
1N/A=head1 AUTHOR
1N/A
1N/AJoe Smith <Joe.Smith@inwap.com>, using the framework created by Russ Allbery
1N/A<rra@stanford.edu>.
1N/A
1N/A=head1 COPYRIGHT AND LICENSE
1N/A
1N/ACopyright 2000 by Joe Smith <Joe.Smith@inwap.com>.
1N/ACopyright 2001 by Russ Allbery <rra@stanford.edu>.
1N/A
1N/AThis program is free software; you may redistribute it and/or modify it
1N/Aunder the same terms as Perl itself.
1N/A
1N/A=cut