Écrire des pages pour Assistant
Logram Assistant est un petit utilitaire lancé lors du premier démarrage de Logram après l'installation. Il a pour but d'afficher à utilisateur de la documentation adaptée à son niveau, qu'il soit novice en informatique, qu'il débute sous Linux, ou qu'il souhaite découvrir Logram.
Introduction
La création de pages se fait via des fichiers de type XML. La création et la traduction des pages sont choses faciles et ne demandent absolument aucune connaissance en programmation. Il vous faut simplement maîtriser le sujet dont vous voulez parler. Cette page est là pour vous apprendre comment baliser votre fichier afin d'obtenir une mise en page appropriée 
Structure d'un fichier
Un élément de la documentation (qu'il s'agisse d'une page ou d'une catégorie) correspond à un fichier XML. Ce fichier XML peut contenir plusieurs sous-pages, et permet d'insérer :
- Du texte
- Des images
- Des boutons pointant vers d'autres pages
- Des entrées de menus (pour les catégories)
Le dossier des sources d'Assistant comporte un sous-dossier pour chaque langue. Ce sous-dossier contient également un dossier "img" contenant les images utilisées par les pages, et un fichier "tree.xml" décrivant l'arborescence des pages et catégories.
Une première page simple
Voilà un fichier tout simple dont nous allons nous servir comme exemple :
<page title="Page de documentation"> <text> Écrivez ici tout le texte de la page de documentation.... </text> </page>
Vous pouvez l'enregistrer dans le dossier correspondant à votre langue, par exemple, fr. La structure de ce fichier est très simple. Comme vous pouvez le constater, tout le contenu de votre page se situe entre les balises "page" :
<page title="titre"> ........ plein de contenu </page>
L'attribut "title" de la balise "page" permet de définir le titre de votre page, tel qu'il apparaitra en gros en haut de la page, et dans le fil d'Ariane. Dans notre exemple précédent, nous avons vu également les balises "text". Elles permettent d'insérer une zone de texte dans votre page :
<text> Le contenu de votre zone de texte </text>
Les images
L'insertion d'une image se fait très simplement dans le fichier grâce à la balise image :
<img path="img/titre-de-la-page/image.png" tooltip="Ceci est une image" />
L'attribut "path" correspond au chemin absolu ou relatif (vu depuis le dossier de votre page) de l'image. Dans l'exemple ci dessus, elle se situe dans un dossier portant le nom de votre page, lui-même dans le dossier "img". En effet, afin de trop encombrer le dossier img, nous vous recommandons de créer un sous-dossier du nom de votre page pour y mettre les images que vous êtes les seuls à utiliser. Si vous pensez que l'image peut servir à plusieurs pages, (exemple, un logo de Logram ou de KDE, ou une image de Tux), placez là dans le dossier img/shared. Il contient déjà quelques images que vous pouvez utiliser. L'attribut "tooltip" représente le texte qui sera affiché au survol de l'image par le curseur.
Les liens #
Il existe actuellement 2 façons de mettre des liens vers d'autres pages dans votre document :
Boutons
Le plus simple est d'utiliser des boutons, qui donneront sur la page un aspect similaire au "QPushButton" de Qt. La déclaration se fait simplement, avec la balise suivante :
<button title="Titre de votre bouton" to="autre-page.xml" />
La encore, c'est très simple. L'attribut "title" désigne le texte qui sera affiché sur le bouton. L'attribut "to" désigne le nom de fichier de la page sur laquelle le bouton pointe. Attention, notez bien qu'il s'agit du nom de fichier, pas d'un chemin.
Menus
Le fonctionnement des menus est similaire à celui des boutons, mais permet d'obtenir plusieurs entrées les unes à la suite des autres, avec un titre, une icône, et un petit texte. Elles sont pour la plupart utilisées par les pages de catégories, qui ont des sous éléments dans l'arborescence :
<menuentry title="Entrée de menu" to="autre-page.xml" icon="img/votre-page/icone.png"> Écrivez ici la description de cette entrée de menu </menuentry>
Les attributs "title" et "to" sont sensiblement identiques à ceux de la balise "button". L'attribut "icon" désigne l'icône de votre entrée de menu. Pour le chemin à indiquer, se référer à la section sur les images. Notez que les entrées de menu n'ont vraiment d'intérêt que si vous en créez plusieurs à la suite.
Les sous-pages
Si votre page est relativement longue, vous aurez sans doute à la découper en plusieurs sous-pages. Des boutons fléchés feront alors leur apparition en haut en en bas de page, pour permettre la transition d'une sous-page à une autre. Leur déclaration se fait très simplement :
<page title="votre page"> ...... tout le contenu de la première page ... encore plein de contenu <page /> .... contenu de la deuxième page </page>
La balise "page /" agit comme un délimiteur. Attention à ne pas la confondre avec les grandes balises "page" et "/page" qui encadrent tout votre document. La balise "page /" se met bien à l'intérieur des autres, et ne nécessite pas d'être fermée par une quelconque "/page". Elle se comporte vraiment comme un séparateur.
Intégrez votre page à l'arborescence
Si elle n'en faisait pas initialement partie, il peut être intéressant d'intégrer votre page à l'arborescence des fichiers définie dans le fichier tree.xml, qui a une syntaxe légèrement différente :
<page title="Accueil" file="home.xml"> <page title="Catégorie 1" file="cat-1.xml"> <page title="Document 1" file="doc-1.xml" /> <page title="Document 2" file="doc-2.xml" /> <page title="Document 3" file="doc-3.xml" /> </page> <page> <page title="Document 4" file="doc-4.xml" /> </page> </page>
Si une page comporte une seule balise de type : "page /" c'est qu'il s'agit d'une page ne contenant que de la documentation. Si au contraire elle commence par une balise "page" et termine par "/page", c'est qu'il s'agit d'une catégorie. Tout ce qui se situe entre "page" et "/page" fait alors partie de la catégorie. Ainsi sur notre exemple nous avons une catégorie "Accueil", qui contient une "Catégorie 1" (contenant elle même 3 documents) ainsi qu'une "Catégorie 2" (contenant elle même 1 document). Vous pouvez emboîter les catégories indéfiniment. Toutes les pages (catégories ou non), ont un attribut "file" qui indique le fichier XML correspondant. Ainsi, créer une catégorie est aussi simple que créer une page normale.
Traductions
Il n'existe actuellement aucun vrai mécanisme de traduction. La seule façon de procéder est de créer un dossier correspondant à la langue souhaitée, par exemple "en" ou "it", puis d'y créer un tree.xml et des fichiers contenant les pages, traduites.
Important : Assistant étant encore actuellement en développement actif, cette page est soumise à changements. Bien que les informations indiquées ici ne risquent pas de changer, il est en revanche fort probable que des possibilités se rajoutent. Pensez à re-consulter cette page de temps à autres.