uman internals

Technical aspects

How uman() works

uman scans SCI/contrib/*, SCIHOME/contrib/*, and all paths/* set as Paths to external modules out of ~/contrib parameter in the uman Preferences. It then sets the list of all ./jar/*.jar archives found, and for each, identifies the name of the related modules (as basename of the *.start files), and the related languages.
This inventory is performed
- the first time uman is run after being installed,
- after each time that an ATOMS module is installed or uninstalled,
- or when the "r" option is used.
When uman is called, a complex algorithm analyses the pattern to determine whether it is about an item of Scilab, or of an ATOMS module (and then which one), or of an external resource in an Scilab forge or of the Scilab FileExchange or elsewhere, or if it's an alias or redirection. In this later case, the true target and its reference (module's name, URL, etc) are determined.
Using the "x" option changes some priorities in this algorithm.
Details of the algorithm can be found in the code, starting at the label "SEARCHING FOR THE RIGHT HELP TARGET".
When the item has actually an help page, the page is extracted from its ./jar/*.jar archive and stored in a SCIHOME/uman subdirectory used as a cache. Forthcoming calls of uman for the same item will then use the page in cache (unless the "r" option is used).

Packaging of modules and their documentation

To be correctly parsed for documentation, the minimal setup of a registered module (ATOMS or others) is as follows:

The name of the module's root directory is free.
A subdirectory ./etc must exists and have a file ./etc/*.start, where * is the module's name. This file can be empty but is mandatory. It is used only to get the name.
A subdirectory ./jar must exist. It stores all scilab_##_##_help.jar standard help zipped archives (as built by the Scilab documentation builder), where ##_## stands for each supported language (one file per language).

That's all. Additional subdirectories may exist but are ignored by uman.

Known limitations

uman can't be used in naked console mode for MS Windows releases: UTF8 characteres are badly rendered. Please see the bug report #10748).
uman can't display correctly Right-to-Left languages in the console.
Switching the language in the help browser run with the "g" option needs first to close it (by hand ; no way by code). See the bug report #12889
Display of tables:
- center- or right-justification in cells is not rendered in the console.
- The indentation and line wrapping are incorrect for structured contents (nested itemized lists, contents in table cells,..) included in a table.
- Cells vertically merged with rowspan are not supported.
If multiple versions of a module are installed or declared (in SCI\contrib\* or SCIHOME\contrib\* subdirectories, etc), its selected pages are unpredictable.
For any local function, heading comments set in a multiline bloc of comments /*...*/ are ignored. See the bug report #14353.
LaTeXed expressions without alt=".." text equivalent defined in the source file can't be displayed as clear text. However, their existence is indicated in the text.
For pages in Chinese, long lines without space are not wrapped.

Resources used and references

For the console, "g", and "w" modes

The following resources are considered:

Scilab->Scilab and external->Scilab aliases, and list of faux-amis (if the "x" option is used).
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 .jar archives stored in the directories or sub-directories at the Paths of external modules out of ~/contrib declared in uman Preferences.
Local user functions written in Scilab language, with heading comments used as embedded help contents, and without standard help page.

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.
Registered uninstalled 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 finally one of these resources matches the given pattern, a message inviting to use the "w" option -- or even the actual pattern -- is displayed in the console.

For the "w" web mode

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

Scilab-to-Scilab, external-to-Scilab, and external-to-external aliases may as well be found and used along the successive searching steps, from the raw input pattern to the actually displayed page.

For the "b" bugs mode

When the unique and final item is a...

Scilab function : Scilab Bugzilla website.
Function of an installed ATOMS module :
- If the module has a Scilab Forge: ticket page of the forge
- Otherwise: Comments section of the ATOMS.scilab.org page of the module
FileExchange item: The Comments section of the related FileExchange page.
Other external items registered in uman with a reference web site : portal of the given web site.
Unknown item, multiple items separated with "|" : Search engine on http://bugzilla.scilab.org

Author

Samuel GOUGEON

History

Version	Description
3.0	2019-08-22 `uman` now automatically detects whether any ATOMS module has been installed or uninstalled during the session, and rescans ressources accordingly. The reloading `'r'` option is still available. It can be used when you install contribs other than ATOMS ones. `uman` now uses automatically the ATOMS packages list downloaded by your ATOMS manager to complete its own set of ATOMS references. Hence, `uman` is now always up-to-date about ATOMS ressources, provided that your ATOMS manager is so. `uman` messages can now be translated. There are already available for french. 75 redirections / references added. ~100 unitary tests added for all uman modes.
2.1	2016-10-30 : 19 references added.
2.0	2016-04-06 : 22 references added.
1.4	2015-07-31 : 10 references added.
1.3	2015-07-12 : 20 references added.
1.2	2015-06-06 : Code ready for Scilab 6.
1.0	2015-03-22 : First release