Info sur JMRI:
Outils de Développement
Structure
Techniques et Standards
Comment Faire
Infos Fonctionnelles
Contexte Infos

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:

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.

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.

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:

  1. Assurez-vous que vous avez exécuté "update" depuis SVN avant de commencer.
  2. 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)
  3. Une fois que la fenêtre s'affiche, sélectionnez "Ouvrir un projet" dans le menu "Fichier".
  4. 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é.
  5. 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.
  6. Cliquez sur le bouton "Create All" pour recréer le TOC, Index, etc.
  7. 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 )