[Contents] [TitleIndex] [WordIndex

Contributor - Upgrade the Scilab help system

This proposal consists in different aspects:

Building

The current build Scilab help system is based on Docbook (docbook-xsl, saxon, jeuclid, jlatexmath and fop). It is a powerful and nice system but it has some performance issues.

Task #1: Disconnect the Help tree from the tree of code

The anarchic wealth on the help root should be tackled. It mainly comes from that presently the help tree is built as scilab modules are loaded in the session. Each main section in the help corresponds to a separate module, and the order of loading modules sets the order of main help sections.

In addition, some pages could be helpful at multiples places in distinct sections, but this is presently impossible, since the code of the related function is at one and only one place. A function is sometimes in a certain module not because it is about the same kind of things than other functions in the module, but because -- due to some internal dependencies --, it must be loaded in the same time. Hence some items in the help can appear in an inappropriate section.

In order to address and fix these major issues, the help builder must be refactored. This may be done by inserting a routing file of paths allowing to disconnect help sections from the actual position and order of modules and their codes. Then

Task #2: Fix some important bugs

Namely: When errors occur when compiling the documentation,

Task #3: Improve or extend some docbook tags

Task #4: Improve build time

TODO. Develop if a student is interested

Profiling:

xsltproc --nonet --profile --timing /usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunkfast.xsl  master_en_US_help.xml

OR

xsltproc --nonet --profile --timing /usr/share/sgml/docbook/xsl-stylesheets/html/chunkfast.xsl  modules/helptools/master_en_US_help.xml

User perspective

Task #1: Add features

Localization / translation issues

Task #1: Allow the help browser to (re)load on-the-fly any available language release of the help

Task #2: Provide a mechanism to see and manage differences between the en_US reference page and other languages

Task #3: Provide a way to let users propose the translation of parts of online pages

Web interface to modify the documentation

Such an interface could be set, in order to ease documentation updates:

Like docbook manager which is expensive and proprietary but free.


2022-09-08 09:26