User manual in console, online, or browser, with language switch & related bugs
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!" @
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.
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.
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
global
line, variables
must not be separated with comas but with spaces.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
umanDefaultOptions
environment variablepattern
, headed with -
,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
| ||||
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 |
x : | priority to eXternal packages and references. This flag is used in 2 different ways:
|
r : | Refresh /
Reload
the documentation list of all
installed external modules, and delete all pages already
extracted from external modules.
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 |
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.
| ||||
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.
| ||||
e : | Examples: display
identified Examples section(s)
Examples included in other types of sections are
displayed within these ones. Using
| ||||
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. |
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.
"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..
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.
Windows, Linux and Mac OS, with Scilab 5.5 and Scilab 6.
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 |
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.
The following resources are considered:
umanUserPaths
environment variable.If the pattern or its possible alias is not found in these resources, other registered uninstalled external resources are scanned against it, namely:
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.
Internal-to-internal, external-to-internal, and external-to-external aliases may as well be found and used along the successive searching steps
Internal-to-internal, external-to-internal, and external-to-external aliases may still be found and used along the successive searching steps.
Online archives of all official Scilab mailing lists.
uman
extracts Scilab, ATOMS and other Contrib pages in SCIHOME\uman
subdirectories.contrib
packages:
~\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.
"g"
option needs first to close it (by hand ; no way by code).
See the bug report #12889uman
is not self-extensible to any language. If you wish to add a (left-to-right) language, please get in touch with the author."g"
option does not bring it to the foreground (if it is docked): See the bug
report #13756uman
can't be used in naked console
mode for MS Windows releases (UTF8 badly rendered: See the bug
report #10748).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
Version | Description |
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 |