| 1 | # Locale::Po4a::Pod -- Convert POD data to PO file, for translation.␊ |
| 2 | #␊ |
| 3 | # This program is free software; you may redistribute it and/or modify it␊ |
| 4 | # under the terms of GPL (see COPYING file).␊ |
| 5 | #␊ |
| 6 | # This module converts POD to PO file, so that it becomes possible to ␊ |
| 7 | # translate POD formatted documentation. See gettext documentation for␊ |
| 8 | # more info about PO files.␊ |
| 9 | ␊ |
| 10 | ############################################################################␊ |
| 11 | # Modules and declarations␊ |
| 12 | ############################################################################␊ |
| 13 | ␊ |
| 14 | use Pod::Parser;␊ |
| 15 | use Locale::Po4a::TransTractor qw(process new get_out_charset);␊ |
| 16 | ␊ |
| 17 | package Locale::Po4a::Pod;␊ |
| 18 | ␊ |
| 19 | use 5.006;␊ |
| 20 | use strict;␊ |
| 21 | use warnings;␊ |
| 22 | ␊ |
| 23 | require Exporter;␊ |
| 24 | ␊ |
| 25 | use vars qw(@ISA);␊ |
| 26 | @ISA = qw(Locale::Po4a::TransTractor Pod::Parser);␊ |
| 27 | ␊ |
| 28 | sub initialize {}␊ |
| 29 | ␊ |
| 30 | sub translate {␊ |
| 31 | my ($self,$str,$ref,$type) = @_;␊ |
| 32 | my (%options)=@_;␊ |
| 33 | ␊ |
| 34 | $str = $self->pre_trans($str,$ref,$type);␊ |
| 35 | $str = $self->SUPER::translate($str, $ref, $type, %options);␊ |
| 36 | $str = $self->post_trans($str,$ref,$type);␊ |
| 37 | ␊ |
| 38 | return $str;␊ |
| 39 | }␊ |
| 40 | ␊ |
| 41 | sub pre_trans {␊ |
| 42 | my ($self,$str,$ref,$type)=@_;␊ |
| 43 | ␊ |
| 44 | return $str;␊ |
| 45 | }␊ |
| 46 | ␊ |
| 47 | sub post_trans {␊ |
| 48 | my ($self,$str,$ref,$type)=@_;␊ |
| 49 | ␊ |
| 50 | # Change ascii non-breaking space to POD one␊ |
| 51 | my $nbs_out = "\xA0";␊ |
| 52 | my $enc_length = Encode::from_to($nbs_out, "latin1",␊ |
| 53 | $self->get_out_charset);␊ |
| 54 | if (defined $enc_length) {␊ |
| 55 | while ($str =~ m/(^|.*\s)(\S+?)\Q$nbs_out\E(\S+?)(\s.*$|$)/s) {␊ |
| 56 | my ($begin, $m1, $m2, $end) = ($1, $2, $3, $4);␊ |
| 57 | $str = (defined $begin)?$begin:"";␊ |
| 58 | # Remove the non-breaking spaces in the string that will be␊ |
| 59 | # between S<...>␊ |
| 60 | $m2 =~ s/\Q$nbs_out\E/ /g;␊ |
| 61 | $str .= "S<$m1 $m2>";␊ |
| 62 | $str .= (defined $end)?$end:"";␊ |
| 63 | }␊ |
| 64 | }␊ |
| 65 | ␊ |
| 66 | return $str;␊ |
| 67 | }␊ |
| 68 | ␊ |
| 69 | ␊ |
| 70 | sub command {␊ |
| 71 | my ($self, $command, $paragraph, $line_num) = @_;␊ |
| 72 | # print STDOUT "cmd: '$command' '$paragraph' at $line_num\n";␊ |
| 73 | if ($command eq 'back'␊ |
| 74 | ␉|| $command eq 'cut'␊ |
| 75 | ␉|| $command eq 'pod') {␊ |
| 76 | ␉$self->pushline("=$command\n\n");␊ |
| 77 | } elsif ($command eq 'over') {␊ |
| 78 | ␉$self->pushline("=$command $paragraph".(length($paragraph)?"":"\n\n"));␊ |
| 79 | } elsif ($command eq 'encoding') {␊ |
| 80 | ␉my $charset = $paragraph;␊ |
| 81 | ␉$charset =~ s/^\s*(.*?)\s*$/$1/s;␊ |
| 82 | ␉$self->detected_charset($charset)␊ |
| 83 | ␉# The =encoding line will be added by docheader␊ |
| 84 | } else {␊ |
| 85 | ␉$paragraph=$self->translate($paragraph,␊ |
| 86 | ␉␉␉␉ $self->input_file().":$line_num",␊ |
| 87 | ␉␉␉␉ "=$command",␊ |
| 88 | ␉␉␉␉ "wrap"=>1);␊ |
| 89 | ␉$self->pushline("=$command $paragraph\n\n");␊ |
| 90 | }␊ |
| 91 | }␊ |
| 92 | ␊ |
| 93 | sub verbatim {␊ |
| 94 | my ($self, $paragraph, $line_num) = @_;␊ |
| 95 | # print "verb: '$paragraph' at $line_num\n";␊ |
| 96 | ␊ |
| 97 | if ($paragraph eq "\n") {␊ |
| 98 | ␉$self->pushline("$paragraph\n");␊ |
| 99 | ␉return;␊ |
| 100 | }␊ |
| 101 | $paragraph=$self->translate($paragraph,␊ |
| 102 | ␉␉␉␉$self->input_file().":$line_num",␊ |
| 103 | ␉␉␉␉"verbatim");␊ |
| 104 | $paragraph =~ s/\n$//m;␊ |
| 105 | $self->pushline("$paragraph\n");␊ |
| 106 | }␊ |
| 107 | ␊ |
| 108 | sub textblock {␊ |
| 109 | my ($self, $paragraph, $line_num) = @_;␊ |
| 110 | # print "text: '$paragraph' at $line_num\n";␊ |
| 111 | ␊ |
| 112 | # Fix a pretty damned bug. ␊ |
| 113 | # Podlators don't wrap explicitelly the text, and groff won't seem to␊ |
| 114 | # wrap any line begining with a space. So, we have to consider as␊ |
| 115 | # verbatim not only the paragraphs whose first line is indented, but␊ |
| 116 | # the paragraph containing an indented line.␊ |
| 117 | # That way, we'll declare more paragraphs as verbatim than needed, but␊ |
| 118 | # that's harmless (only less confortable for translators).␊ |
| 119 | ␊ |
| 120 | if ($paragraph eq "\n") {␊ |
| 121 | ␉$self->pushline("$paragraph\n");␊ |
| 122 | ␉return;␊ |
| 123 | }␊ |
| 124 | if ($paragraph =~ m/^[ \t]/m) {␊ |
| 125 | ␉$self->verbatim($paragraph, $line_num) ;␊ |
| 126 | ␉return;␊ |
| 127 | }␊ |
| 128 | ␊ |
| 129 | $paragraph=$self->translate($paragraph,␊ |
| 130 | ␉␉␉␉$self->input_file().":$line_num",␊ |
| 131 | ␉␉␉␉'textblock',␊ |
| 132 | ␉␉␉␉"wrap"=>1);␊ |
| 133 | $paragraph=~ s/ +\n/\n/gm;␊ |
| 134 | $self->pushline("$paragraph\n\n");␊ |
| 135 | }␊ |
| 136 | ␊ |
| 137 | sub end_pod {}␊ |
| 138 | ␊ |
| 139 | sub read {␊ |
| 140 | my ($self,$filename)=@_;␊ |
| 141 | ␊ |
| 142 | push @{$self->{DOCPOD}{infile}}, $filename;␊ |
| 143 | $self->Locale::Po4a::TransTractor::read($filename);␊ |
| 144 | }␊ |
| 145 | ␊ |
| 146 | sub parse {␊ |
| 147 | my $self=shift;␊ |
| 148 | map {$self->parse_from_file($_)} @{$self->{DOCPOD}{infile}};␊ |
| 149 | }␊ |
| 150 | ␊ |
| 151 | sub docheader {␊ |
| 152 | my $self=shift;␊ |
| 153 | my $encoding = $self->get_out_charset();␊ |
| 154 | if ( (defined $encoding)␊ |
| 155 | and (length $encoding)␊ |
| 156 | and ($encoding ne "ascii")) {␊ |
| 157 | $encoding = "\n=encoding $encoding\n";␊ |
| 158 | } else {␊ |
| 159 | $encoding = "";␊ |
| 160 | }␊ |
| 161 | ␊ |
| 162 | return <<EOT;␊ |
| 163 | ␊ |
| 164 | *****************************************************␊ |
| 165 | * GENERATED FILE, DO NOT EDIT * ␊ |
| 166 | * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *␊ |
| 167 | *****************************************************␊ |
| 168 | ␊ |
| 169 | This file was generated by po4a(7). Do not store it (in VCS, for example),␊ |
| 170 | but store the PO file used as source file by po4a-translate. ␊ |
| 171 | ␊ |
| 172 | In fact, consider this as a binary, and the PO file as a regular .c file:␊ |
| 173 | If the PO get lost, keeping this translation up-to-date will be harder.␊ |
| 174 | $encoding␊ |
| 175 | EOT␊ |
| 176 | }␊ |
| 177 | 1;␊ |
| 178 | ␊ |
| 179 | ##############################################################################␊ |
| 180 | # Module return value and documentation␊ |
| 181 | ##############################################################################␊ |
| 182 | ␊ |
| 183 | 1;␊ |
| 184 | __END__␊ |
| 185 | ␊ |
| 186 | =encoding UTF-8␊ |
| 187 | ␊ |
| 188 | =head1 NAME␊ |
| 189 | ␊ |
| 190 | Locale::Po4a::Pod - convert POD data from/to PO files␊ |
| 191 | ␊ |
| 192 | =head1 SYNOPSIS␊ |
| 193 | ␊ |
| 194 | use Locale::Po4a::Pod;␊ |
| 195 | my $parser = Locale::Po4a::Pod->new (sentence => 0, width => 78);␊ |
| 196 | ␊ |
| 197 | # Read POD from STDIN and write to STDOUT.␊ |
| 198 | $parser->parse_from_filehandle;␊ |
| 199 | ␊ |
| 200 | # Read POD from file.pod and write to file.txt.␊ |
| 201 | $parser->parse_from_file ('file.pod', 'file.txt');␊ |
| 202 | ␊ |
| 203 | =head1 DESCRIPTION␊ |
| 204 | ␊ |
| 205 | Locale::Po4a::Pod is a module to help the translation of documentation in␊ |
| 206 | the POD format (the preferred language for documenting Perl) into other␊ |
| 207 | [human] languages.␊ |
| 208 | ␊ |
| 209 | =head1 STATUS OF THIS MODULE␊ |
| 210 | ␊ |
| 211 | I think that this module is rock stable, and there is only one known bug␊ |
| 212 | with F</usr/lib/perl5/Tk/MainWindow.pod> (and some other␊ |
| 213 | pages, see below) which contains:␊ |
| 214 | ␊ |
| 215 | C<" #n">␊ |
| 216 | ␊ |
| 217 | Lack of luck, in the po4a version, this was split on the space by the␊ |
| 218 | wrapping. As result, in the original version, the man page contains ␊ |
| 219 | ␊ |
| 220 | " #n"␊ |
| 221 | ␊ |
| 222 | and mine contains␊ |
| 223 | ␊ |
| 224 | "" #n""␊ |
| 225 | ␊ |
| 226 | which is logic since CE<lt>foobarE<gt> is rewritten "foobar".␊ |
| 227 | ␊ |
| 228 | Complete list of pages having this problem on my box (from 564 pages; note␊ |
| 229 | that it depends on the chosen wrapping column):␊ |
| 230 | /usr/lib/perl5/Tk/MainWindow.pod␊ |
| 231 | /usr/share/perl/5.8.0/overload.pod␊ |
| 232 | /usr/share/perl/5.8.0/pod/perlapi.pod␊ |
| 233 | /usr/share/perl/5.8.0/pod/perldelta.pod␊ |
| 234 | /usr/share/perl/5.8.0/pod/perlfaq5.pod␊ |
| 235 | /usr/share/perl/5.8.0/pod/perlpod.pod␊ |
| 236 | /usr/share/perl/5.8.0/pod/perlre.pod␊ |
| 237 | /usr/share/perl/5.8.0/pod/perlretut.pod␊ |
| 238 | ␊ |
| 239 | ␊ |
| 240 | ␊ |
| 241 | =head1 INTERNALS␊ |
| 242 | ␊ |
| 243 | As a derived class from Pod::Parser, Locale::Po4a::Pod supports the same␊ |
| 244 | methods and interfaces. See L<Pod::Parser> for all the details; briefly,␊ |
| 245 | one creates a new parser with C<< Locale::Po4a::Pod->new() >> and then␊ |
| 246 | calls either parse_from_filehandle() or parse_from_file().␊ |
| 247 | ␊ |
| 248 | new() can take options, in the form of key/value pairs, that control the␊ |
| 249 | behavior of the parser. The recognized options common to all Pod::Parser␊ |
| 250 | children are:␊ |
| 251 | ␊ |
| 252 | =over 4␊ |
| 253 | ␊ |
| 254 | =item B<alt>␊ |
| 255 | ␊ |
| 256 | If set to a true value, selects an alternate output format that, among other␊ |
| 257 | things, uses a different heading style and marks B<=item> entries with a␊ |
| 258 | colon in the left margin. Defaults to false.␊ |
| 259 | ␊ |
| 260 | =item B<code>␊ |
| 261 | ␊ |
| 262 | If set to a true value, the non-POD parts of the input file will be included␊ |
| 263 | in the output. Useful for viewing code documented with POD blocks with the␊ |
| 264 | POD rendered and the code left intact.␊ |
| 265 | ␊ |
| 266 | =item B<indent>␊ |
| 267 | ␊ |
| 268 | The number of spaces to indent regular text, and the default indentation for␊ |
| 269 | B<=over> blocks. Defaults to 4.␊ |
| 270 | ␊ |
| 271 | =item B<loose>␊ |
| 272 | ␊ |
| 273 | If set to a true value, a blank line is printed after a B<=head1> heading.␊ |
| 274 | If set to false (the default), no blank line is printed after B<=head1>,␊ |
| 275 | although one is still printed after B<=head2>. This is the default because␊ |
| 276 | it's the expected formatting for manual pages; if you're formatting␊ |
| 277 | arbitrary text documents, setting this to true may result in more pleasing␊ |
| 278 | output.␊ |
| 279 | ␊ |
| 280 | =item B<quotes>␊ |
| 281 | ␊ |
| 282 | Sets the quote marks used to surround CE<lt>> text. If the value is a␊ |
| 283 | single character, it is used as both the left and right quote; if it is two␊ |
| 284 | characters, the first character is used as the left quote and the second as␊ |
| 285 | the right quote; and if it is four characters, the first two are used as␊ |
| 286 | the left quote and the second two as the right quote.␊ |
| 287 | ␊ |
| 288 | This may also be set to the special value B<none>, in which case no quote␊ |
| 289 | marks are added around CE<lt>> text.␊ |
| 290 | ␊ |
| 291 | =item B<sentence>␊ |
| 292 | ␊ |
| 293 | If set to a true value, Locale::Po4a::Pod will assume that each sentence␊ |
| 294 | ends in two spaces, and will try to preserve that spacing. If set to␊ |
| 295 | false, all consecutive whitespace in non-verbatim paragraphs is compressed␊ |
| 296 | into a single space. Defaults to true.␊ |
| 297 | ␊ |
| 298 | =item B<width>␊ |
| 299 | ␊ |
| 300 | The column at which to wrap text on the right-hand side. Defaults to 76.␊ |
| 301 | ␊ |
| 302 | =back␊ |
| 303 | ␊ |
| 304 | =head1 SEE ALSO␊ |
| 305 | ␊ |
| 306 | L<Pod::Parser>,␊ |
| 307 | L<Locale::Po4a::Man(3pm)>,␊ |
| 308 | L<Locale::Po4a::TransTractor(3pm)>,␊ |
| 309 | L<po4a(7)|po4a.7>␊ |
| 310 | ␊ |
| 311 | =head1 AUTHORS␊ |
| 312 | ␊ |
| 313 | Denis Barbier <barbier@linuxfr.org>␊ |
| 314 | Martin Quinson (mquinson#debian.org)␊ |
| 315 | ␊ |
| 316 | =head1 COPYRIGHT AND LICENSE␊ |
| 317 | ␊ |
| 318 | Copyright 2002 by SPI, inc.␊ |
| 319 | ␊ |
| 320 | This program is free software; you may redistribute it and/or modify it␊ |
| 321 | under the terms of GPL (see the COPYING file).␊ |
| 322 | ␊ |
| 323 | =cut␊ |
| 324 | |
