JMRI: Utiliser une Aide Java

Cette page parle des aspects techniques de la façon dont JMRI fournit des informations d'aide en utilisant JavaHelp et JHelpDev.

Organisation des fichiers aide

Les fichiers d'aide sont situés dans le répertoire "help" dans le répertoire de distribution JMRI.

La copie maître de ceux-ci est stockée dans notre répertoire comme le répertoire "help" dans le référentiel de code JMRI. Cela signifie que pour obtenir votre propre copie locale, il suffit de suivres les étapes sur la page obtention du code

Dans ce cadre, tous les fichiers de langue Anglaise sont situées dans le sous-répertoire "en". Eventuellement ce sera à vous d'internationaliser les pages d'aide.

Dans ce cadre, il y a plusieurs arbres de fichiers:

Package - organisé comme l'arbre paquet source, il contient les fichiers d'aide spécifiques au code pour par exemple une fenêtre particulière ou d'un composant. Par exemple, une fenêtre qui a créé par la classe jmri.jmrit.speedometer.SpeedometerFrame (depuis le fichier src/jmri/jmrit/speed/SpeedometerFrame.java ) devrait disposer de sa fenêtre d'aide spécifique dans un fichier de package/jmri/jmrit/speed/SpeedometerFrame.shtml.
html - une description générale, des tutoriels, etc. Ceux-ci organisés à leur tour dans des répertoires qui représentent des domaines généraux.
Manuel - une version du manuel DecoderPro reformatée pour une utilisation dans le système d'aide.( Les plus anciens sont stockés dans le site internet principal)

A long terme, nous voulons seulement deux branches dans cette structure: la partie "package" de l'arbre pour aider à l'information qui est spécifique à un morceau de code particulier, et une autre partie de l'arbre pour plus d'informations générales. (C'est une question de religion si cette 2ème partie devrait être appelé "html" ou "manuel "; l'essentiel est qu'on se retrouve avec un seul). Le web est censé être un web , avec de nombreux chemins à suivre pour atteindre le contenu. La deuxième partie de l'arbre devrait également être organisé comme "une page, un thème", avec des liens pour les connecter au besoin

Limitations de JavaHelp HTML

JavaHelp affiche "un bon vieux HTML 4.0", sans fournir certains des sucre syntaxique fourni par de nombreux navigateurs pour permettre de pauvres rendus HTML. En particulier, il y a quelques choses à surveiller.

Les balises d'ancrage demande un format spécifique. spécifiquement, elles doivent être écrites <a name="pull" id="pull"></a> Par exemple, pour mettre une balise d'ancrage sur un titre, faire <a name="foo" id="foo"></a><h2>Foo!</h2>
Note: des balises d'ancrage incorrectement structurées ( pas comme ci-dessus ) souvent provoque juste l'apparition d'un caractère < sur la page de rendu d'aide
Les d'Ancrage ont aussi besoin d'utiliser l'attribut "name" plutôt que l'attribut "id". Voir l'article ci-dessus pour un exemple.
Vous ne pouvez pas compter sur un endroit particulier pour vos fichiers sur la machine locale, aussi tous les liens vers les autres pages d'aide doivent être relatifs.
les liens vers des pages Web en dehors du système d'aide de travail, mais JavaHelp ne peut pas afficher les fichiers PDF. Les Liens vers ceux-ci doivent être représentés de façon explicite comme des liens, afin qu'ils puissent être copiés sur un navigateur Web extérieur.

Accès Web à l'aide

Il est génant d'avoir à maintenir deux pages Web distinctes pour les site web principaux et le système d'aide. Pour réduire le besoin pour cela, nous utilisons un formulaire particulier pour les pages web dans le système d'aide.

utilisation de l'extensions de fichiers ". shtml" de telle sorte que les serveurs Web principaux recherchent les fichiers pour les serveurs inclus .
Lorsque vous créez une nouvelle page, commencez par une copie soit du fichier modèle Aide/fr/template-sidebar.shtml ou de l'aide/fr/template-no-sidebar.shtml , selon que vous souhaitez ou non inclure une "Sidebar" via un fichier du même nom. Cela mettra en haut et en bas la matière en place pour obtenir que la page s'affiche correctement.

Accès au code

Dans le code JMRI, l'accès au système d'aide est obtenu via la classe jmri.util.HelpUtil. (Pour des raisons historiques, il y a un peu de code dans apps.Apps, mais vous devriez l'ignorer).

La façon la plus simple d'ajouter un menu d'aide à un cadre est d'avoir soit un JmriJFrame (que vous devrez faire de toute façon), et appelé addHelpMenu (...) après que vous ayez construit les autres menus.

Par convention, nous utilisons une arborescence de fichiers similaire pour les fichiers de code source et d'aide. Par exemple, la jmri.jmrit.simpleclock.SimpleClockFrame classe hérite de JmriJFrame, et ajoute un menu d'aide avec la ligne addHelpMenu ("package.jmri.jmrit.simpleclock.SimpleClockFrame", true); Le fichier d'aide est alors située à help/fr/package/jmri/jmrit/simpleclock/SimpleClockFrame.shtml .

Un certain nombre de fichiers d'aide ont été mis en place sans contenu; j'espère que certains utilisateurs les modifierons et renverrons l'ascenseur.

Création des fichiers de contrôle avec JHelpDev

JavaHelp utilise divers fichiers XML pour contrôler la façon dont la table des matières et l'index sont affichés. Nous créons les JHelpDev. S'il vous plaît ne pas les modifier manuellement.

JHelpDev est maintenant inclut dans la distribution JMRI. Pour utiliser cet outil:

Assurez-vous que vous avez exécuté "update" depuis SVN avant de commencer.
Démarrez l'outil en cliquant sur le fichier jhelpdev.jar. (Si cela ne fonctionne pas, essayez en exécutant JHelpDev.csh ou JHelpDev.bat, selon le type d'ordinateur que vous avez)
Une fois que la fenêtre s'affiche, sélectionnez "Ouvrir un projet" dans le menu "Fichier".
Naviguez vers le répertoire "help" dans votre copie extraite du code, puis le répertoire "fr" dans ce cadre, puis sélectionnez le fichier "JHelpDev.xml" et cliquez sur "Open".
Vous pouvez avoir un message "[Fatal Error] index.html:1:3: Les déclarations de balisage contenues ou pointées par le document type de déclaration doivent être bien formées." Bien qu'il dit qu'il est fatal, il n'est pas vraiment un problème. N'y faites pas attention. Au démarrage de la carte (un fichier contenant l'index JHelpDev de tous les points d'ancrage dans le système d'aide JMRI) est régénéré.
Cliquez sur l'onglet "Index Editor" ou "TOC Editor" pour réactualiser les entrées d'Aides. Une ligne rouge marque un lien hypertexte que JHelpDev ne peut pas localiser sur le disque. Faites un clic droit sur une telle ligne pour ouvrir le menu Edit context.
Cliquez sur le bouton "Create All" pour recréer le TOC, Index, etc.
Puis, de retour sur la ligne de commande et dans le répertoire de help/fr, appelez "ant" pour créer l'index Web et les pages de la table des matières (Ou si vous utilisez Eclipse, faites un clic droit sur le fichier help/fr/build.xml et sélectionnez Exécuter en tant que construction Ant.)

Les différents fichiers de contrôle qui utilise JavaHelp sont stockés dans notre référentiel de code, donc, une fois que vous avez fait ceci ils seront montrés comme modifié. S'il vous plaît vérifier les lorsque vous vérifiez de nouveaux fichiers d'aide pour que les autres personnes n'aient pas à recréer les fichiers de contrôle eux-mêmes. site web JHelpDev.

Table des Matières (TOC) et Index

Aide Java inclut une table des matières (toc) et un index. Ils sont les eux disponibles comme un lien hyperliens sur le web, et fournis via une agréable interface utilisateur lors de l'utilisation dans le programme.

L'information sous-jacente doit êrte maintenue manuellement dans ls fichiers respectifs help/fr/JmriHelp_enTOC.xml and help/fr/JmriHelp_enIndex.xml. JHelpDev fait alors les fichiers dont Java Help a besoin, et une étape "ant" dans le répertoire fait les fichiers webtoc.shtml et webindex.shtml qui sont affichés sur le web.

vous pouvez aussi utiliser l'outil JHelpDev pour ajouter des articles á la table des matières et á l'index si vous voulez. Il y a plus d'infos sur comment le faire sur le site web JHelpDev. Rappelez-vous d'exécuter "ant" après chaque ajout pour actualiser les versions web.

Mise à jour du site JMRI.org

Des changements pour les pages d'aide qui sont vérifiées devrait apparaître automatiquement sur le site JMRI.org après un court moment.Il y a une tâche Jenkins qui manipule périodiquement les actualisations pour les pages statistiques ( depuis le répertoire, comme JavaDoc )