A présent que nous avons nos fichiers d'exemple de contenu, nous pouvons créez un fichier de rubriques. Celui-ci définit les points d'entrée clés dans les fichiers de contenu HTML en mappant un ID et un libellé de rubrique sur une référence dans l'un des fichiers HTML. Un fichier de rubriques agit comme une table des matières pour un ensemble de contenu HTML.
Les applications dont la migration est effectuée vers la plateforme peuvent réutiliser une documentation existante en utilisant le fichier des rubriques pour définir des points d'entrée dans la documentation.
Un plug-in peut avoir un ou plusieurs fichiers de rubriques. Ceux-ci sont parfois appelés fichiers de navigation du fait qu'ils décrivent comment naviguer dans le contenu HTML. Notre exemple de documentation s'organise en trois catégories principales : les concepts, les tâches et les références. Comment réaliser des fichiers de rubriques représentant cette structure ?
Nous pouvons constituer un grand fichier de rubriques ou un fichier de rubriques distinct pour chaque catégorie principale de contenu. Cette décision doit être prise en fonction du mode de coopération des équipes de documentation. Si un auteur différent détient chaque catégorie, il peut s'avérer préférable de garder des fichiers de rubriques distincts pour chaque catégorie. La décision n'est pas dictée par l'architecture de la plateforme.
Dans cet exemple, nous allons créer un fichier de rubriques pour chaque catégorie de contenu principal. Pour un tel petit nombre de fichiers, avoir des fichiers de rubriques distincts pour chaque catégorie peut s'avérer inutile. Nous lierons cet exemple comme si nous avions davantage de fichiers ou des auteurs différents détenant chacun une catégorie de contenu.
Nos fichiers sont du type suivant :
<topics id="conceptsAll">
<topic label="Concept1" href="doc/concepts/concept1.html">
<topic label="Concept1_1" href="doc/concepts/concept1_1.html"/>
<topic label="Concept1_2" href="doc/concepts/concept1_2.html"/>
</topic>
</topics>
<topics id="tasksAll">
<topic id="plainTasks" label="Plain Stuff">
<topic label="Task1" href="doc/tasks/task1.html"/>
<topic label="Task2" href="doc/tasks/task2.html"/>
</topic> <topic id="funTasks" label="Fun Stuff" >
<topic label="Task3_1" href="doc/tasks/task3_1.html"/>
<topic label="Task3_2" href="doc/tasks/task3_2.html"/>
</topic>
</topics>
<topics id="refAll">
<topic label="Ref1" href="doc/ref/ref1.html"/>
<topic label="Ref2" href="doc/ref/ref2.html"/>
</topics>
Les rubriques sont ajoutées en tant que fragment de l'élément du conteneur de rubriques. Une rubrique peut être un simple lien au contenu. Par exemple, "Task1" fourni un libellé et une liaison href au contenu. Une rubrique peut être également un regroupement hiérarchique de sous-rubriques sans contenu. Par exemple, "Fun Stuff" ne dispose que d'un libellé et de sous-rubriques, mais pas de liaison href. Les rubriques peuvent également avoir les deux. "Concept1" dispose d'une liaison href et de sous-rubriques.
S'il est utilisé comme lien, l'argument contenu dans href est présumé relatif au plug-in courant.
Lorsque nous commençons à lier ces rubriques au support de documentation global, nous nous y référons à l'aide de leur ID. Seules les rubriques disposant d'un ID peuvent être manipulées. Pour lier la totalité des sous-rubriques pour une rubrique spécifique, nous pouvons lier la rubrique parente. Par exemple, la liaison de "Concept1" lierait également "Concept1_1" et "Concept1_2."
Nous modifierons ultérieurement le fichier plugin.xml pour ajouter les contributions réelles pointant sur ces fichiers.