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 |
|
|
1.1. Copies d'écran
| Onglet contenu |
Onglet préférences |
Ajout de fichiers |
|
|
|
Toutes les versions sont accessibles sur
sourceforge.net ou via les
liens ci-dessous.
|
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.
|
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. |
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.
|
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.
|
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.
|
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&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 ) |
|
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 |
|
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[]
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.1. Architecture
Ce chapitre présente l’architecture de l’application ADGen.
7.1.1. Principe
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