Pinging Andrew in case he has a patch for this bug.

I like the "Qt-Help: doc/whatever.qch" idea, possibly with support for a comma-separated list of files. I'll work a patch for that for discussion.

Yes, the point of this bug report is to add support to the pkg command so that a package can use a standard declaration and automatically register a help file with Octave's built in help system.

I propose adding support for

Qt-Help: doc/package.qch

in the package DESCRIPTION file. When a package is loaded and its descriptor contains this field, pkg will arrange for the file to be registered with the GUI help browser. If the file does not exist, pkg will emit a warning.

The goal is to provide a supported mechanism for packages to register Qt help files with Octave. The PKG_ADD mechanism relies on _octave_link_register_doc_. And since that's an undocumented internal function, package authors shouldn't really be calling it, should they? It also relies on the fact that `pkg install` drops the package's "doc" directory directly under the package installation directory; I don't know if that's part of the stable public interface for pkg, or an implementation detail.

A secondary goal is convenience for package authors: I think it'd be easier for package authors to do this declaratively (listing files in package metadata) or by convention (a known doc/<package>.qhp file location) than procedurally with PKG_ADD: the PKG_ADD is a little long and grody (example below). But this is a relatively minor secondary goal.

% Register package's QHelp with the doc browser

% Have to hardcode this since it's not available from context
my_pkg_name = 'chrono';

% We only want this to happen when we're called by 'pkg load', not when
% this code is just added to the path.
% Note: This detection is a hack and is brittle WRT changes in Octave's
% internal implementation.

is_loading = false;
stack = dbstack;
is_loading = any (ismember ({stack.name}, {'load_packages'}));
if ~is_loading
  return;
end

% When a package is installed, the doc/ directory is added as a subdir
% of the main installation dir, which contains the inst/ files

my_pkg_name = 'chrono';
this_dir = fileparts (mfilename ('fullpath'));
my_doc_dir = fullfile (this_dir, 'doc');
my_qhelp_file = fullfile (my_doc_dir, [my_pkg_name '.qch']);
if ~exist (my_qhelp_file, 'file')
  warning('QHelp file for package %s is missing: %s', ...
    my_pkg_name, my_qhelp_file);
  return;
end

__octave_link_register_doc__ (my_qhelp_file);

@Andrew: Could you clarify the goal of this feature request? In particular what feature would you like to see implemented, and how different would it be from your current approach which IIUC is to (un)register packages documentation through the use of PKG_(del)ADD?

Oh, that's promising. Thanks for running that down. I'll fiddle with my QHelp definitions to see if I can work with that.

@Andrew: With the new QHelp files, chrono functions now do appear in the function index and I still observe the same behavior as described in comment #5. So there are two issues:

• "doc KEYWORD" at least partly works for me, not for you. I am on linux mint 19, Octave stable.
• Octave should now find the function in the function index, not using the full text search. There may be some filter at play, that prevents QHelpEngine::linksForIdentifier from finding chrono functions in the function index.

Yeah, a keyword index is on my TODO list. It's currently completely missing.

Ah, cool.

Want to just close this as a dupe of #44529 and take the discussion over there? That's really asking for the same thing, at a higher level.

Yeah, we could do this in the metadata. Perhaps add new lines for "QHelpFiles:", "InfoFiles:", "PdfDocFiles:", each taking a comma-separated list of files with no spaces in their names?

It's less clear to me what the structure for PDF, HTML, and other files should be, since there's not an existing interaction mode for them in doc() or other functions, as far as I know. Handling QHelp is pretty straightforward since there's only one thing to do with it: register it with the QHelp browser. And the QHelp file contains enough internal metadata for that to work smoothly.

Is DESCRIPTION the right place for this? That file seems to contain more externally visible info about the package and its relationship to other packages. Internal package structure info seems to live in INDEX and other metadata files. Maybe a new FILES or METADATA file would be more appropriate?

Might also need to consider how the signature for "doc" interacts with this: it looks like, in non-Qt Octave, doing "doc foo" searches the main Octave info manual index for foo, if foo is not a function or class.

I couldn't find the other bug report.

Hi, Octave folks,

What do you think about having "pkg load" automatically detect and register QHelp collection files for the packages with the doc browser? This would allow Octave to automatically display manuals for the packages in the doc browser along with the main Octave manual. I think this would be convenient.

Patch to do so attached.

This approach assumes that each package defines a single QHelp collection named <package>.qch in its doc/ directory. For an example of a package that does this, along with scripts to generate the .qch file, see my in-progress Chrono package: https://github.com/apjanke/octave-addons-chrono/tree/0ba2e3f860882752931ebfda85daeb965655d74e/doc.