---
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?
=================
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?
-------------
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
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 <a name="..."> tags into a file named list-of-anchors
translatedoc.pl
- includes the whole menu file
- add some "class=" and "<div>" ... 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 <a href...> tag.
TODO:
-----
--- /dev/null
+#!/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 <a name="whatever_but_beginning_with_SECTION"> 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 <a href="path/to/manual/file_name#anchor_name>text level</a>
+#
+#
+# args:
+# -i: list of anchors file name
+# -m: list of manuals to manage
+# -l: lang of the manuals. en by default.
+# -?: help / usage
+# -d: debug requested
+use Getopt::Long ;
+use File::Basename ;
+use Data::Dumper ;
+sub usage {
+ print "handle-xr-references.pl -m | --manuals-list manual's list
+ -i | --input anchors-input-file-name
+ [ -l | --lang language ]
+ [ -d | --debug ]
+ [ --help | -? ]\n" ;
+ exit 1 ;
+}
+#
+# Send message to output in case of debug only
+# ======================
+sub debugdump {
+ my ($what,$msg) = @_ ;
+ if ($debug) {
+ print "\n===============================\nBegin of $msg\n" ;
+ $what->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 (<FH>) {
+ 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 = <FH> ;
+ 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 = "<a class=\"bsys_xrlinkclass\" href=\"../$manual/$filename#$anchor\">$text $level</a>" ;
+ $_ = $l ;
+ s/$xr/$theanchor/ ;
+ $l = $_
+ }
+ print FH "$l" ;
+ }
+ close FH ;
+ }
+}
+1 ;
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
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}/
}
}
#
-# 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 = <FH> ;
- 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 = <FH> ;
- close FH ;
- foreach $l (@content) {
-# print "ligne: $l\n" ;
- if ($l =~ m/<A [^>]*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 (<FH>) {
- 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) ;
$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 ;
$img =~ s/\.\/// ;
$img = $picturesdir . '/' . $img ;
$childlinks->attr('src',$img) ;
- print "img: " . $img . "\n" ;
+# print "img: " . $img . "\n" ;
+ }
+}
+#
+# Locate all <a name="whatever_but_SECTION...">
+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 = <FH>) {
-# foreach my $k (keys %references) {
-# # print "==> The Clef: $k\n" ;
-# my $anchor = sprintf("<a href=\"%s#%s\">%s</a>",
-# $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",{}) ;
projects / bacula / docs / commitdiff