Aide multilingue affichable en console, en ligne, en navigateur, avec fonctionnalités avancées
uman uman pattern uman pattern options uman -options pattern uman -options pattern options
pattern
inclut des espaces, virgules, point-virgules, ":", "=", parenthèses, ou accolades, il doit figurer entre guillemets "..".Mot unique spécifiant une ou plusieurs options. Chaque caractère du mot (ordre et casse indifférents) active une option spécifique. Les options disponibles sont listées ci-après. Elles sont décrites en détails dans la section Description.
OÙ l'aide doit être affichée. Par défaut : dans la console. Autres affichages possibles :
COMMENT l'affichage doit être réalisé :
en | fr | de | ja | pt | ru | zh
de la langue (code absent == en
).INFORMATIONS à afficher.
La page d'aide du pattern
est affichée par défaut, avec les informations suivantes : Chemin dans l'arborescence de l'aide / Désignation réelle du pattern
(après éventuelle redirection) / Séquences d'appel / Paramètres d'entrée et de sortie / Section Voir aussi. Informations affichables à la demande :
pattern
(au lieu de sa page). "s"
annule l'option "w"
."deh"
pattern
.
pattern
documentés.
Si "w"
est également utilisée : ouvre la page web
des bugs afférents.You need human help ? Help yourself, just call uman
uman..
est une commande d'affichage unifié des manuels intégrés d'aide à l'utilisateur. Les pages d'aide de Scilab, des modules ATOMS, des autres modules externes disposant d'une aide au format standard, ou l'aide rédigée en commentaires d'en-tête des functions sont couvertes. Certaines références disponibles dans le Scilab FileExchange sont également accessibles. L'affichage peut être effectué en mode texte dans la console, voire simultanément dans le navigateur d'aide de Scilab ou sur http://help.scilab.org dans votre navigateur internet.
uman..
affiche la version des pages dans n'importe quelle langue disponible, la liste des fonctions conjointes (sommaire afférent), la liste des bugs afférents déjà documentés, etc. Pour plus de 200 termes notamment issus d'autres langages de programmation, l'utilisateur est redirigé automatiquement vers la référence Scilab la plus pertinente.
Une seule fonction pour consulter les pages d'aide de Scilab, des modules ATOMS installés (chargés ou non), des autres modules externes au format standard, ou des commentaires d'en-tête des functions de l'utilisateur. Environ 50 références externes disponibles sur le FileExchange Scilab sont également consultables.
Une même fonction pour cibler et afficher l'aide dans la console, dans le navigateur d'aide, ainsi que sur internet (help, bugzilla, atoms, forge, voire les sites externes de référence).
Indiquez en option le code de la langue choisie en | de | fr | ja | pt | ru | zh
, et l'aide correspondante s'affiche dans la console ou en ligne. Aucun besoin de changer la langue de travail de la session Scilab. Consulter la version de référence en anglais devient trivial, sans abandonner votre session en français.
Affichez l'aide en bref : chemin dans l'aide, séquences d'appel, paramètres d'entrée et de sortie, références Voir aussi. En options, choisissez au détail les informations supplémentaires à afficher : description, exemples, historique, sommaire parent..., ou tout afficher avec l'option "a".
Vous avez vos habitudes avec Octave ? Près de 200 redirections automatiques vous permettent d'afficher la référence Scilab équivalente ou la plus proche de votre indication. Différents raccourcis utiles à tous sont également disponibles.
Vous suspectez un bug ? L'option "wb" liste en ligne les bugs déjà documentés spécifiques à votre saisie, pour les fonctions de Scilab et de nombreux modules ATOMS.
Enfin, le format d'affichage texte en console est proche de l'original : le format des listes d'items imbriquées, des tableaux, des extraits de code, des indicateurs NOTES et ATTENTION, et le style du texte original, sont si possible respectés, dans la largeur de la console. Le style des séquences d'appel et des exemples est par ailleurs amélioré.
uman
est utilisable sous Windows, Linux et Mac OS à partir de Scilab 5.5 et avec Scilab 6.
uman
.
![]() | Les modules ATOMS n'ont pas besoin d'être chargés en session, juste d'être installés (dans SCI\.atoms et SCI\contrib ou SCIHOME\atoms\..). Des pages inaccessibles au navigateur d'aide peuvent ainsi être consultées, avant si nécessaire de charger en session le module correspondant. |
![]() | En cas d'homonymie entre une fonction externe et une fonction Scilab, l'option "x" permet d'afficher en priorité les pages eXternes des modules ATOMS ou d'autres contributions hors ATOMS, avant de scruter les pages de Scilab. |
SCI\contrib
ou dans SCIHOME\contrib
et proposant des pages d'aide au format standard sont également couverts.
![]() | Les pages des modules externes divers sont recherchées seulement lorsque le pattern ne correspond à aucune page de Scilab, à moins que l'option "x" soit spécifiée. |
uman
ne trouve aucune page d'aide correspondant au pattern
, ni pour Scilab ni pour aucun des modules externes installés, l'existence d'une function nommée pattern
définie dans la session est testée. Le cas échéant, uman
affiche le commentaire d'en-tête de la function (s'il existe). Un bloc ininterrompu de lignes mises en commentaire et figurant immédiatement après la ligne "function ..." constitue en effet le moyen le plus simple de documenter une function. Utilisez-le, et affichons-le avec uman
."w"
est utilisée (internet : contenus en ligne).uman
n'a toujours rien trouvé correspondant à votre saisie, uman
cherche si une redirection (référence associée, alias) est prédéfinie pour le pattern
indiqué. Le cas échéant ,uman
est automatiquement relancée pour la nouvelle référence. De telles redirections sont définies pour des termes utilisés dans d'autres langages de programmation scientifique, qui n'existent pas dans Scilab, et qui n'ont pas de signification alternative dans Scilab (faux amis). D'autres termes particuliers sont également admis et traités, telles que les erreurs typographiques fréquentes (lenght
au lieu de length
), ou des raccourcis particulièrement utilisés.
Mot spécifiant une ou plusieurs options
. Chaque caractère active une option particulière. L'ordre et la casse des caractères sont indifférents. Les options sont a priori indiquées après le pattern
. Dans le cas contraire, elles doivent être préfixées par "-"
.
Il est aussi possible d'indiquer des options avant ET après le pattern
. Dans ce cas, elles sont cumulées. Les options
fréquentes peuvent être indiquées avant le pattern
, alors qu'il sera plus pratique d'indiquer en fin de ligne de commande celles à modifier fréquemment.
OÙ l'aide doit être affichée.
Par défaut, le contenu est affiché dans la console. Sa largeur s'adapte à celle de la console mais est limitée à 100 caractères. D'autres affichages sont possibles :
uman
appelle simultanément le navigateur d'aide de Scilab. Si le navigateur n'était pas déjà ouvert, il est ouvert dans la langue imposée par uman
(voir l'option "L##"
).
![]() | Si le pattern relève d'un module externe installé mais non chargé en session, sa page sera inconnue du navigateur d'aide. Une alerte en informe alors l'utilisateur en pied de page dans la console. |
![]() | Lorsque l'option "g" est utilisée avec l'option "x" (module ou référence eXterne prioritaire), la page affichée est celle de la version Scilab du pattern (s'il y en a une), non la version externe. En effet, il n'est pas possible de forcer le navigateur d'aide à afficher prioritairement celle-ci. |
page web (aide en ligne) : lorsque cette option est utilisée sans l'option "b"
(bugs), uman
affiche l'aide en ligne dans votre navigateur web, pour le pattern
considéré (connexion internet active requise). Alors,
pattern
est une référence Scilab :
uman
(par défaut ou avec l'option "l"
) est prise en compte pour cibler la version linguistique correspondante.pattern
est référencé (module ATOMS, autre module externe, référence sur FileExchange, autres références diverses),
pattern
, celui-là est ouvert dans votre navigateur internet (les pages d'aide des modules ATOMS ne sont actuellement pas hébergeables sur http://atoms.scilab.org (voir http://bugzilla.scilab.org/6723)).pattern
fait référence à de l'aide intégrée (ATOMS, autres modules externes avec une aide standard, fonction sur FileExchange intégrant des commentaires d'en-tête, etc), la page ou le contenu est affiché en console.pattern
ne correspond à aucune référence indexée, le moteur de recherche de http://help.scilab.org est appelé pour lui.Lorsque les deux options "wb"
sont utilisées, la page internet de suivi des bugs est ciblée (si elle existe). La page ciblée dépend du pattern
: lorsqu'il
pattern
est sélectionnée sur http://bugzilla.scilab.org et affichée.pattern
est sélectionnée et affichée sur la page des tickets de la forge : http://forge.scilab.org/index.php/p/<module_name>/issues/.Par défaut, les journaux ouverts sont bloqués afin de ne pas recevoir l'aide affichée en console, puis débloqués après l'affichage. Si aucun journal n'est ouvert, "j"
n'en ouvre aucun.
COMMENT la requête doit être traitée :
en | fr | de | ja | pt | ru | zh
de la langue. Par défaut, la langue de la session Scilab est utilisée. Si le code spécifié ne figure pas parmi ceux listés ci-avant, l'anglais en_US
est utilisé. Pour afficher la page de référence en anglais, indiquer Len
(ou simplement L
en dernière option).pattern
est défini à la fois dans Scilab et dans un module externe (ATOMS ou non) ou sur FileExchange, par défaut uman
affiche la version de Scilab. Pour afficher en priorité la version externe, utiliser "x"
. Si aucune version externe n'est connue, la version de Scilab sera affichée.pattern
est défini à la fois dans Scilab et dans un autre langage de programmation scientifique eXterne avec 2 significations distinctes (faux-amis), par défaut il est compris comme relevant de Scilab, et la page correspondante est recherchée. Si l'acception externe doit être considérée, utiliser "x"
. uman
recherchera alors le terme Scilab équivalent et affichera la page Scilab correspondante.
Exemples de faux-amis (avec Octave): type
, end
, load
, home
, range
, null
...
Rafraîchir / Recharger la liste des pages d'aide disponibles, et supprimer toutes les pages déjà appelées et extraites mises en cache, afin de forcer leur ré-extraction lors des prochaines requêtes.
Par défaut, la liste des pages est initialement dressée, stockée, puis actualisée automatiquement une fois par semaine (le temps de réponse de uman
est alors un peu plus long). Par ailleurs, chaque nouvelle page demandée est extraite de l'archive compressée des pages et est stockée sur le disque. Tout appel ultérieur de la même page utilise la version déjà extraite et stockée.
Cette option doit être utilisée après que des modules aient été supprimés ou installés. Lorsqu'un développeur travaille à l'actualisation des pages d'aide d'un module, il pourra également utiliser cette option afin de supprimer l'ancienne version de ses pages et forcer leur ré-extraction depuis la version actualisée de l'archive.
INFORMATIONS à afficher.
La page d'aide du pattern
est a priori affichée, à moins que l'option "s"
soit utilisée : dans ce cas, la liste des items résidant dans la même section de l'aide que le pattern
est affichée.
Les éléments d'une page systématiquement affichés sont : Le chemin dans l'aide Scilab | La désignation réelle du pattern
(en cas de redirection) | Les Séquences d'appel | Les paramètres d'entrée et de sortie | la section Voir aussi de la page. Des informations supplémentaires peuvent être affichées à la demande :
pattern
, à la place de sa page.
![]() | Cette option fonctionne aussi avec l'option "g" (affichage simultané dans le navigateur d'aide). |
![]() | Cette option annule ou ignore l'option "w" (page web), et ignore les options "a", "b", "d", "e", et "h" |
"deh"
![]() | Lorsque le pattern inclut "properties" , les sections Description de la page sont obligatoirement affichées. |
Les exemples inclus dans les autres types de sections sont affichés avec celles-ci, sans que l'option "e"
soit requise
pattern
(s'il existe)pattern
, et à utiliser pour signaler de nouveaux bugs.
Lorsque les options "b"
et "w"
sont utilisées ensemble, la page web des bugs déjà documentés est ouverte dans votre navigateur web : voir la section WHERE/"wb"
détaillée plus haut.
Les termes suivants (en minuscules) n'existent pas dans Scilab mais peuvent être utilisés comme pattern
pour afficher de manière pratique les contenus correspondants :
colors(page listant les couleurs prédéfinies), datatypes (page des types de variables), files (sommaire des fonctions de gestion des fichiers), graphics (sommaire des fonctions graphiques), hdf5 (sommaire des fonctions HDF5), metanet (sommaire des fonctions de ce module externe), shortcuts (page des raccourcis clavier prédéfinis), signal (sommaire des fonctions de traitement du signal), sparses (sommaire des principales fonctions pour les matrices creuses), statistics (sommaire), trigo (trigonométrie), variables (sommaire listant les variables Scilab prédéfinies et les fonctions traitant des variables), windows (sommaire des fonctions Scilab spécifiques à MS Windows), xml (sommaire des fonctions de traitement des contenus XML).
uman
extrait les pages d'aide de Scilab dans le dossier SCIHOME\uman
, et les pages des modules externes ATOMS ou autres dans le dossier SCIHOME\uman\atoms
.
Modules externes divers (contrib)
:
Chaque module doit comporter un dossier ~\help\*
contenant une ou plusieurs archives d'aide standard compressées scilab_##_##_help.jar
, où ##_##
est le code de la langue de la version de l'aide considérée (un fichier .jar par langue). A minima, le fichier de référence scilab_en_US_help.jar
doit être fourni. Ces fichiers .jar sont générés à partir des fichiers d'aide XML, avec la fonction xmltojar(..)
.
Le module doit également comporter un dossier et un fichier ~\etc\<module_nom>.start
. Le fichier peut être vide. Seul son nom <module_nom> est utilisé : il indique le nom du module.
Le dossier contenant un module externe hors ATOMS peut résider n'importe où dans l'arborescence partant de SCI\contrib
ou de SCIHOME\contrib
(non nécessairement directement dans ces deux dossiers).
uman
dure quelques secondes supplémentaires avant de répondre. Le temps de détecter et de référencer toutes les pages d'aide disponibles sur votre ordinateur."gL##"
, il est nécessaire de préalablement fermer le navigateur déjà ouvert (voir http://bugzilla.scilab.org/12889)"g"
n'amène pas celui-ci au premier plan (voir http://bugzilla.scilab.org/13756)uman
n'est pas omnilingue. Si vous souhaitez ajouter une langue (écrite de gauche à droite), SVP contacter l'auteuruman "="
, uman "=="
, uman "(..."
, uman "//"
, uman ";"
, uman ","
... les guillemets sont requis.uman
ne peut pas être utilisée en mode console seule sous MS Windows (problème d'affichage en UTF8 : voir http://bugzilla.scilab.org/10748).uman // affiche cette page d'aide (principales sections) uman .*. cd // Les opérateurs et les symboles sont admis. Ici : redirection vers kron() uman $ cde // un autre symbole. Exemples demandés uman linespec a // tout en minuscules, la requête est insensible à la casse: "LineSpec" est trouvé uman type a // pourrait afficher les pages pour "type" ou "Type". "type" est préféré uman Type a // affiche la page de "Type" uman typE a // la page "typE" n'existe pas => /"typE" is undocumented/ est affiché uman linspace Lrua // version russe de la page linspace uman linspace aL // version de référence en anglais uman uint16 ce // Les pages cumulant la présentation de plusieurs fonctions sont traitées // Les listes à puces ou numérotées imbriquées sont traitées uman daskr cd // Diminuons la largeur de la console, puis : uman daskr cd // Les lignes sont ajustées en longueur (excepté pour les exemples) // Les tableaux avec ou sans bordures sont traités : uman plotsparse cd // 2 tableaux sans bordures, dans la section "Paramètres" uman overloading cd // tableaux avec bordures // Redirections internes vers des pages ou des sommaires : uman colors // redirection vers la page color_list, avec sa section Description uman sparses // Affiche le sommaire des principales fonctions traitant des matrices creuses // D'autres raccourcis sont définis. Essayer avec "statistics" // Equivalents automatiques d'instructions externes en Scilab : uman polyval c // polyval() n'existe pas en Scilab mais est l'équivalent en Octave // de la function Scilab horner() => la page de horner est affichée // Equivalents Scilab de faux-amis externes uman end cde // l'acception à la Scilab est retenue par défaut // => la page = controls (if.. end / for.. end / while..end) est affichée uman end cdex // "x" retient en priorité l'acception eXterne de "end" : en langage Octave, // "end" désigne le n° du dernier élément => la page scilab "$" est affichée // "s" affiche le Sommaire des fonctions dans lequel celle demandée réside uman strstr des uman who sg // Sommaire avec des sous-sections, affiché en console ET dans le navigateur // Option "g" => affichage simultané dans le navigateur d'aide (GUI) (incrustable sur l'éditeur) : uman strstr deg uman cholesky g // = "help choleski". Pas de page dédiée, mais liste les pages contenant "choleski" uman who gs // Un sommaire parent peut aussi être ciblé et affiché dans le navigateur d'aide // Pour changer de version linguistique, le navigateur doit être préalablement fermé. Puis : uman who gslru // Dans tous les cas, le sommaire sera affiché ici en Russe dans la console. // Avec une function spécialement définie ou chargée en session : function r=test(p, q) // // CALLING SEQUENCES // r = test(p) // r = test(p, q) // // PARAMETERS // p: 1st param (describe it here) // q: optional 2nd param (describe it here) // r: result (describe it here) // // DESCRIPTION // This function and its comments must be executed. It is designed to // illustrate uman's acting as head_comments(). // // Go on with other help sections. The block of comments must be continuous. // r = p*q.^2 endfunction uman test // Affiche le bloc de commentaires rédigés en en-tête de la définition de test() // AVEC UN MODULE ATOMS INSTALLé // ============================= uman atoms d // Liste des fonctions relatives à ATOMS yn = atomsIsInstalled("plotlib"); atomsInstall plotlib // Installons le module Plotlib atomsIsLoaded plotlib // => %F : sans redémarrer Scilab, le module n'est pas chargé, juste installé. uman plot cde // la version Scilab de la page de plot() est affichée par défaut. uman plot cdex // "x" permet d'afficher la version eXterne de plot(), celle de Plotlib uman plot cdexg // "g" => le navigateur ne peut pas afficher la page de Plotlib. // Il faudrait que Plotlib soit CHARGé en session. // AVEC UNE CONNEXION INTERNET ACTIVE // ================================== // Pages d'aide en ligne, sur http://help.scilab.org : option "w" // --------------------- uman ode w // Dans la langue de la session (si elle est répertoriée, sinon en anglais) uman ode wlpt // En portugais uman ode wl // Page de référence en anglais uman sort wlru // l'option "w" bénéficie aussi de la redirection "sort => gsort" active. uman cholesky w // Pour un item sans page dédiée, le moteur des pages d'aide en ligne est appelé. uman contour3d w // Pour une fonction uniquement disponible et répertoriée sur FileExchange, // la page correspondante est ouverte. uman quiver xw // quiver() est une fonction du module ATOMS Plotlib. Les modules ATOMS ne // proposent pas (encore) de pages d'aide en ligne => la page disponible est // affichée dans la console, à la place (+ alerte spécifique en pied de page). // Liste des bugs documentés (en ligne) : options "wb" // ------------------------------------ uman ode wb // liste sur bugzilla les bugs rapportés autour de ode(), triés correctement // (bugs non résolus en premier) uman kutta wb // Pour un item queconque sans page d'aide dédiée, une recherche sur Bugzilla // est également effectuée uman quiver xwb // Le module ATOMS contenant quiver() dispose également d'une forge Scilab sur // laquelle un service de suivi de bugs est disponible. La liste des bugs déjà // documentés est filtrée, et seuls les bugs relatifs à "quiver" sont listés en ligne. uman cshift wb // Pour une fonction répertoriée sur FileExchange, les bugs peuvent être indiqués // en commentaires par les utilisateurs, sur la page FileExchange dédiée. if ~yn, atomsRemove("plotlib"), end // Suppression de plotlib, s'il n'était pas installé | ![]() | ![]() |
Version | Description |
1.0 / 2015-03 | Première publication |
1.1 / 2015-04-02 | Version technique intermédiaire republiée par l'administrateur ATOMS (suite à des problèmes du serveur ATOMS) |
1.2 / 2015-06-06 | Mise à niveau. ~40 améliorations et bugs corrigés. Prêt pour Scilab 6. Détails : voir le fichier changelog.txt. |