Manuel d'utilisation en console, documentation multimodale multilingue avancée
uman uman pattern uman pattern options uman -options pattern uman -options pattern options
uman item g uman item gx.. uman item gL uman item gL<lang>
uman item w uman item wx.. uman item wr.. uman item wL uman item wL<lang> uman item1|item2|.. wL<lang> uman "item1 | item2 | .. " wL<lang>
uman bugNumber wb uman item wb uman item1|item2.. wb uman author>item.. wb uman author1|author2|..>item.. wb uman author><Ndays wb uman section/>item.. wb uman section/><Ndays wb uman section1|section2|../author1|author2|..>item1|item2|..<Ndays wb uman "section1|section2|.. / author1|author2|.. > item1 | item2 |..<Ndays" wb
uman topic! @ uman topic @ uman author>topic! @ uman author1|author2>(topic1|topic2)&topic3&~(topic4|topic5)! @ uman author><Ndays @ uman author>topic<Ndays! @ uman "author > topic1 | topic2 < Ndays!" @
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 "wb" 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.
Le comportement par défaut de uman
peut être modifié en utilisant diverse variables de configuration dont la valeur sera fixée dans votre fichier personnel de démarrage de session SCIHOME\scilab.ini
ou SCIHOME\.scilab
.
Ces variables doivent être déclarées en global
afin de les protéger contre d'éventuelles instructions clear
(très prisées des matlabeurs mais dévastatrices en Scilab).
Variables disponibles :
umanMaxLineWidth : entier décimal sur l'intervalle [50, 110]. Les valeurs hors de cet intervalle sont ignorées. La valeur par défaut est 90. Lorsque la console est très large, cette variable permet de restreindre la largeur d'affichage des pages d'aide à une largeur choisie inférieure à celle de la console. Pour rester aisément lisible, chaque ligne doit comporter en moyenne entre 10 et 12 mots. Au delà, le déchiffrage visuel devient pénible. Si la console est plus étroite que umanMaxLineWidth
caractères, sa largeur effective est prise en compte et la valeur de umanMaxLineWidth
est ignorée.
umanDefaultOptions :
Mot sans espace = série d'options de uman
à utiliser par défaut. Voir plus loin la liste complète des options.
uman
.uman
.umanUserPaths : vecteur de textes. Chaque élément du vecteur indique le chemin d'un répertoire dans lequel -- au delà des dossiers standard SCI\contrib
et SCIHOME\contrib
de résidence des modules externes -- uman
doit chercher d'autres modules et leur documentation. Pour être visibles par uman
, ces modules doivent être conditionnés selon les règles minimales décrites dans la section Aspects techniques.
umanAlignSyntaxes = "" | "l" | "r" (par défaut) : indique le mode d'alignement des syntaxes affichées en console pour une fonction :
Le mode "r" est le plus lisible. Il est utilisé lorsque umanAlignSyntaxes
n'est pas explicitement définie.
umanNoStyle = %T | %F : valeur booléenne (par défaut = %F). À fixer à %T si l'on souhaite annuler l'affichage des styles en équivalents ASCII : "/.../" pour les parties en italique, mise en majuscules pour les "PARTIES EN GRAS", etc. En effet, "/" peut parfois devenir ambigu et être confondu avec une division ; si un mot en minuscule mis en gras désigne le nom d'une variable, sa mise en majuscules pose alors problème car désigne une variable distincte ; etc.
Exemple : nous souhaitons fixer par défaut
umanNoStyle = %t
,
umanDefaultOptions = "d"
, et
umanMaxLineWidth = 100
.
Nous ferons :
edit SCIHOME\scilab.ini
. Dans ce fichier, ajoutons les lignes de code suivantes :
global umanNoStyle umanDefaultOptions umanMaxLineWidth umanNoStyle = %T umanDefaultOptions = "d" umanMaxLineWidth = 100
global
, le nom des variables ne doivent pas être séparés par des virgules mais par des espaces.texte simple sans espace indiquant une ou plusieurs options. Chaque caractère (ordre et typographie indifférents) active une fonctionnalité spécifique. Les options disponibles sont décrites ci-après.
Par défaut, les options
sont indiquées after le pattern
. Sinon, le mot des options
doit être préfixé par "-"
.
Les options
umanDefaultOptions
,pattern
et préfixées avec -
, en appelant uman
,pattern
, en appelant uman
,se cumulent selon les priorités décroissantes suivantes :
après le pattern >
avant le pattern >
via umanDefaultOptions >
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
: wb > w, g > @
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 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
| ||||
w : | page Web : affiche dans votre navigateur internet la page d'aide internet officielle, ou la page web des bugs documentés. L'affichage de la page d'aide dans la console est supprimé. Voir uman .. w. | ||||
wb : | Web Bugs : affiche dans votre navigateur internet la page web des bugs documentés concernant le pattern indiqué. Aucun affichage n'est effectué en console. Voir uman .. wb. | ||||
@ : | 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 de tous les affichages produits par uman dans tous les journaux actuellement ouverts (s'il y en a).
Par défaut, tous les journaux ouverts sont suspendus par |
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 Depuis |
x : | Priorité aux modules et références eXternes. Cette option est utilisable de deux manières :
|
r : | Rafraichit / Recharge le registre de tous les modules externes installés, et supprime toutes les pages précédemment extraites des modules externes.
Le registre des ressources JAR est initialement créé lors de la 1ère utilisation de |
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 suivantes :
![]() | Les options de contenus sont classées selon les priorités suivantes : u > s > a > d,e,h,b |
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. En particulier elle annule les options "s" (sommaire) ou "w" (page web). | ||||
s : | affiche le sommaire de la section de l'aide documentant l'item choisi,
au lieu d'afficher sa page d'aide.
| ||||
a : | All : affiche toutes les sections. Cette option équivaut aux options cumulées "deh" . | ||||
d : | Description : affiche les sections Description, Bibliographie, Références, Auteurs sections, ainsi que toutes les autres sections de types non identifiés.
| ||||
e : | Exemples : affiche les sections "Exemples"
Les exemples présentés dans d'autres sections sont affichés au sein et avec celles-ci. L'option | ||||
h : | Historique de l'implémentation du pattern . | ||||
b : | Bugs : URL de la page internet listant les rapports de bugs concernant le pattern . Lorsque l'option "w" est simultanément utilisée, la page correspondante est ouverte dans le navigateur internet. |
You need human help? Just call uman
uman..
est une fonction avancée très compacte et paramétrable permettant d'accéder depuis la console et de manière unifiée à diverses ressources documentaires, en premier lieu aux manuels d'utilisation de Scilab. Les pages d'aide de Scilab, des modules ATOMS, des autres modules externes, ressources documentées sur le FileExchange Scilab ou externes, documentation des fonctions locales en commentaires d'en-tête, archives des listes de messagerie officielles, registres des rapports de bugs.. sont notamment couverts. uman
permet en particulier d'afficher les pages d'aide directement dans la console ou dans votre navigateur internet, dans la langue choisie.
uman
peut être utilisée sous Windows, Linux et Mac OS, avec Scilab 5.4, 5.5, et Scilab 6.
"uman" permet facilement de trouver, extraire, et afficher des informations issues
Où l'information requise se trouve-t-elle ? uman
recherche l'information parmi de nombreuses ressources dispersées, la met en forme et l'affiche pour vous : dans la console, dans le navigateur d'aide, ou dans votre navigateur internet : à vous de choisir avec une option compacte d'un seul caractère.
Le comportement par défaut de uman
ne vous convient pas ? uman
est facilement paramétrable, dans votre fichier de démarrage personnel. Toutes les options d'appel de uman
restent à tout moment utilisables pour s'adapter à vos besoins documentaires ponctuels.
Seule une partie de la page d'aide vous intéresse ? Les syntaxes admises, les exemples, la description des paramètres, les fonctions dans le même chapitre, etc ? uman
vous permet d'afficher uniquement la section souhaitée.. Si toute la page d'aide vous intéresse réellement, l'option "a" l'affichera en entier.
Vous êtes habitué-e au langage Octave ? Indiquez le terme Octave que vous avez à l'esprit : près de 200 redirections vous mèneront directement à la page Scilab équivalente. D'autres racourcis pratiques sont également définis pour tous les utilisateurs.
Inutile de charger les modules externes en session pour en consulter la documentation avec uman
. Même les pages des modules qui ne fonctionnent pas avec votre ordinateur peuvent ainsi être affichées en console.
Indiquez juste en option le code linguistique en | de | fr | ja | pt | ru | zh
souhaité, et la version correspondante de la page demandée s'affiche en console ou en ligne. Inutile de changer la langue de la session. Vous avez un doute sur la version traduite d'une page ? Consulter la version de référence en anglais est immédiat.
Un bug dans votre code vous résiste ? L'option "wb" de uman recherche et affiche la liste des bugs documentés concernant la fonction indiquée qui semble défaillante. Les rapports de bugs peuvent également être sélectionnés selon leur auteur ou commentateur, la catégorie, ou la période de publication, pour Scilab et pour de nombreux modules ATOMS.
Vous souhaitez sonder les archives des listes de diffusion à propos d'un item, d'un auteur de messages, d'une période donnée ? uman
le fait aisément pour vous depuis la console.
Sans conclure.. uman
affiche le texte de manière intelligible. Listes d'items imbriquées, tableaux simples avec ou sans bordures, extraits de code, notes et alertes, styles de texte.. sont supportés. Le style du code des syntaxes admises ou des exemples est également amélioré.
Les termes suivants (en minuscules) ne sont pas des fonctions Scilab, mais sont définis pour uman afin de cibler certains contenus importants de manière directe :
apifun : | Liste des fonctions du module externe apifun (s'il est installé). |
colors : | Fonctions de gestion des couleurs |
datatypes : | Liste des types de données |
files : | Principale liste des fonctions de gestion des fichiers |
gui : | Graphical User Interfaces : interfaces interactives. Composants graphiques interactifs (menus, uicontrols) |
hdf5 : | Liste des fonctionnalités HDF5 (fichiers et format) |
history : | Fonctionnalités d'historisation des commandes Scilab |
ipd : | Fonctions du module externe de traitement d'images IPD (s'il est installé). |
keys : | Liste des raccourcis clavier de Scilab |
metanet : | Fonctions du module externe Metanet (s'il est installé) |
plotting : | Liste des fonctions graphiques |
signal : | Fonctions de traitement du signal (liste principale) |
stats : | Fonctions statistiques (liste principale) |
trigo : | Fonctions trigonométriques normales et hyperboliques, directes et inverses |
variables : | Sommaire de la section Scilab => Variables |
windows : | Fonctions Scilab spécifiques à MS Windows |
xml : | Fonctions de traitement des fichiers et contenus XML |
Nous ne donnerons pas ici l'algorithme détaillé de recherche documentaire suivi par uman
en fonction du pattern
donné. 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 manière de prendre en compte les possibles redirections de tous types, l'option "x", la version linguistique choisie, et la casse typographique du pattern
est directement considérée dans le code.
Les sources documentaires suivantes sont considérées :
umanUserPaths
déclarée dans le fichier de démarrage de l'utilisateur.Si aucune de ces ressources ne correspond à l'item du pattern
ou à ses possibles alias, d'autres ressources externes indexées mais non installées sont scrutées, à savoir :
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.
pattern
donné.Les alias / redirections définis dans uman ne sont pas utilisés en mode "wb".
Archives de l'ensemble des listes de diffusion, sur mailinglists.scilab.org
uman
extrait les pages d'aide de Scilab et des modules ATOMS ou autres modules Contrib et les stocke dans SCIHOME\uman
et ses sous-dossiers.SCI\contrib
(ATOMS ou autres) :
Tout module externe peut et doit résider n'importe où dans les dossiers SCI\contrib
ou SCIHOME\contrib
, pas nécessairement à leur racine.
Chaque module doit avoir un sous-dossier ~\jar\*
contenant un ou plusieurs fichiers standard scilab_##_##_help.jar
tels que produits par xmltojar(..)
, où ##_##
désigne le code linguistique de la version du fichier (un seul fichier .jar par langue).
Le dossier du module doit également avoir un sous-dossier et un fichier ~\etc\<package_name>.start
. Le fichier .start peut éventuellement être vide. Seul son nom <package_name> est utilisé par uman
: il indique le nom = identifiant technique du module.
"uman .. gl##"
.. Voir le bug n° 12889uman
n'est pas automatiquement extensible à toutes les langues. Si vous souhaitez ajouter une langue (par exemple lue de droite à gauche), merci de prendre contact avec l'auteur."g"
n'amène pas celui-ci au 1er plan (s'il est amarré au bureau Scilab) : voir le bug n° 13756uman
ne peut pas être utilisée en mode console sans menus pour Scilab sous Windows : l'affichage UTF8 est défaillant. Voir le bug n° #10748.uman // affiche cette page d'aide (Paramètres, "Voir aussi") uman .*. cd // Les opérateurs et les symboles sont admis (raccourci vers kron()) 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" uman typE a // L'item "typE" n'existe pas => "Aucune page trouvée pour 'typE'" uman linspace Lrua // version russe de la page entière 'linspace' uman linspace aL // version de référence en anglais (par défaut) uman uint16 ce // Cette page présente plusieurs fonctions (int8, int16, etc) // Elle est correctement ciblée et traitée. // Les listes à puces ou numérotées imbriquées sont correctement affichées : uman daskr cd // Réduisons la largeur de la console. Puis relançons uman daskr cd // Les lignes sont correctement 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.. end / for.. end / 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. // L'option "s" affiche le Sommaire de la section de l'item, au lieu de sa page : uman strstr s // toutes les fonctions de traitement du texte sont listées // L'option "g" appelle simultanément le navigateur d'aide (amarrable au dessus de l'éditeur) uman strstr deg uman cholesky g // = "help cholesky". Aucune page dédiée => Liste les pages contenant "cholesky" uman who gs // Le sommaire de la section de l'item peut aussi être ciblé // et affiché dans le navigateur d'aide. // Pour changer la langue du navigateur, il doit être // préalablement fermé. Puis : uman who gslru // version russe demandée affichée en console. // Pour toute fonction locale chargée en session telle que celle-ci : 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 1er bloc continu de commentaires en en-tête dans test() // Avec un module ATOMS installé // ============================= uman atoms d // Liste des fonctions du gestionnaire ATOMS yn = atomsIsInstalled("plotlib"); atomsInstall plotlib ; // Installons le module "Plotlib" atomsIsLoaded plotlib // => %F uman plot cde // La fonction Scilab plot() est prioritaire. Sa page est affichée. uman plot cdex // Avec "x", la fonction plot() du module eXterne "Plotlib" // devient prioritaire. La page Plotlib de plot() est affichée. uman linspace cax // Aucune version externe de linspace() n'est trouvée // => la version Scilab est affichée. uman plot cdexg // Le navigateur d'aide appelé par l'option "g" n'affiche // rien, car "Plotlib" est INSTALLÉ mais n'est pas CHARGÉ if ~yn, atomsRemove("plotlib"), end // (ménage après ces exemples)
Version | Description |
2.1, 2016-10-30 |
|
2.0, 2016-04-06 | Version majeure. uman reformulée. Nombreuses nouvelles fonctionnalités, améliorations, et bugs corrigés. uman est maintenant utilisable avec Sclab 6. |
1.4, 2015-07-31 | Première version binaire pour Scilab 6. 3 bugs corrigés. 10 références ajoutées. |
1.3, 2015-07-12 | 20 bugs corrigés. 20 références ajoutées. Voir les détails dans changelog.txt |
1.2, 2015-06-06 | Près de 40 améliorations et bugs corrigés. Code prêt pour Scilab 6. |
1.1, 2015-04-02 | Version technique intermédiaire créée par l'administrateur ATOMS (après correction de bugs ATOMS) |
1.0, 2015-03-22 | Première version publiée |