git.sur5r.net Git - bacula/docs/blob - docs/tools/handle-xr-references.pl

   1 #!/usr/bin/perl
   2 #
   3 # Philippe Chauvat - Bacula Systems
   4 # ---
   5 # 25-octobre-2013: Creation
   6 # ---
   7 # Context: This script is designed to handle external references in HTML
   8 #          manuals.
   9 # ---
  10 # Overview:
  11 # This is a two step process.
  12 # -a) Each HTML file produced by the latex2html converter is analyzed and
  13 #     every <a name="whatever_but_beginning_with_SECTION"> expression is
  14 #     kept into a global file in a tab form: manual anchor_name file_name
  15 # -b) This (handle-xr-references.pl) script is called once, after the
  16 #     translate.pl post-process.
  17 #     It takes a list of manuals and the filename from (a) (list of anchors)
  18 #     and analyze each HTML file to find the external reference pattern:
  19 #     __XRANCHOR_...
  20 #     Then it replaces the pattern build like __XRANCHOR_TEXT_ANCHOR_MANUAL_LEVEL_
  21 #     by a <a href="path/to/manual/file_name#anchor_name>text level</a>
  22 #
  23 #
  24 # args:
  25 # -i: list of anchors file name
  26 # -m: list of manuals to manage
  27 # -l: lang of the manuals. en by default.
  28 # -?: help / usage
  29 # -d: debug requested
  30 use Getopt::Long ;
  31 use File::Basename ;
  32 use Data::Dumper ;
  33 sub usage {
  34     print "handle-xr-references.pl -m | --manuals-list manual's list
  35  -i | --input anchors-input-file-name
  36  [ -l | --lang language ]
  37  [ -d | --debug ]
  38  [ --help | -? ]\n" ;
  39     exit 1 ;
  40 }
  41 #
  42 # Send message to output in case of debug only
  43 # ======================
  44 sub debugdump {
  45     my ($what,$msg) = @_ ;
  46     if ($debug) {
  47         print "\n===============================\nBegin of $msg\n" ;
  48         $what->dump ;
  49         print "\n===============================\nEnd of $msg\n\n" ;
  50     }
  51 }
  52
  53 sub read_references {
  54     my $referencefile = $_[0] ;
  55     my %references ;
  56     local *FH ;
  57     open FH, "< $referencefile" or die "Unable to open $referencefile\n" ;
  58     while (<FH>) {
  59         our($manual,$filename,$anchor) = split /\t/,$_ ;
  60         chomp($anchor) ;
  61         if ($anchor !~ /^SECTION/ and $anchor !~ /^tex2html/ and $anchor !~ /^\d+/ ) {
  62 #           print "Manual: $manual\nAnchor: $anchor\nFilename: $filename\n\n" ;
  63             $references{$manual}{$anchor} = $filename ;
  64         }
  65     }
  66     close FH ;
  67     return %references ;
  68 }
  69 #
  70 # Args to Vars
  71 our($anchorfile,$manuallist,$help,$debug,$language) ;
  72 #
  73 # Usage in case of missing arguments
  74 usage() unless($#ARGV > -1) ;
  75 #
  76 # Input file / Output file
  77 GetOptions("input|i=s" => \$anchorfile,
  78            "manual-list|m=s" => \$manuallist,
  79            "lang|l=s" => \$language,
  80            "debug|d" => \$debug,
  81            "help|?" => \$help) or usage() ;
  82 #
  83 # Help is requested?
  84 usage() if ($help) ;
  85 #
  86 # Anchor file is mandatory
  87 usage() unless (defined $anchorfile) ;
  88 # ... and file must exist
  89 die "$anchorfile does not exists.\n" unless -e $anchorfile ;
  90 #
  91 # Manual list is mandatory too
  92 usage() unless (defined $manuallist) ;
  93 #
  94 # Read the anchor file
  95 my %references = read_references($anchorfile) ;
  96 #
  97 # Read all HTML files and replace the need references
  98 my @manuals = split / /, $manuallist ;
  99 my $m ;
 100 foreach $m (@manuals) {
 101     print "HTML files for manual $m\n" ;
 102     @htmls = glob($m . "/*html") ;
 103     foreach my $f (@htmls) {
 104         print "HTML file: $f\n" ;
 105         local *FH ;
 106         open FH, "< $f" or die "Unable to open $f\n" ;
 107         my @content = <FH> ;
 108         close FH ;
 109         open FH, "> $f" or die "Unable to write to $f\n" ;
 110         foreach my $l (@content) {
 111 #           print $l . "\n" ;
 112 # __XRANCHOR_Tape Testing_FreeBSDTapes_problems_chapter__
 113             while ($l =~ /(__XRANCHOR_[^_]*_[^_]*_[^_]*_[^_]*__)/) {
 114                 $_ = $1 ;
 115                 my $xr = $1 ;
 116                 my ($text,$anchor,$manual,$level) = /__XRANCHOR_([^_]*)_([^_]*)_([^_]*)_([^_]*)__/ ;
 117 #               print "\t\tText: $text\n\t\tAnchor: $anchor\n\t\tManual: $manual\n\t\tLevel: $level\n" ;
 118                 my $filename = $references{$manual}{$anchor} ;
 119                 my $theanchor = "<a class=\"borg_xrlinkclass\" href=\"../../$manual/$manual/$filename#$anchor\">$text $level</a>" ;
 120                 $_ = $l ;
 121 #               print $l . "\n" ;
 122                 s/$xr/$theanchor/ ;
 123                 $l = $_ ;
 124  #              print $l . "\n" ;
 125             }
 126             while ($l =~ /(__HREF_[^_]*_[^_]*__)/) {
 127                 $_ = $1 ;
 128                 my ($link,$text) = /__HREF_([^_]*)_([^_]*)__/ ;
 129                 my $theanchor = "<a class=\"borg_linkclass\" href=\"$link\">$text</a>" ;
 130                 $_ = $l ;
 131 #               print $l . "\n" ;
 132                 s/$xr/$theanchor/ ;
 133                 $l = $_ ;
 134 #               print $l . "\n" ;
 135             }
 136             print FH "$l" ;
 137         }
 138         close FH ;
 139     }
 140 }
 141 1 ;