HOWTO SLIS-HOWTO

Ou comment participer au travail de rédaction du livre de documentation SLIS

Moreau Laurent

Académie de Grenoble.

$Id: howto-slishowto.xml 144 2004-05-12 21:23:11Z lolo $


1. Introduction
2. Spécifications XML
3. Structure du livre
4. Rédaction d'un document
5. Manipuler XML
6. Travail coopératif
7. Liens utiles

1. Introduction

Ce document à pour objectif de faciliter la rédaction du livre de documention relatif au projet SLIS

L' état d'avancement du travail de rédaction peut être consulté ici : http://slis.ac-grenoble.fr/doc/docbook/slis-howto

Pour toutes remarques et commentaires :

2. Spécifications XML

2.1. DTD utilisée

Nous utilisons une DTD de type "Docbook"

Aujourd'hui :

  • Version : 4.1.2-1.0-14
  • Chemin : /usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-14/docbookx.dtd (Redhat)

Hier :

  • Version : 4.1.2-1.0-8
  • Chemin : /usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-8/docbookx.dtd (Redhat)

2.2. Version XML

  • Version 1.0

3. Structure du livre

Ce chapitre traite de la structure du livre "SLIS-HOWTO"

3.1. Trame du projet de documention SLIS

Cette "trame" à été rédigé lors de la rénion de travail du lundi 10 février 2003

******************************************

1  - Introduction générale
2  - Que fait SLIS ?
3  - Système et architecture réseau
4  - Installation d'un SLIS
5  - Mise en oeuvre du site local
6  - Le serveur web du SLIS
7  - Description de l'interface
8  - Déannage
9  - FAQ
10 - Développement
11 - Annexes

******************************************

Résumé

===========================================
Introduction générale :
===========================================

# comment utiliser cette documentation
# Historique
# objectif
# Evolution/développement
# Articulation
# license GPL


===========================================
Que fait SLIS ?
===========================================

# Résumé des caractéristiques (liens pointant vers les différentes sections)

	* routage avec translation d'adresse dynamique (masquerading)
    	* serveur de messagerie (SMTP/POP) avec gestion de files d'attentes optimis?s.
		(dialogue avec le routeur Numéris si celui-ci est compatible),
    	* proxy-cache web/ftp avec config automatique,et/ou proxy transparent.
	* authentification des accès au web via le proxy cache pour les utilisateurs
    	* Serveur DNS (cache),
    	* mise à jour automatique par réseau,
    	* maintenu et supervision à distance,
    	* configuration par interface web (avec possibilité de création automatique de
		comptes de messagerie par importation).
    	* maintenance d'une base permettant la sauvegarde des opérations de
		configuration pour une réinstallation du système en cas de crash-disque,
    	* serveur http pouvant être répliqué sur un serveur externe.
	* serveur http pouvant être redirigé de manière sécurisé vers un autre
		serveur du réseau local
    	* installation automatisée
    	* filtrage IP de sécurité
    	* planning horaire de fonctionnement par sous-réseaux prédéfinis,
    	* filtrage d'URLs avec bases maintenues (mise en oeuvre de l'outil squidGuard),
    	* serveur DHCP (non activé par défaut) et interface d'administration DHCP.
    	* serveur de fichiers local pour les rôles (fontions CyberEcole),
    	* possibilité de prise en main distante des stations du réseau de l'établissement
		par redirection de port temporaire
    	* possibilité de raccordement par VPN (vtun/IPSec)
	* annuaire LDAP.
	* filtrage de la messagerie sur le champ d'exp?iteur
	* anti-spam (anti relaying, filtrage des spams)
	* activation de modules (Bii, anti virus)

ref => http://slis.ac-grenoble.fr/home.php)

# Avantages de SLIS

	* Des fonctions adaptées aux situations d'enseignement
	* Une administration locale facilitée
	* Une architecture évolutive
	* La maintenance à distance

ref => http://www.cndp.fr/DOSSIERSIE/som41.htm

===========================================
Système et architecture réseau
===========================================

# architecture standard (trop D'IP, pas implémenté ...)
# variantes d'architecture
	* NAT
	* PPP
	* VPN
	* mixtes
# technologies utilisées
	* ADSL
	* câble
	* liaisons hertzienne
	* fibre optique
# intégration dans le réseau académique
	* Serveur DNS
	* Rsync
	* supervision
	* réseau de collecte (régional)
	* concentrateur VPN
	* messagerie
	* filtrage IP
	* plan d'adressage IP

ref => http://slis.ac-grenoble.fr/archi-slis.html


===========================================
Installation d'un SLIS
===========================================

# matériel nécessaire
	* hardware
		- HDD
		- RAM
		- cartes ethernet
		- Onduleur ...
	* software
		- dkb
		- dks (en possession de la dks, lien vers annexe DKS (contenu),et pointeur vers SLIM...)
		- cd
# procédure d'installation
# branchement du SLIS
# validation du fonctionnement

===========================================
Mise en oeuvre du site local
===========================================

# configuration de l'intranet
	* TCP/IP
	* sous réseaux
	* messagerie
	* navigation
	* cyber-école
# définition des rles
	* administrateur
	* webmaster
# Autres serveurs
	* Serveur de fichier (Harp, altair, mrpet ...)
	* SambaEdu (LDAP)
	* serveur Http intranet autre que SLIS (redirection)
	* serveur SQL

===========================================
Le serveur web du SLIS
===========================================

# serveur web
	* repertoire de stockage (public)
	* transfert FTP
# réplication serveur extranet
# bii
# php et base SQl

===========================================
Guide d'utilisation de l'interface d'administration
===========================================

# introduction (mode novice, mode expert)
On reprends ensuite l'ensemble de l'interface point par point :
# utilisateur
# fonctions avancées
# aide
# valider
# annuler

===========================================
Dépannage
===========================================

# d'un point de vue administrateur locale
# d'un point de vue des techniciens en charge de la maintenance (niveau académique)


===========================================
FAQ
===========================================

# Voir FAQ Creteil (http://aleu.ac-creteil.fr/faqclient/index.php?voir=2)

===========================================
DEVELOPPEMENT
===========================================

===========================================
Annexes
===========================================

# disquette setup (DKS)


===========================================

"#" => section de niveau 1
"*" => section de niveau 2
"-" => section de niveau 3

===========================================

3.2. Document "root"

3.2.1. Définition

  • Chaque document XML a une structure LOGIQUE et une structure PHYSIQUE.
  • Le document root slishowto.xml contient uniquement la "structure logique" du livre, du chapitrage aux sections de niveau 1.
  • A chaque section de niveau 1 correspond une entité externe (Les "contenus physiques" = fichiers XML)

Note

Le document root slishowto.xml n'a pas lieu d'être modifié

3.2.2. Source

Source du document root "slishowto.xml" :


<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook XML V4.1.2//EN"
"/usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-8/docbookx.dtd"
[<!ENTITY % content SYSTEM "content.ent">%content;]>

<!--===================== Ouverture du livre ==============================-->

<book>

<!--====================== Informations livre ==============================-->

<bookinfo>
<title>SLIS-HOWTO
  <mediaobject>
   <imageobject>
    <imagedata fileref="img/slis.png" format="PNG" scalefit="1"/>
  </imageobject>
  </mediaobject>
</title>
<authorgroup>
<affiliation><orgname>Carmi-Internet, Académie de Grenoble</orgname></affiliation>
</authorgroup>
<edition>User's Guide version 1.0 for SLIS V3.0</edition>
<releaseinfo>$Id: howto-slishowto.xml 647 2004-12-08 10:37:18Z lolo $</releaseinfo>
</bookinfo>

<!--===================== Introduction ==================================-->

<chapter id="introduction">
 <title>Introduction</title>
   &utilisation_doc;
   &historique;
   &objectif;
   &evolution_et_developpement;
   &articulation;
   &license_gpl;
</chapter>

<!--==================== que fait SLIS ==================================-->

<chapter id="que_fait_slis">
 <title>Que fait SLIS</title>
   &resume_des_caracteristiques;
   &avantage_de_slis;
</chapter>

<!--==================== systeme_et_architecture_reseau ===================-->

<chapter id="systeme_et_architecture_reseau">
 <title>Systeme_et_architecture_réseau</title>
   &architecture_standard;
   &technologies_utilisee;
   &variantes_d_architectures;
   &integration_reseau_academique;
</chapter>

<!--==================== Installation d'un slis ============================-->

<chapter id="installation d_un_slis">
 <title>Installation d'un SLIS</title>
   &materiel_necessaire;
   &procedure_d_installation;
   &branchement_du_slis;
   &validation_du_fonctionnement;
</chapter>

<!--==================== mise_oeuvre_du_site_loca ========================-->

<chapter id="mise_oeuvre_du_site_local">
 <title>Mise en oeuvre du site local</title>
   &configuration_de_l_intranet;
   &definition_des_roles;
   &autres_serveurs;
</chapter>

<!--==================== le_serveur_web_du_slis ==========================-->

<chapter id="le_serveur_web_du_slis">
 <title>Le serveur web du SLIS</title>
   &serveur_web;
   &replication_serveur_extranet;
   &bii;
   &php_et_base_sql;
</chapter>

<!--==================== description_de_l_interface_d_administration ==========-->

<chapter id="description_de_l_interface_d_administration">
 <title>Description de l'interface d'adminsitration</title>
   &introduction;
   &utilisateur;
   &valider;
   &annuler;
   &fonctions_avancees;
   &aide;
</chapter>

<!--==================== D?annage ===================================-->

<chapter id="depannage">
 <title>D?annage</title>
   &administrateur_local;
   &techniciens_academique;
</chapter>

<!--==================== FAQ ========================================-->

<chapter id="faq">
 <title>FAQ</title>
    &faq;
</chapter>

<!--==================== developpement ================================-->

<chapter id="developpement">
 <title>Développement</title>
   &developpement;
</chapter>

<!--=================== annexes =====================================-->

<chapter id="annexes">
 <title>Annexes</title>
   &disquette_setup;
</chapter>

<!--=================== Fermeture du livre ==============================-->

</book>


3.3. Entités externes

3.3.1. Définition

  • Physiquement, le document se compose d'unités appelées entités.
  • Le fichier content.ent défini les entités externes utilisées, leurs noms , le fichier *.xml associé ainsi que leur chemin dans l'arborescence adoptée.
  • C'est dans ces fichiers XML que les r?acteurs vont travailler (Les "contenus physiques").

Note

Le fichier de définition des entités content.ent n'a pas lieu d'être modifié !

3.3.2. Source

Détail du fichier content.ent :


<!ENTITY	utilisation_doc				SYSTEM	"010_introduction/utilisation_doc.xml">
<!ENTITY	historique					SYSTEM	"010_introduction/historique.xml">
<!ENTITY	objectif					SYSTEM	"010_introduction/objectif.xml">
<!ENTITY	evolution_et_developpement	SYSTEM	"010_introduction/evolution_et_developpement.xml">
<!ENTITY	articulation					SYSTEM	"010_introduction/articulation.xml">
<!ENTITY	license_gpl				SYSTEM	"010_introduction/license_gpl.xml">

<!ENTITY	resume_des_caracteristiques	SYSTEM	"020_que.../resume_des_caracteristiques.xml">
<!ENTITY	avantage_de_slis			SYSTEM	"020_que.../avantage_de_slis.xml">

<!ENTITY	php_et_base_sql				SYSTEM	"030_systeme.../php_et_base_sql.xml">
<!ENTITY	architecture_standard			SYSTEM	"030_systeme.../architecture_standard.xml">
<!ENTITY	technologies_utilisee			SYSTEM	"030_systeme.../technologies_utilisee.xml">
<!ENTITY	variantes_d_architectures		SYSTEM	"030.../variantes_d_architectures.xml">
<!ENTITY	integration_reseau_academique	SYSTEM	"030.../integration_reseau_academique.xml">

<!ENTITY	materiel_necessaire			SYSTEM	"040.../materiel_necessaire.xml">
<!ENTITY	procedure_d_installation		SYSTEM	"040.../procedure_d_installation.xml">
<!ENTITY	branchement_du_slis			SYSTEM	"040.../branchement_du_slis.xml">
<!ENTITY	validation_du_fonctionnement	SYSTEM	"040.../validation_du_fonctionnement.xml">

<!ENTITY	configuration_de_l_intranet		SYSTEM	"050_mise.../configuration_de_l_intranet.xml">
<!ENTITY	definition_des_roles			SYSTEM	"050_mise.../definition_des_roles.xml">
<!ENTITY	autres_serveurs				SYSTEM	"050_mise.../autres_serveurs.xml">

<!ENTITY	serveur_web				SYSTEM	"060_le_serveur.../serveur_web.xml">
<!ENTITY	replication_serveur_extranet 	SYSTEM	"060.../replication_serveur_extranet.xml">
<!ENTITY	bii						SYSTEM	"060_le_serveur.../bii.xml">
<!ENTITY	php_et_base_sql				SYSTEM	"060_le_serveur.../php_et_base_sql.xml">

<!ENTITY	introduction				SYSTEM	"070_description.../introduction.xml">
<!ENTITY	utilisateur					SYSTEM	"70_description.../utilisateur.xml">
<!ENTITY	fonctions_avancees			SYSTEM	"70_description.../fonctions_avancees.xml">
<!ENTITY	aide						SYSTEM	"70_description.../aide.xml">
<!ENTITY	valider					SYSTEM	"70_description.../valider.xml">
<!ENTITY	annuler					SYSTEM	"70_description.../annuler.xml">

<!ENTITY	administrateur_local			SYSTEM	"080_depannage/administrateur_local.xml">
<!ENTITY	techniciens_academique		SYSTEM	"080_depannage/techniciens_academique.xml">

<!ENTITY	faq						SYSTEM	"090_faq/faq.xml">
<!ENTITY	developpement				SYSTEM	"100_developpement/developpement.xml">

<!ENTITY	disquette_setup				SYSTEM	"110_annexes/disquette_setup.xml">

3.4. Nommage

3.4.1. Sections de niveau 1

Les sections de niveau 1 sont matérialisées par des fichiers *.xml ( entités ) rangés selon l'arborescence suivante

3.4.2. ID

De manière générale, tout nom "ID" sera suivie par la valeur numérique correspondant à son chapitre. On entends par ID "liens interne" au document (c'est l'"ancre" du html)

Exemple 1. Nommage des "ID"

Soit l'ID désignant la section "serveur web local" située dans Chapitre 7. Description de l'interface d'administration

Nommage = serveur_web_local_070

Avertissement

Au départ, le numéro du chapitre précédait le nom de l'ID. Ce nommage à changé suite au exigence de la grammaire XML ;-(


3.4.3. Images schémas et figures

Les images, figures et schémas sont placés dans le sous repertoire /img du chapitre courant. Leurs noms seront précedés de la valeur numérique correspondant à leur chapitre d'appartenance. Les extensions suivantes suivantes sont acceptées :

  • GIF

  • JPG

  • PNG

Exemple 2. Nommage des fichiers images

Soit une une image relative au chapitre "020_que_fait_slis" :

Nommage et emplacement = 020_que_fait_slis/img/020_mon_image.PNG


3.4.4. Espaces

Les espaces sont matérialisés par "_" (underscore)

3.5. Arborescence

  • Chaque section de niveau 1 est défini par un fichier situé dans le sous-repertoire correspondant à son chapitre
  • Les images et schémas sont placés dans le sous repertoire /img

3.5.1. simple

  • Placé à la racine du projet de documentation SLIS, je vois :
/010_introduction
  |
  -/img
  |
/020_que_fait_slis
  |
  -/img
  |
/030_systeme_et_architecture_reseau
  |
  -/img
  |
/040_installation_d_un_slis
  |
  -/img
  |
/050_mise_oeuvre_du_site_local
  |
  -/img
  |
/060_le_serveur_web_du_slis 
  |
  -/img
  |
/070_description_de_l_interface
  |
  -/img
  |
/080_depannage
  |
  -/img
  |
/090_faq 
  |
  -/img
  |
/100_developpement
  |
  -/img
  |
/110_annexes
  |
  -/img
  |
/img
slishowto.xml
content.ent

3.5.2. détaillée

  • Arborescence détaillée laissant apparaitre le nom des fichiers xml définissant physiquement le contenu des sections de niveau 1:
===================================
RACINE SLIS-HOWTO
===================================
	|
-------------------------------------------------
/010_introduction
-------------------------------------------------
	|
	+--/utilisation_doc.xml
	|
	+--/historique.xml
	|
	+--/objectif.xml
	|
	+--/evolution_et_developpement.xml
	|
	+--/articulation.xml
	|
	+--/license_gpl.xml
	|
 +--/img/
-------------------------------------------------
/020_que_fait_slis
-------------------------------------------------
	|
	+--/resume_des_caracteristiques.xml
	|
	+--/avantage_de_slis.xml
	|
 +--/img/

-------------------------------------------------
/030_systeme_et_architecture_reseau
-------------------------------------------------
	|
	+--/php_et_base_sql.xml
	|
	+--/architecture_standard.xml
	|
	+--/technologies_utilisee.xml
	|
	+--/variantes_d_architectures.xml
	|
	+--/integration_reseau_academique.xml
	|
 +--/img/
-------------------------------------------------
/040_installation_d_un_slis
-------------------------------------------------
	|
	+--/materiel_necessaire.xml
	|
	+--/procedure_d_installation.xml
	|
	+--/branchement_du_slis.xml
	|
	+--/validation_du_fonctionnement.xml
	|
 +--/img/
-------------------------------------------------
/050_mise_oeuvre_du_site_local
--------------------------------------------------
	|
	+--/configuration_de_l_intranet.xml
	|
	+--/definition_des_roles.xml
	|
	+--/autres_serveurs.xml
	|
 +--/img/
-------------------------------------------------
/060_le_serveur_web_du_slis
-------------------------------------------------
	|
	+--/serveur_web.xml
	|
	+--/replication_serveur_extranet.xml
	|
	+--/bii.xml
	|
	+--/php_et_base_sql.xml
	|
 +--/img/
-------------------------------------------------
/070_description_de_l_interface
-------------------------------------------------
	|
	+--/introduction.xml
	|
	+--/utilisateur.xml
	|
	+--/fonctions_avancees.xml
	|
	+--/aide.xml
	|
	+--/valider.xml
	|
	+--/annuler.xml
	|
 +--/img/
-------------------------------------------------
/080_depannage
-------------------------------------------------
	|
	+--/administrateur_local.xml
	|
	+--/techniciens_academique.xml
	|
 +--/img/
-------------------------------------------------
/090_faq
-------------------------------------------------
	|
	+--/faq.xml
	|
 +--/img/
-------------------------------------------------
/100_developpement
-------------------------------------------------
	|
	+--/developpement.xml
	|
 +--/img/
-------------------------------------------------
110_annexes
-------------------------------------------------
	|
	+--/disquette_setup.xml
	|
 +--/img/

4. Rédaction d'un document

4.2. Chapitres

  • Les chapitres sont définis dans le document root et n'ont pas lieu d'être modifiés
  • L' Id d'un chapitre est précédé de la valeur numérique correspondant à son niveau ( "010_introduction" pour le premier chapitre ...)

4.3. Sections de niveau 1

  • On ne fera aucune déclaration relative à la grammaire dans ces documents hormis la version du XML employée et le type d'encodage utilisé. Ces deux spécifications sont résumées dans la ligne suivante :
    <?xml version="1.0" encoding="iso-8859-1"?>
    Cette ligne doit apparaître en tête du document. Ensuite, on commencera directement par la balise "sect2"
  • L' Id d'une section de niveau 1 sera suivie de la valeur numérique correspondant à son chapitre ( "utilisation_doc_010" pour la premiere section de niveau 1 du chapitre 1...)

4.4. Sections de niveau 2, 3, 4 et 5

  • Elles sont inclus dans le fichier de section de niveau 1 auquel elles appartiennent
  • Chaque rédacteur est libre d'ajouter des sous sections pour structurer la section de niveau 1 qu'il rédige
  • on notera la profondeur maximum des sous sections = 5 niveaux

4.5. Encodage des caractère spéciaux (Norme ISO-8859-1)

On utilisera la norme "8859-1"

4.6. Charte graphique

Une feuille de style CSS est associée a chaque document html produit afin d'agrémenter la présentation du livre de documention. Des icônes seront associés aux balises suivantes :
  • Notes

  • Astuces

  • Important

  • Attention

  • Code

Une petite note :

Note

de musique pour de rester Zen -;)

La petite astuce :

Astuce

pour rendre service.

Un point important :

Important

Garder le moral.

Attention ! :

Avertissement

Danger !

Un bout de code :

#echo "hello world"

Afin d'améliorer la lecture du livre, je déconseille la création successive de ces balises. (deux notes ou deux warning ne se suivent pas ...)

5. Manipuler XML

5.1. Editer

Il existe aujourd'hui des éditeurs qui vont considérablement simplifier le travail du rédacteur dans le sens ou l'ensemble des balises disponibles sont proposées par le biais de menus. Par ailleurs, ces derniers garantissent la validité des documents XML produits en surveillant de près la grammaire XML lors de l'édition ainsi que la bonne imbrication des éléments fils. Il est donc très difficile de produire un documents "mal formé" avec de tels éditeurs. Notre choix s'est orienté vers un éditeurs supportant la DTD docbook : XMLMIND. Cet éditeur fonctionne sous Linux et Windows et permet l'édition de document sans restriction. Il est également possible de générer une version html du document dans la version gratuite de l'éditeur.

Note

XMLMIND ne gère pas les entités externes. Ainsi, si vous éditez le document root "slishowto.xml" avec ce dernier, cela aurait pour effet de mettre la structure hiérarchisée "à plat".

Autrement dit : XMLMIND va charger tous les fichiers xml définis par les entités au sein d'un unique fichier xml rendant l'orborescence des sous-repertoires caduques (problèmatique pour les images ...)

D'autres éditeurs XML (version d'évaluation et usines à gaz ...)

5.2. Convertir

Nous utilisons XSLTPROC pour convertir nos sources xml en documents html. Il est a noter qu'il existe également un utilitaire en ligne de commande associé à un GUI vraiment pratique: DOCMAN. Il utilise et install FOP ainsi que les DTD et XSL de DocBook (comme cela tout est fourni, tout marche, aucun problème). il permet de transformer les documents docbook en HTML, CHM, XHTML ou PDF.DOCMAN que vous le trouverez a l'adresse suivante : http://trieloff.net/docbook/distfiles/DocMan/

6. Travail coopératif

6.1. Contribuer au travail de rédaction

6.2. Obtenir un compte subersion

6.3. Utiliser Subersion

Avant de vous connecter au serveur SVN, créer un repertoire destiné son utilisation sur votre machine.

  • Pour récupérer les sources :
    #svn checkout https://svn.ac-grenoble.fr/svn/slis
  • Pour qu'une modification soit prise en compte :
    #svn -m "mon commentaire" commit mon.xml 

Pour toutes questions relatives à l'utilisation de subversion : man svn ;-)

Subversion expliqué en français : http://toutprogrammer.com/article_19.html

7. Liens utiles