Aspects internes

Fonctionnement de uman()

• uman parcourt SCI/contrib/*, SCIHOME/contrib/*, et tous les chemins/* figurant dans les Chemins des modules externes hors ~/contrib déclarés dans les préférences. La liste de toutes les archives ./jar/*.jar trouvées est établie et enregistrée. Le nom des modules afférents et langues est déterminé pour chacun des fichiers .jar.
  Cet inventaire est réalisé
  • la 1ère fois que uman est utilisée, après son installation,
  • après chaque installation ou désinstallation d'un module ATOMS,
  • ou lorsque l'option "r" est utilisée (=refresh / reload).

• Lorsque uman est appelé, un algorithme complexe analyse le pattern afin de déterminer s'il concerne un item de Scilab, ou d'un module ATOMS installé (et lequel), ou une autre ressource connue de uman : autre module externe installé, module ATOMS non installé, fonction distribuée sur le FileExchange officiel, module d'une forge Scilab, autre référence externe. Il peut aussi s'agir d'un alias ou d'une redirection (par exemple d'un terme d'Octave vers le terme Scilab correspondant). Dans ce cas, la cible effective de la requête, et la référence documentaire correspondante (nom de module, URL, etc), sont déterminées en seconde "passe".
  L'option "x" modifie les priorités de l'algorithme.
  Les détails de l'algorithme sont consultables directement dans le code de uman, à partir de la ligne étiquetée "SEARCHING FOR THE RIGHT HELP TARGET".

• Lorsque l'item a effectivement une page d'aide identifiée, celle-ci est extraite de son archive ./jar/*.jar et est stockée dans un sous-dossier de SCIHOME/uman, en cache. Les appels suivants à uman à la même page réutilisent alors la copie déjà extraite (à moins que l'option "r" soit utilisée).

Conditionnement des modules et de leur documentation

Pour être correctement parcouru à la recherche de sa documentation, un module (ATOMS ou autre) indexé doit être a minima conditionné comme suit :

• Le nom du dossier racine du module est libre.
• Un sous-dossier ./etc doit exister et contenir le fichier ./etc/*.start, où * désigne le nom du module. Ce fichier peut être vide, mais il est obligatoire. Il est utilisé uniquement pour obtenir le nom du module.
• Un sous-dossier ./jar doit exister. Il contient les fichiers standard compressés scilab_##_##_help.jar, tels que générés par le compilateur des pages d'aide de Scilab. ##_## désigne les langues (tel que fr_FR) (un fichierpar langue).

C'est tout. Tout sous-dossier supplémentaire est ignoré par uman.

Pour les modes console, "g", et "w"

Nous ne donnerons pas ici l'algorithme détaillé de recherche documentaire suivi par uman en fonction du patterndonné. Nous listerons juste les différents critères et sources utilisés. L'algorithme est consultable directement dans le code, dans la partie "SEARCHING FOR THE RIGHT HELP TARGET". La prise en compte les possibles redirections de tous types, de l'option "x", de la langue choisie, et de la casse typographique du pattern est directement considérée dans le code.

Les sources documentaires suivantes sont considérées :

• Listes des alias / redirections Scilab->Scilab (raccourcis), externe->Scilab, et de faux-amis (si l'option "x" est utilisée).
• Pages d'aide Scilab officielles, dans les 5 langues principalement supportées et distribuées (en, fr, ja, pt, ru).
• Pages d'aide des modules ATOMS installés en modes "all users" (par l'administrateur) et "user" (par l'utilisateur).
• Pages d'aide des autres modules externes installés dans les dossiers SCI\contrib ou SCIHOME\contrib ou dans leurs sous-dossiers.
• Autres archives documentaires .jar stockées dans les dossiers ou sous-dossiers déclarés en Chemins des modules externes hors ~/contrib, dans les Préférences uman.
• Commentaires d'en-tête des fonctions locales écrites en langage Scilab et ne disposant pas de page d'aide dédiée standard.

Si aucune de ces ressources ne correspond au pattern ou à ses possibles alias, d'autres ressources externes indexées mais non installées sont scrutées, à savoir :

• La table uman des alias / redirections externe->externe.
• Les modules ATOMS indexés mais non installés.
• Des modules hors ATOMS disponibles sur une forge Scilab publique.
• Des ressources originales et correctement conditionnées disponibles sur le FileExchange Scilab.
• D'autres références externes hors ATOMS, hors FileExchange et sans forge Scilab.

Si une de ces ressources correspond au pattern, un message invitant à utiliser l'option "w" -- voire précisant le libellé effectif du pattern -- est affiché dans la console.

Pour le mode web "w" :

• Pages d'aide Scilab officielles, pour les 5 langues standard supportées (en,fr,ja,pt,ru).
• Nom et pages d'aide de chaque module ATOMS installé en modes "all users" et "user".
• Noms des autres modules ATOMS indexés dans uman.
• Noms des modules hors ATOMS ayant une forge Scilab publique.
• Ressources distribuées sur le FileExchange, correctement conditionnées, et indexées dans uman.
• Autres ressources externes indexées dans uman.
• Moteur de recherche sur http://help.scilab.org

Les redirections Scilab->Scilab, équivalences externe->Scilab, et équivalences externe->externe définies par uman() peuvent être exploitées afin d'identifier l'item effectif correspondant au pattern donné, avant d'afficher sa page.

Ressources ciblées en mode "b" :

Lorsque l'item unique final est..

• une fonction Scilab : site web bugzilla.scilab.org
• une fonction d'un module ATOMS installé :
  • Si le module a une Forge Scilab : page des tickets de la forge
  • Sinon : page ATOMS.scilab.org du module, section des commentaires.
• un élément de FileExchange : page FileExchange.scilab.org correspondante, section des commentaires.
• un autre item externe indexé dans uman, avec site web référent : la page portail du site.
• un item non reconnu : moteur de recherche sur http://bugzilla.scilab.org. Cette page est également ouverte en cas d'items multiples séparés par "|".