Changes between Initial Version and Version 1 of Divers/recommandations/Trac

Timestamp:

Jun 21, 2006, 3:46:41 PM (18 years ago)

Author:

/C=FR/O=CNRS/OU=UMR8607/CN=Antoine Perus/emailAddress=perus@…

Comment:

--

Divers/recommandations/Trac

@@ +1 @@
+= Recommandations pour la Structuration d'un Projet =
+[[TracNav]]
+
+[[TOC(inline)]]
+
+Cette note présente quelques éléments pour structurer un projet Trac, en particulier les page du !WiKi. Ces recommandations sont issues de l'expérience de la gestion de quelques projets mais ne sont en rien obligatoires. Leur but est d'aider à conserver un site gérable quand le nombre de documents augmente et à maintenir une navigation facile dans les documents.
+
+== Organisation des pages du Wiki ==
+
+Le !WiKi de Trac permet une organisation hiérarchique des pages. Toute l'arborescence des pages du !WiKi se trouve sous l'url 'wiki/' du projet.
+
+La recommandation est de créer une hiérarchie de documents correspondant aux différentes catégories de pages. Par exemple :
+
+{{{
+        wiki/Doc
+        wiki/Divers
+        wiki/Action
+}}}
+
+Chacun de ces niveaux peut lui-même être subdivisé. Par exemple :
+
+{{{
+        wiki/Doc/Apache
+        wiki/Doc/Trac
+}}}
+
+Il y a plusieurs avantages à une telle structuration :
+
+ * Si on demande la liste de [wiki:TitleIndex toutes les pages] du !WiKi, on visualise plus facilement les pages qui ont un lien entre elle. On peut obtenir un effet similaire en utilisant un préfixe commun aux pages traitant du même sujet. Mais ce sera moins exploitable par les outils de navigation décrits plus loin...
+ * En l'absence de tags attachés aux pages, on va pouvoir exploiter cette structure hiérarchique pour offrir une navigation facile dans l'ensemble des documents.
+
+Il est important de prendre le temps pour organiser la structure avant de créer les pages car la modification ultérieure du nom des pages (possible uniquement en copiant/collant le contenu de pages existantes dans de nouvelles pages) cassera inévitablement les références entre page.
+
+== Barre de Navigation ==
+
+=== Configuration ===
+
+Il y a plusieurs facons de construire des menus de navigation. Celle décrite ici repose sur l'utilisation du macro [http://svn.ipd.uka.de/trac/javaparty/wiki/TracNav/Usage TracNav], utilisé dans cette page. !TracNav offre plusieurs fonctionnalités intéressantes :
+
+ * La description des menus disponibles se fait dans une page !WiKi standard en utilisant des listes à puce.
+ * On peut avoir plusieurs niveaux de menus en imbriquant les listes à puces
+ * Lorsqu'il y a plusieurs niveaux, seul la catégorie correspondant au document courant est déroulé, ce qui permet de conserver un menu de navigation court avec un grand nombre de documents.
+
+Pour utiliser TracNav, il suffit de placer l'appel du macro en tête de toutes les pages qui doivent afficher le menu de navigation, généralement après le titre, avec les instructions suivantes :
+
+{{{
+         [[TracNav]]
+}}}
+
+A la première invocation, cela fait apparaître un pavé de navigation vide, avec menu ''Edit''. Ce menu donne accès à l'édition de la page !WiKi qui va contenir les menus, par défaut ''wiki/TOC'' (le mieux est de conserver ce défaut).
+
+Dans cette page, on va trouver l'appel à !TracNav et des listes à puce. Par exemple :
+
+{{{
+[[TracNav]]
+
+ * [wiki:Doc Documentations]
+   * [wiki:Doc Introduction]
+   * [wiki:Doc/Apache Apache]
+     * [wiki:Doc/Apache Introduction]
+     * [wiki:Doc/Apache/ChangeLog Changements de Configuration]
+     * [wiki:Doc/Apache/AccountMgt Gestion des Comptes]
+   * [wiki:Doc/Mail Mailer]
+     * [wiki:Doc/Mail Introduction]
+   * [wiki:Doc/Storage Disques et Backup]
+     * [wiki:Doc/Storage Introduction]
+     * [wiki:Doc/Storage/DiskReplace Remplacement Disque ESA12000]
+   * [wiki:Doc/Trac Trac]
+     * [wiki:Doc/Trac Introduction]
+     * [wiki:Doc/Trac/Configuration Configuration]
+     * [wiki:Doc/Trac/ProjStruct Structuration d'un Projet]
+ * Divers
+   * [wiki:Divers/WikiLALGuidelines Utilisation du WiKi]
+     * [wiki:Divers/WikiLALGuidelines Editer une page]
+}}}
+
+Les éléments des listes à puce peuvent être soit du texte litéral, soit des [http://trac.lal.in2p3.fr/W2KIN2P3/wiki/WikiFormatting références] à des pages Wiki avec la syntaxe explicite utilisé ici.
+
+Si on visualite une page qui fait appel à !TracNav mais n'est pas listé dans la page TOC, l'ensemble du menu apparait déroulé. Si la page se trouve dans le menu TOC, la partie du menu auquel elle appartient est déroulée et les autres sont repliées et transformées en lien. La partie déroulée apparaît toujours en tête.
+
+Lorsqu'on clique sur un lien qui a des sous menus, le document associé à ce lien s'ouvre. Il faut mettre dans le menu une deuxième entrée associée au même document (mais éventuellement avec un autre texte) pour que la page correspondante soit considérée répertoriée dans le TOC. C'est la raison des répétitions comme :
+
+{{{
+ * [wiki:Doc Documentations]
+   * [wiki:Doc Introduction]
+}}}
+
+
+=== Ajouter de nouvelles entrées ===
+
+Pour ajouter une entrée dans le menu, il suffit de l'éditer avec le menu ''edit''. On peut référencer une page existante mais on peut aussi nommer une nouvelle page. En effet, c'est une fonctionnalité de base de TracWiki : si on référence une page inexistance, cela donne accès à une page permettant de la créer. C'est donc souvent le moyen le plus simple de créer de nouvelles pages, en étant sur que la référence sera correcte.
+
+
+=== Conséquence sur l'organisation des pages ===
+
+A chaque niveau de menu, il peut être intéressant d'associer un niveau de hiérarchie dans le nommage des pages. Pour chaque niveau ainsi créer, la recommandation est de créer une page portant le même nom que le niveau et qui deviendra la page d'aperçu du niveau correspondant. Voir la structuration de ce site pour des exemples.
+
+=== Index des pages d'une catégorie ===
+
+Dans la page d'aperçu, il peut être intéressant de donner un accès à toutes les pages de la catégorie, y compris celles qui ne seraient pas dans le menu de navigation. Ceci est grandement facilité par l'organisation hiérarchique des pages. Il suffit d'ajouter dans la page d'aperçu un lien tel que :
+
+{{{
+         [wiki:category/TitleIndex Liste des documents]
+}}}
+
+et de créer le document correspondant (en cliquant sur la référence créée précédemment par exemple) dont une version de base est :
+
+{{{
+= Liste des Documents =
+[[TracNav]]
+
+[[TOC(titleindex,inline)]]
+}}}
+
+Cela produit une liste de toutes les pages de la catégorie, avec le titre de la page en description.
+
+Il est aussi possible d'utiliser le macro TitleIndex au lieu [wiki:Doc/Trac/Macros#TOC TOC]. Dans ce cas, la liste ne contient que le nom des pages, sans le titre.
+
+
+== Table des Matières ==
+
+Quand on écrit des pages un peu longues, il peut être intéressant de générer en tête de la page une table des matières à partir de la structure de la pages (les différents niveaux de titre). Cela se fait très simplement en ajoutant au début de la page (généralement après l'appel à !TracNav) un appel au macro [wiki:Doc/Trac/Macros#TOC TOC]. Par exemple :
+
+{{{
+[[TOC(inline)]]
+}}}
+
+Le paramètre ''inline'' indique que la table des matières doit être instérée au fil du texte et non pas dans une boite de navigation. C'est généralement plus agréable si on utilise aussi !TracNav.
+
+Pour un exemple, éditer cette page.
+
+La macro [wiki:Doc/Trac/Macros#TOC TOC] permet aussi de faire la table des matières de une ou plusieurs autres pages, en les passant leur nom en paramètre de la macro.
+
+== Page de démarrage ==
+
+En lien avec le menu de navigation, il peut être intéressant que la page de démarragedu !WiKi ne soit pas celle par défaut (wiki). Pour cela il suffit de l'éditer et de remplacer son contenu par :
+
+{{{
+= Titre de la page de demarrage =
+
+[redirect(wiki:ma/page/de/demarrage)]
+}}}