######################## ## 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.html : 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 ### Dans sa version 0.1 le programme s'utilise via plusieurs entrées minimales : - 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 suivante : 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 = $(COMPOSANTS)/introduction.html par INTRO = $(COMPOSANTS)/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 = $(COMPOSANTS)/menu.html par MENU = $(COMPOSANTS)/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' : DESTINATION : 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' INTRO : Cf. Chapitre 'Le fichier introduction.html' 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 - categ : 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 - ext : extension des fichiers contenus dans le dossier 'categ' (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'" - image : dossier contenant quelques images pour les éléments de chaque catégorie. Toutes les images ne seront pas utilisées - dest_image : dossier dans lequel seront mises les images choisies dans chacune des catégories (fichiers décrivant les catégories) - image_defaut : image par défaut utilisée si aucune autre image n'est trouvée - composants : dossier dans lequel se trouve l'ensemble des éléments permettant de construire le contenu de la page PorteAil. C'est à dire l'entête et l'enqueue de chaque catégorie ainsi que le code HTML de chaque élément - 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 ;-)