######################################################################
# 
#      ManyPage : Moteur de Publication de site Web
#      ManyPage : Web site Management tools
#
#
# Auteur/Author       		: Pierre Cordani
# Collaborateur/Contributor	: Pascal Vuylsteker, MediaPort team
#
# Documentation : http://www.vrarchitect.net/ManyPage
# Question      : manypage@vuylsteker.net
#
# Creation      : 1/1/00
# Modification  : 1/12/00
# Version       : 0.9
# SoftVersion   : Perl 5
######################################################################
#
# This file contain information only for people that would like to understand
# how manyPage work. If you really want to, you should be abble to read
# French, english... and spanish !
#
# Ce fichier contient des informations pour les personnes dsirant comprendre
# comment Manypage fonctionne. la programmation perl a pour l'instant, plus
# t oriente vers l'optimisation que vers la comprhension du code source
# Si vous savez lire le Franais, l'anglais, ... et l'espagnole, vous devriez
# pouvoir vous faire une ide du fonctionnement  l'aide des notes suivantes.
#
######################################################################
#
#  Copyright (C) 2000 Pierre Cordani - Pascal Vuylsteker
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# Ce programme est un logiciel libre ; vous pouvez le redistribuer et/ou le modifier conformment
# aux dispositions de la Licence Publique Gnrale GNU, telle que publie par la Free Software
# Foundation ; version 2 de la licence, ou encore ( votre choix) toute version ultrieure.
#
###################

	Ce fichier devrai permettre de mieux comprendre le fonctionnement
du script d'habillage et permettre ainsi un possible desinsectisage en cas
de force majeure.
	L'ideal serai que n'importe quelle seance de desinsectisage soit faite 
avec une serie de tests a l'appui, pour ainsi eviter toute introduction
d'un nouvel insecte detectable que dans deux mois, donc difficilement 
reperable dans le source.

    La version du script lors de l'ecriture de ce fichier est 1.6.9

	Le script d'habillage est decoupe en 13 modules listes ci-dessous.

	-habille.pl
	-main.pl
	-transfert.pl
	-lecture.pl
	-ecriture.pl
	-ecriture_obj.pl
	-creation_lien.pl
	-recursivite.pl
	-title.pl
	-transfert_autre.pl
	-image_size.pl
	-utils.pl
	-parallele.pl

	Et deux fichiers de configuration
	
	-config
	-autre_habillage

	*Gestion des habillages paralleles
	
	Le module habille.pl va lire le fichier de config autre_habillage, qui lui
donnera connaissance des differents habillages a utiliser en parallele.
	Ce module va appeler le module main.pl pour chaque nouvel habillage avec
l'option requise

	*Lecture des fichiers .dress, .obj, .link

	Le module qu'on devra appeler pour lancer l'execution du script est
habille.pl, c'est lui qui recevra les parametres necessaires au bon
fonctionnement du programme.
	Mise a part la definition de quelques variable, tout commence dans la
fonction main (habitude de la programmation en C). On effectue la lecture 
des parametres, on definie les variables $Source et $Dest de facon a pouvoir
etre execute depuis n'importe quelle machine, tout en sachant que le code 
reside sur arantel.
	Maintenant, il s'agit de lire les fichiers .dress, .obj et .link. Pour
cela, il est souvent necessaire de faire une petite manipulation sur la 
chaine de caracteres representant le fichier a habiller, de sorte a trouver
le repertoire dans lequel il se trouve et ainsi lire les fichiers .dress, .obj
et .link necessaires a l'habillage.
	Une fois le repertoire obtenu, on lit pour chaque etage du path les
fichiers .dress, .obj et .link. Le fichier .obj doit forcement etre lu pour
chaque etage du path, car il faut garder la notion d'heritage entre les 
objets. Par contre, le fichier .dress est lu de cette maniere par commodite.
Car il faut savoir que tout nouveau .dress ecrasse l'ancien, donc, la lecture 
devrai s'effectuer inversement, en commencant dans le repertoire du fichier
a habiller, et ne remonter que si le fichier .dress est inexistant. De meme
pour le fichier .link qui ne devrai etre lu que dans le repertoire du fichier
a habiller. Mais bon, c'est super car ca me laisse encore une marge en ce
qui concerne le gain en vitesse d'execution.
	Evidement, a la sortie de cette boucle, on obtient:
	- un seul habillage_brut (hashtable)
	- un seul Objet_html	 (hashtable)
	- un seul Mes_Liens		 (hashtable)
	- une bdd de langues	 (hashtable)
	
	Pourquoi je souligne le fait que nous avons en sortie qu'un seul objet
de chaque type. Il ne faut pas oublier que tout l'habillage fonctionne
sous ce que je vais appeler la loi de la recursivite, et donc, pour chaque
nouveau niveau que l'on va decouvrir lors de l'habillage, il faudra garder
en memoire les niveaux precedants pour ainsi avoir la possibilite de remonter
et de redescendre dans d'autres abimes inconnus. 
	
	L'habillage_brut ne represente rien d'autre que les objets tels qu'ils ont 
ete ecrits dans le fichier .obj. Cette facon de stocker les objets est 
primordiale car c'est ainsi qu'on pourra faire jouer la notion d'heritage. La 
resolution trop attive d'un objet ne me permettrai plus de savoir qui le 
constitue et je ne pourrai donc plus modifier un de ses sous-objets.
	C'est pour cela qu'il me faut une bdd en parallele contenant les objets
resolus, cette bdd est le hashtable Objet_html.
	Donc, pour chaque niveau visite, je lis les objets, je les stockes dans
habillage_brut, et je fais une dispersion d'objet pour creer Objet_html.

	Remarque: Un objet brut peu contenir des sous-objets qui le definisent,
alors qu'un objet net ne contient que du code HTML avec de la programmation
SGML (if then else).
	
	La lecture et la dispersion de l'habillage ont lieu dans le module
lecture.pl 
	fonctions:
		- lecture_habillage
		- dispersion_habillage

	La lecture et la construction de la bdd de l'arborescence virtuelle ont
lieu dans le module main.pl
	fonctions:
		-make_liens
		-fin_arb
		
	Une fois ces differentes bdd crees, on passe au vif du sujet, l'habillage
	
	
	*Habillage de la page HTML
	
	Cette partie concerne la totalite des modules du script, mais elle
debute tout de meme dans le module transfert.pl avec la fonction transfert.
	Cette fonction recoit comme parametre le nom du fichier, ainsi que les 
options d'execution et les differentes bdd pour la suite du traitement.
	Premiere chose a faire, lire le fichier, le netoyer un peu, essayer
de comprendre sa langue pour savoir s'il faut lui creer des clones dans une
autre langue, enfin, tout ce qu'il faut pour qu'il rentre en confiance, 
et a ce moment la, quand il est peinard et qu'il ne se l'attend pas,
on l'envoit vers la fonction super_habillage pour une seance de torture.

	Dans la fonction super_habillage, on commence par lire des possibles
fichiers particuliers (.dress et .obj particulier au fichier traite).
	On decoupe notre gentil fichier de facon a pouvoir tout recoller selon
le desir du fichier .dress. On convertit tout ce qui concerne l'ancien 
modele SGML de facon a le gerer en parallele avec le nouveau format 
(langue, liens, ...). On cherche a reconnaitre la langue du fichier a traiter
(ancien format: BI, FR, EN; nouveau format: .fr, .en, ...), et on commence la 
gestion des objets a remplacer au sein du fichier clone.

	Maintenant, il s'agit de gerer les objets dynamiques, dont on ne connait 
pas le contenu que lors du traitement du fichier a habiller.
	On commence par la gestion de l'arborescence virtuelle en remplacant 
les mots clefs tels que <PM.KEYWD.UP> par le nom du fichier correspondant
dans la langue correspondante. Tout ces noms se trouvent dans %Mes_Liens.
	On gerera ensuite la resolution des objets titre comme 
<PM.KEYWD.TITLEBACK>, pour cela on fait appele a la fonction cherche_title
qui se trouve dans le module title.pl.
	Cette fonction va lire les fichiers next, back et up, pour recuperer leur
titre.
	Apres on s'occupera de la gestion de la langue, de sorte a savoir si
un fichier est present dans telle ou telle langue, pour ainsi gerer les
messages du type WARNING.

   	Il s'agit maintenant de gerer la partie programmation des objets SGML.

   
    *Gestion de Tests

	Cela a lieu dans le module main.pl dans la fonction gestion_test. 
Cette fonction permet de gerer des tests imbriques. Le test en lui meme
est simple, il consiste en un simple if then else. Si le contenu de if 
n'est pas vide alors on garde le then, autrement on garde le else.
	Une fois cette gestion terminee, il ne nous reste plus qu'a effectuer
les dernieres modifications dans le fichier clone, puis a ecrire le fichier.

	*Ecriture du fichier clone
	
	On fait appelle a la fonction ecriture_destination qui se trouve dans 
le module ecriture.pl. Dans cette fonction, differentes petites choses
ont lieu avant l'ecriture elle meme, comme par exemple la relativisation 
des liens dans le fichier clone lors de la demande de l'option -a. Le
transfert des fichiers attaches au fichier clone du repertoire $Source vers
le reprtoire $Dest (images, videos, sons, ...) lors de l'utilisation de 
l'option -t. La recherche de la taille des images du fichier pour les tags
WIDTH et HEIGHT, qui a lieu dans le module image_size.pl.
	Une fois toutes ces petites choses effectues, on sauvegarde le fichier
ainsi obtenu.
	Il ne nous reste plus qu'a creer des fichier jumeaux, si cela nous est
demande.

	
	*Gestion de TWIN
	
	Une fois l'habillage termine, et qu'il faut creer un fichier twin,
on fait appel a la fonction gestion_mdp qui se trouve dans le module 
creation_lien.pl. Cette fonction ne se contente pas de creer une simple
copie du fichier source, car si le fichier twin doit etre cree dans une
autre arborescence, aucun lien relatif ne marcherai plus. Il faut donc
tout relativiser par rapport au repertoire destination, puis ecrire le 
resultat.



    *Gestion de la recursivite
	
	Elle a lieu dans le module recursivite.pl ou la fonction reper prend 
tout a sa charge. C'est ici qu'on lira tout nouveau fichier .dress, .obj et
.link pour tout nouveau repertoire etudie. Et pour chaque nouveau fichier 
source a habiller, elle appelera la fonction transfert du module transfert.pl


	*Le module ecriture_obj.pl
	
	Pour accelerer la lecture des fichier .obj pour une arborescence
qui est frequement habille, on pourra utiliser l'option -o pour que,
lors de notre premiere utilisation, le script savegarde un fichier appele
.obj_final_brut et un fichier .obj_final_net qui pourront etre utilises
les fois suivantes grace a l'option -u.

	*Le module utils.pl
	
	Ce module comporte un ensemble de petites fonctions facilitant la 
tache de l'habillage.
	Par exemple : 
		-creation_repertoires
		-debug_lien
		-make_relatif (declenche par l'option -a)
		etc...
		
	Ainsi s'acheve la dure tache d'un script d'habillage.
	
P.S. Pour tout desintectisage, voir commentaires dans le source.
