Commit | Line | Data |
73849855 |
1 | # Pod::Text::Overstrike -- Convert POD data to formatted overstrike text |
2 | # $Id: Overstrike.pm,v 1.1 2000/12/25 12:51:23 eagle Exp $ |
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 | # |
7 | # This program is free software; you can redistribute it and/or modify it |
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 | |
21 | ############################################################################ |
22 | # Modules and declarations |
23 | ############################################################################ |
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 | |
36 | # Don't use the CVS revision as the version, since this module is also in |
37 | # Perl core and too many things could munge CVS magic revision strings. |
38 | # This number should ideally be the same as the CVS revision in podlators, |
39 | # however. |
40 | $VERSION = 1.01; |
41 | |
42 | |
43 | ############################################################################ |
44 | # Overrides |
45 | ############################################################################ |
46 | |
47 | # Make level one headings bold, overridding any existing formatting. |
48 | sub cmd_head1 { |
49 | my $self = shift; |
50 | local $_ = shift; |
51 | s/\s+$//; |
52 | s/(.)\cH\1//g; |
53 | s/_\cH//g; |
54 | s/(.)/$1\b$1/g; |
55 | $self->SUPER::cmd_head1 ($_); |
56 | } |
57 | |
58 | # Make level two headings bold, overriding any existing formatting. |
59 | sub cmd_head2 { |
60 | my $self = shift; |
61 | local $_ = shift; |
62 | s/\s+$//; |
63 | s/(.)\cH\1//g; |
64 | s/_\cH//g; |
65 | s/(.)/$1\b$1/g; |
66 | $self->SUPER::cmd_head2 ($_); |
67 | } |
68 | |
69 | # Make level three headings underscored, overriding any existing formatting. |
70 | sub cmd_head3 { |
71 | my $self = shift; |
72 | local $_ = shift; |
73 | s/\s+$//; |
74 | s/(.)\cH\1//g; |
75 | s/_\cH//g; |
76 | s/(.)/_\b$1/g; |
77 | $self->SUPER::cmd_head3 ($_); |
78 | } |
79 | |
80 | # Fix the various interior sequences. |
81 | sub seq_b { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/$1\b$1/g; $_ } |
82 | sub seq_f { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/_\b$1/g; $_ } |
83 | sub seq_i { local $_ = $_[1]; s/(.)\cH\1//g; s/_\cH//g; s/(.)/_\b$1/g; $_ } |
84 | |
85 | # We unfortunately have to override the wrapping code here, since the normal |
86 | # wrapping code gets really confused by all the escape sequences. |
87 | sub wrap { |
88 | my $self = shift; |
89 | local $_ = shift; |
90 | my $output = ''; |
91 | my $spaces = ' ' x $$self{MARGIN}; |
92 | my $width = $$self{width} - $$self{MARGIN}; |
93 | while (length > $width) { |
94 | if (s/^((?:(?:[^\n]\cH)?[^\n]){0,$width})\s+// |
95 | || s/^((?:(?:[^\n]\cH)?[^\n]){$width})//) { |
96 | $output .= $spaces . $1 . "\n"; |
97 | } else { |
98 | last; |
99 | } |
100 | } |
101 | $output .= $spaces . $_; |
102 | $output =~ s/\s+$/\n\n/; |
103 | $output; |
104 | } |
105 | |
106 | ############################################################################ |
107 | # Module return value and documentation |
108 | ############################################################################ |
109 | |
110 | 1; |
111 | __END__ |
112 | |
113 | =head1 NAME |
114 | |
115 | Pod::Text::Overstrike - Convert POD data to formatted overstrike text |
116 | |
117 | =head1 SYNOPSIS |
118 | |
119 | use Pod::Text::Overstrike; |
120 | my $parser = Pod::Text::Overstrike->new (sentence => 0, width => 78); |
121 | |
122 | # Read POD from STDIN and write to STDOUT. |
123 | $parser->parse_from_filehandle; |
124 | |
125 | # Read POD from file.pod and write to file.txt. |
126 | $parser->parse_from_file ('file.pod', 'file.txt'); |
127 | |
128 | =head1 DESCRIPTION |
129 | |
130 | Pod::Text::Overstrike is a simple subclass of Pod::Text that highlights |
131 | output text using overstrike sequences, in a manner similar to nroff. |
132 | Characters in bold text are overstruck (character, backspace, character) and |
133 | characters in underlined text are converted to overstruck underscores |
134 | (underscore, backspace, character). This format was originally designed for |
135 | hardcopy terminals and/or lineprinters, yet is readable on softcopy (CRT) |
136 | terminals. |
137 | |
138 | Overstruck text is best viewed by page-at-a-time programs that take |
139 | advantage of the terminal's B<stand-out> and I<underline> capabilities, such |
140 | as the less program on Unix. |
141 | |
142 | Apart from the overstrike, it in all ways functions like Pod::Text. See |
143 | L<Pod::Text> for details and available options. |
144 | |
145 | =head1 BUGS |
146 | |
147 | Currently, the outermost formatting instruction wins, so for example |
148 | underlined text inside a region of bold text is displayed as simply bold. |
149 | There may be some better approach possible. |
150 | |
151 | =head1 SEE ALSO |
152 | |
153 | L<Pod::Text|Pod::Text>, L<Pod::Parser|Pod::Parser> |
154 | |
155 | =head1 AUTHOR |
156 | |
157 | Joe Smith E<lt>Joe.Smith@inwap.comE<gt>, using the framework created by Russ |
158 | Allbery E<lt>rra@stanford.eduE<gt>. |
159 | |
160 | =cut |