Plug-ins
Documentation en ligne
Date de publication : 26/10/2011. Date de mise à jour : 22/12/2011.
Par
Serge Bachmann
La commande "Help > Help Contents" affiche la documentation en ligne.
Ce document permet de développer notre propre documentation.
1. Introduction
1-A. Spécification
1-B. Lancement de la plateforme Eclipse
1-C. Passage en perspective « Plug-in Development »
2. Initialisation du Plug-in
2-A. Création du projet
3. Construction du Plug-in
3-A. Génération de la documentation à partir d'un template
3-B. Description de la structure de la documentation
3-B-1. « Tables of contents » (les fichiers « toc »)
3-B-1-A. « toc.xml »
3-B-1-B. « tocgettingstarted.xml »
3-B-1-C. « tocreference.xml »
3-C. Schéma de la structure de la documentation
4. Visualisation de la documentation générée
5. Édition de la documentation
5-A. Renommer la documentation
5-B. Ajouter un sujet dans « getting started »
5-B-1. Création des fichiers html
5-B-2. Création du sujet Champignons
5-C. Test
6. Édition fichier « HTML »
6-A. Création « folder » Images
6-B. Édition des fichiers html
6-C. Test
7. Création plug-in
8. Conclusions
9. Licence
1. Introduction
1-A. Spécification
Créer une documentation accessible à partir de la commande :
« Help > Help Contents »
1-B. Lancement de la plateforme Eclipse
Double cliquer :
ou le raccourci vers cet exécutable si vous l'avez créé dans le répertoire destiné à recevoir les « workspaces ». La plate-forme « Eclipse » est lancée:
On sélectionne le « workspace »:
Cliquer « OK », Fermer la fenêtre « Welcome »
1-C. Passage en perspective « Plug-in Development »
Faire : « Window - Open Perspective > Other... » :
Dans « Open Perspective » sélectionner « Plug-in Development »:
Cliquer « OK »
Pour simplifier le « Workbench » on ferme les vues: Outline, Task List, Error Log, Problems, Tasks, Plug-ins). Avant de fermer une vue il peut être nécessaire de la faire apparaître, dans le cas de la vue « Plug-ins » sa visualisation est longue.
On obtient:
2. Initialisation du Plug-in
2-A. Création du projet
Sélectionner « File > New > Plug-in Project »
Dans « New Plug-in Project - Plug-in Project » nommer le projet :
Cliquer « Next > ».
Dans « New Plug in Project - Content » donner le nom du provider » :
Cliquer « Finish ».
3. Construction du Plug-in
3-A. Génération de la documentation à partir d'un template
Dans le « Plugin Manifest Editor » onglet « Extensions » cliquer « Add... ». Dans « New Extension - Extension Point Selection » sélectionner l'onglet « Extension Wizard » et choisir « Help Content »
Cliquer « Next> ».
Dans « Help Table of Contents - Sample Help Table of Contents » sélectionner les éléments qui constitueront la documentation:
Cliquer « Finish ». Faire une sauvegarde
On obtient:
3-B. Description de la structure de la documentation
La documentation est construite à partir de l'extension « org.eclipse.help.toc »
Sélectionnons dans le « Plug-in Manifest Editor », l'onglet « Extension » on à :
en sélectionnant l'onglet « plugin.xml » on visualise toutes les initialisations :
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
<extension
point="org.eclipse.help.toc">
<toc
file="toc.xml"
primary="true">
</toc>
<toc
file="tocgettingstarted.xml">
</toc>
<toc
file="tocreference.xml">
</toc>
</extension>
</plugin>
|
Cette extension définit les fichiers « toc »
(1) de premier et de second niveau. L'attribut « file » défini le nom des fichiers « toc ». L'attribut « primary » à true indique que le fichier « toc » apparaît au premier niveau dans la structure de la documentation. Un fichier de second niveau ne sera pris en compte que s'il est référencé par un fichier de premier niveau.
Ici, « toc.xml » est de premier niveau il devra référencer "tocgettingstarted.xml" et "tocreference.xml".
3-B-1. « Tables of contents » (les fichiers « toc »)
3-B-1-A. « toc.xml »
Cet la table de premier niveau.
Double cliquer dans la vue « Package Explorer » « toc.xml » sélectionner l'onglet « Definition » :
Si on sélectionne l'onglet « Source » on visualise la totalité de la définition de la table :
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toclabel="Sample Table of Contents"topic="html/toc.html">
<topiclabel="Getting Started">
<anchorid="gettingstarted"/>
</topic>
<topiclabel="Reference">
<anchorid="reference"/>
</topic>
</toc>
|
L'attribut « label » spécifie le texte visualisé dans la liste des sujets (« topics »).
L'attribut « topic » spécifie le texte qui est visualisé si le sujet est sélectionné.
La documentation est ici construite dans une démarche « bottom-up ». dans ce cas le fichier « toc » défini les points d'ancrage ou s'accrocheront d'autre fichiers « toc ». Deux points d'ancrage sont définis "gettingstarted" et "reference".
3-B-1-B. « tocgettingstarted.xml »
Double cliquer dans la vue « Package Explorer » « tocgettingstarted.xml » sélectionner l'onglet « Definition » :
Si on sélectionne l'onglet « Source » on visualise la totalité de la définition de « Getting Started » :
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toclabel="Getting Started"link_to="toc.xml#gettingstarted">
<topiclabel="Main Topic" href="html/gettingstarted/maintopic.html">
<topiclabel="Sub Topic"href="html/gettingstarted/subtopic.html"/>
</topic>
<topiclabel="Main Topic 2">
<topiclabel="Sub Topic 2"href="html/gettingstarted/subtopic2.html"/>
</topic>
</toc>
|
L'attribut « link to » accroche ce fichier à l'ancre "gettingstarted" du fichier "toc.xml".
Puis on défini deux sujets. A chaque sujet est associé un label et un fichier « html ».
3-B-1-C. « tocreference.xml »
Si on sélectionne l'onglet « Source » on visualise la totalité de la définition de « Reference » :
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toclabel="Reference"link_to="toc.xml#reference">
<topiclabel="Main Topic" href="html/reference/maintopic.html">
<topiclabel="Sub Topic"href="html/reference/subtopic.html"/>
</topic>
<topiclabel="Main Topic 2">
<topiclabel="Sub Topic 2"href="html/reference/subtopic2.html"/>
</topic>
</toc>
|
Comme pour la table précédente, l'attribut « link to » accroche ce fichier à l'ancre "reference" du fichier "toc.xml".
3-C. Schéma de la structure de la documentation
L'organisation globale de la documentation est illustrée par la figure ci-dessous:
4. Visualisation de la documentation générée
Faire un clic droit sur le projet « org.eclipse.helpProject » et sélectionner « Run As > Run Configuration... ».
Dans «Run configuration - Create, manage, and run configurations » double cliquer « Eclipse Application ». Une nouvelle configuration est créée, la nommer « DocEnLigne », cliquer « Apply » :
Cliquer « Run ». Une nouvelle plate-forme Eclipse est lancée.
Sélectionner « Help > Help Contents »:
La documentation « Sample Table of Contents » est visualisée :
Vous pouvez naviguer dans cette documentation :
et par exemple sélectionner « Main Topic 2 » dans « Contents » :
5. Édition de la documentation
5-A. Renommer la documentation
Double cliquer dans la vue « Package Explorer » « toc.xml ». Dans « Book Details » renommer la documentation :
Faire une sauvegarde.
5-B. Ajouter un sujet dans « getting started »
On va ajouter un nouveau sujet à « Getting Started »:
5-B-1. Création des fichiers html
Faire un clic droit sur « html/gettingstarted » et sélectionner la commande « New > File ». Nommer le fichier « Champignons.html »
Cliquer « Finish » le fichier est créé :
Ouvrir le fichier avec l'éditeur « Text Editor » :
l'éditer :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>LesChampignons</title>
</head>
<body>
<h1>Leschampignons</h1>
Une classification simpliste d'un non spécialiste.
</body>
</html>
|
Créer de même les autres fichiers:
Divers3_1.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Divers</title>
</head>
<body>
<h1>Divers</h1>
Divers champignons.
</body>
</html>
|
Bolet3_2.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Bolets</title>
</head>
<body>
<h1>Bolet</h1>
Pour reconnaitreunboletleretourner,
ledessousduchapeauestcomposéde tubes juxtaposés.
</body>
</html>
|
BonBolet3_2_1.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>BonsBolets</title>
</head>
<body>
<h1>BonsBolets</h1>
C'est bon!
</body>
</html>
|
AutreBolet3_2_2.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>AutreBolet</title>
</head>
<body>
<h1>AutreBolet</h1>
C'est pas bon!
</body>
</html>
|
Faire une sauvegarde générale. On à :
5-B-2. Création du sujet Champignons
Dans la vue « Package Explorer » double cliquer « tocgettingstarted.xml ». Dans « Getting Started » on va éditer « Table of Contents ».
Faire un clic droit sur « Getting Started » et sélectionner « New > Topic »:
Initialiser « Topic Details »:
On crée un sous « topic » à champignons:
que l'on initialise dans « Topic Details »:
On fini de construire l'arborescence des sujets :
On fini de construire l'arborescence des sujets :
ce qui correspond au source:
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toclabel="Getting Started"link_to="toc.xml#gettingstarted">
<topiclabel="Main Topic" href="html/gettingstarted/maintopic.html">
<topiclabel="Sub Topic"href="html/gettingstarted/subtopic.html"/>
</topic>
<topiclabel="Main Topic 2">
<topiclabel="Sub Topic 2"href="html/gettingstarted/subtopic2.html"/>
</topic>
<topic href="html/gettingstarted/Champignons.html" label="Champignons">
<topic href="html/gettingstarted/Divers3_1.html" label="Divers">
</topic>
<topic href="html/gettingstarted/Bolet3_2.html" label="Bolets">
<topic href="html/gettingstarted/BonBolet3_2_1.html" label="Bons Bolets">
</topic>
<topic href="html/gettingstarted/AutreBolet3_2_2.html" label="Autres Bolets">
</topic>
</topic>
</topic>
</toc>
|
5-C. Test
Lancer le test avec :
Une nouvelle plateforme Eclipse est lancé. Sélectionner « Help > Help Contents ». La fenêtre « Help - Eclipse - Plateform » contient notre documentation et en particulier le sujet « Champignons »:
6. Édition fichier « HTML »
6-A. Création « folder » Images
On crée un folder « Images ». Faire un clic droit sur « org.eclipse.helpProject » sélectionner « New > Folder »:
Dans « New Folder - Folder » nommer le folder:
On place les photos directement dans le folder « Image » en réalisant par exemple des (Copy / Paste) :
6-B. Édition des fichiers html
Ouvrir les fichiers avec « Text Editor » puis les éditer :
AutreBolets3_2_2.html :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
<TITLE>Autre Bolet</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0 (Win32)">
<META NAME="CREATED" CONTENT="0;0">
<META NAME="CHANGED" CONTENT="20100421;9332700">
</HEAD>
<BODY LANG="fr-FR" DIR="LTR">
<H1>Autre Bolet</H1>
<P><IMG SRC="../../Images/BoletPiedRouge.JPG" NAME="images1" ALIGN=LEFT WIDTH=249 HEIGHT=197 BORDER=0><BR CLEAR=LEFT>Bolet
pied Rouge</P>
</BODY>
</HTML>
|
BonBolet3_2_1.html :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
<TITLE>Bons Bolets</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0 (Win32)">
<META NAME="CREATED" CONTENT="0;0">
<META NAME="CHANGED" CONTENT="20100421;9391900">
</HEAD>
<BODY LANG="fr-FR" DIR="LTR">
<H1>Bons Bolets</H1>
<P><IMG SRC="../../Images/BonBolet.jpg" NAME="images1" ALIGN=LEFT WIDTH=148 HEIGHT=194 BORDER=0><BR CLEAR=LEFT>cèpe
de Bordeaux ou Boletus edulis</P>
<P>C'est bon!
</P>
</BODY>
|
Divers3_1.html :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
<TITLE>Divers </TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0 (Win32)">
<META NAME="CREATED" CONTENT="0;0">
<META NAME="CHANGED" CONTENT="20100421;9564000">
</HEAD>
<BODY LANG="fr-FR" DIR="LTR">
<H1>Divers</H1>
<P><IMG SRC="../../Images/AmaniteTueMouches.jpg" NAME="images1" ALIGN=LEFT WIDTH=250 HEIGHT=185 BORDER=0><BR CLEAR=LEFT>Amanite
tue mouches</P>
<P><IMG SRC="../../Images/astreeHygromtrique.jpg" NAME="images2" ALIGN=LEFT WIDTH=248 HEIGHT=186 BORDER=0><BR CLEAR=LEFT>Astrée
hygrométrique</P>
</BODY>
</HTML>
|
Faire une sauvegarde générale.
6-C. Test
Lancer le test avec :
Une nouvelle plateforme Eclipse est lancé. Sélectionner « Help > Help Contents ». La fenêtre « Help - Eclipse Platform » contient notre documentation et en particulier le sujet « Champignons » mis à jour:
7. Création plug-in
Il est nécessaire d'indiquer précisément le contenu du plug-in.
Pour cela ouvrir le « plug-in Manifest Editor » en double cliquant le fichier « META-INF / MANIFEST.MF ». Sélectionner l'onglet « Build ». Dans la zone « Binary Build » sélectionner tout ce qui est nécessaire à la construction de la documentation:
Faire une sauvegarde. Faire un clic droit sur « org.eclipse.helpProject » et sélectionner « Export... ». Dans « Export - Select » sélectionner « Plug-in Development/Deployable plug-ins and fragments ». Cliquer « Next > ». Dans « Export - Deployable plug-in and fragments » choisir le répertoire pour recevoir le plug-in:
Cliquer « Finish ». Le plug-in est créé:
Relancer Eclipse (peu importe le workspace).
Sélectionner « Help > Help Contents » la documentation s'affiche:
8. Conclusions
Comme le montre ce document il est simple de mettre en place la documentation en ligne associé à un « plug-in ». Le seul piège a éviter c'est de ne pas oublier de spécifier le contenu du « plug-in ».
9. Licence
La licence « créative commons » :
s'applique à ce document.
| (1) | « Toc » pour : Table of contents |
