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

It shall become possible to set "Virtual" help sections or subsections corresponding to no module.
A section or a page shall possibly appear at several places in the help tree.
It shall be possible to cancel the default position of a function or of a section in the help, to make it appearing elsewhere.
The tree of modules shall still be used as default help paths, when no detailed alternate information is given to route the builder.
When a help page gathers several xml:id (ex: int8() page), it shall become possible to point to the page for each of its id (xml:id resolution). Moreover, when needed, a flag shall be available to tell to the builder that it must add as many entries in the help as there are xml:id in the page, for this page (or it could be the default behavior).

Task #2: Fix some important bugs

Namely: When errors occur when compiling the documentation,

errors messages are not (always) displayed in the console. This makes documentation's debugging very awkward and tricky. See the report #7255.
pending files are locked. This turns uncertain further documentation processing. See the report #8430

Task #3: Improve or extend some docbook tags

When the code of a <programlisting> section yields a figure, and we want to insert the figure in the page after the <programlisting> section, we are presently compelled to open a <scilab:image> tag and to copy/duplicate in it the Scilab code yielding the figure. In order to avoid this duplication, a new attribute display_figure=".." should be implemented for the <programlisting> tag. See the report #13141. The value of the attribute could be:
- "true": activates the generation and display, with the default image size, in non-localized mode.
- "<sizes>": activate the generation and display, with the given image sizes: "w,", ",h", "w,h" where w is the width and h is the height, in pixels.
- "localized": activate the generation and display, with localized versions of the image.
- "localized|<sizes>": mixes generation and display modes.
In a similar way, when we wish to display in a <screen> tag the results of Scilab instructions as they are displayed in the console, we have to run the code in the console and to copy/paste the result in the <screen> area. When the code is given in a <programlisting> section, a new attribute display_console=".." shall be implemented in order to avoid this duplication. It should automatically get Scilab instructions from the <programlisting> tag, run them, get results from the console (as registered with diary()), automatically open a <screen> area, and put the results in it. See 12369.
- In case that both display_console=".." and display_figure=".." are simultaneously used in the <programlisting> tag, the <screen> content will have to be displayed first, and then the image.
For ordered lists, the "inheritnum" attribute should be supported 11102
For now, when <link type="scilab" linkend="scilab.help/item"> is used in an external module to point a Scilab item,
- the link does not work in the HTML release: See the bug 12820.
- the short description of the Scilab pointed item is not shown, in any release (.jar, html, pdf)
The tags <xref> and <link> do not yet support the "endterm" docbook attribute. It could be implemented (for <link>). See the report #14444 and the discussion there.

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

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

In every jar page, add a link to the related online page, to be used to write some online comments. See report #9909
In the help browser, add a bookmark area.
Allow to display short descriptions in tooltips on help items: According to the setting of a new option settable through the Preferences system, a tooltip showing the short description of the item could be displayed when the mouse overflies it. See report #13749.
History of visited pages: It is already possible to go forward or backward through the already visited pages. But a History list allowing a random access would be better. See the report #5959

Task #2: Improve Help Search

Full text search are limited. For example, searching ilib_ will only return c_link instead of returning also ilib_build, ilib_for_link. See the report#3020

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

A validation system should also be set, with registered reviewers. Implement Google-translate helpers on online pages.

Web interface to modify the documentation

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

Raw XML is not really for humans.
Registered users could contribute without knowing GIT

Like docbook manager which is expensive and proprietary but free.