8f2f8b4092
- Rédaction de la documentation - Préparation du fichier 'GNUmakefile' pour avoir les bonnes variables - ajout de la suppresssion du fichier 'categories.html' dans le 'make clean'
243 lines
7.1 KiB
Plaintext
243 lines
7.1 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 ?).
|
|
|
|
### 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
|
|
- sed
|
|
- bash
|
|
- echo
|
|
- test
|
|
- cat
|
|
- wc
|
|
- grep
|
|
|
|
Normalement ces éléments sont inclus de base dans une distribution GNU/Linux
|
|
et/ou BSD.
|
|
|
|
### INSTALLATION ###
|
|
|
|
Le programme ne requièrt aucune installation particulière. Placez le où vous
|
|
voudrez.
|
|
|
|
### UTILISATION ###
|
|
|
|
Dans sa version 0.1 le programme s'utilise via plusieurs entrées minimales :
|
|
- le fichier GNUmakefile
|
|
- 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 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 GNUmakefile :
|
|
|
|
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.
|
|
|
|
#--[[ Le dossier 'img' et Adresse de l'image ]]--#
|
|
|
|
Dans la version 0.1, il faut indiquer clairement l'adresse de l'image à
|
|
utiliser pour la page de PorteAil.
|
|
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'.
|
|
|
|
Il faut donc concaténer deux chaînes de caractères :
|
|
- './image/' qui est le dossier de destination
|
|
- 'apps/clock.png' qui est l'adresse de l'image actuellement
|
|
|
|
Ainsi cela ressemble à :
|
|
|
|
./image/apps/clock.png
|
|
|
|
#--[[ 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 'GNUmakefile' :
|
|
|
|
#INTRO = $(DOSSIER_HTML)/introduction.html
|
|
|
|
par
|
|
|
|
INTRO = $(DOSSIER_HTML)/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 'GNUmakefile' :
|
|
|
|
#MENU = $(DOSSIER_HTML)/menu.html
|
|
|
|
par
|
|
|
|
MENU = $(DOSSIER_HTML)/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.
|
|
|
|
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
|
|
|
|
#FIXME
|
|
- GNUmakefile, pour aller plus loin
|
|
- creation_categ.sh - personnalisation
|
|
- composants - personnalisation
|
|
- le dossier style
|
|
- le dossier img
|
|
|
|
#--[[ GNUmakefile ]]--#
|
|
|
|
FIXME
|
|
|
|
### 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
|
|
|