1*0Sstevel@tonic-gate# Pod::Text::Overstrike -- Convert POD data to formatted overstrike text 2*0Sstevel@tonic-gate# $Id: Overstrike.pm,v 1.10 2002/08/04 03:35:01 eagle Exp $ 3*0Sstevel@tonic-gate# 4*0Sstevel@tonic-gate# Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000 5*0Sstevel@tonic-gate# (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>) 6*0Sstevel@tonic-gate# 7*0Sstevel@tonic-gate# This program is free software; you may redistribute it and/or modify it 8*0Sstevel@tonic-gate# under the same terms as Perl itself. 9*0Sstevel@tonic-gate# 10*0Sstevel@tonic-gate# This was written because the output from: 11*0Sstevel@tonic-gate# 12*0Sstevel@tonic-gate# pod2text Text.pm > plain.txt; less plain.txt 13*0Sstevel@tonic-gate# 14*0Sstevel@tonic-gate# is not as rich as the output from 15*0Sstevel@tonic-gate# 16*0Sstevel@tonic-gate# pod2man Text.pm | nroff -man > fancy.txt; less fancy.txt 17*0Sstevel@tonic-gate# 18*0Sstevel@tonic-gate# and because both Pod::Text::Color and Pod::Text::Termcap are not device 19*0Sstevel@tonic-gate# independent. 20*0Sstevel@tonic-gate 21*0Sstevel@tonic-gate############################################################################## 22*0Sstevel@tonic-gate# Modules and declarations 23*0Sstevel@tonic-gate############################################################################## 24*0Sstevel@tonic-gate 25*0Sstevel@tonic-gatepackage Pod::Text::Overstrike; 26*0Sstevel@tonic-gate 27*0Sstevel@tonic-gaterequire 5.004; 28*0Sstevel@tonic-gate 29*0Sstevel@tonic-gateuse Pod::Text (); 30*0Sstevel@tonic-gate 31*0Sstevel@tonic-gateuse strict; 32*0Sstevel@tonic-gateuse vars qw(@ISA $VERSION); 33*0Sstevel@tonic-gate 34*0Sstevel@tonic-gate@ISA = qw(Pod::Text); 35*0Sstevel@tonic-gate 36*0Sstevel@tonic-gate# Don't use the CVS revision as the version, since this module is also in Perl 37*0Sstevel@tonic-gate# core and too many things could munge CVS magic revision strings. This 38*0Sstevel@tonic-gate# number should ideally be the same as the CVS revision in podlators, however. 39*0Sstevel@tonic-gate$VERSION = 1.10; 40*0Sstevel@tonic-gate 41*0Sstevel@tonic-gate 42*0Sstevel@tonic-gate############################################################################## 43*0Sstevel@tonic-gate# Overrides 44*0Sstevel@tonic-gate############################################################################## 45*0Sstevel@tonic-gate 46*0Sstevel@tonic-gate# Make level one headings bold, overridding any existing formatting. 47*0Sstevel@tonic-gatesub cmd_head1 { 48*0Sstevel@tonic-gate my ($self, $text, $line) = @_; 49*0Sstevel@tonic-gate $text =~ s/\s+$//; 50*0Sstevel@tonic-gate $text = $self->strip_format ($self->interpolate ($text, $line)); 51*0Sstevel@tonic-gate $text =~ s/(.)/$1\b$1/g; 52*0Sstevel@tonic-gate $self->SUPER::cmd_head1 ($text); 53*0Sstevel@tonic-gate} 54*0Sstevel@tonic-gate 55*0Sstevel@tonic-gate# Make level two headings bold, overriding any existing formatting. 56*0Sstevel@tonic-gatesub cmd_head2 { 57*0Sstevel@tonic-gate my ($self, $text, $line) = @_; 58*0Sstevel@tonic-gate $text =~ s/\s+$//; 59*0Sstevel@tonic-gate $text = $self->strip_format ($self->interpolate ($text, $line)); 60*0Sstevel@tonic-gate $text =~ s/(.)/$1\b$1/g; 61*0Sstevel@tonic-gate $self->SUPER::cmd_head2 ($text); 62*0Sstevel@tonic-gate} 63*0Sstevel@tonic-gate 64*0Sstevel@tonic-gate# Make level three headings underscored, overriding any existing formatting. 65*0Sstevel@tonic-gatesub cmd_head3 { 66*0Sstevel@tonic-gate my ($self, $text, $line) = @_; 67*0Sstevel@tonic-gate $text =~ s/\s+$//; 68*0Sstevel@tonic-gate $text = $self->strip_format ($self->interpolate ($text, $line)); 69*0Sstevel@tonic-gate $text =~ s/(.)/_\b$1/g; 70*0Sstevel@tonic-gate $self->SUPER::cmd_head3 ($text); 71*0Sstevel@tonic-gate} 72*0Sstevel@tonic-gate 73*0Sstevel@tonic-gate# Level four headings look like level three headings. 74*0Sstevel@tonic-gatesub cmd_head4 { 75*0Sstevel@tonic-gate my ($self, $text, $line) = @_; 76*0Sstevel@tonic-gate $text =~ s/\s+$//; 77*0Sstevel@tonic-gate $text = $self->strip_format ($self->interpolate ($text, $line)); 78*0Sstevel@tonic-gate $text =~ s/(.)/_\b$1/g; 79*0Sstevel@tonic-gate $self->SUPER::cmd_head4 ($text); 80*0Sstevel@tonic-gate} 81*0Sstevel@tonic-gate 82*0Sstevel@tonic-gate# The common code for handling all headers. We have to override to avoid 83*0Sstevel@tonic-gate# interpolating twice and because we don't want to honor alt. 84*0Sstevel@tonic-gatesub heading { 85*0Sstevel@tonic-gate my ($self, $text, $line, $indent, $marker) = @_; 86*0Sstevel@tonic-gate $self->item ("\n\n") if defined $$self{ITEM}; 87*0Sstevel@tonic-gate $text .= "\n" if $$self{loose}; 88*0Sstevel@tonic-gate my $margin = ' ' x ($$self{margin} + $indent); 89*0Sstevel@tonic-gate $self->output ($margin . $text . "\n"); 90*0Sstevel@tonic-gate} 91*0Sstevel@tonic-gate 92*0Sstevel@tonic-gate# Fix the various formatting codes. 93*0Sstevel@tonic-gatesub seq_b { local $_ = strip_format (@_); s/(.)/$1\b$1/g; $_ } 94*0Sstevel@tonic-gatesub seq_f { local $_ = strip_format (@_); s/(.)/_\b$1/g; $_ } 95*0Sstevel@tonic-gatesub seq_i { local $_ = strip_format (@_); s/(.)/_\b$1/g; $_ } 96*0Sstevel@tonic-gate 97*0Sstevel@tonic-gate# Output any included code in bold. 98*0Sstevel@tonic-gatesub output_code { 99*0Sstevel@tonic-gate my ($self, $code) = @_; 100*0Sstevel@tonic-gate $code =~ s/(.)/$1\b$1/g; 101*0Sstevel@tonic-gate $self->output ($code); 102*0Sstevel@tonic-gate} 103*0Sstevel@tonic-gate 104*0Sstevel@tonic-gate# We unfortunately have to override the wrapping code here, since the normal 105*0Sstevel@tonic-gate# wrapping code gets really confused by all the backspaces. 106*0Sstevel@tonic-gatesub wrap { 107*0Sstevel@tonic-gate my $self = shift; 108*0Sstevel@tonic-gate local $_ = shift; 109*0Sstevel@tonic-gate my $output = ''; 110*0Sstevel@tonic-gate my $spaces = ' ' x $$self{MARGIN}; 111*0Sstevel@tonic-gate my $width = $$self{width} - $$self{MARGIN}; 112*0Sstevel@tonic-gate while (length > $width) { 113*0Sstevel@tonic-gate # This regex represents a single character, that's possibly underlined 114*0Sstevel@tonic-gate # or in bold (in which case, it's three characters; the character, a 115*0Sstevel@tonic-gate # backspace, and a character). Use [^\n] rather than . to protect 116*0Sstevel@tonic-gate # against odd settings of $*. 117*0Sstevel@tonic-gate my $char = '(?:[^\n][\b])?[^\n]'; 118*0Sstevel@tonic-gate if (s/^((?>$char){0,$width})(?:\Z|\s+)//) { 119*0Sstevel@tonic-gate $output .= $spaces . $1 . "\n"; 120*0Sstevel@tonic-gate } else { 121*0Sstevel@tonic-gate last; 122*0Sstevel@tonic-gate } 123*0Sstevel@tonic-gate } 124*0Sstevel@tonic-gate $output .= $spaces . $_; 125*0Sstevel@tonic-gate $output =~ s/\s+$/\n\n/; 126*0Sstevel@tonic-gate $output; 127*0Sstevel@tonic-gate} 128*0Sstevel@tonic-gate 129*0Sstevel@tonic-gate############################################################################## 130*0Sstevel@tonic-gate# Utility functions 131*0Sstevel@tonic-gate############################################################################## 132*0Sstevel@tonic-gate 133*0Sstevel@tonic-gate# Strip all of the formatting from a provided string, returning the stripped 134*0Sstevel@tonic-gate# version. 135*0Sstevel@tonic-gatesub strip_format { 136*0Sstevel@tonic-gate my ($self, $text) = @_; 137*0Sstevel@tonic-gate $text =~ s/(.)[\b]\1/$1/g; 138*0Sstevel@tonic-gate $text =~ s/_[\b]//g; 139*0Sstevel@tonic-gate return $text; 140*0Sstevel@tonic-gate} 141*0Sstevel@tonic-gate 142*0Sstevel@tonic-gate############################################################################## 143*0Sstevel@tonic-gate# Module return value and documentation 144*0Sstevel@tonic-gate############################################################################## 145*0Sstevel@tonic-gate 146*0Sstevel@tonic-gate1; 147*0Sstevel@tonic-gate__END__ 148*0Sstevel@tonic-gate 149*0Sstevel@tonic-gate=head1 NAME 150*0Sstevel@tonic-gate 151*0Sstevel@tonic-gatePod::Text::Overstrike - Convert POD data to formatted overstrike text 152*0Sstevel@tonic-gate 153*0Sstevel@tonic-gate=head1 SYNOPSIS 154*0Sstevel@tonic-gate 155*0Sstevel@tonic-gate use Pod::Text::Overstrike; 156*0Sstevel@tonic-gate my $parser = Pod::Text::Overstrike->new (sentence => 0, width => 78); 157*0Sstevel@tonic-gate 158*0Sstevel@tonic-gate # Read POD from STDIN and write to STDOUT. 159*0Sstevel@tonic-gate $parser->parse_from_filehandle; 160*0Sstevel@tonic-gate 161*0Sstevel@tonic-gate # Read POD from file.pod and write to file.txt. 162*0Sstevel@tonic-gate $parser->parse_from_file ('file.pod', 'file.txt'); 163*0Sstevel@tonic-gate 164*0Sstevel@tonic-gate=head1 DESCRIPTION 165*0Sstevel@tonic-gate 166*0Sstevel@tonic-gatePod::Text::Overstrike is a simple subclass of Pod::Text that highlights 167*0Sstevel@tonic-gateoutput text using overstrike sequences, in a manner similar to nroff. 168*0Sstevel@tonic-gateCharacters in bold text are overstruck (character, backspace, character) and 169*0Sstevel@tonic-gatecharacters in underlined text are converted to overstruck underscores 170*0Sstevel@tonic-gate(underscore, backspace, character). This format was originally designed for 171*0Sstevel@tonic-gatehardcopy terminals and/or lineprinters, yet is readable on softcopy (CRT) 172*0Sstevel@tonic-gateterminals. 173*0Sstevel@tonic-gate 174*0Sstevel@tonic-gateOverstruck text is best viewed by page-at-a-time programs that take 175*0Sstevel@tonic-gateadvantage of the terminal's B<stand-out> and I<underline> capabilities, such 176*0Sstevel@tonic-gateas the less program on Unix. 177*0Sstevel@tonic-gate 178*0Sstevel@tonic-gateApart from the overstrike, it in all ways functions like Pod::Text. See 179*0Sstevel@tonic-gateL<Pod::Text> for details and available options. 180*0Sstevel@tonic-gate 181*0Sstevel@tonic-gate=head1 BUGS 182*0Sstevel@tonic-gate 183*0Sstevel@tonic-gateCurrently, the outermost formatting instruction wins, so for example 184*0Sstevel@tonic-gateunderlined text inside a region of bold text is displayed as simply bold. 185*0Sstevel@tonic-gateThere may be some better approach possible. 186*0Sstevel@tonic-gate 187*0Sstevel@tonic-gate=head1 SEE ALSO 188*0Sstevel@tonic-gate 189*0Sstevel@tonic-gateL<Pod::Text>, L<Pod::Parser> 190*0Sstevel@tonic-gate 191*0Sstevel@tonic-gateThe current version of this module is always available from its web site at 192*0Sstevel@tonic-gateL<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the 193*0Sstevel@tonic-gatePerl core distribution as of 5.6.0. 194*0Sstevel@tonic-gate 195*0Sstevel@tonic-gate=head1 AUTHOR 196*0Sstevel@tonic-gate 197*0Sstevel@tonic-gateJoe Smith <Joe.Smith@inwap.com>, using the framework created by Russ Allbery 198*0Sstevel@tonic-gate<rra@stanford.edu>. 199*0Sstevel@tonic-gate 200*0Sstevel@tonic-gate=head1 COPYRIGHT AND LICENSE 201*0Sstevel@tonic-gate 202*0Sstevel@tonic-gateCopyright 2000 by Joe Smith <Joe.Smith@inwap.com>. 203*0Sstevel@tonic-gateCopyright 2001 by Russ Allbery <rra@stanford.edu>. 204*0Sstevel@tonic-gate 205*0Sstevel@tonic-gateThis program is free software; you may redistribute it and/or modify it 206*0Sstevel@tonic-gateunder the same terms as Perl itself. 207*0Sstevel@tonic-gate 208*0Sstevel@tonic-gate=cut 209