From: Philippe Chauvat Date: Fri, 25 Oct 2013 13:11:45 +0000 (+0200) Subject: This patch fix the bug referenced as https://bugs.baculasystems.com/view.php?id=23... X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=398dccd36069da57969928fe1d9dc44496b540b4;p=bacula%2Fdocs This patch fix the bug referenced as https://bugs.baculasystems.com/view.php?id=23 All the external references should be handled correctly. --- diff --git a/docs/README.pct b/docs/README.pct index c38fd237..1c20824e 100644 --- a/docs/README.pct +++ b/docs/README.pct @@ -7,6 +7,8 @@ Philippe Chauvat --- 24-octobre-2013: Known bug: Currently, the perl 5.18.1 version has a bug which have a big impact on latex2html +--- +25-octobre-2013: HTML external references added. What has changed? ================= @@ -88,8 +90,7 @@ appropriate files and because references are used over several manuals, this process must be ran over all the manuals, whatever the actual manual on which the modification(s) is (are) made. -Restriction: External references process does not work for the HTML - documentation. +External references are now managed. How it works? ------------- @@ -103,6 +104,13 @@ Where: e.g: \externaldocument[main-]{../main/quickstart} +With HTML, the process is defined by: +- finding into the original LaTeX code the \bsysxrling{$1}{$2}{$3}{$4} macro +- replacing them by __XRANCHOR_$1_$2_$3_$4__ +- modifications made into the translatedoc.pl script (see. docs/tools/README) +- calling the handle-xr-references.pl script at the end of htmls.sh script + (see docs/tools/README) + COVERPAGE MANAGEMENT ==================== The source coverpage file for a manual is located into the docs/covers/svg diff --git a/docs/tools/README b/docs/tools/README index 5d2982e7..3de3f89e 100644 --- a/docs/tools/README +++ b/docs/tools/README @@ -7,6 +7,7 @@ htmls.sh For each manual, the htmls.sh script is designed to achieve those steps: a) Build and isolates the menu b) Interpret the latex2html HTML files located into docs/manuals/en/www-{manual} and rewrite all HTML files for the manual and put them to the expected directory (docs/manuals/en/{manual}/{manual}) +c) Find and note all the tags into a file named list-of-anchors translatedoc.pl @@ -16,6 +17,14 @@ This script is called for each HTML file, read the it and convert it: - includes the whole menu file - add some "class=" and "
" ... tags - do some comestics stuff. +- note all anchors defined into the HTML files. + + +handle-xr-references.pl +----------------------- +This script is designed to read the anchors found when reading original HTML files (see above) +and then replace all the __XRANCHOR_ built during the latex2html process (see docs/README.pct) +into tag. TODO: ----- diff --git a/docs/tools/handle-xr-references.pl b/docs/tools/handle-xr-references.pl new file mode 100755 index 00000000..e2f4dc70 --- /dev/null +++ b/docs/tools/handle-xr-references.pl @@ -0,0 +1,128 @@ +#!/usr/bin/perl +# +# Philippe Chauvat - Bacula Systems +# --- +# 25-octobre-2013: Creation +# --- +# Context: This script is designed to handle external references in HTML +# manuals. +# --- +# Overview: +# This is a two step process. +# -a) Each HTML file produced by the latex2html converter is analyzed and +# every expression is +# kept into a global file in a tab form: manual anchor_name file_name +# -b) This (handle-xr-references.pl) script is called once, after the +# translate.pl post-process. +# It takes a list of manuals and the filename from (a) (list of anchors) +# and analyze each HTML file to find the external reference pattern: +# __XRANCHOR_... +# Then it replaces the pattern build like __XRANCHOR_TEXT_ANCHOR_MANUAL_LEVEL_ +# by a dump ; + print "\n===============================\nEnd of $msg\n\n" ; + } +} + +sub read_references { + my $referencefile = $_[0] ; + my %references ; + local *FH ; + open FH, "< $referencefile" or die "Unable to open $referencefile\n" ; + while () { + our($manual,$filename,$anchor) = split /\t/,$_ ; + chomp($anchor) ; + if ($anchor !~ /^SECTION/ and $anchor !~ /^tex2html/ and $anchor !~ /^\d+/ ) { +# print "Manual: $manual\nAnchor: $anchor\nFilename: $filename\n\n" ; + $references{$manual}{$anchor} = $filename ; + } + } + close FH ; + return %references ; +} +# +# Args to Vars +our($anchorfile,$manuallist,$help,$debug,$language) ; +# +# Usage in case of missing arguments +usage() unless($#ARGV > -1) ; +# +# Input file / Output file +GetOptions("input|i=s" => \$anchorfile, + "manual-list|m=s" => \$manuallist, + "lang|l=s" => \$language, + "debug|d" => \$debug, + "help|?" => \$help) or usage() ; +# +# Help is requested? +usage() if ($help) ; +# +# Anchor file is mandatory +usage() unless (defined $anchorfile) ; +# ... and file must exist +die "$anchorfile does not exists.\n" unless -e $anchorfile ; +# +# Manual list is mandatory too +usage() unless (defined $manuallist) ; +# +# Read the anchor file +my %references = read_references($anchorfile) ; +# +# Read all HTML files and replace the need references +my @manuals = split / /, $manuallist ; +my $m ; +foreach $m (@manuals) { +# print "HTML files for manual $m\n" ; + @htmls = glob($m . "/*html") ; + foreach my $f (@htmls) { +# print "HTML file: $f\n" ; + local *FH ; + open FH, "< $f" or die "Unable to open $f\n" ; + my @content = ; + close FH ; + open FH, "> $f" or die "Unable to write to $f\n" ; + foreach my $l (@content) { +# print $l . "\n" ; +# __XRANCHOR_Tape Testing_FreeBSDTapes_problems_chapter__ + if ($l =~ /(__XRANCHOR_[^_]*_[^_]*_[^_]*_[^_]*__)/) { + $_ = $1 ; + my $xr = $1 ; + my ($text,$anchor,$manual,$level) = /__XRANCHOR_([^_]*)_([^_]*)_([^_]*)_([^_]*)__/ ; + my $filename = $references{$manual}{$anchor} ; + my $theanchor = "$text $level" ; + $_ = $l ; + s/$xr/$theanchor/ ; + $l = $_ + } + print FH "$l" ; + } + close FH ; + } +} +1 ; diff --git a/docs/tools/htmls.sh b/docs/tools/htmls.sh index 47dbe2ef..1cc8abd5 100755 --- a/docs/tools/htmls.sh +++ b/docs/tools/htmls.sh @@ -71,6 +71,8 @@ do thedirname=`echo $M | sed -e 's/.*www-\(.*\)/\1/g'` # # Message to indicate what we are building + echo "" + echo "" echo "$thedirname Manual" # # Where to find HTML files @@ -104,5 +106,19 @@ do fi done # +# Anchor management +readdir="" +for M in ${LIST} +do + # + # Extract the directory name: console, developers, main, etc. + thedirname=`echo $M | sed -e 's/.*www-\(.*\)/\1/g'` + # + # Where to find HTML files + readdir="${readdir} $SOURCEDIRHEAD/$thedirname/$thedirname" +done +echo "./handle-xr-references.pl -m \"${readdir}\" -i list-of-anchors -l en" +./handle-xr-references.pl -m "${readdir}" -i list-of-anchors -l en +# # Copy images cp -v ${SOURCEIMAGEDIR}/png/*.png ${DESTIMAGEDIR}/ diff --git a/docs/tools/translatedoc.pl b/docs/tools/translatedoc.pl index 4b11848e..28205265 100755 --- a/docs/tools/translatedoc.pl +++ b/docs/tools/translatedoc.pl @@ -57,89 +57,6 @@ sub debugdump { } } # -# Build a references list -# Needed to link text and tables, images and so on (see figure xxx) -# with an HTML href -# IN: root dir and reference filename -# OUT: a reference file (ako hash) -# ======================= -sub build_references { - my $root = $_[0] ; - my $referencefile = $_[1] ; - print "Root dir: $root\n" ; - print "References file: $referencefile" ; - my %references ; - my @content ; - local *FH ; - for my $i (`find $root -iname "[a-zA-Z0-9]*.aux"`) { - print "Building references for $i\n" ; - open FH, "< $i" or die "Unable to open file $i\n" ; - @content = ; - close FH ; - for $l (@content) { - if ($l =~ /newlabel/) { -### \newlabel{figbs6:fdstorageaddress}{{2.1}{15}{Backup Over WAN\relax \relax }{figure.caption.15}{}} - my @elts = split('{|}',$l) ; - if ($#elts >4) { - if ($elts[1] ne "" and $elts[4] ne "") { - print "Clef: $elts[1]\n" ; - chomp($i) ; - chomp($elts[1]) ; - chomp($elts[4]) ; - $references{$elts[1]}{anchor} = $elts[4] ; - $references{$elts[1]}{file} = "" ; - $references{$elts[4]}{latexref} = $elts[1] ; - } - } - } - } - } - for my $i (`find $root -iname "[a-zA-Z0-9]*.html"`) { - print "Building anchors for $i\n" ; - open FH, "< $i" or die "Unable to open file $i\n" ; - @content = ; - close FH ; - foreach $l (@content) { -# print "ligne: $l\n" ; - if ($l =~ m/]*NAME *= *"([^>]*)"/) { - chomp($l) ; - print "L matche: $l / $1\n" ; - if (exists $references{$1}{latexref}) { - print "Bingo: $i --- " . $references{$1}{latexref} . "\n" ; - $references{$references{$1}{latexref}}{file} = $i ; - } - } - } - } - print "Writing references\n" ; - open FH,"> $referencefile" or die "Unable to create file $referencefile\n" ; - foreach $k (keys %references) { - if ($references{$k}{file} ne "") { - print "Key: $k\n" ; - print FH $k . " " . $references{$k}{file} . " " . $references{$k}{anchor} . "\n" ; - } - } - close FH ; - return %references ; -} -# -# References reading method -# To be able to handle references accross HTML files -# ========================= -sub read_references { - my $referencefile = $_[0] ; - my %references ; - local *FH ; - open FH, "< $referencefile" or die "Unable to open $referencefile\n" ; - while () { - our($k,$f,$v) = split / /,$_ ; - $refences{$k}{file} = $f ; - $refences{$k}{anchor} = $v ; - } - close FH ; - return %refences ; -} -# # Args to Vars our($inputfile,$outputfile,$help,$debug,$mytree,$extractmenu,$picturesdir, $cssdir,$javascriptdir,$manualname,$sourcedir) ; @@ -182,14 +99,6 @@ if (! defined $manualname) { $manualname = "main" ; } my $MENUFILE="./wholemenu_" . $manualname . ".html" ; -# my $REFERENCEFILE="./references_to_build.txt" ; -# my %references ; -# if (defined $sourcedir) { -# %references = build_references($sourcedir,$REFERENCEFILE) ; -# } -# else { -# %references = read_references($REFERENCEFILE) ; -# } # # Build HTML Tree of existing page $mytree = HTML::TreeBuilder->new ; @@ -509,34 +418,27 @@ foreach $childlinks (@images) { $img =~ s/\.\/// ; $img = $picturesdir . '/' . $img ; $childlinks->attr('src',$img) ; - print "img: " . $img . "\n" ; +# print "img: " . $img . "\n" ; + } +} +# +# Locate all +my @atags = $mytree->look_down('_tag','a') ; +local *AFH ; +open AFH, ">> list-of-anchors" or die "Unable to append to list-of-anchors file\n"; +foreach $childlinks (@atags) { + my $atagname ; + if ($atagname = $childlinks->attr('name')) { + print AFH $manualname . "\t" . basename($inputfile) . "\t" . $atagname . "\n" ; } } +close AFH ; # This li is at first level if ($outputfile) { local *FH ; open FH, ">" . $outputfile or die "Unable to create $outputfile: $!\n" ; print FH $mytree->as_HTML("<>","\t",{}) ; close FH ; -# open FH, "< $outputfile" or die "Unable to open $outputfile\n" ; -# my @content ; -# while (my $l = ) { -# foreach my $k (keys %references) { -# # print "==> The Clef: $k\n" ; -# my $anchor = sprintf("%s", -# $references{$k}{file}, -# $references{$k}{anchor}, -# $k) ; -# $l =~ s/$k/$anchor/g ; -# } -# push @content,$l ; -# } -# close FH ; -# open FH, ">" . $outputfile or die "Unable to create $outputfile: $!\n" ; -# for $l (@content) { -# print FH $l ; -# } -# close FH ; } else { print $mytree->as_HTML("","\t",{}) ;