Tools/fr

Les Kiwix tools sont un ensemble de scripts (le plus souvent en Perl) ayant pour vocation d'aider à la création de contenus exploitables par le logiciel Kiwix.

Introduction

Kiwix est avant tout pensé comme un outil pour publier Wikipédia, mais tout est fait pour qu'il puisse faire plus comme :

• publier d'autres projets de la Fondation Wikimédia,
• d'autres contenus publiés avec l'aide de Mediawiki,
• ou même produit avec d'autres outils, typiquement d'autres moteurs de wiki (comme ici par exemple).

Le cœur de Kiwix étant le moteur de rendu HTML Gecko, l'objectif des Kiwix tools est de produire :

1. dans un premier temps un ensemble cohérent de fichier HTML statiques adjoints de leur nécessaires ressources : feuilles de style, scripts javascript, images, etc.
2. ensuite seulement, et à partir de ces fichiers statiques, de produire un fichier ZIM.

Stockage

Dans notre jargon un tel ensemble cohérent de contenus multimédias est appelé un dump ou encore un corpus. Ces dumps peuvent avoir plusieurs formes : pour Kiwix v0.5, c'était un simple répertoire, Moulinwiki a utilisé un format ou plusieurs fichiers étaient amalgamés et compressés avec bzip2, l'ensemble étant indexé dans une base Sqlite.

Aujourd'hui, Kiwix se base sur le format ZIM : un format tout en un (tout dans un fichier), qui permet à la fois d'avoir des accès rapides ainsi que une compression forte et paramétrable.

ZIM est un format créé par le projet openZIM dont Kiwix est avec d'autres l'initiateur. ZIM est lui-même basé sur un format plus ancien : ZENO. ZENO a été créé par la maison d'édition berlinoise Directmedia et a servi pour publié les CD-ROM de Wikipédia en allemand. Aujourd'hui, le format est abandonné, mais nous avons voulu continuer sont développement. L'avenir dira si cette initiative sera un succès, mais l'objectif est d'en faire un standard et ainsi simplifier pour chacun la problématique du stockage des dumps. Il est de toute manière déjà la meilleure solution libre.

Génération

La question de la méthode pour générer un dump n'est pas une question simple. Pour plusieurs raisons, Kiwix s'est jusqu'à présent concentré sur la manière de générer des dumps offrant une sélection ; même si la publication de dumps complets de Wikipédia reste clairement un objectif. Les Kiwix tools sont donc étudiés pour aider à la sélection, aider à répliquer des contenus issus du site en ligne sur un miroir pour ensuite à partir de ce miroir faire un dump.

Mais ce n'est pas la seule méthode pour générer un dump : on peut s'y prendre théoriquement de différentes manières. Voici une petite liste non exhaustive d'approches :

• Si l'on souhaite produire un dump complet, on peut :
  • prendre un dump HTML issu du gestionnaire du wiki, la Fondation Wikimédia en fournit ici par exemple.
  • choisir de monter un miroir du wiki, d'uploader les données (le code wiki entre autre) dans la base de données et de ensuite générer un dump soit-même. On peut trouver de telles données pour la Fondation Wikimedia ici. Dans le cas d'une sélection, on peut aussi les récupérer dynamiquement sur le site (puisque un wiki est open source).
  • si l'on souhaite générer directement (en récupérant les pages HTML) un dump à l'aide du site web avec un logiciel de type aspirateur.
• Si l'on souhaite un dump partiel, il faut faire une sélection des articles, ensuite la problématique est analogue que pour un dump complet.

Les contraintes sont assez nombreuses, voici de manière générale celles qu'il faut prendre en compte :

• les ressources matérielles du serveur,
• vos propres ressources matérielles,
• l'espace de stockage dont vous disposez pour le résultat final,
• comment faire la sélection si nécessaire.

Inventaire

Voici une liste non exhaustive des scripts disponibles (de nombreux d'entre eux sont spécifiques à Mediawiki) :

• backupMediawikiInstall.pl permet de faire un tgz d'une installe complète de Mediawiki (code + ressources + base de données).

• buildHistoryFile.pl permet à partir d'une liste d'articles et d'une instance en ligne de Mediawiki d'obtenir les historiques complet de chaque page de la liste.

• • extractContributorsFromHistoryFile.pl permet à partir d'extraire une liste des auteurs à partir des historiques obtenus avec buildHistoryFile.pl.

• buildContributorsHtmlPages.pl permet à partir d'un template et d'une liste d'auteurs de contruire un set de pages HTML comportant l'ensemble des auteurs de la liste.

• checkMediawikiPageCompleteness.pl vérifie si les pages d'une instance en ligne de Mediawiki sont complètes ; c'est à dire n'ont pas de dépendences (templates ou fichiers multimédiats) manquantes.

• checkPageExistence.pl vérifie à partir d'une liste et d'une instance de Mediawiki en ligne l'existence des pages. Cela peut-être pratique par exemple pour savoir quelle pages ont été répliquées.

• checkRedirects.pl vérifie si il n'y a pas des pages de redirections pointant vers du vide. Il faudrait aussi ajouter la vérification des pages de redirections se pointant mutuellement.

• installMediawiki.pl permet de mettre en ligne une instance de Mediawiki à partir de son code sans intervention humaine. Cela simule en fait le processus manuel d'installation.

• listAllImages.pl liste les images d'une instance de Mediawiki en ligne.

• listAllPages.pl liste toutes les pages d'une instance de Mediawiki en ligne.

• listCategoryEntries.pl liste les pages dans une catégorie de manière recursive.

• listRedirects.pl liste les redirections dans une instance de Mediawiki en ligne.

• mirrorMediawikiCode.pl permet de télécharger exactement la même version que celle utilisée par un site Mediawiki en ligne ; ceci est valable pour le code de Mediawiki ainsi que pour le code des extensions.

• mirrorMediawikiInterwikis.pl permet d'installer pour sa version locale de Mediawiki exactement les mêmes interwikis que pour une version de Mediawiki déjà en ligne.

• mirrorMediawikiPages.pl permet de copier tout page, ainsi que leurs dépendances (template et ressources multimédia) entre deux Mediawikis en ligne.

• modifyMediawikiEntry.pl permet de supprimer, vider, faire des remplacement sur une liste de pages présentent dans un Mediawiki en ligne.

• resetMediawikiDatabase.pl permet de vider une instance locale de Mediawiki de toutes ces pages.

• buildZimFileFromDirectory.pl permet à partir d'un repertoire contenus les fichiers HTML de créer un fichier ZIM.

• checkEmptyFilesInHtmlDirectory.pl permet de vérifier qu'un répertoire et ses sous répertoires ne contiennent pas de fichiers vides.

• dumpHtml.pl permet à partir d'une instance locale de Mediawiki de rendre statique toutes les pages ; c'est à dire créer un repertoire HTML avec toute ce qu'il faut dedans.

• launchTntreader.pl permet de lancer facilement le tntreader.

• optimizeContents.pl permet d'optimiser un répertoire avec les pages HTML et leurs ressources. Ce script appelle suivant l'extension Tidy HTML pour les fichiers HTML ou les Litte utils pour les images.

Générer un fichier ZIM de A à Z

Il existe de multiple manières d'utiliser ces outils et il est impossible de les lister tous. Cependant semble utile de présenter toutes les étapes nécessaires à la création d'un fichier ZIM. La outils présentés ici ne sont pas parfait, si vous expérimentez des difficultés durant une partie du processus, n'hésitez pas à prendre contact avec les développeurs à l'adresse email suivante : kiwix-developer _arobase_ lists.sourceforge.net (remplacer _arobase_ par @)

Étape 1 : choisir sa source

Si vous avez déjà vos fichiers HTML statiques (et le reste) alors tout ce qui suit ne sert à rien et il faut vous rendre directement à l'étape 6.

Sinon, il vous faut choisir un site web en ligne dont vous souhaitez copier les contenus. Lorsque ce choix sera fait, vérifier bien que ce site fonctionne avec Mediawiki car sinon les Kiwix tools ne pourront vous aider que pour une partie seulement du processus : à partir de l'étape 6.

Étape 2 : créer une instance "miroir" d'un site en ligne

Vous pouvez installer Mediawiki "normalement" à partir d'une archive ou à partir de SVN. Cependant la plupart du temps on cherche à avoir quelque chose le plus proche possible de la version qui est en ligne et que l'on souhaite reproduire. Il faut donc ici avoir une version précise de Mediawiki avec quelques extension particulières. Pour faire cela il existe le script mirrorMediawikiCode.pl. C'est une solution bien imparfaite, sachant que il n'est pas possible facilement de connaitre exactement les détails d'une installation de Mediawiki ; mais pour Wikipedia par exemple, ce script vous aidera facilement à avoir une version du code de Mediawiki et des extension proche de la version originale.

Une fois que votre code Mediawiki est présent, vous pouvez l'installer : ce qui signifie en gros le configure de manière basique et créer la base de donnée MySQL associée. installMediawiki.pl est le script adéquat pour faire cela en une seule ligne de commande.

Il est cependant impossible de savoir exactement comment un Mediawiki est configurer... Vous pouvez néanmoins vous inspirer de la configuration utiliser par le projet qui se trouve ici.

Étape 3 : copier les contenus de l'original au miroir

Copier des contenus d'un Mediawiki à un autre est la partie la plus délicate. C'est délicat, car il n'est pas toujours nécessaire de copier tous les contenus et que une page de Mediawiki pour s'afficher correctement peut dépendre de nombreux autres pages : une page peut avoir de nombreuses dépendances.

Pour faire simple, il existe deux types de dépendances : les médias (le plus souvent des images, mais cela peut aussi être des vidéos ou encore tout autre type de fichier) et d'autres pages de texte (le plus souvent des modèles - ou template en anglais). Avant de commencer à copier des contenus il faut vous demander si vous souhaitez copier seulement quelques articles ou l'ensemble des articles.

Si vous souhaitez copier l'ensemble des articles et que le Mediawiki que vous souhaitez reproduire est un de la Wikimedia Foundation (comme Wikipedia par exemple), alors le plus simple est de travailler avec les dumps XML et SQL fournis... Ce n'est pas simple mais c'est la méthode normale (voir cette aide). Un script perl sera écrit bientôt pour faciliter cette tâche (suivre ceci). Dans tous les cas il vous restera à copier les images par la suite (enfin si vous le souhaitez).

Si vous ne souhaitez reproduire qu'une sélection des articles, alors mirrorMediawikiCode.pl est le script qu'il vous faut. mirrorMediawikiCode.pl permet de reproduire une liste d'articles avec toutes les dépendances nécessaire au bon affichage des articles.

Étape 4 : préparer les contenus à votre façon

Créer un mirroir de Mediawiki est reproduire les contenus de l'instance originale de Mediawiki dans ce même mirroir est une méthode sophistiqué et complexe pour finalement avoir un contenu statique... Elle se doit donc d'offrir des avantages. Le plus grand avantage est que cela permet de faire toute sorte de manipulation pour modifier les contenus.

Il est par ce moyen aisé de supprimer certains modèles/templates qui pourraient être dans le cas d'une version statique inutiles voir gênant. C'est le cas de nombreux modèles méta. Pour cela il vous suffit d'établir une liste est d'utiliser le script modifyMediawikiEntry.pl (par exmple avec l'action empty pour vider certains modèles).

Avec ce même script il vous est aussi possible de supprimer toutes les images qui ne sont pas libres... Vous pourrez obtenir la liste à partir de la catégorie adéquate avec le script listCategoryEntries.pl.

Il peut être aussi souhaitable de rajouter les images manquantes. Pour avoir la liste, le script listDependences.pl peut vous être d'une grande aide... ensuite le traditionnel mirrorMediawikiPages.pl fera l'affaire avec les options adéquates.

Il pourra aussi vous être utilise d'avoir exactement les même interwikis que sur l'originale pour éviter de "poluer" votre articles avec des références à des interwikis inexistant. Pour cela le script mirrorMediawikiInterwikis.pl vous aidera.

Ceci ne reste que des exemples, d'autre modifications plus ou moins automatiques sont naturellement envisageables.

Étape 5 : créer une version statique du mirroir

La création d'une version statique du contenu d'un mediawiki se base toujours sur l'extension dumpHtml. C"est une extension standard de Mediawiki et qui est automatiquement installée si vous utilisée le script mirrorMediawikiCode.pl.

Pour que dumpHtml qui est imparfait et mal maintenu fonctionne comme nous le souhaitons de nombreuse modifications ont été apportées... mais tous cela doit être fait automatiquement normalement si vous utilisez mirrorMediawikiCode.pl..

Pour avoir une version statique il faut utiliser le script dumpHtml.pl et créer la version statique dans le répertoire "html" du répertoire root de mediawiki.

Étape 6 : optimiser les fichier HTML et médias associés

Nous recommandons d'optimiser les contenus avant la création d'un ZIM, cela peut permettre de gagner au moins 10% en taille. Pour cela il existe le script optimizeContents.pl qui permet de réduire la taille de nombreuses images sans perdre en qualité. Pour cela il faut installer auparavant littleutils.

Étape 7 : créer un fichier ZIM

Créer un ZIM ce fait simplement en utilisant buildZimFileFromDirectory.pl. Il faut pour que cela fonctionne que zimwriter soit installé ainsi que PostreSQL.

Étape 8 : créer un index de recherche du fichier ZIM

Pour créer un index de recherche, utiliser le binaire kiwix-index. Kiwix peut lui aussi simplement créer un index à partir de n'importe quel fichier ZIM.