bugGNU Octave - Bugs: bug #55509, pkg load: automatically register...


bug #55509: pkg load: automatically register QHelp files with doc browser

Submitter:  Andrew Janke <apjanke>
Submitted:  Fri 18 Jan 2019 05:11:30 PM UTC
Category:  GUI Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Feature Request
Status:  Need Info Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup

Jump to the original submission

Tue 23 Nov 2021 05:28:00 PM UTC, comment #20: 

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

Rik <rik5>
Group administrator
Thu 25 Apr 2019 04:27:45 PM UTC, comment #19: 

Is there any progress on this bug report?  I'm helping a user new to Octave which is giving me an appreciation of how much we take for granted.  Said new user, rightfully, didn't understand why after loading a package he couldn't find help on the package.

Rik <rik5>
Group administrator
Mon 21 Jan 2019 11:59:14 PM UTC, comment #18: 

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.

Andrew Janke <apjanke>
Mon 21 Jan 2019 11:57:03 PM UTC, comment #17: 

> BTW, I forgot to mention after testing, your PKD_ADD script should clear all the variables that it creates so that the base workspace is left as it was before "pkg load chrono".

I'll add a clear. Thanks.

Is this behavior by design? Seems like PKG_ADD/PKG_DEL shouldn't be clobbering the user's base workspace variables, at least not by default. E.g. if I clear all the variables I set in PKG_ADD, then I've still clobbered and cleared previously existing user variables with the same names, and the workspace is not as it was.

Andrew Janke <apjanke>
Mon 21 Jan 2019 05:15:50 PM UTC, comment #16: 

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.

Mike Miller <mtmiller>
Group Member
Mon 21 Jan 2019 04:53:40 PM UTC, comment #15: 


>> package authors shouldn't really be calling it, should they?

Yes, that was exactly my intension when I initially wrote this interface function. But you are right that the function should be documented and that it should appear somewhere in the manual (probably with a less scary name and without underscores).

As for the "pkg" handling the registration, I have no opinion since I basically know nothing about our package manager. Let's just wonder what would be the actual benefit and how much manpower we want to devote to change something that already works?

BTW, I forgot to mention after testing, your PKD_ADD script should clear all the variables that it creates so that the base workspace is left as it was before "pkg load chrono".

Pantxo Diribarne <pantxo>
Group Member
Mon 21 Jan 2019 04:27:27 PM UTC, comment #14: 

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

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

__octave_link_register_doc__ (my_qhelp_file);

Andrew Janke <apjanke>
Mon 21 Jan 2019 12:39:16 PM UTC, comment #13: 

Or to be clearer (I hope :-)): According to you, why isn't PKG_ADD/DEL the right way to do the job?

Pantxo Diribarne <pantxo>
Group Member
Mon 21 Jan 2019 12:27:55 PM UTC, comment #12: 

@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?

Pantxo Diribarne <pantxo>
Group Member
Sat 19 Jan 2019 09:53:58 AM UTC, comment #11: 

Boom. You called it.

In the .qhp index, I was doing:

          <keyword name="datetime" ref="html/datetime.html"/>

Adding an `id="$fcn_name"` like this got it working:

          <keyword name="datetime" id="datetime" ref="html/datetime.html"/>

Now, on Octave 4.4.1 on macOS 13.6 and Windows 10, doing `pkg load chrono; doc datetime` pulls up Chrono's datetime class documentation.

I pushed a new Chrono 0.1.3 release with this fix. If you want to try it out:

pkg install https://github.com/apjanke/octave-addons/chrono/releases/download/v0.1.3/chrono-0.1.3.tar.gz
pkg load chrono
doc datetime


Andrew Janke <apjanke>
Sat 19 Jan 2019 09:28:07 AM UTC, comment #10: 

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 Janke <apjanke>
Sat 19 Jan 2019 09:21:36 AM UTC, comment #9: 

This simple change makes everything work correctly for me:

diff -r cc59c1aca759 libgui/src/documentation.cc
--- a/libgui/src/documentation.cc       Fri Jan 18 11:18:23 2019 +0100
+++ b/libgui/src/documentation.cc       Sat Jan 19 10:19:34 2019 +0100
@@ -591,7 +591,7 @@

     // First search in the function index
     QMap<QString, QUrl> found_links
-      = m_help_engine->linksForIdentifier (ref_name);
+      = m_help_engine->linksForKeyword (ref_name);

     QTabWidget *navi = static_cast<QTabWidget*> (widget (0));

The "doc KEYWORD" now finds chrono functions in the function index. So this is indeed a problem of installed filter.

Pantxo Diribarne <pantxo>
Group Member
Sat 19 Jan 2019 09:13:30 AM UTC, comment #8: 

@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.
Pantxo Diribarne <pantxo>
Group Member
Sat 19 Jan 2019 01:55:25 AM UTC, comment #7: 

@Pantxo: I've pushed a Chrono 0.1.1 release that has a keyword index in the QHelp.

I've also added a hack to have it automatically load the QHelp in existing versions of Octave using the PKG_ADD mechanism.

All the functions and classes show up in the Index in the help browser now, and double-clicking them will bring you to the appropriate topic.

`doc <function>` isn't working for them, though. I don't know why. For example, `doc timezones` just switches focus to the doc browser, and doesn't bring up the timezones function doco.

Andrew Janke <apjanke>
Sat 19 Jan 2019 12:18:01 AM UTC, comment #6: 

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

Andrew Janke <apjanke>
Sat 19 Jan 2019 12:14:19 AM UTC, comment #5: 

@Andrew: Out of curiosity, I downloaded your QHelp files and just ran the following in the GUI

__octave_link_register_doc__ ("/PATH/TO/chrono.qch");
doc timezones

Links to occurrences of "timezones" in the manual are shown in the search tab, and the "timezones" page is shown in the browser (see attached screenshot).
The Chrono manual is added in the content tab below the Octave manual, but Chrono functions dont appear in the function index tab. You probably need to index functions in the <keyword> section.

Pantxo Diribarne <pantxo>
Group Member
Fri 18 Jan 2019 11:50:09 PM UTC, comment #4: 

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.

Andrew Janke <apjanke>
Fri 18 Jan 2019 10:36:32 PM UTC, comment #3: 

Sure, comma separate list of relative file names seems right to me.

See bug #44529 for the bug on registering package Info files with the doc function, and bug #45852 for an older feature request on registering packages with the GUI help browser (before it was changed to QHelp format).

Also patch #8491 on providing a 'pkg doc' subcommand, a slightly different approach to the same problem.

Mike Miller <mtmiller>
Group Member
Fri 18 Jan 2019 07:48:07 PM UTC, comment #2: 

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.

Andrew Janke <apjanke>
Fri 18 Jan 2019 07:17:05 PM UTC, comment #1: 

Can we tie the location and/or name of the QHelp file into the package metadata? I think it would be far better if a package could declare the file name and (relative) path name of its QHelp (if any), as well as other docs (HTML, Info, PDF, etc) in the package DESCRIPTION file.

There is another similar bug report about extending the doc function to work with Info files provided by packages.

Mike Miller <mtmiller>
Group Member
Fri 18 Jan 2019 05:11:30 PM UTC, original submission:  

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.

Andrew Janke <apjanke>


(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:

Attached Files
file #46019:  timezone_doc.png added by pantxo (170KiB - image/png)
file #46012:  pkg-auto-register-qhelp-files.patch added by apjanke (4KiB - application/octet-stream)


Depends on the following items: None found

Items that depend on this one: None found


Carbon-Copy List
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by pantxo (Updated the item)
  • -email is unavailable- added by apjanke (Submitted the item)

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.


    Follow 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2019-01-21 pantxo StatusNone Need Info
    2019-01-19 pantxo Attached File- Added timezone_doc.png, #46019
    2019-01-18 apjanke Attached File- Added pkg-auto-register-qhelp-files.patch, #46012
        Attached File- Added octave-pkg-load-with-qhelp.gif, #46013

    Back to the top

    Powered by Savane 3.13-4b48.
    Corresponding source code