po4a: add pot_in feature

POT/PO file updated by the secondary master file specified in pot_in if it is
specified.  Otherwise the same master file used for creating the output file.

Signed-off-by: Osamu Aoki <osamu@debian.org>

po4a

@@ -87,9 +87,44 @@ will be reflected in the PO files, and all changes to the PO files (either
 manual or caused by previous step) will be reflected in translation
 documents.
 
- master document --> PO files --> translations
-
-The dataflow cannot be inversed in this tool, and changes in translations
+Normal case without specifying B<pot_in>:
+
+ <- source files ->|<--------- build results --------------->
+
+ addendum ----------------------------------+
+                                            |
+ master document --+---------------------+  |
+                   V                     +--+--> translations
+ old PO files -----+--> updated PO files +  
+      ^                      |
+      |                      V
+      +<.....................+
+    (the updated PO files are manually
+     copied to the source of the next
+     release while manually updating
+     the translation contents)
+
+Special case with specifying B<pot_in>:
+
+ <- source files ->|<--------- build results ----------------->
+
+ master document --+--------------------------+
+                   :                          |
+ external          :    filtered              |
+ filtering ========X..> master                |
+ program                document              |
+                        |                     |
+                        V                     +--> translations
+ old PO files ----------+--> updated PO files +
+      ^                           |
+      |                           V
+      +<..........................+
+    (the updated PO files are manually
+     copied to the source of the next
+     release while manually updating
+     the translation contents)
+
+The dataflow cannot be reversed in this tool, and changes in translations
 are overwritten by the content of the PO files. As a matter of fact, this
 tool cannot be used to convert existing translations to the po4a system. For
 that task, please refer to L<po4a-gettextize(1)>.
@@ -177,6 +212,9 @@ format, and where to put the translations. It can be made by such lines:
               de:doc/de/mein_kram.sgml
  [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
              add_fr:doc/l10n/script.fr.add
+ [type: docbook] doc/script.xml fr:doc/fr/script.xml \
+             de:doc/de/script.xml \
+             pot_in:doc/script.filtered.xml
 
 This should be rather self-explanatory also. Note that in the second case,
 F<doc/l10n/script.fr.add> is an addendum to add to the French version of this document.
@@ -185,8 +223,16 @@ Please refer to L<po4a(7)> for more information about the addenda.
 More formally, the format is:
 
  [type: <format>] <master_doc> (<lang>:<localized_doc>)* \
+                  (pot_in:<filtered_master_doc>)? \
                   (add_<lang>:<modifier>*<addendum_path>)*
 
+If B<pot_in> is specified, I<filtered_master_doc> is used to create POT file
+instead of I<master_doc>.  This feature allows user to create flexible ways to
+avoid contents which shouldn't be included in the PO files.  Tools such as C
+preprocessor (B<cpp>) or XSL Transformation utility (e.g., B<xsltproc>) can be
+used to create the external filtering program and call it before invoking
+B<po4a>.
+
 If there is no modifier, I<addendum_path> is a path to an addendum.
 Modifiers are
 
@@ -829,7 +875,7 @@ my (@langs);
 my (%aliases); # module aliases ([po4a_alias:...]
 my ($pot_filename) = "";
 my (%po_filename); # po_files: '$lang'=>'$path'
-my (%document); # '$master'=> {'format'=>'$format'; '$lang'=>'$path'; 'add_$lang'=>('$path','$path') }
+my (%document); # '$master'=> {'format'=>'$format'; '$lang'=>'$path'; 'add_$lang'=>('$path','$path') ; 'pot_in'=> '$master'}
 my $doc_count = 0;
 my %partial = ( 'master' => {}, 'files' => {}, 'lang' => {} );
 open CONFIG,"<","$config_file" or die wrap_msg(gettext("Can't open %s: %s"), $config_file, $!);
@@ -859,6 +905,7 @@ while (<CONFIG>) {
       unless ($args =~ s/^\[([^\]]*)\] *//);
     my $cmd = $1;
     my $main = ($args=~ s/^(\S+) *// ? $1 : "");
+    my $pot_in = $main; # Default for POT file input is $main
 
     if (@langs) {
         # Expand the $lang templates
@@ -966,6 +1013,7 @@ while (<CONFIG>) {
                 }
         }
         $document{$main}{'format'} = $1;
+        $document{$main}{'pot_in'} = $pot_in;
         $document{$main}{'pos'} = $doc_count;
         $doc_count++;
 
@@ -1052,6 +1100,9 @@ while (<CONFIG>) {
                 } else {
                     push @{$document{$main}{$lang}},$trans;
                 }
+            } elsif ($lang eq "pot_in") {
+                 $document{$main}{$lang} = $trans; # override POT file input
+                 print " .......... divert pot_in=$trans\n" if $po4a_opts{"debug"};
             } else {
                 die wrap_ref_mod("$config_file:$nb", "",
                     gettext("Translation of %s in %s redefined"), $main, $lang)
@@ -1168,7 +1219,8 @@ if (-e $pot_filename) {
     # than the POT.
     foreach my $master (keys %document) {
         next if ($master eq '');
-        if ((stat $master)[9] >= $modtime) {
+        my $pot_in = $document{$master}{'pot_in'};
+        if ((stat $pot_in)[9] >= $modtime) {
             $update_pot_file = 1;
             last;
         }
@@ -1215,6 +1267,7 @@ if ($update_pot_file) {
                                $document{$a}{'pos'} <=> $document{$b}{'pos'}
                              } keys %document) {
         next if ($master eq '');
+        my $pot_in = $document{$master}{'pot_in'};
         my %file_opts = %po4a_opts;
         my $options = $document{$master}{"options"}{"global"};
         if (defined $options) {
@@ -1231,7 +1284,7 @@ if ($update_pot_file) {
 
         $doc->setpoout($potfile);
         my @file_in_name;
-        push @file_in_name, $master;
+        push @file_in_name, $pot_in;
         $doc->process('file_in_name'     => \@file_in_name,
                       'file_in_charset'  => $file_opts{"mastchar"},
                       'srcdir'           => $po4a_opts{"srcdir"},