tbx_build_help

Arguments

title

Title of the help chapter. Not used anymore, kept for backward compatibility.

help_path

The help directory of the toolbox, or one of its la_LA language subdirectories: the images of all the languages are generated either way. Default is the current directory.

Description

The help browser renders the DocBook XML pages of a toolbox directly from its help/la_LA directories: no help file has to be built. tbx_build_help pre-generates the images these pages display: the ones described by <scilab:image> blocks, and the Xcos diagrams (.zcos files) shown through <imagedata>. They are written in the help/images directory of the toolbox, along with their index help_images.index, and are shipped with the toolbox: the help browser then displays them without having to generate them.

The images of all the languages are generated at once. Scripts calling tbx_build_help once per language, from each help/la_LA/build_help.sce, keep working: the first call generates the images, the next ones find them up to date and return immediately. The images are regenerated only when a page of the help directory or a .zcos diagram of the toolbox is newer than the index, and the images of the examples removed from the pages are then deleted.

As the examples usually call the functions of the toolbox itself, the images are generated by another Scilab session, launched in nw mode whatever the mode of the current one, which first runs the etc/*.start file of the toolbox. The libraries of the toolbox must thus be built before its help.

A failure is not fatal: a warning is displayed, and the help browser generates the missing images when their pages are displayed.

The help/images directory may also hold images written by hand, displayed by the pages through <imagedata>: tbx_build_help never overwrites nor deletes a file which is not listed in help_images.index.

Examples

// From the builder_help.sce script of a toolbox, in its help directory:
// the images of all the languages are generated
tbx_build_help("Toolbox Example", get_absolute_file_path("builder_help.sce"))

// Historical usage, from each help/la_LA/build_help.sce script: the first
// call generates the images of all the languages, the next ones do nothing
tbx_build_help("Toolbox Example", get_absolute_file_path("build_help.sce"))

See also

• tbx_builder_help — Builds the multilingual help of a toolbox: pre-generates the images of its pages
• tbx_builder_help_lang — Run build_help.sce script if it exists (toolbox compilation process)
• tbx_build_help_loader — Generate an addchapter.sce script (toolbox compilation process)
• tbx_package — Package a toolbox source tree with binaries into a single file

History