RapazP Home Page
«Using GNU/Linux isn't a matter of choice. It's a matter of freedom!»
left_arrow Introduction
left_arrow GNU/Linux
down_arrow OpenSource
left_arrow Loisirs
left_arrow About me
Table des matières

../../images/icons/uk_flag.png English version / ADGen ChangeLog (Uniquement en anglais)

1. Introduction

AsciiDoc est un format texte destiné à la rédaction de documents, d’articles, de manuels et de man pages UNIX.

Les documents respectant le format AsciiDoc peuvent être utilisés de la même manière qu’un document texte normal. De ce fait, ils peuvent être visualisés, édités ou imprimés directement. Ils peuvent également être convertis en différents formats tel que: PDF, HTML, DocBook ou encore LinuxDoc.

Programmé en Python et basé sur des fichiers de configuration XML, l’application ADGen a pour vocation de simplifier la création et le déploiement de sites web composés de pages écrites au format AsciiDoc.

Outre la conversion de fichiers, ADGen permet d’internationaliser le contenu d’un site web, de gérer la hiérarchie des répertoires et de mettre en place un menu latéral dans une page web.

De plus, il offre la possibilité de déployer automatiquement les fichiers générés par le biais d’un transfert FTP.

Structure avant génération Structure après génération

Avant génération

Après génération

1.1. Copies d'écran

Onglet contenu Onglet préférences Ajout de fichiers

http://www.rapazp.ch/images/adgengui/_thb_mainTabContent.png

http://www.rapazp.ch/images/adgengui/_thb_mainTabPrefs.png

http://www.rapazp.ch/images/adgengui/_thb_addNewFile.png

2. Téléchargement

Toutes les versions sont accessibles sur sourceforge.net ou via les liens ci-dessous.

Fichier Description

ADGen-2.2.1.tar.gz

Version multiplateforme

ADGen_2.2.1_i386.deb

Linux Debian / Ubuntu package 32 bit

ADGen_2.2.1_amd64.deb

Linux Debian / Ubuntu package 64 bit

ADGen-win-2.2.1.zip

Version pour Windows (sans setup)

ADGen-2.2.1.pdf

Documentation pour la version 2.2.1 au format PDF

ADGen-1.2.2.zip

Latest release for ADGen version 1.0

Tip La création des packages debian à partir d’une application écrite en python a été réalisée à l’aide du tutorial "creating a .deb package from a python setup.py"

3. Installation

Note

Tout comme AsciiDoc, ADGen requiert Python 2.4 ou plus récent pour fonctionner. Si vous n’avez pas encore d’interpréteur Python sur votre système, vous pouvez le télécharger sur le site officiel http://www.python.org/.

La version actuelle a été testée sous Linux (Ubuntu) et Cygwin (en mode console) avec AsciiDoc 8.2.6.

3.1. GNU/Linux

3.1.1. Installation manuelle

Pour effectuer une installation manuelle de l’application ADGen dans un environnement Linux, il suffit de décompresser l’archive .tar.gz et de lancer le script d’installation.

3.1.2. Package Debian / Ubuntu

Depuis la version 2.2.0 et plus, vous avez la possibilité d’installer ADGen par le truchement de package Debian. Ceux-ci sont disponibles pour une architecture 32 bit (i386) ou 64 bit (amd64).

3.2. Windows

Il n’existe actuellement pas de script d’installation pour ADGen Windows. La procédure d’installation reste cependant relativement simple étant donné qu’il suffit de décompresser le contenu du fichier zip dans un nouveau répertoire.

Pour exécuter ADGen, déplacez-vous dans le répertoire d’installation et lancez la commande adgen.py ou adgengui.py selon que vous désirez travailler en ligne de commande ou via l’interface graphique. Vous pouvez également ajouter le répertoire d’installation dans votre variable d’environnement PATH afin de pouvoir exécuter l’application quelque soit votre emplacement.

Warning La version graphique nécessite gtk. A priori, cette dernière doit fonctionner sous Windows toutefois aucuns tests n’ont été effectués dans cette configuration.

4. Fichiers de Configuration

Si vous n’utilisez pas l’interface graphique ou que vous rencontrez des problèmes avec les fichiers de configuration. Vous trouverez dans ce chapitre l’organisation et le contenu des différents fichiers utilisés par ADGen.

La configuration d'ADGen s’effectue par le truchement de 3 fichiers:

adgen.conf

Contient la configuration générale d'ADGen. Ce fichier est situé dans le répertoire $HOME/.adgen.

ftp.conf

Facultatif, ce fichier permet de configurer les accès au serveur ftp pour le transfert automatique du site web. Il est situé dans le répertoire $HOME/.adgen.

adgen.adg ou adgen.xml

Contient les données du projet web à générer. Par défaut, ADGen utilise le fichier de configuration situé dans le répertoire de lancement de l’application, cependant vous pouvez le spécifier à l’aide de l’option -c en ligne de commande.

Warning Lors du premier lancement de l’application, les fichiers adgen.conf et ftp.conf sont automatiquement créés à titre d’exemple. Pour utiliser ADGen, ces fichiers doivent impérativement être complétés.

4.1. adgen.conf

Ce fichier de configuration contient toutes les données nécessaires au fonctionnement d'ADGen.

<?xml version="1.0" encoding="UTF-8"?>
<adgen>
  <editor>
    <linux>gedit</linux>
    <windows>D:\Editra\Editra.exe</windows>
  </editor>
  <asciidoc>
    <command>
      <linux>asciidoc</linux>
      <windows>c:/asciidoc/asciidoc.py</windows>

      <extensions layoutFile=".conf" textFile=".txt" webFile=".html"/>
    </command>
  </asciidoc>
</adgen>

4.1.1. Balises

asciidoc
editor

linux

Editeur de texte utiliés dans l’environnement Linux (ce dernier doit être dans la variable d’environnement PATH ou dans /usr/bin)

windows

Chemin pour lancer l'éditeur de texte sous windows.

command

linux

Commande asciidoc sous linux. (AsciiDoc doit être dans la variable d’environnement PATH ou dans /usr/bin)

windows

Chemin pour lancer la commande AsciiDoc sous windows.

extensions

Liste des extensions utilisées par AsciiDoc. (par défaut: textFile=".txt" webFile=".html" layoutFile=".conf")

4.2. ftp.conf

Ce fichier de configuration est facultatif. Il permet de définir les paramètres utilisés pour effectuer un déploiement automatique des fichiers générés via un transfert ftp.

Note Le tranfert ftp reproduit exactement la même arborescence que celle de votre disque dur local. De ce fait, le répertoire web, défini dans le fichier de configuration adgen.xml, sera le point de départ pour le déploiement des fichiers.
<?xml version="1.0" encoding="UTF-8"?>
<adgen>
  <ftpConfig>
    <host>[host_name]</host>
    <user>[user_name]</user>
    <password>[user_password]</password>

    <deploy>all</deploy>
  </ftpConfig>
</adgen>

4.2.1. Balises

ftpConfig
host

Adresse du serveur ftp.

user

Utilisateur de connection (ne peut pas être anonymous).

password

Mot de passe de connection.
Si vous ne désirez pas saisir le mot de passe dans votre fichier de configuration, vous pouvez l’indiquer en ligne de commande lors de l’exécution de l’application grâce à l’option -p. Toutefois, la saisie d’un mot de passe est obligatoire si vous souhaitez transférer automatiquement les fichiers générés via ftp.

deploy

Indique les éléments à transferer sur le serveur ftp. Cette clef peut être surdéfinie au lancement via l’option -d.

all

Transfert tous les fichiers (web et texte)

text

Transfert uniquement les fichiers texte

web

Transfert uniquement les fichiers web (option par défaut)

4.3. adgen.adg (ou adgen.xml)

Ce fichier permet de configurer votre projet.

Il est divisé en deux sections; project qui contient les données générales du projet et webContent qui contient la liste des fichiers à convertir.

Tip Afin de simplifier la création de ce fichier, l’option -N disponible en ligne de commande a pour vocation la création d’un nouveau fichier de configuration dans le répertoire courant.
<?xml version="1.0" encoding="UTF-8" ?>
<adgen>
  <project>
    <version>2.0.0</version>

    <folder>
      <work>
        <linux>/home/spytux/web/infra</linux>
        <windows>c:/web/infra</windows>

        <web>/web/infra</web>

        <rootText>text</rootText>
        <rootHtml>..</rootHtml>
      </work>

      <icons>images/icons</icons>
    </folder>

    <layout>
      <tableBased>layout1</tableBased>
      <simulFrame>layout2</simulFrame>
    </layout>

    <tocTitle>
      <title lang="en">Table of content</title>
      <title lang="fr">Table des mati&amp;egrave;res</title>
    </tocTitle>
  </project>

  <webContent backend="xhtml11" defaultLanguage="fr">
    ...

    <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
    <!--                     SAMPLE PROJECT SECTION                      -->
    <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
    <section webFolder=".." textFolder="opensource" treeNode="opensource">
      <fileName isNumbered="true" isSimulFrame="true">opensource</fileName>
      <fileName isNumbered="true" isSimulFrame="true">internet</fileName>
      <fileName isNumbered="true" isSimulFrame="true">tools</fileName>
    </section>

    <section webFolder="../.." textFolder="opensource/tools" treeNode="opensource">
      <fileName isNumbered="toc" isSimulFrame="true" lang="fr">AsciiDoc</fileName>
       <fileName isNumbered="toc" isSimulFrame="true" lang="en">AsciiDoc</fileName>
    </section>

    <section webFolder="../.." textFolder="opensource/internet" treeNode="opensource">
      <fileName isNumbered="false" isSimulFrame="true">firefox</fileName>
    </section>

    ...
  </webContent>

  ...
</adgen>

4.3.1. Balises

project

Cette balise contient les informations générales du projet.

version

Permet spécifier la version des fichiers générés.

folder

Permet de configurer les répertoires sources et destinations utilisés par le générateur.

work

linux

Répertoire absolu utilisé comme racine lors de la génération sous linux.

windows

Idem ci-dessus mais pour windows.

web

Répertoire absolu utilisé comme racine pour le déploiement web via ftp. Ce répertoire doit exister sur le serveur ftp.

rootText

Ce répertoire est utilisé comme racine pour trouver les .txt à convertir. Il doit être donné de manière relative aux répertoires définis ci-dessus.

rootHtml

Ce répertoire est utilisé comme racine pour écrire les fichiers générés par AsciiDoc. Il doit être donné de manière relative aux répertoires définis ci-dessus.

icons

Dossier du site web contenant les icônes. Cette balise est utilisée pour renseigner l’option "‘iconsdir=`" d’AsciiDoc.

layout
tableBased

Layout basé sur des divisions similaires à une table.

simulFrame

Layout simulant des frames par le biais d’une CSS. (Ce genre de layout n’est pas supporté par Internet Explore 6)

tocTitle

Permet d’internationaliser le titre utilisé lors la génération de la table des matières.

webContent

Cette balise contient la liste des documents à convertir via AsciiDoc.

webContent

Ses attributs sont les suivants:

backend

Indique le backend utilisé par AsciiDoc pour la génération des fichiers. (facultatif)

defaultLanguage

Permet de spécifier la langue par défaut des pages générées. Cet attribut peut être surdéfini pour chaque document.

section

Permet de configurer les documents à convertir. Il faut définir une balise section par répertoire.

Les attributs sont les suivants:

webFolder

Chemin relatif à la balise work (définie plus haut) dans lequel les fichiers générés seront sauvegardés.

textFolder

Chemin relatif à la balise work (définie plus haut) contenant les fichiers à convertir.

treeNode

Permet de spécifier le noeud à utiliser dans le menu latéral de la page web.

fileName

Nom du fichier à convertir (sans l’extension)

Les attributs sont les suivants:

isNumbered

true ou notoc pour numéroter les sections, toc ou toc_X (X indique le nombre niveau de la table des matières (1..4)) pour numéroter les sections et générer la table des matières et false ou none pour ne pas numéroter. Si cet attribut n’est pas présent, les sections ne sont pas numérotées (idem false ou none). (facultatif)

isSimulFrame

true pour utiliser le layout simulant les frames et false pour utiliser le layout classique. Si cet attribut n’est pas présent, le layout standard est utilisé. (facultatif)

lang

Permet de spécifier la langue du document courant. (facultatif )

Note

Les documents traduits dans plusieurs langues devront être sauvegardés avec les initiales de la langue avant l’extension du fichier:

Source Destination

asciidoc.en.txt

asciidoc.en.html

asciidoc.fr.txt

asciidoc.fr.html

defaultLanguage

asciidoc.html

5. Menus et Attributs

Quelques attributs ont étés ajoutés afin de pouvoir gérer les nouvelles fonctionnalités offertes par ADGen. Ces attributs pourront être utilisés dans les fichiers de configuration des layouts.

{baseFolder}

La variable \{baseFolder} est remplacée par le contenu de la balise webFolder.

<link rel="stylesheet"
      href="{stylesdir={baseFolder}stylesheets}/{theme={backend}}.css"
      type="text/css" />
{iconsdir}

L’attribut \{iconsdir} est remplacé par la balise icons. Cet attribut peut être utilisé pour indiquer le répertoire contenant les icônes du site.

<link rel="shortcut icon" href="{iconsdir}/mini_logo.png" />
<link rel="icon" href="{iconsdir}/mini_logo.png" />
{language}

La balise \{language} peut être utilisée pour valoriser la variable Content-Language.

<meta http-equiv="Content-Language" content="{language}" />
{tocTitle}

Cette balise permet d’internationaliser le titre utilisé pour générer la table des matières.

 ifdef::toc[]
   <script type="text/javascript" src="{scriptsdir={baseFolder}scripts}/toc.js"></script>
 endif::toc[]

 ...

 ifdef::toc[]
   <div id="toc">
     <div id="toctitle">{tocTitle}</div>
     <noscript>
       <p><b>
         JavaScript must be enabled in your browser to display the table of contents.
       </b></p>
     </noscript>
   </div>
 endif::toc[]

La gestion des menus s’effectue au niveau du fichier de paramétrage des layouts. L'état d’un menu peut être soit ouvert, soit fermé; ceci est déterminé par la balise treeNode du fichier XML de paramétrage.

 <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
 <!--                           SAMPLE MENU                           -->
 <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
 ifndef::opensource[]
   <img style="border:none; width:10px; height:10px;"
        alt="left_arrow"
        src="{baseFolder}images/icons/left_arrow.png" />
   <a href="{baseFolder}opensource/opensource.html">OpenSource</a>
 endif::opensource[]
 ifdef::opensource[]
   <img style="border:none; width:10px; height:10px;"
        alt="down_arrow"
        src="{baseFolder}images/icons/down_arrow.png" />
   <a href="{baseFolder}opensource/opensource.html">OpenSource</a>
   <div id="sub-menu">
     <div><a href="{baseFolder}opensource/internet.html">Internet</a></div>
   </div>
   <div id="sub-menu">
     <div><a href="{baseFolder}opensource/tools.html">Outils</a></div>
   </div>
 endif::opensource[]

6. Utilisation en ligne commande

Par défaut, l’application adgen.py traite l’intégralité du fichier de configuration. Il est cependant possible de personnaliser l’exécution à l’aide des options décrites ci-dessous.

6.1. Options

-h, --help

Affiche l’aide

-N, --newproject

Crée un nouveau fichier de configuration de projet adgen.adg dans le répertoire courant

-b, --browse

Ouvre le browser pour visualiser la page. Si l’option -f n’est pas spécifiée, la page index.html est ouverte.

-c XMLCONFIGFILE, --config=XMLCONFIGFILE

Permet de spécifier le fichier de configuration XML à utiliser (par défaut: adgen.xml)

-d, --deploymode

Permet de surdéfinir le mode de déploiement ftp (valeurs: text, web or all)

-f FILE(S), --file=FILE(S)

Permet de spécifier les fichiers à traiter (sans l’extension). Séparez les fichiers multiples avec une virgule.

-o, --output

Permet de surcharger la valeur du tag rootHtml lors de l’exécution

-p, --password

Permet de spécifier le mot de passe pour l’accès au serveur ftp si celui-ci n’est pas spécifié dans le fichier de configuration ftp.conf.

-t, --transfer

Transfert les fichiers générés sur le serveur ftp.

-v, --verbose

Affiche toutes les commandes exécutées ainsi que leurs paramètres

-V, --Version

ADGen Version et copyright

7. Développement

7.1. Architecture

Ce chapitre présente l’architecture de l’application ADGen.

7.1.1. Principe

Schéma de principe de l’architecture d’ADGen

7.1.2. Contenu

/src
  /adgen
    /config
      adgenConfig.py          Gestion du fichier 'adgen.conf'
      adgenConstants.py       Constantes du projet
      configHelper.py         Classe de base pour la gestion des fichiers de configuration xml
      ftpConfig.py            Gestion du fichier 'ftp.conf'
      projectConfig.py        Gestion du fichier 'adgen.adg' ou 'adgen.xml'

    /core
      adgenCore.py            Classe commune pour le gui et la ligne de commande
      helper.py               Fonctions d'aides

    /ftp
      ftpManager.py           Classe pour la gestion des transferts ftp

    /gui
      /component
        contentTreeView.py    Composant TreeView utilisé pour la gestion du projet (fichier '.adg' ou '.xml')
        logEvents.py          Composant pour la récupération des I/O de la ligne de commande
        tocTreeView.py        Composant pour la gestion de la table de matière multi-langue

      /glade
        adgen.glade           Interface graphique de l'application
        adgen.svg             Logo utilisé par glade

      /icons                  Contient les icônes du projet

      /widget
        aboutWidget.py        Boîte de dialogue 'A propos'
        addContentWidget.py   Boîte de dialogue utilisée pour l'ajout d'un fichier ou d'une section
        addTocWidget.py       Boîte de dialogue pour l'ajout d'une nouvelle langue pour la table de matières
        fileChooserWidget.py  Boîte de dialoge pour l'ouverture d'un projet
        messageWidget.py      Boîte de dialogue pour l'affichage de message
        preferencesWidget.py  Boîte de dialogue pour la gestion des préférences de l'application

      adgen.desktop           Permet la création du lanceur Gnome

    /util
      adgenI18N.py            Gère l'internationalisation de l'application
      logTool.py              Permet de centraliser tous les messages I/O envoyés sur stdin et stdout

    adgen.py                  Application principale
    adgengui.py               Application principale pour l'exécution en mode GUI

  /bin
    adgen                     Script shell pour l'exécution en ligne de commande
    adgengui                  Script shell pour l'exécution en mode graphique

  /debian                     Contient les fichiers nécessaires pour la création des packages Debian / Ubuntu

  /docs
    adgen.en.txt              Documentation en anglais
    adgen.fr.txt              Documentation en français

  CHANGELOG                   Change log de version
  COPYING                     Termes de licence GPL
  INSTALL                     Procédure d'installation
  MakeFile                    Make file pour la compilation du package Debian / Ubuntu
  MANIFEST.in                 Manifest pour le packaging avec la commande 'setup.py'
  README
  release.sh                  Script d'aide à la création des releases
  setup.py                    Script d'installation d'ADGen
  uninstall.sh                Script d'aide pour la désinstallation suite au lancement du 'setup.py'

7.2. Todo

Ci-dessous, la liste des différentes fonctionnalités devant être développées pour les livraisons à venir:

  • Simplifier la gestion du menu latéral en prenant en compte les informations du fichier de configuration de projet adgen.xml

  • Intégration de la nouvelle API pour l’appel du générateur AsciiDoc 8.4.2 (sans passer par un sous-processus)

  • Support d’autres options du générateur AsciiDoc

  • Permettre le transfert FTP de documents non transformés par AsciiDoc