[Octave-bug-tracker] [bug #55509] pkg load: automatically register QHelp files with doc browser

[Andrew Janke]

Follow-up Comment #14, bug #55509 (project octave):

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);


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?55509>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/