<< disp_usage uman uman .. @ >>

uman >> uman > uman

uman

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

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

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.

Environment variables

uman allows to set environment variables in your personnal startup file SCIHOME\scilab.ini or SCIHOME\.scilab. Values set in these variables modify the default uman bahavior.

These variables must be set as global ones, in order to protect them against any clear instruction used in your code.

Available variables follow:

  • umanMaxLineWidth : Decimal integer in [50, 110]. Values out of this interval are ignored. Default value = 90. When your console is very wide, this variable allows to restrict the display of help contents on shorter lines, in order to remain easily readable. If the console is narrower than umanMaxLineWidth, its true width is taken into account instead of umanMaxLineWidth.

  • umanDefaultOptions : Word with no spaces = series of uman options to be used by default. See the list of options for more details.

    • "w", "wb" and "@" options are not accepted in default ones.
    • Default "s" is overriden by d | e | h | b | a | u on command line.
    • Default "u" is overrriden by d | e | h | b | a | s on command line.

  • umanUserPaths : vector of texts. Each component indicates the path to a directory out of default supported ones (SCI\contrib, SCIHOME\contrib), where uman must look for additional external modules. These modules must be packaged according to minimal rules described in the Technical aspects section.

  • umanNoStyle = %T | %F : boolean value (default = %F). Set to %T whenever you want to cancel ASCII styling with "/.../" for italic, and capitalization "TEXT IN BOLD" for bold styles. Indeed, "/" may be confused with divisions, while changing the case of -- say -- variables names may also be confusing.

Example: We want to set by default umanNoStyle = %t, umanDefaultOptions = "d", and umanMaxLineWidth = 100. We will do:

edit SCIHOME\scilab.ini. In this file, we will add the following lines:

global umanNoStyle umanDefaultOptions umanMaxLineWidth
umanNoStyle = %T
umanDefaultOptions = "d"
umanMaxLineWidth = 100
Note that on the global line, variables must not be separated with comas but with spaces.

options

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 specified

  • as default ones in the umanDefaultOptions environment variable
  • before the pattern, headed with -,
  • and after the pattern
are cumulated with the following decreasing priorities:

after pattern > before pattern > default in umanDefaultOptions > overall 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: wb > w, g > @

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: display the related online help or bugs page in your web browser. The display in console is canceled. See uman .. w.
wb : Web Bugs: display online reported bugs matching the pattern, in your web browser. The display in console is canceled. See uman .. wb.
@ : Mailing lists @listes.scilab.org (web archives): search by subjects, authors, max age of messages. Use this independent option alone. See uman .. @.
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 : 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 draw from it as soon as the chosen item will be available in the chosen "extra" language, and will automatically draw from other Scilab default resources to complete otherwise.

x : priority to eXternal packages and references. 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 resources are finally targeted.
  • "x" may 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, use "x". Then, uman will redirect the user toward the equivalent Scilab page.

    Faux-amis examples: type, end, load, home, range, null, etc. These terms are used in Scilab as well as for instance in Octave, but have completely different meanings in both languages.

r : Refresh / Reload the documentation list of all installed external modules, and delete all pages already extracted from external modules.

"r" must be used after that new modules have been installed or former modules have been uninstalled.

By default, the list of documentations is initially set and stored. 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" will do it.

WHAT must be displayed.

By default, the help page matching the query is displayed, with the following sections: Path in the help tree / Actual name of the feature (after a possible redirection) / Calling sequences / List of input & output parameters / See also section. Additional sections may be displayed on demand (here-below).

Priorities between contents options are: u > s > a > d,e,h,b

u : usages : displays only the list of syntaxes defined for the pattern. This option has the highest priority. It cancels options "s" or "w" (web page).
s : displays the summary of the help section of the pattern, instead of its page.
This option works also with the "g" one (simultaneous output in the Help browser GUI).
"s" cancels or ignores "w", "a", "b", "d", "e", "h" options.
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)

Examples included in other types of sections are displayed within these ones. Using "e" has no effect on their display.

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
  • "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, from the online Scilab help pages and search engine, from ATOMS web pages (200 entries) and their comments, from online Scilab forges, from Scilab FileExchange pages (60 entries), from Scilab's bug trackers, from archives of all official Scilab mailing lists, and from other external web sites presenting Scilab resources.

    You don't have to think about where is the required information: "uman" gets it from the right place and displays it for you. You can get it in the console, in the help browser, or in your internet browser for online resources.

  • 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.

  • No need to view the whole help page. Choose informations that you want to display: only usages (syntaxes), parameters, See also. Or more: 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.

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

  • 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.

  • Set your default "uman" parameters in your startup file, and enjoy. You will always be able to easily override them in compact command-line options.

  • Stucked with a bug? The "wb" option let's you either view the page of a specific bug, or nicely list documented bugs related to a chosen item, or list bugs related to a given category/section, or from some chosen reporters or commenters, or within a chosen period, for Scilab and many ATOMS packages. Online users comments are as well directly reachable..

  • Want to efficiently probe mailing lists, for some items, or some authors, on some given period? "uman" does it easily for you.
  • 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.

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:
apifun : List of apifun (external) function, if installed.
colors : Functions dealing with colors
datatypes : Data types page
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
ipd : List of image processing functions of the external module IPD (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
stat : 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

Resources and references used

We won't here provide detailed information about the fine way uman searches for the given pattern among all considered sources of informations. We just list the different sources and criteria, without telling more about the algorithm. This one can be found in the code, under the "SEARCHING FOR THE RIGHT HELP TARGET" part. how it takes into account possible aliases of various types, the "x" option, the chosen language, and of the case sensitivity of the pattern.

Resources in console mode:

The following resources are considered:

  • Internal and external-to-internal aliases.
  • Scilab official pages, in all officially supported languages (en, fr, ja, pt, ru).
  • ATOMS modules installed in "all users" as well as in "user" modes.
  • Other external modules installed in the SCI\contrib or SCIHOME\contrib directories or their subdirectories.
  • Other resources declared in the umanUserPaths environment variable.
  • Local functions written in Scilab language and having heading comments used as embedded help contents.

If the pattern or its possible alias is not found in these resources, other registered uninstalled external resources are scanned against it, namely:

  • External-to-external aliases.
  • Other registered ATOMS modules.
  • Some other public modules available on the Scilab forge.
  • Well-packed, identified and original resources on the Scilab FileExchange.
  • Other external references out of ATOMS, the Scilab forge, and the FileExchange.

If the pattern is finally found or has an external alias among these additional remote resources, a message inviting to use the "w" option and the proper pattern is displayed in the console.

Resources in web "w" mode:

Internal-to-internal, external-to-internal, and external-to-external aliases may as well be found and used along the successive searching steps

  • Contents of Scilab official online help pages, in all officially supported languages (en,fr,ja,pt,ru).
  • Contents of ATOMS modules installed in "all users" as well as in "user" modes.
  • Names of other registered ATOMS modules.
  • Names of other public modules on the Scilab forge.
  • Well-packed and identified resources on the Scilab FileExchange.
  • Other registered external resources.
  • Search engine on http://help.scilab.org

Resources in "wb" bugs mode:

  • Scilab functions, on Scilab Bugzilla website.
  • Functions of installed ATOMS modules, and then, either the ticket page of their forge, or the Comments section of their ATOMS page.
  • For any pattern identified on the FileExchange: The Comments section of the related FileExchange page.
  • Other registered external resources.
  • Search engine on http://bugzilla.scilab.org

Internal-to-internal, external-to-internal, and external-to-external aliases may still be found and used along the successive searching steps.

Resources in "@ mailing lists mode:

Online archives of all official Scilab mailing lists.

Technical aspects

  • uman extracts Scilab, ATOMS and other Contrib pages in SCIHOME\uman subdirectories.
  • contrib packages:
    • Each package must have a ~\jar\* 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

  • Switching the language in the help browser with the "g" option needs first to close it (by hand ; no way by code). See the bug report #12889
  • It is not possible to target online Tables of Contents on https://help.scilab.org.
  • If multiple versions of a module are available (in SCI\contrib\* or SCIHOME\contrib\* subdirectories, etc), only pages of the last version met will be accessible. It is not necessarily the latest version.
  • For any local function, heading comments set in a multiline bloc of comments /*...*/ are ignored. See the bug report #14353.
  • LaTeXed expressions rendered as images can't be reversed and displayed as clear text. Nevertheless, their existence is indicated in the text.
  • 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.
  • Calling the help browser with the "g" option does not bring it to the foreground (if it is docked): See the bug report #13756
  • uman can't be used in naked console mode for MS Windows releases (UTF8 badly rendered: See the bug report #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 doesn't exist => "'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 overloading cd    // tables with borders.
uman plotsparse cd     // 2 tables without borders, in the arguments section
uman atomsSetConfig ac // tables with long lines in cells are wrapped

// 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).

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

See Also

Author

Samuel GOUGEON

History

VersionDescription
2.0, 2016-04-06

Major version. uman reforged. 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. 10 references added.

1.3, 2015-07-12

20 bugs fixed. 20 references added. See changelog.txt for details.

1.2, 2015-06-06

Upgrade. ~40 improvements and bugs fixed. Code ready for Scilab 6.

1.1, 2015-04-02

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

1.0, 2015-03-22

First release


Report an issue
<< disp_usage uman uman .. @ >>