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