uman >> uman > uman

uman

User manual in console. Advanced multimodal and multilingual documentation.

Syntax

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 b
uman item b
uman item1|item2.. b
uman author>item.. b
uman author1|author2|..>item.. b
uman author/section>item.. b
uman section/author>item.. b
uman section>item.. b
uman section1|section2|../author1|author2|..>item1|item2|.. b
uman "section1|section2|.. / author1|author2|.. > item1 | item2 |..<Ndays" b
uman ..<Ndays b
uman <Ndays b

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!" @

Table of contents

Arguments

pattern

a single string: function name, symbol ($, [, etc ), expression, bug number... about which informations are queried. The query is considered case-insensitive if it is all in lowercase. It is case-sensitive otherwise.

To include white spaces, comma ",", semi-colon ";", colon ":", "=", "//", parentheses, or braces, quotes ".." delimiting the pattern are mandatory.

options
Options described here are available when calling uman(). Another set of "fixed" options changing uman's behavior is available as uman preferences.

options is a single string without spaces, specifying one or several options. Each character (order and case insensitive) is a switch enabling a specific feature. Available options are described here-below.

By default, options are specified after the pattern. Otherwise, "-" must prefix the options string.

Options

  • defined as default ones, as Default display sections preferences,
  • specified before the pattern, prefixed with -,
  • and specified after the pattern

are cumulated, with the following decreasing priorities:

after pattern > before pattern > preferences > overall implicit default values.

WHERE the content must be displayed

By default, the text output is displayed in the console. Other targets are possible.

Priorities between targets options are: b > w, g > (console) > @

g : Help browser GUI. uman calls the Scilab help browser for the given pattern.

If the browser is not already opened, it is called in the active language, or in the language forced with the complementary option "L##".
If the pattern belongs to an external package installed but not loaded, related help pages can't be available in the help browser. Then, the queried page is displayed in the console, ending with a warning in the footer.
When "g" is used with "x" (eXternal packages), the page displayed in the browser is the Scilab version (if any) of the pattern, not the external one. Indeed, there is no way to force the browser considering first or only non-Scilab pages.
w : Web page: displays the related online help page in your web browser. Please see uman .. w for more information.
b : Bugs query: displays in your web browser a page listing online reported bugs related to the given pattern. Please see uman .. b.

This uman() mode is impacted by the Show only unresolved bugs configuration preference.
@ : Mailing lists @listes.scilab.org (web archives): Searches messages by subjects, authors, max message age, and displays the result in your web browser. None of other uman() options are used in "@" mode. Please see uman .. @
j : Journalize: Records in currently opened diaries (if any) all uman outputs printed in the console.

By default, all opened diaries are paused before and resumed after "uman" flows, in order to not be fed. If no diary is priorly opened, no journalization is done.
WHAT must be displayed

By default, the help page matching the query is displayed, with the following minimal sections:

  • Path in the help tree
  • Actual name of the feature (after a possible redirection), and its short description
  • List of allowed syntaxes
  • See also section
Additional sections may be displayed on demand (here-below).

Priorities between contents options are: u > s > a > p,d,e,h
u : usages : displays only the list of syntaxes defined for the pattern. This option has the highest content priority. It cancels all other contents options, but is ignored by the b, w and g mode options.
s : displays the summary of the help section of the pattern, instead of its page.
This option works also with the "g" one (Scilab help GUI). In the opposite, it is ignored in "w" web mode.
a : All sections displayed. It is a shortcut for "pdeh" options.
p : Parameters: displays the Arguments section.
When a page has no Arguments or Parameters section, its Description section is always displayed.
d : Description: displays Description, Bibliography, References, Authorship sections, as well as any other sections of unidentified types.
e : Examples: display identified Examples section(s)

Examples included in other types of sections are displayed within these ones. Using "e" has no effect on their display.
h : History of the pattern.
HOW the query must be processed

c :

Clear the Console before displaying the page.

L## : Language: gets the version of the page in Language ##, where ## mainly stands for one of the en | fr | ja | pt | ru language codes. Other codes such as de | zh | fa are as well supported, provided that resources in these languages are available (some external modules are translated into them). Otherwise, the session's language is used.

If L is specified as last option without ## code, or if the specified code is out of this list, the reference version in english is considered.

Since uman 2.0, partial corpus out of the en,fr,ja,pt,ru languages list are supported. Just put the corresponding .jar file on your computer as a usual package. "uman" will tap from it as soon as the chosen item will be available in the chosen "extra" language, and will automatically tap from other Scilab default resources to complete otherwise.

x : Priority to eXternal packages and references. This flag is used in 2 different ways:
  • When two distinct but homonymous features are proposed in Scilab versus in an external module (ATOMS, other package) or in FileExchange, by default uman addresses the Scilab version. Then "x" can be used to target the eXternal version first.

  • "x" can also be used to process "faux-amis": When the same pattern exists in Scilab and in an eXternal scientific language BUT with 2 different meanings, by default the Scilab meaning is considered. If the eXternal meaning must be considered instead, use "x". Then, uman will redirect the user toward the equivalent Scilab page.

    Faux-amis examples: end, load, home, null, range, type, etc. Hence, uman null will display the Scilab null() page, while uman null x will display the Scilab kernel() page, which is the equivalent of the null() Octave function.
r : Refreshes / Reloads the documentation list of all installed external modules, and deletes from the uman cache all pages already extracted from external modules.

For modules managed with the ATOMS system, the update of uman's registery is done automatically after each new installation or uninstallation of a module, and running the "r" option is useless.

Running once the "r" option will be useful
  • for any user, after changing the set of Paths of external modules out of ~/contrib in uman Preferences, or
  • for pages writers, after building a new version of pages.

Description

uman.. is a unified display command of the user manual and of other Scilab documentation. Help pages of Scilab (current functions or former removed ones), of ATOMS packages, of external packages, or heading comments in local functions are covered. Some references of the Scilab FileExchange are also available. The display may be performed in text mode in the console, as well as in the help browser, or on http://help.scilab.org in your web browser.

uman.. displays pages in any available language, without switching the session. The table of contents of the function's directory may be listed instead. The list of documented bugs related to a given item can be displayed online in a simple way.

For more than 220 external input words (coming from other scientific languages), uman automatically redirects the query to the equivalent or most relevant Scilab reference.

Supported OS

Windows, Linux and Mac OS, with Scilab 5.5 and Scilab 6.

Main features
  1. "uman" allows to easily select, grab and display informations

    • from embedded Scilab help pages,
    • from pages of installed ATOMS modules,
    • from heading comments in local user-defined functions,
    • from pages of other external modules, packed in .jar archives in a standard way,
    • from pages of former removed Scilab functions,
    • from the online Scilab help pages and search engine,
    • from ATOMS web pages (220 entries) and their comments,
    • from online Scilab forges,
    • from Scilab FileExchange pages (60 entries),
    • from Scilab's bugs tracker,
    • from archives of all official Scilab mailing lists,
    • and from other external web sites presenting Scilab resources.

    Do not care where the required information is: uman gets it from the right place and displays it for you: In the console, in the help browser, or in your internet browser for online resources, it's up to you.

  2. The default factory settings of uman do not match your most frequent needs? uman has a comprehensive set of configuration parameters, easy to set in the uman Preferences interface. You will always be able to easily override them with compact command-line options.

  3. No need to view the whole help page. Just choose information that you want to display: only usages (syntaxes) and See also. Or more: parameters, description, examples, history, table of contents of the item's help section.. If really the whole page must be displayed, the "a" option will do it.

  4. You use to code in Octave language? Specify the Octave term you have in mind : More than 220 automatic redirections will target and display the closest Scilab equivalences. Other handy shortcuts are also defined for all users.

  5. Just give a language code en | de | fr | ja | pt | ru | zh in option, and you get the right version of the help page in the console or online. No need to change the session language. Watching the reference en_US english version of the page is now straightforward, without leaving your locales.

  6. The item of your query is a deprecated feature that has been removed from Scilab? uman will tell it to you, and may anyway display its former help page, online, or in the console or the help browser (provided that the https://atoms.scilab.org/toolboxes/removed complementary module gathering pages of removed features is installed).

  7. You think that you met a bug? Check it with the "b" option, that will nicely list online documented bugs related to your query, possibly with filters (reporter's name, category, max age of last reports update), for Scilab and many ATOMS packages. Online users comments are as well directly reachable..

  8. No need to load modules in the Scilab session. Even the documentation of packages that do not run under your Operating System can be viewed and displayed in the console.

  9. Want to efficiently probe mailing lists, for some items, or some authors, on some given period? "uman" does it easily for you from the console.
Shortcuts

The following patterns (in lower case) do not exist as proper Scilab functions, but are uman-defined to display related contents or summaries in a comprehensive way, in the console or in the help browser:
apifun : List of apifun (external) function, if installed.
colors : Functions dealing with colors
files : List of file management functions
gui : Graphical User Interfaces. Interactive components (uicontrols)
hdf5 : List of functions managing HDF5 files
history : List of history management functions
ipcv : List of image processing functions of the external module IPCV (if installed).
keys : Page of Scilab's keyboard shortcuts
metanet : List of functions of the Metanet module (if installed)
plotting : List of graphical functions
signal : List of Signal processing functions
stats : List of functions in the Mathematics => Statistics section
trigo : List of trigonometric functions normal and hyperbolic, direct and inverse.
variables : List of items in the Scilab => Variables section
windows : MSWindows specific functions
xml : List of functions processing XML files and contents

Examples

// Please select each line one-by-one, execute it (CTRL+E), and see the result in console

 uman ndgrid u    // ndgrid() syntaxes (only)
 uman eye p       // Section "Parameters" (Arguments) displayed
 uman eye d       // Section "Description" displayed
 uman eye e       // Section "Examples" displayed
 uman linspace h  // Section "History" displayed
 uman eye ph      // Sections "Parameters" and "History" displayed
 uman eye a       // All: full page displayed
 uman ones d      // "d" displays all misc. sections (like "Remarks") as well

 uman .* cpd      // Operators or symbols are accepted.
                  // Console Cleared before teh display
 uman $ cpde      // Another one. Displays examples as well.

 uman linespec a  // all in lowercase => the query is case-insensitive: "LineSpec" found
 uman type a      // could display "type" or "Type" pages. "type" is prefered
 uman Type a      // displays the "Type" page , <> "type"
 uman typE a      // the "typE" exact page doesn't exist => "'typE' has no dedicated page"

 uman linspace Lruph // Russian version of linspace's page (Parameters and History)
 uman linspace hpL   // English reference version, still for Parameters and history
                     // ("L" used instead of "l" (~ "1" = one), but "l" is OK).

 uman uint16 ce      // Pages presenting several functions are supported
                     //  (here int8, int16, etc)

 // Nested terms, itemized or unordered lists are supported
 uman brackets cd
 //     Let's decrease the console's width. Then re-run
 uman brackets cd    // Wrapping is adjusted (but neither for the code samples)

 // Tables are supported :
 uman plotsparse cd     // 2 tables without borders, in the arguments section
 uman atomsSetConfig ac // tables with borders. Long lines in cells are wrapped

 // Inner redirections to pages or summaries :
 uman keys      // inner redirection to the console page, with its Description
 uman files     // Display the summary of functions dealing with files management.
                // Other shortcuts are defined in the same way. Try with "stats"

 // Scilab equivalences of external patterns inexisting in Scilab
 uman polyval d // Automatic Octave => Scilab redirection performed when possible.
                // polyval() does not exist in Scilab but is the Octave
                // function for Scilab's horner() => horner's page is displayed

 // Scilab equivalence of external faux-amis
 uman end a     // targets the Scilab related page = controls (if | for | while.. end)
 uman end ax    // "x" targets in priority an eXternal meaning for "end".
                //   In Octave, "end" means "index of last element", as "$" in Scilab
                //   => "$" page is displayed.

 uman flipdim x // If no eXternal version is found, Scilab's one is targeted anyway.

 // "s" displays the related Summary instead of the item's page
 uman clear s  // all functions in the "clear"'s section are listed

Using the GUI "g" mode:

uman strstr deg  // In the Scilab help browser the "de" options are ignored.
uman cholesky g  // aka "help cholesky". No dedicated page, but lists pages containing "cholesky"
uman who gs      // The parent summary of the item can also be targetted in the help browser.

// To switch the language in the help browser, this one must priorly be closed. Then:
uman who gslru

With a local user's function:

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
   // Last comment
endfunction
uman test   //  displays the heading block of comments in 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.

With an installed external ATOMS package:

uman atoms d           // List of ATOMS functions
yn = atomsIsInstalled("serial");
atomsInstall serial ; // Let's install the 'serial' external module
atomsIsLoaded serial  // => %F
uman openserial ca
uman openserial s     // Summary of the 'serial' module.
uman openserial ag    // The help browser called with "g" does not come,
                      //  because 'serial' is  INSTALLED, but NOT yet LOADED.
                      //  Instead, the page is displayed in the console.

if ~yn, atomsRemove("serial"), end    // cleaning after the example

See Also

Author

Samuel GOUGEON

History

VersionDescription
3.0 2019-08-22
  • uman Preferences interface introduced, to manage all configuration parameters.
  • New 'p' option to display the Parameters section of a page. The display of this section is no longer mandatory.
Removed Functions and features: In console, web or helpbrowser modes, when querying information about a known removed feature, now
  • uman displays an explicit message with last supporting Scilab version,
  • uman proposes a possible replacement (if any),
  • uman suggests targeting the archived online help page (if any).
uman now uses the complementary module https://atoms.scilab.org/toolboxes/removed whenever it is installed and pointing to it is relevant.

Other noticeable changes:
  • The display of complex contents in table cells has been improved. See the Changelog file.

  • <latex> formulae can now be displayed as text in the console, provided that a text-readable equivalent is provided in the alt <latex alt='..'> attribute in the source file of the page.

  • See also section: A one-line compact display listing only items without their short description is now available as a Preference.

  • Internal and external hyperlinks can now be indicated or displayed, according to a new preference.

  • The display of Xcos blocks pages is improved: Useless 'Module' and 'Palette' sections ignored, as well as the 'Block Screenshot' and 'Contents' ones, irrelevant in console mode. By default, the "a" option is now forced.

  • uman .. g no longer prints in the console a copy of the help page opened in the help browser. Printing is still done only when no content can be displayed in the browser (feature of an external unloaded module ; local user's function, ...).

  • 19 bugs fixed.
2.1 2016-10-30
  • 14 bugs fixed.
  • The block of syntaxes is now aligned. New configuration variable "umanAlignSyntaxes".
  • For a page without parameters section, the description section is now always displayed.
  • French version of help pages added.
2.0 2016-04-06 : Major version. uman refactored. Many new features, improvements, fixed bugs. uman now runs fully with Scilab 6.
1.4 2015-07-31 : First version compiled for Scilab 6. 3 bugs fixed.
1.3 2015-07-12 : 20 bugs fixed. See changelog.txt for details
1.2 2015-06-06 : Upgrade. ~40 improvements and bugs fixed.
1.1 2015-04-02 : Technical release by ATOMS's admin (after fixing ATOMS server issue)
1.0 2015-03-22 : First release

<< uman uman uman .. b >>