Guide du développeur de la bibliothèque numérique Greenstone

David Bainbridge, Dana McKay et Ian H. Witten

Département d'informatique,
Université de Waikato, Nouvelle-Zélande

Greenstone est une suite logicielle destinée à la construction et à la distribution de collections de bibliothèques numériques. Cette suite fournit une nouvelle manière d'organiser l'information et de la publier sur l'Internet ou sur un cédérom. Greenstone est produit par le projet de bibliothèque numérique de Nouvelle-Zélande (dépendant de l'université de Waikato), et distribué en coopération avec l'UNESCO et le projet de bibliothèques pour l'humanité. C'est un logiciel Open Source, qu'on peut obtenir à l'URLhttp://greenstone.org, et qui est diffusé selon les termes de la licence publique générale de GNU.

Nous souhaitons nous assurer que ce logiciel fonctionne bien pour vous.
Faites-nous part, en anglais, de tout problème à l'adresse électronique
.

Greenstone gsdl-2.50  Mars 2004

À propos de ce manuel

Ce manuel explique le fonctionnement de Greenstone. Il vise ceux qui souhaitent personnaliser des collections et développer ou maintenir le logiciel.

La section 1 expose le processus de construction de collection vu de l'intérieur, comprenant la structure de répertoire, le format de document interne, et le fichier de configuration qui gouverne la structure de chaque collection. La section 2 décrit les parties de Greenstone qui traitent les documents source (et leurs méta-données) et dictent la manière dont on accède à l'information depuis l'interface utilisateur. Elle décrit également des composants logiciels «externes», distribués avec Greenstone. La section 3 explique la structure du système d'exécution de Greenstone, et donne aussi des détails du logiciel pour aider à comprendre son fonctionnement et comment le modifier pour correspondre à des besoins particuliers. La section 4 décrit les fichiers de configuration de Greenstone, et une annexe propose une introduction à la bibliothèque standard de patrons (templates) pour C++.

Lors de votre travail avec le logiciel Greenstone, vous trouverez peut-être des références à des fonctionnalités qui ne sont pas décrites dans le présent manuel, car Greenstone est en perpétuel développement. Pour en savoir plus sur les travaux en cours, rejoignez la liste de diffusion de Greenstone (vous trouverez les instructions pour cela sur le site webgreenstone.org).

Documents d'accompagnement

L'ensemble des documents de Greenstone comprend cinq volumes:

• Guide d'installation de la bibliothèque numérique Greenstone
• Guide de l'utilisateur de la bibliothèque numérique Greenstone
• Guide du développeur de la bibliothèque numérique Greenstone (ce document-ci)
• Bibliothèque numérique Greenstone: du papier à la collection
• Bibliothèque numérique Greenstone: Utilisation de "L'organizer"

Remerciements

Le logiciel Greenstone a vu le jour grâce à un effort de collaboration entre de nombreuses personnes. Rodger McNab et Stefan Boddie en sont les principaux architectes et développeurs. Des contributions ont été faites par David Bainbridge, George Buchanan, Hong Chen, Michael Dewsnip, Katherine Don, Elke Duncker, Carl Gutwin, Geoff Holmes, Dana McKay, John McPherson, Craig Nevill-Manning, Dynal Patel, Gordon Paynter, Bernhard Pfahringer, Todd Reed, Bill Rogers, John Thompson, et Stuart Yeates. D'autres membres du Projet de bibliothèque numérique de Nouvelle-Zélande ont également donné des conseils et inspiré les concepteurs du système: Mark Apperley, Sally Jo Cunningham, Steve Jones, Te Taka Keegan, Michel Loots, Malika Mahoui, et Lloyd Smith. Nous remercions aussi tous ceux qui ont contribué au développement des modules sous licence GNU GPL qui font partie de cette distribution: MG, GDBM, PDFTOHTML, PERL, WGET, WVWARE, XLHTML.

Contents

Comprendre le processus de construction d'une collection

Construire des collections depuis la ligne de commande

Les répertoires de Greenstone

Les processus d'import et de construction

Documents d'archives de Greenstone

Fichier de configuration de la collection

Exploitez vos documents au maximum

Greffons (plugins)

Classificateurs

Mettre en forme la sortie de Greenstone

Contrôler l'interface utilisateur de Greenstone

Le répertoire packages

Le système d'exécution de Greenstone

Structure des processus

Cadre conceptuel

Agencement du cadre conceptuel

Code source

Types de base de Greenstone

Serveur de collection

Le protocole

Le réceptionniste

Initialisation

Configurer son site Greenstone

Fichier de configuration principal

Fichier de configuration de site

A. La bibliothèque standard de patrons (templates) pour C++

A..1 Listes

A..2 Correspondances

Bibliographie

1 Comprendre le processus de construction d'une collection

Les utilisateurs finals de Greenstone peuvent construire des collections à l'aide du Collector, décrit dans la section 3 du Guide de l'utilisateur de la bibliothèque numérique Greenstone. Il facilite beaucoup la construction de collections sur le modèle de collections existantes, mais avec des contenus nouveaux. Cependant, il n'est pas réellement possible d'utiliser le Collector pour créer des collections avec des structures complètement nouvelles. Le Collector vous invite bien à éditer le fichier de configuration de la collection, qui gouverne cette structure de collection, mais il faut très bien connaître Greenstone pour pouvoir y effectuer des modifications radicales et efficaces. La présente section vous explique ce qu'il faut savoir pour opérer ainsi. Elle décrit également la structure de répertoire de Greenstone et le format interne de stockage des documents.

Tout au long de ce manuel nous supposerons que vous avez installé Greenstone sur votre ordinateur, que ce dernier fonctionne sous Windows ou sous Unix. Si tel n'est pas encore le cas vous devriez consulter le Guide d'installation de la bibliothèque numérique Greenstone. Le nom GSDLHOME représentera le répertoire racine de Greenstone, qui s'appelle %GSDLHOME% sur des systèmes Windows et $GSDLHOME sur des systèmes Unix. On détermine ce répertoire pendant la procédure d'installation.

1.1 Construire des collections depuis la ligne de commande

Commençons par décrire pas à pas les opérations nécessaires pour construire une collection depuis la ligne de commande, ce qui facilitera la compréhension du processus. Bien sûr, c'est le Collector qu'il faut plutôt utiliser pour construire des collections de manière plus agréable. La collection que nous prenons en exemple est l'une des collections distribuées sur le cédérom du logiciel Greenstone, et elle contient les pages web personnelles de nombreux contributeurs au projet de bibliothèque numérique de Nouvelle-Zélande et au logiciel Greenstone.

Les sections suivantes détaillent la construction sous Windows et sous Unix. En réalité, les deux se ressemblent presque complètement -- ne lisez que celle qui concerne votre système. Lorsque vous suivrez ces étapes, vous penserez peut-être que certaines opérations sont mystérieuses ou des arcanes, mais ne les en suivez pas moins fidèlement -- elles prendront tout leur sens plus tard. Suivra un bref résumé des différences entre les processus de construction sous les deux systèmes.

Construire des collections sous Windows

Le premier défi lors de la construction d'une collection à la ligne de commande sous Windows, c'est de parvenir à l'«interpréteur de commandes», qui est l'endroit où l'on tape les commandes. Dans le menu Démarrer ou le sous-menu Programmes, recherchez une ligne Invite MS-DOS, Invite DOS, ou Interpréteur de commandes. Si vous ne trouvez rien de tel, invoquez l'entrée Exécuter et tentez de taper command (ou cmd) dans la boîte de dialogue qui va apparaître. Si rien de tout ceci ne fonctionne, faites-vous assister par une personne qui s'y connaît, telle que votre administrateur système.

Rendez-vous dans le répertoire d'installation de Greenstone. En supposant que Greenstone a été installé dans l'emplacement standard, vous vous y rendrez en tapant:

Les apostrophes doubles sont nécessaires à cause de l'espace dans Program Files. Tapez ensuite à l'invite:

Ce fichier de commandes (que vous pouvez lire si vous en avez la curiosité) explique au système où trouver les programmes de Greenstone [1]. Si lors de votre session à l'invite de commandes DOS, vous souhaitez revenir au répertoire racine de Greenstone, vous pourrez toujours ce faire en tapant cd "%GSDLHOME%" (ici encore, les apostrophes doubles sont nécessaires: elles sont dues à la présence d'espaces dans le nom de fichier). Si vous fermez votre fenêtre DOS et en ouvrez une autre, il faudra de nouveau invoquer le fichier setup.bat.

Vous avez maintenant la possibilité de compiler, construire, et construire à nouveau des collections. Le premier programme que vous allons examiner est le programme Perl mkcol.pl, dont le nom signifie «make a collection» (compiler une collection). Commencez par exécuter le programme en tapant perl -S mkcol.pl pour obtenir à l'écran une description de la syntaxe et une liste des arguments possibles -- si votre environnement Windows est configuré de manière à associer l'application Perl aux fichiers se terminant en .pl, il vous suffira de taper mkcol.pl pour obtenir ce résultat. Comme vous pourrez le lire dans le message qui apparaît, l'unique argument obligatoire est creator, qui sert à spécifier qui a construit la collection.

Utilisons cette commande pour créer les fichiers et sous-répertoires initiaux nécessaires à notre collection des pages personnelles des membres du projet de bibliothèque numérique Greenstone. Pour affecter à la collection le nom dlpeople («gens de la bibliothèque numérique» en anglais et en abrégé), j'ai tapé:

(on peut se contenter de tapermkcol.pl -creator me@cs.waikato.ac.nz dlpeoplesi Perl est associé aux extensions de fichiers en.pl). N'oubliez pas de remplacer mon adresse électronique par la vôtre!

Pour visualiser les fichiers nouvellement créés, on se déplace dans le répertoire de la collection en tapant:

creator             me@cs.waikato.ac.nz

maintainer          me@cs.waikato.ac.nz

public              true

beta                true

indexes             document:text

defaultindex        document:text

plugin              ZIPPlug

plugin              GAPlug

plugin              TEXTPlug

plugin              HTMLPlug

plugin              EMAILPlug

plugin              ArcPlug

plugin              RecPlug

classify            AZList -metadata "Title"

collectionmeta collectionname    "dlpeople"

collectionmeta iconcollection    ""

collectionmeta collectionextra   ""

collectionmeta .document:text    "documents "

On peut alors lister le contenu du répertoire en tapant dir. Il devrait s'y trouver sept sous-répertoires: archives, building, etc, images, import, index, et perllib.

Il faut maintenant peupler la collection d'échantillons de documents. Les documents source de la collection dlpeople se trouvent sur le cédérom de la distribution Greenstone dans le répertoire collectdlpeople. Insérez d'abord le cédérom dans le lecteur (par exemple, sous D). Copiez ensuite le contenu du répertoire Dcollectdlpeople dans le répertoire import de la collection dlpeople. Vous pouvez procéder comme suit:

Vous pouvez aussi taper la commande:

Dans le répertoire etc de la collection, on trouve un fichier appelé collect.cfg. Ouvrez-le dans votre éditeur de texte préféré -- edit est basique mais communément disponible. Il devrait ressembler à ce que présente la figure 1, qui montre le fichier de configuration de collection créé par la commande:

Nous sommes désormais disposés à «importer» la collection. Il s'agit du processus qui apporte les documents dans le système Greenstone, en normalisant le format des documents, la manière dont les méta-données sont spécifiées, et la structure de fichiers de stockage des documents. Tapez perl -S import.pl à l'invite pour obtenir une liste de toutes les options du programme d'import. L'option -removeold s'assure que tout document préalablement importé est effacé dans un premier temps.

Ne vous inquiétez pas du texte qui défile: il s'agit d'un compte-rendu de la progression de l'import. Sachez que l'import de cette collection prend environ cinq minutes sur une machine à 1 GHz, et d'autant plus longtemps sur des machines plus lentes. Vous remarquerez qu'il n'est pas besoin de se trouver dans les répertoires collect ou dlpeople lors de la saisie de cette commande: la variable GSDLHOME étant déjà positionnée, le logiciel Greenstone peut trouver tous les fichiers nécessaires.

Modifions désormais quelque peu le fichier de configuration de la collection pour en personnaliser la représentation. Donnons d'abord un nom à la collection. Il sera utilisé par les navigateurs web en tant que page de titre pour la première page de la collection, et servira d'icone de collection si aucune image n'est fournie. Remplacez la lignecollectionmeta collectionname "dlpeople"par quelque chose commecollectionmeta collectionname "Les membres du projet NZDL"(NZDL est l'acronyme anglais du projet de bibliothèque numérique de Nouvelle-Zélande: New Zealand Digital Library Project).

Ajoutez une description de votre collection entre les apostrophes doubles de la ligne collectionmeta collectionextra "". Elle servira de texte pour le paragraphe à propos sur la page d'accueil de la collection. J'ai personnellement ajouté: "Cette collection comprend les pages personnelles de certains membres du projet NZDL.". Il est important de saisir cette description sous la forme d'une seule ligne dans l'éditeur -- ne soyez pas tenté de revenir à la ligne si vous arrivez sur le bord droit de la fenêtre, mais continuez simplement à taper! -- sans quoi le fichier de configuration ne pourra pas être correctement analysé. Si vous souhaitez que votre collection puisse être utilisée avec différentes interfaces de langues, il est possible de faire en sorte que cette description dépende de la langue choisie: ce procédé est décrit dans la section 1.5, plus bas.

On peut retenir toute image utilisable dans un navigateur web en tant qu'icone de collection -- l'image que j'ai créée est présentée figure 2. Tapez l'emplacement de l'image entre les apostrophes doubles de la lignecollectionmeta iconcollection ""du fichier de configuration. On peut utiliser le raccourci _httpprefix_ pour remplacer le début d'une URL qui pointe vers une image située dans la zone de fichiers de Greenstone. Cela rend également les configurations plus portables. Vous pouvez par exemple taper:_httpprefix_/collect/dlpeople/images/icon.gifsi vous avez placé une image convenable dans le répertoire images de la collection (collectdlpeopleimages dans l'exemple qui nous intéresse).

Sauvegardez le fichier de configuration de la collection et refermez-le -- vous n'en aurez plus besoin au cours de ce didacticiel.

La prochain étape consiste à «construire» la collection, ce qui crée tous les index et fichiers qui lui permettront de fonctionner. Tapez perl -S buildcol.pl à l'invite pour obtenir la liste des options de construction de collection. Ces options sont présentées plus en détails dans la section section 1.3. Pour l'instant, nous nous contenterons des valeurs par défaut en tapant:

à l'invite. Ici non plus, ne vous inquiétez pas en voyant défiler le compte-rendu de progression.

«Activez» la collection comme suit:

sélectionnez le contenu du répertoire building de la collection dlpeople, et faites-le glisser dans le répertoire index.

Vous pouvez aussi effacer le répertoire index (et tout ce qu'il contient) en tapant la commande:

et rebaptiser ensuite le répertoire building en index avec:

Enfin, tapez:

en vue de futures reconstructions. Il est important de taper ces commandes dans le bon répertoire (à la différence des commandes mkcol.pl, import.pl et buildcol.pl de Greenstone). Si le répertoire actuel n'est pas dlpeople, tapez:cd "%GSDLHOME%\collect\dlpeople"avant de procéder à la séquence rd, ren, et mkdir donnée ci-dessus.

Vous devriez pouvoir accéder à la collection nouvellement construite depuis la page d'accueil de Greenstone. Il vous faudra réactualiser ou recharger cette page si elle était déjà ouverte dans votre navigateur, voire fermer le navigateur et le redémarrer (pour éviter les problèmes de tampon ou cache). Il se peut aussi, dans le cas où vous utilisez la version «Bibliothèque locale» de Greenstone, que vous deviez redémarrer le programme library. Pour visualiser la nouvelle collection, cliquez sur l'image. Le resultat devrait alors ressembler à la figure 3.

Si nous nous résumons, l'ensemble des commandes tapées pour produire la collection dlpeople sont:

Construire des collections sous Unix

Commencez par vous rendre dans le répertoire d'installation de Greenstone. Si par exemple Greenstone a été installé dans l'emplacement standard, dans votre répertoire personnel, vous vous y rendrez en tapant:

Tapez ensuite à l'invite:

Ces fichiers de commandes (que vous pouvez lire si vous en avez la curiosité) expliquent au système où trouver les programmes de Greenstone. Si lors de votre session à l'interpréteur de commandes, vous souhaitez revenir au répertoire racine de Greenstone, vous pourrez toujours ce faire en tapant cd $GSDLHOME.

Si vous ignorez le type d'interpréteur de commandes que vous utilisez, tapez echo $0 à l'invite -- cela affichera l'information recherchée. Si vous utilisez un autre interpréteur de commandes, demandez conseil à votre administrateur système.

Après avoir chargé le bon fichier de réglages, vous avez maintenant la possibilité de compiler, construire, et construire à nouveau des collections. Le premier programme que vous allons examiner est le programme Perl mkcol.pl, dont le nom signifie «make a collection» (compiler une collection). Commencez par exécuter le programme en tapant simplement mkcol.pl pour obtenir à l'écran une description de la syntaxe et une liste des arguments possibles. Comme vous pourrez le lire dans le message qui apparaît, l'unique argument obligatoire est creator, qui sert à spécifier qui a construit la collection.

Utilisons cette commande pour créer les fichiers et sous-répertoires initiaux nécessaires à notre collection des pages personnelles des membres du projet de bibliothèque numérique Greenstone. Pour affecter à la collection le nom dlpeople («gens de la bibliothèque numérique» en anglais et en abrégé), j'ai tapé:

N'oubliez pas de remplacer mon adresse électronique par la vôtre!

Pour visualiser les fichiers nouvellement créés, on se déplace dans le répertoire de la collection en tapant:

On peut alors lister le contenu du répertoire en tapant ls. Il devrait s'y trouver sept sous-répertoires: archives, building, etc, images, import, index, et perllib.

Il faut maintenant peupler la collection d'échantillons de documents. Les documents source de la collection dlpeople se trouvent sur le cédérom de la distribution Greenstone dans le répertoire collect/dlpeople. Pour lire des informations sur un cédérom depuis Linux, insérez le disque dans le lecteur et tapez

à l'invite (cette commande peut varier d'un système à l'autre). Une fois monté, le cédérom peut s'utiliser comme tout autre répertoire; vous pouvez donc taper ls /cdrom/collect. Voilà qui devrait révéler un répertoire dlpeople sur le cédérom.

Copiez ensuite le contenu du répertoire /cdrom/collect/dlpeople dans le répertoire GSDLHOME/collect/dlpeople/import. Pour ce faire, tapez la commande:

puis tapez

pour fermer le lecteur de cédérom.

Dans le répertoire etc de la collection, on trouve un fichier appelé collect.cfg. Ouvrez-le dans votre éditeur de texte préféré -- emacs est un éditeur populaire sous Linux.Il devrait ressembler à ce que présente la figure 1, qui montre le fichier de configuration de collection créé par la commande:mkcol.pl -creator me@cs.waikato.ac.nz dlpeople

Nous sommes désormais disposés à «importer» la collection. Il s'agit du processus qui apporte les documents dans le système Greenstone, en normalisant le format des documents, la manière dont les méta-données sont spécifiées, et la structure de fichiers de stockage des documents. Tapez import.pl à l'invite pour obtenir une liste de toutes les options du programme d'import. L'option -removeold s'assure que tout document préalablement importé est effacé dans un premier temps.

Ne vous inquiétez pas du texte qui défile: il s'agit d'un compte-rendu de la progression de l'import. Sachez que l'import de cette collection prend environ cinq minutes sur une machine à 1 GHz, et d'autant plus longtemps sur des machines plus lentes. Vous remarquerez qu'il n'est pas besoin de se trouver dans les répertoires collect ou dlpeople lors de la saisie de cette commande: la variable GSDLHOME étant déjà positionnée, le logiciel Greenstone peut trouver tous les fichiers nécessaires.

Modifions désormais quelque peu le fichier de configuration de la collection pour en personnaliser la représentation. Donnons d'abord un nom à la collection. Il sera utilisé par les navigateurs web en tant que page de titre pour la première page de la collection, et servira d'icone de collection si aucune image n'est fournie. Remplacez la lignecollectionmeta collectionname "dlpeople"par quelque chose commecollectionmeta collectionname "Les membres du projet NZDL"(NZDL est l'acronyme anglais du projet de bibliothèque numérique de Nouvelle-Zélande: New Zealand Digital Library Project).

Ajoutez une description de votre collection entre les apostrophes doubles de la ligne collectionmeta collectionextra "". Elle servira de texte pour le paragraphe «à propos» sur la page d'accueil de la collection. J'ai personnellement ajouté: "Cette collection comprend les pages personnelles de certains contributeurs au projet NZDL.". Il est important de saisir cette description sous la forme d'une seule ligne dans l'éditeur -- ne soyez pas tenté de revenir à la ligne si vous arrivez sur le bord droit de la fenêtre, mais continuez simplement à taper! -- sans quoi le fichier de configuration ne pourra pas être correctement analysé. Si vous souhaitez que votre collection puisse être utilisée avec différentes interfaces de langues, il est possible de faire en sorte que cette description dépende de la langue choisie: ce procédé est décrit dans la section 1.5, ci-dessous.

On peut retenir toute image utilisable dans un navigateur web en tant qu'icone de collection -- l'image que j'ai créée est présentée figure 2. Tapez l'emplacement de l'image entre les apostrophes doubles de la lignecollectionmeta iconcollection ""du fichier de configuration. On peut utiliser le raccourci _httpprefix_ pour remplacer le début d'une URL qui pointe vers une image située dans la zone de fichiers de Greenstone. Cela rend également les configurations plus portables. Vous pouvez par exemple taper:_httpprefix_/collect/dlpeople/images/icon.gifsi vous avez placé une image convenable dans le répertoire images de la collection (collect/dlpeople/images dans l'exemple qui nous intéresse).

Sauvegardez le fichier de configuration de la collection et refermez-le -- vous n'en aurez plus besoin au cours de ce didacticiel.

La prochain étape consiste à «construire» la collection, ce qui crée tous les index et fichiers qui lui permettront de fonctionner. Tapez buildcol.pl à l'invite pour obtenir la liste des options de construction de collection. Ces options sont présentées plus en détails dans la section section 1.3. Pour l'instant, nous nous contenterons des valeurs par défaut en tapant:

à l'invite. Ici non plus, ne vous inquiétez pas en voyant défiler le compte-rendu de progression.

«Activez» la collection en déplaçant toutes les données qui viennent d'être placées dans le répertoire building vers le répertoire index. Si vous avez déjà construit cette collection de par le passé, commencez d'abord par enlever l'ancien répertoire index avec la commande:

(en supposant que vous vous trouvez alors dans le répertoire dlpeople). Puis tapez

Windows	Linux
Exécutersetup.batpour rendre disponibles les programmes de Greenstone	Chargersetup.bashousetup.cshpour rendre les programmes disponibles
Copier les fichiers depuis le cédérom en utilisant le gestionnaire de fichiers graphique ou des commandes DOS	Copier les fichiers depuis le cédérom en utilisantmountet d'autres commandes Unix
L'ancien index de collection est remplacé en tapantrd /s indexpuisren building indexsuivis demkdir building, ou en utilisant le gestionnaire de fichiers graphique	L'ancien index de collection est remplacé en tapantrm —r index/*puismv building/* index

Vous devriez pouvoir accéder à la collection nouvellement construite depuis la page d'accueil de Greenstone. Il vous faudra réactualiser ou recharger cette page si elle était déjà ouverte dans votre navigateur, voire fermer le navigateur et le redémarrer (pour éviter les problèmes de tampon ou cache). Pour visualiser la nouvelle collection, cliquez sur l'image. Le resultat devrait alors ressembler à la figure 3.

Si nous nous résumons, l'ensemble des commandes tapées pour produire la collection dlpeople sont:

Différences entre Windows et Unix

Les processus de construction de collection sont très similaires sous Unix et sous Windows, mais quelques petites différences demeurent, différences que nous avons résumées dans la table 1.

1.2 Les répertoires de Greenstone

La figure 4 montre la structure du répertoire GSDLHOME. La table 2 donne une brève description du contenu de chacun des répertoires représentés dans le diagramme. Certains répertoires seront plus détaillés plus loin dans le manuel -- utilisez le guide des sections de la table 2 pour savoir où aller chercher des informations supplémentaires.

	Contenu	Section
bin	Code exécutable, comprenant des binaires dans le répertoire portant le nom de votre système d'exploitation.	—
bin/script	Scripts Perl utilisés pour la création et la construction de collections (tels queimport.pletbuildcol.pl). Pour obtenir une description de ces programmes, tapez leur nom à l'invite de commandes.	1.3
perllib	Modules Perl utilisés au moment de l'import et de la construction (tels que les greffons, ouplugins)	2.1
perllib/plugins	Code Perl pour les greffons (plugins) de traitement de documents.	2.1
perllib/classify	Code Perl pour les classificateurs (tels que le code AZList, qui crée une liste de documents en se basant sur l'ordre alphabétique d'un attribut.)	2.2
cgi-bin	Tous les scripts CGI de Greenstone, qui seront déplacés vers le répertoirecgi-bindu système.	—
tmp	Répertoire utilisé par Greenstone pour le stockage des fichiers temporaires.	—
etc	Fichiers de configuration, journaux d'initialisation et d'erreur, bases de données d'autorisation des utilisateurs.	—
src	Code C++ utilisé pour servir des collections sur un serveur web.	3
src/colservr	Code C++ pour servir des collections—pour répondre aux requêtes et ce genre de choses.	3.7
src/recpt	Code C++ pour obtenir des requêtes depuis l'interface utilisateur et mettre en forme les réponses aux requêtes pour cette interface.	3.9
packages	Code source des paquetages logiciels externes à Greenstone mais utilisés par ce dernier.	2.5
packages/mg	Code source de MG, logiciel de compression et d'indexation utilisé par Greenstone.	2.5
mappings	Tables de correspondance Unicode (comme par exemple pour le jeu de caractères chinois GB).	—
macros	Les fichiers de macros utilisés pour l'interface utilisateur.	2.4
collect	Collections servies par cette copie de Greenstone.	1.1
lib	Code C++ utilisé à la fois par le serveur de collection et par le réceptionniste.	3.1
images	Images utilisées dans l'interface utilisateur.	—
docs	Documentation.	—

1.3 Les processus d'import et de construction

Dans le processus de construction de collection décrit à la section 1.1, on utilise une commande pour importer des documents (import.pl) et une autre commande pour construire la collection (buildcol.pl). Nous détaillons dans la présente section ce que ces programmes font et les options qu'ils acceptent. Nous utiliserons la variable nom_col pour nous référer à la collection en cours de construction ou d'import.

Les processus d'import et de construction sont très similaires, ce qui explique le nombre d'options communes qu'ils comptent, options décrites dans la table 3 (souvenez-vous que pour obtenir la liste des options acceptées par tout script Greenstone, il suffit de taper son nom seul, sans argument, à l'invite de commandes).

	Argument	Fonction
-verbosity	Nombre de 0 à 3	Contrôle la quantité d'informations sur le processus qui sont affichées sur la sortie d'erreur standard: «0» en donne un peu, «3» en donne beaucoup.
-archivedir	Nom de répertoire	Spécifie où les fichiers d'archives de Greenstone sont stockés, c'est-à-dire oùimport.plles enregistre et oùbuildcol.plles trouve. La valeur par défaut estGSDLHOME/collect/nom_col/archives.
-maxdocs	Nombre >0	Nombre maximal de documents à importer ou à construire. Option utile lors de tests de fichiers de configuration d'une nouvelle collection, ou de nouveaux greffonsplugins
-collectdir	Nom de répertoire	Spécifie où la collection se trouve. La valeur par défaut estGSDLHOME/collect
-out	Nom de fichier	Spécifie un fichier où écrire tous les messages produits, le comportement par défaut étant de les afficher sur la sortie d'erreur standard (c'est-à-dire l'écran). Option utile lorsque l'on travaille avec des niveaux de débogage.
-keepold	Aucun	N'efface pas le résultat de l'ancienne opération d'import ou de construction. Dans le cas de l'import, ceci signifie que l'on n'efface pas le contenu du répertoirearchives; dans le cas de la construction, ceci signifie que l'on n'efface pas le contenu du répertoirebuilding.
—debug	Aucun	Affiche la sortie du greffonpluginsur la sortie standard.

Le processus d'import

Le processus d'import a pour but principal de convertir les documents depuis leur format d'origine vers le format d'archivage de Greenstone utilisé de manière interne par Greenstone, et d'écrire un fichier de compte-rendu (archives.inf) qui sera utilisé lors de la construction de la collection. Le programme import.pl a besoin de connaître les greffons (plugins) à utiliser, et de savoir où trouver les fichiers des documents originaux. La table 3 montre les options communes aux processus d'import et de construction; la table 4 montre les options propres au processus d'import. L'option OIDtype mérite quelques explications. Chaque document dispose d'un identifiant d'objet associé, ou OID (Object IDentifier). La meilleure façon de calculer un tel identifiant est de calculer une somme de contrôle («hacher») le contenu du document (c'est la méthode hash). Cependant, cette méthode étant lente, il est possible de choisir une solution plus simple, incrémentale, qui se contente de numéroter les documents séquentiellement dans leur ordre de fourniture (c'est la méthode incremental). Vous pouvez utiliser la méthode incremental pour aller plus vite, mais utilisez la méthode hash si vous avez l'intention d'ajouter des documents à votre collection plus tard, sans recommencer tout le processus d'import.

	Argument	Fonction
-importdir	Nom de répertoire	Spécifie où trouver les contenus à importer. La valeur par défaut est Defaults toGSDLHOME/collect/nom_col/import.
-removeold	Aucun	Efface le contenu du répertoire archivesavant l'import.
-gzip	Aucun	Compresse l'archive de documents Greenstone produite parimport(ZIPPlugdoit faire partie de la liste des plugins greffons, et le programmegzipdoit être installé sur votre machine).
-groupsize	Nombre >0	Nombre de documents à rassembler dans un fichier d'archive de Greenstone. La valeur par défaut est 1 (c'est-à-dire que chaque fichier ne renferme qu'un document).
—sortmeta	Nom de balise de méta-données	Trie les documents par ordre alphabétique selon le contenu de la balise de méta-données. Cette fonctionnalité est désactivée si la collection compte plus d'un groupe (c'est-à-dire quegroupsize>1).
-OIDtype	hashou incremental	Méthode de création des OIDspour les documents:hashcalcule une somme de contrôle du contenu mais est lente;incrementalse contente d'affecter des numéros de documents de manière séquentielle, elle est donc plus rapide.

La figure 5 représente le processus d'import tel qu'implémenté par le programme import.pl. Chaque ovale représente un module utilisé pour mener à bien les tâches relatives à une partie spécifique du système Greenstone. On peut trouver tous ces modules dans le répertoire GSDLHOME/perllib.

Pour l'étape 3, remarquez que des variables d'import telles que importdir et archivedir peuvent être positionnées dans le fichier de configuration de la collection ou depuis la ligne de commande. Si elles sont positionnées dans la ligne de commande, toute valeur spécifiée dans le fichier de configuration sera ignorée.

L'étape 6 voit la création du fichier d'information d'archives (archives.inf).

L'étape 7 crée un objet qui saura où sauvegarder les documents, et qui suivra toute instruction particulière de sauvegarde (telle que sortmeta, qui trie les documents selon une balise de méta-données spécifiée).

La plupart du travail effectué par le processus d'import est en fait accompli par les greffons (plugins), qui sont appelés par le module plugin. Ce module met en place un pipe-line des greffons spécifiés dans le fichier de configuration de collection. Il gère aussi l'écriture des documents d'archive de Greenstone (en utilisant un objet document).

Le processus de construction

Lors du processus de construction le texte est compacté, et les index de corps du texte spécifiés dans le fichier de configuration de collection sont créés. De plus, les informations relatives à la collection qui apparaîtront sur le web sont pré-calculées et incorporées dans la collection -- il s'agit par exemple des informations relatives aux icones et aux titres, ainsi que des informations produites par des classificateurs. Le programme buildcol.pl partage de nombreuses options avec import.pl; elles sont détaillées dans la table 3. La table 5 présente les options qui lui sont propres.

	Argument	Fonction
-builddir	Nom de répertoire	Spécifie où trouver le résultat de la construction (la valeur par défaut estGSDLHOME/collect/nom_col/building).
-index	Nom d'index (ex. section:Title)	Spécifie quels index construire. La valeur par défaut est l'ensemble des index indiqués dans le fichier de configuration de la collection.
-allclassifications	Aucun	Empêche le processus de construction d'effacer les classifications qui ne contiennent aucun document (comme par exemple la classification «X» dans les titres si aucun document n'a un titre commençant par la lettre «X»).
-create_images	Aucun	Crée automatiquement les icones de collection (pour utiliser ceci, il faut avoir installé GIMP et le module Perl Gimp).
-mode	all, compress_text, infodb, or build_index	Détermine ce que le processus de construction doit faire (la valeur par défaut estall). Le modeAlleffectue une construction complète,compress_textse contente de compacter le texte du document,infodbcrée une base de données des informations relatives à la collection—nom, fichiers, fichiers associés, informations de classification etc.—etbuild_indexconstruit les index spécifiés dans le fichier de configuration de collection ou à la ligne de commande.
—no_text		Ne stocke pas de texte compacté. Cette option est utile pour minimiser la taille des index construits si l'on souhaite toujours afficher les documents originaux au moment de l'exécution.

Le diagramme de la figure 6 représente l'exécution du programme buildcol.pl. De nombreuses étapes sont communes avec le processus d'import. La première étape qui diffère est l'étape 4 (à gauche sur la figure). Cette étape n'est effectuée que si l'option create_images a été activée. Les images sont alors créées et consignées dans le fichier de configuration de collection à l'aide d'une fonction du script buildcol.pl. Pour que ceci fonctionne correctement, il faut avoir installé et configuré convenablement GIMP (GNU Image-Manipulation Program, programme de manipulation d'images de GNU) et le module Perl Gimp. Il faut aussi disposer d'un accès en écriture (et en lecture) sur le fichier de configuration de collection.

L'étape 5 contrôle d'abord l'existence ou non d'une procédure de construction propre à la collection. Certaines collections impliquent des traitements particuliers au moment de la construction, auquel cas il faut écrire un constructeur propre à la collection et le placer dans son répertoire perllib, sous le nom de la collection auquel on aura concaténé la chaîne «builder» (constructeur). Les constructeurs propres aux collections héritent de mgbuilder. Dans l'étape 5 le constructeur (qu'il s'agisse du constructeur par défaut ou d'un constructeur propre à la collection) est initialisé avec des informations telles que le nombre de documents à inclure, s'il faut ou non garder l'ancienne version de la collection, et où les répertoires building et archive sont localisés.

L'étape 6 est l'étape de construction, au cours de laquelle le texte des documents est compacté et indexé, les titres et les icones de collection sont stockés dans la base de données d'informations de la collection, et les structures de données sont construites pour supporter les classificateurs appelés par les greffons (plugins) de la collection. Toutes ces étapes sont menées à bien par mgbuilder (ou un constructeur propre à la collection), qui lui-même utilise MG (Managing Gigabytes (gérer les giga-octets), voir Wittenet al., 1999), logiciel de compression et d'indexation.

L'option mode permet de spécifier les portions de collection à construire, mais par défaut tout est construit: texte compacté, index, et base de données d'informations de la collection.

Pour publier une collection sur le web après construction, il faut la déplacer du répertoire building vers le répertoire index. Les collections ne sont pas construites directement dans le répertoire index car des collections volumineuses peuvent prendre plusieurs heures ou jours à construire. Il est important que le processus de construction n'affecte pas une copie existante de la collection tant qu'il n'est pas terminé.

1.4 Documents d'archives de Greenstone

Tous les documents source sont importés dans le système Greenstone après conversion dans le format d'archivage de Greenstone. C'est un style XML qui divise les documents en sections, et qui peut renfermer des méta-données au niveau du document ou de chaque section. Vous ne devriez pas avoir à créer des fichiers d'archives de Greenstone manuellement -- c'est le travail des greffons (plugins) de traitement de documents décrits dans le chapitre suivant. Il est cependant utile de comprendre le format des fichiers Greenstone, et c'est pourquoi nous le décrivons ici.

En XML, les mots-clefs sont entourés de chevrons pour le balisage. Le format d'archivage de Greenstone encode des documents déjà en HTML, et tout caractère <, >, ou " compris dans le texte original est échappé grâce à la convention standard &lt;, &gt;, et &quot;.

<!DOCTYPE GreenstoneArchive [

<!ELEMENT Section (Description,Content,Section*)>

<!ELEMENT Description (Metadata*)>

<!ELEMENT Content (#PCDATA)>

<!ELEMENT Metadata (#PCDATA)>

<ATTLIST Metadata name CDATA #REQUIRED>

]>

<?xml version="1.0"?>

<!DOCTYPE GreenstoneArchive SYSTEM

"http://greenstone.org/dtd/GreenstoneArchive/1.0/GreenstoneArchive.dtd" >

<Section>

<Description>

<Metadata name= "gsdlsourcefilename">ec158e.txt</Metadata>

<Metadata name= "Title">Freshwater Resources in Arid Lands</Metadata>

<Metadata name= "Identifier">HASH0158f56086efffe592636058</Metadata>

<Metadata name= "gsdlassocfile">cover.jpg:image/jpeg:</Metadata>

<Metadata name= "gsdlassocfile">p07a.png:image/png:</Metadata>

</Description>

<Section>

<Description>

<Metadata name= "Title">Preface</Metadata>

</Description>

<Content>

This is the text of the preface

</Content>

</Section>

<Section>

<Description>

<Metadata name= "Title">First and only chapter</Metadata>

</Description>

<Section>

<Description>

<Metadata name= "Title">Part 1</Metadata>

</Description>

<Content>

This is the first part of the first and only chapter

</Content>

</Section>

<Section>

<Description>

<Metadata name= "Title">Part 2</Metadata>

</Description>

<Content>

This is the second part of the first and only chapter

</Content>

</Section>

</Section>

</Section>

La première partie de la figure 7a donne la définition de type de document (DTD) pour le format d'archivage de Greenstone. Pour simplifier, un document est divisé en éléments Section, et les sections peuvent être imbriquées. Chaque Section renferme une Description qui comprend zéro ou plusieurs éléments Metadata (méta-données), et un élément Content (contenu), qui peut être vide, et qui renferme les données du document à proprement parler. À chaque élément Metadata on associe un attribut de nom (dont le nom est libre), et des données textuelles. En XML, PCDATA signifie «parsed character data» (données de type caractère analysées), c'est-à-dire du texte, tout simplement.

La deuxième partie de la figure 7b montre un document simple écrit dans ce format, qui est un petit livre avec deux images associées. Le livre consiste en deux sections appelées respectivement Préface et Premier et unique chapitre, la deuxième section se divisant en deux sous-sections. Remarquez qu'il n'existe aucune notion de «chapitre» en tant que tel: un chapitre est simplement représenté comme une section de premier niveau.

gsdlsourcefilename	Fichier original à partir duquel on a généré le fichier d'archive de Greenstone
gsdlassocfile	Fichier associé au document (un fichier d'image par exemple)

La balise <Section> dénote le début de chaque section de document, et la balise fermante correspondante (</Section>) marque la fin de cette section. À la suite de chaque balise <Section> on trouve un élément <Description>. S'y trouve un nombre quelconque d'éléments <Metadata>. On peut ainsi associer différentes méta-données à différentes sections du document. La plupart de ces méta-données sont des types particuliers de méta-données tels que <Title> (titre). Les deux valeurs de l'attribut name (nom) montrées dans la table 6 reçoivent de Greenstone un traitement particulier; toutes les autres sont considérées comme des méta-données attachées à cette section.

Dans certaines collections les documents dont divisés en pages. Ces dernières sont alors traitées comme des sections. Un livre peut par exemple disposer de sections de premier niveau qui correspondent à des chapitres, au sein desquels on trouvera un certain nombre de «sections» qui correspondront en réalité aux différentes pages du chapitre.

Méta-données de document

Les méta-données sont des informations de description associées à un document telles que l'auteur, le titre, la date, des mots-clefs, etc. Nous avons déjà signalé que les méta-données étaient stockées avec les documents. En observant la figure 7a, on remarque que les balises <Metadata> spécifient le nom du type de méta-données, et lui donnent une valeur. On a par exemple la ligne <Metadata name="Title">Premier et unique chapitre</Metadata> dans la deuxième partie de la figure 7b -- le titre d'un document est une méta-donnée qui lui est associée. On utilise le standard de méta-données Dublin Core pour définir des types de méta-données (Dublin Core, 2001; Weibel, 1999; Thiele, 1997).

La table 7 montre les types disponibles dans le standard, les étoiles signalant les entrées disponibles à ce jour sur le site web de la bibliothèque numérique de Nouvelle-Zélande. Si aucun type ne décrit correctement un certain type de méta-données, on peut aussi utiliser des types de méta-données absentes du standard Dublin Core. La collection «Demo» contient par exemple les méta-données how to (comment faire) et Magazine.

Nom	Balise de méta-données	Définition
*Title	Title	Nom donné à la ressource
*Créateur	Creator	Entité principalement responsable de la fabrication du contenu de la ressource
*Thème et mots-clefs	Subject	Thème du contenu de la ressource
*Description	Description	Compte-rendu du contenu de la ressource
*Éditeur	Publisher	Entité responsable de la publication de la ressource
Contributeur	Contributor	Entité responsable de contributions au contenu de la ressource
*Date	Date	Date de publication de la ressource ou toute autre date importante associée à la ressource
Type de ressource	Type	Nature ou genre du contenu de la ressource
Format	Format	Représentation physique ou numérique de la ressource
*Identificateur de resource	Identifier	Référence univoque à la ressource dans un contexte donné: il s'agit de l'identifiant d'objet, ouOID
*Source	Source	Référence à une ressource d'où la présente ressource est tirée
*Langue	Language	Langue du contenu intellectuel de la ressource
Relation	Relation	Référence à une ressource liée
*Couverture	Coverage	Portée ou étendue du contenu de la ressource
Gestion des droits	Rights	Informations sur les droits attachés à la ressource ou dans celle-ci

Au coeur des documents d'archive de Greenstone

Le format d'archivage de Greenstone impose peu de structure aux documents individuels. Les document sont divisés en paragraphes. Ils peuvent être divisés hiérarchiquement en sections et en sous-sections, que l'on peut imbriquer jusqu'à une profondeur arbitraire. À chaque document est associé un identifiant de document ou OID -- ces derniers servant aussi à identifier les sections et les sous-sections par l'ajout de numéros de sections et de sous-sections, séparés par des points, à l'OID du document. On se référera par exemple à la sous-section 3 de la section 2 du document HASHa7 sous la forme HASHa7.2.3.

Quand on lit un livre dans une collection de Greenstone, la hiérarchie des sections est reportée dans la table des matières du livre. Les livres de la collection «Demo», par exemple, disposent d'une table des matières hiérarchique qui montre des chapitres, des sections, et des sous-sections, comme l'illustre la figure