uman

Sommaire

• Arguments
• Options
• Description
  • Systèmes d'exploitation admis
  • Principales fonctionnalités
  • Raccourcis
  • Ressources et références utilisées
  • Aspects techniques
  • Limitations connues
• Exemples
• Voir aussi
• Historique

Arguments

pattern

Texte unique: nom d'une fonction, symbole ($, [, etc ), expression, numéro d'un bug documenté sur bugzilla, terme quelconque... à propos de quoi des informations sont demandées. La requête sera traitée de manière indifférente à la casse typographique si le pattern est libellé tout en minuscules. Sinon la différence entre minuscules et majuscules sera prise en compte (hors modes "b" et "@").

Lorsqu'il inclut des espaces, virgules ",", point-virgules ";", deux-points ":", "=", slashs "//", parenthèses, ou des accolades, le pattern doit obligatoirement figurer entre guillemets ou entre apostrophes.

options

Les options décrites ici sont utilisables à l'appel de uman(). Un autre ensemble d'options de configuration modifiant le comportement de uman() est disponible en préférences.

options est un mot sans espace indiquant une ou plusieurs options. Chaque caractère (ordre et min/majuscules indifférents) active une fonctionnalité spécifique. Les options disponibles sont décrites ci-après.

Par défaut, les options sont indiquées après le pattern. Sinon, le mot des options doit être préfixé par "-".

Les options

• définies comme celles par défaut via la variable de configuration umanDefaultCallOptions,
• indiquées avant le pattern et préfixées avec -, en appelant uman,
• indiquées après le pattern, en appelant uman,

se cumulent selon les priorités décroissantes suivantes :

après le pattern > avant le pattern > préférences configurées > valeurs par défaut implicites.

OÙ le contenu doit être affiché

Par défaut, la sortie texte est affichée dans la console Scilab. C'est le mode normal d'utilisation de uman. D'autres types d'affichage sont cependant possibles.

Priorités entre les différents modes d'utilisation de uman : b > w, g > (console) > @

g :	Navigateur d'aide = interface Graphique. En plus de l'affichage de la page d'aide dans la console, uman appelle le navigateur d'aide de Scilab pour la même requête pattern. Si le navigateur help n'est pas déjà ouvert, il est appelé dans la langue d'usage de la session, ou celle fixée par l'option complémentaire "L##". Si le pattern relève d'un module externe installé mais non chargé en session, les pages d'aide afférentes ne peuvent pas être affichées dans le navigateur. La page requise est alors affichée dans la console, suivi d'une alerte en pied de page. Lorsque les options "g" et "x" (modules eXternes prioritaires) sont utilisées ensemble, la page affichée dans le navigateur est toujours prioritairement celle de la version Scilab du pattern (s'il y en a une), non la version externe. Pour plusieurs versions homonymes des pages d'aide, il est en effet impossible de forcer l'affichage de l'une d'entre elles plutôt qu'une autre.
w :	Page Web : affiche dans votre navigateur internet la page d'aide internet officielle. Voir uman .. w.
b :	Web Bugs : affiche dans votre navigateur internet une page web listant les bugs documentés concernant le pattern donné. Voir uman .. b. Cet usage de uman() dispose de l'option Liste uniquement les bugs non résolus disponible dans les préférences.
@ :	Listes de messagerie @listes.scilab.org (archives internet) : le pattern permet de réaliser des recherches par sujets, auteurs, et âge maximal des messages archivés. Aucune des autres options n'est utilisable en mode "@". Voir uman .. @.
j :	Journaliser : autorise l'enregistrement dans tous les journaux actuellement ouverts (s'il y en a) tous les affichages en console produits par uman. Par défaut, tous les journaux ouverts sont suspendus puis réactivés par uman avant et après tout affichage en console, afin de ne pas être alimentés. Si aucun journal n'est préalablement actif, cette option n'en ouvre pas et aucune journalisation n'est déclenchée.

QUEL CONTENU doit être affiché

Par défaut, la page d'aide correspondant à la requête est affichée, et l'affichage est restreint aux sections minimales suivantes pour l'item :

• Chemin de l'item dans l'arborescence de l'aide
• Désignation réelle de la page (après possible redirection), et description courte
• Liste des syntaxes admises
• Références connexes Voir aussi.

Les informations d'autres sections peuvent être affichées en options à la demande (voir ci-dessous).

Les options de contenus sont classées selon les priorités suivantes : u > s > a > p,d,e,h

u :	usages : affiche uniquement la liste des syntaxes admises, précédée du chemin dans l'aide. Cette option a la priorité la plus forte pour les contenus : elles ignore toutes les autres options de contenus, mais est ignorée en mode b, w ou g.
s :	affiche le sommaire de la section de l'aide documentant le pattern choisi, au lieu de sa page d'aide. Cette option fonctionne aussi avec l'option "g", pour afficher un sommaire dans le navigateur d'aide. En revanche, elle est ignorée en mode web "w".
a :	All : affiche toutes les sections de la page d'aide. Equivaut à utiliser "pdeh".
p :	Paramètres : affiche la section Arguments. Lorsqu'une page n'a pas de section Arguments | Parameters, sa section Description est toujours affichée à la place.
d :	Description : affiche les sections Description, Bibliographie, Références, Auteurs, ainsi que toutes les autres sections de type non identifié.
e :	Exemples : affiche les sections d'exemples Les exemples inclus dans des sections d'un autre type sont affichés au sein et avec celles-ci. L'option "e" n'a aucun effet sur leur affichage.
h :	Historique du pattern.

COMMENT la requête doit être traitée

c :	Clear : effacer la console avant d'y afficher la page.
L## :	Langue d'usage : visualiser la version de la page dans la langue ##, où ## est un des codes linguistiques en | fr | ja | pt | ru. D'autres codes tels que de | zh | fa sont admis, sous réserve que de la documentation dans ces langues soit disponible (la documentation de certains modules externes est traduite dans ces langues). Sans l'option L##, la langue d'usage de la session est utilisée. Si L est indiquée en dernière option et sans code ##, ou si le code donné n'est pas reconnu, la version de référence en anglais est considérée. Depuis uman 2.0, les corpus partiels / sous-ensembles de pages d'aide traduits hors des langues en,fr,ja,pt,ru sont admis et peuvent être exploités. Il suffit de déposer le fichier .jar correspondant sur l'ordinateur, comme pour un module standard. uman y cherchera et extraira les pages dés que l'item désigné dans le pattern est disponible dans la langue. Sinon, comme d'habitude, uman retourne la version par défaut, en anglais.
x :	Priorité aux modules et références eXternes. Cette option est utilisable de deux manières : Lorsque deux fonctions distinctes homonymes sont proposées d'une part dans Scilab et d'autre part dans un module ou une autre ressource externe (ATOMS, autres modules, fichier distribué dans FileExchange), par défaut uman cible et affiche la version Scilab. L'option "x" permet au contraire de cibler prioritairement les versions externes. L'option "x" permet également de traiter les "faux-amis" : lorsque le pattern désigne sous le même nom deux fonctionnalités distinctes d'une part dans Scilab et d'autre part dans un autre langage de programmation scientifique (Octave, etc), par défaut l'acception propre à Scilab est considérée. Pour cibler l'acception externe, l'option "x" sera utilisée. uman redirigera alors automatiquement la requête initiale vers la page Scilab de la fonctionnalité equivalente. Exemples de termes faux-amis : end, load, home, null, range, type, etc. Ainsi, uman null affichera la page Scilab de la fonction null(), tandis que uman null x affichera la page Scilab de la fonction kernel(), équivalente à la fonction null() du langage Octave.
r :	Rafraichit / Recharge le registre de tous les modules externes installés, et supprime toutes les pages précédemment extraites des modules externes et mises en cache. Pour les modules gérés avec le système ATOMS : uman() met automatiquement à jour son registre de ressources après chaque installation ou désinstallation d'un module. L'usage de l'option "r" ne fait rien de plus et est donc inutile. L'option "r" sera utilisée une fois pour tout utilisateur, après toute modification de la liste des Chemins des modules externes hors de ~/contrib disponible en Préférences de uman, ou pour les rédacteurs de pages d'aide : après compilation d'une nouvelle version de pages à afficher avec uman.

Description

uman.. est une fonction avancée compacte et paramétrable permettant d'accéder depuis la console et de manière unifiée à diverses ressources documentaires, en premier lieu aux pages du manuel d'utilisation de Scilab. Les pages de Scilab (fonctions actuelles ou anciennes fonctions supprimées), des modules ATOMS, d'autres modules externes, des ressources documentées sur le FileExchange Scilab ou externes, la documentation des fonctions locales en commentaires d'en-tête, les archives des listes de messagerie officielles, les registres des rapports de bugs.. sont notamment couverts. L'affichage peut à la demande être réalisé directement dans la console, ou dans votre navigateur internet, ou dans le navigateur d'aide de Scilab, dans la langue choisie.

Pour plus de 220 termes externes (issus d'autres langages scientifiques), uman redirige automatiquement la requête vers la référence Scilab équivalente ou la plus appropriée.

Exemples

// SVP sélectionner chaque ligne une à une, l'exécuter (CTRL+E), et voir le résultat en console

 uman ndgrid u    // Uniquement les syntaxes admises pour ndgrid()
 uman eye p       // Section "Paramètres" (Arguments) affichée
 uman eye d       // Section "Description" affichée
 uman eye e       // Section "Exemples" affichée
 uman linspace h  // Section "Historique" affichée
 uman eye ph      // Sections "Paramètres" et "Historique" affichées
 uman eye a       // Page entière affichée
 uman ones d      // "d" affiche aussi toute autre section (ici "Remarques").

 uman .* cpd      // Les opérateurs et les symboles sont admis.
                  // "c" = console effacée avant l'affichage.
 uman $ cde       // Autre symbole. Description et Exemples inclus, après clc()

 uman linespec a  // tout en minuscules => casse typographique indifférente => "LineSpec" trouvé
 uman type a      // Les 2 pages "type" ou "Type" existent. Page "type" choisie
 uman Type a      // Affiche la page "Type" , <> "type"
 uman typE a      // L'item "typE" n'existe pas => "Aucune page trouvée pour 'typE'"

 uman linspace Lruph // version russe de la page entière 'linspace' (Paramètres et Historique)
 uman linspace hpL   // version de référence en anglais (toujours Paramètres et Historique)
                     // ("L" au lieu de "l" (~ "1" = one), mais "l" est OK).

 uman uint16  ce    // Cette page présente plusieurs fonctions (int8, int16, etc)
                    // Elle est correctement ciblée et traitée.

 // Les listes imbriquées de termes, à puces, ou numérotées sont bien affichées :
 uman brackets cd
 //     Réduisons la largeur de la console. Puis relançons
 uman brackets cd   // Les lignes sont bien césurées (mais jamais les lignes de code)

 // Les tableaux simples avec ou sans bordures sont correctement affichés :
 uman plotsparse c      // 2 tableaux sans bordures
 uman atomsSetConfig ac // tableaux avec bordures. Les lignes longues sont césurées

 // Redirections internes vers des pages ou le sommaire du chapitre :
 uman keys        // raccourcis clavier => redirection vers la page "console"
 uman files       // Sommaire des principales fonctions de gestion des fichiers
                  // D'autres raccourcis sont proposés. Essayer "stats"

 // Equivalences Scilab d'items externes non reconnus en Scilab
 uman polyval d   // polyval() n'existe pas en Scilab mais est la fonction Octave
                  // correspondant à horner() => la page Scilab horner() est affichée

 // Equivalences Scilab de termes faux-amis
 uman end a       // la page Scilab "end" est affichée = controls (if | for | while.. end)
 uman end ax      // "x" reconnait en priorité les acceptions externes.
                  //   En langage Octave, "end" désigne le "numéro du dernier élément",
                  //   => la page Scilab "$" est maintenant affichée.

 uman flipdim x   // Aucune version externe trouvée => celle de Scilab est affichée

 // L'option "s" affiche le Sommaire de la section de l'item, au lieu de sa page :
 uman clear s    // toutes les fonctions dans la section de "clear" sont listées

Appeler le navigateur d'aide avec uman() et ses options :

uman strstr deg  // Dans le navigateur, les options "de" sont ignorées.
uman cholesky g  // = "help cholesky".
                 // Aucune page dédiée => Liste les pages contenant "cholesky"
uman who gs      // Affiche le sommaire de la section de "who"

// Pour changer la langue du navigateur, il doit être préalablement fermé. Puis :
uman who gslru

Avec une fonction utilisateur définie localement :

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
   // Fin de la fonction
endfunction
uman test   //  affiche le 1er bloc continu de commentaires en en-tête dans test()

--> uman test
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.

Avec un module ATOMS installé :

uman atoms d          // Liste des fonctions du gestionnaire ATOMS
yn = atomsIsInstalled("serial");
atomsInstall serial ; // Installons le module externe 'serial'
atomsIsLoaded serial  // => %F
uman openserial ca
uman openserial s     // Sommaire du module 'serial'
uman openserial ag    // Le navigateur d'aide appelé par l'option "g" n'affiche rien,
                      //  car "serial" est INSTALLÉ mais n'est pas CHARGÉ.
                      //  À la place, la page est affichée dans la console.

if ~yn, atomsRemove("serial"), end    // (ménage après ces exemples)

Voir aussi

• Configuration — Paramètres de configuration de uman()
• disp_usage — affiche les syntaxes autorisées pour une fonction donnée
• uman .. w — affiche la page web documentant un item
• uman .. b — affiche la liste des bugs documentés concernant un motif donné
• uman .. @ — Sélectionne des messages des archives des forums Scilab
• help
• apropos
• head_comments
• module ATOMS "removed" : pages des fonctions supprimées
• https://help.scilab.org
• http://bugzilla.scilab.org
• http://forge.scilab.org
• http://mailinglists.scilab.org

Auteur

Historique