<< 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, coma or semi-columns, embrasse the pattern between quotes "..".
options

Options are described in details within the Description section. Single string specifying one or several options. Each character (order and case unsensitive) is a switch enabling a specific feature. Available options are described here-above.

WHERE it 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.

HOW the query must be processed:

c :
Clear the Console before displaying the page
L## :
Language of the version to be displayed (if not the session's one). ## = language code en | fr | de | ja | pt | ru | zh (default specified as last option = "en").
x :
priority to eXternal packages and references.
r :
Refresh / Reload the list of all available modules documentations, and the queried page.
j :
Journalize: allows recording the output in currently open diaries (if any).

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

s :
summary: display the parent summary including the pattern, instead of its page.
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
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 user manual. It displays help pages of Scilab, ATOMS packages, external packages, or heading comments in functions, in text mode in the console, as well as in the help browser or online in your web browser (when applicable). A single function for every sources and displayers, with advanced features such that language switching, summaries, or display of bugs related to the query.

Main features
  • Help pages from Scilab, ATOMS modules, other external contribs, and heading comments in functions are supported. No need to priorly load modules in session to view their pages in console.

  • Adaptative depth of infos: focus on main infos: path in help, calling sequences, parameters, see also. Be free to display one or more additional sections on request: description, examples, history...

  • Language switch without changing the session's language. Just give the language code en | de | fr | ja | pt | ru | zh in option, and you get the related page! Thus, access easily to the reference en_US version of the page.

  • Smart text layout in console. Nested lists of items, tables, pieces of codes, notes and warnings, text styles.. are supported. Improved code style of calling sequences and examples.

  • Almost 200 automatic redirections for users coming from other softwares: Search for atan2 leads to.. atan.

  • Easy switch to online pages, with redirection and language facilities, to see users comments or to straight comment the right page.

  • Check the forge: easy and ergonomic access to the list of bugs related to the pattern, for Scilab and many ATOMS packages.

Supported OS
Windows, Linux and Mac OS, with Scilab 5.5.0 or later.

Covered help pages
Scilab pages
are firstly 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 pages are automatically considered.
ATOMS modules do not need to be loaded in session, just be installed (in SCI\.atoms and SCI\contrib or SCIHOME\atoms\..). It is therefore possible to have a look at some pages before loading the related module, whether it looks to be the relevant one.
To target eXternal pages from ATOMS modules or other contrib modules in priority, before Scilab pages, use the "x" option.
Other contrib packages
Every package installed by hand in SCI\contrib or in SCIHOME\contrib and having standard help pages are also covered. As for ATOMS modules,
To display their documentation in the console, external contrib modules do not need to be loaded in session, just to be installed (in SCI\contrib\.. or SCIHOME\contrib\..).
Pages from Contributed external packages are scanned only if the pattern has not been found in the main Scilab pages, unless the "x" option is used.
Redirections
If uman does not find any matching item in Scilab and in installed ATOMS and contrib packages, it silently looks whether a redirection is defined for the queried 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... If a redirection matches the query, uman is rerun with it.
Miscellaneous functions
If definitively uman does not find any matching item in Scilab and installed ATOMS and contrib packages, even within a redirection, it looks whether the pattern is a function defined in the session. If it is the case, it displays its eventual header comments, the easiest way to document a function.

Options : detailled description

single string specifying one or several options. Each character (order and case unsensitive) is a switch enabling a specific feature. Available options are described here-above.

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.

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 ## 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 "en" is used.
x :
eXternal packages and references first. This flag is used in 2 different ways:
  • When the same function name is used in Scilab and in an ATOMS or a contrib package, by default uman addresses the Scilab version. To target the eXternal package 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, null ...

r :
Refresh / Reload the list of all available modules documentations, and the queried page.

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. Any further call to this page uses the stored version. After having installed some new modules, it is necessary to refresh uman to detect their help pages. As well, after updating an help page of a module, it is necessary to delete its stored version and to extract again the page. This is what "r" does.

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

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

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.

When an help page is displayed, the mandatory sections are the following: Path through the documentation, leading to the feature / Actual name of the feature / Calling sequences / List of input & output parameters / "See also" section. Additionnal sections may be displayed on query:

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", the description is always displayed.
e :
Examples: display also identified Examples section(s)

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

h :
History: display also the History section, 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).

If the pattern is related to an installed ATOMS module:

  • If this module has a Scilab's forge at http://forge.scilab.org, the ticket page of its forge is opened in your web browser and filtered with the pattern.
  • Else, if this module has a declared web site, its home page is opened in your web browser.
  • Otherwise, the ATOMS web page of the module is opened. Its comments section is targeted. This is the first place to get help about the module or to report its pitfalls.

a :
All sections displayed, but bugs URLs. Option equivalent to "deh".
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 kills "w" and "b" ones (online and bug addressing cancelled).
Options adding sections are then ignored: "a", "b", "d", "e", "h",...
This option is ignored when "w" is used (except for pages of external packages).

WHERE it must be displayed.

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

g :
Help browser GUI: 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. This warning is then displayed 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: opens your web browser and displays the help page of the online manual, for the given pattern (internet connection alive required). The language (default, or forced with the "l" switch) is taken into account. Page's display in the console is then cancelled.

If the pattern is not found in the help, the search engine of the online help is automatically targeted with it.

When "w" is used with "b", the online manual page is replaced with the online bug tracker page related to the pattern -- when it exists.

When the pattern is related to an external module (from or out of the ATOMS external modules repository), no online help pages are available (see http://bugzilla.scilab.org/6723). This "w" is then ignored, and the help page is as usual displayed in text mode in the console.

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(colors page), datatype (Data types page), files (summary of file management functions), graphics (summary), hdf5 (summary of functions), linespec (related page), metanet (summary), shortcuts (related page), sparses (summary of main functions for sparse matrices), statistics (summary), variables (summary), windows (summary), xml (summary).

Try: --> uman sparses and see.

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 detect 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)
  • 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.
  • In pages in Chinese, long lines without space are not wrapped.
  • Over more than 2000 help pages, a few of them are mis-conditionned and may mislead uman. Reconditionning these pages is softly going on ;)
  • Presently, 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 "//"..., quotes are mandatory.
  • uman can't be used in 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" is undocumented/

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 colors      // inner redirection to the color_list page,with its Description
uman sparses     // Display the summary of functions dealing with sparse matrices. 
                 // Other shortcuts are defined in the same way. Try with "statistics"
                 
// Scilab equivalences of external patterns inexisting in Scilab
uman polyval c   // 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 cde     // targets the Scilab related page = controls (if.. end / for.. end / while..end)
uman end cdex    // "x" targets in priority an eXternal meaning for "end". In Octave, "end" 
                 // means "index of last element", as "$" in Scilab => "$" page is displayed
                  
// "g" calls also the help browser GUI (may be docked over the editor)
uman strstr deg

// "s" display the related Summary instead of the feature's page
uman strstr des
uman who sg       // A Summary with subcategories, here in the browser as well

// With an internet connexion alive:
uman ode wlpt     // ONLINE page of ode() in Portuguese
uman ode wb       // ONLINE list of bugs reported around ode(), well sorted (unfixed bugs first)
uman colors w     // inner redirection to color_list, then ONLINE page (with colors)

// 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" for the eXternal plot() page from Plotlib to be targeted
uman plot cdexg        // the help browser called with "g" does not come, because Plotlib is not loaded
uman quiver wb            // targets the ONLINE bug page of the plotlib module on the Scilab forge.
if ~yn, atomsRemove("plotlib"), end    // cleaning after the example

See Also

History

VersionDescription
1.0 / 2015-03

First release


Report an issue
<< uman uman