453 lines
16 KiB
Plaintext
453 lines
16 KiB
Plaintext
########################
|
||
## Programme PorteAil ##
|
||
########################
|
||
|
||
### À PROPOS ###
|
||
|
||
PorteAil est un portail web dont le but principal est, comme son nom l'indique,
|
||
de partager un ensemble de liens amenant vers divers lieux.
|
||
|
||
Cf. http://fr.wikipedia.org/wiki/Portail_%28web%29 pour de plus amples
|
||
informations.
|
||
|
||
PorteAil est un jeu de mot entre Porte, portail et Ail (l'aliment ou le bruit
|
||
que nous faisons après avoir eu mal ?).
|
||
|
||
#--[[ Site Web ]]--#
|
||
|
||
Rien de plus à dire que : http://porteail.e-mergence.org/
|
||
|
||
#--[[ Contact ]]--#
|
||
|
||
Cf. Chapitre "Contact / Bugs" en bas de page.
|
||
|
||
#--[[ Licence ]]--#
|
||
|
||
Le programme PorteAil est sous licence GPLv3.
|
||
Vous êtes libre de diffuser le programme, de le modifier et de le
|
||
redistribuer sous la même licence en précisant le nom de l'auteur.
|
||
|
||
Pour plus de renseignements je vous invite à lire le fichier COPYING
|
||
joint avec les fichiers du programme.
|
||
|
||
### PRÉ - REQUIS ###
|
||
|
||
Ce programme fonctionne à l'aide de **GNU Make**.
|
||
|
||
Il requièrt également quelques commandes du SHELL sh comme :
|
||
- echo
|
||
- test
|
||
- rm
|
||
- cat
|
||
|
||
### DESCRIPTION ###
|
||
|
||
Le script makefile permet de générer un dossier contenant les fichiers
|
||
suivants :
|
||
- index.xhtml : page de garde du portail web 'PorteAil'
|
||
- defaut.css : feuille de style de PorteAil
|
||
- img : dossier contenant l'ensemble des fichiers images (icônes) pour
|
||
l'affichage des éléments dans la page de garde
|
||
|
||
### DÉPENDANCES ###
|
||
|
||
Le programme requièrt les programmes suivants :
|
||
- GNU make
|
||
- cp
|
||
- GNU sed
|
||
- sh
|
||
- echo
|
||
- test
|
||
- cat
|
||
- wc
|
||
- grep
|
||
|
||
Normalement ces éléments sont inclus de base ou disponibles dans
|
||
n’importe quel système d’exploitation POSIX.
|
||
|
||
### INSTALLATION ###
|
||
|
||
Le programme ne requièrt aucune installation particulière. Placez le où vous
|
||
voudrez.
|
||
|
||
### CONFIGURATION ###
|
||
|
||
Copiez le fichier 'configrc.exemple' (ou bien renommez le) en 'configrc'.
|
||
|
||
Sans ce fichier 'configrc' le programme ne peut pas fonctionner (depuis la
|
||
version 0.1.1).
|
||
|
||
### UTILISATION ###
|
||
|
||
Il vous suffit de lancer la commande suivante dans le dossier du projet :
|
||
|
||
make
|
||
|
||
Cela devrait générer le dossier 'porteail' dans lequel se trouve un exemple
|
||
de résultat possible.
|
||
|
||
Dans sa version 0.1 le programme s'utilise via plusieurs fichiers :
|
||
- le fichier GNUmakefile
|
||
- le fichier configrc
|
||
- le dossier categ
|
||
- le fichier composants/introduction.html
|
||
- le fichier composants/menu.html
|
||
- le dossier img
|
||
|
||
Pour chaque élément, veuillez vous référer au chapitre adéquat.
|
||
|
||
Si vous désirez personnaliser encore plus la page PorteAil, vous pouvez
|
||
lire la section « Pour aller plus loin » qui permet de comprendre un
|
||
peu mieux le fonctionnement du programme.
|
||
|
||
#--[[ Mode de fonctionnement basique ]]--#
|
||
|
||
Pour utiliser le programme, il suffit d'utiliser une console (shell),
|
||
d'aller dans le dossier contenant PorteAil, et de faire :
|
||
|
||
make
|
||
|
||
En théorie un nouveau dossier 'porteail' apparaît dans lequel il y a :
|
||
- un fichier 'index.html'
|
||
- une feuille de style nommée 'defaut.css'
|
||
- un dossier 'img' contenant tout un tas d'image
|
||
|
||
Si vous voulez supprimer les fichiers crées à l'aide de la commande
|
||
'make' ou pour toute autre raison, faites :
|
||
|
||
make clean
|
||
|
||
et cela aura pour effet de supprimer le dossier 'porteail' et le fichier
|
||
'categories.html' crée par différents scripts au moment de la génération
|
||
de la page.
|
||
|
||
#--[[ GNUmakefile ]]--#
|
||
|
||
Ce fichier contient les éléments de base pour lancer PorteAil. Aucun
|
||
changement particulier ne doit être effectué sur celui-ci.
|
||
|
||
#--[[ configrc ]]--#
|
||
|
||
Ce fichier apparaît depuis la version 0.1.1. Il vous permettra de changer le
|
||
titre de la page PorteAil et le titre affiché dans un navigateur. Ceci se
|
||
fait via les deux lignes suivantes :
|
||
|
||
- TITRE=
|
||
- ACCUEIL=
|
||
|
||
Par exemple pour afficher "Mon super site" sur la page PorteAil et
|
||
avoir "Accueil - Mon super site" dans l'onglet du navigateur, il
|
||
suffit de changer les lignes suivantes du fichier 'configrc' :
|
||
|
||
TITRE = Mon super site
|
||
ACCUEIL = Accueil - $(TITRE)
|
||
|
||
Il faut savoir que '$(TITRE)' va se changer en 'Mon super site'.
|
||
C'est la notion même de variables en programmation. Mais passons.
|
||
|
||
Ces deux variables sont les seules à modifier pour une utilisation
|
||
simple du programme.
|
||
|
||
#--[[ Le dossier 'categ' ]]--#
|
||
|
||
Le dossier 'categ' est le dossier qui va contenir nos catégories
|
||
d'éléments.
|
||
Il faut savoir que :
|
||
- un fichier texte portant l'extension '.txt' est considéré comme
|
||
UNE catégorie
|
||
- le programme n'accepte que les fichiers comportant une et une
|
||
seule description de catégorie
|
||
- le programme va lire les éléments renseignés dans le fichier
|
||
|
||
Le format de fichier accepte 3 cas possible de lignes :
|
||
1. les commentaires
|
||
2. une description d'une catégorie
|
||
3. une description d'un élément
|
||
|
||
Voici un commentaire :
|
||
|
||
# un commentaire dans le fichier
|
||
|
||
Voici une description de catégorie :
|
||
|
||
[[Titre de ma catégorie]]Description de ma catégorie
|
||
|
||
Voici une description d'un élément (un par ligne) :
|
||
|
||
Titre##URL##DESC##ADDR_IMG##TITRE_IMG##DESC_IMG
|
||
|
||
où :
|
||
|
||
- Titre : est le nom affiché sur le portail de l'élément.
|
||
- URL : est l'adresse COMPLÈTE du site sur lequel on pointe
|
||
- DESC : est la description complète de notre élément pour le passage de la
|
||
souris sur le lien
|
||
- ADDR_IMG : est l'adresse relative vers l'image (Cf. ci-après pour plus de
|
||
renseignements)
|
||
- TITRE_IMG : est le titre de notre image (si jamais l'image ne s'affiche pas)
|
||
- DESC_IMG : est la description de l'image au passage de la souris
|
||
|
||
Des exemples sont donnés dans le dossier 'categ'. À vous de les modifier comme
|
||
bon vous semble.
|
||
|
||
Astuce : Pour ordonner les catégories dans la page résultante, ajouter des
|
||
chiffres devant chacun de vos fichiers catégories. Par exemple :
|
||
|
||
00-ma_categorie.txt
|
||
01-autre_categorie.txt
|
||
|
||
Vous obtiendrez donc "ma_categorie" en premier lieu, puis "autre_categorie"
|
||
en second lieu.
|
||
|
||
#--[[ Le dossier 'img' et Adresse de l'image ]]--#
|
||
|
||
Dans la version 0.1.1, il faut indiquer l'adresse dite absolute de l'image.
|
||
C'est à dire l'adresse à partir du dossier image source.
|
||
|
||
Le dossier image source est le dossier contenant l'ensemble des images. C'est
|
||
un dossier dans lequel le programme va 'piocher' les éléments.
|
||
|
||
Sachant que le dossier 'img' contient l'ensemble des images disponibles,
|
||
il faut tout d'abord trouver l'adresse d'une image qu'on voudrait, par
|
||
exemple 'apps/clock.png'.
|
||
|
||
Dans un fichier catégorie, on donnera donc l'adresse suivante comme adresse de
|
||
l'image :
|
||
|
||
apps/clock.png
|
||
|
||
Pour un exemple plus criant, je vous propose de lire le fichier suivant :
|
||
|
||
categ/education.txt
|
||
|
||
qui contient un exemple de catégorie avec plusieurs éléments.
|
||
|
||
#--[[ Le fichier introduction.html ]]--#
|
||
|
||
Le fichier 'composants/introduction.html' contient du texte en HTML à
|
||
insérer en début de la page PorteAil, il faut donc connaître un peu le
|
||
langage HTML pour permettre un affichage correct de ce que vous voulez.
|
||
|
||
Par défaut cet élément n'est pas activé. Pour l'activer il suffit de
|
||
changer la ligne suivante dans le fichier 'configrc' :
|
||
|
||
#INTRO = introduction.html
|
||
|
||
par
|
||
|
||
INTRO = introduction.html
|
||
|
||
Vous l'aurez compris, il suffit d'enlever le premier dièse '#' du début de
|
||
ligne.
|
||
|
||
#--[[ Le fichier menu.html ]]--#
|
||
|
||
À l'instar du fichier 'introduction.html', le fichier 'menu.html' permet
|
||
d'insérer un menu dans la page du PorteAil. Ceci est très utile si vous
|
||
voulez agrémenter le portail de tout un tas d'autres pages.
|
||
|
||
Par défaut cet élément n'est pas activé. Pour l'activer il suffit de
|
||
changer la ligne suivante dans el fichier 'configrc' :
|
||
|
||
#MENU = menu.html
|
||
|
||
par
|
||
|
||
MENU = menu.html
|
||
|
||
Comme pour l'introduction, il suffit de supprimer le dièse '#' en début de
|
||
ligne.
|
||
|
||
### POUR ALLER PLUS LOIN ###
|
||
|
||
Tous les éléments expliqués ci-avant ne seront que partiellement ou pas du
|
||
tout expliqué pour des raisons évidentes de redondance d'information.
|
||
|
||
Nous allons donc aborder plusieurs points qui concernent la personnalisation
|
||
de PorteAil afin d'adapter le programme pour qu'il en résulte une page d'une
|
||
structure différente de celle de base.
|
||
|
||
Cela est utile dans le cas où :
|
||
- vous connaissez le langage HTML pour faire des pages internet
|
||
- vous connaissez le langage CSS pour manier visuellement la page sans modifier
|
||
le contenu
|
||
- vous n'avez pas peur de modifier quelques lignes dans des fichiers afin de
|
||
voir le résultat
|
||
|
||
#--[[ Utilisation de la commande make ]]--#
|
||
|
||
Pour plus d'informations sur l'utilisation de la commande 'make', je vous
|
||
renvoie à la page de manuel disponible en tapant :
|
||
|
||
man make
|
||
|
||
Cependant sachez que dans le fichier 'GNUmakefile' il existe plusieurs sections
|
||
susceptibles d'être utilisées. Les principales sont :
|
||
- all : génère la page de PorteAil après avoir fait divers tests d'existence
|
||
des éléments.
|
||
- clean : permet de nettoyer le dossier nommé 'porteail'
|
||
- test : fait quelques tests sur l'existence des ficheirs nécessaires pour
|
||
la compilation de la page.
|
||
|
||
#--[[ configrc ]]--#
|
||
|
||
Le fichier 'configrc' contient un ensemble de variables qui sont utiles pour
|
||
personnaliser la page de résultat. Voici une liste et la description attachée
|
||
pour chacun des éléments modifiable/utilisable dans le fichier 'configrc' :
|
||
|
||
CIBLE : nom du dossier dans lequel ira le résultat de la génération
|
||
|
||
INDEX : adresse, à partir du répertoire dans lequel est contenu le fichier
|
||
'GNUmakefile', dans lequel se trouvera le fichier résultant. Cela donne une
|
||
indication sur le nom que vous voulez donner au fichier
|
||
|
||
CSS_SANS_MENU : nom de la feuille de style à utiliser quand la page est générée
|
||
sans menu. À noter que le fichier doit se trouver dans le dossier 'style'.
|
||
|
||
CSS_AVEC_MENU : nom de la feuille de style à utiliser quand la page est générée
|
||
avec un menu. À noter que le fichier doit se trouver dans le dossier
|
||
'style'.
|
||
|
||
STYLE : nom de la seconde feuille de style à utiliser pour ajouter des
|
||
couleurs à votre page. À noter que le fichier doit se trouver dans le dossier
|
||
'style'.
|
||
|
||
CSS_NOM : nom de la feuille de style dans le résultat final
|
||
|
||
TITRE : Cf. Chapitre 'configrc' ci-avant.
|
||
|
||
ACCUEIL : Cf. Chapitre 'configrc' ci-avant.
|
||
|
||
COMPOSANTS : nom du dossier contenant l'ensemble des composants. Cf Chapitre
|
||
sur les composants 'Les composants'.
|
||
|
||
MENU : Cf. Chapitre 'Le fichier menu.html'
|
||
|
||
MENU_ADDR : Adresse exacte du fichier contenant le menu de la future page
|
||
PorteAil.
|
||
|
||
INTRO : Cf. Chapitre 'Le fichier introduction.html'
|
||
|
||
INTRO_ADDR : Adresse exacte du fichier d'introduction de la future page
|
||
PorteAil.
|
||
|
||
Quelques autres éléments sont modifiables : les composants. Les valeurs
|
||
attachées à ces composants sont les suivantes :
|
||
|
||
- entete : fichier entete.html
|
||
- enqueue : fichier enqueue.html
|
||
- contenu_fin : fichier contenu_fin.html
|
||
- script_contenu : script bash permettant de générer les catégories
|
||
- contenu : fichier temporaire possédant le contenu à insérer dans la page
|
||
- CATEGORIES : désigne le dossier dans lequel se trouve l'ensemble des
|
||
descriptions des catégories et des éléments se trouvant à l'intérieur de
|
||
chacune d'elle
|
||
- CATEGORIES_EXT : extension des fichiers contenus dans le dossier CATEGORIES
|
||
(précédemment renseigné) qui contiendra la description de base de chacune
|
||
des catégories et de ses éléments. Cf. Chapitre "Le dossier 'categ'"
|
||
- IMAGES : dossier contenant quelques images pour les éléments de chaque
|
||
catégorie. Toutes les images ne seront pas utilisées
|
||
- IMAGES_CIBLE : dossier dans lequel seront mises les images choisies dans
|
||
chacune des catégories (fichiers décrivant les catégories)
|
||
- DEFAUT_IMG : image par défaut utilisée si aucune autre image n'est
|
||
trouvée. Se trouve par défaut dans le dossier IMAGES (dossier 'img')
|
||
- DEFAUT_IMG_ADDR : adresse exacte du fichier image par défaut (Cf.
|
||
DEFAUT_IMG ci-avant pour de plus amples renseignements)
|
||
- categ_deb : nom du fichier contenant le code HTML d'un début de catégorie.
|
||
Le fichier doit se trouver dans le dossier renseigné par la variable
|
||
'composants'.
|
||
- categ_fin : nom du fichier contenant le code HTML d'une fin de catégorie.
|
||
Le fichier doit se trouver dans le dossier renseigné par la variable
|
||
'composants'.
|
||
- elem : nom du fichier contenant le code HTML d'un élément. Le fichier doit
|
||
se trouver dans le dossier renseigné par la variable 'composants'
|
||
|
||
Pour plus de renseignements, veuillez vous référer au chapitre 'Les
|
||
composants'.
|
||
|
||
#--[[ Les composants ]]--#
|
||
|
||
Les composants sont les éléments qui permettent de composer la page.
|
||
À cet effet une page a été scindés en les éléments suivants :
|
||
- entete.html : contient le début de notre page HTML
|
||
- categ_deb.html : contient le début d'une catégorie
|
||
- element.html : contient l'ensemble du HTML pour UN élément donné
|
||
- categ_fin.html : contient la fin d'une catégorie
|
||
- contenu_fin.html : contient la fin du corps de la page
|
||
- enqueue.html : contient le pied de page
|
||
- introduction.html : contient du HTML pouvant être ajouté après le titre
|
||
principal de la page
|
||
- menu.html : un menu à ajouter à notre page
|
||
|
||
Pour personnaliser il suffit d'éditer chacun des fichiers afin d'en
|
||
modifier le code source.
|
||
|
||
#--[[ La création des catégorie à l'aide de creation_categ.sh ]]--#
|
||
|
||
Le fichier 'creation_categ.sh' permet de générer le corps de la page.
|
||
À cet effet il va parcourir un dossier, générer les catégories une à une
|
||
et les éléments associés, puis il va tout déposer dans un fichier HTML
|
||
prévu à cet effet.
|
||
|
||
Le script fonctionne avec un certain nombre de paramètres parmi :
|
||
- dossier_cat : contient la source (dossier d'entrée) dans laquelle se trouve
|
||
les fichiers décrivant les catégories et les éléments associés.
|
||
- destination.html : contient la destination. C'est à dire le fichier dans
|
||
lequel se situera le corps, temporairement évidemment.
|
||
- extension : extension des fichiers décrivant les catégories et leurs
|
||
éléments associés
|
||
- dossier_composants : ce dossier réunit l'ensemble des composants de notre
|
||
page finale. Il est utile pour récupérer le fichier 'element.html',
|
||
disponible d'ailleurs dans la variable 'elem'
|
||
- entete_cat.html : contenu HTML du début d'une catégorie
|
||
- enqueue_cat.html : contenu HTML qui marque la fin d'une catégorie
|
||
- element.html : contenu HTML qui contient UN élément
|
||
- dossier_img : dossier contenant les images dites "sources"
|
||
- destination_img : nom du dossier dans lequel seront stockées les images
|
||
finales
|
||
- image.png : nom du fichier par défaut utilisé lorsque les images ne sont pas
|
||
trouvées
|
||
- dossier_porteail : nom du dossier dans lequel sera mise la page PorteAil
|
||
|
||
Normalement, avec toutes ces données vous devriez pouvoir tester par vous
|
||
même le résultat du script et améliorer le rendu de vos pages.
|
||
|
||
#--[[ Le dossier style ]]--#
|
||
|
||
Le dossier 'style' est prévu pour contenir l'ensemble des feuilles de style
|
||
disponible pour l'apparence de notre page PorteAil.
|
||
|
||
Déposez donc ici vos feuille de style et changez la variable 'CSS_AVEC_MENU'
|
||
,'CSS_SANS_MENU' et 'STYLE' du fichier 'configrc' (Cf. Chapitre
|
||
'configrc').
|
||
|
||
#--[[ Le dossier img ]]--#
|
||
|
||
Le dossier 'img' contient, dans la version 0.1, l'ensemble des images
|
||
utilisées pour la page finale.
|
||
|
||
Déposez-y les images que vous voudriez utiliser.
|
||
|
||
### SOURCES ###
|
||
|
||
Les sources du programme peuvent être récupérées sur
|
||
http://git.dossmann.net/ ou via la commande suivante (à l'aide de l'outil
|
||
git) :
|
||
|
||
git clone http://git.dossmann.net/scripts/porteail.git
|
||
|
||
### CONTACT / BUGS ###
|
||
|
||
Pour toute suggestion, critique constructive, remarque, notification de bugs,
|
||
je vous invite à me joindre à l'adresse courriel suivante :
|
||
|
||
olivier CHEZ dossmann POINT net
|
||
|
||
Pensez à ajouter, en début d'objet de votre courriel, l'élément suivant :
|
||
|
||
[PorteAil]
|
||
|
||
Ceci me permettra de savoir directement de quel sujet le courriel traite.
|
||
|
||
Merci d'avance, et amusez-vous bien avec PorteAil ;-)
|