package_texi2qch takes a single input argument, pkgname, which is a char string with the package’s name whose Qt help file needs to be generated, and writes pkgname.qch into the current working directory. Octave’s GUI reads such a file to populate its documentation tab: pkg load registers doc/pkgname.qch from the package’s installation directory and pkg unload unregisters it, so the generated file must be placed in the package’s doc/ directory before the release tarball is built for it to have any effect.

The help text of every function listed in the package’s INDEX file is rendered to HTML, one page per INDEX category, and each function is registered as a keyword pointing at its own anchor within that page.

A classdef is not rendered onto its category page. It keeps the category its INDEX entry puts it in, and is given a page tree of its own beneath it, whatever its size:

• <Class>.html carries the class help text and a list of links to the pages below it.
• <Class>_properties.html carries one section per property, and is absent from a class that declares none.
• <Class>_methods.html carries one section per method. A grouped classdef, one that sorts its methods under ** Group Name ** banner blocks as classdef_texi2html reads them, takes one page per group instead, named after it and carrying that group’s methods, in the order the class declares them.

The contents tree of the documentation browser therefore nests a class under its own category, and is entered rather than scrolled past among its neighbours, which is what a category holding a few dozen classdefs would otherwise ask of a reader. A category page carries its plain functions and a list of links to the classes it owns.

Functions are grouped by category rather than given a page each because every file inside a .qch is compressed on its own, so fragmenting what the pages share inflates the archive: for the statistics package the same documentation measures 0.57 MB at one page per category against 1.89 MB at one page per function. The page tree a classdef is given costs a part of that difference and buys the navigation back.

Demos are not included, neither their code nor their figures. A .qch is an offline reference to be shipped inside the package, where the rendered figures of a package the size of statistics would cost more than the rest of the documentation put together. Demos remain available through demo and through the online pages that package_texi2html builds.

A @tex formula is rendered as its @ifnottex alternative, and dropped when it has none. The documentation browser of the GUI runs no JavaScript, so the MathJax that typesets a formula in the online pages is not available to it, and the TeX would reach the reader as source. This is what makeinfo does for every output that is not TeX, and what help prints in the terminal for the same docstring.

package_texi2qch requires the qhelpgenerator program of the Qt toolkit, which is located on the system’s $PATH unless the 'generator' option names it explicitly. The program is looked up before any page is rendered and, if it cannot be found, an error is raised and nothing is written, rather than spending the build on documentation that cannot be packaged.

Example:

 package_texi2qch ("statistics");

Optional Name/Value pairs

Every help text is checked as it is read, and what is found is reported with the name it belongs to and a line counted from the first line of that help text. A finding never stops the build: a page is written from a help text whatever it says, since refusing would leave the package with no documentation over a defect the reader would have met anyway.

Only the rules a help text can be judged by on its own are applied here. The rest measure the file a help text was written in, which this route never opens, working as it does from the installed package; help is its source and check_texi_docs is where those rules live.

See also: package_texi2html, function_texi2html, classdef_texi2html, check_texi_docs, pkg_doc_options

Source Code: package_texi2qch