<< uman uman

uman >> uman > uman

uman

Aide multilingue affichable en console, en ligne, en navigateur, avec fonctionnalités avancées

Séquences d'appel

uman
uman pattern
uman pattern options
uman -options pattern
uman -options pattern options

Paramètres

pattern
texte : nom d'une fonction, symbole ($, [, etc ), expression... dont la page d'aide est demandée. S'il est tout en minuscules, les minuscules / majuscules ne sont pas distinguées ; sinon, elles le sont. Si le pattern inclut des espaces, il doit figurer entre guillemets "..".
options

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.

l'aide doit être affichée. Par défaut : dans la console. Autres affichages possibles :

g :
navigateur de l'aide (GUI)
w :
page Web (aide en ligne). L'affichage en console est supprimé.

COMMENT l'affichage doit être réalisé :

c :
effacer le contenu de la console avant d'afficher la page (clear console)
L## :
Langue de la version à utiliser (si non celle de la session). ## = code en | fr | de | ja | pt | ru | zh de la langue.
x :
priorité aux modules et références eXternes.
r :
Rafraîchir / Recharger la liste de toutes les pages d'aide disponibles. Ré-extraire la page demandée.
j :
autoriser la Journalisation de la page d'aide affichée, dans les journaux de session déjà ouverts (s'il y en a).

INFORMATIONS à afficher. La page d'aide du pattern est affichée par défaut, avec les informations suivantes : Section du manuel concernée / Désignation réelle du pattern / Séquences d'appel / Paramètres d'entrée et de sortie / Section Voir aussi. Informations affichables à la demande :

s :
sommaire : affiche la liste des fonctions et items résidant dans la catégorie du pattern (à la place de sa page).
a :
all but bugs = Afficher toutes les sections de la page d'aide, sauf les bugs. Option équivalente à "deh"
d :
description : affiche les sections Description, Bibliographie, Références, Auteurs, ainsi que toutes les sections de type non identifié.
e :
exemples : affiche les sections identifiées comme étant des exemples.
h :
historique
b :
bugs : adresse des pages web où consulter les bugs du pattern documentés. Si "w" est également utilisée : ouvre la page web des bugs sélectionnés.

Description

You need human help ? Help yourself : Just call uman

uman.. est un manuel unifié d'aide à l'utilisateur. Cette fonction permet d'afficher les pages d'aide de Scilab, des modules ATOMS, des autres modules externes disposant d'une aide au format standard, ou à défaut l'aide rédigée en commentaires d'en-tête des functions. L'affichage peut être effectué en mode texte dans la console, voire simultanément dans le navigateur d'aide de Scilab ou en ligne dans votre navigateur internet. uman.. propose des fonctionnalités avancées telles que la commutation de langue, l'affichage de sommaires, des raccourcis pour les termes issus d'autres langages de programmation, l'affichage de la liste des bugs pertinents déjà documentés, etc.

Principales fonctionnalités
  • Les pages d'aide de Scilab, des modules ATOMS, des autres modules externes au format standard, et les commentaires d'en-tête des functions sont affichables. Il n'est pas nécessaire de charger en session les modules externes pour afficher leurs pages d'aide dans la console.

  • Informations adaptées à la demande : concentrez-vous sur les principales informations : la section du manuel dans laquelle se trouve ce que vous cherchez, les séquences d'appel, les paramètres d'entrée et de sortie, les références Voir aussi. Vous restez libre d'afficher une ou plusieurs sections supplémentaires à la demande et au détail : description, exemples, historique...

  • Afficher la version de l'aide dans la langue de votre choix, sans changer la langue de travail de votre session Scilab. Donner en option le code de la langue choisie en | de | fr | ja | pt | ru | zh, et la page correspondante s'affiche ! Accéder à la version en_US de référence devient trivial, même sans connexion internet.

  • Affichage formaté dans la console. Listes imbriquées à puces ou de rubriques, tableaux, extraits de programmes, remarques et alertes, styles de texte... sont correctement affichés en mode texte. Le style des séquences d'appel et des exemples est amélioré.

  • Près de 200 redirections automatiques disponibles pour les utilisateurs d'Octave : chercher atan2 mène à.. atan.

  • Vous préférez les pages d'aide en ligne ? Un seul caractère d'option permet de les cibler au lieu de la console, sans perdre le bénéfice des redirections, de la commutation de langue, etc. uman peut aussi utiliser le navigateur d'aide (ça s'impose ;)

  • Consulter la forge : accès direct à la liste des bugs affectant le pattern et déjà documentés, pour Scilab et pour de nombreux modules ATOMS.

Environnement requis
uman est utilisable à partir de Scilab 5.5.0, sous Windows, Linux et Mac OS.

Pages d'aide couvertes
Aide de Scilab
Ce sont les pages considérées en priorité.
Pages des modules ATOMS
Si des modules ATOMS sont installés dans votre distribution de Scilab, que ce soit pour tous les utilisateurs ou seulement à votre usage, toutes les pages d'aide afférentes sont indexées par 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\..). uman permet ainsi de consulter des pages d'aide avant d'estimer pertinent ou non de charger en session le module correspondant.
Pour afficher en priorité les pages eXternes de modules ATOMS ou d'autres contributions hors ATOMS, avant de scruter les pages de Scilab, utiliser l'option "x".
Autres modules externes
Tous les modules installés à la main dans SCI\contrib ou dans SCIHOME\contrib et proposant des pages d'aide au format standard sont également couverts. Comme pour les modules ATOMS,
l'accès à leurs pages d'aide ne requiert pas leur chargement en session Scilab, seulement qu'ils soient installés (dans SCI\contrib\.. ou SCIHOME\contrib\..).
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.
Redirections
Si uman ne trouve pas de page adéquate dans Scilab ni dans les modules externes ATOMS ou autres, uman recherche si un alias est prédéfini pour le pattern donné, alias vers lequel uman sera alors automatiquement redirigée. 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...).
Function diverses
Si finalement uman n'a trouvé aucune page d'aide ni aucun alias correspondant au pattern, ni pour Scilab ni pour aucun des modules externes installés, elle teste si le pattern correspond à une function définie dans la session. Le cas échéant, uman affiche son éventuel commentaire d'en-tête, lequel constitue le moyen le plus simple de documenter une function.

Options : description détaillée

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.

COMMENT la requête doit être traitée :

c :
efface le contenu de la console avant d'afficher la page (clear console)
L## :
Langue à utiliser : choisit la version de la page dans la langue ## sélectionnée, où ## est le code en | fr | de | ja | pt | ru | zh de la langue. L doit être la dernière option spécifiée (avant comme après le pattern). Par défaut, la langue de la session Scilab est utilisée. Si le code spécifié n'est pas listé, 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).
x :
priorité aux modules et références eXternes. Cet indicateur est utilisable à deux occasions :
  • Lorsqu'un même pattern est défini à la fois dans Scilab et dans un module externe (ATOMS ou non), par défaut uman affiche la version de Scilab. Pour afficher en priorité la version externe, utiliser "x" (à défaut de version externe, la version de Scilab sera affichée).
  • Lorsqu'un même pattern est défini à la fois dans Scilab et dans un langage de calcul scientifique eXterne avec 2 significations distinctes (faux-amis), par défaut il est entendu 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, null ...

r :

Rafraîchir / Recharger la liste de toutes les pages d'aide disponibles, et en particulier la page demandée.

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 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. Après avoir installé de nouveaux modules, l'indexation de leurs documentations par uman requiert d'utiliser "r" une fois (pour n'importe quelle page Scilab ou autre).

Plus rarement, "r" pourra aussi être utilisée pour ré-extraire la page demandée et remplacer la version stockée.

j :
autoriser la Journalisation de la page d'aide affichée, dans les journaux de session déjà ouverts (s'il y en a).

Par défaut, les éventuels journaux ouverts sont bloqués afin de ne pas recevoir le contenu de la page affichée en console, puis débloqués après l'affichage. Si aucun journal n'est ouvert, "j" n'en ouvre aucun.

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 : La section du manuel concernée | La désignation réelle du pattern | 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 :

s :
sommaire : affiche la liste de toutes les fonctions ou items résidant dans la catégorie du pattern, à la place de sa page.
Cette option fonctionne aussi avec l'option "g" (affichage simultané dans le navigateur d'aide).
Cette option annule l'option "w" (page web), et ignore les options "a", "b", "d", "e", et "h"
a :
all but bugs = Afficher toutes les sections de la page d'aide, sauf les bugs. Option équivalente à "deh"
d :
description : affiche également les sections Description de la page d'aide, incluant les sections Bibliographie, Références, Auteurs, si elles existent. Toute autre section de type non identifié est également affichée.
Lorsque le pattern inclut "properties", les sections Description de la page sont obligatoirement affichées.
e :
exemples : affiche les sections identifiées comme étant des exemples.

Les exemples inclus dans les autres types de sections sont affichés avec celles-ci, sans que l'option "e" soit requise

h :
historique : affiche l'historique du pattern (s'il existe)
b :
bugs : affiche l'adresse des pages web où consulter les bugs déjà documentés affectant le pattern, et à utiliser pour déclarer un nouveau bug.

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 (sous réserve de la disponibilité d'une connexion internet active).

Si le pattern concerne un module ATOMS installé :

  • Si le module est développé sur la forge de Scilab (http://forge.scilab.org), la page "tickets" de sa forge est ouverte dans votre navigateur web et liste les anomalies rapportées liées au pattern.
  • Sinon, si le module a une page web déclarée, celle-ci est ouverte dans le navigateur web.
  • Dans les autres cas, la page ATOMS du module est ouverte. Sa section Commentaires est ciblée. C'est le lieu le plus approprié pour consulter les retours d'expérience ou faire part des anomalies rencontrées avec les fonctionnalités du module.

l'aide doit être affichée.

Par défaut, elle est affichée dans la console. D'autres affichages sont possibles :

g :
navigateur de l'aide (GUI) : outre l'affichage en console ou en ligne, la navigateur d'aide de Scilab est appelé pour le même pattern. 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. Un message d'alerte est alors affiché 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.
w :

page web (aide en ligne) : affiche dans votre navigateur web la page d'aide en ligne correspondant au pattern donné (connexion internet active requise). La langue (celle par défaut, ou celle spécifiée avec l'option "L") est prise en compte. L'affichage dans la console est alors supprimé.

Si aucune page exacte relative au pattern n'est trouvée, le moteur de recherche de http://help.scilab.org utilise le pattern et liste les pages liées les plus pertinentes.

Lorsque l'option "w" est utilisée avec l'option "b" (bugs), uman ouvre -- si possible -- la page listant les bugs déclarés concernant le pattern.

Lorsque le pattern concerne un module externe (du système ATOMS ou autre), aucune page d'aide en ligne n'est (actuellement) définie (voir http://bugzilla.scilab.org/6723). L'option "w" est alors ignorée, et, à la place, l'aide est affichée dans la console.

Accès directs particuliers

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), datatype (page des types de variables), files (sommaire des fonctions de gestion des fichiers), graphics (sommaire des fonctions graphiques), hdf5 (sommaire des fonctions HDF5), linespec (page des styles de courbes graphiques), metanet (sommaire des fonctions de ce module externe), shortcuts (page des raccourcis clavier prédéfinis), sparses (sommaire des principales fonctions pour les matrices creuses), statistics (sommaire), 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).

Essayer : -->uman sparses

Aspects techniques
  • 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).

Limitations connues
  • Une fois par semaine, la 1ère utilisation de uman travaille 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.
  • Pour changer la langue utilisée dans le navigateur d'aide via les options "gL##", il est nécessaire de préalablement fermer le navigateur déjà ouvert.
  • L'appel du navigateur d'aide avec l'option "g" n'amène pas celui-ci au premier plan (voir http://bugzilla.scilab.org/13756)
  • Les expressions mathématiques LaTeXées affichées sous forme d'image dans l'aide ne peuvent pas être affichées en texte dans la console. Leur existence est néanmoins indiquée dans le texte.
  • Dans les tableaux à plusieurs colonnes, les lignes longues ne sont pas césurées. Chacune est affichée "au kilomètre" sur une ligne unique
  • Dans les pages en Chinois, les lignes longues sans espaces ne sont pas césurées.
  • Sur environ 3000 pages d'aide, certaines pages conditionnées de manière particulière peuvent mettre uman en défaut. Nous tenterons progressivement de résorber ces anomalies ;)
  • Dans sa version actuelle, uman n'est pas omnilingue. Si vous souhaitez ajouter une langue (écrite de gauche à droite), SVP contacter l'auteur
  • Cas particuliers : pour uman "=" .., uman "==", uman "(...", uman "//"..., les guillemets sont requis.
  • uman ne peut pas être utilisée en mode console sous MS Windows (problème d'affichage en UTF8 : voir http://bugzilla.scilab.org/10748).

Exemples

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   

// 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
 
// "g" affiche simultanément la page dans le navigateur d'aide (GUI) (incrustable sur l'éditeur) :
uman strstr deg

// "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

// avec une connexion internet active :
uman ode wlpt    // page d'aide de ode() en Portuguais sur http://help.scilab.org
uman ode wb      // liste des bugs rapportés autour de ode(), triée correctement
                 //  (bugs non résolus en premier)
uman colors w    // redirection vers color_list, puis affichage de la page internet correspondante

// Traitement des modules ATOMS installés : 
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.
uman quiver wb        // Plotlib est sur la Forge de Scilab => ouvre la page internet des bugs 
                      //   correspondants
if ~yn, atomsRemove("plotlib"), end    // Suppression de plotlib, s'il n'était pas installé

Voir aussi

Historique

VersionDescription
1.0 / 2015-03

Première publication


Report an issue
<< uman uman