<< uman uman

uman >> uman > uman

uman

User manual in console, online, or browser, with language switch & related bugs

Calling Sequence

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

Arguments

pattern
a single string: function name, symbol ($, [, etc ), expression... 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, embrasse the pattern between quotes "..".
options

Options are briefly described here-below, as well as in details in the Description section later. Single string specifying one or several options. Each character (order and case unsensitive) is a switch enabling a specific feature.

WHERE the content must be displayed. By default, the text output is displayed in the console. Other targets are possible:

g :
Help browser GUI. Display in console is still done.
w :
Web page: display the related online help or bugs page in your web browser. Display in console is canceled.
j :
Journalize: allows recording the output in currently open diaries (if any).

HOW the query must be processed:

c :
Clear the Console before displaying the page.
L## :
Language of the version forced to be displayed. ## = language code en | fr | de | ja | pt | ru | zh (no code == en).
x :
priority to eXternal packages and references.
r :
Refresh / Reload the documentation list of all installed modules, and deletes all extracted pages. Must be used after new modules have been installed.

WHAT must be displayed. By default, the pattern help page is displayed, with the following sections: Path in the help tree / Actual name of the pattern / Calling sequences / List of input & output parameters / See also section. Additional sections displayed on query:

s :
displays the summary of the help section including the pattern, instead of its page. Cancels the "w" option.
a :
All sections displayed, but bugs URLs. Equivalent to "deh" options.
d :
Description: display Description, Bibliography, References, Authorship sections, as well as any other sections of unidentified types.
When the pattern includes "_properties", the description is always displayed.
e :
Examples: display identified Examples section(s)
h :
History
of the implementation of the pattern.
b :
Bugs: URL of the web page listing documented bugs related to the pattern. When "w" is also used, the page is opened in the web browser.

Description

You need human help? Help yourself, just call uman

uman.. is a unified display command of the user manual. Help pages of Scilab, of ATOMS packages, of external packages, or heading comments in 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 related documented bugs can be displayed online in a simple way. For more than 200 items (coming from other scientific languages), the user is automatically redirected to a relevant Scilab reference.

Main features
  • A single function to see help pages from Scilab, from installed ATOMS modules (no need to load them), from other external modules, and heading comments in functions. Around 50 external references available on the Scilab FileExchange can also be addressed.

  • A single function to target and display contents in the console, in the help browser, as well as online (help, bugzilla, atoms, forge, or even external websites).

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

  • Just display main infos in brief: path in help, calling sequences, parameters, See also. And be free to display more on request: description, examples, history, parent ToC... Or display the whole page with the "a" option.

  • Are you used to use another scientific language? Almost 200 automatic redirections will help you targeting the right Scilab equivalence. Other handy shortcuts are also defined for all users.

  • Stucked with a bug? The "wb" option let's you list documented ones related to the faulty entry, in two seconds, for Scilab and many ATOMS packages. Online users comments have never been so reachable.

  • Last but not least: get a smart text layout in console. Nested lists of items, tables, pieces of codes, notes and warnings, text styles.. are supported. The code style of calling sequences and examples is also improved.

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

Covered help pages and references

Scilab pages
are first and fully covered, in the console as well as online.
ATOMS pages
If some ATOMS modules have been installed for your Scilab, either for all users (by an admin) or only for you (by yourself), all their help pages are automatically considered.
ATOMS modules do not need to be loaded in session, just to be installed (in SCI\.atoms and SCI\contrib or SCIHOME\atoms\..). Hence, some pages unreachable through the help browser may be displayed, before loading the related module whether it looks finally relevant.
To target eXternal pages from ATOMS modules or other contrib modules in priority, before Scilab pages, use the "x" option.
Other contrib packages
As for ATOMS modules, standard help pages of every package installed by hand in SCI\contrib or in SCIHOME\contrib are targettable.
In case of homonymy between a function in an external module and the same in Scilab, the "x" option allows to target the eXternal one first and display it whether it is found, and to scan Scilab contents only afterwards.
Miscellaneous functions
If uman does not find any matching item in Scilab and installed ATOMS and contrib packages, it looks whether the pattern is a function defined in the session. If it is the case, it displays its heading comments (if any), the easiest way to document a Scilab function.
Other references
If no related function loaded in session is found, a table of external references is scanned. These ones mainly deal with functions distributed on the Scilab FileExchange, provided that they are well enough conditioned. A few additional references out of the FileExchange and ATOMS are also defined. This table is scanned only when the "w" is used (online contents targeted).
What next? Redirections!
If uman has still found nothing matching your query, it silently looks whether a redirection (associated reference, alias) is defined for the pattern. Redirections are defined for some usual terms existing in other main Scientific languages, that do not exist in Scilab, and that do not mean anything else in Scilab (faux amis). Some helping terms are also processed, such as typos like lenght for length, as well as a bunch of shortcuts aiming to soften your life... If a redirection matches the query, uman is automatically rerun with it.

Options : detailed description

single string 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 specified before AND after the pattern are cumulated. Frequently used options may be used before the pattern, while it will be more handy changing versatile ones in end of command line.

WHERE it must be displayed.

By default, the text output is displayed in the console. Its width is limited to 100 characters. Other targets are possible:

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

If the browser is not already opened, it is called in the active or forced language (see the "L##" option).

If the pattern belongs to an external package installed but not loaded, related help pages can't be available in the help browser. A warning is then displayed in footer in the console.
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. There is no way to force the browser considering first or only non-Scilab pages.
w :

web page: When this option is used without the "b" one (for bugs), uman opens your web browser and displays the help page of the online manual, for the given pattern (internet connection alive required). Then,

  • if the pattern belongs to Scilab:
    • The online page of the pattern is called on http://help.scilab.org. The language (default, or forced with the "l" switch) is taken into account to target the right online version.
    • The display of the page in the console is canceled.
  • Else, if the pattern is registered (from ATOMS or another external module or FileExchange or among miscellaneous references),
    • If a website is registered for the reference, it is opened in your web browser. Actually, for ATOMS modules, no online help pages are hosted on http://atoms.scilab.org (see http://bugzilla.scilab.org/6723).
    • If the pattern may point to some integrated help contents (ATOMS, other external modules with standard help, Feature from FileExchange with heading comments, etc), the page or content is displayed in the console.
  • Otherwise, if the pattern is definitely not found among available ones, the search engine on http://help.scilab.org is called for it.

When both "wb" options are used, the proper online bug tracker page (when it exists) is targeted instead. This page depends on the pattern: When it

  • ...belongs to Scilab: the sorted list of all documented bugs related to the pattern is selected and displayed on http://bugzilla.scilab.org.
  • ...belongs to an ATOMS module having a Scilab forge: the list of documented bugs related to the pattern is selected and displayed on the tickets page of the Forge http://forge.scilab.org/index.php/p/<module_name>/issues/.
  • ...belongs to an ATOMS module without Scilab forge: the ATOMS page of the module is targeted down to its comments section, where bugs can be reported.
  • ...is a FileExchange item: the FileExchange page of the item is targeted down to its comments section, where bugs can be reported.
  • ...belongs to another external module or reference registered with a proper website: the website is targeted.

j :
Journalize: records the uman's output in currently opened diaries (if any).

By default, 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.

HOW the query must be processed:

c :
Clears the Console before displaying the page
L## :
Language: gets the version of the page in Language ##, where ## stands for one of the en | fr | de | ja | pt | ru | zh language codes. 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.
x :
eXternal packages and references first. This flag is used in 2 different ways:
  • When the same function name is proposed in Scilab as well as from an external module (ATOMS, other package) or from FileExchange, by default uman addresses the Scilab version. To target the eXternal version first, use "x". If "x" is used while there is no version of the pattern in external packages, Scilab is finally targeted.
  • When the same pattern exists in Scilab and in an eXternal scientific language with 2 different meanings, by default the Scilab meaning is considered, and the related Scilab page is targeted. If the eXternal meaning must be considered, use "x". Then, uman will redirect the user toward the equivalent Scilab page.

    Faux-amis examples: type, end, load, home, range, null ...

r :
Refresh / Reload the list of available documentations, and deletes all the already extracted pages in order to force their new extraction for forthcoming queries. This option must be used once, after some new modules have been installed.

By default, the list of documentations is initially set, stored, and automatically refreshed once a week. In addition, each new page extracted from the help system is stored in cache (either for Scilab's pages, or for other ones in a separated cache directory). Any further call to this page uses the stored version. After having installed some new modules or removed some other ones, it is necessary to refresh uman's database to detect the related new help pages. As well, when a developer updates an help page of a module, it is necessary to delete its stored version and to extract again the page. "r" does it.

WHAT must be displayed.

By default, the help page matching the query is displayed. However, the s switch allows to display instead the parent Summary to which the pattern belongs, = the list of functions or features of the same type, appearing at the same level in the help tree.

The following sections of help pages are always displayed: Path through the help tree / Actual name of the feature (after an eventual redirection) / Calling sequences / List of input & output parameters / "See also" section. Additionnal sections may be displayed on demand:

s :
summary: display the parent summary including the pattern, instead of its page.
This option works also with the "g" one (simultaneous output in the Help browser GUI).
This option cancels or ignores "w", "a", "b", "d", "e", "h" options.
a :
All sections displayed, but bugs URLs. Option equivalent to "deh".
d :
Description: display also description sections. This includes Bibliography, References, Authorship sections, whether they exist. Any other sections whose types are unidentified are also displayed.
When the pattern includes "properties" or "property", the description is always displayed without using "d".
e :
Examples: display identified Examples section(s)

Examples included in other types of sections are displayed within these ones, without requiring the "e" option.

h :
History: display the History section of the page (whether it exists).
b :
Bugs: displays links about bugs reporting / reported. When both "b" and "w" are used, the online page reporting bugs about the pattern is opened instead (provided that the user has a persistent internet connection): See hereabove within the WHERE/"wb" section.
Shortcuts

The following patterns (in lower case) do not exist in Scilab but are defined to display related contents or summaries in a comprehensive way: colors (list of named colors), datatypes (Data types page), files (summary of file management functions), graphics (summary), hdf5 (summary of functions), metanet (summary), shortcuts (related page), signal (summary for signal processing), sparses (summary of main functions for sparse matrices), statistics (summary), variables (summary), trigo (trigonometry), windows (summary), xml (summary).

Technical
  • uman extracts Scilab pages in the SCIHOME\uman directory, and ATOMS and contrib pages in SCIHOME\uman\atoms one.

  • contrib packages:

    • Each package must have a ~\help\* directory containing scilab_##_##_help.jar standard help zipped files, where ##_## stands for each supported language (one file per language). At least, a reference scilab_en_US_help.jar file must be available.

    • The package must also have a ~\etc\<package_name>.start directory and file. The file may be empty. Only its name <package_name> is used: it is and it provides the package's name.

    • Each contrib package may be stored anywhere in the SCI\contrib or SCIHOME\contrib subtrees, not necessarily at their roots.

Known limitations

  • Once a week, the first call to uman lasts a bit before answering. This time is spent to redetect and reference all available help pages on your computer.
  • Switching language in the help browser with the "g" option needs first to close it (by hand ; no way by code)(see http://bugzilla.scilab.org/12889)
  • Calling the help browser with the "g" option does not bring it to the foreground: see http://bugzilla.scilab.org/13756
  • LaTeXed expressions rendered as images can't be reversed and displayed as clear text. Nevertheless, their existence is indicated in the text.
  • Long lines in multicolumn table's cells are not wrapped.
  • For pages in Chinese, long lines without space are not wrapped.
  • uman is not self-extensible to any language. If you wish to add a (left-to-right) language, please get in touch with the author.
  • Particular cases : for uman "=", uman "==", uman "(", uman "//", uman ";", uman ","...quotes are mandatory.
  • uman can't be used in naked console mode for MS Windows releases (UTF8 badly rendered: See http://bugzilla.scilab.org/10748).

Examples

uman               // display this man's help (main contents + examples)

uman .*. cd        // Operators or symbols are accepted. here: shortcut to kron()
uman  $  cde       // Another one. Add examples.

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 
uman typE a        // the "typE" exact page does not exist => displays /"typE" has no dedicated page/

uman linspace Lrua // Russian version of linspace's page
uman linspace aL   // English reference version

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

// nested itemized or unordered lists are supported
uman daskr cd   
//     Let's decrease the console's width. Then re-run
uman daskr 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 overloading cd  // tables with borders.

// Inner redirections to pages or summaries :
uman shortuts    // 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 "statistics"
                 
// 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.. end / for.. end / 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
                  
// "s" display the related Summary instead of the item's page
uman strstr s    // all functions related to string processing are listed

// "g" calls also the help browser GUI (may be docked over the editor)
uman strstr deg
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   // Anyway, the version displayed in console will be in the required language.

// With any special loaded 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
endfunction
uman test    //  displays the heading block of comments in test()

// With an ATOMS package
// =====================
uman atoms d           // List of ATOMS functions
yn = atomsIsInstalled("plotlib");
atomsInstall plotlib ; // Let's install Plotlib
atomsIsLoaded plotlib  // => %F
uman plot cde          // The Scilab's plot() page is targeted in priority
uman plot cdex         // "x" means: eXternal plot()'s page first, from Plotlib
uman linspace cax      // If no eXternal version of linspace() is found, Scilab's one is targeted.
uman plot cdexg        // The help browser called with "g" does not come, because Plotlib is 
                       //  INSTALLED, but NOT yet LOADED (Scilab must be restarted after instal).

// WITH AN INTERNET CONNEXION ALIVE
// ================================
// Online help page : The "w" option
// ----------------
uman ode w        // in the session's language (if it is registered, otherwise in english)
uman ode wlpt     // in Portuguese
uman ode wl       // Reference page in english
uman sort wlru    // The "w" option also benefits from the inner redirection "sort => gsort"
uman cholesky w   // For any unknown pattern => online search engine &amp; results
uman contour3d w  // For a function only available and registered on FileExchange, the related
                  //  online page is opened. 
uman quiver xw    // quiver() is from the ATOMS module Plotlib. There is no (yet) online help 
                  //  pages for ATOMS modules => the page is displayed in the console instead 
                  //  (with a specific footer).

// Documented bugs online: The "wb" options
// ----------------------
uman ode wb       // For any Scilab internal function, on bugzilla, well sorted (unfixed bugs first)
uman cholesky wb  // For any unknown pattern, on bugzilla, well sorted (unfixed bugs first)
uman quiver xwb   // The Plotlib ATOMS module containing quiver() has also a Scilab's Forge and
                  //  a dedicated "Tickets tab" for bugs reporting. The list of reported bugs
               //  is filtered against "quiver" and is displayed online.
uman cshift wb       // For some a function registered on FileExchange, bugs may be reported as users
                  //  comments on the dedicated online page.
               
if ~yn, atomsRemove("plotlib"), end    // cleaning after the example

See Also

History

VersionDescription
1.0 / 2015-03-22

First release

1.1 / 2015-04-02

Technical release by ATOMS's admin (after fixing ATOMS server issue)

1.2 / 2015-06-06

Upgrade. ~40 improvements and bugs fixed. Ready for Scilab 6. See the file changelog.txt for details.


Report an issue
<< uman uman