Kolekti.org

[accueil]
Accueil[produits]
Produits[services]
Services[Télécharger]
Télécharger[documentation]
Documentation[contact]
Contact

kolekti.org

 

Description fonctionnelle de kOLEKTi

Ce document présente une description fonctionnelle de kOLEKTI Station Windows (version 0.3).

Environnement

Pour faire fonctionner kOLEKTi Station, les logiciels suivants sont nécessaires :

Installation

Téléchargez le fichier setup-kolektistation-win32_0.3.exe disponible sur le site www.kolekti.org et éxécutez-le sur votre disque local.

Lors de l'installation, spécifiez le répertoire où vous souhaitez installer l'application et la base documentaire.

L'éxécution de kOLEKTi (en fin d'installation ou en double-cliquant sur kolektiServer.exe) entraine le démarrage d'un serveur local.

Dans Firefox, tapez l’adresse http://localhost:8000 pour lancer kOLEKTi.

Cliquez sur "Se connecter à la base" et saisissez dans la fenêtre d'authentification les informations suivantes :

Après avoir validé, vous accédez à l'écran de connexion sur lequel est listé la base "minibase" qui est la base minimale installée par défaut.

Cliquez sur "minibase" pour accéder aux fichiers de la minibase.

Arrêt de l'application

La fermeture du navigateur n'arrête pas l'application, que vous soyez déconnecté ou non. Pour arrêter l'application, faire un clic droit sur l'icone "K" du systray (en bas à droite) et faire "Arrêter Kolekti Serveur".

Description générale

Les menus de kOLEKTi sont les suivants :

Processus de publication

Lorsque vous cliquez sur la commande "Lancer la fabrication" du menu Lancements, kOLEKTi opère successivement les opérations suivantes :

Identification des tâches de publication

Le menu Lancements comporte l'ensemble des lancements possibles, seuls les lancements sélectionnés sont pris en compte par kOLEKTi.

Chaque lancement étant composé d'un ou plusieurs ordres de publication, seuls les ordres actifs (case "Actif" cochée) sont pris en compte par kOLEKTi.

Assemblage et filtrage des modules

Pour chaque ordre actif , kOLEKTi va assembler et filtrer les modules référencés dans la trame, et produire un résultat appelé "document pivot", au format XHTML, qui contient toutes les informations structurelles utiles pour les scripts de sortie.

Lors du processus d'assemblage :

Publication au format de sortie

Si un script est listé dans l'ordre de publication, alors kOLEKTi traite le document pivot pour le transformer directement au format souhaité.

Il est aisé de transformer le XHTML en PDF (en associant une feuille de style CSS) à l'outils tels que PrinceXML (http://www.princexml.com/).

Un script en cours de développement pour transformer le XHTML en Aide en ligne au format Web (disponibilité prévue du script : avec la version 0.3 de kOLEKTi).

Configuration des scripts de sortie

Les scripts sont déclarés dans le fichier bases/_lib/pubscripts.xml

L'élément racine est <scripts>

Chaque script est décrit par un élement <pubscript> fils de la racine, il porte un attribut id unique (utilisé en interne par kolekti), un attribut type qui peut prendre les valeurs shell, plugin ou xsl.

Pubscript contient un élément obligatoire <name> qui est le nom affiché dans le menu de l'ordre de publication;

Les autre sous-élements sont fonction du type :

elements <stylesheet> : nom de la feuille de style (répertoire à déterminer, certainement dans la base), <out> nom du fichier de sortie (meme substitutions que shell).

Lancements

Le menu Lancements liste l'ensemble des ordres de publication et permet le lancement du processus d'assemblage à l'aide de la commande "Lancer la fabrication".

Les consignes de publication sont organisées en 2 niveaux :

Niveau 1 : Lancements

Un Lancement contient un ou plusieurs Ordres de publication. Le nom du Lancement et son contenu sont décidés par l'utilisateur, selon la typologie des produits et documents qu'il a à gérer.

Pour créer un nouveau Lancement (vide), utiliser la commande "Créer Lancement".

Il est également possible de dupliquer un Lancement existant, pour cela :

  1. Ouvrir le Lancement à dupliquer (en cliquant sur son nom)
  2. Dans le champ "Lancement" (en haut à droite), saisir le nom du Lancement à créer
  3. Cliquer sur Enregistrer

Niveau 2 : Ordres de publication

Pour accéder à un Ordre de publication, cliquer sur le nom du Lancement qui le contient.

Un Ordre de publication se caractérise par les éléments suivants :

Nom
Le nom de l'Ordre de publication est le seul champ visible lorsque tous les sous-menus sont repliés. Il est librement défini par l'utilisateur.
Prise en compte
Cocher la case "Actif" pour que l'Ordre de publication soit pris en compte lors du prochain assemblage.
Trame
Sélectionner dans la liste la trame selon laquelle l'assemblage sera effectué. La trame doit être préalablement créée dans le répertoire Trame.
Répertoire de publication
Saisir ici le nom du répertoire de publication. Le chemin peut contenir des syntaxes spéciales, remplacées automatiquement par les critères de publication. Exemple : Machine_M_/_LANG_ donnera lieu à la création d'un répertoire MachineXB12/fr/ (dans le menu Publication), si le critère de publication est M = XB12 et que la langue de publication est le français.
Feuille de style css
Sélectionner dans la liste la feuille de style qui sera associée au document pivot. La feuille de style doit être préalablement créée dans le répertoire Styles.
Script post-publication
Sélectionner dans la liste le script qui sera exécuté sur chaque document pivot produit. Les scripts sont déclarés dans le fichier bases/_lib/pubscripts.xml (voir description plus haut).
Langues de publication
kOLEKTi effectue une publication par langue cochée, sous réserve que les modules traduits figurent bien dans les répertoires de langues définis (dans le cas contraire un message d'alerte s'affiche lors de la publication).
La liste des langues et des zones géographiques est définie dans le fichier _conf.xml de la base. Note : l'édition de ce fichier au format Web est prévu pour les prochaines versions de kOLEKTi.
Critères
Rappel des critères définis dans la Trame référencée. Il est possible de surcharger localement les critères initiaux.

Modules

Définition

On appelle "module" un ensemble homogène d'informations, pouvant être appelé par une trame et constituer in fine une partie de la documentation publiée.

Format

Les modules sont au format XHTML 1.0 strict. Ils peuvent inclure l'ensemble des fonctionnalités de ce format, qui seront conservées par kOLEKTi lors de la phase d'assemblage et seront présentes dans le document pivot (également au format XHTML 1.0).

Les modules doivent être codés en UTF-8.

Contenu

Un module contient généralement plusieurs paragraphes, structurés ou non à l'aide de titres (h1, h2, etc.). L'auteur doit garder à l'esprit qu'il s'agit d'une structuration logique : un titre de niveau 1 (h1) peut devenir un titre de niveau 3 (h3) si le module est référencé au troisième niveau d'une Trame.

Le contenu doit être défini selon l'utilisation prévue en sortie. Ainsi un module pourra être assez volumineux et correspondre à un chapitre dans le cas d'une publication papier, alors qu'il sera plus court dans le cas d'une publication de type "aide en ligne".

Plus un module est petit, plus il aura de chances d'être ré-utilisé dans différents contextes et différentes publications. En revanche, la gestion d'une multitude de "micro-modules" devient vite compliquée. C'est pourquoi nous préconisons des modules complets par sujet (ex : consignes de sécurité), quitte à utiliser de manière intensive les conditions de publication à l'intérieur des modules.

Style

Il est tout a fait possible d'associer au module une feuille de style pour, par exemple, mettre en valeur certaines informations. Il est en effet utile de percevoir rapidement quelles parties du modules sont standards et quelles sont celles qui sont soumises à une condition de publication.

La feuille de style n'est utilisée que pour l'édition du module. Elle n'est pas conservée lors du processus de publication.

Méta données

Le module doit obligatoirement comporter les méta-données suivantes :

kolekti_modversion
Le contenu de cette méta-donnée est le numéro de version du module. Il est utilisé notamment par le script kOLEKtrad qui permet la récupération de traductions inchangées entre 2 versions de langues.
kolekti_modlang
Le contenu de cette méta-donnée est le code langue du module. Note : le code doit être conforme à celui qui est défini dans la base (fichier _conf.xml).

Nommage

Le nom des modules est librement choisi par l'utilisateur. L'expérience montre qu'il est utile de prévoir dans le nom du module :

Ce qui donne au final ce type de nom : mod_101_ConsignesDeSecurite.xht

Pour prévenir tout risque d'erreur lié au gestionnaire de fichiers (qui dysfonctionne parfois lorsqu'il s'agit de lire de l'UTF-8), ne pas utiliser d'accents, d'espaces ou de caractères spéciaux dans les noms de modules.

L'extension est choisie par l'utilisateur. Elle est définie dans le fichier _conf.xml de la base. Dans l'exemple ci-dessus, l'intérêt de choisir ".xht" est de pouvoir lui associer une application particulière dédiée à l'édition (Amaya, NVU, etc.), alors qu'une extension classique du HTML (.htm ou .html) ouvre par défaut un navigateur internet.

Édition d'un module

Il est possible d'ouvrir un module directement en double-cliquant dessus dans l'explorateur de fichier.

Pour pouvoir éditer le module à partir de l'interface web de kOLEKTi, nous utilisons une extension de Firefox appelé "ViewSourceWith".

Pour installer ViewSourceWith dans Firefox :

  1. Dans Firefox cliquer sur Outils > Modules complémentaires
  2. Sélectionner l'onglet Extensions et cliquer sur Obtenir des extensions pour afficher la page Web de recherche des extensions Firefox.
  3. Rechercher l'extension ViewSourceWith et l'installer dans Firefox.

L'utilisation de l'extension "ViewSourceWith" avec kOLEKTi nécessite l'adaptation suivante :

  1. Accéder au Paramètres de l'extension "ViewSourceWith" (Outils > Modules Complémentaires)
  2. Dans l'onglet Mappages, cliquer sur Nouveau
  3. Saisir les caractéristiques du nouveau mappage :
    • Nom : Amaya
    • Filtre : http://localhost:8000/*
    • Répertoire qui inclut les pages sur le serveur : xxx (pas utilisé)
    • Code javascript. Appuyer sur le bouton [JS] (du code s'affiche dans la fenêtre).

      À la fin du code, remplacer :

      arFiles.push(data.pageSourcePath);

      arFiles.push(localPath + dirSep + fileName);

      par :

      //arFiles.push(data.pageSourcePath);

      //arFiles.push(localPath + dirSep + fileName);

      arFiles.push(uri);

  4. Dans l'onglet Générale > Liste des éditeurs, ajouter l'éditeur Amaya
  5. Valider les fenêtres de configuration.

Emplacement des modules

Les modules doivent obligatoirement être situés dans le répertoire Modules, à l'intérieur d'un répertoire de langue. Le répertoire de langue peut directement être situé sous le répertoire Modules, ou bien à l'intérieur de sous-répertoires décidés par l'utilisateur.

Le nom des répertoires de langues doit être conforme à la description qui en est faite dans le fichier de configuration _conf.xml de la base. Pour éviter toute confusion, il est souhaitable d'utiliser les codes de langues définis par l'ISO 639-1 (fr, en, es, de, it, el, etc.).

Illustrations

Format

Les modules étant au format XHTML, les illustrations sont stockées dans un répertoire distinct, et sont référencées dans le module à l'aide d'un élément img.

Les images peuvent être au format bitmap (ex : png) ou vectoriel (ex : svg). C'est souvent le format final de la publication qui est déterminant pour le choix du format, de la résolution, etc.

Lorsqu'une illustration au format SVG comporte une référence à une image bitmap (ex : une copie d'écran annotée ou repérée), kOLEKTi sait le reconnaître et copier les 2 fichiers dans le répertoire de publication.

Chemin

Le chemin d'une image dans un module XHTML est fourni sous la forme d'une url.

Cette url peut être absolue :

http://localhost:8000/minibase/illustrations/CopiesEcran/PageAccueil.png

L'url peut être relative à la racine du serveur kOLEKTi :

/minibase/illustrations/CopiesEcran/PageAccueil.png

L'url peut être relative au module :

../../../illustrations/CopiesEcran/PageAccueil.png

Les trois formes d'url sont supportées par kOLEKTi, cependant nous préconisons la seconde forme car elle est indépendante de la localisation du module dans la base, ainsi que de l'adresse du serveur.

Le chemin peut comporter des noms de répertoire variables qui seront remplacées selon les critères de publication.

Par exemple, le chemin :

/minibase/illustrations/CopiesEcran/_lang_/PageAccueil.png

permet d'aller chercher autant de fichiers PageAccueil.png qu'il y a de langues cochées dans l'ordre de publication.

Un chemin peut comporter plusieurs noms de répertoire variables.

La substitution dynamique n'affecte que les noms de répertoire variables commençant et finissant par "_".

Nommage

Pour prévenir tout risque d'erreur lié au gestionnaire de fichiers (qui dysfonctionne parfois lorsqu'il s'agit de lire de l'UTF-8), ne pas utiliser d'accents, d'espaces ou de caractères spéciaux dans les noms d'illustrations.

Critères

A l'intérieur d'un module, les parties spécifiques à un produit particulier ou à un type de publication particulier peuvent être identifiées par une condition.

Pour spécifier une condition de publication sur un élément XHTML, on utilise l'attribut class de l'élément, auquel on donne une valeur exprimant la condition.

Par exemple, un élément p qui possède un attribut class dont la valeur est M=XB10 n'apparaîtra que dans les publications concernant la machine (M) appelée XB10.

Dans cet exemple, "M" est le critère. Les critères sont définis par l'utilisateur dans le fichier _conf.xml de la base. C'est dans les Trames que l'utilisateur attribut une valeur (ou non) à chaque critère.

L'attribut class peut être défini pour tout élément classique de la syntaxe XHTML (h1, p, li, img, etc.) mais également span et div, ce qui offre une grande souplesse d'utilisation. Attention cependant à ne pas abuser de conditions sur des mots à l'intérieur de phrases, car cela complique singulièrement la tâche de traduction.

Usage du signe "=" (égal)

Le signe "=" est utilisé pour exprimer une condition d'utilisation. Tout élément comportant ce signe est considéré par kOLEKTi comme une condition à évaluer lors de l'assemblage. Après avoir rempli sa fonction de filtre, l'attribut class est retiré et n'apparaît plus dans le document pivot.

A contrario, tout attribut class valeur ne comportant pas de signe "=" (ex : danger) est conservée dans la publication (c'est utile pour pouvoir continuer à utiliser les feuilles de styles CSS).

Usage du signe "," (virgule)

La virgule est utilisé comme un opérateur logique OU entre plusieurs valeurs pour un même critère.

Si la condition suivante est exprimée :

M=XB11,XB22

L’élément correspondant est conservé dans la publication si dans la Trame l'une des valeurs XB11 ou XB22 est associée au critère M.

Le nombre de critères après le signe "égal" n'est pas limité.

Usage du signe ";" (point virgule)

Le point virgule est utilisé comme un opérateur logique ET entre plusieurs critères dans une même condition.

Si un élément comporte un attribut class dont la valeur est :

M=XB11;Z=EU

L’élément est conservé dans la publication si dans la Trame M=XB11et Z=EU

Usage du signe "\" (anti slash)

L'anti slash sert à exprimer une condition de type "tout sauf".

Si un élément comporte un attribut class dont la valeur est :

M=\XB33

L’élément est conservé dans la publication si la valeur du critère M dans la trame n'est pas égale à XB33.

Pour ajouter d'autres valeurs, il n'est pas nécessaire de rajouter l'anti slash. Ainsi :

M=\XB33,XB44

entraîne la suppression de l'élément si la valeur du critère M dans la trame est égale à XB33 ou à XB44.

Usage du signe "!" (point d'exclamation)

Le point d'exclamation est un signe particulier, qui exprime une condition exclusive. A l'inverse de la philosophie générale de kOLEKTi, où tous les éléments sont ré-utilisés sauf éventuellement ceux qui comportent un critère, le critère exclusif désigne, lui, les éléments qui doivent être ré-utilisés, à l'exception des autres.

Cela est utile lorsque l'on a besoin de "prélever" certains éléments (ex : illustrations), pour constituer des supports de formation par exemple.

Si un élément comporte un attribut class dont la valeur est :

!SupportDeCours

Cet élément sera utilisé si SupportDeCours est défini comme critère exclusif dans la trame.

C'est un moyen qui évite de polluer les éléments environnants avec une quantité de critères :

TypePublication=\SupportDeCours

Note : pour des raisons de logique évidentes, une trame ne peut comporter qu'un critère exclusif.

Usage du signe " " (espace)

Les critères peuvent être ou non espacés, sans conséquence sur le programme :

M = XB10

équivaut à

M=XB10

Trames

Une trame est un document xml qui définit une structure d'assemblage de modules en vue d'une publication particulière, ainsi que les critères relatifs à cette publication.

Accès au fichier

Les différentes trames sont situées dans le répertoire "Trames" de la base, accessible via l'explorateur de fichier et éditable avec n'importe quel éditeur de texte (attention cependant de respecter scrupuleusement la structure, et le codage UTF8 des caractères).

Pour limiter les risques d'erreur de saisie, les trames sont visualisables et modifiables via l'interface web de kOLEKTi.

Valeurs des critères

Dans la trame apparaissent les critères définis dans le fichier _conf.xml de la base. Chaque critère est composé d'un libellé court (code utilisé dans les modules pour exprimer les conditions) et d'un libellé long (pour expliciter le libellé court).

Un critère peut avoir des valeurs:

Structure d'assemblage

La structure d'assemblage référence les modules concernés par la publication.

Elle peut comporter plusieurs niveaux (sous-sections).

Le titre de chaque section peut faire référence à une variable de texte automatique, en utilisant la syntaxe suivante :

[var fichier:code]

où fichier est le nom du fichier de textes automatiques, et code l'entrée de texte automatique dans ce fichier.

Utiliser les flèches pour déplacer un module dans la structure, et les pictogrammes pour éditer un titre de section, ajouter une sous-section ou ajouter un module.

Toutes les références aux modules s'effectuent dans la structure d'assemblage, il n'est pas possible de faire référence à un module à l'intérieur d'un autre module.

Textes automatiques

Les textes automatiques sont des chaînes de textes multilingues, identifiées par un code, qu'il est possible d'insérer dans les modules (et dans les titres de la structure d'assemblage) lors de la publication.

Les textes automatiques sont enregistrés dans un tableau au format SXC (tableur OpenOffice), situé dans le répertoire "Office" de la rubrique "Autres".

La première colonne du tableur contient les codes des textes automatiques, obligatoirement précédés de "&" (sinon la ligne n'est pas prise en compte par kOLEKTi).

La deuxième colonne (B) est vide, celle-ci peut être masquée.

Les colonnes suivantes contiennent les traductions des textes dans les différentes langues.

Insertion d'un texte automatique

L'insertion d'un texte automatique dans un module s'effectue à l'aide d'un élément var et de son attribut class.

Exemple :

<p>Appuyez sur le bouton <var class="boutons:Print">xxx</var> pour lancer l'impression.</p>

Dans cet exemple, le texte "xxx" sera remplacé lors de la publication par la chaîne :

L'utilisation des textes automatiques peut également être combinée avec les critères de publication. Ainsi :

<p>Félicitations ! Vous venez d'acquérir la trancheuse <var class="Modeles:_T_">xxx</var> et vous allez voir ce que vous allez voir.</p>

permet de remplacer automatiquement "xxx" selon la valeur attribuée au critère T dans les ordres de publication. Par exemple, si "T=YB55", alors le texte sera remplacé lors de la publication par la chaîne :

La substitution peut également s'effectuer sur le nom du tableur, (ex : <var class="_T_:Poids" />) ce qui offre des perspectives intéressantes pour gérer notamment les caractéristiques techniques des produits.

Note : l'élément var peut être utilisé sans référence à un fichier de texte automatique (<var class="C"/>), dans ce cas c'est la valeur brute du critère qui est insérée dans la publication, indépendamment de la langue.

Transformation du fichier SXC en fichier XML

Le format SXC a été choisi pour son côté pratique, mais kOLEKTi le transforme automatiquement à chaque lancement en un fichier XML plus facile à exploiter.

Ce fichier XML est généré dans le répertoire "XML" de la rubrique "Autres".

Note : les textes automatiques seront gérés dans des classeurs OpenDocument (.ods) dans les prochaines versions de kOLEKTi.

Localisation

kOLEKTi est aujourd'hui disponible en français, et n'est pas localisé dans d'autres langues.